@cdxgen/cdxgen 13.0.0 → 13.1.0

package/lib/core/ui.js

@@ -17,6 +17,7 @@ import process from "node:process";
 import { formatWithOptions, inspect } from "node:util";
 
 import { readEnvironmentVariable } from "./activity.js";
+import { diagnosticStream, TRACE_MODE, traceLog } from "./logger.js";
 import { stringWidth, stripAnsi } from "./text.js";
 
 // Frame interval, and the floor on how often detail/progress updates redraw.
@@ -94,7 +95,11 @@ const PHASE_OUTCOMES = {
  * @returns {{stream: object, interactive: boolean, color: boolean, unicode: boolean, glyphs: object, columns: () => number, rows: () => number}} Capability snapshot
  */
 export function detectCapabilities(overrides = {}) {
-  const stream = overrides.stream || process.stderr;
+  // `CDXGEN_LOG_STREAM=stdout` is the documented escape hatch for callers that
+  // scraped v12's stdout. Resolving the destination here rather than pinning
+  // stderr is what makes it apply to the region, the banners and the tables
+  // instead of only to the thought and trace logs.
+  const stream = overrides.stream || diagnosticStream;
   const env = overrides.env;
   const read = (name) => (env ? env[name] : readEnvironmentVariable(name));
   const isSet = (name) => {
@@ -282,7 +287,7 @@ function formatArgs(args) {
  * Create a live-region controller.
  *
  * @param {object} [options] Controller options
- * @param {object} [options.stream] Writable stream (default `process.stderr`)
+ * @param {object} [options.stream] Writable stream (default: the diagnostic stream, stderr unless `CDXGEN_LOG_STREAM=stdout`)
  * @param {number|string} [options.level] Verbosity ladder 0..3
  * @param {("text"|"json")} [options.format] Log serialization format
  * @param {boolean} [options.noProgress] Force-disable the live region
@@ -538,6 +543,40 @@ export function createUi(options = {}) {
     }
   }
 
+  /**
+   * Mirror a phase transition onto the trace stream.
+   *
+   * The live region is a terminal affordance, so a piped consumer such as the
+   * cdxui terminal UI would otherwise have to scrape formatted lines to learn
+   * what cdxgen is doing. Emitting the phase model structurally lets it render
+   * its own progress. `progress` transitions are throttled to the frame
+   * interval so a per-file loop costs one event per frame, not one per file.
+   *
+   * @param {object} handle Phase handle
+   * @param {string} state One of started, progress, succeeded, failed, skipped
+   */
+  function tracePhase(handle, state) {
+    if (!TRACE_MODE) {
+      return;
+    }
+    const at = now();
+    if (state === "progress") {
+      if (at - (handle.tracedAt || 0) < REFRESH_MS) {
+        return;
+      }
+      handle.tracedAt = at;
+    }
+    traceLog("phase", {
+      phase: handle.label,
+      state,
+      detail: handle.detailText ?? undefined,
+      note: handle.note ?? undefined,
+      done: handle.total > 0 ? handle.done : undefined,
+      total: handle.total > 0 ? handle.total : undefined,
+      elapsedMs: at - handle.startedAt,
+    });
+  }
+
   function commitPhase(phase) {
     const outcome = PHASE_OUTCOMES[phase.status] || PHASE_OUTCOMES.succeeded;
     const glyph = caps.glyphs[phase.status] || caps.glyphs.succeeded;
@@ -568,6 +607,7 @@ export function createUi(options = {}) {
       startedAt: now(),
       note: null,
       committed: false,
+      tracedAt: 0,
 
       /**
        * Replace the trailing detail text on this phase's row.
@@ -578,6 +618,7 @@ export function createUi(options = {}) {
       detail(text) {
         if (!this.committed) {
           this.detailText = text ? `${text}` : null;
+          tracePhase(this, "progress");
           requestRender();
         }
         return this;
@@ -594,6 +635,7 @@ export function createUi(options = {}) {
         if (!this.committed) {
           this.done = Number(done) || 0;
           this.total = Number(total) || 0;
+          tracePhase(this, "progress");
           requestRender();
         }
         return this;
@@ -631,6 +673,7 @@ export function createUi(options = {}) {
       },
     };
     running.push(handle);
+    tracePhase(handle, "started");
     startTimer();
     requestRender(true);
     return handle;
@@ -643,6 +686,7 @@ export function createUi(options = {}) {
     handle.committed = true;
     handle.status = status;
     handle.note = note ? `${note}` : null;
+    tracePhase(handle, status);
     const index = running.indexOf(handle);
     if (index >= 0) {
       running.splice(index, 1);

package/lib/ecosystems/ecosystems.js

@@ -80,6 +80,10 @@ import {
 } from "../inventory/spdx.js";
 import { extractLicenseText, extractRepoUrl } from "../parsers/htmlExtract.js";
 import { xml2js } from "../parsers/xml.js";
+import {
+  applyPypiClassifierMetadata,
+  applyPypiModuleNames,
+} from "./pypiClassifiers.js";
 import {
   collectCargoRegistryProvenanceProperties,
   collectNpmRegistryProvenanceProperties,
@@ -950,6 +954,10 @@ export async function getPyMetadata(pkgList, fetchDepsInfo) {
       continue;
     }
     try {
+      // Module names are derived from the distribution name and the curated alias
+      // map, so they are available without a registry round trip and are attached
+      // before the skip below rather than after it.
+      applyPypiModuleNames(p);
       // If the package name has a url or already includes license and version skip it
       if (p.name.includes("https") || (p.license && p.version)) {
         cdepList.push(p);
@@ -1011,6 +1019,7 @@ export async function getPyMetadata(pkgList, fetchDepsInfo) {
             }
           }
         }
+        applyPypiClassifierMetadata(p, body.info.classifiers);
       }
       if (body.info.license) {
         const licenseId = findLicenseId(body.info.license);

package/lib/ecosystems/gradleutils.js

@@ -10,13 +10,33 @@ import {
   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 { minimumGradleVersionForJava } from "../inventory/jvmToolEnv.js";
 import { applyPurl } 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 +45,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 +70,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 +96,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 +122,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 +407,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 +462,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 +898,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 +1041,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 +1214,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 +1233,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 +1246,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 +1265,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 +1342,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,6 +1372,16 @@ 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;

package/lib/ecosystems/parsers-js.js

@@ -14,6 +14,7 @@ import ssri from "ssri";
 import { parse as _load, parseAllDocuments } from "yaml";
 
 import { DEBUG_MODE, readEnvironmentVariable } from "../core/activity.js";
+import { recordDegradation } from "../core/buildLedger.js";
 import { shouldFetchPackageMetadata } from "../core/env.js";
 import { safeExistsSync } from "../core/fs.js";
 import { analyzeSuspiciousJsFile } from "../inventory/analyzer.js";
@@ -1485,6 +1486,14 @@ export async function parsePkgLock(pkgLockFile, options = {}) {
       tree = await arb.loadVirtual();
     }
   } catch (e) {
+    recordDegradation("js.lockfile-version", {
+      ecosystem: "npm",
+      tool: "npm",
+      impact: "transitive-deps",
+      path: pkgLockFile,
+      detail:
+        "The package-lock.json could not be parsed with the current npm dependency-resolution semantics, so the legacy parser is used instead.",
+    });
     console.log(e);
     console.log(
       `Unable to parse ${pkgLockFile} without legacy peer dependencies. Retrying ...`,
@@ -1499,6 +1508,15 @@ export async function parsePkgLock(pkgLockFile, options = {}) {
       });
       tree = await arb.loadVirtual();
     } catch (e) {
+      recordDegradation("js.lockfile-version", {
+        ecosystem: "npm",
+        tool: "npm",
+        kind: "evidence.degraded",
+        impact: "transitive-deps",
+        path: pkgLockFile,
+        detail:
+          "The package-lock.json could not be parsed in either npm resolution mode, so the resulting SBOM is incomplete.",
+      });
       console.log(e);
       console.log(
         `Unable to parse ${pkgLockFile} in legacy and non-legacy mode. The resulting SBOM would be incomplete.`,
@@ -3104,6 +3122,14 @@ export async function parsePnpmLock(
       try {
         yamlObj = yamlObj[yamlObj.length - 1].toJS();
       } catch (_e) {
+        recordDegradation("js.pnpm-lock-unparseable", {
+          ecosystem: "npm",
+          tool: "pnpm",
+          impact: "transitive-deps",
+          path: pnpmLock,
+          detail:
+            "The pnpm-lock.yaml could not be parsed, so no locked versions were captured from it.",
+        });
         console.log(`Unable to parse the pnpm lock file ${pnpmLock}.`);
         return {};
       }