@blamejs/exceptd-skills 0.19.33 → 0.19.35

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,13 @@ 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.
-        try { fs.realpathSync(full); } catch { /* dangling link — ignore */ }
+        // A symlink Dirent is neither isDirectory() nor isFile(), so it is
+        // never traversed and never emitted — including a dangling one.
+        continue;
       } 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 +100,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 +131,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;