@cdxgen/cdxgen 13.0.0 → 13.1.0

package/lib/core/deferredExit.js

@@ -0,0 +1,141 @@
+/**
+ * Deferred `fail-on-error` exits for introspected runs.
+ *
+ * `--fail-on-error` promises an operator that a failing dependency extractor
+ * never produces a plausible-but-incomplete BOM, so the extractors exit the
+ * process the moment a build tool fails. Under `--introspect` that exit
+ * destroys the very evidence the run exists to produce: the ledger events
+ * recorded a statement earlier die with the process, `postProcess` never
+ * runs, and neither the BOM nor the fidelity report is written.
+ *
+ * On an introspected run the extractor instead records the failure here and
+ * throws {@link DeferredFailOnError}, which the extractor catches at its
+ * completion point so it still returns everything it collected before the
+ * failure — the incomplete-result fallbacks stay skipped, exactly as
+ * `fail-on-error` demands. The CLI then writes the BOM and both reports and
+ * exits with the dedicated {@link INTROSPECTION_FAILURE_EXIT_CODE} status, so
+ * the exit code still claims "an extractor failed", distinct from the
+ * fidelity gate's 4.
+ *
+ * Without introspection this module is a pass-through to `process.exit(1)`;
+ * the default contract of the flag is unchanged.
+ */
+
+import {
+  isIntrospectionEnabled,
+  LEDGER_EVENT_KINDS,
+  recordLedgerEvent,
+} from "./buildLedger.js";
+import { thoughtLog } from "./logger.js";
+
+/**
+ * Exit status used when an introspected run completes its outputs despite a
+ * `--fail-on-error` extractor failure. Distinct from 1 (generic failure),
+ * 3 (TEA publish failure) and 4 (the introspection fidelity gate).
+ *
+ * @type {number}
+ */
+export const INTROSPECTION_FAILURE_EXIT_CODE = 5;
+
+/**
+ * Control-flow signal thrown by {@link deferFailOnError} on an introspected
+ * run. The extractor that called it must let it unwind to its completion
+ * point, keep everything it collected until then, and rethrow anything else.
+ */
+export class DeferredFailOnError extends Error {
+  /**
+   * @param {string} message Human-readable failure summary.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "DeferredFailOnError";
+  }
+}
+
+/**
+ * The extractor failures deferred so far. Populated only on introspected
+ * runs; the CLI reads it after the BOM and the reports are written to decide
+ * the process exit status.
+ *
+ * @type {Array<{ecosystem: string, tool: string, detail: string, exitCode: number|undefined, command: string|undefined, outputExcerpt: string|undefined}>}
+ */
+const deferredFailures = [];
+
+/**
+ * Test whether an error is the fail-on-error deferral signal.
+ *
+ * @param {unknown} err The caught error.
+ * @returns {boolean} True when the error unwinds a deferred fail-on-error abort.
+ */
+export function isDeferredFailOnError(err) {
+  return err instanceof DeferredFailOnError;
+}
+
+/**
+ * Snapshot of the deferred failures recorded by this run.
+ *
+ * @returns {Array<Object>} Frozen copies of the recorded failures.
+ */
+export function getDeferredFailures() {
+  return deferredFailures.map((failure) => Object.freeze({ ...failure }));
+}
+
+/**
+ * Handle a failing extractor on behalf of a `options.failOnError &&
+ * process.exit(1)` site. Without `fail-on-error` the run continues exactly
+ * as it would have. With the flag and no introspection the process exits 1,
+ * unchanged. On an introspected run the failure is recorded — including one
+ * ledger observation on the ecosystem row the failure cost evidence — and
+ * the deferral signal is thrown so the extractor stops where it is without
+ * taking any incomplete-result fallback.
+ *
+ * @param {Object} options CLI options.
+ * @param {Object} failure What failed, for the operator message and the report.
+ * @param {string} failure.tool The build tool that failed.
+ * @param {string} [failure.ecosystem] The ecosystem the tool serves, so the
+ *   observation lands on the row whose evidence the failure cost.
+ * @param {string} failure.detail One sentence, present tense.
+ * @param {number} [failure.exitCode] The tool's exit status, when known.
+ * @param {string} [failure.command] The redacted command that was attempted.
+ * @param {string} [failure.outputExcerpt] The failed command's combined output,
+ *   when the caller already holds it; the recorder bounds and redacts it.
+ * @returns {void} Never returns on an introspected run; it throws.
+ */
+export function deferFailOnError(options, failure) {
+  if (!options?.failOnError) {
+    return;
+  }
+  const entry = {
+    ecosystem: failure?.ecosystem || "cdxgen",
+    tool: failure?.tool || "unknown",
+    detail: failure?.detail || "the extractor reported a failure",
+    exitCode:
+      typeof failure?.exitCode === "number" ? failure.exitCode : undefined,
+    command: failure?.command,
+    outputExcerpt: failure?.outputExcerpt,
+  };
+  if (!isIntrospectionEnabled(options)) {
+    process.exit(1);
+    // Unreachable in a real run; the explicit return keeps the deferral from
+    // continuing wherever process.exit is instrumented rather than fatal.
+    return;
+  }
+  deferredFailures.push(entry);
+  thoughtLog(
+    `Deferring the fail-on-error exit for ${entry.tool} so the introspection verdict can be produced: ${entry.detail}`,
+  );
+  // A `command.failed` observation on the row the failure cost evidence: it
+  // carries no remediationId, so it reports the deferral without competing
+  // with the degradation the extractor recorded for the same failure, and it
+  // never trips the truncation marker, which keys on `evidence.degraded`
+  // under the reserved recorder ecosystem.
+  recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_FAILED, {
+    ecosystem: entry.ecosystem,
+    tool: entry.tool,
+    exitCode: entry.exitCode,
+    command: entry.command,
+    outputExcerpt: entry.outputExcerpt,
+    detail: `fail-on-error was deferred so the BOM and the report could be written: ${entry.detail}`,
+  });
+  throw new DeferredFailOnError(`${entry.tool}: ${entry.detail}`);
+}

package/lib/core/env.js

@@ -173,9 +173,33 @@ export function getJavaCommand() {
 /** Resolved Python executable command (PYTHON_CMD env var > CONDA_PYTHON_EXE > "python"). */
 export const PYTHON_CMD = getPythonCommand();
 
+/**
+ * Whether an executable of the given name is reachable through PATH.
+ *
+ * @param {string} name Executable name, without a platform extension.
+ * @returns {boolean} True when a PATH entry holds the executable.
+ */
+function isOnPath(name) {
+  const searchPath = readEnvironmentVariable("PATH");
+  if (!searchPath) {
+    return false;
+  }
+  const names =
+    process.platform === "win32" ? [`${name}.exe`, `${name}.bat`] : [name];
+  return searchPath
+    .split(process.platform === "win32" ? ";" : ":")
+    .some((binDir) =>
+      names.some((binName) => binDir && safeExistsSync(join(binDir, binName))),
+    );
+}
+
 /**
  * Returns the Python executable command to use, resolved in priority order:
- * PYTHON_CMD env var > CONDA_PYTHON_EXE env var > "python".
+ * PYTHON_CMD env var > CONDA_PYTHON_EXE env var > "python" > "python3".
+ *
+ * Distributions that ship only a versioned interpreter leave a bare "python"
+ * unresolvable, which would fail every virtualenv this tool creates, so the
+ * versioned name is used when it is the only one PATH offers.
  *
  * @returns {string} Path or name of the Python executable
  */
@@ -185,6 +209,8 @@ export function getPythonCommand() {
     pythonCmd = readEnvironmentVariable("PYTHON_CMD");
   } else if (readEnvironmentVariable("CONDA_PYTHON_EXE")) {
     pythonCmd = readEnvironmentVariable("CONDA_PYTHON_EXE");
+  } else if (!isOnPath("python") && isOnPath("python3")) {
+    pythonCmd = "python3";
   }
   return pythonCmd;
 }
@@ -459,6 +485,39 @@ export const PACKAGE_MANAGER_ALIASES = {
   scala: ["sbt"],
 };
 
+/**
+ * Project-type prefixes that accept a version suffix pinning a JVM build
+ * tool, e.g. `maven3.9.9`, `mvn3.9.9`, `gradle8.14`, `sbt1.10`, or
+ * `scala3.6.4`. Kept alongside the alias map because both describe how CLI
+ * project types map to base types.
+ *
+ * @type {string[]}
+ */
+export const JVM_BUILD_TOOL_TYPE_PREFIXES = [
+  "maven",
+  "mvn",
+  "gradle",
+  "sbt",
+  "scala",
+];
+
+/**
+ * Check whether a project type pins a JVM build tool version, i.e. it starts
+ * with one of the JVM build tool prefixes followed by a digit.
+ *
+ * @param {string} projectType Project type from the CLI
+ * @returns {boolean} True for versioned JVM build tool types.
+ */
+export function isVersionedJvmToolProjectType(projectType) {
+  const pt = `${projectType || ""}`.toLowerCase();
+  for (const prefix of JVM_BUILD_TOOL_TYPE_PREFIXES) {
+    if (pt.startsWith(prefix) && /^\d/.test(pt.slice(prefix.length))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Method to check if a given feature flag is enabled.
  *
@@ -553,6 +612,15 @@ export function hasAnyProjectType(projectTypes, options, defaultStatus = true) {
   ) {
     baseProjectTypes.push("ruby");
   }
+  // Versioned JVM build tool types such as maven3.9.9 or gradle8.14 are java
+  // types with a pinned build tool, so they must dispatch java parsing too.
+  if (
+    options.projectType?.length &&
+    projectTypes.includes("java") &&
+    options.projectType.some((pt) => isVersionedJvmToolProjectType(pt))
+  ) {
+    baseProjectTypes.push("java");
+  }
   const baseExcludeTypes = [];
   for (const abt of Object.keys(PROJECT_TYPE_ALIASES)) {
     if (

package/lib/core/fs.js

@@ -2,12 +2,15 @@ import { Buffer } from "node:buffer";
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import {
+  accessSync,
   copyFileSync,
   createReadStream,
   existsSync,
+  constants as fsConstants,
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   rmSync,
   unlinkSync,
   writeFileSync,
@@ -111,6 +114,26 @@ export function safeExistsSync(filePath) {
   return exists;
 }
 
+/**
+ * Permission-aware check for whether a path exists and carries the executable
+ * bit for the current user. Answers false instead of throwing when the path
+ * is absent, unreadable, or blocked by secure mode.
+ *
+ * @param {string} filePath File path to check.
+ * @returns {boolean} True when the path exists and is executable.
+ */
+export function safeIsExecutableSync(filePath) {
+  if (!safeExistsSync(filePath)) {
+    return false;
+  }
+  try {
+    accessSync(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Permission- and dry-run-aware wrapper around writeFileSync. Records the
  * activity and returns undefined when blocked.
@@ -146,6 +169,43 @@ export function safeWriteSync(filePath, data, options) {
   recordFilesystemActivity("write", filePath, "completed");
 }
 
+/**
+ * Permission-aware wrapper around readFileSync that returns undefined instead
+ * of throwing. Reads are allowed in dry-run mode, so unlike the write wrappers
+ * this only guards secure-mode read permission; the read itself is not recorded
+ * in the activity ledger because inspection of classified paths is already
+ * recorded by safeExistsSync and a read has no side effect to audit.
+ *
+ * @param {string} filePath File path to read.
+ * @param {Object|string} [options] readFileSync options; defaults to UTF-8 text.
+ * @returns {string|Buffer|undefined} File content, or undefined when the path cannot be read.
+ */
+export function safeReadFileSync(filePath, options = "utf-8") {
+  if (!hasReadPermission(filePath)) {
+    if (DEBUG_MODE) {
+      console.log("cdxgen lacks read permission for a requested path.");
+    }
+    const pathMetadata = classifyActivityPath(filePath);
+    if (pathMetadata) {
+      recordPolicyActivity(filePath, {
+        metadata: {
+          classification: pathMetadata.classification,
+          ecosystem: pathMetadata.ecosystem,
+          policyType: "fs.read",
+        },
+        reason: `Denied read of ${pathMetadata.label} ${filePath} due to missing fs.read permission.`,
+        status: "blocked",
+      });
+    }
+    return undefined;
+  }
+  try {
+    return readFileSync(filePath, options);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Safely create a directory without crashing due to a lack of permissions
  *

package/lib/core/logger.js

@@ -1,17 +1,18 @@
 import { Console } from "node:console";
-import fs from "node:fs";
 import process from "node:process";
 
+import {
+  closeAllSyncFileWriters,
+  diagnosticStream,
+  openSyncFileWriter,
+} from "./syncFileWriter.js";
+
+export { diagnosticStream };
+
 // Environment variables here are read with raw `process.env` rather than
 // `readEnvironmentVariable`: that helper lives in activity.js, which imports
 // this module, so routing these through it would form an import cycle.
 
-// Stream contract: human-readable diagnostics default to stderr so stdout
-// carries only the BOM payload. CDXGEN_LOG_STREAM=stdout restores the
-// pre-v13 behaviour for callers that scraped cdxgen's stdout.
-const logStream =
-  process.env.CDXGEN_LOG_STREAM === "stdout" ? process.stdout : process.stderr;
-
 // Custom lightweight colors formatting helper replacing yoctocolors
 const colors = {
   cyanBright: (text) => `\x1b[96m${text}\x1b[39m`,
@@ -25,10 +26,10 @@ export const THINK_MODE =
   process.env.CDXGEN_DEBUG_MODE === "verbose";
 
 const thinkOutput = process.env.CDXGEN_THOUGHT_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_THOUGHT_LOG)
-  : logStream;
+  ? openSyncFileWriter(process.env.CDXGEN_THOUGHT_LOG)
+  : diagnosticStream;
 const thinkErrorOutput = process.env.CDXGEN_THOUGHT_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_THOUGHT_LOG)
+  ? thinkOutput
   : process.stderr;
 const thinkLogger = new Console({
   stdout: thinkOutput,
@@ -44,10 +45,10 @@ export const TRACE_MODE =
   process.env.CDXGEN_DEBUG_MODE === "verbose";
 
 const traceOutput = process.env.CDXGEN_TRACE_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_TRACE_LOG)
-  : logStream;
+  ? openSyncFileWriter(process.env.CDXGEN_TRACE_LOG)
+  : diagnosticStream;
 const traceErrorOutput = process.env.CDXGEN_TRACE_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_TRACE_LOG)
+  ? traceOutput
   : process.stderr;
 const traceLogger = new Console({
   stdout: traceOutput,
@@ -80,14 +81,18 @@ export function thoughtLog(s, args) {
     thinkLogger.log(colorizeText(`${s}`));
   }
 }
+let thoughtBlockClosed = false;
+
 /**
  * Closes the think log group by emitting the closing `</think>` marker.
- * Has no effect if THINK_MODE is not enabled.
+ * Has no effect if THINK_MODE is not enabled, and emits the marker at most
+ * once so an explicit call followed by the exit handler cannot produce two.
  *
  * @returns {void}
  */
 export function thoughtEnd() {
-  if (THINK_MODE) {
+  if (THINK_MODE && !thoughtBlockClosed) {
+    thoughtBlockClosed = true;
     thinkLogger.groupEnd();
     thinkLogger.log(colorizeText("</think>"));
   }
@@ -96,13 +101,40 @@ export function thoughtEnd() {
 function colorizeText(s) {
   // Only colorize for an interactive terminal stream; piped/CI/file output
   // stays free of escape bytes so the diagnostic stream is grep-safe.
-  if (process.env.CDXGEN_THOUGHT_LOG || !logStream.isTTY) {
+  if (process.env.CDXGEN_THOUGHT_LOG || !diagnosticStream.isTTY) {
     return s;
   }
   s = s.replace(/(\d+)/g, colors.cyanBright("$1"));
   return colors.dim(s);
 }
 
+// Fields serialized for each trace type. The allow-list is per-type because a
+// single shared list either drops the fields a type exists to carry or leaks
+// unbounded caller objects into the stream: `activity` and `phase` records
+// carry no field in common with `spawn` and `http`.
+const TRACE_FIELDS = {
+  activity: [
+    "identifier",
+    "kind",
+    "status",
+    "target",
+    "reason",
+    "networkIntent",
+    "command",
+    "cwd",
+  ],
+  phase: ["phase", "state", "detail", "note", "done", "total", "elapsedMs"],
+};
+
+const DEFAULT_TRACE_FIELDS = [
+  "command",
+  "cwd",
+  "protocol",
+  "host",
+  "path",
+  "pathname",
+];
+
 /**
  * Log trace messages
  *
@@ -123,15 +155,10 @@ export function traceLog(traceType, args) {
     message.type = traceType;
   }
   if (args) {
-    for (const k of [
-      "command",
-      "cwd",
-      "protocol",
-      "host",
-      "path",
-      "pathname",
-    ]) {
-      if (args[k]) {
+    for (const k of TRACE_FIELDS[traceType] || DEFAULT_TRACE_FIELDS) {
+      // Numeric progress counters are meaningful at zero, so presence is
+      // tested rather than truthiness.
+      if (args[k] !== undefined && args[k] !== null && args[k] !== "") {
         message[k] = args[k];
       }
     }
@@ -140,3 +167,27 @@ export function traceLog(traceType, args) {
     traceLogger.log(JSON.stringify(message, null, null));
   }
 }
+
+let logStreamsClosed = false;
+
+/**
+ * Terminate the think block and close the log file descriptors.
+ *
+ * Readers tail these files as a live feed, so a run that ends without the
+ * closing `</think>` marker leaves the consumer holding an unterminated block.
+ * Registered on process exit and safe to call more than once.
+ *
+ * @returns {void}
+ */
+export function closeLogStreams() {
+  if (logStreamsClosed) {
+    return;
+  }
+  logStreamsClosed = true;
+  thoughtEnd();
+  closeAllSyncFileWriters();
+}
+
+// The writers are synchronous, so this handler only has to emit the terminator
+// and release the descriptors — work that is legal during `exit`.
+process.on("exit", closeLogStreams);

package/lib/core/severity.js

@@ -0,0 +1,16 @@
+/**
+ * Shared severity ordering for finding and confidence ladders.
+ *
+ * Lives in the core layer so modules below the audit layer can order labels
+ * such as `low`/`medium`/`high` without importing the audit package; the audit
+ * scoring module re-exports this constant under its historical name.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const SEVERITY_ORDER = Object.freeze({
+  none: -1,
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+});

package/lib/core/syncFileWriter.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import process from "node:process";
+import { Writable } from "node:stream";
+import { isMainThread } from "node:worker_threads";
+
+// Stream contract: human-readable diagnostics default to stderr so stdout
+// carries only the BOM payload. CDXGEN_LOG_STREAM=stdout restores the
+// pre-v13 behaviour for callers that scraped cdxgen's stdout.
+
+/**
+ * The stream every human-readable diagnostic is written to.
+ *
+ * Also the fallback destination of {@link openSyncFileWriter} when a log path
+ * cannot be opened, so an unwritable path keeps the records visible somewhere
+ * instead of taking the run down.
+ *
+ * @type {NodeJS.WritableStream}
+ */
+export const diagnosticStream =
+  process.env.CDXGEN_LOG_STREAM === "stdout" ? process.stdout : process.stderr;
+
+// Log files are written synchronously rather than through
+// `fs.createWriteStream`. A write stream buffers, so anything still queued when
+// the process exits is lost, leaving readers that tail these files a truncated
+// log. Writing through one shared descriptor per path also keeps concurrent
+// writers from interleaving at independent file offsets.
+const syncFileWriters = new Map();
+
+/**
+ * Open a synchronous writer for a log file path, or return the writer already
+ * open for that path.
+ *
+ * `Console` requires a real stream, so this is a `Writable` whose `_write`
+ * completes synchronously: bytes reach the descriptor as each record is
+ * written, and nothing is left queued for an event loop turn that a process
+ * exit may never take.
+ *
+ * @param {string} filePath Destination path
+ * @param {NodeJS.WritableStream|null} [fallbackStream] Stream returned when the path cannot be opened; defaults to the diagnostic stream. Pass `null` to get `undefined` instead, for callers that must never let data records spill into a diagnostic stream.
+ * @returns {Writable|NodeJS.WritableStream|undefined} Writer for the path, the fallback stream, or `undefined` when the path cannot be opened and no fallback was requested
+ */
+export function openSyncFileWriter(
+  filePath,
+  fallbackStream = diagnosticStream,
+) {
+  const existing = syncFileWriters.get(filePath);
+  if (existing) {
+    return existing;
+  }
+  let fd;
+  try {
+    // Worker threads open the same path through their own instance of this
+    // module, so the descriptor is opened in append mode: O_APPEND lands every
+    // write at the end of the file no matter how many writers share it, where
+    // a truncating open gives each writer its own offset and they punch holes
+    // through each other's records. The main thread truncates once so a run
+    // still starts from an empty log.
+    if (isMainThread) {
+      try {
+        fs.truncateSync(filePath, 0);
+      } catch {
+        // No file yet: the append open below creates it.
+      }
+    }
+    fd = fs.openSync(filePath, "a");
+  } catch {
+    return fallbackStream ?? undefined;
+  }
+  const writer = new Writable({
+    write(chunk, _encoding, callback) {
+      if (fd !== undefined) {
+        try {
+          fs.writeSync(fd, chunk);
+        } catch {
+          // A full disk or a revoked descriptor must not abort BOM generation.
+        }
+      }
+      callback();
+    },
+  });
+  writer.closeSync = () => {
+    if (fd === undefined) {
+      return;
+    }
+    try {
+      fs.closeSync(fd);
+    } finally {
+      fd = undefined;
+      syncFileWriters.delete(filePath);
+    }
+  };
+  syncFileWriters.set(filePath, writer);
+  return writer;
+}
+
+/**
+ * Close every synchronous file writer opened by {@link openSyncFileWriter}.
+ * Safe to call more than once and after individual writers were closed.
+ *
+ * @returns {void}
+ */
+export function closeAllSyncFileWriters() {
+  for (const writer of [...syncFileWriters.values()]) {
+    writer.closeSync();
+  }
+}