@cdxgen/cdxgen 13.0.1 → 13.2.0

package/lib/ecosystems/gradleutils.js

@@ -1,22 +1,43 @@
 import { Buffer } from "node:buffer";
-import { chmodSync } from "node:fs";
+import { chmodSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { basename, join, resolve } from "node:path";
 
 import { build } from "@cdxgen/cdx-purl";
+import * as toml from "smol-toml";
 
 import {
   DEBUG_MODE,
   readEnvironmentVariable,
   recordDecisionActivity,
 } from "../core/activity.js";
+import {
+  commandOutputText,
+  isLedgerEnabled,
+  LEDGER_EVENT_IMPACTS,
+  LEDGER_EVENT_KINDS,
+  recordDegradation,
+  recordLedgerEvent,
+} from "../core/buildLedger.js";
 import { getAllFiles, safeExistsSync, safeSpawnSync } from "../core/fs.js";
 import { thoughtLog } from "../core/logger.js";
 import { isWin } from "../core/paths.js";
 import { collectJarNS } from "../inventory/deps.js";
-import { applyPurl } from "../inventory/purl.js";
+import { minimumGradleVersionForJava } from "../inventory/jvmToolEnv.js";
+import { applyPurl, tryBuildPurl } from "../inventory/purl.js";
 import { parsePkgJson } from "./parsers-js.js";
 
+/**
+ * True when the pre-generation stage pinned an exact JVM build tool version
+ * from the CLI (e.g. `-t maven3.9.9`). Project wrappers must not override
+ * such an explicit pin.
+ */
+function isJvmToolPinned() {
+  return ["true", "1"].includes(
+    readEnvironmentVariable("CDXGEN_JVM_TOOL_PINNED"),
+  );
+}
+
 /**
  * Method to return the gradle command to use.
  *
@@ -25,19 +46,21 @@ import { parsePkgJson } from "./parsers-js.js";
  */
 export function getGradleCommand(srcPath, rootPath) {
   let gradleCmd = "gradle";
+  const pinnedToolSelected = isJvmToolPinned();
 
   let findGradleFile = "gradlew";
   if (platform() === "win32") {
     findGradleFile = "gradlew.bat";
   }
 
-  if (safeExistsSync(join(srcPath, findGradleFile))) {
+  if (!pinnedToolSelected && safeExistsSync(join(srcPath, findGradleFile))) {
     // Use local gradle wrapper if available
     // Enable execute permission
     try {
       chmodSync(join(srcPath, findGradleFile), 0o775);
     } catch (_e) {
-      // continue regardless of error
+      // The wrapper stays un-chmod'ed; the spawn below still reports any
+      // permission failure as a normal command failure.
     }
     gradleCmd = resolve(join(srcPath, findGradleFile));
     recordDecisionActivity(gradleCmd, {
@@ -48,12 +71,17 @@ export function getGradleCommand(srcPath, rootPath) {
       },
       reason: `Selected project-local Gradle wrapper ${gradleCmd}.`,
     });
-  } else if (rootPath && safeExistsSync(join(rootPath, findGradleFile))) {
+  } else if (
+    !pinnedToolSelected &&
+    rootPath &&
+    safeExistsSync(join(rootPath, findGradleFile))
+  ) {
     // Check if the root directory has a wrapper script
     try {
       chmodSync(join(rootPath, findGradleFile), 0o775);
     } catch (_e) {
-      // continue regardless of error
+      // The wrapper stays un-chmod'ed; the spawn below still reports any
+      // permission failure as a normal command failure.
     }
     gradleCmd = resolve(join(rootPath, findGradleFile));
     recordDecisionActivity(gradleCmd, {
@@ -69,10 +97,12 @@ export function getGradleCommand(srcPath, rootPath) {
     recordDecisionActivity(gradleCmd, {
       metadata: {
         decisionType: "path-resolution",
-        selectedSource: "GRADLE_CMD",
+        selectedSource: pinnedToolSelected ? "pinned-cli" : "GRADLE_CMD",
         tool: "gradle",
       },
-      reason: `Selected Gradle command from GRADLE_CMD (${gradleCmd}).`,
+      reason: pinnedToolSelected
+        ? `Selected Gradle command ${gradleCmd} pinned via the CLI project type.`
+        : `Selected Gradle command from GRADLE_CMD (${gradleCmd}).`,
     });
   } else if (readEnvironmentVariable("GRADLE_HOME")) {
     gradleCmd = join(readEnvironmentVariable("GRADLE_HOME"), "bin", "gradle");
@@ -93,6 +123,16 @@ export function getGradleCommand(srcPath, rootPath) {
       },
       reason: "Falling back to Gradle from PATH.",
     });
+    // A Gradle from PATH is a sound outcome whenever its version satisfies
+    // the wrapper pin, so the fallback is recorded as costing nothing.
+    recordLedgerEvent(LEDGER_EVENT_KINDS.FALLBACK_ENGAGED, {
+      ecosystem: "java",
+      tool: "gradle",
+      source: "PATH",
+      impact: LEDGER_EVENT_IMPACTS.NONE,
+      detail:
+        "No wrapper, GRADLE_CMD, or GRADLE_HOME was found; Gradle will run from PATH.",
+    });
   }
   return gradleCmd;
 }
@@ -368,6 +408,9 @@ export function executeParallelGradleProperties(
       shell: isWin,
     });
     if (result.status !== 0 || result.error) {
+      recordGradleInvocationFailure(result, {
+        command: `${basename(gradleCmd)} ${gradleArg.join(" ")}`,
+      });
       if (readEnvironmentVariable("CDXGEN_IN_CONTAINER") === "true") {
         thoughtLog(
           "Gradle build has failed. Perhaps the user is using the wrong container image?",
@@ -420,6 +463,279 @@ export function executeParallelGradleProperties(
   return "";
 }
 
+/** First class-file major a JDK maps from: class file 52 is Java 8. */
+const CLASS_FILE_MAJOR_OFFSET = 44;
+
+/**
+ * Causes already reported this run, so a properties invocation and a
+ * dependencies invocation failing for the same reason record the diagnosis
+ * once.
+ *
+ * @type {Set<string>}
+ */
+const reportedGradleFailureCauses = new Set();
+
+/** Whether an invocation failure was recorded this run. */
+let gradleInvocationFailed = false;
+
+/**
+ * Forget the causes diagnosed so far, so a process that generates more than
+ * one BOM diagnoses each run on its own.
+ *
+ * @returns {void}
+ */
+export function resetGradleFailureCauses() {
+  reportedGradleFailureCauses.clear();
+  gradleInvocationFailed = false;
+}
+
+/**
+ * Whether a gradle invocation has already failed outright this run, so a
+ * caller can skip reporting a consequence of that failure as its own
+ * degradation.
+ *
+ * @returns {boolean} True once an invocation failure has been recorded.
+ */
+export function hasGradleInvocationFailure() {
+  return gradleInvocationFailed;
+}
+
+/**
+ * Extract the Java major from an `Unsupported class file major version N`
+ * message: the class file the running JVM refused, which names the JDK that
+ * is too new for this Gradle.
+ *
+ * @param {string} text Combined gradle output.
+ * @returns {number|undefined} The refused Java major, when named.
+ */
+function refusedJavaMajorFromMessage(text) {
+  const marker = "Unsupported class file major version ";
+  const start = text.indexOf(marker);
+  if (start === -1) {
+    return undefined;
+  }
+  const digits = text
+    .slice(start + marker.length)
+    .split(/\s|\.|,|\r|\n/)[0]
+    .trim();
+  const major = Number.parseInt(digits, 10);
+  return Number.isNaN(major) ? undefined : major - CLASS_FILE_MAJOR_OFFSET;
+}
+
+/**
+ * Extract the Java pair the modern launcher refusal names: the JVM major
+ * Gradle demands and, when the message says so, the one the build is
+ * configured to use. Anything the message does not clearly name stays
+ * undefined — the demanded major is substituted into an install command, so
+ * it must be a bare Java major and nothing else.
+ *
+ * @param {string} text Combined gradle output.
+ * @returns {{wanted: number, found: number|undefined}|undefined} The required and running Java majors, when the refusal names them.
+ */
+function javaPairFromLauncherDemand(text) {
+  const demandMarker = "Gradle requires JVM ";
+  const demandStart = text.indexOf(demandMarker);
+  if (demandStart === -1) {
+    return undefined;
+  }
+  const wantedDigits = text
+    .slice(demandStart + demandMarker.length)
+    .split(/\s|\.|,|\r|\n/)[0]
+    .trim();
+  const wanted = Number.parseInt(wantedDigits, 10);
+  if (Number.isNaN(wanted)) {
+    return undefined;
+  }
+  const foundMarker = "configured to use JVM ";
+  const foundStart = text.indexOf(foundMarker);
+  let found;
+  if (foundStart !== -1) {
+    const foundDigits = text
+      .slice(foundStart + foundMarker.length)
+      .split(/\s|\.|,|\r|\n/)[0]
+      .trim();
+    const parsed = Number.parseInt(foundDigits, 10);
+    if (!Number.isNaN(parsed)) {
+      found = parsed;
+    }
+  }
+  return { wanted, found };
+}
+
+/**
+ * Extract the Java pair an `UnsupportedClassVersionError` names: the class
+ * file version that was compiled for a newer JDK and the version the running
+ * JDK recognises, so the event can say "needs Java A, found Java B".
+ *
+ * @param {string} text Combined gradle output.
+ * @returns {{wanted: number, found: number}|undefined} The required and running Java majors.
+ */
+function javaPairFromClassVersionError(text) {
+  if (!text.includes("UnsupportedClassVersionError")) {
+    return undefined;
+  }
+  const compiledMarker = "class file version ";
+  const compiledStart = text.indexOf(compiledMarker);
+  const limitMarker = "recognizes class file versions up to ";
+  const limitStart = text.indexOf(limitMarker);
+  if (compiledStart === -1 || limitStart === -1) {
+    return { wanted: Number.NaN, found: Number.NaN };
+  }
+  const wanted = Number.parseInt(
+    text.slice(compiledStart + compiledMarker.length).trim(),
+    10,
+  );
+  const found = Number.parseInt(
+    text.slice(limitStart + limitMarker.length).trim(),
+    10,
+  );
+  return {
+    wanted: wanted - CLASS_FILE_MAJOR_OFFSET,
+    found: found - CLASS_FILE_MAJOR_OFFSET,
+  };
+}
+
+/**
+ * Record why a gradle invocation failed. Every failure also records the
+ * `jvm.gradle.invocation-failed` degradation so the reflection can rank the
+ * repair; version-incompatibility causes additionally record a
+ * `tool.mismatch` event naming the versions, which is the fact the report
+ * cannot derive from an empty BOM alone. Diagnosis events are recorded once
+ * per cause per run; the degradation dedupes in the reflection by id.
+ *
+ * @param {Object} result The spawnSync result of the failed invocation.
+ * @param {Object} context Call-site facts.
+ * @param {string} [context.command] The redacted command that was attempted.
+ * @param {string} [context.gradleVersion] The gradle version in play, when the caller knows it.
+ * @returns {void}
+ */
+export function recordGradleInvocationFailure(result, context = {}) {
+  if (!isLedgerEnabled()) {
+    return;
+  }
+  if (!result || (result.status === 0 && !result.error)) {
+    return;
+  }
+  const output = `${result.stderr || ""}\n${result.stdout || ""}`;
+  const exitCode =
+    typeof result.status === "number" ? result.status : undefined;
+  let causeDetail = "the gradle invocation failed";
+
+  // The JDK is too new for this Gradle: the build script or the launcher
+  // refuses its class files. Gradle's own compatibility table names the
+  // minimum release that runs on the refused Java major.
+  const refusedJavaMajor = refusedJavaMajorFromMessage(output);
+  // Gradle's own modern refusal, which names the JVM it demands before any
+  // class file is loaded.
+  const launcherDemand =
+    refusedJavaMajor === undefined
+      ? javaPairFromLauncherDemand(output)
+      : undefined;
+  if (refusedJavaMajor !== undefined) {
+    const minimumGradle = minimumGradleVersionForJava(refusedJavaMajor);
+    const causeKey = `java-too-new:${refusedJavaMajor}`;
+    if (!reportedGradleFailureCauses.has(causeKey)) {
+      reportedGradleFailureCauses.add(causeKey);
+      recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_MISMATCH, {
+        ecosystem: "java",
+        tool: "gradle",
+        wanted: minimumGradle ? `${minimumGradle}` : undefined,
+        found: context.gradleVersion,
+        source: "invocation",
+        detail: minimumGradle
+          ? `Gradle cannot run on Java ${refusedJavaMajor} and refused its class files; Gradle ${minimumGradle} or higher supports it.`
+          : `Gradle cannot run on Java ${refusedJavaMajor} and refused its class files.`,
+      });
+    }
+    causeDetail = `gradle cannot run on Java ${refusedJavaMajor}`;
+  } else if (launcherDemand) {
+    // The demand names the JDK Gradle needs; the JVM that answered it is
+    // the one the build was configured to use.
+    const causeKey = `jvm-demanded:${launcherDemand.wanted}:${launcherDemand.found}`;
+    if (!reportedGradleFailureCauses.has(causeKey)) {
+      reportedGradleFailureCauses.add(causeKey);
+      recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_MISMATCH, {
+        ecosystem: "java",
+        tool: "java",
+        wanted: `${launcherDemand.wanted}`,
+        found:
+          launcherDemand.found === undefined
+            ? undefined
+            : `${launcherDemand.found}`,
+        source: "invocation",
+        detail:
+          launcherDemand.found === undefined
+            ? `Gradle requires Java ${launcherDemand.wanted} or later to run.`
+            : `Gradle requires Java ${launcherDemand.wanted} or later to run; the active JVM is Java ${launcherDemand.found}.`,
+      });
+    }
+    causeDetail = "the gradle launcher requires a newer JDK";
+  } else {
+    // The opposite skew: Gradle (or its wrapper) is compiled for a newer JDK
+    // than the running one, so the JVM refuses to load it.
+    const javaPair = javaPairFromClassVersionError(output);
+    if (javaPair) {
+      const causeKey = `jvm-too-old:${javaPair.wanted}:${javaPair.found}`;
+      if (!reportedGradleFailureCauses.has(causeKey)) {
+        reportedGradleFailureCauses.add(causeKey);
+        recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_MISMATCH, {
+          ecosystem: "java",
+          tool: "java",
+          wanted: Number.isNaN(javaPair.wanted)
+            ? undefined
+            : `${javaPair.wanted}`,
+          found: Number.isNaN(javaPair.found) ? undefined : `${javaPair.found}`,
+          source: "invocation",
+          detail: `The gradle launcher requires Java ${Number.isNaN(javaPair.wanted) ? "a newer release" : javaPair.wanted}; the active JDK is older and refused its class files.`,
+        });
+      }
+      causeDetail = "the gradle launcher requires a newer JDK";
+    } else if (output.includes("JAVA_HOME is set to an invalid directory")) {
+      const causeKey = "invalid-java-home";
+      if (!reportedGradleFailureCauses.has(causeKey)) {
+        reportedGradleFailureCauses.add(causeKey);
+        recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_MISSING, {
+          ecosystem: "java",
+          tool: "java",
+          source: "JAVA_HOME",
+          detail:
+            "JAVA_HOME names a directory that does not hold a JDK, so the gradle launcher refused to start.",
+        });
+      }
+      causeDetail = "JAVA_HOME does not point at a JDK";
+    } else if (
+      output.includes("Could not start Gradle Daemon") ||
+      output.includes("Daemon could not be started") ||
+      output.includes("could not install Gradle distribution")
+    ) {
+      const causeKey = "daemon-start";
+      if (!reportedGradleFailureCauses.has(causeKey)) {
+        reportedGradleFailureCauses.add(causeKey);
+        recordLedgerEvent(LEDGER_EVENT_KINDS.EVIDENCE_DEGRADED, {
+          ecosystem: "java",
+          tool: "gradle",
+          impact: LEDGER_EVENT_IMPACTS.VERSIONS,
+          detail:
+            "The gradle daemon did not start, so no dependency resolution ran.",
+        });
+      }
+      causeDetail = "the gradle daemon did not start";
+    }
+  }
+
+  gradleInvocationFailed = true;
+  recordDegradation("jvm.gradle.invocation-failed", {
+    ecosystem: "java",
+    tool: "gradle",
+    impact: LEDGER_EVENT_IMPACTS.TRANSITIVE_DEPS,
+    command: context.command,
+    exitCode,
+    detail: causeDetail,
+    causeDetail,
+    outputExcerpt: commandOutputText(result),
+  });
+}
+
 /**
  * Method to resolve dependencies from a gradle output
  *
@@ -583,6 +899,8 @@ export async function parseGradleDep(
               });
               bomRef = decodeURIComponent(purl);
             } catch {
+              // A purl that cannot be built keeps a name-only bom-ref so the
+              // component still lands in the graph.
               purl = undefined;
               bomRef = name.replace(/^:/, "");
             }
@@ -724,6 +1042,7 @@ export async function buildObjectForGradleModule(name, metadata) {
       });
       applyPurl(component, purl);
     } catch {
+      // The module component keeps its name identity without a purl.
       applyPurl(component, null);
     }
   }
@@ -896,7 +1215,8 @@ export function getMillCommand(srcPath) {
     try {
       chmodSync(join(srcPath, millCmd), 0o775);
     } catch (_e) {
-      // continue regardless of error
+      // The mill wrapper stays un-chmod'ed; the spawn below still reports any
+      // permission failure as a normal command failure.
     }
     millCmd = resolve(join(srcPath, millCmd));
   }
@@ -914,6 +1234,7 @@ export function getMavenCommand(srcPath, rootPath) {
   // Check if the wrapper script is both available and functional
   let isWrapperReady = false;
   let isWrapperFound = false;
+  const pinnedToolSelected = isJvmToolPinned();
   let findMavenFile = "mvnw";
   let mavenWrapperCmd = null;
   if (platform() === "win32") {
@@ -926,13 +1247,14 @@ export function getMavenCommand(srcPath, rootPath) {
     }
   }
 
-  if (safeExistsSync(join(srcPath, findMavenFile))) {
+  if (!pinnedToolSelected && safeExistsSync(join(srcPath, findMavenFile))) {
     // Use local maven wrapper if available
     // Enable execute permission
     try {
       chmodSync(join(srcPath, findMavenFile), 0o775);
     } catch (_e) {
-      // continue regardless of error
+      // The wrapper stays un-chmod'ed; the spawn below still reports any
+      // permission failure as a normal command failure.
     }
     mavenWrapperCmd = resolve(join(srcPath, findMavenFile));
     isWrapperFound = true;
@@ -944,12 +1266,17 @@ export function getMavenCommand(srcPath, rootPath) {
       },
       reason: `Found Maven wrapper candidate ${mavenWrapperCmd}.`,
     });
-  } else if (rootPath && safeExistsSync(join(rootPath, findMavenFile))) {
+  } else if (
+    !pinnedToolSelected &&
+    rootPath &&
+    safeExistsSync(join(rootPath, findMavenFile))
+  ) {
     // Check if the root directory has a wrapper script
     try {
       chmodSync(join(rootPath, findMavenFile), 0o775);
     } catch (_e) {
-      // continue regardless of error
+      // The wrapper stays un-chmod'ed; the spawn below still reports any
+      // permission failure as a normal command failure.
     }
     mavenWrapperCmd = resolve(join(rootPath, findMavenFile));
     isWrapperFound = true;
@@ -1016,12 +1343,16 @@ export function getMavenCommand(srcPath, rootPath) {
       recordDecisionActivity(mavenCmd, {
         metadata: {
           decisionType: "path-resolution",
-          selectedSource: readEnvironmentVariable("MVN_CMD")
-            ? "MVN_CMD"
-            : "MAVEN_CMD",
+          selectedSource: pinnedToolSelected
+            ? "pinned-cli"
+            : readEnvironmentVariable("MVN_CMD")
+              ? "MVN_CMD"
+              : "MAVEN_CMD",
           tool: "maven",
         },
-        reason: `Selected Maven command from environment (${mavenCmd}).`,
+        reason: pinnedToolSelected
+          ? `Selected Maven command ${mavenCmd} pinned via the CLI project type.`
+          : `Selected Maven command from environment (${mavenCmd}).`,
       });
     } else if (readEnvironmentVariable("MAVEN_HOME")) {
       mavenCmd = join(readEnvironmentVariable("MAVEN_HOME"), "bin", "mvn");
@@ -1042,7 +1373,157 @@ export function getMavenCommand(srcPath, rootPath) {
         },
         reason: "Falling back to Maven from PATH.",
       });
+      // A Maven from PATH is a sound outcome whenever its version satisfies
+      // the wrapper pin, so the fallback is recorded as costing nothing.
+      recordLedgerEvent(LEDGER_EVENT_KINDS.FALLBACK_ENGAGED, {
+        ecosystem: "java",
+        tool: "maven",
+        source: "PATH",
+        impact: LEDGER_EVENT_IMPACTS.NONE,
+        detail:
+          "No wrapper, MVN_CMD/MAVEN_CMD, or MAVEN_HOME was found; Maven will run from PATH.",
+      });
     }
   }
   return mavenCmd;
 }
+
+/**
+ * Parse a Gradle version catalog (`gradle/libs.versions.toml`).
+ *
+ * A catalog declares coordinates the build scripts then reference by alias.
+ * It is a declaration, not a resolution: entries may go unused, and their
+ * versions may be references into the `[versions]` table. Because of that,
+ * catalog components are emitted only as a fallback when Gradle itself
+ * produced no dependency information, and every component carries a
+ * `cdx:gradle:catalog=true` property so consumers can tell declared catalog
+ * entries from a resolved graph.
+ *
+ * Only libraries whose version resolves to a literal (inline or via
+ * `version.ref`) are emitted; rich or unresolved versions would produce purls
+ * that identify no artifact. Plugins are skipped because they are build-time
+ * only.
+ *
+ * @param {string} catalogFile Path to `libs.versions.toml`
+ * @returns {Object[]} Package records for resolvable library entries
+ */
+export function parseGradleVersionCatalog(catalogFile) {
+  let catalog;
+  try {
+    catalog = toml.parse(readFileSync(catalogFile, "utf-8"));
+  } catch (error) {
+    console.warn(`Failed to parse ${catalogFile}: ${error.message}`);
+    return [];
+  }
+  const versions =
+    catalog?.versions && typeof catalog.versions === "object"
+      ? catalog.versions
+      : {};
+  const libraries =
+    catalog?.libraries && typeof catalog.libraries === "object"
+      ? catalog.libraries
+      : {};
+  const pkgList = [];
+  for (const entry of Object.values(libraries)) {
+    const coordinate = catalogCoordinate(entry);
+    if (!coordinate) {
+      continue;
+    }
+    const version = resolveCatalogVersion(entry, versions);
+    if (!version) {
+      continue;
+    }
+    const { group, name } = coordinate;
+    // A catalog is authored input, but a malformed coordinate must cost the
+    // one entry, not the whole scan.
+    const purl = tryBuildPurl({
+      type: "maven",
+      namespace: group,
+      name,
+      version,
+    });
+    if (!purl) {
+      continue;
+    }
+    pkgList.push({
+      group,
+      name,
+      version,
+      type: "library",
+      scope: "required",
+      purl,
+      "bom-ref": decodeURIComponent(purl),
+      properties: [
+        { name: "internal:SrcFile", value: catalogFile },
+        { name: "cdx:gradle:catalog", value: "true" },
+      ],
+      evidence: {
+        identity: {
+          field: "purl",
+          confidence: 0.5,
+          methods: [
+            {
+              technique: "source-code-analysis",
+              confidence: 0.5,
+              value: `Filename ${catalogFile}`,
+            },
+          ],
+        },
+      },
+    });
+  }
+  return pkgList;
+}
+
+/**
+ * Read the Maven coordinate of one catalog entry.
+ *
+ * A catalog writes the coordinate either as `module = "group:name"` or as a
+ * separate `group` and `name` pair; both forms are equivalent and both appear
+ * in real catalogs.
+ *
+ * @param {object} entry Catalog library entry
+ * @returns {{group: string, name: string}|undefined} Coordinate, or undefined
+ */
+function catalogCoordinate(entry) {
+  const module = typeof entry?.module === "string" ? entry.module : undefined;
+  if (module?.includes(":")) {
+    const separator = module.indexOf(":");
+    return {
+      group: module.slice(0, separator),
+      name: module.slice(separator + 1),
+    };
+  }
+  if (typeof entry?.group === "string" && typeof entry?.name === "string") {
+    return { group: entry.group, name: entry.name };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the version of one catalog entry.
+ *
+ * An entry may pin `version = "1.2.3"` directly or reference the versions
+ * table with `version.ref = "alias"`. Version references that are missing, or
+ * that carry Gradle rich-version syntax (ranges, `!!`, separators), resolve
+ * to nothing and the entry is skipped.
+ *
+ * @param {object} entry Catalog library entry
+ * @param {object} versions Parsed `[versions]` table
+ * @returns {string|undefined} Concrete version, or undefined
+ */
+function resolveCatalogVersion(entry, versions) {
+  const raw =
+    typeof entry?.version === "string"
+      ? entry.version
+      : typeof entry?.version?.ref === "string"
+        ? versions[entry.version.ref]
+        : undefined;
+  if (typeof raw !== "string" || !raw) {
+    return undefined;
+  }
+  if (/[[\](),!]|->|\.\./u.test(raw)) {
+    return undefined;
+  }
+  return raw;
+}