ts-axi 0.1.9 → 0.1.11

package/README.md

@@ -11,9 +11,9 @@ $ ts-axi impact main...HEAD
 base: 923fb4d7ddc8f4e5c4df9029be388f8cb29ce095
 head: HEAD
 changes: 2
-changed[2]{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}:
-  formatPrice,function,signature,true,"src/lib/format.ts:5",13,12,0,6,2
-  Cart.total,method,body,true,"src/lib/cart.ts:32",8,8,0,5,3
+changed[2]{symbol,change,at,refs_outside}:
+  formatPrice,signature,"src/lib/format.ts:5",12
+  Cart.total,body,"src/lib/cart.ts:32",8
 refs[20]{symbol,file,line,context}:
   formatPrice,src/components/Counter.tsx,2,"import { formatPrice } from '../lib';"
   formatPrice,src/components/Counter.tsx,12,"{cups} cups = {formatPrice(cups * CUP_CENTS)}"
@@ -25,17 +25,18 @@ refs[20]{symbol,file,line,context}:
 blind_spots[1]{symbol,file,line,reason}:
   Cart.total,src/components/CartSummary.tsx,16,string key 'total' on a type without that member
 elapsed_ms: 679
-help[5]:
+help[6]:
   - "Run `ts-axi refs src/lib/format.ts:5` for every Reference of formatPrice"
   - "Run `ts-axi callers src/lib/format.ts:5` for its call sites with the enclosing function"
   - "Run `ts-axi def src/lib/format.ts:5` for the changed declaration"
+  - Run `ts-axi impact main...HEAD --fields files,tests` for how many files and Test files reference each Symbol
   - Run `ts-axi impact main...HEAD --grep` for textual matches the checker cannot see
   - Run `ts-axi impact main...HEAD --depth 2` for who calls the callers
 ```
 
-(`...` marks rows cut from this README; the command prints all 20.)
+(`...` marks rows cut from this README; the command prints all 20. `--fields all` restores the full row: `{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}`.)
 
-Read-only: no lint, no refactor, no rename.
+Read-only on your code: no lint, no refactor, no rename. The only files it writes are `.ts-axi.json` (`config set`) and, when you ask for it, your agents' hook config (`setup hooks`).
 
 ## Status (v0.1.4)
 
@@ -63,12 +64,15 @@ Then tell your agent about it - one line in `CLAUDE.md` / `AGENTS.md`:
 Use `ts-axi` to find definitions, references and callers in TypeScript/JavaScript code, and `ts-axi impact` to see what a diff affects before reviewing it.
 ```
 
-Or install the on-demand Agent Skill (no per-session cost):
+Or install one of the two integrations (you only need one):
 
 ```sh
-npx skills add cmosgh/ts-axi --skill ts-axi
+ts-axi setup hooks                           # SessionStart hook: the project overview as ambient context (Claude Code, Codex, OpenCode)
+npx skills add cmosgh/ts-axi --skill ts-axi  # on-demand Agent Skill, no per-session cost
 ```
 
+The hook runs `ts-axi` with no arguments: it reads only the file tree and git status (no compiler run, no network) and exits 0 in any directory. `ts-axi setup hooks --project` installs it for the current repository only, `ts-axi setup status` shows what is installed, and `ts-axi setup uninstall` removes only ts-axi's own entries.
+
 ## Commands
 
 | Command | What it does |
@@ -77,11 +81,12 @@ npx skills add cmosgh/ts-axi --skill ts-axi
 | `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` |
 | `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. `--exports` |
-| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Analyses the current checkout |
+| `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` |
+| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Rows default to `{symbol,change,at,refs_outside}`; `--fields kind,exported,refs_total,via,files,tests` (or `all`) adds columns. Analyses the current checkout |
 | `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
 
@@ -135,9 +140,9 @@ The line numbers in front of the body are file lines, so an agent can cite or co
 ```
 $ ts-axi def parse
 symbol: parse
-matches[2]{file,line,kind,exported,signature}:
-  src/lib/parse.ts,1,function,true,"export function parse(input: string): number"
-  src/lib/query.ts,1,function,true,"export function parse(q: string): Record<string, string>"
+matches[2]{at,kind,signature}:
+  "src/lib/parse.ts:1",function,"export function parse(input: string): number"
+  "src/lib/query.ts:1",function,"export function parse(q: string): Record<string, string>"
 help[4]:
   - "Run `ts-axi def src/lib/parse.ts:1` for the one in src/lib/parse.ts"
   - "Run `ts-axi def src/lib/query.ts:1` for the one in src/lib/query.ts"
@@ -167,7 +172,7 @@ refs[1]{file,line,context}:
 ### Script-style JavaScript
 
 ```
-$ ts-axi outline client/app.js
+$ ts-axi outline client/app.js --fields exported
 decls[4]{line,kind,name,exported,signature}:
   6,function,CartCtrl,true,"controller CartCtrl($scope, priceService)"
   12,function,priceService,true,service priceService()
@@ -191,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.
@@ -231,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
 
@@ -239,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)`,
@@ -171,14 +184,17 @@ export function parseFields(raw, available) {
     const requested = [
         ...new Set(raw
             .split(",")
-            .map((f) => f.trim())
+            .map((f) => f.trim().toLowerCase())
             .filter(Boolean)),
     ];
-    const bad = requested.filter((f) => !available.includes(f));
+    const bad = requested.filter((f) => f !== "all" && !available.includes(f));
     if (bad.length > 0) {
         throw usageError(`unknown field${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}`, [
-            `available --fields: ${available.join(", ")}`,
+            `available --fields: ${available.join(", ")} (or all)`,
         ]);
     }
-    return requested;
+    if (requested.includes("all"))
+        return [...available];
+    // Columns keep the documented order whatever order they were asked in.
+    return available.filter((f) => requested.includes(f));
 }

package/dist/src/cli.js

@@ -5,22 +5,26 @@ import { homeCommand } from "./commands/home.js";
 import { impactCommand, IMPACT_HELP } from "./commands/impact.js";
 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]
-commands[7]:
-  (none)=project overview, def, refs, callers, outline, impact, config
+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
@@ -32,9 +36,16 @@ const COMMAND_HELP = {
     outline: OUTLINE_HELP,
     impact: IMPACT_HELP,
     config: CONFIG_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
@@ -70,10 +81,11 @@ export async function main(options = {}) {
                 outline: command("outline", outlineCommand, ctx),
                 impact: command("impact", impactCommand, ctx),
                 config: command("config", configCommand, ctx),
+                setup: command("setup", (args) => setupCommand(args), ctx),
             },
             getCommandHelp: (name) => COMMAND_HELP[name],
             renderUnknownCommand: (name) => `${renderErrorOutput(`unknown command '${name}'`, "VALIDATION_ERROR", [
-                "commands: def, refs, callers, outline, impact, config (no command = project overview)",
+                "commands: def, refs, callers, outline, impact, config, setup (no command = project overview)",
                 "Run `ts-axi --help` for examples",
             ])}\n`,
             formatError,
@@ -81,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]);
@@ -100,11 +121,10 @@ export function positionOf(group) {
 export const MATCH_ROWS = 20;
 /** `matches` (first MATCH_ROWS, shallowest first) plus `matches_total` / `truncated` past that. */
 export function matchRows(groups) {
+    // `at` pastes into `ts-axi def`; TS signatures carry `export`, and `--exported` narrows to exported ones.
     const rows = groups.slice(0, MATCH_ROWS).map((g) => ({
-        file: g.primary.file,
-        line: g.decls[0].nameLine,
+        at: positionOf(g),
         kind: g.primary.kind,
-        exported: g.primary.exported,
         signature: g.decls[0].signature,
     }));
     return { matches: rows, ...(groups.length > MATCH_ROWS ? { matches_total: groups.length, truncated: true } : {}) };
@@ -181,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,13 +2,13 @@ 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]{file,line,kind,exported,signature} (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
+  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
 examples[5]:
   ts-axi def User
@@ -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,7 +1,7 @@
-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 { usageError } from "../errors.js";
+import { AxiError, usageError } from "../errors.js";
 import { currentBranch, dirtyFileCount, isGitRepo } from "../git.js";
 import { block, helpBlock, out } from "../render.js";
 import { SETTINGS_FILE, isTestFile, loadSettings, readSettingsFile } from "../settings.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"
@@ -95,11 +89,30 @@ export async function homeCommand(args, ctx) {
     expectPositionals(parsed, 0, "ts-axi [-P <tsconfig>] [--test-glob <glob>]");
     const cwd = ctx?.cwd ?? process.cwd();
     const project = flag(parsed, "--project");
-    const settings = loadSettings(cwd, {
-        testGlobs: flags(parsed, "--test-glob"),
-        ...(project !== undefined ? { project } : {}),
-    });
-    const tsconfig = resolveTsconfig(cwd, settings);
+    const overrides = { testGlobs: flags(parsed, "--test-glob"), ...(project !== undefined ? { project } : {}) };
+    // A broken .ts-axi.json must not fail the session-start view: report it and carry on without the file.
+    let broken;
+    let settings;
+    try {
+        settings = loadSettings(cwd, overrides);
+    }
+    catch (error) {
+        if (!(error instanceof AxiError))
+            throw error;
+        broken = error.message;
+        settings = loadSettings(cwd, { ...overrides, ignoreFile: true });
+    }
+    let tsconfig;
+    try {
+        tsconfig = resolveTsconfig(cwd, settings);
+    }
+    catch (error) {
+        if (!(error instanceof AxiError) || settings.sources.project !== SETTINGS_FILE)
+            throw error;
+        broken = error.message;
+        settings = loadSettings(cwd, { ...overrides, ignoreFile: true });
+        tsconfig = resolveTsconfig(cwd, settings);
+    }
     // Same rule as the semantic commands: no explicit project + a multi-project workspace = workspace scope.
     let workspace;
     if (settings.project === undefined && (tsconfig === undefined || hasMultiProjectSignal(settings.root))) {
@@ -121,13 +134,17 @@ export async function homeCommand(args, ctx) {
     ]);
     const testFiles = counted.files.filter((f) => isTestFile(rel(settings.root, f), settings)).length;
     const plus = counted.capped ? "+" : "";
-    const present = readSettingsFile(settings.root) !== undefined;
+    const present = broken === undefined && readSettingsFile(settings.root) !== undefined;
     const onDefaultBranch = git.branch === undefined || git.branch === "main" || git.branch === "master";
     const help = [];
-    if (git.dirty > 0 || !onDefaultBranch) {
+    if (broken !== undefined)
+        help.push(`Fix or delete ${SETTINGS_FILE} - def, refs, callers, impact and config refuse to run until then (outline still works)`);
+    if (broken === undefined && (git.dirty > 0 || !onDefaultBranch)) {
         help.push("Run `ts-axi impact` to see which other code your changes affect");
     }
-    help.push("Run `ts-axi outline <file>` to list the declarations in a file", "Run `ts-axi def <name>` to find where a symbol is declared", "Run `ts-axi config` to see or change the test-file globs", "Run `ts-axi --help` for all commands");
+    help.push("Run `ts-axi outline <file>` to list the declarations in a file", ...(broken === undefined
+        ? ["Run `ts-axi def <name>` to find where a symbol is declared", "Run `ts-axi config` to see or change the test-file globs"]
+        : []), "Run `ts-axi --help` for all commands");
     return out(block({
         root: settings.root,
         ...(workspace ? { workspace: `${workspace.kind} (${workspace.projects.length} projects)` } : {}),
@@ -140,6 +157,6 @@ export async function homeCommand(args, ctx) {
         test_globs: settings.testGlobs.length,
         test_files: counted.capped ? `${testFiles}${plus}` : testFiles,
         git: git.text,
-        settings: `${SETTINGS_FILE} (${present ? "present" : "absent"})`,
+        settings: broken !== undefined ? `${SETTINGS_FILE} (ignored - ${/not valid JSON/.test(broken) ? "not valid JSON" : broken.replace(`${SETTINGS_FILE} `, "")})` : `${SETTINGS_FILE} (${present ? "present" : "absent"})`,
     }), helpBlock(help));
 }