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

package/dist/git-snapshot.js

@@ -0,0 +1,250 @@
+/**
+ * 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;
+}
+/**
+ * A snapshot taken NOW, whatever bracket is open — never read from or written to
+ * its memo.
+ *
+ * ⛔ The bracket makes two consumers agree with EACH OTHER; it cannot make them
+ * agree with files read later. A population keyed inside a bracket reads the
+ * working tree afterwards, so an edit landing in between is read and then filed
+ * under the pre-edit key. This is how a caller checks, before filing, that the
+ * bracket's answer still describes the tree. It costs a full snapshot, so it
+ * belongs on the write path, never on a hit.
+ *
+ * @param options - Where to look
+ * @param options.cwd - Any directory inside the repository of interest
+ * @returns The snapshot, or `null` when git could not answer
+ */
+export function freshGitTreeSnapshot(options) {
+    return snapshotsInBracket.exit(() => gitTreeSnapshot(options));
+}
+/**
+ * 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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"}

package/dist/git-tracker.d.ts

@@ -56,6 +56,33 @@ export declare class GitTracker {
     private readonly activeSet;
     /** Absolute paths of every directory that contains at least one active-set file. */
     private readonly activeAncestors;
+    /**
+     * Lowercased absolute path → the root-relative path spelled the way git
+     * spelled it. Built from the very same `git ls-files` output `activeSet`
+     * comes from, so it costs one extra `Map` and no extra git invocation.
+     */
+    private readonly indexPaths;
+    /**
+     * Absolute, forward-slashed directories the active-set listing could not
+     * OPEN, so nothing beneath them is in the set — read off `git ls-files
+     * --others`' stderr through the listing's `unreadable` policy (`degrade`).
+     *
+     * 🚨 Beneath one of these the active set has no opinion. Its rule is "absent
+     * from the set and present on disk ⇒ ignored", and that rule is sound only
+     * where the listing LOOKED: an untracked, non-ignored file under a `--x`
+     * directory is absent because git could not read the directory, not because
+     * a pattern excludes it, and `git check-ignore` — which answers from the
+     * patterns and needs no listing — says so. Before this was recorded the
+     * tracker called such a file gitignored, silently, and every consumer of
+     * that answer (the leak judge, the link-graph walker, audit's distributed
+     * lane) was one refused `opendir` from a wrong verdict.
+     *
+     * The directory ITSELF is non-ignored by construction — git opened it
+     * precisely because no pattern excluded it — so it and its ancestors are
+     * entered into {@link activeAncestors}: a walker must not prune what the
+     * listing could not see into.
+     */
+    private readonly unlistableDirectories;
     private initialized;
     private activeSetPopulated;
     /** Whether `git ls-files` actually answered during {@link initialize}. */
@@ -72,8 +99,60 @@ export declare class GitTracker {
      * With `includeUntracked: false`, only tracked files are pre-populated.
      * Untracked non-ignored files will miss the cache and fall through to
      * `git check-ignore` via {@link isIgnored}.
+     *
+     * ## This is the one bracket in the crawl-timing seam's `shared` stratum
+     *
+     * The `git ls-files` spawn below is preparation BOTH crawlers consume and
+     * NEITHER owns — the incumbent link walk and the projection's contributors are
+     * each handed a tracker by their caller — so it is charged to
+     * {@link CRAWL_SHARED_GIT_TRACKER_ID}, in a stratum belonging to no arm.
+     *
+     * The bracket is here, inside the class, and not at the six sites that build a
+     * tracker, for the reason `crawl-timing.ts` gives about `ResourceRegistry`: six
+     * copies are six chances to disagree, and a seventh site added later would
+     * silently go uncharged. Here, every caller is covered by construction — which
+     * includes `@vibe-agent-toolkit/discovery`, a package that could not have filed
+     * a row from its own call site at all, since it depends on `utils` alone.
+     *
+     * The early return above is deliberately OUTSIDE it: a re-entrant call does no
+     * work, and charging it would inflate `calls` with questions rather than
+     * spawns.
      */
     initialize(options?: GitTrackerInitOptions): Promise<void>;
+    /**
+     * The active set read off a snapshot this process has ALREADY taken — or
+     * `null` to say "ask git yourself".
+     *
+     * ## Why this is the same question, not a similar one
+     *
+     * `git ls-files --cached --others --exclude-standard` returns
+     * `tracked ∪ (untracked ∧ ¬ignored)`. A snapshot is `git add --all` **without**
+     * `--force` staged into a throwaway index, whose membership is that same set
+     * by construction — the exclusion of ignored paths is `--force`'s absence in
+     * both cases. So where a snapshot is already in hand, the spawn this method
+     * replaces would re-derive a set the process is already holding.
+     *
+     * It is deliberately a PEEK ({@link peekGitTreeSnapshot}) and never a take: a
+     * snapshot costs a `git add --all`, so causing one to avoid an `ls-files`
+     * would be a large loss dressed as a saving. On the incumbent walk no snapshot
+     * is ever taken, the peek misses, and this tracker spawns exactly as it always
+     * has.
+     *
+     * ## The one divergence, and why it is an improvement
+     *
+     * `--cached` reads the REAL index, so a tracked file deleted from the working
+     * tree is still listed. `git add --all` stages that deletion, so the snapshot
+     * omits it. The set is therefore not identical — it is the same set minus
+     * paths that do not exist, which is what {@link isIgnoredByActiveSet} already
+     * documents the active set to be ("it can only ever contain paths that
+     * EXIST"). The snapshot-sourced set honours that sentence more exactly than
+     * the spawn does.
+     *
+     * @param includeUntracked - The caller's requested membership
+     * @returns Root-relative paths in `git ls-files` shape, or `null` when no
+     *   snapshot is available or the request is one a snapshot cannot answer
+     */
+    private activePathsFromOpenSnapshot;
     /**
      * Did git actually answer, or is this tracker an empty shell?
      *
@@ -98,6 +177,22 @@ export declare class GitTracker {
      * `hasActiveDescendant` / `isIgnoredByActiveSet` ancestor lookup misses on Windows.
      */
     private populateAncestorSet;
+    /**
+     * Record `start` and every directory above it up to (not including) the
+     * project root as active ancestors, stopping at the first one already known
+     * — everything above it necessarily is too.
+     *
+     * @param start - Forward-slashed absolute directory to begin at
+     */
+    private recordAncestorsFrom;
+    /**
+     * Whether the active set can say anything about a path: it cannot beneath a
+     * directory the listing was refused — see {@link unlistableDirectories}.
+     *
+     * @param normalizedAbsolutePath - Forward-slashed absolute path
+     * @returns True when the path lies strictly beneath a refused directory
+     */
+    private beneathUnlistable;
     /**
      * Returns true if the given absolute path IS an active-set file OR is an
      * ancestor directory of at least one active-set file.
@@ -117,7 +212,9 @@ export declare class GitTracker {
      * For paths INSIDE the project root **that exist on disk**, membership in the
      * active set is authoritative: such a path is ignored iff it is not in the
      * active set AND not an ancestor of any active-set path. No `git
-     * check-ignore` spawn.
+     * check-ignore` spawn. The one exception is a path beneath a directory the
+     * listing could not OPEN — see {@link unlistableDirectories} — where absence
+     * says nothing and the question goes to `git check-ignore`.
      *
      * The existence qualifier is load-bearing, not a caveat. The active set is
      * built from `git ls-files`, so it can only ever contain paths that EXIST — a
@@ -131,7 +228,38 @@ export declare class GitTracker {
      * so a repeated miss on the same path stays O(1).
      *
      * For paths OUTSIDE the project root, falls back to {@link isIgnored} so
-     * legacy behavior is preserved.
+     * legacy behavior is preserved. That fallback is the expensive one, and its
+     * cost does not resemble the in-root cost at all.
+     *
+     * ## ⚠️ The out-of-root fallback costs an order of magnitude more per path
+     *
+     * Measured in the D9 parity fixture: an out-of-root path costs
+     * **185–427 ms**, against **12–28 ms** for every in-repo path — ≈7–36× on
+     * those ranges.
+     *
+     * The mechanism is the delegation above plus what git does with it.
+     * {@link isIgnored} runs `git check-ignore` with the PROJECT ROOT as cwd; git
+     * exits 128 for a path outside that repository; and {@link isGitIgnored}'s
+     * exit-128 recovery walk then spawns `check-ignore` ONCE PER ANCESTOR up to
+     * `/`. No ancestor of an out-of-root path is ever the project root that would
+     * stop the walk, and every one of those ancestors is outside the repository
+     * too — so each also exits 128 and the walk never breaks early either. The
+     * verdict is cached, so the price is paid once per DISTINCT out-of-root path
+     * rather than once per call.
+     *
+     * The consequence for a caller choosing between the two oracles: switching
+     * from {@link isIgnored} to this method removes the spawn population **only
+     * for in-root paths**. A lane feeding out-of-root paths in bulk keeps the
+     * per-path spawn in full. So a comment asserting that the out-of-project case
+     * is rare, safe or cheap is asserting something this measurement contradicts:
+     * it is rare in some lanes, and it is never cheap.
+     *
+     * The exit-128 walk itself is documented in {@link isGitIgnored} — but only
+     * for the two cases already answered there: the SYMLINK case it exists to
+     * serve, and the NO-REPOSITORY case, which an early return now short-circuits
+     * before any spawn. The IN-REPO OUT-OF-ROOT path is the third case, it is
+     * documented nowhere there, and it is the one that still pays the walk in
+     * full. That is why the number lives here.
      *
      * Requires {@link initialize} with `includeUntracked: true` (the default).
      * When initialized without untracked files, this method delegates to
@@ -139,8 +267,21 @@ export declare class GitTracker {
      * possible per-path spawn.
      *
      * @param absolutePath - Absolute path to check
+     * @param knownToExist - The caller's own answer to the existence question, when
+     *   it has already asked. Supplying it skips this method's `existsSync`, which
+     *   is otherwise paid once per path that is absent from the active set — i.e.
+     *   once per ignored path, and the projection's `filesystem` extent enumerates
+     *   all of them (11,108 calls on an 8,496-path adopter tree).
+     *
+     *   **It must mean what `existsSync` means: `stat` succeeds, following
+     *   symlinks.** A caller holding only an `lstat` result has a DIFFERENT fact —
+     *   `lstat` succeeds on a dangling symlink where `existsSync` returns false —
+     *   and must narrow it to `exists && symlinkResolves !== false` rather than
+     *   pass the `lstat` boolean through, or dangling symlinks silently stop
+     *   falling back to `git check-ignore` and start reporting as ignored.
+     *   Omit it and nothing changes.
      */
-    isIgnoredByActiveSet(absolutePath: string): boolean;
+    isIgnoredByActiveSet(absolutePath: string, knownToExist?: boolean): boolean;
     private isWithinProjectRoot;
     /**
      * Check if a file is ignored by git.
@@ -151,6 +292,28 @@ export declare class GitTracker {
      * @returns true if file is gitignored, false otherwise
      */
     isIgnored(filePath: string): boolean;
+    /**
+     * The spelling git records for a path, or `null` if git has no record of it.
+     *
+     * This is the casing oracle, not another ignore check. On a case-insensitive
+     * filesystem `docs/Readme.md` and `docs/README.md` are one inode with two
+     * spellings, and Node's two `realpath` implementations disagree about which
+     * one they hand back — so anything that derives an identity from a path needs
+     * a single authoritative spelling, and git's is it wherever git has one.
+     *
+     * The lookup key is lowercased, which is the point: the caller asks with
+     * whatever casing it observed and gets back the casing git holds.
+     *
+     * Answers only from the pre-populated set — never spawns. A path git does not
+     * know (untracked-and-ignored, non-existent, outside the project root, or any
+     * path at all when `git ls-files` did not answer) returns `null`, and the
+     * caller falls back to the on-disk casing.
+     *
+     * @param absolutePath - Absolute path to look up
+     * @returns Root-relative, forward-slashed path as git spells it — relative to
+     *   THIS tracker's project root — or `null` when git has no record of it
+     */
+    indexPathFor(absolutePath: string): string | null;
     /**
      * Get cache statistics.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"git-tracker.d.ts","sourceRoot":"","sources":["../src/git-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0B;IAC1D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAS;IACnC,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM;IAK/B;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BhE;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAwB3B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAQlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IA0BnD,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAqBpC;;OAEG;IACH,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAE;IAQrF;;OAEG;IACH,KAAK,IAAI,IAAI;CAQd"}
+{"version":3,"file":"git-tracker.d.ts","sourceRoot":"","sources":["../src/git-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0B;IAC1D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAgB;IACtD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAS;IACnC,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM;IAK/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0ChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,CAAC,2BAA2B;IA6BnC;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAUlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0EG;IACH,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO;IAiC3E,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAqBpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIjD;;OAEG;IACH,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAE;IAQrF;;OAEG;IACH,KAAK,IAAI,IAAI;CAUd"}