@descryy/core 0.4.0 → 0.5.0

package/dist/sources/git/env.js

@@ -1,21 +1,20 @@
 /**
- * The variables git exports into every hook and injects into every
- * subprocess it spawns. Left in place, an inherited `GIT_DIR` (or
- * `GIT_WORK_TREE`/`GIT_INDEX_FILE`/`GIT_COMMON_DIR`) overrides repository
- * discovery even when a git subprocess is given an explicit `cwd` — confirmed
- * directly: `GIT_DIR=<other>/.git` with `cwd` pointed elsewhere still
- * initialises `<other>/.git`, not a repository at `cwd`.
- *
- * Anything here that shells out to git against a caller-supplied path must
- * not inherit these, or a caller running inside a git hook (which always has
- * `GIT_DIR` set) silently operates on the hook's own repository instead of
- * the one it was given.
+ * Git env vars that override repo discovery even with an explicit `cwd` (confirmed: `GIT_DIR` elsewhere still wins). Must be stripped before shelling out against a
+ * caller-supplied path, or a caller inside a git hook silently operates on the hook's own repo.
  */
 const LEAKY_GIT_VARS = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"];
+/** B-11: `cwd` may be an untrusted repo (e.g. an extracted archive with an
+ *  attacker-authored `.git/config`). `GIT_CONFIG_NOSYSTEM` closes only the
+ *  system-config layer, not repo-local config — see `HARDENED_GIT_CONFIG_ARGS`. */
 export function cleanGitEnv(base = process.env) {
     const env = { ...base };
     for (const key of LEAKY_GIT_VARS)
         delete env[key];
+    env["GIT_CONFIG_NOSYSTEM"] = "1";
     return env;
 }
+/** `-c` overrides ahead of every git subcommand against a caller-supplied repo (B-11): neutralises `core.fsmonitor`/`core.pager` (external-command hooks; `GIT_CONFIG_NOSYSTEM` can't reach repo-local config), zero behavioural cost since output here never hits a tty.
+ *  `diff.external` handled separately via `--no-ext-diff` at its two call sites (`diff.ts`, `multipr/fingerprint.ts`).
+ *  `filter.*.clean` is NOT addressed — driver name is dynamic per-repo; unreachable through any call here today, disclosed as a residual gap. */
+export const HARDENED_GIT_CONFIG_ARGS = ["-c", "core.fsmonitor=false", "-c", "core.pager=cat"];
 //# sourceMappingURL=env.js.map

package/dist/sources/git/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/sources/git/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,CAAU,CAAC;AAEjG,MAAM,UAAU,WAAW,CAAC,OAA0B,OAAO,CAAC,GAAG;IAC/D,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IACxB,KAAK,MAAM,GAAG,IAAI,cAAc;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/sources/git/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,CAAU,CAAC;AAEjG;;mFAEmF;AACnF,MAAM,UAAU,WAAW,CAAC,OAA0B,OAAO,CAAC,GAAG;IAC/D,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IACxB,KAAK,MAAM,GAAG,IAAI,cAAc;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,GAAG,CAAC,qBAAqB,CAAC,GAAG,GAAG,CAAC;IACjC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;iJAEiJ;AACjJ,MAAM,CAAC,MAAM,wBAAwB,GAAsB,CAAC,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/sources/git/history.d.ts

@@ -1,24 +1,6 @@
 /**
- * Reading git history.
- *
- * No dependency: `git` is invoked directly. A library would buy parsing help and
- * cost a dependency in a package that has none by design, and the format below
- * is chosen so parsing is unambiguous rather than clever.
- *
- * ## Renames are resolved, not ignored
- *
- * `CHANGES_WITH` is file-to-file, and `FILE` identity is DEC-004's documented
- * path fallback — a file's only stable name *is* its path. So a rename silently
- * splits a file's history in two: the co-change weight built up over two years
- * resets to zero, and nothing in the output reveals it happened. That is the
- * exact failure DEC-004 exists to prevent, arriving through the one node type
- * that cannot avoid it.
- *
- * The fix is `-M` plus a canonicalisation pass: history is walked newest-first,
- * and every historical path is mapped forward to the name the file has today. It
- * makes DEC-004's guarantee total for files that git can *follow*; where git's
- * rename detection fails (a rewrite with no similarity), the guarantee stays
- * partial and that is now a bounded, stated gap rather than an unbounded one.
+ * Reading git history. No dependency: git invoked directly, no parsing library. Renames are resolved, not ignored: FILE identity is path-based (DEC-004), so an unresolved rename would silently reset co-change weight to zero.
+ * `-M` plus a newest-first canonicalisation pass maps every historical path forward to today's name — total where git can follow the rename, a disclosed partial gap where it can't (a rewrite with no similarity match).
  */
 export interface CommitChange {
     /** Path as it is known **today**, after following renames forward. */
@@ -42,15 +24,20 @@ export interface HistoryOptions {
     readonly maxFilesPerCommit?: number;
 }
 export declare function gitHead(cwd: string): Promise<string>;
+/** Thrown when the git process itself could not be run (missing binary,
+ *  bad cwd) — distinct from git running and answering "not a repository".
+ *  Collapsing the two (as this used to) teaches a false fact with no way to detect it; every caller must let this propagate rather than treat it as "not a repository". */
+export declare class GitUnavailableError extends Error {
+    constructor(cwd: string, cause: unknown);
+}
 export declare function isGitRepository(cwd: string): Promise<boolean>;
-/**
- * Read history newest-first, with renames followed forward to today's paths.
- *
- * `--no-merges` is deliberate: a merge commit's file list is the union of both
- * branches, so counting it as co-change would report every file in a large merge
- * as coupled to every other. That is the single largest source of false
- * `CHANGES_WITH` edges, and it is free to exclude.
- */
+/** Whether `absolutePath` is tracked by git in `cwd`. A-F1: a bare module
+ *  specifier resolves against the scanned repo's own node_modules — a real
+ *  `npm install` leaves it untracked, but a hostile repo can COMMIT a payload there for a victim who only clones and never runs install; tracked-in-git is the discriminator. Returns null (not false) when `cwd` isn't a git repo at all — "cannot determine" must never collapse into "untracked, therefore safe". Outside `cwd` entirely returns false. */
+export declare function isPathTrackedByGit(cwd: string, absolutePath: string): Promise<boolean | null>;
+/** Read history newest-first, renames followed forward. `--no-merges` is
+ *  deliberate: a merge's file list is the union of both branches — the
+ *  single largest source of false CHANGES_WITH edges, and free to exclude. */
 export declare function readHistory(cwd: string, options?: HistoryOptions): Promise<Commit[]>;
 export interface PathLogOptions {
     /** Cap on commits returned. Default 20 — this is a live, on-demand read, not a bulk ingestion. */
@@ -70,71 +57,64 @@ export interface PathLogCommit {
 }
 export interface PathLogResult {
     readonly commits: readonly PathLogCommit[];
-    /**
-     * How many commits touch this path in total, independent of `maxCommits`.
-     * A second, cheap `git log --format=%H` count — not `commits.length`,
-     * which stops at the cap — so a caller can tell "here are the 20 most
-     * recent" from "here are all 3 there are" without guessing from the cap.
-     */
+    /** Total commits touching this path, independent of `maxCommits` — a
+     *  second cheap count, not `commits.length`, which stops at the cap. */
     readonly totalTouching: number;
 }
-/**
- * Live commit history for one file, right now — distinct from `history.ts`'s
- * `changesWith`, which only reads the graph's stored `CHANGES_WITH` ledger
- * built once at `analyze` time. `--follow` tracks the file across renames;
- * unlike `readHistory`'s whole-repo walk, each commit here reports its own
- * historical name rather than today's — the rename itself is part of what a
- * caller asking "what happened to this file" wants to see.
- */
+/** Live commit history for one file — distinct from the graph's stored
+ *  CHANGES_WITH ledger. `--follow` tracks renames; each commit reports its
+ *  own historical name, not today's — the rename is part of what's asked. */
 export declare function logForPath(cwd: string, path: string, options?: PathLogOptions): Promise<PathLogResult>;
+/** Resolve one commit by sha, bypassing readHistory's HEAD-reachability and
+ *  --no-merges filters — a revert can name a merge or an unreachable, not-yet-GC'd
+ *  commit that readHistory's index can't see. Returns null only if the object is truly gone; caller must disclose, never drop silently (rule 7). Paths aren't forward-canonicalised (disclosed gap). */
+export declare function resolveCommitBySha(cwd: string, sha: string, maxFilesPerCommit?: number): Promise<Commit | null>;
+/** Files changed between two refs, for PR analysis. `base...head` (three
+ *  dots, not two) diffs against the merge base — two dots would include every
+ *  file changed on base since the branch point, someone else's change. Deletions included: what called the removed thing is the useful question. */
+export declare function changedFiles(cwd: string, base: string, head?: string): Promise<string[]>;
+/** `git show --name-only` for one commit, with today's paths where known. */
+export declare function filesInCommit(cwd: string, sha: string): Promise<string[]>;
 /**
- * Resolve one commit directly by sha, bypassing both `readHistory`'s
- * reachability filter and its `--no-merges` exclusion.
+ * Which of these paths git reports as uncommitted — modified, staged or untracked.
  *
- * `readHistory` walks history from `HEAD` only — co-change must stay scoped to
- * mainline, or work in progress on other branches would pollute
- * `CHANGES_WITH` — and drops merge commits, because a merge's file list is
- * the union of both branches (see the module doc). Both are correct for
- * co-change. Neither is correct for resolving what a revert commit names:
- * `git revert`'s `This reverts commit <sha>` line can point at a commit that
- * **is** a merge ("Revert Merge pull request #N"), or at a commit that is
- * real and still in the object database but not an ancestor of `HEAD` — an
- * abandoned branch, or one deleted after a squash/rebase merge whose objects
- * have not yet been garbage-collected. Neither case means the commit does
- * not exist; `readHistory`'s index just cannot see it.
+ * One `git status --porcelain` over the named paths rather than a call per
+ * file. `--porcelain` is the stable machine format, guaranteed across versions,
+ * and its two status columns cover every state that matters here at once: a
+ * file the index has and `HEAD` does not, one the working tree has and the
+ * index does not, and one git has never seen.
  *
- * `git cat-file` and `git diff-tree` operate on the object database directly
- * and enforce neither constraint, so this is the fallback `createGitSource`
- * uses once `readHistory`'s own index has already missed a revert target.
- *
- * Returns `null` only when the object genuinely does not exist — the
- * squash-merge case, where the original commit was never an ancestor of
- * anything that survived and its object is gone from the store. That is the
- * one case nothing can resolve; the caller must disclose it rather than
- * drop it silently (CLAUDE.md rule 7 — every fallback is labelled).
- *
- * File paths returned here are **not** forward-canonicalised through
- * `readHistory`'s rename map — this commit was never visited by that walk.
- * A file renamed on mainline *after* this commit landed will show under its
- * name at the time, not today's name. That is a narrower, disclosed version
- * of the same rename gap the module doc already states for the primary walk.
+ * The distinction this exists to make is not cosmetic. A path absent from a
+ * ref-to-ref diff might be uncommitted work, or it might be a file the caller
+ * named that this branch simply did not touch. Both make a coverage section
+ * describe something else; only the first is a fact about timing that the
+ * developer can act on in the next thirty seconds.
  */
-export declare function resolveCommitBySha(cwd: string, sha: string, maxFilesPerCommit?: number): Promise<Commit | null>;
+export declare function uncommittedAmong(cwd: string, paths: readonly string[]): Promise<readonly string[]>;
+export interface WorkingTreeFilesOptions {
+    /** Which tracked-file comparison to make. Default `"all"` — everything uncommitted. */
+    readonly scope?: "unstaged" | "staged" | "all";
+    /** Include files git has never seen. Default true — see below. */
+    readonly includeUntracked?: boolean;
+    /**
+     * Directory prefixes whose contents are not the change under review — a
+     * tool's own state, where a `.gitignore` does not happen to cover it.
+     * Matched at a segment boundary, so `.descry` leaves `src/.descryfile.ts`.
+     */
+    readonly exclude?: readonly string[];
+}
 /**
- * Files changed between two refs — the input to PR analysis.
+ * The paths a working tree changes, as {@link changedFiles} does for a range.
  *
- * `base...head` (three dots) rather than `base..head`, and the difference is the
- * whole point: two dots diffs the two tips, so every file changed on `base`
- * since the branch point appears in the result as though the PR had touched it.
- * On a branch a week behind `main` that is most of the diff, and the blast
- * radius it produces belongs to somebody else's change. Three dots diffs against
- * the merge base, which is what a reviewer is actually looking at.
+ * Name-only, so it is the cheap counterpart to `gitWorkingTreeChange`: a caller
+ * that only needs to know *which* files changed should not pay for every patch.
  *
- * Deletions are included. A deleted file's nodes may still be in the graph, and
- * *what called the thing you just removed* is the most useful question a diff
- * can be asked.
+ * **Untracked is on by default here**, unlike the diff-producing function. That
+ * one is a library primitive whose existing callers must not change behaviour
+ * by upgrading. This one exists to answer "what is the change about to be
+ * committed", and a new file written and not yet added is part of that change —
+ * defaulting it off would mean the function misses, by default, the case it was
+ * written for.
  */
-export declare function changedFiles(cwd: string, base: string, head?: string): Promise<string[]>;
-/** `git show --name-only` for one commit, with today's paths where known. */
-export declare function filesInCommit(cwd: string, sha: string): Promise<string[]>;
+export declare function workingTreeChangedFiles(cwd: string, options?: WorkingTreeFilesOptions): Promise<string[]>;
 //# sourceMappingURL=history.d.ts.map

package/dist/sources/git/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/sources/git/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA0BH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AA0BD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4D9F;AAED,MAAM,WAAW,cAAc;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,+GAA+G;AAC/G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7C,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAuDxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,iBAAiB,SAAK,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoExB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,SAAS,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB;AAED,6EAA6E;AAC7E,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU/E"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/sources/git/history.ts"],"names":[],"mappings":"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"}

package/dist/sources/git/history.js

@@ -1,32 +1,16 @@
 /**
- * Reading git history.
- *
- * No dependency: `git` is invoked directly. A library would buy parsing help and
- * cost a dependency in a package that has none by design, and the format below
- * is chosen so parsing is unambiguous rather than clever.
- *
- * ## Renames are resolved, not ignored
- *
- * `CHANGES_WITH` is file-to-file, and `FILE` identity is DEC-004's documented
- * path fallback — a file's only stable name *is* its path. So a rename silently
- * splits a file's history in two: the co-change weight built up over two years
- * resets to zero, and nothing in the output reveals it happened. That is the
- * exact failure DEC-004 exists to prevent, arriving through the one node type
- * that cannot avoid it.
- *
- * The fix is `-M` plus a canonicalisation pass: history is walked newest-first,
- * and every historical path is mapped forward to the name the file has today. It
- * makes DEC-004's guarantee total for files that git can *follow*; where git's
- * rename detection fails (a rewrite with no similarity), the guarantee stays
- * partial and that is now a bounded, stated gap rather than an unbounded one.
+ * Reading git history. No dependency: git invoked directly, no parsing library. Renames are resolved, not ignored: FILE identity is path-based (DEC-004), so an unresolved rename would silently reset co-change weight to zero.
+ * `-M` plus a newest-first canonicalisation pass maps every historical path forward to today's name — total where git can follow the rename, a disclosed partial gap where it can't (a rewrite with no similarity match).
  */
 import { execFile } from "node:child_process";
+import { isAbsolute, relative } from "node:path";
 import { promisify } from "node:util";
-import { cleanGitEnv } from "./env.js";
+import { cleanGitEnv, HARDENED_GIT_CONFIG_ARGS } from "./env.js";
 const execFileAsync = promisify(execFile);
-// Always strips GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE/GIT_COMMON_DIR — see env.ts.
+// Always strips GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE/GIT_COMMON_DIR, sets
+// GIT_CONFIG_NOSYSTEM and applies HARDENED_GIT_CONFIG_ARGS — see env.ts (B-11).
 function run(command, args, options) {
-    return execFileAsync(command, args, {
+    return execFileAsync(command, [...HARDENED_GIT_CONFIG_ARGS, ...args], {
         ...options,
         encoding: "utf8",
         env: cleanGitEnv(),
@@ -39,24 +23,62 @@ export async function gitHead(cwd) {
     const { stdout } = await run("git", ["rev-parse", "HEAD"], { cwd });
     return stdout.trim();
 }
+/** Thrown when the git process itself could not be run (missing binary,
+ *  bad cwd) — distinct from git running and answering "not a repository".
+ *  Collapsing the two (as this used to) teaches a false fact with no way to detect it; every caller must let this propagate rather than treat it as "not a repository". */
+export class GitUnavailableError extends Error {
+    constructor(cwd, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`git could not be run in "${cwd}" (${detail}). This is not a fact about whether that ` +
+            "directory is a git repository — check that the directory exists and that git is " +
+            "installed and reachable on PATH.");
+        this.name = "GitUnavailableError";
+        this.cause = cause;
+    }
+}
+/** True only when the git process never started (spawn failed — string
+ *  `code`, no stdout/stderr), vs. running and exiting non-zero (numeric
+ *  code, populated output) — the only signal distinguishing the two cases. */
+function isSpawnFailure(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        typeof err.code === "string");
+}
 export async function isGitRepository(cwd) {
     try {
         const { stdout } = await run("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
         return stdout.trim() === "true";
     }
-    catch {
+    catch (err) {
+        if (isSpawnFailure(err))
+            throw new GitUnavailableError(cwd, err);
         return false;
     }
 }
+/** Whether `absolutePath` is tracked by git in `cwd`. A-F1: a bare module
+ *  specifier resolves against the scanned repo's own node_modules — a real
+ *  `npm install` leaves it untracked, but a hostile repo can COMMIT a payload there for a victim who only clones and never runs install; tracked-in-git is the discriminator. Returns null (not false) when `cwd` isn't a git repo at all — "cannot determine" must never collapse into "untracked, therefore safe". Outside `cwd` entirely returns false. */
+export async function isPathTrackedByGit(cwd, absolutePath) {
+    const rel = relative(cwd, absolutePath);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return false;
+    if (!(await isGitRepository(cwd)))
+        return null;
+    try {
+        const { stdout } = await run("git", ["ls-files", "-z", "--", rel], { cwd });
+        return stdout.length > 0;
+    }
+    catch {
+        // A repo that refuses ls-files (corrupted index, permissions) is the
+        // same "cannot determine" case as no repository — not evidence either way.
+        return null;
+    }
+}
 const LOG_FORMAT = `${RECORD}%H${FIELD}%at${FIELD}%s${FIELD}%b${FIELD}`;
-/**
- * Split one `--format=<RECORD>%H<FIELD>%at<FIELD>%s<FIELD>%b<FIELD>` record
- * into its four fields plus the raw `--name-status` block that follows them.
- * Shared by `readHistory` and `logForPath` — everything past this point
- * (how paths are resolved, whether a rename mutates shared state) differs
- * enough between the two that sharing further would cost more than it
- * saves; see `readHistory`'s own resolve closure for why.
- */
+/** Splits one log record into its four fields plus the raw name-status block.
+ *  Shared by readHistory/logForPath; sharing further isn't worth it since
+ *  path resolution diverges sharply between the two. */
 function splitRecord(record) {
     if (record.trim() === "")
         return null;
@@ -72,14 +94,9 @@ function splitRecord(record) {
         nameStatus: parts.slice(4).join(FIELD),
     };
 }
-/**
- * Read history newest-first, with renames followed forward to today's paths.
- *
- * `--no-merges` is deliberate: a merge commit's file list is the union of both
- * branches, so counting it as co-change would report every file in a large merge
- * as coupled to every other. That is the single largest source of false
- * `CHANGES_WITH` edges, and it is free to exclude.
- */
+/** Read history newest-first, renames followed forward. `--no-merges` is
+ *  deliberate: a merge's file list is the union of both branches — the
+ *  single largest source of false CHANGES_WITH edges, and free to exclude. */
 export async function readHistory(cwd, options = {}) {
     const maxCommits = options.maxCommits ?? 2000;
     const maxFiles = options.maxFilesPerCommit ?? 50;
@@ -106,9 +123,8 @@ export async function readHistory(cwd, options = {}) {
                 const to = fields[2];
                 if (from === undefined || to === undefined)
                     continue;
-                // Walking newest-first, so `to` is the newer name: anything older that
-                // called this file `from` is the same file, known today as whatever
-                // `to` currently resolves to.
+                // Walking newest-first: `to` is the newer name, so anything older
+                // called `from` is the same file, known today as `to` resolves.
                 if (code.startsWith("R"))
                     canonical.set(from, resolve(to));
                 changes.push({ path: resolve(to), status: code.startsWith("R") ? "R" : "C", fromPath: resolve(from) });
@@ -122,10 +138,8 @@ export async function readHistory(cwd, options = {}) {
                 continue;
             changes.push({ path: resolve(path), status });
         }
-        // A commit touching hundreds of files is a reformat, a dependency bump or a
-        // move — it says nothing about which files are logically coupled, and
-        // including it makes every file in it co-change with every other. That is
-        // O(n^2) noise from a single commit.
+        // A commit touching hundreds of files (reformat, dependency bump) says
+        // nothing about coupling — including it is O(n^2) noise from one commit.
         if (changes.length === 0 || changes.length > maxFiles) {
             commits.push({ sha, timestamp, subject, body, changes: [] });
             continue;
@@ -134,14 +148,9 @@ export async function readHistory(cwd, options = {}) {
     }
     return commits;
 }
-/**
- * Live commit history for one file, right now — distinct from `history.ts`'s
- * `changesWith`, which only reads the graph's stored `CHANGES_WITH` ledger
- * built once at `analyze` time. `--follow` tracks the file across renames;
- * unlike `readHistory`'s whole-repo walk, each commit here reports its own
- * historical name rather than today's — the rename itself is part of what a
- * caller asking "what happened to this file" wants to see.
- */
+/** Live commit history for one file — distinct from the graph's stored
+ *  CHANGES_WITH ledger. `--follow` tracks renames; each commit reports its
+ *  own historical name, not today's — the rename is part of what's asked. */
 export async function logForPath(cwd, path, options = {}) {
     const maxCommits = options.maxCommits ?? 20;
     const { stdout } = await run("git", ["log", "--no-merges", "--follow", "-M", "--name-status", `--max-count=${maxCommits}`, `--format=${LOG_FORMAT}`, "--", path], { cwd, maxBuffer: 64 * 1024 * 1024 });
@@ -151,9 +160,8 @@ export async function logForPath(cwd, path, options = {}) {
         if (split === null)
             continue;
         const { sha, timestamp, subject, body, nameStatus } = split;
-        // `--follow` scopes the walk to one file's lineage, so exactly one
-        // name-status line is expected per commit; the first is taken rather
-        // than asserting an invariant a future git version could quietly break.
+        // `--follow` scopes to one file's lineage: exactly one line expected
+        // per commit, taken rather than asserted (a future git could break it).
         const line = nameStatus.split("\n").find((l) => l.trim() !== "");
         if (line === undefined)
             continue;
@@ -189,38 +197,9 @@ export async function logForPath(cwd, path, options = {}) {
     const totalTouching = countOut.split("\n").filter((l) => l.trim() !== "").length;
     return { commits, totalTouching };
 }
-/**
- * Resolve one commit directly by sha, bypassing both `readHistory`'s
- * reachability filter and its `--no-merges` exclusion.
- *
- * `readHistory` walks history from `HEAD` only — co-change must stay scoped to
- * mainline, or work in progress on other branches would pollute
- * `CHANGES_WITH` — and drops merge commits, because a merge's file list is
- * the union of both branches (see the module doc). Both are correct for
- * co-change. Neither is correct for resolving what a revert commit names:
- * `git revert`'s `This reverts commit <sha>` line can point at a commit that
- * **is** a merge ("Revert Merge pull request #N"), or at a commit that is
- * real and still in the object database but not an ancestor of `HEAD` — an
- * abandoned branch, or one deleted after a squash/rebase merge whose objects
- * have not yet been garbage-collected. Neither case means the commit does
- * not exist; `readHistory`'s index just cannot see it.
- *
- * `git cat-file` and `git diff-tree` operate on the object database directly
- * and enforce neither constraint, so this is the fallback `createGitSource`
- * uses once `readHistory`'s own index has already missed a revert target.
- *
- * Returns `null` only when the object genuinely does not exist — the
- * squash-merge case, where the original commit was never an ancestor of
- * anything that survived and its object is gone from the store. That is the
- * one case nothing can resolve; the caller must disclose it rather than
- * drop it silently (CLAUDE.md rule 7 — every fallback is labelled).
- *
- * File paths returned here are **not** forward-canonicalised through
- * `readHistory`'s rename map — this commit was never visited by that walk.
- * A file renamed on mainline *after* this commit landed will show under its
- * name at the time, not today's name. That is a narrower, disclosed version
- * of the same rename gap the module doc already states for the primary walk.
- */
+/** Resolve one commit by sha, bypassing readHistory's HEAD-reachability and
+ *  --no-merges filters — a revert can name a merge or an unreachable, not-yet-GC'd
+ *  commit that readHistory's index can't see. Returns null only if the object is truly gone; caller must disclose, never drop silently (rule 7). Paths aren't forward-canonicalised (disclosed gap). */
 export async function resolveCommitBySha(cwd, sha, maxFilesPerCommit = 50) {
     try {
         await run("git", ["cat-file", "-e", `${sha}^{commit}`], { cwd });
@@ -233,11 +212,9 @@ export async function resolveCommitBySha(cwd, sha, maxFilesPerCommit = 50) {
     const [tsRaw, subject, ...bodyParts] = metaOut.split(FIELD);
     const timestamp = Number(tsRaw ?? 0);
     const body = bodyParts.join(FIELD).replace(/\n+$/, "");
-    // Diff against the first parent: for an ordinary commit that is its only
-    // parent, so this is identical to a normal diff. For a merge commit it is
-    // "what this merge brought in relative to mainline" — exactly the file
-    // list a revert of that merge names. A root commit has no parent at all;
-    // fall back to a diff against the empty tree.
+    // Diff against the first parent — identical to normal for an ordinary
+    // commit, "what this merge brought in" for a merge. Root commit: diff
+    // against the empty tree.
     let nameStatus;
     try {
         ({ stdout: nameStatus } = await run("git", ["diff-tree", "-M", "--no-commit-id", "--name-status", "-r", `${sha}^1`, sha], { cwd, maxBuffer: 64 * 1024 * 1024 }));
@@ -273,26 +250,14 @@ export async function resolveCommitBySha(cwd, sha, maxFilesPerCommit = 50) {
         timestamp,
         subject: subject ?? "",
         body,
-        // Same reformat/dependency-bump cap `readHistory` applies — a revert of a
-        // merge that brought in hundreds of files should not fan
-        // INCIDENT_CORRELATED out into hundreds of edges either.
+        // Same reformat/dependency-bump cap readHistory applies — a big merge
+        // revert shouldn't fan INCIDENT_CORRELATED into hundreds of edges.
         changes: changes.length > maxFilesPerCommit ? [] : changes,
     };
 }
-/**
- * Files changed between two refs — the input to PR analysis.
- *
- * `base...head` (three dots) rather than `base..head`, and the difference is the
- * whole point: two dots diffs the two tips, so every file changed on `base`
- * since the branch point appears in the result as though the PR had touched it.
- * On a branch a week behind `main` that is most of the diff, and the blast
- * radius it produces belongs to somebody else's change. Three dots diffs against
- * the merge base, which is what a reviewer is actually looking at.
- *
- * Deletions are included. A deleted file's nodes may still be in the graph, and
- * *what called the thing you just removed* is the most useful question a diff
- * can be asked.
- */
+/** Files changed between two refs, for PR analysis. `base...head` (three
+ *  dots, not two) diffs against the merge base — two dots would include every
+ *  file changed on base since the branch point, someone else's change. Deletions included: what called the removed thing is the useful question. */
 export async function changedFiles(cwd, base, head = "HEAD") {
     const { stdout } = await run("git", ["diff", "--name-only", "-M", `${base}...${head}`], {
         cwd,
@@ -311,4 +276,68 @@ export async function filesInCommit(cwd, sha) {
         .map((l) => l.trim())
         .filter((l) => l !== "");
 }
+/**
+ * Which of these paths git reports as uncommitted — modified, staged or untracked.
+ *
+ * One `git status --porcelain` over the named paths rather than a call per
+ * file. `--porcelain` is the stable machine format, guaranteed across versions,
+ * and its two status columns cover every state that matters here at once: a
+ * file the index has and `HEAD` does not, one the working tree has and the
+ * index does not, and one git has never seen.
+ *
+ * The distinction this exists to make is not cosmetic. A path absent from a
+ * ref-to-ref diff might be uncommitted work, or it might be a file the caller
+ * named that this branch simply did not touch. Both make a coverage section
+ * describe something else; only the first is a fact about timing that the
+ * developer can act on in the next thirty seconds.
+ */
+export async function uncommittedAmong(cwd, paths) {
+    if (paths.length === 0)
+        return [];
+    const { stdout } = await run("git", ["status", "--porcelain", "--untracked-files=all", "--", ...paths], { cwd, maxBuffer: 64 * 1024 * 1024 });
+    const named = new Set(paths);
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        // `XY <path>`, and for a rename `XY <old> -> <new>`. The path starts at
+        // column 3; a rename's new name is what the working tree has.
+        if (line.length < 4)
+            continue;
+        const rest = line.slice(3).trim();
+        const path = rest.includes(" -> ") ? rest.slice(rest.indexOf(" -> ") + 4) : rest;
+        const unquoted = path.startsWith('"') && path.endsWith('"') ? path.slice(1, -1) : path;
+        if (named.has(unquoted))
+            out.push(unquoted);
+    }
+    return out.sort();
+}
+/**
+ * The paths a working tree changes, as {@link changedFiles} does for a range.
+ *
+ * Name-only, so it is the cheap counterpart to `gitWorkingTreeChange`: a caller
+ * that only needs to know *which* files changed should not pay for every patch.
+ *
+ * **Untracked is on by default here**, unlike the diff-producing function. That
+ * one is a library primitive whose existing callers must not change behaviour
+ * by upgrading. This one exists to answer "what is the change about to be
+ * committed", and a new file written and not yet added is part of that change —
+ * defaulting it off would mean the function misses, by default, the case it was
+ * written for.
+ */
+export async function workingTreeChangedFiles(cwd, options = {}) {
+    const scope = options.scope ?? "all";
+    const revisionArgs = scope === "staged" ? ["--cached"] : scope === "all" ? ["HEAD"] : [];
+    const read = async (args) => {
+        const { stdout } = await run("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+        return stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line !== "");
+    };
+    const tracked = await read(["diff", "--name-only", "-M", ...revisionArgs]);
+    const untracked = options.includeUntracked === false
+        ? []
+        : await read(["ls-files", "--others", "--exclude-standard"]);
+    const excluded = (path) => (options.exclude ?? []).some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+    return [...new Set([...tracked, ...untracked])].filter((p) => !excluded(p)).sort();
+}
 //# sourceMappingURL=history.js.map