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

package/dist/registry/load-boundary-rules.d.ts

@@ -1,12 +1,40 @@
 import { type IImportContext } from '@shrkcrft/core';
-import { type IBoundaryRule } from '../model/boundary-rule.js';
+import { type IBoundaryRule, type IBoundaryRuleValidationIssue } from '../model/boundary-rule.js';
+/** One rule a file declared that failed validation — dropped from the registry, never silently. */
+export interface IBoundaryRuleInvalid {
+    /** Position in the file's rule array. */
+    readonly index: number;
+    /** The rule's id, when it had a string one. */
+    readonly ruleId?: string;
+    /** The export the rule array came from (`default`, `rules` or `boundaries`). */
+    readonly exportName?: string;
+    readonly issues: readonly IBoundaryRuleValidationIssue[];
+}
 export interface ILoadedBoundaryRulesFile {
     source: string;
     rules: IBoundaryRule[];
     warnings: string[];
+    /**
+     * Rules that failed validation (round 11, 1.3#boundary-invalid-rule). They
+     * used to be a warning string nobody rendered, and `check boundaries`
+     * reported green over the fence that had just vanished. The structured list
+     * lets every surface report them as ERRORED rules — never evaluated.
+     */
+    invalid: IBoundaryRuleInvalid[];
+    /** The file could not be imported, or exported no rule array. Nothing in it was evaluated. */
+    loadError?: string;
+    /** The file does not exist. */
+    missing?: boolean;
 }
 export interface ILoadBoundaryRulesOptions {
     importContext?: IImportContext;
+    /**
+     * The pack that contributed the file (round 13): stamped onto every
+     * `expectEmpty` marker of its rules (`stampUnitMarks`), so a pack marker that
+     * went live is reported as INFO and never fails the consumer, who cannot edit
+     * it. Unset for local rules and `--rule-file` / `--diff-against` candidates.
+     */
+    packageName?: string;
 }
 export declare function loadBoundaryRulesFromFile(absPath: string, options?: ILoadBoundaryRulesOptions): Promise<ILoadedBoundaryRulesFile>;
 //# sourceMappingURL=load-boundary-rules.d.ts.map

package/dist/registry/load-boundary-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-boundary-rules.d.ts","sourceRoot":"","sources":["../../src/registry/load-boundary-rules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAErF,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC"}
+{"version":3,"file":"load-boundary-rules.d.ts","sourceRoot":"","sources":["../../src/registry/load-boundary-rules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAA8B,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,4BAA4B,EAClC,MAAM,2BAA2B,CAAC;AAInC,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAwEnC"}

package/dist/registry/load-boundary-rules.js

@@ -1,14 +1,17 @@
 import { existsSync } from 'node:fs';
-import { safeImport } from '@shrkcrft/core';
-import { validateBoundaryRule } from "../model/boundary-rule.js";
+import { safeImport, unitProblemsOf } from '@shrkcrft/core';
+import { validateBoundaryRule, } from "../model/boundary-rule.js";
+import { normalizeBoundaryRule } from "../model/normalize-boundary-rule.js";
 export async function loadBoundaryRulesFromFile(absPath, options = {}) {
     const out = {
         source: absPath,
         rules: [],
         warnings: [],
+        invalid: [],
     };
     if (!existsSync(absPath)) {
         out.warnings.push(`boundary rules file not found: ${absPath}`);
+        out.missing = true;
         return out;
     }
     const result = options.importContext
@@ -21,20 +24,47 @@ export async function loadBoundaryRulesFromFile(absPath, options = {}) {
             ? 'timed out loading boundary rules from'
             : 'failed to load boundary rules from';
         out.warnings.push(`${label} ${absPath}: ${result.error.message}`);
+        out.loadError = result.error.message;
         return out;
     }
     const candidates = pickArray(result.module.default) ??
         pickArray(result.module.rules) ??
-        pickArray(result.module.boundaries) ??
-        [];
-    for (const c of candidates) {
+        pickArray(result.module.boundaries);
+    if (candidates === null) {
+        // A listed rule file that exports no array loads NOTHING — the same silent
+        // vanishing act as an invalid rule, one level up.
+        const message = 'exports no rule array (expected a default export, `rules` or `boundaries` array)';
+        out.warnings.push(`${absPath}: ${message}`);
+        out.loadError = message;
+        return out;
+    }
+    // The export the rule array came from, so every rejection surface prints
+    // `(default[1])` — one wording with every other contribution kind.
+    const exportName = pickArray(result.module.default) !== null
+        ? 'default'
+        : pickArray(result.module.rules) !== null
+            ? 'rules'
+            : 'boundaries';
+    candidates.forEach((c, index) => {
         const v = validateBoundaryRule(c);
+        const id = c?.id;
         if (!v.valid) {
             out.warnings.push(`${absPath}: skipping invalid boundary rule (${v.issues.map((i) => i.field).join(', ')})`);
-            continue;
+            out.invalid.push({ index, exportName, ...(typeof id === 'string' ? { ruleId: id } : {}), issues: v.issues });
+            return;
         }
-        out.rules.push(c);
-    }
+        // Round 13: the LOADED rule — plain string lists plus the expectEmptyUnits
+        // ledger, each marker stamped with the contributing pack. Validation above
+        // ran the same parser, so this cannot fail for a valid rule; if it ever
+        // did, the rule is an errored rule, never a crash.
+        const n = normalizeBoundaryRule(c, options.packageName);
+        if (!n.ok) {
+            const issues = unitProblemsOf(n.error).map((message) => ({ field: '<markers>', message }));
+            out.invalid.push({ index, exportName, ...(typeof id === 'string' ? { ruleId: id } : {}), issues });
+            return;
+        }
+        out.rules.push(n.value);
+    });
     return out;
 }
 function pickArray(v) {

package/dist/scan/glob.d.ts

@@ -1,3 +1,5 @@
+import { type IGlobList } from '@shrkcrft/core';
+import type { IGlobUnitMeasure } from './i-glob-unit-measure.js';
 /**
  * Minimal glob matcher tuned for the patterns boundary rules use:
  *   - `**` matches any number of path segments (including zero)
@@ -7,7 +9,95 @@
  *
  * Patterns are matched against the literal string (file path or import
  * specifier) — no I/O, no resolution. The function is pure and deterministic.
+ *
+ * Compiled patterns are MEMOISED (round 11, 6.3): `matchesAny` used to
+ * recompile a pattern on every test, once per edge × pattern, and that was the
+ * dominant cost of a boundary run at scale (1.5 s → 0.09 s at 300 rules). The
+ * returned RegExp has no `g`/`y` flag, so sharing one instance is stateless.
+ * The cache is bounded ({@link GLOB_REGEX_CACHE_LIMIT}) and simply cleared when
+ * full — a pattern set larger than that is recompiled, never wrong.
  */
 export declare function globToRegex(pattern: string): RegExp;
+/** The most compiled globs {@link globToRegex} keeps before it starts over. */
+export declare const GLOB_REGEX_CACHE_LIMIT = 10000;
+/** How many compiled globs are memoised right now (bounded by {@link GLOB_REGEX_CACHE_LIMIT}). */
+export declare function globRegexCacheSize(): number;
+/**
+ * The raw OR primitive: does ANY pattern match `value`? A `!` is a literal
+ * character here, so it is right for import specifiers and plain pattern sets,
+ * and WRONG for a user-written glob list — use {@link globListSelects} there.
+ */
 export declare function matchesAny(value: string, patterns: readonly string[]): boolean;
+/**
+ * A list's inclusion globs and negations (`!` stripped), through core's one
+ * parser. Memoised by the list's TEXT (its JSON, so no two lists share a key),
+ * never by array identity — a caller that builds a list and then pushes to it
+ * must not read a stale parse.
+ */
+export declare function globListParts(globs: readonly string[]): IGlobList;
+/**
+ * THE scope test for a user-written glob list, on every gate plane: `path` is
+ * selected iff one of the list's inclusion globs matches it and none of its
+ * negations does.
+ *
+ * Order-independent (a later glob never re-includes) and LIST-LOCAL: a
+ * negation subtracts from its own list's positive set only. That is why a walk
+ * is never negation-aware ({@link globListWalkGlobs}): planes walk the UNION of
+ * many lists once, and a negation applied there would delete rule A's `!x`
+ * from rule B's scope. Selection happens per list, after the walk.
+ */
+export declare function globListSelects(path: string, globs: readonly string[]): boolean;
+/**
+ * The globs a WALK over `globs` must match: the inclusion globs only. A walk
+ * is a positive union primitive (see {@link globListSelects}); what a list's
+ * negations remove is decided per list, over what the walk returned.
+ */
+export declare function globListWalkGlobs(globs: readonly string[]): readonly string[];
+/**
+ * What each glob of ONE list did to `paths`, in first-seen order (a glob listed
+ * twice is measured once). See {@link IGlobUnitMeasure}: an inclusion glob's
+ * `effective` count is what it selected that survives the list's negations; a
+ * negation's is what it removed from the list's positive set.
+ *
+ * `paths` may be a wider walk than this list's own (a union over many rules):
+ * only the paths one of THIS list's inclusion globs matches are its positive
+ * set, so another list's files never count as excluded here.
+ */
+export declare function measureGlobList(paths: readonly string[], globs: readonly string[]): readonly IGlobUnitMeasure[];
+/**
+ * Could `glob` match some path strictly BENEATH directory `dir` (project-
+ * relative, `/`-separated; a trailing `/` is optional and `./` is the root)?
+ *
+ * The question an unlistable directory asks: its files were never enumerated,
+ * so a rule is in front of it whenever a path under it COULD be in the rule's
+ * scope. Segment-wise and deliberately one-directional: a `**` absorbs the
+ * rest, so a false "yes" is possible (a gap reported that a full listing might
+ * have ruled out) and a false "no" is not — `src/app/*.ts` cannot reach
+ * `src/app/sub/`, `src/app/**` and `**\/*.ts` can.
+ */
+export declare function globMayMatchUnder(glob: string, dir: string): boolean;
+/**
+ * Does `glob` match EVERY path beneath directory `dir`? True for `**`, and for
+ * a glob ending in `/**` whose base matches the directory or one of its
+ * ancestors (`src/generated/**` covers `src/generated/` and
+ * `src/generated/deep/`). The test an exemption must pass to take an
+ * unlistable directory out of a rule's scope: exempting PART of it leaves the
+ * rest a gap. Conservative — any other shape answers `false`.
+ */
+export declare function globCoversAllUnder(glob: string, dir: string): boolean;
+/**
+ * How many of `paths` each glob of ONE list effectively counts for, keyed by
+ * glob in first-seen order (a glob listed twice is counted once): an inclusion
+ * glob's selected files (those surviving the list's negations), a negation's
+ * EXCLUDED files. The `glob → effective` projection of {@link measureGlobList}.
+ *
+ * `globListSelects` collapses a glob LIST into one yes/no, which is right for
+ * "is this file in scope" and exactly wrong for "is every glob still live": one
+ * glob of a rule's `files[]` can match nothing after a directory rename while
+ * its siblings keep the rule connected, and the rule reads green forever. A
+ * zero here is that dead unit — and, since round 12, a negation is judged by
+ * what it EXCLUDES, so a load-bearing `!**\/*.spec.ts` is never a zero. Pure —
+ * callers pass the file list their own walk produced.
+ */
+export declare function countMatchesPerGlob(paths: readonly string[], globs: readonly string[]): ReadonlyMap<string, number>;
 //# sourceMappingURL=glob.d.ts.map

package/dist/scan/glob.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/scan/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmCnD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK9E"}
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/scan/glob.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAI7C,kGAAkG;AAClG,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAuCD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK9E;AAUD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CASjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAE7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,gBAAgB,EAAE,CA2B/G;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAapE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAWrE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7B"}

package/dist/scan/glob.js

@@ -1,3 +1,4 @@
+import { isNegatedGlob, parseGlobList } from '@shrkcrft/core';
 /**
  * Minimal glob matcher tuned for the patterns boundary rules use:
  *   - `**` matches any number of path segments (including zero)
@@ -7,8 +8,32 @@
  *
  * Patterns are matched against the literal string (file path or import
  * specifier) — no I/O, no resolution. The function is pure and deterministic.
+ *
+ * Compiled patterns are MEMOISED (round 11, 6.3): `matchesAny` used to
+ * recompile a pattern on every test, once per edge × pattern, and that was the
+ * dominant cost of a boundary run at scale (1.5 s → 0.09 s at 300 rules). The
+ * returned RegExp has no `g`/`y` flag, so sharing one instance is stateless.
+ * The cache is bounded ({@link GLOB_REGEX_CACHE_LIMIT}) and simply cleared when
+ * full — a pattern set larger than that is recompiled, never wrong.
  */
 export function globToRegex(pattern) {
+    const cached = GLOB_REGEX_CACHE.get(pattern);
+    if (cached)
+        return cached;
+    if (GLOB_REGEX_CACHE.size >= GLOB_REGEX_CACHE_LIMIT)
+        GLOB_REGEX_CACHE.clear();
+    const compiled = compileGlob(pattern);
+    GLOB_REGEX_CACHE.set(pattern, compiled);
+    return compiled;
+}
+/** The most compiled globs {@link globToRegex} keeps before it starts over. */
+export const GLOB_REGEX_CACHE_LIMIT = 10_000;
+const GLOB_REGEX_CACHE = new Map();
+/** How many compiled globs are memoised right now (bounded by {@link GLOB_REGEX_CACHE_LIMIT}). */
+export function globRegexCacheSize() {
+    return GLOB_REGEX_CACHE.size;
+}
+function compileGlob(pattern) {
     let r = '';
     for (let i = 0; i < pattern.length; i += 1) {
         const ch = pattern[i];
@@ -46,6 +71,11 @@ export function globToRegex(pattern) {
     }
     return new RegExp('^' + r + '$');
 }
+/**
+ * The raw OR primitive: does ANY pattern match `value`? A `!` is a literal
+ * character here, so it is right for import specifiers and plain pattern sets,
+ * and WRONG for a user-written glob list — use {@link globListSelects} there.
+ */
 export function matchesAny(value, patterns) {
     for (const p of patterns) {
         if (globToRegex(p).test(value))
@@ -53,3 +83,178 @@ export function matchesAny(value, patterns) {
     }
     return false;
 }
+/** Parsed lists that carry a negation, keyed by the list's text (bounded like the regex cache). */
+const GLOB_LIST_CACHE = new Map();
+function hasNegation(globs) {
+    for (const g of globs)
+        if (isNegatedGlob(g))
+            return true;
+    return false;
+}
+/**
+ * A list's inclusion globs and negations (`!` stripped), through core's one
+ * parser. Memoised by the list's TEXT (its JSON, so no two lists share a key),
+ * never by array identity — a caller that builds a list and then pushes to it
+ * must not read a stale parse.
+ */
+export function globListParts(globs) {
+    if (!hasNegation(globs))
+        return { include: globs, exclude: [] };
+    const key = JSON.stringify(globs);
+    const cached = GLOB_LIST_CACHE.get(key);
+    if (cached)
+        return cached;
+    if (GLOB_LIST_CACHE.size >= GLOB_REGEX_CACHE_LIMIT)
+        GLOB_LIST_CACHE.clear();
+    const parsed = parseGlobList(globs);
+    GLOB_LIST_CACHE.set(key, parsed);
+    return parsed;
+}
+/**
+ * THE scope test for a user-written glob list, on every gate plane: `path` is
+ * selected iff one of the list's inclusion globs matches it and none of its
+ * negations does.
+ *
+ * Order-independent (a later glob never re-includes) and LIST-LOCAL: a
+ * negation subtracts from its own list's positive set only. That is why a walk
+ * is never negation-aware ({@link globListWalkGlobs}): planes walk the UNION of
+ * many lists once, and a negation applied there would delete rule A's `!x`
+ * from rule B's scope. Selection happens per list, after the walk.
+ */
+export function globListSelects(path, globs) {
+    if (!hasNegation(globs))
+        return matchesAny(path, globs);
+    const list = globListParts(globs);
+    return matchesAny(path, list.include) && !matchesAny(path, list.exclude);
+}
+/**
+ * The globs a WALK over `globs` must match: the inclusion globs only. A walk
+ * is a positive union primitive (see {@link globListSelects}); what a list's
+ * negations remove is decided per list, over what the walk returned.
+ */
+export function globListWalkGlobs(globs) {
+    return globListParts(globs).include;
+}
+/**
+ * What each glob of ONE list did to `paths`, in first-seen order (a glob listed
+ * twice is measured once). See {@link IGlobUnitMeasure}: an inclusion glob's
+ * `effective` count is what it selected that survives the list's negations; a
+ * negation's is what it removed from the list's positive set.
+ *
+ * `paths` may be a wider walk than this list's own (a union over many rules):
+ * only the paths one of THIS list's inclusion globs matches are its positive
+ * set, so another list's files never count as excluded here.
+ */
+export function measureGlobList(paths, globs) {
+    const list = globListParts(globs);
+    const positive = list.exclude.length === 0 ? undefined : paths.filter((p) => matchesAny(p, list.include));
+    const selected = positive?.filter((p) => !matchesAny(p, list.exclude));
+    const out = [];
+    const seen = new Set();
+    for (const glob of globs) {
+        if (seen.has(glob))
+            continue;
+        seen.add(glob);
+        if (isNegatedGlob(glob)) {
+            const re = globToRegex(glob.slice(1));
+            let excluded = 0;
+            for (const p of positive ?? [])
+                if (re.test(p))
+                    excluded += 1;
+            out.push({ glob, negation: true, matched: excluded, effective: excluded });
+            continue;
+        }
+        const re = globToRegex(glob);
+        let matched = 0;
+        for (const p of paths)
+            if (re.test(p))
+                matched += 1;
+        let effective = matched;
+        if (selected !== undefined) {
+            effective = 0;
+            for (const p of selected)
+                if (re.test(p))
+                    effective += 1;
+        }
+        out.push({ glob, negation: false, matched, effective });
+    }
+    return out;
+}
+/** A project-relative directory path without `./` or trailing slashes (`''` is the root). */
+function normaliseDirPath(dir) {
+    let d = dir;
+    if (d === '.' || d === './')
+        return '';
+    if (d.startsWith('./'))
+        d = d.slice(2);
+    return d.replace(/\/+$/, '');
+}
+/**
+ * Could `glob` match some path strictly BENEATH directory `dir` (project-
+ * relative, `/`-separated; a trailing `/` is optional and `./` is the root)?
+ *
+ * The question an unlistable directory asks: its files were never enumerated,
+ * so a rule is in front of it whenever a path under it COULD be in the rule's
+ * scope. Segment-wise and deliberately one-directional: a `**` absorbs the
+ * rest, so a false "yes" is possible (a gap reported that a full listing might
+ * have ruled out) and a false "no" is not — `src/app/*.ts` cannot reach
+ * `src/app/sub/`, `src/app/**` and `**\/*.ts` can.
+ */
+export function globMayMatchUnder(glob, dir) {
+    const d = normaliseDirPath(dir);
+    const dirSegs = d === '' ? [] : d.split('/');
+    const globSegs = glob.split('/');
+    for (let i = 0; i < globSegs.length; i += 1) {
+        const segment = globSegs[i];
+        if (segment.includes('**'))
+            return true;
+        // The directory is consumed and the glob has segments left for a file beneath it.
+        if (i >= dirSegs.length)
+            return true;
+        if (!globToRegex(segment).test(dirSegs[i]))
+            return false;
+    }
+    // The glob ended at (or above) the directory: nothing strictly beneath it matches.
+    return false;
+}
+/**
+ * Does `glob` match EVERY path beneath directory `dir`? True for `**`, and for
+ * a glob ending in `/**` whose base matches the directory or one of its
+ * ancestors (`src/generated/**` covers `src/generated/` and
+ * `src/generated/deep/`). The test an exemption must pass to take an
+ * unlistable directory out of a rule's scope: exempting PART of it leaves the
+ * rest a gap. Conservative — any other shape answers `false`.
+ */
+export function globCoversAllUnder(glob, dir) {
+    if (glob === '**')
+        return true;
+    if (!glob.endsWith('/**'))
+        return false;
+    const base = glob.slice(0, -3);
+    const d = normaliseDirPath(dir);
+    if (d === '')
+        return false;
+    const segs = d.split('/');
+    for (let n = segs.length; n >= 1; n -= 1) {
+        if (globToRegex(base).test(segs.slice(0, n).join('/')))
+            return true;
+    }
+    return false;
+}
+/**
+ * How many of `paths` each glob of ONE list effectively counts for, keyed by
+ * glob in first-seen order (a glob listed twice is counted once): an inclusion
+ * glob's selected files (those surviving the list's negations), a negation's
+ * EXCLUDED files. The `glob → effective` projection of {@link measureGlobList}.
+ *
+ * `globListSelects` collapses a glob LIST into one yes/no, which is right for
+ * "is this file in scope" and exactly wrong for "is every glob still live": one
+ * glob of a rule's `files[]` can match nothing after a directory rename while
+ * its siblings keep the rule connected, and the rule reads green forever. A
+ * zero here is that dead unit — and, since round 12, a negation is judged by
+ * what it EXCLUDES, so a load-bearing `!**\/*.spec.ts` is never a zero. Pure —
+ * callers pass the file list their own walk produced.
+ */
+export function countMatchesPerGlob(paths, globs) {
+    return new Map(measureGlobList(paths, globs).map((m) => [m.glob, m.effective]));
+}

package/dist/scan/i-glob-unit-measure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What ONE glob of a list did to a set of paths (`measureGlobList`).
+ *
+ * An inclusion glob's `effective` count is the paths it matched that SURVIVE
+ * the list's negations; a negation's is the paths it REMOVED from what the
+ * list's inclusion globs selected. So "is this unit live?" is `effective > 0`
+ * for both kinds, and a negation is never "dead" merely for matching no path
+ * on its own — a negation matches nothing by itself; it subtracts.
+ */
+export interface IGlobUnitMeasure {
+    /** The glob as written (a negation keeps its `!`). */
+    readonly glob: string;
+    readonly negation: boolean;
+    /**
+     * Inclusion glob: every path it matches. Negation: every path it matches
+     * among those the list's inclusion globs select (its raw reach).
+     */
+    readonly matched: number;
+    /** Inclusion glob: matched paths that are selected. Negation: paths it excludes. */
+    readonly effective: number;
+}
+//# sourceMappingURL=i-glob-unit-measure.d.ts.map

package/dist/scan/i-glob-unit-measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-glob-unit-measure.d.ts","sourceRoot":"","sources":["../../src/scan/i-glob-unit-measure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/scan/i-glob-unit-measure.js

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

package/dist/scan/import-pattern.d.ts

@@ -0,0 +1,109 @@
+import type { BoundaryMatchKind, ForbiddenMatchMode } from '../model/boundary-rule.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 declare function isPackagePattern(pattern: string): boolean;
+/**
+ * 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 declare function matchImportPattern(specifier: string, pattern: string, mode?: ForbiddenMatchMode): BoundaryMatchKind | 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 declare function importPatternDefect(pattern: string, mode?: ForbiddenMatchMode): string | 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 declare function importPatternSubsumes(outer: string, inner: string, outerMode?: ForbiddenMatchMode, innerMode?: ForbiddenMatchMode): boolean;
+/** Why the dead-unit judge never calls a relative specifier pattern dead — its went-live evidence and the marker refusal both quote it. */
+export declare 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 declare 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 declare function couldMatchPackageName(pattern: string, name: string, mode: ForbiddenMatchMode): boolean;
+/**
+ * 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 declare function importPatternNeverJudgedDead(pattern: string, mode?: ForbiddenMatchMode): string | undefined;
+//# sourceMappingURL=import-pattern.d.ts.map

package/dist/scan/import-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-pattern.d.ts","sourceRoot":"","sources":["../../src/scan/import-pattern.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIvF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,kBAA8B,GACnC,iBAAiB,GAAG,IAAI,CAM1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,kBAA8B,GAAG,MAAM,GAAG,SAAS,CAoB7G;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,kBAA8B,EACzC,SAAS,GAAE,kBAA8B,GACxC,OAAO,CAgBT;AAED,2IAA2I;AAC3I,eAAO,MAAM,2BAA2B,4FACmD,CAAC;AAE5F,8IAA8I;AAC9I,eAAO,MAAM,2BAA2B,sFAC6C,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAkBtG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,kBAA8B,GAAG,MAAM,GAAG,SAAS,CAWtH"}