@cdxgen/cdxgen 13.0.0 → 13.1.0

package/lib/stages/postgen/introspection/formulationEvidence.js

@@ -0,0 +1,427 @@
+/**
+ * Reader over the BOM's formulation section, the third evidence source.
+ *
+ * Formulation is two things at once, and the distinction governs every
+ * confidence decision downstream. The run-derived half — `type: "platform"`
+ * components recording the toolchain the generating run probed, and the git
+ * provenance components — is what cdxgen itself did. The config-parsed half —
+ * the commands, environment variables and task types under
+ * `formulation[].workflows[]` — is what the repo's CI declares, and a
+ * declared command was never observed to run.
+ *
+ * This module is pure: the BOM and the caller's run facts are the only
+ * inputs, nothing is read from the filesystem, and environment variable
+ * *values* are never touched — names only, because the BOM stores them and
+ * copying them into a report would republish them.
+ */
+
+/**
+ * Property carrying the id of the run that stamped a BOM's formulation, set
+ * on every formulation workflow by the introspection pass that reflected
+ * over the freshly generated document.
+ *
+ * @type {string}
+ */
+export const FORMULATION_RUN_ID_PROPERTY = "cdx:introspection:runId";
+
+/** The formulation record was produced by the run being reflected. */
+export const FORMULATION_ORIGIN_SAME_RUN = "same-run";
+
+/** The formulation record came with a BOM this run did not generate. */
+export const FORMULATION_ORIGIN_FOREIGN = "foreign";
+
+/**
+ * The BOM carries no formulation record at all, which is neither of the
+ * above: there is no evidence to weigh, so every consumer must behave as it
+ * did before formulation became a source.
+ */
+export const FORMULATION_ORIGIN_ABSENT = "absent";
+
+/**
+ * Platform component names, as the environment probes emit them, mapped to
+ * the canonical ecosystem whose row their facts can corroborate. Names not
+ * listed here have no fidelity row to join.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const TOOL_NAME_ECOSYSTEMS = Object.freeze({
+  java: "java",
+  dotnet: "csharp",
+  python: "python",
+  "Node.js": "npm",
+  gcc: "c",
+  rustc: "rust",
+  go: "go",
+  ruby: "ruby",
+  swift: "swift",
+});
+
+/**
+ * Resolver executables whose presence in a declared command says a build or
+ * dependency resolution was attempted, mapped to the ecosystem they drive.
+ * Keys are executable basenames, lower-cased.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RESOLVER_EXECUTABLES = Object.freeze({
+  mvn: "java",
+  mvnw: "java",
+  gradle: "java",
+  gradlew: "java",
+  java: "java",
+  ant: "java",
+  sbt: "java",
+  npm: "npm",
+  pnpm: "npm",
+  yarn: "npm",
+  bun: "npm",
+  deno: "npm",
+  npx: "npm",
+  node: "npm",
+  pip: "python",
+  pip3: "python",
+  poetry: "python",
+  uv: "python",
+  pdm: "python",
+  pipenv: "python",
+  conda: "python",
+  python: "python",
+  python3: "python",
+  cargo: "rust",
+  go: "go",
+  bundle: "ruby",
+  gem: "ruby",
+  rake: "ruby",
+  ruby: "ruby",
+  dotnet: "csharp",
+  nuget: "csharp",
+  composer: "php",
+  dart: "dart",
+  flutter: "dart",
+  helm: "helm",
+  lein: "clojure",
+  clj: "clojure",
+  clojure: "clojure",
+  swift: "swift",
+  pod: "cocoa",
+  mix: "elixir",
+  cmake: "c",
+  make: "c",
+  meson: "c",
+  ninja: "c",
+  cabal: "haskell",
+  stack: "haskell",
+});
+
+/**
+ * The runtime names the reflection reports, mapped to the family a
+ * formulation platform component records for the same runtime.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const RUNTIME_FAMILIES = Object.freeze({
+  "Node.js": "Node.js",
+  node: "Node.js",
+  Deno: "Deno",
+  deno: "Deno",
+  Bun: "Bun",
+  bun: "Bun",
+});
+
+/**
+ * The final path segment of a POSIX- or Windows-flavoured command token.
+ *
+ * @param {string} token Command token.
+ * @returns {string} The token after its last path separator.
+ */
+function basenameOfToken(token) {
+  const slash = token.lastIndexOf("/");
+  const backslash = token.lastIndexOf("\\");
+  return token.slice(Math.max(slash, backslash) + 1);
+}
+
+/**
+ * Whether an `executed` value is a CI action reference such as
+ * `actions/checkout@<sha>` rather than a shell command. An action reference
+ * carries no whitespace, contains a path separator, and names a revision of
+ * the repository after the last separator; a relative-path executable such
+ * as `./mvnw` carries no revision and stays a command.
+ *
+ * @param {string|undefined} executed The executed value of a step command.
+ * @returns {boolean} True when the value names an action, not a command.
+ */
+export function isActionReference(executed) {
+  if (typeof executed !== "string" || !executed.trim()) {
+    return false;
+  }
+  const text = executed.trim();
+  if (/\s/.test(text) || !text.includes("/")) {
+    return false;
+  }
+  const lastSegment = text.slice(text.lastIndexOf("/") + 1);
+  return lastSegment.includes("@");
+}
+
+/**
+ * The executable a command line starts with, as a bare name.
+ *
+ * @param {string|undefined} commandLine Command line.
+ * @returns {string} Basename of the first whitespace token, or "" when absent.
+ */
+export function executableOf(commandLine) {
+  const first = `${commandLine || ""}`.trim().split(/\s+/)[0] || "";
+  return basenameOfToken(first);
+}
+
+/**
+ * The revision a git provenance component records, from its OmniBOR or
+ * Software Heritage identifier. Identifiers prefix the raw hash with a
+ * scheme and type, so the value after the last colon is the revision itself.
+ *
+ * @param {Object} component Formulation component of type `file`.
+ * @returns {string|undefined} The raw revision, when the component names one.
+ */
+function revisionOf(component) {
+  const identifiers = [
+    ...(Array.isArray(component?.omniborId) ? component.omniborId : []),
+    ...(Array.isArray(component?.swhid) ? component.swhid : []),
+  ];
+  for (const identifier of identifiers) {
+    if (typeof identifier === "string" && identifier.includes(":")) {
+      return identifier.slice(identifier.lastIndexOf(":") + 1) || undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether a formulation component is one of the git graph nodes the
+ * provenance builder adds beside the per-file blobs.
+ *
+ * @param {Object} component Formulation component.
+ * @returns {boolean} True for `git-parent` and `git-tree`.
+ */
+function isGitGraphNode(component) {
+  return component?.name === "git-parent" || component?.name === "git-tree";
+}
+
+/**
+ * The run id a formulation workflow carries, when the introspection pass
+ * that reflected over it stamped one.
+ *
+ * @param {Object} workflow Formulation workflow.
+ * @returns {string|undefined} The stamped run id, when present.
+ */
+function stampedRunId(workflow) {
+  for (const property of Array.isArray(workflow?.properties)
+    ? workflow.properties
+    : []) {
+    if (property?.name === FORMULATION_RUN_ID_PROPERTY) {
+      return property?.value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether a formulation workflow carries this run's id marker.
+ *
+ * @param {Object} bomJson CycloneDX BOM.
+ * @param {string} runId The reflection's own run id.
+ * @returns {boolean} True when the formulation names this run.
+ */
+function carriesRunIdMarker(bomJson, runId) {
+  if (!runId) {
+    return false;
+  }
+  for (const entry of Array.isArray(bomJson?.formulation)
+    ? bomJson.formulation
+    : []) {
+    for (const workflow of Array.isArray(entry?.workflows)
+      ? entry.workflows
+      : []) {
+      if (stampedRunId(workflow) === runId) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Read the provenance-aware formulation evidence out of a BOM.
+ *
+ * `origin` decides how the evidence may be used. `same-run` means the
+ * formulation describes this very run — its platform components are the same
+ * probes the ledger recorded as `tool.resolved`, so the evidence corroborates
+ * and must never add confidence. `foreign` means the BOM arrived without a
+ * ledger for its generation, and the formulation is the only surviving trace
+ * of what that build attempted. `absent` is neither: the BOM carries no
+ * formulation record, so there is nothing to weigh and every consumer keeps
+ * the behaviour it had before formulation became a source.
+ *
+ * Environment variable names are collected; values are never read.
+ *
+ * @param {Object} bomJson CycloneDX BOM.
+ * @param {Object} [context] Run facts the caller already knows.
+ * @param {string} [context.runId] This reflection's run id, matched against the formulation's marker.
+ * @param {number} [context.ledgerEventCount] Events the ledger holds for this BOM's generation.
+ * @returns {{
+ *   origin: "same-run"|"foreign"|"absent",
+ *   tools: {name: string|undefined, version: string|undefined, source: "probe"}[],
+ *   declaredCommands: {executable: string, commandLine: string, workflow: string|undefined, task: string|undefined, step: string|undefined, source: "ci-config"}[],
+ *   sourceTree: {commit: string|undefined, treeId: string|undefined, fileCount: number}|undefined,
+ *   environmentKeys: string[]
+ * }} The formulation evidence.
+ */
+export function readFormulationEvidence(bomJson, context = {}) {
+  const entries = Array.isArray(bomJson?.formulation)
+    ? bomJson.formulation
+    : [];
+  const sameRun =
+    Number(context.ledgerEventCount) > 0 ||
+    carriesRunIdMarker(bomJson, context.runId);
+  const tools = [];
+  let commit;
+  let treeId;
+  let fileCount = 0;
+  const environmentKeys = [];
+  const declaredCommands = [];
+  for (const entry of entries) {
+    for (const component of Array.isArray(entry?.components)
+      ? entry.components
+      : []) {
+      if (component?.type === "platform") {
+        tools.push({
+          name: component.name,
+          version: component.version,
+          source: "probe",
+        });
+      } else if (component?.type === "file") {
+        if (isGitGraphNode(component)) {
+          if (component.name === "git-parent") {
+            commit = revisionOf(component) || commit;
+          } else {
+            treeId = revisionOf(component) || treeId;
+          }
+        } else {
+          fileCount += 1;
+        }
+      }
+    }
+    for (const workflow of Array.isArray(entry?.workflows)
+      ? entry.workflows
+      : []) {
+      for (const input of Array.isArray(workflow?.inputs)
+        ? workflow.inputs
+        : []) {
+        for (const variable of Array.isArray(input?.environmentVars)
+          ? input.environmentVars
+          : []) {
+          if (variable?.name && !environmentKeys.includes(variable.name)) {
+            environmentKeys.push(variable.name);
+          }
+        }
+      }
+      for (const task of Array.isArray(workflow?.tasks) ? workflow.tasks : []) {
+        for (const step of Array.isArray(task?.steps) ? task.steps : []) {
+          for (const command of Array.isArray(step?.commands)
+            ? step.commands
+            : []) {
+            const executed = command?.executed;
+            if (
+              typeof executed !== "string" ||
+              !executed.trim() ||
+              isActionReference(executed)
+            ) {
+              continue;
+            }
+            declaredCommands.push({
+              executable: executableOf(executed),
+              commandLine: executed.trim(),
+              workflow: workflow?.name || workflow?.uid,
+              task: task?.name || task?.uid,
+              step: step?.name,
+              source: "ci-config",
+            });
+          }
+        }
+      }
+    }
+  }
+  return {
+    origin: !entries.length
+      ? FORMULATION_ORIGIN_ABSENT
+      : sameRun
+        ? FORMULATION_ORIGIN_SAME_RUN
+        : FORMULATION_ORIGIN_FOREIGN,
+    tools,
+    declaredCommands,
+    sourceTree:
+      commit || treeId || fileCount > 0
+        ? { commit, treeId, fileCount }
+        : undefined,
+    environmentKeys,
+  };
+}
+
+/**
+ * The formulation platform entry for the runtime family this reflection runs
+ * on, when the record cannot describe the machine in use: either the
+ * recorded version of the family differs from the runtime actually running,
+ * or the record names other toolchains but no entry of this family at all. A
+ * difference proves the formulation's toolchain record describes a machine
+ * other than the one re-scanning the BOM; it says nothing about the other
+ * toolchains the record names, which no probe of this run observed.
+ *
+ * @param {Object} evidence Formulation evidence from readFormulationEvidence.
+ * @param {Object} runtime The reflection's runtime facts.
+ * @param {string} runtime.name Runtime name, such as "Node.js".
+ * @param {string} runtime.version Runtime version.
+ * @returns {{tool: string, recordedVersion: string|undefined, runtimeVersion: string}|undefined} The mismatching formulation entry, when one exists.
+ */
+export function findRuntimeToolMismatch(evidence, runtime) {
+  const family = RUNTIME_FAMILIES[`${runtime?.name}`];
+  const tools = Array.isArray(evidence?.tools) ? evidence.tools : [];
+  if (!family || !runtime?.version || !tools.length) {
+    return undefined;
+  }
+  for (const tool of tools) {
+    if (tool?.name === family) {
+      if (tool.version !== runtime.version) {
+        return {
+          tool: family,
+          recordedVersion: tool.version,
+          runtimeVersion: runtime.version,
+        };
+      }
+      return undefined;
+    }
+  }
+  return {
+    tool: family,
+    recordedVersion: undefined,
+    runtimeVersion: runtime.version,
+  };
+}
+
+/**
+ * The declared CI command a formulation records for one ecosystem, if any.
+ * Commands carry no ecosystem tag, so the executable answers: the first
+ * declared command whose executable drives that ecosystem's resolver wins,
+ * in the order the formulation records them.
+ *
+ * @param {Object} evidence Formulation evidence from readFormulationEvidence.
+ * @param {string} ecosystem Canonical ecosystem name.
+ * @returns {Object|undefined} The matching declared command entry.
+ */
+export function declaredCommandForEcosystem(evidence, ecosystem) {
+  for (const command of Array.isArray(evidence?.declaredCommands)
+    ? evidence.declaredCommands
+    : []) {
+    if (RESOLVER_EXECUTABLES[command.executable] === ecosystem) {
+      return command;
+    }
+  }
+  return undefined;
+}

package/lib/stages/postgen/introspection/markers.js

@@ -0,0 +1,227 @@
+/**
+ * Ecosystem marker detection for the build-introspection reflection step.
+ *
+ * A marker is a manifest or lockfile whose presence on disk proves an
+ * ecosystem was part of the scanned project. Markers drive two verdicts:
+ * an ecosystem with markers but zero components in the BOM is `absent`, and
+ * an ecosystem that has markers but no cdxgen project type at all is a
+ * coverage gap (`unsupported`), which is cdxgen's backlog rather than the
+ * user's problem.
+ *
+ * Detection is deliberately bounded: the scanned directory itself plus one
+ * level of immediate subdirectories. postProcess runs after generation, so a
+ * second full tree walk would be a measurable cost on large repos; markers
+ * deeper than one directory level are simply not seen, which is acceptable
+ * because tier assignment never relies on markers alone when the BOM already
+ * carries the ecosystem's components.
+ */
+
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { safeExistsSync } from "../../../core/fs.js";
+
+/** Largest number of immediate subdirectories inspected at depth one. */
+const MAX_SUBDIRS_SCANNED = 100;
+
+/**
+ * Marker table: ecosystem → manifest and lockfile names that indicate the
+ * ecosystem is part of the project. Entries are either exact file names or
+ * `{ suffix }` matchers for extension-driven ecosystems. Ecosystems cdxgen
+ * cannot parse (elm, crystal, nim, perl, r) are included so the reflection
+ * can report them as coverage gaps instead of silently ignoring them.
+ *
+ * @type {Readonly<Record<string, {names: string[], suffixes: string[]}>>}
+ */
+export const ECOSYSTEM_MARKERS = Object.freeze({
+  java: {
+    names: [
+      "pom.xml",
+      "build.gradle",
+      "build.gradle.kts",
+      "settings.gradle",
+      "settings.gradle.kts",
+      "gradlew",
+      "build.sbt",
+      "mill-version",
+      ".sdkmanrc",
+    ],
+    suffixes: [],
+  },
+  npm: {
+    names: [
+      "package.json",
+      "package-lock.json",
+      "pnpm-lock.yaml",
+      "pnpm-workspace.yaml",
+      "yarn.lock",
+      "bun.lockb",
+      "bun.lock",
+      "deno.lock",
+    ],
+    suffixes: [],
+  },
+  python: {
+    names: [
+      "requirements.txt",
+      "Pipfile",
+      "Pipfile.lock",
+      "pyproject.toml",
+      "poetry.lock",
+      "pdm.lock",
+      "uv.lock",
+      "setup.py",
+      "setup.cfg",
+      ".python-version",
+      "environment.yml",
+    ],
+    suffixes: [],
+  },
+  go: { names: ["go.mod", "go.sum", "go.work"], suffixes: [] },
+  rust: {
+    names: [
+      "Cargo.toml",
+      "Cargo.lock",
+      "rust-toolchain.toml",
+      "rust-toolchain",
+    ],
+    suffixes: [],
+  },
+  ruby: { names: ["Gemfile", "Gemfile.lock", ".ruby-version"], suffixes: [] },
+  csharp: {
+    names: ["global.json", "nuget.config"],
+    suffixes: [".csproj", ".vbproj", ".fsproj", ".sln"],
+  },
+  php: { names: ["composer.json", "composer.lock"], suffixes: [] },
+  dart: { names: ["pubspec.yaml", "pubspec.lock"], suffixes: [] },
+  helm: { names: ["Chart.yaml", "Chart.yml"], suffixes: [] },
+  clojure: {
+    names: ["project.clj", "deps.edn", "bb.edn", "shadow-cljs.edn"],
+    suffixes: [],
+  },
+  cocoa: { names: ["Podfile", "Podfile.lock"], suffixes: [] },
+  swift: { names: ["Package.swift", "Package.resolved"], suffixes: [] },
+  elixir: { names: ["mix.exs", "mix.lock"], suffixes: [] },
+  c: {
+    names: ["CMakeLists.txt", "conanfile.txt", "conanfile.py"],
+    suffixes: [],
+  },
+  haskell: { names: ["cabal.project", "stack.yaml"], suffixes: [".cabal"] },
+  elm: { names: ["elm.json"], suffixes: [] },
+  crystal: { names: ["shard.yml", "shard.lock"], suffixes: [] },
+  nim: { names: ["nim.cfg", "config.nims"], suffixes: [".nimble"] },
+  perl: {
+    names: ["cpanfile", "META.json", "META.yml", "Makefile.PL", "Build.PL"],
+    suffixes: [],
+  },
+  r: { names: ["DESCRIPTION", "renv.lock"], suffixes: [] },
+});
+
+/** Marker file name → ecosystems claiming it, and marker suffix → claiming
+ * ecosystems, both built once from the table. The name index is exported so
+ * the reflection can recognize marker paths carried in ledger events without
+ * rescanning the filesystem. */
+export const MARKERS_BY_NAME = new Map();
+/** Marker suffix → ecosystems claiming it. */
+const MARKERS_BY_SUFFIX = [];
+for (const [ecosystem, markers] of Object.entries(ECOSYSTEM_MARKERS)) {
+  for (const name of markers.names) {
+    const ecosystems = MARKERS_BY_NAME.get(name) || [];
+    ecosystems.push(ecosystem);
+    MARKERS_BY_NAME.set(name, ecosystems);
+  }
+  for (const suffix of markers.suffixes) {
+    MARKERS_BY_SUFFIX.push({ ecosystem, suffix });
+  }
+}
+
+/**
+ * List a directory's entries as plain `{ name, directory }` records, sorted by
+ * name so detection results are deterministic. Callers may inject this helper
+ * to bound or observe the scan in tests.
+ *
+ * @param {string} dirPath Directory to list.
+ * @returns {{name: string, directory: boolean}[]} Sorted entries.
+ */
+function listDirectory(dirPath) {
+  return readdirSync(dirPath, { withFileTypes: true })
+    .map((entry) => ({ name: entry.name, directory: entry.isDirectory() }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Match one directory's entries against the marker index and record the full
+ * paths of every marker found.
+ *
+ * @param {string} dirPath Directory the entries belong to.
+ * @param {{name: string, directory: boolean}[]} entries Directory entries.
+ * @param {Map<string, Set<string>>} markersByEcosystem Accumulator keyed by ecosystem.
+ * @returns {void}
+ */
+function scanEntries(dirPath, entries, markersByEcosystem) {
+  for (const entry of entries) {
+    const nameEcosystems = MARKERS_BY_NAME.get(entry.name);
+    if (nameEcosystems) {
+      for (const ecosystem of nameEcosystems) {
+        const paths = markersByEcosystem.get(ecosystem) || new Set();
+        paths.add(join(dirPath, entry.name));
+        markersByEcosystem.set(ecosystem, paths);
+      }
+    }
+    for (const { ecosystem, suffix } of MARKERS_BY_SUFFIX) {
+      if (entry.name.length > suffix.length && entry.name.endsWith(suffix)) {
+        const paths = markersByEcosystem.get(ecosystem) || new Set();
+        paths.add(join(dirPath, entry.name));
+        markersByEcosystem.set(ecosystem, paths);
+      }
+    }
+  }
+}
+
+/**
+ * Detect ecosystem markers under a project directory without walking the full
+ * tree: the directory itself is inspected, then up to
+ * {@link MAX_SUBDIRS_SCANNED} immediate subdirectories in sorted order. Paths
+ * are built with `node:path`, so `markersOnDisk` carries platform-correct
+ * separators.
+ *
+ * @param {string} projectPath Directory that was scanned, when known.
+ * @param {Object} [hooks] Test hooks.
+ * @param {(dirPath: string) => {name: string, directory: boolean}[]} [hooks.listDir] Directory lister override.
+ * @returns {{markersByEcosystem: Map<string, string[]>, scannedDirectories: number}} Marker paths per ecosystem and the number of directories inspected.
+ */
+export function detectEcosystemMarkers(projectPath, hooks = {}) {
+  const markersByEcosystem = new Map();
+  if (!projectPath || !safeExistsSync(projectPath)) {
+    return { markersByEcosystem, scannedDirectories: 0 };
+  }
+  const listDir = hooks.listDir || listDirectory;
+  let rootEntries;
+  try {
+    rootEntries = listDir(projectPath);
+  } catch {
+    return { markersByEcosystem, scannedDirectories: 0 };
+  }
+  scanEntries(projectPath, rootEntries, markersByEcosystem);
+  const subdirs = rootEntries
+    .filter((entry) => entry.directory)
+    .map((entry) => entry.name)
+    .slice(0, MAX_SUBDIRS_SCANNED);
+  let scannedDirectories = 1;
+  for (const subdir of subdirs) {
+    const subdirPath = join(projectPath, subdir);
+    try {
+      scanEntries(subdirPath, listDir(subdirPath), markersByEcosystem);
+    } catch {
+      continue;
+    }
+    scannedDirectories += 1;
+  }
+  const sorted = new Map(
+    [...markersByEcosystem.entries()].map(([ecosystem, paths]) => [
+      ecosystem,
+      [...paths].sort(),
+    ]),
+  );
+  return { markersByEcosystem: sorted, scannedDirectories };
+}