@nielspeter/eess-ts 0.2.1 → 0.4.0

package/dist/builders/correspondence-builder.js

@@ -0,0 +1,393 @@
+import { duplicateKeyFindings, materializeSides, resolveSides, emptinessFindings, matchFindings, unboundDeclarationFindings, } from './correspondence-findings.js';
+import { selectionMemo } from '@nielspeter/eess';
+import { RuleBuilder } from '../core/rule-builder.js';
+import { TerminalBuilder } from '../core/terminal-builder.js';
+import { setCorrespondence } from '@nielspeter/eess';
+function toKeyArray(key) {
+    return typeof key === 'string' ? [key] : key;
+}
+/** Model wrappers (ArchCall, ArchFunction, …) expose getNode(): Node. */
+function keyedFromSelection(source, keyFn) {
+    const map = new Map();
+    for (const subject of source.subjects()) {
+        for (const key of toKeyArray(keyFn(subject))) {
+            const bucket = map.get(key);
+            if (bucket)
+                bucket.push(subject);
+            else
+                map.set(key, [subject]);
+        }
+    }
+    return map;
+}
+function keyedFromKeys(keys) {
+    const map = new Map();
+    for (const key of keys) {
+        if (!map.has(key))
+            map.set(key, []);
+    }
+    return map;
+}
+/**
+ * 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 const sidesOf = selectionMemo();
+/**
+ * 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 class CrossProjectBuilder extends TerminalBuilder {
+    _sides = [];
+    _checkComplete = false;
+    _checkNoOrphans = false;
+    _expectEmptySides = new Set();
+    _distinctKeys = new Set();
+    // `_project` is accepted for API symmetry with the other entry points
+    // (modules/classes/…); crossProject's sides carry their own project.
+    constructor(_project) {
+        super();
+    }
+    /**
+     * Declare one side of the pairing.
+     *
+     * `source` is either a `RuleBuilder` selection — in which case `keyFn` is
+     * REQUIRED, because a subject has no inherent key and guessing one silently
+     * mis-joins the two sides — or a ready-made key source.
+     *
+     * Call it twice; a builder with fewer than two sides has compared nothing,
+     * which `examinedUnits()` reports as zero rather than passing vacuously.
+     */
+    side(name, source, keyFn) {
+        const next = this.copy();
+        if (source instanceof RuleBuilder) {
+            if (!keyFn) {
+                throw new TypeError(`crossProject side '${name}' from a selection requires a keyFn (subject -> key).`);
+            }
+            next._sides.push({ name, materialize: () => keyedFromSelection(source, keyFn) });
+        }
+        else {
+            next._sides.push({ name, materialize: () => keyedFromKeys(source) });
+        }
+        return next;
+    }
+    /**
+     * 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.
+     */
+    copy() {
+        const clone = super.copy();
+        clone._sides = [...this._sides];
+        clone._expectEmptySides = new Set(this._expectEmptySides);
+        clone._distinctKeys = new Set(this._distinctKeys);
+        return clone;
+    }
+    /** Optional readability markers — the assertion terminals may be called directly. */
+    should() {
+        return this;
+    }
+    /**
+     * Reads as English between two conditions (`.beComplete().andShould()…`) and
+     * changes nothing — the builder is already in its condition phase.
+     */
+    andShould() {
+        return this;
+    }
+    /** Every key of the first side must have a match in the second (A ⊆ B). */
+    beComplete() {
+        const next = this.copy();
+        next._checkComplete = true;
+        return next;
+    }
+    /** Every key of the second side must have a source in the first (B ⊆ A). */
+    haveNoOrphans() {
+        const next = this.copy();
+        next._checkNoOrphans = true;
+        return next;
+    }
+    /** Both directions — the two key sets must be identical. */
+    beBijective() {
+        const next = this.copy();
+        next._checkComplete = true;
+        next._checkNoOrphans = true;
+        return next;
+    }
+    /**
+     * 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) {
+        if (side === undefined) {
+            throw new TypeError('crossProject() declares emptiness per side: call .expectEmpty(sideName) for each side ' +
+                'you expect to be empty. A crossProject compares two named sides, so a whole-rule ' +
+                'declaration would suppress both and expire on neither.');
+        }
+        const next = this.copy();
+        next._expectEmptySides.add(side);
+        return next;
+    }
+    /**
+     * 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.
+     */
+    examinedUnitNoun() {
+        return 'keys';
+    }
+    /**
+     * 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() {
+        const [first, second] = this._sides;
+        // Zero is the honest answer for an under-declared pairing: nothing was
+        // compared, and ADR-010 wants that visible rather than defaulted away.
+        if (first === undefined || second === undefined)
+            return 0;
+        const [a, b] = materializeSides(this, first, second);
+        return a.size + b.size;
+    }
+    /**
+     * 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() {
+        return '.expectEmpty(sideName) for each side';
+    }
+    /**
+     * 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() {
+        return this._sides.length > 0 && this._sides.every((s) => this._expectEmptySides.has(s.name));
+    }
+    /** Fail if a side maps two distinct subjects to one key (over-normalization guard). */
+    distinctKeysOn(sideName) {
+        const next = this.copy();
+        next._distinctKeys.add(sideName);
+        return next;
+    }
+    /**
+     * 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() {
+        return this._sides.length === 2 && (this._checkComplete || this._checkNoOrphans);
+    }
+    /**
+     * 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() {
+        // Two distinct faults reach here, and naming the wrong one is the ADR-008
+        // rule 2 defect this plan is partly about: with fewer than two sides the
+        // fix is another `.side(...)`, not an assertion — adding `.beComplete()`
+        // would leave the rule exactly as broken (measured in review).
+        if (this._sides.length !== 2) {
+            return (`this crossProject has ${String(this._sides.length)} side(s) and needs exactly two, ` +
+                'so it compares nothing. Add the missing .side(name, ...) call.');
+        }
+        return 'this crossProject asserts nothing: call .beComplete(), .haveNoOrphans(), or .beBijective().';
+    }
+    /** Named by id or by its sides, not 'unnamed' (plan 0070 §4). */
+    describeRule() {
+        const sides = this._sides.map((side) => side.name).join(' <-> ');
+        return {
+            ...super.describeRule(),
+            rule: this._metadata?.id ?? (sides ? `crossProject [${sides}]` : 'crossProject'),
+        };
+    }
+    /** What this rule declared, as a value the findings functions can read. */
+    declared() {
+        return {
+            sides: this._sides,
+            distinctKeys: this._distinctKeys,
+            expectEmptySides: this._expectEmptySides,
+            checkComplete: this._checkComplete,
+            checkNoOrphans: this._checkNoOrphans,
+            metadata: this._metadata,
+            reason: this._reason,
+        };
+    }
+    /** Materialize both sides and pair their keys — the input every finding reads. */
+    pairingFor(sideA, sideB, meta) {
+        const [aKeyed, bKeyed] = materializeSides(this, sideA, sideB);
+        return {
+            sideA,
+            sideB,
+            aKeyed,
+            bKeyed,
+            result: setCorrespondence(aKeyed.keys(), bKeyed.keys()),
+            meta,
+            declared: this.declared(),
+        };
+    }
+    collectViolations() {
+        const { sideA, sideB, meta } = resolveSides(this._sides, this._reason, this._metadata);
+        const unbound = unboundDeclarationFindings(this.declared(), sideA, sideB);
+        // A configuration fault: the sides were never materialized, so nothing was
+        // examined. Plan 0098 — 0 here is the honest number, not a placeholder.
+        if (unbound.length > 0)
+            return { violations: unbound, examined: 0 };
+        const pairing = this.pairingFor(sideA, sideB, meta);
+        // Emptiness first: a side that resolved nothing makes every later question
+        // vacuous, so its finding replaces them rather than joining them.
+        const { emptyFindings, falseDeclarations } = emptinessFindings(pairing);
+        if (emptyFindings.length > 0) {
+            return {
+                violations: [...emptyFindings, ...falseDeclarations],
+                examined: this.examinedUnits(),
+            };
+        }
+        return {
+            violations: [
+                ...falseDeclarations,
+                ...matchFindings(pairing),
+                ...duplicateKeyFindings(pairing),
+            ],
+            examined: this.examinedUnits(),
+        };
+    }
+}
+/**
+ * Entry point: assert a correspondence between two independently-derived key
+ * sets. Call `.side(...)` twice, then an assertion terminal.
+ */
+export function crossProject(p) {
+    return new CrossProjectBuilder(p);
+}
+// --- keyFn vocabulary (the common cases; keyFn stays a raw escape hatch) ---
+/** Key a subject by its name (`getName()`); anonymous subjects fall back to `<anonymous>`. */
+export function byName() {
+    return (subject) => subject.getName() ?? '<anonymous>';
+}
+/**
+ * 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 function byArg(index) {
+    return (subject) => {
+        const arg = subject.getArguments()[index];
+        return arg ? unquote(arg.getText()) : '<no-arg>';
+    };
+}
+/** Strip a single pair of matching surrounding quotes/backticks, if present. */
+function unquote(text) {
+    const first = text[0];
+    if ((first === '"' || first === "'" || first === '`') &&
+        text.length >= 2 &&
+        text.endsWith(first)) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+/** Key a type-like subject by each of its property names (one subject → many keys). */
+export function byPropertyNames() {
+    return (subject) => subject.getProperties().map((property) => property.getName());
+}
+//# sourceMappingURL=correspondence-builder.js.map

package/dist/builders/correspondence-builder.js.map

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

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

@@ -0,0 +1,104 @@
+import type { ArchViolation } from '@nielspeter/eess';
+import type { Declared, Pairing, Side } from './correspondence-builder.js';
+export interface ViolationMeta {
+    readonly rule: string;
+    readonly because?: string;
+    readonly ruleId?: string;
+    readonly suggestion?: string;
+    readonly docs?: string;
+}
+/**
+ * Declarations — `.expectEmpty(name)` / `.withDistinctKeys(name)` — that name a
+ * side this crossProject does not have.
+ *
+ * A declaration that binds to no side is a configuration finding, not a no-op
+ * (plan 0097, correcting the same defect the shipped version had).
+ * `.expectEmpty('servcies')` was accepted silently and asserted nothing
+ * forever: the exact hazard this class's own docstring rejects the permanent
+ * form for ("one word, silent forever, TYPO OR NOT, and nothing revisits it"),
+ * inherited whole by the replacement.
+ *
+ * ADR-010 part 3 already ruled the structurally identical preset case — a
+ * declaration binding to no constructed rule is a FAILING finding, never a
+ * warning — so this follows settled precedent rather than deciding anew.
+ *
+ * Here rather than in the setter: `.expectEmpty(name)` may legally precede
+ * `.side(name, …)`, so the setter cannot know yet.
+ *
+ * A Set, not a concatenation: a name in BOTH sets produced two findings with
+ * identical element, message, file and line — the identity shape bugs 0064,
+ * 0065 and 0067 were filed for. And membership is tested against the side LIST
+ * rather than two name comparisons, so it cannot rot if arity ever changes.
+ */
+export declare function unboundDeclarationFindings(declared: Declared, sideA: Side, sideB: Side): ArchViolation[];
+/**
+ * Findings about each side being empty, and about a declaration that says so
+ * while the side is not.
+ */
+export declare function emptinessFindings(p: Pairing): {
+    emptyFindings: ArchViolation[];
+    falseDeclarations: ArchViolation[];
+};
+/**
+ * Findings from the pairing itself — keys on one side with no partner
+ * on the other, in whichever directions the rule asked about.
+ */
+export declare function matchFindings(p: Pairing): ArchViolation[];
+/**
+ * Findings for a side whose key function maps several distinct subjects onto
+ * one key — over-normalization can mask a real mismatch.
+ */
+export declare function duplicateKeyFindings(p: Pairing): ArchViolation[];
+/**
+ * Run the pairing and collect its findings, in four phases:
+ * unbound declarations, emptiness, the match itself, then duplicate keys.
+ *
+ * ## The arity throw is an invariant, not an error path
+ *
+ * Unreachable through `.check()` / `.warn()` / `.violations()` as of the
+ * bug-0025 fix: `assertsSomething()` is false for wrong arity, so the gate
+ * reports it as a configuration finding before this method is called. Kept as
+ * the invariant it always was — this method indexes `_sides[0]` and
+ * `_sides[1]` below, and a direct subclass caller deserves the named error
+ * rather than an undefined read. Do not treat it as the answer to "what
+ * happens with the wrong number of sides": the loud answer is the gate, and if
+ * this ever throws again through a terminal, the gate is gone.
+ *
+ * There is deliberately NO missing-assertion throw: the gate reports that as a
+ * configuration finding before this runs (bug 0019), which is why the gate sits
+ * ahead of this method — a `RangeError` from here escaped the CLI's
+ * `ArchRuleError`-only catch and dropped every remaining rule file. The
+ * sides-count check stays, because wrong arity is a different fault from a
+ * missing assertion and its remedy is another `.side(...)`.
+ */
+/**
+ * The two sides and the metadata every finding from them carries.
+ *
+ * Extracted so `collectViolations` reads as the decision sequence it is —
+ * unbound, then emptiness, then matching — rather than opening with a guard
+ * and a literal. The arity check lives here because it is the precondition
+ * for the metadata: the rule name is built from both side names.
+ */
+export declare function resolveSides(sides: readonly Side[], reason: string | undefined, metadata: {
+    id?: string;
+    suggestion?: string;
+    docs?: string;
+} | undefined): {
+    sideA: Side;
+    sideB: Side;
+    meta: ViolationMeta;
+};
+/**
+ * Both sides, materialized once — plan 0096, and the ONE method both readers
+ * call.
+ *
+ * CrossProject has no corpus of its own: its sides ARE its input, so the
+ * examined unit is their keys and the "selection" is the materialization
+ * itself. Sharing it matters more here than anywhere else, because
+ * `Side.materialize` is a bare closure over a user-supplied `keyFn` and a full
+ * rule selection — so a second derivation would re-run arbitrary user code,
+ * and `diagnose()` calling the accessor before `check()` would pay for the
+ * whole thing twice.
+ */
+export declare function materializeSides(owner: object, a: Side, b: Side): [Map<string, unknown[]>, Map<string, unknown[]>];
+//# sourceMappingURL=correspondence-findings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"correspondence-findings.d.ts","sourceRoot":"","sources":["../../src/builders/correspondence-findings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAA;AAyB1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAoJD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,GACV,aAAa,EAAE,CAOjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG;IAC7C,aAAa,EAAE,aAAa,EAAE,CAAA;IAC9B,iBAAiB,EAAE,aAAa,EAAE,CAAA;CACnC,CA2BA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,CAsBzD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,CA8BhE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACxE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAkBnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,CAAC,EAAE,IAAI,EACP,CAAC,EAAE,IAAI,GACN,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAclD"}