@cdxgen/cdxgen 13.3.0 → 13.5.0

package/lib/inventory/atomUtils.js

@@ -6,7 +6,13 @@ import {
   statSync,
 } from "node:fs";
 import { tmpdir, totalmem } from "node:os";
-import { delimiter as _delimiter, dirname, join, resolve } from "node:path";
+import {
+  delimiter as _delimiter,
+  basename,
+  dirname,
+  join,
+  resolve,
+} from "node:path";
 import process from "node:process";
 
 import {
@@ -23,7 +29,10 @@ import {
 } from "../core/fs.js";
 import { TRACE_MODE } from "../core/logger.js";
 import { dirNameStr, isWin } from "../core/paths.js";
+import { formatDuration, reapProcessTree } from "../core/processTree.js";
+import { isProjectToolingAllowed } from "../core/projectTooling.js";
 import { readJsonFile } from "../parsers/largeJson.js";
+import { cmakeBuildDirCandidates } from "./cmakeBuildDirs.js";
 
 const ASTGEN_DEFAULT_IGNORE_DIRS = [
   "venv",
@@ -83,9 +92,6 @@ const ATOM_C_LANGUAGES = new Set([
 
 const COMPILE_COMMANDS_FILE = "compile_commands.json";
 
-/** Build directories, under the scan root, searched for a compilation database. */
-const COMPILE_COMMANDS_BUILD_DIRS = ["build", "out", "builddir"];
-
 /**
  * Characters a Windows shell command line would interpret: `&`, `|`, `<` and
  * `>` chain or redirect commands, `%` expands variables even inside quotes,
@@ -117,9 +123,12 @@ function compileCommandsIn(dir) {
  * language its build uses.
  *
  * An explicit `options.compileCommands` (a file, or a directory holding one
- * directly or under `build/`) wins. Otherwise the scan root, `build/`, `out/`,
- * `builddir/`, `cmake-build-*` and the directory of `options.cmakeCache` are
- * searched. A database can come with the code it describes, and atom asks the
+ * directly or under `build/`) wins. Otherwise the scan root and the project's
+ * build directories are searched: the directory of `options.cmakeCache`, the
+ * build directories of its CMake presets, and the conventional `build`,
+ * `out`, `builddir` and `cmake-build-` directories (see
+ * `cmakeBuildDirCandidates`). A database can come with the code it describes,
+ * and atom asks the
  * GCC or Clang driver it names (from the PATH, or an absolute path outside
  * the project) for its predefined macros, so in secure mode only an explicit
  * database is used.
@@ -159,20 +168,7 @@ export function findCompileCommands(src, options = {}) {
   if (!rootIsDir) {
     return undefined;
   }
-  const dirs = [root, ...COMPILE_COMMANDS_BUILD_DIRS.map((d) => join(root, d))];
-  try {
-    dirs.push(
-      ...readdirSync(root, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && e.name.startsWith("cmake-build-"))
-        .map((e) => join(root, e.name))
-        .sort(),
-    );
-  } catch (_err) {
-    // an unreadable root has no build directories to offer
-  }
-  if (options.cmakeCache) {
-    dirs.push(dirname(resolve(`${options.cmakeCache}`)));
-  }
+  const dirs = [root, ...cmakeBuildDirCandidates(root, options)];
   for (const dir of dirs) {
     const candidate = join(dir, COMPILE_COMMANDS_FILE);
     try {
@@ -319,6 +315,38 @@ export function atomCompileCommandsArgs(src, language, options = {}) {
   return ["--frontend-args", `compile-commands=${database}`];
 }
 
+/**
+ * The arguments that stop atom's Java frontend from running the scanned
+ * project's build. In its default delombok mode, atom runs
+ * `mvn dependency:build-classpath` inside a Maven project, which loads the
+ * project's `.mvn` configuration and build extensions, so delombok and
+ * dependency fetching are turned off whenever the project's own tooling may
+ * not run.
+ *
+ * @param {string} language atom `-l` value
+ * @param {Object} options CLI options
+ * @returns {string[]|undefined} Arguments to add to the atom command, or
+ *   undefined when the installed atom cannot be told to leave the build alone
+ */
+export function atomBuildToolArgs(language, options = {}) {
+  if (
+    `${language}`.toLowerCase() !== "java" ||
+    isProjectToolingAllowed(options)
+  ) {
+    return [];
+  }
+  const keys = atomFrontendArgKeys(language);
+  if (!keys.has("delombok-mode")) {
+    return undefined;
+  }
+  return [
+    "--frontend-args",
+    keys.has("fetch-dependencies")
+      ? "delombok-mode=no-delombok,fetch-dependencies=false"
+      : "delombok-mode=no-delombok",
+  ];
+}
+
 // Absolute ceiling on atom's heap. Past this point a larger heap buys a
 // collector that runs less often rather than an analysis that succeeds where it
 // otherwise would not, while the reservation itself is what pushes a build
@@ -751,18 +779,32 @@ export function buildAtomCommandEnv(options = {}, language = "") {
   // that does not exist on native platforms, and atom 3.0.x crashes parsing
   // that bogus value. Forward the resolved php-parse location through the env
   // so executeAtom can bypass the dispatcher for PHP (see
-  // resolveDirectAtomBinaryPath). Computed independently of exclude patterns.
+  // resolveDirectAtomBinaryPath). PHP_ASTGEN_BIN additionally names the
+  // batch-capable generator (phpastgen.js): chen parses the whole tree, vendor
+  // included, in one generator run instead of one php interpreter per file,
+  // which on windows is the difference between minutes and hours. Computed
+  // independently of exclude patterns.
   const phpParseBin = ATOM_PHP_LANGUAGES.has(normalizedLanguage)
     ? resolvePhpParseBin()
     : undefined;
+  const phpAstgenBin = ATOM_PHP_LANGUAGES.has(normalizedLanguage)
+    ? resolvePhpAstgenBin()
+    : undefined;
+  const phpEnv = {};
+  if (phpParseBin) {
+    phpEnv.PHP_PARSER_BIN = phpParseBin;
+  }
+  if (phpAstgenBin) {
+    phpEnv.PHP_ASTGEN_BIN = phpAstgenBin;
+  }
   if (!excludePatterns.length) {
-    return phpParseBin ? { PHP_PARSER_BIN: phpParseBin } : {};
+    return phpEnv;
   }
   const chenIgnoreDirs = mergeCsvValues(
     readEnvironmentVariable("CHEN_IGNORE_DIRS"),
     extractIgnoreDirsFromExcludePatterns(excludePatterns, true),
   );
-  const env = {};
+  const env = { ...phpEnv };
   if (chenIgnoreDirs) {
     env.CHEN_IGNORE_DIRS = chenIgnoreDirs;
   }
@@ -788,9 +830,6 @@ export function buildAtomCommandEnv(options = {}, language = "") {
       env.ASTGEN_IGNORE_FILE_PATTERN = astgenIgnoreFilePattern;
     }
   }
-  if (phpParseBin) {
-    env.PHP_PARSER_BIN = phpParseBin;
-  }
   return env;
 }
 
@@ -880,15 +919,19 @@ export function resolveAtomProvider(opts = {}) {
  * ceiling differently, and a native-image runtime option on a jar run reaches
  * atom as an unknown argument that fails every slice. So the kind follows what
  * is installed where cdxgen can see it: the native binary means native, the jar
- * package without it means jar. With neither in view (a custom `ATOM_CMD`, an
- * install elsewhere) the platform's kind stands.
+ * package without it means jar. An `ATOM_CMD` is classified by what it names
+ * (see `atomCommandKind`). With nothing in view (an install elsewhere) the
+ * platform's kind stands.
  *
  * Also used to gate Java/JDK advice, so users on the five native platforms are
  * not told to install a JDK for a failure that has nothing to do with Java.
  */
 export function atomProviderKind() {
   const { kind } = resolveAtomProvider();
-  if (kind !== "native" || readEnvironmentVariable("ATOM_CMD")) {
+  if (readEnvironmentVariable("ATOM_CMD")) {
+    return atomCommandKind(readEnvironmentVariable("ATOM_CMD"), kind);
+  }
+  if (kind !== "native") {
     return kind;
   }
   const atomHome = readEnvironmentVariable("ATOM_HOME");
@@ -906,13 +949,64 @@ export function atomProviderKind() {
   return jarPlugins ? "jar" : kind;
 }
 
+/**
+ * Whether `ATOM_CMD` launches a jar or follows the platform.
+ *
+ * The jar launchers (`plugins/bin/atom`, `plugins/bin/atom.bat`) sit next to a
+ * `plugins/lib` directory holding atom's jars, so a launcher with that sibling,
+ * or any `.bat` (only the jar payload ships one), runs on the JVM whatever the
+ * platform is. Everything else, including the npm dispatcher (`node
+ * .../index.js`, its `atom`/`atom.cmd` bin shims) and a native binary, follows
+ * the platform's kind. A GraalVM `-XX:` heap argument handed to a jar launcher
+ * is rejected by atom's option parser before any analysis starts, and a
+ * `JAVA_TOOL_OPTIONS` ceiling handed to a native image is silently ignored, so
+ * the distinction decides whether the heap is bounded at all.
+ *
+ * @param {string} command The `ATOM_CMD` value
+ * @param {"native"|"jar"} platformKind Kind the platform prefers
+ * @returns {"native"|"jar"}
+ */
+export function atomCommandKind(command, platformKind) {
+  const [bin, leadingArg] = splitAtomCommand(command);
+  const runsScript =
+    leadingArg !== undefined && /^node(\.exe)?$/i.test(basename(bin));
+  let launcher = runsScript ? leadingArg : bin;
+  if (/\.bat$/i.test(launcher)) {
+    return "jar";
+  }
+  try {
+    // npm bin entries are symlinks into the package (`/usr/local/bin/atom` ->
+    // `.../@appthreat/atom/index.js`), and `/usr/local` has a `lib` of its own.
+    launcher = realpathSync(launcher);
+  } catch {
+    return platformKind;
+  }
+  const binDir = dirname(launcher);
+  if (basename(binDir) !== "bin") {
+    return platformKind;
+  }
+  try {
+    const libDir = join(dirname(binDir), "lib");
+    if (
+      readdirSync(libDir).some(
+        (file) => file.startsWith("io.appthreat.atom") && file.endsWith(".jar"),
+      )
+    ) {
+      return "jar";
+    }
+  } catch {
+    // no lib directory: not a jar layout
+  }
+  return platformKind;
+}
+
 /**
  * Locate the `php-parse` binary that the PHP frontend needs.
  *
  * atom 3's dispatcher unconditionally sets `PHP_PARSER_BIN=<ATOM_HOME>/bin/php-parse`,
  * which for a native sub-package does not exist and also clobbers a caller-set
- * value. cdxgen therefore resolves the real location and forwards it through
- * the child env (see `buildAtomCommandEnv`); `executeAtom` then spawns the
+ * value. cdxgen therefore resolves the real location and forwards it through the
+ * child env (see `buildAtomCommandEnv`); `executeAtom` then spawns the
  * native binary directly for PHP so the dispatcher cannot clobber it (see
  * `resolveDirectAtomBinaryPath`). Resolution order:
  *   1. explicit `PHP_PARSER_BIN` env var (operators / container images)
@@ -929,6 +1023,44 @@ export function resolvePhpParseBin() {
   if (readEnvironmentVariable("PHP_PARSER_BIN")) {
     return readEnvironmentVariable("PHP_PARSER_BIN");
   }
+  return parsetoolsFile("plugins", "bin", "php-parse");
+}
+
+/**
+ * Locate the `phpastgen` generator that lets the PHP frontend parse whole
+ * directories in one batch.
+ *
+ * `php-parse` (forwarded as `PHP_PARSER_BIN`) is the per-file parser: atom
+ * starts a php interpreter for every `.php` file, which on windows turns a
+ * vendored PHP project (thousands of files under `vendor/`) into an hours-long
+ * run that no timeout can rescue. `phpastgen` answers the `--parser-info`
+ * capability probe, so atom's batch path engages, and atom-parsetools 1.9 and
+ * later parse the whole tree, vendor included, with a few interpreters that
+ * each take a chunk of files. It is a Node script, so the frontend launches it
+ * with `node` rather than `php`; an atom that does not know `PHP_ASTGEN_BIN`
+ * simply ignores it and keeps today's per-file behaviour. Resolution order:
+ *   1. explicit `PHP_ASTGEN_BIN` env var (operators / container images)
+ *   2. `@appthreat/atom-parsetools/phpastgen.js` under cdxgen's own
+ *      node_modules, then under `GLOBAL_NODE_MODULES_PATH` for global installs
+ *
+ * @returns {string|undefined}
+ */
+export function resolvePhpAstgenBin() {
+  if (readEnvironmentVariable("PHP_ASTGEN_BIN")) {
+    return readEnvironmentVariable("PHP_ASTGEN_BIN");
+  }
+  return parsetoolsFile("phpastgen.js");
+}
+
+/**
+ * Resolve a file inside the installed `@appthreat/atom-parsetools` package,
+ * searching cdxgen's own node_modules and `GLOBAL_NODE_MODULES_PATH` for global
+ * installs.
+ *
+ * @param {...string} segments Path segments below the package root
+ * @returns {string|undefined}
+ */
+export function parsetoolsFile(...segments) {
   const roots = [dirNameStr];
   if (readEnvironmentVariable("GLOBAL_NODE_MODULES_PATH")) {
     roots.push(dirname(readEnvironmentVariable("GLOBAL_NODE_MODULES_PATH")));
@@ -939,9 +1071,7 @@ export function resolvePhpParseBin() {
       "node_modules",
       "@appthreat",
       "atom-parsetools",
-      "plugins",
-      "bin",
-      "php-parse",
+      ...segments,
     );
     if (safeExistsSync(candidate)) {
       return candidate;
@@ -1213,25 +1343,41 @@ export function atomTimeouts() {
   };
 }
 
-function formatDuration(ms) {
-  if (ms >= 60_000) {
-    const minutes = Math.round(ms / 6_000) / 10;
-    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
-  }
-  return `${Math.round(ms / 100) / 10} seconds`;
-}
-
 // The status the atom dispatcher exits with when ATOM_TIMEOUT stops atom.
 const ATOM_TIMEOUT_EXIT_CODE = 124;
 
+/**
+ * Reap everything a timed-out atom run left behind on Windows.
+ *
+ * cdxgen starts atom through a shell there (`shell: isWin`), so the spawn
+ * timeout terminates only that `cmd.exe`, and the runtime and every parser
+ * worker under it (one `php.exe` per file for the per-file PHP frontend) keep
+ * running against the next slice of the same run. See
+ * {@link reapProcessTree} for how they are found. A chain broken by an
+ * intermediate that already exited (the npm dispatcher stopping its runtime
+ * itself) cannot be followed, and atom 4 stops its helpers once
+ * `ATOM_PARENT_PID` is gone.
+ *
+ * @param {number|undefined} rootPid pid of the process cdxgen spawned
+ * @param {number} startedAt Epoch milliseconds at which the run started
+ * @param {number} [endedAt] Epoch milliseconds at which the spawned process ended
+ * @returns {number[]} The pids that were stopped
+ */
+export function reapAtomProcessTree(rootPid, startedAt, endedAt = Date.now()) {
+  return reapProcessTree(rootPid, startedAt, endedAt, "atom");
+}
+
 /**
  * Whether an atom run ended because it ran out of time.
  *
  * The dispatcher reports its own limit with status 124. cdxgen's spawn timeout
  * shows up as `ETIMEDOUT`. A dispatcher older than the status code stops atom
- * with SIGTERM and exits 1, so status 1 at or past the limit counts as well,
- * unless atom's own output shows it failed for another reason first (an
- * exhausted heap, a crash), which deserves its own diagnosis.
+ * with SIGTERM and passes on how the runtime ended: 1, or the runtime's own
+ * exit on SIGTERM (143) or SIGKILL (137), which is what atom 3.1 reports. Those
+ * statuses at or past the limit count as well, unless atom's own output shows
+ * it failed for another reason first (an exhausted heap, a crash), which
+ * deserves its own diagnosis. Missing one leaves the half-written atom behind,
+ * and the next slice of the run fails to load it.
  *
  * @param {Object} result spawnSync result
  * @param {number} elapsedMs How long the run took
@@ -1245,13 +1391,21 @@ export function atomRunTimedOut(result, elapsedMs, atomTimeoutMs) {
   if (result?.error?.code === "ETIMEDOUT") {
     return true;
   }
-  if (result?.status !== 1 || elapsedMs < atomTimeoutMs) {
+  if (
+    !ATOM_STOPPED_STATUSES.includes(result?.status) ||
+    elapsedMs < atomTimeoutMs
+  ) {
     return false;
   }
   const output = `${result.stdout || ""}\n${result.stderr || ""}`;
   return !ATOM_FAILURE_MARKERS.some((marker) => output.includes(marker));
 }
 
+// How a runtime stopped by an older dispatcher at ATOM_TIMEOUT exits: the
+// dispatcher's own 1, or the runtime's exit on SIGTERM (128 + 15) or SIGKILL
+// (128 + 9) passed through.
+const ATOM_STOPPED_STATUSES = [1, 137, 143];
+
 // Output that means atom failed by itself, whatever the clock says.
 const ATOM_FAILURE_MARKERS = [
   "OutOfMemoryError",
@@ -1350,10 +1504,12 @@ export function executeAtom(src, args, extra_env = {}) {
     env,
     timeout: spawnTimeoutMs,
   });
-  if (atomRunTimedOut(result, Date.now() - startedAt, atomTimeoutMs)) {
+  const endedAt = Date.now();
+  if (atomRunTimedOut(result, endedAt - startedAt, atomTimeoutMs)) {
     console.warn(
       `WARN: atom did not finish within ${formatDuration(atomTimeoutMs)} and was stopped, so its results are missing or incomplete. Allow more time with ATOM_TIMEOUT (milliseconds, atom only) or CDXGEN_TIMEOUT_MS (every external command).`,
     );
+    reapAtomProcessTree(result.pid, startedAt, endedAt);
     // A stopped atom leaves its graph half written, and the next slice of the
     // same run would try to reuse it and fail to load it.
     const atomFileIndex = args.indexOf("-o");

package/lib/inventory/auditCategories.js

@@ -1,4 +1,4 @@
-import { shouldRunPredictiveBomAudit } from "../core/env.js";
+import { getCommandName, shouldRunPredictiveBomAudit } from "../core/env.js";
 
 /** Frozen list of hardware-bill-of-materials (HBOM) audit categories. */
 export const HBOM_AUDIT_CATEGORIES = Object.freeze([
@@ -23,6 +23,12 @@ export const GOLEM_AUDIT_CATEGORIES = Object.freeze([
   "golem-compliance",
 ]);
 
+/** Frozen list of Scala Evinse (scalasem) audit categories. */
+export const SCALA_AUDIT_CATEGORIES = Object.freeze([
+  "scala-security",
+  "scala-compliance",
+]);
+
 /** Frozen list of Cargo (Rust) audit categories. */
 export const CARGO_AUDIT_CATEGORIES = Object.freeze([
   "cargo-security",
@@ -64,6 +70,7 @@ export const BOM_AUDIT_CATEGORY_ALIASES = Object.freeze({
   golem: [...GOLEM_AUDIT_CATEGORIES],
   hbom: [...HBOM_AUDIT_CATEGORIES],
   rust: [...CARGO_AUDIT_CATEGORIES],
+  scala: [...SCALA_AUDIT_CATEGORIES],
   host: [...HBOM_AUDIT_CATEGORIES, ...HOST_TOPOLOGY_AUDIT_CATEGORIES],
 });
 
@@ -179,11 +186,11 @@ export function validateBomAuditCategories(categories, rules) {
  * @returns {string | undefined} Default category string, if any
  */
 export function getDefaultBomAuditCategories(options, commandPath) {
-  const normalizedCommandPath = `${commandPath || ""}`.toLowerCase();
+  const commandName = getCommandName(commandPath);
   const defaultHbomCategories = options?.includeRuntime
     ? `${DEFAULT_HBOM_AUDIT_CATEGORIES},host-topology`
     : DEFAULT_HBOM_AUDIT_CATEGORIES;
-  if (normalizedCommandPath.includes("hbom")) {
+  if (commandName.startsWith("hbom")) {
     return defaultHbomCategories;
   }
   const projectTypes = Array.isArray(options?.projectType)

package/lib/inventory/buildToolRateLimit.js

@@ -0,0 +1,144 @@
+import { recordDegradation } from "../core/buildLedger.js";
+import { registerRunReset } from "../core/runState.js";
+
+/**
+ * Text a build tool prints when its Maven repository answers HTTP 429, as
+ * recorded from each tool against a repository that rate limits. One small
+ * matcher per tool, plain substring tests on the combined output: the tools
+ * reword their messages between versions, so the matched fragment is the one
+ * every observed phrasing keeps (the status number in the tool's own wording).
+ *
+ * sbt, Mill and scala-cli resolve through Coursier, so they share the
+ * coursier matcher. The Coursier inside sbt 1.x reports the JDK's
+ * `Server returned HTTP response code: 429`; the one in sbt 2, Mill and
+ * scala-cli reports `retryable HTTP error: <url> (HTTP 429)`, with a
+ * `Retry-After` inside the parentheses when the server sent one.
+ *
+ * @type {Object<string, string[]>}
+ */
+const RATE_LIMIT_MARKERS = {
+  maven: ["status code: 429", "Too Many Requests"],
+  gradle: ["Received status code 429", "[HTTP 429: http"],
+  coursier: ["response code: 429", "(HTTP 429"],
+};
+
+/**
+ * The matcher family a tool belongs to.
+ *
+ * @type {Object<string, string>}
+ */
+const TOOL_MATCHER = {
+  maven: "maven",
+  gradle: "gradle",
+  sbt: "coursier",
+  mill: "coursier",
+  "scala-cli": "coursier",
+};
+
+/**
+ * How each tool is moved to a mirror, named in one hint per tool and scan.
+ * sbt reads its own repositories file; Mill and scala-cli read Coursier's
+ * mirror.properties, whose entry spells the semicolon-separated format
+ * because a comma list is silently ignored.
+ *
+ * @type {Object<string, string>}
+ */
+const MIRROR_SETTINGS = {
+  maven:
+    "Point Maven at a mirror with a <mirror> entry in the Maven settings.xml, or set MVNW_REPOURL for the Maven wrapper.",
+  gradle:
+    "Point Gradle at a mirror by declaring the repository in a Gradle init script.",
+  sbt: "Point sbt at a mirror by listing it in ~/.sbt/repositories and passing -Dsbt.override.build.repos=true in SBT_OPTS or .sbtopts.",
+  coursier:
+    "Point Coursier at a mirror with mirror.properties, setting central.from and central.to (separate several central.from URLs with semicolons, not commas).",
+};
+
+/**
+ * Tools whose later invocations or retries cdxgen skips once one met a rate
+ * limit. Mill and scala-cli resolve in a single invocation.
+ *
+ * @type {Set<string>}
+ */
+const STOPPED_TOOLS = new Set(["maven", "gradle", "sbt"]);
+
+/**
+ * Tools whose repository answered HTTP 429 during the current scan. Further
+ * invocations of that tool would only pay the same back-off for the same
+ * empty answer.
+ *
+ * @type {Set<string>}
+ */
+const rateLimitedTools = new Set();
+
+registerRunReset("inventory.buildToolRateLimit", () => {
+  rateLimitedTools.clear();
+});
+
+/**
+ * Whether a tool's combined output names a rate limit from its repository.
+ * The answer text is treated as untrusted: only fixed substrings are looked
+ * for, nothing from the output is kept.
+ *
+ * @param {string} output Combined stdout and stderr of one invocation.
+ * @param {string} tool One of maven, gradle, sbt, mill, scala-cli.
+ * @returns {boolean} True when the output names an HTTP 429 answer.
+ */
+export function detectBuildToolRateLimit(output, tool) {
+  const markers = RATE_LIMIT_MARKERS[TOOL_MATCHER[tool]];
+  if (!markers || typeof output !== "string" || !output) {
+    return false;
+  }
+  return markers.some((marker) => output.includes(marker));
+}
+
+/**
+ * Whether a tool was already found rate limited in this scan, so the caller
+ * can skip its remaining invocations.
+ *
+ * @param {string} tool One of maven, gradle, sbt, mill, scala-cli.
+ * @returns {boolean}
+ */
+export function isBuildToolRateLimited(tool) {
+  return rateLimitedTools.has(tool);
+}
+
+/**
+ * Read a completed invocation's output for a rate limit. When one is found,
+ * the tool is remembered for the scan, one hint naming the tool's mirror
+ * setting is printed, and the `build.rate-limited` degradation is recorded.
+ * The first invocation that shows the rate limit is the one recorded; later
+ * ones add nothing, because the same answer ends them all.
+ *
+ * @param {string} tool One of maven, gradle, sbt, mill, scala-cli.
+ * @param {string|undefined} output Combined output, as commandOutputText
+ *   returns it for a spawn result.
+ * @param {Object} [context] Call-site facts for the degradation event.
+ * @param {string} [context.command] The redacted command that was attempted.
+ * @param {number} [context.exitCode] The invocation's exit status.
+ * @returns {boolean} True when this output names a rate limit.
+ */
+export function noteBuildToolRateLimit(tool, output, context = {}) {
+  if (!detectBuildToolRateLimit(output, tool)) {
+    return false;
+  }
+  if (isBuildToolRateLimited(tool)) {
+    return true;
+  }
+  rateLimitedTools.add(tool);
+  const stopped = STOPPED_TOOLS.has(tool)
+    ? `, so cdxgen runs no further ${tool} resolution in this scan and`
+    : ", so";
+  console.warn(
+    `The repository ${tool} downloads from is rate limiting this machine (HTTP 429)${stopped} its dependency tree is incomplete. ${MIRROR_SETTINGS[tool] || MIRROR_SETTINGS[TOOL_MATCHER[tool]]} cdxgen's own lookups can be moved with MAVEN_CENTRAL_URL.`,
+  );
+  recordDegradation("build.rate-limited", {
+    ecosystem: "java",
+    tool,
+    impact: "transitive-deps",
+    command: context.command,
+    exitCode: context.exitCode,
+    detail: `The repository ${tool} downloads from answered HTTP 429, so ${tool} resolved no dependencies.`,
+    outputExcerpt: output,
+  });
+  return true;
+}

package/lib/inventory/cacheCommands.js

@@ -1,5 +1,6 @@
 /**
- * `cdxgen cache` subcommand — inspect and purge the metadata fetch cache.
+ * `cdxgen cache` subcommand — inspect and purge the metadata fetch cache that
+ * cdxrs and the JS batch pool share.
  *
  * This module operates directly on the filesystem because JS is the authority
  * for the cache directory. The cache layout is:

package/lib/inventory/cacheDir.js

@@ -28,13 +28,21 @@ import { isMac, isWin } from "../core/paths.js";
  * rather than reading `isWin`/`isMac` here, or the Windows and Linux branches
  * become untestable on a macOS developer machine.
  *
+ * Every environment-derived root must be absolute by the *target* platform's
+ * rules, never the host's (`path.isAbsolute` would accept `\cache` on a
+ * Windows host): a relative value is ignored, so it cannot point inside the
+ * working directory. XDG requires this of `XDG_CACHE_HOME`; the home and
+ * `LOCALAPPDATA` roots get the same treatment for the same reason.
+ *
  * @param {Object} inputs Resolution inputs.
  * @param {"linux"|"macos"|"windows"} inputs.platform Which convention to apply.
- * @param {string} [inputs.cdxgenCacheDir] `CDXGEN_CACHE_DIR`.
+ * @param {string} [inputs.cdxgenCacheDir] `CDXGEN_CACHE_DIR`, an explicit
+ *   override taken as given.
  * @param {string} [inputs.xdgCacheHome] `XDG_CACHE_HOME`. Ignored unless
- *   absolute, per the XDG spec, so it cannot point inside the working directory.
- * @param {string} [inputs.home] Home directory.
- * @param {string} [inputs.localAppData] `LOCALAPPDATA`.
+ *   `/`-rooted.
+ * @param {string} [inputs.home] Home directory. Ignored unless absolute.
+ * @param {string} [inputs.localAppData] `LOCALAPPDATA`. Ignored unless drive-
+ *   or UNC-rooted; the home profile is the fallback.
  * @returns {string|null} Absolute path, or null when nothing resolves.
  */
 export function resolveCacheDirFor({
@@ -48,20 +56,55 @@ export function resolveCacheDirFor({
     return path.resolve(cdxgenCacheDir);
   }
   if (platform === "windows") {
-    if (localAppData?.trim()) {
+    if (isWindowsAbsolute(localAppData)) {
       return path.join(localAppData, "cdxgen", "cache");
     }
-    return home?.trim()
+    return isWindowsAbsolute(home)
       ? path.join(home, "AppData", "Local", "cdxgen", "cache")
       : null;
   }
   if (platform === "macos") {
-    return home?.trim() ? path.join(home, "Library", "Caches", "cdxgen") : null;
+    return isPosixAbsolute(home)
+      ? path.join(home, "Library", "Caches", "cdxgen")
+      : null;
   }
-  if (xdgCacheHome?.trim() && path.isAbsolute(xdgCacheHome)) {
+  if (isPosixAbsolute(xdgCacheHome)) {
     return path.join(xdgCacheHome, "cdxgen");
   }
-  return home?.trim() ? path.join(home, ".cache", "cdxgen") : null;
+  return isPosixAbsolute(home) ? path.join(home, ".cache", "cdxgen") : null;
+}
+
+/**
+ * Absolute by POSIX rules: `/`-rooted.
+ *
+ * @param {string} [value] Candidate path
+ * @returns {boolean} Whether the path is absolute
+ */
+function isPosixAbsolute(value) {
+  return typeof value === "string" && value.startsWith("/");
+}
+
+/**
+ * Absolute by Windows rules: a drive letter followed by a separator (`C:\` or
+ * `C:/`), or a UNC path (`\\server\share`). `C:cache` (relative to the drive's
+ * current directory) and `\cache` (relative to the current drive) are not.
+ * Mirrors `is_windows_absolute` in cdxrs.
+ *
+ * @param {string} [value] Candidate path
+ * @returns {boolean} Whether the path is absolute
+ */
+function isWindowsAbsolute(value) {
+  if (typeof value !== "string" || value.length < 3) {
+    return false;
+  }
+  const isSeparator = (char) => char === "\\" || char === "/";
+  const driveRooted = /^[a-zA-Z]$/.test(value[0]) && value[1] === ":";
+  if (driveRooted) {
+    return isSeparator(value[2]);
+  }
+  return (
+    isSeparator(value[0]) && isSeparator(value[1]) && !isSeparator(value[2])
+  );
 }
 
 /**