@cyclonedx/cdxgen 12.1.5 → 12.2.0

package/lib/helpers/utils.js

@@ -48,13 +48,13 @@ 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";
@@ -79,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
@@ -124,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")) ||
@@ -147,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 = {};
   }
@@ -303,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 &&
@@ -310,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)
@@ -336,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) {
@@ -352,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) {
@@ -486,7 +577,6 @@ export const PROJECT_TYPE_ALIASES = {
     "typescript",
     "ts",
     "tsx",
-    "vsix",
     "yarn",
     "rush",
   ],
@@ -581,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
@@ -1158,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) {
@@ -1242,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 {
@@ -1306,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
@@ -1450,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) {
@@ -1731,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$/, "");
           }
         }
       }
@@ -2774,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"));
@@ -2872,42 +3093,28 @@ export async function pnpmMetadata(pkgList, 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) {
@@ -2926,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++;
         }
       }
@@ -2949,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;
 }
 
@@ -3018,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);
@@ -3320,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 ||
@@ -3538,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) {
@@ -3554,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,
             });
           });
@@ -3652,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);
@@ -4685,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"]) {
@@ -7302,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()) {
@@ -7485,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" });
@@ -7888,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) {
@@ -7937,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) {
@@ -9263,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(
@@ -9322,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) {
@@ -9424,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;
@@ -9450,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;
@@ -9515,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;
@@ -9600,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();
@@ -9667,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 = [];
 
@@ -9728,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 = [];
@@ -9795,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) {
@@ -9821,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 = [];
@@ -9902,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) {
@@ -9954,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) {
@@ -9982,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) {
@@ -10009,376 +10388,27 @@ export function parseMixLockData(mixData) {
   return pkgList;
 }
 
-export function parseGitHubWorkflowData(f) {
-  const pkgList = [];
-  if (!f) {
-    return pkgList;
-  }
-  const ghwData = readFileSync(f, { encoding: "utf-8" });
-  const keys_cache = {};
-  if (!ghwData) {
-    return pkgList;
-  }
-  const yamlObj = _load(ghwData);
-  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 (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.
+ * 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).
  *
- * 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
+ * @param {string} f Path to the GitHub Actions workflow YAML file
+ * @returns {Object[]} List of action component objects with purl, properties, and evidence
  */
-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";
+export function parseGitHubWorkflowData(f) {
+  const { components } = parseWorkflowFile(f);
+  return components.filter((c) => c.scope === "required");
 }
 
 /**
- * Extract package manager commands from run steps
+ * 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
  */
-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 = {};
@@ -10455,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"
@@ -10580,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 = {};
@@ -10663,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) {
@@ -10698,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) {
@@ -10732,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) {
@@ -10811,7 +10881,7 @@ export function parseFlakeNix(flakeNixFile) {
   const pkgList = [];
   const dependencies = [];
 
-  if (!existsSync(flakeNixFile)) {
+  if (!safeExistsSync(flakeNixFile)) {
     return { pkgList, dependencies };
   }
 
@@ -10896,7 +10966,7 @@ export function parseFlakeLock(flakeLockFile) {
   const pkgList = [];
   const dependencies = [];
 
-  if (!existsSync(flakeLockFile)) {
+  if (!safeExistsSync(flakeLockFile)) {
     return { pkgList, dependencies };
   }
 
@@ -11178,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) {
@@ -11710,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"
@@ -11960,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 = [];
@@ -12078,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 = [];
@@ -12252,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;
     }
   }
@@ -12403,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 = [];
@@ -12719,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)) {
@@ -12819,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;
@@ -13111,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,
@@ -13324,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)) {
@@ -13427,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) {
@@ -13444,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) {
@@ -13461,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, "/")
@@ -14364,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,
@@ -15112,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);
@@ -16195,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 = {
@@ -16373,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"]) {
@@ -16384,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 = [];
@@ -16493,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 = [];
@@ -16746,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 || []) {
@@ -17359,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
@@ -17793,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();
@@ -17979,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"),
@@ -18043,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());
+}