@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/rule-builder.js

@@ -0,0 +1,463 @@
+import { selectMatching, recordPredicate, matchingElements } from '@nielspeter/eess/internal';
+import { conditionContextFrom } from '@nielspeter/eess/internal';
+import { assertionAdviceOf, buildRuleDescription, describeRuleOf, globsOf, } from './rule-declaration.js';
+import { TerminalBuilder } from './terminal-builder.js';
+import { assertsCardinality, collectResult } from '@nielspeter/eess';
+/**
+ * Abstract base class for the predicate/condition 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.
+ *
+ * Extends `TerminalBuilder`, which owns everything that is not about the
+ * predicate/condition pipeline: `because`, `rule`, `excluding`, `violations`,
+ * `check`, `warn`, `asSeverity`, `severity`. Those used to exist twice, once
+ * here and once there, and the two copies had already drifted — this class's
+ * `excluding()` documented matching against element/file/message while the
+ * other still claimed element only, and the more accurate one was the one
+ * fewer builders inherited.
+ *
+ * The cost of the second root was not duplication, it was silent
+ * non-coverage: the materialized subject set (plan 0064) and the
+ * empty-selector guard (plan 0067) were added here and never reached the
+ * seven builders on the other branch. Plan 0069 needs `globs()` to reach all
+ * thirteen, so it goes on the root and the root is now singular.
+ */
+export class RuleBuilder extends TerminalBuilder {
+    project;
+    _predicates = [];
+    _conditions = [];
+    _phase = 'predicate';
+    // Plan 0070: state for the assertion-less remedies. `_phase` cannot carry
+    // either fact — `.should().that()` legally returns to the predicate phase,
+    // so `_phase === 'predicate'` does not mean `.should()` was never reached,
+    // and a predicate applied after `should()` leaves no other trace.
+    _reachedShould = false;
+    _misplaced = [];
+    /** `.expectEmpty()` — plan 0074. Asserts the selection is empty, and fails when it is not. */
+    constructor(project) {
+        super();
+        this.project = project;
+    }
+    // --- Chain methods (grammar transitions) ---
+    /**
+     * Begin the predicate phase. Returns a COPY, per bug 0016 — a held selection
+     * is never edited by narrowing it. Every ordinary chain is unaffected,
+     * because the copy is what the chain continues on; what changed is that
+     * `held.that()...` no longer reaches back into `held`.
+     * Purely a readability marker — `.that().haveNameMatching(...)` reads like English.
+     * Explicitly resets phase to 'predicate' — defensive against `.should().that()` misuse.
+     */
+    that() {
+        const next = this.copy();
+        next._phase = 'predicate';
+        return next;
+    }
+    /**
+     * 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';
+        fork._reachedShould = true;
+        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);
+    }
+    // --- Terminal methods ---
+    /**
+     * Return the predicate-filtered elements as a labelled `Selection<T>` for
+     * cross-validation (`crossProject()`). The set is exactly the elements this
+     * rule would evaluate — the same filtering `.check()` applies.
+     *
+     * **Restored in plan 0165 Phase 2.** `select()` is eess's, not upstream's: it
+     * is the side of the kernel's two-sided join, and `@nielspeter/eess-crossvalidate`
+     * is built entirely on it — four of its five source files failed `tsc` and 33 of
+     * its tests failed without it. The wholesale engine copy of plan 0165 dropped it
+     * along with the rest of eess's `RuleBuilder`.
+     *
+     * Stateless by construction, which is why it can live here while the kernel keeps
+     * its own copy: it reads `getElements()` and `_predicates` and returns a plain
+     * object. The duplication that matters — and that Phase 1 measured breaking — is
+     * module-level STATE, not a pure method.
+     *
+     * @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) {
+        // The kernel's — this was byte-identical, and the hierarchies differ, so a
+        // free function is the only way the two builders can share it.
+        return selectMatching(this.getElements(), this._predicates, opts);
+    }
+    /** This rule as declared — the input every description and advice reads. */
+    asDeclared() {
+        return {
+            predicates: this._predicates,
+            conditions: this._conditions,
+            misplaced: this._misplaced,
+            reachedShould: this._reachedShould,
+            metadata: this._metadata,
+            reason: this._reason,
+        };
+    }
+    /**
+     * Return a structured description of this rule without executing it.
+     * Used by the `explain` CLI subcommand.
+     */
+    describeRule() {
+        return describeRuleOf(this.asDeclared());
+    }
+    /**
+     * Return the subject set this rule would evaluate: the elements matched by
+     * the predicate chain (`.that()...`), before any condition runs. Executes the
+     * predicate filter and returns the materialized set.
+     *
+     * Distinct from the abstract `getElements()`, which is the *pre-filter*
+     * population. This is the materialization contract (F1, plan 0064) that
+     * composable primitives build on — `crossProject().side(selection, keyFn)`
+     * keys each subject, and `.expectNonEmpty()` (plan 0064+) asserts the set is
+     * non-empty. It does not evaluate conditions and never warns about their
+     * absence, so it is safe to call on a bare `.that()` selection.
+     *
+     * Note (ADR-007): the returned `T` is the builder's element type (e.g. a
+     * ts-morph `ClassDeclaration` for `classes()`), so this is an acknowledged
+     * raw-node seam for callers that derive keys from subjects.
+     */
+    subjects() {
+        return this.filterElements();
+    }
+    /**
+     * The selector and condition globs this rule declares.
+     *
+     * `position` is derived, not declared: a predicate registered while
+     * `_phase` is `'predicate'` is a selector, one registered after `.should()`
+     * is a condition. That is a structural fact about where the code is, which
+     * is why it is not on `DeclaredGlob` for an author to get wrong.
+     */
+    globs() {
+        return globsOf(this.asDeclared());
+    }
+    /**
+     * The project this rule was built against.
+     *
+     * Used by `within()` to create scoped builders, and by `doctor` to find the
+     * project to compare globs against — which must be the one the rules
+     * actually ran on, not one the CLI guessed at.
+     */
+    /**
+     * Plan 0074: is EVERY condition satisfied by an empty selection?
+     *
+     * `.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 one
+     * cardinality condition would silence the other. 0069's appendix names this
+     * as an implementation constraint; the first cut used `.some()`.
+     *
+     * An empty condition list is NOT exempt: `[].every()` is `true`, and a rule
+     * with no conditions is the assertion-less case that its own gate reports.
+     */
+    assertsCardinality() {
+        if (this._conditions.length === 0)
+            return false;
+        return this._conditions.every((condition) => assertsCardinality(condition));
+    }
+    /**
+     * The project this rule was built against.
+     *
+     * Public because the empty-project and dead-glob findings are constructed by
+     * `TerminalBuilder`, which has no project of its own to consult.
+     */
+    getProject() {
+        return this.project;
+    }
+    /**
+     * Whether this rule asserts anything about the elements it selected.
+     *
+     * `.that()...` with no `.should()` selects a set and then says nothing about
+     * it, so it can never fail — proposal 019. Exposed as a method because
+     * `_conditions` is protected and `doctor` must not duck-type a private name.
+     *
+     * **A misplaced predicate disqualifies the rule even when conditions exist**,
+     * which `_conditions.length > 0` alone did not. Measured on the shipped 0.23.0
+     * branch, and it is the worst shape of the seven rather than a corner:
+     *
+     *     functions(p).that().haveNameMatching(/^parse/).should().notExist().areAsync()
+     *       subjects 4 -> 0   violations 4 -> 0   diagnose() []   check() passes
+     *
+     * `areAsync()` after `.should()` lands in `addPredicate` and retroactively
+     * narrows the set every condition is evaluated over — here to nothing, so
+     * `notExist` holds vacuously. The rule reads as deliberate, its description
+     * reads as deliberate, and it certifies nothing. Every other assertion-less
+     * shape at least looks unfinished; this one does not, so the author has no
+     * reason to look. Under ADR-008 the finding is not optional: the remedy is
+     * one method call and nothing about it is a judgement call.
+     */
+    assertsSomething() {
+        return this._conditions.length > 0 && this._misplaced.length === 0;
+    }
+    /**
+     * Three assertion-less states, three remedies (plan 0070). Branching on
+     * `_reachedShould`/`_misplaced`, never `_phase` — `.should().that()` lands
+     * in the predicate phase having reached `.should()`, and would be told a
+     * verifiable falsehood by any phase-derived message.
+     */
+    assertionAdvice() {
+        return assertionAdviceOf(this.asDeclared());
+    }
+    /**
+     * The root's collection hook. `evaluate()` is this builder's pipeline —
+     * filter by predicates, run conditions, add the empty-selector finding —
+     * and the root's terminal methods do the rest.
+     */
+    collectViolations() {
+        // Plan 0098. The unit is the POST-predicate set — what the conditions
+        // actually receive — not `getElements()`. `filterElements()` is memoized per
+        // builder (`element-cache.ts`), so asking here and again inside `evaluate()`
+        // walks once.
+        return collectResult(this.evaluate(), { examined: this.examinedUnits() });
+    }
+    /**
+     * Units this rule examined — plan 0098: the POST-predicate subjects, which is
+     * exactly what `subjects()` returns and what the conditions receive.
+     *
+     * Public for the same structural reason as `assertsSomething()`: `diagnose()`
+     * reads it through a structural interface and a protected member cannot
+     * satisfy one. One definition, two readers — `collectViolations()` above and
+     * the preview — so the number the gate carries and the number the preview
+     * reports cannot drift apart.
+     */
+    examinedUnits() {
+        return this.filterElements().length;
+    }
+    // --- Protected: for subclasses ---
+    /**
+     * Register a predicate. Called by concrete builder methods like
+     * `.haveNameMatching()`, `.extend()`, etc.
+     */
+    addPredicate(predicate) {
+        const next = this.copy();
+        // The kernel's. The two copies differed only in comment wording and braces.
+        recordPredicate(predicate, next._predicates, next._misplaced, next._phase);
+        return next;
+    }
+    /**
+     * Register a DUAL-USE method's condition or predicate, according to phase.
+     *
+     * Sixteen builder methods across four builders wrote this dispatch out —
+     * `no-copy-paste` reported them as two clusters at 100%. The dispatch is the
+     * only thing they share; the pair handed to it is what each method IS.
+     *
+     * Both sides are constructed eagerly rather than passed as thunks. Every one
+     * of the sixteen pairs is pure object construction — checked, none of the
+     * modules they come from (`conditions/structural`, `conditions/class`,
+     * `conditions/dependency`, `predicates/identity`, `predicates/module`)
+     * throws — so building the unused half costs an object and changes nothing.
+     * Thunks would buy laziness nobody needs at the price of two closures per
+     * call, and would hide the pair behind a lambda in every reader's way.
+     *
+     * A dual-use method is NOT the same as a predicate-only one. `areExported()`
+     * written after `.should()` still filters and is reported by the assertion
+     * gate as a misplaced predicate; a dual-use method written there asserts.
+     * That difference is a property of the method, so it stays at the method.
+     */
+    dualUse(condition, predicate) {
+        return this._phase === 'condition' ? this.addCondition(condition) : this.addPredicate(predicate);
+    }
+    /**
+     * Register a condition. Called by concrete builder methods like
+     * `.notContain()`, `.notExist()`, etc.
+     */
+    addCondition(condition) {
+        const next = this.copy();
+        next._conditions.push(condition);
+        return next;
+    }
+    /**
+     * An independent copy, carrying **both** lists. See `TerminalBuilder.copy`.
+     *
+     * Nothing on this class clears the conditions any more (bug 0020): a rule
+     * that asserted something must never be turned into one that asserts nothing
+     * by a chain method, which is what `.should()` used to do via `fork()`.
+     * `.should().beExported().that().areAsync()` keeps `beExported`, and a second
+     * `.should()` accumulates exactly as `.andShould()` does.
+     */
+    copy() {
+        const clone = super.copy();
+        clone._predicates = [...this._predicates];
+        clone._conditions = [...this._conditions];
+        clone._misplaced = [...this._misplaced];
+        return clone;
+    }
+    /**
+     * A copy carrying everything, including the conditions, with `_reason`
+     * resolved from metadata. The only caller is `.should()`.
+     *
+     * **The name is historical.** It used to clear the conditions, which is what
+     * distinguished it from `copy()`, and that clearing was
+     * [bug 0156](../../../../work/bugs/fixed/0156-should-twice-silently-drops-the-first-assertion.md):
+     * a second `.should()` on a builder that already carried a condition discarded
+     * it, so `.should().notExist().should().beExported()` enforced only the second
+     * and lost four findings with no output. Measured. Removed in 0.23.0 —
+     * conditions accumulate, and a second `.should()` behaves as `.andShould()`.
+     *
+     * What is left is `copy()` plus the `_reason` resolution, so the method is now
+     * thin enough to inline. It stays because it is `protected` on an exported
+     * class: deleting it is a compile break for an external subclass that
+     * overrides or calls it, which is the same compatibility argument that keeps
+     * `globs()` concrete and `assertsSomething()` exempt-by-default. Do not read
+     * the name as a description of the behaviour.
+     */
+    fork() {
+        const fork = this.copy();
+        fork._reason = fork._metadata?.because ?? this._reason;
+        return fork;
+    }
+    // --- Private: execution engine ---
+    /**
+     * Materialize the subject set: all elements narrowed by the predicate chain
+     * (the post-`.that()` set), before any condition runs. Shared by the
+     * `RuleBuilder` execution pipeline (`evaluate`) and the public `subjects()`
+     * accessor so those two cannot diverge (F1). Note: a few builders keep their
+     * own separate materialization for other paths (e.g. `CallRuleBuilder`'s
+     * `within()` matcher) — those are not routed through here.
+     */
+    filterElements() {
+        // AND semantics — every predicate must match.
+        return matchingElements(this.getElements(), this._predicates);
+    }
+    /**
+     * Build the config-level meta-finding for an empty selector under
+     * `.expectNonEmpty()`. A typed literal (no `createViolation` — there is no
+     * Node), ADR-005-clean, flagged `bypassFilters` so diff/baseline keep it.
+     */
+    emptySelectionViolation() {
+        const description = buildRuleDescription(this.asDeclared()) || 'selector';
+        // The TEXT comes from the shared producer; the ATTRIBUTION stays here.
+        //
+        // Plan 0099 keeps this family's block because it is the better-attributed
+        // implementation — it names the chain and carries the author's `because`.
+        // What it must not keep is its own wording: two texts for one state is the
+        // plan-0070 drift shape, and its copy carried the three defects 0098's
+        // user-perspective review found.
+        //
+        // Fields are assigned LITERALLY rather than spread, and that is not style.
+        // The config-finding census scans for a `bypassFilters: true`
+        // PropertyAssignment and for a literal `suggestion`; a spread made this
+        // producer invisible to it, which silently dropped its census row — through
+        // the exact route the census docstring claims is impossible ("no spreads that
+        // introduce the flag"). Review measured that regression.
+        //
+        // `element` keeps the rule id: unlike the expiry finding, N rules that cannot
+        // enforce ARE one edit, so `dedupeConfigFindings` collapsing them is correct.
+        const shared = this.zeroSubjectsViolation(this.project);
+        return {
+            rule: description,
+            ruleId: this._metadata?.id,
+            element: this._metadata?.id ?? description,
+            file: '',
+            line: 0,
+            message: shared.message,
+            suggestion: shared.suggestion,
+            // The author's rationale, which the shared producer has no access to. Not
+            // their `suggestion`/`docs` (bug 0021): this finding says the selector
+            // matched nothing, and the author's remedy is for a violation of the rule.
+            because: this._reason,
+            bypassFilters: true,
+        };
+    }
+    /**
+     * Execute the full pipeline: filter elements with predicates,
+     * evaluate conditions, return violations.
+     */
+    evaluate() {
+        // Step 1+2: Get elements and narrow by predicates (see filterElements).
+        const filtered = this.filterElements();
+        // Step 3: the selection is empty — a FAULT by default since plan 0074.
+        //
+        // The inversion R3b exists for. A condition reports a violation when SOME
+        // subject fails; over an empty set that is vacuously false, so every rule
+        // passed and the suite counted it as coverage. `.expectNonEmpty()` was the
+        // opt-in, and terminal-builder.ts records why that was not enough: it is
+        // "the opt-in this whole plan exists because nobody uses".
+        //
+        // Read the exemptions in this order — most specific first.
+        if (filtered.length === 0) {
+            // The author said so, in the rule, where a reader sees it. Not a
+            // silencer: the non-empty branch below fails the day it matches.
+            if (this._expectEmpty)
+                return [];
+            // Every condition is satisfied BY emptiness — `.should().notExist()`, the
+            // pre-emptive guard. `.every()`, because `andShould()` ANDs.
+            if (this.assertsCardinality())
+                return [];
+            return [this.emptySelectionViolation()];
+        }
+        // NO expiry branch here. Plan 0099 moved it to the root
+        // (`TerminalBuilder.collectWithAssertionGuard`), because this family's copy
+        // and the root's would both fire and double-report one fault.
+        //
+        // The property it enforced is unchanged and is now enforced for EVERY family
+        // rather than this one: a false declaration fails, and — the part plan 0089's
+        // review measured — it does not swallow the violations underneath it. The
+        // root appends them, so a fanned-out preset id whose one non-empty instance
+        // used to replace a genuine `imports "lodash" which matches forbidden` with a
+        // config error now reports both.
+        // 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 conditionContextFrom({
+            metadata: this._metadata,
+            reason: this._reason,
+            rule: buildRuleDescription(this.asDeclared()),
+        });
+    }
+}
+//# sourceMappingURL=rule-builder.js.map

package/dist/core/rule-builder.js.map

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

package/dist/core/rule-declaration.d.ts

@@ -0,0 +1,32 @@
+import type { Condition, GlobNode, Predicate, RuleDescription } from '@nielspeter/eess';
+/**
+ * A rule as DECLARED — what was chained onto the builder, before anything runs.
+ *
+ * The description, the imperative and the assertion advice are all functions of
+ * this and nothing else. Keeping them as methods only meant the class carried
+ * them; they read no evaluation state and call nothing back.
+ */
+export interface DeclaredRule {
+    readonly predicates: readonly Predicate<unknown>[];
+    readonly conditions: readonly Condition<unknown>[];
+    readonly misplaced: readonly string[];
+    readonly reachedShould: boolean;
+    readonly metadata: {
+        id?: string;
+        imperative?: string;
+        suggestion?: string;
+        docs?: string;
+    } | undefined;
+    readonly reason: string | undefined;
+}
+/**
+ * Build the rule description from predicates and conditions.
+ */
+export declare function buildRuleDescription(declared: DeclaredRule): string;
+/** The value behind `RuleBuilder.globs()`. */
+export declare function globsOf(declared: DeclaredRule): readonly GlobNode[];
+/** The value behind `RuleBuilder.assertionAdvice()`. */
+export declare function assertionAdviceOf(declared: DeclaredRule): string;
+/** The value behind `RuleBuilder.describeRule()`. */
+export declare function describeRuleOf(declared: DeclaredRule): RuleDescription;
+//# sourceMappingURL=rule-declaration.d.ts.map

package/dist/core/rule-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-declaration.d.ts","sourceRoot":"","sources":["../../src/core/rule-declaration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAIvF;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,CAAA;IAClD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EACb;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACxE,SAAS,CAAA;IACb,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAkCD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAInE;AAwBD,8CAA8C;AAC9C,wBAAgB,OAAO,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,QAAQ,EAAE,CAKnE;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAchE;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,eAAe,CAOtE"}

package/dist/core/rule-declaration.js

@@ -0,0 +1,88 @@
+import { declaredGlobsOf } from '@nielspeter/eess/internal';
+import { ruleDescriptionOf, ruleDescriptionFrom } from '@nielspeter/eess/internal';
+/**
+ * Advice for predicates that landed after `.should()`.
+ *
+ * Extracted from {@link assertionAdvice} so that method reads as its three
+ * outcomes rather than as one of them. Two remedies live here, and the
+ * distinction is the point: with conditions present the rule is not
+ * "asserting nothing" — it asserts something over a set the misplaced
+ * predicate silently shrank, which is a different fault and a different fix
+ * (move it; do NOT add another condition). Telling that author to "add a
+ * condition" names a fix that leaves the rule exactly as broken (ADR-008
+ * rule 2).
+ */
+function misplacedPredicateAdvice(declared) {
+    const names = declared.misplaced.map((d) => `"${d}"`).join(', ');
+    const one = declared.misplaced.length === 1;
+    const verb = one ? 'is a predicate, which filters' : 'are predicates, which filter';
+    const it = one ? 'it' : 'them';
+    if (declared.conditions.length > 0) {
+        return (`this rule's ${names} ${verb} subjects rather than asserting anything about them, ` +
+            `and ${one ? 'it comes' : 'they come'} after .should() — so ${it} narrowed the ` +
+            "selection this rule's conditions are evaluated over, and if that narrowed it to " +
+            `nothing the conditions hold vacuously. Move ${it} before .should(), where the ` +
+            'filtering is explicit.');
+    }
+    return (`this rule asserts nothing: ${names} ${verb} subjects rather than asserting ` +
+        `anything about them. Move ${it} before .should(), then add a condition.`);
+}
+/**
+ * Build the rule description from predicates and conditions.
+ */
+export function buildRuleDescription(declared) {
+    // The kernel's. This package's copy differed only in taking a `DeclaredRule`
+    // rather than the two lists.
+    return ruleDescriptionOf(declared.predicates, declared.conditions);
+}
+/**
+ * Build an imperative "Do NOT … / MUST …" sentence for AI-agent system
+ * prompts (`explain --format agent`). Heuristic FALLBACK — a rule author's
+ * `.rule({ imperative })` overrides it.
+ */
+function buildImperative(declared) {
+    // The Do-NOT/MUST transform only reads the polarity of a single condition.
+    // For zero or multiple (`and`-joined) conditions, negating the joined string
+    // would mis-handle mixed polarity ("not X and not Y"), so fall back to the
+    // plain, always-correct rule description.
+    const [only] = declared.conditions;
+    if (declared.conditions.length !== 1 || only === undefined) {
+        return buildRuleDescription(declared) || 'Follow the architecture rule.';
+    }
+    const cond = only.description;
+    const isNegative = /^(not|no)\b/i.test(cond);
+    const body = cond.replace(/^(not|no)\s+/i, '');
+    const scope = declared.predicates.map((p) => p.description).join(' and ');
+    const scopeSuffix = scope ? ` (in code that ${scope})` : '';
+    return `${isNegative ? 'Do NOT' : 'MUST'} ${body}${scopeSuffix}`;
+}
+/** The value behind `RuleBuilder.globs()`. */
+export function globsOf(declared) {
+    // The kernel's, not a copy. This package carried a 94%-similar version whose
+    // one real difference — honouring `originLabel` — the kernel has now adopted,
+    // so there is nothing left here but the shape of the argument.
+    return declaredGlobsOf(declared.predicates, declared.conditions);
+}
+/** The value behind `RuleBuilder.assertionAdvice()`. */
+export function assertionAdviceOf(declared) {
+    if (!declared.reachedShould) {
+        return ('this rule never reached .should(), so it asserts nothing and can never fail. ' +
+            'Add .should() and a condition, or delete the rule.');
+    }
+    if (declared.misplaced.length > 0)
+        return misplacedPredicateAdvice(declared);
+    return ('this rule reached .should() but no condition follows, so it asserts nothing and can ' +
+        'never fail. Add a condition after .should() — or, if this rule is generated from ' +
+        'configuration, skip generating it when there is nothing to assert; if it comes from ' +
+        'a preset (ruleId "preset/..."), report it to the preset\'s author.');
+}
+/** The value behind `RuleBuilder.describeRule()`. */
+export function describeRuleOf(declared) {
+    return ruleDescriptionFrom({
+        metadata: declared.metadata,
+        reason: declared.reason,
+        rule: buildRuleDescription(declared),
+        imperativeFallback: buildImperative(declared),
+    });
+}
+//# sourceMappingURL=rule-declaration.js.map

package/dist/core/rule-declaration.js.map

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