@cyclonedx/cdxgen 12.1.4 → 12.2.0

package/lib/helpers/utils.js

@@ -48,15 +48,16 @@ import {
   satisfies,
   valid,
 } from "semver";
-import { v4 as uuidv4 } from "uuid";
 import { xml2js } from "xml-js";
-import { parse as _load } from "yaml";
+import { parse as _load, parseAllDocuments } from "yaml";
 
 import { getTreeWithPlugin } from "../managers/piptree.js";
 import { IriValidationStrategy, validateIri } from "../parsers/iri.js";
 import Arborist from "../third-party/arborist/lib/index.js";
+import { parseWorkflowFile } from "./ciParsers/githubActions.js";
 import { extractPackageInfoFromHintPath } from "./dotnetutils.js";
 import { thoughtLog, traceLog } from "./logger.js";
+import { get_python_command_from_env, getVenvMetadata } from "./pythonutils.js";
 
 let url = import.meta?.url;
 if (url && !url.startsWith("file://")) {
@@ -78,12 +79,6 @@ export const isDeno = globalThis.Deno?.version?.deno !== undefined;
 
 export const isWin = platform() === "win32";
 export const isMac = platform() === "darwin";
-export let ATOM_DB = join(homedir(), ".local", "share", ".atomdb");
-if (isWin) {
-  ATOM_DB = join(homedir(), "AppData", "Local", ".atomdb");
-} else if (isMac) {
-  ATOM_DB = join(homedir(), "Library", "Application Support", ".atomdb");
-}
 
 /**
  * Safely check if a file path exists without crashing due to a lack of permissions
@@ -123,14 +118,68 @@ export function safeMkdirSync(filePath, options) {
 }
 
 export const commandsExecuted = new Set();
+const ALLOW_COMMANDS = (process.env.CDXGEN_ALLOWED_COMMANDS || "").split(",");
 function isAllowedCommand(command) {
   if (!process.env.CDXGEN_ALLOWED_COMMANDS) {
     return true;
   }
-  const allow_commands = (process.env.CDXGEN_ALLOWED_COMMANDS || "").split(",");
-  return allow_commands.includes(command.trim());
+  return ALLOW_COMMANDS.includes(command.trim());
+}
+
+const ALLOWED_WRAPPERS = new Set(["gradlew", "mvnw"]);
+
+/**
+ * Check for Windows CWD executable hijack when shell: true is used.
+ * cmd.exe searches CWD before PATH, allowing local files to shadow system commands.
+ *
+ * @param {string} command The executable to spawn
+ * @param {Object} options Options forwarded to spawnSync (e.g. cwd, env, shell)
+ *
+ * @returns {boolean} true if there is a hijack risk. false otherwise.
+ */
+function isWindowsShellHijackRisk(command, options) {
+  const cwd = options?.cwd;
+  const usesShell = options?.shell === true;
+  if (!isWin || !usesShell || !cwd || !command) {
+    return false;
+  }
+  if (/[\/\\]/.test(command)) {
+    return false;
+  }
+  const cmdBase = command.toLowerCase();
+  if (ALLOWED_WRAPPERS.has(cmdBase)) {
+    return false;
+  }
+  const pathExt = (
+    process.env.PATHEXT ||
+    ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC"
+  )
+    .split(";")
+    .filter(Boolean);
+  const candidates = [
+    cmdBase,
+    ...pathExt.map((ext) => cmdBase + ext.toLowerCase()),
+  ];
+  const absCwd = resolve(cwd);
+  for (const candidate of candidates) {
+    const candidatePath = path.join(absCwd, candidate);
+    if (existsSync(candidatePath)) {
+      return true;
+    }
+  }
+  return false;
 }
 
+/**
+ * Safe wrapper around spawnSync that enforces permission checks, injects default
+ * options (maxBuffer, encoding, timeout), warns about unsafe Python and pip/uv
+ * invocations, and records every executed command in the commandsExecuted set.
+ *
+ * @param {string} command The executable to spawn
+ * @param {string[]} args Arguments to pass to the command
+ * @param {Object} options Options forwarded to spawnSync (e.g. cwd, env, shell)
+ * @returns {Object} spawnSync result object with status, stdout, stderr, and error fields
+ */
 export function safeSpawnSync(command, args, options) {
   if (
     (isSecureMode && process.permission && !process.permission.has("child")) ||
@@ -146,6 +195,25 @@ export function safeSpawnSync(command, args, options) {
       error: new Error("No execute permission"),
     };
   }
+  if (isSecureMode) {
+    if (isWindowsShellHijackRisk(command, options)) {
+      const blockedReason = `${command} matches local file in cwd (Windows shell hijack risk)`;
+      console.warn(`\x1b[1;31mSecurity Alert: ${blockedReason}\x1b[0m`);
+      return {
+        status: 1,
+        stdout: undefined,
+        stderr: undefined,
+        error: new Error(blockedReason),
+      };
+    }
+    if (options?.cwd && options.cwd !== resolve(options.cwd)) {
+      if (DEBUG_MODE) {
+        console.log(
+          "Executing commands with a relative cwd can cause security issues.",
+        );
+      }
+    }
+  }
   if (!options) {
     options = {};
   }
@@ -175,6 +243,40 @@ export function safeSpawnSync(command, args, options) {
       );
     }
   }
+  let isPyPackageInstall = false;
+  if (command.includes("pip") && args?.includes("install")) {
+    isPyPackageInstall = true;
+  } else if (
+    command.includes("python") &&
+    args?.includes("pip") &&
+    args?.includes("install")
+  ) {
+    isPyPackageInstall = true;
+  } else if (
+    command.includes("uv") &&
+    args?.includes("pip") &&
+    args?.includes("install")
+  ) {
+    isPyPackageInstall = true;
+  }
+  if (isPyPackageInstall) {
+    const hasOnlyBinary = args?.some(
+      (arg) => arg === "--only-binary" || arg.startsWith("--only-binary="),
+    );
+    if (!hasOnlyBinary) {
+      if (isSecureMode) {
+        console.warn(
+          "\x1b[1;31mSecurity Alert: pip/uv install invoked without '--only-binary' argument in secure mode. This is a bug in cdxgen and introduces Arbitrary Code Execution (ACE) risks. Please report with an example repo here https://github.com/cdxgen/cdxgen/issues.\x1b[0m",
+        );
+      } else if (process.env?.CDXGEN_IN_CONTAINER === "true") {
+        console.log("Running pip/uv install without '--only-binary' argument.");
+      } else {
+        console.warn(
+          "\x1b[1;35mNotice: pip/uv install invoked without '--only-binary'. This allows executing untrusted setup.py scripts. Only run cdxgen in trusted directories.\x1b",
+        );
+      }
+    }
+  }
   traceLog("spawn", { command, args, ...options });
   commandsExecuted.add(command);
   // Fix for DEP0190 warning
@@ -268,6 +370,12 @@ export const PREFER_MAVEN_DEPS_TREE = !["false", "0"].includes(
   process.env?.PREFER_MAVEN_DEPS_TREE,
 );
 
+/**
+ * Determines whether license information should be fetched from remote sources,
+ * based on the FETCH_LICENSE environment variable.
+ *
+ * @returns {boolean} True if the FETCH_LICENSE env var is set to "true" or "1"
+ */
 export function shouldFetchLicense() {
   return (
     process.env.FETCH_LICENSE &&
@@ -275,6 +383,12 @@ export function shouldFetchLicense() {
   );
 }
 
+/**
+ * Determines whether VCS (version control system) information should be fetched
+ * for Go packages, based on the GO_FETCH_VCS environment variable.
+ *
+ * @returns {boolean} True if the GO_FETCH_VCS env var is set to "true" or "1"
+ */
 export function shouldFetchVCS() {
   return (
     process.env.GO_FETCH_VCS && ["true", "1"].includes(process.env.GO_FETCH_VCS)
@@ -301,6 +415,12 @@ const MAX_LICENSE_ID_LENGTH = 100;
 
 export const JAVA_CMD = getJavaCommand();
 
+/**
+ * Returns the Java executable command to use, resolved in priority order:
+ * JAVA_CMD env var > JAVA_HOME/bin/java > "java".
+ *
+ * @returns {string} Path or name of the Java executable
+ */
 export function getJavaCommand() {
   let javaCmd = "java";
   if (process.env.JAVA_CMD) {
@@ -317,6 +437,12 @@ export function getJavaCommand() {
 
 export const PYTHON_CMD = getPythonCommand();
 
+/**
+ * Returns the Python executable command to use, resolved in priority order:
+ * PYTHON_CMD env var > CONDA_PYTHON_EXE env var > "python".
+ *
+ * @returns {string} Path or name of the Python executable
+ */
 export function getPythonCommand() {
   let pythonCmd = "python";
   if (process.env.PYTHON_CMD) {
@@ -451,7 +577,6 @@ export const PROJECT_TYPE_ALIASES = {
     "typescript",
     "ts",
     "tsx",
-    "vsix",
     "yarn",
     "rush",
   ],
@@ -471,7 +596,11 @@ export const PROJECT_TYPE_ALIASES = {
     "poetry",
     "uv",
     "pdm",
+    "rye",
     "hatch",
+    "conda",
+    "miniconda",
+    "pyenv",
   ],
   go: ["go", "golang", "gomod", "gopkg"],
   rust: ["rust", "rust-lang", "cargo"],
@@ -542,6 +671,14 @@ export const PROJECT_TYPE_ALIASES = {
   scala: ["scala", "scala3", "sbt", "mill"],
   nix: ["nix", "nixos", "flake"],
   caxa: ["caxa"],
+  "vscode-extension": [
+    "vscode-extension",
+    "vsix",
+    "vscode",
+    "openvsx",
+    "vscode-extensions",
+    "ide-extensions",
+  ],
 };
 
 // Package manager aliases
@@ -1119,6 +1256,13 @@ export function readLicenseText(licenseFilepath, licenseContentType) {
   return null;
 }
 
+/**
+ * Fetches license information for a list of Swift packages by querying the
+ * GitHub repository license API for packages hosted on github.com.
+ *
+ * @param {Object[]} pkgList List of Swift package objects with optional repository.url fields
+ * @returns {Promise<Object[]>} Resolved list of package objects, each augmented with a license field where available
+ */
 export async function getSwiftPackageMetadata(pkgList) {
   const cdepList = [];
   for (const p of pkgList) {
@@ -1203,8 +1347,13 @@ export async function getNpmMetadata(pkgList) {
  *
  * @param {string} pkgJsonFile package.json file
  * @param {boolean} simple Return a simpler representation of the component by skipping extended attributes and license fetch.
+ * @param {boolean} securityProps Collect security-related properties
  */
-export async function parsePkgJson(pkgJsonFile, simple = false) {
+export async function parsePkgJson(
+  pkgJsonFile,
+  simple = false,
+  securityProps = false,
+) {
   const pkgList = [];
   if (safeExistsSync(pkgJsonFile)) {
     try {
@@ -1267,6 +1416,107 @@ export async function parsePkgJson(pkgJsonFile, simple = false) {
           },
         };
       }
+      if (securityProps) {
+        if (!apkg.properties) {
+          apkg.properties = [];
+        }
+        // Track executable binaries (potential code execution vectors)
+        if (pkgData.bin) {
+          const binValue =
+            typeof pkgData.bin === "object"
+              ? Object.keys(pkgData.bin).join(", ")
+              : pkgData.bin;
+          apkg.properties.push({
+            name: "cdx:npm:bin",
+            value: binValue,
+          });
+          apkg.properties.push({
+            name: "cdx:npm:has_binary",
+            value: "true",
+          });
+        }
+        // Track lifecycle scripts (preinstall, postinstall, etc. - code execution risk)
+        if (pkgData.scripts && Object.keys(pkgData.scripts).length) {
+          const scriptNames = Object.keys(pkgData.scripts).join(", ");
+          apkg.properties.push({
+            name: "cdx:npm:scripts",
+            value: scriptNames,
+          });
+          // Flag high-risk scripts specifically
+          const riskyScripts = [
+            "preinstall",
+            "install",
+            "postinstall",
+            "prepublish",
+            "prepare",
+          ].filter((script) => pkgData.scripts[script]);
+          if (riskyScripts.length) {
+            apkg.properties.push({
+              name: "cdx:npm:risky_scripts",
+              value: riskyScripts.join(", "),
+            });
+          }
+        }
+        // Track platform/architecture constraints
+        if (pkgData.cpu && Array.isArray(pkgData.cpu) && pkgData.cpu.length) {
+          apkg.properties.push({
+            name: "cdx:npm:cpu",
+            value: pkgData.cpu.join(", "),
+          });
+        }
+        if (pkgData.os && Array.isArray(pkgData.os) && pkgData.os.length) {
+          apkg.properties.push({
+            name: "cdx:npm:os",
+            value: pkgData.os.join(", "),
+          });
+        }
+        if (
+          pkgData.libc &&
+          Array.isArray(pkgData.libc) &&
+          pkgData.libc.length
+        ) {
+          apkg.properties.push({
+            name: "cdx:npm:libc",
+            value: pkgData.libc.join(", "),
+          });
+        }
+        // Track deprecation notices
+        if (pkgData.deprecated) {
+          apkg.properties.push({
+            name: "cdx:npm:deprecation_notice",
+            value: pkgData.deprecated,
+          });
+        }
+        // Track if package uses node-gyp (native C/C++ addons = higher risk)
+        if (
+          pkgData.gypfile === true ||
+          pkgData.files?.some((f) => f.endsWith(".gyp") || f.endsWith(".gypi"))
+        ) {
+          apkg.properties.push({
+            name: "cdx:npm:gypfile",
+            value: "true",
+          });
+          apkg.properties.push({
+            name: "cdx:npm:native_addon",
+            value: "true",
+          });
+          const nativeDeps = [
+            "nan",
+            "node-addon-api",
+            "bindings",
+            "node-gyp-build",
+          ];
+          const foundNativeDeps = Object.keys(
+            pkgData.dependencies || {},
+          ).filter((dep) => nativeDeps.includes(dep));
+          if (foundNativeDeps.length) {
+            apkg.properties.push({
+              name: "cdx:npm:native_deps",
+              value: foundNativeDeps.join(", "),
+            });
+          }
+        }
+      }
       pkgList.push(apkg);
     } catch (_err) {
       // continue regardless of error
@@ -1411,7 +1661,10 @@ export async function parsePkgLock(pkgLockFile, options = {}) {
             name: "ResolvedUrl",
             value: node.resolved,
           });
-          pkg.distribution = { url: node.resolved };
+          pkg.externalReferences.push({
+            type: "distribution",
+            url: node.resolved,
+          });
         }
       }
       if (node.location) {
@@ -1692,7 +1945,7 @@ export async function parsePkgLock(pkgLockFile, options = {}) {
         if (!targetVersion || !targetName) {
           if (pkgSpecVersionCache[`${edge.name}-${edge.spec}`]) {
             targetVersion = pkgSpecVersionCache[`${edge.name}-${edge.spec}`];
-            targetName = edge.name;
+            targetName = edge.name.replace(/-cjs$/, "");
           }
         }
       }
@@ -2735,6 +2988,13 @@ function findMatchingWorkspace(workspacePackages, packageName) {
   );
 }
 
+/**
+ * Parses the workspaces field from a package.json file and returns the list of
+ * workspace glob patterns. Handles both array and object (with packages key) formats.
+ *
+ * @param {string} packageJsonFile Path to the package.json file to parse
+ * @returns {Object} Object with a packages array of workspace glob patterns, or an empty object on error
+ */
 export function parseYarnWorkspace(packageJsonFile) {
   try {
     const packageData = JSON.parse(readFileSync(packageJsonFile, "utf-8"));
@@ -2830,45 +3090,31 @@ export function findPnpmPackagePath(baseDir, packageName, version) {
  * @returns {Array} Enhanced package list
  */
 export async function pnpmMetadata(pkgList, lockFilePath) {
-  if (!pkgList || !pkgList.length || !lockFilePath) {
+  if (!pkgList?.length || !lockFilePath) {
     return pkgList;
   }
-
   const baseDir = dirname(lockFilePath);
   const nodeModulesDir = join(baseDir, "node_modules");
-
-  // Only proceed if node_modules exists
   if (!safeExistsSync(nodeModulesDir)) {
     return pkgList;
   }
-
   if (DEBUG_MODE) {
     console.log(
       `Metadata for ${pkgList.length} pnpm packages using local node_modules at ${nodeModulesDir}`,
     );
   }
-
   let enhancedCount = 0;
   for (const pkg of pkgList) {
-    // Skip if package already has complete metadata
-    if (pkg.description && pkg.author && pkg.license) {
-      continue;
-    }
-
-    // Find the package path in node_modules
     const packagePath = findPnpmPackagePath(baseDir, pkg.name, pkg.version);
     if (!packagePath) {
       continue;
     }
-
     const packageJsonPath = join(packagePath, "package.json");
     if (!safeExistsSync(packageJsonPath)) {
       continue;
     }
-
     try {
-      // Parse the local package.json to get metadata
-      const localPkgList = await parsePkgJson(packageJsonPath, true);
+      const localPkgList = await parsePkgJson(packageJsonPath, true, true);
       if (localPkgList && localPkgList.length === 1) {
         const localMetadata = localPkgList[0];
         if (localMetadata && Object.keys(localMetadata).length) {
@@ -2887,16 +3133,27 @@ export async function pnpmMetadata(pkgList, lockFilePath) {
           if (!pkg.repository && localMetadata.repository) {
             pkg.repository = localMetadata.repository;
           }
-
-          // Add a property to track that we enhanced from local node_modules
           if (!pkg.properties) {
             pkg.properties = [];
           }
+          if (localMetadata?.properties?.length) {
+            const seenProperties = new Set(
+              pkg.properties.map(
+                (prop) => `${String(prop?.name)}\u0000${String(prop?.value)}`,
+              ),
+            );
+            for (const prop of localMetadata.properties) {
+              const propertyKey = `${String(prop?.name)}\u0000${String(prop?.value)}`;
+              if (!seenProperties.has(propertyKey)) {
+                pkg.properties.push(prop);
+                seenProperties.add(propertyKey);
+              }
+            }
+          }
           pkg.properties.push({
             name: "LocalNodeModulesPath",
             value: packagePath,
           });
-
           enhancedCount++;
         }
       }
@@ -2910,13 +3167,11 @@ export async function pnpmMetadata(pkgList, lockFilePath) {
       }
     }
   }
-
   if (DEBUG_MODE && enhancedCount > 0) {
     console.log(
       `Enhanced metadata for ${enhancedCount} packages from local node_modules`,
     );
   }
-
   return pkgList;
 }
 
@@ -2979,10 +3234,18 @@ export async function parsePnpmLock(
   }
   if (safeExistsSync(pnpmLock)) {
     const lockData = readFileSync(pnpmLock, "utf8");
-    const yamlObj = _load(lockData);
+    let yamlObj = parseAllDocuments(lockData);
     if (!yamlObj) {
       return {};
     }
+    if (Array.isArray(yamlObj)) {
+      try {
+        yamlObj = yamlObj[yamlObj.length - 1].toJS();
+      } catch (_e) {
+        console.log(`Unable to parse the pnpm lock file ${pnpmLock}.`);
+        return {};
+      }
+    }
     lockfileVersion = yamlObj.lockfileVersion;
     try {
       lockfileVersion = Number.parseFloat(lockfileVersion, 10);
@@ -3281,6 +3544,7 @@ export async function parsePnpmLock(
         packages[fullName]?.resolution ||
         snapshots[fullName]?.resolution;
       const integrity = resolution?.integrity;
+      const tarball = resolution?.tarball;
       const cpu =
         packages[pkgKeys[k]]?.cpu ||
         snapshots[pkgKeys[k]]?.cpu ||
@@ -3499,10 +3763,10 @@ export async function parsePnpmLock(
               value: pnpmLock,
             },
           ];
-          if (hasBin || os || cpu || libc) {
+          if (hasBin) {
             properties.push({
               name: "cdx:npm:has_binary",
-              value: `${hasBin}`,
+              value: "true",
             });
           }
           if (deprecatedMessage) {
@@ -3515,7 +3779,7 @@ export async function parsePnpmLock(
           Object.entries(binary_metadata).forEach(([key, value]) => {
             if (!value) return;
             properties.push({
-              name: `cdx:pnpm:${key}`,
+              name: `cdx:npm:${key}`,
               value: Array.isArray(value) ? value.join(", ") : value,
             });
           });
@@ -3613,6 +3877,14 @@ export async function parsePnpmLock(
               },
             },
           };
+          if (tarball) {
+            thePkg.externalReferences = [
+              {
+                type: "distribution",
+                url: tarball,
+              },
+            ];
+          }
           // Don't add internal workspace packages to the components list
           if (thePkg.type !== "application") {
             pkgList.push(thePkg);
@@ -4646,6 +4918,15 @@ export function parseLeinDep(rawOutput) {
   return [];
 }
 
+/**
+ * Recursively walks a parsed EDN map node produced by the Leiningen dependency
+ * tree and collects unique dependency entries into the deps array.
+ *
+ * @param {Object} node Parsed EDN node (expected to have a "map" property)
+ * @param {Object} keys_cache Cache object used to deduplicate entries by group-name-version key
+ * @param {Object[]} deps Accumulator array of dependency objects with group, name, and version fields
+ * @returns {Object[]} The populated deps array
+ */
 export function parseLeinMap(node, keys_cache, deps) {
   if (node["map"]) {
     for (const n of node["map"]) {
@@ -5096,7 +5377,7 @@ export async function getMvnMetadata(
   const ANDROID_MAVEN_URL =
     process.env.ANDROID_MAVEN_URL || "https://maven.google.com/";
   const cdepList = [];
-  if (!pkgList || !pkgList.length) {
+  if (!pkgList?.length) {
     return pkgList;
   }
   if (DEBUG_MODE && shouldFetchLicense()) {
@@ -5390,7 +5671,7 @@ export async function getPyMetadata(pkgList, fetchDepsInfo) {
   const PYPI_URL = process.env.PYPI_URL || "https://pypi.org/pypi/";
   const cdepList = [];
   for (const p of pkgList) {
-    if (!p || !p.name) {
+    if (!p?.name) {
       continue;
     }
     try {
@@ -5474,7 +5755,7 @@ export async function getPyMetadata(pkgList, fetchDepsInfo) {
         }
       }
       // Use the latest version if none specified
-      if (!p.version || !p.version.trim().length) {
+      if (!p.version?.trim().length) {
         let versionSpecifiers;
         if (p.properties?.length) {
           for (const pprop of p.properties) {
@@ -5629,6 +5910,9 @@ export function parseBdistMetadata(mDataFile, rawMetadata = undefined) {
     externalReferences: [],
     properties: [],
   };
+  if (mDataFile) {
+    pkg.properties.push({ name: "SrcFile", value: mDataFile });
+  }
   const lines = mData.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
   let isBody = false;
   for (const line of lines) {
@@ -6467,7 +6751,8 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
         },
       }
     : undefined;
-  const lines = reqData.replace(/\r/g, "").replace(/\\$/gm, "").split("\n");
+  const normalizedData = reqData.replace(/\r/g, "").replace(/\\\n/g, " ");
+  const lines = normalizedData.split("\n");
   for (const line of lines) {
     let l = line.trim();
     if (l.includes("# Basic requirements")) {
@@ -6495,7 +6780,25 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
           },
         ]
       : [];
-
+    const hashes = [];
+    const hashRegex = /--hash=([a-zA-Z0-9\-]+):([a-fA-F0-9]+)/g;
+    let hashMatch;
+    while ((hashMatch = hashRegex.exec(l)) !== null) {
+      let alg = hashMatch[1].toUpperCase();
+      if (alg === "SHA256") alg = "SHA-256";
+      else if (alg === "SHA384") alg = "SHA-384";
+      else if (alg === "SHA512") alg = "SHA-512";
+      else if (alg === "SHA1") alg = "SHA-1";
+      hashes.push({
+        alg: alg,
+        content: hashMatch[2],
+      });
+    }
+    // Strip the hash flags and any residual backslashes
+    l = l
+      .replace(/--hash=[a-zA-Z0-9\-]+:[a-fA-F0-9]+/g, "")
+      .replace(/\\/g, "")
+      .trim();
     // Handle markers
     let markers = null;
     let structuredMarkers = null;
@@ -6535,6 +6838,9 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
         scope: compScope,
         evidence,
       };
+      if (hashes.length > 0) {
+        apkg.hashes = hashes;
+      }
       if (comment) {
         apkg.licenses = comment
           .split("/")
@@ -7238,6 +7544,16 @@ async function getGoPkgVCSUrl(group, name) {
   return undefined;
 }
 
+/**
+ * Builds a Go package component object containing purl, bom-ref, integrity hash,
+ * and optionally license and VCS external reference information.
+ *
+ * @param {string} group Package group (module path prefix, may be empty)
+ * @param {string} name Package name (full module path when group is empty)
+ * @param {string} version Package version string
+ * @param {string} hash Integrity hash (e.g. "sha256-…"), used as _integrity
+ * @returns {Promise<Object>} Component object ready for inclusion in a BOM package list
+ */
 export async function getGoPkgComponent(group, name, version, hash) {
   let license;
   if (shouldFetchLicense()) {
@@ -7421,6 +7737,15 @@ export async function parseGoModData(goModData, gosumMap) {
   };
 }
 
+/**
+ * Parses a Go modules text file (e.g. vendor/modules.txt) and returns a list of
+ * Go package components. Cross-references the go.sum map for integrity hashes and
+ * sets scope and confidence based on hash availability.
+ *
+ * @param {string} txtFile Path to the modules.txt file
+ * @param {Object} gosumMap Map of "module@version" keys to sha256 hash values from go.sum
+ * @returns {Promise<Object[]>} List of Go package component objects with evidence
+ */
 export async function parseGoModulesTxt(txtFile, gosumMap) {
   const pkgList = [];
   const txtData = readFileSync(txtFile, { encoding: "utf-8" });
@@ -7824,6 +8149,14 @@ export async function parseGosumData(gosumData) {
   return pkgList;
 }
 
+/**
+ * Parses the contents of a Gopkg.lock or Gopkg.toml file (dep tool format) and
+ * returns a list of Go package components. Optionally fetches license information
+ * for each package when FETCH_LICENSE is enabled.
+ *
+ * @param {string} gopkgData Raw string contents of the Gopkg lock/toml file
+ * @returns {Promise<Object[]>} List of Go package component objects
+ */
 export async function parseGopkgData(gopkgData) {
   const pkgList = [];
   if (!gopkgData) {
@@ -7873,6 +8206,13 @@ export async function parseGopkgData(gopkgData) {
   return pkgList;
 }
 
+/**
+ * Parses the output of `go version -m` (build info) and returns a list of Go
+ * package components for each "dep" line, including name, version, and integrity hash.
+ *
+ * @param {string} buildInfoData Raw string output from `go version -m`
+ * @returns {Promise<Object[]>} List of Go package component objects
+ */
 export async function parseGoVersionData(buildInfoData) {
   const pkgList = [];
   if (!buildInfoData) {
@@ -9199,6 +9539,13 @@ export async function parseCargoData(
   return pkgList;
 }
 
+/**
+ * Parses a Cargo.lock file's TOML data and returns a flat dependency graph as an
+ * array of objects mapping each package purl to the purls it directly depends on.
+ *
+ * @param {string} cargoLockData Raw TOML string contents of a Cargo.lock file
+ * @returns {Object[]} Array of dependency relationship objects with ref and dependsOn fields
+ */
 export function parseCargoDependencyData(cargoLockData) {
   const purlFromPackageInfo = (pkg) =>
     decodeURIComponent(
@@ -9258,6 +9605,14 @@ export function parseCargoDependencyData(cargoLockData) {
   return result;
 }
 
+/**
+ * Parses tab-separated cargo-auditable binary metadata output and returns a list
+ * of Rust package components. Optionally fetches crates.io metadata when
+ * FETCH_LICENSE is enabled.
+ *
+ * @param {string} cargoData Tab-separated string output from cargo-auditable or similar tool
+ * @returns {Promise<Object[]>} List of Rust package component objects with group, name, and version
+ */
 export async function parseCargoAuditableData(cargoData) {
   const pkgList = [];
   if (!cargoData) {
@@ -9360,6 +9715,13 @@ export async function parsePubLockData(pubLockData, lockFile) {
   return { rootList, pkgList };
 }
 
+/**
+ * Parses a Dart pub package's pubspec.yaml content and returns a list containing
+ * a single component object with name, description, version, homepage, and purl.
+ *
+ * @param {string} pubYamlData Raw YAML string contents of a pubspec.yaml file
+ * @returns {Object[]} List containing a single Dart package component object
+ */
 export function parsePubYamlData(pubYamlData) {
   const pkgList = [];
   let yamlObj;
@@ -9386,6 +9748,14 @@ export function parsePubYamlData(pubYamlData) {
   return pkgList;
 }
 
+/**
+ * Parses Helm chart YAML data (Chart.yaml or repository index.yaml) and returns
+ * a list of Helm chart component objects including the chart itself and any
+ * declared dependencies or index entries.
+ *
+ * @param {string} helmData Raw YAML string contents of a Helm Chart.yaml or index.yaml file
+ * @returns {Object[]} List of Helm chart component objects with name, version, and optional homepage/repository
+ */
 export function parseHelmYamlData(helmData) {
   const pkgList = [];
   let yamlObj;
@@ -9451,6 +9821,17 @@ export function parseHelmYamlData(helmData) {
   return pkgList;
 }
 
+/**
+ * Recursively walks a parsed YAML/JSON object structure to find container image
+ * references stored under common keys (image, repository, dockerImage, etc.) and
+ * appends discovered image and service entries to pkgList while tracking seen
+ * images in imgList to avoid duplicates.
+ *
+ * @param {Object|Array|string} keyValueObj The object, array, or string node to inspect
+ * @param {Object[]} pkgList Accumulator array that receives {image} and {service} entries
+ * @param {string[]} imgList Accumulator array of image name strings already seen
+ * @returns {string[]} The updated imgList
+ */
 export function recurseImageNameLookup(keyValueObj, pkgList, imgList) {
   if (typeof keyValueObj === "string" || keyValueObj instanceof String) {
     return imgList;
@@ -9536,6 +9917,14 @@ function substituteBuildArgs(statement, buildArgs) {
   return statement;
 }
 
+/**
+ * Parses the contents of a Dockerfile or Containerfile and returns a list of
+ * base image objects referenced by FROM instructions, substituting ARG default
+ * values where possible and skipping multi-stage build alias references.
+ *
+ * @param {string} fileContents Raw string contents of the Dockerfile/Containerfile
+ * @returns {Object[]} Array of objects with an image property for each unique base image
+ */
 export function parseContainerFile(fileContents) {
   const buildArgs = new Map();
   const imagesSet = new Set();
@@ -9603,6 +9992,13 @@ export function parseContainerFile(fileContents) {
   });
 }
 
+/**
+ * Parses a Bitbucket Pipelines YAML file and extracts all Docker image references
+ * used as build environments and pipe references (docker:// pipes are normalized).
+ *
+ * @param {string} fileContents Raw string contents of the bitbucket-pipelines.yml file
+ * @returns {Object[]} Array of objects with an image property for each referenced image or pipe
+ */
 export function parseBitbucketPipelinesFile(fileContents) {
   const imgList = [];
 
@@ -9664,6 +10060,14 @@ export function parseBitbucketPipelinesFile(fileContents) {
   return imgList;
 }
 
+/**
+ * Parses container specification data such as Docker Compose files, Kubernetes
+ * manifests, Tekton tasks, Skaffold configs, or Kustomize overlays (YAML, possibly
+ * multi-document) and returns a list of image, service, and OCI spec entries.
+ *
+ * @param {string} dcData Raw YAML string contents of the container spec file
+ * @returns {Object[]} Array of objects with image, service, or ociSpec properties
+ */
 export function parseContainerSpecData(dcData) {
   const pkgList = [];
   const imgList = [];
@@ -9731,6 +10135,14 @@ export function parseContainerSpecData(dcData) {
   return pkgList;
 }
 
+/**
+ * Identifies the data flow direction of a Privado processing object based on its
+ * sinkId value: "write" sinks map to "inbound", "read" sinks to "outbound", and
+ * HTTP/gRPC sinks to "bi-directional".
+ *
+ * @param {Object} processingObj Privado processing object, expected to have a sinkId property
+ * @returns {string} Flow direction string: "inbound", "outbound", "bi-directional", or "unknown"
+ */
 export function identifyFlow(processingObj) {
   let flow = "unknown";
   if (processingObj.sinkId) {
@@ -9757,6 +10169,14 @@ function convertProcessing(processing_list) {
   return data_list;
 }
 
+/**
+ * Parses a Privado data flow JSON file and returns a list of service objects
+ * enriched with data classifications, endpoints, trust-boundary flag, violations,
+ * and git metadata properties extracted from the scan result.
+ *
+ * @param {string} f Path to the Privado scan result JSON file
+ * @returns {Object[]} List of service component objects suitable for a SaaSBOM
+ */
 export function parsePrivadoFile(f) {
   const pData = readFileSync(f, { encoding: "utf-8" });
   const servlist = [];
@@ -9838,6 +10258,15 @@ export function parsePrivadoFile(f) {
   return servlist;
 }
 
+/**
+ * Parses an OpenAPI specification (JSON or YAML string) and returns a list
+ * containing a single service object with name, version, endpoints, and
+ * authentication flag derived from the spec's info, servers, paths, and
+ * securitySchemes sections.
+ *
+ * @param {string} oaData Raw JSON or YAML string contents of an OpenAPI specification
+ * @returns {Object[]} List containing a single service component object
+ */
 export function parseOpenapiSpecData(oaData) {
   const servlist = [];
   if (!oaData) {
@@ -9890,6 +10319,13 @@ export function parseOpenapiSpecData(oaData) {
   return servlist;
 }
 
+/**
+ * Parses Haskell Cabal freeze file content and extracts package name and version
+ * pairs from constraint lines (lines containing " ==").
+ *
+ * @param {string} cabalData Raw string contents of a Cabal freeze file
+ * @returns {Object[]} List of package objects with name and version fields
+ */
 export function parseCabalData(cabalData) {
   const pkgList = [];
   if (!cabalData) {
@@ -9918,6 +10354,13 @@ export function parseCabalData(cabalData) {
   return pkgList;
 }
 
+/**
+ * Parses an Elixir mix.lock file and extracts Hex package name and version pairs
+ * from lines containing ":hex".
+ *
+ * @param {string} mixData Raw string contents of a mix.lock file
+ * @returns {Object[]} List of package objects with name and version fields
+ */
 export function parseMixLockData(mixData) {
   const pkgList = [];
   if (!mixData) {
@@ -9945,404 +10388,55 @@ export function parseMixLockData(mixData) {
   return pkgList;
 }
 
+/**
+ * Parses a GitHub Actions workflow YAML file and returns a list of action
+ * components for each step that uses an external action (steps with a "uses"
+ * field). Each component captures the action name, group, version/commit SHA,
+ * version pinning type, job context (runner, permissions, environment), and
+ * workflow-level metadata (triggers, concurrency, write permissions).
+ *
+ * @param {string} f Path to the GitHub Actions workflow YAML file
+ * @returns {Object[]} List of action component objects with purl, properties, and evidence
+ */
 export function parseGitHubWorkflowData(f) {
+  const { components } = parseWorkflowFile(f);
+  return components.filter((c) => c.scope === "required");
+}
+
+/**
+ * Parse Google Cloud Build YAML data and extract container image steps as packages.
+ *
+ * @param {string} cbwData Raw YAML string of a Cloud Build configuration file
+ * @returns {Object[]} Array of package objects parsed from the build steps
+ */
+export function parseCloudBuildData(cbwData) {
   const pkgList = [];
-  if (!f) {
-    return pkgList;
-  }
-  const ghwData = readFileSync(f, { encoding: "utf-8" });
   const keys_cache = {};
-  if (!ghwData) {
+  if (!cbwData) {
     return pkgList;
   }
-  const yamlObj = _load(ghwData);
+  const yamlObj = _load(cbwData);
   if (!yamlObj) {
     return pkgList;
   }
-  const lines = ghwData.split("\n");
-  // workflow-related values
-  const workflowName = yamlObj.name || path.basename(f, path.extname(f));
-  const workflowTriggers = yamlObj.on || yamlObj.true;
-  const workflowPermissions = yamlObj.permissions || {};
-  let hasWritePermissions = analyzePermissions(workflowPermissions);
-  // GitHub of course supports strings such as "write-all" to make it easy to create supply-chain attacks.
-  if (
-    (typeof workflowPermissions === "string" ||
-      workflowPermissions instanceof String) &&
-    workflowPermissions.includes("write")
-  ) {
-    hasWritePermissions = true;
-  }
-  const workflowConcurrency = yamlObj.concurrency || {};
-  const _workflowEnv = yamlObj.env || {};
-  const hasIdTokenWrite = workflowPermissions?.["id-token"] === "write";
-  for (const jobName of Object.keys(yamlObj.jobs)) {
-    const job = yamlObj.jobs[jobName];
-    if (!job.steps) {
-      continue;
-    }
-    // job-related values
-    const jobRunner = job["runs-on"] || "unknown";
-    const jobEnvironment = job.environment?.name || job.environment || "";
-    const jobTimeout = job["timeout-minutes"] || null;
-    const jobPermissions = job.permissions || {};
-    const jobServices = job.services ? Object.keys(job.services) : [];
-    let jobNeeds = job.needs || [];
-    if (!Array.isArray(jobNeeds)) {
-      jobNeeds = [jobNeeds];
-    }
-    const _jobIf = job.if || "";
-    const _jobStrategy = job.strategy ? JSON.stringify(job.strategy) : "";
-    const jobHasWritePermissions = analyzePermissions(jobPermissions);
-    for (const step of job.steps) {
-      if (step.uses) {
-        const tmpA = step.uses.split("@");
-        if (tmpA.length !== 2) {
-          continue;
-        }
-        const groupName = tmpA[0];
-        let name = groupName;
-        let group = "";
-        const tagOrCommit = tmpA[1];
-        let version = tagOrCommit;
-        const tmpB = groupName.split("/");
-        if (tmpB.length >= 2) {
-          name = tmpB.pop();
-          group = tmpB.join("/");
-        } else if (tmpB.length === 1) {
-          name = tmpB[0];
-          group = "";
-        }
-        const versionPinningType = getVersionPinningType(tagOrCommit);
-        const isShaPinned = versionPinningType === "sha";
-        const _isTagPinned = versionPinningType === "tag";
-        const _isBranchRef = versionPinningType === "branch";
-        let lineNum = -1;
-        const stepLineMatch = ghwData.indexOf(step.uses);
-        if (stepLineMatch >= 0) {
-          lineNum = ghwData.substring(0, stepLineMatch).split("\n").length - 1;
-        }
-        if (lineNum >= 0 && lines[lineNum]) {
-          const line = lines[lineNum];
-          const commentMatch = line.match(/#\s*v?([0-9]+(?:\.[0-9]+)*)/);
-          if (commentMatch?.[1]) {
-            version = commentMatch[1];
-          }
-        }
-        const key = `${group}-${name}-${version}`;
-        let confidence = 0.6;
-        if (!keys_cache[key] && name && version) {
-          keys_cache[key] = key;
-          let fullName = name;
-          if (group.length) {
-            fullName = `${group}/${name}`;
-          }
-          let purl = `pkg:github/${fullName}@${version}`;
-          if (tagOrCommit && version !== tagOrCommit) {
-            const qualifierDesc = tagOrCommit.startsWith("v")
-              ? "tag"
-              : "commit";
-            purl = `${purl}?${qualifierDesc}=${tagOrCommit}`;
-            confidence = 0.7;
-          }
-          const properties = [
-            { name: "SrcFile", value: f },
-            { name: "cdx:github:workflow:name", value: workflowName },
-            { name: "cdx:github:job:name", value: jobName },
-            {
-              name: "cdx:github:job:runner",
-              value: Array.isArray(jobRunner) ? jobRunner.join(",") : jobRunner,
-            },
-            { name: "cdx:github:action:uses", value: step.uses },
-            {
-              name: "cdx:github:action:versionPinningType",
-              value: versionPinningType,
-            },
-            {
-              name: "cdx:github:action:isShaPinned",
-              value: isShaPinned.toString(),
-            },
-          ];
-          if (step.name) {
-            properties.push({ name: "cdx:github:step:name", value: step.name });
-          }
-          if (step.if) {
-            properties.push({
-              name: "cdx:github:step:condition",
-              value: step.if,
-            });
-          }
-          if (step["continue-on-error"]) {
-            properties.push({
-              name: "cdx:github:step:continueOnError",
-              value: "true",
-            });
+  if (yamlObj.steps) {
+    for (const step of yamlObj.steps) {
+      if (step.name) {
+        const tmpA = step.name.split(":");
+        if (tmpA.length === 2) {
+          let group = dirname(tmpA[0]);
+          const name = basename(tmpA[0]);
+          if (group === ".") {
+            group = "";
           }
-          if (step.timeout) {
-            properties.push({
-              name: "cdx:github:step:timeout",
-              value: step.timeout.toString(),
-            });
-          }
-          if (jobEnvironment) {
-            properties.push({
-              name: "cdx:github:job:environment",
-              value: jobEnvironment,
-            });
-          }
-          if (jobTimeout) {
-            properties.push({
-              name: "cdx:github:job:timeoutMinutes",
-              value: jobTimeout.toString(),
-            });
-          }
-          if (jobHasWritePermissions) {
-            properties.push({
-              name: "cdx:github:job:hasWritePermissions",
-              value: "true",
-            });
-          }
-          if (jobServices.length > 0) {
-            properties.push({
-              name: "cdx:github:job:services",
-              value: jobServices.join(","),
-            });
-          }
-          if (jobNeeds.length > 0) {
-            properties.push({
-              name: "cdx:github:job:needs",
-              value: jobNeeds.join(","),
-            });
-          }
-          if (hasWritePermissions) {
-            properties.push({
-              name: "cdx:github:workflow:hasWritePermissions",
-              value: "true",
-            });
-          }
-          if (hasIdTokenWrite) {
-            properties.push({
-              name: "cdx:github:workflow:hasIdTokenWrite",
-              value: "true",
-            });
-          }
-          if (workflowConcurrency?.group) {
-            properties.push({
-              name: "cdx:github:workflow:concurrencyGroup",
-              value: workflowConcurrency.group,
-            });
-          }
-          if (group?.startsWith("github/") || group === "actions") {
-            properties.push({ name: "cdx:actions:isOfficial", value: "true" });
-          }
-          if (group?.startsWith("github/")) {
-            properties.push({ name: "cdx:actions:isVerified", value: "true" });
-          }
-          if (workflowTriggers) {
-            const triggers =
-              typeof workflowTriggers === "string"
-                ? workflowTriggers
-                : Object.keys(workflowTriggers).join(",");
-            properties.push({
-              name: "cdx:github:workflow:triggers",
-              value: triggers,
-            });
-          }
-          pkgList.push({
-            group,
-            name,
-            version,
-            purl,
-            properties,
-            evidence: {
-              identity: {
-                field: "purl",
-                confidence,
-                methods: [
-                  {
-                    technique: "source-code-analysis",
-                    confidence,
-                    value: f,
-                  },
-                ],
-              },
-            },
-          });
-        }
-      }
-      if (step.run) {
-        const runLineNum = ghwData.indexOf(step.run);
-        const runLine =
-          runLineNum >= 0
-            ? ghwData.substring(0, runLineNum).split("\n").length
-            : -1;
-        const pkgCommands = extractPackageManagerCommands(step.run);
-        for (const pkgCmd of pkgCommands) {
-          const key = `run-${pkgCmd.name}-${pkgCmd.version || "latest"}`;
-          if (!keys_cache[key]) {
-            keys_cache[key] = key;
-            pkgList.push({
-              group: "",
-              name: pkgCmd.name,
-              version: pkgCmd.version || undefined,
-              scope: "excluded",
-              "bom-ref": uuidv4(),
-              description: key,
-              properties: [
-                { name: "SrcFile", value: f },
-                { name: "cdx:github:workflow:name", value: workflowName },
-                { name: "cdx:github:job:name", value: jobName },
-                { name: "cdx:github:step:type", value: "run" },
-                { name: "cdx:github:step:command", value: pkgCmd.command },
-                { name: "cdx:github:run:line", value: runLine.toString() },
-              ],
-              evidence: {
-                identity: {
-                  field: "purl",
-                  confidence: 0.5,
-                  methods: [
-                    {
-                      technique: "source-code-analysis",
-                      confidence: 0.5,
-                      value: f,
-                    },
-                  ],
-                },
-              },
-            });
-          }
-        }
-      }
-    }
-  }
-  return pkgList;
-}
-
-/**
- * Analyze permissions for write access.
- *
- * Refer to https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions
- */
-function analyzePermissions(permissions) {
-  if (!permissions || typeof permissions !== "object") {
-    return false;
-  }
-  const writePermissions = [
-    "actions",
-    "artifact-metadata",
-    "attestations",
-    "checks",
-    "contents",
-    "deployments",
-    "id-token",
-    "models",
-    "discussions",
-    "packages",
-    "pages",
-    "actions",
-    "deployments",
-    "issues",
-    "pull-requests",
-    "security-events",
-    "statuses",
-  ];
-  for (const perm of writePermissions) {
-    if (permissions[perm] === "write") {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Determine version pinning type for security assessment
- */
-function getVersionPinningType(versionRef) {
-  if (!versionRef) {
-    return "unknown";
-  }
-  if (/^[a-f0-9]{40}$/.test(versionRef)) {
-    return "sha";
-  }
-  if (/^[a-f0-9]{7,}$/.test(versionRef)) {
-    return "sha";
-  }
-  if (
-    versionRef === "main" ||
-    versionRef === "master" ||
-    versionRef.includes("/")
-  ) {
-    return "branch";
-  }
-  return "tag";
-}
-
-/**
- * Extract package manager commands from run steps
- */
-function extractPackageManagerCommands(runScript) {
-  const commands = [];
-  if (!runScript) {
-    return commands;
-  }
-  const patterns = [
-    { regex: /npm\s+(install|i|ci)\s+([^&\n|;]+)/g, name: "npm", type: "npm" },
-    {
-      regex: /yarn\s+(add|install)\s+([^&\n|;]+)/g,
-      name: "yarn",
-      type: "yarn",
-    },
-    { regex: /pip\s+(install)\s+([^&\n|;]+)/g, name: "pip", type: "pip" },
-    { regex: /pip3\s+(install)\s+([^&\n|;]+)/g, name: "pip3", type: "pip" },
-    { regex: /gem\s+(install)\s+([^&\n|;]+)/g, name: "gem", type: "gem" },
-    { regex: /go\s+(get|install)\s+([^&\n|;]+)/g, name: "go", type: "go" },
-    {
-      regex: /cargo\s+(install|add)\s+([^&\n|;]+)/g,
-      name: "cargo",
-      type: "cargo",
-    },
-  ];
-  for (const pattern of patterns) {
-    let match;
-    while ((match = pattern.regex.exec(runScript)) !== null) {
-      commands.push({
-        name: pattern.name,
-        command: match[0],
-        version: null,
-      });
-    }
-  }
-  return commands;
-}
-
-export function parseCloudBuildData(cbwData) {
-  const pkgList = [];
-  const keys_cache = {};
-  if (!cbwData) {
-    return pkgList;
-  }
-  const yamlObj = _load(cbwData);
-  if (!yamlObj) {
-    return pkgList;
-  }
-  if (yamlObj.steps) {
-    for (const step of yamlObj.steps) {
-      if (step.name) {
-        const tmpA = step.name.split(":");
-        if (tmpA.length === 2) {
-          let group = dirname(tmpA[0]);
-          const name = basename(tmpA[0]);
-          if (group === ".") {
-            group = "";
-          }
-          const version = tmpA[1];
-          const key = `${group}-${name}-${version}`;
-          if (!keys_cache[key] && name && version) {
-            keys_cache[key] = key;
-            pkgList.push({
-              group,
-              name,
-              version,
+          const version = tmpA[1];
+          const key = `${group}-${name}-${version}`;
+          if (!keys_cache[key] && name && version) {
+            keys_cache[key] = key;
+            pkgList.push({
+              group,
+              name,
+              version,
             });
           }
         }
@@ -10391,6 +10485,16 @@ function untilFirst(separator, inputStr) {
   ];
 }
 
+/**
+ * Map a Conan package reference string to a PackageURL string, name, and version.
+ *
+ * Parses a full Conan package reference of the form
+ * `name/version@user/channel#recipe_revision:package_id#package_revision`
+ * and returns the equivalent purl string together with the extracted name and version.
+ *
+ * @param {string} conanPkgRef Conan package reference string
+ * @returns {Array} Tuple of [purlString, name, version], or [null, null, null] on parse failure
+ */
 export function mapConanPkgRefToPurlStringAndNameAndVersion(conanPkgRef) {
   // A full Conan package reference may be composed of the following segments:
   // conanPkgRef = "name/version@user/channel#recipe_revision:package_id#package_revision"
@@ -10516,6 +10620,16 @@ export function mapConanPkgRefToPurlStringAndNameAndVersion(conanPkgRef) {
   return [purl, info.name, info.version];
 }
 
+/**
+ * Parse Conan lock file data (conan.lock) and return the package list, dependency map,
+ * and parent component dependencies.
+ *
+ * Supports both the legacy `graph_lock.nodes` format (Conan 1.x) and the newer
+ * `requires` format (Conan 2.x).
+ *
+ * @param {string} conanLockData Raw JSON string of the Conan lock file
+ * @returns {{ pkgList: Object[], dependencies: Object, parentComponentDependencies: string[] }}
+ */
 export function parseConanLockData(conanLockData) {
   const pkgList = [];
   const dependencies = {};
@@ -10526,10 +10640,7 @@ export function parseConanLockData(conanLockData) {
   }
 
   const lockFile = JSON.parse(conanLockData);
-  if (
-    (!lockFile || !lockFile.graph_lock || !lockFile.graph_lock.nodes) &&
-    !lockFile.requires
-  ) {
+  if (!lockFile?.graph_lock?.nodes && !lockFile.requires) {
     return { pkgList, dependencies, parentComponentDependencies };
   }
 
@@ -10602,6 +10713,12 @@ export function parseConanLockData(conanLockData) {
   return { pkgList, dependencies, parentComponentDependencies };
 }
 
+/**
+ * Parse a Conan conanfile.txt and extract required and optional packages.
+ *
+ * @param {string} conanData Raw text contents of a conanfile.txt
+ * @returns {Object[]} Array of package objects with purl, name, version, and scope
+ */
 export function parseConanData(conanData) {
   const pkgList = [];
   if (!conanData) {
@@ -10637,6 +10754,12 @@ export function parseConanData(conanData) {
   return pkgList;
 }
 
+/**
+ * Parse Leiningen project.clj data and extract dependency packages.
+ *
+ * @param {string} leinData Raw text contents of a Leiningen project.clj file
+ * @returns {Object[]} Array of package objects with group, name, and version
+ */
 export function parseLeiningenData(leinData) {
   const pkgList = [];
   if (!leinData) {
@@ -10671,6 +10794,14 @@ export function parseLeiningenData(leinData) {
   return pkgList;
 }
 
+/**
+ * Parse EDN (Extensible Data Notation) deps.edn data and extract dependency packages.
+ *
+ * Handles Clojure deps.edn files, extracting packages listed under the `:deps` key.
+ *
+ * @param {string} rawEdnData Raw EDN text contents of a deps.edn file
+ * @returns {Object[]} Array of package objects with group, name, and version
+ */
 export function parseEdnData(rawEdnData) {
   const pkgList = [];
   if (!rawEdnData) {
@@ -10750,7 +10881,7 @@ export function parseFlakeNix(flakeNixFile) {
   const pkgList = [];
   const dependencies = [];
 
-  if (!existsSync(flakeNixFile)) {
+  if (!safeExistsSync(flakeNixFile)) {
     return { pkgList, dependencies };
   }
 
@@ -10835,7 +10966,7 @@ export function parseFlakeLock(flakeLockFile) {
   const pkgList = [];
   const dependencies = [];
 
-  if (!existsSync(flakeLockFile)) {
+  if (!safeExistsSync(flakeLockFile)) {
     return { pkgList, dependencies };
   }
 
@@ -11117,6 +11248,13 @@ export function parseNuspecData(nupkgFile, nuspecData) {
   };
 }
 
+/**
+ * Parse a C# packages.config XML file and return a list of NuGet package components.
+ *
+ * @param {string} pkgData Raw XML string of a packages.config file
+ * @param {string} pkgFile Path to the packages.config file, used for evidence properties
+ * @returns {Object[]} Array of NuGet package objects with purl, name, and version
+ */
 export function parseCsPkgData(pkgData, pkgFile) {
   const pkgList = [];
   if (!pkgData) {
@@ -11649,6 +11787,17 @@ export function parseCsProjData(
   };
 }
 
+/**
+ * Parse a .NET project.assets.json file and return the package list and dependency tree.
+ *
+ * Extracts NuGet packages and their transitive dependency relationships from the
+ * `libraries` and `targets` sections of a project.assets.json file produced by
+ * the .NET restore process.
+ *
+ * @param {string} csProjData Raw JSON string of the project.assets.json file
+ * @param {string} assetsJsonFile Path to the project.assets.json file, used for evidence properties
+ * @returns {{ pkgList: Object[], dependenciesList: Object[] }}
+ */
 export function parseCsProjAssetsData(csProjData, assetsJsonFile) {
   // extract name, operator, version from .NET package representation
   // like "NLog >= 4.5.0"
@@ -11899,6 +12048,14 @@ export function parseCsProjAssetsData(csProjData, assetsJsonFile) {
   };
 }
 
+/**
+ * Parse a .NET packages.lock.json file and return the package list, dependency tree,
+ * and list of direct/root dependencies.
+ *
+ * @param {string} csLockData Raw JSON string of the packages.lock.json file
+ * @param {string} pkgLockFile Path to the packages.lock.json file, used for evidence properties
+ * @returns {{ pkgList: Object[], dependenciesList: Object[], rootList: Object[] }}
+ */
 export function parseCsPkgLockData(csLockData, pkgLockFile) {
   const pkgList = [];
   const dependenciesList = [];
@@ -11912,7 +12069,7 @@ export function parseCsPkgLockData(csLockData, pkgLockFile) {
     };
   }
   const assetData = JSON.parse(csLockData);
-  if (!assetData || !assetData.dependencies) {
+  if (!assetData?.dependencies) {
     return {
       pkgList,
       dependenciesList,
@@ -12017,6 +12174,14 @@ export function parseCsPkgLockData(csLockData, pkgLockFile) {
   };
 }
 
+/**
+ * Parse a Paket dependency manager lock file (paket.lock) and return the package list
+ * and dependency tree.
+ *
+ * @param {string} paketLockData Raw text contents of the paket.lock file
+ * @param {string} pkgLockFile Path to the paket.lock file, used for evidence properties
+ * @returns {{ pkgList: Object[], dependenciesList: Object[] }}
+ */
 export function parsePaketLockData(paketLockData, pkgLockFile) {
   const pkgList = [];
   const dependenciesList = [];
@@ -12191,6 +12356,16 @@ export function parseComposerLock(pkgLockFile, rootRequires) {
   const rootRequiresMap = {};
   if (rootRequires) {
     for (const rr of Object.keys(rootRequires)) {
+      // Skip platform requirements (php, hhvm, ext-*, lib-*) — they are never
+      // Composer package names and must not be used to identify root packages.
+      if (
+        rr === "php" ||
+        rr === "hhvm" ||
+        rr.startsWith("ext-") ||
+        rr.startsWith("lib-")
+      ) {
+        continue;
+      }
       rootRequiresMap[rr] = true;
     }
   }
@@ -12215,7 +12390,7 @@ export function parseComposerLock(pkgLockFile, rootRequires) {
         for (const i in packages[compScope]) {
           const pkg = packages[compScope][i];
           // Be extra cautious. Potential fix for #236
-          if (!pkg || !pkg.name || !pkg.version) {
+          if (!pkg?.name || !pkg.version) {
             continue;
           }
 
@@ -12313,7 +12488,7 @@ export function parseComposerLock(pkgLockFile, rootRequires) {
       for (const compScope in packages) {
         for (const i in packages[compScope]) {
           const pkg = packages[compScope][i];
-          if (!pkg || !pkg.name || !pkg.version) {
+          if (!pkg?.name || !pkg.version) {
             continue;
           }
           if (!pkg.require || !Object.keys(pkg.require).length) {
@@ -12342,6 +12517,15 @@ export function parseComposerLock(pkgLockFile, rootRequires) {
   };
 }
 
+/**
+ * Parse an sbt dependency tree output file and return the package list and dependency tree.
+ *
+ * Reads a file produced by the sbt `dependencyTree` command and extracts Maven artifact
+ * coordinates, building a hierarchical dependency graph. Evicted packages and ranges are ignored.
+ *
+ * @param {string} sbtTreeFile Path to the sbt dependency tree output file
+ * @returns {{ pkgList: Object[], dependenciesList: Object[] }}
+ */
 export function parseSbtTree(sbtTreeFile) {
   const pkgList = [];
   const dependenciesList = [];
@@ -12658,6 +12842,10 @@ export function convertOSQueryResults(
       if (publisher === "null") {
         publisher = "";
       }
+      // For vscode-extension purl type, the publisher is used as the namespace
+      if (queryObj.purlType === "vscode-extension" && publisher) {
+        group = publisher.toLowerCase();
+      }
       let scope;
       const compScope = res.priority;
       if (["required", "optional", "excluded"].includes(compScope)) {
@@ -12758,6 +12946,17 @@ export function convertOSQueryResults(
   return pkgList;
 }
 
+/**
+ * Create a PackageURL object from a repository URL string, package type, and version.
+ *
+ * Supports HTTPS URLs, SSH `git@` URLs, Bitbucket SSH URLs, and local paths.
+ * Extracts the namespace (host + path prefix) and repository name from the URL.
+ *
+ * @param {string} type PackageURL type (e.g. `"swift"`, `"generic"`)
+ * @param {string} repoUrl Repository URL string
+ * @param {string} version Package version
+ * @returns {PackageURL|undefined} PackageURL object, or undefined for unsupported URL formats
+ */
 export function purlFromUrlString(type, repoUrl, version) {
   let namespace = "";
   let name;
@@ -13050,6 +13249,20 @@ export async function collectMvnDependencies(
   return jarNSMapping;
 }
 
+/**
+ * Collect Gradle project dependencies by scanning the Gradle cache directory for JAR files
+ * and their associated POM files.
+ *
+ * Uses the `GRADLE_CACHE_DIR` or `GRADLE_USER_HOME` environment variables to locate the
+ * Gradle files-2.1 cache, then delegates to {@link collectJarNS} to extract namespace
+ * and purl information from those JARs.
+ *
+ * @param {string} _gradleCmd Gradle command (unused; reserved for future use)
+ * @param {string} _basePath Base project path (unused; reserved for future use)
+ * @param {boolean} _cleanup Whether to clean up temporary files (unused; reserved for future use)
+ * @param {boolean} _includeCacheDir Whether to include cache directory (unused; reserved for future use)
+ * @returns {Promise<Object>} JAR namespace mapping object returned by collectJarNS
+ */
 export async function collectGradleDependencies(
   _gradleCmd,
   _basePath,
@@ -13263,6 +13476,16 @@ export async function collectJarNS(jarPath, pomPathMap = {}) {
   return jarNSMapping;
 }
 
+/**
+ * Convert a JAR namespace mapping (produced by {@link collectJarNS}) into an array
+ * of CycloneDX package component objects.
+ *
+ * Each entry in the mapping is resolved to a component with name, group, version,
+ * purl, hashes, namespace properties, and source file evidence.
+ *
+ * @param {Object} jarNSMapping Map of purl string to `{ jarFile, pom, namespaces, hashes }`
+ * @returns {Promise<Object[]>} Array of component objects derived from the JAR mapping
+ */
 export async function convertJarNSToPackages(jarNSMapping) {
   const pkgList = [];
   for (const purl of Object.keys(jarNSMapping)) {
@@ -13366,6 +13589,12 @@ export function parsePomXml(pomXmlData) {
   return undefined;
 }
 
+/**
+ * Parse a JAR MANIFEST.MF file and return its key-value pairs as an object.
+ *
+ * @param {string} jarMetadata Raw text contents of a MANIFEST.MF file
+ * @returns {Object} Key-value pairs extracted from the manifest
+ */
 export function parseJarManifest(jarMetadata) {
   const metadata = {};
   if (!jarMetadata) {
@@ -13383,6 +13612,12 @@ export function parseJarManifest(jarMetadata) {
   return metadata;
 }
 
+/**
+ * Parse a Maven pom.properties file and return its key-value pairs as an object.
+ *
+ * @param {string} pomProperties Raw text contents of a pom.properties file
+ * @returns {Object} Key-value pairs extracted from the properties file
+ */
 export function parsePomProperties(pomProperties) {
   const properties = {};
   if (!pomProperties) {
@@ -13400,6 +13635,13 @@ export function parsePomProperties(pomProperties) {
   return properties;
 }
 
+/**
+ * Encode a string for safe inclusion in a PackageURL, percent-encoding special characters
+ * while preserving already-encoded `%40` sequences and keeping `:` and `/` unencoded.
+ *
+ * @param {string} s String to encode
+ * @returns {string} Encoded string suitable for use in a PackageURL component
+ */
 export function encodeForPurl(s) {
   return s && !s.includes("%40")
     ? encodeURIComponent(s).replace(/%3A/g, ":").replace(/%2F/g, "/")
@@ -14303,10 +14545,10 @@ export async function parsePodfileLock(podfileLock, projectPath) {
           },
         ];
         let podspec = join(projectLocation, `${podName}.podspec`);
-        if (!existsSync(podspec)) {
+        if (!safeExistsSync(podspec)) {
           podspec = `${podspec}.json`;
         }
-        if (existsSync(podspec)) {
+        if (safeExistsSync(podspec)) {
           dependency.metadata.properties.push({
             name: "cdx:pods:podspecLocation",
             value: podspec,
@@ -15051,6 +15293,19 @@ export function getAtomCommand() {
   return "atom";
 }
 
+/**
+ * Execute the atom tool against a source directory or file with the given arguments.
+ *
+ * Resolves the atom binary via `getAtomCommand`, sets up the required environment
+ * (including `JAVA_HOME` from `ATOM_JAVA_HOME` if set), and spawns the process.
+ * Logs diagnostic messages for common failure modes such as unsupported Java versions,
+ * missing `astgen`, and JVM crashes.
+ *
+ * @param {string} src Path to the source directory or file to analyse
+ * @param {string[]} args Arguments to pass to the atom command
+ * @param {Object} extra_env Additional environment variables to merge into the process environment
+ * @returns {boolean} `true` if atom executed successfully and the language is supported; `false` otherwise
+ */
 export function executeAtom(src, args, extra_env = {}) {
   const cwd =
     safeExistsSync(src) && lstatSync(src).isDirectory() ? src : dirname(src);
@@ -15266,36 +15521,6 @@ function flattenDeps(dependenciesMap, pkgList, reqOrSetupFile, t) {
     .sort();
 }
 
-function get_python_command_from_env(env) {
-  // Virtual environments needs special treatment to use the correct python executable
-  // Without this step, the default python is always used resulting in false positives
-  const python_exe_name = isWin ? "python.exe" : "python";
-  const python3_exe_name = isWin ? "python3.exe" : "python3";
-  let python_cmd_to_use = PYTHON_CMD;
-  if (env.VIRTUAL_ENV) {
-    const bin_dir = isWin ? "Scripts" : "bin";
-    if (safeExistsSync(join(env.VIRTUAL_ENV, bin_dir, python_exe_name))) {
-      python_cmd_to_use = join(env.VIRTUAL_ENV, bin_dir, python_exe_name);
-    } else if (
-      safeExistsSync(join(env.VIRTUAL_ENV, bin_dir, python3_exe_name))
-    ) {
-      python_cmd_to_use = join(env.VIRTUAL_ENV, bin_dir, python3_exe_name);
-    }
-  } else if (env.CONDA_PREFIX) {
-    const bin_dir = isWin ? "" : "bin";
-    if (safeExistsSync(join(env.CONDA_PREFIX, bin_dir, python_exe_name))) {
-      python_cmd_to_use = join(env.CONDA_PREFIX, bin_dir, python_exe_name);
-    } else if (
-      safeExistsSync(join(env.CONDA_PREFIX, bin_dir, python3_exe_name))
-    ) {
-      python_cmd_to_use = join(env.CONDA_PREFIX, bin_dir, python3_exe_name);
-    }
-  } else if (env.CONDA_PYTHON_EXE) {
-    python_cmd_to_use = env.CONDA_PYTHON_EXE;
-  }
-  return python_cmd_to_use;
-}
-
 /**
  * Create uv.lock file with uv sync command.
  *
@@ -15378,14 +15603,12 @@ export async function getPipFrozenTree(
     ...process.env,
   };
 
-  // FIX: Create a set of explicit dependencies from requirements.txt to identify root packages.
   const explicitDeps = new Set();
   if (reqOrSetupFile?.endsWith(".txt") && safeExistsSync(reqOrSetupFile)) {
     // We only need the package names, so we pass `false` to avoid fetching full metadata.
     const tempPkgList = await parseReqFile(reqOrSetupFile, null, false);
     for (const pkg of tempPkgList) {
       if (pkg.name) {
-        // Normalize the name (lowercase, hyphenated) for accurate lookups.
         explicitDeps.add(pkg.name.replace(/_/g, "-").toLowerCase());
       }
     }
@@ -15441,17 +15664,26 @@ export async function getPipFrozenTree(
       }
     }
   }
-  /**
-   * We now have a virtual environment so we can attempt to install the project and perform
-   * pip freeze to collect the packages that got installed.
-   * Note that we did not create a virtual environment for poetry because poetry will do this when we run the install.
-   * This step is accurate but not reproducible since the resulting list could differ based on various factors
-   * such as the version of python, pip, os, pypi.org availability (and weather?)
-   */
-  // Bug #388. Perform pip install in all virtualenv to make the experience consistent
+  const venvMeta = getVenvMetadata(env);
+  const python_cmd_for_tree = get_python_command_from_env(env);
+  // Check if pyproject.toml is actually a uv-configured workspace
+  let hasToolUv = false;
+  let hasToolPoetry = false;
+  if (
+    reqOrSetupFile?.endsWith("pyproject.toml") &&
+    safeExistsSync(reqOrSetupFile)
+  ) {
+    try {
+      const content = readFileSync(reqOrSetupFile, "utf-8");
+      hasToolUv = content.includes("[tool.uv]");
+      hasToolPoetry = content.includes('build-backend = "poetry.core');
+    } catch (_err) {
+      // Ignore read error
+    }
+  }
   if (reqOrSetupFile) {
     // We have a poetry.lock file
-    if (reqOrSetupFile.endsWith("poetry.lock")) {
+    if (reqOrSetupFile.endsWith("poetry.lock") || hasToolPoetry) {
       const poetryConfigArgs = [
         "-m",
         "poetry",
@@ -15538,20 +15770,78 @@ export async function getPipFrozenTree(
           )}${_delimiter}${process.env.PATH || ""}`;
         }
       }
+    } else if (reqOrSetupFile.endsWith("pdm.lock") || venvMeta.type === "pdm") {
+      thoughtLog("Performing pdm install");
+      result = safeSpawnSync("pdm", ["install"], {
+        cwd: basePath,
+        shell: isWin,
+        env,
+      });
+      if (result.status !== 0 || result.error) {
+        frozen = false;
+      }
+    } else if (
+      reqOrSetupFile.endsWith("pixi.lock") ||
+      venvMeta.type === "pixi"
+    ) {
+      thoughtLog("Performing pixi install");
+      result = safeSpawnSync("pixi", ["install"], {
+        cwd: basePath,
+        shell: isWin,
+        env,
+      });
+      if (result.status !== 0 || result.error) {
+        frozen = false;
+      }
+    } else if (
+      reqOrSetupFile.endsWith("uv.lock") ||
+      (venvMeta.type === "uv" && hasToolUv)
+    ) {
+      thoughtLog("Performing uv sync");
+      result = safeSpawnSync("uv", ["sync"], {
+        cwd: basePath,
+        shell: isWin,
+        env,
+      });
+      if (result.status !== 0 || result.error) {
+        frozen = false;
+      }
+    } else if (
+      venvMeta.type === "rye" ||
+      reqOrSetupFile.endsWith("requirements.lock")
+    ) {
+      thoughtLog("Performing rye sync");
+      result = safeSpawnSync("rye", ["sync"], {
+        cwd: basePath,
+        shell: isWin,
+        env,
+      });
+      if (result.status !== 0 || result.error) {
+        frozen = false;
+      }
     } else {
-      // We are about to do a pip install with the right python command from the virtual environment
-      // This step can fail if the correct OS packages and development libraries are not installed
-      const python_cmd_for_tree = get_python_command_from_env(env);
-      let pipInstallArgs = [
-        "-m",
-        "pip",
-        "install",
-        "--disable-pip-version-check",
-      ];
-      if (isSecureMode) {
-        pipInstallArgs.unshift("-S");
+      // General package installation (Handling pip, or uv pip)
+      let installCmd = python_cmd_for_tree;
+      let pipInstallArgs = [];
+      if (venvMeta.type === "uv") {
+        installCmd = "uv";
+        pipInstallArgs = ["pip", "install"];
+        if (isSecureMode) {
+          pipInstallArgs.push("--only-binary");
+          pipInstallArgs.push(":all:");
+        }
+      } else {
+        pipInstallArgs = [
+          "-m",
+          "pip",
+          "install",
+          "--disable-pip-version-check",
+        ];
+        if (isSecureMode) {
+          pipInstallArgs.push("--only-binary=:all:");
+          pipInstallArgs.unshift("-S");
+        }
       }
-      // Requirements.txt could be called with any name so best to check for not setup.py and not pyproject.toml
       if (
         !reqOrSetupFile.endsWith("setup.py") &&
         !reqOrSetupFile.endsWith("pyproject.toml")
@@ -15566,20 +15856,17 @@ export async function getPipFrozenTree(
       } else {
         pipInstallArgs.push(resolve(basePath));
       }
-      // Support for passing additional arguments to pip
-      // Eg: --python-version 3.10 --ignore-requires-python --no-warn-conflicts --only-binary=:all:
       if (process?.env?.PIP_INSTALL_ARGS) {
         const addArgs = process.env.PIP_INSTALL_ARGS.split(" ");
         pipInstallArgs = pipInstallArgs.concat(addArgs);
       }
       thoughtLog(
-        `**PIP**: Trying pip install using the arguments ${pipInstallArgs.join(" ")}`,
+        `**INSTALL**: Trying package install using the arguments: ${installCmd} ${pipInstallArgs.join(" ")}`,
       );
       if (DEBUG_MODE) {
-        console.log("Executing", python_cmd_for_tree);
+        console.log("Executing", installCmd);
       }
-      // Attempt to perform pip install
-      result = safeSpawnSync(python_cmd_for_tree, pipInstallArgs, {
+      result = safeSpawnSync(installCmd, pipInstallArgs, {
         cwd: basePath,
         shell: isWin,
         env,
@@ -15604,6 +15891,10 @@ export async function getPipFrozenTree(
             );
           }
           console.log(result.stderr);
+        } else if (result?.stderr?.includes("No module named pip")) {
+          console.log(
+            "Using uv? Ensure 'uv' is in your PATH to allow cdxgen to use `uv pip install` automatically.",
+          );
         } else if (
           process.env.PIP_INSTALL_ARGS &&
           result.stderr?.includes("Cannot set --home and --prefix together")
@@ -15734,18 +16025,42 @@ export async function getPipFrozenTree(
   }
   // Bug #375. Attempt pip freeze on existing and new virtual environments
   if (env.VIRTUAL_ENV?.length || env.CONDA_PREFIX?.length) {
-    /**
-     * At this point, the previous attempt to do a pip install might have failed and we might have an unclean virtual environment with an incomplete list
-     * The position taken by cdxgen is "Some SBOM is better than no SBOM", so we proceed to collecting the dependencies that got installed with pip freeze
-     */
-    if (DEBUG_MODE) {
-      if (reqOrSetupFile) {
-        console.log(
-          `About to construct the pip dependency tree based on ${reqOrSetupFile}. Please wait ...`,
-        );
+    const venvRoot = env.VIRTUAL_ENV || env.CONDA_PREFIX;
+    const binDir = platform() === "win32" ? "Scripts" : "bin";
+    const pipExe = join(
+      venvRoot,
+      binDir,
+      platform() === "win32" ? "pip.exe" : "pip",
+    );
+    if (!safeExistsSync(pipExe)) {
+      thoughtLog(
+        "The 'pip' module is missing in this environment. Bootstrapping it to support piptree extraction.",
+      );
+      if (venvMeta.type === "uv") {
+        safeSpawnSync("uv", ["pip", "install", "pip"], {
+          cwd: basePath,
+          shell: isWin,
+          env,
+        });
+      } else if (venvMeta.type === "rye") {
+        safeSpawnSync("rye", ["run", "pip", "install", "pip"], {
+          cwd: basePath,
+          shell: isWin,
+          env,
+        });
+      } else {
+        safeSpawnSync(python_cmd_for_tree, ["-m", "ensurepip", "--upgrade"], {
+          cwd: basePath,
+          shell: isWin,
+          env,
+        });
       }
     }
-    const python_cmd_for_tree = get_python_command_from_env(env);
+    if (DEBUG_MODE && reqOrSetupFile) {
+      console.log(
+        `About to construct the dependency tree based on ${reqOrSetupFile}. Please wait ...`,
+      );
+    }
     // This is a slow step that ideally needs to be invoked only once per venv
     const tree = getTreeWithPlugin(env, python_cmd_for_tree, basePath);
     if (DEBUG_MODE && !tree.length) {
@@ -15896,10 +16211,23 @@ export function getPipTreeForPackages(
       env.PYTHONPATH = undefined;
     }
   }
+  const venvMeta = getVenvMetadata(env);
   const python_cmd_for_tree = get_python_command_from_env(env);
-  let pipInstallArgs = ["-m", "pip", "install", "--disable-pip-version-check"];
-  if (isSecureMode) {
-    pipInstallArgs.unshift("-S");
+  let installCmd = python_cmd_for_tree;
+  let pipInstallArgs = [];
+  if (venvMeta.type === "uv") {
+    installCmd = "uv";
+    pipInstallArgs = ["pip", "install"];
+    if (isSecureMode) {
+      pipInstallArgs.push("--only-binary");
+      pipInstallArgs.push(":all:");
+    }
+  } else {
+    pipInstallArgs = ["-m", "pip", "install", "--disable-pip-version-check"];
+    if (isSecureMode) {
+      pipInstallArgs.push("--only-binary=:all:");
+      pipInstallArgs.unshift("-S");
+    }
   }
   // Support for passing additional arguments to pip
   // Eg: --python-version 3.10 --ignore-requires-python --no-warn-conflicts
@@ -15907,19 +16235,23 @@ export function getPipTreeForPackages(
     const addArgs = process.env.PIP_INSTALL_ARGS.split(" ");
     pipInstallArgs = pipInstallArgs.concat(addArgs);
   } else {
-    pipInstallArgs = pipInstallArgs.concat([
-      "--ignore-requires-python",
-      "--no-compile",
-      "--no-warn-script-location",
-      "--no-warn-conflicts",
-    ]);
+    if (venvMeta.type !== "uv") {
+      pipInstallArgs = pipInstallArgs.concat([
+        "--ignore-requires-python",
+        "--no-compile",
+        "--no-warn-script-location",
+        "--no-warn-conflicts",
+      ]);
+    } else {
+      pipInstallArgs.push("--no-compile");
+    }
   }
   if (DEBUG_MODE) {
     console.log(
       "Installing",
       pkgList.length,
       "packages using the command",
-      python_cmd_for_tree,
+      installCmd,
       pipInstallArgs.join(" "),
     );
   }
@@ -15949,7 +16281,7 @@ export function getPipTreeForPackages(
     }
     // Attempt to perform pip install for pkgSpecifier
     const result = safeSpawnSync(
-      python_cmd_for_tree,
+      installCmd,
       [...pipInstallArgs, pkgSpecifier],
       {
         cwd: basePath,
@@ -15966,6 +16298,30 @@ export function getPipTreeForPackages(
   }
   // Did any package get installed successfully?
   if (failedPkgList.length < pkgList.length) {
+    const venvRoot = env.VIRTUAL_ENV || env.CONDA_PREFIX;
+    if (venvRoot) {
+      const binDir = platform() === "win32" ? "Scripts" : "bin";
+      const pipExe = join(
+        venvRoot,
+        binDir,
+        platform() === "win32" ? "pip.exe" : "pip",
+      );
+      if (!safeExistsSync(pipExe)) {
+        if (venvMeta.type === "uv") {
+          safeSpawnSync("uv", ["pip", "install", "pip"], {
+            cwd: basePath,
+            shell: isWin,
+            env,
+          });
+        } else {
+          safeSpawnSync(python_cmd_for_tree, ["-m", "ensurepip", "--upgrade"], {
+            cwd: basePath,
+            shell: isWin,
+            env,
+          });
+        }
+      }
+    }
     const dependenciesMap = {};
     const tree = getTreeWithPlugin(env, python_cmd_for_tree, basePath);
     for (const t of tree) {
@@ -16033,6 +16389,13 @@ export function getPipTreeForPackages(
 }
 
 // taken from a very old package https://github.com/keithamus/parse-packagejson-name/blob/master/index.js
+/**
+ * Parse a package.json `name` field (or a plain string) and extract its scope,
+ * full name, project name, and module name components.
+ *
+ * @param {string|Object} name The package name string or an object with a `name` property
+ * @returns {{ scope: string|null, fullName: string, projectName: string|null, moduleName: string|null }}
+ */
 export function parsePackageJsonName(name) {
   const nameRegExp = /^(?:@([^/]+)\/)?(([^.]+)(?:\.(.*))?)$/;
   const returnObject = {
@@ -16169,7 +16532,12 @@ export async function addEvidenceForImports(
         }
         break;
       }
-      if (impPkgs?.length > 0 && !isImported && DEBUG_MODE) {
+      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`,
         );
@@ -16206,6 +16574,16 @@ export async function addEvidenceForImports(
   return pkgList;
 }
 
+/**
+ * Comparator function for sorting CycloneDX component objects.
+ *
+ * Compares components by `bom-ref`, then `purl`, then `name`, using locale-aware
+ * string comparison on the first available key.
+ *
+ * @param {Object|string} a First component to compare
+ * @param {Object|string} b Second component to compare
+ * @returns {number} Negative, zero, or positive integer as required by Array.sort
+ */
 export function componentSorter(a, b) {
   if (a && b) {
     for (const k of ["bom-ref", "purl", "name"]) {
@@ -16217,6 +16595,19 @@ export function componentSorter(a, b) {
   return a.localeCompare(b);
 }
 
+/**
+ * Parse a CMake-generated dot/graphviz file and extract components and their dependency
+ * relationships.
+ *
+ * The first `digraph` entry becomes the parent component. Subsequent `node` entries
+ * with a `label` attribute are treated as direct dependencies, while commented
+ * `node -> node` relationships are used to construct the dependency graph.
+ *
+ * @param {string} dotFile Path to the CMake-generated dot file
+ * @param {string} pkgType PackageURL type to assign to extracted packages (e.g. `"generic"`)
+ * @param {Object} options CLI options; may contain `projectGroup`, `projectName`, and `projectVersion`
+ * @returns {{ parentComponent: Object, pkgList: Object[], dependenciesList: Object[] }}
+ */
 export function parseCmakeDotFile(dotFile, pkgType, options = {}) {
   const dotGraphData = readFileSync(dotFile, { encoding: "utf-8" });
   const pkgList = [];
@@ -16326,6 +16717,19 @@ export function parseCmakeDotFile(dotFile, pkgType, options = {}) {
   };
 }
 
+/**
+ * Parse a CMake-like build file (CMakeLists.txt, meson.build, etc.) and extract the
+ * parent component and list of dependency packages.
+ *
+ * Handles `set`, `project`, `find_package`, `find_library`, `find_dependency`,
+ * `find_file`, `FetchContent_MakeAvailable`, and `dependency()` directives.
+ * Uses the MesonWrapDB to improve name resolution confidence.
+ *
+ * @param {string} cmakeListFile Path to the CMake-like build file
+ * @param {string} pkgType PackageURL type to assign to extracted packages (e.g. `"generic"`)
+ * @param {Object} options CLI options; may contain `projectGroup`, `projectName`, and `projectVersion`
+ * @returns {{ parentComponent: Object, pkgList: Object[] }}
+ */
 export function parseCmakeLikeFile(cmakeListFile, pkgType, options = {}) {
   let cmakeListData = readFileSync(cmakeListFile, { encoding: "utf-8" });
   const pkgList = [];
@@ -16579,6 +16983,14 @@ export function parseCmakeLikeFile(cmakeListFile, pkgType, options = {}) {
   };
 }
 
+/**
+ * Find the OS package component that provides a given file, by searching the
+ * `PkgProvides` property of each package in the OS package list.
+ *
+ * @param {string} afile Filename or path to look up (matched case-insensitively)
+ * @param {Object[]} osPkgsList Array of OS package component objects to search
+ * @returns {Object|undefined} The matching OS package component, or undefined if not found
+ */
 export function getOSPackageForFile(afile, osPkgsList) {
   for (const ospkg of osPkgsList) {
     for (const props of ospkg.properties || []) {
@@ -16760,7 +17172,7 @@ export function getCppModules(src, options, osPkgsList, epkgList) {
     // Normalize windows separator
     afile = afile.replace("..\\", "").replace(/\\/g, "/");
     const fileName = basename(afile);
-    if (!fileName || !fileName.length) {
+    if (!fileName?.length) {
       continue;
     }
     const extn = extname(fileName);
@@ -16997,7 +17409,7 @@ async function queryNuget(p, NUGET_URL) {
     { responseType: "json" },
   );
   const items = res.body.items;
-  if (!items || !items[0]) {
+  if (!items?.[0]) {
     return [np, newBody, body];
   }
   if (items[0] && !items[0].items) {
@@ -17192,6 +17604,18 @@ export async function getNugetMetadata(pkgList, dependencies = undefined) {
   };
 }
 
+/**
+ * Enrich .NET package components with occurrence evidence and imported module/method
+ * information from a dosai dependency slices file.
+ *
+ * Builds a mapping of DLL filenames to purls using the `PackageFiles` property of each
+ * package, then reads the slices file to add occurrence locations, imported modules,
+ * called methods, and assembly version information where available.
+ *
+ * @param {Object[]} pkgList Array of .NET package component objects to enrich
+ * @param {string} slicesFile Path to the dosai dependency slices JSON file
+ * @returns {Object[]} The enriched package list (same array, mutated in place)
+ */
 export function addEvidenceForDotnet(pkgList, slicesFile) {
   // We need two datastructures.
   // dll to purl mapping from the pkgList
@@ -17626,7 +18050,7 @@ export function collectSharedLibs(
 }
 
 function collectAllLdConfs(basePath, ldConf, allLdConfDirs, libPaths) {
-  if (ldConf && existsSync(join(basePath, ldConf))) {
+  if (ldConf && safeExistsSync(join(basePath, ldConf))) {
     const ldConfData = readFileSync(join(basePath, ldConf), "utf-8");
     for (let line of ldConfData.split("\n")) {
       line = line.replace("\r", "").trim();
@@ -17812,6 +18236,14 @@ export function retrieveCdxgenVersion() {
   return `\x1b[1mCycloneDX Generator ${packageJson.version}\x1b[0m\nRuntime: ${runtimeInfo.runtime}, Version: ${runtimeInfo.version}`;
 }
 
+/**
+ * Retrieve the version of the cdxgen plugins binary package from package.json.
+ *
+ * Reads the local package.json and searches the `optionalDependencies` for a package
+ * whose name starts with `@cdxgen/cdxgen-plugins-bin`, returning its declared version.
+ *
+ * @returns {string|undefined} Version string of the plugins binary package, or undefined if not found
+ */
 export function retrieveCdxgenPluginVersion() {
   const packageJsonAsString = readFileSync(
     join(dirNameStr, "package.json"),
@@ -17876,3 +18308,13 @@ export function splitCommandArgs(commandString) {
   }
   return args;
 }
+
+/**
+ * Convert hyphenated strings to camel case.
+ *
+ * @param {String} str String to convert
+ * @returns {String} camelCased string
+ */
+export function toCamel(str) {
+  return str.replace(/-([a-z])/g, (_, g) => g.toUpperCase());
+}