@cdxgen/cdxgen 13.5.0 → 13.7.0

package/lib/cli/index.js

@@ -50,9 +50,14 @@ import {
   buildDependencyTrackBomRequest,
   getDependencyTrackBomApiUrl,
 } from "../helpers/remote/dependency-track.js";
+import { collectObomIdeInventory } from "../helpers/vsixutils.js";
 import { optionIncludesAiInventoryProjectType } from "../inventory/aiInventory.js";
 import { readApkInstalledDb } from "../inventory/apkInstalledDb.js";
-import { isCycloneDxComponentTypeEnabled } from "../inventory/bomUtils.js";
+import {
+  isCycloneDx20SpecVersion,
+  isCycloneDxComponentTypeEnabled,
+} from "../inventory/bomUtils.js";
+import { DEPENDENCY_TRACK_CDX20_ERROR } from "../inventory/cyclonedx20.js";
 import {
   mergeDependencies,
   mergeServices,
@@ -70,16 +75,28 @@ import {
   hasHbomProjectType,
 } from "../inventory/hbom.js";
 import { mergeHostInventoryBoms } from "../inventory/hostTopology.js";
+import { probeHostNode } from "../inventory/nodeHostProbe.js";
+import { markOsInstalledLanguagePackages } from "../inventory/osPackageResolver.js";
 import { orderParentCandidates } from "../inventory/parentSelection.js";
 import { probeHostPhp } from "../inventory/phpHostProbe.js";
 // Imported directly rather than through the utils.js barrel: purl validity is
 // checked in a hot path and the barrel is already the root of several import
 // cycles.
 import { applyPurl, ociPurl } from "../inventory/purl.js";
+import {
+  deriveOsPackagedRubyRuntimes,
+  linkDefaultGemsToRuntimes,
+} from "../inventory/rubyBuildInfo.js";
+import { probeHostRuby } from "../inventory/rubyHostProbe.js";
 import { table } from "../inventory/table.js";
 
 export { summarizeAiInventory } from "../inventory/aiInventory.js";
 
+import { probeHostRubyGems } from "../ecosystems/gemHostProbe.js";
+import {
+  mergeHostPythonEnvironmentPackages,
+  probeHostPythonEnvironments,
+} from "../ecosystems/venvProbe.js";
 import {
   enrichOSComponentsWithTrustData,
   executeOsQuery,
@@ -240,6 +257,28 @@ switch (_platform()) {
     break;
 }
 
+/**
+ * Home directories whose editor extension folders an OBOM reads: every user's
+ * home from osquery when cdxgen runs as root, and otherwise the current
+ * user's, which is the only one it can read.
+ *
+ * @returns {string[]} Home directories
+ */
+function obomUserHomes() {
+  const ownHome = homedir();
+  if (typeof process.getuid !== "function" || process.getuid() !== 0) {
+    return [ownHome];
+  }
+  const homes = new Set([ownHome]);
+  for (const row of executeOsQuery("SELECT directory FROM users;") || []) {
+    const dir = row?.directory;
+    if (typeof dir === "string" && dir.startsWith("/") && safeExistsSync(dir)) {
+      homes.add(dir);
+    }
+  }
+  return [...homes];
+}
+
 /**
  * Function to create obom string for the current OS using osquery
  *
@@ -247,7 +286,7 @@ switch (_platform()) {
  * @param {Object} options Parse options from the cli
  * @returns {Promise<Object>} Promise resolving to BOM object
  */
-export function createOSBom(_path, options) {
+export async function createOSBom(_path, options) {
   console.warn(
     "About to generate OBOM for the current OS installation. This will take several minutes ...",
   );
@@ -309,6 +348,53 @@ export function createOSBom(_path, options) {
   if (hostPhp.components.length) {
     pkgList = pkgList.concat(hostPhp.components);
   }
+  // Nor a Node.js from a release tarball or a version manager, or the Brotli
+  // decoder compiled into it.
+  const hostNode = probeHostNode({
+    executeOsQuery,
+    packageComponents: pkgList,
+  });
+  if (hostNode.components.length) {
+    pkgList = pkgList.concat(hostNode.components);
+  }
+  // Nor a Ruby from ruby-build, a version manager or a toolcache tarball.
+  const hostRuby = probeHostRuby({
+    executeOsQuery,
+    packageComponents: pkgList,
+  });
+  if (hostRuby.components.length) {
+    pkgList = pkgList.concat(hostRuby.components);
+  }
+  // A Ruby a package manager installed is also named by its upstream version.
+  pkgList = pkgList.concat(deriveOsPackagedRubyRuntimes(pkgList));
+  // osquery has no table for RubyGems; the gems of the host's gem homes are
+  // read from their specifications.
+  const hostGems = await probeHostRubyGems({
+    executeOsQuery,
+    packageComponents: pkgList,
+  });
+  if (hostGems.length) {
+    const knownRefs = new Set(pkgList.map((component) => component["bom-ref"]));
+    pkgList = pkgList.concat(
+      hostGems.filter((gem) => !knownRefs.has(gem["bom-ref"])),
+    );
+  }
+  // osquery reads the interpreter's own site-packages; packages installed into
+  // a virtual environment or a pyenv interpreter are read from their METADATA.
+  pkgList = mergeHostPythonEnvironmentPackages(
+    pkgList,
+    probeHostPythonEnvironments(),
+  );
+  // osquery reads the extension registry of a fixed list of editors; the
+  // editors themselves, and the extensions of the others, come from the
+  // extension folders. A root scan reads every user's home, as osquery does.
+  try {
+    pkgList = pkgList.concat(
+      collectObomIdeInventory(pkgList, { homes: obomUserHomes() }),
+    );
+  } catch (err) {
+    thoughtLog(`Unable to read the editor extension folders: ${err.message}`);
+  }
   const hostTrustInventory = enrichOSComponentsWithTrustData(pkgList);
   if (hostTrustInventory?.components?.length) {
     pkgList = hostTrustInventory.components;
@@ -770,13 +856,52 @@ export function summarizePurlTypes(components) {
  *   data object (components, dependencies, bomJson, parentComponent, etc.)
  */
 export async function createMultiXBom(pathList, options) {
+  /**
+   * What createMultiXBom reads from the result of a create*Bom builder.
+   *
+   * @typedef {Object} BuilderBomData
+   * @property {{components?: Object[], dependencies?: Object[], services?: Object[]}} [bomJson] The generated BOM
+   * @property {Object} [parentComponent] The project the builder detected
+   * @property {Object[]} [dependencies] Dependencies returned beside bomJson (crypto scan)
+   * @property {Object[]} [formulationList] Formulation components for postProcess
+   * @property {Object[]} [metadataProperties] Properties for metadata (php platform data)
+   */
+
+  /**
+   * One ecosystem that createMultiXBom scans every path for.
+   *
+   * @typedef {Object} PathScanStep
+   * @property {(path: string, options: Object) => boolean} applies Whether the step runs for this path
+   * @property {(path: string, options: Object) => any} [prepare] Computes a value once for the hooks below
+   * @property {(path: string, options: Object, context: any) => void} [announce] Thought logs written before the scan
+   * @property {string|((context: any) => string)} activityType Project type recorded in the activity context
+   * @property {(path: string) => void} [beforeBuild] Runs after the activity context is set
+   * @property {(path: string, options: Object) => any} build The create*Bom builder, whose result is read as BuilderBomData
+   * @property {(bomData: BuilderBomData | undefined) => boolean} [isUseful] Whether the result is merged; by default, when it has components
+   * @property {(count: number, path: string, context: any) => string} [foundThought] Thought log for the components found
+   * @property {(count: number, path: string, context: any) => string} debugMessage Debug log for the components found
+   * @property {"concat"|"topLevel"|"mergeWithParent"} [dependencyMerge] How dependencies are merged; mergeDependencies by default
+   * @property {boolean} [mergeServices] Merge bomJson.services into options.services
+   * @property {boolean} [keepParent] Record the detected project as a sub-component; true by default
+   * @property {"plain"|"gradle"} [hoistSubComponents] Hoist the project's own sub-components
+   * @property {boolean} [collectMetadataProperties] Collect metadataProperties whether or not components were found
+   * @property {boolean} [collectFormulation] Collect the formulation list whether or not components were found
+   */
+
+  /** @type {Object[]} */
   let components = [];
+  /** @type {Object[]} */
   let dependencies = [];
+  /** @type {BuilderBomData | undefined} */
   let bomData;
+  /** @type {Object[]} */
   let formulationList = [];
+  /** @type {Object[]} */
   let metadataProperties = [];
   let parentComponent = determineParentComponent(options) || {};
+  /** @type {Object[]} */
   let parentSubComponents = [];
+  let osFileOwners;
   const setProjectTypeActivityContext = (projectType, sourcePath) => {
     setActivityContext({
       projectType,
@@ -797,6 +922,8 @@ export async function createMultiXBom(pathList, options) {
     const {
       osPackages,
       osPackageFiles,
+      nativeExtensionFiles,
+      ownerByPath,
       dependenciesList,
       allTypes,
       bundledSdks,
@@ -811,6 +938,7 @@ export async function createMultiXBom(pathList, options) {
       options.exportData?.inspectData?.Config,
       options,
     );
+    osFileOwners = ownerByPath;
     osPhase.succeed(
       summarizeCounts([
         [osPackages.length, "OS package", "OS packages"],
@@ -859,6 +987,7 @@ export async function createMultiXBom(pathList, options) {
     components = components.concat(osPackageFiles || []);
     components = components.concat(executables);
     components = components.concat(sharedLibs);
+    components = components.concat(nativeExtensionFiles || []);
     if (dependenciesList?.length) {
       dependencies = mergeDependencies(dependencies, dependenciesList);
     }
@@ -871,945 +1000,602 @@ export async function createMultiXBom(pathList, options) {
         osPackages.concat(osPackageFiles || []).map((p) => p["bom-ref"]),
       );
       dependencies.splice(0, 0, {
-        ref: parentComponent["bom-ref"],
-        dependsOn: Array.from(parentDependsOn).sort(),
-      });
-    }
-  }
-  if (hasAnyProjectType(["os"], options, false) && options.bomData) {
-    bomData = options.bomData;
-    if (bomData?.bomJson?.components) {
-      if (DEBUG_MODE) {
-        console.log(`Found ${bomData.bomJson.components.length} OS components`);
-      }
-      if (bomData.bomJson.components.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} OS packages 😎.`,
-        );
-      }
-      components = components.concat(bomData.bomJson.components);
-    }
-  }
-  const sharedOptions = options;
-  // The exploded image layers are written once by the extractor and only read
-  // from here on, so repeated walks of them can share one view of the tree.
-  setDirWalkCacheRoot(options.allLayersExplodedDir);
-  const scanOnePath = async (path) => {
-    try {
-      return await scanOnePathInner(path);
-    } catch (err) {
-      if (!isDeferredFailOnError(err)) {
-        throw err;
-      }
-      // The failing path contributes nothing, and the remaining paths still
-      // do: fail-on-error scopes the loss to the leg that failed.
-      return {
-        components: [],
-        dependencies: [],
-        options: { ...sharedOptions },
-        parentSubComponents: [],
-        metadataProperties: [],
-      };
-    }
-  };
-  const scanOnePathInner = async (path) => {
-    // Each path accumulates into its own lists and its own view of options, so
-    // that legs which record a parent component or a tool cannot overwrite
-    // another path's. The lists are merged below in pathList order.
-    const options = { ...sharedOptions };
-    let bomData;
-    let components = [];
-    let dependencies = [];
-    let parentSubComponents = [];
-    let metadataProperties = [];
-    // Each builder detects the project of its own ecosystem. A builder that sets
-    // options.parentComponent to force its project into its own BOM must not
-    // make that project the next builder's too, or the next ecosystem's project
-    // is lost: every builder starts from the parent the caller gave.
-    const callerParent = options.parentComponent;
-    const withOwnParent = async (build) => {
-      options.parentComponent = callerParent;
-      try {
-        return await build();
-      } finally {
-        options.parentComponent = callerParent;
-      }
-    };
-    setActivityContext({
-      projectType: Array.isArray(options.projectType)
-        ? options.projectType.join(",")
-        : options.projectType,
-      sourcePath: path,
-    });
-    recordActivity({
-      kind: "read",
-      reason:
-        "Scanning project path for supported languages and package managers.",
-      status: "completed",
-      target: path,
-    });
-    if (DEBUG_MODE) {
-      console.log("Scanning", path);
-    }
-    if (pathList.length > 2) {
-      thoughtLog(`Let's thoroughly check the path ${path}.`);
-    }
-    // Node.js and AI inventory
-    if (
-      hasAnyProjectType(["oci", "js"], options) ||
-      hasAnyProjectType(["mcp", "ai-skill", "ai"], options) ||
-      getDirectAiInventoryType(path, options)
-    ) {
-      const exactAiInventoryType = getDirectAiInventoryType(path, options);
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        if (exactAiInventoryType === "mcp") {
-          thoughtLog(
-            "**MCP**: Looking for MCP services, MCP configs, and related AI control-plane artifacts.",
-          );
-        } else if (exactAiInventoryType === "ai") {
-          thoughtLog(
-            "**AI-BOM**: Looking for AI models, direct model metadata, pedigree, quantization, and operator-facing AI context.",
-          );
-        } else if (exactAiInventoryType === "ai-skill") {
-          thoughtLog(
-            "**AI-SKILL**: Looking for AI instruction, skill, and agent-definition files that can influence build or release flows.",
-          );
-        } else {
-          thoughtLog(
-            "**JS**: Now looking for JavaScript projects (npm, yarn, pnpm) and files.",
-          );
-        }
-      }
-      setProjectTypeActivityContext(exactAiInventoryType || "js", path);
-      bomData = await withOwnParent(() => createNodejsBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        if (exactAiInventoryType) {
-          thoughtLog(
-            `I found ${bomData.bomJson.components.length} ${exactAiInventoryType} component(s). Let's keep looking.`,
-          );
-        } else {
-          thoughtLog(
-            `I found ${bomData.bomJson.components.length} npm packages. Let's keep looking.`,
-          );
-        }
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} ${exactAiInventoryType || "npm"} components at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (bomData?.bomJson?.services?.length) {
-          options.services = mergeServices(
-            options.services || [],
-            bomData.bomJson.services,
-          );
-        }
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components
-        if (bomData.parentComponent.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    // Java
-    if (hasAnyProjectType(["oci", "java"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**JAVA**: Looking for Java projects (e.g., Maven, Gradle, SBT). I hope all configurations—from Java version to individual build settings—are correctly aligned.",
-        );
-      }
-      setProjectTypeActivityContext("java", path);
-      bomData = await withOwnParent(() => createJavaBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} java packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} java packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components, but add duplicates to the list of current components
-        // and removing them from metadata.component.components -- the components are merged later
-        if (bomData.parentComponent.components?.length) {
-          let bomSubComponents = bomData.parentComponent.components;
-          if (
-            !["false", "0"].includes(
-              readEnvironmentVariable("GRADLE_RESOLVE_FROM_NODE"),
-            )
-          ) {
-            thoughtLog(
-              "Wait, the user wants me to resolve gradle projects from npm.",
-            );
-            const allRefs = components.map((c) => c["bom-ref"]);
-            const duplicateComponents = bomSubComponents.filter((c) =>
-              allRefs.includes(c["bom-ref"]),
-            );
-            components = components.concat(duplicateComponents);
-            const duplicateComponentRefs = duplicateComponents.map(
-              (c) => c["bom-ref"],
-            );
-            bomSubComponents = bomSubComponents.filter(
-              (c) => !duplicateComponentRefs.includes(c["bom-ref"]),
-            );
-          }
-          parentSubComponents = parentSubComponents.concat(bomSubComponents);
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "py"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**PYTHON**: Looking for Python projects with package managers such as pip, poetry, uv, etc. Wish me good luck!",
-        );
-      }
-      if (
-        readEnvironmentVariable("CDXGEN_IN_CONTAINER") !== "true" &&
-        pathList.length <= 2
-      ) {
-        thoughtLog(
-          "I'm running in a non-container environment. Let's hope the correct build tools are available ✌️.",
-        );
-      }
-      setProjectTypeActivityContext("py", path);
-      bomData = await withOwnParent(() => createPythonBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} python packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} python packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components. uv workspace members are
-        // nested under the python project, so hoisting them keeps them
-        // siblings of the other sub-components instead of riding one level
-        // deeper (or being dropped by the same-name collapse) when another
-        // ecosystem's project becomes the parent.
-        if (bomData.parentComponent?.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-      if (bomData?.formulationList?.length) {
-        formulationList = formulationList.concat(bomData.formulationList);
-      }
-    }
-    if (hasAnyProjectType(["oci", "go"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**GO**: Looking for go projects. I need to be cautious about purl namespaces and potential failures with the 'go list' command.",
-        );
-      }
-      setProjectTypeActivityContext("go", path);
-      bomData = await withOwnParent(() => createGoBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(`I found ${bomData.bomJson.components.length} go packages.`);
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} go packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "rust"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**RUST**: Let's search for Cargo/Rust projects. Should I warn the user that we don't support Cargo 'features' and native dependencies, which may lead to both false positives and false negatives? 🤔?",
-        );
-      }
-      setProjectTypeActivityContext("rust", path);
-      bomData = await withOwnParent(() => createRustBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} rust packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} rust packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components
-        if (bomData.parentComponent?.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "php"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**PHP**: About to search for Composer-based projects. I hope lock files are available; otherwise, the 'composer install' command might fail for various reasons.",
-        );
-      }
-      setProjectTypeActivityContext("php", path);
-      bomData = await withOwnParent(() => createPHPBom(path, options));
-      // A lock with no packages can still hold the project's platform data.
-      if (bomData?.metadataProperties?.length) {
-        metadataProperties = metadataProperties.concat(
-          bomData.metadataProperties,
-        );
-      }
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} php packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} php packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components
-        if (bomData.parentComponent?.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "ruby"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**RUBY**: Are there any Ruby projects in this path? There's only one way to know.",
-        );
-      }
-      setProjectTypeActivityContext("ruby", path);
-      bomData = await withOwnParent(() => createRubyBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `We got ${bomData.bomJson.components.length} ruby packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} ruby packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-          bomData.parentComponent,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components
-        if (bomData.parentComponent?.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "csharp"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog("**CSHARP**: What about csharp and fsharp projects?");
-      }
-      setProjectTypeActivityContext("csharp", path);
-      bomData = await withOwnParent(() => createCsharpBom(path, options));
-      // Every project the scan read has a dependency entry of its own, so a
-      // project that uses no packages is kept along with its parent.
-      if (
-        bomData?.bomJson?.components?.length ||
-        bomData?.bomJson?.dependencies?.length
-      ) {
-        thoughtLog(
-          `There are ${bomData.bomJson.components.length} csharp packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} csharp packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-        // Retain metadata.component.components
-        if (bomData.parentComponent?.components?.length) {
-          parentSubComponents = parentSubComponents.concat(
-            bomData.parentComponent.components,
-          );
-          delete bomData.parentComponent.components;
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "dart"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**DART**: Looking for Dart projects. These are rare ones. Should I inform the user that they can pass the types argument via the command-line to speed things up?",
-        );
-      }
-      setProjectTypeActivityContext("dart", path);
-      bomData = await withOwnParent(() => createDartBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} pub packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} pub packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "haskell"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**HASKELL**: Looking for Haskell projects. They're rarely encountered.",
-        );
-      }
-      setProjectTypeActivityContext("haskell", path);
-      bomData = await withOwnParent(() => createHaskellBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} hackage packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} hackage packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "elixir"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**ELIXIR**: Looking for Elixir projects—they're quite rare as well.",
-        );
-      }
-      setProjectTypeActivityContext("elixir", path);
-      bomData = await withOwnParent(() => createElixirBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} mix packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} mix packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "c"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**C/C++**: Looking for C/C++ projects. Should I warn the user that the generated SBOM might have low accuracy and contain errors?",
-        );
-      }
-      setProjectTypeActivityContext("c", path);
-      bomData = await withOwnParent(() => createCppBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} cpp packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} cpp packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-      // presets and compilers describe the build, whatever it depends on
-      if (bomData?.formulationList?.length) {
-        formulationList = formulationList.concat(bomData.formulationList);
-      }
-    }
-    if (hasAnyProjectType(["oci", "clojure"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**CLOJURE**: Looking for Clojure projects. Should I warn the user that the purl namespace 'clojars' isn't widely supported by tools like Dependency-Track?",
-        );
-      }
-      setProjectTypeActivityContext("clojure", path);
-      bomData = await withOwnParent(() => createClojureBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} clojure packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} clojure packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "github"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**GITHUB**: Looking for any github packages and workflows.",
-        );
-      }
-      setProjectTypeActivityContext("github", path);
-      bomData = await withOwnParent(() => createGitHubBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} github action packages as well. Should I convert these to formulation instead 🤔`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} GitHub action packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "cloudbuild"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**CLOUDBUILD**: Let's check for CloudBuild configuration files that include package dependencies.",
-        );
-      }
-      setProjectTypeActivityContext("cloudbuild", path);
-      bomData = await withOwnParent(() => createCloudBuildBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} cloudbuild packages.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} CloudBuild configuration at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "swift"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**SWIFT**: Now checking for Swift projects. We don't support CocoaPods, Objective-C, or pure Xcode projects, so the SBOM will be incomplete.",
-        );
-      }
-      setProjectTypeActivityContext("swift", path);
-      bomData = await withOwnParent(() => createSwiftBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} swift packages here.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} Swift packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["oci", "jar", "war", "ear"], options)) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**JAR**: Let's check for any bundled jar/war/ear files to improve the SBOM accuracy.",
-        );
-      }
-      setProjectTypeActivityContext("jar", path);
-      recordDegradation("jvm.jar.heuristic", {
-        ecosystem: "java",
-        tool: "jar",
-        impact: "versions",
-        path,
-        detail:
-          "Components are being inferred by scanning jar/war/ear files from disk.",
+        ref: parentComponent["bom-ref"],
+        dependsOn: Array.from(parentDependsOn).sort(),
       });
-      bomData = await withOwnParent(() => createJarBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
+    }
+  }
+  if (hasAnyProjectType(["os"], options, false) && options.bomData) {
+    bomData = options.bomData;
+    if (bomData?.bomJson?.components) {
+      if (DEBUG_MODE) {
+        console.log(`Found ${bomData.bomJson.components.length} OS components`);
+      }
+      if (bomData.bomJson.components.length) {
         thoughtLog(
-          `I found ${bomData.bomJson.components.length} jar packages as well.`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} jar packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
+          `I found ${bomData.bomJson.components.length} OS packages 😎.`,
         );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
       }
+      components = components.concat(bomData.bomJson.components);
     }
-    if (hasAnyProjectType(["oci", "cocoa"], options)) {
-      setProjectTypeActivityContext("cocoa", path);
-      bomData = await withOwnParent(() => createCocoaBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} Cocoa packages at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = dependencies.concat(bomData.bomJson.dependencies);
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
+  }
+  const sharedOptions = options;
+  // The exploded image layers are written once by the extractor and only read
+  // from here on, so repeated walks of them can share one view of the tree.
+  setDirWalkCacheRoot(options.allLayersExplodedDir);
+  // The ecosystems every path is scanned for, in the order their builders run.
+  // Each step reads the per-path copy of options that scanOnePathInner passes
+  // in. One list merged by one loop also keeps type checking of this function
+  // linear: a separate block per ecosystem, each reassigning an untyped
+  // evolving array, makes TypeScript's control-flow analysis exponential in
+  // the number of blocks (issue #4705).
+  /**
+   * @param {string} path Scanned path
+   * @returns {boolean} Whether the path is a Chrome extension directory or its manifest.json
+   */
+  const isChromeExtensionPath = (path) => {
+    if (!safeExistsSync(path)) {
+      return false;
     }
-    if (hasAnyProjectType(["oci", "nix"], options)) {
-      setProjectTypeActivityContext("nix", path);
-      bomData = await withOwnParent(() => createNixBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} Nix flake packages at ${path}`,
+    if (basename(path) === "manifest.json") {
+      return true;
+    }
+    try {
+      return (
+        statSync(path).isDirectory() &&
+        safeExistsSync(join(path, "manifest.json"))
+      );
+    } catch (_err) {
+      return false;
+    }
+  };
+  /**
+   * @param {string} thought Thought log written unless the scan is of a container image
+   * @returns {(path: string, scanOptions: Object) => void} The announce hook
+   */
+  const ociQuiet = (thought) => (_path, scanOptions) => {
+    if (!hasAnyProjectType(["oci"], scanOptions, false)) {
+      thoughtLog(thought);
+    }
+  };
+  /** @type {PathScanStep[]} */
+  const pathScanSteps = [
+    {
+      // Node.js and AI inventory
+      applies: (path, scanOptions) =>
+        hasAnyProjectType(["oci", "js"], scanOptions) ||
+        hasAnyProjectType(["mcp", "ai-skill", "ai"], scanOptions) ||
+        !!getDirectAiInventoryType(path, scanOptions),
+      prepare: (path, scanOptions) =>
+        getDirectAiInventoryType(path, scanOptions),
+      announce: (_path, scanOptions, exactAiInventoryType) => {
+        if (hasAnyProjectType(["oci"], scanOptions, false)) {
+          return;
+        }
+        if (exactAiInventoryType === "mcp") {
+          thoughtLog(
+            "**MCP**: Looking for MCP services, MCP configs, and related AI control-plane artifacts.",
+          );
+        } else if (exactAiInventoryType === "ai") {
+          thoughtLog(
+            "**AI-BOM**: Looking for AI models, direct model metadata, pedigree, quantization, and operator-facing AI context.",
+          );
+        } else if (exactAiInventoryType === "ai-skill") {
+          thoughtLog(
+            "**AI-SKILL**: Looking for AI instruction, skill, and agent-definition files that can influence build or release flows.",
+          );
+        } else {
+          thoughtLog(
+            "**JS**: Now looking for JavaScript projects (npm, yarn, pnpm) and files.",
           );
         }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
+      },
+      activityType: (exactAiInventoryType) => exactAiInventoryType || "js",
+      build: createNodejsBom,
+      foundThought: (count, _path, exactAiInventoryType) =>
+        exactAiInventoryType
+          ? `I found ${count} ${exactAiInventoryType} component(s). Let's keep looking.`
+          : `I found ${count} npm packages. Let's keep looking.`,
+      debugMessage: (count, path, exactAiInventoryType) =>
+        `Found ${count} ${exactAiInventoryType || "npm"} components at ${path}`,
+      mergeServices: true,
+      hoistSubComponents: "plain",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "java"], scanOptions),
+      announce: ociQuiet(
+        "**JAVA**: Looking for Java projects (e.g., Maven, Gradle, SBT). I hope all configurations—from Java version to individual build settings—are correctly aligned.",
+      ),
+      activityType: "java",
+      build: createJavaBom,
+      foundThought: (count) => `I found ${count} java packages.`,
+      debugMessage: (count, path) => `Found ${count} java packages at ${path}`,
+      hoistSubComponents: "gradle",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "py"], scanOptions),
+      announce: (path, scanOptions) => {
+        ociQuiet(
+          "**PYTHON**: Looking for Python projects with package managers such as pip, poetry, uv, etc. Wish me good luck!",
+        )(path, scanOptions);
         if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
+          readEnvironmentVariable("CDXGEN_IN_CONTAINER") !== "true" &&
+          pathList.length <= 2
         ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
-      }
-    }
-    if (hasAnyProjectType(["caxa"], options, false)) {
-      setProjectTypeActivityContext("caxa", path);
-      bomData = await withOwnParent(() => createCaxaBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} caxa packages at ${path}`,
+          thoughtLog(
+            "I'm running in a non-container environment. Let's hope the correct build tools are available ✌️.",
           );
         }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
+      },
+      activityType: "py",
+      build: createPythonBom,
+      foundThought: (count) => `I found ${count} python packages.`,
+      debugMessage: (count, path) =>
+        `Found ${count} python packages at ${path}`,
+      // uv workspace members are nested under the python project, so hoisting
+      // them keeps them siblings of the other sub-components instead of riding
+      // one level deeper (or being dropped by the same-name collapse) when
+      // another ecosystem's project becomes the parent.
+      hoistSubComponents: "plain",
+      collectFormulation: true,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "go"], scanOptions),
+      announce: ociQuiet(
+        "**GO**: Looking for go projects. I need to be cautious about purl namespaces and potential failures with the 'go list' command.",
+      ),
+      activityType: "go",
+      build: createGoBom,
+      foundThought: (count) => `I found ${count} go packages.`,
+      debugMessage: (count, path) => `Found ${count} go packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "rust"], scanOptions),
+      announce: ociQuiet(
+        "**RUST**: Let's search for Cargo/Rust projects. Should I warn the user that we don't support Cargo 'features' and native dependencies, which may lead to both false positives and false negatives? 🤔?",
+      ),
+      activityType: "rust",
+      build: createRustBom,
+      foundThought: (count) => `I found ${count} rust packages.`,
+      debugMessage: (count, path) => `Found ${count} rust packages at ${path}`,
+      hoistSubComponents: "plain",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "php"], scanOptions),
+      announce: ociQuiet(
+        "**PHP**: About to search for Composer-based projects. I hope lock files are available; otherwise, the 'composer install' command might fail for various reasons.",
+      ),
+      activityType: "php",
+      build: createPHPBom,
+      // A lock with no packages can still hold the project's platform data.
+      collectMetadataProperties: true,
+      foundThought: (count) => `I found ${count} php packages.`,
+      debugMessage: (count, path) => `Found ${count} php packages at ${path}`,
+      hoistSubComponents: "plain",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "ruby"], scanOptions),
+      announce: ociQuiet(
+        "**RUBY**: Are there any Ruby projects in this path? There's only one way to know.",
+      ),
+      activityType: "ruby",
+      build: createRubyBom,
+      foundThought: (count) => `We got ${count} ruby packages.`,
+      debugMessage: (count, path) => `Found ${count} ruby packages at ${path}`,
+      dependencyMerge: "mergeWithParent",
+      hoistSubComponents: "plain",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "csharp"], scanOptions),
+      announce: ociQuiet("**CSHARP**: What about csharp and fsharp projects?"),
+      activityType: "csharp",
+      build: createCsharpBom,
+      // Every project the scan read has a dependency entry of its own, so a
+      // project that uses no packages is kept along with its parent.
+      isUseful: (bomData) =>
+        !!(
+          bomData?.bomJson?.components?.length ||
+          bomData?.bomJson?.dependencies?.length
+        ),
+      foundThought: (count) => `There are ${count} csharp packages.`,
+      debugMessage: (count, path) =>
+        `Found ${count} csharp packages at ${path}`,
+      hoistSubComponents: "plain",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "dart"], scanOptions),
+      announce: ociQuiet(
+        "**DART**: Looking for Dart projects. These are rare ones. Should I inform the user that they can pass the types argument via the command-line to speed things up?",
+      ),
+      activityType: "dart",
+      build: createDartBom,
+      foundThought: (count) => `I found ${count} pub packages.`,
+      debugMessage: (count, path) => `Found ${count} pub packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "haskell"], scanOptions),
+      announce: ociQuiet(
+        "**HASKELL**: Looking for Haskell projects. They're rarely encountered.",
+      ),
+      activityType: "haskell",
+      build: createHaskellBom,
+      foundThought: (count) => `I found ${count} hackage packages.`,
+      debugMessage: (count, path) =>
+        `Found ${count} hackage packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "elixir"], scanOptions),
+      announce: ociQuiet(
+        "**ELIXIR**: Looking for Elixir projects—they're quite rare as well.",
+      ),
+      activityType: "elixir",
+      build: createElixirBom,
+      foundThought: (count) => `I found ${count} mix packages.`,
+      debugMessage: (count, path) => `Found ${count} mix packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "c"], scanOptions),
+      announce: ociQuiet(
+        "**C/C++**: Looking for C/C++ projects. Should I warn the user that the generated SBOM might have low accuracy and contain errors?",
+      ),
+      activityType: "c",
+      build: createCppBom,
+      foundThought: (count) => `I found ${count} cpp packages.`,
+      debugMessage: (count, path) => `Found ${count} cpp packages at ${path}`,
+      // presets and compilers describe the build, whatever it depends on
+      collectFormulation: true,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "clojure"], scanOptions),
+      announce: ociQuiet(
+        "**CLOJURE**: Looking for Clojure projects. Should I warn the user that the purl namespace 'clojars' isn't widely supported by tools like Dependency-Track?",
+      ),
+      activityType: "clojure",
+      build: createClojureBom,
+      foundThought: (count) => `I found ${count} clojure packages.`,
+      debugMessage: (count, path) =>
+        `Found ${count} clojure packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "github"], scanOptions),
+      announce: ociQuiet(
+        "**GITHUB**: Looking for any github packages and workflows.",
+      ),
+      activityType: "github",
+      build: createGitHubBom,
+      foundThought: (count) =>
+        `I found ${count} github action packages as well. Should I convert these to formulation instead 🤔`,
+      debugMessage: (count, path) =>
+        `Found ${count} GitHub action packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "cloudbuild"], scanOptions),
+      announce: ociQuiet(
+        "**CLOUDBUILD**: Let's check for CloudBuild configuration files that include package dependencies.",
+      ),
+      activityType: "cloudbuild",
+      build: createCloudBuildBom,
+      foundThought: (count) => `I found ${count} cloudbuild packages.`,
+      debugMessage: (count, path) =>
+        `Found ${count} CloudBuild configuration at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "swift"], scanOptions),
+      announce: ociQuiet(
+        "**SWIFT**: Now checking for Swift projects. We don't support CocoaPods, Objective-C, or pure Xcode projects, so the SBOM will be incomplete.",
+      ),
+      activityType: "swift",
+      build: createSwiftBom,
+      foundThought: (count) => `I found ${count} swift packages here.`,
+      debugMessage: (count, path) => `Found ${count} Swift packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "jar", "war", "ear"], scanOptions),
+      announce: ociQuiet(
+        "**JAR**: Let's check for any bundled jar/war/ear files to improve the SBOM accuracy.",
+      ),
+      activityType: "jar",
+      beforeBuild: (path) => {
+        recordDegradation("jvm.jar.heuristic", {
+          ecosystem: "java",
+          tool: "jar",
+          impact: "versions",
+          path,
+          detail:
+            "Components are being inferred by scanning jar/war/ear files from disk.",
+        });
+      },
+      build: createJarBom,
+      foundThought: (count) => `I found ${count} jar packages as well.`,
+      debugMessage: (count, path) => `Found ${count} jar packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "cocoa"], scanOptions),
+      activityType: "cocoa",
+      build: createCocoaBom,
+      debugMessage: (count, path) => `Found ${count} Cocoa packages at ${path}`,
+      dependencyMerge: "concat",
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["oci", "nix"], scanOptions),
+      activityType: "nix",
+      build: createNixBom,
+      debugMessage: (count, path) =>
+        `Found ${count} Nix flake packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["caxa"], scanOptions, false),
+      activityType: "caxa",
+      build: createCaxaBom,
+      debugMessage: (count, path) => `Found ${count} caxa packages at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["asar"], scanOptions, false),
+      activityType: "asar",
+      build: createAsarBom,
+      debugMessage: (count, path) =>
+        `Found ${count} ASAR component(s) at ${path}`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["vscode-extension"], scanOptions, false),
+      activityType: "vscode-extension",
+      build: createVscodeExtensionBom,
+      debugMessage: (count, path) =>
+        `Found ${count} VS Code extension(s) at ${path}`,
+    },
+    {
+      // A path that is a Chrome extension is always scanned. Any other path
+      // scans the extensions installed on this host, which happens once per
+      // run however many paths there are.
+      applies: (path, scanOptions) =>
+        hasAnyProjectType(["chrome-extension"], scanOptions, false) &&
+        (isChromeExtensionPath(path) ||
+          !sharedOptions.__didScanChromeExtensions),
+      beforeBuild: (path) => {
+        if (!isChromeExtensionPath(path)) {
+          sharedOptions.__didScanChromeExtensions = true;
         }
+      },
+      activityType: "chrome-extension",
+      build: createChromeExtensionBom,
+      debugMessage: (count) =>
+        `Found ${count} Chrome extension(s) on this host`,
+    },
+    {
+      applies: (_path, scanOptions) =>
+        hasAnyProjectType(["terraform"], scanOptions),
+      announce: () => {
+        thoughtLog(
+          "**TERRAFORM**: Looking for Terraform and OpenTofu modules and providers. The registry metadata fetch is opt-in, so I will rely on the lock file, the module manifest and the configuration files.",
+        );
+      },
+      activityType: "terraform",
+      build: createTerraformBom,
+      foundThought: (count) =>
+        `I found ${count} terraform components. Should I also resolve their licenses from the registry when FETCH_LICENSE is enabled?`,
+      debugMessage: (count, path) =>
+        `Found ${count} terraform components at ${path}`,
+    },
+    {
+      // Collect any crypto keys
+      applies: (_path, scanOptions) =>
+        scanOptions.specVersion >= 1.6 &&
+        !!scanOptions.includeCrypto &&
+        isCycloneDxComponentTypeEnabled("cryptographic-asset", scanOptions),
+      announce: ociQuiet(
+        "**CBOM**: Wait, the user wants me to look for cryptographic assets. Let's check thoroughly.",
+      ),
+      activityType: "cbom",
+      build: createCryptoCertsBom,
+      foundThought: (count) => `I found ${count} crypto assets.`,
+      debugMessage: (count, path) => `Found ${count} crypto assets at ${path}`,
+      dependencyMerge: "topLevel",
+      keepParent: false,
+    },
+  ];
+  const scanOnePath = async (path) => {
+    try {
+      return await scanOnePathInner(path);
+    } catch (err) {
+      if (!isDeferredFailOnError(err)) {
+        throw err;
       }
+      // The failing path contributes nothing, and the remaining paths still
+      // do: fail-on-error scopes the loss to the leg that failed.
+      return {
+        components: [],
+        dependencies: [],
+        options: { ...sharedOptions },
+        parentSubComponents: [],
+        metadataProperties: [],
+        formulationList: [],
+      };
     }
-    if (hasAnyProjectType(["asar"], options, false)) {
-      setProjectTypeActivityContext("asar", path);
-      bomData = await withOwnParent(() => createAsarBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} ASAR component(s) at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
+  };
+  const scanOnePathInner = async (path) => {
+    // Each path accumulates into its own lists and its own view of options, so
+    // that legs which record a parent component or a tool cannot overwrite
+    // another path's. The lists are merged below in pathList order.
+    const options = { ...sharedOptions };
+    /** @type {BuilderBomData | undefined} */
+    let bomData;
+    /** @type {Object[]} */
+    let components = [];
+    /** @type {Object[]} */
+    let dependencies = [];
+    /** @type {Object[]} */
+    let parentSubComponents = [];
+    /** @type {Object[]} */
+    let metadataProperties = [];
+    /** @type {Object[]} */
+    let pathFormulationList = [];
+    // Each builder detects the project of its own ecosystem. A builder that sets
+    // options.parentComponent to force its project into its own BOM must not
+    // make that project the next builder's too, or the next ecosystem's project
+    // is lost: every builder starts from the parent the caller gave.
+    const callerParent = options.parentComponent;
+    const withOwnParent = async (build) => {
+      options.parentComponent = callerParent;
+      try {
+        return await build();
+      } finally {
+        options.parentComponent = callerParent;
       }
+    };
+    setActivityContext({
+      projectType: Array.isArray(options.projectType)
+        ? options.projectType.join(",")
+        : options.projectType,
+      sourcePath: path,
+    });
+    recordActivity({
+      kind: "read",
+      reason:
+        "Scanning project path for supported languages and package managers.",
+      status: "completed",
+      target: path,
+    });
+    if (DEBUG_MODE) {
+      console.log("Scanning", path);
     }
-    if (hasAnyProjectType(["vscode-extension"], options, false)) {
-      setProjectTypeActivityContext("vscode-extension", path);
-      bomData = await withOwnParent(() =>
-        createVscodeExtensionBom(path, options),
+    if (pathList.length > 2) {
+      thoughtLog(`Let's thoroughly check the path ${path}.`);
+    }
+    for (const step of pathScanSteps) {
+      if (!step.applies(path, options)) {
+        continue;
+      }
+      const context = step.prepare?.(path, options);
+      step.announce?.(path, options, context);
+      setProjectTypeActivityContext(
+        typeof step.activityType === "function"
+          ? step.activityType(context)
+          : step.activityType,
+        path,
       );
-      if (bomData?.bomJson?.components?.length) {
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} VS Code extension(s) at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
+      step.beforeBuild?.(path);
+      const { build } = step;
+      bomData = /** @type {BuilderBomData | undefined} */ (
+        await withOwnParent(() => build(path, options))
+      );
+      if (
+        step.collectMetadataProperties &&
+        bomData?.metadataProperties?.length
+      ) {
+        metadataProperties = metadataProperties.concat(
+          bomData.metadataProperties,
         );
-        if (
-          bomData.parentComponent &&
-          Object.keys(bomData.parentComponent).length
-        ) {
-          parentSubComponents.push(bomData.parentComponent);
-        }
       }
-    }
-    if (hasAnyProjectType(["chrome-extension"], options, false)) {
-      let isExplicitChromeExtensionPath = false;
-      if (safeExistsSync(path)) {
-        if (basename(path) === "manifest.json") {
-          isExplicitChromeExtensionPath = true;
-        } else {
-          try {
-            isExplicitChromeExtensionPath =
-              statSync(path).isDirectory() &&
-              safeExistsSync(join(path, "manifest.json"));
-          } catch (_err) {
-            isExplicitChromeExtensionPath = false;
-          }
+      const isUseful = step.isUseful
+        ? step.isUseful(bomData)
+        : !!bomData?.bomJson?.components?.length;
+      if (isUseful) {
+        // a csharp result can be kept for its dependencies alone
+        const count = bomData.bomJson.components?.length || 0;
+        const thought = step.foundThought?.(count, path, context);
+        if (thought) {
+          thoughtLog(thought);
         }
-      }
-      if (
-        isExplicitChromeExtensionPath ||
-        !sharedOptions.__didScanChromeExtensions
-      ) {
-        if (!isExplicitChromeExtensionPath) {
-          sharedOptions.__didScanChromeExtensions = true;
+        if (DEBUG_MODE) {
+          console.log(step.debugMessage(count, path, context));
         }
-        setProjectTypeActivityContext("chrome-extension", path);
-        bomData = await withOwnParent(() =>
-          createChromeExtensionBom(path, options),
-        );
-        if (bomData?.bomJson?.components?.length) {
-          if (DEBUG_MODE) {
-            console.log(
-              `Found ${bomData.bomJson.components.length} Chrome extension(s) on this host`,
+        components = components.concat(bomData.bomJson.components || []);
+        if (step.dependencyMerge === "concat") {
+          dependencies = dependencies.concat(
+            bomData.bomJson.dependencies || [],
+          );
+        } else if (step.dependencyMerge === "topLevel") {
+          // the crypto scan returns its dependencies beside bomJson
+          if (bomData.dependencies?.length) {
+            dependencies = mergeDependencies(
+              dependencies,
+              bomData.dependencies,
             );
           }
-          components = components.concat(bomData.bomJson.components);
+        } else if (step.dependencyMerge === "mergeWithParent") {
+          dependencies = mergeDependencies(
+            dependencies,
+            bomData.bomJson.dependencies,
+            bomData.parentComponent,
+          );
+        } else {
           dependencies = mergeDependencies(
             dependencies,
             bomData.bomJson.dependencies,
           );
-          if (
-            bomData.parentComponent &&
-            Object.keys(bomData.parentComponent).length
-          ) {
-            parentSubComponents.push(bomData.parentComponent);
-          }
         }
-      }
-    }
-    if (hasAnyProjectType(["terraform"], options)) {
-      thoughtLog(
-        "**TERRAFORM**: Looking for Terraform and OpenTofu modules and providers. The registry metadata fetch is opt-in, so I will rely on the lock file, the module manifest and the configuration files.",
-      );
-      setProjectTypeActivityContext("terraform", path);
-      bomData = await withOwnParent(() => createTerraformBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} terraform components. Should I also resolve their licenses from the registry when FETCH_LICENSE is enabled?`,
-        );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} terraform components at ${path}`,
+        if (step.mergeServices && bomData?.bomJson?.services?.length) {
+          options.services = mergeServices(
+            options.services || [],
+            bomData.bomJson.services,
           );
         }
-        components = components.concat(bomData.bomJson.components);
-        dependencies = mergeDependencies(
-          dependencies,
-          bomData.bomJson.dependencies,
-        );
         if (
+          step.keepParent !== false &&
           bomData.parentComponent &&
           Object.keys(bomData.parentComponent).length
         ) {
           parentSubComponents.push(bomData.parentComponent);
         }
+        // Retain metadata.component.components
+        if (
+          step.hoistSubComponents &&
+          bomData.parentComponent?.components?.length
+        ) {
+          let bomSubComponents = bomData.parentComponent.components;
+          // For java, sub-components that are already components are added
+          // to the list of current components and removed from
+          // metadata.component.components; the components are merged later.
+          if (
+            step.hoistSubComponents === "gradle" &&
+            !["false", "0"].includes(
+              readEnvironmentVariable("GRADLE_RESOLVE_FROM_NODE"),
+            )
+          ) {
+            thoughtLog(
+              "Wait, the user wants me to resolve gradle projects from npm.",
+            );
+            const allRefs = components.map((c) => c["bom-ref"]);
+            const duplicateComponents = bomSubComponents.filter((c) =>
+              allRefs.includes(c["bom-ref"]),
+            );
+            components = components.concat(duplicateComponents);
+            const duplicateComponentRefs = duplicateComponents.map(
+              (c) => c["bom-ref"],
+            );
+            bomSubComponents = bomSubComponents.filter(
+              (c) => !duplicateComponentRefs.includes(c["bom-ref"]),
+            );
+          }
+          parentSubComponents = parentSubComponents.concat(bomSubComponents);
+          delete bomData.parentComponent.components;
+        }
       }
-    }
-    // Collect any crypto keys
-    if (
-      options.specVersion >= 1.6 &&
-      options.includeCrypto &&
-      isCycloneDxComponentTypeEnabled("cryptographic-asset", options)
-    ) {
-      if (!hasAnyProjectType(["oci"], options, false)) {
-        thoughtLog(
-          "**CBOM**: Wait, the user wants me to look for cryptographic assets. Let's check thoroughly.",
-        );
-      }
-      setProjectTypeActivityContext("cbom", path);
-      bomData = await withOwnParent(() => createCryptoCertsBom(path, options));
-      if (bomData?.bomJson?.components?.length) {
-        thoughtLog(
-          `I found ${bomData.bomJson.components.length} crypto assets.`,
+      if (step.collectFormulation && bomData?.formulationList?.length) {
+        pathFormulationList = pathFormulationList.concat(
+          bomData.formulationList,
         );
-        if (DEBUG_MODE) {
-          console.log(
-            `Found ${bomData.bomJson.components.length} crypto assets at ${path}`,
-          );
-        }
-        components = components.concat(bomData.bomJson.components);
-        if (bomData.dependencies?.length) {
-          dependencies = mergeDependencies(dependencies, bomData.dependencies);
-        }
       }
     }
     return {
@@ -1818,6 +1604,7 @@ export async function createMultiXBom(pathList, options) {
       options,
       parentSubComponents,
       metadataProperties,
+      formulationList: pathFormulationList,
     };
   };
   const pathResults = [];
@@ -1884,6 +1671,7 @@ export async function createMultiXBom(pathList, options) {
     metadataProperties = metadataProperties.concat(
       pathResult.metadataProperties,
     );
+    formulationList = formulationList.concat(pathResult.formulationList);
     if (pathResult.options.services?.length) {
       sharedOptions.services = mergeServices(
         sharedOptions.services || [],
@@ -1975,6 +1763,26 @@ export async function createMultiXBom(pathList, options) {
     dependencies,
     metadataProperties,
   );
+  // Language packages an OS package installed are judged by that package.
+  // Duplicates have merged by now, so a component found both where the distro
+  // put it and where pip did is seen whole and left unmarked.
+  markOsInstalledLanguagePackages(
+    multiResult.bomJson?.components,
+    osFileOwners,
+    options.allLayersExplodedDir,
+  );
+  // The default gems of an unpackaged Ruby, such as resolv in a Docker
+  // Official image, ship with that Ruby and are updated by its releases.
+  const defaultGemEdges = linkDefaultGemsToRuntimes(
+    multiResult.bomJson?.components,
+    options.allLayersExplodedDir,
+  );
+  if (defaultGemEdges.length && multiResult.bomJson) {
+    multiResult.bomJson.dependencies = mergeDependencies(
+      multiResult.bomJson.dependencies || [],
+      defaultGemEdges,
+    );
+  }
   if (formulationList.length) {
     multiResult.formulationList = formulationList;
   }
@@ -3051,6 +2859,16 @@ async function createBomForPath(path, options) {
  * @throws {Error} if the request fails
  */
 export async function submitBom(args, bomContents) {
+  // Dependency-Track ingests CycloneDX 1.x only. The CLI and the server refuse
+  // a 2.0 upload before generating; this covers library callers.
+  if (
+    isCycloneDx20SpecVersion(bomContents?.specVersion) ||
+    bomContents?.specFormat !== undefined
+  ) {
+    console.log(DEPENDENCY_TRACK_CDX20_ERROR);
+    args.failOnError && process.exit(1);
+    return undefined;
+  }
   const dependencyTrackApiUrl = getDependencyTrackBomApiUrl(args.serverUrl);
   const serverUrl = dependencyTrackApiUrl?.toString();
   if (!dependencyTrackApiUrl || !serverUrl) {