@blamejs/exceptd-skills 0.19.33 → 0.19.34

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 = [
@@ -203,16 +180,12 @@ function captureLockfile(p, ecosystem, parser, label) {
 
 function findLockfiles(cwd) {
   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
@@ -225,11 +198,6 @@ function findLockfiles(cwd) {
     }
   } catch { /* swallow */ }
 
-  // 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;
@@ -239,9 +207,7 @@ function findLockfiles(cwd) {
     } catch { 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 +220,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) {
@@ -284,21 +247,16 @@ function findSbomDocuments(cwd) {
   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; }
     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.
+      // 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 { content = null; }
       let component_count = null;
       if (content && s.format === "cyclonedx-1.x") {
@@ -322,9 +280,7 @@ 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.
+  // sbom-tool-available: a lockfile or an SBOM document is a sufficient proxy.
   const lockfiles = findLockfiles(root);
   const sbomDocuments = findSbomDocuments(root);
   const hasAnything = lockfiles.length > 0 || sbomDocuments.length > 0;
@@ -344,22 +300,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 +310,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 +330,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 +344,14 @@ 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.
+      // A malformed lockfile leaves the indicator unflipped: 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 +361,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,

package/lib/collectors/scan-excludes.js

@@ -1,72 +1,33 @@
 "use strict";
 
 /**
- * lib/collectors/scan-excludes.js
- *
- * Shared directory-walk exclusion policy for every code-scope collector.
- *
- * Before this existed, each collector hard-coded its own exclude Set. None
- * skipped agent/editor worktree copies (`.claude/worktrees/`), so a tree
- * holding N detached worktrees scanned each one as a full repo — inflating
- * hit counts to N+1 duplicates of the same source and forcing manual dedup.
- *
- * Two layers:
- *   1. NAME exclusions — directory basenames never worth descending into
- *      (dependency caches, build output, VCS metadata, agent scratch).
- *   2. A LINKED-WORKTREE predicate — a directory that is itself a git
- *      worktree distinct from the scan root. A `git worktree add` target
- *      carries a `.git` *file* (a gitdir pointer) rather than a `.git`
- *      directory; agent tools frequently stamp full repo copies under
- *      `.claude/worktrees/`. Skipping these keeps a scan to the one tree
- *      the operator actually pointed at.
- *
- * Collectors apply both: spread DEFAULT_CODE_EXCLUDES into their exclude
- * Set, and call isLinkedWorktreeDir(fullPath) before descending into a
- * subdirectory.
+ * Shared directory-walk exclusion policy for every code-scope collector: a set of
+ * directory basenames never worth descending into, and a predicate for linked git
+ * worktrees, which rescan the host tree's source and multiply every hit.
+ * Collectors spread DEFAULT_CODE_EXCLUDES into their exclude Set and call
+ * isLinkedWorktreeDir(fullPath) before descending.
  */
 
 const fs = require("node:fs");
 const path = require("node:path");
 
-// Directory basenames excluded from every code-scope walk. Superset of the
-// per-collector lists that predated this module, plus agent/editor scratch
-// (`.claude`) and additional dependency/build caches that only ever hold
-// generated or third-party content.
 const DEFAULT_CODE_EXCLUDES = Object.freeze([
-  // VCS + agent/editor scratch
   ".git", ".hg", ".svn", ".claude", ".idea", ".vscode",
-  // dependency trees / package caches
   "node_modules", ".pnpm-store", "bower_components",
   ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache",
   ".tox", ".gradle", ".m2",
-  // build output
   "dist", "build", "out", "target", "coverage",
   ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
 ]);
 
-/**
- * Build an exclude Set for a collector. Pass any collector-specific extra
- * basenames; they are merged with the shared defaults.
- *
- * @param {Iterable<string>} [extra] additional basenames to exclude
- * @returns {Set<string>}
- */
 function codeExcludeSet(extra = []) {
   return new Set([...DEFAULT_CODE_EXCLUDES, ...extra]);
 }
 
 /**
- * True when `dir` is a git worktree linked to a repository elsewhere — i.e.
- * its `.git` entry is a file (a `gitdir: …` pointer) rather than a directory.
- * These are detached copies created by `git worktree add` (commonly under
- * `.claude/worktrees/<id>/`); descending into them rescans unrelated repo
- * state. A normal repo root has a `.git` *directory* and is NOT skipped.
- *
- * Cheap and synchronous: one lstat. Returns false on any error so a walk
- * never aborts on a permission/race issue.
- *
- * @param {string} dir absolute path to a candidate directory
- * @returns {boolean}
+ * True when `dir` is a git worktree linked elsewhere — its `.git` entry is a file
+ * (a `gitdir: …` pointer), where a normal repo root has a `.git` *directory* and
+ * is NOT skipped. Returns false on any error, so a walk never aborts on a race.
  */
 function isLinkedWorktreeDir(dir) {
   try {
@@ -79,46 +40,14 @@ function isLinkedWorktreeDir(dir) {
 }
 
 /**
- * Shared cwd-tree walker for every code-scope collector. Returns one entry
- * per regular file as `{ full, rel, name }` — the exact shape the four
- * collectors (secrets / crypto-codebase / containers / citation-hygiene)
- * built with their own near-identical local walkers.
- *
- * Behavior preserved from those walkers:
- *   - Directory basenames in `excludes` are never descended into.
- *   - A linked git worktree (its `.git` is a gitdir-pointer FILE) is never
- *     descended into (isLinkedWorktreeDir).
- *   - Recursion follows ONLY real directories (`entry.isDirectory()`).
- *     Symlinks are never traversed and symlink targets are never emitted
- *     as files — matching the old behavior where a Dirent for a symlink is
- *     neither isDirectory() nor isFile(), so it fell through both branches.
- *   - Depth is capped at `maxDepth`.
- *
- * Performance: `fs.realpathSync` is called ONLY on directories and symlinks
- * (the only entries that can introduce a traversal cycle), never on regular
- * files. The old walkers realpath'd every file entry, which on a large repo
- * dominated walk time. A regular file cannot create a directory cycle, so
- * dropping its realpath preserves cycle protection exactly while removing
- * the per-file syscall. The symlink-cycle `seen` set still guards every
- * directory and symlink by canonical path.
- *
- * Depth-cap visibility: a subtree pruned because it would exceed `maxDepth`
- * is otherwise an invisible coverage gap — the files inside are never emitted
- * and the caller cannot tell "scanned, nothing there" from "never scanned".
- * Pass `opts.truncations` (an array) to have the walker push one
- * `{ rel, depth }` entry per directory whose contents were skipped for being
- * beyond the cap, so a content collector can surface a `depth_capped` notice
- * symmetric with its per-file size-cap reporting. The return value is
- * unchanged (the file array); callers that don't pass `truncations` are
- * unaffected.
+ * Shared cwd-tree walker for every code-scope collector. Returns one entry per
+ * regular file as `{ full, rel, name }`, `rel` forward-slashed on every platform.
+ * Directory basenames in `excludes` and linked git worktrees are never descended
+ * into, recursion follows only real directories — a symlink is neither traversed
+ * nor emitted — and depth is capped at `maxDepth`.
  *
- * @param {string} root absolute scan root
- * @param {object} [opts]
- * @param {number} [opts.maxDepth] max recursion depth (collector-specific)
- * @param {Set<string>} [opts.excludes] directory basenames to skip
- * @param {Array<{rel:string, depth:number}>} [opts.truncations] out-param the
- *        walker appends to when a directory is pruned for exceeding maxDepth
- * @returns {Array<{full:string, rel:string, name:string}>}
+ * `opts.truncations`, when an array, is an out-param: one `{ rel, depth }` per
+ * directory pruned for exceeding the cap. The return value is the file array.
  */
 function walkTree(root, opts = {}) {
   const maxDepth = opts.maxDepth ?? 6;
@@ -137,21 +66,14 @@ function walkTree(root, opts = {}) {
       const full = path.join(dir, entry.name);
 
       if (entry.isDirectory()) {
-        // Cycle guard: canonicalize directories (and symlinks below) so a
-        // symlinked or bind-mounted loop is visited at most once. realpath
-        // here is bounded by directory count, not file count.
+        // Cycle guard: canonicalize so a symlinked or bind-mounted loop is
+        // visited at most once.
         let real;
         try { real = fs.realpathSync(full); } catch { continue; }
         if (seen.has(real)) continue;
         seen.add(real);
-        // Never descend into a linked git worktree (its `.git` is a gitdir
-        // pointer file) — agent tooling stamps full repo copies under
-        // `.claude/worktrees/<id>/`; walking them rescans the same source
-        // as the host tree and multiplies every hit.
         if (isLinkedWorktreeDir(full)) continue;
-        // Descending would land at depth+1 > maxDepth: the directory's
-        // contents are about to be dropped. Record the prune so the caller
-        // can report the unscanned subtree instead of silently missing it.
+        // Checked before descending, so the pruned directory can be recorded.
         if (depth + 1 > maxDepth) {
           if (truncations) {
             truncations.push({
@@ -163,19 +85,12 @@ function walkTree(root, opts = {}) {
         }
         walk(full, depth + 1);
       } else if (entry.isSymbolicLink()) {
-        // A symlink Dirent is neither isDirectory() nor isFile(). The old
-        // walkers realpath'd it (adding the target to `seen`) and then
-        // emitted nothing, because neither branch matched. Preserve that:
-        // canonicalize for the cycle guard, never emit, never traverse.
+        // A symlink Dirent is neither isDirectory() nor isFile(): never emitted.
         try { fs.realpathSync(full); } catch { /* dangling link — ignore */ }
       } else if (entry.isFile()) {
-        // Regular files cannot introduce a directory cycle, so no realpath /
-        // `seen` check is needed. This is the hot path — it runs once per
-        // file in the tree and is now syscall-free beyond the parent
-        // readdir.
-        // Emit forward-slash rel paths on every platform so artifact
-        // summaries match the SARIF evidence_locations (which normalize the
-        // same way) — on Windows path.relative returns backslash separators.
+        // A regular file cannot introduce a directory cycle, so no realpath /
+        // `seen` check. Windows path.relative returns backslashes, so rel is
+        // normalized to match SARIF locations.
         out.push({ full, rel: path.relative(root, full).split(path.sep).join("/"), name: entry.name });
       }
     }
@@ -184,27 +99,15 @@ function walkTree(root, opts = {}) {
   return out;
 }
 
-// Per-indicator cap so a flood of identical findings can't bloat a SARIF
-// upload. 50 locations per result is well within GitHub code-scanning's
-// rendering budget while still showing the operator where every distinct
-// finding lives.
+// Per-indicator cap: 50 sits well inside GitHub code-scanning's rendering budget.
 const MAX_EVIDENCE_LOCATIONS_PER_INDICATOR = 50;
 
 /**
- * Turn a collector's per-indicator file hits into the `evidence_locations`
- * entry the runner threads onto a firing indicator for SARIF
- * `results[].locations`. Each hit contributes a `{ uri, startLine? }` where
- * `uri` is the repo-relative file path the collector already recorded and
- * `startLine` is included only when a real (non-placeholder) line number is
- * present — many collectors store `line: 0` to mean "file-level, no line",
- * which omits the region so SARIF points at the file rather than line 0.
- *
- * Identical `{ uri, startLine }` entries are de-duplicated and the list is
- * capped at MAX_EVIDENCE_LOCATIONS_PER_INDICATOR.
- *
- * @param {Array<object>} hits  entries with a `rel` or `file` repo-relative
- *                              path and an optional `line` number
- * @returns {Array<{uri:string,startLine?:number}>}
+ * Turns a collector's per-indicator file hits into `evidence_locations` for SARIF
+ * `results[].locations`. Each hit yields `{ uri, startLine? }` from its `rel` (or
+ * `file`) repo-relative path; `startLine` is emitted only above zero, because
+ * collectors store `line: 0` to mean "file-level, no line". Identical entries
+ * de-duplicate; the list caps at MAX_EVIDENCE_LOCATIONS_PER_INDICATOR.
  */
 function buildEvidenceLocations(hits) {
   if (!Array.isArray(hits) || hits.length === 0) return [];
@@ -227,19 +130,9 @@ function buildEvidenceLocations(hits) {
 }
 
 /**
- * Convert a byte/char offset into a file's text to a 1-based line number.
- * Content-regex collectors record the offset of a match (`m.index`) but not
- * a line, which left `buildEvidenceLocations` emitting a file-level location
- * with no region. Pairing the offset with this helper lets SARIF point at the
- * exact line.
- *
- * Returns 1 for offset 0 / a non-finite offset (file-level fallback at the
- * first line). Counts `\n` occurrences before the offset; `\r\n` is handled
- * because the `\n` is what increments the line.
- *
- * @param {string} content the file text the offset indexes into
- * @param {number} offset  0-based offset of the match within `content`
- * @returns {number} 1-based line number
+ * Converts a 0-based offset into `content` to a 1-based line number, so a
+ * content-regex collector can pair a match's `m.index` with a SARIF region.
+ * Returns 1 for offset 0 or a non-finite offset. Counts `\n`, covering `\r\n`.
  */
 function lineFromOffset(content, offset) {
   if (typeof content !== "string") return 1;