@vibe-agent-toolkit/utils 0.2.0-rc.1 → 0.2.0-rc.3

package/dist/git-run.js

@@ -0,0 +1,154 @@
+/**
+ * The one way to run `git` — safe by construction, for VAT and for anyone
+ * building on `@vibe-agent-toolkit/utils`.
+ *
+ * ## Why this exists rather than "remember to pass the right options"
+ *
+ * A `git` child inherits `GIT_DIR`, `GIT_INDEX_FILE`, `GIT_PREFIX` and friends
+ * from any ancestor `git` process, and **those override the `cwd` you passed**.
+ * The result is not an error — it is a well-formed answer about a different
+ * repository, at exit 0. Measured 2026-08-16 against real pre-commit hooks:
+ *
+ * - `git status --porcelain` at a caller-supplied path reported the *committing*
+ *   repository's status, exit 0.
+ * - `git init` in a fresh directory silently re-initialized the inherited
+ *   `GIT_DIR` — no `.git` appeared where it was asked for — and the following
+ *   `add`/`commit` landed in a **bystander repository**, switching its branch
+ *   and rewriting its index, while every step reported success.
+ * - `git rev-parse --show-toplevel` answered **correctly** throughout, so the
+ *   obvious "am I in the right repository?" guard cannot detect any of it.
+ *
+ * The hazard is therefore invisible at every call site, which is exactly the
+ * kind of thing that must be handled by the default rather than by discipline.
+ *
+ * ## The default is the whole design
+ *
+ * **The environment is scrubbed unless you say `ambient: true`.** Almost every
+ * git command in a tool is about a path the caller was *handed* — a project
+ * root, a temp staging repo, a clone destination — and for those the inherited
+ * environment is always wrong. The rare command that genuinely means "the
+ * repository I am standing in" (`git remote get-url` inside the user's own
+ * checkout, say) opts out explicitly, and has to name itself when it does.
+ *
+ * ## What this is, mechanically: a set of defaults over `@vibe-validate/git`
+ *
+ * The spawn itself, the environment scrub and the treatment of a spawn-level
+ * error all live in `executeGitCommand`, which is that package's single
+ * chokepoint and is exercised by vibe-validate on every commit it gates. This
+ * module supplies only the three defaults VAT needs to differ on, and a result
+ * shape that never throws:
+ *
+ * - **`scrubGitEnv` is on unless `ambient: true`** — the inverse of
+ *   `executeGitCommand`'s `false`. That default is right for vibe-validate,
+ *   which mostly operates on the repository it was invoked in; it is wrong here,
+ *   because VAT and its adopters are handed a root. Consolidating without this
+ *   wrapper would relocate the opt-in rather than remove the hazard.
+ * - **`maxBuffer` is 64 MiB, never Node's 1 MiB** (`executeGitCommand` defaults
+ *   to 10 MiB). `git ls-files -s -z` emits ~104 bytes per path, so an
+ *   8,500-file tree reaches 84% of Node's default and a larger one truncates.
+ * - **A spawn-level failure is a failure regardless of exit status**, which
+ *   `executeGitCommand` now enforces itself; `ok` simply forwards its `success`.
+ *
+ * ⚠️ **One property was given up in the consolidation:** this used to resolve the
+ * binary with `which.sync('git')` and spawn an absolute path. `executeGitCommand`
+ * spawns bare `'git'` and lets the OS search `PATH`, so a "git is not on PATH"
+ * condition now arrives as an `ENOENT` in `error` rather than as a distinct
+ * pre-spawn message. Both are reported through {@link GitRunResult}, so no caller
+ * can mistake either for success.
+ */
+import { executeGitCommand } from '@vibe-validate/git';
+/**
+ * 64 MiB. Chosen against `git ls-files -s -z`, the widest-output command here:
+ * ~104 bytes per path means this covers roughly 640,000 paths, while Node's
+ * 1 MiB default covers about 10,000 — a ceiling ordinary monorepos reach.
+ */
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+/** Wall-clock ceiling on one invocation, so a hung remote cannot wedge a build. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Run one `git` command.
+ *
+ * Never throws: a missing binary, a timeout and a non-zero exit are all reported
+ * through {@link GitRunResult} so a caller can tell them apart and choose. Check
+ * `ok`, not `status`.
+ *
+ * @param args - Arguments after the `git` executable, e.g. `['status', '--porcelain']`
+ * @param options - See {@link GitRunOptions}; the environment is scrubbed unless
+ *   `ambient` is set
+ * @returns The outcome, including any spawn-level failure
+ *
+ * @example
+ * ```typescript
+ * // About a path you were handed — the ordinary case, safe by default.
+ * const r = runGit(['status', '--porcelain'], { cwd: projectRoot });
+ * if (!r.ok) throw new Error(`git status failed: ${r.stderr}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // About the repository this process is standing in — opt out explicitly.
+ * const url = runGit(['remote', 'get-url', 'origin'], { ambient: true });
+ * ```
+ */
+export function runGit(args, options = {}) {
+    if (args.length === 0) {
+        // Handled here rather than by `executeGitCommand`, which THROWS on an empty
+        // argv. This function's whole contract is that it never throws.
+        return {
+            ok: false,
+            status: 1,
+            stdout: '',
+            stderr: 'runGit() needs at least one argument',
+            error: new Error('runGit() needs at least one argument'),
+        };
+    }
+    // `ignoreErrors` is what makes this non-throwing, and it is safe to set
+    // unconditionally only because `executeGitCommand` now reports `error` on that
+    // path too. Before that fix it dropped the spawn cause entirely, and a caller
+    // reading the result could not tell "git is not installed" from "exit 1 is the
+    // answer" from "your listing was truncated" — which is why this wrapper could
+    // not have been written against the previous release.
+    const result = executeGitCommand([...args], {
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.input === undefined ? {} : { stdin: options.input }),
+        scrubGitEnv: options.ambient !== true,
+        suppressStderr: options.suppressStderr ?? false,
+        trimOutput: options.trim ?? true,
+        ignoreErrors: true,
+        timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+        maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER,
+    });
+    return {
+        ok: result.success,
+        status: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+/**
+ * {@link runGit}, but a failure throws instead of being reported.
+ *
+ * For callers whose next line has no meaning if the command did not work —
+ * setting up a fixture repository, or any step whose failure should stop the
+ * run rather than be interpreted. Prefer {@link runGit} wherever a non-zero
+ * exit carries information ("no commit yet", "not a repository", "no such
+ * remote"), because those are answers rather than faults.
+ *
+ * @param args - Arguments after the `git` executable
+ * @param options - See {@link GitRunOptions}
+ * @returns The trimmed stdout
+ * @throws {Error} When git could not run, or ran and exited non-zero
+ */
+export function runGitOrThrow(args, options = {}) {
+    const result = runGit(args, options);
+    if (result.ok)
+        return result.stdout;
+    // The subcommand only: a commit message can be hundreds of KB, and
+    // interpolating the whole argv buries the actual error in CI output.
+    const label = args[0] ?? '<no args>';
+    const detail = result.stderr || `exit ${String(result.status)}`;
+    throw new Error(`git ${label} failed: ${detail}`);
+}
+//# sourceMappingURL=git-run.js.map

package/dist/git-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-run.js","sourceRoot":"","sources":["../src/git-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,mFAAmF;AACnF,MAAM,kBAAkB,GAAG,MAAM,CAAC;AA8ElC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,MAAM,CAAC,IAAuB,EAAE,UAAyB,EAAE;IACzE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,4EAA4E;QAC5E,gEAAgE;QAChE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,sCAAsC;YAC9C,KAAK,EAAE,IAAI,KAAK,CAAC,sCAAsC,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,+EAA+E;IAC/E,8EAA8E;IAC9E,+EAA+E;IAC/E,8EAA8E;IAC9E,sDAAsD;IACtD,MAAM,MAAM,GAAG,iBAAiB,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE;QAC1C,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAChE,WAAW,EAAE,OAAO,CAAC,OAAO,KAAK,IAAI;QACrC,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;QAC/C,UAAU,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;QAChC,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,kBAAkB;QAC9C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB;KACnD,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,OAAO;QAClB,MAAM,EAAE,MAAM,CAAC,QAAQ;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,IAAuB,EAAE,UAAyB,EAAE;IAChF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IAEpC,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IAChE,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,YAAY,MAAM,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/git-snapshot.d.ts

@@ -0,0 +1,181 @@
+/**
+ * A **dirty-corrected git tree snapshot**, rebased onto absolute paths.
+ *
+ * `@vibe-validate/git`'s `getGitTreeSnapshot` answers the question git is
+ * uniquely good at: every path git can see under a directory, each with a blob
+ * OID naming *the bytes that are actually on disk right now* — dirty working-tree
+ * edits included, not the stale committed-index SHA — plus one deterministic
+ * `write-tree` hash over the whole set. Membership is `git add --all` without
+ * `--force`, i.e. `tracked ∪ (untracked ∧ ¬ignored)`.
+ *
+ * This module is the thin layer VAT needs on top, and it exists for one reason
+ * that is easy to get wrong: **git spells those paths relative to the repository
+ * root, not to the directory you asked about.** A caller scanning
+ * `<repo>/packages/foo` gets back `packages/foo/x.md`, and a caller that joined
+ * those onto its own root would build `<repo>/packages/foo/packages/foo/x.md` —
+ * a path that does not exist, so every consumer reads it as "absent" rather than
+ * as a bug. Resolving against the repository root here makes that unrepresentable
+ * at the call site.
+ *
+ * ## ⚠️ This is not a pure read
+ *
+ * Taking a snapshot runs `git add --all` against a throwaway index, which
+ * **writes loose blob objects into the target repository's `.git/objects`** for
+ * any content git has not already stored. The real index and working tree are
+ * never touched, and the objects are ordinary unreferenced blobs that `git gc`
+ * reclaims — but a command that advertises itself as read-only is, at the byte
+ * level, not. `vibe-validate` accepts this cost on every commit it gates; a VAT
+ * lane that adopts it inherits the same trade rather than a different one.
+ *
+ * ## ⚠️ A symlink's OID names its TARGET STRING, not a file's bytes
+ *
+ * Git stores a symlink as a blob whose content is the link target, under mode
+ * `120000`. Two links with the same relative target but different resolutions
+ * therefore share an OID while a consumer that follows them reads two different
+ * documents. {@link GitSnapshotEntry.isSymlink} is computed here precisely so
+ * that a consumer keying work off `oid` can exclude them — see
+ * `packages/resources/src/content-key.ts`, whose standing rule is that a git SHA
+ * may be a *lookup hint whose miss is free* and must never be the key itself.
+ *
+ * ## ⚠️ Two consumers want the SAME snapshot — see {@link withGitSnapshotCache}
+ *
+ * One command takes this snapshot twice, of one repository, sequentially, and
+ * keeps a different half of each: the projection store keeps `hash` as its
+ * cache key, and the git crawl source keeps `entries`. Bracketing the command
+ * makes that one snapshot. Everything outside the bracket still pays per call,
+ * deliberately.
+ */
+/** One path in a {@link GitTreeSnapshot}, located absolutely. */
+export interface GitSnapshotEntry {
+    /** Absolute, forward-slashed path, resolved against the repository root. */
+    absolutePath: string;
+    /**
+     * Blob OID for this path's **on-disk** bytes.
+     *
+     * Equal OIDs mean equal bytes, which is what makes this usable as a lookup
+     * hint. It is NOT usable as a content key — see the module docstring.
+     */
+    oid: string;
+    /** Git's six-digit mode, verbatim: `100644`, `100755`, `120000`, `160000`. */
+    mode: string;
+    /** Mode `120000`. Its {@link GitSnapshotEntry.oid} is the target string. */
+    isSymlink: boolean;
+    /**
+     * Mode `160000` — a submodule.
+     *
+     * The OID is a **commit**, not a blob, so `cat-file` on it yields no file
+     * bytes, and none of the submodule's own files appear anywhere in the
+     * snapshot. A consumer that needs them takes a second snapshot rooted there.
+     */
+    isSubmodule: boolean;
+}
+/** One repository's snapshot. */
+export interface GitTreeSnapshot {
+    /**
+     * `git write-tree` over the snapshot — a deterministic key for the whole set.
+     *
+     * Byte-identical content always produces it, because a tree object carries no
+     * timestamp. (A `stash create` would not: a stash is a commit, and two calls
+     * over identical content agree only within the same wall-clock second.)
+     */
+    hash: string;
+    /** The repository root every entry was resolved against, forward-slashed. */
+    repositoryRoot: string;
+    /** Every path git can see, in git's own order. */
+    entries: GitSnapshotEntry[];
+}
+/**
+ * Run work that may snapshot the same repository more than once, and pay for
+ * each repository ONCE.
+ *
+ * ## What this buys, in both currencies
+ *
+ * A snapshot is not a read — it copies the index, runs `git add --all` into it
+ * and then `git write-tree`. One `vat` command took two of them, of the same
+ * repository, back to back: `openPopulationCache` needs `hash` to key the
+ * projection store, and `GitCrawlSource` needs `entries` to enumerate. Measured
+ * on a large monorepo, the pair cost 195.22 ms and 158.55 ms.
+ *
+ * The cost is the smaller half. Two snapshots taken 195 ms apart are two
+ * *different answers* whenever the working tree changes in between, and the
+ * command then files the second one's extent under the first one's key — a
+ * cache entry whose key does not describe its contents, produced silently and
+ * discoverable only as a wrong answer much later. One snapshot removes the race
+ * rather than merely the duplicate.
+ *
+ * ## Where to open it
+ *
+ * At the level that already brackets the whole command, so that it encloses
+ * *every* snapshotting consumer. Opened deeper than one of them, the dedupe
+ * silently does nothing and looks exactly like a dedupe that works.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * Inside the bracket, a working-tree edit made between two calls is not
+ * observed by the second — the first snapshot is the answer for the whole
+ * bracket. That is the race being closed, not a limitation to work around. Work
+ * that must see edits as they land does not belong inside one bracket.
+ *
+ * Nesting is safe and inner-most wins: an inner bracket starts an empty memo,
+ * and the outer one's entries are restored when it returns.
+ *
+ * @param run - The work to run with the memo open. Sync or async — the return
+ *   value is passed straight through, so an async `run` keeps the memo for the
+ *   whole promise it returns
+ * @returns Whatever `run` returned
+ *
+ * @example
+ * ```typescript
+ * return withGitSnapshotCache(async () => {
+ *   const opened = await openPopulationCache(options); // snapshots
+ *   return work(opened?.cache);                        // crawls, snapshots
+ * });
+ * ```
+ */
+export declare function withGitSnapshotCache<T>(run: () => T): T;
+/**
+ * Snapshot everything git can see under a directory.
+ *
+ * Inside a {@link withGitSnapshotCache} bracket the answer for a given
+ * repository is taken once and reused — including a `null`. Outside one, every
+ * call spawns git, which is what it has always done.
+ *
+ * @param options - Where to look
+ * @param options.cwd - Any directory inside the repository of interest. Git
+ *   resolves upward to the worktree root, and the snapshot covers that whole
+ *   root — NOT only the subtree named here. Narrowing is the caller's job, and
+ *   is why {@link GitSnapshotEntry.absolutePath} is absolute
+ * @returns The snapshot, or `null` when git could not answer — no `git` on
+ *   `PATH`, not a repository, a bare or unreadable one. An empty `entries` is a
+ *   real answer (an initialized repository with no files) and stays
+ *   distinguishable from it
+ */
+export declare function gitTreeSnapshot(options: {
+    cwd: string;
+}): GitTreeSnapshot | null;
+/**
+ * The snapshot this bracket ALREADY holds for a repository — never a new one.
+ *
+ * The difference from {@link gitTreeSnapshot} is the whole reason this exists:
+ * that function TAKES a snapshot when the memo misses, and a snapshot is three
+ * spawns and a `git add --all`. This one only ever reports what a previous
+ * caller already paid for, so a consumer can prefer it and fall back to its own
+ * cheaper question without any risk of turning a miss into the most expensive
+ * git operation in the package.
+ *
+ * That asymmetry is what makes it safe to reach for from shared code. The
+ * {@link GitTracker} does exactly this: inside the projection's git lane a
+ * snapshot is already in hand and describes precisely the set its own
+ * `git ls-files --cached --others --exclude-standard` would spawn to rebuild,
+ * while on the incumbent walk no snapshot is ever taken and the tracker must
+ * keep spawning. One consumer, two lanes, and neither pays for the other's
+ * strategy.
+ *
+ * @param cwd - Any directory inside the repository of interest
+ * @returns The memoized snapshot, or `undefined` when this bracket has none —
+ *   which includes there being no bracket open at all, and includes a memoized
+ *   `null` (git could not answer). Callers treat all three the same way: ask
+ *   your own question instead
+ */
+export declare function peekGitTreeSnapshot(cwd: string): GitTreeSnapshot | undefined;
+//# sourceMappingURL=git-snapshot.d.ts.map

package/dist/git-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-snapshot.d.ts","sourceRoot":"","sources":["../src/git-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AASH,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAEvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GAAG,IAAI,CA2BhF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAY5E"}

package/dist/git-snapshot.js

@@ -0,0 +1,232 @@
+/**
+ * A **dirty-corrected git tree snapshot**, rebased onto absolute paths.
+ *
+ * `@vibe-validate/git`'s `getGitTreeSnapshot` answers the question git is
+ * uniquely good at: every path git can see under a directory, each with a blob
+ * OID naming *the bytes that are actually on disk right now* — dirty working-tree
+ * edits included, not the stale committed-index SHA — plus one deterministic
+ * `write-tree` hash over the whole set. Membership is `git add --all` without
+ * `--force`, i.e. `tracked ∪ (untracked ∧ ¬ignored)`.
+ *
+ * This module is the thin layer VAT needs on top, and it exists for one reason
+ * that is easy to get wrong: **git spells those paths relative to the repository
+ * root, not to the directory you asked about.** A caller scanning
+ * `<repo>/packages/foo` gets back `packages/foo/x.md`, and a caller that joined
+ * those onto its own root would build `<repo>/packages/foo/packages/foo/x.md` —
+ * a path that does not exist, so every consumer reads it as "absent" rather than
+ * as a bug. Resolving against the repository root here makes that unrepresentable
+ * at the call site.
+ *
+ * ## ⚠️ This is not a pure read
+ *
+ * Taking a snapshot runs `git add --all` against a throwaway index, which
+ * **writes loose blob objects into the target repository's `.git/objects`** for
+ * any content git has not already stored. The real index and working tree are
+ * never touched, and the objects are ordinary unreferenced blobs that `git gc`
+ * reclaims — but a command that advertises itself as read-only is, at the byte
+ * level, not. `vibe-validate` accepts this cost on every commit it gates; a VAT
+ * lane that adopts it inherits the same trade rather than a different one.
+ *
+ * ## ⚠️ A symlink's OID names its TARGET STRING, not a file's bytes
+ *
+ * Git stores a symlink as a blob whose content is the link target, under mode
+ * `120000`. Two links with the same relative target but different resolutions
+ * therefore share an OID while a consumer that follows them reads two different
+ * documents. {@link GitSnapshotEntry.isSymlink} is computed here precisely so
+ * that a consumer keying work off `oid` can exclude them — see
+ * `packages/resources/src/content-key.ts`, whose standing rule is that a git SHA
+ * may be a *lookup hint whose miss is free* and must never be the key itself.
+ *
+ * ## ⚠️ Two consumers want the SAME snapshot — see {@link withGitSnapshotCache}
+ *
+ * One command takes this snapshot twice, of one repository, sequentially, and
+ * keeps a different half of each: the projection store keeps `hash` as its
+ * cache key, and the git crawl source keeps `entries`. Bracketing the command
+ * makes that one snapshot. Everything outside the bracket still pays per call,
+ * deliberately.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getGitTreeSnapshot, GIT_MODE_GITLINK, GIT_MODE_SYMLINK } from '@vibe-validate/git';
+import { gitFindRoot } from './git-utils.js';
+import { safePath } from './path-utils.js';
+/**
+ * The snapshots taken inside the bracket now open, keyed by repository root.
+ *
+ * `AsyncLocalStorage` rather than a module-level `Map`, and the distinction is
+ * the whole design. A blanket memo would dedupe the same two calls — and would
+ * then hand a stale snapshot to anything that mutates a repository and
+ * re-snapshots it in the same process, which is what a vitest worker running
+ * many suites does all day. Scoping it to a bracket makes the memo's lifetime
+ * something a caller states rather than something the module assumes; outside
+ * one, {@link gitTreeSnapshot} behaves exactly as it did before this existed.
+ *
+ * Async-scoped rather than a plain variable because the bracket spans a whole
+ * command's `await`s, and two commands may be open at once in one process —
+ * `crawl-timing.ts` reaches for the same primitive for the same reason.
+ *
+ * `null` is a stored value, not an absence: "git could not answer" costs a full
+ * `add`/`write-tree` attempt to discover, so repeating it is pure cost. Absence
+ * is `undefined`, which `Map.get` returns and this module never stores.
+ */
+const snapshotsInBracket = new AsyncLocalStorage();
+/**
+ * Run work that may snapshot the same repository more than once, and pay for
+ * each repository ONCE.
+ *
+ * ## What this buys, in both currencies
+ *
+ * A snapshot is not a read — it copies the index, runs `git add --all` into it
+ * and then `git write-tree`. One `vat` command took two of them, of the same
+ * repository, back to back: `openPopulationCache` needs `hash` to key the
+ * projection store, and `GitCrawlSource` needs `entries` to enumerate. Measured
+ * on a large monorepo, the pair cost 195.22 ms and 158.55 ms.
+ *
+ * The cost is the smaller half. Two snapshots taken 195 ms apart are two
+ * *different answers* whenever the working tree changes in between, and the
+ * command then files the second one's extent under the first one's key — a
+ * cache entry whose key does not describe its contents, produced silently and
+ * discoverable only as a wrong answer much later. One snapshot removes the race
+ * rather than merely the duplicate.
+ *
+ * ## Where to open it
+ *
+ * At the level that already brackets the whole command, so that it encloses
+ * *every* snapshotting consumer. Opened deeper than one of them, the dedupe
+ * silently does nothing and looks exactly like a dedupe that works.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * Inside the bracket, a working-tree edit made between two calls is not
+ * observed by the second — the first snapshot is the answer for the whole
+ * bracket. That is the race being closed, not a limitation to work around. Work
+ * that must see edits as they land does not belong inside one bracket.
+ *
+ * Nesting is safe and inner-most wins: an inner bracket starts an empty memo,
+ * and the outer one's entries are restored when it returns.
+ *
+ * @param run - The work to run with the memo open. Sync or async — the return
+ *   value is passed straight through, so an async `run` keeps the memo for the
+ *   whole promise it returns
+ * @returns Whatever `run` returned
+ *
+ * @example
+ * ```typescript
+ * return withGitSnapshotCache(async () => {
+ *   const opened = await openPopulationCache(options); // snapshots
+ *   return work(opened?.cache);                        // crawls, snapshots
+ * });
+ * ```
+ */
+export function withGitSnapshotCache(run) {
+    return snapshotsInBracket.run(new Map(), run);
+}
+/**
+ * Snapshot everything git can see under a directory.
+ *
+ * Inside a {@link withGitSnapshotCache} bracket the answer for a given
+ * repository is taken once and reused — including a `null`. Outside one, every
+ * call spawns git, which is what it has always done.
+ *
+ * @param options - Where to look
+ * @param options.cwd - Any directory inside the repository of interest. Git
+ *   resolves upward to the worktree root, and the snapshot covers that whole
+ *   root — NOT only the subtree named here. Narrowing is the caller's job, and
+ *   is why {@link GitSnapshotEntry.absolutePath} is absolute
+ * @returns The snapshot, or `null` when git could not answer — no `git` on
+ *   `PATH`, not a repository, a bare or unreadable one. An empty `entries` is a
+ *   real answer (an initialized repository with no files) and stays
+ *   distinguishable from it
+ */
+export function gitTreeSnapshot(options) {
+    // Resolved from the filesystem BEFORE spawning anything, and deliberately not
+    // from a `rev-parse` of our own: `getGitTreeSnapshot` has already paid for that
+    // question internally, and asking it twice invites the two answers to disagree
+    // on a worktree, where the git directory and the worktree root are different
+    // places. `gitFindRoot` is memoized, so this is free after the first call.
+    const repositoryRoot = gitFindRoot(options.cwd);
+    if (repositoryRoot === null) {
+        // Not memoized, and it does not need to be: this branch spawns nothing, and
+        // `gitFindRoot` has its own memo. There is also no key to file it under —
+        // the memo is keyed by repository root, and this is the case with none.
+        return null;
+    }
+    // Keyed by the RESOLVED root rather than by `options.cwd`, because a snapshot
+    // covers the whole repository however deep the directory it was asked from.
+    // The two call sites this bracket exists for pass different directories — the
+    // corpus root and the project root — so keying on `cwd` would produce two
+    // entries holding the identical answer, i.e. a dedupe that does nothing in
+    // exactly the case it was written for.
+    const memo = snapshotsInBracket.getStore();
+    const memoized = memo?.get(repositoryRoot);
+    if (memoized !== undefined)
+        return memoized;
+    const snapshot = takeSnapshot(options.cwd, repositoryRoot);
+    memo?.set(repositoryRoot, snapshot);
+    return snapshot;
+}
+/**
+ * The snapshot this bracket ALREADY holds for a repository — never a new one.
+ *
+ * The difference from {@link gitTreeSnapshot} is the whole reason this exists:
+ * that function TAKES a snapshot when the memo misses, and a snapshot is three
+ * spawns and a `git add --all`. This one only ever reports what a previous
+ * caller already paid for, so a consumer can prefer it and fall back to its own
+ * cheaper question without any risk of turning a miss into the most expensive
+ * git operation in the package.
+ *
+ * That asymmetry is what makes it safe to reach for from shared code. The
+ * {@link GitTracker} does exactly this: inside the projection's git lane a
+ * snapshot is already in hand and describes precisely the set its own
+ * `git ls-files --cached --others --exclude-standard` would spawn to rebuild,
+ * while on the incumbent walk no snapshot is ever taken and the tracker must
+ * keep spawning. One consumer, two lanes, and neither pays for the other's
+ * strategy.
+ *
+ * @param cwd - Any directory inside the repository of interest
+ * @returns The memoized snapshot, or `undefined` when this bracket has none —
+ *   which includes there being no bracket open at all, and includes a memoized
+ *   `null` (git could not answer). Callers treat all three the same way: ask
+ *   your own question instead
+ */
+export function peekGitTreeSnapshot(cwd) {
+    const memo = snapshotsInBracket.getStore();
+    if (memo === undefined)
+        return undefined;
+    // Resolved the same way `gitTreeSnapshot` resolves it, because the memo is
+    // keyed by repository root and not by the directory anyone asked from. A peek
+    // keyed on `cwd` would miss every time the snapshot was taken from a different
+    // depth — which is the normal case, and a miss here is silent.
+    const repositoryRoot = gitFindRoot(cwd);
+    if (repositoryRoot === null)
+        return undefined;
+    return memo.get(repositoryRoot) ?? undefined;
+}
+/**
+ * Ask git, and rebase the answer onto absolute paths.
+ *
+ * Split out so {@link gitTreeSnapshot} reads as "key, look up, or take one" —
+ * the memo has to sit above the spawn, and a memo interleaved with the mapping
+ * is how a later edit ends up caching the wrong half.
+ *
+ * @param cwd - The directory to ask git from
+ * @param repositoryRoot - The already-resolved root every entry is rebased onto
+ * @returns The snapshot, or `null` when git could not answer
+ */
+function takeSnapshot(cwd, repositoryRoot) {
+    const snapshot = getGitTreeSnapshot({ cwd });
+    if (snapshot === null) {
+        return null;
+    }
+    return {
+        hash: snapshot.hash,
+        repositoryRoot,
+        entries: snapshot.entries.map((entry) => ({
+            absolutePath: safePath.resolve(repositoryRoot, entry.path),
+            oid: entry.oid,
+            mode: entry.mode,
+            isSymlink: entry.mode === GIT_MODE_SYMLINK,
+            isSubmodule: entry.mode === GIT_MODE_GITLINK,
+        })),
+    };
+}
+//# sourceMappingURL=git-snapshot.js.map

package/dist/git-snapshot.js.map

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