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

package/dist/evaluate/evaluate-boundaries.js

@@ -1,95 +1,523 @@
-import { matchesAny } from "../scan/glob.js";
+import { UnitDeadCause, UnitDeadWeight, unitProblemsOf, } from '@shrkcrft/core';
+import { BoundaryMarkableList } from "../model/boundary-markable-list.js";
+import { boundaryForbiddenMatch, boundaryPatternOverlaps, boundaryRuleScope, boundaryRuleSeverity, boundaryScopeDecision, } from "../model/boundary-rule-scope.js";
+import { normalizeBoundaryRule } from "../model/normalize-boundary-rule.js";
+import { globToRegex, matchesAny } from "../scan/glob.js";
+import { couldMatchPackageName, importPatternDefect, LEADING_WILDCARD_NEVER_DEAD, matchImportPattern, RELATIVE_PATTERN_NEVER_DEAD, } from "../scan/import-pattern.js";
 import { resolveAliasCandidates, } from "../scan/tsconfig-aliases.js";
-function severityOf(rule) {
-    return rule.severity ?? 'error';
-}
+import { settleBoundaryRule } from "./settle-boundary-rule.js";
+import { withBoundaryRuleSettlement } from "./with-boundary-rule-settlement.js";
+/** The skip reason an unnormalisable rule carries — the loaders' errored-rule words. */
+const NOT_EVALUATED = 'failed validation — NOT evaluated';
 /**
  * Evaluate every rule against every scanned edge. Returns the list of
- * violations + counts. Pure function — no I/O.
+ * violations + counts, and — round 11 — what every rule and every selector
+ * unit actually matched, so a rule that enforced nothing can never read as
+ * evaluated. Pure function — no I/O.
+ *
+ * Round 13: each rule is normalised IDEMPOTENTLY at entry
+ * (`normalizeBoundaryRule` — a loaded rule comes back unchanged), so a
+ * hand-built rule with a `{ pattern, expectEmpty: true }` entry is honoured,
+ * never a `pattern.includes is not a function` crash; and every rule's units
+ * and emptiness settle through the ONE boundary settle (`settleBoundaryRule`).
  */
 export function evaluateBoundaries(scan, rules, options = {}) {
-    const filtered = options.onlyRuleId
+    const selected = options.onlyRuleId
         ? rules.filter((r) => r.id === options.onlyRuleId)
         : rules;
+    const fileUniverse = scan.files ? 'scan' : 'edges';
+    const files = scan.files ?? [...new Set(scan.edges.map((e) => e.from))];
+    const edgesByFile = new Map();
+    for (const e of scan.edges) {
+        const list = edgesByFile.get(e.from);
+        if (list)
+            list.push(e);
+        else
+            edgesByFile.set(e.from, [e]);
+    }
+    // Literal specifier + tsconfig alias resolutions, computed once per specifier.
+    const candidateCache = new Map();
+    const candidatesOf = (specifier) => {
+        const hit = candidateCache.get(specifier);
+        if (hit)
+            return hit;
+        const out = [specifier];
+        if (options.tsconfigPaths) {
+            for (const resolved of resolveAliasCandidates(specifier, options.tsconfigPaths))
+                out.push(resolved);
+        }
+        candidateCache.set(specifier, out);
+        return out;
+    };
+    const distinctSpecifiers = [...new Set(scan.edges.map((e) => e.importSpecifier))];
+    const anywhere = new PatternReach(distinctSpecifiers, candidatesOf, files, options);
     const violations = [];
-    for (const rule of filtered) {
-        for (const edge of scan.edges) {
-            const matchedFrom = firstMatch(edge.from, rule.from);
-            if (!matchedFrom)
+    const suppressed = [];
+    const staleExceptions = [];
+    const coverage = [];
+    const invalidRules = [];
+    for (const input of selected) {
+        const normalized = normalizeBoundaryRule(input);
+        if (!normalized.ok) {
+            const problems = unitProblemsOf(normalized.error);
+            const ruleId = typeof input.id === 'string' ? input.id : '(no id)';
+            invalidRules.push({ ruleId, problems });
+            coverage.push({
+                ruleId,
+                severity: boundaryRuleSeverity(input),
+                status: 'skipped',
+                skipReason: `${NOT_EVALUATED}: ${problems.join('; ')}`,
+                failedOnEmpty: true,
+                filesInScope: 0,
+                exemptFilesInScope: 0,
+                edgesInScope: 0,
+                violations: 0,
+                suppressed: 0,
+                fromGlobs: [],
+                forbidden: [],
+                allowed: [],
+                exemptions: [],
+                exceptions: [],
+                deadUnits: [],
+                coverage: { unit: 'rules', expected: 1, examined: 0, reason: NOT_EVALUATED },
+            });
+            continue;
+        }
+        const rule = normalized.value;
+        const scope = boundaryRuleScope(rule);
+        const mode = boundaryForbiddenMatch(rule);
+        const severity = boundaryRuleSeverity(rule);
+        const forbiddenPatterns = rule.forbiddenImports ?? [];
+        const allowedPatterns = rule.allowedImports ?? [];
+        const exceptions = rule.exceptions ?? [];
+        const governedPerGlob = new Map(scope.include.map((g) => [g, 0]));
+        const anyPerGlob = new Map(scope.include.map((g) => [g, 0]));
+        const exemptPerIndex = scope.exemptions.map(() => 0);
+        const hitsInScope = new Map(forbiddenPatterns.map((p) => [p, 0]));
+        const exceptionMatched = exceptions.map(() => 0);
+        let filesInScope = 0;
+        let exemptFilesInScope = 0;
+        let edgesInScope = 0;
+        let ruleViolations = 0;
+        let ruleSuppressed = 0;
+        for (const file of files) {
+            // THE scope decision — the same function why-file, the rule-graph bridge
+            // and every other reader call, so none of them can disagree with this.
+            const decision = boundaryScopeDecision(scope, file);
+            if (decision === 'out')
                 continue;
-            // Build the candidate list: the literal specifier + any tsconfig
-            // alias resolutions. The first match wins; resolved paths give the
-            // boundary rule a chance to match against `libs/app/adapter/**`
-            // even when the source code wrote `@app/adapter-core`.
-            const specifiers = [edge.importSpecifier];
-            if (options.tsconfigPaths) {
-                for (const resolved of resolveAliasCandidates(edge.importSpecifier, options.tsconfigPaths)) {
-                    specifiers.push(resolved);
-                }
+            const matchedInclude = scope.include.filter((g) => globToRegex(g).test(file));
+            for (const g of matchedInclude)
+                anyPerGlob.set(g, (anyPerGlob.get(g) ?? 0) + 1);
+            let exemptGlob;
+            if (decision === 'exempt') {
+                exemptFilesInScope += 1;
+                scope.exemptions.forEach((e, i) => {
+                    if (globToRegex(e.glob).test(file)) {
+                        exemptPerIndex[i] = (exemptPerIndex[i] ?? 0) + 1;
+                        exemptGlob ??= e.glob;
+                    }
+                });
+            }
+            else {
+                filesInScope += 1;
+                for (const g of matchedInclude)
+                    governedPerGlob.set(g, (governedPerGlob.get(g) ?? 0) + 1);
             }
-            // Forbidden imports — match any candidate.
-            let matchedForbidden;
-            let matchedVia;
-            if (rule.forbiddenImports) {
+            const matchedFrom = matchedInclude[0] ?? scope.include[0] ?? '';
+            for (const edge of edgesByFile.get(file) ?? []) {
+                if (decision === 'in')
+                    edgesInScope += 1;
+                const specifiers = candidatesOf(edge.importSpecifier);
+                let violation;
+                // Forbidden imports — the first candidate any pattern reaches wins.
                 for (const spec of specifiers) {
-                    const m = firstMatch(spec, rule.forbiddenImports);
-                    if (m) {
-                        matchedForbidden = m;
-                        matchedVia = spec !== edge.importSpecifier ? spec : undefined;
+                    let hit;
+                    for (const p of forbiddenPatterns) {
+                        const kind = matchImportPattern(spec, p, mode);
+                        if (kind) {
+                            hit = { pattern: p, kind };
+                            break;
+                        }
+                    }
+                    if (hit) {
+                        violation = violationFor(rule, severity, edge, matchedFrom, hit.pattern, hit.kind);
+                        if (spec !== edge.importSpecifier)
+                            violation.resolvedVia = spec;
+                        if (decision === 'in')
+                            hitsInScope.set(hit.pattern, (hitsInScope.get(hit.pattern) ?? 0) + 1);
                         break;
                     }
                 }
-            }
-            if (matchedForbidden) {
-                const v = violationFor(rule, edge, matchedFrom, matchedForbidden);
-                if (matchedVia)
-                    v.resolvedVia = matchedVia;
-                violations.push(v);
-                continue;
-            }
-            // Allowed imports — when set, anything NOT matching (any candidate)
-            // is a violation.
-            if (rule.allowedImports && rule.allowedImports.length > 0) {
-                const matchedAllowed = specifiers.some((s) => matchesAny(s, rule.allowedImports));
-                if (!matchedAllowed && !edge.importSpecifier.startsWith('.')) {
-                    violations.push({
-                        ...violationFor(rule, edge, matchedFrom, undefined),
-                        notAllowed: true,
-                    });
+                // Allowed imports — when set, anything NOT matching (any candidate) is
+                // a violation. Exact glob semantics: an allow-list is never widened.
+                if (!violation && allowedPatterns.length > 0) {
+                    const matchedAllowed = specifiers.some((s) => matchesAny(s, allowedPatterns));
+                    if (!matchedAllowed && !edge.importSpecifier.startsWith('.')) {
+                        violation = { ...violationFor(rule, severity, edge, matchedFrom, undefined, undefined), notAllowed: true };
+                    }
+                }
+                if (!violation)
+                    continue;
+                if (decision === 'exempt') {
+                    suppressed.push({ violation, reason: 'exempt-file', ...(exemptGlob ? { glob: exemptGlob } : {}) });
+                    ruleSuppressed += 1;
+                    continue;
+                }
+                // Credit EVERY exception whose (path, target) matches this edge, and
+                // suppress the violation once (attributed to the first). Crediting
+                // only the first made an overlapping exception — an area-wide one next
+                // to a file-level one for the same edge — read as STALE (exit 1) while
+                // it matched a real edge. Only an exception matching no violating edge
+                // at all is stale.
+                let exceptionIndex = -1;
+                exceptions.forEach((ex, idx) => {
+                    if (!matchesAny(edge.from, [ex.path]))
+                        return;
+                    if (!specifiers.some((s) => matchImportPattern(s, ex.target, mode) !== null))
+                        return;
+                    exceptionMatched[idx] = (exceptionMatched[idx] ?? 0) + 1;
+                    if (exceptionIndex < 0)
+                        exceptionIndex = idx;
+                });
+                if (exceptionIndex >= 0) {
+                    suppressed.push({ violation, reason: 'exception', exception: exceptions[exceptionIndex] });
+                    ruleSuppressed += 1;
+                    continue;
                 }
+                violations.push(violation);
+                ruleViolations += 1;
             }
         }
+        // ── selector units: OBSERVE, then settle through the one boundary settle ──
+        // Each unit reports two facts (round 13): whether its target EXISTS at all
+        // (raw — before exemptions and effectiveness), which decides a MARKED unit
+        // (intended-empty or went-live); and whether it is LIVE (the dead predicate
+        // this plane has always used, negated), which decides an unmarked one.
+        const includedAny = filesInScope + exemptFilesInScope;
+        const marked = new Set((rule.expectEmptyUnits ?? []).map((m) => `${m.list} ${m.unit}`));
+        const observations = [];
+        for (const g of scope.include) {
+            const any = anyPerGlob.get(g) ?? 0;
+            const governed = governedPerGlob.get(g) ?? 0;
+            observations.push({
+                list: BoundaryMarkableList.From,
+                unit: g,
+                label: g,
+                weight: UnitDeadWeight.Coverage,
+                exists: any > 0,
+                live: governed > 0,
+                matched: any,
+                liveBecause: governed > 0 ? `it governs ${governed} scanned file(s)` : `it matches ${any} scanned file(s)`,
+                deadReason: any > 0 ? `matches only exempt files (${any})` : `matched 0 of ${files.length} scanned files`,
+            });
+        }
+        scope.exemptions.forEach((e, i) => {
+            // The `excludeTests` shorthand is allowed to be vacuous (a repo with no
+            // tests yet). An exemption of a rule whose from globs match nothing
+            // exempts nothing by construction, so it is judged only when marked —
+            // a marker is never left unobserved.
+            if (e.origin === 'excludeTests')
+                return;
+            const list = e.origin === 'from-negation' ? BoundaryMarkableList.From : BoundaryMarkableList.ExemptFiles;
+            const unit = e.origin === 'from-negation' ? `!${e.glob}` : e.glob;
+            if (includedAny === 0 && !marked.has(`${list} ${unit}`))
+                return;
+            const n = exemptPerIndex[i] ?? 0;
+            observations.push({
+                list,
+                unit,
+                label: unit,
+                exists: n > 0,
+                live: n > 0,
+                matched: n,
+                liveBecause: `it exempts ${n} file(s)`,
+                deadReason: includedAny > 0
+                    ? `exempts none of the ${includedAny} file(s) the rule's from globs match`
+                    : "exempts nothing — the rule's from globs match no file",
+            });
+        });
+        // Patterns that can never change the verdict — the one static answer
+        // `boundaries explain` and MCP `get_boundary_rule` print too.
+        const overlaps = boundaryPatternOverlaps(rule);
+        const subsumedBy = new Map(overlaps.redundantForbidden.map((o) => [o.index, o.by]));
+        const shadowedBy = new Map(overlaps.shadowedAllowed.map((o) => [o.index, o.by]));
+        const forbiddenCounts = forbiddenPatterns.map((p, i) => {
+            const reach = anywhere.forbidden(p, mode);
+            const resolvedBy = reach.hits > 0 ? undefined : anywhere.resolvedBy(p, mode);
+            const resolvable = reach.hits > 0 || resolvedBy !== undefined;
+            // A malformed pattern says WHY (the validator rejects it at load; a
+            // hand-built rule reaches here) — never the "typo, retired target" causes.
+            const defect = resolvable ? undefined : importPatternDefect(p, mode);
+            const subpathNote = mode === 'exact' && reach.subpathHits > 0
+                ? ` — ${reach.subpathHits} subpath import(s) of it exist; forbiddenMatch: 'exact' excludes them`
+                : '';
+            observations.push({
+                list: BoundaryMarkableList.ForbiddenImports,
+                unit: p,
+                label: p,
+                exists: resolvable,
+                live: resolvable,
+                matched: reach.hits,
+                liveBecause: reach.hits > 0 ? `${reach.hits} import(s) match it` : `no import yet, but ${resolvedBy ?? 'it resolves'}`,
+                deadReason: defect ??
+                    `matches no import anywhere in the repo, no workspace/dependency package name, no tsconfig alias and no file${subpathNote}`,
+                ...(defect !== undefined ? { cause: UnitDeadCause.Defect } : {}),
+            });
+            const coveredBy = subsumedBy.get(i);
+            return {
+                pattern: p,
+                hitsInScope: hitsInScope.get(p) ?? 0,
+                hitsAnywhere: reach.hits,
+                resolvable,
+                ...(mode === 'exact' ? { subpathHitsAnywhere: reach.subpathHits } : {}),
+                ...(coveredBy !== undefined ? { subsumedBy: coveredBy } : {}),
+            };
+        });
+        const allowedCounts = allowedPatterns.map((p, i) => {
+            const hits = anywhere.allowed(p);
+            const shadow = shadowedBy.get(i);
+            if (shadow !== undefined) {
+                // Forbidden is checked first and allowed never re-admits: an allowance
+                // a forbidden pattern covers can never admit anything — the carve-out
+                // under a bare forbidden package that package semantics made inert.
+                observations.push({
+                    list: BoundaryMarkableList.AllowedImports,
+                    unit: p,
+                    label: p,
+                    exists: hits > 0,
+                    live: false,
+                    matched: hits,
+                    deadReason: `shadowed by forbidden '${shadow}' — forbiddenImports is checked first` +
+                        (mode === 'package' ? ` and '${shadow}' covers every subpath (package semantics)` : '') +
+                        `, so this allowance can never admit an import; carve the subpath out with exceptions[{ path, target: '${p}', reason }]` +
+                        (mode === 'package' ? " or set forbiddenMatch: 'exact'" : ''),
+                    cause: UnitDeadCause.Shadowed,
+                });
+            }
+            else {
+                const resolvedBy = hits > 0 ? undefined : anywhere.resolvedBy(p, 'exact');
+                const resolvable = hits > 0 || resolvedBy !== undefined;
+                const defect = resolvable ? undefined : importPatternDefect(p, 'exact');
+                observations.push({
+                    list: BoundaryMarkableList.AllowedImports,
+                    unit: p,
+                    label: p,
+                    exists: resolvable,
+                    live: resolvable,
+                    matched: hits,
+                    liveBecause: hits > 0 ? `${hits} import(s) match it` : `no import yet, but ${resolvedBy ?? 'it resolves'}`,
+                    deadReason: defect ??
+                        'matches no import anywhere in the repo, no workspace/dependency package name, no tsconfig alias and no file',
+                    ...(defect !== undefined ? { cause: UnitDeadCause.Defect } : {}),
+                });
+            }
+            return { pattern: p, hitsAnywhere: hits, ...(shadow !== undefined ? { shadowedBy: shadow } : {}) };
+        });
+        // ── stale exceptions ──────────────────────────────────────────────────
+        exceptions.forEach((ex, index) => {
+            if ((exceptionMatched[index] ?? 0) > 0)
+                return;
+            staleExceptions.push({
+                ruleId: rule.id,
+                index,
+                exception: ex,
+                severity: 'error',
+                message: `exception ${index} of ${rule.id} (path ${ex.path} → target ${ex.target}; reason: ${ex.reason}) no longer matches any violating edge — delete it, or the rule it narrows is not what you think`,
+            });
+        });
+        // ── status + coverage: THE boundary settle ────────────────────────────
+        const settlement = settleBoundaryRule({
+            rule,
+            observations,
+            includeGlobs: scope.include,
+            filesScanned: files.length,
+            fileUniverse,
+            filesInScope,
+            exemptFilesInScope,
+            violations: ruleViolations,
+            unread: false,
+        });
+        coverage.push(withBoundaryRuleSettlement({
+            ruleId: rule.id,
+            severity,
+            filesInScope,
+            exemptFilesInScope,
+            edgesInScope,
+            violations: ruleViolations,
+            suppressed: ruleSuppressed,
+            fromGlobs: scope.include.map((g) => ({ glob: g, files: governedPerGlob.get(g) ?? 0 })),
+            forbidden: forbiddenCounts,
+            allowed: allowedCounts,
+            exemptions: scope.exemptions.map((e, i) => ({ ...e, files: exemptPerIndex[i] ?? 0 })),
+            exceptions: exceptions.map((ex, i) => ({ ...ex, matched: exceptionMatched[i] ?? 0 })),
+        }, settlement));
     }
     const counts = { error: 0, warning: 0, info: 0 };
     for (const v of violations)
         counts[v.severity] += 1;
+    // Every rule's settled dead list, in rule order — read, never re-derived.
+    const deadUnits = coverage.flatMap((c) => c.deadUnits);
     return {
-        rulesEvaluated: filtered.length,
+        rulesConfigured: selected.length,
+        rulesEvaluated: coverage.filter((c) => c.status !== 'skipped' && c.acceptedAsIntendedEmpty !== true).length,
+        rulesAcceptedEmpty: coverage.filter((c) => c.acceptedAsIntendedEmpty === true).length,
         edgesEvaluated: scan.edges.length,
+        filesScanned: files.length,
+        fileUniverse,
         violations,
         counts,
+        suppressed,
+        suppressedCounts: {
+            exemptFile: suppressed.filter((s) => s.reason === 'exempt-file').length,
+            exception: suppressed.filter((s) => s.reason === 'exception').length,
+        },
+        staleExceptions,
+        coverage,
+        skipped: coverage
+            .filter((c) => c.status === 'skipped')
+            .map((c) => ({
+            ruleId: c.ruleId,
+            reason: c.skipReason ?? 'checked nothing',
+            severity: c.severity,
+            failed: c.failedOnEmpty === true,
+        })),
+        deadUnits,
+        ...(invalidRules.length > 0 ? { invalidRules } : {}),
     };
 }
-function firstMatch(value, patterns) {
-    for (const p of patterns) {
-        if (matchesAny(value, [p]))
-            return p;
+/**
+ * "Could this pattern ever match?" — the whole-scan reach of a pattern,
+ * memoised per (pattern, mode) because rule sets share patterns.
+ *
+ * 0 violations in scope is the NORMAL state of a healthy fence, so a pattern is
+ * dead only when it resolves to nothing ANYWHERE: no import in the repo, no
+ * workspace / dependency / builtin package name, no tsconfig alias, no file.
+ */
+class PatternReach {
+    specifiers;
+    candidatesOf;
+    files;
+    options;
+    forbiddenCache = new Map();
+    allowedCache = new Map();
+    resolveCache = new Map();
+    constructor(specifiers, candidatesOf, files, options) {
+        this.specifiers = specifiers;
+        this.candidatesOf = candidatesOf;
+        this.files = files;
+        this.options = options;
+    }
+    forbidden(pattern, mode) {
+        const key = [mode, pattern].join(String.fromCharCode(0));
+        const cached = this.forbiddenCache.get(key);
+        if (cached)
+            return cached;
+        let hits = 0;
+        let subpathHits = 0;
+        for (const s of this.specifiers) {
+            const candidates = this.candidatesOf(s);
+            if (candidates.some((c) => matchImportPattern(c, pattern, mode) !== null)) {
+                hits += 1;
+            }
+            else if (mode === 'exact' &&
+                candidates.some((c) => matchImportPattern(c, pattern, 'package') === 'subpath')) {
+                subpathHits += 1;
+            }
+        }
+        const out = { hits, subpathHits };
+        this.forbiddenCache.set(key, out);
+        return out;
+    }
+    allowed(pattern) {
+        const cached = this.allowedCache.get(pattern);
+        if (cached !== undefined)
+            return cached;
+        let hits = 0;
+        for (const s of this.specifiers) {
+            if (this.candidatesOf(s).some((c) => matchesAny(c, [pattern])))
+                hits += 1;
+        }
+        this.allowedCache.set(pattern, hits);
+        return hits;
+    }
+    /**
+     * WHY the pattern is resolvable with no import of it today — a relative
+     * target, a known package, an alias, a file — or `undefined` when nothing
+     * names it. The went-live line quotes it (round 13), so a stale marker says
+     * what made its target real.
+     */
+    resolvedBy(pattern, mode) {
+        const key = [mode, pattern].join(String.fromCharCode(0));
+        if (this.resolveCache.has(key))
+            return this.resolveCache.get(key);
+        let out;
+        // A malformed pattern (`importPatternDefect`) cannot mean what it says —
+        // never "resolvable" through a package name it merely spells
+        // (`'@scope/pkg/'` used to read resolvable via the known `@scope/pkg`).
+        if (importPatternDefect(pattern, mode) === undefined) {
+            if (pattern.startsWith('.')) {
+                // A relative pattern cannot be judged without an importing file — so
+                // it is never reported dead, and a marker on it has nothing to wait for
+                // (the rule validator refuses one: `importPatternNeverJudgedDead`).
+                out = RELATIVE_PATTERN_NEVER_DEAD;
+            }
+            else {
+                // Name a piece of EVIDENCE only when it is one: a known package the
+                // pattern actually matches (or names a subpath / prefix of), an alias,
+                // a file. A LEADING `*` "could match" every package name — the
+                // permissive half of the dead predicate, never proof that the target
+                // exists — so it is said as what it is, never as "'<builtin>' is a
+                // known package" (round 13 review: `*-legacy` read "'_http_agent' is a
+                // known package"). The resolvable/not answer is unchanged.
+                const known = this.options.knownPackages ?? [];
+                const leadingWildcard = pattern.startsWith('*');
+                const pkg = known.find((k) => matchImportPattern(k, pattern, mode) !== null) ??
+                    (leadingWildcard ? undefined : known.find((k) => couldMatchPackageName(pattern, k, mode)));
+                const alias = pkg === undefined
+                    ? [...(this.options.tsconfigPaths?.aliases.keys() ?? [])].find((aliasKey) => aliasKey.endsWith('*')
+                        ? pattern.startsWith(aliasKey.slice(0, -1)) ||
+                            couldMatchPackageName(pattern, aliasKey.slice(0, -1) + 'x', mode)
+                        : couldMatchPackageName(pattern, aliasKey, mode))
+                    : undefined;
+                const file = pkg === undefined && alias === undefined
+                    ? this.files.find((f) => matchImportPattern(f, pattern, 'package') !== null)
+                    : undefined;
+                const wildcardOnly = pkg === undefined &&
+                    alias === undefined &&
+                    file === undefined &&
+                    leadingWildcard &&
+                    known.some((k) => couldMatchPackageName(pattern, k, mode));
+                out =
+                    pkg !== undefined
+                        ? `'${pkg}' is a known package (a node builtin, a workspace package or a declared dependency)`
+                        : alias !== undefined
+                            ? `the tsconfig alias '${alias}' names it`
+                            : file !== undefined
+                                ? `the file '${file}' matches it`
+                                : wildcardOnly
+                                    ? LEADING_WILDCARD_NEVER_DEAD
+                                    : undefined;
+            }
+        }
+        this.resolveCache.set(key, out);
+        return out;
     }
-    return undefined;
 }
-function violationFor(rule, edge, matchedFrom, matchedForbidden) {
+function violationFor(rule, severity, edge, matchedFrom, matchedForbidden, matchKind) {
     return {
         ruleId: rule.id,
         ruleTitle: rule.title,
-        severity: severityOf(rule),
+        severity,
         file: edge.from,
         importSpecifier: edge.importSpecifier,
         line: edge.line,
         matchedFrom,
         ...(matchedForbidden ? { matchedForbidden } : {}),
+        ...(matchKind ? { matchKind } : {}),
         message: rule.message ??
             (matchedForbidden
-                ? `Forbidden import in ${edge.from}: "${edge.importSpecifier}" matched "${matchedForbidden}"`
+                ? `Forbidden import in ${edge.from}: "${edge.importSpecifier}" matched "${matchedForbidden}"${matchKind === 'subpath' ? ' (a subpath of the forbidden package)' : ''}`
                 : `Import "${edge.importSpecifier}" not in allowed list for ${rule.id}`),
         ...(rule.suggestedFix ? { suggestedFix: rule.suggestedFix } : {}),
     };

package/dist/evaluate/i-boundary-rule-settle-input.d.ts

@@ -0,0 +1,27 @@
+import type { IUnitObservation } from '@shrkcrft/core';
+import type { IBoundaryRule } from '../model/boundary-rule.js';
+/** What `settleBoundaryRule` needs: one rule's selector-unit observations and the counts its emptiness is decided from. */
+export interface IBoundaryRuleSettleInput {
+    readonly rule: Pick<IBoundaryRule, 'id' | 'severity' | 'failOnEmpty' | 'expectEmptyUnits'>;
+    /**
+     * One per judged unit: `from` inclusions (Coverage weight), `from` negations
+     * and `exemptFiles`, `forbiddenImports`, `allowedImports` (Advisory). The
+     * `list` of each is its `BoundaryMarkableList` value — the list its marks carry.
+     */
+    readonly observations: readonly IUnitObservation[];
+    /** The rule's `from` inclusion globs — named when the rule matched no file. */
+    readonly includeGlobs: readonly string[];
+    /** Scanned files the scopes were counted against. */
+    readonly filesScanned: number;
+    /** Where that file list came from (`edges`: a hand-built scan without a file list). */
+    readonly fileUniverse: 'scan' | 'edges';
+    /** Governed files: inside `from`, not exempt. */
+    readonly filesInScope: number;
+    /** Inside `from` but exempt. */
+    readonly exemptFilesInScope: number;
+    /** The rule's unsuppressed violations. */
+    readonly violations: number;
+    /** A governed file in the rule's scope could not be read: the rule is partial, never "matched nothing". */
+    readonly unread: boolean;
+}
+//# sourceMappingURL=i-boundary-rule-settle-input.d.ts.map

package/dist/evaluate/i-boundary-rule-settle-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-boundary-rule-settle-input.d.ts","sourceRoot":"","sources":["../../src/evaluate/i-boundary-rule-settle-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,2HAA2H;AAC3H,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,UAAU,GAAG,aAAa,GAAG,kBAAkB,CAAC,CAAC;IAC3F;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B"}

package/dist/evaluate/i-boundary-rule-settle-input.js

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

package/dist/evaluate/i-boundary-rule-settlement.d.ts

@@ -0,0 +1,23 @@
+import type { ISettledRuleEmptiness, ISettledUnitLiveness, IUnitStateLists, IVerdictCoverage } from '@shrkcrft/core';
+import type { BoundaryRuleStatus, IBoundaryDeadUnit } from './evaluate-boundaries.js';
+/** `settleBoundaryRule`'s answer: how one rule settled — its units, its emptiness, and the fields its coverage record carries. */
+export interface IBoundaryRuleSettlement {
+    /** Every unit's state (core `settleUnitLiveness`). */
+    readonly settled: ISettledUnitLiveness;
+    /** What the rule's empty scope is (core `settleRuleEmptiness`). */
+    readonly emptiness: ISettledRuleEmptiness;
+    readonly status: BoundaryRuleStatus;
+    /** Why the rule checked nothing, when `skipped`. */
+    readonly skipReason?: string;
+    /** A skip that fails the run (`failOnEmpty`). */
+    readonly failedOnEmpty: boolean;
+    /** The primary verdict record: the scope-glob shortfall (record A), or the acceptance itself for an IntendedEmpty rule. */
+    readonly coverage: IVerdictCoverage;
+    /** Record B — the rule's intended-empty units, `acceptedBy: 'expectEmpty'`. */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live unit lines (`unitStateLists`), when it has any. */
+    readonly units?: IUnitStateLists;
+    /** The settled `.dead` (UNMARKED units only), as the boundary JSON has always reported them. */
+    readonly deadUnits: readonly IBoundaryDeadUnit[];
+}
+//# sourceMappingURL=i-boundary-rule-settlement.d.ts.map

package/dist/evaluate/i-boundary-rule-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-boundary-rule-settlement.d.ts","sourceRoot":"","sources":["../../src/evaluate/i-boundary-rule-settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEtF,kIAAkI;AAClI,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD"}

package/dist/evaluate/i-boundary-rule-settlement.js

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