@vibe-agent-toolkit/utils 0.2.0-rc.6 → 0.2.0-rc.8

package/dist/git-utils.js

@@ -4,9 +4,118 @@
  */
 import { existsSync } from 'node:fs';
 import { dirname, parse } from 'node:path';
+import { directoryRefusalFor, listingFailure } from './fs-utils.js';
 import { lookupGitRoot, rememberGitRoot } from './git-root-cache.js';
 import { runGit } from './git-run.js';
+import { requireUnreadablePolicy, settleRefusal } from './listing-refusal.js';
 import { safePath } from './path-utils.js';
+/**
+ * One line of git's stderr that means "I skipped this directory".
+ *
+ * `git ls-files --others` (and `--ignored`, and `git add --all`) walks the
+ * working tree to find untracked files. On a directory it cannot open it prints
+ * this warning, exits 0, and omits the subtree — so stdout alone is a shorter
+ * list that nothing can tell from a complete one. The path is spelled
+ * **relative to the worktree root** with a trailing slash, even when git was
+ * run from a subdirectory (measured: cwd `docs/open`, warning names
+ * `'docs/open/sub/'`).
+ *
+ * Anchored to the line so an unrelated warning naming a directory in passing
+ * is not read as a refusal. The reason after the colon is `strerror` text —
+ * see {@link STRERROR_TO_ERRNO}.
+ */
+const UNLISTABLE_DIRECTORY_LINE = /^warning: could not open directory '(.+?)\/?': (.*)$/gm;
+/**
+ * C-locale `strerror` text → errno, for the reasons git can print here.
+ *
+ * git does not print the errno name, only its message; every listing below
+ * runs with `LC_ALL=C` so the message is the C-locale one and this table can
+ * be short. An unlisted reason is still a refusal — it becomes `UNKNOWN`, the
+ * same answer `listingFailure` gives an error carrying no errno — because
+ * dropping the line would reinstate the silent gap for exactly the errnos
+ * nobody thought of.
+ *
+ * The two ABSENCE reasons are listed so that `listingFailure` — the one owner
+ * of the absent/unreadable split — can recognise them and the line can be
+ * skipped: git prints "No such file or directory" for an untracked directory
+ * deleted between its parent's `readdir` and its own `opendir` (a concurrent
+ * `rm -rf tmp/`), and the walk route treats that same race as "no longer in
+ * the population" rather than as a refusal. Left unmapped it read as an
+ * `UNKNOWN` refusal, and the git route aborted a run the walk completed.
+ */
+const STRERROR_TO_ERRNO = new Map([
+    ['Permission denied', 'EACCES'],
+    ['Too many open files', 'EMFILE'],
+    ['Too many open files in system', 'ENFILE'],
+    ['Too many levels of symbolic links', 'ELOOP'],
+    ['Resource temporarily unavailable', 'EAGAIN'],
+    ['Input/output error', 'EIO'],
+    ['Stale file handle', 'ESTALE'],
+    ['Stale NFS file handle', 'ESTALE'],
+    ['No such file or directory', 'ENOENT'],
+    ['Not a directory', 'ENOTDIR'],
+]);
+/**
+ * The directories a git listing was REFUSED, read off its stderr.
+ *
+ * Pure. Returns each refused directory once, worktree-relative and without
+ * git's trailing slash, with the errno its reason maps to. A directory git
+ * could not open because it no longer exists is not returned: that is the
+ * `absent` outcome of {@link listingFailure}, decided there and not here, so
+ * the two routes classify a vanished directory the same way.
+ *
+ * @param stderr - What the listing wrote to stderr
+ * @returns The refusals, in the order git printed them, deduplicated
+ */
+export function unlistableDirectoriesIn(stderr) {
+    const seen = new Set();
+    const refusals = [];
+    for (const match of stderr.matchAll(UNLISTABLE_DIRECTORY_LINE)) {
+        const directory = match[1] ?? '';
+        if (directory === '' || seen.has(directory))
+            continue;
+        seen.add(directory);
+        const listing = listingFailure({ code: STRERROR_TO_ERRNO.get((match[2] ?? '').trim()) });
+        if (listing.outcome === 'unreadable')
+            refusals.push({ directory, code: listing.code });
+    }
+    return refusals;
+}
+/**
+ * Run one NUL-delimited `ls-files` listing and report what git skipped.
+ *
+ * `LC_ALL=C` so the stderr reason is the C-locale `strerror` text the parser
+ * knows; `trim: false` because the output is NUL-delimited (see the callers).
+ *
+ * @param args - The `ls-files` argv
+ * @param cwd - Where to run it
+ * @param api - The entry point, for the sentence an omitted policy gets
+ * @param unreadable - What a skipped directory means to the caller
+ * @returns The listed paths, or null when git did not answer
+ */
+function runListing(args, cwd, api, unreadable) {
+    // Before the spawn: an omitted policy is a programming error, not a fact
+    // about the tree, and a tree with nothing unreadable must not hide it.
+    requireUnreadablePolicy(unreadable, api);
+    const result = runGit(args, { cwd, trim: false, env: { LC_ALL: 'C' } });
+    // Every failure means the same thing to this caller — no listing. That covers
+    // "not a repository" (128), git missing entirely, and a listing too large for
+    // the buffer, which `ok` folds in because a truncated answer here is files
+    // silently missing rather than a short list.
+    if (!result.ok) {
+        return null;
+    }
+    if (result.stderr !== '') {
+        // The warning is worktree-root-relative regardless of `cwd`.
+        const worktreeRoot = gitFindRoot(cwd) ?? cwd;
+        for (const { directory, code } of unlistableDirectoriesIn(result.stderr)) {
+            settleRefusal(unreadable, directoryRefusalFor({ outcome: 'unreadable', code }, safePath.resolve(worktreeRoot, directory)));
+        }
+    }
+    // NUL-separated (from -z), so no path can ever need quote-unescaping — a
+    // trailing NUL just produces one empty string at the end, dropped here.
+    return result.stdout.split('\0').filter((line) => line.length > 0);
+}
 /**
  * Find the git repository root by walking up from the given directory.
  *
@@ -34,7 +143,6 @@ export function gitFindRoot(startDir) {
             return rememberGitRoot(climbed, memoized);
         climbed.push(currentDir);
         const gitDir = safePath.join(currentDir, '.git');
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walking up from validated startDir
         if (existsSync(gitDir)) {
             return rememberGitRoot(climbed, currentDir);
         }
@@ -49,6 +157,8 @@ export function gitFindRoot(startDir) {
  * @param options.cwd - Working directory (git repository root or subdirectory)
  * @param options.patterns - Optional glob patterns to filter files (e.g., '*.md', 'docs/**\/*.ts')
  * @param options.includeUntracked - Include untracked files that aren't gitignored (default: false)
+ * @param options.unreadable - See {@link GitListingOptions}. Only the untracked
+ *   listing walks the working tree, so only it can have skipped a directory
  * @returns Array of file paths relative to the git root, or null if not in a git repo
  *
  * @example
@@ -74,20 +184,10 @@ export function gitLsFiles(options) {
     if (options.patterns && options.patterns.length > 0) {
         args.push('--', ...options.patterns);
     }
-    // `trim: false` because the output is NUL-delimited: git sorts by byte value,
-    // so a path beginning with a space sorts FIRST and a trim would silently
-    // rename it to a path that does not exist.
-    const result = runGit(args, { cwd: options.cwd, trim: false });
-    // Every failure means the same thing to this caller — no listing. That covers
-    // "not a repository" (128), git missing entirely, and a listing too large for
-    // the buffer, which `ok` folds in because a truncated answer here is files
-    // silently missing rather than a short list.
-    if (!result.ok) {
-        return null;
-    }
-    // NUL-separated (from -z above), so no path can ever need quote-unescaping —
-    // a trailing NUL just produces one empty string at the end, dropped below.
-    return result.stdout.split('\0').filter((line) => line.length > 0);
+    // `trim: false` (inside `runListing`) because the output is NUL-delimited:
+    // git sorts by byte value, so a path beginning with a space sorts FIRST and a
+    // trim would silently rename it to a path that does not exist.
+    return runListing(args, options.cwd, 'gitLsFiles', options.unreadable);
 }
 /**
  * List paths git does NOT track, with each wholly-untracked directory collapsed
@@ -113,6 +213,13 @@ export function gitLsFiles(options) {
  *   untracked directory, since a directory with no files in it is invisible to
  *   `ls-files` and to any tree object
  * @param options.directory - Collapse a wholly-untracked directory to one entry
+ * @param options.unreadable - See {@link GitListingOptions}. ⚠️ The two
+ *   listings meet different refusals: without `--ignored`, git collapses a
+ *   WHOLLY-untracked directory without opening it, but it still opens a
+ *   non-ignored directory that holds tracked files (to look for untracked
+ *   siblings) and warns when it cannot; the `ignored` listing opens every
+ *   non-ignored directory and so meets every refusal the first one does and
+ *   more (measured on git 2.50)
  * @returns Paths relative to the git root, or null if git did not answer
  *
  * @example
@@ -136,11 +243,7 @@ export function gitLsOthers(options) {
     }
     // See `gitLsFiles`: NUL-delimited output must not be trimmed, or a path
     // beginning with a space — which git sorts FIRST — comes back renamed.
-    const result = runGit(args, { cwd: options.cwd, trim: false });
-    if (!result.ok) {
-        return null;
-    }
-    return result.stdout.split('\0').filter((line) => line.length > 0);
+    return runListing(args, options.cwd, 'gitLsOthers', options.unreadable);
 }
 /**
  * Check if a file path is ignored by git

package/dist/git-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-utils.js","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"git-utils.js","sourceRoot":"","sources":["../src/git-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAyB,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,yBAAyB,GAAG,wDAAwD,CAAC;AAE3F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAC;IAC7D,CAAC,mBAAmB,EAAE,QAAQ,CAAC;IAC/B,CAAC,qBAAqB,EAAE,QAAQ,CAAC;IACjC,CAAC,+BAA+B,EAAE,QAAQ,CAAC;IAC3C,CAAC,mCAAmC,EAAE,OAAO,CAAC;IAC9C,CAAC,kCAAkC,EAAE,QAAQ,CAAC;IAC9C,CAAC,oBAAoB,EAAE,KAAK,CAAC;IAC7B,CAAC,mBAAmB,EAAE,QAAQ,CAAC;IAC/B,CAAC,uBAAuB,EAAE,QAAQ,CAAC;IACnC,CAAC,2BAA2B,EAAE,QAAQ,CAAC;IACvC,CAAC,iBAAiB,EAAE,SAAS,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAA0C,EAAE,CAAC;IAC3D,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,SAAS,KAAK,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QACtD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QACzF,IAAI,OAAO,CAAC,OAAO,KAAK,YAAY;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAsBD;;;;;;;;;;;GAWG;AACH,SAAS,UAAU,CACjB,IAAuB,EACvB,GAAW,EACX,GAAW,EACX,UAAwC;IAExC,yEAAyE;IACzE,uEAAuE;IACvE,uBAAuB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAExE,8EAA8E;IAC9E,8EAA8E;IAC9E,2EAA2E;IAC3E,6CAA6C;IAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACzB,6DAA6D;QAC7D,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAC7C,KAAK,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACzE,aAAa,CACX,UAAU,EACV,mBAAmB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,CAChG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACrE,CAAC;AAGD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;IACpC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,OAAO,UAAU,KAAK,IAAI,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEzB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,OAAO,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC9C,CAAC;QACD,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,UAAU,CAAC,OAI1B;IACC,6EAA6E;IAC7E,yEAAyE;IACzE,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAEhC,iDAAiD;IACjD,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC;IAC1D,CAAC;IAED,2BAA2B;IAC3B,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,2EAA2E;IAC3E,8EAA8E;IAC9E,+DAA+D;IAC/D,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,WAAW,CAAC,OAI3B;IACC,6EAA6E;IAC7E,8EAA8E;IAC9E,8EAA8E;IAC9E,2BAA2B;IAC3B,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC;IAElE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC3B,CAAC;IAED,wEAAwE;IACxE,uEAAuE;IACvE,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,oFAAoF;IACpF,qFAAqF;IACrF,mFAAmF;IACnF,kFAAkF;IAClF,oFAAoF;IACpF,qFAAqF;IACrF,4EAA4E;IAC5E,+EAA+E;IAC/E,EAAE;IACF,gFAAgF;IAChF,uCAAuC;IACvC,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,eAAe,GAAG,CAAC,cAAc,EAAE,IAAI,CAAU,CAAC;IAExD,oEAAoE;IACpE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,eAAe,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAE/D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mEAAmE;IACnE,mEAAmE;IACnE,0EAA0E;IAC1E,yCAAyC;IACzC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACrD,IAAI,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAEpC,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACzE,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,GAAG,eAAe,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACtE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,6DAA6D;YAC7D,sEAAsE;YACtE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChC,MAAM;YACR,CAAC;YACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/git.d.ts

@@ -24,6 +24,7 @@
  */
 export { runGit, runGitOrThrow, type GitRunOptions, type GitRunResult, } from './git-run.js';
 export { gitFindRoot, gitLsFiles, gitLsOthers, isGitIgnored } from './git-utils.js';
+export type { RefuseListingContext, UnreadablePolicy } from './listing-refusal.js';
 export { gitTreeSnapshot, peekGitTreeSnapshot, withGitSnapshotCache, type GitSnapshotEntry, type GitTreeSnapshot, } from './git-snapshot.js';
 export { loadGitignoreRules } from './gitignore-checker.js';
 export { GitTracker, type GitTrackerInitOptions } from './git-tracker.js';

package/dist/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,MAAM,EACN,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,WAAW,EACX,KAAK,0BAA0B,EAC/B,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,MAAM,EACN,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIpF,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,WAAW,EACX,KAAK,0BAA0B,EAC/B,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC"}

package/dist/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,MAAM,EACN,aAAa,GAGd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAA8B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,WAAW,GAGZ,MAAM,cAAc,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,MAAM,EACN,aAAa,GAGd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKpF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAA8B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,WAAW,GAGZ,MAAM,cAAc,CAAC"}

package/dist/gitignore-checker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore-checker.d.ts","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAe,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAK7C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0CnF"}
+{"version":3,"file":"gitignore-checker.d.ts","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAe,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAM7C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8CnF"}

package/dist/gitignore-checker.js

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import ignore from 'ignore';
+import { isPathAbsentError } from './errors/errno.js';
 import { safePath, toForwardSlash } from './path-utils.js';
 import { readTextContentSync } from './text-file.js';
 /**
@@ -40,7 +41,6 @@ export function loadGitignoreRules(gitRoot, baseDir) {
     // Load .gitignore files from git root down to baseDir
     for (const dir of dirsToCheck) {
         const gitignorePath = safePath.join(dir, '.gitignore');
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from validated gitRoot and baseDir
         if (fs.existsSync(gitignorePath)) {
             try {
                 // Through the decoding seam. A `.gitignore` written by PowerShell's `>`
@@ -49,8 +49,14 @@ export function loadGitignoreRules(gitRoot, baseDir) {
                 // no error anywhere.
                 ig.add(readTextContentSync(gitignorePath).text);
             }
-            catch {
-                // Skip gitignore files we can't read
+            catch (error) {
+                // Gone between `existsSync` and the read: no rules here. A `.gitignore`
+                // the OS refuses to read (`EACCES`), or one that is a directory
+                // (`EISDIR`), holds rules this checker cannot honour — and a crawl that
+                // quietly proceeded without them enumerated the ignored tree with
+                // nothing anywhere saying so. Those stay loud.
+                if (!isPathAbsentError(error))
+                    throw error;
             }
         }
     }

package/dist/gitignore-checker.js.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore-checker.js","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,MAAuB,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAgB;IAClE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,+BAA+B;IAC/B,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACf,QAAQ,GAAG,IAAI,CAAC;IAEhB,kDAAkD;IAClD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;IACtD,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD,+CAA+C;IAC/C,MAAM,iBAAiB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAE1D,OAAO,cAAc,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM;QACR,CAAC;QACD,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACvD,qHAAqH;QACrH,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,wEAAwE;gBACxE,oEAAoE;gBACpE,yEAAyE;gBACzE,qBAAqB;gBACrB,EAAE,CAAC,GAAG,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,qCAAqC;YACvC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"gitignore-checker.js","sourceRoot":"","sources":["../src/gitignore-checker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,MAAuB,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAgB;IAClE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,+BAA+B;IAC/B,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACf,QAAQ,GAAG,IAAI,CAAC;IAEhB,kDAAkD;IAClD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;IACtD,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD,+CAA+C;IAC/C,MAAM,iBAAiB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAE1D,OAAO,cAAc,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAChE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM;QACR,CAAC;QACD,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACvD,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,wEAAwE;gBACxE,oEAAoE;gBACpE,yEAAyE;gBACzE,qBAAqB;gBACrB,EAAE,CAAC,GAAG,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wEAAwE;gBACxE,gEAAgE;gBAChE,wEAAwE;gBACxE,kEAAkE;gBAClE,+CAA+C;gBAC/C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBAAE,MAAM,KAAK,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC"}

package/dist/index.d.ts

@@ -22,20 +22,26 @@
  * here — directly or transitively, through any module below — turns that row red
  * and has to be an argued edit rather than an unnoticed one.
  */
+export * from './errors/vat-error.js';
 export * from './path-utils.js';
+export * from './path-containment.js';
+export * from './dirent-kind.js';
 export * from './text-content.js';
 export * from './text-file.js';
 export * from './asset-reference.js';
-export { classifyFilenameCaseFrom, copyDirectory, fillRealpaths, fillSiblingNames, FsLookupCache, isFilesystemAccessError, realpathFrom, } from './fs-utils.js';
-export type { FilenameCaseVerdict, FilenameMatch, PathProbe, PathProbeStats, RealpathTable, SiblingNamesTable, } from './fs-utils.js';
+export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
+export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
+export type { AbsenceCause, ComponentMatch, FilenameMatch, PathProbe, PathProbeStats, PathSpelling, PathSpellingRequest, PathSpellingTable, RealpathTable, VerifiedPrefix, } from './fs-utils.js';
 export * from './project-utils.js';
-export * from './test-helpers.js';
+export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_GIT_ENV, symlinkCapability, type SymlinkCapability, } from './test-helpers.js';
 export * from './zod-introspection.js';
 export * from './skill-targets.js';
 export * from './glob/glob-pattern.js';
 export * from './fs/file-hash.js';
 export { parseWholeNumberAtLeast } from './numeric-args.js';
+export { parseEnvBoolean } from './env-flag.js';
 export { compareCodeUnits } from './compare-code-units.js';
-export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, type CrawlDriverStratum, type CrawlStratum, type CrawlTimingDump, type CrawlTimingEntry, type CrawlTimingProcess, __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
+export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, type CrawlDriverStratum, type CrawlStratum, type CrawlTimingDump, type CrawlTimingEntry, type CrawlTimingProcess, } from './crawl-timing.js';
 export { ensureTimingDirectory, normalizeTimingDirectory, readTimingProcess, type TimingProcess, writeTimingDump, } from './timing-dump.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,cAAc,iBAAiB,CAAC;AAShC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAqCrC,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAIvB,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAgB3D,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,cAAc,uBAAuB,CAAC;AAGtC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC;AASjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAyCrC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,aAAa,EACb,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAC;AAIvB,cAAc,oBAAoB,CAAC;AASnC,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AAGvC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAK5D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAgB3D,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -22,8 +22,15 @@
  * here — directly or transitively, through any module below — turns that row red
  * and has to be an argued edit rather than an unnoticed one.
  */
+// The base of every error VAT throws on purpose; `code` is what a catch
+// block dispatches on, never `message`.
+export * from './errors/vat-error.js';
 // Cross-platform path utilities
 export * from './path-utils.js';
+// The filesystem-backed containment verdict every delete/copy/uninstall sink asks.
+export * from './path-containment.js';
+// The Dirent classifiers a walk uses instead of a bare isFile()/isDirectory().
+export * from './dirent-kind.js';
 // THE content-decoding seam: bytes to text, in one place. `decodeTextContent` is
 // pure and also reachable from the dependency-free `./text` entry; the two
 // file-reading wrappers need `node:fs` and are also on `./fs`. Other routes from
@@ -37,45 +44,59 @@ export * from './text-file.js';
 export * from './asset-reference.js';
 // Filesystem utilities.
 //
-// Named rather than `export *` on purpose: `classifyFilenameCase` (the pure
-// judge over a hand-held row) and `siblingNamesFrom` (the table lookup that
-// throws on a miss) are internal members of the fill+judge pairs below, and a
-// star re-export would publish them on this barrel the moment they were written.
-// (The `./fs` subpath was already an explicit list and was never at risk.) The
-// public surface is a decision, not a side effect of module layout.
+// Named rather than `export *` on purpose: `fs-utils.ts` holds internal members
+// of the fill+judge pairs below — the per-directory index build, the table-key
+// derivation — and a star re-export would publish each of them on this barrel
+// the moment it was written. (The `./fs` subpath was already an explicit list
+// and was never at risk.) The public surface is a decision, not a side effect of
+// module layout.
 //
 // TWO materialized columns are published, both shaped fill-first-then-judge:
 //
-//   - sibling names — `fillSiblingNames` (every listing, once, up front) plus
-//     `classifyFilenameCaseFrom` (pure judgement over the filled table). Its row
-//     lookup `siblingNamesFrom` stays internal because a row there is not yet an
-//     answer: it still needs a judge, and that judge is what we export.
+//   - path spellings — `fillPathSpellings` plus `pathSpellingFrom`. It judges a
+//     WHOLE path, which is what a caller validating references needs: judging
+//     only the basename hands every directory component back to the host
+//     filesystem's own folding, so a link that resolves on macOS 404s on a
+//     case-sensitive filesystem. The `DirectorySpellingIndex` underneath is
+//     published too, for the lazy caller that cannot enumerate its targets up
+//     front.
 //   - realpaths — `fillRealpaths` (every canonicalization, once, up front) plus
-//     `realpathFrom`. Here the row lookup IS the judge: the canonical path is the
-//     answer, so there is nothing left to keep internal.
+//     `realpathFrom`.
+//
+// In both, the row lookup IS the judge: the row is the answer, so there is
+// nothing left to keep internal.
 //
 // There is deliberately no one-call wrapper composing either pair: handed one, a
 // caller with many paths loops over it, which reinstates the per-path `await` the
 // pairs exist to remove.
 //
-// The `SiblingNames` row type is withheld for the same reason its judge is: it is
-// only ever that judge's parameter, so publishing it would advertise a shape no
-// consumer can hand anywhere. `SiblingNamesTable` and `RealpathTable` — what the
-// fills return and the judges consume — are the ones a caller can name, as are
-// `FilenameCaseVerdict`/`FilenameMatch`, which a consumer does not hand in but
-// does receive and branch on.
+// `PathSpellingTable` and `RealpathTable` — what the fills return and the judges
+// consume — are the types a caller can name, as are `PathSpelling`,
+// `PathSpellingRequest`, `ComponentMatch` and `FilenameMatch`, which a consumer
+// receives and branches on.
 //
 // The cost of that decision, stated so it is not a surprise: a new *type* added
 // to `fs-utils.ts` no longer reaches consumers automatically, and
 // `barrel-exports.test.ts` pins runtime names only, so nothing will fail. The
 // symptom is a type that cannot be imported, which surfaces the first time
 // someone tries — not a silent break in existing code.
-export { classifyFilenameCaseFrom, copyDirectory, fillRealpaths, fillSiblingNames, FsLookupCache, isFilesystemAccessError, realpathFrom, } from './fs-utils.js';
+// The lookups themselves, plus the memo every fill shares.
+export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
+export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
+// The two fill+judge pairs, in the order the note above lists them, plus the
+// lazy index a caller that cannot enumerate its targets up front reaches for.
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
 // Project root discovery (canonical: config → git → null).
 // CLI-boundary use only — see docs/concepts/roots-and-config.md.
 export * from './project-utils.js';
-// Test helpers for isolated test output directories
-export * from './test-helpers.js';
+// The runtime half of `test-helpers.ts`: symlink creation with its host
+// capability probe, and the git-environment detachment every child process
+// needs. Named rather than `export *` because the SAME module also holds the
+// fs-refusal fakes (`refuseSyncFs` and siblings), which are test scaffolding
+// and reach adopters on the `./testing` subpath only. A published runtime
+// barrel that carried them — eight such names, once — was the audit's finding,
+// and an `export *` here is how they got in.
+export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_GIT_ENV, symlinkCapability, } from './test-helpers.js';
 // Zod type introspection (version-agnostic)
 export * from './zod-introspection.js';
 // Skill target resolution (cross-platform flat skill install paths)
@@ -85,6 +106,10 @@ export * from './glob/glob-pattern.js';
 // Filesystem hashing (sha256 of raw file bytes)
 export * from './fs/file-hash.js';
 export { parseWholeNumberAtLeast } from './numeric-args.js';
+// THE reading of an environment variable as a boolean. One implementation
+// because three switches each had their own `!== '0'` comparison and none of
+// them turned off for `=false`.
+export { parseEnvBoolean } from './env-flag.js';
 // Machine-independent string ordering for hashed/serialized output — never `localeCompare`.
 export { compareCodeUnits } from './compare-code-units.js';
 // The crawl-timing seam: which contributor, stratum and fixpoint pass owns the
@@ -101,7 +126,8 @@ export { compareCodeUnits } from './compare-code-units.js';
 // `keyOf`, `recordInheritedPass`) are not surface, and `timing-dump.ts` is
 // plumbing shared with `resources`' package-internal `parse-timing.ts` — a star
 // re-export would publish both the moment either grew a symbol.
-export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
+export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, } from './crawl-timing.js';
+// The three `__*ForTest` seams of the same module are on `./testing`, not here.
 // The on-disk plumbing both timing seams share. Exported because
 // `resources`' `parse-timing.ts` is the other consumer and now sits a package
 // away; nothing else should reach for it.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,iFAAiF;AACjF,2EAA2E;AAC3E,iFAAiF;AACjF,gEAAgE;AAChE,6EAA6E;AAC7E,iFAAiF;AACjF,gFAAgF;AAChF,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,wBAAwB;AACxB,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,8EAA8E;AAC9E,iFAAiF;AACjF,+EAA+E;AAC/E,oEAAoE;AACpE,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,iFAAiF;AACjF,wEAAwE;AACxE,gFAAgF;AAChF,kFAAkF;AAClF,yDAAyD;AACzD,EAAE;AACF,iFAAiF;AACjF,kFAAkF;AAClF,yBAAyB;AACzB,EAAE;AACF,kFAAkF;AAClF,gFAAgF;AAChF,iFAAiF;AACjF,+EAA+E;AAC/E,+EAA+E;AAC/E,8BAA8B;AAC9B,EAAE;AACF,gFAAgF;AAChF,kEAAkE;AAClE,8EAA8E;AAC9E,2EAA2E;AAC3E,uDAAuD;AACvD,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,YAAY,GACb,MAAM,eAAe,CAAC;AAUvB,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,oEAAoE;AACpE,cAAc,oBAAoB,CAAC;AAEnC,oEAAoE;AACpE,cAAc,wBAAwB,CAAC;AAEvC,gDAAgD;AAChD,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,4FAA4F;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,+EAA+E;AAC/E,mCAAmC;AACnC,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,8EAA8E;AAC9E,EAAE;AACF,uEAAuE;AACvE,2EAA2E;AAC3E,gFAAgF;AAChF,gEAAgE;AAChE,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAMhB,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAE3B,iEAAiE;AACjE,8EAA8E;AAC9E,0CAA0C;AAC1C,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EAEjB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/listing-refusal.d.ts

@@ -0,0 +1,112 @@
+/**
+ * What a listing does with a directory it was refused — the vocabulary shared
+ * by the filesystem walk (`file-crawler.ts`) and the git listings
+ * (`git-utils.ts`), so a caller decides ONCE for both routes.
+ *
+ * 🚨 A refused listing is a gap in the POPULATION: every file beneath that
+ * directory the listing would have found was never seen and is absent from
+ * every count downstream. There are exactly two honest answers — stop, with a
+ * sentence the adopter can act on, or keep going and REPORT the gap — and
+ * which one is right is the caller's knowledge, not the crawler's. So the
+ * policy is {@link UnreadablePolicy}, it is REQUIRED wherever a listing is
+ * asked for, and it has no default.
+ *
+ * 🪤 It used to be `onUnreadable?`, an optional callback. Every caller that
+ * ignored it compiled; the two routes then defaulted differently (the walk
+ * threw a programmer-facing sentence, the git route dropped the refusal off
+ * its stderr without a word); and the miss surfaced one review round later as
+ * a HIGH. A required field is what makes `tsc` enumerate the callers.
+ */
+import { VatError } from './errors/vat-error.js';
+import { type DirectoryRefusal } from './fs-utils.js';
+/**
+ * What a caller that STOPS on a refusal tells the person reading the error.
+ *
+ * A caller that has decided to stop — a build that must not ship an incomplete
+ * bundle, a discovery that must not silently find fewer skills — owes the
+ * adopter the directory against the root they know, and the knob THEY have.
+ */
+export interface RefuseListingContext {
+    /**
+     * The root the refused directory is expressed against. An absolute path in
+     * an error is the developer's `$HOME` in every CI log.
+     */
+    root: string;
+    /**
+     * What the adopter can do about it — naming this lane's deliberate-drop
+     * mechanism (`resources.exclude`, a plugin `exclude:`, `--exclude`), which
+     * differs per caller and is why the crawler cannot supply it.
+     */
+    remedy: string;
+}
+/**
+ * The caller's decision about a directory the listing cannot open.
+ *
+ * - `{ refuse }` — STOP: the listing throws {@link DirectoryListingRefusedError}
+ *   with the adopter-facing sentence built from the context. Right for every
+ *   lane whose output is acted on as a complete population (a build, a
+ *   discovery, a fingerprint, a copy).
+ * - `{ degrade }` — KEEP GOING and hand the refusal over. The caller is
+ *   promising to REPORT the gap — as its own finding, with the directory and
+ *   errno the refusal carries — not to drop it. Right for a backstop appended
+ *   to a larger report, where one unlistable directory must not destroy every
+ *   finding beside it.
+ *
+ * A directory that VANISHED between being enumerated and being listed
+ * (`ENOENT` / `ENOTDIR`) is not a refusal under either arm: it is no longer in
+ * the population and is skipped without a call.
+ */
+export type UnreadablePolicy = {
+    readonly refuse: RefuseListingContext;
+} | {
+    readonly degrade: (refusal: DirectoryRefusal) => void;
+};
+/**
+ * Thrown by a listing under `{ refuse }` when a directory refused to be
+ * listed. The message is the adopter's sentence — see {@link refusedListingMessage}.
+ */
+export declare class DirectoryListingRefusedError extends VatError {
+    readonly refusal: DirectoryRefusal;
+    constructor(refusal: DirectoryRefusal, context: RefuseListingContext);
+}
+/**
+ * The adopter-facing sentence: root-relative directory, errno, the gap, and
+ * the caller's remedy — **the one owner of that sentence.**
+ *
+ * Exported so every lane that refuses says the same thing. Three lanes used to
+ * compose this by hand and had drifted by a clause each ("enumerated" /
+ * "scanned" / "the population could not be enumerated"); the transient clause
+ * in particular was written once in `fs-utils.ts` precisely so nobody would.
+ * See {@link REFUSAL_GAP_CLAUSE} for why it asserts nothing about what WAS
+ * enumerated beneath the directory.
+ *
+ * @param refusal - What was refused
+ * @param context - The root to express it against, and what the adopter can do
+ * @returns One sentence, root-relative, never containing the absolute path
+ */
+export declare function refusedListingMessage(refusal: DirectoryRefusal, context: RefuseListingContext): string;
+/**
+ * Apply the caller's policy to one refusal: throw under `{ refuse }`, hand it
+ * over under `{ degrade }`. The single place either route settles a refusal,
+ * so the two cannot drift.
+ *
+ * @param policy - The caller's decision
+ * @param refusal - The directory that could not be listed
+ */
+export declare function settleRefusal(policy: UnreadablePolicy, refusal: DirectoryRefusal): void;
+/**
+ * Refuse an omitted policy up front, by name, before any directory is listed.
+ *
+ * The type already makes `unreadable` required, and that is what enumerates
+ * the TypeScript callers. This is the runtime half, for the callers the type
+ * cannot reach — test files are not typechecked by the build, and a JavaScript
+ * adopter has no compiler at all. Without it an omitted policy would surface
+ * only on the first refusal, as a `TypeError` from the `in` operator, and a
+ * tree with nothing unreadable would keep returning complete lists — the
+ * optional seam back again, one layer down.
+ *
+ * @param policy - What the caller passed as `unreadable`
+ * @param api - The entry point, for the sentence
+ */
+export declare function requireUnreadablePolicy(policy: UnreadablePolicy | undefined, api: string): asserts policy is UnreadablePolicy;
+//# sourceMappingURL=listing-refusal.d.ts.map

package/dist/listing-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-refusal.d.ts","sourceRoot":"","sources":["../src/listing-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAG9E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAAE,CAAC;AAE9D;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,QAAQ;IACxD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAEvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB;CAIrE;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAOtG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAGvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,gBAAgB,CAO7H"}