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

package/dist/model/boundary-rule-scope.js

@@ -0,0 +1,175 @@
+import { failsWhenEmpty, parseGlobList } from '@shrkcrft/core';
+import { matchesAny } from "../scan/glob.js";
+import { importPatternSubsumes } from "../scan/import-pattern.js";
+import { unreadEntryMatches, unreadEntryWhollyMatches } from "../util/read-scope-coverage.js";
+/**
+ * The ONE answer to "is file F in rule R's scope?" and "how severe is R?".
+ *
+ * Before round 11 four code paths each read `rule.from` on their own — the
+ * evaluator, `why-file`, the rule-graph bridge, the changes summary — and the
+ * CLI renderers each defaulted an unset severity to `'warning'` while the
+ * evaluator enforced it as `'error'` (an author inspecting a rule was told
+ * "warning" for a rule that blocks CI). With exemptions in the model, any
+ * reader that kept matching `from` alone would keep claiming a rule applies to
+ * an exempted file. So every reader calls these, and the evaluator itself
+ * decides scope through {@link boundaryScopeDecision}.
+ */
+/**
+ * The test-file shorthand `excludeTests: true` expands to. Deliberately the
+ * common layouts only — a repo with another convention lists its own globs in
+ * `exemptFiles`.
+ */
+export const TEST_FILE_GLOBS = [
+    '**/__tests__/**',
+    '**/__mocks__/**',
+    '**/*.spec.*',
+    '**/*.test.*',
+];
+/**
+ * A rule's source-side scope: the globs that include files and the globs that
+ * exempt them.
+ *
+ * A `from` entry starting with `!` is normalised into an exemption — the syntax
+ * authors already type (`'!**\/*.spec.ts'`) used to compile to a literal `!`
+ * glob that matched nothing, silently, while the spec file stayed governed.
+ *
+ * `from` is split by core's ONE `!` parser (`parseGlobList`), the same one
+ * every gate plane selects through. The planes differ in what a negation DOES,
+ * never in what it is: here it EXEMPTS (the file is still scanned, its
+ * violations are marked suppressed and counted — the boundary counterpart of
+ * policy `exemptFiles`); on the gate planes it EXCLUDES (out of scope). Both
+ * share one liveness rule: a negation is alive iff it removes at least one
+ * file from its own positive set. A bare `!` is rejected at load
+ * (`globListProblem`), so the empty-glob guard below only meets an
+ * unvalidated rule.
+ */
+export function boundaryRuleScope(rule) {
+    const { include, exclude } = parseGlobList(rule.from ?? []);
+    const exemptions = [];
+    for (const glob of exclude) {
+        if (glob.length > 0)
+            exemptions.push({ glob, origin: 'from-negation' });
+    }
+    for (const glob of rule.exemptFiles ?? [])
+        exemptions.push({ glob, origin: 'exemptFiles' });
+    if (rule.excludeTests === true) {
+        for (const glob of TEST_FILE_GLOBS)
+            exemptions.push({ glob, origin: 'excludeTests' });
+    }
+    return { include, exempt: exemptions.map((e) => e.glob), exemptions };
+}
+/**
+ * Where `relPath` sits relative to a precomputed scope: `in` (governed),
+ * `exempt` (inside `from`, but exempted — still scanned, its violations are
+ * MARKED suppressed, never dropped), or `out`.
+ */
+export function boundaryScopeDecision(scope, relPath) {
+    if (!matchesAny(relPath, scope.include))
+        return 'out';
+    if (scope.exempt.length > 0 && matchesAny(relPath, scope.exempt))
+        return 'exempt';
+    return 'in';
+}
+/**
+ * {@link boundaryScopeDecision} for an UNREAD entry: a file the scan matched
+ * but could not read, or a directory it could not list. A file is governed
+ * exactly as a read one would be. A directory is governed when an include glob
+ * could match beneath it and no exemption covers ALL of it — through the one
+ * unread-entry test every plane uses (`unreadEntryMatches` /
+ * `unreadEntryWhollyMatches`).
+ */
+export function boundaryScopeCoversUnread(scope, u) {
+    if (!unreadEntryMatches(u, scope.include))
+        return false;
+    return !(scope.exempt.length > 0 && unreadEntryWhollyMatches(u, scope.exempt));
+}
+/** {@link boundaryScopeDecision} for one rule — the call every reader uses. */
+export function boundaryRuleCovers(rule, relPath) {
+    return boundaryScopeDecision(boundaryRuleScope(rule), relPath);
+}
+/** The severity the evaluator ENFORCES: an unset severity is `error`. */
+export function boundaryRuleSeverity(rule) {
+    return rule.severity ?? 'error';
+}
+/**
+ * Whether a rule whose scope matched no scanned file is a FAILURE rather than a
+ * skip — the gate planes' `failOnEmpty` default: on for `error` rules. The
+ * boundary VIEW of the one failOnEmpty authority (`failsWhenEmpty`,
+ * `@shrkcrft/core`), never a second default: an `info` rule, like a `warning`
+ * one, defaults off.
+ */
+export function boundaryRuleFailsOnEmpty(rule) {
+    return failsWhenEmpty({
+        ...(rule.failOnEmpty !== undefined ? { failOnEmpty: rule.failOnEmpty } : {}),
+        severity: boundaryRuleSeverity(rule) === 'error' ? 'error' : 'warning',
+    });
+}
+/** How the rule's `forbiddenImports` / `exceptions[].target` match: package semantics unless opted out. */
+export function boundaryForbiddenMatch(rule) {
+    return rule.forbiddenMatch ?? 'package';
+}
+/**
+ * The patterns of one rule that can never change its verdict (round 12,
+ * R12-5.3 / R12-5.6) — the ONE answer the evaluator (coverage `subsumedBy` /
+ * `shadowedBy`, the shadowed dead unit), `boundaries explain` and MCP
+ * `get_boundary_rule` read, through the one subsumption proof beside the
+ * matcher (`importPatternSubsumes`).
+ *
+ *   - `redundantForbidden`: a `forbiddenImports` entry another KEPT entry
+ *     already covers — `@scope/pkg/**` next to `@scope/pkg` under package
+ *     semantics, the `pkg` + `pkg/**` helper consumers wrote while a bare
+ *     pattern missed subpaths. Of two entries covering each other the FIRST is
+ *     kept, and a coverer is always a kept entry, so deleting every redundant
+ *     one never narrows the fence. INFO only.
+ *   - `shadowedAllowed`: an `allowedImports` entry a forbidden entry covers.
+ *     Forbidden is checked first and allowed never re-admits, so it can never
+ *     admit an import — under package semantics a bare forbidden package
+ *     shadows every allowed subpath of it (a carve-out alpha.30 honoured).
+ */
+export function boundaryPatternOverlaps(rule) {
+    const mode = boundaryForbiddenMatch(rule);
+    const forbidden = rule.forbiddenImports ?? [];
+    const allowed = rule.allowedImports ?? [];
+    const covers = (outer, inner) => importPatternSubsumes(forbidden[outer], forbidden[inner], mode);
+    const coveredBy = new Map();
+    for (let i = 0; i < forbidden.length; i += 1) {
+        for (let j = 0; j < forbidden.length; j += 1) {
+            if (j === i || !covers(j, i))
+                continue;
+            if (j > i && covers(i, j))
+                continue; // mutual cover (e.g. a duplicate): the FIRST is kept
+            coveredBy.set(i, j);
+            break;
+        }
+    }
+    // A coverer must itself be KEPT: were both ends of a chain flagged, deleting
+    // every redundant entry could drop the only one that enforced them.
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const [i, j] of coveredBy) {
+            if (!coveredBy.has(j))
+                continue;
+            const kept = forbidden.findIndex((_, k) => k !== i && !coveredBy.has(k) && covers(k, i));
+            if (kept >= 0) {
+                coveredBy.set(i, kept);
+            }
+            else {
+                coveredBy.delete(i);
+                changed = true;
+            }
+        }
+    }
+    const redundantForbidden = [...coveredBy]
+        .sort(([a], [b]) => a - b)
+        .map(([index, by]) => ({ pattern: forbidden[index], index, by: forbidden[by] }));
+    const shadowedAllowed = [];
+    allowed.forEach((pattern, index) => {
+        const shadows = (k) => importPatternSubsumes(forbidden[k], pattern, mode, 'exact');
+        let by = forbidden.findIndex((_, k) => !coveredBy.has(k) && shadows(k));
+        if (by < 0)
+            by = forbidden.findIndex((_, k) => shadows(k));
+        if (by >= 0)
+            shadowedAllowed.push({ pattern, index, by: forbidden[by] });
+    });
+    return { redundantForbidden, shadowedAllowed };
+}

package/dist/model/boundary-rule.d.ts

@@ -1,32 +1,147 @@
+import { type IAssetReference, type IUnitMark } from '@shrkcrft/core';
+import type { IBoundaryRuleInput } from './boundary-rule-input.js';
 export type BoundarySeverity = 'error' | 'warning' | 'info';
+/**
+ * How a rule's `forbiddenImports` (and `exceptions[].target`) match a specifier
+ * (round 11, 1.5):
+ *
+ *   - `package` (the default): a pattern with no `**` and no trailing `/` is a
+ *     PACKAGE pattern — it matches the specifier and every subpath under it
+ *     (`@scope/pkg` → `@scope/pkg/deep`, never `@scope/pkg-legacy`).
+ *   - `exact`: the pattern is matched exactly as a glob — the entrypoint-only
+ *     behaviour, for barrel-avoidance rules ("forbid `lodash`, allow
+ *     `lodash/get`").
+ *
+ * `allowedImports` never takes package semantics: widening an allow-list is the
+ * permissive direction, which would silently turn existing red into green.
+ */
+export type ForbiddenMatchMode = 'package' | 'exact';
+/** Which half of the pattern language matched a forbidden import. */
+export type BoundaryMatchKind = 'exact' | 'subpath';
+/** Where a file sits relative to a rule's scope: governed, exempted, or outside. */
+export type BoundaryScopeDecision = 'in' | 'exempt' | 'out';
+/** One exemption glob, and which rule field it came from. */
+export interface IBoundaryScopeExemption {
+    readonly glob: string;
+    /** `from-negation` = a `!`-prefixed `from` entry; `excludeTests` = the shorthand. */
+    readonly origin: 'from-negation' | 'exemptFiles' | 'excludeTests';
+}
+/** A rule's normalised source-side scope. */
+export interface IBoundaryRuleScope {
+    /** `from` globs that INCLUDE files (every entry not starting with `!`). */
+    readonly include: readonly string[];
+    /** Every exemption glob (from `!` entries, `exemptFiles`, `excludeTests`). */
+    readonly exempt: readonly string[];
+    readonly exemptions: readonly IBoundaryScopeExemption[];
+}
+/**
+ * One adjudicated edge a rule allows. It is safe to ship only because it can
+ * rot loudly: an exception that no longer suppresses any real edge is a
+ * `stale-exception` ERROR, so the list can never grow into permanent silent
+ * width.
+ */
+export interface IBoundaryRuleException {
+    /** File glob of the importing file, matched like `from`. */
+    path: string;
+    /**
+     * Specifier pattern, matched with the rule's `forbiddenImports` semantics
+     * (alias candidates included). So under the default package semantics a
+     * bare target also excuses that package's SUBPATHS — `'@acme/sdk'` excuses
+     * `'@acme/sdk/client'` too: an exception allows one (path, target) PAIR,
+     * which may be more than one edge. Write the deepest subpath you mean;
+     * `forbiddenMatch: 'exact'` makes targets exact too. Deliberate — a target
+     * spelled like the forbidden pattern excuses exactly what that pattern flags
+     * (pinned by r76-exception-target-semantics).
+     */
+    target: string;
+    /** Why the edge is sanctioned. Required — an unexplained exception is not an adjudication. */
+    reason: string;
+}
 export interface IBoundaryRule {
     id: string;
     title: string;
     description?: string;
+    /** Unset means `error` — the evaluator enforces it so (see `boundaryRuleSeverity`). */
     severity?: BoundarySeverity;
     /**
      * Glob patterns describing which files the rule applies to. Matched against
-     * the file path relative to the project root.
+     * the file path relative to the project root. An entry starting with `!` is
+     * an exemption (same as `exemptFiles`).
      */
     from: readonly string[];
     /**
-     * Glob patterns describing imports that are forbidden from `from` files.
-     * Matched against the literal import specifier.
+     * Import specifiers forbidden from `from` files. Matched against the literal
+     * specifier AND its tsconfig-alias-resolved paths, with package semantics
+     * unless `forbiddenMatch: 'exact'` (see {@link ForbiddenMatchMode}).
      */
     forbiddenImports?: readonly string[];
+    /** See {@link ForbiddenMatchMode}. Default `package`. */
+    forbiddenMatch?: ForbiddenMatchMode;
     /**
      * Optional whitelist of allowed imports (when set, non-matching imports
-     * also trigger the rule). Useful for "from X, only @x/y is allowed".
+     * also trigger the rule). Useful for "from X, only @x/y is allowed". Exact
+     * glob semantics — never widened to subpaths.
      */
     allowedImports?: readonly string[];
+    /**
+     * Whether a rule whose `from` globs match NO scanned file fails the run (`1`)
+     * instead of being reported skipped (`2`). Default: `true` for `error`
+     * rules — the gate planes' contract. A rule matching nothing enforced
+     * nothing, whatever its neighbours did.
+     */
+    failOnEmpty?: boolean;
+    /**
+     * File globs subtracted from the source side. Exempt files are still scanned;
+     * their violations are MARKED suppressed (`exempt-file`) and counted — never
+     * silently dropped. An exemption glob matching none of the rule's files is a
+     * dead unit.
+     */
+    exemptFiles?: readonly string[];
+    /** Shorthand: exempt `**\/__tests__/**`, `**\/__mocks__/**`, `**\/*.spec.*`, `**\/*.test.*`. */
+    excludeTests?: boolean;
+    /** Adjudicated edges this rule allows — see {@link IBoundaryRuleException}. */
+    exceptions?: readonly IBoundaryRuleException[];
     tags?: readonly string[];
     appliesWhen?: readonly string[];
     message?: string;
     suggestedFix?: string;
     relatedRules?: readonly string[];
     relatedPathConventions?: readonly string[];
+    /**
+     * Verifiable pointers to what this rule is ABOUT (the directories and
+     * packages its globs describe) — the same shape knowledge entries declare,
+     * swept by the same `shrk knowledge stale-check`. An undeclared key used to be
+     * tolerated and checked by nothing, which is worse than absent: it looks
+     * policed.
+     */
+    references?: readonly IAssetReference[];
+    /**
+     * The rule's `expectEmpty` markers (round 13) — DERIVED by the loader
+     * (`normalizeBoundaryRule`) from `{ pattern, expectEmpty: true, reason? }`
+     * entries in `from` / `exemptFiles` / `forbiddenImports` / `allowedImports`,
+     * each mark's `list` naming its list and its `packageName` stamped from the
+     * contributing pack. The lists above stay plain strings. Never authored: an
+     * authored rule is an {@link IBoundaryRuleInput}, and this key is refused on it.
+     */
+    expectEmptyUnits?: readonly IUnitMark[];
+}
+/** Type a boundary rule as authored — the four selector lists accept `{ pattern, expectEmpty: true, reason? }` entries. */
+export declare function defineBoundaryRule<T extends IBoundaryRuleInput>(rule: T): T;
+/** One pattern of a rule that can never change its verdict, and the forbidden pattern that makes it so. */
+export interface IBoundaryPatternOverlap {
+    readonly pattern: string;
+    /** Its position in its list (`forbiddenImports` or `allowedImports`). */
+    readonly index: number;
+    /** The forbidden pattern that already covers every import it matches. */
+    readonly by: string;
+}
+/** What `boundaryPatternOverlaps` proves about one rule's specifier lists (round 12, R12-5.3 / R12-5.6). */
+export interface IBoundaryPatternOverlaps {
+    /** `forbiddenImports` entries a KEPT sibling already covers — deleting every one never narrows the fence. */
+    readonly redundantForbidden: readonly IBoundaryPatternOverlap[];
+    /** `allowedImports` entries a forbidden entry covers — forbidden is checked first, so they never admit an import. */
+    readonly shadowedAllowed: readonly IBoundaryPatternOverlap[];
 }
-export declare function defineBoundaryRule<T extends IBoundaryRule>(rule: T): T;
 export interface IBoundaryRuleValidationIssue {
     field: string;
     message: string;

package/dist/model/boundary-rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boundary-rule.d.ts","sourceRoot":"","sources":["../../src/model/boundary-rule.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEtE;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,4BAA4B,EAAE,CAAC;CACxC,CAyBA"}
+{"version":3,"file":"boundary-rule.d.ts","sourceRoot":"","sources":["../../src/model/boundary-rule.ts"],"names":[],"mappings":"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"}

package/dist/model/boundary-rule.js

@@ -1,7 +1,18 @@
+import { ASSET_REFERENCE_KINDS, exemptionListProblem, globListProblem, isMarkerObject, normalizeUnitList, unitProblemsOf, } from '@shrkcrft/core';
+import { importPatternDefect } from "../scan/import-pattern.js";
+import { BoundaryMarkableList } from "./boundary-markable-list.js";
+import { boundaryRuleKeyProblems } from "./boundary-rule-key-problems.js";
+import { boundaryRuleMarkerProblems } from "./boundary-rule-marker-problems.js";
+import { boundaryUnitProblemIssue } from "./boundary-unit-problem-issue.js";
+/** Type a boundary rule as authored — the four selector lists accept `{ pattern, expectEmpty: true, reason? }` entries. */
 export function defineBoundaryRule(rule) {
     return rule;
 }
 const ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const SEVERITIES = ['error', 'warning', 'info'];
+const FORBIDDEN_MATCH_MODES = ['package', 'exact'];
+/** How a markable list may be written — named by every "must be a list" refusal. */
+const LIST_ENTRY_SHAPE = 'strings, or { pattern, expectEmpty: true, reason? }';
 export function validateBoundaryRule(value) {
     const issues = [];
     if (!value || typeof value !== 'object') {
@@ -11,14 +22,45 @@ export function validateBoundaryRule(value) {
         };
     }
     const r = value;
+    // Round 13 — a key that is not a rule field (a rule-level `expectEmpty` /
+    // `allowDead` among them) used to load and be silently ignored.
+    issues.push(...boundaryRuleKeyProblems(r));
     if (typeof r.id !== 'string' || !ID_PATTERN.test(r.id)) {
         issues.push({ field: 'id', message: 'id required, slug-style' });
     }
     if (typeof r.title !== 'string' || r.title.length === 0) {
         issues.push({ field: 'title', message: 'title required' });
     }
+    // Round 13 — each markable list through core's ONE marker parser FIRST
+    // (every malformed marker named `<list>[i]: …`); every existing string check
+    // below then runs on the NORMALISED units, so `{ pattern: '!' }` is refused
+    // exactly like `'!'` and a marked pattern gets the same defect check.
+    const normalized = (field) => {
+        const raw = r[field];
+        if (!Array.isArray(raw))
+            return undefined;
+        const n = normalizeUnitList(raw, field);
+        if (!n.ok) {
+            for (const problem of unitProblemsOf(n.error))
+                issues.push(boundaryUnitProblemIssue(problem, field));
+            return undefined;
+        }
+        return n.value;
+    };
+    const from = normalized(BoundaryMarkableList.From);
+    const forbidden = normalized(BoundaryMarkableList.ForbiddenImports);
+    const allowed = normalized(BoundaryMarkableList.AllowedImports);
+    const exempt = normalized(BoundaryMarkableList.ExemptFiles);
     if (!Array.isArray(r.from) || r.from.length === 0) {
-        issues.push({ field: 'from', message: 'from must be a non-empty string array' });
+        issues.push({ field: 'from', message: `from must be a non-empty array of globs (${LIST_ENTRY_SHAPE})` });
+    }
+    else if (from !== undefined) {
+        // The one list-shape check, beside core's one `!` parser: a bare `!` (an
+        // empty exemption, silently dropped before round 12), a `!!x`, or only
+        // exemptions — each governs nothing, forever. On this plane `!` EXEMPTS.
+        const problem = globListProblem(from.units, 'are exemptions');
+        if (problem !== undefined)
+            issues.push({ field: 'from', message: `from ${problem}` });
     }
     if (!Array.isArray(r.forbiddenImports) && !Array.isArray(r.allowedImports)) {
         issues.push({
@@ -26,5 +68,110 @@ export function validateBoundaryRule(value) {
             message: 'either forbiddenImports or allowedImports must be set',
         });
     }
+    if (r.forbiddenImports !== undefined && !Array.isArray(r.forbiddenImports)) {
+        issues.push({ field: 'forbiddenImports', message: `forbiddenImports must be an array of import patterns (${LIST_ENTRY_SHAPE})` });
+    }
+    if (r.allowedImports !== undefined && !Array.isArray(r.allowedImports)) {
+        issues.push({ field: 'allowedImports', message: `allowedImports must be an array of import patterns (${LIST_ENTRY_SHAPE})` });
+    }
+    // R12-5.2 — a specifier pattern that cannot mean what it says (a `!`, an
+    // empty pattern, a trailing `/` under package semantics) is an authoring
+    // error: it used to load, match nothing its author meant, and let the gate
+    // print ✓ over imports of the very package it named. The one predicate
+    // (`importPatternDefect`) sits beside the matcher; `allowedImports` is always
+    // matched exactly, targets take the rule's mode. A normalised list keeps each
+    // entry at its index, so `[i]` names the authored entry.
+    const patternMode = r.forbiddenMatch === 'exact' ? 'exact' : 'package';
+    const checkPatterns = (field, list, mode) => {
+        list?.units.forEach((pattern, i) => {
+            const defect = importPatternDefect(pattern, mode);
+            if (defect !== undefined)
+                issues.push({ field: `${field}[${i}]`, message: `'${pattern}': ${defect}` });
+        });
+    };
+    checkPatterns(BoundaryMarkableList.ForbiddenImports, forbidden, patternMode);
+    checkPatterns(BoundaryMarkableList.AllowedImports, allowed, 'exact');
+    // A marker on a pattern dead by its shape, and failOnEmpty: true over an
+    // all-marked `from` — refused (DECISIONS §4).
+    issues.push(...boundaryRuleMarkerProblems({ from, forbiddenImports: forbidden, allowedImports: allowed }, patternMode, r.failOnEmpty));
+    if (r.severity !== undefined && (typeof r.severity !== 'string' || !SEVERITIES.includes(r.severity))) {
+        issues.push({ field: 'severity', message: `severity must be one of ${SEVERITIES.join(', ')}` });
+    }
+    if (r.forbiddenMatch !== undefined &&
+        (typeof r.forbiddenMatch !== 'string' || !FORBIDDEN_MATCH_MODES.includes(r.forbiddenMatch))) {
+        issues.push({
+            field: 'forbiddenMatch',
+            message: `forbiddenMatch must be one of ${FORBIDDEN_MATCH_MODES.join(', ')}`,
+        });
+    }
+    if (r.failOnEmpty !== undefined && typeof r.failOnEmpty !== 'boolean') {
+        issues.push({ field: 'failOnEmpty', message: 'failOnEmpty must be a boolean' });
+    }
+    if (r.excludeTests !== undefined && typeof r.excludeTests !== 'boolean') {
+        issues.push({ field: 'excludeTests', message: 'excludeTests must be a boolean' });
+    }
+    if (r.exemptFiles !== undefined && !Array.isArray(r.exemptFiles)) {
+        issues.push({ field: 'exemptFiles', message: `exemptFiles must be an array of globs (${LIST_ENTRY_SHAPE})` });
+    }
+    else if (exempt !== undefined) {
+        const problem = exemptionListProblem(exempt.units);
+        if (problem !== undefined)
+            issues.push({ field: 'exemptFiles', message: `exemptFiles ${problem}` });
+    }
+    if (r.exceptions !== undefined) {
+        if (!Array.isArray(r.exceptions)) {
+            issues.push({ field: 'exceptions', message: 'exceptions must be an array of { path, target, reason }' });
+        }
+        else {
+            r.exceptions.forEach((e, i) => {
+                const ex = (e ?? {});
+                for (const key of ['path', 'target', 'reason']) {
+                    const v = ex[key];
+                    if (key === 'target' && isMarkerObject(v)) {
+                        // Round 13: an exception adjudicates a real edge; one written
+                        // ahead of its edge is width with nothing to adjudicate, and it
+                        // must rot loudly (stale-exception, exit 1) — never be waived.
+                        issues.push({
+                            field: `exceptions[${i}].target`,
+                            message: 'exceptions take no expectEmpty — a stale exception is an error by design',
+                        });
+                        continue;
+                    }
+                    if (typeof v !== 'string' || v.trim().length === 0) {
+                        issues.push({
+                            field: `exceptions[${i}].${key}`,
+                            message: key === 'reason'
+                                ? 'an exception needs a non-empty reason — an unexplained exception is not an adjudication'
+                                : `${key} must be a non-empty string`,
+                        });
+                    }
+                }
+                if (typeof ex.target === 'string' && ex.target.trim().length > 0) {
+                    const defect = importPatternDefect(ex.target, patternMode);
+                    if (defect !== undefined) {
+                        issues.push({ field: `exceptions[${i}].target`, message: `'${ex.target}': ${defect}` });
+                    }
+                }
+            });
+        }
+    }
+    if (r.references !== undefined) {
+        // Shape only — whether each target still resolves is the staleness
+        // sweep's job (`shrk knowledge stale-check`), against the live tree.
+        if (!Array.isArray(r.references)) {
+            issues.push({ field: 'references', message: 'references must be an array of { kind, path | id | symbol }' });
+        }
+        else {
+            r.references.forEach((ref, i) => {
+                const kind = ref?.kind;
+                if (typeof kind !== 'string' || !ASSET_REFERENCE_KINDS.includes(kind)) {
+                    issues.push({
+                        field: `references[${i}].kind`,
+                        message: `kind must be one of ${ASSET_REFERENCE_KINDS.join(', ')}`,
+                    });
+                }
+            });
+        }
+    }
     return { valid: issues.length === 0, issues };
 }

package/dist/model/boundary-unit-problem-issue.d.ts

@@ -0,0 +1,9 @@
+import type { IBoundaryRuleValidationIssue } from './boundary-rule.js';
+/**
+ * One core marker problem (`<listPath>[i]: …`, from `normalizeUnitList`) as a
+ * boundary validation issue — field `<listPath>[i]`, message the sentence after
+ * it — so every surface prints `forbiddenImports[1]: …` once, in the shape
+ * every other boundary issue has (`field: message`).
+ */
+export declare function boundaryUnitProblemIssue(problem: string, listPath: string): IBoundaryRuleValidationIssue;
+//# sourceMappingURL=boundary-unit-problem-issue.d.ts.map

package/dist/model/boundary-unit-problem-issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-unit-problem-issue.d.ts","sourceRoot":"","sources":["../../src/model/boundary-unit-problem-issue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,4BAA4B,CAOxG"}

package/dist/model/boundary-unit-problem-issue.js

@@ -0,0 +1,16 @@
+/**
+ * One core marker problem (`<listPath>[i]: …`, from `normalizeUnitList`) as a
+ * boundary validation issue — field `<listPath>[i]`, message the sentence after
+ * it — so every surface prints `forbiddenImports[1]: …` once, in the shape
+ * every other boundary issue has (`field: message`).
+ */
+export function boundaryUnitProblemIssue(problem, listPath) {
+    if (problem.startsWith(`${listPath}[`)) {
+        const end = problem.indexOf(']: ');
+        if (end > 0)
+            return { field: problem.slice(0, end + 1), message: problem.slice(end + 3) };
+    }
+    if (problem.startsWith(`${listPath}: `))
+        return { field: listPath, message: problem.slice(listPath.length + 2) };
+    return { field: listPath, message: problem };
+}

package/dist/model/normalize-boundary-rule.d.ts

@@ -0,0 +1,21 @@
+import { AppErrorImpl, type Result } from '@shrkcrft/core';
+import type { IBoundaryRule } from './boundary-rule.js';
+import type { IBoundaryRuleInput } from './boundary-rule-input.js';
+/**
+ * An authored boundary rule as the LOADED rule (round 13): each of the four
+ * selector lists through core's ONE marker parser (`normalizeUnitList`) — the
+ * plain string list every reader already consumes, and every
+ * `{ pattern, expectEmpty: true, reason? }` entry as a mark in ONE
+ * `expectEmptyUnits` ledger, stamped with the contributing pack
+ * (`stampUnitMarks`) when the loader knows it.
+ *
+ * Called by the loader after validation (local rules, pack `boundaryFiles`,
+ * `--rule-file` / `--diff-against`) and, IDEMPOTENTLY, at the top of
+ * `evaluateBoundaries` — so a hand-built rule (the plan-review /
+ * plan-simulation call sites, any API caller) never crashes on an object
+ * pattern and never silently ignores a marker. A rule with nothing to
+ * normalise comes back as the same object; a malformed entry is an error
+ * carrying every `<list>[i]: …` problem (`details.problems`).
+ */
+export declare function normalizeBoundaryRule(rule: IBoundaryRuleInput | IBoundaryRule, packageName?: string): Result<IBoundaryRule, AppErrorImpl>;
+//# sourceMappingURL=normalize-boundary-rule.d.ts.map

package/dist/model/normalize-boundary-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-boundary-rule.d.ts","sourceRoot":"","sources":["../../src/model/normalize-boundary-rule.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EASZ,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAKnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,kBAAkB,GAAG,aAAa,EACxC,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,aAAa,EAAE,YAAY,CAAC,CA0CrC"}

package/dist/model/normalize-boundary-rule.js

@@ -0,0 +1,62 @@
+import { AppErrorImpl, ERROR_CODES, err, mergeUnitMarks, normalizeUnitList, ok, stampUnitMarks, unitProblemsOf, } from '@shrkcrft/core';
+import { BoundaryMarkableList } from "./boundary-markable-list.js";
+const LISTS = Object.values(BoundaryMarkableList);
+/**
+ * An authored boundary rule as the LOADED rule (round 13): each of the four
+ * selector lists through core's ONE marker parser (`normalizeUnitList`) — the
+ * plain string list every reader already consumes, and every
+ * `{ pattern, expectEmpty: true, reason? }` entry as a mark in ONE
+ * `expectEmptyUnits` ledger, stamped with the contributing pack
+ * (`stampUnitMarks`) when the loader knows it.
+ *
+ * Called by the loader after validation (local rules, pack `boundaryFiles`,
+ * `--rule-file` / `--diff-against`) and, IDEMPOTENTLY, at the top of
+ * `evaluateBoundaries` — so a hand-built rule (the plan-review /
+ * plan-simulation call sites, any API caller) never crashes on an object
+ * pattern and never silently ignores a marker. A rule with nothing to
+ * normalise comes back as the same object; a malformed entry is an error
+ * carrying every `<list>[i]: …` problem (`details.problems`).
+ */
+export function normalizeBoundaryRule(rule, packageName) {
+    const raw = rule;
+    const problems = [];
+    const normalized = new Map();
+    for (const list of LISTS) {
+        const entries = raw[list];
+        if (entries === undefined)
+            continue;
+        const n = normalizeUnitList(entries, list);
+        if (!n.ok) {
+            problems.push(...unitProblemsOf(n.error));
+            continue;
+        }
+        normalized.set(list, n.value);
+    }
+    if (problems.length > 0) {
+        const id = typeof raw['id'] === 'string' ? raw['id'] : '(no id)';
+        const more = problems.length > 1 ? ` (+${problems.length - 1} more)` : '';
+        return err(new AppErrorImpl(ERROR_CODES.CONFIG_INVALID, `boundary rule '${id}': ${problems[0]}${more}`, {
+            details: { ruleId: id, problems: [...problems] },
+            suggestion: 'write each entry as a plain string, or as { pattern, expectEmpty: true, reason? }',
+        }));
+    }
+    const loaded = rule;
+    const found = [...normalized.values()].flatMap((l) => l.marks);
+    const existing = loaded.expectEmptyUnits ?? [];
+    const stamps = packageName !== undefined && packageName.length > 0 && existing.length > 0;
+    if (found.length === 0 && !stamps)
+        return ok(loaded);
+    const marks = stampUnitMarks(mergeUnitMarks(existing, found), packageName);
+    const units = (list) => normalized.get(list)?.units;
+    const exemptFiles = units(BoundaryMarkableList.ExemptFiles);
+    const forbiddenImports = units(BoundaryMarkableList.ForbiddenImports);
+    const allowedImports = units(BoundaryMarkableList.AllowedImports);
+    return ok({
+        ...loaded,
+        from: units(BoundaryMarkableList.From) ?? loaded.from,
+        ...(exemptFiles !== undefined ? { exemptFiles } : {}),
+        ...(forbiddenImports !== undefined ? { forbiddenImports } : {}),
+        ...(allowedImports !== undefined ? { allowedImports } : {}),
+        ...(marks.length > 0 ? { expectEmptyUnits: marks } : {}),
+    });
+}