ts-axi 0.1.10 → 0.1.11

package/README.md

@@ -86,7 +86,7 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | `config` | Show effective settings with their source; `config set <key> <value>` and `config unset <key>` write `.ts-axi.json` |
 | `setup <hooks\|status\|uninstall>` | Opt-in SessionStart hook for Claude Code, Codex and OpenCode that runs the home view at session start. `--project` for the current repository only |
 
-`ts-axi <command> --help` prints a concise, complete flag reference. `-P <tsconfig>` selects a project on any command that may analyse types; `--json` prints the decoded payload.
+`ts-axi <command> --help` prints a concise, complete flag reference. `-P <tsconfig>` selects a project on any command that may analyse types; `--ref <rev>` answers `def`, `refs`, `callers` and `outline` at a git revision ([below](#reading-another-revision---ref)); `--json` prints the decoded payload.
 
 ### A review, end to end
 
@@ -196,6 +196,31 @@ scope: nx workspace - 30 of 5433 files (seeds 1; importers 29)
 
 Files are listed with `git ls-files` (tracked plus untracked, gitignore applied), so nested worktrees and ignored copies are never analysed. Outside git, a directory walk skips `node_modules`, build output, `.claude`, `.cursor`, `.idea`, `.vscode` and any nested checkout.
 
+## Reading another revision (`--ref`)
+
+`def`, `refs`, `callers` and `outline` take `--ref <rev>` (a branch, tag, `origin/main`, `HEAD~3`, a SHA) and answer from that commit's tree, read straight from git objects. Nothing is checked out, written or fetched, and the working tree has no effect on the answer: a triage agent can ask about the deployed code while the checkout is on another branch or dirty.
+
+```sh
+ts-axi callers Cart.total --ref origin/main
+```
+
+```
+ref: origin/main @ 5474e0f
+symbol: Cart.total
+...
+help[1]:
+  - Run `ts-axi refs src/lib/cart.ts:32 --ref origin/main` for every Reference (not only calls)
+```
+
+- The rev is resolved once to a SHA (`ref: <rev> @ <sha>`), so a `git fetch` during the run cannot mix versions. Paths in the output look as they do without `--ref`, and every follow-up hint keeps `--ref`.
+- A file that is not in the revision is absent even if it exists locally, and a file deleted locally is still there: `file not in origin/main: src/new.ts`.
+- `node_modules` is not in git, so dependency types come from the working tree; the output says `node_modules: working tree (not in git)` when it read any.
+- A partial clone never fetches: a blob that is not available locally is a `GIT_ERROR` (`git fetch` or a full clone fixes it). Fetch the ref yourself first if it may be stale.
+- `.ts-axi.json` is read from the working tree, like `--test-glob`.
+- `impact` already compares git revisions (`ts-axi impact origin/main...HEAD`) and rejects `--ref`, as do `config` and `setup`.
+
+Cost: the tree listing and one batched blob read add about 0.1 s on a small repo and 0.1-0.3 s on a ~5k-file Nx monorepo.
+
 ## Test files
 
 A file counts as a test by path pattern. Defaults: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/e2e/**`, `**/spec/**`, `**/test.*`, `**/*_test.*`. The home view shows `test_globs` and `test_files` so a wrong rule is visible.
@@ -236,7 +261,7 @@ corepack pnpm install
 corepack pnpm run check   # typecheck, tests, build, skill freshness
 ```
 
-`skills/ts-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec, `GLOSSARY.md` for the vocabulary and `docs/adr/` for the two engine decisions (TypeScript LanguageService over ts-morph / tree-sitter; importer subgraph over a configured project list).
+`skills/ts-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec, `GLOSSARY.md` for the vocabulary and `docs/adr/` for the design decisions (TypeScript LanguageService over ts-morph / tree-sitter; importer subgraph over a configured project list; `--ref` over git objects instead of a worktree).
 
 ### Tests
 
@@ -244,6 +269,7 @@ corepack pnpm run check   # typecheck, tests, build, skill freshness
 | --- | --- | --- |
 | `test/unit.test.ts`, `test/workspace.test.ts` | `pnpm test` | target parsing, signatures, change classification, diff parsing, settings, glob matching, reference classification, workspace detection, import resolution |
 | `test/commands.test.ts` | `pnpm test` | the whole CLI through `main()` over five fixtures copied to temp git repos: `test/fixtures/project` (TS, interface + implementations, barrel, JS consumer, `any` access), `test/fixtures/workspace` (Nx + pnpm workspace, `paths`, references-only tsconfigs), `test/fixtures/legacy-js` (AngularJS, Meteor, prototype, IIFE, CommonJS), `test/fixtures/commonjs` (`require('..')` shim, expando methods, `.d.ts` twin), `test/fixtures/esm-js` (`"type": "module"`, `index.js` + `index.d.ts`) |
+| `test/ref.test.ts`, `test/ref-leak.test.ts`, `test/gittree.test.ts` | `pnpm test` | `--ref`: answers on a poisoned working tree equal a clean checkout (four fixtures), no read below the repo root bypasses the git tree (`node:fs` and `ts.sys` spied), tree listing, blob batches, symlinks, submodules, bad revisions |
 | `test/integration/*.test.ts` | `pnpm run test:integration` | the built binary against the vendored Astro + React sample in `test/integration/sample` (installs its own dependencies once; copied to a temp git repo per run, see `test/integration/README.md`) |
 
 CI runs the first two on Node 22 and 24, the built CLI on Node 20, and the integration suite on Node 24.

package/dist/src/args.js

@@ -19,6 +19,14 @@ const POSITIONAL = {
     "--symbol": "pass the symbol as a positional argument",
     "--name": "pass the symbol as a positional argument",
 };
+/** Commands that take `--ref <rev>`. */
+export const REF_COMMANDS = ["def", "refs", "callers", "outline"];
+function refHint(command, rev) {
+    const value = rev && !rev.startsWith("-") ? rev : "<ref>";
+    if (command === "ts-axi impact")
+        return `Run \`ts-axi impact ${value}...HEAD\` - impact takes git revisions as its range`;
+    return `--ref works with ${REF_COMMANDS.join(", ")} only`;
+}
 /**
  * Strict declarative parser: every flag must be declared, unknown flags fail
  * loud with the valid set inline (AXI principle 6). Supports `--flag value`,
@@ -38,8 +46,11 @@ export function parseArgs(args, specs, command) {
         positionals: [],
     };
     const unknown = [];
+    let refValue;
     for (let i = 0; i < args.length; i++) {
         const token = args[i];
+        if (token === "--ref" || token.startsWith("--ref="))
+            refValue = token.startsWith("--ref=") ? token.slice(6) : args[i + 1];
         if (token === "--") {
             parsed.positionals.push(...args.slice(i + 1));
             break;
@@ -98,7 +109,9 @@ export function parseArgs(args, specs, command) {
         const positional = unknown
             .filter((flag) => POSITIONAL[flag])
             .map((flag) => `${flag} is not supported; ${POSITIONAL[flag]}`);
+        const ref = unknown.includes("--ref") ? [refHint(command, refValue)] : [];
         throw usageError(`unknown flag${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} for \`${command}\``, [
+            ...ref,
             ...renamed,
             ...positional,
             `valid flags for \`${command}\`: ${valid} (--help always allowed)`,

package/dist/src/cli.js

@@ -7,7 +7,9 @@ import { outlineCommand, OUTLINE_HELP } from "./commands/outline.js";
 import { callersCommand, CALLERS_HELP, refsCommand, REFS_HELP } from "./commands/refs.js";
 import { setupCommand, SETUP_HELP } from "./commands/setup.js";
 import { AxiError, exitCodeForError } from "./errors.js";
-import { renderErrorOutput, setJsonMode, toJson } from "./render.js";
+import { refHeader } from "./commands/common.js";
+import { diskFs, setSourceFs } from "./fs.js";
+import { out, renderErrorOutput, setHintRef, setJsonMode, toJson } from "./render.js";
 import { VERSION } from "./version.js";
 export const DESCRIPTION = "TypeScript/JavaScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (what a diff affects) from the TypeScript compiler. Prefer it over grep for 'who uses this'.";
 export const TOP_HELP = `usage: ts-axi [command] [args] [flags]
@@ -15,13 +17,14 @@ commands[8]:
   (none)=project overview, def, refs, callers, outline, impact, config, setup (opt-in session hooks)
 targets:
   name (save), member (User.save) or position (src/a.ts:42 or src/a.ts:42:7)
-flags[4]:
-  -P <tsconfig> (after the command; default nearest tsconfig.json), --json (anywhere), --help, -v/-V/--version
+flags[5]:
+  -P <tsconfig> (after the command; default nearest tsconfig.json), --ref <rev> (def/refs/callers/outline; read a git revision instead of the working tree), --json (anywhere), --help, -v/-V/--version
 examples:
   ts-axi
   ts-axi def User.save
   ts-axi refs src/models/user.ts:12
   ts-axi callers runSync --depth 2
+  ts-axi refs User.save --ref origin/main
   ts-axi outline src/models/user.ts
   ts-axi impact main...HEAD
   ts-axi refs --help
@@ -36,7 +39,13 @@ const COMMAND_HELP = {
     setup: SETUP_HELP,
 };
 function command(name, handler, ctx) {
-    return async (args) => (args.includes("-h") ? (COMMAND_HELP[name] ?? "").trimEnd() : handler(args, ctx));
+    return async (args) => {
+        if (args.includes("-h"))
+            return (COMMAND_HELP[name] ?? "").trimEnd();
+        const result = await handler(args, ctx);
+        // After the handler: the node_modules note depends on what it read.
+        return out(refHeader(), result);
+    };
 }
 function formatError(error) {
     const axi = error instanceof AxiError
@@ -84,6 +93,8 @@ export async function main(options = {}) {
     }
     finally {
         setJsonMode(false);
+        setSourceFs(diskFs);
+        setHintRef(undefined);
     }
     if (!json)
         return;

package/dist/src/commands/common.js

@@ -1,6 +1,6 @@
-// Plumbing shared by def / refs / callers / outline: flags, project opening,
-// target resolution and code rendering.
-import { existsSync } from "node:fs";
+import { setSourceFs, sourceFs } from "../fs.js";
+import { openGitTree } from "../gittree.js";
+import { block, setHintRef } from "../render.js";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import ts from "typescript";
 import { enumFlag, flag, flags, bool } from "../args.js";
@@ -18,7 +18,28 @@ export const TARGET_FLAGS = [
     { name: "--exported", boolean: true },
     { name: "--fuzzy", boolean: true },
     { name: "-P" },
+    { name: "--ref" },
 ];
+/**
+ * `--ref <rev>`: read the repo from that commit's git tree for the rest of the run. Returns the
+ * context with the cwd mapped into the tree (no disk realpath of the working tree).
+ */
+export function useRef(ctx, parsed) {
+    const rev = flag(parsed, "--ref");
+    if (rev === undefined)
+        return ctx;
+    const fs = openGitTree(ctx.cwd, rev);
+    setSourceFs(fs);
+    setHintRef(rev);
+    return { ...ctx, cwd: fs.ref.cwd };
+}
+/** The header block of a `--ref` run: `ref: <rev> @ <short sha>`, plus where node_modules came from. */
+export function refHeader() {
+    const ref = sourceFs().ref;
+    if (!ref)
+        return undefined;
+    return block({ ref: `${ref.rev} @ ${ref.sha.slice(0, 7)}`, ...(ref.nodeModulesRead ? { node_modules: "working tree (not in git)" } : {}) });
+}
 export function readFilters(parsed, extraKinds = []) {
     const raw = flag(parsed, "--kind");
     const kind = raw === undefined ? undefined : enumFlag(parsed, "--kind", [...KINDS, ...extraKinds], KINDS[0]);
@@ -180,8 +201,9 @@ function filterSuffixOf(label, target) {
 }
 export function resolvePositionFile(cwd, file) {
     const abs = resolve(cwd, file);
-    if (!existsSync(abs)) {
-        throw usageError(`file not found: ${file}`, ["paths are relative to the current directory"]);
+    if (!sourceFs().exists(abs)) {
+        const ref = sourceFs().ref;
+        throw usageError(ref ? `file not in ${ref.rev}: ${file}` : `file not found: ${file}`, ["paths are relative to the current directory"]);
     }
     return abs;
 }

package/dist/src/commands/def.js

@@ -2,10 +2,10 @@ import { bool, expectPositionals, flag, parseArgs } from "../args.js";
 import { semanticFor } from "../scope.js";
 import { block, fenced, helpBlock, out } from "../render.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
-import { BODY_LINES, declarationAt, filterSuffix, MATCH_ROWS, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, } from "./common.js";
+import { BODY_LINES, declarationAt, filterSuffix, MATCH_ROWS, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, useRef, } from "./common.js";
 export const DEF_HELP = `usage: ts-axi def <name | Class.member | path:line[:col]> [flags]
-flags[7]:
-  --kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state>, --in <dir|glob> (repeatable; restrict to files), --exported, --fuzzy (substring, case-insensitive), --full (whole body; default first ${BODY_LINES} lines), -P <tsconfig>, --json
+flags[8]:
+  --kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state>, --in <dir|glob> (repeatable; restrict to files), --exported, --fuzzy (substring, case-insensitive), --full (whole body; default first ${BODY_LINES} lines), -P <tsconfig>, --ref <rev> (read the code at a git revision; working tree ignored), --json
 output:
   1 match = file, line, kind, exported, signature + body fenced with file line numbers
   several = matches[n]{at,kind,signature} (at = path:line) (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
@@ -49,6 +49,7 @@ export async function defCommand(args, ctx) {
     const target = parseTarget(raw, { fuzzy: f.fuzzy });
     const full = bool(parsed, "--full");
     const project = flag(parsed, "-P");
+    ctx = useRef(ctx, parsed);
     const opened = open(ctx.cwd, parsed, positionStartDir(ctx.cwd, target));
     const label = targetLabel(target);
     if (target.kind === "position") {

package/dist/src/commands/home.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { sourceFs } from "../fs.js";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { expectPositionals, flag, flags, parseArgs } from "../args.js";
 import { AxiError, usageError } from "../errors.js";
@@ -18,20 +18,14 @@ const HOME_SPECS = [
 ];
 /** Does `dir` hold a TS/JS source within `depth` levels (shared skip rule)? */
 function hasSources(dir, depth, root = dir) {
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return false;
-    }
+    const entries = sourceFs().readdir(dir);
     for (const entry of entries) {
-        if (entry.isFile() && SOURCE_EXT.test(entry.name))
+        if (entry.isFile && SOURCE_EXT.test(entry.name))
             return true;
     }
     if (depth === 0)
         return false;
-    return entries.some((e) => e.isDirectory() && !skipDir(e.name, join(dir, e.name), root) && hasSources(join(dir, e.name), depth - 1, root));
+    return entries.some((e) => e.isDirectory && !skipDir(e.name, join(dir, e.name), root) && hasSources(join(dir, e.name), depth - 1, root));
 }
 /** Implicit project: every source below `root` from the shared listing (git, else a bounded fs walk). */
 function walkSources(root) {
@@ -41,7 +35,7 @@ function findTsconfig(cwd) {
     let dir = cwd;
     for (;;) {
         const candidate = join(dir, "tsconfig.json");
-        if (existsSync(candidate))
+        if (sourceFs().exists(candidate))
             return candidate;
         const parent = dirname(dir);
         if (parent === dir)
@@ -79,7 +73,7 @@ function resolveTsconfig(cwd, settings) {
         // -P is relative to cwd, the .ts-axi.json value to the repo root.
         const base = settings.sources.project === "flag" ? cwd : settings.root;
         const path = resolve(base, settings.project);
-        if (!existsSync(path) || !statSync(path).isFile()) {
+        if (!sourceFs().isFile(path)) {
             throw usageError(`tsconfig not found: ${settings.project}`, [
                 settings.sources.project === "flag"
                     ? "Pass an existing file to -P"

package/dist/src/commands/impact.js

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { sourceFs } from "../fs.js";
 import { basename, dirname, join, relative, sep } from "node:path";
 import ts from "typescript";
 import { bool, flag, intFlag, parseArgs, parseFields } from "../args.js";
@@ -69,6 +70,7 @@ async function readStdin() {
         chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
     return Buffer.concat(chunks).toString("utf8");
 }
+// Always the working tree: it is the "after" side of the diff (impact rejects --ref).
 function readText(abs) {
     try {
         return readFileSync(abs, "utf8");
@@ -243,6 +245,7 @@ export function textualMatches(opened, semantic, names, known, skipLines, change
     const files = [...semantic.projectFiles];
     const projectSet = new Set(files);
     walkExtra(opened.root, files);
+    sourceFs().prefetch(files);
     const rows = [];
     for (const abs of files) {
         const text = opened.index.text(abs);
@@ -311,6 +314,7 @@ export function textualCount(opened, needle, changeSet = new Map(), onlyFile) {
     const candidates = onlyFile !== undefined ? [onlyFile] : [...project];
     if (token && onlyFile === undefined)
         walkExtra(opened.root, candidates);
+    sourceFs().prefetch(candidates);
     for (const abs of new Set(candidates)) {
         const text = opened.index.text(abs);
         if (text === undefined || !text.includes(name))
@@ -432,7 +436,7 @@ function specFilesHint(cwd, opened, skipped, noTests) {
     const dir = dirname(tsconfig);
     const name = basename(tsconfig);
     const order = name === "tsconfig.lib.json" || name === "tsconfig.app.json" ? ["tsconfig.json", "tsconfig.spec.json"] : ["tsconfig.spec.json", "tsconfig.json"];
-    const candidates = order.map((n) => join(dir, n)).filter((c) => c !== tsconfig && existsSync(c));
+    const candidates = order.map((n) => join(dir, n)).filter((c) => c !== tsconfig && sourceFs().exists(c));
     // Prefer the one that really includes a skipped spec file (an Nx tsconfig.json may only hold references).
     const includes = (c) => {
         try {

package/dist/src/commands/outline.js

@@ -1,14 +1,15 @@
-import { existsSync, statSync } from "node:fs";
+import { sourceFs } from "../fs.js";
 import { posix, relative, resolve, sep } from "node:path";
 import { bool, flag, parseArgs, parseFields } from "../args.js";
 import { usageError } from "../errors.js";
 import { hasGlobMagic, matchesGlob } from "../glob.js";
 import { createSyntacticIndex, findRepoRoot, openProject, SOURCE_EXTENSIONS } from "../project.js";
 import { block, helpBlock, out } from "../render.js";
+import { useRef } from "./common.js";
 const MAX_ROWS = 300;
 export const OUTLINE_HELP = `usage: ts-axi outline <file | glob>... [flags]
-flags[4]:
-  --exported (alias --exports; exported Declarations only), --fields exported (adds an exported column), -P <tsconfig> (file list for globs), --json
+flags[5]:
+  --exported (alias --exports; exported Declarations only), --fields exported (adds an exported column), -P <tsconfig> (file list for globs), --ref <rev> (the file at a git revision), --json
 output:
   one file = file + decls[n]{line,kind,name,signature}; several = decls[n]{at,kind,name,signature} (at = path:line); --exported keeps only exported Declarations, --fields exported adds the column
   class members follow their class as Class.member; at most ${MAX_ROWS} rows
@@ -27,6 +28,7 @@ export async function outlineCommand(args, ctx) {
         { name: "--exported", alias: "--exports", boolean: true },
         { name: "--fields" },
         { name: "-P" },
+        { name: "--ref" },
     ], COMMAND);
     if (parsed.positionals.length === 0) {
         throw usageError("missing argument", [`usage: ${COMMAND} <file | glob>... [--exported]`]);
@@ -34,14 +36,16 @@ export async function outlineCommand(args, ctx) {
     const exportedOnly = bool(parsed, "--exported");
     const showExported = parseFields(flag(parsed, "--fields"), ["exported"]).length > 0;
     const override = flag(parsed, "-P");
+    ctx = useRef(ctx, parsed);
     const root = findRepoRoot(ctx.cwd);
     const cwdPrefix = relative(root, resolve(ctx.cwd)).split(sep).join("/");
     const files = [];
     const globs = parsed.positionals.filter(hasGlobMagic);
     for (const raw of parsed.positionals.filter((p) => !hasGlobMagic(p))) {
         const abs = resolve(ctx.cwd, raw);
-        if (!existsSync(abs) || !statSync(abs).isFile()) {
-            throw usageError(`file not found: ${raw}`, ["pass a source file or a quoted glob such as \"src/**/*.ts\""]);
+        if (!sourceFs().isFile(abs)) {
+            const ref = sourceFs().ref;
+            throw usageError(ref ? `file not in ${ref.rev}: ${raw}` : `file not found: ${raw}`, ["pass a source file or a quoted glob such as \"src/**/*.ts\""]);
         }
         if (!isSource(abs))
             throw usageError(`not a TypeScript/JavaScript source file: ${raw}`);

package/dist/src/commands/refs.js

@@ -11,11 +11,11 @@ import { byDepthThenPath } from "../walk.js";
 import { detectWorkspace, isMultiProject } from "../workspace.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
-import { contextOf, declarationAt, filterSuffix, lineOf, MATCH_ROWS, matchRows, narrowHints, open, positionStartDir, projectFields, readFilters, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
+import { contextOf, declarationAt, filterSuffix, lineOf, MATCH_ROWS, matchRows, narrowHints, open, positionStartDir, projectFields, readFilters, useRef, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const DEPTH_ROWS = 50;
-const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --json`;
+const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --ref <rev> (read the code at a git revision; working tree ignored), --json`;
 const VIA_DOC = `via_interface: n (Iface.member) = References through an interface or base member the Symbol implements or overrides - they MAY reach it; not in refs_total
   via_implementations: n (Impl.member) = References to implementations or overrides of the Symbol; not in refs_total
   implementations: n = members that implement or override the Symbol (their Declarations are never refs)
@@ -26,7 +26,7 @@ const VIA_DOC = `via_interface: n (Iface.member) = References through an interfa
   textual: n matches in m files = whole-word count of the name in Project files (JavaScript declarations and implicit projects; a state counts its full dotted name as a whole token, templates included; not for a state's resolve keys and hooks - injected by name, not imported); 'n matches in this file' for a non-exported local; above refs_total = uses the checker cannot resolve - see refs --grep
   templates: n usages in m files = template uses (.html .htm .ejs .hbs .njk .pug) of a directive or component (<wap-select / wap-select / data-wap-select), its bindings (fallback-display-property= on that tag), a controller (ng-controller) or a filter (| money); refs --grep lists them in unresolved`;
 export const REFS_HELP = `usage: ts-axi refs <name | Class.member | path:line[:col]> [flags]
-flags[12]:
+flags[13]:
   ${SHARED_FLAGS}
   --implementations (lists implementations[n]{file,line,symbol} instead of the count)
   --grep (adds unresolved[n]{file,line,context} - textual matches of the name that are not References; also searches .astro/.vue/.svelte/.mdx/.html)
@@ -43,7 +43,7 @@ examples[4]:
   ts-axi refs runSync --limit 200
 `;
 export const CALLERS_HELP = `usage: ts-axi callers <name | Class.member | path:line[:col]> [flags]
-flags[11]:
+flags[12]:
   ${SHARED_FLAGS}
   --depth <1-3> (default 1; levels > 1 print callers_depthN[n]{caller,file,count}, no locations)
 output:
@@ -86,6 +86,7 @@ async function run(args, ctx, invoked) {
         grep: invoked === "refs" && bool(parsed, "--grep"),
     };
     const started = performance.now();
+    ctx = useRef(ctx, parsed);
     const opened = open(ctx.cwd, parsed, positionStartDir(ctx.cwd, target));
     const warning = opened.warning ? { warning: opened.warning } : {};
     // Resolve to exactly one Symbol before building a program.

package/dist/src/fs.js

@@ -0,0 +1,68 @@
+// The file-system seam: every read of repo content goes through `sourceFs()`. `diskFs` is the
+// working tree; `--ref` swaps in a git-tree view (src/gittree.ts). Node builtins only.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const diskFs = {
+    exists: (abs) => existsSync(abs),
+    isFile(abs) {
+        try {
+            return statSync(abs).isFile();
+        }
+        catch {
+            return false;
+        }
+    },
+    isDirectory(abs) {
+        try {
+            return statSync(abs).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    readFile(abs) {
+        try {
+            return readFileSync(abs, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    },
+    readdir(abs) {
+        try {
+            return readdirSync(abs, { withFileTypes: true }).map((e) => ({ name: e.name, isFile: e.isFile(), isDirectory: e.isDirectory() }));
+        }
+        catch {
+            return [];
+        }
+    },
+    realpath: (abs) => realpathSync(abs),
+    listFiles(root) {
+        if (!existsSync(join(root, ".git")))
+            return undefined;
+        try {
+            const raw = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+                cwd: root,
+                encoding: "utf8",
+                maxBuffer: 512 * 1024 * 1024,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            // A nested repo shows up as one `dir/` entry; deleted-but-tracked files are dropped by the caller's exists check.
+            return [...new Set(raw.split("\0").filter((f) => f !== "" && !f.endsWith("/")))];
+        }
+        catch {
+            return undefined;
+        }
+    },
+    prefetch: () => { },
+};
+// One fs per run, set by the command that parsed `--ref` and reset by `main()`. A module-level
+// value because the reads sit in ~40 free functions (tsconfig chains, workspace detection, TS hosts).
+let active = diskFs;
+export function sourceFs() {
+    return active;
+}
+export function setSourceFs(fs) {
+    active = fs;
+}

package/dist/src/git.js

@@ -7,6 +7,7 @@ const TIMEOUT_MS = 20_000;
 const MAX_BUFFER = 256 * 1024 * 1024;
 /** `git diff` target for a repository with no commits yet. */
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export const REV_HINT = "Run `git branch -a` or `git log --oneline -5` to pick an existing revision";
 /** Run git; resolves with the exit code instead of throwing on non-zero. */
 async function run(cwd, args) {
     try {
@@ -44,7 +45,7 @@ function gitError(result, args) {
         ? ["Run `ts-axi impact -` with a unified diff on stdin instead"]
         : /unknown revision|bad revision|invalid object name|no merge base/i.test(first)
             ? [
-                "Run `git branch -a` or `git log --oneline -5` to pick an existing revision",
+                REV_HINT,
                 "Run `ts-axi impact` for uncommitted changes, or `ts-axi impact <base>...HEAD` for a branch",
             ]
             : [];