@nielspeter/eess 0.2.2 → 0.5.0

package/dist/terminal-builder.d.ts

@@ -1,25 +1,68 @@
 import type { ArchViolation } from './violation.js';
+import { type CollectResult } from './collect-result.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';
+/**
+ * A rule's verdict, carrying evidence of examination alongside the findings —
+ * ADR-010. `examined` is the count of units the family's own examining seam
+ * actually iterated (never a count of matches, never upstream discovery like
+ * files loaded) — each concrete `collectViolations()` names its own unit.
+ *
+ * `sourceEmpty` — ADR-010 part 3's precedence rule: "an empty project
+ * outranks every token." Set `true` when `examined === 0` because the
+ * family's own upstream source (files loaded, a diagram parsed, an SDL
+ * string) produced nothing at all — BEFORE any predicate/selection
+ * narrowed it — as distinct from a predicate narrowing a non-empty source
+ * down to zero. This is a stronger claim than a bare zero-examined dead
+ * selector: `.expectEmpty()` cannot rescue it, because there is no
+ * selection to widen — the instrument itself never loaded anything to
+ * examine. Omit (or `false`) when the distinction doesn't apply (the
+ * family has no separate source/selection stages) or the zero came from
+ * narrowing, not upstream emptiness.
+ */
+export type { CollectResult } from './collect-result.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).
+ * PairFinalBuilder, SmellBuilder, CorrespondenceBuilder, TsconfigBuilder, and
+ * (as of plan 0088 Phase 4) RuleBuilder — all of which implement the same
+ * terminal methods and now share evidence-of-examination (ADR-010) alongside
+ * evaluation-model differences.
  */
 export declare abstract class TerminalBuilder {
     protected _reason?: string;
     protected _metadata?: RuleMetadata;
-    private readonly _exclusions;
-    private readonly _silentIndices;
+    protected _exclusions: (string | RegExp)[];
+    protected _silentIndices: Set<number>;
+    /** ADR-010 part 3 — `.expectEmpty()`/`.expectNonEmpty()`. `undefined` = no declaration. */
+    protected _expectEmpty?: boolean;
+    /**
+     * Declare that this rule's examined set is expected to be empty. A pass is
+     * legitimate only while the declaration stays true — the day a unit is
+     * examined, this rule reddens (ADR-010 part 3's expiry property). The
+     * complement of `expectNonEmpty()`; declaring both is nonsensical and the
+     * later call wins (last-write, matching `.rule()`'s own semantics).
+     */
+    expectEmpty(): this;
+    /**
+     * Declare that this rule's examined set must be non-empty — the opposite
+     * assertion, for a corpus the author has positive knowledge should never
+     * legitimately be empty. Unlike a bare, undeclared rule, this **overrides
+     * `assertsCardinality()`'s exemption**: a `.notExist()`-shaped condition
+     * that finds zero subjects normally passes silently (emptiness satisfies
+     * what it asserts) — but if the author declared `.expectNonEmpty()`, that
+     * silence is exactly what they said should never happen, so it reddens
+     * instead, naming the declaration as the reason. This is the real
+     * difference from not declaring anything: without it, a `.notExist()` rule
+     * over an accidentally-emptied corpus (a glob typo, a temporarily-missing
+     * folder) passes and says nothing; with it, that same emptiness is caught.
+     */
+    expectNonEmpty(): this;
     /**
      * Attach a human-readable rationale to the rule.
      * Included in violation messages when `.check()` throws.
@@ -49,11 +92,27 @@ export declare abstract class TerminalBuilder {
      * Used by the `explain` CLI subcommand.
      */
     describeRule(): RuleDescription;
+    /** This rule's own account of itself, for `vacuity-findings.ts`. */
+    private facts;
+    /**
+     * What every terminal method hands the filter pipeline.
+     *
+     * The same four fields were written out at each of `violations`, `check` and
+     * `warn` — `no-copy-paste` reported the three at 100% with `applyFilters ->
+     * executeCheck` as the only varying axis. `eess-ts`'s `TerminalBuilder`
+     * already had exactly this method; the kernel never adopted it.
+     *
+     * Not just tidier: three terminal methods that build the filter context
+     * separately can drift, and a field present on `.check()` but missing on
+     * `.violations()` means a rule fails in CI and passes when a preset
+     * aggregates it — the same finding, two answers.
+     */
+    private filterContext;
     /**
      * Execute the rule and return violations after exclusion filtering.
      * Does not throw — use for programmatic access (presets, aggregation).
      */
-    violations(): ArchViolation[];
+    violations(): CollectResult;
     /**
      * Execute the rule and throw `ArchRuleError` if any violations are found.
      * This is the primary terminal method — use in test assertions.
@@ -68,6 +127,59 @@ export declare abstract class TerminalBuilder {
      * @param options - Optional baseline, diff filtering, and output format
      */
     warn(options?: CheckOptions): void;
+    /**
+     * ADR-010 — the evidence gate. Calls `collectViolations()` once and turns
+     * its `{ violations, examined, sourceEmpty }` verdict into the
+     * `ArchViolation[]` every terminal method still emits, applying the
+     * declared-empty precedence:
+     *
+     * - `examined === 0`, `sourceEmpty === true`: ADR-010 part 3's precedence
+     *   rule — "an empty project outranks every token." The family's own
+     *   upstream source (files loaded, a diagram parsed) produced nothing at
+     *   all, before any predicate ran. Neither `.expectEmpty()` nor
+     *   `assertsCardinality()` can rescue this: there is no selection to
+     *   widen, and a `.notExist()`-shaped condition "passing" against an
+     *   instrument that never loaded anything is not evidence of anything.
+     *   Always an unsuppressable configuration finding.
+     * - `examined === 0`, `.expectNonEmpty()` declared: the caller has positive
+     *   knowledge this corpus should never be empty — this OVERRIDES
+     *   `assertsCardinality()`'s exemption (a `.notExist()` rule that would
+     *   otherwise pass silently on zero subjects reddens instead, since silent
+     *   emptiness is exactly what the declaration rules out). Fails, naming the
+     *   unmet declaration.
+     * - `examined === 0`, no `.expectEmpty()` declared: the rule's own
+     *   instrument is broken (a dead selector, an unreachable seam) — this is
+     *   a configuration finding, unsuppressable (`bypassFilters`), not a silent
+     *   pass. This is the guarantee ADR-009/010 exist for.
+     * - `examined === 0`, `.expectEmpty()` declared: satisfied. Passes.
+     * - `examined === 0`, `assertsCardinality()` true (and no `.expectNonEmpty()`
+     *   override above): the rule's own conditions are satisfied BY emptiness
+     *   (e.g. `.notExist()`) — a different exemption from `.expectEmpty()`,
+     *   because it is a property of what the condition asserts, not a caller's
+     *   declaration about the corpus. Passes, with no finding at all (not even
+     *   a silent one — the condition already reported truthfully that it found
+     *   nothing wrong).
+     * - `examined > 0`, `.expectEmpty()` declared: the declaration has expired
+     *   — a unit was examined despite the author's "this stays empty" claim.
+     *   Fails, appending an expiry finding to whatever `collectViolations()`
+     *   found (never replacing it — the underlying findings are still real).
+     * - `examined > 0`, no declaration or `.expectNonEmpty()` (the ordinary
+     *   case — `.expectNonEmpty()` has nothing left to assert once subjects
+     *   exist): the rule's own violations stand as computed.
+     */
+    private evidencedViolations;
+    /**
+     * Which finding a zero-examined rule earns, or `undefined` when it earned none
+     * because it declared the emptiness.
+     *
+     * Extracted from `evidencedViolations` under `check:arch`'s complexity rule.
+     * The precedence is the whole content and is unchanged: an empty source
+     * outranks every declaration (ADR-010 §3), an explicit declaration is
+     * satisfied, `.expectNonEmpty()` is unmet, a cardinality condition is
+     * satisfied by emptiness, and a nameable dead glob outranks the generic
+     * message because it is strictly more actionable.
+     */
+    private zeroExaminedFinding;
     /**
      * Execute the rule with the given severity.
      * `.severity('error')` is equivalent to `.check()`.
@@ -75,9 +187,111 @@ export declare abstract class TerminalBuilder {
      */
     severity(level: 'error' | 'warn'): void;
     /**
-     * Subclasses implement this to collect and evaluate violations.
+     * An independent copy of this builder.
+     *
+     * **A held selection is immutable** (a bug class ported alongside the
+     * kernel — plan 0088 Phase 4, matching `ts-archunit`'s own documented
+     * "bug 0016"). Before this, every chain method mutated `this` in place:
+     *
+     * ```ts
+     * const repos = classes(p).that().extend('BaseRepository')
+     * repos.that().haveNameEndingWith('Legacy').should().notExist().check()
+     * repos.should().beExported().check()   // silently narrowed to Legacy too
+     * ```
+     *
+     * A held selection reused for a second rule silently inherited the first
+     * rule's narrowing, exclusions, and rule id — found live in this repo's own
+     * test suite once the ADR-010 evidence gate stopped treating "examined
+     * zero units because a stale narrowing ate the selection" as an ordinary,
+     * silent pass. `because`/`rule`/`excluding`/`expectEmpty`/`expectNonEmpty`
+     * on `TerminalBuilder`, and `that`/`addPredicate`/`addCondition` on
+     * `RuleBuilder`, all return a copy rather than mutating `this`.
+     *
+     * Subclasses with additional fields beyond `TerminalBuilder`'s own MUST
+     * override this (see `RuleBuilder.copy()`) and call `super.copy()` first.
+     */
+    protected copy(): this;
+    /**
+     * Give this builder independent copies of another's filter state.
+     *
+     * `copy()` shallow-copies every field via `Object.assign`, so without this
+     * a copy would share its source's `_exclusions` array and `_silentIndices`
+     * set by reference — `.excluding()` on one would silently mutate the
+     * other, the exact hazard `copy()` exists to close, one field deeper.
+     */
+    protected adoptFilterState(source: TerminalBuilder): void;
+    /**
+     * Subclasses implement this to collect and evaluate violations, and to
+     * report how many units they examined (ADR-010) — counted at the family's
+     * own examining seam, in whatever unit that family names as its own
+     * (post-predicate subjects for `RuleBuilder`, bodies compared for
+     * `SmellBuilder`, the key sets of both sides for `correspondence()`).
      * Called lazily during `.check()` / `.warn()`.
      */
-    protected abstract collectViolations(): ArchViolation[];
+    protected abstract collectViolations(): CollectResult;
+    /**
+     * Is this rule's own assertion satisfied by an empty examined set, as a
+     * matter of what it asserts (`.notExist()`-shaped), not a caller's
+     * `.expectEmpty()` declaration? Default `false` — most families have no
+     * such condition and stay covered by the ordinary zero-examined gate.
+     * `RuleBuilder` overrides this to check its own `_conditions` against the
+     * kernel's `assertsCardinality()` registry (ADR-010, `cardinality.ts`).
+     */
+    protected assertsCardinality(): boolean;
 }
+/**
+ * The configuration finding for a rule that asserts nothing — bug 0155.
+ *
+ * An assertion-less rule — subjects found, nothing asserted about them —
+ * cannot fail, so it certifies nothing while reading as coverage.
+ *
+ * **The guard was unreachable, not merely quiet.** It used to read
+ * `_conditions.length === 0 && _phase === 'predicate'`, and `should()` sets
+ * the phase to `'condition'`, so for every rule shape the DSL documents it
+ * could never fire — the defect passed in total silence, never even reaching
+ * the stderr warning it was routed to. Hence no `_phase` term at the call
+ * site.
+ *
+ * **A finding, not a warning**, per ADR-009 rule 1's discriminator: the remedy
+ * is not optional. There is no state in which "keeps asserting nothing" is
+ * correct — add a condition, or delete the rule. The two rules ADR-009 names
+ * as deliberately `warn` (`no-silent-catch`, `no-empty-bodies`) warn *because*
+ * they carry suppressible false positives a reader must judge case by case.
+ * This carries none.
+ *
+ * **A declared emptiness expectation is an assertion**, so `_expectEmpty`
+ * exempts a rule from this gate. `.expectNonEmpty()` reddens when the corpus
+ * it says must never be empty becomes empty; `.expectEmpty()` reddens the day
+ * the set it says must stay empty gains a member. Neither lives in
+ * `_conditions`. Without that term the gate called a working corpus guard
+ * assertion-less and told its author to "add a condition or delete the rule" —
+ * both of which destroy the guard — and for `.expectEmpty()` reported two
+ * findings for one fault. Found in PR #71's review.
+ *
+ * **Placed AFTER the zero-examined branch**, so a dead selector still reports
+ * as a dead selector. Measured: `resideInFolder('srcc/**')` with no condition
+ * reports the dead glob, not this finding. An earlier draft of this docstring
+ * (and of the changeset and bug record) claimed the opposite — "reports the
+ * missing assertion only" — and justified it as gate-first. Both were wrong:
+ * `getElements()` and the predicate filter already ran, so the ordering saves
+ * no work, and the behaviour is the reverse. The real precedence is the better
+ * one, and is now stated as what it is: this finding fires only when subjects
+ * were actually selected.
+ *
+ * **Exported** rather than private to `RuleBuilder`. Its five siblings
+ * (`zeroExaminedViolation`, `deadGlobViolation`, `unmetExpectNonEmptyViolation`,
+ * `expiredExpectEmptyViolation`, `zeroLoadedSourceViolation`) have since moved to
+ * `vacuity-findings.ts`; this one stayed, because unlike them it is constructed
+ * from a builder's own condition list rather than from `RuleFacts` alone. The *detection* has to stay per-builder —
+ * `TerminalBuilder` has no `_conditions` — but a private constructor meant
+ * `eess-ts`'s slice/schema/resolver builders could not reuse it and were left
+ * warning while the kernel's rules failed: the same defect, one DSL, four
+ * different answers.
+ *
+ * `bypassFilters` makes it a **configuration** finding — `error` regardless of
+ * `.asSeverity('warn')`, refused by `.excluding()`, skipped by diff and
+ * baseline. It reports that the rule's own instrument is broken, not a fault
+ * in what was examined, so a filter aimed at the latter must not suppress it.
+ */
+export declare function assertionLessViolation(ruleId: string, advice?: string): ArchViolation;
 //# sourceMappingURL=terminal-builder.d.ts.map

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

@@ -1 +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;IAW/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"}
+{"version":3,"file":"terminal-builder.d.ts","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,qBAAqB,CAAA;AACvE,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;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAM5D;;;;;;;;;;;;;;;;;GAiBG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;GAUG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IAClC,SAAS,CAAC,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAK;IAC/C,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAY;IACjD,2FAA2F;IAC3F,SAAS,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAEhC;;;;;;OAMG;IACH,WAAW,IAAI,IAAI;IAMnB;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,IAAI;IAMtB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM7B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IASlC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC,EAAE,GAAG,IAAI;IAMnE;;;OAGG;IACH,YAAY,IAAI,eAAe;IAQ/B,oEAAoE;IACpE,OAAO,CAAC,KAAK;IAQb;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,aAAa;IAcrB;;;OAGG;IACH,UAAU,IAAI,aAAa;IAa3B;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAInC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAIlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,OAAO,CAAC,mBAAmB;IAwC3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,IAAI,IAAI,IAAI;IAOtB;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAKzD;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,aAAa;IAErD;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,IAAI,OAAO;CAGxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAiCrF"}