@trustify-da/trustify-da-javascript-client 0.3.0-ea.e12bc82 → 0.3.0-ea.e258fba

package/dist/src/providers/rust_cargo.js

@@ -0,0 +1,682 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PackageURL } from 'packageurl-js';
+import { parse as parseToml } from 'smol-toml';
+import { getLicense } from '../license/license_utils.js';
+import Sbom from '../sbom.js';
+import { getCustom, getCustomPath, invokeCommand } from '../tools.js';
+export default { isSupported, validateLockFile, provideComponent, provideStack, readLicenseFromManifest, packageManagerName() { return 'cargo'; } };
+/** @typedef {import('../provider').Provider} */
+/** @typedef {import('../provider').Provided} Provided */
+/**
+ * @type {string} ecosystem identifier for cargo/crates packages
+ * @private
+ */
+const ecosystem = 'cargo';
+/**
+ * Ignore markers recognised in Cargo.toml comments.
+ * Supports both the legacy `exhortignore` marker and the new `trustify-da-ignore` marker.
+ * @type {string[]}
+ * @private
+ */
+const IGNORE_MARKERS = ['exhortignore', 'trustify-da-ignore'];
+/**
+ * Checks whether a line contains any of the recognised ignore markers.
+ * @param {string} line - the line to check
+ * @returns {boolean} true if the line contains at least one ignore marker
+ * @private
+ */
+function hasIgnoreMarker(line) {
+    return IGNORE_MARKERS.some(marker => line.includes(marker));
+}
+/**
+ * Checks whether a dependency name is in the ignored set, accounting for
+ * Cargo's underscore/hyphen equivalence
+ * @param {string} name - the dependency name to check
+ * @param {Set<string>} ignoredDeps - set of ignored dependency names
+ * @returns {boolean} true if the dependency should be ignored
+ * @private
+ */
+function isDepIgnored(name, ignoredDeps) {
+    if (ignoredDeps.has(name)) {
+        return true;
+    }
+    let normalized = name.replace(/_/g, '-');
+    if (normalized !== name && ignoredDeps.has(normalized)) {
+        return true;
+    }
+    normalized = name.replace(/-/g, '_');
+    if (normalized !== name && ignoredDeps.has(normalized)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Enum-like constants for Cargo project types.
+ * @private
+ */
+const CrateType = {
+    SINGLE_CRATE: 'SINGLE_CRATE',
+    WORKSPACE_VIRTUAL: 'WORKSPACE_VIRTUAL',
+    WORKSPACE_WITH_ROOT_CRATE: 'WORKSPACE_WITH_ROOT_CRATE'
+};
+/**
+ * @param {string} manifestName - the subject manifest name-type
+ * @returns {boolean} - return true if `Cargo.toml` is the manifest name-type
+ */
+function isSupported(manifestName) {
+    return 'Cargo.toml' === manifestName;
+}
+/**
+ * Read project license from Cargo.toml, with fallback to LICENSE file.
+ * Supports the `license` field under `[package]` (single crate / workspace
+ * with root) and under `[workspace.package]` (virtual workspaces).
+ * When a member crate uses `license = { workspace = true }`, the actual
+ * license is resolved from the workspace root Cargo.toml.
+ * @param {string} manifestPath - path to Cargo.toml
+ * @param {object} [metadata] - cargo metadata output (needed for workspace license resolution)
+ * @returns {string|null} SPDX identifier or null
+ */
+function readLicenseFromManifest(manifestPath, metadata) {
+    let fromManifest = null;
+    try {
+        let content = fs.readFileSync(manifestPath, 'utf-8');
+        let parsed = parseToml(content);
+        let packageLicense = parsed.package?.license;
+        if (typeof packageLicense === 'object' && packageLicense?.workspace === true) {
+            packageLicense = resolveWorkspaceLicense(parsed, metadata);
+        }
+        fromManifest = packageLicense
+            || parsed.workspace?.package?.license
+            || null;
+    }
+    catch (_) {
+        // leave fromManifest as null
+    }
+    return getLicense(fromManifest, manifestPath);
+}
+/**
+ * Resolve a workspace-inherited license from the workspace root Cargo.toml.
+ * @param {object} parsed - the parsed member crate Cargo.toml
+ * @param {object} [metadata] - cargo metadata output with workspace_root
+ * @returns {string|null} resolved license string or null
+ */
+function resolveWorkspaceLicense(parsed, metadata) {
+    if (metadata?.workspace_root) {
+        let cargoTomlPath = path.join(metadata.workspace_root, 'Cargo.toml');
+        try {
+            let content = fs.readFileSync(cargoTomlPath, 'utf-8');
+            let workspaceParsed = parseToml(content);
+            return workspaceParsed.workspace?.package?.license || null;
+        }
+        catch (_) {
+            // fall through
+        }
+    }
+    return parsed.workspace?.package?.license || null;
+}
+/**
+ * Finds the directory containing Cargo.lock, honoring TRUSTIFY_DA_WORKSPACE_DIR.
+ * Walks up from manifestDir looking for Cargo.lock, stopping at workspace root or filesystem root.
+ * @param {string} manifestDir - the directory where the manifest lies
+ * @param {{TRUSTIFY_DA_WORKSPACE_DIR?: string}} [opts={}] - optional workspace root
+ * @returns {string|null} the directory path containing Cargo.lock, or null if not found
+ * @private
+ */
+function _findCargoLockDir(manifestDir, opts = {}) {
+    const workspaceDir = getCustom('TRUSTIFY_DA_WORKSPACE_DIR', null, opts);
+    if (workspaceDir) {
+        const dir = path.resolve(workspaceDir);
+        return fs.existsSync(path.join(dir, 'Cargo.lock')) ? dir : null;
+    }
+    let dir = path.resolve(manifestDir);
+    let parent = dir;
+    do {
+        dir = parent;
+        if (fs.existsSync(path.join(dir, 'Cargo.lock'))) {
+            return dir;
+        }
+        // If this directory has a Cargo.toml with [workspace], the lock file
+        // should have been here — stop searching.
+        let cargoToml = path.join(dir, 'Cargo.toml');
+        if (fs.existsSync(cargoToml)) {
+            try {
+                let content = fs.readFileSync(cargoToml, 'utf-8');
+                if (/\[workspace\]/.test(content)) {
+                    return null;
+                }
+            }
+            catch (_) {
+                // ignore read errors, keep searching
+            }
+        }
+        parent = path.dirname(dir);
+    } while (parent !== dir);
+    return null;
+}
+/**
+ * Validates that Cargo.lock exists in the manifest directory or in a parent
+ * workspace root directory.  In Cargo workspaces the lock file always lives at
+ * the workspace root, so when a member crate's Cargo.toml is provided we walk
+ * up the directory tree looking for Cargo.lock (stopping when we find a
+ * Cargo.toml that contains a [workspace] section, or when we reach the
+ * filesystem root).
+ * When TRUSTIFY_DA_WORKSPACE_DIR is provided (via env var or opts),
+ * checks only that directory for Cargo.lock — no walk-up.
+ * @param {string} manifestDir - the directory where the manifest lies
+ * @param {{TRUSTIFY_DA_WORKSPACE_DIR?: string}} [opts={}] - optional workspace root
+ * @returns {boolean} true if Cargo.lock is found
+ */
+function validateLockFile(manifestDir, opts = {}) {
+    return _findCargoLockDir(manifestDir, opts) !== null;
+}
+/**
+ * Provide content and content type for Cargo stack analysis.
+ * @param {string} manifest - the manifest path
+ * @param {{}} [opts={}] - optional various options to pass along the application
+ * @returns {Provided}
+ */
+function provideStack(manifest, opts = {}) {
+    return {
+        ecosystem,
+        content: getSBOM(manifest, opts, true),
+        contentType: 'application/vnd.cyclonedx+json'
+    };
+}
+/**
+ * Provide content and content type for Cargo component analysis.
+ * @param {string} manifest - path to Cargo.toml for component report
+ * @param {{}} [opts={}] - optional various options to pass along the application
+ * @returns {Provided}
+ */
+function provideComponent(manifest, opts = {}) {
+    return {
+        ecosystem,
+        content: getSBOM(manifest, opts, false),
+        contentType: 'application/vnd.cyclonedx+json'
+    };
+}
+/**
+ * Create SBOM json string for a Cargo project.
+ * @param {string} manifest - path to Cargo.toml
+ * @param {{}} [opts={}] - optional various options to pass along the application
+ * @param {boolean} includeTransitive - whether the sbom should contain transitive dependencies
+ * @returns {string} the SBOM json content
+ * @private
+ */
+function getSBOM(manifest, opts = {}, includeTransitive) {
+    let cargoBin = getCustomPath('cargo', opts);
+    verifyCargoAccessible(cargoBin);
+    let manifestDir = path.dirname(manifest);
+    let metadata = executeCargoMetadata(cargoBin, manifestDir);
+    let ignoredDeps = getIgnoredDeps(manifest, metadata);
+    let crateType = detectCrateType(metadata);
+    let license = readLicenseFromManifest(manifest, metadata);
+    let hashMap = parseCargoLockHashes(manifestDir, opts);
+    let sbom;
+    if (crateType === CrateType.WORKSPACE_VIRTUAL) {
+        sbom = handleVirtualWorkspace(manifest, metadata, ignoredDeps, includeTransitive, opts, license, hashMap);
+    }
+    else {
+        sbom = handleSingleCrate(metadata, ignoredDeps, includeTransitive, opts, license, hashMap);
+    }
+    return sbom;
+}
+/**
+ * Verifies that the cargo binary is accessible.
+ * @param {string} cargoBin - path to cargo binary
+ * @throws {Error} if cargo is not accessible
+ * @private
+ */
+function verifyCargoAccessible(cargoBin) {
+    try {
+        invokeCommand(cargoBin, ['--version']);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`cargo binary is not accessible at "${cargoBin}"`);
+        }
+        throw new Error('failed to check for cargo binary', { cause: error });
+    }
+}
+/**
+ * Executes `cargo metadata` and returns the parsed JSON.
+ * @param {string} cargoBin - path to cargo binary
+ * @param {string} manifestDir - directory containing Cargo.toml
+ * @returns {object} parsed cargo metadata JSON
+ * @throws {Error} if cargo metadata fails
+ * @private
+ */
+function executeCargoMetadata(cargoBin, manifestDir) {
+    try {
+        let output = invokeCommand(cargoBin, ['metadata', '--format-version', '1'], { cwd: manifestDir });
+        return JSON.parse(output.toString().trim());
+    }
+    catch (error) {
+        throw new Error('failed to execute cargo metadata', { cause: error });
+    }
+}
+/**
+ * Parses Cargo.lock to extract SHA-256 checksums for each package.
+ * @param {string} manifestDir - directory containing Cargo.toml (Cargo.lock is searched upward)
+ * @param {{TRUSTIFY_DA_WORKSPACE_DIR?: string}} [opts={}] - optional workspace root
+ * @returns {Map<string, Array<{alg: string, content: string}>>} map of "name@version" to CycloneDX hashes
+ * @private
+ */
+function parseCargoLockHashes(manifestDir, opts = {}) {
+    let hashMap = new Map();
+    let lockDir = _findCargoLockDir(manifestDir, opts);
+    if (!lockDir) {
+        return hashMap;
+    }
+    let lockPath = path.join(lockDir, 'Cargo.lock');
+    try {
+        let content = fs.readFileSync(lockPath, 'utf-8');
+        let parsed = parseToml(content);
+        for (let pkg of (parsed.package || [])) {
+            if (pkg.name && pkg.version && pkg.checksum) {
+                hashMap.set(`${pkg.name}@${pkg.version}`, [{ alg: 'SHA-256', content: pkg.checksum }]);
+            }
+        }
+    }
+    catch (error) {
+        console.warn('Failed to parse Cargo.lock for hashes, SBOM will be generated without hashes');
+    }
+    return hashMap;
+}
+/**
+ * Detects the type of Cargo project from metadata.
+ * @param {object} metadata - parsed cargo metadata
+ * @returns {string} one of CrateType values
+ * @private
+ */
+function detectCrateType(metadata) {
+    let rootPackageId = metadata.resolve?.root;
+    let workspaceMembers = metadata.workspace_members || [];
+    if (!rootPackageId && workspaceMembers.length > 0) {
+        return CrateType.WORKSPACE_VIRTUAL;
+    }
+    if (rootPackageId && workspaceMembers.length > 1) {
+        return CrateType.WORKSPACE_WITH_ROOT_CRATE;
+    }
+    return CrateType.SINGLE_CRATE;
+}
+/**
+ * Handles SBOM generation for single crate and workspace-with-root-crate projects.
+ * For workspace-with-root-crate, workspace members are only included if they
+ * appear in the root crate's dependency graph from cargo metadata.  We don't
+ * automatically add all members as dependencies since most workspace members
+ * (examples, tools, benchmarks) depend ON the root crate, not the other way around.
+ * @param {object} metadata - parsed cargo metadata
+ * @param {Set<string>} ignoredDeps - set of ignored dependency names
+ * @param {boolean} includeTransitive - whether to include transitive dependencies
+ * @param {{}} opts - options
+ * @param {string|null} license - SPDX license identifier for the root component
+ * @returns {string} SBOM json string
+ * @private
+ */
+function handleSingleCrate(metadata, ignoredDeps, includeTransitive, opts, license, hashMap) {
+    let rootPackageId = metadata.resolve.root;
+    let rootPackage = findPackageById(metadata, rootPackageId);
+    let rootPurl = toPurl(rootPackage.name, rootPackage.version);
+    let sbom = new Sbom();
+    sbom.addRoot(rootPurl, license);
+    let resolveNode = findResolveNode(metadata, rootPackageId);
+    if (!resolveNode) {
+        return sbom.getAsJsonString(opts);
+    }
+    if (includeTransitive) {
+        addTransitiveDeps(sbom, metadata, rootPackageId, ignoredDeps, new Set(), hashMap, rootPurl);
+    }
+    else {
+        addDirectDeps(sbom, metadata, rootPackageId, rootPurl, ignoredDeps, hashMap);
+    }
+    return sbom.getAsJsonString(opts);
+}
+/**
+ * Handles SBOM generation for virtual workspace projects.
+ *
+ * For stack analysis (includeTransitive=true):
+ *   Iterates all workspace members and walks their full dependency trees.
+ *
+ * For component analysis (includeTransitive=false):
+ *   Only includes dependencies explicitly listed in [workspace.dependencies]
+ *   of the root Cargo.toml.  If that section is absent the SBOM contains only
+ *   the synthetic workspace root with no dependencies — this matches the Java
+ *   client behaviour where CA "just analyzes direct dependencies defined in
+ *   Cargo.toml".
+ *
+ * @param {string} manifest - path to the root Cargo.toml
+ * @param {object} metadata - parsed cargo metadata
+ * @param {Set<string>} ignoredDeps - set of ignored dependency names
+ * @param {boolean} includeTransitive - whether to include transitive dependencies
+ * @param {{}} opts - options
+ * @param {string|null} license - SPDX license identifier for the root component
+ * @returns {string} SBOM json string
+ * @private
+ */
+function handleVirtualWorkspace(manifest, metadata, ignoredDeps, includeTransitive, opts, license, hashMap) {
+    let workspaceRoot = metadata.workspace_root;
+    let rootName = path.basename(workspaceRoot);
+    let workspaceVersion = getWorkspaceVersion(metadata);
+    let rootPurl = toPurl(rootName, workspaceVersion);
+    let sbom = new Sbom();
+    sbom.addRoot(rootPurl, license);
+    if (includeTransitive) {
+        let workspaceMembers = metadata.workspace_members || [];
+        for (let memberId of workspaceMembers) {
+            let memberPackage = findPackageById(metadata, memberId);
+            if (!memberPackage) {
+                continue;
+            }
+            let memberPurl = memberPackage.source == null
+                ? toPathDepPurl(memberPackage.name, memberPackage.version)
+                : toPurl(memberPackage.name, memberPackage.version);
+            sbom.addDependency(rootPurl, memberPurl);
+            addTransitiveDeps(sbom, metadata, memberId, ignoredDeps, new Set(), hashMap, memberPurl);
+        }
+    }
+    else {
+        let workspaceDeps = getWorkspaceDepsFromManifest(manifest);
+        for (let depName of workspaceDeps) {
+            if (isDepIgnored(depName, ignoredDeps)) {
+                continue;
+            }
+            let pkg = metadata.packages.find(p => p.name === depName);
+            if (!pkg) {
+                let altName = depName.replace(/-/g, '_');
+                pkg = metadata.packages.find(p => p.name === altName);
+            }
+            if (!pkg) {
+                continue;
+            }
+            let depPurl = pkg.source == null
+                ? toPathDepPurl(pkg.name, pkg.version)
+                : toPurl(pkg.name, pkg.version);
+            let hashes = hashMap.get(`${pkg.name}@${pkg.version}`);
+            sbom.addDependency(rootPurl, depPurl, undefined, hashes);
+        }
+    }
+    return sbom.getAsJsonString(opts);
+}
+/**
+ * Recursively adds transitive dependencies to the SBOM.
+ * Path dependencies (source == null) are included with a
+ * {@code repository_url=local} qualifier so the backend can skip
+ * vulnerability checks while still showing them in the dependency tree.
+ * @param {Sbom} sbom - the SBOM to add dependencies to
+ * @param {object} metadata - parsed cargo metadata
+ * @param {string} packageId - the package ID to resolve dependencies for
+ * @param {Set<string>} ignoredDeps - set of ignored dependency names
+ * @param {Set<string>} visited - set of already-visited package IDs to prevent cycles
+ * @param {PackageURL} [startingPurl] - purl to use for the starting package,
+ *   so callers can ensure it matches the purl already added to the SBOM
+ * @private
+ */
+function addTransitiveDeps(sbom, metadata, packageId, ignoredDeps, visited, hashMap, startingPurl) {
+    if (visited.has(packageId)) {
+        return;
+    }
+    visited.add(packageId);
+    let resolveNode = findResolveNode(metadata, packageId);
+    if (!resolveNode) {
+        return;
+    }
+    let sourcePackage = findPackageById(metadata, packageId);
+    if (!sourcePackage) {
+        return;
+    }
+    let sourcePurl = startingPurl || (sourcePackage.source == null
+        ? toPathDepPurl(sourcePackage.name, sourcePackage.version)
+        : toPurl(sourcePackage.name, sourcePackage.version));
+    let runtimeDeps = filterRuntimeDeps(resolveNode);
+    for (let depId of runtimeDeps) {
+        let depPackage = findPackageById(metadata, depId);
+        if (!depPackage) {
+            continue;
+        }
+        if (isDepIgnored(depPackage.name, ignoredDeps)) {
+            continue;
+        }
+        let depPurl = depPackage.source == null
+            ? toPathDepPurl(depPackage.name, depPackage.version)
+            : toPurl(depPackage.name, depPackage.version);
+        let hashes = hashMap ? hashMap.get(`${depPackage.name}@${depPackage.version}`) : undefined;
+        sbom.addDependency(sourcePurl, depPurl, undefined, hashes);
+        addTransitiveDeps(sbom, metadata, depId, ignoredDeps, visited, hashMap);
+    }
+}
+/**
+ * Adds only direct (non-transitive) dependencies to the SBOM.
+ * Path dependencies are included with a {@code repository_url=local} qualifier.
+ * @param {Sbom} sbom - the SBOM to add dependencies to
+ * @param {object} metadata - parsed cargo metadata
+ * @param {string} packageId - the package ID to resolve dependencies for
+ * @param {PackageURL} parentPurl - the parent purl to attach dependencies to
+ * @param {Set<string>} ignoredDeps - set of ignored dependency names
+ * @private
+ */
+function addDirectDeps(sbom, metadata, packageId, parentPurl, ignoredDeps, hashMap) {
+    let resolveNode = findResolveNode(metadata, packageId);
+    if (!resolveNode) {
+        return;
+    }
+    let runtimeDeps = filterRuntimeDeps(resolveNode);
+    for (let depId of runtimeDeps) {
+        let depPackage = findPackageById(metadata, depId);
+        if (!depPackage) {
+            continue;
+        }
+        if (isDepIgnored(depPackage.name, ignoredDeps)) {
+            continue;
+        }
+        let depPurl = depPackage.source == null
+            ? toPathDepPurl(depPackage.name, depPackage.version)
+            : toPurl(depPackage.name, depPackage.version);
+        let hashes = hashMap ? hashMap.get(`${depPackage.name}@${depPackage.version}`) : undefined;
+        sbom.addDependency(parentPurl, depPurl, undefined, hashes);
+    }
+}
+/**
+ * Filters the deps of a resolve node to only include runtime (normal) dependencies.
+ * @param {object} resolveNode - a node from metadata.resolve.nodes
+ * @returns {string[]} array of package IDs for runtime dependencies
+ * @private
+ */
+function filterRuntimeDeps(resolveNode) {
+    if (!resolveNode.deps) {
+        return [];
+    }
+    return resolveNode.deps
+        .filter(dep => {
+        if (!dep.dep_kinds || dep.dep_kinds.length === 0) {
+            return true;
+        }
+        return dep.dep_kinds.some(dk => dk.kind == null || dk.kind === 'normal');
+    })
+        .map(dep => dep.pkg);
+}
+/**
+ * Finds a package in the metadata by its ID.
+ * @param {object} metadata - parsed cargo metadata
+ * @param {string} packageId - the package ID to find
+ * @returns {object|undefined} the found package or undefined
+ * @private
+ */
+function findPackageById(metadata, packageId) {
+    return metadata.packages.find(pkg => pkg.id === packageId);
+}
+/**
+ * Finds a resolve node by package ID.
+ * @param {object} metadata - parsed cargo metadata
+ * @param {string} packageId - the package ID to find
+ * @returns {object|undefined} the found resolve node or undefined
+ * @private
+ */
+function findResolveNode(metadata, packageId) {
+    return metadata.resolve.nodes.find(node => node.id === packageId);
+}
+/**
+ * Parses the root Cargo.toml and returns the dependency names listed in the
+ * [workspace.dependencies] section.  Returns an empty array when the section
+ * does not exist.
+ * @param {string} manifest - path to the root Cargo.toml
+ * @returns {string[]} list of dependency names
+ * @private
+ */
+function getWorkspaceDepsFromManifest(manifest) {
+    let content = fs.readFileSync(manifest, 'utf-8');
+    let parsed = parseToml(content);
+    return Object.keys(parsed.workspace?.dependencies || {});
+}
+/**
+ * Extracts the workspace version from metadata if defined.
+ * @param {object} metadata - parsed cargo metadata
+ * @returns {string} the workspace version or a placeholder
+ * @private
+ */
+function getWorkspaceVersion(metadata) {
+    let workspaceRoot = metadata.workspace_root;
+    let cargoTomlPath = path.join(workspaceRoot, 'Cargo.toml');
+    try {
+        let content = fs.readFileSync(cargoTomlPath, 'utf-8');
+        let parsed = parseToml(content);
+        return parsed.workspace?.package?.version || '0.0.0';
+    }
+    catch (_) {
+        return '0.0.0';
+    }
+}
+/**
+ * Parses Cargo.toml for dependencies annotated with an ignore marker.
+ * Supports both `exhortignore` and `trustify-da-ignore` markers.
+ * Supports inline deps, table-based deps, and workspace-level dependency sections.
+ * Uses cargo metadata to discover workspace members (which already handles glob
+ * expansion and exclude filtering) instead of parsing workspace member paths ourselves.
+ * @param {string} manifest - path to Cargo.toml
+ * @param {object} metadata - parsed cargo metadata
+ * @returns {Set<string>} set of dependency names to ignore
+ * @private
+ */
+function getIgnoredDeps(manifest, metadata) {
+    let ignored = new Set();
+    scanManifestForIgnored(manifest, ignored);
+    // Scan workspace member manifests using metadata
+    let manifestDir = path.dirname(manifest);
+    let workspaceRoot = metadata.workspace_root;
+    let workspaceMembers = metadata.workspace_members || [];
+    for (let memberId of workspaceMembers) {
+        let memberRelDir = getMemberRelativeDir(memberId, workspaceRoot);
+        if (memberRelDir == null) {
+            continue;
+        }
+        let memberManifest = path.join(manifestDir, memberRelDir, 'Cargo.toml');
+        if (path.resolve(memberManifest) === path.resolve(manifest)) {
+            continue;
+        }
+        if (fs.existsSync(memberManifest)) {
+            scanManifestForIgnored(memberManifest, ignored);
+        }
+    }
+    return ignored;
+}
+/**
+ * Extracts a workspace member's directory path relative to the workspace root
+ * from its cargo package ID.  Workspace member IDs use the `path+file://` scheme,
+ * e.g. `path+file:///workspace/root/crates/member#0.1.0`.
+ * @param {string} packageId - the cargo package ID
+ * @param {string} workspaceRoot - the workspace root path from cargo metadata
+ * @returns {string|null} relative directory path, or null if it cannot be determined
+ * @private
+ */
+function getMemberRelativeDir(packageId, workspaceRoot) {
+    let pathMatch = packageId.match(/path\+file:\/\/(.+?)#/);
+    if (!pathMatch) {
+        return null;
+    }
+    let pkgPath = pathMatch[1];
+    if (!pkgPath.startsWith(workspaceRoot)) {
+        return null;
+    }
+    let relPath = pkgPath.substring(workspaceRoot.length);
+    if (relPath.startsWith('/')) {
+        relPath = relPath.substring(1);
+    }
+    return relPath || null;
+}
+/**
+ * Scans a single Cargo.toml for ignored dependencies and adds them to the set.
+ * @param {string} manifest - path to Cargo.toml
+ * @param {Set<string>} ignored - the set to add ignored dependency names to
+ * @private
+ */
+function scanManifestForIgnored(manifest, ignored) {
+    let content = fs.readFileSync(manifest, 'utf-8');
+    let lines = content.split(/\r?\n/);
+    let currentSection = '';
+    let currentDepName = null;
+    for (let line of lines) {
+        let trimmed = line.trim();
+        let sectionMatch = trimmed.match(/^\[([^\]]+)\]\s*(?:#.*)?$/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1];
+            currentDepName = null;
+            let tableDep = currentSection.match(/^(?:dependencies|dev-dependencies|build-dependencies|workspace\.dependencies)\.(.+)$/);
+            if (tableDep) {
+                currentDepName = tableDep[1];
+                // If the section header line itself carries an ignore marker,
+                // immediately add the dep
+                if (hasIgnoreMarker(line)) {
+                    ignored.add(currentDepName);
+                }
+            }
+            continue;
+        }
+        let isIgnored = hasIgnoreMarker(line);
+        if (isIgnored && isInDependencySection(currentSection)) {
+            let inlineMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*=/);
+            if (inlineMatch) {
+                ignored.add(inlineMatch[1]);
+                continue;
+            }
+        }
+        if (isIgnored && currentDepName) {
+            ignored.add(currentDepName);
+            continue;
+        }
+    }
+}
+/**
+ * Checks if a section name is a dependency section.
+ * @param {string} section - the TOML section name
+ * @returns {boolean}
+ * @private
+ */
+function isInDependencySection(section) {
+    return section === 'dependencies' ||
+        section === 'dev-dependencies' ||
+        section === 'build-dependencies' ||
+        section === 'workspace.dependencies';
+}
+/**
+ * Creates a PackageURL for a Cargo/crates.io package.
+ * @param {string} name - the crate name
+ * @param {string} version - the crate version
+ * @returns {PackageURL} the package URL
+ * @private
+ */
+function toPurl(name, version) {
+    return new PackageURL(ecosystem, undefined, name, version, undefined, undefined);
+}
+/**
+ * Creates a PackageURL for a local path dependency, marked with a
+ * {@code repository_url=local} qualifier so the backend can distinguish
+ * it from registry packages and skip vulnerability checks.
+ * @param {string} name - the crate name
+ * @param {string} version - the crate version
+ * @returns {PackageURL} the package URL with local qualifier
+ * @private
+ */
+function toPathDepPurl(name, version) {
+    return new PackageURL(ecosystem, undefined, name, version, { repository_url: 'local' }, undefined);
+}