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

package/dist/scan/import-pattern.js

@@ -0,0 +1,191 @@
+import { globToRegex } from "./glob.js";
+import { nodeBuiltinPackageNames } from "./node-builtin-package-names.js";
+/**
+ * How a forbidden-import (or exception-target) pattern matches an import
+ * specifier — the pattern language of the boundary plane (round 11, 1.5).
+ *
+ * The generic glob matcher keeps `*` = "any chars except `/`" (glob.test.ts
+ * pins that), so a bare package pattern like `@scope/package-a` or
+ * `@scope/package-*` used to match ONLY the package entrypoint: every subpath
+ * import of the very same forbidden package (`@scope/package-a/sub`) escaped
+ * the fence, and the gate reported green over it. Package semantics live HERE,
+ * in the boundary evaluator's matcher, not in glob.ts.
+ *
+ * The rule, in one sentence: a pattern with no `**` and no trailing `/` is a
+ * PACKAGE pattern — it matches the specifier itself and everything under it
+ * (`<pattern>/**`), at a segment boundary, so `@scope/pkg` covers
+ * `@scope/pkg/deep` but never `@scope/pkg-legacy`. A pattern containing `**`
+ * already says how deep it reaches and is matched exactly as written. A rule
+ * that means "the entrypoint only" (barrel avoidance: forbid `lodash`, allow
+ * `lodash/get`) opts out with `forbiddenMatch: 'exact'`.
+ */
+/** Does `pattern` take package semantics (entrypoint + every subpath)? */
+export function isPackagePattern(pattern) {
+    return !pattern.includes('**') && !pattern.endsWith('/');
+}
+/**
+ * Match `specifier` against `pattern`.
+ *
+ * Returns `'exact'` when the pattern matches the specifier as written,
+ * `'subpath'` when only the package semantics reached it (a deeper import of a
+ * package the pattern names), and `null` otherwise. `mode: 'exact'` disables
+ * the subpath half. The verdict label travels on the violation (`matchKind`)
+ * so a newly-reported subpath edge explains itself.
+ */
+export function matchImportPattern(specifier, pattern, mode = 'package') {
+    if (globToRegex(pattern).test(specifier))
+        return 'exact';
+    if (mode === 'package' && isPackagePattern(pattern) && globToRegex(`${pattern}/**`).test(specifier)) {
+        return 'subpath';
+    }
+    return null;
+}
+/**
+ * Why `pattern` cannot mean what its author wrote in a SPECIFIER list
+ * (`forbiddenImports`, `allowedImports`, `exceptions[].target`) matched under
+ * `mode` — or `undefined` for a well-formed pattern (round 12, R12-5.2). The
+ * one predicate the rule validator (every local AND pack rule file) and the
+ * evaluator's dead-unit reach both read.
+ *
+ *   - `''` names no import.
+ *   - A leading `!` is the NEGATION syntax of every glob list in this repo, but
+ *     a specifier list takes none: compiled as written it matches only an
+ *     import that itself starts with `!` (a webpack inline loader), so the
+ *     carve-out an author meant silently matched nothing. (A literal
+ *     inline-loader specifier is still reachable: start the pattern with `?`.)
+ *   - Under package semantics a trailing `/` is the one spelling left literal
+ *     ({@link isPackagePattern}): it matches only an import written WITH that
+ *     slash (`'buffer/'`, the userland-polyfill idiom) — never the package, never
+ *     its subpaths — while the gate reported ✓ over both. `mode: 'exact'` (and
+ *     `allowedImports`, always exact) keeps it as the literal it then plainly is.
+ *
+ * Deliberately NOT "can never match": `'buffer/'` is a real import specifier.
+ * The trailing-slash fix it names is lossless — the package spelling covers
+ * the slash spelling too (`matchImportPattern('buffer/', 'buffer')` is
+ * `subpath`), so following the advice never narrows a fence.
+ */
+export function importPatternDefect(pattern, mode = 'package') {
+    if (pattern.length === 0)
+        return 'an empty pattern names no import';
+    if (pattern.startsWith('!')) {
+        return ('negation is only supported in `from` — a specifier list takes no "!" (as written this matches only an import that itself starts with "!"). ' +
+            'forbiddenImports is checked before allowedImports, so allowedImports never re-admits a forbidden import: carve a subpath out with exceptions[{ path, target, reason }], ' +
+            "or set forbiddenMatch: 'exact' and list exactly what you forbid");
+    }
+    if (mode === 'package' && pattern.endsWith('/')) {
+        const bare = pattern.replace(/\/+$/, '');
+        const fix = bare.length === 0
+            ? 'name a package or a path'
+            : isPackagePattern(bare)
+                ? `write '${bare}' (the package and every subpath — '${pattern}' included) or '${bare}/**' (subpaths only)`
+                : `write '${bare}'`;
+        return `a trailing '/' matches only an import written with that slash, never the package or its subpaths — ${fix}; forbiddenMatch: 'exact' keeps '${pattern}' as a literal`;
+    }
+    return undefined;
+}
+/**
+ * Does every specifier `inner` matches also match `outer`? (round 12, R12-5.3 /
+ * R12-5.6). `outerMode` is how `outer` matches (the rule's `forbiddenMatch`);
+ * `innerMode` is how `inner` does — the same mode for a sibling forbidden
+ * pattern, `exact` for an `allowedImports` entry (never widened).
+ *
+ * Deliberately CONSERVATIVE — `true` only when the literal shape proves it,
+ * because a false "covered" would tell an author to delete a live pattern (or
+ * call a working allowance dead). Two proofs:
+ *
+ *   1. `inner` is a literal (no `*` / `?`) that `outer` matches — and, when
+ *      `inner` itself widens to its subpaths (a package pattern under package
+ *      semantics), `outer` widens too.
+ *   2. `outer` is a package pattern under package semantics, and it matches
+ *      `inner`'s literal prefix up to one of its `/`: every specifier `inner`
+ *      can match starts with that prefix plus `/`, a subpath `outer` covers.
+ *
+ * A pattern with an {@link importPatternDefect} proves nothing either way.
+ */
+export function importPatternSubsumes(outer, inner, outerMode = 'package', innerMode = outerMode) {
+    if (importPatternDefect(outer, outerMode) !== undefined)
+        return false;
+    if (importPatternDefect(inner, innerMode) !== undefined)
+        return false;
+    const outerWidens = outerMode === 'package' && isPackagePattern(outer);
+    const wild = inner.search(/[*?]/);
+    if (wild === -1) {
+        if (matchImportPattern(inner, outer, outerMode) === null)
+            return false;
+        const innerWidens = innerMode === 'package' && isPackagePattern(inner);
+        return !innerWidens || outerWidens;
+    }
+    if (!outerWidens)
+        return false;
+    const prefix = inner.slice(0, wild);
+    for (let k = prefix.indexOf('/'); k > 0; k = prefix.indexOf('/', k + 1)) {
+        if (matchImportPattern(prefix.slice(0, k), outer, 'package') !== null)
+            return true;
+    }
+    return false;
+}
+/** Why the dead-unit judge never calls a relative specifier pattern dead — its went-live evidence and the marker refusal both quote it. */
+export const RELATIVE_PATTERN_NEVER_DEAD = 'a relative pattern is never judged dead (it cannot be judged without an importing file)';
+/** Why the dead-unit judge never calls a leading-`*` specifier pattern dead — its went-live evidence and the marker refusal both quote it. */
+export const LEADING_WILDCARD_NEVER_DEAD = 'a leading wildcard could match any known package name, so it is never judged dead';
+/**
+ * Could `pattern` match an import of package `name` (or one of its subpaths)?
+ * Deliberately permissive — a false "resolvable" costs a missed warning, a false
+ * "dead" would cry wolf on a legitimate guard. The evaluator's reach
+ * (`resolvedBy`) and {@link importPatternNeverJudgedDead} both read it.
+ */
+export function couldMatchPackageName(pattern, name, mode) {
+    if (matchImportPattern(name, pattern, mode) !== null)
+        return true;
+    const wild = pattern.search(/[*?]/);
+    if (wild === -1)
+        return pattern.startsWith(`${name}/`);
+    const prefix = pattern.slice(0, wild);
+    if (prefix.length === 0) {
+        // A leading `*` could be anything. A leading `?` is exactly ONE character:
+        // the literal after the `?` run must still fit the name at that offset —
+        // so `?!raw-loader!**` (an inline-loader pattern) can never match a package
+        // name, and one that matches no import is a dead unit, not "resolvable"
+        // through every known package (round 12 review, R12-DOC-1).
+        const lead = pattern.length - pattern.replace(/^\?+/, '').length;
+        if (lead === 0)
+            return true;
+        const literal = pattern.slice(lead).split(/[*?]/)[0] ?? '';
+        const rest = name.slice(lead);
+        return literal.length === 0 || rest.startsWith(literal) || literal.startsWith(`${rest}/`);
+    }
+    return name.startsWith(prefix) || prefix.startsWith(`${name}/`);
+}
+/**
+ * Why the boundary dead-unit judge can NEVER call `pattern` dead, matched
+ * under `mode` — or `undefined` when it can (round 13, K5). Proved from the
+ * pattern alone, through the judge's own reach rules (`resolvedBy` in the
+ * evaluator): the judge calls a specifier pattern dead only when it resolves to
+ * nothing anywhere, and the orchestrator ALWAYS supplies the runtime builtins
+ * as known packages (`nodeBuiltinPackageNames`), so these always resolve:
+ *
+ *   - a relative pattern (`./x`, `../legacy/**`) — never judged without an
+ *     importing file;
+ *   - a leading `*` — it could match any known package name, and a builtin is
+ *     always known;
+ *   - a pattern a runtime builtin module matches (`fs`, `node:*`,
+ *     `fs/promises`) — that package always exists.
+ *
+ * A `{ pattern, expectEmpty: true }` marker on such a pattern could only ever
+ * read went-live, so the rule validator refuses it at load. A pattern with an
+ * {@link importPatternDefect} is answered by the defect instead (`undefined`).
+ */
+export function importPatternNeverJudgedDead(pattern, mode = 'package') {
+    if (importPatternDefect(pattern, mode) !== undefined)
+        return undefined;
+    if (pattern.startsWith('.'))
+        return RELATIVE_PATTERN_NEVER_DEAD;
+    if (pattern.startsWith('*'))
+        return LEADING_WILDCARD_NEVER_DEAD;
+    const builtins = nodeBuiltinPackageNames();
+    const builtin = builtins.find((b) => matchImportPattern(b, pattern, mode) !== null) ??
+        builtins.find((b) => couldMatchPackageName(pattern, b, mode));
+    return builtin !== undefined
+        ? `'${builtin}' is a runtime builtin module — always a known package — so it always resolves and is never judged dead`
+        : undefined;
+}

package/dist/scan/node-builtin-package-names.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Every module the running runtime ships built in, as an import specifier:
+ * each bare name and its `node:` spelling (a name that already carries a
+ * scheme — `node:test`, `bun:ffi` — as listed).
+ *
+ * THE list the boundary plane treats as always-known packages (round 13): the
+ * orchestrator's known-package set (`collectKnownPackages`, which the dead-unit
+ * judge reads) and the load-time marker refusal (`importPatternNeverJudgedDead`)
+ * both read it, so the judge and the refusal can never disagree about whether a
+ * builtin-named pattern could ever be judged dead.
+ */
+export declare function nodeBuiltinPackageNames(): readonly string[];
+//# sourceMappingURL=node-builtin-package-names.d.ts.map

package/dist/scan/node-builtin-package-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-builtin-package-names.d.ts","sourceRoot":"","sources":["../../src/scan/node-builtin-package-names.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,MAAM,EAAE,CAU3D"}

package/dist/scan/node-builtin-package-names.js

@@ -0,0 +1,25 @@
+import { builtinModules } from 'node:module';
+let cached;
+/**
+ * Every module the running runtime ships built in, as an import specifier:
+ * each bare name and its `node:` spelling (a name that already carries a
+ * scheme — `node:test`, `bun:ffi` — as listed).
+ *
+ * THE list the boundary plane treats as always-known packages (round 13): the
+ * orchestrator's known-package set (`collectKnownPackages`, which the dead-unit
+ * judge reads) and the load-time marker refusal (`importPatternNeverJudgedDead`)
+ * both read it, so the judge and the refusal can never disagree about whether a
+ * builtin-named pattern could ever be judged dead.
+ */
+export function nodeBuiltinPackageNames() {
+    if (cached === undefined) {
+        const out = new Set();
+        for (const m of builtinModules) {
+            out.add(m);
+            if (!m.includes(':'))
+                out.add(`node:${m}`);
+        }
+        cached = [...out];
+    }
+    return cached;
+}

package/dist/scan/scan-imports.d.ts

@@ -1,15 +1,22 @@
+import type { IUnreadFile } from '../util/unread-file.js';
 export interface IScanImportsOptions {
     projectRoot: string;
     extraIgnore?: readonly string[];
-    /** When set, only files under one of these globs are scanned. */
+    /** When set, only files matching one of these globs (project-relative) are scanned. */
     include?: readonly string[];
+    /**
+     * Read imports from the RAW text, comments included (`check boundaries
+     * --include-comments`). Default `false`: a commented-out import, an import in
+     * a doc-comment code fence, or one inside a string literal is not an edge.
+     */
+    includeComments?: boolean;
 }
 export interface IImportEdge {
-    /** Source file (relative to projectRoot). */
+    /** Source file (relative to projectRoot, `/`-separated). */
     from: string;
     /** Literal import specifier. */
     importSpecifier: string;
-    /** Approximate 1-based line number in the source file. */
+    /** 1-based line of the statement's `import` / `export` / `require` keyword. */
     line: number;
     /**
      * Heuristic resolution. v1 sets:
@@ -18,12 +25,38 @@ export interface IImportEdge {
      * (We do not attempt tsconfig path-mapping resolution here.)
      */
     kind: 'internal' | 'external';
+    /** True for `import type` / `export type … from` — still a real dependency edge. */
+    typeOnly?: boolean;
 }
 export interface IImportScanResult {
     filesScanned: number;
     edges: IImportEdge[];
     warnings: string[];
+    /**
+     * Every scanned source file (project-relative, `/`-separated), INCLUDING files
+     * with zero imports. A rule's scope is counted against this list, so a glob
+     * that matches only import-free files is still live. Optional for callers
+     * that hand-build a scan; the evaluator then falls back to the files that
+     * appear in `edges` (and says so in its coverage).
+     */
+    files?: string[];
+    /**
+     * Source files the walk matched but could NOT read (a stat or read failure —
+     * permissions, or a file vanishing mid-scan), with the reason. They are NOT
+     * in `files` and NOT counted in `filesScanned`: a file whose imports were
+     * never read was not scanned. `runBoundaryCheck` folds each one into the
+     * coverage of every rule whose scope it is in (`readScopeCoverage`), so a
+     * rule over an unreadable file settles PARTIAL (2) — never "examined 1 of 1"
+     * over the file that held the violation.
+     */
+    unread?: IUnreadFile[];
+    /** Every `package.json` the walk passed (project-relative) — workspace package names. */
+    manifestFiles?: string[];
+    /** Which text the edges were read from. */
+    zone?: 'code' | 'all';
 }
+/** Drop every memoised file (tests, or a caller that rewrote files in place within one tick). */
+export declare function clearImportScanMemo(): void;
 /**
  * Walk the project root and return every detected import edge.
  */

package/dist/scan/scan-imports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-imports.d.ts","sourceRoot":"","sources":["../../src/scan/scan-imports.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAyB3E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB7E"}
+{"version":3,"file":"scan-imports.d.ts","sourceRoot":"","sources":["../../src/scan/scan-imports.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAmB1D,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,uFAAuF;IACvF,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB;AA8ED,iGAAiG;AACjG,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAyBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAyE3E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB7E"}

package/dist/scan/scan-imports.js

@@ -1,5 +1,8 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { parseImportStatements } from "../extract/parse-imports.js";
+import { UnreadFileReason } from "../util/unread-file-reason.js";
+import { globMayMatchUnder, matchesAny } from "./glob.js";
 const SUPPORTED_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
 const DEFAULT_IGNORE = new Set([
     'node_modules',
@@ -13,18 +16,6 @@ const DEFAULT_IGNORE = new Set([
     '.tmp-pack',
     '.tmp-smoke-consumer.txt',
 ]);
-// Match `import ... from 'x'`, `export ... from 'x'`, `require('x')`,
-// `import('x')` (static and dynamic). Captures the specifier as group 1.
-//
-// We DELIBERATELY use a single regex per kind rather than a real parser —
-// boundary rules need stable behavior across syntaxes and a regex scanner is
-// the simplest thing that works for v1. Comments and string escapes can fool
-// it; we filter the lowest-hanging fruit (single-line // and /* */ stripped
-// per line, but a `// import "x"` line is still ignored).
-const IMPORT_RE = /(?:^|\s)(?:import|export)\s+[^'"`]*?from\s+['"]([^'"`]+)['"]/g;
-const SIDE_EFFECT_IMPORT_RE = /(?:^|\s)import\s+['"]([^'"`]+)['"]/g;
-const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
-const REQUIRE_RE = /\brequire\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
 function isIgnored(name, extraIgnore) {
     if (DEFAULT_IGNORE.has(name))
         return true;
@@ -39,7 +30,13 @@ function* walk(root, current, extraIgnore) {
     try {
         entries = readdirSync(current, { withFileTypes: true });
     }
-    catch {
+    catch (e) {
+        // A directory that vanished mid-walk is out of scope; one that could not
+        // be listed (permissions) is in front of every rule that reaches under it.
+        const code = e.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            yield { full: current, manifest: false, unlistable: e.message };
+        }
         return;
     }
     for (const entry of entries) {
@@ -59,38 +56,55 @@ function* walk(root, current, extraIgnore) {
             continue;
         }
         if (entry.isFile()) {
+            if (name === 'package.json') {
+                yield { full, manifest: true };
+                continue;
+            }
             const ext = nodePath.extname(name);
             if (!SUPPORTED_EXTS.has(ext))
                 continue;
-            yield full;
+            yield { full, manifest: false };
         }
     }
 }
-function lineFor(source, offset) {
-    let line = 1;
-    for (let i = 0; i < offset && i < source.length; i += 1) {
-        if (source[i] === '\n')
-            line += 1;
-    }
-    return line;
+/**
+ * Per-process memo of the edges ONE file contributes, keyed on scan root + file
+ * + zone and validated by a stat fingerprint (size, mtime, ctime).
+ *
+ * `scanImports` runs several times per command — the architecture map calls it
+ * twice and impact analysis once for a single task-risk report — and for the
+ * whole life of the MCP server. Round 11's comment-aware parse (lex → blank
+ * comments → match) made re-reading and re-lexing every unchanged file on every
+ * call the dominant cost of those reports (~3x). An edited file changes its
+ * fingerprint and is re-parsed; an unchanged one is not. Edges are handed out
+ * as COPIES so a caller that decorates an edge can never corrupt the memo.
+ */
+const EDGE_MEMO = new Map();
+const EDGE_MEMO_LIMIT = 50_000;
+/** Drop every memoised file (tests, or a caller that rewrote files in place within one tick). */
+export function clearImportScanMemo() {
+    EDGE_MEMO.clear();
 }
-function extractImports(source, relPath) {
-    const edges = [];
-    for (const re of [IMPORT_RE, SIDE_EFFECT_IMPORT_RE, DYNAMIC_IMPORT_RE, REQUIRE_RE]) {
-        re.lastIndex = 0;
-        let m;
-        while ((m = re.exec(source)) !== null) {
-            const spec = m[1];
-            const line = lineFor(source, m.index);
-            edges.push({
-                from: relPath,
-                importSpecifier: spec,
-                line,
-                kind: spec.startsWith('.') ? 'internal' : 'external',
-            });
-        }
-    }
-    return edges;
+function toPosix(rel) {
+    return nodePath.sep === '/' ? rel : rel.split(nodePath.sep).join('/');
+}
+/**
+ * The edges one file contributes — read through THE import parser
+ * (`parseImportStatements`), so `check boundaries` and the `import-edges` DSL
+ * extractor can never disagree about what a file imports. (Round 11 deleted the
+ * four private regexes that used to live here, together with a comment that
+ * claimed they stripped comments: no stripping code existed, a commented-out
+ * import was a violation, and every import after line 1 was reported one line
+ * early.)
+ */
+function extractImports(source, relPath, zone) {
+    return parseImportStatements(source, { zone }).map((p) => ({
+        from: relPath,
+        importSpecifier: p.specifier,
+        line: p.line,
+        kind: p.specifier.startsWith('.') ? 'internal' : 'external',
+        ...(p.typeOnly ? { typeOnly: true } : {}),
+    }));
 }
 /**
  * Walk the project root and return every detected import edge.
@@ -98,27 +112,82 @@ function extractImports(source, relPath) {
 export function scanImports(options) {
     const root = nodePath.resolve(options.projectRoot);
     const extraIgnore = new Set(options.extraIgnore ?? []);
+    const zone = options.includeComments === true ? 'all' : 'code';
+    const include = options.include && options.include.length > 0 ? options.include : undefined;
     const result = {
         filesScanned: 0,
         edges: [],
         warnings: [],
+        files: [],
+        unread: [],
+        manifestFiles: [],
+        zone,
     };
     if (!existsSync(root)) {
         result.warnings.push(`scan root does not exist: ${root}`);
         return result;
     }
-    for (const file of walk(root, root, extraIgnore)) {
-        result.filesScanned += 1;
-        const rel = nodePath.relative(root, file);
+    // A file counts as SCANNED only once its imports were actually read (or
+    // served from the memo). It used to be counted — and listed in `files`, the
+    // universe every rule's scope is measured against — before the read, so an
+    // unreadable file read as "examined 1 of 1" while its imports were never seen.
+    const unreadable = (rel, e) => {
+        result.warnings.push(`unreadable: ${rel} (${e.message})`);
+        result.unread.push({ path: rel, reason: UnreadFileReason.Unreadable });
+    };
+    for (const hit of walk(root, root, extraIgnore)) {
+        const rel = toPosix(nodePath.relative(root, hit.full));
+        if (hit.unlistable !== undefined) {
+            const dir = rel === '' ? './' : `${rel}/`;
+            if (include && !include.some((g) => globMayMatchUnder(g, dir)))
+                continue;
+            result.warnings.push(`unlistable directory: ${dir} (${hit.unlistable})`);
+            result.unread.push({ path: dir, reason: UnreadFileReason.UnreadableDirectory });
+            continue;
+        }
+        if (hit.manifest) {
+            result.manifestFiles.push(rel);
+            continue;
+        }
+        if (include && !matchesAny(rel, include))
+            continue;
+        let fingerprint;
+        try {
+            const st = statSync(hit.full);
+            fingerprint = `${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+        }
+        catch (e) {
+            // Deleted since the walk saw it: gone, so out of scope (the one reader's
+            // rule, `readMatchingFiles`). Anything else leaves it unexamined.
+            if (e.code !== 'ENOENT')
+                unreadable(rel, e);
+            continue;
+        }
+        const key = `${root}\0${hit.full}\0${zone}`;
+        const memo = EDGE_MEMO.get(key);
+        if (memo && memo.fingerprint === fingerprint) {
+            result.filesScanned += 1;
+            result.files.push(rel);
+            for (const e of memo.edges)
+                result.edges.push({ ...e });
+            continue;
+        }
         let source;
         try {
-            source = readFileSync(file, 'utf8');
+            source = readFileSync(hit.full, 'utf8');
         }
         catch (e) {
-            result.warnings.push(`unreadable: ${rel} (${e.message})`);
+            unreadable(rel, e);
             continue;
         }
-        result.edges.push(...extractImports(source, rel));
+        result.filesScanned += 1;
+        result.files.push(rel);
+        const edges = extractImports(source, rel, zone);
+        if (EDGE_MEMO.size >= EDGE_MEMO_LIMIT)
+            EDGE_MEMO.clear();
+        EDGE_MEMO.set(key, { fingerprint, edges });
+        for (const e of edges)
+            result.edges.push({ ...e });
     }
     return result;
 }

package/dist/util/blank-run-hazard-finding.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One blank-run backtracking hazard found in a regex source by
+ * `findBlankRunHazards`.
+ *
+ * `leading`: an alternative can START a match at every offset of a blank run
+ * and then consume the rest of the run — O(run²) per blanked comment/string.
+ * `adjacent`: two whitespace-consuming quantifiers touch (only optional items
+ * between them), so the engine re-partitions every run between them.
+ */
+export interface IBlankRunHazard {
+    readonly shape: 'leading' | 'adjacent';
+    /** Offset of the offending construct in the regex source. */
+    readonly index: number;
+    /** The offending slice of the source. */
+    readonly fragment: string;
+    /** One sentence: what backtracks, and why a blanked buffer makes it expensive. */
+    readonly message: string;
+    /**
+     * The hazard's REACH: whether the flagged quantifier(s) consume newlines.
+     *
+     * A line-bounded hazard (`[ \t]*`, `.*?`, `[ ]*` — or an `adjacent` pair
+     * overlapping only on spaces) re-scans at most to the end of its line, so
+     * on a blanked buffer it costs Σ line-run², not Σ (multi-line run)². A
+     * cost prediction that ignores this skips files the pattern would scan in
+     * milliseconds.
+     */
+    readonly crossesNewline: boolean;
+    /**
+     * `leading` only: a match can start only at a LINE start (`(?:^|\n)\s*`),
+     * so the cost is (lines × run), not run².
+     */
+    readonly fromLineStart?: boolean;
+}
+//# sourceMappingURL=blank-run-hazard-finding.d.ts.map

package/dist/util/blank-run-hazard-finding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blank-run-hazard-finding.d.ts","sourceRoot":"","sources":["../../src/util/blank-run-hazard-finding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC"}

package/dist/util/blank-run-hazard-finding.js

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

package/dist/util/blank-run-hazard.d.ts

@@ -0,0 +1,29 @@
+import type { IBlankRunHazard } from './blank-run-hazard-finding.js';
+/**
+ * Static lint: does this regex backtrack quadratically on a BLANKED buffer?
+ *
+ * A non-`all` `scan` zone blanks comments and strings into runs of spaces
+ * (newlines kept, so line numbers stay true). A pattern that is fast on real
+ * source becomes O(run²) on such a buffer when:
+ *
+ *   - (leading) an alternative's first mandatory construct — after only
+ *     optional groups or non-restricting zero-width atoms — is a
+ *     whitespace-consuming quantifier. Every offset of a run is a start, and
+ *     each start re-scans the rest of the run. A start restricted to newlines
+ *     (`(?:^|\n)`) is only a hazard when the quantifier also crosses newlines
+ *     (`\s*`); `[ \t]*` then stops at the end of its line.
+ *   - (adjacent) two whitespace-consuming quantifiers touch, separated only by
+ *     optional items or whitespace-capable atoms — `\s*(?:<x>)?\s*=`, a lazy
+ *     `[^;'"]*?` next to `\s*` — so the engine re-partitions each run between
+ *     them.
+ *
+ * Measured: one such pattern took 3 ms on raw text and 5,402 ms on the
+ * blanked buffer of the same file. This cannot be caught by tests over
+ * ordinary source; it is caught here, from the pattern text, before it runs.
+ *
+ * Deterministic and advisory: a small tokenizer over the regex source, no
+ * regex engine involved. It over-approximates (lookarounds are treated as
+ * transparent; flags are ignored), which is the right direction for a hint.
+ */
+export declare function findBlankRunHazards(source: string): readonly IBlankRunHazard[];
+//# sourceMappingURL=blank-run-hazard.d.ts.map

package/dist/util/blank-run-hazard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blank-run-hazard.d.ts","sourceRoot":"","sources":["../../src/util/blank-run-hazard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAY9E"}