ts-axi 0.1.10 → 0.1.12

package/README.md

@@ -78,7 +78,7 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | Command | What it does |
 | --- | --- |
 | `ts-axi` | Home view: project root, tsconfig used (or implicit), source file count, test-file glob and match counts, git branch and dirty count, next steps. Under a second, exit 0 everywhere |
-| `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` |
+| `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` and, when the name still occurs in the code, the `refs <name> --grep` that lists those textual matches |
 | `refs <target>` | References of one symbol, grouped by file, with test counts. A class member that implements an interface (or overrides a base) member counts only its direct References; calls through the interface are `via_interface: n (Iface.member)`, sibling implementations are dropped, and an interface member reports `implementations: n`. `--limit`, `--kind calls`, `--via` (via rows with a `via` column), `--implementations` |
 | `callers <target>` | Incoming calls of a function-like symbol, split the same way (`via_interface`, `--via`). `--depth 1..3` |
 | `outline <file>` | Top-level declarations in source order, class members nested: `{line,kind,name,signature}` (`{at,kind,name,signature}` over several files). `--exports`, `--fields exported` |
@@ -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
 
@@ -180,7 +180,7 @@ decls[4]{line,kind,name,exported,signature}:
   17,function,cartBadge,true,directive cartBadge()
 ```
 
-An edit inside `CartCtrl` is reported by `impact` as `CartCtrl body`, not as a file-level change. Names registered by a string have no identifier the checker can follow; `refs` says so and offers `--grep`. ui-router and ngRoute states are Declarations of kind `state` (`states.cart`, with callbacks as `states.cart.resolve.items`), so an edit inside a `resolve` names that callback; state objects in exported arrays (`` module.exports = [{ name: `${base}.init`, url, resolve }] ``) count too, their template-literal names filled from same-file consts. Directives, components, their `scope`/`bindings` keys, controllers and filters also get `templates: <n> usages in <m> files` (kebab-case elements and attributes, `ng-controller`, `| filter` in `.html`/`.htm`/`.ejs`/`.hbs`/`.njk`/`.pug`), a `templates` column in `impact`, and a changed template that uses a changed directive or binding is listed under `template_changes` instead of `skipped`.
+An edit inside `CartCtrl` is reported by `impact` as `CartCtrl body`, not as a file-level change. Names registered by a string have no identifier the checker can follow; `refs` says so and offers `--grep`. A registration that names a same-file function (`.directive('fancyBox', fancyBox)`, `['$uibModal', fancyBox]`) links the two, so `refs` on the function reports the registration's template usages too. Function-valued members of an object a function returns (`return { canReadItem: async () => ... }`) are Declarations (`makeItemDeps.canReadItem`), so `def canReadItem` finds them; their `textual:` count covers the whole project, while a real local (a parameter, an IIFE helper, a CommonJS binding no `module.exports` hands out) says `in this file`. ui-router and ngRoute states are Declarations of kind `state` (`states.cart`, with callbacks as `states.cart.resolve.items`), so an edit inside a `resolve` names that callback; state objects in exported arrays (`` module.exports = [{ name: `${base}.init`, url, resolve }] ``) count too, their template-literal names filled from same-file consts. Directives, components, their `scope`/`bindings` keys, controllers and filters also get `templates: <n> usages in <m> files` (kebab-case elements and attributes, `ng-controller`, `| filter` in `.html`/`.htm`/`.ejs`/`.hbs`/`.njk`/`.pug`), a `templates` column in `impact`, and a changed template that uses a changed directive or binding is listed under `template_changes` instead of `skipped`.
 
 ## Monorepos
 
@@ -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;
 }
@@ -195,9 +217,27 @@ function identifiers(node, sf, outIds) {
     }
     ts.forEachChild(node, (child) => identifiers(child, sf, outIds));
 }
+function isFunctionValue(expr) {
+    let e = expr;
+    while (ts.isParenthesizedExpression(e))
+        e = e.expression;
+    return ts.isArrowFunction(e) || ts.isFunctionExpression(e);
+}
+/** Declares a name: a Declaration kind, a parameter, a binding element, or a function-valued property. */
 function isDeclarationName(id) {
     const parent = id.parent;
-    return parent !== undefined && parent.name === id && (kindOf(parent) !== undefined || ts.isParameter(parent) || ts.isBindingElement(parent));
+    if (parent === undefined || parent.name !== id)
+        return false;
+    if (ts.isPropertyAssignment(parent))
+        return isFunctionValue(parent.initializer);
+    return kindOf(parent) !== undefined || ts.isParameter(parent) || ts.isBindingElement(parent);
+}
+/** The node a declaration name owns, for nesting: `this.x = fn` → the whole assignment. */
+function declarationNode(id) {
+    const parent = id.parent;
+    if (ts.isPropertyAccessExpression(parent) && parent.name === id && ts.isBinaryExpression(parent.parent) && parent.parent.left === parent)
+        return parent.parent;
+    return parent;
 }
 /** The identifier a `path:line[:col]` target points at (see PLAN.md Targets). */
 export function resolvePosition(index, cwd, target) {
@@ -230,33 +270,41 @@ export function resolvePosition(index, cwd, target) {
         return hit ? pick(hit) : { kind: "none", abs, file, reason: `no identifier at ${file}:${target.line}:${target.col}` };
     }
     // A string-registered name has no identifier: its line stands for it.
-    const nameless = decls.find((d) => d.nameless && d.nameLine === target.line);
+    // The registration line too: `.directive('x', fancyBox)` has its name far from the function.
+    const nameless = decls.find((d) => d.nameless && d.nameLine === target.line) ?? decls.find((d) => d.nameless && d.line === target.line);
     if (nameless)
         return { kind: "decl", decl: nameless, abs };
     if (onLine.length === 0)
         return { kind: "none", abs, file, reason: `no identifier on ${file}:${target.line}` };
+    const ambiguous = (ids) => {
+        const distinct = new Map();
+        for (const id of ids)
+            if (!distinct.has(id.text))
+                distinct.set(id.text, id);
+        if (distinct.size === 1)
+            return pick(ids[0]);
+        return {
+            kind: "ambiguous",
+            abs,
+            file,
+            candidates: [...distinct.values()].map((id) => ({ name: id.text, line: target.line, col: id.getStart(sf) - lineStart + 1 })),
+        };
+    };
     const constructorDecl = decls.find((d) => d.nameLine === target.line && d.name === "constructor");
-    const declared = onLine.find((id) => declFor(id)) ?? onLine.find(isDeclarationName);
-    if (declared)
-        return pick(declared);
+    // The declaration that starts the line: names nested in another one's declaration (its parameters, its members) rank after it.
+    const declaring = onLine.filter((id) => declFor(id) !== undefined || isDeclarationName(id));
+    const owned = (inner, outer) => {
+        const node = declarationNode(outer);
+        const at = inner.getStart(sf);
+        return node !== declarationNode(inner) && node.getStart(sf) <= at && at < node.end;
+    };
+    const outer = declaring.filter((id) => !(constructorDecl && ts.isParameter(id.parent) && ts.isConstructorDeclaration(id.parent.parent)) &&
+        !declaring.some((other) => other !== id && owned(id, other)));
+    if (outer.length > 0)
+        return ambiguous(outer);
     if (constructorDecl)
         return { kind: "decl", decl: constructorDecl, abs };
-    const distinct = new Map();
-    for (const id of onLine)
-        if (!distinct.has(id.text))
-            distinct.set(id.text, id);
-    if (distinct.size === 1)
-        return pick(onLine[0]);
-    return {
-        kind: "ambiguous",
-        abs,
-        file,
-        candidates: [...distinct.values()].map((id) => ({
-            name: id.text,
-            line: target.line,
-            col: id.getStart(sf) - lineStart + 1,
-        })),
-    };
+    return ambiguous(onLine);
 }
 /** A Declaration for an arbitrary declaration name position (locals, parameters) not in the index. */
 export function declarationAt(index, abs, pos, fallbackKind) {

package/dist/src/commands/def.js

@@ -1,15 +1,16 @@
 import { bool, expectPositionals, flag, parseArgs } from "../args.js";
 import { semanticFor } from "../scope.js";
+import { textualScan, textualScanHint } from "./impact.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
-  none = matches: 0 + did_you_mean
+  none = matches: 0 + did_you_mean; when the name still occurs in Project files, help gives the refs --grep that lists those textual matches
 examples[5]:
   ts-axi def User
   ts-axi def User.save
@@ -49,6 +50,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") {
@@ -77,7 +79,8 @@ export async function defCommand(args, ctx) {
         return detail(opened, groups[0].decls, full, label);
     if (groups.length === 0) {
         const suggested = suggestions(opened, target);
-        const help = suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``);
+        const text = f.fuzzy ? 0 : textualScan(opened, target.member ?? target.name).length;
+        const help = [...(text > 0 ? [textualScanHint(label, text)] : []), ...suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``)];
         if (!f.fuzzy)
             help.push(`Run \`ts-axi def ${label} --fuzzy\` for substring matches`);
         if (f.kind || f.in.length > 0 || f.exported)

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);
@@ -267,6 +270,27 @@ export function textualMatches(opened, semantic, names, known, skipLines, change
     }
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
 }
+/** Whole-word matches of `name` in the Project files, one row per line: the fallback when no Declaration matches. */
+export function textualScan(opened, name) {
+    const rows = [];
+    sourceFs().prefetch(opened.index.files);
+    for (const abs of opened.index.files) {
+        const text = opened.index.text(abs);
+        if (text === undefined || !text.includes(name))
+            continue;
+        let last = 0;
+        for (const m of wordMatches(text, name)) {
+            if (m.line === last)
+                continue;
+            last = m.line;
+            rows.push({ file: opened.index.rel(abs), line: m.line, context: contextOf(lineOf(text, m.line), m.col) });
+        }
+    }
+    return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+export function textualScanHint(label, matches) {
+    return `Run \`ts-axi refs ${label} --grep\` for ${matches} textual matches`;
+}
 /** Whether a whole-word count of the name says anything: not for router-called or by-name-injected members (`injected`). */
 export function isTextualCandidate(decl) {
     return decl?.injected !== true;
@@ -294,9 +318,66 @@ export function isUntyped(opened, decl, file) {
         return false;
     return decl?.nameless === true || opened.index.project.implicit || (file !== undefined && /\.[mc]?jsx?$/.test(file));
 }
-/** A non-exported, non-member, identifier-named Declaration: only its own file can name it. */
-export function isPlainLocal(decl) {
-    return decl !== undefined && !decl.exported && !decl.nameless && decl.parentName === undefined;
+/** The identifier starting at `pos`. */
+function identifierAt(node, pos, sf) {
+    if (ts.isIdentifier(node) && node.getStart(sf) === pos)
+        return node;
+    return ts.forEachChild(node, (child) => (child.pos <= pos && pos < child.end ? identifierAt(child, pos, sf) : undefined));
+}
+/** Names a CommonJS file hands out (`module.exports = { a, b: c }`, `exports.x = d`); undefined when not CommonJS. */
+function commonJsExports(sf) {
+    const names = new Set();
+    let cjs = /\brequire\s*\(/.test(sf.text);
+    // Values only: identifiers used inside exported function bodies do not leave the file.
+    const collect = (expr) => {
+        let e = expr;
+        while (ts.isParenthesizedExpression(e))
+            e = e.expression;
+        if (ts.isIdentifier(e))
+            names.add(e.text);
+        else if (ts.isObjectLiteralExpression(e)) {
+            for (const p of e.properties) {
+                if (ts.isShorthandPropertyAssignment(p))
+                    names.add(p.name.text);
+                else if (ts.isPropertyAssignment(p))
+                    collect(p.initializer);
+                else if (ts.isSpreadAssignment(p))
+                    collect(p.expression);
+            }
+        }
+    };
+    for (const st of sf.statements) {
+        if (!ts.isExpressionStatement(st) || !ts.isBinaryExpression(st.expression) || st.expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+            continue;
+        const left = st.expression.left.getText(sf).replace(/\s+/g, "");
+        if (!/^(module\.exports|exports)(\.|$)/.test(left))
+            continue;
+        cjs = true;
+        collect(st.expression.right);
+    }
+    return cjs ? names : undefined;
+}
+/**
+ * A Declaration only its own file can name: a parameter or function-scoped binding, or a non-exported top-level
+ * binding of an ES module, or of a CommonJS file whose exports never mention it. Members, object properties,
+ * string registrations and script globals are not.
+ */
+export function isPlainLocal(index, decl) {
+    if (decl === undefined || decl.exported || decl.nameless || decl.parentName !== undefined)
+        return false;
+    const sf = index.sourceFile(index.abs(decl.file));
+    const id = sf && identifierAt(sf, decl.namePos, sf);
+    if (!sf || !id)
+        return false;
+    const owner = id.parent;
+    if (ts.isPropertyAssignment(owner) || ts.isShorthandPropertyAssignment(owner) || ts.isMethodDeclaration(owner) || ts.isPropertyAccessExpression(owner))
+        return false;
+    for (let n = owner.parent; !ts.isSourceFile(n); n = n.parent)
+        if (ts.isFunctionLike(n))
+            return true;
+    if (ts.isExternalModule(sf))
+        return true;
+    return commonJsExports(sf)?.has(decl.name) === false;
 }
 /**
  * Whole-word occurrences of `name` in Project files outside `changeSet`; lines declaring a `name` excluded.
@@ -311,6 +392,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 +514,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 {
@@ -588,7 +670,7 @@ export async function impactCommand(args, ctx) {
     for (const row of rows) {
         if (!row.live || !isUntyped(opened, row.live, row.live.file))
             continue;
-        const localTo = isPlainLocal(row.live) ? new Map([[row.live.name, opened.index.abs(row.live.file)]]) : undefined;
+        const localTo = isPlainLocal(opened.index, row.live) ? new Map([[row.live.name, opened.index.abs(row.live.file)]]) : undefined;
         const needle = textualNeedle(row.live);
         if (!needle)
             continue;
@@ -663,7 +745,7 @@ export async function impactCommand(args, ctx) {
         if (!textNames.has(needle.text))
             textNames.set(needle.text, needle);
         const abs = opened.index.abs(decl.file);
-        if (!isPlainLocal(decl) || (localTo.has(name) && localTo.get(name) !== abs))
+        if (!isPlainLocal(opened.index, decl) || (localTo.has(name) && localTo.get(name) !== abs))
             wide.add(name);
         else
             localTo.set(name, abs);

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}`);