ts-axi 0.1.1 → 0.1.3

package/dist/src/commands/refs.js

@@ -1,19 +1,34 @@
-import { expectPositionals, flag, intFlag, parseArgs } from "../args.js";
-import { createSemanticProject } from "../project.js";
+import { relative, sep } from "node:path";
+import { bool, expectPositionals, flag, intFlag, parseArgs } from "../args.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;
-const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), -P <tsconfig>, --json`;
+const SHARED_FLAGS = `--kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace> (narrows a name), --in <dir|glob> (repeatable; Declarations in these files), --exported, --fuzzy, --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} rows), --test-glob <glob> (repeatable; extra Test file pattern), --via (adds via rows with a via column), -P <tsconfig>, --json`;
+const VIA_DOC = `via_interface: n (Iface.member) = References through an interface or base member the Symbol implements or overrides - they MAY reach it; not in refs_total
+  via_implementations: n (Impl.member) = References to implementations or overrides of the Symbol; not in refs_total
+  implementations: n = members that implement or override the Symbol (their Declarations are never refs)
+  matches: 0 under -P lists found_outside_project[n]{file,line} when the name is declared outside that Project
+  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[9]:
+flags[11]:
   ${SHARED_FLAGS}
+  --implementations (lists implementations[n]{file,line,symbol} instead of the count)
   --kind calls = same as \`ts-axi callers\`
 output:
   symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,context} (Declarations excluded), elapsed_ms
+  ${VIA_DOC}
   an ambiguous name lists matches[n] + the disambiguated forms; nothing is analysed
 examples[4]:
   ts-axi refs User.save
@@ -22,12 +37,13 @@ examples[4]:
   ts-axi refs runSync --limit 200
 `;
 export const CALLERS_HELP = `usage: ts-axi callers <name | Class.member | path:line[:col]> [flags]
-flags[10]:
+flags[11]:
   ${SHARED_FLAGS}
   --depth <1-3> (default 1; levels > 1 print callers_depthN[n]{caller,file,count}, no locations)
 output:
   symbol, kind, declared_at, refs_total, files, tests, refs[n]{file,line,caller,context}, elapsed_ms
   caller = enclosing function or method; (top-level) for module code
+  ${VIA_DOC}
 examples[3]:
   ts-axi callers runSync
   ts-axi callers User.save --depth 2
@@ -45,7 +61,8 @@ async function run(args, ctx, invoked) {
         ...TARGET_FLAGS,
         { name: "--limit" },
         { name: "--test-glob", repeatable: true },
-        ...(invoked === "calls" ? [{ name: "--depth" }] : []),
+        { name: "--via", boolean: true },
+        ...(invoked === "calls" ? [{ name: "--depth" }] : [{ name: "--implementations", boolean: true }]),
     ];
     const parsed = parseArgs(args, specs, command);
     const [raw] = expectPositionals(parsed, 1, `${command} <name | Class.member | path:line[:col]> [flags]`);
@@ -57,6 +74,7 @@ async function run(args, ctx, invoked) {
     const label = targetLabel(target);
     const project = flag(parsed, "-P");
     const name = mode === "calls" ? "callers" : "refs";
+    const show = { via: bool(parsed, "--via"), implementations: invoked === "refs" && bool(parsed, "--implementations") };
     const started = performance.now();
     const opened = open(ctx.cwd, parsed, positionStartDir(ctx.cwd, target));
     const warning = opened.warning ? { warning: opened.warning } : {};
@@ -65,6 +83,23 @@ async function run(args, ctx, invoked) {
     if (target.kind === "name") {
         const groups = resolveNameTarget(opened, target, f);
         if (groups.length === 0) {
+            // Under an explicit Project the name may live in a sibling one: say so before suggesting --fuzzy.
+            const outside = project || opened.settings.project
+                ? findOutsideProject(opened.index, { name: target.name, ...(target.member !== undefined ? { member: target.member } : {}), fuzzy: f.fuzzy })
+                : [];
+            if (outside.length > 0) {
+                const tsconfig = nearestTsconfig(opened.index.abs(outside[0].file), opened.root);
+                const rel = tsconfig ? relative(ctx.cwd, tsconfig).split(sep).join("/") : undefined;
+                return out(block({
+                    ...warning,
+                    matches: 0,
+                    found_outside_project: outside.map((d) => ({ file: d.file, line: d.nameLine })),
+                    hint: `symbol is declared outside the selected project - run with -P ${rel ?? "<its tsconfig>"} or without -P`,
+                }), helpBlock([
+                    ...(rel ? [`Run \`ts-axi ${name} ${label} -P ${rel}\``] : []),
+                    `Run \`ts-axi ${name} ${outside[0].file}:${outside[0].nameLine}\` to use the nearest tsconfig of that file`,
+                ]));
+            }
             const suggested = suggestions(opened, target);
             return out(block({ ...warning, matches: 0, ...(suggested.length > 0 ? { did_you_mean: suggested } : {}) }), helpBlock([
                 ...suggested.slice(0, 2).map((s) => `Run \`ts-axi ${name} ${s}\``),
@@ -75,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);
@@ -87,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 })
-        : renderRefs(semantic, opened, resolved, header, { limit, started, symbol, declaredAt, kind });
+        ? 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);
@@ -113,32 +193,72 @@ function footer(semantic, started, touched) {
     const diagnostics = semantic.diagnosticsCount(touched);
     return { elapsed_ms: Math.round(performance.now() - started), ...(diagnostics > 0 ? { diagnostics } : {}) };
 }
+/** `via_interface` / `via_implementations` counts, plus the hint to see their rows. */
+function viaFields(via, bases) {
+    const base = via.filter((v) => v.through === "base");
+    const impl = via.filter((v) => v.through === "implementation");
+    return {
+        ...(bases.length > 0 || base.length > 0 ? { via_interface: viaLine(base.length, [...bases, ...base.map((v) => v.via)]) } : {}),
+        ...(impl.length > 0 ? { via_implementations: viaLine(impl.length, impl.map((v) => v.via)) } : {}),
+    };
+}
+/** Direct rows, plus via rows (with a `via` column) under `--via`. */
+function mergedRows(direct, via, show) {
+    return show.via ? sortRows([...direct, ...via]) : direct;
+}
 function renderRefs(semantic, opened, resolved, header, o) {
-    const rows = sortRows(semantic.findReferences(resolved.absFile, resolved.pos).filter((r) => !r.isDefinition));
+    const split = semantic.referenceSplit(resolved.absFile, resolved.pos);
+    const rows = sortRows([...split.direct]);
+    const via = sortRows([...split.via]);
+    const impls = sortRows([...split.implementations]);
     const { files, tests, fileList } = summary(opened, rows);
-    const shown = rows.slice(0, o.limit);
-    const truncated = shown.length < rows.length;
+    const listed = mergedRows(rows, via, o.show);
+    const shown = listed.slice(0, o.limit);
+    const truncated = shown.length < listed.length;
     const help = [];
     if (truncated) {
         help.push(o.limit < MAX_LIMIT
-            ? `Showing ${shown.length} of ${rows.length}; run \`ts-axi refs ${o.declaredAt} --limit ${Math.min(MAX_LIMIT, rows.length)}\` for more`
-            : `Showing ${shown.length} of ${rows.length}; narrow by reading one file at a time`);
+            ? `Showing ${shown.length} of ${listed.length}; run \`ts-axi refs ${o.declaredAt}${o.show.via ? " --via" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`
+            : `Showing ${shown.length} of ${listed.length}; narrow by reading one file at a time`);
     }
+    if (via.length > 0 && !o.show.via)
+        help.push(`Run \`ts-axi refs ${o.declaredAt} --via\` for the ${via.length} via References (${viaNames(via)})`);
+    if (impls.length > 0 && !o.show.implementations)
+        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,
         files,
         tests,
-        ...(rows.length === 0
+        ...viaFields(via, split.bases),
+        ...(impls.length > 0
+            ? { implementations: o.show.implementations ? impls.map((r) => ({ file: r.file, line: r.line, symbol: r.name })) : impls.length }
+            : {}),
+        ...(shown.length === 0
             ? {}
-            : { refs: shown.map((r) => ({ file: r.file, line: r.line, context: contextCell(opened, r) })) }),
+            : {
+                refs: shown.map((r) => ({
+                    file: r.file,
+                    line: r.line,
+                    ...(o.show.via ? { via: r.via ?? "-" } : {}),
+                    context: contextCell(opened, r),
+                })),
+            }),
         ...(truncated ? { truncated: true } : {}),
+        ...outside.fields,
+        ...scopeFields(o.scope),
         ...footer(semantic, o.started, fileList),
     }), helpBlock(help));
 }
+function viaNames(via) {
+    return [...new Set(via.map((v) => v.via))].join("; ");
+}
 function itemKey(site) {
     return `${site.item.file}#${site.item.selectionSpan.start}`;
 }
@@ -170,15 +290,17 @@ 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]);
+    const rows = sortRows(sites.filter((s) => s.via === undefined));
+    const via = sortRows(sites.filter((s) => s.via !== undefined));
     const { files, tests, fileList } = summary(opened, rows);
-    const shown = rows.slice(0, o.limit);
-    const truncated = shown.length < rows.length;
+    const listed = mergedRows(rows, via, o.show);
+    const shown = listed.slice(0, o.limit);
+    const truncated = shown.length < listed.length;
     const levels = {};
     const visited = new Set();
-    let level = rows;
+    let level = listed;
     for (let d = 2; d <= o.depth; d++) {
         level = nextLevel(semantic, level, visited);
         const agg = depthRows(level);
@@ -190,22 +312,38 @@ function renderCallers(semantic, opened, resolved, header, o) {
     }
     const help = [];
     if (truncated) {
-        help.push(`Showing ${shown.length} of ${rows.length}; run \`ts-axi callers ${o.declaredAt} --limit ${Math.min(MAX_LIMIT, rows.length)}\` for more`);
+        help.push(`Showing ${shown.length} of ${listed.length}; run \`ts-axi callers ${o.declaredAt}${o.show.via ? " --via" : ""} --limit ${Math.min(MAX_LIMIT, listed.length)}\` for more`);
     }
+    if (via.length > 0 && !o.show.via)
+        help.push(`Run \`ts-axi callers ${o.declaredAt} --via\` for the ${via.length} via calls (${viaNames(via)})`);
     const top = shown.find((r) => r.caller !== "(top-level)");
     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,
         files,
         tests,
-        ...(rows.length === 0
+        ...viaFields(via, []),
+        ...(shown.length === 0
             ? {}
-            : { refs: shown.map((r) => ({ file: r.file, line: r.line, caller: r.caller, context: contextCell(opened, r) })) }),
+            : {
+                refs: shown.map((r) => ({
+                    file: r.file,
+                    line: r.line,
+                    caller: r.caller,
+                    ...(o.show.via ? { via: r.via ?? "-" } : {}),
+                    context: contextCell(opened, r),
+                })),
+            }),
         ...(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() };
+}