ts-axi 0.1.4 → 0.1.5

package/README.md

@@ -37,7 +37,17 @@ help[5]:
 
 Read-only: no lint, no refactor, no rename.
 
-> **Status: early (v0.1.x).**
+## Status (v0.1.4)
+
+Early, but already used in real reviews. What the numbers say so far:
+
+- **Correctness on the test corpus.** 152 unit and command tests over five synthetic fixtures (a TS project with an interface and three implementations, an Nx-style workspace with `tsconfig.base.json` paths and a pnpm workspace, a script-style JavaScript tree, a CommonJS package and an ESM package without tsconfig), plus 39 integration tests that run the built binary against a vendored Astro + React one-pager (`test/integration/sample`: barrel re-exports, JSX islands, custom hooks, a JS consumer of a TS export, a `.ts-axi.json` test glob). They pin exact line numbers, reference counts, test counts, change classes and the interface split.
+- **A real monorepo** (Nx, 142 projects, ~5.4k source files after gitignore): `refs` on a service method finds its two callers in *another* project in 3-5 s without any flag; `impact` on a 7-file commit reports 15 changes with cross-project references in ~5 s; `callers` on a method that implements an interface shared by seven classes reports the 1 direct call plus the spec calls, where the raw compiler API returned 8 unrelated implementations. Before the workspace scope, the same `impact` ran out of memory.
+- **Against grep, in characters an agent has to read** (same monorepo, measured by a reviewer session): `callers` 720 vs ~3.5k for the two greps a reviewer needs - and grep still leaves the interface ambiguity to the human; `impact` on a commit 4.7k vs ~7.3k for per-symbol greps plus the `git show --stat` needed to learn the symbol list. `def` on a very common name was *worse* than grep until nested git worktrees were excluded (96 matches, 92 of them copies); it is 4 now.
+
+- **Plain JavaScript** (no tsconfig, measured on two public packages): on p-limit (ESM, `index.js` beside `index.d.ts`) `refs pLimit` went from 1 to 48 References, 35 of them in `test.js`, which now counts as a Test file; on express (CommonJS, `index.js` = `module.exports = require('./lib/express')`) `callers createApplication` went from 2 call sites in 2 files to 678 in 94 files, 67 of them Test files (every one of the 22 test files that does `require('..')` included). The rule: References are semantic wherever the checker can follow them, and every Symbol declared in JavaScript (or in an implicit project) also prints `textual: <n> matches in <m> files`; when the text names it more often than the checker found, `help` points at `--grep` for the rest. `refs app.render` on express is the honest case: the method sits on an untyped expando object, the checker finds 0 References, and the output says `textual: 132 matches in 21 files` with the `--grep` hint instead of a bare 0; `impact` adds a `textual` column for such a Change rather than calling it local-only.
+
+Known limits: `.astro` / `.vue` / `.svelte` files are not analysed (they appear under `skipped`, and `--grep` searches them textually); every semantic command starts cold (0.3 s on a small project, 2-5 s on the monorepo, dominated by the library `.d.ts` files that barrels pull in); import specifiers are extracted textually, so computed specifiers and bundler-only aliases are missed.
 
 ## Install
 
@@ -73,7 +83,99 @@ npx skills add cmosgh/ts-axi --skill ts-axi
 
 `ts-axi <command> --help` prints a concise, complete flag reference. `-P <tsconfig>` selects a project on any command that may analyse types; `--json` prints the decoded payload.
 
-<!-- TODO(phase 4): paste real examples for def / refs / outline / config from the fixture project. -->
+### A review, end to end
+
+```sh
+ts-axi                                  # which project, how many files, how many are tests
+ts-axi impact main...HEAD               # what the branch changes and who depends on it
+ts-axi callers src/lib/format.ts:5      # the risky symbol: every call site with its enclosing function
+ts-axi def src/lib/cart.ts:32           # read one declaration, numbered for inline comments
+ts-axi outline src/lib/cart.ts          # the rest of the file, without reading it
+```
+
+Real output from the sample project (`test/integration/sample`):
+
+```
+$ ts-axi callers formatPrice
+symbol: formatPrice
+kind: function
+declared_at: "src/lib/format.ts:5"
+refs_total: 7
+files: 6
+tests: 2
+refs[7]{file,line,caller,context}:
+  src/components/Counter.tsx,12,Counter,"{cups} cups = {formatPrice(cups * CUP_CENTS)}"
+  src/components/ProductCard.tsx,13,ProductCard,"<p>{formatPrice(item.priceCents)}</p>"
+  src/lib/analytics.js,4,trackPurchase,"return { event: 'purchase', value: formatPrice(cents, 'EUR') };"
+  src/lib/cart.it.ts,8,(top-level),expect(cart.total()).toBe(formatPrice(3700));
+  src/lib/cart.ts,34,Cart.total,return formatPrice(cents);
+  src/lib/format.test.ts,6,(top-level),expect(formatPrice(1850)).toBe('18.50 USD');
+  src/lib/format.test.ts,9,(top-level),"expect(formatPrice(305, 'EUR')).toBe('3.05 EUR');"
+elapsed_ms: 549
+```
+
+```
+$ ts-axi def Cart.total
+file: src/lib/cart.ts
+line: 32
+kind: method
+exported: true
+signature: "total(): string"
+body:
+---
+  32 |   total(): string {
+  33 |     const cents = this.items.reduce((sum, i) => sum + i.priceCents * i.qty, 0);
+  34 |     return formatPrice(cents);
+  35 |   }
+---
+```
+
+The line numbers in front of the body are file lines, so an agent can cite or comment on them directly. An ambiguous name lists the candidates and the exact commands that narrow them:
+
+```
+$ ts-axi def parse
+symbol: parse
+matches[2]{file,line,kind,exported,signature}:
+  src/lib/parse.ts,1,function,true,"export function parse(input: string): number"
+  src/lib/query.ts,1,function,true,"export function parse(q: string): Record<string, string>"
+help[4]:
+  - "Run `ts-axi def src/lib/parse.ts:1` for the one in src/lib/parse.ts"
+  - "Run `ts-axi def src/lib/query.ts:1` for the one in src/lib/query.ts"
+  ...
+```
+
+### Interfaces are not conflated
+
+`findReferences` in the compiler resolves a call like `parser.parse(raw)` (with `parser: FieldParser`) to every implementation of `parse`, and lists the other implementations' declarations as references. For a review that inflates the blast radius badly. ts-axi keeps the split:
+
+```
+$ ts-axi callers DateParser.parse
+symbol: DateParser.parse
+refs_total: 1
+via_interface: 1 (FieldParser.parse)
+refs[1]{file,line,caller,context}:
+  src/services/dates.ts,4,dayOf,return new DateParser().parse(x);
+
+$ ts-axi refs FieldParser.parse
+refs_total: 1
+via_implementations: 1 (DateParser.parse)
+implementations: 3
+refs[1]{file,line,context}:
+  src/parsers/registry.ts,5,return parser.parse(raw);
+```
+
+### Script-style JavaScript
+
+```
+$ ts-axi outline client/app.js
+decls[4]{line,kind,name,exported,signature}:
+  6,function,CartCtrl,true,"controller CartCtrl($scope, priceService)"
+  12,function,priceService,true,service priceService()
+  13,method,priceService.sum,true,this.sum = function (items)
+  17,function,cartBadge,true,directive cartBadge()
+```
+
+An edit inside `CartCtrl` is reported by `impact` as `CartCtrl body`, not as a file-level change. Names registered by a string have no identifier the checker can follow; `refs` says so and offers `--grep`.
 
 ## Monorepos
 
@@ -91,7 +193,7 @@ Files are listed with `git ls-files` (tracked plus untracked, gitignore applied)
 
 ## Test files
 
-A file counts as a test by path pattern. Defaults: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/e2e/**`. The home view shows `test_globs` and `test_files` so a wrong rule is visible.
+A file counts as a test by path pattern. Defaults: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/e2e/**`, `**/spec/**`, `**/test.*`, `**/*_test.*`. The home view shows `test_globs` and `test_files` so a wrong rule is visible.
 
 ## `.ts-axi.json`
 
@@ -116,6 +218,7 @@ One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-
 - `outline`, `def` and the home view only parse files (`ts.createSourceFile`): no tsconfig needed, well under a second.
 - `refs`, `callers` and `impact` build a `LanguageService` over the nearest `tsconfig.json` (or an implicit project of every source file when none exists, with a warning; in a monorepo or an implicit project of more than 3000 files, over the importer subgraph described above) and ask it for references and call hierarchy. Symbol identity comes from the checker, so `user.save` resolves to `User.save` through imports and re-exports.
 - `impact` reads the "before" version of touched files with `git show` and compares signatures to classify each change (`added`, `removed`, `signature`, `body`, `type`, `modified`). Uses it cannot follow (access through `any`, dynamic string keys) are reported as `blind_spots`, never silently dropped.
+- 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, 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.
 
@@ -128,7 +231,17 @@ corepack pnpm install
 corepack pnpm run check   # typecheck, tests, build, skill freshness
 ```
 
-`skills/ts-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec and `GLOSSARY.md` for the vocabulary.
+`skills/ts-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec, `GLOSSARY.md` for the vocabulary and `docs/adr/` for the two engine decisions (TypeScript LanguageService over ts-morph / tree-sitter; importer subgraph over a configured project list).
+
+### Tests
+
+| Suite | Runs | Covers |
+| --- | --- | --- |
+| `test/unit.test.ts`, `test/workspace.test.ts` | `pnpm test` | target parsing, signatures, change classification, diff parsing, settings, glob matching, reference classification, workspace detection, import resolution |
+| `test/commands.test.ts` | `pnpm test` | the whole CLI through `main()` over five fixtures copied to temp git repos: `test/fixtures/project` (TS, interface + implementations, barrel, JS consumer, `any` access), `test/fixtures/workspace` (Nx + pnpm workspace, `paths`, references-only tsconfigs), `test/fixtures/legacy-js` (AngularJS, Meteor, prototype, IIFE, CommonJS), `test/fixtures/commonjs` (`require('..')` shim, expando methods, `.d.ts` twin), `test/fixtures/esm-js` (`"type": "module"`, `index.js` + `index.d.ts`) |
+| `test/integration/*.test.ts` | `pnpm run test:integration` | the built binary against the vendored Astro + React sample in `test/integration/sample` (installs its own dependencies once; copied to a temp git repo per run, see `test/integration/README.md`) |
+
+CI runs the first two on Node 22 and 24, the built CLI on Node 20, and the integration suite on Node 24.
 
 ## License
 

package/dist/src/commands/impact.js

@@ -28,6 +28,7 @@ flags[7]:
 output:
   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
+  textual = column added only when an untyped (JavaScript; implicit project) Symbol has more whole-word matches outside the change set than refs_outside - those are uses the checker cannot resolve; - for typed rows; such a Change is never local_only
   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)
@@ -254,6 +255,33 @@ export function textualMatches(opened, semantic, names, known, skipLines, change
     }
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
 }
+/** The checker may miss uses: JS declaring file, a string-registered name, or no tsconfig at all. */
+export function isUntyped(opened, decl, file) {
+    return decl?.nameless === true || opened.index.project.implicit || (file !== undefined && /\.[mc]?jsx?$/.test(file));
+}
+/** Whole-word occurrences of `name` in Project files outside `changeSet`; lines declaring a `name` excluded. */
+export function textualCount(opened, name, changeSet = new Map()) {
+    let matches = 0;
+    let files = 0;
+    for (const abs of opened.index.files) {
+        const text = opened.index.text(abs);
+        if (text === undefined || !text.includes(name))
+            continue;
+        const rel = opened.index.rel(abs);
+        const declared = new Set(opened.index.declarations(abs).filter((d) => d.name === name).map((d) => d.nameLine));
+        const n = wordMatches(text, name).filter((m) => !declared.has(m.line) && !inRanges(changeSet.get(rel), m.line)).length;
+        matches += n;
+        if (n > 0)
+            files++;
+    }
+    return { matches, files };
+}
+export function textualLine(count) {
+    return `${count.matches} matches in ${count.files} files`;
+}
+export function textualHint(command, gap) {
+    return `Run \`${command}\` for the ${gap} textual matches the checker cannot resolve (untyped JavaScript)`;
+}
 function siteKey(site) {
     return `${site.item.file}#${site.item.selectionSpan.start}`;
 }
@@ -464,8 +492,17 @@ export async function impactCommand(args, ctx) {
         row.all = entries.filter((e) => !e.isDefinition);
         row.outside = row.all.filter((e) => !inRanges(changeSet.get(e.file), e.line)).sort(byPosition);
     }
+    for (const row of rows) {
+        if (!row.live || !isUntyped(opened, row.live, row.live.file))
+            continue;
+        row.textual = textualCount(opened, row.live.name, changeSet);
+        if (row.textual.matches > 0)
+            row.unresolved = textualMatches(opened, semantic, [row.live.name], known, new Set(), changeSet).length;
+    }
+    // Textual matches the checker did not resolve: such a Change is never local_only.
+    const textualGap = (r) => (r.textual && r.textual.matches > r.outside.length ? r.unresolved ?? 0 : 0);
     const shownRefs = (r) => (showVia ? [...r.outside, ...r.via].sort(byPosition) : r.outside);
-    const hasOutside = (r) => r.outside.length > 0 || r.via.length > 0;
+    const hasOutside = (r) => r.outside.length > 0 || r.via.length > 0 || textualGap(r) > 0;
     const listed = rows
         .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 }));
@@ -513,7 +550,10 @@ export async function impactCommand(args, ctx) {
         help.push(`${removedTop.symbol} was removed but is still referenced - those files break`);
     if (truncated)
         help.push(`Showing ${refRows.length} of ${outsideTotal} ref rows; run \`${rerun(arg, parsed, `--limit ${Math.min(MAX_LIMIT, outsideTotal)}`)}\` for more`);
-    if (spots.length > 0 && !grep)
+    const gap = listed.reduce((n, r) => n + textualGap(r), 0);
+    if (gap > 0 && !grep)
+        help.unshift(textualHint(rerun(arg, parsed, "--grep"), gap));
+    if (spots.length > 0 && !grep && gap === 0)
         help.push(`Run \`${rerun(arg, parsed, "--grep")}\` for textual matches the checker cannot see`);
     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`);
@@ -543,9 +583,10 @@ export async function impactCommand(args, ctx) {
                     refs_total: r.all.length,
                     refs_outside: r.outside.length,
                     via: r.via.length,
+                    ...(gap > 0 ? { textual: r.textual ? r.textual.matches : "-" } : {}),
                     ...fileCounts(r),
                 })),
-                refs: refRows,
+                ...(refRows.length > 0 ? { refs: refRows } : {}),
             }
             : {}),
         ...(truncated ? { truncated: true, refs_shown: refRows.length, refs_outside_total: outsideTotal } : {}),

package/dist/src/commands/refs.js

@@ -1,7 +1,7 @@
 import { relative, sep } from "node:path";
 import { bool, expectPositionals, flag, intFlag, parseArgs } from "../args.js";
 import { importerClosure } from "../importers.js";
-import { textualMatches } from "./impact.js";
+import { isUntyped, textualCount, textualHint, textualLine, textualMatches } from "./impact.js";
 import { findOutsideProject, nearestTsconfig } from "../project.js";
 import { viaLine } from "../references.js";
 import { block, helpBlock, out } from "../render.js";
@@ -21,7 +21,8 @@ const VIA_DOC = `via_interface: n (Iface.member) = References through an interfa
   matches: 0 under -P lists found_outside_project[n]{file,line} when the name is declared outside that Project
   refs_total: 0 under -P in a workspace lists found_outside_project[n]{file,line} = importers outside that Project
   scope = in a monorepo without -P the program is the declaring file + its importers (scope_partial: true when the importer scan was capped)
-  tsconfig: x (n referenced configs) = a references-only tsconfig expanded to the configs it references`;
+  tsconfig: x (n referenced configs) = a references-only tsconfig expanded to the configs it references
+  textual: n matches in m files = whole-word count of the name in Project files (JavaScript declarations and implicit projects); above refs_total = uses the checker cannot resolve - see refs --grep`;
 export const REFS_HELP = `usage: ts-axi refs <name | Class.member | path:line[:col]> [flags]
 flags[12]:
   ${SHARED_FLAGS}
@@ -146,7 +147,9 @@ 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, ...projectFields(opened), symbol, kind, declared_at: declaredAt };
     const explicit = Boolean(project || opened.settings.project);
-    const o = { started, symbol, declaredAt, show, scope, explicit, label, name, absFile: resolved.absFile, ...(decl ? { decl } : {}) };
+    const declaredFile = decl?.file ?? (def && def.line > 0 ? def.file : undefined);
+    const textual = declaredFile !== undefined && isUntyped(opened, decl, declaredFile) ? textualCount(opened, symbol.split(".").pop()) : undefined;
+    const o = { started, symbol, declaredAt, show, scope, explicit, label, name, absFile: resolved.absFile, ...(decl ? { decl } : {}), ...(textual ? { textual } : {}) };
     return mode === "calls"
         ? renderCallers(semantic, opened, resolved, header, { ...o, limit, depth })
         : renderRefs(semantic, opened, resolved, header, { ...o, limit, kind });
@@ -210,6 +213,23 @@ function viaFields(via, bases) {
         ...(impl.length > 0 ? { via_implementations: viaLine(impl.length, impl.map((v) => v.via)) } : {}),
     };
 }
+/** Whole-word matches of the name on lines that hold no known position (what `--grep` lists). */
+function unresolvedOf(opened, semantic, o, known) {
+    return textualMatches(opened, semantic, [o.symbol.split(".").pop()], new Set(known.map((r) => `${r.file}:${r.line}`)), new Set(o.decl ? [`${o.decl.file}:${o.decl.line}`, `${o.decl.file}:${o.decl.nameLine}`] : []), new Map());
+}
+/**
+ * `textual` field and, when the name occurs more often than refs_total and some matches sit on no
+ * Reference line (`unresolved` = the `--grep` rows), the `--grep` hint.
+ */
+function textualFields(o, refsTotal, unresolved, grepShown) {
+    if (!o.textual)
+        return { fields: {}, help: [] };
+    const gap = o.textual.matches > refsTotal ? unresolved : 0;
+    return {
+        fields: { textual: textualLine(o.textual) },
+        help: gap > 0 && !grepShown ? [textualHint(`ts-axi refs ${o.declaredAt} --grep`, gap)] : [],
+    };
+}
 /** Direct rows, plus via rows (with a `via` column) under `--via`. */
 function mergedRows(direct, via, show) {
     return show.via ? sortRows([...direct, ...via]) : direct;
@@ -236,10 +256,11 @@ function renderRefs(semantic, opened, resolved, header, o) {
     const outside = rows.length === 0 ? outsideImporters(opened, o) : { fields: {}, help: [] };
     help.unshift(...outside.help);
     const word = o.symbol.split(".").pop();
-    const unresolved = o.show.grep
-        ? textualMatches(opened, semantic, [word], new Set([...rows, ...via, ...impls].map((r) => `${r.file}:${r.line}`)), new Set(o.decl ? [`${o.decl.file}:${o.decl.line}`, `${o.decl.file}:${o.decl.nameLine}`] : []), new Map())
-        : [];
-    if (o.decl?.nameless && !o.show.grep)
+    const unresolved = o.show.grep || o.textual ? unresolvedOf(opened, semantic, o, [...rows, ...via, ...impls]) : [];
+    const text = textualFields(o, rows.length, unresolved.length, o.show.grep);
+    if (text.help.length > 0)
+        help.unshift(...text.help);
+    else if (o.decl?.nameless && !o.show.grep)
         help.unshift(`Run \`ts-axi refs ${o.declaredAt} --grep\` for textual matches of '${word}'`);
     if (isFunctionLike(o.kind))
         help.push(`Run \`ts-axi callers ${o.declaredAt}\` for call sites with their enclosing function`);
@@ -249,6 +270,7 @@ function renderRefs(semantic, opened, resolved, header, o) {
         ...header,
         ...(o.decl?.nameless ? { note: NAMELESS_NOTE } : {}),
         refs_total: rows.length,
+        ...text.fields,
         files,
         tests,
         ...viaFields(via, split.bases),
@@ -306,8 +328,17 @@ function depthRows(sites) {
 }
 function renderCallers(semantic, opened, resolved, header, o) {
     const sites = semantic.incomingCalls(resolved.absFile, resolved.pos);
+    // Every Reference line counts as known: the gap is what `refs --grep` would list.
+    const callerText = o.textual
+        ? (() => {
+            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;
+            return textualFields(o, calls, unresolvedOf(opened, semantic, o, known).length, false);
+        })()
+        : { fields: {}, help: [] };
     if (sites === undefined) {
-        return out(block({ ...header, refs_total: 0, note: "not callable - no call hierarchy for this Symbol", ...scopeFields(o.scope), ...footer(semantic, o.started, []) }), helpBlock([`Run \`ts-axi refs ${o.declaredAt}\` for every Reference`]));
+        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 rows = sortRows(sites.filter((s) => s.via === undefined));
     const via = sortRows(sites.filter((s) => s.via !== undefined));
@@ -338,12 +369,14 @@ function renderCallers(semantic, opened, resolved, header, o) {
         help.push(`Run \`ts-axi callers ${o.declaredAt} --depth 2\` for who calls the callers`);
     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(...scopeHelp(o.scope));
     return out(block({
         ...header,
         ...(o.decl?.nameless ? { note: NAMELESS_NOTE } : {}),
         refs_total: rows.length,
+        ...callerText.fields,
         files,
         tests,
         ...viaFields(via, []),

package/dist/src/project.js

@@ -72,6 +72,10 @@ function isSourceFile(name) {
 export function walkSourceFiles(root) {
     return listFiles(root, isSourceFile).files;
 }
+// `Bundler` resolves `require('..')` (directory `main`/`index.js`), ESM `./x.js` specifiers and
+// `"type": "module"` packages alike; NodeNext/Node10 gave the same References on CommonJS and ESM
+// samples. What breaks plain JavaScript is not the option set but `.d.ts` twins and
+// `module.exports = require()` shims, handled by `resolveModuleNameLiterals` in the host.
 export const IMPLICIT_COMPILER_OPTIONS = {
     allowJs: true,
     checkJs: false,
@@ -278,6 +282,80 @@ export function createSyntacticIndex(root, project) {
     return index;
 }
 const FULL_DIAGNOSTICS_LIMIT = 300;
+const DECLARATION_TWINS = [
+    [/\.d\.ts$/, [[".js", ts.Extension.Js], [".jsx", ts.Extension.Jsx], [".mjs", ts.Extension.Mjs], [".cjs", ts.Extension.Cjs]]],
+    [/\.d\.mts$/, [[".mjs", ts.Extension.Mjs]]],
+    [/\.d\.cts$/, [[".cjs", ts.Extension.Cjs]]],
+];
+/** The implementation beside a `.d.ts` (`index.d.ts` → `index.js`) when it is a Project source file. */
+function implementationTwin(file, isSource) {
+    for (const [re, impls] of DECLARATION_TWINS) {
+        if (!re.test(file))
+            continue;
+        const base = file.replace(re, "");
+        for (const [ext, extension] of impls)
+            if (isSource(base + ext))
+                return { file: base + ext, extension };
+    }
+    return undefined;
+}
+/** `'x'` of a module whose only statement is `module.exports = require('x')` (`exports = module.exports = ...` too). */
+export function passThroughRequire(sf) {
+    const statements = sf.statements.filter((s) => !(ts.isExpressionStatement(s) && ts.isStringLiteral(s.expression)));
+    const only = statements.length === 1 ? statements[0] : undefined;
+    if (!only || !ts.isExpressionStatement(only))
+        return undefined;
+    let expr = only.expression;
+    let assignsModuleExports = false;
+    while (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        const left = expr.left;
+        if (ts.isPropertyAccessExpression(left) && ts.isIdentifier(left.expression) && left.expression.text === "module" && left.name.text === "exports") {
+            assignsModuleExports = true;
+        }
+        else if (!(ts.isIdentifier(left) && left.text === "exports"))
+            return undefined;
+        expr = expr.right;
+    }
+    if (!assignsModuleExports || !ts.isCallExpression(expr) || !ts.isIdentifier(expr.expression) || expr.expression.text !== "require")
+        return undefined;
+    const [arg] = expr.arguments;
+    return expr.arguments.length === 1 && arg && ts.isStringLiteralLike(arg) ? arg.text : undefined;
+}
+const MAX_SHIM_HOPS = 3;
+/**
+ * TypeScript's resolution, then two substitutions so References reach implementations:
+ * a `.d.ts` with a JS twin in the Project resolves to the twin (TS tries `.d.ts` before `.js`),
+ * and a `module.exports = require('x')` shim resolves to `x` (the binder makes no alias of it).
+ */
+function createModuleResolver(options, currentDirectory, isSource, sourceOf) {
+    const cache = ts.createModuleResolutionCache(currentDirectory, (s) => (ts.sys.useCaseSensitiveFileNames ? s : s.toLowerCase()), options);
+    const resolveOne = (name, containingFile, mode, redirected, hops) => {
+        const result = ts.resolveModuleName(name, containingFile, options, ts.sys, cache, redirected, mode);
+        const found = result.resolvedModule;
+        if (!found)
+            return result;
+        let resolvedFileName = resolve(found.resolvedFileName);
+        let extension = found.extension;
+        const twin = implementationTwin(resolvedFileName, isSource);
+        if (twin)
+            ({ file: resolvedFileName, extension } = twin);
+        else if (!isSource(resolvedFileName))
+            return result;
+        if (hops < MAX_SHIM_HOPS && /\.[mc]?jsx?$/.test(resolvedFileName)) {
+            const sf = sourceOf(resolvedFileName);
+            const inner = sf ? passThroughRequire(sf) : undefined;
+            if (inner !== undefined) {
+                const next = resolveOne(inner, resolvedFileName, ts.ModuleKind.CommonJS, redirected, hops + 1);
+                if (next.resolvedModule && isSource(resolve(next.resolvedModule.resolvedFileName)))
+                    return next;
+            }
+        }
+        if (!twin)
+            return result;
+        return { ...result, resolvedModule: { ...found, resolvedFileName, extension, isExternalLibraryImport: false } };
+    };
+    return (literals, containingFile, redirected, opts, containingSourceFile) => literals.map((literal) => resolveOne(literal.text, containingFile, ts.getModeForUsageLocation(containingSourceFile, literal, opts), redirected, 0));
+}
 export function createSemanticProject(index, scope) {
     const started = performance.now();
     const { project } = index;
@@ -306,6 +384,7 @@ export function createSemanticProject(index, scope) {
         getDirectories: ts.sys.getDirectories,
         realpath: ts.sys.realpath,
         useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+        resolveModuleNameLiterals: createModuleResolver(options, currentDirectory, (f) => indexed.has(f), (f) => index.sourceFile(f)),
     };
     const service = ts.createLanguageService(host, ts.createDocumentRegistry());
     const program = service.getProgram();
@@ -406,8 +485,34 @@ export function createSemanticProject(index, scope) {
         }
         return [...keys];
     };
+    /**
+     * The same-named top-level Declaration in the `.d.ts` beside a JS file, when that `.d.ts` is in the
+     * program: importers the resolver did not redirect (a package.json `types` field) bind to it.
+     */
+    const declarationTwin = (absFile, pos) => {
+        if (!/\.[mc]?jsx?$/.test(absFile))
+            return undefined;
+        const sf = program.getSourceFile(absFile);
+        const id = sf ? nodeAt(sf, pos) : undefined;
+        if (!id || !ts.isIdentifier(id))
+            return undefined;
+        const base = absFile.replace(/\.([mc]?)jsx?$/, "");
+        const twin = [".d.ts", ".d.mts", ".d.cts"].map((ext) => program.getSourceFile(base + ext)).find((t) => t !== undefined);
+        if (!twin)
+            return undefined;
+        for (const statement of twin.statements) {
+            const names = ts.isVariableStatement(statement)
+                ? statement.declarationList.declarations.map((d) => d.name)
+                : "name" in statement && statement.name ? [statement.name] : [];
+            const hit = names.find((n) => ts.isIdentifier(n) && n.text === id.text);
+            if (hit)
+                return { file: twin.fileName, pos: hit.getStart(twin) };
+        }
+        return undefined;
+    };
     const split = (absFile, pos) => {
-        const groups = service.findReferences(absFile, pos) ?? [];
+        const twin = declarationTwin(absFile, pos);
+        const groups = [...(service.findReferences(absFile, pos) ?? []), ...(twin ? service.findReferences(twin.file, twin.pos) ?? [] : [])];
         const descriptors = [];
         let target = -1;
         let flagged = -1;
@@ -514,7 +619,15 @@ export function createSemanticProject(index, scope) {
             const items = prepared === undefined ? [] : Array.isArray(prepared) ? prepared : [prepared];
             if (items.length === 0)
                 return undefined;
-            return items.flatMap((item) => splitSites(item.file, item.selectionSpan.start, service.provideCallHierarchyIncomingCalls(item.file, item.selectionSpan.start)));
+            const twin = declarationTwin(absFile, pos);
+            const twinCalls = twin ? service.provideCallHierarchyIncomingCalls(twin.file, twin.pos) : [];
+            const seen = new Set();
+            return items
+                .flatMap((item) => splitSites(item.file, item.selectionSpan.start, [...service.provideCallHierarchyIncomingCalls(item.file, item.selectionSpan.start), ...twinCalls]))
+                .filter((site) => {
+                const key = `${site.file}:${site.line}:${site.col}`;
+                return !seen.has(key) && Boolean(seen.add(key));
+            });
         },
         incomingCallsOf(item) {
             if (item.kind === ts.ScriptElementKind.scriptElement)

package/dist/src/settings.js

@@ -11,6 +11,9 @@ export const DEFAULT_TEST_GLOBS = [
     "**/test/**",
     "**/tests/**",
     "**/e2e/**",
+    "**/spec/**",
+    "**/test.*",
+    "**/*_test.*",
 ];
 export const SETTINGS_FILE = ".ts-axi.json";
 export const SETTINGS_KEYS = ["testGlobs", "testGlobsReplace", "project"];

package/package.json

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