@cdxgen/cdxgen 13.6.0 → 13.7.0

package/lib/ecosystems/gradleutils.js

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 import { chmodSync, readdirSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import process from "node:process";
 
 import { build } from "@cdxgen/cdx-purl";
@@ -12,6 +12,7 @@ import {
   readEnvironmentVariable,
   recordDecisionActivity,
 } from "../core/activity.js";
+import { readRegularTextFile } from "../core/boundedFile.js";
 import {
   commandOutputText,
   isLedgerEnabled,
@@ -30,10 +31,13 @@ import {
   noteBuildToolRateLimit,
 } from "../inventory/buildToolRateLimit.js";
 import { collectJarNS } from "../inventory/deps.js";
+import { splitArtifactFileName } from "../inventory/jvmLocalRepos.js";
 import { minimumGradleVersionForJava } from "../inventory/jvmToolEnv.js";
 import { gradleMirrorInitScriptArgs } from "../inventory/mavenCentralMirror.js";
-import { applyPurl, tryBuildPurl } from "../inventory/purl.js";
+import { applyPurl, mavenPurl, tryBuildPurl } from "../inventory/purl.js";
+import { xml2js } from "../parsers/xml.js";
 import { parsePkgJson } from "./parsers-js.js";
+import { isInVendoredDir } from "./vendoredCode.js";
 
 /**
  * True when the pre-generation stage pinned an exact JVM build tool version
@@ -1223,7 +1227,12 @@ function parseGradleTreeLine(line) {
     }
   }
   const [requested, selected] = text.split(" -> ");
-  if (requested.startsWith("project ")) {
+  // Gradle 9.6 and later print the root project as `root project '<name>'`
+  // where earlier versions print `project :`. Either way it is the root
+  // project, whose path is `:`.
+  if (requested.startsWith("root project ")) {
+    parsed.projectPath = ":";
+  } else if (requested.startsWith("project ")) {
     parsed.projectPath = gradleProjectPath(requested.slice("project ".length));
   } else {
     const [group, name, ...versionParts] = requested.split(":");
@@ -1235,7 +1244,11 @@ function parseGradleTreeLine(line) {
     parsed.requestedVersion = versionParts.join(":") || undefined;
     parsed.version = gradleRequestedVersion(parsed.requestedVersion);
   }
-  if (selected?.startsWith("project ")) {
+  if (selected?.startsWith("root project ")) {
+    // A module substituted by the root project, as with
+    // `substitute module('org.ex:main') using project(':')`.
+    parsed.projectPath = ":";
+  } else if (selected?.startsWith("project ")) {
     parsed.projectPath = gradleProjectPath(selected.slice("project ".length));
   } else if (selected?.includes(":")) {
     // The selected module replaces the requested one, version and all.
@@ -1244,8 +1257,12 @@ function parseGradleTreeLine(line) {
     parsed.name = name;
     parsed.version = version;
     parsed.requestedVersion = undefined;
-  } else if (selected) {
+  } else if (selected && !/\s/u.test(selected)) {
+    // A selected version has no whitespace. Anything else is a form of the
+    // report this parser does not know, and must not become a version.
     parsed.version = selected;
+  } else if (selected) {
+    return { level: parsed.level, unknown: true };
   }
   if (parsed.projectPath === undefined && !parsed.group) {
     return { level: parsed.level, unknown: true };
@@ -2433,6 +2450,14 @@ function catalogCoordinate(entry) {
   return undefined;
 }
 
+/**
+ * Gradle rich-version syntax that names no single version: a bracketed range,
+ * an interval, a `!!` or `{strictly}` marker, a `->` transition, or a `..`
+ * separator. A version text matching this is a declaration about versions, not
+ * one version.
+ */
+const GRADLE_RICH_VERSION_PATTERN = /[[\](),!]|->|\.\./u;
+
 /**
  * Resolve the version of one catalog entry.
  *
@@ -2455,8 +2480,1059 @@ function resolveCatalogVersion(entry, versions) {
   if (typeof raw !== "string" || !raw) {
     return undefined;
   }
-  if (/[[\](),!]|->|\.\./u.test(raw)) {
+  if (GRADLE_RICH_VERSION_PATTERN.test(raw)) {
     return undefined;
   }
   return raw;
 }
+
+/**
+ * The largest Gradle lockfile read. Real lockfiles of large multi-project
+ * builds stay well under a megabyte; the file is untrusted input, so a larger
+ * one is skipped whole rather than read in part.
+ */
+const GRADLE_LOCKFILE_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The most lines read from one Gradle lockfile. Lines past the cap are
+ * ignored.
+ */
+const GRADLE_LOCKFILE_MAX_LINES = 100000;
+
+/**
+ * Gradle 6+ lockfiles that lock a buildscript classpath rather than the
+ * project's own configurations.
+ */
+const GRADLE_BUILD_TOOLING_LOCKFILES = new Set([
+  "buildscript-gradle.lockfile",
+  "settings-gradle.lockfile",
+]);
+
+const GRADLE_LOCKFILE_SUFFIX = ".lockfile";
+
+/**
+ * Work out which kind of Gradle lockfile a path names.
+ *
+ * Gradle 6 and later write one `gradle.lockfile` per project, plus
+ * `buildscript-gradle.lockfile` and `settings-gradle.lockfile` for the
+ * buildscript classpaths. Gradle 4.8 to 5.x wrote one
+ * `gradle/dependency-locks/<configuration>.lockfile` per configuration, with
+ * the buildscript configurations prefixed `buildscript-`.
+ *
+ * @param {string} lockFile Path to the lockfile
+ * @returns {{legacy: boolean, buildTooling: boolean, configuration: (string|undefined)}|undefined}
+ *   The kind, or undefined when the name is not a lockfile name
+ */
+function gradleLockfileKind(lockFile) {
+  const fileName = basename(lockFile);
+  if (!fileName.endsWith(GRADLE_LOCKFILE_SUFFIX)) {
+    return undefined;
+  }
+  const parentDir = dirname(lockFile);
+  if (
+    basename(parentDir) === "dependency-locks" &&
+    basename(dirname(parentDir)) === "gradle"
+  ) {
+    const configuration = fileName.slice(0, -GRADLE_LOCKFILE_SUFFIX.length);
+    if (!configuration) {
+      return undefined;
+    }
+    return {
+      legacy: true,
+      buildTooling: configuration.startsWith("buildscript-"),
+      configuration,
+    };
+  }
+  return {
+    legacy: false,
+    buildTooling: GRADLE_BUILD_TOOLING_LOCKFILES.has(fileName),
+    configuration: undefined,
+  };
+}
+
+/**
+ * Read a `group:name:version` coordinate from a lockfile entry.
+ *
+ * Gradle writes only resolved versions to a lockfile, so a version that is
+ * blank, a range, a dynamic selector (`1.+`, `latest.release`) or any other
+ * rich-version syntax means the line was not written by Gradle and is
+ * skipped.
+ *
+ * @param {string} text Coordinate text, already trimmed
+ * @returns {{group: string, name: string, version: string}|undefined}
+ *   The coordinate, or undefined for anything else
+ */
+function parseGradleLockCoordinate(text) {
+  if (!text || /[\s=]/u.test(text)) {
+    return undefined;
+  }
+  const parts = text.split(":");
+  if (parts.length !== 3 || parts.some((part) => !part)) {
+    return undefined;
+  }
+  const [group, name, version] = parts;
+  // Gradle writes only resolved versions to a lockfile, so a rich version or
+  // a dynamic selector (`1.+`, `2.*`, `latest.release`) means the line was
+  // not written by Gradle. The rich-version rejection is the one
+  // `resolveCatalogVersion` applies; a trailing `+` and a `*` are the
+  // dynamic selectors.
+  if (
+    version.startsWith("latest.") ||
+    version.endsWith("+") ||
+    version.includes("*") ||
+    GRADLE_RICH_VERSION_PATTERN.test(version)
+  ) {
+    return undefined;
+  }
+  return { group, name, version };
+}
+
+/**
+ * Parse one Gradle dependency lockfile.
+ *
+ * Both layouts are read. A Gradle 6+ `gradle.lockfile` has one
+ * `group:name:version=configuration,configuration` line per module and an
+ * `empty=` line naming the configurations that resolved nothing. A legacy
+ * `gradle/dependency-locks/<configuration>.lockfile` has one
+ * `group:name:version` line per module, and the file name is the
+ * configuration.
+ *
+ * The scope of a module is the strongest that `gradleConfigurationScope`
+ * gives any of its configurations, so a module locked for both
+ * `testRuntimeClasspath` and `runtimeClasspath` is `required`. Everything in
+ * a buildscript or settings lockfile is build tooling and `excluded`.
+ *
+ * A lockfile records resolved versions, so components carry a purl identity
+ * with confidence 1 and the lockfile path as the evidence value. The purl and
+ * bom-ref match what `parseGradleDep` builds for the same coordinate, so a
+ * component reads the same whether Gradle ran or not. A lockfile is flat: it
+ * says nothing about which module depends on which, so no dependency graph is
+ * returned.
+ *
+ * The file is untrusted input. It is read only when it is a regular file no
+ * larger than 8 MiB, at most 100000 lines are read, and a malformed line
+ * costs only itself. Line content never reaches a property.
+ *
+ * @param {string} lockFile Path to the lockfile
+ * @param {Object} [options] Parse options
+ * @param {string} [options.rootDir] Directory the lockfile must resolve inside
+ * @returns {Object[]} Components, one per locked module
+ */
+export function parseGradleLockfile(lockFile, options = {}) {
+  const kind = gradleLockfileKind(lockFile);
+  if (!kind) {
+    return [];
+  }
+  const text = readRegularTextFile(
+    lockFile,
+    GRADLE_LOCKFILE_MAX_BYTES,
+    options?.rootDir,
+  );
+  if (text === undefined) {
+    if (safeExistsSync(lockFile)) {
+      console.warn(
+        `Skipping ${lockFile}: it is not a regular file inside the project, or is larger than ${GRADLE_LOCKFILE_MAX_BYTES} bytes.`,
+      );
+    }
+    return [];
+  }
+  const body = text.startsWith("\uFEFF") ? text.slice(1) : text;
+  const pkgsByRef = new Map();
+  let skippedLines = 0;
+  let lineStart = 0;
+  let lineCount = 0;
+  while (lineStart <= body.length) {
+    if (lineCount === GRADLE_LOCKFILE_MAX_LINES) {
+      if (lineStart < body.length) {
+        thoughtLog(
+          `${lockFile} has more than ${GRADLE_LOCKFILE_MAX_LINES} lines; only the first ${GRADLE_LOCKFILE_MAX_LINES} are read.`,
+        );
+      }
+      break;
+    }
+    let lineEnd = body.indexOf("\n", lineStart);
+    if (lineEnd === -1) {
+      lineEnd = body.length;
+    }
+    const line = body.slice(lineStart, lineEnd).trim();
+    lineStart = lineEnd + 1;
+    lineCount++;
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    let coordinateText = line;
+    let configurations = [kind.configuration];
+    if (!kind.legacy) {
+      const separator = line.indexOf("=");
+      if (separator === -1) {
+        skippedLines++;
+        continue;
+      }
+      coordinateText = line.slice(0, separator).trim();
+      if (coordinateText === "empty") {
+        continue;
+      }
+      configurations = line
+        .slice(separator + 1)
+        .split(",")
+        .map((configuration) => configuration.trim())
+        .filter(Boolean);
+    }
+    const coordinate = parseGradleLockCoordinate(coordinateText);
+    if (!coordinate || !configurations.length) {
+      skippedLines++;
+      continue;
+    }
+    const { group, name, version } = coordinate;
+    const purl = mavenPurl(group, name, version, { type: "jar" });
+    if (!purl) {
+      skippedLines++;
+      continue;
+    }
+    let scope = "excluded";
+    if (!kind.buildTooling) {
+      for (const configuration of configurations) {
+        const configurationScope = gradleConfigurationScope(configuration);
+        if (gradleScopeRank(configurationScope) > gradleScopeRank(scope)) {
+          scope = configurationScope;
+        }
+      }
+    }
+    const bomRef = decodeURIComponent(purl);
+    const existing = pkgsByRef.get(bomRef);
+    if (existing) {
+      if (gradleScopeRank(scope) > gradleScopeRank(existing.scope)) {
+        existing.scope = scope;
+      }
+      continue;
+    }
+    pkgsByRef.set(bomRef, {
+      group,
+      name,
+      version,
+      qualifiers: { type: "jar" },
+      type: "library",
+      scope,
+      purl,
+      "bom-ref": bomRef,
+      properties: [{ name: "internal:SrcFile", value: lockFile }],
+      evidence: {
+        identity: {
+          field: "purl",
+          confidence: 1,
+          concludedValue: purl,
+          methods: [
+            {
+              technique: "manifest-analysis",
+              confidence: 1,
+              value: lockFile,
+            },
+          ],
+        },
+      },
+    });
+  }
+  if (skippedLines) {
+    thoughtLog(
+      `Skipped ${skippedLines} malformed or unresolved line(s) in ${lockFile}.`,
+    );
+  }
+  return [...pkgsByRef.values()];
+}
+
+/**
+ * Parse several Gradle lockfiles of one build and merge the result.
+ *
+ * Every project of a multi-project build has its own lockfile, so the same
+ * module often appears in several of them with different configurations. The
+ * copies collapse into one component with the strongest scope any lockfile
+ * gave it (see `reconcileGradleComponents`), and its evidence lists every
+ * lockfile that locked it. The first lockfile that locked a module stays its
+ * `internal:SrcFile`.
+ *
+ * @param {string[]} lockFiles Paths to the lockfiles
+ * @param {Object} [options] Parse options, as for `parseGradleLockfile`
+ * @returns {Object[]} Components, one per locked module
+ */
+export function parseGradleLockfiles(lockFiles, options = {}) {
+  const allPkgs = [];
+  for (const lockFile of lockFiles || []) {
+    allPkgs.push(...parseGradleLockfile(lockFile, options));
+  }
+  reconcileGradleComponents(allPkgs);
+  const pkgsByRef = new Map();
+  for (const pkg of allPkgs) {
+    const existing = pkgsByRef.get(pkg["bom-ref"]);
+    if (!existing) {
+      pkgsByRef.set(pkg["bom-ref"], pkg);
+      continue;
+    }
+    const methods = existing.evidence.identity.methods;
+    for (const method of pkg.evidence.identity.methods) {
+      if (!methods.some((m) => m.value === method.value)) {
+        methods.push(method);
+      }
+    }
+  }
+  return [...pkgsByRef.values()];
+}
+
+/**
+ * The build files that mark a directory as a Gradle project of its own. A
+ * lockfile is accepted only beside one of these, so a lockfile copied into a
+ * notes folder or a build's output is not read as an inventory source.
+ */
+const GRADLE_PROJECT_MARKERS = [
+  "build.gradle",
+  "build.gradle.kts",
+  "settings.gradle",
+  "settings.gradle.kts",
+];
+
+/**
+ * Find the Gradle dependency lockfiles of one build.
+ *
+ * Both layouts are searched below `rootPath`, recursively even when
+ * `options.multiProject` is off: every subproject of a Gradle build locks its
+ * own configurations, and the subprojects belong to the same build. The
+ * Gradle 6+ names are `gradle.lockfile`, `buildscript-gradle.lockfile` and
+ * `settings-gradle.lockfile`; the Gradle 4.8 to 5.x layout is
+ * `gradle/dependency-locks/<configuration>.lockfile`.
+ *
+ * A lockfile is accepted only when the project directory that owns it holds a
+ * Gradle build file, and never when it sits under `build/`, `.gradle/`,
+ * `node_modules/` or a vendored directory. `getAllFiles` already leaves
+ * `.git`, `.hg`, `.chen` and `node_modules` out; `build/` and `.gradle/` are
+ * Gradle's own output and cache directories, which a lockfile in them cannot
+ * belong to the project's source of truth.
+ *
+ * Custom `dependencyLocking.lockFile` paths, the Nebula `dependencies.lock`
+ * and Palantir `versions.lock` formats are not looked for.
+ *
+ * @param {string} rootPath Directory to search
+ * @param {Object} [options] CLI options
+ * @returns {string[]} Lockfile paths, in a stable order
+ */
+export function findGradleLockfiles(rootPath, options = {}) {
+  const lockFiles = new Set();
+  for (const pattern of [
+    "**/{gradle,buildscript-gradle,settings-gradle}.lockfile",
+    "**/gradle/dependency-locks/*.lockfile",
+  ]) {
+    for (const lockFile of getAllFiles(rootPath, pattern, options)) {
+      // Only the segments below the scan root count: a scan root that sits
+      // under a directory named `build` still has lockfiles of its own.
+      const segments = relative(rootPath, lockFile).split(/[\\/]/);
+      if (
+        segments.some((segment) =>
+          ["build", ".gradle", "node_modules"].includes(segment),
+        )
+      ) {
+        continue;
+      }
+      if (isInVendoredDir(rootPath, lockFile)) {
+        continue;
+      }
+      const kind = gradleLockfileKind(lockFile);
+      if (!kind) {
+        continue;
+      }
+      // The project directory is the lockfile's own directory, and the
+      // directory above `gradle` for a legacy dependency-locks file.
+      const projectDir = kind.legacy
+        ? dirname(dirname(dirname(lockFile)))
+        : dirname(lockFile);
+      if (
+        !GRADLE_PROJECT_MARKERS.some((marker) =>
+          safeExistsSync(join(projectDir, marker)),
+        )
+      ) {
+        continue;
+      }
+      lockFiles.add(lockFile);
+    }
+  }
+  return [...lockFiles].sort();
+}
+
+/**
+ * The most bytes read from a settings script when looking for the root
+ * project name.
+ */
+const GRADLE_SETTINGS_MAX_BYTES = 1024 * 1024;
+
+/**
+ * Read the root project name a Gradle settings script assigns with
+ * `rootProject.name = '<name>'` or `rootProject.name = "<name>"`, without
+ * running Gradle.
+ *
+ * `settings.gradle` is read before `settings.gradle.kts`, and the last
+ * assignment in the file wins, as it does in Gradle. Only a plain string
+ * literal is accepted: a value built from a variable, a template
+ * (`"${x}"`) or a method call is not something a static read can resolve.
+ *
+ * @param {string} gradleRootPath Root directory of the Gradle build
+ * @returns {string|undefined} The root project name, or undefined when no
+ *   settings script assigns one as a plain literal
+ */
+export function readGradleRootProjectName(gradleRootPath) {
+  for (const settingsName of ["settings.gradle", "settings.gradle.kts"]) {
+    const settingsFile = join(gradleRootPath, settingsName);
+    if (!safeExistsSync(settingsFile)) {
+      continue;
+    }
+    const text = readRegularTextFile(
+      settingsFile,
+      GRADLE_SETTINGS_MAX_BYTES,
+      gradleRootPath,
+    );
+    if (!text) {
+      continue;
+    }
+    let rootName;
+    for (const rawLine of text.split("\n")) {
+      const line = rawLine.trim();
+      if (!line.startsWith("rootProject.name")) {
+        continue;
+      }
+      let rest = line.slice("rootProject.name".length).trim();
+      if (!rest.startsWith("=")) {
+        continue;
+      }
+      rest = rest.slice(1).trim();
+      const commentIndex = rest.indexOf("//");
+      if (commentIndex !== -1) {
+        rest = rest.slice(0, commentIndex).trim();
+      }
+      if (rest.endsWith(";")) {
+        rest = rest.slice(0, -1).trim();
+      }
+      const quote = rest.charAt(0);
+      if (
+        rest.length < 3 ||
+        !["'", '"'].includes(quote) ||
+        !rest.endsWith(quote)
+      ) {
+        continue;
+      }
+      const value = rest.slice(1, -1).trim();
+      if (
+        !value ||
+        [..."'\"$\\"].some((ch) => value.includes(ch)) ||
+        value.includes("/")
+      ) {
+        continue;
+      }
+      rootName = value;
+    }
+    if (rootName) {
+      return rootName;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The largest gradle/verification-metadata.xml read. Real files of large
+ * builds stay around half a megabyte; the file is untrusted input, so a
+ * larger one is skipped whole rather than read in part.
+ */
+const GRADLE_VERIFICATION_METADATA_MAX_BYTES = 32 * 1024 * 1024;
+
+/**
+ * The most components read from one verification-metadata.xml. Components
+ * past the cap are ignored.
+ */
+const GRADLE_VERIFICATION_METADATA_MAX_COMPONENTS = 200000;
+
+/**
+ * The most artifacts read for one component. A real entry names the jar, the
+ * pom and the module metadata; a coordinate listing many more artifacts was
+ * not written by Gradle.
+ */
+const GRADLE_VERIFICATION_METADATA_MAX_ARTIFACTS = 64;
+
+/**
+ * Checksum element of the verification schema, the CycloneDX hash algorithm
+ * it maps to, and the exact hex digest length that algorithm produces. A
+ * digest of any other length was not written by Gradle.
+ */
+const VERIFICATION_HASH_ALGORITHMS = [
+  { element: "sha512", alg: "SHA-512", length: 128 },
+  { element: "sha256", alg: "SHA-256", length: 64 },
+  { element: "sha1", alg: "SHA-1", length: 40 },
+  { element: "md5", alg: "MD5", length: 32 },
+];
+
+const HEX_DIGEST_PATTERN = /^[0-9a-f]+$/iu;
+
+/**
+ * A `pgp value` is either a 16-character long key id or a 40-character v4
+ * fingerprint. Anything else is not a key id.
+ */
+const PGP_KEY_ID_LENGTHS = new Set([16, 40]);
+
+/**
+ * The build stamp a timestamped SNAPSHOT file carries in place of
+ * `-SNAPSHOT`, for example `-20240401.123456-1`.
+ */
+const SNAPSHOT_STAMP_PATTERN = /^-\d{8}\.\d{6}-\d+/u;
+
+/**
+ * Children of one element in the compact XML form. A child that occurs once
+ * parses as an object and a repeated child as an array; this accepts both.
+ *
+ * @param {object|object[]|undefined} value Compact-form child or children
+ * @returns {object[]} The children as a list
+ */
+function verificationElementList(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * One named child of an element in the compact XML form.
+ *
+ * A document whose root element carries a namespace prefix keeps that prefix
+ * on the name of every element below it, so the child name is looked up with
+ * the root's prefix in front of it. Attributes are never prefixed: the
+ * schema's attributes are unqualified even when the elements are not.
+ *
+ * @param {object|undefined} element Compact-form element
+ * @param {string} name Child element name without a prefix
+ * @param {string} [prefix] Namespace prefix of the root element, with its
+ *   colon
+ * @returns {object[]} The children as a list
+ */
+function verificationChildList(element, name, prefix = "") {
+  return verificationElementList(element?.[`${prefix}${name}`]);
+}
+
+/**
+ * Read the `true` or `false` text of a configuration flag. A flag that is
+ * absent, or whose text is neither, reads as undefined so the caller cannot
+ * tell a written `false` from an unreadable one.
+ *
+ * @param {object|undefined} element Compact-form flag element
+ * @returns {boolean|undefined} The flag value, or undefined
+ */
+function verificationBoolean(element) {
+  const value = typeof element?._ === "string" ? element._.trim() : "";
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  return undefined;
+}
+
+/**
+ * Split an artifact file name into its classifier and extension, accepting
+ * the timestamped file names Gradle writes for SNAPSHOT versions, for which
+ * the build stamp replaces `-SNAPSHOT` in the file name only.
+ *
+ * @param {string} fileName File name from the verification metadata
+ * @param {string} name Artifact ID of the coordinate
+ * @param {string} version Version of the coordinate
+ * @returns {{classifier: string, extension: string}|undefined} Undefined when
+ *   the name does not belong to the coordinate
+ */
+function splitVerificationArtifactName(fileName, name, version) {
+  const split = splitArtifactFileName(fileName, name, version);
+  if (split) {
+    return split;
+  }
+  if (!version.endsWith("-SNAPSHOT")) {
+    return undefined;
+  }
+  const base = version.slice(0, -"-SNAPSHOT".length);
+  if (!fileName.startsWith(`${name}-${base}`)) {
+    return undefined;
+  }
+  const stamp = SNAPSHOT_STAMP_PATTERN.exec(
+    fileName.substring(`${name}-${base}`.length),
+  );
+  if (!stamp) {
+    return undefined;
+  }
+  return splitArtifactFileName(fileName, name, `${base}${stamp[0]}`);
+}
+
+/**
+ * Keep a checksum value only when it is a hex digest of the exact length its
+ * algorithm produces. The `origin` and `reason` attributes, and the
+ * `also-trust` alternates, are never read.
+ *
+ * @param {string} alg CycloneDX hash algorithm name
+ * @param {number} length Expected hex digest length
+ * @param {object|undefined} element Compact-form checksum element
+ * @returns {{alg: string, content: string}|undefined} The hash, or undefined
+ */
+function verificationHash(alg, length, element) {
+  const value = element?.$?.value;
+  if (typeof value !== "string" || value.length !== length) {
+    return undefined;
+  }
+  if (!HEX_DIGEST_PATTERN.test(value)) {
+    return undefined;
+  }
+  return { alg, content: value.toLowerCase() };
+}
+
+/**
+ * Keep a `pgp value` only when it is a long key id or a v4 fingerprint, in
+ * the upper-case form the verification schema itself uses.
+ *
+ * @param {object|undefined} element Compact-form pgp element
+ * @returns {string|undefined} The key id, or undefined
+ */
+function verificationPgpKeyId(element) {
+  const value = element?.$?.value;
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const keyId = value.trim();
+  if (
+    !PGP_KEY_ID_LENGTHS.has(keyId.length) ||
+    !HEX_DIGEST_PATTERN.test(keyId)
+  ) {
+    return undefined;
+  }
+  return keyId.toUpperCase();
+}
+
+/**
+ * Parse a `gradle/verification-metadata.xml` file.
+ *
+ * The file is untrusted input. It records what Gradle verified when
+ * `gradle --write-verification-metadata` last ran, which does not prove that
+ * the artifacts in this BOM match: the file travels with the source, and
+ * nothing here re-checks the digests. Trust rules (`trusted-artifacts`,
+ * `trusted-keys`, `ignored-keys`) may be regular expressions, so they are
+ * only counted, never evaluated, and no free text of the file (an `origin`, a
+ * `reason`, a key-server URI) reaches the result. Only checksum digests,
+ * PGP key ids and the configuration flags survive.
+ *
+ * The read is bounded: the file must be a regular file no larger than
+ * 32 MiB inside `options.rootDir`, at most 200000 components and 64
+ * artifacts per component are read, and a malformed file yields undefined
+ * rather than an error.
+ *
+ * @param {string} metadataFile Path to verification-metadata.xml
+ * @param {Object} [options] Parse options
+ * @param {string} [options.rootDir] Directory the file must resolve inside
+ * @returns {{configuration: {verifyMetadata: (boolean|undefined), verifySignatures: (boolean|undefined), trustedKeyCount: number, trustedArtifactRuleCount: number, ignoredKeyCount: number, keyServerCount: number}, components: Map<string, {group: string, name: string, version: string, artifacts: {fileName: string, classifier: string, extension: string, hashes: {alg: string, content: string}[], pgpKeyIds: string[]}[]}>}|undefined}
+ *   The parsed metadata, or undefined when the file could not be read
+ */
+export function parseGradleVerificationMetadata(metadataFile, options = {}) {
+  const text = readRegularTextFile(
+    metadataFile,
+    GRADLE_VERIFICATION_METADATA_MAX_BYTES,
+    options?.rootDir,
+  );
+  if (text === undefined) {
+    if (safeExistsSync(metadataFile)) {
+      console.warn(
+        `Skipping ${metadataFile}: it is not a regular file inside the project, or is larger than ${GRADLE_VERIFICATION_METADATA_MAX_BYTES} bytes.`,
+      );
+    }
+    return undefined;
+  }
+  const body = text.startsWith("\uFEFF") ? text.slice(1) : text;
+  let parsed;
+  try {
+    parsed = xml2js(body, {
+      compact: true,
+      ignoreComment: true,
+      ignoreDoctype: true,
+      ignoreDeclaration: true,
+      textKey: "_",
+      attributesKey: "$",
+    });
+  } catch (err) {
+    thoughtLog(
+      `${metadataFile} is not well-formed XML, so it was skipped: ${
+        err?.message || err
+      }`,
+    );
+    return undefined;
+  }
+  // Gradle writes the root element in its own namespace, which a default
+  // namespace leaves off element names and a prefix keeps; both are accepted.
+  // A prefixed document keeps the prefix on the name of every element below
+  // the root, so the prefix is carried into every child lookup below.
+  const rootKey = Object.keys(parsed).find(
+    (key) =>
+      key === "verification-metadata" || key.endsWith(":verification-metadata"),
+  );
+  const root = verificationElementList(
+    rootKey ? parsed[rootKey] : undefined,
+  )[0];
+  if (!root) {
+    thoughtLog(
+      `${metadataFile} has no verification-metadata root element, so it was skipped.`,
+    );
+    return undefined;
+  }
+  const prefix = rootKey?.includes(":")
+    ? rootKey.slice(0, rootKey.indexOf(":") + 1)
+    : "";
+  const configurationElement = verificationChildList(
+    root,
+    "configuration",
+    prefix,
+  )[0];
+  const componentsElement = verificationChildList(
+    root,
+    "components",
+    prefix,
+  )[0];
+  const trustedKeysElement = verificationChildList(
+    configurationElement,
+    "trusted-keys",
+    prefix,
+  )[0];
+  const trustedArtifactsElement = verificationChildList(
+    configurationElement,
+    "trusted-artifacts",
+    prefix,
+  )[0];
+  const ignoredKeysElement = verificationChildList(
+    configurationElement,
+    "ignored-keys",
+    prefix,
+  )[0];
+  const keyServersElement = verificationChildList(
+    configurationElement,
+    "key-servers",
+    prefix,
+  )[0];
+  const components = new Map();
+  let skippedArtifacts = 0;
+  const componentList = verificationChildList(
+    componentsElement,
+    "component",
+    prefix,
+  );
+  for (const componentElement of componentList) {
+    if (components.size === GRADLE_VERIFICATION_METADATA_MAX_COMPONENTS) {
+      thoughtLog(
+        `${metadataFile} lists more than ${GRADLE_VERIFICATION_METADATA_MAX_COMPONENTS} components; only the first ${GRADLE_VERIFICATION_METADATA_MAX_COMPONENTS} are read.`,
+      );
+      break;
+    }
+    const attributes = componentElement?.$ || {};
+    const group =
+      typeof attributes.group === "string" ? attributes.group.trim() : "";
+    const name =
+      typeof attributes.name === "string" ? attributes.name.trim() : "";
+    const version =
+      typeof attributes.version === "string" ? attributes.version.trim() : "";
+    // A coordinate without all three parts, or one no valid purl can be
+    // built for, can never match a component of this BOM.
+    if (!group || !name || !version) {
+      continue;
+    }
+    if (!mavenPurl(group, name, version)) {
+      continue;
+    }
+    const artifacts = [];
+    const artifactList = verificationChildList(
+      componentElement,
+      "artifact",
+      prefix,
+    );
+    if (artifactList.length > GRADLE_VERIFICATION_METADATA_MAX_ARTIFACTS) {
+      skippedArtifacts +=
+        artifactList.length - GRADLE_VERIFICATION_METADATA_MAX_ARTIFACTS;
+    }
+    for (const artifactElement of artifactList.slice(
+      0,
+      GRADLE_VERIFICATION_METADATA_MAX_ARTIFACTS,
+    )) {
+      const fileName =
+        typeof artifactElement?.$?.name === "string"
+          ? artifactElement.$.name.trim()
+          : "";
+      const split = fileName
+        ? splitVerificationArtifactName(fileName, name, version)
+        : undefined;
+      if (!split) {
+        skippedArtifacts++;
+        continue;
+      }
+      const hashes = [];
+      for (const { element, alg, length } of VERIFICATION_HASH_ALGORITHMS) {
+        const hash = verificationHash(
+          alg,
+          length,
+          verificationChildList(artifactElement, element, prefix)[0],
+        );
+        if (hash) {
+          hashes.push(hash);
+        }
+      }
+      const pgpKeyIds = [];
+      for (const pgpElement of verificationChildList(
+        artifactElement,
+        "pgp",
+        prefix,
+      )) {
+        const keyId = verificationPgpKeyId(pgpElement);
+        if (keyId && !pgpKeyIds.includes(keyId)) {
+          pgpKeyIds.push(keyId);
+        }
+      }
+      pgpKeyIds.sort();
+      artifacts.push({
+        fileName,
+        classifier: split.classifier,
+        extension: split.extension,
+        hashes,
+        pgpKeyIds,
+      });
+    }
+    const key = `${group}:${name}:${version}`;
+    if (!components.has(key)) {
+      components.set(key, { group, name, version, artifacts });
+    }
+  }
+  if (skippedArtifacts) {
+    thoughtLog(
+      `Skipped ${skippedArtifacts} artifact element(s) whose file name does not belong to their coordinate in ${metadataFile}.`,
+    );
+  }
+  return {
+    configuration: {
+      verifyMetadata: verificationBoolean(
+        verificationChildList(
+          configurationElement,
+          "verify-metadata",
+          prefix,
+        )[0],
+      ),
+      verifySignatures: verificationBoolean(
+        verificationChildList(
+          configurationElement,
+          "verify-signatures",
+          prefix,
+        )[0],
+      ),
+      trustedKeyCount: verificationChildList(
+        trustedKeysElement,
+        "trusted-key",
+        prefix,
+      ).length,
+      trustedArtifactRuleCount: verificationChildList(
+        trustedArtifactsElement,
+        "trust",
+        prefix,
+      ).length,
+      ignoredKeyCount: verificationChildList(
+        ignoredKeysElement,
+        "ignored-key",
+        prefix,
+      ).length,
+      keyServerCount: verificationChildList(
+        keyServersElement,
+        "key-server",
+        prefix,
+      ).length,
+    },
+    components,
+  };
+}
+
+/**
+ * Find the gradle/verification-metadata.xml of one Gradle build.
+ *
+ * Gradle reads one verification file per build, from the root build's
+ * `gradle` directory; included builds' copies are ignored, so nothing is
+ * searched below the root. The file is accepted only when the directory is a
+ * Gradle project of its own, so a file copied into a nested folder is not
+ * read as an inventory source.
+ *
+ * @param {string} gradleRootPath Root directory of the Gradle build
+ * @returns {string|undefined} The metadata file path, or undefined
+ */
+export function findGradleVerificationMetadata(gradleRootPath) {
+  const metadataFile = join(
+    gradleRootPath,
+    "gradle",
+    "verification-metadata.xml",
+  );
+  if (!safeExistsSync(metadataFile)) {
+    return undefined;
+  }
+  if (
+    !GRADLE_PROJECT_MARKERS.some((marker) =>
+      safeExistsSync(join(gradleRootPath, marker)),
+    )
+  ) {
+    return undefined;
+  }
+  return metadataFile;
+}
+
+/**
+ * The artifact of a coordinate whose hashes describe the component itself:
+ * the `.pom` artifact for a platform or BOM component, else the main jar,
+ * else the main aar. Sources, javadoc and other classifiers, and the
+ * `.module` and `.pom` hashes of a jar component, are never used.
+ *
+ * @param {object} component Parsed verification metadata component
+ * @param {boolean} wantsPom True for a component with purl qualifier type=pom
+ * @returns {object|undefined} The artifact, or undefined
+ */
+export function gradleVerificationMainArtifact(component, wantsPom) {
+  const wanted = wantsPom ? "pom" : "jar";
+  const main = component.artifacts.find(
+    (artifact) => !artifact.classifier && artifact.extension === wanted,
+  );
+  if (main || wantsPom) {
+    return main;
+  }
+  return component.artifacts.find(
+    (artifact) => !artifact.classifier && artifact.extension === "aar",
+  );
+}
+
+/**
+ * Merge the checksums and PGP key ids a verification-metadata.xml records
+ * into the components of a package list.
+ *
+ * A digest of the artifact itself, computed from the jar in the local cache
+ * or found by another collector, is the stronger claim, so the recorded
+ * digests only fill the algorithms a component still lacks. Where the file
+ * records a different digest for an algorithm the component already has,
+ * the recorded digest never wins: the component keeps its own, and the
+ * component gains the cdx:gradle:verificationMismatch=true property so the
+ * disagreement is visible. A released Maven version does not change after
+ * publishing, so a stale file cannot explain a mismatch: a stale file names
+ * old versions, which match nothing. The likely causes are an artifact
+ * republished on a mirror or internal repository, or a corrupted or
+ * tampered cache. SNAPSHOT versions and digests that are not hex are not
+ * compared.
+ *
+ * Every matched component also gains two properties naming the verification
+ * methods and the PGP key ids of its artifact. The evidence of the
+ * component is left alone: a component found by a Gradle run or a lockfile
+ * keeps the identity evidence of that source, and only the components the
+ * verification-metadata fallback built carry the file as their evidence.
+ *
+ * @param {Object[]} pkgList Components to enrich in place
+ * @param {Object} metadata Parsed metadata, as parseGradleVerificationMetadata
+ *   returns
+ * @param {string} metadataFile Path to the verification-metadata.xml, named
+ *   in the debug reasoning
+ * @returns {number} The number of components this call changed
+ */
+export function applyGradleVerificationMetadata(
+  pkgList,
+  metadata,
+  metadataFile,
+) {
+  if (!metadata?.components?.size) {
+    return 0;
+  }
+  let changedCount = 0;
+  for (const pkg of pkgList || []) {
+    if (!pkg?.purl?.startsWith("pkg:maven/")) {
+      continue;
+    }
+    const component = metadata.components.get(
+      `${pkg.group}:${pkg.name}:${pkg.version}`,
+    );
+    if (!component) {
+      continue;
+    }
+    const artifact = gradleVerificationMainArtifact(
+      component,
+      pkg.qualifiers?.type === "pom",
+    );
+    if (!artifact) {
+      continue;
+    }
+    const hashesBefore = pkg.hashes;
+    const propertiesBefore = pkg.properties;
+    // A SNAPSHOT version names a moving artifact: the file can record
+    // several timestamped builds of it while the cache holds the newest, so
+    // a differing digest there says nothing about tampering.
+    const comparable = !String(pkg.version || "").endsWith("-SNAPSHOT");
+    // The merged list keeps the order the component's own hashes came in
+    // and appends the recorded ones in the schema's algorithm order.
+    const hashes = Array.isArray(pkg.hashes) ? [...pkg.hashes] : [];
+    let mismatch = false;
+    for (const recorded of artifact.hashes) {
+      const existing = hashes.find((hash) => hash.alg === recorded.alg);
+      if (existing) {
+        // Other collectors may carry an upper-case or base64 digest; only a
+        // hex digest can be compared with the recorded one.
+        const existingContent =
+          typeof existing.content === "string" ? existing.content : "";
+        if (
+          comparable &&
+          HEX_DIGEST_PATTERN.test(existingContent) &&
+          existingContent.toLowerCase() !== recorded.content
+        ) {
+          mismatch = true;
+          thoughtLog(
+            `${metadataFile} records a different ${recorded.alg} digest for ${pkg.group}:${pkg.name}:${pkg.version} than the artifact carries; the recorded digest is flagged, not applied.`,
+          );
+        }
+        continue;
+      }
+      hashes.push({ alg: recorded.alg, content: recorded.content });
+    }
+    if (hashes.length && hashes.length !== (pkg.hashes?.length || 0)) {
+      pkg.hashes = hashes;
+    }
+    const methods = new Set();
+    for (const { element, alg } of VERIFICATION_HASH_ALGORITHMS) {
+      if (artifact.hashes.some((hash) => hash.alg === alg)) {
+        methods.add(element);
+      }
+    }
+    if (artifact.pgpKeyIds.length) {
+      methods.add("pgp");
+    }
+    const properties = pkg.properties || [];
+    if (
+      methods.size &&
+      !properties.some((p) => p.name === "cdx:gradle:verificationMethods")
+    ) {
+      properties.push({
+        name: "cdx:gradle:verificationMethods",
+        value: [...methods].sort().join(","),
+      });
+    }
+    if (
+      artifact.pgpKeyIds.length &&
+      !properties.some((p) => p.name === "cdx:gradle:pgpKeyIds")
+    ) {
+      properties.push({
+        name: "cdx:gradle:pgpKeyIds",
+        value: [...new Set(artifact.pgpKeyIds)].sort().slice(0, 10).join(","),
+      });
+    }
+    if (
+      mismatch &&
+      !properties.some((p) => p.name === "cdx:gradle:verificationMismatch")
+    ) {
+      properties.push({
+        name: "cdx:gradle:verificationMismatch",
+        value: "true",
+      });
+    }
+    if (properties.length !== (pkg.properties?.length || 0)) {
+      pkg.properties = properties;
+    }
+    if (pkg.hashes !== hashesBefore || pkg.properties !== propertiesBefore) {
+      changedCount++;
+    }
+  }
+  return changedCount;
+}