refactor(scanner): rename packageName to spec for from and verify APIs

.changeset/large-signs-look.md

@@ -0,0 +1,5 @@
+---
+"@nodesecure/scanner": patch
+---
+
+Rename packageName argument in from and verify APIs to spec

workspaces/scanner/README.md

@@ -53,12 +53,12 @@ function workingDir(
   logger?: Scanner.Logger
 ): Promise<Scanner.Payload>;
 function from(
-  packageName: string,
+  spec: string,
   options?: Scanner.FromOptions,
   logger?: Scanner.Logger
 ): Promise<Scanner.Payload>;
 function verify(
-  packageName?: string
+  spec?: string
 ): Promise<tarball.ScannedPackageResult>;
 ```
 

workspaces/scanner/docs/from.md

@@ -13,13 +13,13 @@ console.log(payload);
 
 ```ts
 function from(
-  packageName: string,
+  spec: string,
   options?: FromOptions,
   logger?: Logger
 ): Promise<Scanner.Payload>
 ```
 
-- `packageName` — npm package name, with optional version or semver range (e.g. `"mocha"`, `"mocha@10"`, `"mocha@^10.0.0"`).
+- `spec` — npm package name, with optional version or semver range (e.g. `"mocha"`, `"mocha@10"`, `"mocha@^10.0.0"`).
 - `options` — optional configuration, see `FromOptions` below.
 - `logger` — optional logger instance for tracking scan phases. See [logger](./logger.md).
 

workspaces/scanner/docs/verify.md

@@ -13,23 +13,18 @@ console.log(result);
 
 ```ts
 function verify(
-  packageName?: string
+  spec?: string
 ): Promise<tarball.ScannedPackageResult>
 ```
 
-## Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `packageName` | `string` | — | Name (and optional version) of the npm package to verify. If omitted, the current working directory is scanned instead. |
-
 ## Behavior
 
-- **With `packageName`:** Downloads the package tarball from the npm registry into a temporary directory, then scans its contents.
-- **Without `packageName`:** Scans the current working directory (`process.cwd()`) directly.
+- **With `spec`:** Downloads the package tarball from the npm registry into a temporary directory, then scans its contents.
+- **Without `spec`:** Scans the current working directory (`process.cwd()`) directly.
 
 Unlike `from()` and `workingDir()`, `verify()` does **not** recursively walk the dependency tree. It scans the package files of a single package only.
 
 ## Return value
 
-Returns `Promise<tarball.ScannedPackageResult>` from [`@nodesecure/tarball`](https://github.com/NodeSecure/tarball). The result contains the JS-X-Ray analysis of each file in the package, including detected warnings such as obfuscated code, unsafe regex, encoded literals, and more.
+Returns `Promise<tarball.ScannedPackageResult>` from [`@nodesecure/tarball`](https://github.com/NodeSecure/tarball).
+The result contains the JS-X-Ray analysis of each file in the package, including detected warnings such as obfuscated code, unsafe regex, encoded literals, and more.

workspaces/scanner/src/index.ts

@@ -106,7 +106,7 @@ export type FromOptions = Omit<Options, "includeDevDeps"> & {
 };
 
 export async function from(
-  packageName: string,
+  spec: string,
   options: FromOptions = {},
   logger = new Logger()
 ): Promise<Payload> {
@@ -115,7 +115,7 @@ export async function from(
     getLocalRegistryURL();
 
   logger.start(ScannerLoggerEvents.manifest.fetch);
-  const manifest = await pacote.manifest(packageName, {
+  const manifest = await pacote.manifest(spec, {
     ...NPM_TOKEN, registry, cache: `${os.homedir()}/.npm`,
     userAgent: `@nodesecure/scanner node/${process.version}`
   });
@@ -136,16 +136,16 @@ export async function from(
 }
 
 export async function verify(
-  packageName?: string
+  spec?: string
 ): Promise<tarball.ScannedPackageResult> {
-  if (typeof packageName === "undefined") {
+  if (typeof spec === "undefined") {
     return tarball.scanPackage(process.cwd());
   }
 
   await using tempDir = await TempDirectory.create();
 
   const mama = await tarball.extractAndResolve(tempDir.location, {
-    spec: packageName,
+    spec,
     registry: getLocalRegistryURL()
   });