ts-axi 0.1.15 → 0.1.17

package/README.md

@@ -81,6 +81,19 @@ The fixture files are 5 to 40 lines long, so a ±40-line read is the whole file:
 
 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).
 
+### Speed
+
+The same runs count tool calls (each ts-axi command, `git grep`, `git diff` and file read is one call) and time the commands. An agent's task time is mostly model round-trips, so the estimate adds an **assumed** 3 s per call to the measured command time (`TURN_MS` in `test/compare.ts`). On the Nx monorepo:
+
+| task | ts-axi calls | grep calls | ts-axi command time | grep command time | est. task time ts-axi | est. task time grep |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| def of a service method | 1 | 3 | 1.4 s | 0.94 s | 4.4 s | 9.9 s |
+| callers of a service method | 2 | 28 | 11.1 s | 0.20 s | 17.1 s | 84.2 s |
+| refs of a service method with a common name | 2 | 100 | 6.3 s | 0.27 s | 12.3 s | 300.3 s |
+| impact of a two-commit fix | 2 | 19 | 8.1 s | 0.22 s | 14.1 s | 57.2 s |
+
+Each ts-axi command is slower than a `git grep` (every call starts cold and builds a program: 3-6 s per semantic call here), but it replaces dozens of reads. The integration test checks that ts-axi never needs more tool calls than the grep workflow; times are printed, not asserted.
+
 ## Install
 
 Requires Node.js 20+.
@@ -109,7 +122,7 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | Command | What it does |
 | --- | --- |
 | `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 |
+| `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` |
 | `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` |

package/dist/src/commands/def.js

@@ -2,6 +2,7 @@ import { bool, expectPositionals, flag, parseArgs } from "../args.js";
 import { semanticFor } from "../scope.js";
 import { textualScan, textualScanHint } from "./impact.js";
 import { block, fenced, helpBlock, out } from "../render.js";
+import { isOutside, missFallback, missRows, notSearched, outsideReason } from "./miss.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
 import { BODY_LINES, declarationAt, filterSuffix, MATCH_ROWS, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, useRef, } from "./common.js";
 export const DEF_HELP = `usage: ts-axi def <name | Class.member | path:line[:col]> [flags]
@@ -10,7 +11,8 @@ flags[8]:
 output:
   1 match = file, line, kind, exported, signature + body fenced with file line numbers
   several = matches[n]{at,kind,signature} (at = path:line) (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
-  none = matches: 0 + did_you_mean; when the name still occurs in Project files, help gives the refs --grep that lists those textual matches
+  not indexed = a function-local Declaration (local_to: Comp) or one in a file the tsconfig leaves out (project: outside (not in tsconfig.json | own tsconfig x | Deno x/deno.json)) shows the same way; several = matches[n]{at,kind,name,where} (at = path:line:col)
+  none = matches: 0 + did_you_mean; when the name still occurs in source files (left-out files too), help gives the refs --grep that lists those textual matches
 examples[5]:
   ts-axi def User
   ts-axi def User.save
@@ -19,13 +21,13 @@ examples[5]:
   ts-axi def sav --fuzzy --exported
 `;
 const COMMAND = "ts-axi def";
-function detail(ctx, decls, full, label, extra = {}) {
+function detail(ctx, decls, full, label, extra = {}, at) {
     const primary = decls.find((d) => d.hasBody) ?? decls[0];
     const first = decls[0];
     const from = Math.min(...decls.map((d) => d.line));
     const to = Math.max(...decls.map((d) => d.endLine));
     const body = numberedLines(ctx.index.text(ctx.index.abs(primary.file)) ?? "", from, to, full ? undefined : BODY_LINES);
-    const position = `${first.file}:${first.nameLine}`;
+    const position = at ?? `${first.file}:${first.nameLine}`;
     const help = [`Run \`ts-axi refs ${position}\` for its references`];
     if (isFunctionLike(primary.kind))
         help.push(`Run \`ts-axi callers ${position}\` for its call sites`);
@@ -40,6 +42,7 @@ function detail(ctx, decls, full, label, extra = {}) {
         exported: primary.exported,
         signature: first.signature,
         ...(decls.filter((d) => !d.hasBody).length > 0 ? { overloads: decls.filter((d) => !d.hasBody).length } : {}),
+        ...(isOutside(ctx, ctx.index.abs(primary.file)) ? { project: outsideReason(ctx, ctx.index.abs(primary.file)) } : {}),
         ...extra,
     }), fenced("body", body), helpBlock(help));
 }
@@ -78,9 +81,19 @@ export async function defCommand(args, ctx) {
     if (groups.length === 1)
         return detail(opened, groups[0].decls, full, label);
     if (groups.length === 0) {
+        const miss = missFallback(opened, target, f);
+        if (miss.hits.length === 1) {
+            const hit = miss.hits[0];
+            return detail(opened, [hit.decl], full, hit.at, hit.localTo !== undefined ? { local_to: hit.localTo } : {}, hit.at);
+        }
+        if (miss.hits.length > 1) {
+            return out(block({ ...(opened.warning ? { warning: opened.warning } : {}), symbol: label, ...missRows(miss, MATCH_ROWS) }), helpBlock(miss.hits.slice(0, 3).map((h) => `Run \`ts-axi def ${h.at}\` for the one ${h.localTo !== undefined ? `in ${h.localTo}` : `in ${h.decl.file}`}`)));
+        }
         const suggested = suggestions(opened, target);
-        const text = f.fuzzy ? 0 : textualScan(opened, target.member ?? target.name).length;
-        const help = [...(text > 0 ? [textualScanHint(label, text)] : []), ...suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``)];
+        const rows = f.fuzzy ? [] : textualScan(opened, target.member ?? target.name);
+        const text = rows.length;
+        const outsideCount = rows.filter((r) => isOutside(opened, opened.index.abs(r.file))).length;
+        const help = [...(text > 0 ? [textualScanHint(label, text, outsideCount)] : []), ...suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``)];
         if (!f.fuzzy)
             help.push(`Run \`ts-axi def ${label} --fuzzy\` for substring matches`);
         if (f.kind || f.in.length > 0 || f.exported)
@@ -89,6 +102,7 @@ export async function defCommand(args, ctx) {
             ...(opened.warning ? { warning: opened.warning } : {}),
             matches: 0,
             ...(suggested.length > 0 ? { did_you_mean: suggested } : {}),
+            ...notSearched(miss),
         }), helpBlock(help));
     }
     return out(block({

package/dist/src/commands/impact.js

@@ -15,6 +15,7 @@ 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 { outsideFiles } from "./miss.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const SIDE_ROWS = 20;
@@ -281,11 +282,15 @@ export function textualMatches(opened, semantic, names, known, skipLines, change
     }
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
 }
-/** Whole-word matches of `name` in the Project files, one row per line: the fallback when no Declaration matches. */
+/**
+ * Whole-word matches of `name` in the Project files and the source files it leaves out, one row per line:
+ * the fallback when no Declaration matches.
+ */
 export function textualScan(opened, name) {
     const rows = [];
-    sourceFs().prefetch(opened.index.files);
-    for (const abs of opened.index.files) {
+    const files = [...opened.index.files, ...outsideFiles(opened)];
+    sourceFs().prefetch(files);
+    for (const abs of files) {
         const text = opened.index.text(abs);
         if (text === undefined || !text.includes(name))
             continue;
@@ -299,8 +304,8 @@ export function textualScan(opened, name) {
     }
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
 }
-export function textualScanHint(label, matches) {
-    return `Run \`ts-axi refs ${label} --grep\` for ${matches} textual matches`;
+export function textualScanHint(label, matches, outside = 0) {
+    return `Run \`ts-axi refs ${label} --grep\` for ${matches} textual matches${outside > 0 ? ` (${outside} in files outside the Project)` : ""}`;
 }
 /** Whether a whole-word count of the name says anything: not for router-called or by-name-injected members (`injected`). */
 export function isTextualCandidate(decl) {

package/dist/src/commands/miss.js

@@ -0,0 +1,225 @@
+// The miss fallback: when a name target matches no indexed Declaration, look for it syntactically in
+// source files the tsconfig leaves out and in function-local Declarations, so a miss is never silent.
+import { dirname, join, posix, relative, sep } from "node:path";
+import ts from "typescript";
+import { sourceFs } from "../fs.js";
+import { matchesGlob } from "../glob.js";
+import { declMatches, isSourceFile, nearestTsconfig } from "../project.js";
+import { byDepthThenPath, listFiles } from "../walk.js";
+import { declarationAt } from "./common.js";
+/** At most this many files that pass the name prefilter are parsed; the rest are counted in `not_searched`. */
+export const MISS_PARSE_CAP = 2_000;
+const ANON = "(anonymous)";
+function nameOf(node) {
+    return node && (ts.isIdentifier(node) || ts.isPrivateIdentifier(node) || ts.isStringLiteral(node)) ? node.text : undefined;
+}
+/** Name of a function-like node: its own, or the variable / property / member it is assigned to. */
+function functionName(fn) {
+    const parent = fn.parent;
+    const cls = parent && (ts.isClassDeclaration(parent) || ts.isClassExpression(parent)) ? nameOf(parent.name) ?? ANON : undefined;
+    if (ts.isConstructorDeclaration(fn))
+        return `${cls ?? ANON}.constructor`;
+    const own = nameOf(fn.name);
+    if (own !== undefined)
+        return cls !== undefined ? `${cls}.${own}` : own;
+    if (ts.isVariableDeclaration(parent) || ts.isPropertyAssignment(parent))
+        return nameOf(parent.name);
+    if (ts.isPropertyDeclaration(parent)) {
+        const owner = parent.parent;
+        return `${nameOf(owner.name) ?? ANON}.${nameOf(parent.name) ?? ANON}`;
+    }
+    return undefined;
+}
+/** Nearest named enclosing function; anonymous callbacks (`useEffect(() => ...)`) are skipped. */
+function ownerOf(node) {
+    for (let n = node.parent; n && !ts.isSourceFile(n); n = n.parent) {
+        if (ts.isFunctionLike(n)) {
+            const name = functionName(n);
+            if (name !== undefined)
+                return name;
+        }
+    }
+    return "(top-level block)";
+}
+/**
+ * Function, class and plain `const/let/var x` Declarations named `name` that sit in a function or block
+ * body (not top level, not a namespace). Parameters, destructured and loop bindings are left out.
+ */
+export function findLocals(sf, name) {
+    const found = [];
+    const nested = (statement) => !ts.isSourceFile(statement.parent) && !ts.isModuleBlock(statement.parent);
+    const visit = (node) => {
+        if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name?.text === name && nested(node)) {
+            found.push({ pos: node.name.getStart(sf), name, owner: ownerOf(node) });
+        }
+        else if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text === name &&
+            ts.isVariableStatement(node.parent.parent) &&
+            nested(node.parent.parent)) {
+            found.push({ pos: node.name.getStart(sf), name, owner: ownerOf(node) });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return found;
+}
+const outsideCache = new WeakMap();
+/**
+ * Source files below the repo root the Project does not list (gitignored, node_modules and `.d.ts`
+ * dropped). Empty for a workspace or implicit Project: those already list every source file.
+ */
+export function outsideFiles(opened) {
+    const cached = outsideCache.get(opened);
+    if (cached)
+        return cached.files;
+    const { project } = opened.index;
+    let files = [];
+    let capped = false;
+    if (!project.scope && !project.implicit) {
+        const known = new Set(opened.index.files);
+        // node_modules and build dirs are already dropped by the shared skip rule.
+        const listing = listFiles(opened.root, isSourceFile, { maxFiles: 20_000, deadline: Date.now() + 600 });
+        files = listing.files.filter((f) => !known.has(f));
+        capped = listing.capped;
+    }
+    outsideCache.set(opened, { files, set: new Set(files), capped });
+    return files;
+}
+const projectSets = new WeakMap();
+/** Lists the left-out files only for a file the Project does not hold, so hit paths stay listing-free. */
+export function isOutside(opened, abs) {
+    let known = projectSets.get(opened);
+    if (!known)
+        projectSets.set(opened, (known = new Set(opened.index.files)));
+    if (known.has(abs))
+        return false;
+    outsideFiles(opened);
+    return outsideCache.get(opened).set.has(abs);
+}
+/** `outside (Deno edge/deno.json)`, `outside (own tsconfig x/tsconfig.json)` or `outside (not in tsconfig.json)`. */
+export function outsideReason(opened, abs) {
+    const root = opened.root;
+    for (let dir = dirname(abs);; dir = dirname(dir)) {
+        for (const name of ["deno.json", "deno.jsonc"]) {
+            if (sourceFs().exists(join(dir, name)))
+                return `outside (Deno ${opened.index.rel(join(dir, name))})`;
+        }
+        if (dir === root || dirname(dir) === dir)
+            break;
+    }
+    const own = nearestTsconfig(abs, root);
+    const projectTsconfig = opened.index.project.tsconfig;
+    if (own && own !== projectTsconfig)
+        return `outside (own tsconfig ${opened.index.rel(own)})`;
+    return projectTsconfig ? `outside (not in ${relative(opened.cwd, projectTsconfig).split(sep).join("/")})` : "outside (not in the Project)";
+}
+/** `--in` globs are cwd-relative; files are root-relative. */
+function rootGlobs(opened, globs) {
+    const prefix = relative(opened.root, opened.cwd).split(sep).join("/");
+    return globs.map((g) => {
+        const clean = g.replace(/^\.\//, "");
+        return prefix && !prefix.startsWith("..") ? posix.join(prefix, clean) : clean;
+    });
+}
+function inGlobs(rel, globs) {
+    return globs.length === 0 || globs.some((g) => matchesGlob(rel, g));
+}
+function nameCol(sf, pos) {
+    const lc = sf.getLineAndCharacterOfPosition(pos);
+    return { line: lc.line + 1, col: lc.character + 1 };
+}
+/** Declarations of the name outside the Project, plus function-local ones anywhere (see the header). */
+export function missFallback(opened, target, f) {
+    if (f.fuzzy)
+        return { hits: [], skipped: 0, walkCapped: false };
+    const { index } = opened;
+    const globs = rootGlobs(opened, f.in);
+    const outside = outsideFiles(opened);
+    const word = target.member ?? target.name;
+    const pick = (list) => (globs.length === 0 ? list : list.filter((abs) => inGlobs(index.rel(abs), globs)));
+    const outsidePicked = pick(outside);
+    const candidates = [...pick(index.files), ...outsidePicked];
+    sourceFs().prefetch(outsidePicked);
+    const hits = [];
+    let parsed = 0;
+    let skipped = 0;
+    for (const abs of candidates) {
+        const text = index.text(abs);
+        if (text === undefined || !text.includes(word))
+            continue;
+        if (++parsed > MISS_PARSE_CAP) {
+            skipped++;
+            continue;
+        }
+        const sf = index.sourceFile(abs);
+        if (!sf)
+            continue;
+        const reason = isOutside(opened, abs) ? outsideReason(opened, abs) : undefined;
+        const add = (decl, localTo) => {
+            if (f.kind !== undefined && decl.kind !== f.kind)
+                return;
+            if (f.exported && !decl.exported)
+                return;
+            const { line, col } = nameCol(sf, decl.namePos);
+            hits.push({ decl, abs, at: `${decl.file}:${line}:${col}`, ...(localTo !== undefined ? { localTo } : {}), ...(reason ? { outside: reason } : {}) });
+        };
+        const indexed = index.declarations(abs);
+        if (reason)
+            for (const d of indexed)
+                if (declMatches(d, { name: target.name, ...(target.member !== undefined ? { member: target.member } : {}) }))
+                    add(d);
+        if (target.member !== undefined)
+            continue;
+        const known = new Set(indexed.map((d) => d.namePos));
+        for (const local of findLocals(sf, target.name)) {
+            if (known.has(local.pos))
+                continue;
+            const decl = declarationAt(index, abs, local.pos, "variable");
+            if (decl)
+                add(decl, local.owner);
+        }
+    }
+    hits.sort((a, b) => byDepthThenPath(a.decl.file, b.decl.file) || a.decl.namePos - b.decl.namePos);
+    return { hits, skipped, walkCapped: outsideCache.get(opened).capped };
+}
+/** `local to Comp`, `outside (...)` or both: the `where` cell and the single-hit fields. */
+export function whereOf(hit) {
+    return [hit.localTo !== undefined ? `local to ${hit.localTo}` : undefined, hit.outside].filter(Boolean).join("; ");
+}
+/** Fields a single fallback hit adds to a detail or refs header. */
+export function missFields(hit) {
+    return { ...(hit.localTo !== undefined ? { local_to: hit.localTo } : {}), ...(hit.outside ? { project: hit.outside } : {}) };
+}
+/** `matches[n]{at,kind,name,where}` for several fallback hits. */
+export function missRows(result, max) {
+    const rows = result.hits.slice(0, max).map((h) => ({ at: h.at, kind: h.decl.kind, name: h.decl.qualifiedName, where: whereOf(h) }));
+    return {
+        matches: rows,
+        ...(result.hits.length > max ? { matches_total: result.hits.length, truncated: true } : {}),
+        ...notSearched(result),
+    };
+}
+/** `not_searched` when a bound stopped the fallback. */
+export function notSearched(result) {
+    const parts = [
+        ...(result.skipped > 0 ? [`${result.skipped} files past the ${MISS_PARSE_CAP}-file cap`] : []),
+        ...(result.walkCapped ? ["files past the 20000-file or 0.6 s walk bound (no git)"] : []),
+    ];
+    return parts.length > 0 ? { not_searched: parts.join("; ") } : {};
+}
+/** Outside-Project source files whose text holds `name`: extra roots so a semantic run sees their uses. */
+export function outsideSeeds(opened, name) {
+    return outsideFiles(opened).filter((abs) => opened.index.text(abs)?.includes(name));
+}
+/** `3 matches in 2 files (edge/fn; tools)`: textual rows from outside-Project files, at most 3 dirs. */
+export function outsideLine(opened, rows) {
+    const outside = new Set(outsideFiles(opened).map((abs) => opened.index.rel(abs)));
+    const mine = rows.filter((r) => outside.has(r.file));
+    if (mine.length === 0)
+        return undefined;
+    const files = [...new Set(mine.map((r) => r.file))];
+    const dirs = [...new Set(files.map((f) => posix.dirname(f)))];
+    const shown = dirs.slice(0, 3).join("; ") + (dirs.length > 3 ? `; +${dirs.length - 3} more` : "");
+    return `${mine.length} matches in ${files.length} files (${shown})`;
+}

package/dist/src/commands/outline.js

@@ -3,7 +3,8 @@ import { posix, relative, resolve, sep } from "node:path";
 import { bool, flag, parseArgs, parseFields } from "../args.js";
 import { usageError } from "../errors.js";
 import { hasGlobMagic, matchesGlob } from "../glob.js";
-import { createSyntacticIndex, findRepoRoot, openProject, SOURCE_EXTENSIONS } from "../project.js";
+import { createSyntacticIndex, findRepoRoot, isSourceFile, openProject, SOURCE_EXTENSIONS } from "../project.js";
+import { listFiles } from "../walk.js";
 import { block, helpBlock, out } from "../render.js";
 import { useRef } from "./common.js";
 const MAX_ROWS = 300;
@@ -55,13 +56,17 @@ export async function outlineCommand(args, ctx) {
     const index = globs.length > 0
         ? openProject(ctx.cwd, override ? { override } : {}).index
         : createSyntacticIndex(root, { root, tsconfig: null, implicit: true, fileNames: files, options: {} });
+    let outsideCount = 0;
     if (globs.length > 0) {
         const rooted = globs.map((g) => (cwdPrefix && !cwdPrefix.startsWith("..") ? posix.join(cwdPrefix, g.replace(/^\.\//, "")) : g));
-        for (const file of index.files)
-            if (rooted.some((g) => matchesGlob(index.rel(file), g)))
-                files.push(file);
+        const matching = (list) => list.filter((file) => rooted.some((g) => matchesGlob(index.rel(file), g)));
+        const inProject = matching(index.files);
+        // Files the tsconfig leaves out parse alone, like a plain path.
+        const outside = inProject.length === 0 && files.length === 0 ? matching(listFiles(root, isSourceFile, { maxFiles: 20_000, deadline: Date.now() + 600 }).files) : [];
+        outsideCount = outside.length;
+        files.push(...inProject, ...outside);
         if (files.length === 0) {
-            return out(block({ files: 0, decls: 0 }), helpBlock([`No Project file matches ${globs.join(" ")}; paths are relative to the current directory`]));
+            return out(block({ files: 0, decls: 0 }), helpBlock([`No source file matches ${globs.join(" ")}; paths are relative to the current directory`]));
         }
     }
     const unique = [...new Set(files)];
@@ -97,6 +102,7 @@ export async function outlineCommand(args, ctx) {
         ...(single ? { file: index.rel(unique[0]) } : { files: unique.length }),
         decls: rows.length === 0 ? 0 : rows,
         ...(decls.length > MAX_ROWS ? { truncated: true, decls_total: decls.length } : {}),
+        ...(outsideCount > 0 ? { note: `${outsideCount} files outside the Project` } : {}),
     }), helpBlock(help));
 }
 function isInterfaceMember(fileDecls, d) {

package/dist/src/commands/refs.js

@@ -8,6 +8,7 @@ import { block, helpBlock, out } from "../render.js";
 import { importerIndexFor, REFS_HOPS, scopeFields, scopeHelp, semanticFor } from "../scope.js";
 import { loadTemplates, templatesLine, templateTarget, templateUsages } from "../templates.js";
 import { byDepthThenPath } from "../walk.js";
+import { isOutside, missFallback, missRows, notSearched, outsideLine, outsideReason, outsideSeeds } from "./miss.js";
 import { detectWorkspace, isMultiProject } from "../workspace.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget, registrationOf } from "../symbols.js";
@@ -20,6 +21,9 @@ const VIA_DOC = `via_interface: n (Iface.member) = References through an interfa
   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
+  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
   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
@@ -35,7 +39,7 @@ output:
   symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,context} (Declarations excluded), elapsed_ms
   ${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 Project files, and --grep lists them in unresolved with note 'no declaration found - textual matches only'
+  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)
   path:line = the declaration that starts the line (a function before its parameters, a property before its value's parameters; siblings like 'const a = 1, b = 2' list identifiers - add :col)
   an ambiguous name lists matches[n] (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms; nothing is analysed
 examples[4]:
@@ -93,6 +97,8 @@ async function run(args, ctx, invoked) {
     const warning = opened.warning ? { warning: opened.warning } : {};
     // Resolve to exactly one Symbol before building a program.
     let resolved;
+    let local;
+    let miss;
     if (target.kind === "name") {
         const groups = resolveNameTarget(opened, target, f);
         if (groups.length === 0) {
@@ -113,13 +119,33 @@ async function run(args, ctx, invoked) {
                     `Run \`ts-axi ${name} ${outside[0].file}:${outside[0].nameLine}\` to use the nearest tsconfig of that file`,
                 ]));
             }
+            miss = missFallback(opened, target, f);
+            if (miss.hits.length > 1) {
+                return out(block({ ...warning, symbol: label, ambiguous: `${miss.hits.length} Declarations outside the index - pick one`, ...missRows(miss, MATCH_ROWS) }), helpBlock(miss.hits.slice(0, 3).map((h) => `Run \`ts-axi ${name} ${h.at}\` for the one ${h.localTo !== undefined ? `in ${h.localTo}` : `in ${h.decl.file}`}`)));
+            }
+            const hit = miss.hits[0];
+            if (hit && hit.localTo !== undefined) {
+                // A local is file-scoped: the normal position path finds every Reference.
+                local = hit;
+                resolved = { absFile: hit.abs, pos: hit.decl.namePos, decl: hit.decl };
+            }
+            else if (hit) {
+                return outsideMiss(opened, hit, { warning, name, limit, label: target.member ?? target.name });
+            }
+        }
+        if (resolved) {
+            // A local found by the miss fallback.
+        }
+        else if (groups.length === 0) {
             // No Declaration, but the name may still be written: an untyped property set up elsewhere.
             const text = f.fuzzy ? [] : textualScan(opened, target.member ?? target.name);
+            const outsideText = outsideLine(opened, text);
             if (show.grep) {
                 return out(block({
                     ...warning,
                     matches: 0,
                     note: "no declaration found - textual matches only",
+                    ...(outsideText ? { outside_project: outsideText } : {}),
                     unresolved: text.length === 0 ? 0 : text.slice(0, limit),
                     ...(text.length > limit ? { unresolved_total: text.length } : {}),
                 }), helpBlock([
@@ -128,17 +154,19 @@ async function run(args, ctx, invoked) {
                 ]));
             }
             const suggested = suggestions(opened, target);
-            return out(block({ ...warning, matches: 0, ...(suggested.length > 0 ? { did_you_mean: suggested } : {}) }), helpBlock([
-                ...(text.length > 0 ? [textualScanHint(label, text.length)] : []),
+            return out(block({ ...warning, matches: 0, ...(suggested.length > 0 ? { did_you_mean: suggested } : {}), ...(miss ? notSearched(miss) : {}) }), helpBlock([
+                ...(text.length > 0 ? [textualScanHint(label, text.length, text.filter((r) => isOutside(opened, opened.index.abs(r.file))).length)] : []),
                 ...suggested.slice(0, 2).map((s) => `Run \`ts-axi ${name} ${s}\``),
                 ...(f.fuzzy ? [] : [`Run \`ts-axi def ${label} --fuzzy\` for substring matches`]),
             ]));
         }
-        if (groups.length > 1) {
+        else if (groups.length > 1) {
             return out(block({ ...warning, symbol: label, ambiguous: `${groups.length} Symbols - pick one`, ...matchRows(groups) }), helpBlock(narrowHints(opened, name, groups, f, `${label}${filterSuffix(f, project)}`, target)));
         }
-        const decl = groups[0].decls[0];
-        resolved = { absFile: opened.index.abs(decl.file), pos: decl.namePos, decl, seeds: [...new Set(groups[0].decls.map((d) => opened.index.abs(d.file)))] };
+        else {
+            const decl = groups[0].decls[0];
+            resolved = { absFile: opened.index.abs(decl.file), pos: decl.namePos, decl, seeds: [...new Set(groups[0].decls.map((d) => opened.index.abs(d.file)))] };
+        }
     }
     else {
         const at = resolvePosition(opened.index, ctx.cwd, target);
@@ -150,13 +178,21 @@ async function run(args, ctx, invoked) {
         }
         resolved = at.kind === "decl" ? { absFile: at.abs, pos: at.decl.namePos, decl: at.decl } : { absFile: at.abs, pos: at.pos };
     }
-    let built = semanticFor(opened, resolved.seeds ?? [resolved.absFile], resolved.decl ? REFS_HOPS : 0);
-    if (!resolved.decl && built.scope) {
+    // A file the tsconfig leaves out brings the other left-out files that name the identifier.
+    const seedsOf = (files, abs, pos) => {
+        if (!isOutside(opened, abs))
+            return files;
+        const sf = opened.index.sourceFile(abs);
+        const word = sf ? /^[\w$]+/.exec(sf.text.slice(pos))?.[0] : undefined;
+        return [...new Set([...files, ...(word ? outsideSeeds(opened, word) : [])])];
+    };
+    let built = semanticFor(opened, seedsOf(resolved.seeds ?? [resolved.absFile], resolved.absFile, resolved.pos), resolved.decl ? REFS_HOPS : 0);
+    if (!resolved.decl && (built.scope || isOutside(opened, resolved.absFile))) {
         // A use position: find its Declaration in a small program, then scope around the declaring file.
         const at = built.semantic.definitionAt(resolved.absFile, resolved.pos);
         if (at && at.line > 0)
             resolved = { absFile: at.absFile, pos: at.pos };
-        built = semanticFor(opened, [resolved.absFile], REFS_HOPS);
+        built = semanticFor(opened, seedsOf([resolved.absFile], resolved.absFile, resolved.pos), REFS_HOPS);
     }
     const { semantic, scope } = built;
     const def = semantic.definitionAt(resolved.absFile, resolved.pos);
@@ -166,8 +202,17 @@ async function run(args, ctx, invoked) {
     const decl = (found && registrationOf(found, opened.index.declarations(opened.index.abs(found.file)))) ?? found;
     const kind = decl?.kind ?? kindFromScriptElement(def?.kind ?? semantic.quickInfo(resolved.absFile, resolved.pos)?.kind ?? "");
     const symbol = decl?.qualifiedName ?? def?.name ?? label;
-    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 declaredAt = local ? local.at : decl ? `${decl.file}:${decl.nameLine}` : def && def.line > 0 ? `${def.file}:${def.line}` : "(outside the Project)";
+    const declaredAbs = decl ? opened.index.abs(decl.file) : def && def.line > 0 ? def.absFile : undefined;
+    const header = {
+        ...warning,
+        ...projectFields(opened),
+        symbol,
+        kind,
+        declared_at: declaredAt,
+        ...(local ? { local_to: local.localTo } : {}),
+        ...(declaredAbs && isOutside(opened, declaredAbs) ? { project: outsideReason(opened, declaredAbs) } : {}),
+    };
     const explicit = Boolean(project || opened.settings.project);
     const declaredFile = decl?.file ?? (def && def.line > 0 ? def.file : undefined);
     const localFile = isPlainLocal(opened.index, decl) ? opened.index.abs(decl.file) : undefined;
@@ -180,6 +225,26 @@ async function run(args, ctx, invoked) {
         ? renderCallers(semantic, opened, resolved, header, { ...o, limit, depth })
         : renderRefs(semantic, opened, resolved, header, { ...o, limit, kind });
 }
+/**
+ * One Declaration in a file the tsconfig leaves out: no semantic program for a name target, so the
+ * textual rows of the name (Project + left-out files) and the position target that does run one.
+ */
+function outsideMiss(opened, hit, o) {
+    const rows = textualScan(opened, o.label).filter((r) => !(r.file === hit.decl.file && r.line === hit.decl.nameLine));
+    const outsideText = outsideLine(opened, rows);
+    return out(block({
+        ...o.warning,
+        matches: 0,
+        declared_at: `${hit.decl.file}:${hit.decl.nameLine}`,
+        project: hit.outside,
+        ...(outsideText ? { outside_project: outsideText } : {}),
+        unresolved: rows.length === 0 ? 0 : rows.slice(0, o.limit),
+        ...(rows.length > o.limit ? { unresolved_total: rows.length } : {}),
+    }), helpBlock([
+        `Run \`ts-axi ${o.name} ${hit.at}\` for semantic ${o.name === "callers" ? "call sites" : "References"} - a position target adds the left-out files to the program`,
+        `Run \`ts-axi def ${hit.at}\` for the declaration body`,
+    ]));
+}
 /** Template usages as `--grep` rows. */
 export function templateRows(files, target) {
     const texts = new Map(files.map((f) => [f.rel, f.text]));

package/dist/src/project.js

@@ -102,7 +102,7 @@ export function discoverTsconfig(startDir, options = {}) {
         dir = parent;
     }
 }
-function isSourceFile(name) {
+export function isSourceFile(name) {
     return SOURCE_EXTENSIONS.some((ext) => name.endsWith(ext)) && !/\.d\.[mc]?ts$/.test(name);
 }
 /** Every source file below `root` from the shared listing (`src/walk.ts`: git, else fs walk), minus `.d.ts`. */
@@ -204,7 +204,7 @@ export function parseSource(file, text) {
 export function relPath(root, abs) {
     return relative(root, abs).split(sep).join("/");
 }
-function declMatches(decl, query) {
+export function declMatches(decl, query) {
     const needle = query.fuzzy ? query.name.toLowerCase() : query.name;
     if (query.member !== undefined) {
         if (decl.parentName === undefined)

package/dist/src/scope.js

@@ -99,8 +99,21 @@ export function planScope(index, seeds, hops, extra = []) {
 }
 /** A LanguageService over the Project, or over the importer subgraph of `seeds` when the Project is scoped. */
 export function semanticFor(ctx, seeds, hops, extra = []) {
-    if (!ctx.index.project.scope)
-        return { semantic: createSemanticProject(ctx.index) };
+    if (!ctx.index.project.scope) {
+        // A seed the tsconfig leaves out (an excluded dir) joins the Project's roots, or the service cannot see it.
+        const known = new Set(ctx.index.files);
+        const outside = seeds.filter((s) => !known.has(s) && sourceFs().exists(s));
+        if (outside.length === 0)
+            return { semantic: createSemanticProject(ctx.index) };
+        const { project } = ctx.index;
+        return {
+            semantic: createSemanticProject(ctx.index, {
+                rootNames: [...project.fileNames, ...new Set(outside)],
+                options: project.options,
+                currentDirectory: project.tsconfig ? dirname(project.tsconfig) : ctx.index.root,
+            }),
+        };
+    }
     const { program, info } = planScope(ctx.index, seeds, hops, extra);
     return { semantic: createSemanticProject(ctx.index, program), scope: info };
 }

package/dist/src/symbols.js

@@ -390,6 +390,25 @@ export function collectDeclarations(sf, file) {
                 !(ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node)),
         });
     };
+    const classMembers = (cls, exported, qualified) => {
+        for (const member of cls.members) {
+            if (ts.isSemicolonClassElement(member) || ts.isClassStaticBlockDeclaration(member) || ts.isIndexSignatureDeclaration(member))
+                continue;
+            const memberName = ts.isConstructorDeclaration(member) ? "constructor" : nameText(member.name, sf);
+            if (!memberName)
+                continue;
+            const nameNode = ts.isConstructorDeclaration(member)
+                ? member.getChildren(sf).find((c) => c.kind === ts.SyntaxKind.ConstructorKeyword)
+                : member.name;
+            add(member, nameNode, memberName, exported && !isPrivateMember(member), qualified);
+        }
+    };
+    /** `module.exports = class X {...}`, `exports.X = class {...}`, `export default class {...}` expression. */
+    const exportedClass = (cls, fallback) => {
+        const name = cls.name?.text ?? fallback;
+        add(cls, cls.name, name, true);
+        classMembers(cls, true, name);
+    };
     const nested = (raw) => {
         raws.push({ ...raw, qualifiedName: raw.qualifiedName ?? (raw.parentName ? `${raw.parentName}.${raw.name}` : raw.name), hasBody: true });
     };
@@ -737,7 +756,9 @@ export function collectDeclarations(sf, file) {
             return;
         const target = compact(left, sf);
         if (target === "module.exports") {
-            if (ts.isObjectLiteralExpression(right))
+            if (ts.isClassExpression(right))
+                exportedClass(right, "exports");
+            else if (ts.isObjectLiteralExpression(right))
                 objectMembers(right, "exports", true);
             else if (asFunction(right))
                 returnedMembers(asFunction(right).body, "exports", true);
@@ -746,6 +767,8 @@ export function collectDeclarations(sf, file) {
             return;
         }
         if (target === `exports.${left.name.text}` || target === `module.exports.${left.name.text}`) {
+            if (ts.isClassExpression(right))
+                return exportedClass(right, left.name.text);
             if (ts.isObjectLiteralExpression(right))
                 objectMembers(right, left.name.text, true);
             else
@@ -829,7 +852,9 @@ export function collectDeclarations(sf, file) {
         }
         else if (ts.isExportAssignment(statement)) {
             const value = unwrap(statement.expression);
-            if (ts.isObjectLiteralExpression(value))
+            if (ts.isClassExpression(value))
+                exportedClass(value, "default");
+            else if (ts.isObjectLiteralExpression(value))
                 objectMembers(value, "default", true);
             else
                 stateArray(statement.expression);
@@ -876,17 +901,7 @@ export function collectDeclarations(sf, file) {
                 add(statement, statement.name, name, exported, parent);
                 const qualified = parent ? `${parent}.${name}` : name;
                 if (ts.isClassDeclaration(statement)) {
-                    for (const member of statement.members) {
-                        if (ts.isSemicolonClassElement(member) || ts.isClassStaticBlockDeclaration(member) || ts.isIndexSignatureDeclaration(member))
-                            continue;
-                        const memberName = ts.isConstructorDeclaration(member) ? "constructor" : nameText(member.name, sf);
-                        if (!memberName)
-                            continue;
-                        const nameNode = ts.isConstructorDeclaration(member)
-                            ? member.getChildren(sf).find((c) => c.kind === ts.SyntaxKind.ConstructorKeyword)
-                            : member.name;
-                        add(member, nameNode, memberName, exported && !isPrivateMember(member), qualified);
-                    }
+                    classMembers(statement, exported, qualified);
                 }
                 else if (ts.isInterfaceDeclaration(statement)) {
                     for (const member of statement.members) {

package/package.json

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