@nielspeter/eess-ts 0.2.0 → 0.4.0

package/dist/builders/correspondence-findings.js

@@ -0,0 +1,301 @@
+import { Node } from 'ts-morph';
+import { getElementName, getElementFile, getElementLine } from '../core/violation.js';
+import { sidesOf } from './correspondence-builder.js';
+function isNodeBearer(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'getNode' in value &&
+        typeof value.getNode === 'function');
+}
+/** Resolve a subject to a ts-morph node for file:line, or undefined if it carries none. */
+function toNode(subject) {
+    if (Node.isNode(subject))
+        return subject;
+    if (isNodeBearer(subject)) {
+        const node = subject.getNode();
+        if (Node.isNode(node))
+            return node;
+    }
+    return undefined;
+}
+function keyViolations(keyed, key, message, meta) {
+    const subjects = keyed.get(key) ?? [];
+    if (subjects.length === 0) {
+        // Plain-key side — no source location available.
+        return [baseViolation({ element: key, file: '', line: 0 }, message, meta)];
+    }
+    return subjects.map((subject) => {
+        const node = toNode(subject);
+        if (node) {
+            return baseViolation({
+                element: getElementName(node),
+                file: getElementFile(node),
+                line: getElementLine(node),
+            }, message, meta);
+        }
+        return baseViolation({ element: key, file: '', line: 0 }, message, meta);
+    });
+}
+/**
+ * A declaration names a side this rule does not have — plan 0097.
+ *
+ * Covers `.expectEmpty(name)` and `.distinctKeysOn(name)` alike, because both
+ * are membership tests against side names and both were silent on a typo. The
+ * remedy is mechanical and names the sides that DO exist, so the reader does
+ * not have to go and look.
+ */
+function unboundSideViolation(name, actual, metadata, reason) {
+    const known = actual.map((s) => `'${s}'`).join(' and ');
+    return {
+        ...baseViolation({ element: name, file: '', line: 0 }, `this rule declares something about a side named '${name}', but its sides are ${known} — ` +
+            `so the declaration binds to nothing and asserts nothing.`, {
+            rule: `crossProject [${actual.join(' <-> ')}]`,
+            because: reason,
+            ruleId: metadata?.id,
+        }),
+        suggestion: `Correct the side name to one of ${known}, or remove the declaration.`,
+        docs: undefined,
+        bypassFilters: true,
+    };
+}
+/**
+ * The declared side filled up — plan 0097.
+ *
+ * This finding is why `.expectEmpty(side)` replaced `allowEmpty(side)`: the
+ * permission had no failing state, so a side that gained keys silently kept a
+ * rule green that was certifying nothing about them. An assertion that expires
+ * reports itself; a permission never does.
+ *
+ * Its remedy is mechanical and is the one ADR-009 rule 2 asks be verified:
+ * remove the declaration, and the finding clears.
+ */
+function unexpectedlyNonEmptyViolation(sideName, meta) {
+    return {
+        ...baseViolation({ element: sideName, file: '', line: 0 }, `crossProject side '${sideName}' was declared empty with .expectEmpty('${sideName}'), ` +
+            `and now matches subjects — so the declaration no longer describes this rule.`, meta),
+        suggestion: `Remove .expectEmpty('${sideName}') so the side is compared like any other, or narrow ` +
+            `the '${sideName}' selector if it was meant to stay empty.`,
+        docs: undefined,
+        bypassFilters: true,
+    };
+}
+function emptyViolation(sideName, meta) {
+    return {
+        ...baseViolation({ element: sideName, file: '', line: 0 }, `crossProject side '${sideName}' matched 0 subjects — a pairing over an ` +
+            `empty side certifies nothing. Fix the selector, or call .expectEmpty('${sideName}') ` +
+            `if an empty side is valid here.`, meta),
+        // Its own remedy, overriding what `baseViolation` copied from the rule's
+        // metadata (bug 0021). `baseViolation` is shared with real violations, where
+        // inheriting the author's `suggestion` is correct — so the override has to be
+        // here, and the guard in `execute-rule.ts` cannot reach it.
+        suggestion: `Fix the '${sideName}' selector so it matches at least one subject, or call ` +
+            `.expectEmpty('${sideName}') if an empty side is the point — that asserts it, and fails the day the side fills up.`,
+        docs: undefined,
+        // Config-level meta-finding: no source file to attribute to, so it must
+        // survive diff-aware/baseline or the guard re-greens under standard CI.
+        bypassFilters: true,
+    };
+}
+/**
+ * The common shape of every crossProject finding.
+ *
+ * `element`/`file`/`line` travel together as one `at` — they are a location,
+ * and passing three positional strings-and-a-number invited exactly the
+ * transposition the parameter cap exists to prevent.
+ */
+function baseViolation(at, message, meta) {
+    const { element, file, line } = at;
+    return {
+        rule: meta.rule,
+        ruleId: meta.ruleId,
+        element,
+        file,
+        line,
+        message,
+        because: meta.because,
+        suggestion: meta.suggestion,
+        docs: meta.docs,
+    };
+}
+/**
+ * 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 function unboundDeclarationFindings(declared, sideA, sideB) {
+    const declaredNames = new Set([...declared.expectEmptySides, ...declared.distinctKeys]);
+    return [...declaredNames]
+        .filter((n) => !declared.sides.some((side) => side.name === n))
+        .map((name) => unboundSideViolation(name, [sideA.name, sideB.name], declared.metadata, declared.reason));
+}
+/**
+ * Findings about each side being empty, and about a declaration that says so
+ * while the side is not.
+ */
+export function emptinessFindings(p) {
+    const { sideA, sideB, result, meta, declared } = p;
+    const emptyFindings = [];
+    const falseDeclarations = [];
+    for (const [side, isEmpty] of [
+        [sideA, result.aEmpty],
+        [sideB, result.bEmpty],
+    ]) {
+        // Per-side only. A `declaresEmpty()` helper stood here with an
+        // `_expectEmpty || every(side => declared)` body; the `every` half was
+        // unreachable — if every side is in the set then `has(side.name)` is
+        // already true for the side under test — and three reviewers deleted it
+        // against the full suite with nothing failing. Its stated rationale
+        // ("without the OR a user who declared both sides still redded") was a
+        // property the code never had.
+        const sideDeclared = declared.expectEmptySides.has(side.name);
+        if (isEmpty && !sideDeclared) {
+            emptyFindings.push(emptyViolation(side.name, meta));
+        }
+        // The expiry half, and the reason this is an assertion rather than a
+        // permission: a declared-empty side that filled up is the intent
+        // reporting itself, where `allowEmpty()` stayed silent forever.
+        if (!isEmpty && declared.expectEmptySides.has(side.name)) {
+            falseDeclarations.push(unexpectedlyNonEmptyViolation(side.name, meta));
+        }
+    }
+    return { emptyFindings, falseDeclarations };
+}
+/**
+ * Findings from the pairing itself — keys on one side with no partner
+ * on the other, in whichever directions the rule asked about.
+ */
+export function matchFindings(p) {
+    const { sideA, sideB, aKeyed, bKeyed, result, meta, declared } = p;
+    const violations = [];
+    if (declared.checkComplete) {
+        for (const key of result.missing) {
+            violations.push(...keyViolations(aKeyed, key, `${sideA.name} "${key}" has no matching ${sideB.name}`, meta));
+        }
+    }
+    if (declared.checkNoOrphans) {
+        for (const key of result.orphans) {
+            violations.push(...keyViolations(bKeyed, key, `${sideB.name} "${key}" has no matching ${sideA.name}`, meta));
+        }
+    }
+    // Over-normalization guard (opt-in): one key from many subjects can mask a
+    // real "two subjects, one counterpart" mismatch.
+    return violations;
+}
+/**
+ * Findings for a side whose key function maps several distinct subjects onto
+ * one key — over-normalization can mask a real mismatch.
+ */
+export function duplicateKeyFindings(p) {
+    const { sideA, sideB, aKeyed, bKeyed, meta, declared } = p;
+    const violations = [];
+    for (const side of [sideA, sideB]) {
+        if (!declared.distinctKeys.has(side.name))
+            continue;
+        const keyed = side === sideA ? aKeyed : bKeyed;
+        for (const [key, subjects] of keyed) {
+            if (subjects.length > 1) {
+                violations.push(...keyViolations(keyed, key, `${side.name} maps ${String(subjects.length)} distinct subjects to the key "${key}" — over-normalization can mask a real mismatch`, meta));
+            }
+        }
+    }
+    // NOTE: independence of the two sides is a *requirement* stated in the docs,
+    // not something the builder can mechanically enforce — two literal lists can
+    // be legitimately independent (e.g. Object.keys of two different runtime
+    // objects), so a "both sides literal" heuristic would false-positive, and a
+    // console.warn is invisible to the agent consumer (ADR-008). Left to review.
+    // The false declaration FIRST — it says the configuration is wrong, which the
+    // reader needs before the findings produced under it, matching the ordering
+    // `RuleBuilder.evaluate` and the preset config findings already use.
+    return violations;
+}
+/**
+ * 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 function resolveSides(sides, reason, metadata) {
+    const [sideA, sideB] = sides;
+    if (sides.length !== 2 || sideA === undefined || sideB === undefined) {
+        throw new RangeError(`crossProject() requires exactly two .side(...) calls; got ${String(sides.length)}.`);
+    }
+    return {
+        sideA,
+        sideB,
+        meta: {
+            rule: `crossProject [${sideA.name} <-> ${sideB.name}]`,
+            because: reason,
+            ruleId: metadata?.id,
+            suggestion: metadata?.suggestion,
+            docs: metadata?.docs,
+        },
+    };
+}
+/**
+ * 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 function materializeSides(owner, a, b) {
+    // Narrowed, not asserted (ADR-005). A `?? new Map()` fallback would be worse
+    // than the `!` this replaced — the compute always returns two entries, so the
+    // fallback could never fire, and a branch that cannot fire is the shape this
+    // whole programme is about even when it is only types. Throwing says the same
+    // thing without lying about it.
+    const pair = sidesOf(owner, () => [a.materialize(), b.materialize()]);
+    const [first, second] = pair;
+    if (first === undefined || second === undefined) {
+        throw new RangeError(`crossProject(): the memoized side pair held ${String(pair.length)} entries, not 2.`);
+    }
+    return [first, second];
+}
+//# sourceMappingURL=correspondence-findings.js.map

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

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

package/dist/builders/cross-layer-builder.d.ts

@@ -1,8 +1,10 @@
+import type { CollectResult } from '../core/terminal-builder.js';
 import type { SourceFile } from 'ts-morph';
 import type { ArchProject } from '../core/project.js';
 import type { PairCondition } from '../core/pair-condition.js';
 import type { Layer, LayerPair } from '../models/cross-layer.js';
-import { TerminalBuilder } from '@nielspeter/eess';
+import type { GlobNode } from '@nielspeter/eess';
+import { TerminalBuilder } from '../core/terminal-builder.js';
 /**
  * Builder for cross-layer consistency rules.
  *
@@ -11,8 +13,8 @@ import { TerminalBuilder } from '@nielspeter/eess';
  *
  * @example
  * crossLayer(project)
- *   .layer('routes', 'src/routes/**')
- *   .layer('schemas', 'src/schemas/**')
+ *   .layer('routes', '**\/src/routes/**')
+ *   .layer('schemas', '**\/src/schemas/**')
  *   .mapping((a, b) => a.getBaseName().replace('Route', '') === b.getBaseName().replace('Schema', ''))
  *   .forEachPair()
  *   .should(haveMatchingCounterpart())
@@ -20,13 +22,24 @@ import { TerminalBuilder } from '@nielspeter/eess';
  */
 export declare class CrossLayerBuilder {
     private readonly project;
-    private readonly _layerDefs;
+    private _layerDefs;
     constructor(project: ArchProject);
     /**
      * Define a layer by name and glob pattern.
      * At least two layers must be defined before calling `.mapping()`.
      */
     layer(name: string, pattern: string): this;
+    /**
+     * An independent copy, carrying the layer definitions (bug 0016).
+     *
+     * This class does not extend {@link TerminalBuilder} — it produces a rule
+     * rather than being one — so it does not inherit that class's `copy()`. It
+     * still needs copy-on-write for the same reason: a held `crossLayer(p)`
+     * accumulated a layer per `.layer()` call across every rule derived from it,
+     * and `mapping()` pairs *consecutive* layers, so an extra layer silently
+     * changes which pairs a later rule compares.
+     */
+    private copy;
     /**
      * Provide a mapping function that determines which elements form pairs.
      * The function receives one element from each layer and returns `true` if they should be paired.
@@ -42,7 +55,8 @@ export declare class CrossLayerBuilder {
 export declare class MappedCrossLayerBuilder {
     private readonly layers;
     private readonly pairs;
-    constructor(layers: Layer[], pairs: LayerPair[]);
+    private readonly project?;
+    constructor(layers: Layer[], pairs: LayerPair[], project?: ArchProject | undefined);
     /**
      * Iterate over each matched pair. Returns a builder for attaching conditions.
      */
@@ -54,7 +68,8 @@ export declare class MappedCrossLayerBuilder {
 export declare class PairConditionBuilder {
     private readonly layers;
     private readonly pairs;
-    constructor(layers: Layer[], pairs: LayerPair[]);
+    private readonly project?;
+    constructor(layers: Layer[], pairs: LayerPair[], project?: ArchProject | undefined);
     /**
      * Attach a pair condition to evaluate against matched pairs.
      */
@@ -67,8 +82,67 @@ export declare class PairFinalBuilder extends TerminalBuilder {
     private readonly layers;
     private readonly pairs;
     private readonly condition;
-    constructor(layers: Layer[], pairs: LayerPair[], condition: PairCondition);
-    protected collectViolations(): import("@nielspeter/eess").ArchViolation[];
+    private readonly project?;
+    /**
+     * @param project - Optional so the constructor stays source-compatible; the
+     *   chain always supplies it. Without it `doctor` cannot check this rule's
+     *   layer globs and has to report that it could not, which is honest but
+     *   useless — and used to be silent.
+     */
+    constructor(layers: Layer[], pairs: LayerPair[], condition: PairCondition, project?: ArchProject | undefined);
+    /** The project this rule was built against. See `RuleBuilder.getProject`. */
+    getProject(): ArchProject | undefined;
+    /**
+     * The layer globs, one tree each.
+     *
+     * Per layer rather than one `any` node, for the same reason as
+     * `assignedFrom`: a dead glob means that layer is empty, and every pair
+     * involving it is silently unchecked. Folding them together would report a
+     * fault only when EVERY layer was empty.
+     */
+    globs(): readonly GlobNode[];
+    /**
+     * Does the condition this rule was built with diagnose its own empty layers?
+     *
+     * **Asked of the condition, not asserted about all of them** (plan 0081). This
+     * returned a bare `true` while the docstring here claimed "all three produce a
+     * finding naming the layer" — and at v0.45.0 that was false, because
+     * `haveMatchingCounterpart` missed a dead FINAL layer. The blanket declaration
+     * suppressed the gate for precisely the case its declared owner did not handle,
+     * so the reader got silence instead of a generic message
+     * ([ts-archunit bug 0040](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0040-a-crosslayer-rule-reports-nothing-when-its-layer-resolves-nothing.md)).
+     *
+     * A prose claim about three implementations goes stale when a fourth arrives.
+     * A tag read off the condition cannot: an untagged condition is covered by the
+     * gate, which is the recoverable direction.
+     *
+     * The gate is worth standing down for when the tag IS present: it short-circuits
+     * before the condition runs, and the condition's finding names the dead layer
+     * and points at the `.layer()` call to edit — a remedy corrected three times
+     * before it was right (bug 0042).
+     */
+    protected ownsDiscoveryDiagnosis(): boolean;
+    /**
+     * Pairs this rule examined — plan 0098. `condition.evaluate` receives exactly
+     * this array, so the count cannot drift from what was checked.
+     */
+    /**
+     * This family counts layer pairs — the pairs of layers it compares.
+     *
+     * 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.
+     *
+     * The materialized elements of the layer selection.
+     */
+    examinedUnits(): number;
+    protected collectViolations(): CollectResult;
 }
 /**
  * Entry point: create a cross-layer consistency rule builder.
@@ -78,19 +152,28 @@ export declare class PairFinalBuilder extends TerminalBuilder {
  *
  * @example
  * crossLayer(project)
- *   .layer('routes', 'src/routes/**')
- *   .layer('schemas', 'src/schemas/**')
+ *   .layer('routes', '**\/src/routes/**')
+ *   .layer('schemas', '**\/src/schemas/**')
  *   .mapping((a, b) => a.getBaseName().replace('-route', '') === b.getBaseName().replace('-schema', ''))
  *   .forEachPair()
  *   .should(haveMatchingCounterpart())
  *   .check()
+ */
+/**
+ * @deprecated Superseded by `crossProject()` **for pairings that are key equality** —
+ * `key(a) === key(b)` with each key derived from its own side. That covers most
+ * rules, including `haveConsistentExports` (a key function may return an array, so
+ * one file expands into one key per symbol). It is a rewrite, not a rename: the
+ * pairing moves from `.mapping(fn)` into the key.
+ *
+ * KEEP `crossLayer` if your `.mapping(fn)` is not key equality — prefix matching,
+ * directory nesting, "imports its schema" — or if you use `satisfyPairCondition`,
+ * whose callback builds its own violation (including `measured`/`metricUnit` for the
+ * baseline ratchet) and has no `crossProject` equivalent. Chains of 3+ layers become
+ * N−1 separate rules.
  *
- * @deprecated Superseded by the kernel `correspondence()` primitive
- * (`@nielspeter/eess`), which binds two element `Selection`s from *any* loaders
- * (not just two globs within one project) and is the engine `crossLayer` should
- * have been built on. `crossLayer` continues to work; new rules should prefer
- * `correspondence({ left, right }).should().beComplete(...)`. Full internal
- * delegation onto `correspondence()` is a follow-up (see plan 0059, Phase 3).
+ * Migration table and the full list of what changes:
+ * https://github.com/nielspeter/eess/blob/main/docs/cross-project.md#migrating-from-crosslayer
  */
 export declare function crossLayer(p: ArchProject): CrossLayerBuilder;
 //# sourceMappingURL=cross-layer-builder.d.ts.map

package/dist/builders/cross-layer-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-layer-builder.d.ts","sourceRoot":"","sources":["../../src/builders/cross-layer-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,EAAE,eAAe,EAAmB,MAAM,kBAAkB,CAAA;AAqCnE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+C;gBAE7C,OAAO,EAAE,WAAW;IAEjD;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK1C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,GAAG,uBAAuB;CAkBhF;AAED;;;GAGG;AAEH,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE;IAGrC;;OAEG;IACH,WAAW,IAAI,oBAAoB;CAGpC;AAED;;GAEG;AAEH,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE;IAGrC;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;CAGnD;AAED;;GAEG;AAEH,qBAAa,gBAAiB,SAAQ,eAAe;IAEjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE,EAClB,SAAS,EAAE,aAAa;IAK3C,SAAS,CAAC,iBAAiB;CAY5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAE5D"}
+{"version":3,"file":"cross-layer-builder.d.ts","sourceRoot":"","sources":["../../src/builders/cross-layer-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAA;AACpF,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAiD7D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,UAAU,CAA+C;gBAEpC,OAAO,EAAE,WAAW;IAEjD;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAM1C;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI;IAMZ;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,GAAG,uBAAuB;CAkBhF;AAED;;;GAGG;AAQH,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFR,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,CAAC,EAAE,WAAW,YAAA;IAGxC;;OAEG;IACH,WAAW,IAAI,oBAAoB;CAGpC;AAED;;GAEG;AAQH,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFR,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,CAAC,EAAE,WAAW,YAAA;IAGxC;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;CAGnD;AAED;;GAEG;AAQH,qBAAa,gBAAiB,SAAQ,eAAe;IAQjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAV3B;;;;;OAKG;gBAEgB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,SAAS,EAAE,EAClB,SAAS,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,WAAW,YAAA;IAKxC,6EAA6E;IAC7E,UAAU,IAAI,WAAW,GAAG,SAAS;IAIrC;;;;;;;OAOG;IACM,KAAK,IAAI,SAAS,QAAQ,EAAE;IAcrC;;;;;;;;;;;;;;;;;;;OAmBG;cACgB,sBAAsB,IAAI,OAAO;IASpD;;;OAGG;IAEH;;;;;;;OAOG;cACgB,gBAAgB,IAAI,MAAM;IAI7C;;;;;OAKG;IACH,aAAa,IAAI,MAAM;IAIvB,SAAS,CAAC,iBAAiB,IAAI,aAAa;CAsB7C;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAE5D"}