@nielspeter/eess 0.1.0

package/dist/rule-builder.js

@@ -0,0 +1,323 @@
+import { isSilent } from './silent-exclusion.js';
+import { executeCheck, executeWarn, applyFilters } from './execute-rule.js';
+/**
+ * Abstract base class for all rule builders.
+ *
+ * Concrete entry points (plans 0007+) extend this and:
+ * 1. Implement `getElements()` to return the elements to check
+ * 2. Add predicate methods that call `addPredicate()`
+ * 3. Add condition methods that call `addCondition()`
+ *
+ * The builder accumulates predicates and conditions. Nothing executes
+ * until a terminal method (`.check()`, `.warn()`, `.severity()`) is called.
+ */
+export class RuleBuilder {
+    project;
+    _predicates = [];
+    _conditions = [];
+    _reason;
+    _metadata;
+    _exclusions = [];
+    _silentIndices = new Set();
+    _phase = 'predicate';
+    constructor(project) {
+        this.project = project;
+    }
+    // --- Chain methods (grammar transitions) ---
+    /**
+     * Begin the predicate phase. Returns `this` for chaining.
+     * Purely a readability marker — `.that().haveNameMatching(...)` reads like English.
+     * Explicitly resets phase to 'predicate' — defensive against `.should().that()` misuse.
+     */
+    that() {
+        this._phase = 'predicate';
+        return this;
+    }
+    /**
+     * Add another predicate (AND). Returns `this` for chaining.
+     * `.that().extend('Base').and().resideInFolder('src/repos/**')` means both must match.
+     */
+    and() {
+        return this;
+    }
+    /**
+     * Begin the condition phase. Returns a forked builder for named selection safety.
+     * Creates a fresh builder with the same predicates but empty conditions.
+     * Sets phase to 'condition' so dual-use methods dispatch correctly.
+     */
+    should() {
+        const fork = this.fork();
+        fork._phase = 'condition';
+        return fork;
+    }
+    /**
+     * Add another condition that must ALSO pass (AND).
+     * `.should().notContain(call('x')).andShould().notContain(call('y'))` means both must hold.
+     */
+    andShould() {
+        return this;
+    }
+    /**
+     * Plug in a custom predicate or condition.
+     *
+     * After `.that()` — pass a `Predicate<T>` to filter elements.
+     * After `.should()` — pass a `Condition<T>` to assert against filtered elements.
+     *
+     * Dispatch is structural: if the object has a `test` method it is treated
+     * as a predicate; if it has `evaluate` it is treated as a condition.
+     */
+    satisfy(custom) {
+        if ('test' in custom) {
+            return this.addPredicate(custom);
+        }
+        return this.addCondition(custom);
+    }
+    /**
+     * Attach a human-readable rationale to the rule.
+     * Included in violation messages when `.check()` throws.
+     */
+    because(reason) {
+        this._reason = reason;
+        return this;
+    }
+    /**
+     * Attach rich metadata to the rule.
+     * Provides educational context in violation output: why, how to fix, docs link.
+     *
+     * If `metadata.because` is set, it also sets the reason (same as `.because()`).
+     */
+    rule(metadata) {
+        this._metadata = metadata;
+        if (metadata.because) {
+            this._reason = metadata.because;
+        }
+        return this;
+    }
+    /**
+     * Exclude specific violations from reporting by matching against
+     * the violation's `element`, `file`, or `message` fields.
+     *
+     * Matched violations are silently suppressed. Use for permanent,
+     * intentional exceptions — not for temporary violations (use baseline for those).
+     *
+     * Patterns are matched against all three fields. Prefer anchored regexes
+     * or full string matches over short substrings, especially for `message`
+     * matching, to avoid accidentally suppressing unrelated violations whose
+     * messages happen to contain the same text.
+     *
+     * Emits a warning if an exclusion matches zero violations — so renamed
+     * or deleted exceptions don't silently stay in the rule.
+     *
+     * For narrowing a rule's scope at the predicate phase (so the rule never
+     * evaluates the excluded element), use `satisfy(not(<predicate>))` instead.
+     * See the "Excluding a file from a rule's scope" recipe in docs/recipes.md.
+     *
+     * @example
+     * // Exclude by element name (fully qualified)
+     * .excluding('Asset.getImageUrl')
+     *
+     * @example
+     * // Exclude by file path (regex anchored to suffix)
+     * .excluding(/repositories\/index\.ts$/)
+     *
+     * @example
+     * // Multiple exclusions, mixed forms
+     * .excluding('Asset.getImageUrl', /\/legacy\//, /generated/)
+     */
+    excluding(...patterns) {
+        for (const p of patterns) {
+            if (isSilent(p)) {
+                this._exclusions.push(p.pattern);
+                this._silentIndices.add(this._exclusions.length - 1);
+            }
+            else {
+                this._exclusions.push(p);
+            }
+        }
+        return this;
+    }
+    // --- Terminal methods ---
+    /**
+     * Return the predicate-filtered elements as a labelled `Selection<T>` for
+     * cross-validation (`correspondence()`). The set is exactly the elements this
+     * rule would evaluate — the same filtering `.check()` applies.
+     *
+     * @param opts.label - human-readable name of this side ("diagram class")
+     * @param opts.identify - map an element to its message metadata (name/file/line)
+     */
+    select(opts) {
+        const filtered = this.getElements().filter((element) => this._predicates.every((predicate) => predicate.test(element)));
+        return { elements: filtered, label: opts.label, identify: opts.identify };
+    }
+    /**
+     * Return a structured description of this rule without executing it.
+     * Used by the `explain` CLI subcommand.
+     */
+    describeRule() {
+        return {
+            rule: this.buildRuleDescription(),
+            id: this._metadata?.id,
+            because: this._reason,
+            suggestion: this._metadata?.suggestion,
+            docs: this._metadata?.docs,
+        };
+    }
+    /**
+     * Execute the rule and return violations after exclusion filtering.
+     * Does not throw — use for programmatic access (presets, aggregation).
+     */
+    violations() {
+        const raw = this.evaluate();
+        return applyFilters(raw, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        });
+    }
+    /**
+     * Execute the rule and throw `ArchRuleError` if any violations are found.
+     * This is the primary terminal method — use in test assertions.
+     *
+     * @param options - Optional baseline and diff filtering
+     */
+    check(options) {
+        const violations = this.evaluate();
+        executeCheck(violations, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        }, options);
+    }
+    /**
+     * Execute the rule and log violations to stderr. Does not throw.
+     * Use for rules that should warn but not fail CI.
+     *
+     * @param options - Optional baseline and diff filtering
+     */
+    warn(options) {
+        const violations = this.evaluate();
+        executeWarn(violations, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        }, options);
+    }
+    /**
+     * Execute the rule with the given severity.
+     * `.severity('error')` is equivalent to `.check()`.
+     * `.severity('warn')` is equivalent to `.warn()`.
+     */
+    severity(level) {
+        if (level === 'error') {
+            this.check();
+        }
+        else {
+            this.warn();
+        }
+    }
+    // --- Protected: for subclasses ---
+    /**
+     * Register a predicate. Called by concrete builder methods like
+     * `.haveNameMatching()`, `.extend()`, etc.
+     */
+    addPredicate(predicate) {
+        this._predicates.push(predicate);
+        return this;
+    }
+    /**
+     * Register a condition. Called by concrete builder methods like
+     * `.notContain()`, `.notExist()`, etc.
+     */
+    addCondition(condition) {
+        this._conditions.push(condition);
+        return this;
+    }
+    /**
+     * Create a fork of this builder with the same predicates but empty conditions.
+     * Used by `.should()` to support named selections without mutation.
+     *
+     * Subclasses with additional constructor args MUST override this method.
+     */
+    fork() {
+        // Object.create/getPrototypeOf return untyped — casts unavoidable at JS interop boundary
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const proto = Object.getPrototypeOf(this);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const fork = Object.create(proto);
+        Object.assign(fork, this);
+        fork._predicates = [...this._predicates];
+        fork._conditions = [];
+        fork._exclusions = [...this._exclusions];
+        fork._silentIndices = new Set(this._silentIndices);
+        fork._metadata = this._metadata ? { ...this._metadata } : undefined;
+        fork._reason = fork._metadata?.because ?? this._reason;
+        return fork;
+    }
+    // --- Private: execution engine ---
+    /**
+     * Build the rule description from predicates and conditions.
+     */
+    buildRuleDescription() {
+        const predicateDesc = this._predicates.map((p) => p.description).join(' and ');
+        const conditionDesc = this._conditions.map((c) => c.description).join(' and ');
+        const parts = [];
+        if (predicateDesc)
+            parts.push(`that ${predicateDesc}`);
+        if (conditionDesc)
+            parts.push(`should ${conditionDesc}`);
+        return parts.join(' ');
+    }
+    /**
+     * Execute the full pipeline: filter elements with predicates,
+     * evaluate conditions, return violations.
+     */
+    evaluate() {
+        // Step 1: Get all elements from the concrete builder
+        const allElements = this.getElements();
+        // Step 2: Filter with predicates (AND — all predicates must match)
+        const filtered = allElements.filter((element) => this._predicates.every((predicate) => predicate.test(element)));
+        // Step 3: If no elements match predicates, no violations
+        if (filtered.length === 0) {
+            return [];
+        }
+        // Step 3b: Warn if no conditions were added and phase is still 'predicate'
+        // — likely a predicate-only method was called after .should().
+        // Phase-aware methods dispatch correctly, so this only fires for predicate-only methods.
+        if (this._conditions.length === 0 && this._phase === 'predicate') {
+            const ruleId = this._metadata?.id ?? (this.buildRuleDescription() || 'unnamed');
+            console.warn(`[eess] Rule '${ruleId}' has predicates but no conditions. ` +
+                `Did you use a predicate-only method after .should()? ` +
+                `Predicate-only methods (e.g. areExported, areAsync) filter elements; ` +
+                `use a condition method or .satisfy() after .should().`);
+            return [];
+        }
+        // Step 4: Build context for conditions
+        const context = this.buildConditionContext();
+        // Step 5: Evaluate all conditions (AND — all must pass)
+        const violations = [];
+        for (const condition of this._conditions) {
+            violations.push(...condition.evaluate(filtered, context));
+        }
+        return violations;
+    }
+    /**
+     * Build the `ConditionContext` passed to each condition.
+     *
+     * Subclasses with builder-specific context fields (e.g. `CallRuleBuilder`'s
+     * `_identifyByArgument`) override this to extend the base context.
+     * Call `super.buildConditionContext()` and spread the result.
+     */
+    buildConditionContext() {
+        return {
+            rule: this.buildRuleDescription(),
+            because: this._reason,
+            ruleId: this._metadata?.id,
+            suggestion: this._metadata?.suggestion,
+            docs: this._metadata?.docs,
+        };
+    }
+}
+//# sourceMappingURL=rule-builder.js.map

package/dist/rule-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-builder.js","sourceRoot":"","sources":["../src/rule-builder.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAG3E;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,WAAW;IASA;IARrB,WAAW,GAAmB,EAAE,CAAA;IAChC,WAAW,GAAmB,EAAE,CAAA;IAChC,OAAO,CAAS;IAChB,SAAS,CAAe;IACxB,WAAW,GAAwB,EAAE,CAAA;IACrC,cAAc,GAAgB,IAAI,GAAG,EAAE,CAAA;IACvC,MAAM,GAA8B,WAAW,CAAA;IAEzD,YAA+B,OAAU;QAAV,YAAO,GAAP,OAAO,CAAG;IAAG,CAAC;IAE7C,8CAA8C;IAE9C;;;;OAIG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,WAAW,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,GAAG;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,WAAW,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAmC;QACzC,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAc;QACpB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,QAAsB;QACzB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;QACjC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,SAAS,CAAC,GAAG,QAA+C;QAC1D,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;gBAChC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YACtD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,2BAA2B;IAE3B;;;;;;;OAOG;IACH,MAAM,CAAC,IAA8D;QACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CACrD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAC/D,CAAA;QACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;IAC3E,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,oBAAoB,EAAE;YACjC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU;YACtC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI;SAC3B,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;QAC3B,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAsB;QAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;QAClC,YAAY,CACV,UAAU,EACV;YACE,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,EACD,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAsB;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;QAClC,WAAW,CACT,UAAU,EACV;YACE,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,EACD,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAuB;QAC9B,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAED,oCAAoC;IAEpC;;;OAGG;IACO,YAAY,CAAC,SAAuB;QAC5C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAChC,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACO,YAAY,CAAC,SAAuB;QAC5C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAChC,OAAO,IAAI,CAAA;IACb,CAAC;IAQD;;;;;OAKG;IACO,IAAI;QACZ,yFAAyF;QACzF,mEAAmE;QACnE,MAAM,KAAK,GAAW,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;QACjD,mEAAmE;QACnE,MAAM,IAAI,GAAS,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACvC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACzB,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;QACxC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAA;QACrB,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;QACxC,IAAI,CAAC,cAAc,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAClD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QACnE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAA;QACtD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,oCAAoC;IAEpC;;OAEG;IACK,oBAAoB;QAC1B,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC9E,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC9E,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,IAAI,aAAa;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,aAAa,EAAE,CAAC,CAAA;QACtD,IAAI,aAAa;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,aAAa,EAAE,CAAC,CAAA;QACxD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB,CAAC;IAED;;;OAGG;IACK,QAAQ;QACd,qDAAqD;QACrD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAEtC,mEAAmE;QACnE,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAC9C,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAC/D,CAAA;QAED,yDAAyD;QACzD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAA;QACX,CAAC;QAED,2EAA2E;QAC3E,+DAA+D;QAC/D,yFAAyF;QACzF,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACjE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,SAAS,CAAC,CAAA;YAC/E,OAAO,CAAC,IAAI,CACV,gBAAgB,MAAM,sCAAsC;gBAC1D,uDAAuD;gBACvD,uEAAuE;gBACvE,uDAAuD,CAC1D,CAAA;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QAED,uCAAuC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAA;QAE5C,wDAAwD;QACxD,MAAM,UAAU,GAAoB,EAAE,CAAA;QACtC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACzC,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;QAC3D,CAAC;QAED,OAAO,UAAU,CAAA;IACnB,CAAC;IAED;;;;;;OAMG;IACO,qBAAqB;QAC7B,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,oBAAoB,EAAE;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE;YAC1B,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU;YACtC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI;SAC3B,CAAA;IACH,CAAC;CACF"}

package/dist/rule-description.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Structured description of a rule, returned by `.describe()`.
+ * Used by the `explain` CLI subcommand to dump active rules as JSON.
+ */
+export interface RuleDescription {
+    rule: string;
+    id?: string;
+    because?: string;
+    suggestion?: string;
+    docs?: string;
+}
+//# sourceMappingURL=rule-description.d.ts.map

package/dist/rule-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-description.d.ts","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd"}

package/dist/rule-description.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rule-description.js.map

package/dist/rule-description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-description.js","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":""}

package/dist/rule-metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Rich metadata for an architecture rule.
+ *
+ * Provides educational context beyond the violation message:
+ * why the rule exists, how to fix violations, where to learn more.
+ */
+export interface RuleMetadata {
+    /** Unique rule identifier, e.g. 'repo/typed-errors' */
+    id?: string;
+    /** Why this rule exists — the risk or impact */
+    because?: string;
+    /** How to fix — actionable suggestion with code example */
+    suggestion?: string;
+    /** Link to documentation — ADR, wiki, style guide */
+    docs?: string;
+}
+//# sourceMappingURL=rule-metadata.d.ts.map

package/dist/rule-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-metadata.d.ts","sourceRoot":"","sources":["../src/rule-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IAEX,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd"}

package/dist/rule-metadata.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rule-metadata.js.map

package/dist/rule-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-metadata.js","sourceRoot":"","sources":["../src/rule-metadata.ts"],"names":[],"mappings":""}

package/dist/silent-exclusion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Symbol used to tag silent exclusion patterns.
+ * Not exported — only isSilent() should inspect this.
+ */
+declare const SILENT: unique symbol;
+/**
+ * A wrapped exclusion pattern that suppresses the "unused exclusion" warning.
+ *
+ * Use `silent()` to wrap patterns that intentionally match zero violations in
+ * some configurations — for example, shared exclusions across monorepo workspaces
+ * where not every workspace triggers every pattern.
+ */
+export interface SilentExclusion {
+    readonly pattern: string | RegExp;
+    readonly [SILENT]: true;
+}
+/**
+ * Wrap an exclusion pattern to suppress the "unused exclusion" warning.
+ *
+ * By default, `.excluding()` warns when a pattern matches zero violations
+ * (stale-exclusion detection). Use `silent()` for patterns that are
+ * intentionally broad and may legitimately match nothing in some contexts.
+ *
+ * @example
+ * import { silent } from '\@nielspeter/eess-ts'
+ *
+ * modules(p)
+ *   .should().satisfy(noDeadModules())
+ *   .excluding(silent(/\.d\.ts$/), 'index.ts')
+ *   .check()
+ */
+export declare function silent(pattern: string | RegExp): SilentExclusion;
+/**
+ * Check whether a value is a SilentExclusion.
+ */
+export declare function isSilent(value: unknown): value is SilentExclusion;
+export {};
+//# sourceMappingURL=silent-exclusion.d.ts.map

package/dist/silent-exclusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent-exclusion.d.ts","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,QAAA,MAAM,MAAM,EAAE,OAAO,MAAmC,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAEhE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAEjE"}

package/dist/silent-exclusion.js

@@ -0,0 +1,30 @@
+/**
+ * Symbol used to tag silent exclusion patterns.
+ * Not exported — only isSilent() should inspect this.
+ */
+const SILENT = Symbol('silent-exclusion');
+/**
+ * Wrap an exclusion pattern to suppress the "unused exclusion" warning.
+ *
+ * By default, `.excluding()` warns when a pattern matches zero violations
+ * (stale-exclusion detection). Use `silent()` for patterns that are
+ * intentionally broad and may legitimately match nothing in some contexts.
+ *
+ * @example
+ * import { silent } from '\@nielspeter/eess-ts'
+ *
+ * modules(p)
+ *   .should().satisfy(noDeadModules())
+ *   .excluding(silent(/\.d\.ts$/), 'index.ts')
+ *   .check()
+ */
+export function silent(pattern) {
+    return { pattern, [SILENT]: true };
+}
+/**
+ * Check whether a value is a SilentExclusion.
+ */
+export function isSilent(value) {
+    return typeof value === 'object' && value !== null && SILENT in value;
+}
+//# sourceMappingURL=silent-exclusion.js.map

package/dist/silent-exclusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent-exclusion.js","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,GAAkB,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAcxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,CAAA;AACvE,CAAC"}

package/dist/terminal-builder.d.ts

@@ -0,0 +1,83 @@
+import type { ArchViolation } from './violation.js';
+import type { CheckOptions } from './check-options.js';
+import type { RuleMetadata } from './rule-metadata.js';
+import type { RuleDescription } from './rule-description.js';
+import type { SilentExclusion } from './silent-exclusion.js';
+/**
+ * Abstract base class for builders that share the terminal method pattern
+ * (because, rule, excluding, check, warn, severity) but have different
+ * element collection and evaluation models.
+ *
+ * Used by SliceRuleBuilder, SchemaRuleBuilder, ResolverRuleBuilder,
+ * PairFinalBuilder, and SmellBuilder — all of which implement the same
+ * terminal methods but differ in how they collect and evaluate elements.
+ *
+ * RuleBuilder<T> does NOT extend this because it predates it and has
+ * additional concerns (predicate/condition pipeline, fork semantics).
+ */
+export declare abstract class TerminalBuilder {
+    protected _reason?: string;
+    protected _metadata?: RuleMetadata;
+    private readonly _exclusions;
+    private readonly _silentIndices;
+    /**
+     * Attach a human-readable rationale to the rule.
+     * Included in violation messages when `.check()` throws.
+     */
+    because(reason: string): this;
+    /**
+     * Attach rich metadata to the rule.
+     * Provides educational context in violation output: why, how to fix, docs link.
+     *
+     * If `metadata.because` is set, it also sets the reason (same as `.because()`).
+     */
+    rule(metadata: RuleMetadata): this;
+    /**
+     * Exclude specific elements from violation reporting.
+     *
+     * Matched violations are silently suppressed. Use for permanent,
+     * intentional exceptions — not for temporary violations (use baseline for those).
+     *
+     * Matches against the violation's `element` field.
+     * Supports exact strings and regex patterns.
+     *
+     * Emits a warning if an exclusion matches zero violations (stale exclusion).
+     */
+    excluding(...patterns: (string | RegExp | SilentExclusion)[]): this;
+    /**
+     * Return a structured description of this rule without executing it.
+     * Used by the `explain` CLI subcommand.
+     */
+    describeRule(): RuleDescription;
+    /**
+     * Execute the rule and return violations after exclusion filtering.
+     * Does not throw — use for programmatic access (presets, aggregation).
+     */
+    violations(): ArchViolation[];
+    /**
+     * Execute the rule and throw `ArchRuleError` if any violations are found.
+     * This is the primary terminal method — use in test assertions.
+     *
+     * @param options - Optional baseline, diff filtering, and output format
+     */
+    check(options?: CheckOptions): void;
+    /**
+     * Execute the rule and log violations to stderr. Does not throw.
+     * Use for rules that should warn but not fail CI.
+     *
+     * @param options - Optional baseline, diff filtering, and output format
+     */
+    warn(options?: CheckOptions): void;
+    /**
+     * Execute the rule with the given severity.
+     * `.severity('error')` is equivalent to `.check()`.
+     * `.severity('warn')` is equivalent to `.warn()`.
+     */
+    severity(level: 'error' | 'warn'): void;
+    /**
+     * Subclasses implement this to collect and evaluate violations.
+     * Called lazily during `.check()` / `.warn()`.
+     */
+    protected abstract collectViolations(): ArchViolation[];
+}
+//# sourceMappingURL=terminal-builder.d.ts.map

package/dist/terminal-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-builder.d.ts","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D;;;;;;;;;;;GAWG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAExD;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAQlC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC,EAAE,GAAG,IAAI;IAYnE;;;OAGG;IACH,YAAY,IAAI,eAAe;IAU/B;;;OAGG;IACH,UAAU,IAAI,aAAa,EAAE;IAU7B;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAcnC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAclC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQvC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,aAAa,EAAE;CACxD"}