@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/collectors/sbom.js

@@ -1,16 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/sbom.js
- *
- * Companion collector for the `sbom` playbook. Identifies the lockfile
- * fingerprint of the cwd (npm / yarn / pnpm / pip / cargo / go / ruby /
- * composer) so the runner can correlate against the SBOM-currency +
- * supply-chain integrity indicators. Counts components per lockfile
- * for a coarse SBOM-presence signal.
- *
- * Scope: any cwd with a recognizable lockfile. Multi-ecosystem repos
- * report every detected lockfile.
+ * Companion collector for the `sbom` playbook. Fingerprints the lockfiles in the
+ * cwd (npm, yarn, pnpm, pip, cargo, go, ruby, composer) and counts components
+ * per lockfile as a coarse SBOM-presence signal.
  *
  * Interface: see lib/collectors/README.md
  */
@@ -21,8 +14,8 @@ const { buildEvidenceLocations } = require("./scan-excludes");
 
 const COLLECTOR_ID = "sbom";
 
-// Lockfile fingerprints. Each entry: { file: <basename>, ecosystem,
-// parser: <function(content) -> { component_count, top_level_count }> }.
+// Each parser takes the file content and returns
+// { component_count, top_level_count, lockfile_version } or { error }.
 const LOCKFILES = [
   {
     file: "package-lock.json",
@@ -123,30 +116,21 @@ const LOCKFILES = [
       } catch (e) { return { error: e.message }; }
     },
   },
-  // Python dependency MANIFEST (not strictly a lockfile but the
-  // canonical project file for modern Python projects). Counted as
-  // a Python ecosystem dependency source so projects with only a
-  // pyproject.toml + no requirements.txt are recognized.
+  // A manifest, not a lockfile: a pyproject-only project is still recognized.
   {
     file: "pyproject.toml",
     ecosystem: "python",
     parser: (content) => {
-      // Count entries in [project.dependencies] / [project.optional-
-      // dependencies.*] / [tool.poetry.dependencies] / [tool.poetry
-      // .dev-dependencies]. Coarse line-based count — the TOML parser
-      // would pull a dep into the stdlib-only contract.
+      // Line-based, not parsed: the collector contract is stdlib-only.
       const depBlocks = content.match(/^\[(?:project\.(?:dependencies|optional-dependencies)|tool\.poetry\.(?:dependencies|dev-dependencies|group\.[a-z0-9_-]+\.dependencies))[^\]]*\][\s\S]*?(?=^\[|$)/gm) || [];
       let count = 0;
       for (const block of depBlocks) {
-        // count "name = ..." lines (excluding the block header)
         const lines = block.split(/\r?\n/).slice(1);
         for (const line of lines) {
           if (/^\s*[A-Za-z][A-Za-z0-9._\-]*\s*=/.test(line)) count++;
         }
       }
-      // Also handle the PEP 621 array-style:
-      //   [project]
-      //   dependencies = [ "a", "b", ... ]
+      // PEP 621 array style: `dependencies = [ "a", "b" ]` under [project].
       const arrMatch = content.match(/^\s*dependencies\s*=\s*\[([\s\S]*?)\]/m);
       if (arrMatch) {
         const entries = arrMatch[1].match(/"([^"]+)"|'([^']+)'/g) || [];
@@ -157,10 +141,7 @@ const LOCKFILES = [
   },
 ];
 
-// Python requirements*.txt glob. Variants include requirements-dev
-// .txt, requirements-prod.txt, dev-requirements.txt. The
-// requirements.txt entry above covers the canonical name; this
-// glob extends coverage to the common variants.
+// requirements*.txt variants; the canonical name is a LOCKFILES entry above.
 const REQUIREMENTS_GLOB_RE = /^(?:[a-z0-9_-]+-)?requirements(?:-[a-z0-9_-]+)?\.txt$/i;
 const REQUIREMENTS_LF = {
   ecosystem: "pip",
@@ -170,11 +151,7 @@ const REQUIREMENTS_LF = {
   },
 };
 
-// Subdirectory probe paths — one level deep, hand-listed to keep
-// the walk bounded. Covers the common monorepo / docs-subdir / iac
-// layouts: docs/ (requirements.txt for sphinx-style docs builds),
-// packages/* (monorepo workspaces), backend/ + frontend/ +
-// infra/ + iac/ (split-stack repos).
+// Probed one level deep and hand-listed so the walk stays bounded.
 const SUBDIR_PROBE_PATHS = ["docs", "packages", "backend", "frontend", "infra", "iac", "src", "app"];
 
 const SBOM_FORMATS = [
@@ -195,24 +172,31 @@ function captureLockfile(p, ecosystem, parser, label) {
       path: p,
       size_bytes: Buffer.byteLength(content, "utf8"),
       ...stats,
+      // A parser that could not decode the structure returns `error`; the read
+      // itself succeeded, so the two failures carry different kinds downstream.
+      ...(stats && stats.error ? { error_kind: "lockfile_parse_failed" } : {}),
     };
   } catch (e) {
-    return { file: label, ecosystem, path: p, error: e.message };
+    return { file: label, ecosystem, path: p, error: e.message, error_kind: "lockfile_read_failed" };
   }
 }
 
-function findLockfiles(cwd) {
+// `errors` is the collector_errors channel: a directory the walk could not read
+// is a scan gap the operator has to see, not a silent zero. Required, not
+// defaulted: a default array would restore the discard-into-the-void behaviour
+// for any caller that forgets it, and neither this function nor
+// findSbomDocuments is exported, so no test could reach that caller.
+function findLockfiles(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findLockfiles: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
-  // Canonical names at cwd root.
   for (const lf of LOCKFILES) {
     const p = path.join(cwd, lf.file);
     if (fs.existsSync(p)) {
       found.push(captureLockfile(p, lf.ecosystem, lf.parser, lf.file));
     }
   }
-  // requirements*.txt glob at cwd root — covers requirements-dev.txt,
-  // dev-requirements.txt, etc. The exact-name `requirements.txt`
-  // already lands via LOCKFILES; skip it here.
   try {
     for (const entry of fs.readdirSync(cwd)) {
       if (entry === "requirements.txt") continue; // captured above
@@ -223,25 +207,35 @@ function findLockfiles(cwd) {
         }
       }
     }
-  } catch { /* swallow */ }
+  } catch (e) {
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: "readdir_failed",
+      reason: `cwd root: ${e.message} — requirements*.txt variants were not enumerated`,
+    });
+  }
 
-  // One-level subdirectory probe for canonical-name lockfiles. The
-  // common pattern: docs/requirements.txt (sphinx builds),
-  // packages/*/package.json (monorepo workspaces), backend/Gemfile
-  // .lock (split-stack repos). Capped depth (1 level only) and
-  // pre-listed subdirs to keep the walk bounded.
   for (const sub of SUBDIR_PROBE_PATHS) {
     const subDir = path.join(cwd, sub);
     let entries;
     try {
       if (!fs.statSync(subDir).isDirectory()) continue;
       entries = fs.readdirSync(subDir, { withFileTypes: true });
-    } catch { continue; }
+    } catch (e) {
+      // An absent probe dir is the normal case, not a gap. A permission or I/O
+      // failure on one that IS there means the subtree went unscanned.
+      if (e.code !== "ENOENT") {
+        errors.push({
+          artifact_id: "lockfile-inventory",
+          kind: "readdir_failed",
+          reason: `${sub}/: ${e.message} — subtree not scanned for lockfiles`,
+        });
+      }
+      continue;
+    }
     for (const e of entries) {
       if (e.isDirectory()) {
-        // For packages/* etc. — probe ONE level deeper for canonical
-        // names. (Doesn't recurse further; monorepo workspaces are
-        // the only common case.)
+        // packages/* gets one more level for monorepo workspaces, no deeper.
         if (sub === "packages") {
           for (const lf of LOCKFILES) {
             const p = path.join(subDir, e.name, lf.file);
@@ -254,10 +248,7 @@ function findLockfiles(cwd) {
         continue;
       }
       if (!e.isFile()) continue;
-      // Try canonical LOCKFILES name match first; if it matches, the
-      // file is captured there. The requirements glob below catches
-      // ONLY non-canonical names (e.g. requirements-dev.txt) so
-      // exact `requirements.txt` doesn't double-fire.
+      // A canonical name wins, so `requirements.txt` cannot double-fire below.
       let captured = false;
       for (const lf of LOCKFILES) {
         if (e.name === lf.file) {
@@ -279,37 +270,53 @@ function findLockfiles(cwd) {
   return found;
 }
 
-function findSbomDocuments(cwd) {
+// `errors` is required for the same reason it is on findLockfiles above.
+function findSbomDocuments(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findSbomDocuments: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
   for (const s of SBOM_FORMATS) {
     const p = path.join(cwd, s.file);
     let fd;
-    // Open once and fstat the descriptor instead of existsSync→statSync→read:
-    // an absent file (ENOENT) is skipped just as the existsSync(false) path did,
-    // but there is no TOCTOU window between the check, the size stat, and the read.
+    // Open once and fstat the descriptor rather than existsSync→statSync→read:
+    // ENOENT still skips, and there is no TOCTOU window.
     try { fd = fs.openSync(p, "r"); }
-    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message }); continue; }
+    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message, error_kind: "open_failed" }); continue; }
     try {
       const stat = fs.fstatSync(fd);
       let content;
-      // Read from the already-open descriptor (no re-open by path → no
-      // TOCTOU window, preserving the fstat-on-fd hardening). readFileSync(fd)
-      // loops internally to EOF; a single readSync(fd, buf, …, stat.size) does
-      // NOT — it can return a short read (network/FUSE mount, signal), leaving
-      // the buffer NUL-padded and truncating valid JSON, so JSON.parse would
-      // throw and component_count silently fall back to null on a present,
-      // parseable SBOM. The fd stays open for the finally{} closeSync.
-      try { content = fs.readFileSync(fd, "utf8"); } catch { content = null; }
+      // Read from the open descriptor, never by path again. readFileSync(fd) loops
+      // to EOF; a single readSync can return short on a network or FUSE mount,
+      // NUL-padding the buffer and truncating otherwise-valid JSON.
+      try { content = fs.readFileSync(fd, "utf8"); } catch (e) {
+        content = null;
+        errors.push({
+          artifact_id: "sbom-document",
+          kind: "read_failed",
+          reason: `${s.file}: ${e.message} — component count not derived`,
+        });
+      }
       let component_count = null;
       if (content && s.format === "cyclonedx-1.x") {
         try {
           const j = JSON.parse(content);
           component_count = (j.components || []).length;
-        } catch {}
+        } catch (e) {
+          // A present-but-unparseable SBOM reported `null components` with no
+          // explanation, which reads as "no components" rather than "not read".
+          errors.push({
+            artifact_id: "sbom-document",
+            kind: "parse_failed",
+            reason: `${s.file}: ${e.message} — component count unavailable`,
+          });
+        }
       }
       found.push({ file: s.file, format: s.format, size_bytes: stat.size, component_count });
     } catch (e) {
-      found.push({ file: s.file, format: s.format, error: e.message });
+      // The descriptor opened; fstat is what failed here. Reporting it as an
+      // open failure sends the operator after the wrong thing.
+      found.push({ file: s.file, format: s.format, error: e.message, error_kind: "stat_failed" });
     } finally {
       if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } }
     }
@@ -322,13 +329,32 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const startTime = Date.now();
   const root = path.resolve(cwd);
 
-  // Precondition: sbom-tool-available — the runner / playbook treats
-  // this as "an operator has SOME way to produce an SBOM". For the
-  // collector, "we found a lockfile or an SBOM" is a sufficient proxy.
-  const lockfiles = findLockfiles(root);
-  const sbomDocuments = findSbomDocuments(root);
+  // sbom-tool-available: a lockfile or an SBOM document is a sufficient proxy.
+  const lockfiles = findLockfiles(root, errors);
+  const sbomDocuments = findSbomDocuments(root, errors);
   const hasAnything = lockfiles.length > 0 || sbomDocuments.length > 0;
 
+  // A lockfile that was found but not read contributes no component count, so
+  // the inventory under-reports; the operator sees which one and why.
+  for (const l of lockfiles) {
+    if (!l.error) continue;
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: l.error_kind || "lockfile_read_failed",
+      reason: `${l.file}: ${l.error}`,
+    });
+  }
+  for (const s of sbomDocuments) {
+    if (!s.error) continue;
+    errors.push({
+      artifact_id: "sbom-document",
+      // Carried from the push site, mirroring the lockfile loop above: an
+      // fstat failure and an open failure are different operator actions.
+      kind: s.error_kind || "open_failed",
+      reason: `${s.file}: ${s.error}`,
+    });
+  }
+
   const artifacts = {
     "lockfile-inventory": {
       value: lockfiles.length
@@ -344,22 +370,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     },
   };
 
-  // The sbom playbook's detect indicators (package-matches-catalogued-cve,
-  // lockfile-no-integrity, transitive-deps-incomplete-sbom,
-  // matched-cve-without-vex, ai-code-no-provenance, ...) require
-  // catalog cross-referencing the collector does not have — that's
-  // the runner's job. The collector's role here is to surface the
-  // artifacts (lockfile-inventory + sbom-document) and let the
-  // runner evaluate the indicators against them. Emitting
-  // signal_overrides for keys that don't exist in the playbook
-  // would be silently ignored; surfacing the artifacts honestly
-  // is the contract.
-  //
-  // One indicator the collector CAN decide deterministically:
-  // lockfile-no-integrity — true when an npm package-lock.json
-  // exists but has zero `integrity` entries (lockfileVersion 1
-  // legacy) OR when the dependency list contains entries lacking
-  // `integrity` strings.
+  // lockfile-no-integrity is the one indicator decidable here: an npm
+  // package-lock.json with entries carrying no `integrity`. The rest need catalog
+  // cross-referencing, which the runner does against the artifacts above.
   const npmLockfile = lockfiles.find(l => l.file === "package-lock.json");
   const signal_overrides = {};
   if (npmLockfile && !npmLockfile.error) {
@@ -367,19 +380,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       const j = JSON.parse(fs.readFileSync(npmLockfile.path, "utf8"));
       let withIntegrity = 0;
       let withoutIntegrity = 0;
-      // Track whether any integrity-less entry is a local-path / workspace /
-      // git ref. lockfile-no-integrity FP[0] demotes those — they legitimately
-      // have no registry integrity hash. A remote-registry tarball without
-      // integrity is the genuine finding.
+      // A local-path, workspace or git ref legitimately has no integrity hash, so
+      // FP check [0] demotes those; a remote-registry tarball is the finding.
       let withoutIntegrityLocalOnly = true;
       const LOCAL_REF_RE = /^(?:file:|link:|workspace:|git\+ssh:|git\+https:|git:|github:|portal:)/i;
       const walk = (obj) => {
         if (!obj || typeof obj !== "object") return;
-        // Only remote-tarball entries (those with a `resolved` URL) are
-        // expected to carry an `integrity` hash. The npm 7+ root entry
-        // `"": { name, version }` legitimately has no `resolved` and no
-        // `integrity`, so keying off `version` would false-positive on
-        // every clean lockfile. Mirror library-author.js's guard.
+        // Only entries with a `resolved` URL are expected to carry `integrity`.
+        // The npm 7+ root entry `"": { name, version }` has neither, so keying off
+        // `version` false-positives. library-author.js guards the same way.
         if (obj.resolved != null) {
           if (obj.integrity != null) {
             withIntegrity++;
@@ -391,15 +400,12 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
         for (const v of Object.values(obj)) if (v && typeof v === "object") walk(v);
       };
       walk(j.packages || j.dependencies || {});
-      // Fire only if integrity is missing on ANY package entry that
-      // resolves to a remote tarball — the indicator captures the
-      // class, not full coverage.
+      // Any single integrity-less resolved entry fires it: the class, not coverage.
       if (withoutIntegrity > 0) {
         signal_overrides["lockfile-no-integrity"] = "hit";
-        // __fp_checks attestation. [0]: at least one integrity-less entry is a
-        // remote-registry tarball (not exclusively local-path/workspace/git
-        // refs). [1]: the lockfile is the canonical root package-lock.json the
-        // build consumes, not a stale copy under archive/ pre-migration/.
+        // __fp_checks attestation — [0]: an integrity-less entry is a remote
+        // tarball, not only local, workspace or git refs. [1]: this is the root
+        // lockfile the build consumes, not a stale archived copy.
         const att = {};
         if (!withoutIntegrityLocalOnly) att["0"] = true;
         const rel = (npmLockfile.path || "").replace(/\\/g, "/");
@@ -408,19 +414,19 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       } else if (withIntegrity > 0) {
         signal_overrides["lockfile-no-integrity"] = "miss";
       }
-      // Stash diagnostic counts on collector_meta further below.
       npmLockfile.integrity_present_count = withIntegrity;
       npmLockfile.integrity_missing_count = withoutIntegrity;
-    } catch {
-      // Malformed lockfile — leave the indicator unflipped so the
-      // runner returns inconclusive rather than a forced miss.
+    } catch (e) {
+      // A malformed lockfile leaves the indicator unflipped: inconclusive, not miss.
+      errors.push({
+        artifact_id: "lockfile-inventory",
+        kind: "lockfile_parse_failed",
+        reason: `${npmLockfile.file}: ${e.message} — lockfile-no-integrity left undecided (inconclusive, not miss)`,
+      });
     }
   }
 
-  // Per-indicator file location for the one deterministically-decided
-  // indicator: a lockfile-no-integrity hit points at the npm lockfile that
-  // carries integrity-less entries. File-level (the gap is spread across
-  // many entries, not one line).
+  // File-level: the gap is spread across entries rather than sitting on one line.
   const evidence_locations = {};
   if (signal_overrides["lockfile-no-integrity"] === "hit" && npmLockfile) {
     const locs = buildEvidenceLocations([{ file: npmLockfile.file }]);
@@ -430,11 +436,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   return {
     precondition_checks: {
       "sbom-tool-available": hasAnything,
-      // Auto-attest the playbook's any-package-manager-present gate from what
-      // we actually collected: the runner's autoDetectPreconditions can't probe
-      // the scanned --cwd (it sees the run process cwd, not the collected repo),
-      // so a lockfile we found here would otherwise surface a spurious
-      // precondition_unverified warning on a repo that clearly has one.
+      // Attested from what was collected: autoDetectPreconditions sees the run
+      // process cwd, not the scanned --cwd, so this would warn as unverified.
       "any-package-manager-present": lockfiles.length > 0,
     },
     artifacts,
@@ -450,6 +453,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       lockfiles_found: lockfiles.length,
       sbom_documents_found: sbomDocuments.length,
       ecosystems_detected: [...new Set(lockfiles.map(l => l.ecosystem))],
+      // Magnitude behind the lockfile-no-integrity verdict: "hit" alone does not
+      // say whether one entry or nine hundred resolve without a hash. Present
+      // only when an npm lockfile was found AND parsed.
+      ...(npmLockfile && npmLockfile.integrity_present_count != null
+        ? {
+          npm_integrity_present_count: npmLockfile.integrity_present_count,
+          npm_integrity_missing_count: npmLockfile.integrity_missing_count,
+        }
+        : {}),
     },
     collector_errors: errors,
   };