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

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,37 @@ 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[];
+    /**
+     * How many characters a non-`all` `scan` zone blanked before extraction.
+     *
+     * Surfaced (not merely applied) because a zone is the one setting that can
+     * make a rule match LESS while still reading green: an author who sees the
+     * number drop can tell "my pattern was matching prose" from "my glob went
+     * stale". `explain` prints it.
+     */
+    readonly blankedChars?: number;
     /** 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 +53,26 @@ 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;
+/**
+ * Wall-clock cap for ONE file's `regex-capture` pass under a non-`all` scan
+ * zone. Checked between matches; a file that trips it contributes nothing and
+ * is NAMED (the source errors), so a partial token set can never read green.
+ */
+export declare const ZONED_REGEX_FILE_BUDGET_MS = 1000;
+/**
+ * The head regexes the anchor-based extractors run — possibly on a blanked
+ * buffer. One factory, so the linearity lock (`r75-blank-run-linearity`)
+ * times and lints the exact patterns that run, not copies of them.
+ */
+export declare function extractorHeadPatterns(anchor: string): {
+    readonly arrayLiteral: RegExp;
+    readonly objectLiteral: RegExp;
+    readonly enumBody: RegExp;
+    readonly call: RegExp;
+    readonly decorator: RegExp;
+    readonly stringUnion: RegExp;
+    readonly exportDecl: RegExp;
+    readonly exportClause: RegExp;
+};
 //# 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;AAMxB,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;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,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,CAiHhB;AA+CD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAmN/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAgBA"}

package/dist/extract/extract-tokens.js

@@ -1,5 +1,8 @@
 import { resolveExtractorAnchor, resolveExtractorKind, validateWiringSource, } from '@shrkcrft/core';
 import { safeCompile } from "../util/safe-regex.js";
+import { findBlankRunHazards } from "../util/blank-run-hazard.js";
+import { blankOutsideZone } from "./code-zones.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,41 +13,94 @@ 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 };
     const kind = resolveExtractorKind(source);
     const anchor = resolveExtractorAnchor(source);
+    // Zone the CONTENT once, up front, instead of teaching every extractor about
+    // comments. Blanking preserves length and newlines, so each extractor still
+    // reports the true `file:line` and none of them needs zone logic of its own.
+    const zone = source.scan ?? 'all';
+    let blankedChars = 0;
+    // `import-edges` zones itself (round 11, 6.1a#import-edges-scan): it judges a
+    // statement by where its KEYWORD starts, through the one import parser.
+    // Pre-blanking here erased every specifier (a string) under `scan: 'code'`,
+    // and the rule silently extracted nothing.
+    const scanned = zone === 'all' || kind === 'import-edges'
+        ? files
+        : files.map((f) => {
+            const blanked = blankOutsideZone(f.content, zone);
+            blankedChars += blanked.blankedChars;
+            return { path: f.path, content: blanked.content };
+        });
     let sites;
+    // A user pattern run on a BLANKED buffer can backtrack O(run²) on the
+    // whitespace runs the zone manufactures. Lint it (the hint reaches `gates
+    // coverage` / `explain`), and bound each file: a file over budget is a
+    // named, loud skip — the rule errors, never a silent partial.
+    let regexHint;
     switch (kind) {
-        case 'regex-capture':
-            sites = byRegex(source, files);
+        case 'regex-capture': {
+            const zoned = zone !== 'all';
+            const hazards = zoned ? findBlankRunHazards(source.pattern) : [];
+            if (hazards.length > 0)
+                regexHint = blankRunHazardHint(zone, hazards);
+            const run = byRegex(source, scanned, zoned, hazards);
+            if (run.predicted.length + run.ran.length > 0) {
+                return {
+                    sites: [],
+                    error: zonedOverBudgetError(zone, run, hazards),
+                    ...(regexHint ? { hint: regexHint } : {}),
+                    ...zoneMeta(zone, blankedChars),
+                };
+            }
+            sites = run.sites;
             break;
+        }
         case 'array-members':
-            sites = byBracketLiteral(anchor, '[', files, (el) => elementToken(el));
+            sites = byBracketLiteral(anchor, '[', scanned, (el) => elementToken(el));
             break;
         case 'object-keys':
-            sites = byBracketLiteral(anchor, '{', files, (el) => source.capture === 'value' ? elementValue(el) : elementToken(el));
+            sites = byBracketLiteral(anchor, '{', scanned, (el) => source.capture === 'value' ? elementValue(el) : elementToken(el));
             break;
         case 'enum-members':
-            sites = byEnumMembers(anchor, source.capture === 'value', files);
+            sites = byEnumMembers(anchor, source.capture === 'value', scanned);
             break;
         case 'export-names':
-            sites = byExportNames(files);
+            sites = byExportNames(scanned);
             break;
         case 'call-args':
-            sites = byCallArgs(anchor, source.argIndex ?? 0, false, files);
+            sites = byCallArgs(anchor, source.argIndex ?? 0, false, scanned);
             break;
         case 'decorator-args':
-            sites = byCallArgs(anchor, source.argIndex ?? 0, true, files);
+            sites = byCallArgs(anchor, source.argIndex ?? 0, true, scanned);
             break;
         case 'string-union-members':
-            sites = byStringUnion(anchor, files);
+            sites = byStringUnion(anchor, scanned);
             break;
         case 'json-path':
-            sites = byJsonPath(source.jsonPath, files);
+            sites = byJsonPath(source.jsonPath, scanned);
+            break;
+        case 'filenames':
+            sites = byFilenames(source, scanned);
+            break;
+        case 'import-edges': {
+            const edges = extractImportEdges(source, scanned, {
+                ...(context.tsconfigPaths ? { tsconfigPaths: context.tsconfigPaths } : {}),
+            });
+            if (edges.error)
+                return { sites: [], error: edges.error };
+            // It zones itself, so what its zone blanked is its own figure — the
+            // `scan: code (N chars blanked)` note must not read 0 over a zone that
+            // dropped a commented-out edge.
+            blankedChars += edges.blankedChars ?? 0;
+            if (edges.hint)
+                return { sites: edges.sites, hint: edges.hint, ...zoneMeta(zone, blankedChars) };
+            sites = edges.sites;
             break;
+        }
         default:
             return { sites: [], error: `unknown extract kind "${String(kind)}"` };
     }
@@ -66,15 +122,187 @@ export function extractTokens(source, files) {
             });
         }
     }
-    return { sites };
+    return { sites, ...zoneMeta(zone, blankedChars), ...(regexHint ? { hint: regexHint } : {}) };
+}
+/** The zone provenance to attach to a result — omitted entirely when unzoned. */
+function zoneMeta(zone, blankedChars) {
+    return zone === 'all' ? {} : { blankedChars };
+}
+/**
+ * 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;
+}
+/**
+ * Wall-clock cap for ONE file's `regex-capture` pass under a non-`all` scan
+ * zone. Checked between matches; a file that trips it contributes nothing and
+ * is NAMED (the source errors), so a partial token set can never read green.
+ */
+export const ZONED_REGEX_FILE_BUDGET_MS = 1000;
+/**
+ * For a pattern the blank-run lint flags: a file whose PREDICTED backtracking
+ * work (priced by each hazard's reach, below) exceeds this is skipped BEFORE
+ * the regex runs. One `exec` over such a buffer cannot be interrupted (a
+ * 16 KB newline-crossing run already costs ~300–470 ms), so the prediction is
+ * what makes the cap a real bound.
+ */
+const ZONED_HAZARD_COST_LIMIT = 2e8;
+/** Blank stretches shorter than this are ordinary indentation — not worth pricing. */
+const MIN_PRICED_RUN = 64;
+function blankRunCosts(content) {
+    let run = 0;
+    let segment = 0;
+    let newlines = 0;
+    let runCost = 0;
+    let lineCost = 0;
+    let linesTimesRun = 0;
+    for (let i = 0; i <= content.length; i += 1) {
+        const c = i < content.length ? content.charCodeAt(i) : 0;
+        if (c === 0x20) {
+            run += 1;
+            segment += 1;
+            continue;
+        }
+        if (segment >= MIN_PRICED_RUN)
+            lineCost += segment * segment;
+        segment = 0;
+        if (c === 0x0a) {
+            run += 1;
+            newlines += 1;
+            continue;
+        }
+        if (run >= MIN_PRICED_RUN) {
+            runCost += run * run;
+            linesTimesRun += (newlines + 1) * run;
+        }
+        run = 0;
+        newlines = 0;
+    }
+    return { run: runCost, line: lineCost, linesTimesRun };
 }
-/** Capture-group-1 of a pattern, per file. */
-function byRegex(source, files) {
+/** Price every flagged hazard by its OWN reach; the file costs what its worst hazard costs. */
+function predictedHazardCost(hazards, costs) {
+    let worst = { cost: 0, measure: 'Σ run²' };
+    for (const h of hazards) {
+        const priced = !h.crossesNewline
+            ? { cost: costs.line, measure: 'Σ line-run²' }
+            : h.shape === 'leading' && h.fromLineStart
+                ? { cost: costs.linesTimesRun, measure: 'Σ lines×run' }
+                : { cost: costs.run, measure: 'Σ run²' };
+        if (priced.cost > worst.cost)
+            worst = priced;
+    }
+    return worst;
+}
+/**
+ * The remedy for each hazard shape present. A LEADING quantifier is fixed by
+ * a literal anchor — never by another quantifier: a leading `[ \t]*` is still
+ * tried at every offset of a blanked line.
+ */
+function hazardRemedy(hazards) {
+    const remedies = [];
+    if (hazards.some((h) => h.shape === 'leading')) {
+        remedies.push('anchor the alternative on a literal — begin it with the token the whitespace precedes ' +
+            '(`foo[ \\t]*\\(`, not `[ \\t]*foo\\(`), since a leading whitespace quantifier of any class is tried at every offset');
+    }
+    if (hazards.some((h) => h.shape === 'adjacent')) {
+        remedies.push('collapse the touching whitespace quantifiers into one');
+    }
+    return remedies.join('; ');
+}
+/** The hint a hazardous user pattern earns under a zone — surfaced through `gates coverage` / `explain`. */
+function blankRunHazardHint(zone, hazards) {
+    const h = hazards[0];
+    const reach = hazards.every((x) => !x.crossesNewline)
+        ? ' It stops at each newline, so only a very long blanked line is costly.'
+        : '';
+    return (`pattern backtracking hazard under scan: '${zone}': ${h.message}. Blanked comments and strings become ` +
+        `long whitespace runs; ${hazardRemedy(hazards)} (or scan: 'all').${reach}`);
+}
+function namedFiles(files) {
+    return files.slice(0, 5).join(', ') + (files.length > 5 ? `, … (+${files.length - 5} more)` : '');
+}
+function formatCost(n) {
+    return n.toExponential(1).replace('e+', 'e');
+}
+/**
+ * The error for files a zoned `regex-capture` could not judge — loud, named,
+ * never a silent partial. The two causes are worded apart: a PREDICTED skip
+ * never ran the regex (so it spent nothing), a STOPPED file ran past the cap.
+ */
+function zonedOverBudgetError(zone, run, hazards) {
+    const parts = [];
+    if (run.predicted.length > 0) {
+        const worst = run.predicted.reduce((a, b) => (b.cost > a.cost ? b : a));
+        parts.push(`predicted over budget, so the regex was never run (${worst.measure} = ${formatCost(worst.cost)} > ` +
+            `${formatCost(ZONED_HAZARD_COST_LIMIT)}): ${namedFiles(run.predicted.map((p) => p.path))}`);
+    }
+    if (run.ran.length > 0) {
+        parts.push(`ran past the ${ZONED_REGEX_FILE_BUDGET_MS} ms per-file cap and was stopped: ${namedFiles(run.ran)}`);
+    }
+    const total = run.predicted.length + run.ran.length;
+    const why = hazards.length > 0 ? ` — ${hazards[0].message}` : '';
+    const fix = hazards.length > 0 ? hazardRemedy(hazards) : 'simplify the pattern';
+    return (`regex-capture under scan: '${zone}' skipped ${total} file(s): over budget — ${parts.join('; ')}${why}. ` +
+        `${fix.charAt(0).toUpperCase()}${fix.slice(1)}, or use scan: 'all'.`);
+}
+/**
+ * Capture-group-1 of a pattern, per file. Under a zone (`zoned`), each file is
+ * bounded: a FLAGGED pattern skips a file whose predicted work — each hazard
+ * priced by its own reach, so a line-bounded one pays per line — is over the
+ * limit, and any pattern stops a file that runs past the per-file budget.
+ * Both are named, never a quietly smaller token set.
+ */
+function byRegex(source, files, zoned, hazards) {
     const { re } = safeCompile(source.pattern, source.flags);
     if (!re)
-        return [];
+        return { sites: [], predicted: [], ran: [] };
     const sites = [];
+    const predicted = [];
+    const ran = [];
     for (const f of files) {
+        if (zoned && hazards.length > 0) {
+            const p = predictedHazardCost(hazards, blankRunCosts(f.content));
+            if (p.cost > ZONED_HAZARD_COST_LIMIT) {
+                predicted.push({ path: f.path, ...p });
+                continue;
+            }
+        }
+        const startedAt = Date.now();
+        const fileSites = [];
+        let over = false;
         re.lastIndex = 0;
         let m;
         while ((m = re.exec(f.content)) !== null) {
@@ -82,12 +310,42 @@ function byRegex(source, files) {
             if (m.index === re.lastIndex)
                 re.lastIndex += 1;
             const token = m[1];
-            if (token === undefined || token === '')
-                continue;
-            sites.push({ token, file: f.path, line: lineOf(f.content, m.index) });
+            if (token !== undefined && token !== '') {
+                fileSites.push({ token, file: f.path, line: lineOf(f.content, m.index) });
+            }
+            if (zoned && Date.now() - startedAt > ZONED_REGEX_FILE_BUDGET_MS) {
+                over = true;
+                break;
+            }
+        }
+        if (over) {
+            ran.push(f.path);
+            continue;
         }
+        sites.push(...fileSites);
     }
-    return sites;
+    return { sites, predicted, ran };
+}
+/**
+ * The head regexes the anchor-based extractors run — possibly on a blanked
+ * buffer. One factory, so the linearity lock (`r75-blank-run-linearity`)
+ * times and lints the exact patterns that run, not copies of them.
+ */
+export function extractorHeadPatterns(anchor) {
+    const a = escapeRegex(anchor);
+    const literalHead = (open) => new RegExp(`(?<![\\w$])${a}\\s*(?::[^=\\n]*)?[:=]\\s*(?:[A-Za-z_$][\\w$.]*\\s*\\(\\s*)?\\${open}`, 'g');
+    return {
+        arrayLiteral: literalHead('['),
+        objectLiteral: literalHead('{'),
+        enumBody: new RegExp(`\\benum\\s+${a}\\s*\\{`, 'g'),
+        call: new RegExp(`(?<![\\w$.@])${a}\\s*\\(`, 'g'),
+        decorator: new RegExp(`@${a}\\s*\\(`, 'g'),
+        // Collapsed from `\s*(?:<[^>]*>)?\s*=`: two whitespace quantifiers with
+        // only an optional group between them re-partition a blank run.
+        stringUnion: new RegExp(`\\btype\\s+${a}\\s*(?:<[^>]*>\\s*)?=`, 'g'),
+        exportDecl: EXPORT_DECL,
+        exportClause: EXPORT_CLAUSE,
+    };
 }
 /**
  * Elements of every `<anchor> = <open> … ` / `<anchor>: <open> … ` literal.
@@ -99,7 +357,8 @@ function byRegex(source, files) {
  */
 function byBracketLiteral(anchor, open, files, tokenOf) {
     const sites = [];
-    const head = new RegExp(`(?<![\\w$])${escapeRegex(anchor)}\\s*(?::[^=\\n]*)?[:=]\\s*(?:[A-Za-z_$][\\w$.]*\\s*\\(\\s*)?\\${open}`, 'g');
+    const heads = extractorHeadPatterns(anchor);
+    const head = open === '[' ? heads.arrayLiteral : heads.objectLiteral;
     for (const f of files) {
         head.lastIndex = 0;
         let m;
@@ -122,7 +381,7 @@ function byBracketLiteral(anchor, open, files, tokenOf) {
 /** Members of `enum <anchor> { … }` — the member name, or its assigned value. */
 function byEnumMembers(anchor, wantValue, files) {
     const sites = [];
-    const head = new RegExp(`\\benum\\s+${escapeRegex(anchor)}\\s*\\{`, 'g');
+    const head = extractorHeadPatterns(anchor).enumBody;
     for (const f of files) {
         head.lastIndex = 0;
         let m;
@@ -173,9 +432,8 @@ function byExportNames(files) {
 /** Argument `argIndex` of every `anchor(…)` call — or `@anchor(…)` decorator. */
 function byCallArgs(anchor, argIndex, decorator, files) {
     const sites = [];
-    const head = decorator
-        ? new RegExp(`@${escapeRegex(anchor)}\\s*\\(`, 'g')
-        : new RegExp(`(?<![\\w$.@])${escapeRegex(anchor)}\\s*\\(`, 'g');
+    const heads = extractorHeadPatterns(anchor);
+    const head = decorator ? heads.decorator : heads.call;
     for (const f of files) {
         head.lastIndex = 0;
         let m;
@@ -199,7 +457,7 @@ function byCallArgs(anchor, argIndex, decorator, files) {
 /** The string literals of `type <anchor> = 'a' | 'b' | 'c'`. */
 function byStringUnion(anchor, files) {
     const sites = [];
-    const head = new RegExp(`\\btype\\s+${escapeRegex(anchor)}\\s*(?:<[^>]*>)?\\s*=`, 'g');
+    const head = extractorHeadPatterns(anchor).stringUnion;
     const member = /['"`]([^'"`]+)['"`]/g;
     for (const f of files) {
         head.lastIndex = 0;

package/dist/extract/i-labeled-source.d.ts

@@ -0,0 +1,12 @@
+import type { IWiringSource } from '@shrkcrft/core';
+/**
+ * One extraction source of a gate rule, named by the side it plays —
+ * `declared`, `registered[1]`, `chain[0]`, `source`, `consumer`, a role, or
+ * `compute.source`. The label qualifies the source's marker lists
+ * (`declared.files`) and prefixes its units in a multi-source report.
+ */
+export interface ILabeledSource {
+    readonly label: string;
+    readonly source: IWiringSource;
+}
+//# sourceMappingURL=i-labeled-source.d.ts.map

package/dist/extract/i-labeled-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-labeled-source.d.ts","sourceRoot":"","sources":["../../src/extract/i-labeled-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC"}

package/dist/extract/i-labeled-source.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,50 @@
+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;
+    blankedChars?: number;
+};
+//# 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;AAmFxD,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,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CA4FnF"}