@nielspeter/eess-ts 0.2.1 → 0.4.0

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

@@ -0,0 +1,282 @@
+import type { GlobNode } from '@nielspeter/eess';
+import type { ArchProject } from './project.js';
+import type { CollectResult } from './terminal-builder.js';
+import type { Predicate } from '@nielspeter/eess';
+import type { Condition, ConditionContext } from '@nielspeter/eess';
+import type { RuleDescription } from '@nielspeter/eess';
+import type { Selection, ElementInfo } from '@nielspeter/eess';
+import { TerminalBuilder } from './terminal-builder.js';
+/**
+ * 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 declare abstract class RuleBuilder<T> extends TerminalBuilder {
+    protected readonly project: ArchProject;
+    protected _predicates: Predicate<T>[];
+    protected _conditions: Condition<T>[];
+    protected _phase: 'predicate' | 'condition';
+    protected _reachedShould: boolean;
+    protected _misplaced: string[];
+    /** `.expectEmpty()` — plan 0074. Asserts the selection is empty, and fails when it is not. */
+    constructor(project: ArchProject);
+    /**
+     * 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(): this;
+    /**
+     * Add another predicate (AND). Returns `this` for chaining.
+     * `.that().extend('Base').and().resideInFolder('src/repos/**')` means both must match.
+     */
+    and(): 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(): this;
+    /**
+     * Add another condition that must ALSO pass (AND).
+     * `.should().notContain(call('x')).andShould().notContain(call('y'))` means both must hold.
+     */
+    andShould(): 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: Predicate<T> | Condition<T>): this;
+    /**
+     * 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: {
+        label: string;
+        identify: (element: T) => ElementInfo;
+    }): Selection<T>;
+    /** This rule as declared — the input every description and advice reads. */
+    private asDeclared;
+    /**
+     * Return a structured description of this rule without executing it.
+     * Used by the `explain` CLI subcommand.
+     */
+    describeRule(): RuleDescription;
+    /**
+     * 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(): readonly T[];
+    /**
+     * 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(): readonly GlobNode[];
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): ArchProject;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): string;
+    /**
+     * 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.
+     */
+    protected collectViolations(): CollectResult;
+    /**
+     * 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(): number;
+    /**
+     * Register a predicate. Called by concrete builder methods like
+     * `.haveNameMatching()`, `.extend()`, etc.
+     */
+    protected addPredicate(predicate: Predicate<T>): this;
+    /**
+     * Register a condition. Called by concrete builder methods like
+     * `.notContain()`, `.notExist()`, etc.
+     */
+    protected addCondition(condition: Condition<T>): this;
+    /**
+     * Subclasses implement this to return the elements to check.
+     * Called lazily during `.check()` / `.warn()`.
+     */
+    protected abstract getElements(): T[];
+    /**
+     * 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.
+     */
+    protected copy(): this;
+    /**
+     * 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/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.
+     */
+    protected fork(): this;
+    /**
+     * 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.
+     */
+    protected filterElements(): T[];
+    /**
+     * 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.
+     */
+    private emptySelectionViolation;
+    /**
+     * Execute the full pipeline: filter elements with predicates,
+     * evaluate conditions, return violations.
+     */
+    private evaluate;
+    /**
+     * 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.
+     */
+    protected buildConditionContext(): ConditionContext;
+}
+//# sourceMappingURL=rule-builder.d.ts.map

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

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