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

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

@@ -26,6 +26,15 @@ export interface IExtractContext {
 /** 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;
     /**
@@ -45,4 +54,25 @@ export interface IExtractResult {
  * an `error` and no sites.
  */
 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;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"}
+{"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,7 @@
 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";
 /**
@@ -17,46 +19,85 @@ export function extractTokens(source, files, context = {}) {
         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, files);
+            sites = byFilenames(source, scanned);
             break;
         case 'import-edges': {
-            const edges = extractImportEdges(source, files, {
+            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 };
+                return { sites: edges.sites, hint: edges.hint, ...zoneMeta(zone, blankedChars) };
             sites = edges.sites;
             break;
         }
@@ -81,7 +122,11 @@ export function extractTokens(source, files, context = {}) {
             });
         }
     }
-    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.
@@ -120,13 +165,144 @@ function byFilenames(source, files) {
     }
     return sites;
 }
-/** Capture-group-1 of a pattern, per file. */
-function byRegex(source, files) {
+/**
+ * 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 };
+}
+/** 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) {
@@ -134,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.
@@ -151,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;
@@ -174,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;
@@ -225,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;
@@ -251,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

@@ -45,5 +45,6 @@ export declare function extractImportEdges(source: IWiringSource, files: readonl
     sites: IExtractedSite[];
     error?: string;
     hint?: string;
+    blankedChars?: number;
 };
 //# sourceMappingURL=import-edges.d.ts.map

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

@@ -1 +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"}
+{"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"}

package/dist/extract/import-edges.js

@@ -1,7 +1,7 @@
-import { matchesAny } from "../scan/glob.js";
+import { globListSelects } from "../scan/glob.js";
 import { resolveAliasCandidates } from "../scan/tsconfig-aliases.js";
 import { safeCompile } from "../util/safe-regex.js";
-import { parseImportStatements } from "./parse-imports.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('/')) : '';
@@ -55,14 +55,15 @@ function matchesTarget(resolved, to, modulePattern) {
             return true;
     }
     if (to.files && to.files.length > 0 && resolved.path !== undefined) {
-        if (matchesAny(resolved.path, to.files))
+        // `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 (matchesAny(resolved.path + ext, to.files))
+            if (globListSelects(resolved.path + ext, to.files))
                 return true;
-            if (matchesAny(`${resolved.path}/index${ext}`, to.files))
+            if (globListSelects(`${resolved.path}/index${ext}`, to.files))
                 return true;
         }
     }
@@ -92,9 +93,20 @@ export function extractImportEdges(source, files, context = {}) {
             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) {
-        for (const statement of parseImportStatements(file.content)) {
+        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;
@@ -151,7 +163,8 @@ export function extractImportEdges(source, files, context = {}) {
             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 };
+    return { sites, blankedChars };
 }

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

@@ -1,9 +1,17 @@
-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. */
@@ -26,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;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"}
+{"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,5 +1,6 @@
-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";
 /**
@@ -11,12 +12,17 @@ import { loadTsconfigPaths } from "../scan/tsconfig-aliases.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 { 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.
@@ -24,9 +30,46 @@ export function inspectSource(projectRoot, source, excludeDirs = []) {
     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],
+    };
+}