@cdxgen/cdxgen 13.1.0 → 13.2.0

package/lib/ecosystems/parsers-rust.js

@@ -2,8 +2,8 @@ import { readFileSync } from "node:fs";
 import { sep as _sep, basename, dirname, join, resolve } from "node:path";
 
 import { build } from "@cdxgen/cdx-purl";
-import toml from "@iarna/toml";
 import { globSync } from "glob";
+import * as toml from "smol-toml";
 
 import { DEBUG_MODE } from "../core/activity.js";
 import { shouldFetchLicense } from "../core/env.js";
@@ -108,9 +108,83 @@ function parseCargoDependencyFromPackageNode(packageNode) {
   if (!isExtendFromWorkspace(pkgDependencies) && pkgDependencies) {
     pkg.dependencies = pkgDependencies;
   }
+  const pkgSource = packageNode["source"];
+  if (!isExtendFromWorkspace(pkgSource) && typeof pkgSource === "string") {
+    pkg.source = pkgSource;
+  }
   return pkg;
 }
 
+/** The crates.io index, which a cargo purl identifies without a qualifier. */
+const CRATES_IO_INDEX_URLS = new Set([
+  "https://github.com/rust-lang/crates.io-index",
+  "sparse+https://index.crates.io/",
+  "sparse+https://index.crates.io",
+]);
+
+/**
+ * Describe a cargo source string, as a lock file spells it, so a component can
+ * say where it came from and whether that is the public registry.
+ *
+ * A crate resolved from an alternative or private registry shares its name and
+ * version with whatever crates.io publishes under them, so the registry has to
+ * take part in the component's identity.
+ *
+ * @param {string} source Lock file `source` value
+ * @returns {{kind: string, url: string, isAlternateRegistry: boolean}|undefined} Source facts
+ */
+function cargoSourceInfo(source) {
+  if (!source || typeof source !== "string") {
+    return undefined;
+  }
+  const separatorIndex = source.indexOf("+");
+  if (separatorIndex === -1) {
+    return { kind: source, url: "", isAlternateRegistry: false };
+  }
+  const kind = source.slice(0, separatorIndex);
+  let url = source.slice(separatorIndex + 1);
+  if (kind === "sparse") {
+    // `sparse+https://…` is a registry protocol, not a source kind.
+    return {
+      kind: "registry",
+      url,
+      isAlternateRegistry: !CRATES_IO_INDEX_URLS.has(source),
+    };
+  }
+  if (kind === "git") {
+    // The fragment is the resolved commit, which the purl carries separately.
+    url = url.split("#")[0];
+  }
+  return {
+    kind,
+    url,
+    isAlternateRegistry:
+      kind === "registry" && !CRATES_IO_INDEX_URLS.has(url.replace(/\/$/, "")),
+  };
+}
+
+/**
+ * Build the purl for a cargo package, qualifying it with the registry when the
+ * crate does not come from crates.io.
+ *
+ * @param {{name: string, group?: string, version?: string, source?: string}} pkg Package identity
+ * @returns {string} cargo purl
+ */
+function buildCargoPurl(pkg) {
+  const sourceInfo = cargoSourceInfo(pkg?.source);
+  const qualifiers =
+    sourceInfo?.isAlternateRegistry && sourceInfo.url
+      ? { repository_url: sourceInfo.url }
+      : undefined;
+  return build({
+    type: "cargo",
+    namespace: pkg?.group || null,
+    name: pkg?.name,
+    version: pkg?.version || null,
+    qualifiers,
+  });
+}
+
 function cargoIntegrityToComponentHash(integrity) {
   const normalizedIntegrity = normalizeCargoIntegrity(integrity);
   if (!normalizedIntegrity) {
@@ -935,16 +1009,11 @@ export async function parseCargoData(
       return;
     }
 
-    const purl = build({
-      type: "cargo",
-      namespace: "" || null,
-      name: newPackage.name,
-      version: newPackage.version || null,
-    });
+    const purl = buildCargoPurl(newPackage);
     const component = {
       type: "library",
       group: newPackage.group,
-      "bom-ref": purl,
+      "bom-ref": decodeURIComponent(purl),
       purl: purl,
       name: newPackage.name,
       version: newPackage.version,
@@ -984,6 +1053,22 @@ export async function parseCargoData(
           value: cargoLockFile,
         },
       ];
+      const sourceInfo = cargoSourceInfo(newPackage.source);
+      // The public registry is the norm, and saying so on every component
+      // would bury the crates whose source is worth a second look. Only a
+      // source that is not plain crates.io is recorded.
+      if (sourceInfo && sourceInfo.kind !== "registry") {
+        appendCargoProperty(component, "cdx:cargo:sourceKind", sourceInfo.kind);
+        appendCargoProperty(component, "cdx:cargo:sourceUrl", sourceInfo.url);
+      } else if (sourceInfo?.isAlternateRegistry) {
+        appendCargoProperty(component, "cdx:cargo:sourceKind", "registry");
+        appendCargoProperty(component, "cdx:cargo:sourceUrl", sourceInfo.url);
+        appendCargoProperty(component, "cdx:cargo:alternateRegistry", "true");
+      } else if (!sourceInfo && newPackage.name) {
+        // A package with no source is local to the workspace: a path
+        // dependency, a workspace member, or a `[patch]`/`[replace]` override.
+        appendCargoProperty(component, "cdx:cargo:sourceKind", "local");
+      }
       if (pkgFilesMap?.[newPackage.name]) {
         component.components = fileListToComponents(
           pkgFilesMap[component.name],
@@ -1204,15 +1289,7 @@ export function parseCargoManifestDependencyData(cargoTomlFile, context = {}) {
  * @returns {Object[]} Array of dependency relationship objects with ref and dependsOn fields
  */
 export function parseCargoDependencyData(cargoLockData) {
-  const purlFromPackageInfo = (pkg) =>
-    decodeURIComponent(
-      build({
-        type: "cargo",
-        namespace: "" || null,
-        name: pkg.name,
-        version: pkg.version || null,
-      }),
-    );
+  const purlFromPackageInfo = (pkg) => decodeURIComponent(buildCargoPurl(pkg));
   const cargoData = toml.parse(cargoLockData);
   const packageNode = cargoData?.package;
   if (!packageNode || !Array.isArray(packageNode)) {
@@ -1267,6 +1344,844 @@ export function parseCargoDependencyData(cargoLockData) {
   return result;
 }
 
+/**
+ * Normalize a cargo dependency kind to the vocabulary used by the cargo
+ * manifest parsers.
+ *
+ * `cargo metadata` encodes a normal dependency as `null` rather than a string,
+ * so a truthiness test would silently leave runtime dependencies unlabelled.
+ *
+ * @param {string|null|undefined} kind Dependency kind as reported by cargo
+ * @returns {string} One of `runtime`, `build` or `dev`
+ */
+export function normalizeCargoDepKind(kind) {
+  if (kind === null || kind === undefined || kind === "" || kind === "normal") {
+    return "runtime";
+  }
+  return kind;
+}
+
+/**
+ * Parse a cargo package id into its name and version.
+ *
+ * cargo 1.77 and later emit the package id spec form
+ * (`registry+https://...#name@1.0.0`, or `path+file:///p/foo#1.0.0` where the
+ * name is carried by the path); earlier releases emit `name 1.0.0 (source)`.
+ *
+ * @param {string} packageId cargo package id
+ * @returns {{name: string, version: string}|undefined} Parsed identity
+ */
+export function parseCargoPackageId(packageId) {
+  if (!packageId || typeof packageId !== "string") {
+    return undefined;
+  }
+  const hashIndex = packageId.indexOf("#");
+  if (hashIndex !== -1) {
+    const source = packageId.slice(0, hashIndex);
+    const fragment = packageId.slice(hashIndex + 1);
+    const atIndex = fragment.lastIndexOf("@");
+    if (atIndex > 0) {
+      return {
+        name: fragment.slice(0, atIndex),
+        version: fragment.slice(atIndex + 1),
+      };
+    }
+    // `path+file:///workspace/crates/foo#1.0.0` - the name is the last path segment.
+    const sourcePath = source.replace(/^[a-z+]+\+/, "").replace(/\/+$/, "");
+    const name = basename(sourcePath.split("?")[0]);
+    if (name) {
+      return { name, version: fragment };
+    }
+    return undefined;
+  }
+  const legacyMatch = packageId.match(/^(\S+)\s+(\S+)(\s+\(.*\))?$/);
+  if (legacyMatch) {
+    return { name: legacyMatch[1], version: legacyMatch[2] };
+  }
+  return undefined;
+}
+
+/**
+ * Build the `name@version` key used to correlate cargo components across the
+ * lock file, the manifests and `cargo metadata`.
+ *
+ * @param {{name: string, version: string}} pkg Package identity
+ * @returns {string} Correlation key
+ */
+export function cargoComponentKey(pkg) {
+  if (!pkg?.name) {
+    return "";
+  }
+  return `${pkg.name}@${pkg.version || ""}`;
+}
+
+/**
+ * Convert a cargo purl or bom-ref into a `name@version` correlation key.
+ *
+ * @param {string} purl cargo purl
+ * @returns {string} Correlation key
+ */
+export function cargoPurlToComponentKey(purl) {
+  if (!purl || typeof purl !== "string") {
+    return "";
+  }
+  const withoutPrefix = decodeURIComponent(purl).replace(/^pkg:cargo\//, "");
+  const [identity] = withoutPrefix.split("?");
+  const slashIndex = identity.lastIndexOf("/");
+  return slashIndex === -1 ? identity : identity.slice(slashIndex + 1);
+}
+
+/**
+ * Collect the dependency kinds and platform gates declared by a single
+ * `Cargo.toml`, keyed by the crate name that cargo resolves the entry to.
+ *
+ * Manifests declare version requirements rather than resolved versions, so the
+ * returned map is keyed by name alone and is meant to label the edges leaving a
+ * workspace member in the lock file graph.
+ *
+ * @param {string} cargoTomlFile Cargo.toml path
+ * @param {object} [context] Workspace resolution context
+ * @returns {Map<string, {kinds: Set<string>, targets: Set<string>, optional: boolean}>} Declared edges
+ */
+export function parseCargoManifestDependencyKinds(cargoTomlFile, context = {}) {
+  const declaredEdges = new Map();
+  if (!cargoTomlFile || !safeExistsSync(cargoTomlFile)) {
+    return declaredEdges;
+  }
+  const normalizedCargoTomlFile = resolve(cargoTomlFile);
+  const cargoData = readCargoTomlData(normalizedCargoTomlFile);
+  if (!cargoData) {
+    return declaredEdges;
+  }
+  const workspaceContext = resolveCargoWorkspaceContext(
+    normalizedCargoTomlFile,
+    cargoData,
+    context,
+  );
+  const workspaceDependencies = workspaceContext?.workspaceData?.dependencies;
+  const collect = (dependencyEntries, dependencyKind, targetSelector) => {
+    if (!dependencyEntries || typeof dependencyEntries !== "object") {
+      return;
+    }
+    for (const dependencyName of Object.keys(dependencyEntries)) {
+      const dependencyNode = mergeCargoWorkspaceDependencySpec(
+        dependencyName,
+        dependencyEntries[dependencyName],
+        workspaceDependencies,
+      );
+      // `foo = { package = "bar" }` renames the crate; the lock file graph
+      // carries the real crate name.
+      const resolvedName =
+        (typeof dependencyNode === "object" && dependencyNode?.package) ||
+        dependencyName;
+      const existing = declaredEdges.get(resolvedName) || {
+        kinds: new Set(),
+        targets: new Set(),
+        optional: false,
+      };
+      existing.kinds.add(dependencyKind);
+      if (targetSelector) {
+        existing.targets.add(targetSelector);
+      }
+      if (typeof dependencyNode === "object" && dependencyNode?.optional) {
+        existing.optional = true;
+      }
+      declaredEdges.set(resolvedName, existing);
+    }
+  };
+  collect(cargoData.dependencies, "runtime", undefined);
+  collect(cargoData["build-dependencies"], "build", undefined);
+  collect(cargoData["dev-dependencies"], "dev", undefined);
+  if (cargoData.target && typeof cargoData.target === "object") {
+    for (const targetSelector of Object.keys(cargoData.target)) {
+      const targetBlock = cargoData.target[targetSelector];
+      if (!targetBlock || typeof targetBlock !== "object") {
+        continue;
+      }
+      collect(targetBlock.dependencies, "runtime", targetSelector);
+      collect(targetBlock["build-dependencies"], "build", targetSelector);
+      collect(targetBlock["dev-dependencies"], "dev", targetSelector);
+    }
+  }
+  return declaredEdges;
+}
+
+/**
+ * Roll per-edge cargo dependency kinds up to an effective kind per component.
+ *
+ * A crate is only dev-only when *every* path reaching it from a workspace root
+ * traverses a dev edge, so a crate shared between a dev dependency and a normal
+ * one keeps its runtime kind. Cargo never builds the dev dependencies of a
+ * dependency, so dev edges are followed from the workspace roots alone.
+ *
+ * @param {object} graph Dependency graph
+ * @param {string[]} graph.rootKeys Workspace member component keys
+ * @param {Map<string, Array<{to: string, kind: string, target?: string}>>} graph.edges Adjacency map
+ * @returns {Map<string, {kind: string, kinds: Set<string>, targets: Set<string>, targetGated: boolean}>} Effective kinds
+ */
+export function rollupCargoDependencyKinds({ rootKeys, edges }) {
+  const states = new Map();
+  const queue = [];
+  const visit = (key, kind, gated, targets) => {
+    let state = states.get(key);
+    if (!state) {
+      state = { kinds: new Map(), targets: new Set() };
+      states.set(key, state);
+    }
+    for (const target of targets) {
+      state.targets.add(target);
+    }
+    const previous = state.kinds.get(kind);
+    // An ungated path subsumes a gated one; revisit only when the knowledge improves.
+    if (previous !== undefined && (previous === false || gated === true)) {
+      return;
+    }
+    state.kinds.set(kind, gated);
+    queue.push({ key, kind, gated, targets });
+  };
+  for (const rootKey of rootKeys || []) {
+    if (rootKey) {
+      visit(rootKey, "root", false, new Set());
+    }
+  }
+  while (queue.length) {
+    const current = queue.shift();
+    for (const edge of edges.get(current.key) || []) {
+      const edgeKind = normalizeCargoDepKind(edge.kind);
+      let nextKind;
+      if (current.kind === "root") {
+        nextKind = edgeKind;
+      } else if (edgeKind === "dev") {
+        // The dev dependencies of a dependency are never built.
+        continue;
+      } else if (edgeKind === "build") {
+        nextKind = "build";
+      } else {
+        nextKind = current.kind;
+      }
+      const nextTargets = new Set(current.targets);
+      if (edge.target) {
+        nextTargets.add(edge.target);
+      }
+      visit(edge.to, nextKind, current.gated || !!edge.target, nextTargets);
+    }
+  }
+  const rollup = new Map();
+  for (const [key, state] of states) {
+    const kinds = new Set(state.kinds.keys());
+    let kind;
+    for (const candidate of ["root", "runtime", "build", "dev"]) {
+      if (state.kinds.has(candidate)) {
+        kind = candidate;
+        break;
+      }
+    }
+    if (!kind) {
+      continue;
+    }
+    rollup.set(key, {
+      kind,
+      kinds,
+      targets: state.targets,
+      targetGated: state.kinds.get(kind) === true,
+    });
+  }
+  return rollup;
+}
+
+/**
+ * Build a cargo dependency graph from the `resolve` section of
+ * `cargo metadata --format-version 1`.
+ *
+ * @param {object} metadata Parsed `cargo metadata` output
+ * @returns {{rootKeys: string[], edges: Map<string, Array<object>>, packageInfo: Map<string, object>, resolvedKeys: Set<string>}} Graph
+ */
+export function parseCargoMetadataResolve(metadata) {
+  const edges = new Map();
+  const packageInfo = new Map();
+  const rootKeys = [];
+  // Every package the resolver kept. With `--filter-platform` this is the set
+  // that a build for that triple actually pulls in.
+  const resolvedKeys = new Set();
+  if (!metadata || typeof metadata !== "object") {
+    return { rootKeys, edges, packageInfo, resolvedKeys };
+  }
+  const keyById = new Map();
+  for (const pkg of metadata.packages || []) {
+    if (!pkg?.id) {
+      continue;
+    }
+    const key = cargoComponentKey({ name: pkg.name, version: pkg.version });
+    keyById.set(pkg.id, key);
+    const targetKinds = new Set();
+    for (const cargoTarget of pkg.targets || []) {
+      for (const targetKind of cargoTarget?.kind || []) {
+        targetKinds.add(targetKind);
+      }
+    }
+    packageInfo.set(key, {
+      procMacro: targetKinds.has("proc-macro"),
+      source: pkg.source || "",
+      manifestPath: pkg.manifest_path,
+      // The native library this crate links, as declared by `links` in its
+      // manifest. Only a `-sys` style crate carries one.
+      links: pkg.links || "",
+      version: pkg.version,
+      name: pkg.name,
+      // The feature names the crate declares. A vendored source directory
+      // named after a feature that is not enabled belongs to a variant this
+      // build does not compile.
+      declaredFeatures: Object.keys(pkg.features || {}),
+    });
+  }
+  const resolveIdToKey = (packageId) => {
+    const known = keyById.get(packageId);
+    if (known) {
+      return known;
+    }
+    // A `[patch]`ed or vendored package can appear in `resolve` under an id the
+    // package list spells differently.
+    const parsed = parseCargoPackageId(packageId);
+    return parsed ? cargoComponentKey(parsed) : "";
+  };
+  // `resolve.root` is null for a virtual workspace, so the roots always come
+  // from `workspace_members`.
+  for (const memberId of metadata.workspace_members || []) {
+    const key = resolveIdToKey(memberId);
+    if (key) {
+      rootKeys.push(key);
+    }
+  }
+  if (!rootKeys.length && metadata.resolve?.root) {
+    const key = resolveIdToKey(metadata.resolve.root);
+    if (key) {
+      rootKeys.push(key);
+    }
+  }
+  for (const node of metadata.resolve?.nodes || []) {
+    const fromKey = resolveIdToKey(node?.id);
+    if (!fromKey) {
+      continue;
+    }
+    resolvedKeys.add(fromKey);
+    if (Array.isArray(node.features)) {
+      // The features the resolver actually enabled, as opposed to the ones the
+      // manifest declares. These decide which code is compiled, which optional
+      // dependencies activate, and whether a vulnerable path exists at all.
+      const info = packageInfo.get(fromKey) || {};
+      info.resolvedFeatures = node.features;
+      packageInfo.set(fromKey, info);
+    }
+    const nodeEdges = edges.get(fromKey) || [];
+    for (const dep of node.deps || []) {
+      const toKey = resolveIdToKey(dep?.pkg);
+      if (!toKey) {
+        continue;
+      }
+      // A single edge can carry several kinds, for example a crate used both
+      // as a normal and as a dev dependency by the same package.
+      const depKinds = dep.dep_kinds?.length
+        ? dep.dep_kinds
+        : [{ kind: null, target: null }];
+      for (const depKind of depKinds) {
+        nodeEdges.push({
+          to: toKey,
+          kind: normalizeCargoDepKind(depKind?.kind),
+          target: depKind?.target || undefined,
+        });
+      }
+    }
+    edges.set(fromKey, nodeEdges);
+  }
+  return { rootKeys, edges, packageInfo, resolvedKeys };
+}
+
+/**
+ * Build a cargo dependency graph from the lock file relationships, labelling
+ * the edges that leave a workspace member with the kinds declared by its
+ * manifest.
+ *
+ * The lock file is the union of every dependency kind and every target triple,
+ * so only the manifests can distinguish them. The resulting labels are exact at
+ * depth one and inherited below it, which is enough to identify dev-only and
+ * build-only subtrees without invoking cargo.
+ *
+ * @param {object[]} lockDependencies Relationships from {@link parseCargoDependencyData}
+ * @param {Map<string, Map<string, object>>} declaredEdgesByRoot Declared edges keyed by root component key
+ * @returns {{rootKeys: string[], edges: Map<string, Array<object>>}} Graph
+ */
+export function buildCargoLockDependencyGraph(
+  lockDependencies,
+  declaredEdgesByRoot,
+) {
+  const edges = new Map();
+  const rootKeys = [...(declaredEdgesByRoot?.keys() || [])];
+  for (const relationship of lockDependencies || []) {
+    const fromKey = cargoPurlToComponentKey(relationship?.ref);
+    if (!fromKey) {
+      continue;
+    }
+    const declaredEdges = declaredEdgesByRoot?.get(fromKey);
+    const nodeEdges = edges.get(fromKey) || [];
+    for (const dependsOnRef of relationship.dependsOn || []) {
+      const toKey = cargoPurlToComponentKey(dependsOnRef);
+      if (!toKey) {
+        continue;
+      }
+      const declared = declaredEdges?.get(toKey.split("@")[0]);
+      if (!declared) {
+        nodeEdges.push({ to: toKey, kind: "runtime" });
+        continue;
+      }
+      const targets = declared.targets.size ? [...declared.targets] : [null];
+      for (const kind of declared.kinds) {
+        for (const target of targets) {
+          nodeEdges.push({ to: toKey, kind, target: target || undefined });
+        }
+      }
+    }
+    edges.set(fromKey, nodeEdges);
+  }
+  return { rootKeys, edges };
+}
+
+/**
+ * Annotate cargo components with their effective dependency kind, platform
+ * gates and scope.
+ *
+ * Components reachable only through dev edges are scoped `excluded` so
+ * `--required-only` drops them. Build dependencies stay required because a
+ * build script is part of producing the artifact; the kind is recorded as a
+ * property so a consumer can filter on it.
+ *
+ * @param {object[]} pkgList Components to annotate
+ * @param {Map<string, object>} rollup Effective kinds from {@link rollupCargoDependencyKinds}
+ * @param {Map<string, object>} [packageInfo] Extra per-package facts
+ * @param {object} [options] Annotation options
+ * @param {boolean} [options.resolveIsComplete] The rollup covers every workspace in the scan, so a
+ *        component missing from it is an optional dependency no feature activates
+ * @returns {object[]} The annotated components
+ */
+export function applyCargoDependencyKindMetadata(
+  pkgList,
+  rollup,
+  packageInfo = new Map(),
+  options = {},
+) {
+  for (const pkg of pkgList || []) {
+    const key = cargoComponentKey(pkg);
+    const effective = rollup?.get(key);
+    const info = packageInfo?.get(key);
+    if (info?.resolvedFeatures?.length) {
+      appendCargoProperty(
+        pkg,
+        "cdx:cargo:resolvedFeatures",
+        [...info.resolvedFeatures].sort().join(", "),
+      );
+    }
+    if (info?.links) {
+      appendCargoProperty(pkg, "cdx:cargo:links", info.links);
+    }
+    if (info?.procMacro) {
+      // A proc-macro crate is compiled for the host, never for the target.
+      appendCargoProperty(pkg, "cdx:cargo:procMacro", "true");
+      appendCargoProperty(pkg, "cdx:cargo:hostOnly", "true");
+    }
+    if (
+      options?.filterPlatform &&
+      options?.targetIncludedKeys &&
+      effective?.kind !== "root" &&
+      !options.targetIncludedKeys.has(key)
+    ) {
+      // The resolver for the requested triple did not keep this crate, so no
+      // build for that triple links it.
+      appendCargoProperty(pkg, "cdx:cargo:targetExcluded", "true");
+      appendCargoProperty(
+        pkg,
+        "cdx:cargo:filterPlatform",
+        options.filterPlatform,
+      );
+      pkg.scope = "excluded";
+    }
+    if (!effective) {
+      // The lock file keeps optional dependencies that no enabled feature
+      // pulls in; the resolve graph is what says they are never built.
+      if (options?.resolveIsComplete) {
+        appendCargoProperty(pkg, "cdx:cargo:activated", "false");
+        if (!pkg.scope) {
+          pkg.scope = "optional";
+        }
+      }
+      continue;
+    }
+    if (effective.kind === "root") {
+      continue;
+    }
+    appendCargoProperty(pkg, "cdx:cargo:dependencyKind", effective.kind);
+    appendCargoProperty(pkg, "cdx:cargo:scope", effective.kind);
+    if (effective.kinds.size > 1) {
+      appendCargoProperty(
+        pkg,
+        "cdx:cargo:dependencyKinds",
+        [...effective.kinds].sort().join(", "),
+      );
+    }
+    if (effective.targets.size) {
+      appendCargoProperty(
+        pkg,
+        "cdx:cargo:target",
+        [...effective.targets].sort().join(", "),
+      );
+    }
+    if (effective.targetGated) {
+      appendCargoProperty(pkg, "cdx:cargo:targetGated", "true");
+    }
+    if (effective.kind === "build") {
+      // A build dependency is not part of the assembly; it is consumed while
+      // producing it, which is what the formulation section describes.
+      appendCargoProperty(pkg, "cdx:cargo:hostOnly", "true");
+    }
+    if (effective.kind === "dev" && pkg.scope !== "optional") {
+      pkg.scope = "excluded";
+    }
+  }
+  return pkgList;
+}
+
+/**
+ * Well-known `links` values whose library is better known by another name. The
+ * `links` key is a linker-level identifier, so `z` is zlib and `sqlite3` is
+ * SQLite; a consumer matching advisories or license obligations needs the name
+ * the upstream project publishes under. Anything absent from this map keeps its
+ * `links` value, which is still what the crate declared.
+ */
+const CARGO_NATIVE_LIBRARY_NAMES = Object.freeze({
+  bz2: "bzip2",
+  crypto: "openssl",
+  git2: "libgit2",
+  jpeg: "libjpeg",
+  lzma: "xz",
+  png: "libpng",
+  sqlite3: "sqlite",
+  ssl: "openssl",
+  z: "zlib",
+  zstd: "zstd",
+});
+
+/**
+ * Features whose presence means the native library is compiled into the
+ * artifact rather than linked against one the environment provides.
+ */
+const CARGO_STATIC_LINK_FEATURES = new Set([
+  "bundled",
+  "static",
+  "static-link",
+  "static-linking",
+  "vendored",
+]);
+
+/**
+ * Recover the upstream version of a native library from the version of the
+ * crate that ships it.
+ *
+ * The `-sys` and `-src` crates carry the upstream version as semver build
+ * metadata, because the crate's own version tracks the binding's releases
+ * rather than the library's: `openssl-src@300.6.1+3.6.3` ships OpenSSL 3.6.3
+ * and `curl-sys@0.4.74+curl-8.9.0` ships curl 8.9.0.
+ *
+ * @param {string} crateVersion Version of the providing crate
+ * @returns {string} Upstream version, or an empty string when it is not encoded
+ */
+export function cargoUpstreamVersionFromCrateVersion(crateVersion) {
+  if (!crateVersion || typeof crateVersion !== "string") {
+    return "";
+  }
+  const buildMetadata = crateVersion.split("+")[1];
+  if (!buildMetadata) {
+    return "";
+  }
+  // `curl-8.9.0` and `zstd.1.5.6` both prefix the version with the library name.
+  const versionMatch = buildMetadata.match(/(\d+(?:\.\d+)*[A-Za-z0-9.-]*)$/);
+  return versionMatch ? versionMatch[1] : "";
+}
+
+/**
+ * Recover the version of a vendored native library from the C source the crate
+ * ships.
+ *
+ * A `-sys` crate that bundles its library carries the upstream version in a
+ * header define - `ZLIB_VERSION`, `SQLITE_VERSION`, `OPENSSL_VERSION_TEXT` -
+ * which is the only statement of the version for the crates that do not encode
+ * it in their own version. A crate often ships more than one variant, so a
+ * candidate sitting in a directory named after a feature this build did not
+ * enable is dropped: `libz-sys` ships both `src/zlib` and `src/zlib-ng`, and
+ * only one of them is compiled.
+ *
+ * @param {object} args Resolution inputs
+ * @param {string} args.crateDir Directory holding the crate's unpacked source
+ * @param {string} args.links The crate's `links` value
+ * @param {string} args.libraryName Normalized library name
+ * @param {string[]} [args.declaredFeatures] Features the crate declares
+ * @param {Set<string>} [args.resolvedFeatures] Features the resolver enabled
+ * @returns {{version: string, evidence: string, candidates: string[]}} Version and where it came from
+ */
+export function resolveCargoVendoredLibraryVersion({
+  crateDir,
+  links,
+  libraryName,
+  declaredFeatures = [],
+  resolvedFeatures = new Set(),
+}) {
+  const empty = { version: "", evidence: "", candidates: [] };
+  if (!crateDir || !safeExistsSync(crateDir)) {
+    return empty;
+  }
+  const libraryTokens = [...new Set([libraryName, links])].filter(Boolean);
+  const defineNames = new Set();
+  for (const token of libraryTokens) {
+    const upperToken = token.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+    defineNames.add(`${upperToken}_VERSION`);
+    defineNames.add(`${upperToken}_VERSION_TEXT`);
+    defineNames.add(`${upperToken}_VERSION_STR`);
+  }
+  let headerFiles;
+  try {
+    headerFiles = globSync("**/*.h", {
+      absolute: true,
+      cwd: crateDir,
+      nodir: true,
+      windowsPathsNoEscape: true,
+    });
+  } catch (_err) {
+    return empty;
+  }
+  // Only a header named after the library states the library's version, and
+  // the filter keeps a large vendored tree from being read in full.
+  const interestingHeaders = headerFiles.filter((headerFile) => {
+    const headerName = basename(headerFile).toLowerCase();
+    return libraryTokens.some((token) =>
+      headerName.includes(token.toLowerCase()),
+    );
+  });
+  // A feature the crate declares but the resolver did not enable names a
+  // variant that is not built.
+  const disabledFeatures = declaredFeatures.filter(
+    (feature) => !resolvedFeatures.has(feature),
+  );
+  const candidates = new Map();
+  for (const headerFile of interestingHeaders.slice(0, 64)) {
+    let headerData;
+    try {
+      headerData = readFileSync(headerFile, { encoding: "utf-8" });
+    } catch (_err) {
+      continue;
+    }
+    for (const match of headerData.matchAll(
+      /^\s*#\s*define\s+([A-Z0-9_]+)\s+"([^"]+)"/gm,
+    )) {
+      if (!defineNames.has(match[1])) {
+        continue;
+      }
+      const version = match[2].trim();
+      if (!/^\d/.test(version)) {
+        continue;
+      }
+      const pathSegments = headerFile.split(/[\\/]/);
+      const isDisabledVariant = disabledFeatures.some((feature) =>
+        pathSegments.includes(feature),
+      );
+      if (isDisabledVariant) {
+        continue;
+      }
+      if (!candidates.has(version)) {
+        candidates.set(version, headerFile);
+      }
+    }
+  }
+  if (candidates.size === 1) {
+    const [version, headerFile] = [...candidates.entries()][0];
+    // The absolute path runs through the user's CARGO_HOME, which does not
+    // belong in a shared document; the crate-relative path is the part that
+    // lets a reviewer find the same define.
+    const registryMatch = headerFile.match(
+      /[\\/]registry[\\/]src[\\/][^\\/]+[\\/](.+)$/,
+    );
+    return {
+      version,
+      evidence: registryMatch ? registryMatch[1] : basename(headerFile),
+      candidates: [version],
+    };
+  }
+  // Several variants remain in play, so naming one of them would be a guess.
+  return { ...empty, candidates: [...candidates.keys()].sort() };
+}
+
+/**
+ * Build components for the native libraries that `-sys` crates link.
+ *
+ * A crate declaring `links = "openssl"` puts a C library into the artifact that
+ * the cargo dependency graph cannot describe: its advisories and its license
+ * obligations belong to OpenSSL, not to the Rust binding. When the resolver
+ * enabled a vendoring feature, that library is compiled into the binary, which
+ * makes it a component of the delivered assembly.
+ *
+ * @param {Map<string, object>} packageInfo Per-package facts from {@link parseCargoMetadataResolve}
+ * @param {Map<string, Array<object>>} edges Dependency edges keyed by component key
+ * @param {Map<string, object>} rollup Effective kinds, used to skip crates no build reaches
+ * @returns {{components: object[], dependencies: object[]}} Native library components and their edges
+ */
+export function buildCargoNativeLibraryComponents(packageInfo, edges, rollup) {
+  const components = [];
+  const dependencies = [];
+  const componentsByRef = new Map();
+  for (const [key, info] of packageInfo || []) {
+    if (!info?.links) {
+      continue;
+    }
+    // A crate no build reaches contributes no native library either.
+    const effective = rollup?.get(key);
+    if (rollup?.size && !effective) {
+      continue;
+    }
+    const resolvedFeatures = new Set(info.resolvedFeatures || []);
+    const linkFeatures = [...resolvedFeatures].filter((feature) =>
+      CARGO_STATIC_LINK_FEATURES.has(feature),
+    );
+    // A `*-src` dependency exists only to compile the library from source.
+    const sourceCrateKeys = (edges?.get(key) || [])
+      .map((edge) => edge.to)
+      .filter((to) => to.split("@")[0].endsWith("-src"));
+    const isStatic = linkFeatures.length > 0 || sourceCrateKeys.length > 0;
+    let upstreamVersion = "";
+    let versionSource = "";
+    for (const sourceCrateKey of sourceCrateKeys) {
+      const sourceInfo = packageInfo.get(sourceCrateKey);
+      upstreamVersion = cargoUpstreamVersionFromCrateVersion(
+        sourceInfo?.version || sourceCrateKey.split("@")[1],
+      );
+      if (upstreamVersion) {
+        versionSource = sourceCrateKey;
+        break;
+      }
+    }
+    if (!upstreamVersion) {
+      upstreamVersion = cargoUpstreamVersionFromCrateVersion(info.version);
+      if (upstreamVersion) {
+        versionSource = key;
+      }
+    }
+    const libraryName = CARGO_NATIVE_LIBRARY_NAMES[info.links] || info.links;
+    let versionCandidates = [];
+    if (!upstreamVersion && isStatic && info.manifestPath) {
+      const vendoredVersion = resolveCargoVendoredLibraryVersion({
+        crateDir: dirname(info.manifestPath),
+        declaredFeatures: info.declaredFeatures,
+        libraryName,
+        links: info.links,
+        resolvedFeatures,
+      });
+      upstreamVersion = vendoredVersion.version;
+      versionCandidates = vendoredVersion.candidates;
+      if (upstreamVersion) {
+        versionSource = vendoredVersion.evidence;
+      }
+    }
+    const purl = build({
+      type: "generic",
+      namespace: null,
+      name: libraryName,
+      version: upstreamVersion || null,
+    });
+    const bomRef = decodeURIComponent(purl);
+    const providerPurl = decodeURIComponent(
+      build({
+        type: "cargo",
+        namespace: null,
+        name: info.name || key.split("@")[0],
+        version: info.version || key.split("@")[1] || null,
+      }),
+    );
+    let component = componentsByRef.get(bomRef);
+    if (!component) {
+      component = {
+        "bom-ref": bomRef,
+        name: libraryName,
+        purl,
+        type: "library",
+        properties: [],
+        evidence: {
+          identity: {
+            field: "purl",
+            // The library is inferred from a manifest declaration rather than
+            // observed in the artifact, and its version, when known at all,
+            // comes from a crate version's build metadata.
+            confidence: upstreamVersion ? 0.5 : 0.3,
+            methods: [
+              {
+                technique: "manifest-analysis",
+                confidence: upstreamVersion ? 0.5 : 0.3,
+                value: info.manifestPath || "",
+              },
+            ],
+          },
+        },
+      };
+      if (upstreamVersion) {
+        component.version = upstreamVersion;
+      }
+      componentsByRef.set(bomRef, component);
+      components.push(component);
+    }
+    appendCargoProperty(component, "cdx:cargo:nativeLibrary", info.links);
+    appendCargoProperty(component, "cdx:cargo:providedBy", providerPurl);
+    appendCargoProperty(
+      component,
+      "cdx:cargo:linkage",
+      isStatic ? "static" : "dynamic",
+    );
+    if (!isStatic) {
+      // A dynamically linked library is not part of the assembly but is
+      // expected from the deployment environment, which is what CycloneDX 1.7
+      // calls an external component.
+      component.isExternal = true;
+    }
+    if (linkFeatures.length) {
+      appendCargoProperty(
+        component,
+        "cdx:cargo:linkageEvidence",
+        linkFeatures.sort().join(", "),
+      );
+    }
+    for (const sourceCrateKey of sourceCrateKeys) {
+      appendCargoProperty(
+        component,
+        "cdx:cargo:linkageEvidence",
+        sourceCrateKey,
+      );
+    }
+    if (versionSource) {
+      appendCargoProperty(
+        component,
+        "cdx:cargo:upstreamVersionSource",
+        versionSource,
+      );
+    }
+    if (!upstreamVersion && versionCandidates.length) {
+      // The crate ships several variants of the library and nothing in the
+      // build says which one is compiled, so the versions are reported as
+      // candidates rather than one of them being chosen.
+      appendCargoProperty(
+        component,
+        "cdx:cargo:upstreamVersionCandidates",
+        versionCandidates.join(", "),
+      );
+    }
+    dependencies.push({ ref: providerPurl, dependsOn: [bomRef] });
+    dependencies.push({ ref: bomRef, dependsOn: [] });
+  }
+  return { components, dependencies };
+}
+
 /**
  * Parses tab-separated cargo-auditable binary metadata output and returns a list
  * of Rust package components. Optionally fetches crates.io metadata when