ts-axi 0.1.0 → 0.1.2

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,10 +65,10 @@ 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.

package/dist/src/commands/impact.js

@@ -1,12 +1,12 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, 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 { createSemanticProject, loadProject, SOURCE_EXTENSIONS } from "../project.js";
 import { block, helpBlock, out } from "../render.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike } from "../symbols.js";
@@ -22,12 +22,14 @@ 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)
@@ -41,6 +43,7 @@ examples[5]:
 `;
 const SPECS = [
     { name: "--staged", boolean: true },
+    { name: "--via", boolean: true },
     { name: "--depth" },
     { name: "--limit" },
     { name: "--grep", boolean: true },
@@ -316,6 +319,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.location.path;
+    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 +361,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 === "-"
@@ -387,6 +421,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 } : {}),
@@ -408,6 +445,8 @@ export async function impactCommand(args, ctx) {
             at: `${change.file}:${(live ?? source).nameLine}`,
             all: [],
             outside: [],
+            via: [],
+            bases: [],
         };
     });
     for (const row of rows) {
@@ -415,33 +454,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 +528,17 @@ 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);
+    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,12 +551,14 @@ 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),

package/dist/src/commands/refs.js

@@ -1,5 +1,7 @@
-import { expectPositionals, flag, intFlag, parseArgs } from "../args.js";
-import { createSemanticProject } from "../project.js";
+import { relative, sep } from "node:path";
+import { bool, expectPositionals, flag, intFlag, parseArgs } from "../args.js";
+import { createSemanticProject, findOutsideProject, nearestTsconfig } from "../project.js";
+import { viaLine } from "../references.js";
 import { block, helpBlock, out } from "../render.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
@@ -7,13 +9,19 @@ import { contextOf, declarationAt, filterSuffix, lineOf, matchRows, narrowHints,
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const DEPTH_ROWS = 50;
-const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), -P <tsconfig>, --json`;
+const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --json`;
+const VIA_DOC = `via_interface: n (Iface.member) = References through an interface or base member the Symbol implements or overrides - they MAY reach it; not in refs_total
+  via_implementations: n (Impl.member) = References to implementations or overrides of the Symbol; not in refs_total
+  implementations: n = members that implement or override the Symbol (their Declarations are never refs)
+  matches: 0 under -P lists found_outside_project[n]{file,line} when the name is declared outside that Project`;
 export const REFS_HELP = `usage: ts-axi refs <name | Class.member | path:line[:col]> [flags]
-flags[9]:
+flags[11]:
   ${SHARED_FLAGS}
+  --implementations (lists implementations[n]{file,line,symbol} instead of the count)
   --kind calls = same as \`ts-axi callers\`
 output:
   symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,context} (Declarations excluded), elapsed_ms
+  ${VIA_DOC}
   an ambiguous name lists matches[n] + the disambiguated forms; nothing is analysed
 examples[4]:
   ts-axi refs User.save
@@ -22,12 +30,13 @@ examples[4]:
   ts-axi refs runSync --limit 200
 `;
 export const CALLERS_HELP = `usage: ts-axi callers <name | Class.member | path:line[:col]> [flags]
-flags[10]:
+flags[11]:
   ${SHARED_FLAGS}
   --depth <1-3> (default 1; levels > 1 print callers_depthN[n]{caller,file,count}, no locations)
 output:
   symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,caller,context}, elapsed_ms
   caller = enclosing function or method; (top-level) for module code
+  ${VIA_DOC}
 examples[3]:
   ts-axi callers runSync
   ts-axi callers User.save --depth 2
@@ -45,7 +54,8 @@ async function run(args, ctx, invoked) {
         ...TARGET_FLAGS,
         { name: "--limit" },
         { name: "--test-glob", repeatable: true },
-        ...(invoked === "calls" ? [{ name: "--depth" }] : []),
+        { name: "--via", boolean: true },
+        ...(invoked === "calls" ? [{ name: "--depth" }] : [{ name: "--implementations", boolean: true }]),
     ];
     const parsed = parseArgs(args, specs, command);
     const [raw] = expectPositionals(parsed, 1, `${command} <name | Class.member | path:line[:col]> [flags]`);
@@ -57,6 +67,7 @@ async function run(args, ctx, invoked) {
     const label = targetLabel(target);
     const project = flag(parsed, "-P");
     const name = mode === "calls" ? "callers" : "refs";
+    const show = { via: bool(parsed, "--via"), implementations: invoked === "refs" && bool(parsed, "--implementations") };
     const started = performance.now();
     const opened = open(ctx.cwd, parsed, positionStartDir(ctx.cwd, target));
     const warning = opened.warning ? { warning: opened.warning } : {};
@@ -65,6 +76,23 @@ async function run(args, ctx, invoked) {
     if (target.kind === "name") {
         const groups = resolveNameTarget(opened, target, f);
         if (groups.length === 0) {
+            // Under an explicit Project the name may live in a sibling one: say so before suggesting --fuzzy.
+            const outside = project || opened.settings.project
+                ? findOutsideProject(opened.index, { name: target.name, ...(target.member !== undefined ? { member: target.member } : {}), fuzzy: f.fuzzy })
+                : [];
+            if (outside.length > 0) {
+                const tsconfig = nearestTsconfig(opened.index.abs(outside[0].file), opened.root);
+                const rel = tsconfig ? relative(ctx.cwd, tsconfig).split(sep).join("/") : undefined;
+                return out(block({
+                    ...warning,
+                    matches: 0,
+                    found_outside_project: outside.map((d) => ({ file: d.file, line: d.nameLine })),
+                    hint: `symbol is declared outside the selected project - run with -P ${rel ?? "<its tsconfig>"} or without -P`,
+                }), helpBlock([
+                    ...(rel ? [`Run \`ts-axi ${name} ${label} -P ${rel}\``] : []),
+                    `Run \`ts-axi ${name} ${outside[0].file}:${outside[0].nameLine}\` to use the nearest tsconfig of that file`,
+                ]));
+            }
             const suggested = suggestions(opened, target);
             return out(block({ ...warning, matches: 0, ...(suggested.length > 0 ? { did_you_mean: suggested } : {}) }), helpBlock([
                 ...suggested.slice(0, 2).map((s) => `Run \`ts-axi ${name} ${s}\``),
@@ -96,8 +124,8 @@ async function run(args, ctx, invoked) {
     const declaredAt = decl ? `${decl.file}:${decl.nameLine}` : def && def.line > 0 ? `${def.file}:${def.line}` : "(outside the Project)";
     const header = { ...warning, symbol, kind, declared_at: declaredAt };
     return mode === "calls"
-        ? renderCallers(semantic, opened, resolved, header, { limit, depth, started, symbol, declaredAt })
-        : renderRefs(semantic, opened, resolved, header, { limit, started, symbol, declaredAt, kind });
+        ? renderCallers(semantic, opened, resolved, header, { limit, depth, started, symbol, declaredAt, show })
+        : renderRefs(semantic, opened, resolved, header, { limit, started, symbol, declaredAt, kind, show });
 }
 function sortRows(rows) {
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col);
@@ -113,17 +141,38 @@ function footer(semantic, started, touched) {
     const diagnostics = semantic.diagnosticsCount(touched);
     return { elapsed_ms: Math.round(performance.now() - started), ...(diagnostics > 0 ? { diagnostics } : {}) };
 }
+/** `via_interface` / `via_implementations` counts, plus the hint to see their rows. */
+function viaFields(via, bases) {
+    const base = via.filter((v) => v.through === "base");
+    const impl = via.filter((v) => v.through === "implementation");
+    return {
+        ...(bases.length > 0 || base.length > 0 ? { via_interface: viaLine(base.length, [...bases, ...base.map((v) => v.via)]) } : {}),
+        ...(impl.length > 0 ? { via_implementations: viaLine(impl.length, impl.map((v) => v.via)) } : {}),
+    };
+}
+/** Direct rows, plus via rows (with a `via` column) under `--via`. */
+function mergedRows(direct, via, show) {
+    return show.via ? sortRows([...direct, ...via]) : direct;
+}
 function renderRefs(semantic, opened, resolved, header, o) {
-    const rows = sortRows(semantic.findReferences(resolved.absFile, resolved.pos).filter((r) => !r.isDefinition));
+    const split = semantic.referenceSplit(resolved.absFile, resolved.pos);
+    const rows = sortRows([...split.direct]);
+    const via = sortRows([...split.via]);
+    const impls = sortRows([...split.implementations]);
     const { files, tests, fileList } = summary(opened, rows);
-    const shown = rows.slice(0, o.limit);
-    const truncated = shown.length < rows.length;
+    const listed = mergedRows(rows, via, o.show);
+    const shown = listed.slice(0, o.limit);
+    const truncated = shown.length < listed.length;
     const help = [];
     if (truncated) {
         help.push(o.limit < MAX_LIMIT
-            ? `Showing ${shown.length} of ${rows.length}; run \`ts-axi refs ${o.declaredAt} --limit ${Math.min(MAX_LIMIT, rows.length)}\` for more`
-            : `Showing ${shown.length} of ${rows.length}; narrow by reading one file at a time`);
+            ? `Showing ${shown.length} of ${listed.length}; run \`ts-axi refs ${o.declaredAt}${o.show.via ? " --via" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`
+            : `Showing ${shown.length} of ${listed.length}; narrow by reading one file at a time`);
     }
+    if (via.length > 0 && !o.show.via)
+        help.push(`Run \`ts-axi refs ${o.declaredAt} --via\` for the ${via.length} via References (${viaNames(via)})`);
+    if (impls.length > 0 && !o.show.implementations)
+        help.push(`Run \`ts-axi refs ${o.declaredAt} --implementations\` to list the ${impls.length} implementations`);
     if (isFunctionLike(o.kind))
         help.push(`Run \`ts-axi callers ${o.declaredAt}\` for call sites with their enclosing function`);
     help.push(`Run \`ts-axi def ${o.declaredAt}\` for the declaration body`);
@@ -132,13 +181,27 @@ function renderRefs(semantic, opened, resolved, header, o) {
         refs_total: rows.length,
         files,
         tests,
-        ...(rows.length === 0
+        ...viaFields(via, split.bases),
+        ...(impls.length > 0
+            ? { implementations: o.show.implementations ? impls.map((r) => ({ file: r.file, line: r.line, symbol: r.name })) : impls.length }
+            : {}),
+        ...(shown.length === 0
             ? {}
-            : { refs: shown.map((r) => ({ file: r.file, line: r.line, context: contextCell(opened, r) })) }),
+            : {
+                refs: shown.map((r) => ({
+                    file: r.file,
+                    line: r.line,
+                    ...(o.show.via ? { via: r.via ?? "-" } : {}),
+                    context: contextCell(opened, r),
+                })),
+            }),
         ...(truncated ? { truncated: true } : {}),
         ...footer(semantic, o.started, fileList),
     }), helpBlock(help));
 }
+function viaNames(via) {
+    return [...new Set(via.map((v) => v.via))].join("; ");
+}
 function itemKey(site) {
     return `${site.item.file}#${site.item.selectionSpan.start}`;
 }
@@ -172,13 +235,15 @@ function renderCallers(semantic, opened, resolved, header, o) {
     if (sites === undefined) {
         return out(block({ ...header, refs_total: 0, note: "not callable - no call hierarchy for this Symbol", ...footer(semantic, o.started, []) }), helpBlock([`Run \`ts-axi refs ${o.declaredAt}\` for every Reference`]));
     }
-    const rows = sortRows([...sites]);
+    const rows = sortRows(sites.filter((s) => s.via === undefined));
+    const via = sortRows(sites.filter((s) => s.via !== undefined));
     const { files, tests, fileList } = summary(opened, rows);
-    const shown = rows.slice(0, o.limit);
-    const truncated = shown.length < rows.length;
+    const listed = mergedRows(rows, via, o.show);
+    const shown = listed.slice(0, o.limit);
+    const truncated = shown.length < listed.length;
     const levels = {};
     const visited = new Set();
-    let level = rows;
+    let level = listed;
     for (let d = 2; d <= o.depth; d++) {
         level = nextLevel(semantic, level, visited);
         const agg = depthRows(level);
@@ -190,8 +255,10 @@ function renderCallers(semantic, opened, resolved, header, o) {
     }
     const help = [];
     if (truncated) {
-        help.push(`Showing ${shown.length} of ${rows.length}; run \`ts-axi callers ${o.declaredAt} --limit ${Math.min(MAX_LIMIT, rows.length)}\` for more`);
+        help.push(`Showing ${shown.length} of ${listed.length}; run \`ts-axi callers ${o.declaredAt}${o.show.via ? " --via" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`);
     }
+    if (via.length > 0 && !o.show.via)
+        help.push(`Run \`ts-axi callers ${o.declaredAt} --via\` for the ${via.length} via calls (${viaNames(via)})`);
     const top = shown.find((r) => r.caller !== "(top-level)");
     if (top && o.depth === 1)
         help.push(`Run \`ts-axi callers ${o.declaredAt} --depth 2\` for who calls the callers`);
@@ -201,9 +268,18 @@ function renderCallers(semantic, opened, resolved, header, o) {
         refs_total: rows.length,
         files,
         tests,
-        ...(rows.length === 0
+        ...viaFields(via, []),
+        ...(shown.length === 0
             ? {}
-            : { refs: shown.map((r) => ({ file: r.file, line: r.line, caller: r.caller, context: contextCell(opened, r) })) }),
+            : {
+                refs: shown.map((r) => ({
+                    file: r.file,
+                    line: r.line,
+                    caller: r.caller,
+                    ...(o.show.via ? { via: r.via ?? "-" } : {}),
+                    context: contextCell(opened, r),
+                })),
+            }),
         ...(truncated ? { truncated: true } : {}),
         ...levels,
         ...footer(semantic, o.started, fileList),

package/dist/src/project.js

@@ -4,6 +4,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "n
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import ts from "typescript";
 import { usageError } from "./errors.js";
+import { classifyReferenceGroups } from "./references.js";
 import { collectDeclarations } from "./symbols.js";
 export const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
 const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
@@ -130,6 +131,75 @@ export function parseSource(file, text) {
 export function relPath(root, abs) {
     return relative(root, abs).split(sep).join("/");
 }
+function declMatches(decl, query) {
+    const needle = query.fuzzy ? query.name.toLowerCase() : query.name;
+    if (query.member !== undefined) {
+        if (decl.parentName === undefined)
+            return false;
+        const parent = decl.parentName.split(".").pop();
+        return query.fuzzy
+            ? parent.toLowerCase().includes(needle) && decl.name.toLowerCase().includes(query.member.toLowerCase())
+            : parent === query.name && decl.name === query.member;
+    }
+    return query.fuzzy ? decl.name.toLowerCase().includes(needle) : decl.name === query.name;
+}
+// Same bounds as the home view's walk: this runs on an empty result, it must stay cheap.
+const OUTSIDE_WALK_CAP = 20_000;
+const OUTSIDE_WALK_MS = 600;
+/**
+ * Declarations matching `query` in source files below the repo root that are not in the Project
+ * (syntactic, bounded by file count and time; stops after `max` hits).
+ */
+export function findOutsideProject(index, query, max = 3) {
+    const inProject = new Set(index.files);
+    const deadline = Date.now() + OUTSIDE_WALK_MS;
+    const hits = [];
+    const stack = [index.root];
+    let visited = 0;
+    while (stack.length > 0 && hits.length < max && visited < OUTSIDE_WALK_CAP && Date.now() <= deadline) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort((a, b) => b.name.localeCompare(a.name))) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    stack.push(path);
+                continue;
+            }
+            if (!entry.isFile() || !isSourceFile(entry.name) || inProject.has(path))
+                continue;
+            visited++;
+            const text = index.text(path);
+            if (text === undefined || !text.includes(query.name))
+                continue;
+            for (const decl of index.declarations(path)) {
+                if (declMatches(decl, query))
+                    hits.push(decl);
+                if (hits.length >= max)
+                    break;
+            }
+            if (hits.length >= max)
+                break;
+        }
+    }
+    return hits.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+/** Nearest `tsconfig.json` from the directory of `abs` up to `root` (inclusive). */
+export function nearestTsconfig(abs, root) {
+    for (let dir = dirname(abs);; dir = dirname(dir)) {
+        const candidate = join(dir, "tsconfig.json");
+        if (existsSync(candidate))
+            return candidate;
+        if (dir === root || dirname(dir) === dir)
+            return undefined;
+    }
+}
 export function createSyntacticIndex(root, project) {
     const texts = new Map();
     const sources = new Map();
@@ -178,21 +248,9 @@ export function createSyntacticIndex(root, project) {
                     continue;
                 if (query.fuzzy ? !text.toLowerCase().includes(needle) : !text.includes(needle))
                     continue;
-                for (const decl of index.declarations(file)) {
-                    if (query.member !== undefined) {
-                        if (decl.parentName === undefined)
-                            continue;
-                        const parent = decl.parentName.split(".").pop();
-                        const ok = query.fuzzy
-                            ? parent.toLowerCase().includes(needle) && decl.name.toLowerCase().includes(query.member.toLowerCase())
-                            : parent === query.name && decl.name === query.member;
-                        if (ok)
-                            result.push(decl);
-                    }
-                    else if (query.fuzzy ? decl.name.toLowerCase().includes(needle) : decl.name === query.name) {
+                for (const decl of index.declarations(file))
+                    if (declMatches(decl, query))
                         result.push(decl);
-                    }
-                }
             }
             return result;
         },
@@ -271,28 +329,165 @@ export function createSemanticProject(index) {
         }
         return sites;
     };
+    const checker = program.getTypeChecker();
+    /** Deepest node whose span holds `pos`. */
+    const nodeAt = (sf, pos) => {
+        let node = sf;
+        for (;;) {
+            const child = ts.forEachChild(node, (c) => (c.getStart(sf) <= pos && pos < c.end ? c : undefined));
+            if (!child)
+                return node;
+            node = child;
+        }
+    };
+    const isMemberNode = (node) => ts.isMethodDeclaration(node) || ts.isMethodSignature(node) || ts.isPropertyDeclaration(node) || ts.isPropertySignature(node) ||
+        ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isPropertyAssignment(node);
+    const isTypeContainer = (node) => ts.isClassLike(node) || ts.isInterfaceDeclaration(node);
+    const memberAt = (fileName, pos) => {
+        const sf = program.getSourceFile(fileName);
+        if (!sf)
+            return undefined;
+        const parent = nodeAt(sf, pos).parent;
+        return parent && isMemberNode(parent) && parent.name.getStart(sf) === pos ? parent : undefined;
+    };
+    const memberKey = (member) => `${resolve(member.getSourceFile().fileName)}#${member.name.getStart(member.getSourceFile())}`;
+    const memberName = (member) => {
+        const owner = member.parent;
+        const ownerName = isTypeContainer(owner) && owner.name ? owner.name.text
+            : ts.isObjectLiteralExpression(owner) && ts.isVariableDeclaration(owner.parent) && ts.isIdentifier(owner.parent.name) ? owner.parent.name.text
+                : "(object)";
+        return `${ownerName}.${member.name.getText(member.getSourceFile())}`;
+    };
+    /** Keys of every member `member` implements or overrides, through extends/implements (transitively) or an object literal's contextual type. */
+    const basesOf = (member) => {
+        if (ts.isPrivateIdentifier(member.name))
+            return [];
+        const name = ts.isIdentifier(member.name) || ts.isStringLiteral(member.name) || ts.isNumericLiteral(member.name) ? member.name.text : undefined;
+        if (name === undefined)
+            return [];
+        const keys = new Set();
+        const seen = new Set();
+        const fromType = (type) => {
+            for (const decl of checker.getPropertyOfType(type, name)?.declarations ?? []) {
+                if (decl !== member && isMemberNode(decl))
+                    keys.add(memberKey(decl));
+            }
+            for (const decl of type.getSymbol()?.declarations ?? [])
+                if (isTypeContainer(decl))
+                    fromHeritage(decl);
+        };
+        const fromHeritage = (container) => {
+            if (seen.has(container))
+                return;
+            seen.add(container);
+            for (const clause of container.heritageClauses ?? [])
+                for (const t of clause.types)
+                    fromType(checker.getTypeAtLocation(t));
+        };
+        const owner = member.parent;
+        if (isTypeContainer(owner))
+            fromHeritage(owner);
+        else if (ts.isObjectLiteralExpression(owner)) {
+            const contextual = checker.getContextualType(owner);
+            if (contextual)
+                fromType(contextual);
+        }
+        return [...keys];
+    };
+    const split = (absFile, pos) => {
+        const groups = service.findReferences(absFile, pos) ?? [];
+        const descriptors = [];
+        let target = -1;
+        let flagged = -1;
+        for (const group of groups) {
+            const def = group.definition;
+            const member = memberAt(def.fileName, def.textSpan.start);
+            const bases = member ? basesOf(member) : [];
+            const typeMember = member !== undefined && (isTypeContainer(member.parent) || bases.length > 0);
+            const groupKey = member ? memberKey(member) : `${resolve(def.fileName)}#${def.textSpan.start}`;
+            const refs = [];
+            for (const ref of group.references) {
+                const loc = location(ref.fileName, ref.textSpan.start);
+                const refFile = resolve(ref.fileName);
+                if (refFile === resolve(absFile) && ref.textSpan.start <= pos && pos <= ref.textSpan.start + ref.textSpan.length && target < 0) {
+                    target = descriptors.length;
+                }
+                if (ref.isDefinition && flagged < 0)
+                    flagged = descriptors.length;
+                if (!loc)
+                    continue;
+                const sf = program.getSourceFile(ref.fileName);
+                const parent = nodeAt(sf, ref.textSpan.start).parent;
+                refs.push({
+                    key: `${loc.file}:${loc.line}:${loc.col}`,
+                    isDefinition: ref.isDefinition ?? false,
+                    atDefinition: `${refFile}#${ref.textSpan.start}` === groupKey,
+                    isSuper: parent !== undefined && ts.isPropertyAccessExpression(parent) && parent.expression.kind === ts.SyntaxKind.SuperKeyword,
+                    entry: { ...loc, isDefinition: ref.isDefinition ?? false, isWrite: ref.isWriteAccess },
+                    absFile: refFile,
+                    start: ref.textSpan.start,
+                });
+            }
+            descriptors.push({ key: groupKey, name: member ? memberName(member) : def.name, member: typeMember, bases, refs });
+        }
+        const index = target >= 0 ? target : Math.max(0, flagged);
+        const c = classifyReferenceGroups(descriptors, index);
+        const raw = new Map();
+        const buckets = new Map();
+        for (const d of descriptors)
+            for (const r of d.refs)
+                raw.set(r.key, r);
+        for (const r of [...c.direct, ...c.declarations])
+            buckets.set(r.key, "direct");
+        for (const v of c.via)
+            buckets.set(v.ref.key, "via");
+        for (const r of [...c.dropped, ...c.implementations.map((i) => i.ref)])
+            buckets.set(r.key, "dropped");
+        return {
+            result: {
+                direct: c.direct.map((r) => r.entry),
+                declarations: c.declarations.map((r) => ({ ...r.entry, isDefinition: true })),
+                via: c.via.map((v) => ({ ...v.ref.entry, via: v.via, through: v.through })),
+                implementations: c.implementations.map((i) => ({ ...i.ref.entry, name: i.name })),
+                dropped: c.dropped.map((r) => r.entry),
+                bases: c.bases,
+            },
+            raw,
+            buckets,
+        };
+    };
+    /** Call sites keyed against the reference split: direct and via kept, sibling calls dropped. */
+    const splitSites = (absFile, pos, calls) => {
+        const { result, raw, buckets } = split(absFile, pos);
+        const viaOf = new Map(result.via.map((v) => [`${v.file}:${v.line}:${v.col}`, v]));
+        const sites = [];
+        for (const call of calls) {
+            for (const span of call.fromSpans) {
+                const loc = location(call.from.file, span.start);
+                if (!loc)
+                    continue;
+                const file = resolve(call.from.file);
+                const hits = [...raw.values()].filter((r) => r.absFile === file && span.start <= r.start && r.start <= span.start + span.length);
+                const kinds = hits.map((h) => buckets.get(h.key));
+                if (kinds.length > 0 && !kinds.includes("direct") && !kinds.includes("via"))
+                    continue;
+                const viaHit = kinds.includes("direct") ? undefined : hits.find((h) => viaOf.has(h.key));
+                sites.push({ ...loc, caller: callerName(call.from), item: call.from, ...(viaHit ? { via: viaOf.get(viaHit.key).via, through: viaOf.get(viaHit.key).through } : {}) });
+            }
+        }
+        return sites;
+    };
     return {
         index,
         service,
         program,
         projectFiles,
         findReferences(absFile, pos) {
-            const groups = service.findReferences(absFile, pos) ?? [];
-            const seen = new Set();
-            const entries = [];
-            for (const group of groups) {
-                for (const ref of group.references) {
-                    const loc = location(ref.fileName, ref.textSpan.start);
-                    if (!loc)
-                        continue;
-                    const key = `${loc.file}:${loc.line}:${loc.col}`;
-                    if (seen.has(key))
-                        continue;
-                    seen.add(key);
-                    entries.push({ ...loc, isDefinition: ref.isDefinition ?? false, isWrite: ref.isWriteAccess });
-                }
-            }
-            return entries;
+            const { result } = split(absFile, pos);
+            return [...result.declarations, ...result.direct];
+        },
+        referenceSplit(absFile, pos) {
+            return split(absFile, pos).result;
         },
         definitionAt(absFile, pos) {
             const defs = service.getDefinitionAtPosition(absFile, pos) ?? [];
@@ -307,7 +502,7 @@ export function createSemanticProject(index) {
             const items = prepared === undefined ? [] : Array.isArray(prepared) ? prepared : [prepared];
             if (items.length === 0)
                 return undefined;
-            return items.flatMap((item) => toCallSites(service.provideCallHierarchyIncomingCalls(item.file, item.selectionSpan.start)));
+            return items.flatMap((item) => splitSites(item.file, item.selectionSpan.start, service.provideCallHierarchyIncomingCalls(item.file, item.selectionSpan.start)));
         },
         incomingCallsOf(item) {
             if (item.kind === ts.ScriptElementKind.scriptElement)

package/dist/src/references.js

@@ -0,0 +1,69 @@
+// Pure split of `findReferences` groups into direct / via / implementation / dropped.
+// The LanguageService resolves a class member through the interface or base member it
+// implements, so its result also holds sibling implementations and their call sites.
+// A position reported in several groups keeps its most specific bucket.
+const RANK = { direct: 0, declaration: 1, implementation: 2, via: 3, dropped: 4 };
+/**
+ * Rules: the target group is direct. When the target is a class/interface member, a group it
+ * implements/overrides (a base) is via, minus Declarations and `super` calls; a group that
+ * implements/overrides the target is an implementation (its Declaration) or via (its uses);
+ * any other member group is a sibling and dropped. Non-member groups (import aliases) are direct.
+ */
+export function classifyReferenceGroups(groups, targetIndex) {
+    const target = groups[targetIndex];
+    const best = new Map();
+    const put = (bucket, ref, name = "", through) => {
+        const prev = best.get(ref.key);
+        if (!prev || RANK[bucket] < RANK[prev.bucket])
+            best.set(ref.key, { bucket, ref, name, ...(through ? { through } : {}) });
+    };
+    const bases = new Set(target?.bases ?? []);
+    groups.forEach((group, i) => {
+        const isTarget = i === targetIndex;
+        const relation = isTarget || !target?.member || !group.member
+            ? "direct"
+            : bases.has(group.key)
+                ? "base"
+                : group.bases.includes(target.key)
+                    ? "derived"
+                    : "sibling";
+        for (const ref of group.refs) {
+            switch (relation) {
+                case "direct":
+                    put(ref.isDefinition || (isTarget && ref.atDefinition) ? "declaration" : "direct", ref);
+                    break;
+                case "base":
+                    put(ref.isDefinition || ref.atDefinition || ref.isSuper ? "dropped" : "via", ref, group.name, "base");
+                    break;
+                case "derived":
+                    if (ref.atDefinition)
+                        put("implementation", ref, group.name);
+                    else
+                        put("via", ref, group.name, "implementation");
+                    break;
+                default:
+                    put("dropped", ref);
+            }
+        }
+    });
+    const result = { direct: [], declarations: [], via: [], implementations: [], dropped: [], bases: [] };
+    for (const { bucket, ref, name, through } of best.values()) {
+        if (bucket === "direct")
+            result.direct.push(ref);
+        else if (bucket === "declaration")
+            result.declarations.push(ref);
+        else if (bucket === "via")
+            result.via.push({ ref, via: name, through: through });
+        else if (bucket === "implementation")
+            result.implementations.push({ ref, name });
+        else
+            result.dropped.push(ref);
+    }
+    result.bases = groups.filter((g, i) => i !== targetIndex && bases.has(g.key)).map((g) => g.name);
+    return result;
+}
+/** `7 (FieldParser.parse)`: a count with the distinct member names, no commas. */
+export function viaLine(count, names) {
+    const distinct = [...new Set(names)];
+    return distinct.length === 0 ? String(count) : `${count} (${distinct.join("; ")})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-axi",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AXI-compliant TypeScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (blast radius) with token-efficient TOON output",
   "type": "module",
   "keywords": [