ts-axi 0.1.1 → 0.1.3

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,files,tests}:
-  formatPrice,function,signature,true,"src/lib/format.ts:5",13,12,6,2
-  Cart.total,method,body,true,"src/lib/cart.ts:32",8,8,5,3
+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
 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)}"
@@ -65,16 +65,30 @@ npx skills add cmosgh/ts-axi --skill ts-axi
 | --- | --- |
 | `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` |
-| `refs <target>` | References of one symbol, grouped by file, with test counts. `--limit`, `--kind calls` |
-| `callers <target>` | Incoming calls of a function-like symbol. `--depth 1..3` |
+| `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, test-file counts, `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Analyses the current checkout |
+| `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 |
 | `config` | Show effective settings with their source; `config set <key> <value>` and `config unset <key>` write `.ts-axi.json` |
 
 `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.
 
 <!-- TODO(phase 4): paste real examples for def / refs / outline / config from the fixture project. -->
 
+## Monorepos
+
+No configuration and no new files in your repo: ts-axi detects the layout from what is already there - `nx.json` (projects = `project.json` dirs, or a legacy `workspace.json`), `pnpm-workspace.yaml`, `package.json` `workspaces`, or a root `tsconfig.json` that only holds `references`. The home view prints `workspace: nx (14 projects)`.
+
+Without `-P`, `refs`, `callers` and `impact` do not type-check the whole repo. They build the program from a subgraph: the declaring file (for `impact`, the touched files) plus every file that imports it, found by a fast text scan of import specifiers that follows `tsconfig.base.json` `paths`, workspace package names and `export * from` barrels. A caller in another project is found; the cost tracks the subgraph, not the repo. Each result says what was analysed:
+
+```
+scope: nx workspace - 30 of 5433 files (seeds 1; importers 29)
+```
+
+`scope_partial: true` means the importer scan stopped at its cap (50k files or 3 s); the help line says what is missing. `-P <tsconfig>` still analyses exactly one project; when it finds nothing, `found_outside_project` lists the importers outside it. A `-P` tsconfig that only holds `references` (an Nx project's `tsconfig.json`) is expanded to the configs it references: `tsconfig: libs/shared/tsconfig.json (2 referenced configs)`.
+
+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.
+
 ## Test files
 
 A file counts as a test by path pattern. Defaults: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/e2e/**`. The home view shows `test_globs` and `test_files` so a wrong rule is visible.
@@ -100,7 +114,7 @@ Any other key is a `VALIDATION_ERROR` naming the valid ones. `--test-glob <glob>
 One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-language-service-engine.md`).
 
 - `outline`, `def` and the home view only parse files (`ts.createSourceFile`): no tsconfig needed, well under a second.
-- `refs`, `callers` and `impact` build a `LanguageService` over the nearest `tsconfig.json` (or an implicit project of every source file when none exists, with a warning) and ask it for references and call hierarchy. Symbol identity comes from the checker, so `user.save` resolves to `User.save` through imports and re-exports.
+- `refs`, `callers` and `impact` build a `LanguageService` over the nearest `tsconfig.json` (or an implicit project of every source file when none exists, with a warning; in a monorepo or an implicit project of more than 3000 files, over the importer subgraph described above) and ask it for references and call hierarchy. Symbol identity comes from the checker, so `user.save` resolves to `User.save` through imports and re-exports.
 - `impact` reads the "before" version of touched files with `git show` and compares signatures to classify each change (`added`, `removed`, `signature`, `body`, `type`, `modified`). Uses it cannot follow (access through `any`, dynamic string keys) are reported as `blind_spots`, never silently dropped.
 - Type errors in the analysed project never block anything; they are reported as a `diagnostics` count.
 

package/dist/src/commands/common.js

@@ -8,6 +8,7 @@ import { usageError } from "../errors.js";
 import { hasGlobMagic, matchesGlob } from "../glob.js";
 import { openProject } from "../project.js";
 import { loadSettings } from "../settings.js";
+import { byDepthThenPath } from "../walk.js";
 import { clip, didYouMean, groupSymbols, KINDS, kindOf, signatureOf, } from "../symbols.js";
 export const BODY_LINES = 60;
 export const CONTEXT_MAX = 100;
@@ -71,7 +72,15 @@ export function resolveNameTarget(ctx, target, f) {
         ...(target.member !== undefined ? { member: target.member } : {}),
         fuzzy: f.fuzzy,
     });
-    return groupSymbols(applyFilters(ctx, found, f));
+    // Shallowest path first: the canonical copy before nested duplicates.
+    return groupSymbols(applyFilters(ctx, found, f)).sort((a, b) => byDepthThenPath(a.primary.file, b.primary.file) || a.decls[0].nameLine - b.decls[0].nameLine);
+}
+/** `tsconfig: x (n referenced configs)` when a references-only tsconfig was expanded. */
+export function projectFields(ctx) {
+    const { tsconfig, referenced } = ctx.index.project;
+    if (!tsconfig || referenced === undefined)
+        return {};
+    return { tsconfig: `${relative(ctx.cwd, tsconfig).split(sep).join("/")} (${referenced} referenced configs)` };
 }
 export function suggestions(ctx, target) {
     const names = [...ctx.index.allNames()].filter((n) => (target.member === undefined ? !n.includes(".") : n.includes(".")));

package/dist/src/commands/def.js

@@ -1,5 +1,5 @@
 import { bool, expectPositionals, flag, parseArgs } from "../args.js";
-import { createSemanticProject } from "../project.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, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, } from "./common.js";
@@ -63,7 +63,7 @@ export async function defCommand(args, ctx) {
             return out(block({ position: label, identifiers: at.candidates }), helpBlock(at.candidates.slice(0, 3).map((c) => `Run \`ts-axi def ${at.file}:${c.line}:${c.col}\` for ${c.name}`)));
         }
         // A reference, not a Declaration: ask the checker where it is declared.
-        const semantic = createSemanticProject(opened.index);
+        const { semantic } = semanticFor(opened, [at.abs], 0);
         const def = semantic.definitionAt(at.abs, at.pos);
         const decl = def && def.line > 0 ? declarationAt(opened.index, def.absFile, def.pos, kindFromScriptElement(def.kind)) : undefined;
         if (!decl) {

package/dist/src/commands/home.js

@@ -5,8 +5,9 @@ import { 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";
+import { listFiles, skipDir } from "../walk.js";
+import { detectWorkspace, hasMultiProjectSignal, isMultiProject } from "../workspace.js";
 const SOURCE_EXT = /\.(?:[cm]?[jt]s|[jt]sx)$/;
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
 /** The view runs at session start: bound the file walk by count and time. */
 const WALK_CAP = 20_000;
 const WALK_DEADLINE_MS = 600;
@@ -15,8 +16,8 @@ const HOME_SPECS = [
     { name: "--test-glob", repeatable: true },
     { name: "--project", alias: "-P" },
 ];
-/** Does `dir` hold a TS/JS source within `depth` levels (node_modules skipped)? */
-function hasSources(dir, depth) {
+/** 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 });
@@ -30,36 +31,11 @@ function hasSources(dir, depth) {
     }
     if (depth === 0)
         return false;
-    return entries.some((e) => e.isDirectory() && e.name !== "node_modules" && e.name !== ".git" && hasSources(join(dir, e.name), depth - 1));
+    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`, minus node_modules, dist, build, .git. */
+/** Implicit project: every source below `root` from the shared listing (git, else a bounded fs walk). */
 function walkSources(root) {
-    const files = [];
-    const deadline = Date.now() + WALK_DEADLINE_MS;
-    let capped = false;
-    const stack = [root];
-    while (stack.length > 0 && !capped) {
-        const dir = stack.pop();
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                if (!SKIP_DIRS.has(entry.name))
-                    stack.push(join(dir, entry.name));
-            }
-            else if (entry.isFile() && SOURCE_EXT.test(entry.name)) {
-                files.push(join(dir, entry.name));
-            }
-        }
-        if (files.length >= WALK_CAP || Date.now() > deadline)
-            capped = true;
-    }
-    return { files, capped };
+    return listFiles(root, (name) => SOURCE_EXT.test(name) && !/\.d\.[mc]?ts$/.test(name), { maxFiles: WALK_CAP, deadline: Date.now() + WALK_DEADLINE_MS });
 }
 function findTsconfig(cwd) {
     let dir = cwd;
@@ -73,14 +49,16 @@ function findTsconfig(cwd) {
         dir = parent;
     }
 }
-async function tsconfigFiles(tsconfig) {
-    const ts = (await import("typescript")).default;
-    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
-    if (read.error)
+async function tsconfigFiles(tsconfig, root) {
+    // Loaded lazily: the TypeScript module is only needed when a tsconfig exists.
+    const { loadProject } = await import("../project.js");
+    try {
+        const project = loadProject(root, { path: tsconfig, implicit: false });
+        return { files: project.fileNames, capped: false, ...(project.referenced !== undefined ? { referenced: project.referenced } : {}) };
+    }
+    catch {
         return { files: [], capped: false };
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfig), undefined, tsconfig);
-    const files = parsed.fileNames.filter((f) => !f.split(/[\\/]/).includes("node_modules"));
-    return { files, capped: false };
+    }
 }
 function rel(root, path) {
     return relative(root, path).split(sep).join("/") || ".";
@@ -112,17 +90,24 @@ function resolveTsconfig(cwd, settings) {
     }
     return findTsconfig(cwd);
 }
-export async function homeCommand(args) {
+export async function homeCommand(args, ctx) {
     const parsed = parseArgs(args, HOME_SPECS, "ts-axi");
     expectPositionals(parsed, 0, "ts-axi [-P <tsconfig>] [--test-glob <glob>]");
-    const cwd = process.cwd();
+    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);
-    if (tsconfig === undefined && !hasSources(cwd, PROBE_DEPTH)) {
+    // 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))) {
+        const detected = detectWorkspace(settings.root);
+        if (isMultiProject(detected.kind))
+            workspace = detected;
+    }
+    if (tsconfig === undefined && workspace === undefined && !hasSources(cwd, PROBE_DEPTH)) {
         return out(block({ project: "none" }), helpBlock([
             "Run `ts-axi outline <file>` on any .ts/.js file; it needs no project",
             "Run `ts-axi --help` for all commands",
@@ -130,7 +115,9 @@ export async function homeCommand(args) {
     }
     const [git, counted] = await Promise.all([
         gitSummary(cwd),
-        tsconfig !== undefined ? tsconfigFiles(tsconfig) : Promise.resolve(walkSources(settings.root)),
+        workspace
+            ? Promise.resolve({ files: workspace.sourceFiles, capped: false })
+            : tsconfig !== undefined ? tsconfigFiles(tsconfig, settings.root) : Promise.resolve(walkSources(settings.root)),
     ]);
     const testFiles = counted.files.filter((f) => isTestFile(rel(settings.root, f), settings)).length;
     const plus = counted.capped ? "+" : "";
@@ -143,7 +130,12 @@ export async function homeCommand(args) {
     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");
     return out(block({
         root: settings.root,
-        tsconfig: tsconfig === undefined ? "implicit" : rel(settings.root, tsconfig),
+        ...(workspace ? { workspace: `${workspace.kind} (${workspace.projects.length} projects)` } : {}),
+        tsconfig: workspace
+            ? "nearest per file - workspace scope"
+            : tsconfig === undefined
+                ? "implicit"
+                : `${rel(settings.root, tsconfig)}${counted.referenced !== undefined ? ` (${counted.referenced} referenced configs)` : ""}`,
         source_files: counted.capped ? `${counted.files.length}${plus}` : counted.files.length,
         test_globs: settings.testGlobs.length,
         test_files: counted.capped ? `${testFiles}${plus}` : testFiles,

package/dist/src/commands/impact.js

@@ -1,37 +1,41 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
 import ts from "typescript";
 import { bool, intFlag, parseArgs, flag } from "../args.js";
 import { changedRanges, parseUnifiedDiff } from "../diff.js";
 import { AxiError, usageError } from "../errors.js";
 import { diffNameStatus, diffUnified, isGitRepo, resolveBaseRev, showFile, untrackedFiles } from "../git.js";
 import { allocateBudget, classifyFile, compareChanges, formatRanges, inRanges, localOnlyLine, matchKey, reverseApply, wordMatches, } from "../impact.js";
-import { createSemanticProject, SOURCE_EXTENSIONS } from "../project.js";
+import { loadProject, SOURCE_EXTENSIONS } from "../project.js";
 import { block, helpBlock, out } from "../render.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike } from "../symbols.js";
-import { contextOf, lineOf, open } from "./common.js";
+import { IMPACT_HOPS, scopeFields, scopeHelp, semanticFor } from "../scope.js";
+import { walkFiles } from "../walk.js";
+import { contextOf, lineOf, open, projectFields } from "./common.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const SIDE_ROWS = 20;
 /** Non-TS files `--grep` also searches: templates that use TS exports the checker never sees. */
 const GREP_EXTRA = [".astro", ".vue", ".svelte", ".mdx", ".html"];
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
 export const IMPACT_HELP = `usage: ts-axi impact [<git-range> | -] [flags]
 input:
   (none) = working tree vs HEAD (staged + unstaged + untracked); --staged = index vs HEAD
   <git-range> = any git diff range (main...HEAD, abc123, v1..v2); - = unified diff on stdin (needs the after side checked out)
   analysis is of the current checkout - for a range whose head is not the working tree, check that head out first
-flags[6]:
-  --staged, --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), -P <tsconfig>, --json
+flags[7]:
+  --staged, --via (adds References through an interface or base member to refs[n] with a via column), --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), -P <tsconfig>, --json
 output:
-  base, head, changes (count), changed[n]{symbol,kind,change,exported,at,refs_total,refs_outside,files,tests}
+  base, head, changes (count), changed[n]{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}
   change = signature | removed | type | added | body | modified (before unavailable) - riskiest first
+  refs_* / files / tests count direct References only; via = References outside the change set that reach the Symbol through an interface or base member it implements (or name an override of it) - they MAY call it
   refs[n]{symbol,file,line,context} = References outside the change set; truncated + refs_shown + refs_outside_total when cut
+  notes[n]{symbol,note} = a signature change of a member that implements an interface or base member (the contract may break)
   local_only = Changes with no Reference outside the change set; file_level[n]{file,lines} = changed lines outside any Declaration
   blind_spots[n]{symbol,file,line,reason} = uses the checker cannot follow (any; string keys; unresolved export *)
   skipped[n]{file,reason} = files in the diff that were not analysed (.astro, .json, outside the Project)
   tests: 0 on an exported signature or body change = no Test file references it
+  scope = in a monorepo without -P the program is the touched files + two levels of importers (scope_partial: true when capped)
 examples[5]:
   ts-axi impact
   ts-axi impact --staged
@@ -41,6 +45,7 @@ examples[5]:
 `;
 const SPECS = [
     { name: "--staged", boolean: true },
+    { name: "--via", boolean: true },
     { name: "--depth" },
     { name: "--limit" },
     { name: "--grep", boolean: true },
@@ -220,22 +225,7 @@ function blindSpots(semantic, names, changeSet) {
     return spots;
 }
 function walkExtra(dir, outFiles) {
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith("."))
-                walkExtra(join(dir, entry.name), outFiles);
-        }
-        else if (GREP_EXTRA.some((ext) => entry.name.endsWith(ext))) {
-            outFiles.push(join(dir, entry.name));
-        }
-    }
+    outFiles.push(...walkFiles(dir, { accept: (name) => GREP_EXTRA.some((ext) => name.endsWith(ext)) }).files);
 }
 function textualMatches(opened, semantic, names, known, skipLines, changeSet) {
     const files = [...semantic.projectFiles];
@@ -316,6 +306,36 @@ function rerun(arg, parsed, extra) {
     parts.push(extra);
     return `${arg === "-" ? "<diff> | " : ""}${parts.join(" ")}`;
 }
+/**
+ * Spec files skipped as "not in the Project" (a tsconfig.lib.json / tsconfig.app.json that excludes
+ * them): name the sibling tsconfig that includes them so tests get counted.
+ */
+function specFilesHint(cwd, opened, skipped, noTests) {
+    const tsconfig = opened.index.project.tsconfig;
+    if (!tsconfig)
+        return undefined;
+    const outside = skipped.filter((s) => s.reason === "not in the Project");
+    const tests = outside.filter((s) => isTestFile(s.file, opened.settings));
+    if (tests.length === 0 || !(tests.length === outside.length || noTests))
+        return undefined;
+    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));
+    // Prefer the one that really includes a skipped spec file (an Nx tsconfig.json may only hold references).
+    const includes = (c) => {
+        try {
+            const files = new Set(loadProject(opened.root, { path: c, implicit: false }).fileNames);
+            return tests.some((t) => files.has(opened.index.abs(t.file)));
+        }
+        catch {
+            return false;
+        }
+    };
+    const pick = candidates.find(includes) ?? candidates[0];
+    const rel = (abs) => relative(cwd, abs).split(sep).join("/");
+    return `Spec files are outside ${rel(tsconfig)}; run with -P ${pick ? rel(pick) : "<sibling tsconfig.json that includes them>"} to count tests`;
+}
 export async function impactCommand(args, ctx) {
     const parsed = parseArgs(args, SPECS, "ts-axi impact");
     if (parsed.positionals.length > 1) {
@@ -328,6 +348,7 @@ export async function impactCommand(args, ctx) {
     const limit = intFlag(parsed, "--limit", DEFAULT_LIMIT, { min: 1, max: MAX_LIMIT });
     const depth = intFlag(parsed, "--depth", 1, { min: 1, max: 3 });
     const grep = bool(parsed, "--grep");
+    const showVia = bool(parsed, "--via");
     const started = performance.now();
     const opened = open(ctx.cwd, parsed);
     const input = arg === "-"
@@ -376,6 +397,7 @@ export async function impactCommand(args, ctx) {
     const total = declChanges.length + fileLevel.length;
     const header = {
         ...(warnings.length > 0 ? { warning: warnings.join("; ") } : {}),
+        ...projectFields(opened),
         base: input.base,
         head: input.head,
         changes: total,
@@ -387,6 +409,9 @@ export async function impactCommand(args, ctx) {
             : ["Changes touch imports or module-level statements only - read those lines directly"];
         if (skipped.length > 0)
             help.push("Skipped files are not TS or JS source of the Project - review them by hand");
+        const specHint = specFilesHint(ctx.cwd, opened, skipped, true);
+        if (specHint)
+            help.push(specHint);
         return out(block({
             ...header,
             ...(fileLevel.length > 0 ? { file_level: fileLevel } : {}),
@@ -395,7 +420,8 @@ export async function impactCommand(args, ctx) {
         }), helpBlock(help));
     }
     // --- References (semantic, on the checkout) ---
-    const semantic = createSemanticProject(opened.index);
+    // Scoped workspace: touched files + two levels of importers; deleted or renamed-away paths still resolve so their importers count.
+    const { semantic, scope } = semanticFor(opened, analysed.filter((f) => f.status !== "deleted").map((f) => opened.index.abs(f.path)), IMPACT_HOPS, analysed.flatMap((f) => (f.status === "deleted" ? [f.path] : f.oldPath ? [f.oldPath] : [])).map((p) => opened.index.abs(p)));
     const rows = declChanges.map((change) => {
         const source = change.after ?? change.before;
         const live = change.after ? opened.index.declarations(opened.index.abs(change.file)).find((d) => matchKey(d) === change.key) : undefined;
@@ -408,6 +434,8 @@ export async function impactCommand(args, ctx) {
             at: `${change.file}:${(live ?? source).nameLine}`,
             all: [],
             outside: [],
+            via: [],
+            bases: [],
         };
     });
     for (const row of rows) {
@@ -415,33 +443,43 @@ export async function impactCommand(args, ctx) {
             changeSet.set(row.change.file, [...(changeSet.get(row.change.file) ?? []), [row.live.line, row.live.endLine]]);
     }
     const known = new Set();
+    const byPosition = (a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col;
     for (const row of rows) {
-        const entries = row.live
-            ? semantic.findReferences(opened.index.abs(row.live.file), row.live.namePos)
-            : row.change.change === "removed"
-                ? brokenReferences(semantic, row.change.before)
-                : [];
+        let entries = [];
+        if (row.live) {
+            const split = semantic.referenceSplit(opened.index.abs(row.live.file), row.live.namePos);
+            entries = [...split.declarations, ...split.direct];
+            // Sibling implementations and via uses are known positions, not textual misses for --grep.
+            for (const e of [...split.via, ...split.implementations, ...split.dropped])
+                known.add(`${e.file}:${e.line}`);
+            row.via = split.via.filter((e) => !inRanges(changeSet.get(e.file), e.line)).sort(byPosition);
+            row.bases = split.bases;
+        }
+        else if (row.change.change === "removed") {
+            entries = brokenReferences(semantic, row.change.before);
+        }
         for (const e of entries)
             known.add(`${e.file}:${e.line}`);
         row.all = entries.filter((e) => !e.isDefinition);
-        row.outside = row.all
-            .filter((e) => !inRanges(changeSet.get(e.file), e.line))
-            .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col);
+        row.outside = row.all.filter((e) => !inRanges(changeSet.get(e.file), e.line)).sort(byPosition);
     }
+    const shownRefs = (r) => (showVia ? [...r.outside, ...r.via].sort(byPosition) : r.outside);
+    const hasOutside = (r) => r.outside.length > 0 || r.via.length > 0;
     const listed = rows
-        .filter((r) => r.outside.length > 0)
+        .filter(hasOutside)
         .sort((a, b) => compareChanges({ change: a.change.change, exported: a.exported, refsOutside: a.outside.length, file: a.change.file, line: (a.live ?? a.change.before).line }, { change: b.change.change, exported: b.exported, refsOutside: b.outside.length, file: b.change.file, line: (b.live ?? b.change.before).line }));
     const localOnly = rows
-        .filter((r) => r.outside.length === 0)
+        .filter((r) => !hasOutside(r))
         .sort((a, b) => compareChanges({ change: a.change.change, exported: a.exported, refsOutside: 0, file: a.change.file, line: (a.live ?? a.change.before).line }, { change: b.change.change, exported: b.exported, refsOutside: 0, file: b.change.file, line: (b.live ?? b.change.before).line }));
-    const quotas = allocateBudget(listed.map((r) => r.outside.length), limit);
-    const refRows = listed.flatMap((r, i) => r.outside.slice(0, quotas[i]).map((e) => ({
+    const quotas = allocateBudget(listed.map((r) => shownRefs(r).length), limit);
+    const refRows = listed.flatMap((r, i) => shownRefs(r).slice(0, quotas[i]).map((e) => ({
         symbol: r.symbol,
         file: e.file,
         line: e.line,
+        ...(showVia ? { via: e.via ?? "-" } : {}),
         context: contextOf(lineOf(opened.index.text(opened.index.abs(e.file)), e.line), e.col),
     })));
-    const outsideTotal = listed.reduce((n, r) => n + r.outside.length, 0);
+    const outsideTotal = listed.reduce((n, r) => n + shownRefs(r).length, 0);
     const truncated = refRows.length < outsideTotal;
     const fileCounts = (r) => {
         const files = [...new Set(r.outside.map((e) => e.file))];
@@ -479,8 +517,18 @@ export async function impactCommand(args, ctx) {
     if (depth === 1 && rows.some((r) => r.live && isFunctionLike(r.kind) && r.outside.length > 0)) {
         help.push(`Run \`${rerun(arg, parsed, "--depth 2")}\` for who calls the callers`);
     }
+    if (!showVia && listed.some((r) => r.via.length > 0)) {
+        help.push(`Run \`${rerun(arg, parsed, "--via")}\` for References through an interface or base member - they may reach the changed code`);
+    }
     if (skipped.length > 0)
         help.push("Skipped files are not TS or JS source of the Project - review them by hand");
+    const specHint = specFilesHint(ctx.cwd, opened, skipped, listed.every((r) => fileCounts(r).tests === 0));
+    if (specHint)
+        help.push(specHint);
+    help.push(...scopeHelp(scope));
+    const notes = rows
+        .filter((r) => r.change.change === "signature" && r.bases.length > 0)
+        .map((r) => ({ symbol: r.symbol, note: `implements ${r.bases.join(" and ")}` }));
     return out(block({
         ...header,
         ...(listed.length > 0
@@ -493,18 +541,21 @@ export async function impactCommand(args, ctx) {
                     at: r.at,
                     refs_total: r.all.length,
                     refs_outside: r.outside.length,
+                    via: r.via.length,
                     ...fileCounts(r),
                 })),
                 refs: refRows,
             }
             : {}),
         ...(truncated ? { truncated: true, refs_shown: refRows.length, refs_outside_total: outsideTotal } : {}),
+        ...(notes.length > 0 ? { notes } : {}),
         ...(localOnly.length > 0 ? { local_only: localOnlyLine(localOnly.map((r) => `${r.symbol} ${r.change.change}`)) } : {}),
         ...(fileLevel.length > 0 ? { file_level: fileLevel } : {}),
         ...capped("blind_spots", spots),
         ...(grep ? capped("unresolved", unresolved) : {}),
         ...depthLevels(semantic, rows, depth),
         ...skippedBlock,
+        ...scopeFields(scope),
         elapsed_ms: Math.round(performance.now() - started),
         ...(diagnostics > 0 ? { diagnostics } : {}),
     }), helpBlock(help));