@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/collectors/library-author.js

@@ -1,31 +1,10 @@
 "use strict";
 
 /**
- * lib/collectors/library-author.js
- *
- * Companion collector for the `library-author` playbook. Audits a
- * publisher-side repository for supply-chain posture markers:
- * SECURITY.md / security.txt presence, sbom + signature pair,
- * publish-workflow shape (id-token write, action-ref pinning, frozen
- * install), package.json provenance opt-in, vendor-tree provenance,
- * lockfile integrity.
- *
- * Skipped indicators (require external API or runtime data, left
- * unflipped so the runner returns inconclusive rather than a forced
- * miss):
- *
- *   tag-protection-absent           GitHub branch-protection API
- *   private-vuln-reporting-disabled GitHub repo-settings API
- *   no-rekor-entry-for-latest-release  sigstore lookup
- *   release-tag-not-signed          git tag --verify on each release
- *   release-signed-with-personal-gpg-key  GPG identity policy
- *   sbom-regenerated-at-request-time     timing-based; needs build
- *                                        pipeline trace
- *   skill-signing-but-verification-not-gated  project-internal CI
- *                                              gate inspection
- *   ssdf-claimed-cra-not-ready      operator interview shape
- *   gha-workflow-script-injection-sink  complex pattern; future pass
- *
+ * Companion collector for the `library-author` playbook: audits a publisher-side
+ * repository for supply-chain posture markers. Indicators needing an external API
+ * or a build-pipeline trace are left unflipped, so the runner returns
+ * inconclusive rather than a forced miss.
  * Interface: see lib/collectors/README.md
  */
 
@@ -35,11 +14,8 @@ const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require(
 
 const COLLECTOR_ID = "library-author";
 
-const DEFAULT_MAX_DEPTH = 6;
-// Shared code-scope exclusions (dependency caches, build output, VCS +
-// agent/editor scratch including `.claude/`). Applied to the vendor-tree
-// walk so a linked worktree or dependency cache nested under `vendor/`
-// isn't mistaken for vendored provenance state.
+// Applied to the vendor-tree walk, so a cache nested under `vendor/` is not
+// mistaken for vendored provenance state.
 const DEFAULT_EXCLUDES = codeExcludeSet();
 
 function readSafe(full, max = 512 * 1024) {
@@ -48,10 +24,8 @@ function readSafe(full, max = 512 * 1024) {
     fd = fs.openSync(full, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd), never a single readSync: a short read on a network fd
+    // NUL-fills the tail. Reading the open fd is also TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -74,53 +48,34 @@ function walkWorkflows(root) {
 }
 
 function looksLikePublishWorkflow(name, content) {
-  // Heuristic: filename starts with a publish-prefix, OR the body
-  // invokes a publish command. Conservative — broad signals like
-  // `id-token: write`, bare `sigstore/cosign-installer`, or `cosign
-  // sign-blob` (commonly used in test workflows) DO NOT count; they
-  // produced false positives on verification + e2e workflows that
-  // happen to share signing infrastructure.
+  // Broad signals — `id-token: write`, a cosign installer — must not count:
+  // verification and e2e workflows share the same signing infrastructure.
   const lower = name.toLowerCase();
 
-  // Verification / test / e2e workflows are never publish, regardless
-  // of body content. Hard demotion.
   if (/^(test|verify|validate|e2e|kind|check|conformance|coverage)/.test(lower)) return false;
 
-  // Filename prefix signals: only the canonical publish words.
   if (/^(release|publish|deploy|promote|tag-and-release)/.test(lower)) return true;
 
-  // Strip YAML line-comments before the content-shape probes so a comment that
-  // merely MENTIONS a publish verb (e.g. a ci.yml line "# … matches the npm
-  // publish workflow's depth.") can't masquerade as a publish command. The
-  // filename-prefix checks above are unaffected. A `#` inside a quoted string
-  // is rare in workflow YAML and not load-bearing for these command probes
-  // (stripping can only REMOVE comment text, never create a false match).
+  // Comment-stripped, so a `#` line mentioning a publish verb cannot masquerade
+  // as one. Stripping can only remove text, never create a match.
   const code = stripYamlComments(content);
 
-  // Explicit publish-shape commands — these are commitments to push
-  // artifacts, not setup / scaffolding.
   if (/\bnpm\s+publish\b/.test(code)) return true;
   if (/pypa\/gh-action-pypi-publish/.test(code)) return true;
   if (/\bcargo\s+publish\b/.test(code)) return true;
   if (/goreleaser/.test(code)) return true;
   if (/softprops\/action-gh-release/.test(code)) return true;
-  // `ko build` builds AND pushes container images by default (unless
-  // --push=false). All four sub-commands push to a registry.
+  // All four `ko` sub-commands push to a registry by default, `build` included.
   if (/\bko\s+(?:publish|build|apply|resolve)\b/.test(code)) return true;
-  // `cosign sign` (container signing — publish-shape). Exclude
-  // `cosign sign-blob` which signs arbitrary artifacts and shows
-  // up in verification / e2e tests as often as in publishes.
+  // The `(?!-)` keeps out `cosign sign-blob`, as common in verification workflows.
   if (/\bcosign\s+sign\b(?!-)/.test(code)) return true;
   if (/\bcrane\s+(?:push|copy|append)\b/.test(code)) return true;
   if (/\boras\s+(?:push|copy)\b/.test(code)) return true;
   if (/docker\/build-push-action/.test(code)) return true;
   if (/\bdocker\s+push\b/.test(code)) return true;
 
-  // Registry login actions — when a workflow logs into a registry,
-  // it's almost certainly publishing. Picks up Makefile / opaque
-  // publish paths (cosign's build.yaml uses make sign-ci-containers
-  // after docker/login-action). Does NOT match verification tests
-  // because those don't authenticate to a registry.
+  // Registry login stands in for opaque publish paths (a Makefile target run
+  // after docker/login-action); verification workflows never authenticate.
   if (/docker\/login-action/.test(code)) return true;
   if (/google-github-actions\/auth/.test(code) && /gcloud auth configure-docker/.test(code)) return true;
   if (/aws-actions\/configure-aws-credentials/.test(code) && /amazon-ecr/.test(code)) return true;
@@ -128,33 +83,117 @@ function looksLikePublishWorkflow(name, content) {
   return false;
 }
 
-// `id-token: write` grants the OIDC token used for npm provenance and
-// sigstore keyless signing. It is valid at workflow-level permissions or at
-// a specific job's `permissions:` block, so any occurrence of the
-// `id-token: write` token within the publish workflow file counts as the
-// capability being present — this is what lets a job-scoped declaration
-// (not just a workflow-level one) satisfy the check. The match is
-// deliberately scoped to the file being scanned, not repo-wide: a sibling
-// workflow's OIDC does not grant it to the publish job.
+// `id-token: write` is valid at workflow OR job scope, so any occurrence counts.
+// Scoped to the one file passed in: a sibling workflow's OIDC does not grant it.
 function hasIdTokenWriteAnyScope(content) {
   return /\bid-token:\s*write\b/.test(content);
 }
 
-// Strip YAML line-comments so a `#`-commented MENTION of a publish-shape
-// token / command / runner is not read as the real thing. The classifier
-// (looksLikePublishWorkflow) already does this; the indicator probes — and the
-// provenance / SBOM-capability probes in collect() — must use the same view,
-// or a comment produces a false (often deterministic) hit, and in the
-// provenance direction a commented `--provenance` would suppress a real gap
-// (a false negative on a security-relevant posture check).
+// Every probe that reads workflow bodies must use this view: a commented publish
+// token otherwise produces a false hit, and a commented `--provenance` hides a gap.
 function stripYamlComments(content) {
   return content.replace(/#.*$/gm, "");
 }
 
-function scanPublishWorkflow(content, rel) {
-  // Whole-content probes below run against a comment-stripped view. The
-  // `uses:` line scan stays on the raw lines — its anchored regex already
-  // rejects `#`-prefixed lines, so a commented `uses:` cannot match.
+// Splits comment-stripped workflow text into individual shell commands, so a
+// flag on one install cannot vouch for another. A workflow that hash-pins its
+// build requirements and then resolves its runtime ones must still report the
+// unpinned command, which a whole-file flag test would suppress.
+function shellCommands(code) {
+  const out = [];
+  const lines = code.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    // A real `run:` line is never KBs long; skipping overlong ones keeps a
+    // crafted whitespace run from driving regex backtracking.
+    if (lines[i].length > 4096) continue;
+    // A backslash-continued command is ONE command: a `pip install \` whose
+    // `-r` sits on the next line is otherwise two fragments that each match
+    // nothing. The continuation lines are consumed, never re-emitted.
+    const startLine = i + 1;
+    let raw = lines[i];
+    while (/\\[ \t]*$/.test(raw) && i + 1 < lines.length &&
+           lines[i + 1].length <= 4096 && raw.length <= 8192) {
+      raw = `${raw.replace(/\\[ \t]*$/, " ")}${lines[i + 1].trim()}`;
+      i++;
+    }
+    for (const seg of raw.split(/&&|\|\||[;|]/)) {
+      const cmd = seg.trim();
+      // Comment stripping preserves line breaks, so the index still addresses
+      // the line the command STARTS on in the file an operator opens.
+      if (cmd) out.push({ cmd, line: startLine });
+    }
+  }
+  return out;
+}
+
+// Evidence snippets are read in a report, so a pathological one-line script
+// cannot be pasted in whole.
+function snippetOf(cmd, max = 200) {
+  return cmd.length > max ? `${cmd.slice(0, max)}…` : cmd;
+}
+
+// pip enters hash-checking mode as soon as ONE requirement carries a hash, so
+// `pip install -r <file>` against a `pip-compile --generate-hashes` output is
+// already reproducible. Resolves the named file one level only: a nested `-r`
+// include is not followed, and an unreadable path counts as unhashed.
+// pip accepts the requirement file attached (`-rreq.txt`) as well as separated
+// (`-r req.txt`, `--requirement=req.txt`). One definition for both the detection
+// predicate and the hash lookup: two regexes for one flag drift, and the pair
+// that drifts silently is a command examined by neither.
+// `(?:^|\s)-r` rather than `\b-r` so the `-r` inside `--requirement` is not read
+// as the short form with `equirement...` as its filename.
+const PIP_REQUIREMENT_RE = /(?:^|\s)(?:-r\s*=?\s*|--requirement[=\s]*)['"]?([^'"\s]+)/;
+
+function pipRequirementTarget(cmd) {
+  const m = cmd.match(PIP_REQUIREMENT_RE);
+  return m ? m[1] : null;
+}
+
+// `working-directory:`, at job defaults or on a single step, is what a `run:`
+// command resolves its relative paths against. Collected as a set of candidate
+// bases rather than bound to the step that declared it: the scanner is
+// line-based, so attributing one to a specific command would need the step
+// nesting it does not track.
+// Matches the block form and the flow form (`{ run: { working-directory: x } }`)
+// alike. A key-shaped string inside a `run:` command matches too; that only adds
+// a base that does not resolve, and an unresolvable base is skipped.
+function workingDirectories(code) {
+  const dirs = [];
+  for (const m of code.matchAll(/working-directory:\s*['"]?([^'"\n,}]+?)['"]?\s*(?=$|[,}])/gm)) {
+    const d = m[1].trim();
+    if (d && d !== "." && !path.isAbsolute(d)) dirs.push(d);
+  }
+  return dirs;
+}
+
+// True only when every candidate that EXISTS is hash-pinned, and at least one
+// does. Requiring all of them keeps a hashed copy in one working directory from
+// vouching for an unhashed copy in another — over-suppression here reports an
+// unpinned release as reproducible, which is the direction that costs something.
+// A target that resolves nowhere stays unproven, so the caller still reports it.
+function requirementsFileIsHashed(cmd, root, extraBases = []) {
+  if (!root) return false;
+  const target = pipRequirementTarget(cmd);
+  if (!target) return false;
+  if (path.isAbsolute(target)) return false;
+
+  let found = 0;
+  for (const base of [root, ...extraBases.map((d) => path.resolve(root, d))]) {
+    // Never read outside the scanned tree, whatever `../` the workflow names —
+    // for the base itself as well as the target resolved against it.
+    if (base !== root && !base.startsWith(root + path.sep)) continue;
+    const full = path.resolve(base, target);
+    if (full !== root && !full.startsWith(root + path.sep)) continue;
+    const body = readSafe(full);
+    if (body === null) continue;
+    found++;
+    if (!/--hash=/.test(body)) return false;
+  }
+  return found > 0;
+}
+
+function scanPublishWorkflow(content, rel, root) {
+  // Whole-content probes read `code`; the `uses:` scan below stays on raw lines.
   const code = stripYamlComments(content);
   const hits = {
     "publish-workflow-uses-static-token": [],
@@ -164,18 +203,10 @@ function scanPublishWorkflow(content, rel) {
     "publish-workflow-runs-on-self-hosted": [],
   };
 
-  // static-token: workflow references a publish-credential secret
-  // without a corresponding `id-token: write` permission (at any scope).
-  // The predicate (per data/playbooks/library-author.json) lists
-  // NPM_TOKEN / PYPI_TOKEN / CARGO_TOKEN / RUBYGEMS_API_KEY /
-  // GEM_HOST_API_KEY; expand to cover the common variants for each
-  // ecosystem.
+  // Widens the predicate in data/playbooks/library-author.json to the common
+  // token-name variant per ecosystem.
   const usesStaticToken = /\bsecrets\.(NPM_TOKEN|PYPI_TOKEN|PYPI_API_TOKEN|CARGO_TOKEN|CARGO_REGISTRY_TOKEN|RUBYGEMS_API_KEY|GEM_HOST_API_KEY|MAVEN_TOKEN|MAVEN_CENTRAL_TOKEN|GH_TOKEN)\b/.test(code);
-  // OIDC is available when THIS publish file declares `id-token: write` at
-  // any scope (workflow or job). Scoped to the file by design — a sibling
-  // workflow's OIDC does not authenticate this publish job. Read from the
-  // comment-stripped view so a commented `id-token: write` cannot falsely
-  // satisfy the capability (which would suppress the static-token finding).
+  // Comment-stripped: a commented `id-token: write` would suppress the finding.
   const hasIdTokenWrite = hasIdTokenWriteAnyScope(code);
   if (usesStaticToken && !hasIdTokenWrite) {
     hits["publish-workflow-uses-static-token"].push({ file: rel, line: 0, snippet: "publish workflow uses a static long-lived token (NPM_TOKEN / PYPI / Cargo / Maven) without id-token: write for OIDC" });
@@ -184,20 +215,15 @@ function scanPublishWorkflow(content, rel) {
     hits["publish-workflow-no-id-token-write"].push({ file: rel, line: 0, snippet: "no id-token: write at any scope (workflow or job) — npm provenance / sigstore signing unavailable" });
   }
 
-  // action-refs-mutable: any `uses: <action>@<ref>` where ref is NOT
-  // a 40-char hex sha. Excludes `uses: ./local-action`.
+  // Mutable = any `uses: <action>@<ref>` whose ref is not a 40-char hex sha.
   const lines = content.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    // A real `uses:` line is never multiple KB. Skip overlong lines so a
-    // crafted whitespace run can't drive regex backtracking.
+    // A real `uses:` line is never KBs long; skipping overlong ones keeps a
+    // crafted whitespace run from driving regex backtracking.
     if (line.length > 4096) continue;
-    // Allow optional leading `-` from a YAML list item: `- uses: ...`.
-    // `^[ \t]*(?:-[ \t]*)?` anchors the indentation once, then an optional
-    // `- ` list marker — no overlapping `\s*` runs that backtrack. Exclude `#`
-    // from the capture and drop the end anchor (mirroring the cicd collector) so
-    // a `uses: x@v1  # comment` line is still matched — the `$`-anchored pattern
-    // silently missed every floating ref that carried a trailing YAML comment.
+    // No end anchor and `#` excluded from the capture, so `uses: x@v1  # comment`
+    // still matches. The indent and `- ` marker are each anchored once.
     const m = line.match(/^[ \t]*(?:-[ \t]*)?uses:\s*['"]?([^'"\s#]+)['"]?/);
     if (!m) continue;
     const ref = m[1];
@@ -210,17 +236,53 @@ function scanPublishWorkflow(content, rel) {
     }
   }
 
-  // non-frozen-install: workflow uses `npm install` instead of `npm ci`,
-  // or `pip install <pkg>` without `--require-hashes`, or `cargo
-  // install` without `--locked`.
+  // npm alone stays a whole-file test, because its suppressor is a DIFFERENT
+  // command rather than a flag: `npm ci` elsewhere in the workflow is the
+  // frozen install, and the `npm install` line beside it is usually tooling.
   if (/\bnpm\s+install\b/.test(code) && !/\bnpm\s+ci\b/.test(code)) {
     hits["release-workflow-non-frozen-install"].push({ file: rel, line: 0, snippet: "publish workflow uses `npm install` rather than `npm ci` — lockfile is not enforced" });
   }
-  if (/\bcargo\s+(?:build|install)\b/.test(code) && !/--locked\b/.test(code) && !/--frozen\b/.test(code)) {
-    hits["release-workflow-non-frozen-install"].push({ file: rel, line: 0, snippet: "cargo build/install without --locked / --frozen" });
+
+  // Bundler's frozen mode can be set once for the job rather than per command
+  // (`bundle config set frozen/deployment`, or the BUNDLE_ env equivalents), so
+  // that suppressor is genuinely file-scoped; the flags below are not.
+  // The setting has to be turned ON. `bundle config set frozen false` names the
+  // key and disables it, so matching the key alone reads an explicit opt-out as
+  // the protection it opts out of — the env form already required a value.
+  const bundlerFrozenConfig =
+    /\bbundle\s+config\b[^\n]*\b(?:frozen|deployment)\s+['"]?(?:true|1)\b/.test(code) ||
+    /\bBUNDLE_(?:FROZEN|DEPLOYMENT)\s*[:=]\s*['"]?(?:true|1)\b/i.test(code);
+
+  const runBases = workingDirectories(code);
+
+  // Every remaining ecosystem is probed one command at a time. The playbook
+  // indicator names npm / pnpm / pip -r / bundle; cargo is probed on the same
+  // --locked / --frozen predicate.
+  for (const { cmd, line } of shellCommands(code)) {
+    if (/\bcargo\s+(?:build|install)\b/.test(cmd) && !/--locked\b/.test(cmd) && !/--frozen\b/.test(cmd)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `cargo build/install without --locked / --frozen: ${snippetOf(cmd)}` });
+    }
+    // Without --require-hashes the requirement set resolves at release time, so
+    // the artifact is not reproducible — unless the named file is hash-pinned,
+    // which switches pip into hash-checking mode on its own.
+    if (/\b(?:pip3?|python3?\s+-m\s+pip)\s+install\b/.test(cmd) &&
+        pipRequirementTarget(cmd) !== null &&
+        !/--require-hashes\b/.test(cmd) &&
+        !requirementsFileIsHashed(cmd, root, runBases)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `pip install -r without --require-hashes — requirements are resolved at release time: ${snippetOf(cmd)}` });
+    }
+    // pnpm defaults to --frozen-lockfile when CI is set, which GitHub Actions
+    // always sets — so a bare `pnpm install` here is already frozen and only an
+    // explicit opt-out resolves at release time.
+    if (/\bpnpm\s+(?:install|i)\b/.test(cmd) &&
+        /--no-frozen-lockfile\b|--frozen-lockfile[=\s]+false\b/.test(cmd)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `pnpm install opts out of the frozen lockfile: ${snippetOf(cmd)}` });
+    }
+    if (/\bbundle\s+install\b/.test(cmd) && !/--deployment\b/.test(cmd) && !/--frozen\b/.test(cmd) && !bundlerFrozenConfig) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `bundle install without --deployment / --frozen: ${snippetOf(cmd)}` });
+    }
   }
 
-  // runs-on-self-hosted: any `runs-on: self-hosted` line.
   if (/runs-on:\s*['"]?(?:self-hosted|\[?\s*self-hosted)/i.test(code)) {
     hits["publish-workflow-runs-on-self-hosted"].push({ file: rel, line: 0, snippet: "publish workflow runs on a self-hosted runner — non-ephemeral execution context" });
   }
@@ -233,7 +295,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const startTime = Date.now();
   const root = path.resolve(cwd);
 
-  // package-manifest detection.
   const manifests = [];
   const manifestFiles = [
     "package.json", "pyproject.toml", "Cargo.toml", "go.mod",
@@ -246,7 +307,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       manifests.push({ file: f, path: p, content: readSafe(p) });
     }
   }
-  // *.gemspec — glob at root only.
   try {
     for (const e of fs.readdirSync(root)) {
       if (e.endsWith(".gemspec")) {
@@ -256,11 +316,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     }
   } catch {}
 
-  // Release / publish workflows.
   const workflows = walkWorkflows(root).map(w => ({ ...w, content: readSafe(w.full) || "" }));
   const publishWorkflows = workflows.filter(w => looksLikePublishWorkflow(w.name, w.content));
 
-  // Aggregate publish-workflow indicator hits.
   const workflowHits = {
     "publish-workflow-uses-static-token": [],
     "publish-workflow-no-id-token-write": [],
@@ -268,24 +326,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "release-workflow-non-frozen-install": [],
     "publish-workflow-runs-on-self-hosted": [],
   };
-  // OIDC capability is evaluated per publish workflow, NOT repo-wide: a
-  // sibling docs/deploy workflow declaring `id-token: write` does not give
-  // OIDC to a release job that still publishes with a long-lived
-  // `secrets.NPM_TOKEN`. Treating it repo-wide would mask exactly the
-  // static-token publisher-takeover case this indicator exists to catch.
-  // Job-scoped `id-token: write` inside the publish file still counts —
-  // hasIdTokenWriteAnyScope matches any scope within the scanned file.
+  // OIDC capability is evaluated per publish workflow, never repo-wide: a sibling
+  // workflow's `id-token: write` gives nothing to a job using a static token.
   for (const w of publishWorkflows) {
-    const h = scanPublishWorkflow(w.content, w.rel);
+    const h = scanPublishWorkflow(w.content, w.rel, root);
     for (const [id, list] of Object.entries(h)) workflowHits[id].push(...list);
   }
 
-  // package.json provenance: per playbook, the indicator fires
-  // when EITHER the manifest opts in (`publishConfig.provenance:
-  // true`) is missing AND the publish workflow does not invoke
-  // `npm publish --provenance`. Repos that flip provenance on at
-  // the workflow level (the modern path) should not be flagged.
-  // We need the workflow inventory above this point.
+  // Fires only when neither `publishConfig.provenance: true` nor a workflow
+  // `npm publish --provenance` opts in. Needs the workflow inventory above.
   let provenanceMissing = "miss";
   const pkgManifest = manifests.find(m => m.file === "package.json");
   if (pkgManifest && pkgManifest.content) {
@@ -299,16 +348,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     }
   }
 
-  // lockfile-missing-integrity (per playbook): "any pinned entry
-  // in walked lockfiles lacks an integrity field (sha512/sha384/
-  // sha256, sri-integrity, go.sum h1: hash)". The predicate
-  // covers every ecosystem's lockfile shape, not just npm. Walk
-  // each supported lockfile and flip the indicator if any one of
-  // them has a missing-integrity entry. When NO lockfile is
-  // present, leave the indicator unflipped (undefined) so the
-  // runner returns inconclusive — a no-lockfile repo is not
-  // evidence of "no missing integrity"; it's evidence we can't
-  // tell, and the playbook covers that case as inconclusive.
+  // Any one lockfile with a missing-integrity entry flips the indicator. With no
+  // lockfile it stays undefined: a repo without one is not evidence of integrity.
   let lockfileMissingIntegrity = undefined;
   const lockfilesChecked = [];
   const lockfileScans = [
@@ -317,15 +358,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       scan: (text) => {
         const j = JSON.parse(text);
         let missing = 0;
-        // Only a REMOTE-tarball entry (`resolved` is an http(s)/git URL) is
-        // expected to carry an integrity hash. Workspace links — npm v3 emits
-        // them as `{ "resolved": "<relative-path>", "link": true }` — and
-        // file:/link:/workspace:/git: refs legitimately have NO integrity (a
-        // local symlink is not a registry artifact). Counting them flips
-        // lockfile-missing-integrity to a false hit on every npm-workspaces
-        // monorepo even when every registry dep is sha512-pinned. Mirrors
-        // sbom.js's local-ref demotion; the bare-relative-path + `link:true`
-        // shape is the canonical workspace link.
+        // Only a remote-tarball entry (`resolved` is an http(s)/git URL) owes an
+        // integrity hash; a workspace link and file:/link:/workspace: refs have
+        // none by nature, and counting them false-hits every workspaces monorepo.
         const walkObj = (obj) => {
           if (!obj || typeof obj !== "object") return;
           if (
@@ -343,8 +378,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     {
       file: "yarn.lock",
       scan: (text) => {
-        // yarn.lock entries: a `resolved "https://..."` line should be
-        // followed within ~5 lines by an `integrity sha512-...` line.
+        // A `resolved "https://..."` line owes an `integrity sha512-...` nearby.
         const lines = text.split(/\r?\n/);
         let missing = 0;
         for (let i = 0; i < lines.length; i++) {
@@ -358,9 +392,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     {
       file: "pnpm-lock.yaml",
       scan: (text) => {
-        // pnpm entries have an `integrity:` field. Count entries
-        // with `resolution: { tarball: ... }` lines whose nearby
-        // block lacks `integrity:`.
+        // A pnpm block carrying `resolution:` owes an `integrity:` field.
         const blocks = text.split(/\n(?=\s+\/)/);
         let missing = 0;
         for (const b of blocks) {
@@ -373,14 +405,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     {
       file: "Cargo.lock",
       scan: (text) => {
-        // Cargo.lock entries have `checksum = "..."` per [[package]]
-        // (registry deps only — path / git deps legitimately have
-        // none, so count only registry packages).
+        // `checksum` is owed per [[package]] by registry deps only.
         const packages = text.split(/^\[\[package\]\]/m).slice(1);
         let missing = 0;
         for (const p of packages) {
-          // Skip path / git deps — they have a `source = "<...>"`
-          // line; registry deps have `source = "registry+..."`.
           const sourceMatch = p.match(/^source\s*=\s*"([^"]+)"/m);
           if (!sourceMatch) continue; // path dep, no integrity expected
           if (!sourceMatch[1].startsWith("registry+")) continue;
@@ -392,8 +420,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     {
       file: "go.sum",
       scan: (text) => {
-        // go.sum entries are `<module> <version> h1:<hash>=`.
-        // Missing-integrity = a line without `h1:` (rare; malformed).
+        // A go.sum line is `<module> <version> h1:<hash>=`; one without `h1:` is malformed.
         const lines = text.split(/\r?\n/).filter(Boolean);
         let missing = 0;
         for (const l of lines) {
@@ -414,8 +441,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
         lockfileMissingIntegrity = "hit";
         break;
       }
-      // If at least one lockfile scanned cleanly, the indicator
-      // moves to miss — we have evidence of integrity coverage.
       if (lockfileMissingIntegrity === undefined) lockfileMissingIntegrity = "miss";
     } catch (e) {
       errors.push({
@@ -425,55 +450,37 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       });
     }
   }
-  // If no supported lockfile was present, leave the indicator
-  // unflipped (undefined). The runner returns inconclusive.
-
-  // SECURITY.md presence (root + .github/SECURITY.md).
   const securityMdPresent =
     fs.existsSync(path.join(root, "SECURITY.md")) ||
     fs.existsSync(path.join(root, ".github", "SECURITY.md"));
 
-  // security.txt presence (.well-known/security.txt + security.txt).
   const securityTxtPresent =
     fs.existsSync(path.join(root, ".well-known", "security.txt")) ||
     fs.existsSync(path.join(root, "security.txt"));
 
-  // sbom-absent-or-unsigned: no sbom file at root, OR sbom file
-  // present but no matching .sig sidecar.
+  // Fires when there is no root SBOM, or one with no matching .sig sidecar.
   let sbomFile = null;
   for (const f of ["sbom.cdx.json", "sbom.json", "bom.json", "sbom.spdx.json", "sbom.cdx.xml"]) {
     if (fs.existsSync(path.join(root, f))) { sbomFile = f; break; }
   }
-  // Many publishers don't commit a static SBOM; they generate a
-  // cosign-signed CycloneDX/SPDX SBOM (and provenance attestation) at
-  // release time inside the publish workflow. Those assets never land in
-  // the committed tree, so a repo-state-only check can't see them. Detect
-  // the *capability* in the publish workflows: an SBOM-generation step
-  // (cyclonedx / syft / anchore-sbom-action / trivy / `npm sbom`), npm
-  // provenance (`--provenance` flag or `publishConfig.provenance: true`),
-  // or a sigstore/cosign signing step. If any is present, the SBOM /
-  // signed-attestation capability exists at release and the indicator
-  // should not fire on the absence of a committed artifact.
+  // An SBOM generated and signed at release time never lands in the committed
+  // tree, so the capability is detected in the publish workflows instead.
   const releaseSbomCapable = publishWorkflows.some(w => {
     const c = stripYamlComments(w.content);
     return (
-      // SBOM-generation tooling invoked in the workflow.
       /cyclonedx/i.test(c) ||
       /\bsyft\b/i.test(c) ||
       /anchore\/sbom-action/i.test(c) ||
       /\btrivy\b[^\n]*\bsbom\b/i.test(c) ||
       /\bnpm\s+sbom\b/.test(c) ||
       /spdx-sbom-generator/i.test(c) ||
-      // npm provenance (signed build provenance attestation at publish).
       /npm\s+publish[^\n]*--provenance\b/.test(c) ||
-      // sigstore / cosign signing of release artifacts.
       /\bcosign\s+(?:sign|attest)\b/.test(c) ||
       /sigstore\//i.test(c) ||
       /gh-action-sigstore-python/i.test(c)
     );
   });
-  // package.json publishConfig.provenance opt-in also signals a signed
-  // provenance attestation is produced at publish time.
+  // The manifest opt-in likewise produces a signed provenance attestation.
   const manifestProvenanceOptIn = (() => {
     if (!pkgManifest || !pkgManifest.content) return false;
     try { return JSON.parse(pkgManifest.content)?.publishConfig?.provenance === true; }
@@ -484,14 +491,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     const sigPath = path.join(root, `${sbomFile}.sig`);
     sbomAbsentOrUnsigned = fs.existsSync(sigPath) ? "miss" : "hit";
   } else if (releaseSbomCapable || manifestProvenanceOptIn) {
-    // No committed SBOM, but the release pipeline generates / signs one
-    // (or emits a signed provenance attestation). Treat the capability
-    // as present-at-release rather than reporting it absent.
     sbomAbsentOrUnsigned = "miss";
   }
 
-  // vendored-no-provenance: vendor/ directory exists without a
-  // _PROVENANCE.json at any level inside it.
+  // Fires when vendor/ exists with no _PROVENANCE.json at any level inside it.
   let vendoredNoProvenance = "miss";
   const vendorDir = path.join(root, "vendor");
   if (fs.existsSync(vendorDir)) {
@@ -505,10 +508,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
         if (e.isDirectory()) {
           if (DEFAULT_EXCLUDES.has(e.name)) continue;
           const sub = path.join(dir, e.name);
-          // Don't descend into a linked git worktree nested under
-          // vendor/ — its `.git` is a gitdir pointer file, and a repo
-          // copy stamped by agent tooling carries unrelated provenance
-          // state that shouldn't count toward this tree's vendoring.
+          // A linked worktree under vendor/ is a separate repo copy.
           if (isLinkedWorktreeDir(sub)) continue;
           walkVendor(sub, depth + 1);
         }
@@ -530,19 +530,14 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "no-security-txt": securityTxtPresent ? "miss" : "hit",
     "vendored-no-provenance": vendoredNoProvenance,
   };
-  // Conditionally include lockfile-missing-integrity — leave it
-  // out (so the runner returns inconclusive) when no supported
-  // lockfile was present to scan.
+  // Omitted when no lockfile was there to scan, so the runner reads inconclusive.
   if (lockfileMissingIntegrity !== undefined) {
     signal_overrides["lockfile-missing-integrity"] = lockfileMissingIntegrity;
   }
 
-  // __fp_checks attestation for publish-workflow-action-refs-mutable. Both
-  // false_positive_checks_required entries are deterministic from the repo:
-  //   [0] Dependabot configured for github-actions on a weekly+ schedule
-  //       demotes the finding — attest survival when no such config exists.
-  //   [1] every mutable ref pointing to a github-owned action is lower risk —
-  //       attest survival when at least one mutable ref is third-party.
+  // The keys "0" and "1" are positional indexes into the indicator's
+  // false_positive_checks_required list: [0] Dependabot on github-actions demotes,
+  // [1] all-github-owned refs are lower risk. Reordering that list mis-attests.
   if (signal_overrides["publish-workflow-action-refs-mutable"] === "hit") {
     let dependabotActions = false;
     try {
@@ -567,12 +562,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     if (Object.keys(att).length) signal_overrides["publish-workflow-action-refs-mutable__fp_checks"] = att;
   }
 
-  // Per-indicator file locations for the publish-workflow indicators
-  // flipped to "hit", so a SARIF result points at the workflow file (and,
-  // for mutable action refs, the offending `uses:` line). The other
-  // indicators (provenance / sbom / security.md / security.txt / vendor /
-  // lockfile) reflect a whole-repo presence-or-absence state with no single
-  // offending file, so they carry no file-level location here.
+  // Only the workflow indicators get locations, so a SARIF result can point at the
+  // offending `uses:` line; the rest are whole-repo presence or absence.
   const evidence_locations = {};
   for (const id of Object.keys(workflowHits)) {
     if (signal_overrides[id] === "hit") {
@@ -610,13 +601,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   return {
     precondition_checks: {
       "publisher-context": manifests.length > 0,
-      // Auto-attest the playbook's publishable-artifact-evidence gate from what
-      // we collected (a package manifest or a publish workflow): the runner
-      // can't probe the scanned --cwd, so otherwise a repo that clearly has a
-      // manifest surfaces a spurious precondition_unverified warning. (The
-      // repo-walk-access HALT gate is intentionally NOT attested here — it is
-      // resolved host-side and attesting it from the collector would turn a
-      // currently-passing run on a non-git dir into a fail-closed halt.)
+      // Attested here because the runner cannot probe the scanned --cwd. The
+      // repo-walk-access HALT gate must not be attested from the collector: it is
+      // resolved host-side, and attesting it turns a passing run into a halt.
       "publishable-artifact-evidence": manifests.length > 0 || publishWorkflows.length > 0,
     },
     artifacts,