ts-axi 0.1.17 → 0.1.19

package/README.md

@@ -58,11 +58,11 @@ Known limits: `.astro` / `.vue` / `.svelte` files are not analysed (they appear
 | task | repo | ts-axi tokens | grep tokens | ratio | recall |
 | --- | --- | ---: | ---: | ---: | --- |
 | def of a class method | astro sample | 117 | 266 | 0.44 | 100% (1/1) |
-| callers of a function | astro sample | 227 | 1169 | 0.19 | 100% (8/8) |
-| refs of a class member | astro sample | 216 | 1133 | 0.19 | 100% (8/8) |
-| impact of a signature change | astro sample | 737 | 1304 | 0.56 | 100% (14/14) |
+| callers of a function | astro sample | 204 | 1169 | 0.17 | 100% (8/8, 3 by count) |
+| refs of a class member | astro sample | 170 | 1133 | 0.15 | 100% (8/8, 5 by count) |
+| impact of a signature change | astro sample | 687 | 1304 | 0.53 | 100% (14/14) |
 | template uses of a directive | legacy-js | 409 | 289 | 1.42 | 100% (5/5) |
-| refs of an untyped CommonJS member | legacy-js | 387 | 401 | 0.96 | 100% (5/5) |
+| refs of an untyped CommonJS member | legacy-js | 369 | 401 | 0.92 | 100% (5/5, 2 by count) |
 
 - def of a class method is over 0.3 - the class file has 36 lines, so the grep side reads all of it once.
 - impact of a signature change is over 0.3 - the followed hint repeats the first output with the extra rows (refs on the changed function); impact alone is 0.33.
@@ -123,8 +123,8 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | --- | --- |
 | `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` and, when the name still occurs in the code, the `refs <name> --grep` that lists those textual matches. Before saying none, a name that is only a function-local Declaration (`local_to: Comp`) or only declared in a file the tsconfig leaves out (`project: outside (Deno edge/deno.json)`) is found syntactically and shown like a match |
-| `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` |
+| `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`. Rows in Test files come last and are collapsed to `test_refs[n]{file,count}` unless `--tests`. A property also names `same_name_members` (a DTO filled from an entity: same name, no Reference). `--limit`, `--kind calls`, `--via` (via rows with a `via` column), `--implementations`, `--tests` |
+| `callers <target>` | Incoming calls of a function-like symbol, split the same way (`via_interface`, `--via`). Only call expressions count: `x.fn.mockResolvedValue(...)` or `expect(x.fn)` are `not_calls: n` (listed by `refs`). Test rows collapse like `refs`. `--depth 1..3`, `--tests` |
 | `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. `--size` adds a `size` block (files, hunks at zero context, lines added and removed, patch characters, exported signature changes, removed symbols) for routing a review by diff size. Analyses the current checkout |
 | `anchor [<git-range> \| - \| --staged] <file:line[-end]>...` | Checks review-comment anchors: a line is commentable when the diff shows it (added or context; removed or context with `--side old`). Rows are `{anchor,ok,reason,symbol}`: a reason with the nearest hunk when not, and the enclosing Declaration (`Cart.total#method`) as a stable key for the finding. Git sources diff at `--context 3` (what Bitbucket and GitHub show); a stdin diff is used as given. `--fields in_diff,in_file,nearest,change,other_line` (or `all`). Exit 3 when any anchor is not ok, with the full output |
@@ -319,7 +319,7 @@ One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-
 - `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.
 - Module resolution keeps TypeScript's rules with two substitutions so References reach implementations: a `.d.ts` that has a JavaScript twin in the Project (`index.d.ts` beside `index.js`) resolves to the twin, and a CommonJS shim whose only statement is `module.exports = require('./x')` resolves to `./x`, so `require('..')` reaches the real function. A `.d.ts` twin that still ends up in the program is queried too and its References merged.
 - Script-style JavaScript (AngularJS registrations with their `this` / `var self = this` members and factory objects, ui-router states, Meteor methods and helpers, `module.exports` objects, prototype methods, IIFE helpers) gets nested declarations with qualified names, so `outline` lists them and `impact` names the function an edit touches instead of a file-level change.
-- Type errors in the analysed project never block anything; they are reported as a `diagnostics` count.
+- Type errors in the analysed project never block anything; they are reported as a `diagnostics` count (the whole Project up to 300 files, else the files with results). `--diagnostics` on `refs`, `callers` and `impact` lists them (`diagnostic_rows[n]{file,line,code,message}`, at most 20). They rarely change the result; an unresolved import can hide References.
 
 Every semantic command starts cold and prints `elapsed_ms`.
 
@@ -353,6 +353,7 @@ CI runs the first two on Node 22 and 24, the built CLI on Node 20, and the integ
 - [`mongo-rw-axi`](https://www.npmjs.com/package/mongo-rw-axi): Write-capable MongoDB CLI for agents, loopback hosts only
 - [`mysql-axi`](https://www.npmjs.com/package/mysql-axi): Read-only MySQL CLI for agents
 - [`mysql-rw-axi`](https://www.npmjs.com/package/mysql-rw-axi): Write-capable MySQL CLI for agents, loopback hosts only
+- [`secrets-axi`](https://www.npmjs.com/package/secrets-axi): Secrets guard CLI for agents
 <!-- axi-tools:end -->
 
 ## License

package/dist/src/commands/common.js

@@ -374,3 +374,24 @@ export function lineOf(text, line) {
     return lines[line - 1] ?? "";
 }
 export { clip, hasGlobMagic };
+const DIAGNOSTIC_ROWS = 20;
+/** Help text for `diagnostics` and `--diagnostics`, shared by refs, callers and impact. */
+export const DIAGNOSTICS_DOC = "diagnostics: n = TypeScript errors (syntax + type) in the analysed files - the whole Project up to 300 files, else the files with results; they rarely change the result, but an unresolved import there can hide References; --diagnostics lists them";
+/**
+ * `diagnostics: n`, plus `diagnostic_rows` under `--diagnostics`, or a hint to list them.
+ * `rerun` is the same command with `--diagnostics` added.
+ */
+export function diagnosticsFields(semantic, touched, show, rerun) {
+    if (!show) {
+        const n = semantic.diagnosticsCount(touched);
+        return n === 0 ? { fields: {}, help: [] } : { fields: { diagnostics: n }, help: [`Run \`${rerun}\` to list the ${n} TypeScript errors counted in diagnostics`] };
+    }
+    const rows = semantic.diagnostics(touched);
+    return {
+        fields: {
+            diagnostics: rows.length,
+            ...(rows.length > 0 ? { diagnostic_rows: rows.slice(0, DIAGNOSTIC_ROWS).map((d) => ({ file: d.file, line: d.line, code: `TS${d.code}`, message: clip(d.message, CONTEXT_MAX) })) } : {}),
+        },
+        help: rows.length > DIAGNOSTIC_ROWS ? [`Showing ${DIAGNOSTIC_ROWS} of ${rows.length} diagnostics; run \`tsc --noEmit\` in the Project for all`] : [],
+    };
+}

package/dist/src/commands/impact.js

@@ -14,7 +14,7 @@ import { isFunctionLike } from "../symbols.js";
 import { IMPACT_HOPS, scopeFields, scopeHelp, semanticFor } from "../scope.js";
 import { isTemplatePath, loadTemplates, templateTarget, templateUsages, usagesIn } from "../templates.js";
 import { walkFiles } from "../walk.js";
-import { contextOf, lineOf, open, projectFields } from "./common.js";
+import { contextOf, DIAGNOSTICS_DOC, diagnosticsFields, lineOf, open, projectFields } from "./common.js";
 import { outsideFiles } from "./miss.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
@@ -26,8 +26,8 @@ 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[9]:
-  --staged, --size (adds size{files,hunks,lines_added,lines_removed,patch_chars,exported_signature_changes,removed_symbols} - hunks are counted at zero context for a git source, as given for -; untracked files count as added),--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), --fields <kind,exported,refs_total,via,files,tests|all> (extra changed[n] columns), -P <tsconfig>, --json
+flags[10]:
+  --staged, --size (adds size{files,hunks,lines_added,lines_removed,patch_chars,exported_signature_changes,removed_symbols} - hunks are counted at zero context for a git source, as given for -; untracked files count as added),--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), --fields <kind,exported,refs_total,via,files,tests|all> (extra changed[n] columns), --diagnostics (lists the TypeScript errors behind diagnostics), -P <tsconfig>, --json
 output:
   base, head, changes (count), changed[n]{symbol,change,at,refs_outside} by default; --fields adds columns in place, --fields all gives {symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}
   change = signature | removed | type | added | body | modified (before unavailable) - riskiest first
@@ -42,6 +42,7 @@ output:
   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 (columns from --fields exported,tests)
   scope = in a monorepo without -P the program is the touched files + two levels of importers (scope_partial: true when capped)
+  ${DIAGNOSTICS_DOC}
 examples[6]:
   ts-axi impact
   ts-axi impact --staged
@@ -59,6 +60,7 @@ const SPECS = [
     { name: "--test-glob", repeatable: true },
     { name: "--fields" },
     { name: "--size", boolean: true },
+    { name: "--diagnostics", boolean: true },
     { name: "-P" },
 ];
 // Opt-in columns of changed[n]; the default keeps symbol, change, at, refs_outside.
@@ -458,7 +460,7 @@ function depthLevels(semantic, rows, depth) {
     let level = [];
     for (const row of rows) {
         if (row.live && isFunctionLike(row.kind))
-            level.push(...(semantic.incomingCalls(semantic.index.abs(row.live.file), row.live.namePos) ?? []));
+            level.push(...(semantic.incomingCalls(semantic.index.abs(row.live.file), row.live.namePos) ?? []).filter((s) => !s.notCall));
     }
     const visited = new Set();
     for (let d = 2; d <= depth; d++) {
@@ -469,7 +471,7 @@ function depthLevels(semantic, rows, depth) {
         level = [];
         for (const [key, site] of items) {
             visited.add(key);
-            level.push(...semantic.incomingCallsOf(site.item));
+            level.push(...semantic.incomingCallsOf(site.item).filter((s) => !s.notCall));
         }
         const counts = new Map();
         for (const site of level)
@@ -788,7 +790,7 @@ export async function impactCommand(args, ctx) {
         : [];
     const unresolved = grep ? withTemplateRows(textRows, rows, templateFiles ?? []) : [];
     const touched = [...new Set([...analysed.filter((f) => f.status !== "deleted").map((f) => f.path), ...listed.flatMap((r) => r.outside.map((e) => e.file))])];
-    const diagnostics = semantic.diagnosticsCount(touched);
+    const diagnostics = diagnosticsFields(semantic, touched, bool(parsed, "--diagnostics"), rerun(arg, parsed, "--diagnostics"));
     // --- Help ---
     const help = [];
     const top = listed.find((r) => r.live) ?? localOnly.find((r) => r.live);
@@ -827,6 +829,7 @@ export async function impactCommand(args, ctx) {
     if (specHint)
         help.push(specHint);
     help.push(...scopeHelp(scope));
+    help.push(...diagnostics.help);
     const notes = rows
         .filter((r) => r.change.change === "signature" && r.bases.length > 0)
         .map((r) => ({ symbol: r.symbol, note: `implements ${r.bases.join(" and ")}` }));
@@ -865,6 +868,6 @@ export async function impactCommand(args, ctx) {
         ...skippedBlock,
         ...scopeFields(scope),
         elapsed_ms: Math.round(performance.now() - started),
-        ...(diagnostics > 0 ? { diagnostics } : {}),
+        ...diagnostics.fields,
     }), helpBlock(help));
 }

package/dist/src/commands/refs.js

@@ -12,15 +12,19 @@ import { isOutside, missFallback, missRows, notSearched, outsideLine, outsideRea
 import { detectWorkspace, isMultiProject } from "../workspace.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget, registrationOf } from "../symbols.js";
-import { contextOf, declarationAt, filterSuffix, lineOf, MATCH_ROWS, matchRows, narrowHints, open, positionStartDir, projectFields, readFilters, useRef, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
+import { contextOf, declarationAt, DIAGNOSTICS_DOC, diagnosticsFields, filterSuffix, lineOf, MATCH_ROWS, matchRows, narrowHints, open, positionStartDir, projectFields, readFilters, useRef, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const DEPTH_ROWS = 50;
-const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --ref <rev> (read the code at a git revision; working tree ignored), --json`;
+const TEST_ROWS = 20;
+const SAME_NAME_ROWS = 5;
+const SHARED_FLAGS = `--tests (lists Test file rows after the others; default a per-file count), --diagnostics (lists the TypeScript errors behind diagnostics), --kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --ref <rev> (read the code at a git revision; working tree ignored), --json`;
 const VIA_DOC = `via_interface: n (Iface.member) = References through an interface or base member the Symbol implements or overrides - they MAY reach it; not in refs_total
   via_implementations: n (Impl.member) = References to implementations or overrides of the Symbol; not in refs_total
   implementations: n = members that implement or override the Symbol (their Declarations are never refs)
   matches: 0 under -P lists found_outside_project[n]{file,line} when the name is declared outside that Project
+  test_refs[n]{file,count} = rows in Test files, counted per file (biggest first, at most ${TEST_ROWS}); --tests lists them as rows after the others
+  ${DIAGNOSTICS_DOC}
   local_to: Comp = the name is a function-local Declaration (not indexed): its References from the declaring file
   matches: 0 + project: outside (...) = declared only in a file the tsconfig leaves out: outside_project + unresolved list its textual matches; the help position target runs the checker with the left-out files added (project: outside on that output)
   matches[n]{at,kind,name,where} = several function-local or left-out Declarations; pick one by its path:line:col
@@ -30,13 +34,14 @@ const VIA_DOC = `via_interface: n (Iface.member) = References through an interfa
   textual: n matches in m files = whole-word count of the name in Project files (JavaScript declarations and implicit projects; a state counts its full dotted name as a whole token, templates included; not for a state's resolve keys and hooks - injected by name, not imported); 'n matches in this file' only for a real local (a parameter, a binding inside a function or IIFE, a non-exported top-level binding of an ES module or of a CommonJS file whose module.exports never hands it out) - members, object properties and script globals count Project-wide; above refs_total = uses the checker cannot resolve - see refs --grep
   templates: n usages in m files = template uses (.html .htm .ejs .hbs .njk .pug) of a directive or component (<wap-select / wap-select / data-wap-select), its bindings (fallback-display-property= on that tag), a controller (ng-controller) or a filter (| money) - also for a function registered by identifier (.directive('fancyBox', fancyBox)), under the registered name; refs --grep lists them in unresolved`;
 export const REFS_HELP = `usage: ts-axi refs <name | Class.member | path:line[:col]> [flags]
-flags[13]:
+flags[15]:
   ${SHARED_FLAGS}
   --implementations (lists implementations[n]{file,line,symbol} instead of the count)
   --grep (adds unresolved[n]{file,line,context} - textual matches of the name that are not References; also searches .astro/.vue/.svelte/.mdx/.html)
   --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
+  symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,context} (Declarations excluded; non-test files first), elapsed_ms
+  same_name_members: n (Other.prop) = for a property - members of other types with the same name (a DTO filled from an entity); their References are not counted; the names are listed up to ${SAME_NAME_ROWS}
   ${VIA_DOC}
   note = the name is registered by a string ('Name' in .controller('Name', fn), or fn a same-file function named by identifier) - its uses are textual; add --grep
   matches: 0 = no Declaration of the name; help counts its whole-word matches in source files (left-out files too), and --grep lists them in unresolved with note 'no declaration found - textual matches only' (outside_project = the share in files the tsconfig leaves out)
@@ -49,11 +54,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[12]:
+flags[14]:
   ${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
+  symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,caller,context} (non-test files first), elapsed_ms
+  refs_total = calls only - the callee of a call, new, tagged template, decorator or JSX tag (fn.call/apply/bind count)
+  not_calls: n = References that are no call (mock setup like x.fn.mockResolvedValue; expect(x.fn); a callback passed on) - listed by refs
   caller = enclosing function or method; (top-level) for module code
   ${VIA_DOC}
 examples[3]:
@@ -74,6 +81,8 @@ async function run(args, ctx, invoked) {
         { name: "--limit" },
         { name: "--test-glob", repeatable: true },
         { name: "--via", boolean: true },
+        { name: "--tests", boolean: true },
+        { name: "--diagnostics", boolean: true },
         ...(invoked === "calls" ? [{ name: "--depth" }] : [{ name: "--implementations", boolean: true }, { name: "--grep", boolean: true }]),
     ];
     const parsed = parseArgs(args, specs, command);
@@ -90,6 +99,8 @@ async function run(args, ctx, invoked) {
         via: bool(parsed, "--via"),
         implementations: invoked === "refs" && bool(parsed, "--implementations"),
         grep: invoked === "refs" && bool(parsed, "--grep"),
+        tests: bool(parsed, "--tests"),
+        diagnostics: bool(parsed, "--diagnostics"),
     };
     const started = performance.now();
     ctx = useRef(ctx, parsed);
@@ -314,9 +325,57 @@ function summary(opened, rows) {
 function contextCell(opened, row) {
     return contextOf(lineOf(opened.index.text(opened.index.abs(row.file)), row.line), row.col);
 }
-function footer(semantic, started, touched) {
-    const diagnostics = semantic.diagnosticsCount(touched);
-    return { elapsed_ms: Math.round(performance.now() - started), ...(diagnostics > 0 ? { diagnostics } : {}) };
+function footer(semantic, o, touched, command) {
+    const d = diagnosticsFields(semantic, touched, o.show.diagnostics, diagnosticsRerun(o, command));
+    return { fields: { elapsed_ms: Math.round(performance.now() - o.started), ...d.fields }, help: d.help };
+}
+/**
+ * Non-test rows first. Without `--tests` the Test file rows leave the list and become
+ * `test_refs[n]{file,count}`, with a hint to list them.
+ */
+function testSplit(opened, rows, o, command) {
+    const isTest = new Map();
+    const testFile = (file) => {
+        if (!isTest.has(file))
+            isTest.set(file, isTestFile(file, opened.settings));
+        return isTest.get(file);
+    };
+    const prod = rows.filter((r) => !testFile(r.file));
+    const tests = rows.filter((r) => testFile(r.file));
+    if (o.show.tests || tests.length === 0)
+        return { listed: [...prod, ...tests], fields: {}, help: [] };
+    const counts = new Map();
+    for (const r of tests)
+        counts.set(r.file, (counts.get(r.file) ?? 0) + 1);
+    const perFile = [...counts].map(([file, count]) => ({ file, count })).sort((a, b) => b.count - a.count || a.file.localeCompare(b.file));
+    return {
+        listed: prod,
+        fields: { test_refs: perFile.slice(0, TEST_ROWS), ...(perFile.length > TEST_ROWS ? { test_refs_total: perFile.length } : {}) },
+        help: [`Run \`ts-axi ${command} ${o.declaredAt}${o.show.via ? " --via" : ""} --tests\` to list the ${tests.length} rows in Test files`],
+    };
+}
+/** Rerun with `--diagnostics` added. */
+function diagnosticsRerun(o, command) {
+    return `ts-axi ${command} ${o.declaredAt}${o.show.via ? " --via" : ""}${o.show.tests ? " --tests" : ""} --diagnostics`;
+}
+/** Properties of other types with the property's name: an entity field copied into a DTO is not a Reference. */
+function sameNameMembers(opened, o, known) {
+    const decl = o.decl;
+    if (!decl || decl.kind !== "property" || decl.parentName === undefined)
+        return { fields: {}, help: [] };
+    const names = [
+        ...new Set(opened.index
+            .findDeclarations({ name: decl.name })
+            .filter((d) => d.kind === "property" && d.parentName !== undefined && d.qualifiedName !== decl.qualifiedName && !known.has(d.qualifiedName))
+            .sort((a, b) => byDepthThenPath(a.file, b.file))
+            .map((d) => d.qualifiedName)),
+    ];
+    if (names.length === 0)
+        return { fields: {}, help: [] };
+    return {
+        fields: { same_name_members: names.length <= SAME_NAME_ROWS ? viaLine(names.length, names) : names.length },
+        help: names.length <= SAME_NAME_ROWS ? [`Run \`ts-axi refs ${names[0]}\` for References of the same-named ${names[0]}`] : [],
+    };
 }
 const NAMELESS_NOTE = "registered by a string - References to it are textual (templates; DI arrays; route configs)";
 /** `via_interface` / `via_implementations` counts, plus the hint to see their rows. */
@@ -358,15 +417,17 @@ function renderRefs(semantic, opened, resolved, header, o) {
     const via = sortRows([...split.via]);
     const impls = sortRows([...split.implementations]);
     const { files, tests, fileList } = summary(opened, rows);
-    const listed = mergedRows(rows, via, o.show);
+    const testRows = testSplit(opened, mergedRows(rows, via, o.show), o, "refs");
+    const listed = testRows.listed;
     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 ${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}; run \`ts-axi refs ${o.declaredAt}${o.show.via ? " --via" : ""}${o.show.tests ? " --tests" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`
             : `Showing ${shown.length} of ${listed.length}; narrow by reading one file at a time`);
     }
+    help.push(...testRows.help);
     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)
@@ -384,10 +445,14 @@ function renderRefs(semantic, opened, resolved, header, o) {
     else if (o.decl?.nameless && word && !o.show.grep && tpl.help.length === 0)
         help.unshift(`Run \`ts-axi refs ${o.declaredAt} --grep\` for textual matches of '${word}'`);
     help.unshift(...tpl.help);
+    const same = sameNameMembers(opened, o, new Set([...split.bases, ...via.map((v) => v.via), ...impls.map((i) => i.name)]));
+    help.push(...same.help);
     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`);
     help.push(...scopeHelp(o.scope));
+    const foot = footer(semantic, o, fileList, "refs");
+    help.push(...foot.help);
     return out(block({
         ...header,
         ...(o.decl?.nameless ? { note: NAMELESS_NOTE } : {}),
@@ -396,6 +461,7 @@ function renderRefs(semantic, opened, resolved, header, o) {
         ...tpl.fields,
         files,
         tests,
+        ...same.fields,
         ...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 }
@@ -411,11 +477,12 @@ function renderRefs(semantic, opened, resolved, header, o) {
                 })),
             }),
         ...(truncated ? { truncated: true } : {}),
+        ...testRows.fields,
         ...(o.show.grep ? { unresolved: grepRows.length === 0 ? 0 : grepRows.slice(0, o.limit) } : {}),
         ...(grepRows.length > o.limit ? { unresolved_total: grepRows.length } : {}),
         ...outside.fields,
         ...scopeFields(o.scope),
-        ...footer(semantic, o.started, fileList),
+        ...foot.fields,
     }), helpBlock(help));
 }
 function viaNames(via) {
@@ -435,7 +502,7 @@ function nextLevel(semantic, sites, visited) {
         if (visited.has(key))
             continue;
         visited.add(key);
-        next.push(...semantic.incomingCallsOf(site.item));
+        next.push(...semantic.incomingCallsOf(site.item).filter((s) => !s.notCall));
     }
     return next;
 }
@@ -456,7 +523,7 @@ function renderCallers(semantic, opened, resolved, header, o) {
         ? (() => {
             const split = semantic.referenceSplit(resolved.absFile, resolved.pos);
             const known = [...split.direct, ...split.declarations, ...split.via, ...split.implementations, ...split.dropped, ...(sites ?? [])];
-            const calls = (sites ?? []).filter((s) => s.via === undefined).length;
+            const calls = (sites ?? []).filter((s) => s.via === undefined && !s.notCall).length;
             return textualFields(o, calls, withTemplates(unresolvedOf(opened, semantic, o, known), o.templates).length, false);
         })()
         : { fields: {}, help: [] };
@@ -464,17 +531,23 @@ function renderCallers(semantic, opened, resolved, header, o) {
     callerText.fields = { ...callerText.fields, ...tpl.fields };
     callerText.help = [...tpl.help, ...callerText.help];
     if (sites === undefined) {
-        return out(block({ ...header, refs_total: 0, ...callerText.fields, note: "not callable - no call hierarchy for this Symbol", ...scopeFields(o.scope), ...footer(semantic, o.started, []) }), helpBlock([...callerText.help, `Run \`ts-axi refs ${o.declaredAt}\` for every Reference`]));
+        const foot = footer(semantic, o, [], "callers");
+        return out(block({ ...header, refs_total: 0, ...callerText.fields, note: "not callable - no call hierarchy for this Symbol", ...scopeFields(o.scope), ...foot.fields }), helpBlock([...callerText.help, `Run \`ts-axi refs ${o.declaredAt}\` for every Reference`, ...foot.help]));
     }
-    const rows = sortRows(sites.filter((s) => s.via === undefined));
-    const via = sortRows(sites.filter((s) => s.via !== undefined));
+    const notCalls = sites.filter((s) => s.notCall && s.via === undefined).length;
+    const calls = sites.filter((s) => !s.notCall);
+    const rows = sortRows(calls.filter((s) => s.via === undefined));
+    const via = sortRows(calls.filter((s) => s.via !== undefined));
     const { files, tests, fileList } = summary(opened, rows);
-    const listed = mergedRows(rows, via, o.show);
+    const merged = mergedRows(rows, via, o.show);
+    const testRows = testSplit(opened, merged, o, "callers");
+    const listed = testRows.listed;
     const shown = listed.slice(0, o.limit);
     const truncated = shown.length < listed.length;
     const levels = {};
     const visited = new Set();
-    let level = listed;
+    // Deeper levels start from every call, Test files included.
+    let level = merged;
     for (let d = 2; d <= o.depth; d++) {
         level = nextLevel(semantic, level, visited);
         const agg = depthRows(level);
@@ -486,8 +559,9 @@ function renderCallers(semantic, opened, resolved, header, o) {
     }
     const help = [];
     if (truncated) {
-        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`);
+        help.push(`Showing ${shown.length} of ${listed.length}; run \`ts-axi callers ${o.declaredAt}${o.show.via ? " --via" : ""}${o.show.tests ? " --tests" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`);
     }
+    help.push(...testRows.help);
     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)");
@@ -496,12 +570,17 @@ function renderCallers(semantic, opened, resolved, header, o) {
     const outside = rows.length === 0 ? outsideImporters(opened, o) : { fields: {}, help: [] };
     help.unshift(...outside.help);
     help.unshift(...callerText.help);
-    help.push(`Run \`ts-axi refs ${o.declaredAt}${o.decl?.nameless ? " --grep" : ""}\` for every Reference (not only calls)`);
+    help.push(notCalls > 0
+        ? `Run \`ts-axi refs ${o.declaredAt}${o.decl?.nameless ? " --grep" : ""}\` for the ${notCalls} not_calls with every other Reference`
+        : `Run \`ts-axi refs ${o.declaredAt}${o.decl?.nameless ? " --grep" : ""}\` for every Reference (not only calls)`);
     help.push(...scopeHelp(o.scope));
+    const foot = footer(semantic, o, fileList, "callers");
+    help.push(...foot.help);
     return out(block({
         ...header,
         ...(o.decl?.nameless ? { note: NAMELESS_NOTE } : {}),
         refs_total: rows.length,
+        ...(notCalls > 0 ? { not_calls: notCalls } : {}),
         ...callerText.fields,
         files,
         tests,
@@ -518,9 +597,10 @@ function renderCallers(semantic, opened, resolved, header, o) {
                 })),
             }),
         ...(truncated ? { truncated: true } : {}),
+        ...testRows.fields,
         ...levels,
         ...outside.fields,
         ...scopeFields(o.scope),
-        ...footer(semantic, o.started, fileList),
+        ...foot.fields,
     }), helpBlock(help));
 }

package/dist/src/project.js

@@ -452,7 +452,7 @@ export function createSemanticProject(index, scope) {
             for (const span of call.fromSpans) {
                 const loc = location(call.from.file, span.start);
                 if (loc)
-                    sites.push({ ...loc, caller: callerName(call.from), item: call.from });
+                    sites.push({ ...loc, caller: callerName(call.from), item: call.from, ...(isCallTarget(call.from.file, span.start) ? {} : { notCall: true }) });
             }
         }
         return sites;
@@ -468,6 +468,41 @@ export function createSemanticProject(index, scope) {
             node = child;
         }
     };
+    const CALL_FORWARDERS = new Set(["call", "apply", "bind"]);
+    const skipOuter = (node) => {
+        let n = node;
+        while (n.parent && (ts.isParenthesizedExpression(n.parent) || ts.isNonNullExpression(n.parent) || ts.isAsExpression(n.parent) || ts.isTypeAssertionExpression(n.parent) || ts.isSatisfiesExpression(n.parent)))
+            n = n.parent;
+        return n;
+    };
+    /**
+     * The Reference at `start` is what a call, `new`, tagged template, decorator or JSX tag invokes
+     * (`fn.call/apply/bind` count). The call hierarchy also reports any `x.method` property access.
+     */
+    const isCallTarget = (fileName, start) => {
+        const sf = program.getSourceFile(fileName);
+        if (!sf)
+            return true;
+        let n = nodeAt(sf, start);
+        const up = n.parent;
+        if (up && ((ts.isPropertyAccessExpression(up) && up.name === n) || (ts.isElementAccessExpression(up) && up.argumentExpression === n)))
+            n = up;
+        n = skipOuter(n);
+        const p = n.parent;
+        if (!p)
+            return false;
+        if ((ts.isCallExpression(p) || ts.isNewExpression(p)) && p.expression === n)
+            return true;
+        if ((ts.isTaggedTemplateExpression(p) && p.tag === n) || ts.isDecorator(p))
+            return true;
+        if ((ts.isJsxOpeningElement(p) || ts.isJsxSelfClosingElement(p)) && p.tagName === n)
+            return true;
+        if (ts.isPropertyAccessExpression(p) && p.expression === n && CALL_FORWARDERS.has(p.name.text)) {
+            const call = skipOuter(p).parent;
+            return call !== undefined && ts.isCallExpression(call) && skipOuter(p) === call.expression;
+        }
+        return false;
+    };
     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);
@@ -547,9 +582,91 @@ export function createSemanticProject(index, scope) {
         }
         return undefined;
     };
-    const split = (absFile, pos) => {
+    /** Where findReferences stops on CommonJS: a `module.exports` property of the Symbol, and the locals of `const { x } = require()`. */
+    const commonJsHop = (fileName, start) => {
+        const sf = program.getSourceFile(fileName);
+        if (!sf)
+            return undefined;
+        const id = nodeAt(sf, start);
+        if (!ts.isIdentifier(id))
+            return undefined;
+        const parent = id.parent;
+        if ((ts.isShorthandPropertyAssignment(parent) && parent.name === id) || (ts.isPropertyAssignment(parent) && parent.initializer === id)) {
+            return isModuleExportsObject(parent.parent) ? parent.name.getStart(sf) : undefined;
+        }
+        const element = ts.isBindingElement(parent) ? parent : undefined;
+        if (!element || !ts.isIdentifier(element.name) || !ts.isObjectBindingPattern(element.parent))
+            return undefined;
+        const decl = element.parent.parent;
+        if (!ts.isVariableDeclaration(decl) || !decl.initializer || !isRequireCall(decl.initializer))
+            return undefined;
+        return element.name.getStart(sf);
+    };
+    /** findReferences of the Symbol at `pos`, with the CommonJS hops of `commonJsHop` merged into the target group. */
+    const referenceGroups = (absFile, pos) => {
         const twin = declarationTwin(absFile, pos);
         const groups = [...(service.findReferences(absFile, pos) ?? []), ...(twin ? service.findReferences(twin.file, twin.pos) ?? [] : [])];
+        const covers = (r) => resolve(r.fileName) === resolve(absFile) && r.textSpan.start <= pos && pos <= r.textSpan.start + r.textSpan.length;
+        const target = groups.find((g) => g.references.some(covers));
+        if (!target)
+            return { groups, extra: [] };
+        const seen = new Set(groups.flatMap((g) => g.references.map((r) => `${resolve(r.fileName)}#${r.textSpan.start}`)));
+        const extra = [];
+        const hops = new Set();
+        const queue = [...target.references];
+        for (let i = 0; i < queue.length && i < 500; i++) {
+            const hop = commonJsHop(queue[i].fileName, queue[i].textSpan.start);
+            const hopKey = `${resolve(queue[i].fileName)}#${hop}`;
+            if (hop === undefined || hops.has(hopKey))
+                continue;
+            hops.add(hopKey);
+            for (const g of service.findReferences(queue[i].fileName, hop) ?? []) {
+                for (const r of g.references) {
+                    const key = `${resolve(r.fileName)}#${r.textSpan.start}`;
+                    // A renamed local (`{ x: y }`) declares `y`; its uses are the References.
+                    if (seen.has(key) || (r.isDefinition && resolve(r.fileName) === resolve(queue[i].fileName) && r.textSpan.start === hop && hop !== queue[i].textSpan.start))
+                        continue;
+                    seen.add(key);
+                    const entry = { ...r, isDefinition: false };
+                    extra.push(entry);
+                    queue.push(entry);
+                }
+            }
+        }
+        return { groups: extra.length === 0 ? groups : groups.map((g) => (g === target ? { ...g, references: [...g.references, ...extra] } : g)), extra };
+    };
+    /** Call sites among CommonJS-hop References; call hierarchy does not reach a destructured `require()` local. */
+    const commonJsCalls = (refs) => {
+        const sites = [];
+        for (const ref of refs) {
+            const sf = program.getSourceFile(ref.fileName);
+            const loc = location(ref.fileName, ref.textSpan.start);
+            if (!sf || !loc)
+                continue;
+            const id = nodeAt(sf, ref.textSpan.start);
+            const call = id.parent;
+            if (!(ts.isCallExpression(call) || ts.isNewExpression(call)) || call.expression !== id)
+                continue;
+            const item = enclosingItem(sf, call);
+            sites.push({ ...loc, caller: callerName(item), item });
+        }
+        return sites;
+    };
+    /** Call hierarchy item of the nearest named function around `node`, else the file itself. */
+    const enclosingItem = (sf, node) => {
+        for (let n = node.parent; n && !ts.isSourceFile(n); n = n.parent) {
+            if (!ts.isFunctionLike(n))
+                continue;
+            const prepared = service.prepareCallHierarchy(sf.fileName, n.getStart(sf));
+            const item = Array.isArray(prepared) ? prepared[0] : prepared;
+            if (item && item.kind !== ts.ScriptElementKind.scriptElement)
+                return item;
+        }
+        const span = { start: 0, length: sf.end };
+        return { name: sf.fileName, kind: ts.ScriptElementKind.scriptElement, file: sf.fileName, span, selectionSpan: span };
+    };
+    const split = (absFile, pos) => {
+        const { groups } = referenceGroups(absFile, pos);
         const descriptors = [];
         let target = -1;
         let flagged = -1;
@@ -626,11 +743,29 @@ export function createSemanticProject(index, scope) {
                 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 } : {}) });
+                sites.push({
+                    ...loc,
+                    caller: callerName(call.from),
+                    item: call.from,
+                    ...(isCallTarget(call.from.file, span.start) ? {} : { notCall: true }),
+                    ...(viaHit ? { via: viaOf.get(viaHit.key).via, through: viaOf.get(viaHit.key).through } : {}),
+                });
             }
         }
         return sites;
     };
+    // A subgraph program mixes projects under one set of options: only the touched files count there.
+    const diagnosticsOf = (touched) => {
+        const files = !scope && projectFiles.length <= FULL_DIAGNOSTICS_LIMIT ? projectFiles : touched.map((f) => index.abs(f));
+        const result = [];
+        for (const file of files) {
+            const sf = program.getSourceFile(file);
+            if (!sf)
+                continue;
+            result.push(...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf));
+        }
+        return result;
+    };
     return {
         index,
         service,
@@ -661,6 +796,7 @@ export function createSemanticProject(index, scope) {
             const seen = new Set();
             return items
                 .flatMap((item) => splitSites(item.file, item.selectionSpan.start, [...service.provideCallHierarchyIncomingCalls(item.file, item.selectionSpan.start), ...twinCalls]))
+                .concat(commonJsCalls(referenceGroups(absFile, pos).extra))
                 .filter((site) => {
                 const key = `${site.file}:${site.line}:${site.col}`;
                 return !seen.has(key) && Boolean(seen.add(key));
@@ -675,16 +811,18 @@ export function createSemanticProject(index, scope) {
             return service.getQuickInfoAtPosition(absFile, pos);
         },
         diagnosticsCount(touched = []) {
-            // A subgraph program mixes projects under one set of options: count the touched files only.
-            const files = !scope && projectFiles.length <= FULL_DIAGNOSTICS_LIMIT ? projectFiles : touched.map((f) => index.abs(f));
-            let count = 0;
-            for (const file of files) {
-                const sf = program.getSourceFile(file);
-                if (!sf)
-                    continue;
-                count += program.getSyntacticDiagnostics(sf).length + program.getSemanticDiagnostics(sf).length;
-            }
-            return count;
+            return diagnosticsOf(touched).length;
+        },
+        diagnostics(touched = []) {
+            return diagnosticsOf(touched).map((d) => {
+                const lc = d.file?.getLineAndCharacterOfPosition(d.start ?? 0);
+                return {
+                    file: d.file ? index.rel(resolve(d.file.fileName)) : "-",
+                    line: lc ? lc.line + 1 : 0,
+                    code: d.code,
+                    message: ts.flattenDiagnosticMessageText(d.messageText, " "),
+                };
+            });
         },
         elapsedMs: () => Math.round(performance.now() - started),
     };
@@ -726,3 +864,20 @@ export function openProject(cwd, options = {}) {
     const index = createSyntacticIndex(root, project);
     return { cwd, root, location, index, ...(project.implicit ? { warning: IMPLICIT_WARNING } : {}) };
 }
+/** The object of `module.exports = {...}`. */
+function isModuleExportsObject(node) {
+    if (!ts.isObjectLiteralExpression(node))
+        return false;
+    let assign = node.parent;
+    while (ts.isParenthesizedExpression(assign))
+        assign = assign.parent;
+    if (!ts.isBinaryExpression(assign) || assign.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return false;
+    const left = assign.left;
+    return ts.isPropertyAccessExpression(left) && ts.isIdentifier(left.expression) && left.expression.text === "module" && left.name.text === "exports";
+}
+function isRequireCall(expr) {
+    while (ts.isParenthesizedExpression(expr))
+        expr = expr.expression;
+    return ts.isCallExpression(expr) && ts.isIdentifier(expr.expression) && expr.expression.text === "require" && expr.arguments.length === 1;
+}

package/dist/src/symbols.js

@@ -441,6 +441,10 @@ export function collectDeclarations(sf, file) {
                     nested({ start: prop.getStart(sf), end: prop.end, kind: "method", name, parentName: holder, exported, signature: headUntil(prop, fn, sf), namePos: prop.name.getStart(sf) });
                 else if (scope && ts.isIdentifier(value))
                     aliasedMember(scope, value, name, holder, exported, prop.name);
+                else if (holder === "exports" && !ts.isIdentifier(value)) {
+                    // `module.exports = { x: make(...) }`: the property is the only Declaration a destructured require can reach.
+                    nested({ start: prop.getStart(sf), end: prop.end, kind: "property", name, parentName: holder, exported, signature: clip(tokenText(prop, sf, prop.getStart(sf), prop.end)), namePos: prop.name.getStart(sf) });
+                }
             }
             else if (scope && ts.isShorthandPropertyAssignment(prop)) {
                 aliasedMember(scope, prop.name, name, holder, exported, prop.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-axi",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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": [