@shrkcrft/boundaries 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/extract/import-edges.js

@@ -0,0 +1,170 @@
+import { globListSelects } from "../scan/glob.js";
+import { resolveAliasCandidates } from "../scan/tsconfig-aliases.js";
+import { safeCompile } from "../util/safe-regex.js";
+import { parseImportStatementsWithMeta } 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) {
+        // `to.files` is a glob LIST like any other: a `!` entry subtracts.
+        if (globListSelects(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 (globListSelects(resolved.path + ext, to.files))
+                return true;
+            if (globListSelects(`${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;
+    }
+    // Zoning is judged by where the statement's KEYWORD starts and whether its
+    // specifier is a real string — the same authority `check boundaries` uses
+    // (round 11, 6.1a#import-edges-scan). The extractor receives RAW content:
+    // pre-blanking with `scan: 'code'` used to erase every specifier (a string)
+    // and turn the rule vacuous. Unset → comment-aware, matching `check
+    // boundaries`; `scan: 'all'` is the raw escape hatch. (`strings` / `comments`
+    // are rejected at config load: an import statement is code.)
+    const zone = source.scan === 'all' ? 'all' : 'code';
+    const sites = [];
+    let blankedChars = 0;
+    for (const file of files) {
+        const parsed = parseImportStatementsWithMeta(file.content, { zone });
+        blankedChars += parsed.blankedChars;
+        for (const statement of parsed.statements) {
+            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.',
+            blankedChars,
+        };
+    }
+    return { sites, blankedChars };
+}

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

@@ -1,15 +1,29 @@
-import type { IWiringSource } from '@shrkcrft/core';
+import { type IWiringSource } from '@shrkcrft/core';
+import type { IGlobListUnits } from '../util/i-glob-list-units.js';
+import type { IUnreadFile } from '../util/unread-file.js';
 import { type IExtractedSite } from './extract-tokens.js';
 /** What one source actually resolved to against the live tree. */
 export interface ISourceInspection {
-    /** Files the globs matched (after the shared walk's skip rules). */
+    /** Files the globs matched and the reader READ (after the shared walk's skip rules). */
     readonly filesScanned: number;
+    /**
+     * Files the globs matched that the reader did NOT read (over the read cap,
+     * or unreadable). A source with any is not "matched nothing" and not fully
+     * examined: its coverage names them (`readScopeCoverage`).
+     */
+    readonly unread: readonly IUnreadFile[];
     /** Distinct ids extracted, sorted. */
     readonly ids: readonly string[];
     /** Every capture site, in stable (file, line) order. */
     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.
@@ -20,5 +34,26 @@ export interface ISourceInspection {
  * extract?" has one answer computed one way. A rule that matched 0 is then a
  * fact the tooling can report, not something an author has to notice.
  */
-export declare function inspectSource(projectRoot: string, source: IWiringSource, excludeDirs?: readonly string[]): ISourceInspection;
+export declare function inspectSource(projectRoot: string, rawSource: IWiringSource, excludeDirs?: readonly string[]): ISourceInspection;
+/**
+ * ONE source's glob units: the dead ones (each with its reason), the live
+ * negations with what each excludes, and how many globs were checked — through
+ * the one dead-unit decision, `globListUnits`.
+ *
+ * It reads the same walk {@link inspectSource} reads (inside
+ * `withFileReadCache` a second call over the same globs is a memo hit), so the
+ * answer is about the files the source actually SEES — after `SKIP_DIRS` and
+ * `excludeDirs`. The walk is the list's POSITIVE set (every file an inclusion
+ * glob matched), so a negation is judged by what it removes from it, never by
+ * what it "matches". A file over the read cap was still MATCHED, so a glob that
+ * matched only such a file is not dead. Only `files[]` walk globs count: an
+ * `import-edges` `to.files` matches resolved specifiers, not walked files.
+ */
+export declare function sourceGlobUnits(projectRoot: string, source: IWiringSource, excludeDirs?: readonly string[]): IGlobListUnits;
+/**
+ * The globs of ONE source that do nothing — a dead unit inside a rule whose
+ * other globs may still keep it connected. The labels of
+ * {@link sourceGlobUnits}`.dead` (a dead negation keeps its `!`).
+ */
+export declare function sourceDeadGlobs(projectRoot: string, source: IWiringSource, excludeDirs?: readonly string[]): readonly string[];
 //# sourceMappingURL=inspect-source.d.ts.map

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,EAAyB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGzE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,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,SAAS,EAAE,aAAa,EACxB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,cAAc,CAEhB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,SAAS,MAAM,EAAE,CAEnB"}

package/dist/extract/inspect-source.js

@@ -1,6 +1,8 @@
-import { matchesAny } from "../scan/glob.js";
-import { readMatchingFiles } from "../util/walk-files.js";
+import { normalizeWiringSource } from '@shrkcrft/core';
+import { readSelectedFiles } from "../util/read-selected-files.js";
+import { readGlobListUnits } from "../util/dead-glob-units.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.
  *
@@ -10,18 +12,64 @@ import { extractTokens } from "./extract-tokens.js";
  * extract?" has one answer computed one way. A rule that matched 0 is then a
  * fact the tooling can report, not something an author has to notice.
  */
-export function inspectSource(projectRoot, source, excludeDirs = []) {
+export function inspectSource(projectRoot, rawSource, excludeDirs = []) {
+    // The engine entry normalises idempotently (round 13): a loaded source comes
+    // back equal; a hand-built one with a `{ pattern, expectEmpty }` entry reads
+    // its pattern as the glob, and a malformed entry is a misconfiguration —
+    // never a glob reader handed an object.
+    const normalized = normalizeWiringSource(rawSource);
+    if (!normalized.ok)
+        return { filesScanned: 0, unread: [], ids: [], sites: [], error: normalized.error.message };
+    const source = normalized.value;
     const globs = source.files ?? [];
-    const cache = readMatchingFiles(projectRoot, globs, new Set(excludeDirs));
-    const files = [...cache.entries()]
-        .filter(([path]) => matchesAny(path, globs))
-        .map(([path, content]) => ({ path, content }));
-    const res = extractTokens(source, files);
+    const { files, unread } = sourceFiles(projectRoot, globs, excludeDirs);
+    // `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,
+        unread,
         ids: [...new Set(sites.map((s) => s.token))].sort(),
         sites,
         ...(res.error ? { error: res.error } : {}),
+        ...(res.hint ? { hint: res.hint } : {}),
+    };
+}
+/**
+ * ONE source's glob units: the dead ones (each with its reason), the live
+ * negations with what each excludes, and how many globs were checked — through
+ * the one dead-unit decision, `globListUnits`.
+ *
+ * It reads the same walk {@link inspectSource} reads (inside
+ * `withFileReadCache` a second call over the same globs is a memo hit), so the
+ * answer is about the files the source actually SEES — after `SKIP_DIRS` and
+ * `excludeDirs`. The walk is the list's POSITIVE set (every file an inclusion
+ * glob matched), so a negation is judged by what it removes from it, never by
+ * what it "matches". A file over the read cap was still MATCHED, so a glob that
+ * matched only such a file is not dead. Only `files[]` walk globs count: an
+ * `import-edges` `to.files` matches resolved specifiers, not walked files.
+ */
+export function sourceGlobUnits(projectRoot, source, excludeDirs = []) {
+    return readGlobListUnits(projectRoot, source.files ?? [], new Set(excludeDirs));
+}
+/**
+ * The globs of ONE source that do nothing — a dead unit inside a rule whose
+ * other globs may still keep it connected. The labels of
+ * {@link sourceGlobUnits}`.dead` (a dead negation keeps its `!`).
+ */
+export function sourceDeadGlobs(projectRoot, source, excludeDirs = []) {
+    return sourceGlobUnits(projectRoot, source, excludeDirs).dead.map((u) => u.glob);
+}
+/**
+ * The files a source's glob list SELECTS (an inclusion glob matches, no
+ * negation does), after the shared walk's skip rules: read, and unread.
+ */
+function sourceFiles(projectRoot, globs, excludeDirs) {
+    const selected = readSelectedFiles(projectRoot, globs, new Set(excludeDirs));
+    return {
+        files: [...selected.files.entries()].map(([path, content]) => ({ path, content })),
+        unread: [...selected.unread],
     };
 }

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

@@ -0,0 +1,80 @@
+/**
+ * Which text an import statement may be read from.
+ *
+ *   - `code` (the default): the statement's keyword must start in executable
+ *     code and its specifier must be a real string literal; comments are
+ *     blanked before matching, so an apostrophe inside a comment within a
+ *     multi-line clause can no longer cut a real import short.
+ *   - `all`: the raw file text — every byte, comments included. The explicit
+ *     escape hatch (`check boundaries --include-comments`, `scan: 'all'`).
+ */
+export type ImportParseZone = 'code' | 'all';
+/** Options for {@link parseImportStatements}. */
+export interface IParseImportsOptions {
+    /** Default `code`. */
+    readonly zone?: ImportParseZone;
+}
+/** 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.
+ *
+ * In the default `code` zone a statement is kept only when its keyword starts
+ * in a code zone AND its specifier quote opens a real string literal — the
+ * same {@link zoneKeepsAt} authority the policy plane and the extraction DSL
+ * use. Offsets, lines and `raw` always refer to the ORIGINAL text (blanking
+ * preserves length), so callers that splice `content` stay correct.
+ */
+export declare function parseImportStatements(content: string, options?: IParseImportsOptions): IParsedImport[];
+/**
+ * {@link parseImportStatements}, plus how many characters the zone BLANKED
+ * before matching: the comment characters under `code`, `0` under `all`.
+ *
+ * The `import-edges` extractor zones itself (a pre-blanked buffer would erase
+ * every specifier), so this is the figure it reports as its `blankedChars` —
+ * the number `wiring explain` / `gates explain` print as
+ * `scan: code (N chars blanked)`. Without it the note claimed a zone removed
+ * nothing while it had dropped a commented-out edge.
+ */
+export declare function parseImportStatementsWithMeta(content: string, options?: IParseImportsOptions): {
+    readonly statements: IParsedImport[];
+    readonly blankedChars: number;
+};
+//# 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":"AA8BA;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7C,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;CACjC;AAED,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;AAsID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,aAAa,EAAE,CAEjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC;IAAE,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA4EzE"}

package/dist/extract/parse-imports.js

@@ -0,0 +1,254 @@
+/**
+ * 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.
+ *
+ * Round 11 (6.1a) made it the ONLY import extractor: `scanImports` (every
+ * boundary check, drift, impact, review packet…) and the `import-edges` DSL
+ * extractor both read through here, so "what does this file import" has one
+ * answer. By default it reads CODE only — a commented-out import, an import in
+ * a doc-comment code fence, or `"import x from 'y'"` inside a string is not a
+ * dependency. Measured against the TypeScript oracle over this repo (1716
+ * files): 79 phantom edges and 1 real miss before, 0 / 0 after.
+ */
+import { blankZoneKinds, lexCodeZones, zoneContaining, zoneKeepsAt, } from "./code-zones.js";
+/**
+ * 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 `;`, a quote or a BACKTICK, which is what keeps the lazy match
+ * from running past the end of its own statement into the next one. No real
+ * import clause holds a backtick; prose does — a doc comment's
+ * `` `shrk import <format> --populate` `` used to open a clause that ran on to
+ * the next real `from '…'`, so the raw reading (`--include-comments`,
+ * `scan: 'all'`) filed that import on the comment's line. The old scanImports
+ * regex excluded the backtick too; raw-mode lines match it again.
+ *
+ * `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.
+ *
+ * Linear by construction (round 11, 6.1(b)): the old form
+ * `\s+([^;'"]*?)\s*from` put three whitespace-consuming quantifiers side by
+ * side, which is fine on raw source and O(run²) once comments are blanked into
+ * long runs of spaces (6 / 24 / 94 / 371 ms as a JSDoc block doubled). Here a
+ * single `\s` separates the keyword from ONE lazy class, and `\bfrom` needs no
+ * whitespace quantifier in front of it, so each keyword costs one forward scan
+ * to its statement's end. Verified byte-identical to the old form on the raw
+ * text of every file in this repo. Do not reintroduce adjacent `\s*`/`\s+`
+ * around a lazy class — `r75-import-scan-zones.test.ts` times it.
+ */
+const IMPORT_STATEMENT = /\b(import|export)\s([^;'"`]*?)\bfrom\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;
+}
+/** Offsets of every `\n` in `content`, for O(log n) line lookups. */
+function newlineOffsets(content) {
+    const out = [];
+    for (let i = content.indexOf('\n'); i !== -1; i = content.indexOf('\n', i + 1))
+        out.push(i);
+    return out;
+}
+/**
+ * 1-based line of `index`: one plus the number of newlines BEFORE it. The
+ * index is the keyword's own offset — the old `scanImports` regex consumed the
+ * preceding `\n` with `(?:^|\s)`, so every import after line 1 was reported
+ * one line early (round 11, 6.1a#line-numbers).
+ */
+function lineAt(newlines, index) {
+    let lo = 0;
+    let hi = newlines.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (newlines[mid] < index)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo + 1;
+}
+/** Zones blanked before matching in `code` mode: comments only — the specifier is a string. */
+const COMMENT_ZONES = new Set(['comment']);
+/**
+ * Offset (within the match) of the specifier's OPENING quote. Every pattern
+ * ends `<quote><specifier><quote>` followed only by whitespace, `;` or `)`,
+ * and no clause may contain a quote, so the last quote in the match closes the
+ * specifier.
+ */
+function specifierQuoteOffset(match, specifier) {
+    const closing = Math.max(match.lastIndexOf("'"), match.lastIndexOf('"'));
+    return closing - specifier.length - 1;
+}
+/**
+ * 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.
+ *
+ * In the default `code` zone a statement is kept only when its keyword starts
+ * in a code zone AND its specifier quote opens a real string literal — the
+ * same {@link zoneKeepsAt} authority the policy plane and the extraction DSL
+ * use. Offsets, lines and `raw` always refer to the ORIGINAL text (blanking
+ * preserves length), so callers that splice `content` stay correct.
+ */
+export function parseImportStatements(content, options = {}) {
+    return parseImportStatementsWithMeta(content, options).statements;
+}
+/**
+ * {@link parseImportStatements}, plus how many characters the zone BLANKED
+ * before matching: the comment characters under `code`, `0` under `all`.
+ *
+ * The `import-edges` extractor zones itself (a pre-blanked buffer would erase
+ * every specifier), so this is the figure it reports as its `blankedChars` —
+ * the number `wiring explain` / `gates explain` print as
+ * `scan: code (N chars blanked)`. Without it the note claimed a zone removed
+ * nothing while it had dropped a commented-out edge.
+ */
+export function parseImportStatementsWithMeta(content, options = {}) {
+    const zone = options.zone ?? 'code';
+    const zones = zone === 'code' ? lexCodeZones(content) : undefined;
+    const blanked = zones ? blankZoneKinds(content, zones, COMMENT_ZONES) : undefined;
+    const text = blanked ? blanked.content : content;
+    // Built on first use: a file whose statements are all zoned out (or that has
+    // none) never needs a line table.
+    let newlines;
+    const lineOfIndex = (index) => lineAt((newlines ??= newlineOffsets(content)), index);
+    const keep = (index, match, specifier) => {
+        if (!zones)
+            return true;
+        const quote = index + specifierQuoteOffset(match, specifier);
+        // The specifier's quote must OPEN a plain string literal. "Inside a string"
+        // is not enough: `export const t = \`import z from 'w'\`` starts with a
+        // code `export`, and its `'w'` sits inside the template literal.
+        const specZone = zoneContaining(zones, quote);
+        return (zoneKeepsAt('code', zones, index) &&
+            zoneKeepsAt('strings', zones, quote) &&
+            specZone !== undefined &&
+            specZone.start === quote &&
+            specZone.template !== true);
+    };
+    const out = [];
+    const claimed = [];
+    let m;
+    IMPORT_STATEMENT.lastIndex = 0;
+    while ((m = IMPORT_STATEMENT.exec(text)) !== null) {
+        const specifier = m[3];
+        if (!keep(m.index, m[0], specifier))
+            continue;
+        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,
+            bindings: typeOnly ? [] : parseClause(clause),
+            line: lineOfIndex(m.index),
+            index: m.index,
+            raw: content.slice(m.index, m.index + m[0].length),
+            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(text)) !== null) {
+            if (overlapsClaimed(m.index))
+                continue;
+            const specifier = m[1];
+            if (!keep(m.index, m[0], specifier))
+                continue;
+            out.push({
+                specifier,
+                bindings: [],
+                line: lineOfIndex(m.index),
+                index: m.index,
+                raw: content.slice(m.index, m.index + m[0].length),
+                typeOnly: false,
+                kind,
+            });
+        }
+    }
+    return { statements: out.sort((a, b) => a.index - b.index), blankedChars: blanked?.blankedChars ?? 0 };
+}