ts-axi 0.1.2 → 0.1.3

package/README.md

@@ -75,6 +75,20 @@ npx skills add cmosgh/ts-axi --skill ts-axi
 
 <!-- TODO(phase 4): paste real examples for def / refs / outline / config from the fixture project. -->
 
+## Monorepos
+
+No configuration and no new files in your repo: ts-axi detects the layout from what is already there - `nx.json` (projects = `project.json` dirs, or a legacy `workspace.json`), `pnpm-workspace.yaml`, `package.json` `workspaces`, or a root `tsconfig.json` that only holds `references`. The home view prints `workspace: nx (14 projects)`.
+
+Without `-P`, `refs`, `callers` and `impact` do not type-check the whole repo. They build the program from a subgraph: the declaring file (for `impact`, the touched files) plus every file that imports it, found by a fast text scan of import specifiers that follows `tsconfig.base.json` `paths`, workspace package names and `export * from` barrels. A caller in another project is found; the cost tracks the subgraph, not the repo. Each result says what was analysed:
+
+```
+scope: nx workspace - 30 of 5433 files (seeds 1; importers 29)
+```
+
+`scope_partial: true` means the importer scan stopped at its cap (50k files or 3 s); the help line says what is missing. `-P <tsconfig>` still analyses exactly one project; when it finds nothing, `found_outside_project` lists the importers outside it. A `-P` tsconfig that only holds `references` (an Nx project's `tsconfig.json`) is expanded to the configs it references: `tsconfig: libs/shared/tsconfig.json (2 referenced configs)`.
+
+Files are listed with `git ls-files` (tracked plus untracked, gitignore applied), so nested worktrees and ignored copies are never analysed. Outside git, a directory walk skips `node_modules`, build output, `.claude`, `.cursor`, `.idea`, `.vscode` and any nested checkout.
+
 ## 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.
@@ -100,7 +114,7 @@ Any other key is a `VALIDATION_ERROR` naming the valid ones. `--test-glob <glob>
 One dependency: the `typescript` compiler API (ADR in `docs/adr/0001-typescript-language-service-engine.md`).
 
 - `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) 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.
+- `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.
 - Type errors in the analysed project never block anything; they are reported as a `diagnostics` count.
 

package/dist/src/commands/common.js

@@ -8,6 +8,7 @@ import { usageError } from "../errors.js";
 import { hasGlobMagic, matchesGlob } from "../glob.js";
 import { openProject } from "../project.js";
 import { loadSettings } from "../settings.js";
+import { byDepthThenPath } from "../walk.js";
 import { clip, didYouMean, groupSymbols, KINDS, kindOf, signatureOf, } from "../symbols.js";
 export const BODY_LINES = 60;
 export const CONTEXT_MAX = 100;
@@ -71,7 +72,15 @@ export function resolveNameTarget(ctx, target, f) {
         ...(target.member !== undefined ? { member: target.member } : {}),
         fuzzy: f.fuzzy,
     });
-    return groupSymbols(applyFilters(ctx, found, f));
+    // Shallowest path first: the canonical copy before nested duplicates.
+    return groupSymbols(applyFilters(ctx, found, f)).sort((a, b) => byDepthThenPath(a.primary.file, b.primary.file) || a.decls[0].nameLine - b.decls[0].nameLine);
+}
+/** `tsconfig: x (n referenced configs)` when a references-only tsconfig was expanded. */
+export function projectFields(ctx) {
+    const { tsconfig, referenced } = ctx.index.project;
+    if (!tsconfig || referenced === undefined)
+        return {};
+    return { tsconfig: `${relative(ctx.cwd, tsconfig).split(sep).join("/")} (${referenced} referenced configs)` };
 }
 export function suggestions(ctx, target) {
     const names = [...ctx.index.allNames()].filter((n) => (target.member === undefined ? !n.includes(".") : n.includes(".")));

package/dist/src/commands/def.js

@@ -1,5 +1,5 @@
 import { bool, expectPositionals, flag, parseArgs } from "../args.js";
-import { createSemanticProject } from "../project.js";
+import { semanticFor } from "../scope.js";
 import { block, fenced, helpBlock, out } from "../render.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
 import { BODY_LINES, declarationAt, filterSuffix, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, } from "./common.js";
@@ -63,7 +63,7 @@ export async function defCommand(args, ctx) {
             return out(block({ position: label, identifiers: at.candidates }), helpBlock(at.candidates.slice(0, 3).map((c) => `Run \`ts-axi def ${at.file}:${c.line}:${c.col}\` for ${c.name}`)));
         }
         // A reference, not a Declaration: ask the checker where it is declared.
-        const semantic = createSemanticProject(opened.index);
+        const { semantic } = semanticFor(opened, [at.abs], 0);
         const def = semantic.definitionAt(at.abs, at.pos);
         const decl = def && def.line > 0 ? declarationAt(opened.index, def.absFile, def.pos, kindFromScriptElement(def.kind)) : undefined;
         if (!decl) {

package/dist/src/commands/home.js

@@ -5,8 +5,9 @@ import { usageError } from "../errors.js";
 import { currentBranch, dirtyFileCount, isGitRepo } from "../git.js";
 import { block, helpBlock, out } from "../render.js";
 import { SETTINGS_FILE, isTestFile, loadSettings, readSettingsFile } from "../settings.js";
+import { listFiles, skipDir } from "../walk.js";
+import { detectWorkspace, hasMultiProjectSignal, isMultiProject } from "../workspace.js";
 const SOURCE_EXT = /\.(?:[cm]?[jt]s|[jt]sx)$/;
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
 /** The view runs at session start: bound the file walk by count and time. */
 const WALK_CAP = 20_000;
 const WALK_DEADLINE_MS = 600;
@@ -15,8 +16,8 @@ const HOME_SPECS = [
     { name: "--test-glob", repeatable: true },
     { name: "--project", alias: "-P" },
 ];
-/** Does `dir` hold a TS/JS source within `depth` levels (node_modules skipped)? */
-function hasSources(dir, depth) {
+/** Does `dir` hold a TS/JS source within `depth` levels (shared skip rule)? */
+function hasSources(dir, depth, root = dir) {
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -30,36 +31,11 @@ function hasSources(dir, depth) {
     }
     if (depth === 0)
         return false;
-    return entries.some((e) => e.isDirectory() && e.name !== "node_modules" && e.name !== ".git" && hasSources(join(dir, e.name), depth - 1));
+    return entries.some((e) => e.isDirectory() && !skipDir(e.name, join(dir, e.name), root) && hasSources(join(dir, e.name), depth - 1, root));
 }
-/** Implicit project: every source below `root`, minus node_modules, dist, build, .git. */
+/** Implicit project: every source below `root` from the shared listing (git, else a bounded fs walk). */
 function walkSources(root) {
-    const files = [];
-    const deadline = Date.now() + WALK_DEADLINE_MS;
-    let capped = false;
-    const stack = [root];
-    while (stack.length > 0 && !capped) {
-        const dir = stack.pop();
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                if (!SKIP_DIRS.has(entry.name))
-                    stack.push(join(dir, entry.name));
-            }
-            else if (entry.isFile() && SOURCE_EXT.test(entry.name)) {
-                files.push(join(dir, entry.name));
-            }
-        }
-        if (files.length >= WALK_CAP || Date.now() > deadline)
-            capped = true;
-    }
-    return { files, capped };
+    return listFiles(root, (name) => SOURCE_EXT.test(name) && !/\.d\.[mc]?ts$/.test(name), { maxFiles: WALK_CAP, deadline: Date.now() + WALK_DEADLINE_MS });
 }
 function findTsconfig(cwd) {
     let dir = cwd;
@@ -73,14 +49,16 @@ function findTsconfig(cwd) {
         dir = parent;
     }
 }
-async function tsconfigFiles(tsconfig) {
-    const ts = (await import("typescript")).default;
-    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
-    if (read.error)
+async function tsconfigFiles(tsconfig, root) {
+    // Loaded lazily: the TypeScript module is only needed when a tsconfig exists.
+    const { loadProject } = await import("../project.js");
+    try {
+        const project = loadProject(root, { path: tsconfig, implicit: false });
+        return { files: project.fileNames, capped: false, ...(project.referenced !== undefined ? { referenced: project.referenced } : {}) };
+    }
+    catch {
         return { files: [], capped: false };
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfig), undefined, tsconfig);
-    const files = parsed.fileNames.filter((f) => !f.split(/[\\/]/).includes("node_modules"));
-    return { files, capped: false };
+    }
 }
 function rel(root, path) {
     return relative(root, path).split(sep).join("/") || ".";
@@ -112,17 +90,24 @@ function resolveTsconfig(cwd, settings) {
     }
     return findTsconfig(cwd);
 }
-export async function homeCommand(args) {
+export async function homeCommand(args, ctx) {
     const parsed = parseArgs(args, HOME_SPECS, "ts-axi");
     expectPositionals(parsed, 0, "ts-axi [-P <tsconfig>] [--test-glob <glob>]");
-    const cwd = process.cwd();
+    const cwd = ctx?.cwd ?? process.cwd();
     const project = flag(parsed, "--project");
     const settings = loadSettings(cwd, {
         testGlobs: flags(parsed, "--test-glob"),
         ...(project !== undefined ? { project } : {}),
     });
     const tsconfig = resolveTsconfig(cwd, settings);
-    if (tsconfig === undefined && !hasSources(cwd, PROBE_DEPTH)) {
+    // Same rule as the semantic commands: no explicit project + a multi-project workspace = workspace scope.
+    let workspace;
+    if (settings.project === undefined && (tsconfig === undefined || hasMultiProjectSignal(settings.root))) {
+        const detected = detectWorkspace(settings.root);
+        if (isMultiProject(detected.kind))
+            workspace = detected;
+    }
+    if (tsconfig === undefined && workspace === undefined && !hasSources(cwd, PROBE_DEPTH)) {
         return out(block({ project: "none" }), helpBlock([
             "Run `ts-axi outline <file>` on any .ts/.js file; it needs no project",
             "Run `ts-axi --help` for all commands",
@@ -130,7 +115,9 @@ export async function homeCommand(args) {
     }
     const [git, counted] = await Promise.all([
         gitSummary(cwd),
-        tsconfig !== undefined ? tsconfigFiles(tsconfig) : Promise.resolve(walkSources(settings.root)),
+        workspace
+            ? Promise.resolve({ files: workspace.sourceFiles, capped: false })
+            : tsconfig !== undefined ? tsconfigFiles(tsconfig, settings.root) : Promise.resolve(walkSources(settings.root)),
     ]);
     const testFiles = counted.files.filter((f) => isTestFile(rel(settings.root, f), settings)).length;
     const plus = counted.capped ? "+" : "";
@@ -143,7 +130,12 @@ export async function homeCommand(args) {
     help.push("Run `ts-axi outline <file>` to list the declarations in a file", "Run `ts-axi def <name>` to find where a symbol is declared", "Run `ts-axi config` to see or change the test-file globs", "Run `ts-axi --help` for all commands");
     return out(block({
         root: settings.root,
-        tsconfig: tsconfig === undefined ? "implicit" : rel(settings.root, tsconfig),
+        ...(workspace ? { workspace: `${workspace.kind} (${workspace.projects.length} projects)` } : {}),
+        tsconfig: workspace
+            ? "nearest per file - workspace scope"
+            : tsconfig === undefined
+                ? "implicit"
+                : `${rel(settings.root, tsconfig)}${counted.referenced !== undefined ? ` (${counted.referenced} referenced configs)` : ""}`,
         source_files: counted.capped ? `${counted.files.length}${plus}` : counted.files.length,
         test_globs: settings.testGlobs.length,
         test_files: counted.capped ? `${testFiles}${plus}` : testFiles,

package/dist/src/commands/impact.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, relative, sep } from "node:path";
 import ts from "typescript";
 import { bool, intFlag, parseArgs, flag } from "../args.js";
@@ -6,17 +6,18 @@ import { changedRanges, parseUnifiedDiff } from "../diff.js";
 import { AxiError, usageError } from "../errors.js";
 import { diffNameStatus, diffUnified, isGitRepo, resolveBaseRev, showFile, untrackedFiles } from "../git.js";
 import { allocateBudget, classifyFile, compareChanges, formatRanges, inRanges, localOnlyLine, matchKey, reverseApply, wordMatches, } from "../impact.js";
-import { createSemanticProject, loadProject, SOURCE_EXTENSIONS } from "../project.js";
+import { loadProject, SOURCE_EXTENSIONS } from "../project.js";
 import { block, helpBlock, out } from "../render.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike } from "../symbols.js";
-import { contextOf, lineOf, open } from "./common.js";
+import { IMPACT_HOPS, scopeFields, scopeHelp, semanticFor } from "../scope.js";
+import { walkFiles } from "../walk.js";
+import { contextOf, lineOf, open, projectFields } from "./common.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const SIDE_ROWS = 20;
 /** Non-TS files `--grep` also searches: templates that use TS exports the checker never sees. */
 const GREP_EXTRA = [".astro", ".vue", ".svelte", ".mdx", ".html"];
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
 export const IMPACT_HELP = `usage: ts-axi impact [<git-range> | -] [flags]
 input:
   (none) = working tree vs HEAD (staged + unstaged + untracked); --staged = index vs HEAD
@@ -34,6 +35,7 @@ output:
   blind_spots[n]{symbol,file,line,reason} = uses the checker cannot follow (any; string keys; unresolved export *)
   skipped[n]{file,reason} = files in the diff that were not analysed (.astro, .json, outside the Project)
   tests: 0 on an exported signature or body change = no Test file references it
+  scope = in a monorepo without -P the program is the touched files + two levels of importers (scope_partial: true when capped)
 examples[5]:
   ts-axi impact
   ts-axi impact --staged
@@ -223,22 +225,7 @@ function blindSpots(semantic, names, changeSet) {
     return spots;
 }
 function walkExtra(dir, outFiles) {
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith("."))
-                walkExtra(join(dir, entry.name), outFiles);
-        }
-        else if (GREP_EXTRA.some((ext) => entry.name.endsWith(ext))) {
-            outFiles.push(join(dir, entry.name));
-        }
-    }
+    outFiles.push(...walkFiles(dir, { accept: (name) => GREP_EXTRA.some((ext) => name.endsWith(ext)) }).files);
 }
 function textualMatches(opened, semantic, names, known, skipLines, changeSet) {
     const files = [...semantic.projectFiles];
@@ -324,7 +311,7 @@ function rerun(arg, parsed, extra) {
  * them): name the sibling tsconfig that includes them so tests get counted.
  */
 function specFilesHint(cwd, opened, skipped, noTests) {
-    const tsconfig = opened.location.path;
+    const tsconfig = opened.index.project.tsconfig;
     if (!tsconfig)
         return undefined;
     const outside = skipped.filter((s) => s.reason === "not in the Project");
@@ -410,6 +397,7 @@ export async function impactCommand(args, ctx) {
     const total = declChanges.length + fileLevel.length;
     const header = {
         ...(warnings.length > 0 ? { warning: warnings.join("; ") } : {}),
+        ...projectFields(opened),
         base: input.base,
         head: input.head,
         changes: total,
@@ -432,7 +420,8 @@ export async function impactCommand(args, ctx) {
         }), helpBlock(help));
     }
     // --- References (semantic, on the checkout) ---
-    const semantic = createSemanticProject(opened.index);
+    // Scoped workspace: touched files + two levels of importers; deleted or renamed-away paths still resolve so their importers count.
+    const { semantic, scope } = semanticFor(opened, analysed.filter((f) => f.status !== "deleted").map((f) => opened.index.abs(f.path)), IMPACT_HOPS, analysed.flatMap((f) => (f.status === "deleted" ? [f.path] : f.oldPath ? [f.oldPath] : [])).map((p) => opened.index.abs(p)));
     const rows = declChanges.map((change) => {
         const source = change.after ?? change.before;
         const live = change.after ? opened.index.declarations(opened.index.abs(change.file)).find((d) => matchKey(d) === change.key) : undefined;
@@ -536,6 +525,7 @@ export async function impactCommand(args, ctx) {
     const specHint = specFilesHint(ctx.cwd, opened, skipped, listed.every((r) => fileCounts(r).tests === 0));
     if (specHint)
         help.push(specHint);
+    help.push(...scopeHelp(scope));
     const notes = rows
         .filter((r) => r.change.change === "signature" && r.bases.length > 0)
         .map((r) => ({ symbol: r.symbol, note: `implements ${r.bases.join(" and ")}` }));
@@ -565,6 +555,7 @@ export async function impactCommand(args, ctx) {
         ...(grep ? capped("unresolved", unresolved) : {}),
         ...depthLevels(semantic, rows, depth),
         ...skippedBlock,
+        ...scopeFields(scope),
         elapsed_ms: Math.round(performance.now() - started),
         ...(diagnostics > 0 ? { diagnostics } : {}),
     }), helpBlock(help));

package/dist/src/commands/refs.js

@@ -1,11 +1,15 @@
 import { relative, sep } from "node:path";
 import { bool, expectPositionals, flag, intFlag, parseArgs } from "../args.js";
-import { createSemanticProject, findOutsideProject, nearestTsconfig } from "../project.js";
+import { importerClosure } from "../importers.js";
+import { findOutsideProject, nearestTsconfig } from "../project.js";
 import { viaLine } from "../references.js";
 import { block, helpBlock, out } from "../render.js";
+import { importerIndexFor, REFS_HOPS, scopeFields, scopeHelp, semanticFor } from "../scope.js";
+import { byDepthThenPath } from "../walk.js";
+import { detectWorkspace, isMultiProject } from "../workspace.js";
 import { isTestFile } from "../settings.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
-import { contextOf, declarationAt, filterSuffix, lineOf, matchRows, narrowHints, open, positionStartDir, readFilters, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
+import { contextOf, declarationAt, filterSuffix, lineOf, matchRows, narrowHints, open, positionStartDir, projectFields, readFilters, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, } from "./common.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 500;
 const DEPTH_ROWS = 50;
@@ -13,7 +17,10 @@ const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|
 const VIA_DOC = `via_interface: n (Iface.member) = References through an interface or base member the Symbol implements or overrides - they MAY reach it; not in refs_total
   via_implementations: n (Impl.member) = References to implementations or overrides of the Symbol; not in refs_total
   implementations: n = members that implement or override the Symbol (their Declarations are never refs)
-  matches: 0 under -P lists found_outside_project[n]{file,line} when the name is declared outside that Project`;
+  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`;
 export const REFS_HELP = `usage: ts-axi refs <name | Class.member | path:line[:col]> [flags]
 flags[11]:
   ${SHARED_FLAGS}
@@ -103,7 +110,7 @@ async function run(args, ctx, invoked) {
             return out(block({ ...warning, symbol: label, ambiguous: `${groups.length} Symbols - pick one`, matches: matchRows(groups) }), helpBlock(narrowHints(name, groups, f, `${label}${filterSuffix(f, project)}`)));
         }
         const decl = groups[0].decls[0];
-        resolved = { absFile: opened.index.abs(decl.file), pos: decl.namePos, decl };
+        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);
@@ -115,17 +122,62 @@ 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 };
     }
-    const semantic = createSemanticProject(opened.index);
+    let built = semanticFor(opened, resolved.seeds ?? [resolved.absFile], resolved.decl ? REFS_HOPS : 0);
+    if (!resolved.decl && built.scope) {
+        // 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);
+    }
+    const { semantic, scope } = built;
     const def = semantic.definitionAt(resolved.absFile, resolved.pos);
     const decl = resolved.decl ??
         (def && def.line > 0 ? declarationAt(opened.index, def.absFile, def.pos, kindFromScriptElement(def.kind)) : undefined);
     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, symbol, kind, declared_at: declaredAt };
+    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 };
     return mode === "calls"
-        ? renderCallers(semantic, opened, resolved, header, { limit, depth, started, symbol, declaredAt, show })
-        : renderRefs(semantic, opened, resolved, header, { limit, started, symbol, declaredAt, kind, show });
+        ? renderCallers(semantic, opened, resolved, header, { ...o, limit, depth })
+        : renderRefs(semantic, opened, resolved, header, { ...o, limit, kind });
+}
+const OUTSIDE_ROWS = 5;
+/**
+ * No References under an explicit Project: importers of the declaring file (or of a barrel
+ * re-exporting it) elsewhere in the workspace, from the syntactic importer index.
+ */
+function outsideImporters(opened, o) {
+    if (!o.explicit)
+        return { fields: {}, help: [] };
+    const workspace = detectWorkspace(opened.root);
+    if (!isMultiProject(workspace.kind))
+        return { fields: {}, help: [] };
+    const index = importerIndexFor(opened.index, workspace);
+    const closure = importerClosure(index, [o.absFile], REFS_HOPS);
+    const inProject = new Set(opened.index.files);
+    const barrels = new Set(closure.barrels);
+    const targets = [o.absFile, ...closure.barrels];
+    const needle = o.symbol.split(".").pop();
+    const rows = closure.importers
+        .filter((f) => !inProject.has(f) && !barrels.has(f) && (opened.index.text(f) ?? "").includes(needle))
+        .map((f) => {
+        const line = targets.flatMap((t) => index.importersOf(t)).find((i) => i.file === f)?.line ?? 1;
+        return { file: opened.index.rel(f), line };
+    })
+        .sort((a, b) => byDepthThenPath(a.file, b.file));
+    if (rows.length === 0)
+        return { fields: {}, help: [] };
+    return {
+        fields: {
+            found_outside_project: rows.slice(0, OUTSIDE_ROWS),
+            ...(rows.length > OUTSIDE_ROWS ? { found_outside_total: rows.length } : {}),
+            hint: `${rows.length} files outside the selected project import it - run without -P for workspace scope`,
+        },
+        help: [`Run \`ts-axi ${o.name} ${o.label}\` without -P to search the whole workspace`],
+    };
 }
 function sortRows(rows) {
     return rows.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col);
@@ -173,9 +225,12 @@ function renderRefs(semantic, opened, resolved, header, o) {
         help.push(`Run \`ts-axi refs ${o.declaredAt} --via\` for the ${via.length} via References (${viaNames(via)})`);
     if (impls.length > 0 && !o.show.implementations)
         help.push(`Run \`ts-axi refs ${o.declaredAt} --implementations\` to list the ${impls.length} implementations`);
+    const outside = rows.length === 0 ? outsideImporters(opened, o) : { fields: {}, help: [] };
+    help.unshift(...outside.help);
     if (isFunctionLike(o.kind))
         help.push(`Run \`ts-axi callers ${o.declaredAt}\` for call sites with their enclosing function`);
     help.push(`Run \`ts-axi def ${o.declaredAt}\` for the declaration body`);
+    help.push(...scopeHelp(o.scope));
     return out(block({
         ...header,
         refs_total: rows.length,
@@ -196,6 +251,8 @@ function renderRefs(semantic, opened, resolved, header, o) {
                 })),
             }),
         ...(truncated ? { truncated: true } : {}),
+        ...outside.fields,
+        ...scopeFields(o.scope),
         ...footer(semantic, o.started, fileList),
     }), helpBlock(help));
 }
@@ -233,7 +290,7 @@ function depthRows(sites) {
 function renderCallers(semantic, opened, resolved, header, o) {
     const sites = semantic.incomingCalls(resolved.absFile, resolved.pos);
     if (sites === undefined) {
-        return out(block({ ...header, refs_total: 0, note: "not callable - no call hierarchy for this Symbol", ...footer(semantic, o.started, []) }), helpBlock([`Run \`ts-axi refs ${o.declaredAt}\` for every Reference`]));
+        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`]));
     }
     const rows = sortRows(sites.filter((s) => s.via === undefined));
     const via = sortRows(sites.filter((s) => s.via !== undefined));
@@ -262,7 +319,10 @@ function renderCallers(semantic, opened, resolved, header, o) {
     const top = shown.find((r) => r.caller !== "(top-level)");
     if (top && o.depth === 1)
         help.push(`Run \`ts-axi callers ${o.declaredAt} --depth 2\` for who calls the callers`);
+    const outside = rows.length === 0 ? outsideImporters(opened, o) : { fields: {}, help: [] };
+    help.unshift(...outside.help);
     help.push(`Run \`ts-axi refs ${o.declaredAt}\` for every Reference (not only calls)`);
+    help.push(...scopeHelp(o.scope));
     return out(block({
         ...header,
         refs_total: rows.length,
@@ -282,6 +342,8 @@ function renderCallers(semantic, opened, resolved, header, o) {
             }),
         ...(truncated ? { truncated: true } : {}),
         ...levels,
+        ...outside.fields,
+        ...scopeFields(o.scope),
         ...footer(semantic, o.started, fileList),
     }), helpBlock(help));
 }

package/dist/src/importers.js

@@ -0,0 +1,182 @@
+// Syntactic reverse-import graph (regex over file text, no AST): which workspace files import
+// a given file, through relative paths, `paths` aliases, workspace package names and barrels.
+import { dirname, resolve } from "node:path";
+const PATTERNS = [
+    { re: /\bexport\s+(?:type\s+)?(?:\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s*from\s*(['"])([^'"\n]+)\1/g, reexport: true },
+    { re: /\bimport\s+(?:type\s+)?[^'";]*?\bfrom\s*(['"])([^'"\n]+)\1/g, reexport: false },
+    { re: /\bimport\s*(['"])([^'"\n]+)\1/g, reexport: false },
+    { re: /\b(?:require|import|(?:vi|jest)\.(?:mock|doMock|requireActual|importActual))\s*\(\s*(['"])([^'"\n]+)\1/g, reexport: false },
+];
+/** Static specifiers of `import`/`export ... from`, side-effect imports, `require()`, `import()`, `vi.mock()`. */
+export function extractImports(text) {
+    if (!/\b(?:import|export|require|mock)\b/.test(text))
+        return [];
+    const edges = new Map();
+    let lineStarts;
+    const lineAt = (offset) => {
+        lineStarts ??= [0, ...[...text.matchAll(/\n/g)].map((m) => m.index + 1)];
+        let lo = 0;
+        let hi = lineStarts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (lineStarts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+    for (const { re, reexport } of PATTERNS) {
+        for (const m of text.matchAll(re)) {
+            const specOffset = m.index + m[0].lastIndexOf(m[2]);
+            // A position matched by an earlier (re-export) pattern keeps that classification.
+            if (!edges.has(specOffset))
+                edges.set(specOffset, { spec: m[2], reexport, line: lineAt(specOffset) });
+        }
+    }
+    return [...edges.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => e);
+}
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+/** Resolves a specifier to a file of `files` (absolute paths); anything else (node_modules, builtins) is undefined. */
+export function createResolver(input, files) {
+    const tryPath = (p, depth = 0) => {
+        if (files.has(p))
+            return p;
+        const stem = p.replace(/\.(?:d\.)?[mc]?[jt]sx?$/, "");
+        for (const ext of EXTENSIONS)
+            if (files.has(stem + ext))
+                return stem + ext;
+        for (const ext of EXTENSIONS)
+            if (files.has(`${p}/index${ext}`))
+                return `${p}/index${ext}`;
+        // Build output in a package manifest: look for the source next to it.
+        if (depth === 0 && /[\\/](?:dist|build|lib|out)[\\/]/.test(p))
+            return tryPath(p.replace(/([\\/])(?:dist|build|lib|out)([\\/])/, "$1src$2"), 1);
+        return undefined;
+    };
+    const aliases = Object.entries(input.paths?.paths ?? {})
+        .map(([pattern, targets]) => {
+        const star = pattern.indexOf("*");
+        return { pattern, targets, prefix: star < 0 ? pattern : pattern.slice(0, star), suffix: star < 0 ? "" : pattern.slice(star + 1), wildcard: star >= 0 };
+    })
+        // Exact patterns first, then the longest prefix (TypeScript's order).
+        .sort((a, b) => Number(a.wildcard) - Number(b.wildcard) || b.prefix.length - a.prefix.length);
+    const aliasBase = input.paths?.base ?? "";
+    const fromAlias = (spec) => {
+        for (const a of aliases) {
+            let captured;
+            if (!a.wildcard) {
+                if (spec !== a.pattern)
+                    continue;
+                captured = "";
+            }
+            else {
+                if (!spec.startsWith(a.prefix) || !spec.endsWith(a.suffix) || spec.length < a.prefix.length + a.suffix.length)
+                    continue;
+                captured = spec.slice(a.prefix.length, spec.length - a.suffix.length);
+            }
+            for (const target of a.targets) {
+                const hit = tryPath(resolve(aliasBase, target.replace("*", captured)));
+                if (hit)
+                    return hit;
+            }
+        }
+        return undefined;
+    };
+    const packages = [...input.packages].sort((a, b) => b.name.length - a.name.length);
+    const fromPackage = (spec) => {
+        const pkg = packages.find((p) => spec === p.name || spec.startsWith(`${p.name}/`));
+        if (!pkg)
+            return undefined;
+        const sub = spec === pkg.name ? "." : `./${spec.slice(pkg.name.length + 1)}`;
+        const candidates = [...(pkg.exports[sub] ?? [])];
+        for (const [key, targets] of Object.entries(pkg.exports)) {
+            const star = key.indexOf("*");
+            if (star < 0 || !sub.startsWith(key.slice(0, star)) || !sub.endsWith(key.slice(star + 1)))
+                continue;
+            const captured = sub.slice(star, sub.length - (key.length - star - 1));
+            candidates.push(...targets.map((t) => t.replace("*", captured)));
+        }
+        if (sub !== ".")
+            candidates.push(resolve(pkg.dir, sub), resolve(pkg.dir, "src", sub));
+        for (const c of candidates) {
+            const hit = tryPath(c);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    return (spec, fromFile) => {
+        if (spec.startsWith(".") || spec.startsWith("/"))
+            return tryPath(resolve(dirname(fromFile), spec));
+        return fromAlias(spec) ?? fromPackage(spec);
+    };
+}
+export const IMPORTER_MAX_FILES = 50_000;
+export const IMPORTER_MAX_MS = 3_000;
+/** Reads every candidate once (bounded) and inverts its resolved imports. */
+export function buildImporterIndex(files, read, resolveSpec, options = {}) {
+    const maxFiles = options.maxFiles ?? IMPORTER_MAX_FILES;
+    const deadline = performance.now() + (options.maxMs ?? IMPORTER_MAX_MS);
+    const reverse = new Map();
+    let scanned = 0;
+    let partial = false;
+    for (const file of files) {
+        if (scanned >= maxFiles || performance.now() > deadline) {
+            partial = true;
+            break;
+        }
+        scanned++;
+        const text = read(file);
+        if (text === undefined)
+            continue;
+        const seen = new Set();
+        for (const edge of extractImports(text)) {
+            const target = resolveSpec(edge.spec, file);
+            if (!target || target === file)
+                continue;
+            const key = `${target}#${edge.reexport}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const list = reverse.get(target) ?? [];
+            list.push({ file, reexport: edge.reexport, line: edge.line });
+            reverse.set(target, list);
+        }
+    }
+    return { scanned, total: files.length, partial, importersOf: (file) => reverse.get(file) ?? [] };
+}
+/**
+ * Importers of `seeds` up to `hops` levels; a re-export (barrel) does not use a hop, so
+ * importers of a barrel that re-exports a seed count as direct importers.
+ */
+export function importerClosure(index, seeds, hops) {
+    const seedSet = new Set(seeds);
+    const importers = new Set();
+    const barrels = new Set();
+    let frontier = [...seeds];
+    const expanded = new Set(seeds);
+    for (let hop = 0; hop < hops && frontier.length > 0; hop++) {
+        const next = [];
+        const queue = [...frontier];
+        while (queue.length > 0) {
+            const file = queue.pop();
+            for (const imp of index.importersOf(file)) {
+                if (seedSet.has(imp.file))
+                    continue;
+                importers.add(imp.file);
+                if (imp.reexport)
+                    barrels.add(imp.file);
+                if (expanded.has(imp.file))
+                    continue;
+                expanded.add(imp.file);
+                if (imp.reexport)
+                    queue.push(imp.file);
+                else
+                    next.push(imp.file);
+            }
+        }
+        frontier = next;
+    }
+    return { importers: [...importers].sort(), barrels: [...barrels].sort() };
+}