@cdxgen/cdxgen 13.0.1 → 13.2.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;
 }
@@ -230,6 +256,19 @@ if (readEnvironmentVariable("CARGO_CMD")) {
   CARGO_CMD = readEnvironmentVariable("CARGO_CMD");
 }
 
+/**
+ * Target triple the cargo resolve graph is filtered to, so that a
+ * cross-compiled project can be described for the triple it ships on rather
+ * than for the union of every triple its lock file covers.
+ *
+ * `CDXGEN_CARGO_TARGET` is cdxgen's own name for it; `CARGO_BUILD_TARGET` is
+ * cargo's standard variable, which a cross-compiling build already sets.
+ */
+export const CARGO_TARGET =
+  readEnvironmentVariable("CDXGEN_CARGO_TARGET") ||
+  readEnvironmentVariable("CARGO_BUILD_TARGET") ||
+  undefined;
+
 /** Resolved Clojure CLI executable command (CLJ_CMD env var, or "clj"). */
 export let CLJ_CMD = "clj";
 if (readEnvironmentVariable("CLJ_CMD")) {
@@ -281,6 +320,7 @@ export const PROJECT_TYPE_ALIASES = {
     "java24",
     "java25",
     "java26",
+    "java27",
     "groovy",
     "kotlin",
     "kt",
@@ -313,6 +353,9 @@ export const PROJECT_TYPE_ALIASES = {
     "nodejs20",
     "nodejs22",
     "nodejs23",
+    "nodejs24",
+    "nodejs25",
+    "nodejs26",
     "node",
     "node8",
     "node10",
@@ -323,11 +366,16 @@ export const PROJECT_TYPE_ALIASES = {
     "node20",
     "node22",
     "node23",
+    "node24",
+    "node25",
+    "node26",
     "js",
     "javascript",
     "typescript",
     "ts",
     "tsx",
+    "svelte",
+    "sveltekit",
     "yarn",
     "rush",
     "bun",
@@ -335,6 +383,7 @@ export const PROJECT_TYPE_ALIASES = {
   ],
   mcp: ["mcp"],
   "ai-skill": ["ai-skill", "skill", "skills"],
+  agentic: ["agentic", "agentic-cli", "ai-tools", "ai-cli"],
   py: [
     "py",
     "python",
@@ -346,6 +395,8 @@ export const PROJECT_TYPE_ALIASES = {
     "python311",
     "python312",
     "python313",
+    "python314",
+    "python315",
     "pixi",
     "pip",
     "poetry",
@@ -372,6 +423,8 @@ export const PROJECT_TYPE_ALIASES = {
     "dotnet7",
     "dotnet8",
     "dotnet9",
+    "dotnet10",
+    "dotnet11",
     "dotnet-framework",
     "dotnet-framework47",
     "dotnet-framework48",
@@ -391,8 +444,19 @@ export const PROJECT_TYPE_ALIASES = {
     "hmiproj",
   ],
   dart: ["dart", "flutter", "pub"],
-  haskell: ["haskell", "hackage", "cabal"],
+  haskell: ["haskell", "hackage", "cabal", "stack", "stackage"],
   elixir: ["elixir", "hex", "mix"],
+  erlang: ["erlang", "rebar", "rebar3"],
+  julia: ["julia"],
+  r: ["r", "cran", "renv"],
+  ocaml: ["ocaml", "opam", "dune"],
+  elm: ["elm"],
+  crystal: ["crystal", "shards"],
+  nim: ["nim", "nimble"],
+  lua: ["lua", "luarocks"],
+  perl: ["perl", "cpan", "carton", "cpanfile"],
+  spack: ["spack"],
+  terraform: ["terraform", "opentofu", "tf"],
   c: ["c", "cpp", "c++", "conan", "collider"],
   clojure: ["clojure", "edn", "clj", "leiningen"],
   github: ["github", "actions"],
@@ -459,6 +523,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 +650,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,31 +1,18 @@
 import { Console } from "node:console";
-import fs from "node:fs";
 import process from "node:process";
-import { Writable } from "node:stream";
-import { isMainThread } from "node:worker_threads";
+
+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;
-
-/**
- * The stream every human-readable diagnostic is written to.
- *
- * Exported so that the live region and the table renderer resolve the same
- * destination as the loggers do. A caller that sets `CDXGEN_LOG_STREAM=stdout`
- * gets the pre-v13 behaviour for all of it, not just for the thought and trace
- * logs.
- *
- * @type {NodeJS.WritableStream}
- */
-export const diagnosticStream = logStream;
-
 // Custom lightweight colors formatting helper replacing yoctocolors
 const colors = {
   cyanBright: (text) => `\x1b[96m${text}\x1b[39m`,
@@ -38,81 +25,9 @@ export const THINK_MODE =
   ["true", "1"].includes(process.env.CDXGEN_THINK_MODE) ||
   process.env.CDXGEN_DEBUG_MODE === "verbose";
 
-// 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 with no closing `</think>` marker. Writing through one shared descriptor
-// per path also keeps the two Console channels from interleaving at
-// independent file offsets.
-const syncFileWriters = new Map();
-
-/**
- * Open a synchronous writer for a log file path.
- *
- * `Console` requires a real stream, so this is a `Writable` whose `_write`
- * completes synchronously: bytes reach the descriptor as each record is
- * logged, and nothing is left queued for an event loop turn that a process
- * exit may never take.
- *
- * @param {string} filePath Destination path
- * @returns {Writable} Writer, or the diagnostic stream when the path is unwritable
- */
-function openSyncFileWriter(filePath) {
-  const existing = syncFileWriters.get(filePath);
-  if (existing) {
-    return existing;
-  }
-  let fd;
-  try {
-    // Worker threads log to 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 {
-    // An unwritable path must not take the whole run down: fall back to the
-    // diagnostic stream so the records stay visible somewhere.
-    return logStream;
-  }
-  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;
-}
-
 const thinkOutput = process.env.CDXGEN_THOUGHT_LOG
   ? openSyncFileWriter(process.env.CDXGEN_THOUGHT_LOG)
-  : logStream;
+  : diagnosticStream;
 const thinkErrorOutput = process.env.CDXGEN_THOUGHT_LOG
   ? thinkOutput
   : process.stderr;
@@ -131,7 +46,7 @@ export const TRACE_MODE =
 
 const traceOutput = process.env.CDXGEN_TRACE_LOG
   ? openSyncFileWriter(process.env.CDXGEN_TRACE_LOG)
-  : logStream;
+  : diagnosticStream;
 const traceErrorOutput = process.env.CDXGEN_TRACE_LOG
   ? traceOutput
   : process.stderr;
@@ -186,7 +101,7 @@ 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"));
@@ -270,9 +185,7 @@ export function closeLogStreams() {
   }
   logStreamsClosed = true;
   thoughtEnd();
-  for (const writer of [...syncFileWriters.values()]) {
-    writer.closeSync();
-  }
+  closeAllSyncFileWriters();
 }
 
 // The writers are synchronous, so this handler only has to emit the terminator

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();
+  }
+}