@cdxgen/cdxgen 13.0.1 → 13.1.0

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

@@ -0,0 +1,320 @@
+/**
+ * BOM mutations that carry the introspection verdict inside the document:
+ * eight metadata properties and a block of document-level annotations.
+ *
+ * Sidecar report files get lost; the BOM travels. A consumer who receives
+ * only the BOM still learns how much to trust it from the metadata properties,
+ * and the annotations carry one entry per remediation the loop should act on.
+ * No component or dependency is touched.
+ *
+ * Both mutations are replace-by-name: a document that was already introspected
+ * (a BOM enriched again after an evidence pass) loses its previous
+ * introspection state and gains a fresh one, so the verdict always describes
+ * the final document.
+ */
+
+import {
+  buildDocumentAnnotation,
+  evidenceProperties,
+} from "../annotationBuilder.js";
+import { FORMULATION_RUN_ID_PROPERTY } from "./formulationEvidence.js";
+import { overallAssessment } from "./report.js";
+
+/**
+ * Version of the introspection BOM surface. Matches the JSON report's
+ * schemaVersion so the two stay comparable.
+ *
+ * @type {string}
+ */
+export const INTROSPECTION_SCHEMA_VERSION = "1.1";
+
+/**
+ * Namespace of every property and annotation entry this module emits.
+ *
+ * @type {string}
+ */
+export const INTROSPECTION_PROPERTY_PREFIX = "cdx:introspection";
+
+/**
+ * The metadata properties that summarize the verdict, in emission order. The
+ * overall tier and confidence are omitted when the run produced no scored row
+ * (nothing was graded, so no verdict is claimed); per-ecosystem rows cover the
+ * scored ecosystems only, since unsupported ones have neither a tier nor a
+ * score.
+ *
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @returns {{name: string, value: string}[]} Metadata property entries.
+ */
+export function introspectionMetadataProperties(reflection, scored) {
+  const assessment = overallAssessment(scored);
+  const properties = [
+    {
+      name: `${INTROSPECTION_PROPERTY_PREFIX}:schemaVersion`,
+      value: INTROSPECTION_SCHEMA_VERSION,
+    },
+  ];
+  if (assessment.tier) {
+    properties.push({
+      name: `${INTROSPECTION_PROPERTY_PREFIX}:tier`,
+      value: assessment.tier,
+    });
+  }
+  properties.push({
+    name: `${INTROSPECTION_PROPERTY_PREFIX}:score`,
+    value: String(scored?.overallScore ?? 100),
+  });
+  if (assessment.confidence) {
+    properties.push({
+      name: `${INTROSPECTION_PROPERTY_PREFIX}:confidence`,
+      value: assessment.confidence,
+    });
+  }
+  properties.push({
+    name: `${INTROSPECTION_PROPERTY_PREFIX}:ledgerComplete`,
+    value: String(reflection?.ledgerComplete !== false),
+  });
+  for (const row of sortedScoredRows(scored)) {
+    properties.push({
+      name: `${INTROSPECTION_PROPERTY_PREFIX}:ecosystem:${row.ecosystem}:tier`,
+      value: `${row.tier}`,
+    });
+    properties.push({
+      name: `${INTROSPECTION_PROPERTY_PREFIX}:ecosystem:${row.ecosystem}:score`,
+      value: String(row.score),
+    });
+  }
+  properties.push({
+    name: `${INTROSPECTION_PROPERTY_PREFIX}:remediationCount`,
+    value: String(actionableRemediations(scored).length),
+  });
+  return properties;
+}
+
+/**
+ * The annotation describing the run as a whole. Its structured facts are the
+ * metadata properties, so the summary is readable without the rest of the
+ * document.
+ *
+ * @param {Object} bomJson CycloneDX BOM the annotation describes.
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @returns {Object|undefined} The summary annotation, or undefined without a cdxgen annotator.
+ */
+function summaryAnnotation(bomJson, reflection, scored) {
+  const assessment = overallAssessment(scored);
+  const remediationCount = (
+    Array.isArray(scored?.remediations) ? scored.remediations : []
+  ).length;
+  // Annotation text is escaped as markdown before it reaches the BOM, so the
+  // summary is phrased without brackets or pipes that would survive as
+  // backslashes in the rendered document.
+  const message =
+    `Build introspection: overall tier ${assessment.tier ?? "ungraded"}, ` +
+    `score ${scored?.overallScore ?? 100} of 100, ` +
+    `confidence ${assessment.confidence ?? "not available"}. ` +
+    `${remediationCount} remediation${remediationCount === 1 ? "" : "s"} ranked.`;
+  return buildDocumentAnnotation({
+    bomJson,
+    message,
+    properties: introspectionMetadataProperties(reflection, scored),
+  });
+}
+
+/**
+ * One annotation per non-blocked remediation, in ranked order. Blocked
+ * entries are constraints of the environment rather than work the loop can
+ * do, so they stay in the report files and out of the document. A remediation
+ * that subsumes other rules names them, so nothing the run detected goes
+ * unreported.
+ *
+ * @param {Object} bomJson CycloneDX BOM the annotations describe.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @returns {Object[]} Remediation annotations.
+ */
+function remediationAnnotations(bomJson, scored) {
+  const tierByEcosystem = new Map(
+    sortedScoredRows(scored).map((row) => [row.ecosystem, row.tier]),
+  );
+  const annotations = [];
+  for (const entry of actionableRemediations(scored)) {
+    const properties = [
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:remediationId`,
+        value: `${entry.remediationId}`,
+      },
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:ecosystem`,
+        value: `${entry.ecosystem}`,
+      },
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:currentTier`,
+        value: `${tierByEcosystem.get(entry.ecosystem) || entry.targetTier}`,
+      },
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:targetTier`,
+        value: `${entry.targetTier}`,
+      },
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:expectedGain`,
+        value: Number(entry.expectedGain ?? 0).toFixed(2),
+      },
+      {
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:confidence`,
+        value: `${entry.confidence}`,
+      },
+    ];
+    const rules = Array.isArray(entry.verify?.rules) ? entry.verify.rules : [];
+    if (rules.length) {
+      properties.push({
+        name: `${INTROSPECTION_PROPERTY_PREFIX}:verify:rules`,
+        value: rules.join(","),
+      });
+    }
+    const evidence = { source: entry.source };
+    if (entry.impact) {
+      evidence.impact = entry.impact;
+    }
+    if (entry.severity) {
+      evidence.severity = entry.severity;
+    }
+    if (Number.isFinite(entry.evidenceCount)) {
+      evidence.events = entry.evidenceCount;
+    }
+    if (Array.isArray(entry.subsumes) && entry.subsumes.length) {
+      evidence.subsumes = entry.subsumes;
+    }
+    if (
+      Array.isArray(entry.verify?.eventsCleared) &&
+      entry.verify.eventsCleared.length
+    ) {
+      evidence.eventsCleared = entry.verify.eventsCleared;
+    }
+    properties.push(
+      ...evidenceProperties(INTROSPECTION_PROPERTY_PREFIX, evidence),
+    );
+    const annotation = buildDocumentAnnotation({
+      bomJson,
+      message: `${entry.summary || entry.remediationId}`,
+      properties,
+    });
+    if (annotation) {
+      annotations.push(annotation);
+    }
+  }
+  return annotations;
+}
+
+/**
+ * Attach the introspection verdict to the document: metadata properties plus
+ * the summary and remediation annotations. Any introspection state left on the
+ * document by a previous pass is removed first, so enrichment flows that run
+ * post-processing twice leave exactly one verdict.
+ *
+ * @param {Object} bomJson CycloneDX BOM, mutated in place.
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @param {Object} [guards] Emission guards.
+ * @param {boolean} [guards.annotations] False skips the annotations, for documents at a spec version that predates them.
+ * @returns {Object} The mutated BOM.
+ */
+export function applyIntrospectionToBom(
+  bomJson,
+  reflection,
+  scored,
+  guards = {},
+) {
+  if (!bomJson?.metadata) {
+    return bomJson;
+  }
+  const freshProperties = introspectionMetadataProperties(reflection, scored);
+  const retainedProperties = (
+    Array.isArray(bomJson.metadata.properties)
+      ? bomJson.metadata.properties
+      : []
+  ).filter(
+    (property) =>
+      !`${property?.name || ""}`.startsWith(INTROSPECTION_PROPERTY_PREFIX),
+  );
+  bomJson.metadata.properties = [...retainedProperties, ...freshProperties];
+  if (guards.annotations === false) {
+    return bomJson;
+  }
+  const retainedAnnotations = (
+    Array.isArray(bomJson.annotations) ? bomJson.annotations : []
+  ).filter(
+    (annotation) =>
+      !`${annotation?.text || ""}`.includes(INTROSPECTION_PROPERTY_PREFIX),
+  );
+  const freshAnnotations = [
+    summaryAnnotation(bomJson, reflection, scored),
+    ...remediationAnnotations(bomJson, scored),
+  ].filter(Boolean);
+  if (freshAnnotations.length) {
+    bomJson.annotations = [...retainedAnnotations, ...freshAnnotations];
+  }
+  return bomJson;
+}
+
+/** Scored rows in ecosystem order. */
+function sortedScoredRows(scored) {
+  return [...(Array.isArray(scored?.ecosystems) ? scored.ecosystems : [])]
+    .filter((row) => row?.ecosystem)
+    .sort((a, b) => `${a.ecosystem}`.localeCompare(`${b.ecosystem}`));
+}
+
+/** Remediations the loop can act on, in ranked order. */
+function actionableRemediations(scored) {
+  return (
+    Array.isArray(scored?.remediations) ? scored.remediations : []
+  ).filter((entry) => entry?.blocked !== true);
+}
+
+/**
+ * Stamp every formulation workflow with the id of the run that reflected over
+ * the document, so a later consumer of the BOM can tell a formulation record
+ * this run generated from one that arrived with a foreign BOM. The stamp is
+ * replace-by-name, matching how the rest of the verdict mutates the
+ * document: a BOM enriched twice keeps only the latest run's id.
+ *
+ * @param {Object} bomJson CycloneDX BOM, mutated in place.
+ * @param {string} runId Run id of the introspection pass.
+ * @returns {Object} The mutated BOM.
+ */
+export function applyFormulationRunIdMarker(bomJson, runId) {
+  if (!bomJson || !runId) {
+    return bomJson;
+  }
+  for (const entry of Array.isArray(bomJson.formulation)
+    ? bomJson.formulation
+    : []) {
+    for (const workflow of Array.isArray(entry?.workflows)
+      ? entry.workflows
+      : []) {
+      const retained = (
+        Array.isArray(workflow.properties) ? workflow.properties : []
+      ).filter((property) => property?.name !== FORMULATION_RUN_ID_PROPERTY);
+      workflow.properties = [
+        ...retained,
+        { name: FORMULATION_RUN_ID_PROPERTY, value: runId },
+      ];
+    }
+  }
+  return bomJson;
+}
+
+/**
+ * Whether a BOM already carries an introspection verdict.
+ *
+ * Evidence collection re-processes a finished BOM through a fresh wrapper, so
+ * the document itself is the only marker that survives between passes.
+ *
+ * @param {Object} bomJson CycloneDX BOM.
+ * @returns {boolean} True when the BOM was already introspected.
+ */
+export function hasIntrospectionVerdict(bomJson) {
+  return (bomJson?.metadata?.properties || []).some(
+    (property) =>
+      property?.name === `${INTROSPECTION_PROPERTY_PREFIX}:schemaVersion`,
+  );
+}

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

@@ -0,0 +1,293 @@
+/**
+ * Command-facts collector for command shaping.
+ *
+ * Gathers, once per run and cached, the project facts the command resolver
+ * consumes: which maven and gradle wrapper scripts the project root carries,
+ * which Python manager owns its lock files, and which npm client the project
+ * names or locks. Detection is filesystem reads only — existence and, for
+ * the platform's own shell scripts, the executable bit. Nothing here spawns
+ * a process: whether a wrapper actually runs is a question the run itself
+ * answers elsewhere, and shaping that cannot know says so through the
+ * resolver's fallbacks.
+ */
+
+import { join } from "node:path";
+
+import {
+  safeExistsSync,
+  safeIsExecutableSync,
+  safeReadFileSync,
+} from "../../../core/fs.js";
+
+/**
+ * The POSIX wrapper scripts whose executable bit is meaningful, mapped to
+ * the fact names the resolver reads.
+ *
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const POSIX_WRAPPERS = [
+  ["mvnw", "mvnw"],
+  ["gradlew", "gradlew"],
+  ["composer.phar", "composerPhar"],
+];
+
+/**
+ * The Windows wrapper batches whose presence is the practical usability
+ * test, mapped to the fact names the resolver reads.
+ *
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const WINDOWS_WRAPPERS = [
+  ["mvnw.cmd", "mvnwCmd"],
+  ["gradlew.bat", "gradlewBat"],
+];
+
+/**
+ * Python managers detected through the lock file that owns them. Poetry is
+ * completed by the build backend its pyproject.toml declares, because a
+ * stray poetry.lock alone does not make a project poetry-managed.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const MANAGER_LOCK_FILES = Object.freeze({
+  "uv.lock": "uv",
+  "poetry.lock": "poetry",
+  "pdm.lock": "pdm",
+  "Pipfile.lock": "pipenv",
+});
+
+/**
+ * pyproject.toml build backends that settle which competing manager governs
+ * the project.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const BACKEND_MANAGERS = Object.freeze({
+  "poetry.core.masonry.api": "poetry",
+  "pdm.backend": "pdm",
+  "pdm.pep517.api": "pdm",
+  uv: "uv",
+  uv_build: "uv",
+});
+
+/** Facts gathered so far, keyed by the project root they describe. */
+const factsCache = new Map();
+
+/**
+ * Whether a path exists and, on POSIX, carries the executable bit for the
+ * current user. On Windows every readable file is runnable, so existence is
+ * the whole answer.
+ *
+ * @param {string} filePath Path to check.
+ * @param {boolean} checkExecutable True when the executable bit matters.
+ * @returns {boolean} Usability of the path as an executable.
+ */
+function isUsableExecutable(filePath, checkExecutable) {
+  return checkExecutable
+    ? safeIsExecutableSync(filePath)
+    : safeExistsSync(filePath);
+}
+
+/**
+ * Read the build backend a pyproject.toml declares, from its
+ * `[build-system]` section only, so a mention elsewhere cannot answer.
+ *
+ * @param {string} pyprojectPath Path to pyproject.toml.
+ * @returns {string|undefined} The declared backend, when present.
+ */
+function declaredBuildBackend(pyprojectPath) {
+  let content;
+  try {
+    content = safeReadFileSync(pyprojectPath, "utf-8");
+  } catch {
+    return undefined;
+  }
+  let inBuildSystem = false;
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[")) {
+      inBuildSystem = trimmed === "[build-system]";
+      continue;
+    }
+    if (!inBuildSystem || !trimmed.startsWith("build-backend")) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) {
+      return undefined;
+    }
+    return trimmed
+      .slice(eq + 1)
+      .trim()
+      .replace(/^["']|["']$/g, "")
+      .trim();
+  }
+  return undefined;
+}
+
+/**
+ * Whether a pyproject.toml declares a `[tool.<name>]` section, so a
+ * manager's own configuration marks the project as its own.
+ *
+ * @param {string} pyprojectPath Path to pyproject.toml.
+ * @param {string} toolName Tool section name, e.g. `poetry`.
+ * @returns {boolean} True when the section is present.
+ */
+function hasToolSection(pyprojectPath, toolName) {
+  let content;
+  try {
+    content = safeReadFileSync(pyprojectPath, "utf-8");
+  } catch {
+    return false;
+  }
+  const section = `[tool.${toolName}]`;
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === section || trimmed.startsWith(`${section.slice(0, -1)}.`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Detect the Python manager in play at a project root: the manager whose
+ * lock file is present, with poetry confirmed by the `[tool.poetry]`
+ * section its pyproject.toml declares. Two competing managers are settled
+ * by the declared build backend; when it settles nothing, both candidates
+ * travel in the facts so the report can ask instead of guessing.
+ *
+ * @param {string} projectRoot Directory to inspect.
+ * @returns {{manager: string|undefined, candidates: string[]}} The manager in play and every candidate detected.
+ */
+function detectPythonManager(projectRoot) {
+  const pyprojectPath = join(projectRoot, "pyproject.toml");
+  const hasPyproject = safeExistsSync(pyprojectPath);
+  const candidates = [];
+  for (const [lockName, manager] of Object.entries(MANAGER_LOCK_FILES)) {
+    if (!safeExistsSync(join(projectRoot, lockName))) {
+      continue;
+    }
+    if (manager === "poetry") {
+      if (!hasPyproject || !hasToolSection(pyprojectPath, "poetry")) {
+        continue;
+      }
+    }
+    if (!candidates.includes(manager)) {
+      candidates.push(manager);
+    }
+  }
+  const ordered = candidates.sort();
+  if (ordered.length <= 1) {
+    return { manager: ordered[0], candidates: ordered };
+  }
+  const backend = hasPyproject
+    ? declaredBuildBackend(pyprojectPath)
+    : undefined;
+  const settled = backend ? BACKEND_MANAGERS[backend] : undefined;
+  if (settled && ordered.includes(settled)) {
+    return { manager: settled, candidates: ordered };
+  }
+  return { manager: undefined, candidates: ordered };
+}
+
+/**
+ * Detect the npm client a project root uses: the `packageManager` field of
+ * its package.json when the project names one, else the lock file present,
+ * else npm.
+ *
+ * @param {string} projectRoot Directory to inspect.
+ * @returns {string} The npm client name.
+ */
+function detectNpmClient(projectRoot) {
+  const packageJsonPath = join(projectRoot, "package.json");
+  if (safeExistsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(
+        safeReadFileSync(packageJsonPath, "utf-8"),
+      );
+      const pinned = `${packageJson?.packageManager || ""}`;
+      const at = pinned.indexOf("@");
+      const name = (at > 0 ? pinned.slice(0, at) : pinned).trim();
+      if (name) {
+        return name;
+      }
+    } catch {
+      // An unreadable package.json leaves the lock files to answer.
+    }
+  }
+  const lockClients = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lockb", "bun"],
+    ["bun.lock", "bun"],
+    ["deno.lock", "deno"],
+    ["package-lock.json", "npm"],
+  ];
+  for (const [lockName, client] of lockClients) {
+    if (safeExistsSync(join(projectRoot, lockName))) {
+      return client;
+    }
+  }
+  return "npm";
+}
+
+/**
+ * Gather the command-shaping facts for a project root. The result is cached
+ * per root, so repeated scoring passes over the same project read the
+ * filesystem once.
+ *
+ * @param {string} projectRoot Directory that was scanned.
+ * @param {Object} [options] Test hooks.
+ * @param {"posix"|"windows"} [options.platform] Platform override; defaults to the runtime platform.
+ * @returns {import("./shapeCommand.js").CommandFacts} Facts for the resolver.
+ */
+export function collectCommandFacts(projectRoot, options = {}) {
+  const platform =
+    options.platform ||
+    (globalThis.process?.platform === "win32" ? "windows" : "posix");
+  const cacheKey = `${platform}\n${projectRoot || ""}`;
+  const cached = factsCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const facts = {
+    projectRoot: projectRoot || "",
+    platform,
+    wrappers: {},
+    pythonManager: undefined,
+    pythonManagerCandidates: [],
+    npmClient: "npm",
+  };
+  if (projectRoot && safeExistsSync(projectRoot)) {
+    const checkExecutable = platform === "posix";
+    for (const [fileName, factName] of POSIX_WRAPPERS) {
+      const wrapperPath = join(projectRoot, fileName);
+      if (isUsableExecutable(wrapperPath, checkExecutable)) {
+        facts.wrappers[factName] = true;
+      } else if (safeExistsSync(wrapperPath)) {
+        facts.wrappers[`${factName}Inexecutable`] = true;
+      }
+    }
+    for (const [fileName, factName] of WINDOWS_WRAPPERS) {
+      if (isUsableExecutable(join(projectRoot, fileName), false)) {
+        facts.wrappers[factName] = true;
+      }
+    }
+    const python = detectPythonManager(projectRoot);
+    facts.pythonManager = python.manager;
+    facts.pythonManagerCandidates = python.candidates;
+    facts.npmClient = detectNpmClient(projectRoot);
+  }
+  factsCache.set(cacheKey, facts);
+  return facts;
+}
+
+/**
+ * Forget the gathered facts. Test hook; a production run gathers once.
+ *
+ * @returns {void}
+ */
+export function clearCommandFactsCache() {
+  factsCache.clear();
+}