@vibe-agent-toolkit/utils 0.1.42 → 0.2.0-rc.2

package/dist/fs-utils.js

@@ -1,9 +1,20 @@
 /**
  * Filesystem utilities
  */
+// ⚠️ The sync half is reached through the DEFAULT object (`nodeFs.existsSync`),
+// not as named imports, and that is load-bearing rather than stylistic. Node
+// snapshots a builtin's named ESM exports at import time, so `vi.spyOn(fs,
+// 'existsSync')` cannot see a call made through a named binding — the spy
+// attaches and counts zero, which reads exactly like "this function performs no
+// I/O". `classifyFilenameCaseFrom` is guarded by precisely that assertion (it
+// must reach neither `readdir` nor this pair), so a "tidy-up" back to named
+// imports would silently disarm the guard. The async half below already uses the
+// default object for the same reason.
+import nodeFs from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { toForwardSlash } from './path-core.js';
+import { promisify } from 'node:util';
+import { toForwardSlash, toNfc } from './path-core.js';
 import { safePath } from './path-utils.js';
 /**
  * Per-run memo for the two filesystem lookups that validation repeats on values
@@ -21,11 +32,16 @@ import { safePath } from './path-utils.js';
  * arbitrarily long ago. The intended lifetime is one instance per validation run,
  * constructed as a local and collected with the run.
  *
+ * Fill first, then judge. The loop holds no `await`, because every listing the
+ * loop could have needed was already taken:
+ *
  * @example
  * ```typescript
  * const fsCache = new FsLookupCache();          // one per run
- * for (const link of links) {
- *   await verifyCaseSensitiveFilename(link.target, fsCache);
+ * const targets = links.map((link) => link.target);
+ * const siblingNames = await fillSiblingNames(targets, fsCache);  // all the I/O, once
+ * for (const target of targets) {
+ *   classifyFilenameCaseFrom(siblingNames, target);               // pure — no syscall
  * }
  * ```
  */
@@ -34,10 +50,137 @@ export class FsLookupCache {
     #listings = new Map();
     /** Path → its canonical path, falling back to the resolved path. */
     #realpaths = new Map();
+    /** Path → the existence/kind pair recorded the first time it was probed. */
+    #probes = new Map();
+    /** Probe calls received, and how many of them reached the filesystem. */
+    #probeCount = 0;
+    #probeMisses = 0;
+    /**
+     * Probe counters, for tests and `--debug` output.
+     *
+     * A memo whose tests never assert its hit count is theatre: every assertion
+     * about *values* still passes when the memo is disabled, because an
+     * always-miss cache returns the same answers — only more slowly. This is the
+     * one observable that dies when the memo does.
+     */
+    get probeStats() {
+        return { probes: this.#probeCount, misses: this.#probeMisses };
+    }
+    /**
+     * Does this path exist, and is it a directory — asked once per run.
+     *
+     * **Both syscalls are preserved, in order, exactly as an uncached caller
+     * would make them.** `existsSync` then `statSync` is not the same as one
+     * `statSync`: the pair distinguishes "absent" from "present but unstattable",
+     * and the link walker's classifier branches differently on each. Collapsing
+     * them would be a behaviour change wearing the shape of an optimization, so
+     * this method deduplicates the pair rather than replacing it.
+     *
+     * Synchronous, unlike this class's other two lookups, because its caller (the
+     * skill link-graph walker) is synchronous throughout. One oracle answering
+     * both shapes beats a second class that differs only in colour.
+     *
+     * @param targetPath - Path to probe
+     * @returns The recorded existence/kind pair
+     */
+    probe(targetPath) {
+        this.#probeCount++;
+        const cached = this.#probes.get(targetPath);
+        if (cached !== undefined)
+            return cached;
+        this.#probeMisses++;
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-validated path
+        const exists = nodeFs.existsSync(targetPath);
+        let isDirectory = null;
+        if (exists) {
+            try {
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-validated path
+                isDirectory = nodeFs.statSync(targetPath).isDirectory();
+            }
+            catch {
+                // Present to `existsSync` but unstattable. `null` records "no answer"
+                // rather than guessing `false`, which would read as "it is a file".
+                isDirectory = null;
+            }
+        }
+        const result = { exists, isDirectory };
+        this.#probes.set(targetPath, result);
+        return result;
+    }
     /**
-     * Canonical path for `targetPath`, falling back to `safePath.resolve()` when the
-     * path does not exist or cannot be resolved (a non-existent file has no realpath,
-     * and callers comparing paths still need an answer).
+     * Canonical path for `targetPath`. A path that cannot be canonicalized is
+     * answered from its **deepest existing ancestor** — that ancestor's realpath
+     * with the missing remainder re-appended — because a non-existent file has no
+     * realpath and callers comparing paths still need an answer.
+     *
+     * ⚠️ **The fallback must stay in the same NAMESPACE as the success path, which
+     * a lexical `safePath.resolve()` is not.** The only consumer of this column
+     * compares one canonical path against another (`isWithinProject` /
+     * `isWithinProjectFrom`), so an answer resolved lexically is being compared
+     * against an answer resolved through symlinks. Where the root traverses a
+     * symlink — macOS `/tmp → /private/tmp`, bind mounts, a worktree under a
+     * symlinked path — the two spellings differ and the comparison is nonsense.
+     * Measured truth table for `isWithinProject(file, root)` under a `link → real`
+     * root, before the walk:
+     *
+     * ```text
+     * existing file, symlinked root : true
+     * MISSING  file, symlinked root : false  ← lexical fallback, wrong namespace
+     * MISSING  file, plain root     : true
+     * symlink inside pointing out   : false  (correct either way)
+     * ```
+     *
+     * The middle row is user-visible: a merely BROKEN root-absolute markdown link
+     * was reported as *escaping the project*. The walk fixes it without widening
+     * containment, because the ancestor is exactly where an escaping symlink
+     * lives — a missing file behind a directory link that points outside still
+     * canonicalizes outside.
+     *
+     * The recursion goes through `this.realpath(parent)`, not a private helper, so
+     * ancestors land in the same memo and share in-flight promises. A missing
+     * file's parent directory is almost always already cached, so the common case
+     * costs no extra syscall. **The fixpoint guard is mandatory**: `path.dirname`
+     * is idempotent at a root (`'/'` on posix, `'C:/'` for a drive, `'//server/share/'`
+     * for a UNC share), so without it the walk never terminates.
+     *
+     * Errno is deliberately not inspected. EACCES on an existing file and ELOOP on
+     * a symlink cycle land in the same catch as ENOENT, and for all three the
+     * ancestor's namespace is a strictly better answer than the lexical one.
+     *
+     * ⚠️ **`promisify(nodeFs.realpath)` — NOT `fs/promises.realpath`. Node ships two
+     * different realpaths and they do not agree.** `fs.realpathSync` and the
+     * `fs.realpath` *callback* form run Node's own JS implementation: an
+     * lstat/readlink walk that preserves the casing you asked for. `fs/promises.realpath`
+     * and `fs.realpath.native` call `uv_fs_realpath` (`realpath(3)` /
+     * `GetFinalPathNameByHandleW`), which reports the casing **on disk**. On a
+     * case-insensitive filesystem — macOS and Windows — those are different strings,
+     * and this column feeds *synchronous* judges that previously called
+     * `fs.realpathSync` themselves. A column that does not match `realpathSync` byte
+     * for byte flips containment verdicts and emits findings the un-refactored code
+     * does not. Measured, Node v24.13.1 / darwin, disk holding `<B>/Sub/Target.TXT`,
+     * asked for `<B>/sub/target.txt`:
+     *
+     * ```text
+     * realpathSync           : <B>/sub/target.txt   ← the contract
+     * promisify(fs.realpath) : <B>/sub/target.txt   ✅ matches (this call)
+     * fs/promises.realpath   : <B>/Sub/Target.TXT   ❌ on-disk casing
+     * fs.realpath.native     : <B>/Sub/Target.TXT   ❌ on-disk casing
+     * ```
+     *
+     * They also disagree on `''`, where the sync form resolves to the cwd and the
+     * native form throws `ENOENT`. **Do not "modernize" this back to `fs/promises`** —
+     * it reads tidier and silently changes output. `packages/utils/test/fs-utils.test.ts`
+     * → *"answers a mis-cased path exactly as realpathSync does, not as the native
+     * resolver does"* pins the equivalence (and skips itself on a case-sensitive
+     * filesystem, where the two routes cannot be told apart).
+     *
+     * `promisify` is applied **per call, on the default object**, not once at module
+     * scope: an eagerly captured function bypasses any `vi.spyOn(nodeFs, 'realpath')`
+     * installed after import, so this method's I/O would count zero — indistinguishable
+     * from performing none. (`fs.realpath` carries no `util.promisify.custom`, so this
+     * promisification really does get the JS implementation; it is verified, not
+     * assumed — see *"routes canonicalization through the node:fs default object"*.)
+     * The wrapper is allocated only on a cache MISS, i.e. once per actual syscall.
      *
      * @param targetPath - Path to canonicalize
      * @returns Canonical path with forward slashes on every platform
@@ -48,14 +191,39 @@ export class FsLookupCache {
             return cached;
         // Stored before the first `await` anywhere can run, so concurrent callers
         // reaching this method share the one in-flight promise.
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-validated path
-        const pending = fs
-            .realpath(targetPath)
+        //
+        // No `security/detect-non-literal-fs-filename` suppression here, unlike the
+        // sibling lookups: the rule matches a member call on an fs object, and the
+        // path is passed to the promisified wrapper instead. The path is
+        // caller-validated all the same.
+        const pending = promisify(nodeFs.realpath)(targetPath)
             .then(toForwardSlash)
-            .catch(() => safePath.resolve(targetPath));
+            .catch(() => this.#canonicalizeViaAncestor(targetPath));
         this.#realpaths.set(targetPath, pending);
         return pending;
     }
+    /**
+     * The ancestor walk behind {@link FsLookupCache.realpath}'s fallback: canonicalize
+     * the parent — through the public method, so the memo and in-flight sharing
+     * apply — and re-append this path's own basename.
+     *
+     * Runs inside the already-stored promise's `.catch()`, which is what keeps the
+     * store-before-await property intact: the row for `targetPath` is in the map
+     * before any of this can start.
+     *
+     * @param targetPath - Path that could not be canonicalized
+     * @returns Canonical ancestor plus the missing remainder, forward-slashed
+     */
+    async #canonicalizeViaAncestor(targetPath) {
+        const absolutePath = safePath.resolve(targetPath);
+        const parent = toForwardSlash(path.dirname(absolutePath));
+        // Fixpoint at a filesystem root — `/`, `C:/`, `//server/share/` — where
+        // `dirname` returns its own input. Nothing left to walk, and no guard means
+        // no termination.
+        if (parent === absolutePath)
+            return absolutePath;
+        return safePath.join(await this.realpath(parent), path.basename(absolutePath));
+    }
     /**
      * Entry names of `dirPath`, or `null` when it cannot be read (missing directory,
      * no permission). The unreadable answer is cached too — re-asking is the same
@@ -100,61 +268,262 @@ export async function copyDirectory(src, dest) {
     }
 }
 /**
- * Verify that a file exists with the exact case-sensitive filename.
+ * List the parent directory of every path in `filePaths` — the only place I/O is
+ * legal for this fact, and the pass that must run *before* any judging.
  *
- * On case-insensitive filesystems (Windows, macOS), a file might be found even if
- * the case doesn't match. This function checks that the actual filename on disk
- * matches the requested path exactly (case-sensitive).
+ * ⚠️ **It takes FILE paths, not directory paths, deliberately.** It derives each
+ * parent with `path.dirname` itself, so exactly one function in the system owns
+ * the key derivation and a caller cannot construct a key that
+ * {@link siblingNamesFrom} then misses. Do not "simplify" this to take
+ * directories: that hands the derivation back to every call site and reopens the
+ * silent-miss class this shape closes.
  *
- * Answering requires listing the target's parent directory. Callers checking many
- * paths (every link in a corpus) hit the same handful of directories over and over,
- * so the listing comes from a caller-supplied {@link FsLookupCache}.
+ * Distinct parents are listed **concurrently**: the shape this replaced asked one
+ * link at a time at judgement time, which serialised every `readdir` behind the
+ * previous link's `await`. De-duplication is by parent, so N files in one
+ * directory cost one listing; the listing itself goes through
+ * {@link FsLookupCache.readdir}, which memoizes and shares in-flight promises
+ * across fills.
  *
- * The cache parameter is **required rather than defaulted on purpose**: a default
- * would let an unmigrated call site silently keep the un-memoized behaviour, which
- * is a no-op wearing the shape of a fix. `new FsLookupCache()` per call reproduces
- * the old behaviour exactly, so migrating is mechanical — but it has to be a
- * decision someone made.
- *
- * @param filePath - Absolute path to the file to verify
+ * @param filePaths - File paths whose parent directories should be listed
  * @param fsCache - Per-run lookup cache (one instance per validation run)
- * @returns Object with exists flag and actual filename (or null if not found)
+ * @returns The filled table; empty input yields an empty table with no syscalls
+ */
+export async function fillSiblingNames(filePaths, fsCache) {
+    const parentDirs = new Set();
+    for (const filePath of filePaths) {
+        parentDirs.add(path.dirname(filePath));
+    }
+    const table = new Map();
+    await Promise.all([...parentDirs].map(async (parentDir) => {
+        // Stored EXACTLY as `readdir` returned it — no Unicode folding, no copy.
+        //
+        // The fill used to fold every entry to NFC here (and `siblingNamesFrom`
+        // folded `expectedName` to match), which left the judge a pure `===` over
+        // pre-reconciled strings. It also destroyed the only evidence that could
+        // distinguish "these two spellings are the same bytes" from "these two
+        // spellings are equal only after folding" — and those are different facts
+        // on a byte-exact filesystem. Comparison semantics now live entirely in
+        // {@link classifyFilenameCase}, so the fill has no opinion to disagree
+        // with, and a hand-written row is raw `readdir` output rather than a form
+        // only the fill knew how to produce.
+        //
+        // The array is the cache's own and is deliberately not copied: the table
+        // type is `readonly string[]`, several tables may share one listing, and
+        // copying every listing per fill is exactly the per-run cost this pair
+        // exists to avoid. Treat it as immutable.
+        table.set(parentDir, await fsCache.readdir(parentDir));
+    }));
+    return table;
+}
+/**
+ * Read the row for `filePath` out of an already-filled table. Pure.
  *
- * @example
- * ```typescript
- * // On case-insensitive filesystem with file "README.md"
- * const fsCache = new FsLookupCache();
- * const result1 = await verifyCaseSensitiveFilename('/project/README.md', fsCache);
- * // { exists: true, actualName: 'README.md' }
+ * **A miss throws rather than degrading to `names: null`.** The fill set is
+ * derived from exactly the paths the judge will be asked about, so a missing
+ * parent is a programming error — a path judged that nobody filled. The `null`
+ * fallback would answer it as "the directory is unreadable", which reports every
+ * file under that directory as *missing*: a wrong answer wearing the shape of a
+ * graceful degradation, and one no test of the verdict would catch.
  *
- * const result2 = await verifyCaseSensitiveFilename('/project/readme.md', fsCache);
- * // { exists: false, actualName: 'README.md' } - case mismatch!
- * ```
+ * Internal on purpose — {@link classifyFilenameCaseFrom} is the public judge.
+ *
+ * @param table - Table filled by {@link fillSiblingNames}
+ * @param filePath - Path being asked about
+ * @returns The row: the expected basename plus the parent's entries
+ * @throws If `table` holds no entry for the path's parent directory
  */
-export async function verifyCaseSensitiveFilename(filePath, fsCache) {
-    // Get parent directory and expected filename
+export function siblingNamesFrom(table, filePath) {
     const parentDir = path.dirname(filePath);
-    const expectedName = path.basename(filePath);
-    // Read actual directory entries
-    const entries = await fsCache.readdir(parentDir);
-    if (entries === null) {
-        // Parent directory doesn't exist (or can't be read)
-        return { exists: false, actualName: null };
+    // `undefined` can only mean "absent key": a filled entry is an array or an
+    // explicit `null`, never `undefined`.
+    const names = table.get(parentDir);
+    if (names === undefined) {
+        throw new Error(`No sibling listing for directory "${parentDir}" (asked about "${filePath}"). ` +
+            `Fill it with fillSiblingNames() before judging.`);
+    }
+    // Raw on this side too. This lookup reads a row; it does not judge, and
+    // folding here would be judging — see {@link classifyFilenameCase}, which
+    // needs the spelling the caller actually asked for in order to tell a
+    // byte-exact hit from a fold-only one.
+    return { expectedName: path.basename(filePath), names };
+}
+/**
+ * Decide whether `row.expectedName` names a real entry, and how faithfully.
+ *
+ * Pure: no filesystem, no cache, no path parsing — it reads only the columns it
+ * is handed, which is what makes hand-written listings a legitimate test input.
+ * Both columns arrive **raw**, exactly as `readdir` and `path.basename` produced
+ * them; this function owns every comparison rule, so nothing upstream can
+ * disagree with it about what "the same filename" means.
+ *
+ * **Three passes, strictly in this order, first match wins — the order IS the
+ * contract**, because each pass accepts a strictly weaker notion of sameness and
+ * a weaker pass reached first would mislabel a file that is genuinely there:
+ *
+ * 1. **byte-exact** `entry === expectedName`. On a case-insensitive filesystem a
+ *    listing can hold both `readme.md` and `README.md`, in either order; asking
+ *    for `README.md` must report it present regardless of which one `readdir`
+ *    happened to return first. Same argument, one form weaker, for pass 2.
+ * 2. **NFC-folded** `toNfc(entry) === toNfc(expectedName)`. `é` has two encodings
+ *    (NFC `U+00E9` vs NFD `e` + `U+0301`) that are `!==` and that case-folding
+ *    does not reconcile, so without this pass an accented file that plainly
+ *    exists was reported flatly *missing* — not even a case-mismatch hint, since
+ *    that needs pass 3 to match (ledger entry D7).
+ * 3. **case-insensitive, on the folded forms.** Folding first is required, not
+ *    tidy: `toLowerCase()` does not reconcile NFC against NFD, so a name that
+ *    differs in *both* case and normalization falls out as `absent` and the
+ *    author loses the suggestion.
+ *
+ * ⚠️ **Passes 1 and 2 are not the same verdict, and collapsing them is a
+ * silently-wrong answer rather than a lost nicety.** The fix for D7 originally
+ * folded both sides *before* comparing, which repaired the false "missing" on
+ * macOS/APFS — and over-corrected into the opposite error on Linux/ext4, where
+ * the filesystem is byte-exact: a markdown link spelling a filename NFD while
+ * disk holds NFC genuinely 404s there, and the folded judge answered "exists,
+ * exact match, no issue". `match` is what keeps both facts: the link resolves
+ * (so it must not be reported broken), *and* it resolves only by folding (so a
+ * caller can warn). {@link classifyFilenameCaseFrom}'s consumer in
+ * `@vibe-agent-toolkit/resources` turns `'normalized'` into
+ * `LINK_NORMALIZATION_MISMATCH`.
+ *
+ * **Folding is deferred to the miss path, and that is a real saving.** Pass 1
+ * calls `toNfc` zero times, so a corpus whose links all resolve byte-exactly —
+ * every pure-ASCII corpus, i.e. nearly all of them — normalizes nothing at all.
+ * The older shape folded every entry of every directory in the fill,
+ * unconditionally.
+ *
+ * @param row - The listing row, read out of a filled table by {@link siblingNamesFrom}
+ * @returns The verdict: whether it resolves, the entry really on disk, and which pass matched
+ */
+export function classifyFilenameCase(row) {
+    const { expectedName, names } = row;
+    if (names === null) {
+        // Parent directory doesn't exist (or can't be read).
+        return { exists: false, actualName: null, match: 'absent' };
+    }
+    // Pass 1 — byte-exact.
+    // Tested against `undefined` rather than for truthiness: `readdir` never
+    // yields an empty entry name, but hand-written rows are this function's
+    // advertised input now that it is pure, and `''` is falsy — it would fall
+    // through to a later pass and come back as `actualName: ''` with the wrong
+    // `match`.
+    const exactMatch = names.find(entry => entry === expectedName);
+    if (exactMatch !== undefined) {
+        return { exists: true, actualName: exactMatch, match: 'exact' };
     }
-    // Find the actual filename (case-sensitive exact match)
-    const exactMatch = entries.find(entry => entry === expectedName);
-    if (exactMatch) {
-        // Found exact case match - file exists with correct case
-        return { exists: true, actualName: exactMatch };
+    // Pass 2 — equal only after NFC folding. Reached only when pass 1 missed, so
+    // an all-ASCII corpus never pays for it.
+    const foldedExpected = toNfc(expectedName);
+    const normalizedMatch = names.find(entry => toNfc(entry) === foldedExpected);
+    if (normalizedMatch !== undefined) {
+        return { exists: true, actualName: normalizedMatch, match: 'normalized' };
+    }
+    // Pass 3 — case-insensitive over the folded forms.
+    const loweredExpected = foldedExpected.toLowerCase();
+    const caseInsensitiveMatch = names.find(entry => toNfc(entry).toLowerCase() === loweredExpected);
+    return caseInsensitiveMatch === undefined
+        ? { exists: false, actualName: null, match: 'absent' }
+        : { exists: false, actualName: caseInsensitiveMatch, match: 'case_mismatch' };
+}
+/**
+ * Judge `filePath` against an already-filled {@link SiblingNamesTable}.
+ *
+ * This is the judging half of the two-pass shape: {@link fillSiblingNames} does
+ * every listing first, then this runs over as many paths as you like with no
+ * interleaved I/O.
+ *
+ * **The signature is not what keeps this free of I/O — a test is.** `fs-utils.ts`
+ * imports `node:fs` and `node:fs/promises` at module scope, so this function's
+ * module reaches the filesystem freely; taking no {@link FsLookupCache} and no
+ * `fs` parameter constrains a future edit not at all, which could call
+ * `nodeFs.statSync` on the next line and still typecheck. What actually holds the
+ * property is `packages/utils/test/fs-utils.test.ts` →
+ * *"judges from a filled table, reaching neither readdir nor the sync stat pair"*:
+ * it spies `fs.readdir`, `nodeFs.existsSync` and `nodeFs.statSync` on the very
+ * default objects this module imports, drives a positive control through each so
+ * a zero cannot mean "the instrument never attached", and asserts the counts do
+ * not move across judgement. If a future check needs another fact about the parent
+ * directory, widen the *table* rather than reaching for `fs` here — and expect
+ * that test, not this signature, to be what stops you.
+ *
+ * @param table - Table filled by {@link fillSiblingNames}
+ * @param filePath - Absolute path to judge
+ * @returns The verdict — see {@link FilenameCaseVerdict}
+ * @throws If `table` holds no entry for the path's parent directory — see
+ *   {@link siblingNamesFrom}
+ */
+export function classifyFilenameCaseFrom(table, filePath) {
+    return classifyFilenameCase(siblingNamesFrom(table, filePath));
+}
+/**
+ * Canonicalize every path in `paths` — the only place I/O is legal for this
+ * fact, and the pass that must run *before* any judging.
+ *
+ * ⚠️ **Rows are keyed by the input path string exactly as given** — not a
+ * dirname, not a re-resolved form. {@link realpathFrom} looks that same string
+ * up, so any normalization applied here and not there is a silent miss (a loud
+ * one, in fact: the judge throws). Contrast {@link fillSiblingNames}, which keys
+ * by `path.dirname` *because* many files share one listing; here the answer is
+ * per path, so the path is the key.
+ *
+ * Distinct paths are canonicalized **concurrently**: the shape this replaces
+ * asked one path at a time at judgement time, which serialised every `realpath`
+ * behind the previous path's `await`. De-duplication is by path, so the same
+ * path passed N times costs one syscall; the call itself goes through
+ * {@link FsLookupCache.realpath}, which memoizes and shares in-flight promises
+ * across fills.
+ *
+ * @param paths - Paths to canonicalize
+ * @param fsCache - Per-run lookup cache (one instance per validation run)
+ * @returns The filled table; empty input yields an empty table with no syscalls
+ */
+export async function fillRealpaths(paths, fsCache) {
+    const distinctPaths = new Set(paths);
+    const table = new Map();
+    await Promise.all([...distinctPaths].map(async (filePath) => {
+        table.set(filePath, await fsCache.realpath(filePath));
+    }));
+    return table;
+}
+/**
+ * Read the canonical path for `filePath` out of an already-filled table. Pure.
+ *
+ * **A miss throws rather than degrading to a recomputed realpath.** The fill set
+ * is derived from exactly the paths the judge will be asked about, so a missing
+ * key is a programming error — a path judged that nobody filled. Recomputing it
+ * would answer *correctly* and silently reintroduce the per-path syscall this
+ * column exists to remove: a regression no test of the verdict could catch,
+ * because the verdict would be identical, only slower.
+ *
+ * Public, unlike {@link siblingNamesFrom}: a sibling-names row is not yet an
+ * answer (it still needs {@link classifyFilenameCase}), whereas here the row IS
+ * the answer — so this lookup is itself the judge for this column, and there is
+ * nothing left to keep internal.
+ *
+ * **The signature is not what keeps this free of I/O — a test is.** As with
+ * {@link classifyFilenameCaseFrom}, this module imports `node:fs` and
+ * `node:fs/promises` at module scope, so withholding a {@link FsLookupCache} from
+ * the parameter list prevents nothing. The guard is
+ * `packages/utils/test/fs-utils.test.ts` → *"judges from a filled table, reaching
+ * neither the async nor the sync realpath"*, which spies `nodeFs.realpath` and
+ * `nodeFs.realpathSync` on the module default objects, proves both instruments
+ * attached with a positive control, and asserts zero calls across judgement.
+ *
+ * @param table - Table filled by {@link fillRealpaths}
+ * @param filePath - Path being asked about, as it was handed to the fill
+ * @returns The canonical path, with forward slashes on every platform
+ * @throws If `table` holds no row for `filePath`
+ */
+export function realpathFrom(table, filePath) {
+    // `undefined` can only mean "absent key": a filled row is always a string,
+    // because `FsLookupCache.realpath` falls back to the deepest existing
+    // ancestor's canonical path rather than leaving an unresolvable path without
+    // an answer.
+    const realPath = table.get(filePath);
+    if (realPath === undefined) {
+        throw new Error(`No canonical path for "${filePath}". Fill it with fillRealpaths() before judging.`);
     }
-    // No exact match - check for case-insensitive match
-    const caseInsensitiveMatch = entries.find(entry => entry.toLowerCase() === expectedName.toLowerCase());
-    // Return result:
-    // - If case-insensitive match found: exists=false (wrong case), actualName=<actual>
-    // - If no match at all: exists=false, actualName=null
-    return {
-        exists: false,
-        actualName: caseInsensitiveMatch ?? null,
-    };
+    return realPath;
 }
 //# sourceMappingURL=fs-utils.js.map

package/dist/fs-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../src/fs-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../src/fs-utils.ts"],"names":[],"mappings":"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"}

package/dist/fs.d.ts

@@ -8,5 +8,6 @@
  * `@vibe-agent-toolkit/utils/path` instead — it is dramatically cheaper.
  */
 export { normalizePath, normalizedTmpdir, mkdirSyncReal, resolveFromImportMeta, dynamicImportPath, } from './path-utils.js';
-export { copyDirectory, FsLookupCache, verifyCaseSensitiveFilename } from './fs-utils.js';
+export { classifyFilenameCaseFrom, copyDirectory, fillRealpaths, fillSiblingNames, FsLookupCache, realpathFrom, } from './fs-utils.js';
+export type { FilenameCaseVerdict, FilenameMatch, PathProbe, PathProbeStats, RealpathTable, SiblingNamesTable, } from './fs-utils.js';
 //# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAQzB,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC"}

package/dist/fs.js

@@ -8,5 +8,11 @@
  * `@vibe-agent-toolkit/utils/path` instead — it is dramatically cheaper.
  */
 export { normalizePath, normalizedTmpdir, mkdirSyncReal, resolveFromImportMeta, dynamicImportPath, } from './path-utils.js';
-export { copyDirectory, FsLookupCache, verifyCaseSensitiveFilename } from './fs-utils.js';
+// Two materialized columns, each a fill+judge pair and nothing else. For sibling
+// names the judge is `classifyFilenameCaseFrom`, and the internal
+// `classifyFilenameCase`/`siblingNamesFrom` members plus the `SiblingNames` row
+// type they trade in stay module-local — a row there is not yet an answer. For
+// realpaths the row IS the answer, so the row lookup `realpathFrom` is itself the
+// judge and is exported. See `index.ts` for the full reasoning.
+export { classifyFilenameCaseFrom, copyDirectory, fillRealpaths, fillSiblingNames, FsLookupCache, realpathFrom, } from './fs-utils.js';
 //# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,iFAAiF;AACjF,kEAAkE;AAClE,gFAAgF;AAChF,+EAA+E;AAC/E,kFAAkF;AAClF,gEAAgE;AAChE,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/git-root-cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The module-level memo behind `gitFindRoot`, in its own leaf module.
+ *
+ * Two modules need it and they must not need each other:
+ *
+ * - `git-utils.ts` reads and writes it (it owns the walk).
+ * - `project-utils.ts` clears it from `resetProjectRootCaches()`, so callers
+ *   have ONE reset to remember rather than one per walk-up cache.
+ *
+ * Having `project-utils.ts` import `git-utils.ts` for that would drag `which`
+ * and `node:child_process` into the `./project` entry, which exists precisely so
+ * root discovery costs no third-party packages to reach. This file imports
+ * nothing, so both sides can depend on it.
+ *
+ * Deliberately not re-exported from `index.ts` or any subpath: the memo is an
+ * implementation detail of `gitFindRoot`, and a second public reset name is a
+ * reset callers forget to call.
+ */
+/**
+ * Look up a memoized git root.
+ *
+ * @param dir - Resolved directory to look up
+ * @returns The memoized answer (possibly `null`), or `undefined` if unknown
+ */
+export declare function lookupGitRoot(dir: string): string | null | undefined;
+/**
+ * Record `gitRoot` as the answer for every directory a walk climbed through.
+ *
+ * @param climbed - Directories visited by the walk, deepest first
+ * @param gitRoot - The answer they all share
+ * @returns `gitRoot`, so a walk can `return rememberGitRoot(...)`
+ */
+export declare function rememberGitRoot(climbed: readonly string[], gitRoot: string | null): string | null;
+/**
+ * Drop every memoized git root.
+ *
+ * Not called directly by application code — `resetProjectRootCaches()` calls it,
+ * so one reset invalidates both walk-up caches. Necessary because a `.git`
+ * directory can appear or vanish while the process lives (tests build fixtures
+ * mid-run; a long-lived host re-enters `vat audit` between edits), and a stale
+ * entry would outlive the change.
+ */
+export declare function resetGitRootCache(): void;
+//# sourceMappingURL=git-root-cache.d.ts.map