@shrkcrft/boundaries 0.1.0-alpha.28 → 0.1.0-alpha.30

package/dist/baseline/compute-baseline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/compute-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKpD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAenB"}
+{"version":3,"file":"compute-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/compute-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAenB"}

package/dist/baseline/compute-baseline.js

@@ -1,5 +1,6 @@
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
+import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
 import { extractTokens } from "../extract/extract-tokens.js";
 /**
  * Compute a baseline from the extraction DSL — the pure alternative to shelling
@@ -17,7 +18,7 @@ export function computeBaselineFromExtractor(projectRoot, source, excludeDirs =
     const files = [...cache.entries()]
         .filter(([path]) => matchesAny(path, source.files ?? []))
         .map(([path, content]) => ({ path, content }));
-    const res = extractTokens(source, files);
+    const res = extractTokens(source, files, { tsconfigPaths: loadTsconfigPaths(projectRoot) });
     if (res.error) {
         return { text: '[]', ids: [], filesScanned: files.length, error: res.error };
     }

package/dist/extract/extract-tokens.d.ts

@@ -1,4 +1,5 @@
 import { type IWiringSource } from '@shrkcrft/core';
+import type { ITsconfigPathsMap } from '../scan/tsconfig-aliases.js';
 /** A file made available to an extractor. */
 export interface IExtractFileEntry {
     /** Project-relative POSIX path. */
@@ -11,11 +12,28 @@ export interface IExtractedSite {
     readonly file: string;
     readonly line: number;
 }
+/**
+ * Optional project context an extractor may need.
+ *
+ * Kept OUT of the source spec because it is not part of the rule — it is what
+ * the caller knows about the workspace. Only `import-edges` reads it today, and
+ * every other kind stays a pure function of (source, file contents).
+ */
+export interface IExtractContext {
+    /** tsconfig `paths` map, so alias specifiers resolve as the compiler would. */
+    readonly tsconfigPaths?: ITsconfigPathsMap;
+}
 /** Outcome of running one source: the sites, or a configuration error. */
 export interface IExtractResult {
     readonly sites: readonly IExtractedSite[];
     /** Set when the SOURCE is misconfigured (never thrown — rules degrade). */
     readonly error?: string;
+    /**
+     * A diagnosis for a zero-match that is CORRECT but almost certainly not what
+     * the author meant. Distinct from `error`: nothing is wrong with the source,
+     * it just cannot mean what it looks like it means.
+     */
+    readonly hint?: string;
 }
 /**
  * Run one source's extractor over the given files.
@@ -26,5 +44,5 @@ export interface IExtractResult {
  * new extractor kind for free). Never throws — a misconfigured source returns
  * an `error` and no sites.
  */
-export declare function extractTokens(source: IWiringSource, files: readonly IExtractFileEntry[]): IExtractResult;
+export declare function extractTokens(source: IWiringSource, files: readonly IExtractFileEntry[], context?: IExtractContext): IExtractResult;
 //# sourceMappingURL=extract-tokens.d.ts.map

package/dist/extract/extract-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-tokens.d.ts","sourceRoot":"","sources":["../../src/extract/extract-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAUxB,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAClC,cAAc,CA4DhB"}
+{"version":3,"file":"extract-tokens.d.ts","sourceRoot":"","sources":["../../src/extract/extract-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AASrE,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAwEhB"}

package/dist/extract/extract-tokens.js

@@ -1,5 +1,6 @@
 import { resolveExtractorAnchor, resolveExtractorKind, validateWiringSource, } from '@shrkcrft/core';
 import { safeCompile } from "../util/safe-regex.js";
+import { extractImportEdges } from "./import-edges.js";
 import { elementToken, elementValue, escapeRegex, lineOf, scanBalanced, } from "./scan-literals.js";
 /**
  * Run one source's extractor over the given files.
@@ -10,7 +11,7 @@ import { elementToken, elementValue, escapeRegex, lineOf, scanBalanced, } from "
  * new extractor kind for free). Never throws — a misconfigured source returns
  * an `error` and no sites.
  */
-export function extractTokens(source, files) {
+export function extractTokens(source, files, context = {}) {
     const error = validateWiringSource(source);
     if (error)
         return { sites: [], error };
@@ -45,6 +46,20 @@ export function extractTokens(source, files) {
         case 'json-path':
             sites = byJsonPath(source.jsonPath, files);
             break;
+        case 'filenames':
+            sites = byFilenames(source, files);
+            break;
+        case 'import-edges': {
+            const edges = extractImportEdges(source, files, {
+                ...(context.tsconfigPaths ? { tsconfigPaths: context.tsconfigPaths } : {}),
+            });
+            if (edges.error)
+                return { sites: [], error: edges.error };
+            if (edges.hint)
+                return { sites: edges.sites, hint: edges.hint };
+            sites = edges.sites;
+            break;
+        }
         default:
             return { sites: [], error: `unknown extract kind "${String(kind)}"` };
     }
@@ -68,6 +83,43 @@ export function extractTokens(source, files) {
     }
     return { sites };
 }
+/**
+ * One id per FILE, derived from its path.
+ *
+ * Every other extractor reads a file's CONTENTS, so "a declared thing must have
+ * its sibling FILE" — a `FOO_DESCRIPTOR` const paired with `FOO_DESCRIPTOR.ts` —
+ * had no expression at all. Paired with a `parity` wiring rule this asserts the
+ * correspondence in BOTH directions: a const with no file, and a file with no
+ * const.
+ *
+ * The site line is 1: the id comes from the path, not from any line in it, and
+ * claiming a more specific location would be inventing one.
+ */
+function byFilenames(source, files) {
+    const capture = source.capturePath ?? 'stem';
+    let re;
+    if (capture === 'regex') {
+        const compiled = safeCompile(source.pathPattern, source.pathPatternFlags);
+        if (!compiled.re)
+            return [];
+        re = compiled.re;
+    }
+    const sites = [];
+    for (const file of files) {
+        if (capture === 'regex') {
+            re.lastIndex = 0;
+            const m = re.exec(file.path);
+            if (m?.[1])
+                sites.push({ token: m[1], file: file.path, line: 1 });
+            continue;
+        }
+        const basename = file.path.slice(file.path.lastIndexOf('/') + 1);
+        const dot = basename.indexOf('.');
+        const token = capture === 'basename' || dot <= 0 ? basename : basename.slice(0, dot);
+        sites.push({ token, file: file.path, line: 1 });
+    }
+    return sites;
+}
 /** Capture-group-1 of a pattern, per file. */
 function byRegex(source, files) {
     const { re } = safeCompile(source.pattern, source.flags);

package/dist/extract/import-edges.d.ts

@@ -0,0 +1,49 @@
+import type { IWiringSource } from '@shrkcrft/core';
+import { type ITsconfigPathsMap } from '../scan/tsconfig-aliases.js';
+import type { IExtractFileEntry, IExtractedSite } from './extract-tokens.js';
+/**
+ * The `import-edges` extractor — the dependency graph as a rule input.
+ *
+ * Every other extractor reads file CONTENTS: a regex, an array literal, an enum
+ * body, an export list. None of them can see which file imports what, so an
+ * entire class of invariant — alias-resolved dependency direction — was
+ * inexpressible as a rule, and repos hand-rolled scripts for it (adoption
+ * ledgers, orphan scans, deprecation ratchets).
+ *
+ * This emits that missing fact as an id set, so every existing plane gets it for
+ * free: a `baseline` over the set is an adoption ledger (a LOST edge is a silent
+ * de-adoption); `direction: 'no-shrink'` over the importer set is a deprecation
+ * ratchet; a `wiring` rule whose registered side is "symbols with ≥1 importer"
+ * finds dead generated code a byte-drift gate cannot see.
+ *
+ * **On freshness.** It reads the files the caller already walked, resolving
+ * specifiers on the spot — there is no persisted graph index behind it and
+ * therefore no staleness question to get wrong. That is deliberate: a rule
+ * answering from a stale graph would be a confident false green, the exact
+ * failure this engine exists to prevent.
+ *
+ * **Honest scope.** It resolves what the text says plus tsconfig path aliases —
+ * the same resolution `check boundaries` uses. It does not follow a re-export
+ * chain to attribute a symbol to its original module: a barrel is reported as
+ * the module the consumer actually names. That is a lexer's honest answer, and
+ * `to.files` matches the resolved target when you need the real path.
+ */
+/** What an emitted id represents. */
+export type ImportEdgeEmit = 'edge' | 'symbol' | 'from';
+/** Context a caller supplies so alias specifiers resolve. */
+export interface IImportEdgeContext {
+    readonly tsconfigPaths?: ITsconfigPathsMap;
+}
+/**
+ * Extract the import edges a source selects.
+ *
+ * `files` is the CONSUMER glob (the `from` side): it reuses the field every
+ * other extractor uses, so `--changed-only` footprinting, the shared walk, and
+ * `$use` all work on it unchanged.
+ */
+export declare function extractImportEdges(source: IWiringSource, files: readonly IExtractFileEntry[], context?: IImportEdgeContext): {
+    sites: IExtractedSite[];
+    error?: string;
+    hint?: string;
+};
+//# sourceMappingURL=import-edges.d.ts.map

package/dist/extract/import-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-edges.d.ts","sourceRoot":"","sources":["../../src/extract/import-edges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAG7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAkFxD,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,OAAO,GAAE,kBAAuB,GAC/B;IAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAgF5D"}

package/dist/extract/import-edges.js

@@ -0,0 +1,157 @@
+import { matchesAny } from "../scan/glob.js";
+import { resolveAliasCandidates } from "../scan/tsconfig-aliases.js";
+import { safeCompile } from "../util/safe-regex.js";
+import { parseImportStatements } from "./parse-imports.js";
+/** Normalize a relative specifier against the importing file's directory. */
+function resolveRelative(fromFile, specifier) {
+    const dir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : '';
+    const stack = dir.split('/').filter(Boolean);
+    for (const part of specifier.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            stack.pop();
+            continue;
+        }
+        stack.push(part);
+    }
+    return stack.join('/');
+}
+/**
+ * Resolve a specifier the way the boundary engine does: relative paths against
+ * the importing file, bare specifiers through the tsconfig alias map, and
+ * anything left over kept as the literal package name.
+ */
+function resolveSpecifier(fromFile, specifier, aliases) {
+    if (specifier.startsWith('.')) {
+        return { specifier, path: resolveRelative(fromFile, specifier) };
+    }
+    if (aliases) {
+        const candidates = resolveAliasCandidates(specifier, aliases);
+        // The first candidate is the one the compiler would try first; keeping only
+        // it makes the emitted id deterministic rather than order-dependent.
+        if (candidates.length > 0)
+            return { specifier, path: candidates[0] };
+    }
+    return { specifier };
+}
+/** Whether a resolved specifier is one the rule's `to` selects. */
+function matchesTarget(resolved, to, modulePattern) {
+    const hasSelector = to.module !== undefined || to.modulePattern !== undefined || (to.files?.length ?? 0) > 0;
+    // No target selector at all means "every import" — useful when the rule
+    // narrows by symbol alone.
+    if (!hasSelector)
+        return true;
+    if (to.module !== undefined) {
+        // Exact package, or a subpath of it: `@x/generated` selects
+        // `@x/generated` and `@x/generated/views` but never `@x/generated-legacy`.
+        if (resolved.specifier === to.module || resolved.specifier.startsWith(`${to.module}/`)) {
+            return true;
+        }
+    }
+    if (modulePattern) {
+        modulePattern.lastIndex = 0;
+        if (modulePattern.test(resolved.specifier))
+            return true;
+    }
+    if (to.files && to.files.length > 0 && resolved.path !== undefined) {
+        if (matchesAny(resolved.path, to.files))
+            return true;
+        // Specifiers routinely omit the extension, so probe the usual endings
+        // rather than forcing every config to spell `*.{ts,tsx,…}` itself.
+        for (const ext of ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx']) {
+            if (matchesAny(resolved.path + ext, to.files))
+                return true;
+            if (matchesAny(`${resolved.path}/index${ext}`, to.files))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Extract the import edges a source selects.
+ *
+ * `files` is the CONSUMER glob (the `from` side): it reuses the field every
+ * other extractor uses, so `--changed-only` footprinting, the shared walk, and
+ * `$use` all work on it unchanged.
+ */
+export function extractImportEdges(source, files, context = {}) {
+    const to = source.to ?? {};
+    const emit = source.emit ?? 'edge';
+    let modulePattern;
+    if (to.modulePattern !== undefined) {
+        const compiled = safeCompile(to.modulePattern, to.modulePatternFlags);
+        if (compiled.error || !compiled.re)
+            return { sites: [], error: `to.modulePattern ${compiled.error}` };
+        modulePattern = compiled.re;
+    }
+    let symbolPattern;
+    if (to.match !== undefined) {
+        const compiled = safeCompile(to.match, to.matchFlags);
+        if (compiled.error || !compiled.re)
+            return { sites: [], error: `to.match ${compiled.error}` };
+        symbolPattern = compiled.re;
+    }
+    const sites = [];
+    for (const file of files) {
+        for (const statement of parseImportStatements(file.content)) {
+            const resolved = resolveSpecifier(file.path, statement.specifier, context.tsconfigPaths);
+            if (!matchesTarget(resolved, to, modulePattern))
+                continue;
+            const symbols = statement.bindings
+                .map((b) => b.imported ?? b.local)
+                .filter((name) => {
+                if (!symbolPattern)
+                    return true;
+                symbolPattern.lastIndex = 0;
+                return symbolPattern.test(name);
+            });
+            // A symbol filter that matched nothing means this statement is not a hit,
+            // even though its module was: the rule asked about specific symbols.
+            if (symbolPattern && symbols.length === 0)
+                continue;
+            if (emit === 'from') {
+                sites.push({ token: file.path, file: file.path, line: statement.line });
+                continue;
+            }
+            if (symbols.length === 0) {
+                // A side-effect or type-only import binds no name; the edge is still a
+                // real dependency, so it is reported against the module it names.
+                if (emit === 'symbol')
+                    continue;
+                sites.push({
+                    token: `${file.path} → ${resolved.specifier}`,
+                    file: file.path,
+                    line: statement.line,
+                });
+                continue;
+            }
+            for (const symbol of symbols) {
+                sites.push({
+                    token: emit === 'symbol' ? symbol : `${file.path} → ${symbol}`,
+                    file: file.path,
+                    line: statement.line,
+                });
+            }
+        }
+    }
+    // The one place a user's intuition reliably trips: `to.files` matches an
+    // import's DIRECTLY-resolved path, and a symbol re-exported through a barrel
+    // resolves to the package entry, not the deep file. "Edges to files in
+    // generated/**" then finds nothing, correctly but unhelpfully. Detecting the
+    // exact shape of that dead end and naming the fix costs one conditional.
+    //
+    // Narrow on purpose. A rule that ALREADY targets by module has been told to
+    // use the thing it is using, which is worse than saying nothing — so the
+    // hint fires only when `to.files` is the sole target selector.
+    const targetsByFilesOnly = (to.files?.length ?? 0) > 0 && to.module === undefined && to.modulePattern === undefined;
+    if (sites.length === 0 && files.length > 0 && targetsByFilesOnly) {
+        return {
+            sites,
+            hint: '0 edges via `to.files` — that matches an import\'s DIRECTLY-resolved path, so a symbol ' +
+                're-exported through a barrel/package resolves to the package entry, not the deep file. ' +
+                'Target by `to.module` + `to.match` instead.',
+        };
+    }
+    return { sites };
+}

package/dist/extract/inspect-source.d.ts

@@ -10,6 +10,12 @@ export interface ISourceInspection {
     readonly sites: readonly IExtractedSite[];
     /** Set when the source is misconfigured. */
     readonly error?: string;
+    /**
+     * A diagnosis for a zero-match that is technically correct but almost
+     * certainly not what the author meant — surfaced alongside the loud skip so
+     * the dead end explains itself.
+     */
+    readonly hint?: string;
 }
 /**
  * Resolve ONE source against the tree and report what it matched.

package/dist/extract/inspect-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-source.d.ts","sourceRoot":"","sources":["../../src/extract/inspect-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEzE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAgBnB"}
+{"version":3,"file":"inspect-source.d.ts","sourceRoot":"","sources":["../../src/extract/inspect-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGzE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAoBnB"}

package/dist/extract/inspect-source.js

@@ -1,6 +1,7 @@
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
 import { extractTokens } from "./extract-tokens.js";
+import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
 /**
  * Resolve ONE source against the tree and report what it matched.
  *
@@ -16,12 +17,16 @@ export function inspectSource(projectRoot, source, excludeDirs = []) {
     const files = [...cache.entries()]
         .filter(([path]) => matchesAny(path, globs))
         .map(([path, content]) => ({ path, content }));
-    const res = extractTokens(source, files);
+    // `import-edges` resolves alias specifiers the way the compiler would, so it
+    // needs the project's tsconfig paths. Loading it here (rather than inside the
+    // extractor) keeps every extractor a pure function of its inputs.
+    const res = extractTokens(source, files, { tsconfigPaths: loadTsconfigPaths(projectRoot) });
     const sites = [...res.sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.token.localeCompare(b.token));
     return {
         filesScanned: files.length,
         ids: [...new Set(sites.map((s) => s.token))].sort(),
         sites,
         ...(res.error ? { error: res.error } : {}),
+        ...(res.hint ? { hint: res.hint } : {}),
     };
 }

package/dist/extract/parse-imports.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The ONE import-statement parser.
+ *
+ * Two features need to read import statements out of source text: the
+ * `--fix` planner (does this sink bind the token, and how?) and the
+ * `import-edges` extractor (which file imports what, from where?). A second
+ * parser would drift from the first, and the two would then disagree about
+ * what a file imports — which is precisely the class of silent disagreement
+ * this engine exists to eliminate. So both consume this.
+ *
+ * It is a lexer, not a compiler: it answers what the text says, which is the
+ * largest thing that stays honest across `.ts`, `.tsx`, `.mts` and plain JS
+ * with one code path.
+ */
+/** How a name entered scope through an import. */
+export type ImportBindingKind = 'named' | 'default' | 'namespace';
+/** One name bound by an import statement. */
+export interface IImportBinding {
+    /** The name as used in the file (after any `as` alias). */
+    readonly local: string;
+    readonly kind: ImportBindingKind;
+    /** The exported name, for a named import (differs from `local` when aliased). */
+    readonly imported?: string;
+}
+/**
+ * How the dependency was expressed.
+ *
+ * `--fix` only ever extends the STATIC import block, so it filters on this;
+ * the dependency graph counts every kind, because a fence that missed
+ * `await import('../secret')` would have a hole exactly where someone
+ * motivated would put one.
+ */
+export type ImportStatementKind = 'import' | 'reexport' | 'side-effect' | 'dynamic' | 'require';
+/** One parsed dependency statement. */
+export interface IParsedImport {
+    readonly specifier: string;
+    readonly bindings: readonly IImportBinding[];
+    /** 1-based line of the statement's start. */
+    readonly line: number;
+    /** Character offset of the statement's start. */
+    readonly index: number;
+    /** The matched statement text, for style detection (quotes, semicolons). */
+    readonly raw: string;
+    /** True for `import type { … }` — binds no runtime value. */
+    readonly typeOnly: boolean;
+    readonly kind: ImportStatementKind;
+}
+/**
+ * Every import / re-export statement in `content`, with the names it binds.
+ *
+ * A `import type { … }` statement is returned with `typeOnly: true` rather than
+ * dropped: the `--fix` planner must ignore it (it binds no value), while the
+ * dependency graph legitimately counts it as an edge. Returning it and letting
+ * each caller decide keeps that judgement at the call site instead of baking
+ * one feature's answer into the shared parser.
+ */
+export declare function parseImportStatements(content: string): IParsedImport[];
+//# sourceMappingURL=parse-imports.d.ts.map

package/dist/extract/parse-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-imports.d.ts","sourceRoot":"","sources":["../../src/extract/parse-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAElE,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhG,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAgDtE"}

package/dist/extract/parse-imports.js

@@ -0,0 +1,155 @@
+/**
+ * The ONE import-statement parser.
+ *
+ * Two features need to read import statements out of source text: the
+ * `--fix` planner (does this sink bind the token, and how?) and the
+ * `import-edges` extractor (which file imports what, from where?). A second
+ * parser would drift from the first, and the two would then disagree about
+ * what a file imports — which is precisely the class of silent disagreement
+ * this engine exists to eliminate. So both consume this.
+ *
+ * It is a lexer, not a compiler: it answers what the text says, which is the
+ * largest thing that stays honest across `.ts`, `.tsx`, `.mts` and plain JS
+ * with one code path.
+ */
+/**
+ * Matches one import/re-export statement up to its specifier.
+ *
+ * The clause may span lines (a multi-line `{ … }` block is normal) but never
+ * contains a `;` or a quote, which is what keeps the lazy match from running
+ * past the end of its own statement into the next one.
+ *
+ * `export … from '…'` is matched too: a re-export is an edge in the dependency
+ * graph exactly like an import, and a barrel that is invisible here would make
+ * every consumer behind it invisible as well.
+ */
+const IMPORT_STATEMENT = /\b(import|export)\s+([^;'"]*?)\s*from\s*['"]([^'"]+)['"]\s*;?/g;
+/**
+ * The specifier-only forms, which bind no name: a side-effect import, a dynamic
+ * `import()`, and `require()`. Each is a real dependency edge — the boundary
+ * engine counts all three — even though none of them introduces a binding.
+ */
+const SIDE_EFFECT_IMPORT = /\bimport\s*['"]([^'"]+)['"]\s*;?/g;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const REQUIRE_CALL = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+/** Split a clause on commas that are OUTSIDE a `{ … }` block. */
+function splitTopLevel(clause) {
+    const out = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of clause) {
+        if (ch === '{')
+            depth += 1;
+        if (ch === '}')
+            depth -= 1;
+        if (ch === ',' && depth === 0) {
+            out.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim() !== '')
+        out.push(current);
+    return out;
+}
+/** Parse the clause between `import`/`export` and `from`. */
+function parseClause(clause) {
+    const bindings = [];
+    for (const part of splitTopLevel(clause.trim())) {
+        const piece = part.trim();
+        if (piece === '')
+            continue;
+        if (piece.startsWith('*')) {
+            const m = /^\*\s*as\s+([A-Za-z_$][\w$]*)$/.exec(piece);
+            if (m)
+                bindings.push({ local: m[1], kind: 'namespace' });
+            continue;
+        }
+        if (piece.startsWith('{')) {
+            const inner = piece.replace(/^\{/, '').replace(/\}$/, '');
+            for (const spec of inner.split(',')) {
+                const s = spec.trim();
+                // An inline `type` specifier binds no runtime value.
+                if (s === '' || /^type\b/.test(s))
+                    continue;
+                const aliased = /^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/.exec(s);
+                if (aliased) {
+                    bindings.push({ local: aliased[2], kind: 'named', imported: aliased[1] });
+                    continue;
+                }
+                if (/^[A-Za-z_$][\w$]*$/.test(s)) {
+                    bindings.push({ local: s, kind: 'named', imported: s });
+                }
+            }
+            continue;
+        }
+        if (/^[A-Za-z_$][\w$]*$/.test(piece)) {
+            bindings.push({ local: piece, kind: 'default' });
+        }
+    }
+    return bindings;
+}
+/** 1-based line number of `index` within `content`. */
+function lineAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i += 1) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+/**
+ * Every import / re-export statement in `content`, with the names it binds.
+ *
+ * A `import type { … }` statement is returned with `typeOnly: true` rather than
+ * dropped: the `--fix` planner must ignore it (it binds no value), while the
+ * dependency graph legitimately counts it as an edge. Returning it and letting
+ * each caller decide keeps that judgement at the call site instead of baking
+ * one feature's answer into the shared parser.
+ */
+export function parseImportStatements(content) {
+    const out = [];
+    const claimed = [];
+    let m;
+    IMPORT_STATEMENT.lastIndex = 0;
+    while ((m = IMPORT_STATEMENT.exec(content)) !== null) {
+        const clause = m[2];
+        const typeOnly = /^type\b/.test(clause.trim());
+        claimed.push({ start: m.index, end: m.index + m[0].length });
+        out.push({
+            specifier: m[3],
+            bindings: typeOnly ? [] : parseClause(clause),
+            line: lineAt(content, m.index),
+            index: m.index,
+            raw: m[0],
+            typeOnly,
+            kind: m[1] === 'export' ? 'reexport' : 'import',
+        });
+    }
+    // A `import x from 'y'` also contains the text `import … 'y'`, so the
+    // specifier-only patterns would re-report it. Skipping anything inside an
+    // already-claimed span keeps each dependency counted exactly once.
+    const overlapsClaimed = (start) => claimed.some((c) => start >= c.start && start < c.end);
+    for (const [re, kind] of [
+        [SIDE_EFFECT_IMPORT, 'side-effect'],
+        [DYNAMIC_IMPORT, 'dynamic'],
+        [REQUIRE_CALL, 'require'],
+    ]) {
+        re.lastIndex = 0;
+        while ((m = re.exec(content)) !== null) {
+            if (overlapsClaimed(m.index))
+                continue;
+            out.push({
+                specifier: m[1],
+                bindings: [],
+                line: lineAt(content, m.index),
+                index: m.index,
+                raw: m[0],
+                typeOnly: false,
+                kind,
+            });
+        }
+    }
+    return out.sort((a, b) => a.index - b.index);
+}