ts-axi 0.1.13 → 0.1.15

package/README.md

@@ -50,6 +50,37 @@ Early, but already used in real reviews. What the numbers say so far:
 
 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.
 
+## Token cost
+
+`test/integration/token-compare.test.ts` does six agent tasks twice: with ts-axi (plus one followed hint where that is the normal next step), and the way a careful agent does them without it - at most 3 `git grep -n` calls, then a ±40-line numbered read around each relevant match (overlaps merged), with `git diff` first for impact. Tokens are characters / 4. A recall gate fails when a grep hit in code (not a comment, a string or a doc file) is neither listed by ts-axi nor covered by its `textual` / `templates` count.
+
+<!-- token-compare:start -->
+| 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) |
+| 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) |
+
+- 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.
+- template uses of a directive is over 0.3 - the followed hint repeats the first output with the extra rows (--grep); the two matching files have 21 and 4 lines.
+- refs of an untyped CommonJS member is over 0.3 - the followed hint repeats the first output with the extra rows (--grep); the two matching files have 24 and 12 lines.
+<!-- token-compare:end -->
+
+The fixture files are 5 to 40 lines long, so a ±40-line read is the whole file: the cheapest case for grep, and where a followed hint repeating the first output weighs most. On a real Nx monorepo (143 projects, ~5.4k source files; `scripts/token-compare.ts`, run locally):
+
+| task | ts-axi tokens | grep tokens | ratio | recall |
+| --- | ---: | ---: | ---: | --- |
+| def of a service method | 496 | 1256 | 0.40 | 1/1 |
+| callers of a service method (96 call sites) | 6587 | 54314 | 0.12 | 96/96 |
+| refs of a service method with a common name | 4653 | 147944 | 0.03 | 77/77 (244 more hits are other declarations of the name) |
+| impact of a two-commit fix (4 changed symbols) | 2255 | 23948 | 0.09 | 44/44 (5 in the diff) |
+
+The ts-axi side follows the `--limit` hint when a list is cut at 50 rows, as an agent would. Most rows past the first 50 are member accesses through a deep-mock mapped type (`DeepMocked<Service>`) in test files: `findReferences` returns them as extra groups defined at the method itself, and they count as References (before 0.1.15 they were dropped, and recall was 17/96 and 18/77).
+
 ## Install
 
 Requires Node.js 20+.
@@ -274,7 +305,7 @@ One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-
 - `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 and 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.
+- 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.
 
 Every semantic command starts cold and prints `elapsed_ms`.

package/dist/src/commands/common.js

@@ -259,7 +259,8 @@ export function resolvePosition(index, cwd, target) {
         return start >= lineStart && start < lineEnd;
     });
     const decls = index.declarations(abs);
-    const declFor = (id) => decls.find((d) => d.namePos === id.getStart(sf));
+    // `self.loadItem = loadItem`: the member name there stands for the nested function's member too.
+    const declFor = (id) => decls.find((d) => d.namePos === id.getStart(sf)) ?? decls.find((d) => d.aliasPos === id.getStart(sf));
     const pick = (id) => {
         const decl = declFor(id);
         return decl ? { kind: "decl", decl, abs } : { kind: "ident", abs, pos: id.getStart(sf), name: id.text };

package/dist/src/commands/impact.js

@@ -251,7 +251,9 @@ function walkExtra(dir, outFiles) {
  * a name in `localTo` (name → absolute file) is searched in that file only.
  */
 export function textualMatches(opened, semantic, names, known, skipLines, changeSet, localTo = new Map()) {
-    const files = [...semantic.projectFiles];
+    // The whole Project, like `textualCount`: a subgraph program misses DI uses, which import nothing.
+    const byRel = new Map([...semantic.projectFiles, ...opened.index.files].map((f) => [opened.index.rel(f), f]));
+    const files = [...byRel.values()];
     const projectSet = new Set(files);
     walkExtra(opened.root, files);
     sourceFs().prefetch(files);
@@ -262,7 +264,7 @@ export function textualMatches(opened, semantic, names, known, skipLines, change
             continue;
         const rel = opened.index.rel(abs);
         // A Declaration of another Symbol with the same name is provably not a use.
-        const declared = new Set(projectSet.has(abs) ? opened.index.declarations(abs).map((d) => d.nameLine) : []);
+        const declared = new Set(projectSet.has(abs) ? opened.index.declarations(abs).flatMap((d) => (d.aliasLine ? [d.nameLine, d.aliasLine] : [d.nameLine])) : []);
         const lines = new Set();
         for (const { text: name, token } of names) {
             if (localTo.has(name) && localTo.get(name) !== abs)
@@ -317,6 +319,10 @@ export function textualNeedle(subject, kind) {
     }
     return { text: symbol.split(".").pop(), token: false };
 }
+/** A Reference on a member's aliasing line (`self.x = x`) is part of its Declaration, not a use. */
+export function onAliasLine(decl, e) {
+    return decl?.aliasLine !== undefined && e.file === decl.file && e.line === decl.aliasLine;
+}
 /** Whether `any`-typed property accesses of the name can be uses of the Symbol: same rule as `isTextualCandidate`. */
 export function isBlindSpotCandidate(decl) {
     return decl?.injected !== true;
@@ -407,7 +413,7 @@ export function textualCount(opened, needle, changeSet = new Map(), onlyFile) {
         if (text === undefined || !text.includes(name))
             continue;
         const rel = opened.index.rel(abs);
-        const declared = new Set(project.has(abs) ? opened.index.declarations(abs).filter((d) => d.name === name).map((d) => d.nameLine) : []);
+        const declared = new Set(project.has(abs) ? opened.index.declarations(abs).filter((d) => d.name === name).flatMap((d) => (d.aliasLine ? [d.nameLine, d.aliasLine] : [d.nameLine])) : []);
         const n = wordMatches(text, name, token).filter((m) => !declared.has(m.line) && !inRanges(changeSet.get(rel), m.line)).length;
         matches += n;
         if (n > 0)
@@ -683,7 +689,7 @@ export async function impactCommand(args, ctx) {
         }
         for (const e of entries)
             known.add(`${e.file}:${e.line}`);
-        row.all = entries.filter((e) => !e.isDefinition);
+        row.all = entries.filter((e) => !e.isDefinition && !onAliasLine(row.live, e));
         row.outside = row.all.filter((e) => !inRanges(changeSet.get(e.file), e.line)).sort(byPosition);
     }
     for (const row of rows) {

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 { isPlainLocal, isTextualCandidate, isUntyped, textualCount, textualNeedle, textualHint, textualLine, textualMatches, textualScan, textualScanHint } from "./impact.js";
+import { isPlainLocal, isTextualCandidate, onAliasLine, isUntyped, textualCount, textualNeedle, textualHint, textualLine, textualMatches, textualScan, textualScanHint } from "./impact.js";
 import { findOutsideProject, nearestTsconfig } from "../project.js";
 import { viaLine } from "../references.js";
 import { block, helpBlock, out } from "../render.js";
@@ -289,7 +289,7 @@ function mergedRows(direct, via, show) {
 }
 function renderRefs(semantic, opened, resolved, header, o) {
     const split = semantic.referenceSplit(resolved.absFile, resolved.pos);
-    const rows = sortRows([...split.direct]);
+    const rows = sortRows(split.direct.filter((e) => !onAliasLine(o.decl, e)));
     const via = sortRows([...split.via]);
     const impls = sortRows([...split.implementations]);
     const { files, tests, fileList } = summary(opened, rows);

package/dist/src/references.js

@@ -7,7 +7,8 @@ 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.
+ * any other member group is a sibling and dropped. Non-member groups (import aliases) and groups
+ * defined at the target itself (mock mapped types) are direct.
  */
 export function classifyReferenceGroups(groups, targetIndex) {
     const target = groups[targetIndex];
@@ -19,7 +20,8 @@ export function classifyReferenceGroups(groups, targetIndex) {
     };
     const bases = new Set(target?.bases ?? []);
     groups.forEach((group, i) => {
-        const isTarget = i === targetIndex;
+        // Mock shapes (`{ [K in keyof T]: … } & T`) come back as extra groups defined at the target itself.
+        const isTarget = i === targetIndex || (target !== undefined && group.key === target.key);
         const relation = isTarget || !target?.member || !group.member
             ? "direct"
             : bases.has(group.key)

package/dist/src/symbols.js

@@ -289,27 +289,57 @@ function functionByIdentifier(call, arg) {
     let scope = call;
     while (!ts.isSourceFile(scope) && !(ts.isBlock(scope) && ts.isFunctionLike(scope.parent)))
         scope = scope.parent;
-    const statements = scope.statements;
+    return functionInStatements(scope.statements, ref.text);
+}
+/** The function declaration or function-valued variable `name` among `statements` (any position: hoisting), with its `$inject`. */
+function functionInStatements(statements, name) {
     let found;
     let inject;
     for (const st of statements) {
-        if (ts.isFunctionDeclaration(st) && st.name?.text === ref.text && st.body)
+        if (ts.isFunctionDeclaration(st) && st.name?.text === name && st.body)
             found = { fn: st, name: st.name };
         else if (ts.isVariableStatement(st)) {
             for (const d of st.declarationList.declarations) {
                 const fn = asFunction(d.initializer);
-                if (fn && ts.isIdentifier(d.name) && d.name.text === ref.text)
+                if (fn && ts.isIdentifier(d.name) && d.name.text === name)
                     found = { fn, name: d.name };
             }
         }
         else if (ts.isExpressionStatement(st) && ts.isBinaryExpression(st.expression) && ts.isPropertyAccessExpression(st.expression.left)) {
             const { left, right } = st.expression;
-            if (left.name.text === "$inject" && ts.isIdentifier(left.expression) && left.expression.text === ref.text && ts.isArrayLiteralExpression(right))
+            if (left.name.text === "$inject" && ts.isIdentifier(left.expression) && left.expression.text === name && ts.isArrayLiteralExpression(right))
                 inject = right;
         }
     }
     return found && (inject ? { ...found, inject } : found);
 }
+/** Names bound to `this` at the top level of a body (`var self = this`, `const vm = this`). */
+function thisAliases(statements) {
+    const names = new Set();
+    for (const st of statements) {
+        if (!ts.isVariableStatement(st))
+            continue;
+        for (const d of st.declarationList.declarations) {
+            if (ts.isIdentifier(d.name) && d.initializer && unwrap(d.initializer).kind === ts.SyntaxKind.ThisKeyword)
+                names.add(d.name.text);
+        }
+    }
+    return names;
+}
+/** The object literal of a top-level `var <name> = {...}` among `statements`. */
+function objectVariable(statements, name) {
+    let found;
+    for (const st of statements) {
+        if (!ts.isVariableStatement(st))
+            continue;
+        for (const d of st.declarationList.declarations) {
+            const init = d.initializer && unwrap(d.initializer);
+            if (ts.isIdentifier(d.name) && d.name.text === name && init && ts.isObjectLiteralExpression(init))
+                found = init;
+        }
+    }
+    return found;
+}
 function isStringName(node) {
     return node !== undefined && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node));
 }
@@ -363,8 +393,21 @@ export function collectDeclarations(sf, file) {
     const nested = (raw) => {
         raws.push({ ...raw, qualifiedName: raw.qualifiedName ?? (raw.parentName ? `${raw.parentName}.${raw.name}` : raw.name), hasBody: true });
     };
-    /** Method and function-valued properties of an object literal as `<holder>.<name>`. */
-    const objectMembers = (obj, holder, exported) => {
+    /**
+     * `<holder>.<name>` for a nested function named by identifier (`self.x = loadItem`, `{ x: loadItem }`): the
+     * function's own span, signature and name, so its line and the aliasing line both resolve to the member.
+     */
+    const aliasedMember = (scope, ref, name, holder, exported, alias) => {
+        const target = functionInStatements(scope, ref.text);
+        if (!target)
+            return;
+        const decl = ts.isFunctionDeclaration(target.fn) ? target.fn : target.name.parent;
+        const list = decl.parent;
+        const node = ts.isVariableDeclaration(decl) && ts.isVariableDeclarationList(list) && ts.isVariableStatement(list.parent) && list.declarations[0] === decl ? list.parent : decl;
+        nested({ start: node.getStart(sf), end: node.end, kind: "method", name, parentName: holder, exported, signature: fullSignatureOf(decl, sf), namePos: target.name.getStart(sf), aliasPos: alias.getStart(sf) });
+    };
+    /** Method and function-valued properties of an object literal as `<holder>.<name>`; with `scope`, also identifiers naming its functions. */
+    const objectMembers = (obj, holder, exported, scope) => {
         for (const prop of obj.properties) {
             const name = nameText(prop.name, sf);
             if (!name || !prop.name)
@@ -374,35 +417,60 @@ export function collectDeclarations(sf, file) {
             }
             else if (ts.isPropertyAssignment(prop)) {
                 const fn = asFunction(prop.initializer);
+                const value = unwrap(prop.initializer);
                 if (fn)
                     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 (scope && ts.isShorthandPropertyAssignment(prop)) {
+                aliasedMember(scope, prop.name, name, holder, exported, prop.name);
             }
         }
     };
-    /** `this.x = function` statements at the top level of a constructor-like body. */
-    const thisMembers = (body, owner, exported) => {
-        if (!body || !ts.isBlock(body))
-            return;
-        for (const statement of body.statements) {
+    /** `<holder>.x = function | <nested function>` at the top level of a body; `isHolder` matches `this`, its aliases or a returned object. */
+    const memberAssignments = (statements, isHolder, owner, exported) => {
+        for (const statement of statements) {
             if (!ts.isExpressionStatement(statement) || !ts.isBinaryExpression(statement.expression))
                 continue;
             const { left, operatorToken, right } = statement.expression;
-            if (operatorToken.kind !== ts.SyntaxKind.EqualsToken || !ts.isPropertyAccessExpression(left) || left.expression.kind !== ts.SyntaxKind.ThisKeyword)
+            if (operatorToken.kind !== ts.SyntaxKind.EqualsToken || !ts.isPropertyAccessExpression(left) || !isHolder(left.expression))
                 continue;
             const value = unwrap(right);
             if (ts.isObjectLiteralExpression(value))
                 objectMembers(value, `${owner}.${left.name.text}`, exported);
+            if (ts.isIdentifier(value))
+                aliasedMember(statements, value, left.name.text, owner, exported, left.name);
             const fn = asFunction(right);
             if (!fn)
                 continue;
             nested({ start: statement.getStart(sf), end: statement.end, kind: "method", name: left.name.text, parentName: owner, exported, signature: headUntil(statement.expression, fn, sf), namePos: left.name.getStart(sf) });
         }
     };
-    /** Object literals a function returns at its top level (a factory's API, a deps object): their function-valued members. */
+    /** `this.x = ...` (also through `var self = this`) at the top level of a constructor-like body. */
+    const thisMembers = (body, owner, exported) => {
+        if (!body || !ts.isBlock(body))
+            return;
+        const aliases = thisAliases(body.statements);
+        memberAssignments(body.statements, (e) => e.kind === ts.SyntaxKind.ThisKeyword || (ts.isIdentifier(e) && aliases.has(e.text)), owner, exported);
+    };
+    /** Object literals a function returns at its top level (a factory's API, a deps object), directly or as `var service = {...}; return service`. */
     const returnedMembers = (body, owner, exported) => {
-        if (body)
-            for (const obj of returnedObjects(body))
-                objectMembers(obj, owner, exported);
+        if (!body)
+            return;
+        const scope = ts.isBlock(body) ? body.statements : undefined;
+        for (const obj of returnedObjects(body))
+            objectMembers(obj, owner, exported, scope);
+        for (const st of scope ?? []) {
+            const ret = ts.isReturnStatement(st) && st.expression ? unwrap(st.expression) : undefined;
+            if (!ret || !ts.isIdentifier(ret))
+                continue;
+            const obj = objectVariable(scope, ret.text);
+            if (!obj)
+                continue;
+            objectMembers(obj, owner, exported, scope);
+            memberAssignments(scope, (e) => ts.isIdentifier(e) && e.text === ret.text, owner, exported);
+        }
     };
     const topLevelExported = (name) => raws.find((r) => r.qualifiedName === name && r.parentName === undefined)?.exported ?? false;
     const isConstructorName = (name) => /^[A-Z]/.test(name);
@@ -851,7 +919,18 @@ export function collectDeclarations(sf, file) {
     const kept = registeredBodies.length === 0
         ? raws
         : raws.filter((r) => r.registered || !registeredBodies.some(([s, e]) => r.namePos >= s && r.namePos < e));
-    const ordered = kept.map((r, i) => ({ r, i })).sort((a, b) => a.r.start - b.r.start || a.i - b.i);
+    // One function named twice for the same holder (`this.x = x` and `return { x }`) is one member.
+    const seen = new Set();
+    const unique = kept.filter((r) => {
+        if (r.aliasPos === undefined)
+            return true;
+        const key = `${r.qualifiedName}@${r.namePos}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const ordered = unique.map((r, i) => ({ r, i })).sort((a, b) => a.r.start - b.r.start || a.i - b.i);
     return ordered.map(({ r }) => {
         const startLc = sf.getLineAndCharacterOfPosition(r.start);
         const full = r.signature;
@@ -872,6 +951,7 @@ export function collectDeclarations(sf, file) {
             fullSignature: full,
             ...(r.nameless ? { nameless: true } : {}),
             ...(r.injected ? { injected: true } : {}),
+            ...(r.aliasPos !== undefined ? { aliasPos: r.aliasPos, aliasLine: sf.getLineAndCharacterOfPosition(r.aliasPos).line + 1 } : {}),
         };
     });
 }

package/package.json

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