@nielspeter/eess-ts 0.2.1 → 0.4.0

package/dist/builders/correspondence-builder.d.ts

@@ -0,0 +1,287 @@
+/**
+ * **The exports here are `crossProject` / `CrossProjectBuilder`; the FILE is still
+ * `correspondence-builder.ts`, on purpose.**
+ *
+ * The symbols were renamed because `correspondence` collided: the kernel exports
+ * a different `correspondence({ left, right })` that `eess-md` re-exports and
+ * `docs/markdown.md` teaches, so one word named two incompatible APIs inside one
+ * family — and `family.rules.ts`'s allowlist, written to mean "eess-ts has no
+ * correspondence", silently permitted "eess-ts has a different one". Found by the
+ * product and architect reviews of PR #72.
+ *
+ * The filename did not follow because nine `path:line` pointers in CLOSED records
+ * (plans 0147 and 0150) cite it. Renaming the file would either break them or
+ * require rewriting finished history to describe a name that never existed at the
+ * time. The collision was in the published API, and that is what was fixed;
+ * tidying the filename is not worth falsifying a record.
+ */
+import type { ViolationMeta } from './correspondence-findings.js';
+import type { RuleDescription } from '@nielspeter/eess';
+import type { CollectResult } from '../core/terminal-builder.js';
+import type { ArchProject } from '../core/project.js';
+import { RuleBuilder } from '../core/rule-builder.js';
+import { TerminalBuilder } from '../core/terminal-builder.js';
+import type { CorrespondenceResult } from '@nielspeter/eess';
+/**
+ * Map a selection subject to one or more comparison keys.
+ *
+ * This is the acknowledged raw-node seam (ADR-007): `subject` is the builder's
+ * element type (a ts-morph node for `classes()`/`types()`, an `ArchCall` /
+ * `ArchFunction` wrapper otherwise). Prefer the `byName` / `byArg` /
+ * `byPropertyNames` vocabulary below for the common cases.
+ */
+export type KeyFn<T> = (subject: T) => string | readonly string[];
+/** A plain, already-derived key set. Normalize keys before passing them. */
+export type KeysSource = readonly string[] | ReadonlySet<string>;
+/**
+ * The materialized state of one crossProject check, threaded to the phase
+ * helpers as ONE object.
+ *
+ * Six values travel together — two sides, their keyed maps, the set result and
+ * the violation metadata — and passing them positionally would put every helper
+ * over the four-parameter cap while inviting the transposition that cap exists
+ * to prevent (`aKeyed`/`bKeyed` are the same type).
+ */
+export interface Pairing {
+    readonly sideA: Side;
+    readonly sideB: Side;
+    readonly aKeyed: Map<string, unknown[]>;
+    readonly bKeyed: Map<string, unknown[]>;
+    readonly result: CorrespondenceResult;
+    readonly meta: ViolationMeta;
+    /** What the rule DECLARED — the fields the findings functions read. */
+    readonly declared: Declared;
+}
+/** The assertions a crossProject rule made about its two sides. */
+export interface Declared {
+    readonly sides: readonly Side[];
+    readonly distinctKeys: ReadonlySet<string>;
+    readonly expectEmptySides: ReadonlySet<string>;
+    readonly checkComplete: boolean;
+    readonly checkNoOrphans: boolean;
+    readonly metadata: {
+        id?: string;
+        suggestion?: string;
+        docs?: string;
+    } | undefined;
+    readonly reason: string | undefined;
+}
+export interface Side {
+    readonly name: string;
+    /** Lazily build key → subjects (subjects is empty for a literal side). */
+    readonly materialize: () => Map<string, unknown[]>;
+}
+/**
+ * Assert a correspondence between two independently-derived key sets:
+ * "every X has a matching Y" (and/or the reverse). This is ADR-008 Rule 5 as a
+ * primitive — two derivations plus a disagreement test — so identity-not-count
+ * and non-vacuity are impossible to get wrong.
+ *
+ * The chain: `.side()` twice → `.beComplete()` / `.haveNoOrphans()` /
+ * `.beBijective()` → `.check()`.
+ *
+ * @example
+ * crossProject(p)
+ *   .side('routes', calls(p).that().onObject('app'), byArg(0))
+ *   .side('matrix', Object.keys(ROUTE_PERMISSIONS))
+ *   .should()
+ *   .beComplete()
+ *   .rule({ id: 'auth/route-matrix', suggestion: 'Add the route to ROUTE_PERMISSIONS.' })
+ *   .check()
+ */
+export declare const sidesOf: (owner: object, compute: () => Map<string, unknown[]>[]) => Map<string, unknown[]>[];
+/**
+ * The two-sided join: bind two artifacts by key and fail on the difference.
+ *
+ * Where every other builder selects subjects and asserts something about each,
+ * this one declares two (or more) named SIDES, derives a key set from each, and
+ * reports the set difference. It is the kernel's answer to "these two things must
+ * agree" — a route table against its permission map, a diagram against the code,
+ * a README table against the workspace.
+ *
+ * ```ts
+ * crossProject(project)
+ *   .side('routes', classes(project).that().haveDecorator('Controller'), routeKey)
+ *   .side('matrix', Object.keys(ROUTE_PERMISSIONS))
+ *   .should()
+ *   .beComplete()
+ *   .check()
+ * ```
+ *
+ * `beComplete()` reports keys the second side is missing, `haveNoOrphans()` the
+ * reverse, and `beBijective()` both. A builder with fewer than two sides has
+ * compared nothing, and `examinedUnits()` reports that as zero rather than
+ * letting it pass vacuously (ADR-010).
+ */
+export declare class CrossProjectBuilder extends TerminalBuilder {
+    private _sides;
+    private _checkComplete;
+    private _checkNoOrphans;
+    private _expectEmptySides;
+    private _distinctKeys;
+    constructor(_project: ArchProject);
+    /** Add a side from a selection, keyed by `keyFn`. */
+    side<T>(name: string, source: RuleBuilder<T>, keyFn: KeyFn<T>): this;
+    /** Add a side from an already-derived key set (pre-normalized). */
+    side(name: string, keys: KeysSource): this;
+    /**
+     * An independent copy, carrying the sides and both opt-out sets.
+     *
+     * `collectViolations` throws unless there are exactly two sides, so a leaked
+     * `_sides` push does not fail silently here — but a leaked declaration does:
+     * it is what stands between a vacuous side and a finding, and inheriting it
+     * turns a later rule's empty side green.
+     */
+    protected copy(): this;
+    /** Optional readability markers — the assertion terminals may be called directly. */
+    should(): this;
+    /**
+     * Reads as English between two conditions (`.beComplete().andShould()…`) and
+     * changes nothing — the builder is already in its condition phase.
+     */
+    andShould(): this;
+    /** Every key of the first side must have a match in the second (A ⊆ B). */
+    beComplete(): this;
+    /** Every key of the second side must have a source in the first (B ⊆ A). */
+    haveNoOrphans(): this;
+    /** Both directions — the two key sets must be identical. */
+    beBijective(): this;
+    /**
+     * Declare that a NAMED side is empty — plan 0097, replacing `allowEmpty()`.
+     *
+     * The difference is the whole point, and it is not a rename. `allowEmpty()`
+     * PERMITTED a side to be empty and never spoke again: a permanent, silent
+     * opt-out that stayed green the day the side filled up and the rule started
+     * certifying nothing about it. This ASSERTS the side is empty, and fails the
+     * day it stops being — an intent that expires and reports itself, which is
+     * the property ADR-010 part 3 requires of every declaration. Plan 0069's
+     * appendix rejected the permanent form for the rule family with receipts; a
+     * sibling family had it shipped and documented.
+     *
+     * **The zero-argument form throws here**, and that is the correction of a
+     * defect this method shipped with. The parameter has to be optional — a
+     * required one is not a valid override of `TerminalBuilder`'s zero-arg
+     * `expectEmpty()` — but the OVERRIDE VALIDITY argument justifies the
+     * signature, not the semantics. Inheriting the base meaning gave
+     * `crossProject().expectEmpty()` a whole-rule flag that suppressed the
+     * empty-side finding for BOTH sides and that the expiry branch never read:
+     * `allowEmpty` restored, permanent and silent, in fewer characters than
+     * before, on the release that deleted it. Measured green over two populated
+     * sides, forever.
+     *
+     * A crossProject compares two named sides, so "this rule is empty" has no
+     * meaning that is not per-side. Refusing at build time is the same answer
+     * this class already gives a contradiction, and it is loud where the
+     * inherited semantics were silent.
+     */
+    expectEmpty(side?: string): this;
+    /**
+     * Units this rule examined — plan 0096: the keys of both sides, summed.
+     *
+     * Zero means the comparison had nothing to compare, which for this family is
+     * two empty sides. One empty side is already its own finding and is not this
+     * question.
+     */
+    /**
+     * This family counts keys — the keys of both sides, summed.
+     *
+     * Plan 0099: `CollectResult.examined` is unit-typed per family (ADR-009 part
+     * 1), and the zero-examined message prints the noun. Inheriting the base
+     * `'subjects'` is a category error in a sentence whose whole job is naming what
+     * was and was not looked at.
+     */
+    protected examinedUnitNoun(): string;
+    /**
+     * How many units this rule actually examined — ADR-010's evidence that a pass
+     * was constructed rather than defaulted.
+     *
+     * Both materialized sides, summed — zero until two sides are declared, which is itself the evidence that nothing was compared.
+     */
+    examinedUnits(): number;
+    /**
+     * Declared when EVERY side is — plan 0097.
+     *
+     * The base implementation reads the whole-rule flag, which this class refuses
+     * to let anyone set. Without this override, 0098's floor would red a rule
+     * whose every side the author declared, with a finding telling them to
+     * declare. The per-side loop in `collectViolations` does not need this — its
+     * membership test covers each side directly — which is exactly why the
+     * previous private version was dead code and was removed. This one is for
+     * the root, which asks the question about the rule rather than about a side.
+     *
+     * **This was recorded as unobservable-until-0098, and that equivalence EXPIRED**
+     * the moment plan 0096 made `diagnose()` its first reader. Reverting this
+     * override to the base body — which for this class can never be true, since the
+     * zero-arg `expectEmpty()` throws — makes a rule whose every side is declared
+     * report `zero-subjects` again, telling the author to declare what they
+     * declared. A recorded equivalence is a claim with a lifetime, and this one's
+     * ended one commit after it was written; it is guarded now.
+     */
+    emptyDeclarationAdvice(): string;
+    /**
+     * Whether the author declared this rule's empty result intentional.
+     *
+     * Overrides `TerminalBuilder`'s `.expectEmpty()` reading, because this builder
+     * has more than one side and each can be declared empty independently.
+     */
+    declaresEmpty(): boolean;
+    /** Fail if a side maps two distinct subjects to one key (over-normalization guard). */
+    distinctKeysOn(sideName: string): this;
+    /**
+     * Wrong arity counts as asserting nothing, **whatever assertion was chosen**.
+     *
+     * `.beComplete()` on a one-sided crossProject cannot assert anything: there
+     * is no second side to compare against, so the call is a claim about a
+     * comparison that does not exist. Reading only the assertion flags let that
+     * pair through the gate and into `collectViolations()`, where the arity check
+     * throws a `RangeError` — and until bug 0025 that error escaped the CLI and
+     * dropped every remaining rule file's findings.
+     *
+     * So the same fault now reports the same way whether or not an assertion was
+     * chosen, and `assertionAdvice()` below already names the right remedy for it
+     * (another `.side(...)`, never `.beComplete()`). The arity throw stays as an
+     * invariant on `collectViolations()`, unreachable through the terminals.
+     */
+    assertsSomething(): boolean;
+    /**
+     * The remedy for this builder's assertion-less state, as one string.
+     *
+     * One channel, so `diagnose()`'s advice and the finding's own message cannot
+     * disagree. Overrides `TerminalBuilder`'s generic text with wording specific to
+     * what this builder is missing.
+     */
+    assertionAdvice(): string;
+    /** Named by id or by its sides, not 'unnamed' (plan 0070 §4). */
+    describeRule(): RuleDescription;
+    /** What this rule declared, as a value the findings functions can read. */
+    private declared;
+    /** Materialize both sides and pair their keys — the input every finding reads. */
+    private pairingFor;
+    protected collectViolations(): CollectResult;
+}
+/**
+ * Entry point: assert a correspondence between two independently-derived key
+ * sets. Call `.side(...)` twice, then an assertion terminal.
+ */
+export declare function crossProject(p: ArchProject): CrossProjectBuilder;
+/** Key a subject by its name (`getName()`); anonymous subjects fall back to `<anonymous>`. */
+export declare function byName<T extends {
+    getName(): string | undefined;
+}>(): KeyFn<T>;
+/**
+ * Key a call-like subject by its argument at `index`. String/template literal
+ * arguments are unquoted so keys match plain sides (e.g. `Object.keys(map)`) —
+ * `app.get("/x", …)` keys as `/x`, not `"/x"`. Non-literal args key by raw text.
+ */
+export declare function byArg<T extends {
+    getArguments(): {
+        getText(): string;
+    }[];
+}>(index: number): KeyFn<T>;
+/** Key a type-like subject by each of its property names (one subject → many keys). */
+export declare function byPropertyNames<T extends {
+    getProperties(): {
+        getName(): string;
+    }[];
+}>(): KeyFn<T>;
+//# sourceMappingURL=correspondence-builder.d.ts.map

package/dist/builders/correspondence-builder.d.ts.map

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