@nielspeter/eess 0.2.2 → 0.4.0

package/dist/rule-builder.js

@@ -1,5 +1,39 @@
-import { isSilent } from './silent-exclusion.js';
-import { executeCheck, executeWarn, applyFilters } from './execute-rule.js';
+import { assertionAdviceFor } from './assertion-advice.js';
+import { countDeclaredGlobs, stampGlobs } from './glob-site.js';
+import { TerminalBuilder, assertionLessViolation } from './terminal-builder.js';
+import { assertsCardinality as conditionAssertsCardinality } from './cardinality.js';
+/**
+ * A declared glob's own label in a dead-glob finding — the predicate/
+ * condition's description, disambiguated with the literal glob only when
+ * more than one site shares the description (a variadic predicate like
+ * `importFrom(...globs)` already spells every glob into its own
+ * description, so a substring test would collapse the one case this exists
+ * to separate — keyed on the site COUNT instead).
+ */
+function describeOrigin(description, glob, siteCount) {
+    return siteCount > 1 ? `${description} ("${glob.glob}")` : description;
+}
+/**
+ * The actual walk `RuleBuilder.globs()` delegates to — a free function
+ * rather than a method body, to keep the class itself under this repo's own
+ * 300-line class-length gate (`arch.internal.rules.ts`).
+ */
+function declaredGlobsOf(predicates, conditions) {
+    const trees = [];
+    for (const predicate of predicates) {
+        if (predicate.globs) {
+            const count = countDeclaredGlobs(predicate.globs);
+            trees.push(stampGlobs(predicate.globs, 'selector', (g) => describeOrigin(predicate.description, g, count)));
+        }
+    }
+    for (const condition of conditions) {
+        if (condition.globs) {
+            const count = countDeclaredGlobs(condition.globs);
+            trees.push(stampGlobs(condition.globs, 'condition', (g) => describeOrigin(condition.description, g, count)));
+        }
+    }
+    return trees;
+}
 /**
  * Abstract base class for all rule builders.
  *
@@ -9,29 +43,46 @@ import { executeCheck, executeWarn, applyFilters } from './execute-rule.js';
  * 3. Add condition methods that call `addCondition()`
  *
  * The builder accumulates predicates and conditions. Nothing executes
- * until a terminal method (`.check()`, `.warn()`, `.severity()`) is called.
+ * until a terminal method (`.check()`, `.warn()`, `.severity()`) is called —
+ * inherited from {@link TerminalBuilder} (plan 0088 Phase 4), which also
+ * supplies `because`/`rule`/`excluding`/`violations`/`expectEmpty`/
+ * `expectNonEmpty` and the ADR-010 evidence gate. `RuleBuilder` keeps its own
+ * `<T, P>` two-param generic — `P` is the dialect's project type, kept
+ * separate from `TerminalBuilder` (which has no project concept, since
+ * `correspondence()`, `SmellBuilder`, and the graphql builders don't share a
+ * uniform notion of "one project") — every builder across all five dialects
+ * depends on this exact two-param signature, so it is not replaced by the
+ * fold, only extended.
  */
-export class RuleBuilder {
+export class RuleBuilder extends TerminalBuilder {
     project;
     _predicates = [];
     _conditions = [];
-    _reason;
-    _metadata;
-    _exclusions = [];
-    _silentIndices = new Set();
     _phase = 'predicate';
+    /** Whether `.should()` was ever reached — bug 0155 state 3/4 vs state 1. */
+    _reachedShould = false;
+    /**
+     * Descriptions of predicate-only methods used AFTER `.should()` — bug 0155
+     * state 2. A dual-use method dispatches to a condition in that phase and
+     * never lands here, so anything recorded is genuinely a filter written where
+     * an assertion was meant.
+     */
+    _misplaced = [];
     constructor(project) {
+        super();
         this.project = project;
     }
     // --- Chain methods (grammar transitions) ---
     /**
-     * Begin the predicate phase. Returns `this` for chaining.
+     * Begin the predicate phase. Returns a COPY — a held selection is never
+     * edited by narrowing it (see `TerminalBuilder.copy()`).
      * 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;
+        const next = this.copy();
+        next._phase = 'predicate';
+        return next;
     }
     /**
      * Add another predicate (AND). Returns `this` for chaining.
@@ -48,6 +99,7 @@ export class RuleBuilder {
     should() {
         const fork = this.fork();
         fork._phase = 'condition';
+        fork._reachedShould = true;
         return fork;
     }
     /**
@@ -72,70 +124,11 @@ export class RuleBuilder {
         }
         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;
-    }
+    // `because`, `rule`, `excluding`, `violations`, `check`, `warn`, `severity`,
+    // `expectEmpty`, `expectNonEmpty` are inherited from `TerminalBuilder`
+    // (plan 0088 Phase 4) — this class used to duplicate all of them, and the
+    // two copies had already drifted (the exact hazard `ts-archunit`'s own
+    // `RuleBuilder`/`TerminalBuilder` merge commit documents).
     // --- Terminal methods ---
     /**
      * Return the predicate-filtered elements as a labelled `Selection<T>` for
@@ -164,96 +157,133 @@ export class RuleBuilder {
         };
     }
     /**
-     * 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.
+     * ADR-010: is this rule's assertion satisfied by an empty selection, as a
+     * property of what its conditions assert (`.notExist()`) rather than a
+     * caller's `.expectEmpty()` declaration?
+     *
+     * `.every()`, not `.some()` — `.andShould()` ANDs, so a rule reading
+     * `.should().notExist().andShould().beExported()` still asserts something
+     * about subjects that exist, and exempting it on the strength of the one
+     * cardinality condition would silence the other. An empty condition list is
+     * NOT exempt: `[].every()` is vacuously `true`, and a rule with zero
+     * conditions is the assertion-less case `collectViolations()` now reports as
+     * a configuration finding (bug 0155; it used to be an unreachable stderr
+     * warning, which this comment named until that fix landed) — this override
+     * must not paper over it by also declaring it cardinality-satisfied.
      *
-     * @param options - Optional baseline and diff filtering
+     * **Load-bearing:** for a DEAD selector this early return is the only thing
+     * between an assertion-less rule and a silent pass (the gate runs after the
+     * zero-examined branch). Pinned in `assertion-less-rules.test.ts`.
      */
-    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.
+     * Does this rule assert anything at all? — bug 0155.
      *
-     * @param options - Optional baseline and diff filtering
+     * Conditions alone are not enough: a predicate-only method written *after*
+     * `.should()` silently shrank the set the conditions run over, possibly to
+     * empty, in which case they hold vacuously. That rule asserts nothing
+     * meaningful even though `_conditions` is non-empty.
      */
-    warn(options) {
-        const violations = this.evaluate();
-        executeWarn(violations, {
-            reason: this._reason,
-            metadata: this._metadata,
-            exclusions: this._exclusions,
-            silentIndices: this._silentIndices,
-        }, options);
+    assertsSomething() {
+        return this._conditions.length > 0 && this._misplaced.length === 0;
+    }
+    assertionAdvice() {
+        return assertionAdviceFor({
+            reachedShould: this._reachedShould,
+            misplaced: this._misplaced,
+            conditionCount: this._conditions.length,
+        });
+    }
+    assertsCardinality() {
+        if (this._conditions.length === 0)
+            return false;
+        return this._conditions.every((condition) => conditionAssertsCardinality(condition));
     }
     /**
-     * Execute the rule with the given severity.
-     * `.severity('error')` is equivalent to `.check()`.
-     * `.severity('warn')` is equivalent to `.warn()`.
+     * ADR-010 part 3: did this rule's own underlying source (the project, a
+     * diagram, an SDL string — whatever `P` loads) produce nothing at all,
+     * before `getElements()`'s own domain-specific extraction or any
+     * predicate ran? Default `false` — the kernel has no way to know, since
+     * `P` is opaque here. A dialect's concrete builder, which knows `P`'s real
+     * shape (e.g. `ArchProject`), overrides this to check its own project's
+     * file count directly — never `getElements().length`, which conflates "the
+     * source is empty" with "this domain legitimately has nothing in a
+     * healthy project" (e.g. zero JSX elements in a backend-only codebase).
      */
-    severity(level) {
-        if (level === 'error') {
-            this.check();
-        }
-        else {
-            this.warn();
-        }
+    sourceEmpty() {
+        return false;
+    }
+    /** Declared globs, position derived from `_phase`. Pure — no `P` needed. */
+    globs() {
+        return declaredGlobsOf(this._predicates, this._conditions);
+    }
+    /** This rule's own project, for `diagnose()`/`doctor` outside `.check()`. */
+    getProject() {
+        return this.project;
+    }
+    /** A `globs()` tree diagnosably dead, when zero examined — same shape as `sourceEmpty()`. */
+    deadGlobDiagnosis() {
+        return undefined;
     }
     // --- Protected: for subclasses ---
     /**
      * Register a predicate. Called by concrete builder methods like
-     * `.haveNameMatching()`, `.extend()`, etc.
+     * `.haveNameMatching()`, `.extend()`, etc. Returns a COPY — see `copy()`.
      */
     addPredicate(predicate) {
-        this._predicates.push(predicate);
-        return this;
+        const next = this.copy();
+        next._predicates.push(predicate);
+        // Bug 0155 state 2: a predicate-only method used after `.should()`. Dual-use
+        // methods dispatch to conditions in that phase and never reach here, so this
+        // is a filter written where an assertion was meant — the one state whose fix
+        // is "move it before .should()", not "add a condition".
+        if (next._phase === 'condition')
+            next._misplaced.push(predicate.description);
+        return next;
     }
     /**
      * Register a condition. Called by concrete builder methods like
-     * `.notContain()`, `.notExist()`, etc.
+     * `.notContain()`, `.notExist()`, etc. Returns a COPY — see `copy()`.
      */
     addCondition(condition) {
-        this._conditions.push(condition);
-        return this;
+        const next = this.copy();
+        next._conditions.push(condition);
+        return next;
     }
     /**
-     * Create a fork of this builder with the same predicates but empty conditions.
-     * Used by `.should()` to support named selections without mutation.
+     * An independent copy, carrying **both** predicates and conditions.
+     * Extends `TerminalBuilder.copy()` with the fields this class adds.
      *
-     * Subclasses with additional constructor args MUST override this method.
+     * Subclasses with additional mutable-reference fields of their own (arrays,
+     * sets, maps a chain method pushes onto) MUST override this and call
+     * `super.copy()` first, the same reason `TerminalBuilder.copy()`'s own
+     * docstring gives — `Object.assign` shallow-copies a field, it does not
+     * give it independent identity.
+     */
+    copy() {
+        const clone = super.copy();
+        clone._predicates = [...this._predicates];
+        clone._conditions = [...this._conditions];
+        clone._misplaced = [...this._misplaced];
+        return clone;
+    }
+    /**
+     * A fork of this builder, carrying BOTH lists. Used by `.should()` to support
+     * named selections without mutation.
+     *
+     * **Nothing here clears the conditions** (bug 0156). It used to, and a second
+     * `.should()` therefore silently discarded the first assertion — a rule that
+     * asserted something turned into one that asserted less, by a chain method.
+     * `.should().X().should().Y()` now accumulates exactly as `.andShould()` does.
+     *
+     * Ported from `packages/ts/src/core/rule-builder.ts`, where the engine copy
+     * landed the fix and left the kernel behind. Found by the architect review of
+     * PR #72: `eess-md`, `eess-mermaid` and `eess-gherkin` all extend THIS class,
+     * so they carried the defect — and `check:corpus`, `check:ledger` and
+     * `check:diagram` are md/mermaid gates, meaning this repo's own corpus
+     * enforcement ran on the broken copy.
      */
     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;
+        const fork = this.copy();
         fork._reason = fork._metadata?.because ?? this._reason;
         return fork;
     }
@@ -272,28 +302,42 @@ export class RuleBuilder {
         return parts.join(' ');
     }
     /**
-     * Execute the full pipeline: filter elements with predicates,
-     * evaluate conditions, return violations.
+     * Execute the full pipeline: filter elements with predicates, evaluate
+     * conditions, return violations plus the ADR-010 evidence — the
+     * post-predicate subject count, whatever it is. `TerminalBuilder.check()` /
+     * `.warn()` / `.violations()` decide what a zero count means (a
+     * configuration finding, unless `.expectEmpty()` was declared); this method
+     * only reports the count, never interprets it.
+     *
+     * `sourceEmpty` (ADR-010 part 3) is deliberately not `allElements.length
+     * === 0` — a domain's own `getElements()` legitimately returning nothing in
+     * a healthy, fully-loaded project (e.g. zero JSX elements in a
+     * backend-only codebase) is not brokenness, and conflating the two broke
+     * `.notExist()`'s cardinality exemption for exactly that case. Subclasses
+     * that can answer "did my underlying source load anything at all" override
+     * `sourceEmpty()`; the default assumes it did.
      */
-    evaluate() {
-        // Step 1: Get all elements from the concrete builder
+    collectViolations() {
         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
+        const examined = filtered.length;
         if (filtered.length === 0) {
-            return [];
+            const sourceEmpty = this.sourceEmpty();
+            // Skip the diagnosis (a real filesystem walk, in a dialect's
+            // override) when the project itself is already known empty — nothing
+            // useful to say about one glob's fate against zero loaded files, and
+            // `sourceEmpty` outranks it in `evidencedViolations()` regardless.
+            const deadGlob = sourceEmpty ? undefined : this.deadGlobDiagnosis();
+            return { violations: [], examined, sourceEmpty, deadGlob };
         }
-        // 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') {
+        // Bug 0155 — gate-first, before the conditions run. See
+        // `assertionLessViolation` for why this is a finding and not a warning,
+        // and why there is no `_phase` term.
+        // `_expectEmpty === undefined`: a declared emptiness expectation is an
+        // assertion too — see `assertionLessViolation`.
+        if (!this.assertsSomething() && this._expectEmpty === undefined) {
             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 [];
+            return { violations: [assertionLessViolation(ruleId, this.assertionAdvice())], examined };
         }
         // Step 4: Build context for conditions
         const context = this.buildConditionContext();
@@ -302,7 +346,7 @@ export class RuleBuilder {
         for (const condition of this._conditions) {
             violations.push(...condition.evaluate(filtered, context));
         }
-        return violations;
+        return { violations, examined };
     }
     /**
      * Build the `ConditionContext` passed to each condition.

package/dist/rule-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-builder.js","sourceRoot":"","sources":["../src/rule-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rule-builder.js","sourceRoot":"","sources":["../src/rule-builder.ts"],"names":[],"mappings":"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"}

package/dist/rule-description.d.ts

@@ -8,7 +8,39 @@ export interface RuleDescription {
     because?: string;
     suggestion?: string;
     docs?: string;
-    /** One-line imperative for AI-agent prompts (see {@link RuleMetadata.imperative}). */
+    /** Imperative "Do NOT … / MUST …" sentence for agent system prompts. */
     imperative?: string;
 }
+/**
+ * A rule that can describe itself.
+ *
+ * `RuleBuilderLike` declares only `violations()` — deliberately, so a caller can
+ * pass a plain object — while every builder in `src/` implements `describeRule()`.
+ * So reading a rule's id or remedy needs a narrowing, and that narrowing existed
+ * in **three** places with two different implementations: `cli/commands/explain.ts`
+ * and two test files.
+ *
+ * One owner, because a duplicated predicate is not a style problem here:
+ * [ts-archunit bug 0044](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0044-an-inline-exclusion-comment-has-no-feedback-channel.md)
+ * was a measurement error caused by exactly that, and the fix was to delete the
+ * duplicate rather than to test both copies.
+ *
+ * `DiagnosableRule` and `orphanExclusions` are NOT copies of this: they declare
+ * `describeRule?` as an optional structural member of their own input type, which
+ * is a different mechanism and correct where it is used.
+ */
+export interface Describable {
+    describeRule: () => RuleDescription;
+}
+/**
+ * Does this value describe itself?
+ *
+ * Cast-free, and that is the point: the version in `explain.ts` read
+ * `(value as Record<string, unknown>)['describeRule']`, an ADR-005 breach in
+ * shipped source with no `eslint-disable` and no interop boundary to justify it.
+ * It was also unnecessary — once `value` is narrowed to `object`, `'describeRule'
+ * in value` narrows enough for the property access to compile, which is what the
+ * two test copies already did.
+ */
+export declare function isDescribable(value: unknown): value is Describable;
 //# sourceMappingURL=rule-description.d.ts.map

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

@@ -1 +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;IACb,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"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;IACb,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,eAAe,CAAA;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAIlE"}

package/dist/rule-description.js

@@ -1,2 +1,18 @@
-export {};
+/**
+ * Does this value describe itself?
+ *
+ * Cast-free, and that is the point: the version in `explain.ts` read
+ * `(value as Record<string, unknown>)['describeRule']`, an ADR-005 breach in
+ * shipped source with no `eslint-disable` and no interop boundary to justify it.
+ * It was also unnecessary — once `value` is narrowed to `object`, `'describeRule'
+ * in value` narrows enough for the property access to compile, which is what the
+ * two test copies already did.
+ */
+export function isDescribable(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('describeRule' in value))
+        return false;
+    return typeof value.describeRule === 'function';
+}
 //# sourceMappingURL=rule-description.js.map

package/dist/rule-description.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-description.js","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":""}
+{"version":3,"file":"rule-description.js","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC7D,IAAI,CAAC,CAAC,cAAc,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC5C,OAAO,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU,CAAA;AACjD,CAAC"}

package/dist/rule-metadata.d.ts

@@ -14,10 +14,27 @@ export interface RuleMetadata {
     /** Link to documentation — ADR, wiki, style guide */
     docs?: string;
     /**
-     * One-line imperative statement of the rule for an AI-agent system prompt,
-     * e.g. `'Do NOT call eval()'`. Surfaced by `explain --format agent`; falls
-     * back to the rule description when unset.
+     * Imperative one-liner for AI-agent system prompts, e.g.
+     * "Do NOT throw new Error() in repositories". Surfaced by
+     * `explain --format agent`. When unset, a heuristic is derived from the
+     * rule's predicate/condition description.
      */
     imperative?: string;
+    /**
+     * How the AUTHOR of this rule spells "I declare this empty" — plan 0099.
+     *
+     * Set by whoever constructs the rule, because only they know. A preset sets
+     * `expectEmpty: ['<id>']` because that is what its user can type; a builder
+     * author leaves it unset and gets `.expectEmpty()`.
+     *
+     * Core used to derive this from the rule id starting with `preset/`, which it
+     * cannot verify: that is false for a hand-written `.rule({ id: 'preset/...' })`,
+     * for a third-party preset that never extended `PresetBaseOptions`, and for a
+     * preset that forwards `overrides` but not `expectEmpty`. A prefix is a naming
+     * convention, not a capability, and the remedy has to name a call the reader
+     * can actually make ([ADR-009](../../../adr/009-agent-first-failure-surfaces.md)
+     * rule 2).
+     */
+    declarationSpelling?: string;
 }
 //# sourceMappingURL=rule-metadata.d.ts.map

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

@@ -1 +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;IAEb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"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;IAEb;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B"}