@cdxgen/cdxgen 13.2.0 → 13.4.0

package/lib/ecosystems/jsEvidence.js

@@ -6,11 +6,11 @@
 // import parsers-js directly instead of having parsePkgJson threaded in as an
 // injected helper from the CLI.
 
-import { join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
-import { DEBUG_MODE } from "../core/activity.js";
 import { safeExistsSync } from "../core/fs.js";
 import { createOccurrenceEvidence } from "../inventory/evidenceUtils.js";
+import { isPkgTypeOnlyImport, setNpmTypeOnlyProperty } from "./npmutils.js";
 import { parsePkgJson } from "./parsers-js.js";
 
 const NPM_BIN_IMPORT_PREFIX = "cdx:npm:bin/";
@@ -104,13 +104,95 @@ function applyNpmBinCommandEvidence(pkg, allImports) {
   }
 }
 
+/**
+ * Full npm package name (`@scope/name` or `name`) of a component or manifest.
+ *
+ * @param {{group?: string, name?: string}} pkg Component or parsed manifest.
+ * @returns {string} The package name npm installs it under.
+ */
+function npmPackageName({ group, name }) {
+  const scope = group?.startsWith("@") ? group.substring(1) : group;
+  return scope ? `@${scope}/${name}` : name;
+}
+
+/**
+ * Fill in a component's missing npm metadata (description, author, license,
+ * homepage, repository) from the package.json of its installed copy.
+ *
+ * `internal:LocalNodeModulesPath` holds either an absolute install directory
+ * (pnpm) or an arborist `node.location`. A location that starts with
+ * `node_modules/` is relative to the directory of the component's
+ * `internal:SrcFile`. Other relative locations, such as a workspace member or a
+ * package nested under one, have no recorded base and are skipped; the deep npm
+ * parse reads those manifests from the arborist node itself. The manifest is
+ * used only when it names the component's package and version, and it fills
+ * only the fields the component lacks.
+ *
+ * @param {object} pkg Package component to enrich in place.
+ */
+async function fillMissingMetadataFromLocalNodeModules(pkg) {
+  if (pkg.description || !Array.isArray(pkg.properties)) {
+    return;
+  }
+  const propValue = (propName) =>
+    pkg.properties.find((property) => property.name === propName)?.value;
+  const localNodeModulesPath = propValue("internal:LocalNodeModulesPath");
+  if (!localNodeModulesPath) {
+    return;
+  }
+  let pkgJsonFile;
+  if (isAbsolute(localNodeModulesPath)) {
+    pkgJsonFile = join(localNodeModulesPath, "package.json");
+  } else {
+    const srcFile = propValue("internal:SrcFile");
+    if (!srcFile || !localNodeModulesPath.startsWith("node_modules/")) {
+      return;
+    }
+    pkgJsonFile = resolve(
+      dirname(srcFile),
+      localNodeModulesPath,
+      "package.json",
+    );
+  }
+  if (!safeExistsSync(pkgJsonFile)) {
+    return;
+  }
+  const lnmPkgList = await parsePkgJson(pkgJsonFile, true);
+  const lnmMetadata = lnmPkgList?.length === 1 ? lnmPkgList[0] : undefined;
+  if (
+    !lnmMetadata ||
+    npmPackageName(lnmMetadata) !== npmPackageName(pkg) ||
+    lnmMetadata.version !== pkg.version
+  ) {
+    return;
+  }
+  if (!pkg.description && lnmMetadata.description) {
+    pkg.description = lnmMetadata.description;
+  }
+  if (!pkg.author && lnmMetadata.author) {
+    pkg.author = lnmMetadata.author;
+  }
+  if (!pkg.license && lnmMetadata.license) {
+    pkg.license = lnmMetadata.license;
+  }
+  if (!pkg.homepage && lnmMetadata.homepage) {
+    pkg.homepage = lnmMetadata.homepage;
+  }
+  if (!pkg.repository && lnmMetadata.repository) {
+    pkg.repository = lnmMetadata.repository;
+  }
+}
+
 /**
  * Attach JS/TS import and export usage evidence to matching package components.
  *
  * For each component, resolves its module aliases (including the deno jsr
  * specifier), records imported/exported modules as properties, attaches
- * occurrence evidence, and adjusts the component scope to "required" when the
- * package is used or "optional" when it is not.
+ * occurrence evidence, and promotes the component scope to "required" when the
+ * package is used. A package with no observed usage keeps the scope its
+ * manifest parser assigned: static import analysis cannot see packages loaded
+ * from configuration, bundler entrypoints, stylesheets, or plugins, so a
+ * missing import is not evidence that a package is optional.
  *
  * @param {Array<object>} pkgList Package components to enrich.
  * @param {object} allImports Map of import specifier to usage evidence objects.
@@ -128,15 +210,16 @@ export async function addEvidenceForImports(
   const impPkgs = Object.keys(allImports);
   const exportedPkgs = Object.keys(allExports);
   for (const pkg of pkgList) {
-    if (impPkgs?.length) {
-      // Assume that all packages are optional until we see an evidence
-      pkg.scope = "optional";
-    }
     const { group, name } = pkg;
     // Evidence belonging to a type must be associated with the package
     if (group === "@types") {
       continue;
     }
+    // Runs ahead of the alias loop, which a matching import ends with a break,
+    // so that every component is enriched whichever alias the source imports.
+    if (deep) {
+      await fillMissingMetadataFromLocalNodeModules(pkg);
+    }
     const aliases = group?.length
       ? [name, `${group}/${name}`, `@${group}/${name}`]
       : [name];
@@ -155,7 +238,6 @@ export async function addEvidenceForImports(
         aliases.push(jsrSpecifier);
       }
     }
-    let isImported = false;
     for (const alias of aliases) {
       const isWasmAlias = /\.wasm([?#].*)?$/i.test(alias);
       const all_includes = impPkgs.filter(
@@ -213,11 +295,22 @@ export async function addEvidenceForImports(
       }
       // Identify all the imported modules of a component
       if (impPkgs.includes(alias) || all_includes.length) {
-        isImported = true;
         let importedModules = new Set();
         let wasmExportedModules = new Set();
         const seenOccurrenceLocations = new Set();
-        pkg.scope = "required";
+        // A package imported only for its types is erased at compile time.
+        // Scoping it excluded here, rather than when the BOM is assembled,
+        // keeps propagateRequiredScopeFromDependencies from promoting what it
+        // depends on. A package whose bin command is used is still required.
+        if (
+          isPkgTypeOnlyImport(allImports, group, name) &&
+          !getNpmBinCommandEvidenceKeys(allImports, pkg).length
+        ) {
+          pkg.scope = "excluded";
+          setNpmTypeOnlyProperty(pkg);
+        } else {
+          pkg.scope = "required";
+        }
         for (const subevidence of all_includes) {
           const evidences = allImports[subevidence];
           for (const evidence of evidences) {
@@ -273,39 +366,6 @@ export async function addEvidenceForImports(
         }
         break;
       }
-      if (
-        impPkgs?.length > 0 &&
-        !isImported &&
-        DEBUG_MODE &&
-        pkg?.scope !== "optional"
-      ) {
-        console.debug(
-          `\x1b[1;35mNotice: Package ${pkg.name} has no usage in code. Check if it is needed.\x1b[0m`,
-        );
-      }
-      // Capture metadata such as description from local node_modules in deep mode
-      if (deep && !pkg.description && pkg.properties) {
-        let localNodeModulesPath;
-        for (const aprop of pkg.properties) {
-          if (aprop.name === "internal:LocalNodeModulesPath") {
-            localNodeModulesPath = resolve(join(aprop.value, "package.json"));
-            break;
-          }
-        }
-        if (localNodeModulesPath && safeExistsSync(localNodeModulesPath)) {
-          const lnmPkgList = await parsePkgJson(localNodeModulesPath, true);
-          if (lnmPkgList && lnmPkgList.length === 1) {
-            const lnmMetadata = lnmPkgList[0];
-            if (lnmMetadata && Object.keys(lnmMetadata).length) {
-              pkg.description = lnmMetadata.description;
-              pkg.author = lnmMetadata.author;
-              pkg.license = lnmMetadata.license;
-              pkg.homepage = lnmMetadata.homepage;
-              pkg.repository = lnmMetadata.repository;
-            }
-          }
-        }
-      }
     } // for alias
     // Trim the properties
     applyNpmBinCommandEvidence(pkg, allImports);

package/lib/ecosystems/kosi.js

@@ -10,8 +10,13 @@ import {
   safeRmSync,
   safeSpawnSync,
 } from "../core/fs.js";
+import { resolvePluginSourceDir } from "../core/pluginRun.js";
 import { resolvePluginBinary } from "../inventory/plugins.js";
-import { tryBuildPurl, tryParsePurl } from "../inventory/purl.js";
+import {
+  parsePurlLoose,
+  tryBuildPurl,
+  tryParsePurl,
+} from "../inventory/purl.js";
 
 /**
  * kosi — JS bridge to the Kotlin-native evidence binary (thirdparty/kosi in
@@ -46,7 +51,10 @@ export function kosiWorkspaceComponent(workspaceModule) {
   if (!workspaceModule?.purl) {
     return undefined;
   }
-  const version = workspaceModule.purl.split("@")[1] || "unspecified";
+  // The version is read through the purl parser: cutting the text after `@`
+  // kept its escaping (`1.0.0%2Bbuild`) and any `?type=jar` qualifiers.
+  const version =
+    parsePurlLoose(workspaceModule.purl)?.version || "unspecified";
   const cleanName = (workspaceModule.name || "").replace(/^['"]|['"]+$/g, "");
   const purl =
     tryParsePurl(workspaceModule.purl) ||
@@ -59,7 +67,7 @@ export function kosiWorkspaceComponent(workspaceModule) {
     name: cleanName || workspaceModule.name,
     version,
     purl,
-    "bom-ref": purl,
+    "bom-ref": decodeURIComponent(purl),
   };
 }
 
@@ -167,14 +175,25 @@ export function analyzeKosiProject(src, options = {}) {
     );
     return undefined;
   }
+  // cdxgen may run with its working directory already inside the project
+  // while the source argument is relative to a repository root; a plain
+  // resolve would join the two into a directory that does not exist.
+  const analysisDir = resolvePluginSourceDir(src, [
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "settings.gradle",
+    "settings.gradle.kts",
+    "classpath.txt",
+  ]);
   const tempDir = safeMkdtempSync(join(getTmpDir(), "kosi-"));
   try {
     const outputFile = join(tempDir, "kosi-all.json");
-    const allArgs = kosiArgs(kosi, src, outputFile, "all");
+    const allArgs = kosiArgs(kosi, analysisDir, outputFile, "all");
     if (DEBUG_MODE) {
       console.log("Executing", kosi.cmd, allArgs.join(" "));
     }
-    const report = runKosi(kosi, src, allArgs, outputFile, options);
+    const report = runKosi(kosi, analysisDir, allArgs, outputFile, options);
     if (!report) {
       return undefined;
     }
@@ -184,10 +203,15 @@ export function analyzeKosiProject(src, options = {}) {
     // all-pass's. Losing it would silently drop the filtered evidence,
     // so a failure here names itself but keeps the all-pass evidence.
     const reachableFile = join(tempDir, "kosi-reachable.json");
-    const reachableArgs = kosiArgs(kosi, src, reachableFile, "reachable");
+    const reachableArgs = kosiArgs(
+      kosi,
+      analysisDir,
+      reachableFile,
+      "reachable",
+    );
     const reachableReport = runKosi(
       kosi,
-      src,
+      analysisDir,
       reachableArgs,
       reachableFile,
       options,

package/lib/ecosystems/npmutils.js

@@ -2,8 +2,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { build, Purl } from "@cdxgen/cdx-purl";
+import { clean } from "semver";
 
 import { safeExistsSync } from "../core/fs.js";
+import { parsePurlLoose } from "../inventory/purl.js";
+import { spdxLicenses } from "../inventory/spdx.js";
 import { parseNpmrc, parseNpmrcFromEnv } from "../parsers/npmrc.js";
 
 const npmPackageHydrationFields = [
@@ -17,6 +20,9 @@ const npmPackageHydrationFields = [
   "homepage",
   "keywords",
   "license",
+  // Legacy plural form kept by long-lived packages such as fuzzy 0.1.3: the
+  // manifest carries `licenses` instead of `license` (issue 4466).
+  "licenses",
   "repository",
 ];
 
@@ -84,6 +90,89 @@ export function setNpmPeerProperty(pkg) {
   addComponentProperty(pkg, "cdx:npm:package:peer", "true");
 }
 
+/**
+ * Marks an npm component as imported only for its TypeScript types.
+ *
+ * @param {object} pkg Component object to annotate
+ * @returns {void}
+ */
+export function setNpmTypeOnlyProperty(pkg) {
+  addComponentProperty(pkg, "cdx:npm:package:type-only", "true");
+}
+
+/**
+ * Clean an npm version the way `npm publish` does before it records a release.
+ *
+ * Publishing a directory runs the manifest through `npm pkg fix`
+ * (`fixVersionField` in `@npmcli/package-json`, which calls `semver.clean` in
+ * loose mode) and then through libnpmpublish, which calls `semver.clean` again
+ * in strict mode and records the result as the packument version, the
+ * dist-tag, the `_id` and the tarball file name. Semver build metadata
+ * (`1.0.0+build.5`), a leading `v` or `=`, surrounding whitespace and leading
+ * zeros are dropped; a prerelease is kept.
+ *
+ * The `package.json` inside the published tarball keeps the original string,
+ * and so do the lockfiles npm, pnpm, yarn and bun write for a project, a
+ * workspace member or a git, file or link dependency. The cleaned form is the
+ * version the npm registry knows the package by.
+ *
+ * @param {string} version Version as a manifest or lockfile records it
+ * @returns {string|null} The cleaned version, or null when npm would reject `version` as invalid semver
+ */
+export function cleanNpmVersion(version) {
+  if (typeof version !== "string" || !version.trim()) {
+    return null;
+  }
+  const looseClean = clean(version, { loose: true });
+  if (!looseClean) {
+    return null;
+  }
+  return clean(looseClean);
+}
+
+/**
+ * Record the version npm would publish when it differs from the recorded one.
+ *
+ * Sets `cdx:npm:cleanedVersion` on an npm component whose version is valid
+ * semver but not in the form {@link cleanNpmVersion} produces, for example
+ * `1.0.0+build.5` (published as `1.0.0`). The component's `version` and `purl`
+ * keep the recorded string: that is what the manifest and lockfile say. A
+ * component whose version is already clean, or not semver at all (a git
+ * commit, a `file:` path), is left without the property, and a stale value from
+ * an earlier pass is replaced.
+ *
+ * @param {object} component Component or package object with `version` and `purl`
+ * @returns {object} The same component, for chaining
+ */
+export function setNpmCleanedVersionProperty(component) {
+  if (!component || typeof component !== "object") {
+    return component;
+  }
+  const purl = component.purl;
+  if (typeof purl !== "string" || !purl.startsWith("pkg:npm/")) {
+    return component;
+  }
+  const cleaned = cleanNpmVersion(component.version);
+  const wanted = cleaned && cleaned !== component.version ? cleaned : undefined;
+  const existing = component.properties?.filter(
+    (property) => property?.name === "cdx:npm:cleanedVersion",
+  );
+  if (
+    (!existing?.length && !wanted) ||
+    (existing?.length === 1 && existing[0].value === wanted)
+  ) {
+    return component;
+  }
+  const properties = (component.properties || []).filter(
+    (property) => property?.name !== "cdx:npm:cleanedVersion",
+  );
+  if (wanted) {
+    properties.push({ name: "cdx:npm:cleanedVersion", value: wanted });
+  }
+  component.properties = properties;
+  return component;
+}
+
 /**
  * Helper function to create a properly encoded workspace PURL
  *
@@ -130,14 +219,18 @@ export function findMatchingNpmWorkspace(workspacePackages, packageName) {
     return undefined;
   }
 
-  const expectedEncodedPurl = createNpmWorkspacePurl(packageName);
-  const simplePurl = `pkg:npm/${packageName}`;
-
-  return workspacePackages.find(
-    (workspacePackage) =>
-      workspacePackage.startsWith(expectedEncodedPurl) ||
-      workspacePackage.startsWith(simplePurl),
-  );
+  // Compare the parsed coordinates: a prefix match on the purl text would let
+  // `ws` match `wsmember`, and the reference may be escaped or decoded.
+  return workspacePackages.find((workspacePackage) => {
+    const parts = parsePurlLoose(workspacePackage);
+    if (parts?.type !== "npm") {
+      return false;
+    }
+    const fullName = parts.namespace
+      ? `${parts.namespace}/${parts.name}`
+      : parts.name;
+    return fullName === packageName;
+  });
 }
 
 /**
@@ -201,6 +294,12 @@ export function collectNpmManifestSources(node) {
     return manifestSources;
   }
   for (const edge of node.edgesIn) {
+    // Arborist adds a `workspace` edge from the root to every member, with an
+    // absolute `file:` spec it builds from the checkout path. No manifest
+    // declares it, and copying it would put the local path into the BOM.
+    if (edge?.workspace || edge?.type === "workspace") {
+      continue;
+    }
     const manifestSource = classifyNpmManifestSource(edge?.spec);
     if (!manifestSource) {
       continue;
@@ -215,6 +314,66 @@ export function collectNpmManifestSources(node) {
   return manifestSources;
 }
 
+/**
+ * Whether a value of the legacy `licenses` field names a license: a non-empty
+ * string, or an object with a non-empty `type`.
+ *
+ * @param {*} entry One value of the legacy field
+ * @returns {boolean} True when the entry names a license
+ */
+function isLegacyNpmLicenseEntry(entry) {
+  if (typeof entry === "string") {
+    return entry.trim() !== "";
+  }
+  return typeof entry?.type === "string" && entry.type.trim() !== "";
+}
+
+/**
+ * Resolve the license of an npm-style manifest, honouring the legacy plural
+ * `licenses` field that packages published before the SPDX convention still
+ * carry (issue 4466). A modern `license` value is returned unchanged. The
+ * legacy field may hold one entry or an array of them, each a string or a
+ * `{ type, url }` object; one entry is returned as it is. npm documents an
+ * array of several entries as a choice between them, so when every entry is an
+ * SPDX identifier the array becomes the equivalent `MIT OR Apache-2.0`
+ * expression, and otherwise stays a list for `getLicenses` to convert entry by
+ * entry.
+ *
+ * @param {object} pkgData Parsed package.json (or bower.json) manifest
+ * @returns {string|object|Array|undefined} The effective license value
+ */
+export function resolveNpmLicense(pkgData) {
+  if (!pkgData || typeof pkgData !== "object") {
+    return undefined;
+  }
+  const license = pkgData.license;
+  // An empty or null license is no declaration and defers to `licenses`.
+  if (
+    license !== undefined &&
+    license !== null &&
+    !(typeof license === "string" && license.trim() === "")
+  ) {
+    return license;
+  }
+  const legacyEntries = (
+    Array.isArray(pkgData.licenses) ? pkgData.licenses : [pkgData.licenses]
+  ).filter(isLegacyNpmLicenseEntry);
+  if (legacyEntries.length <= 1) {
+    return legacyEntries[0];
+  }
+  const licenseIds = [
+    ...new Set(
+      legacyEntries.map((entry) =>
+        (typeof entry === "string" ? entry : entry.type).trim(),
+      ),
+    ),
+  ];
+  if (licenseIds.every((licenseId) => spdxLicenses.includes(licenseId))) {
+    return licenseIds.join(" OR ");
+  }
+  return legacyEntries;
+}
+
 /**
  * Hydrates sparse npm package metadata from the installed package.json in deep mode.
  * Existing metadata on the Arborist node wins over on-disk values.
@@ -520,7 +679,9 @@ export function parsePnpmGitLockKey(lockKey) {
  * @returns {Object<string, object>} Map of lookup key to git package reference.
  */
 export function buildPnpmGitPkgRefs(packages, snapshots, npmrcConfig = {}) {
-  const gitPkgRefs = {};
+  // A null prototype keeps inherited Object properties (such as `constructor`)
+  // from masquerading as lookup hits for keys that were never registered.
+  const gitPkgRefs = Object.create(null);
   const registerEntry = (lockKey, packageNode) => {
     const resolution = packageNode?.resolution;
     const parsed = parsePnpmGitLockKey(lockKey);
@@ -531,6 +692,10 @@ export function buildPnpmGitPkgRefs(packages, snapshots, npmrcConfig = {}) {
       return;
     }
     const { group, name, gitSpec, fullName, packageName } = parsed;
+    if (name === "__proto__" || packageName === "__proto__") {
+      // A crafted lock key cannot become a lookup entry under this name.
+      return;
+    }
     const version = packageNode?.version || resolution?.commit || "";
     const repo = resolution?.repo || "";
     const commit = resolution?.commit || "";