@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/testing/conformance-core.d.ts

@@ -1,15 +1,15 @@
 /**
- * Shared plumbing for the conformance kits: the assertion primitives and CST walks
- * `container-conformance.ts` (G4.3) and `kind-conformance.ts` sit on. Runner-agnostic —
- * a failure is a plain thrown `Error`, so no suite reaching for one seam is forced to
- * load a runner.
+ * The cell runner, assertion helpers and tree traversals the conformance kits share. A failure is
+ * a plain thrown `Error`, so using one never forces a suite to load a test runner.
  */
 import type { AnyBlockKind, CstNode, Document } from '../core/nodes';
-import type { BlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { type BlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { showValue as show } from '../core/metadata-parity';
+export { show };
 /**
- * How a cell is covered: `assert` runs the real check, `exempt` means the invariant has
- * nothing to bite on, `boundary` means it needs something headless code cannot reach.
- * Both non-assert modes carry a substantive reason — never a silent skip.
+ * How a cell is covered: `assert` runs the real check, `exempt` means the invariant has nothing
+ * to test here, `boundary` means it needs something headless code cannot reach. Both of the
+ * non-asserting modes carry a real reason, so nothing is ever skipped silently.
  */
 export type ConformanceCoverage = {
     mode: 'assert';
@@ -20,26 +20,58 @@ export type ConformanceCoverage = {
     mode: 'boundary';
     reason: string;
 };
+export type CellStatus = 'asserted' | 'exempt' | 'boundary';
+export interface CellReport<Cell extends string = string> {
+    cell: Cell;
+    status: CellStatus;
+    /** Why a cell was excused, or which mechanism an asserted cell drove. */
+    detail?: string;
+}
+/** What a check returns: nothing or a detail line when it ran, or an explicit status when it
+ *  could not do its work, which is never reported `asserted`. */
+export type CellOutcome = void | string | {
+    status: CellStatus;
+    detail: string;
+};
+export interface KitCell<Cell extends string, Ctx> {
+    cell: Cell;
+    /** The profile's declaration for the cell; a cell without one always runs. */
+    coverage?: (ctx: Ctx) => ConformanceCoverage;
+    run: (ctx: Ctx) => CellOutcome | Promise<CellOutcome>;
+    /** Throws when the declared excuse can be disproved. */
+    falsify?: (ctx: Ctx) => void;
+}
+/** Runs one cell, or throws its failure; `subject` names the kind or handler in messages. */
+export declare function runCell<Cell extends string, Ctx>(kitCell: KitCell<Cell, Ctx>, ctx: Ctx, subject: string): Promise<CellReport<Cell>>;
+/** Runs every cell and throws one `Error` under `heading` naming each failure, `earlier` ones
+ *  (found before any cell ran) first. */
+export declare function runCells<Cell extends string, Ctx>(cells: readonly KitCell<Cell, Ctx>[], ctx: Ctx, names: {
+    subject: string;
+    heading: string;
+}, earlier?: readonly string[]): Promise<CellReport<Cell>[]>;
 export declare function fail(message: string): never;
 export declare function assert(condition: unknown, message: string): asserts condition;
 export declare function assertIs(actual: unknown, expected: unknown, message: string): void;
 export declare function assertIndices(actual: readonly number[], expected: readonly number[], message: string): void;
-export declare function show(value: unknown): string;
-/** A documented reason is substantive, never a bare token — the visible-not-silent-skip floor. */
+/** A documented reason says something, never a bare token: a skip has to be visible. */
 export declare function assertReasonDocumented(reason: string, label: string): void;
-/** An EXEMPT/BOUNDARY cell must carry a substantive reason — visible, never a silent skip. */
+/** An exempt or boundary cell carries a real reason, so the skip stays visible. */
 export declare function assertExemptionDocumented(cell: ConformanceCoverage, label: string): void;
 /**
- * For a byte-faithful (strip/opaque) rebuild, `rebuildRaw` is the parse inverse: it must
- * reproduce the SAME bytes, not merely run twice with the same wrong output. Grid rebuilds
- * canonicalize delimiter/padding widths by contract, so they ride the determinism cell
- * instead. Mutates `node.raw` in place — pass a fresh parse, never a shared cell node.
+ * A byte-faithful rebuild must reproduce the parsed bytes (a grid one canonicalizes widths, so it
+ * only has to run). Writes `node.raw` in place: pass a fresh parse, never a node a cell shares.
  */
 export declare function assertRebuildIsParseCanonical(descriptor: BlockKindDescriptor, node: CstNode, label: string): void;
+/** Where a cell's node sits: a document-rooted path, or the first node of the kind in pre-order. */
+export type SubjectAt = readonly number[] | 'first';
+/** The path to the node a cell checks, failing unless a node of `kind` sits there, so no cell
+ *  reports `asserted` over another kind; `label` names the fixture in the failure. */
+export declare function subjectPath(doc: Document, kind: AnyBlockKind, at: SubjectAt, label: string): number[];
+export declare function subjectNode(doc: Document, kind: AnyBlockKind, at: SubjectAt, label: string): CstNode;
 export declare function firstChildOfKind(source: string, kind: AnyBlockKind): CstNode;
-export declare function nodeAtPath(root: Document | CstNode, path: number[]): CstNode;
-/** First node of `kind` in a pre-order walk (the kind may be nested below the root). */
+export declare function nodeAtPath(doc: Document, path: number[]): CstNode;
+/** First node of `kind` in a pre-order traversal (the kind may be nested below the root). */
 export declare function findFirstOfKind(root: Document | CstNode, kind: AnyBlockKind): CstNode | null;
-/** Doc-rooted path of the first node of `kind` in a pre-order walk, or null. */
+/** Path from `root` to the first node of `kind` in a pre-order traversal, or null. */
 export declare function findFirstPathOfKind(root: Document | CstNode, kind: AnyBlockKind): number[] | null;
 export declare function pathPassesThroughKind(doc: Document, leafPath: number[], kind: AnyBlockKind): boolean;

package/dist/testing/conformance-core.js

@@ -1,10 +1,49 @@
 /**
- * Shared plumbing for the conformance kits: the assertion primitives and CST walks
- * `container-conformance.ts` (G4.3) and `kind-conformance.ts` sit on. Runner-agnostic —
- * a failure is a plain thrown `Error`, so no suite reaching for one seam is forced to
- * load a runner.
+ * The cell runner, assertion helpers and tree traversals the conformance kits share. A failure is
+ * a plain thrown `Error`, so using one never forces a suite to load a test runner.
  */
 import { parse } from '../core/parser';
+import { ancestorsOf, walkBlocks } from '../core/paths';
+import { blockNodeAt } from '../tree-operations/node-primitives';
+import { isGridDescriptor } from '../schema/block-kind-descriptor';
+import { showValue as show } from '../core/metadata-parity';
+export { show };
+/** Runs one cell, or throws its failure; `subject` names the kind or handler in messages. */
+export async function runCell(kitCell, ctx, subject) {
+    const { cell } = kitCell;
+    const coverage = kitCell.coverage?.(ctx) ?? { mode: 'assert' };
+    if (coverage.mode !== 'assert') {
+        assertExemptionDocumented(coverage, `${subject} ${cell}`);
+        kitCell.falsify?.(ctx);
+        return { cell, status: coverage.mode, detail: coverage.reason };
+    }
+    const outcome = await kitCell.run(ctx);
+    if (outcome === undefined)
+        return { cell, status: 'asserted' };
+    if (typeof outcome === 'string')
+        return { cell, status: 'asserted', detail: outcome };
+    if (outcome.status !== 'asserted') {
+        assertReasonDocumented(outcome.detail, `${subject} ${cell} ${outcome.status} reason`);
+    }
+    return { cell, ...outcome };
+}
+/** Runs every cell and throws one `Error` under `heading` naming each failure, `earlier` ones
+ *  (found before any cell ran) first. */
+export async function runCells(cells, ctx, names, earlier = []) {
+    const reports = [];
+    const failures = [...earlier];
+    for (const kitCell of cells) {
+        try {
+            reports.push(await runCell(kitCell, ctx, names.subject));
+        }
+        catch (error) {
+            failures.push(`${kitCell.cell}: ${error.message}`);
+        }
+    }
+    if (failures.length > 0)
+        fail(`${names.heading}:\n  - ${failures.join('\n  - ')}`);
+    return reports;
+}
 // ── Assertion kit ────────────────────────────────────────────────────────────
 export function fail(message) {
     throw new Error(message);
@@ -23,14 +62,11 @@ export function assertIndices(actual, expected, message) {
         fail(`${message} — expected [${expected}], got [${actual}]`);
     }
 }
-export function show(value) {
-    return typeof value === 'string' ? JSON.stringify(value) : String(value);
-}
-/** A documented reason is substantive, never a bare token — the visible-not-silent-skip floor. */
+/** A documented reason says something, never a bare token: a skip has to be visible. */
 export function assertReasonDocumented(reason, label) {
     assert(reason.length > 20, `${label} is documented`);
 }
-/** An EXEMPT/BOUNDARY cell must carry a substantive reason — visible, never a silent skip. */
+/** An exempt or boundary cell carries a real reason, so the skip stays visible. */
 export function assertExemptionDocumented(cell, label) {
     if (cell.mode === 'assert') {
         fail(`assertExemptionDocumented called on an 'assert' cell: ${label}`);
@@ -38,10 +74,8 @@ export function assertExemptionDocumented(cell, label) {
     assertReasonDocumented(cell.reason, `${label} ${cell.mode} reason`);
 }
 /**
- * For a byte-faithful (strip/opaque) rebuild, `rebuildRaw` is the parse inverse: it must
- * reproduce the SAME bytes, not merely run twice with the same wrong output. Grid rebuilds
- * canonicalize delimiter/padding widths by contract, so they ride the determinism cell
- * instead. Mutates `node.raw` in place — pass a fresh parse, never a shared cell node.
+ * A byte-faithful rebuild must reproduce the parsed bytes (a grid one canonicalizes widths, so it
+ * only has to run). Writes `node.raw` in place: pass a fresh parse, never a node a cell shares.
  */
 export function assertRebuildIsParseCanonical(descriptor, node, label) {
     const before = node.raw;
@@ -51,55 +85,59 @@ export function assertRebuildIsParseCanonical(descriptor, node, label) {
     catch (error) {
         fail(`${label} rebuildRaw throws over a parsed fixture: ${error.message}`);
     }
-    if (descriptor.containerContract !== 'grid') {
+    if (!isGridDescriptor(descriptor)) {
         assertIs(node.raw, before, `${label} rebuildRaw reproduces the parse-canonical raw`);
     }
 }
+/** The path to the node a cell checks, failing unless a node of `kind` sits there, so no cell
+ *  reports `asserted` over another kind; `label` names the fixture in the failure. */
+export function subjectPath(doc, kind, at, label) {
+    const path = at === 'first' ? findFirstPathOfKind(doc, kind) : [...at];
+    if (!path)
+        fail(`${label} parses to no "${kind}" node`);
+    const found = blockNodeAt(doc, path)?.kind;
+    if (found !== kind) {
+        const held = found === undefined ? 'no node' : `a "${found}"`;
+        fail(`${label} holds ${held} at [${path}], not the "${kind}" under test`);
+    }
+    return path;
+}
+export function subjectNode(doc, kind, at, label) {
+    return nodeAtPath(doc, subjectPath(doc, kind, at, label));
+}
 // ── Tree walks ───────────────────────────────────────────────────────────────
 export function firstChildOfKind(source, kind) {
-    const node = parse(source).children[0];
-    assertIs(node.kind, kind, `sample's first child is "${kind}"`);
+    const node = subjectNode(parse(source), kind, [0], 'the sample');
     assert(node.children, 'sample container has children');
     return node;
 }
-export function nodeAtPath(root, path) {
-    let cur = root;
-    for (const i of path) {
-        assert(cur.children, 'path step has children');
-        cur = cur.children[i];
-    }
-    assert('raw' in cur, 'path resolves to a block node');
-    return cur;
+export function nodeAtPath(doc, path) {
+    const node = blockNodeAt(doc, path);
+    assert(node, 'path resolves to a block node');
+    return node;
 }
-/** First node of `kind` in a pre-order walk (the kind may be nested below the root). */
+/** First node of `kind` in a pre-order traversal (the kind may be nested below the root). */
 export function findFirstOfKind(root, kind) {
-    for (const child of root.children ?? []) {
-        if (child.kind === kind)
-            return child;
-        const found = findFirstOfKind(child, kind);
-        if (found)
-            return found;
-    }
-    return null;
+    let found = null;
+    walkBlocks(root, (node) => {
+        if (node.kind !== kind)
+            return;
+        found = node;
+        return 'stop';
+    });
+    return found;
 }
-/** Doc-rooted path of the first node of `kind` in a pre-order walk, or null. */
+/** Path from `root` to the first node of `kind` in a pre-order traversal, or null. */
 export function findFirstPathOfKind(root, kind) {
-    const children = root.children ?? [];
-    for (let i = 0; i < children.length; i++) {
-        if (children[i].kind === kind)
-            return [i];
-        const deeper = findFirstPathOfKind(children[i], kind);
-        if (deeper)
-            return [i, ...deeper];
-    }
-    return null;
+    let found = null;
+    walkBlocks(root, (node, path) => {
+        if (node.kind !== kind)
+            return;
+        found = path;
+        return 'stop';
+    });
+    return found;
 }
 export function pathPassesThroughKind(doc, leafPath, kind) {
-    let cur = doc;
-    for (let depth = 0; depth < leafPath.length - 1; depth++) {
-        cur = cur.children[leafPath[depth]];
-        if (cur.kind === kind)
-            return true;
-    }
-    return false;
+    return ancestorsOf(doc, leafPath).some((node) => node.kind === kind);
 }

package/dist/testing/container-conformance.d.ts

@@ -1,16 +1,15 @@
 /**
- * G4.3 — container conformance kit, published at `@voithos-labs/aragonite/testing`. Register your kind, then
- * point the kit at it with fixtures plus a coverage matrix declaring per invariant whether it
- * asserts or is excused (never a silent skip; a thin reason fails the run). Which answer a
- * container owes each cell is in the plugin guide's "Conformance-testing a container". Asserted
- * checks drive the real per-kind action path, stopping at the nested-action default and at a DOM.
+ * The container conformance kit, published at `@voithos-labs/aragonite/testing`. Register your
+ * kind, then run the kit with fixtures and a coverage table saying, per invariant, whether the cell
+ * asserts or is excused; a thin excuse fails the run. What each cell expects:
+ * `docs/guide/plugin-testing.md` § The container checkup.
  */
 import type { AnyBlockKind, CstNode } from '../core/nodes';
-import { type ConformanceCoverage } from './conformance-core';
+import { type CellOutcome, type CellReport, type ConformanceCoverage, type KitCell } from './conformance-core';
 /**
- * `containerChain` is doc-rooted, from the doc root down to and including the
- * kind-under-test. Its last container has `targetChild` edited — pick a NON-first child
- * or a NON-zero chain position, or the check is vacuous (`checkStripLocalIndexAddressing`).
+ * `containerChain` runs from the document root down to and including the kind under test. Its last
+ * container has `targetChild` edited, so pick a child that is not the first, or a chain position
+ * that is not zero, or the check proves nothing (`checkStripLocalIndexAddressing`).
  */
 export interface LocalIndexFixture {
     source: string;
@@ -18,19 +17,15 @@ export interface LocalIndexFixture {
     targetChild: number;
 }
 /**
- * `source` must parse to a document whose FIRST top-level block is the kind under
- * test; `bodyRaw` replaces that node's LAST child and must contain a line
- * reproducing the container's terminator (a bare `:::` for a colon fence, a
- * `</details>` line for an HTML close tag).
+ * `source` parses to a document whose first top-level block is the kind under test. `bodyRaw`
+ * replaces that node's last child and has to contain a line that reproduces the container's
+ * terminator (a bare `:::` for a colon fence, a `</details>` line for an HTML close tag).
  */
 export interface TerminatorCollisionFixture {
     source: string;
     bodyRaw: string;
-    /**
-     * Required when the fixture node parses CHILDLESS (a metadata-bodied whole block): the kit
-     * hands over bytes already run through the kind's `bodyWrite` rule and the fixture seats them
-     * wherever that container's body lives. The rebuild and the convergence oracle stay the kit's.
-     */
+    /** Required when the fixture node parses childless (its body lives in metadata): puts the
+     *  kit's `bodyWrite`-normalized bytes wherever that container keeps its body. */
     writeBody?: (node: CstNode, body: string) => void;
 }
 export interface ContainerConformanceProfile {
@@ -39,18 +34,15 @@ export interface ContainerConformanceProfile {
         source: string;
         leafPath: number[];
     };
-    /** Required when `localIndex` asserts (strip/opaque kinds; grid has its own path). */
+    /** Required when `localIndex` asserts on a strip or opaque kind. */
     localIndexFixture?: LocalIndexFixture;
     /** Required when `focusBubble` asserts: a source whose tree holds a node of the kind with ≥1 child. */
     focusSource?: string;
     /** Required when `terminatorCollision` asserts. `bodyRaw` goes through the kind's
-     *  `bodyWrite` rule, so it names the bytes a USER produces, not what reaches the tree. */
+     *  `bodyWrite` rule, so it names the bytes a user types, not what reaches the tree. */
     terminatorCollisionFixture?: TerminatorCollisionFixture;
-    /**
-     * Why NO behavioral cell asserts. A profile excusing every one of them tests nothing while
-     * reporting a reviewed reason per cell, so the all-excused shape is declared once, at the
-     * profile, rather than assembled cell by cell.
-     */
+    /** Why no behavioral cell asserts: required when the profile excuses them all, and rejected
+     *  when any cell asserts. */
     wholeProfileExemption?: string;
     localIndex: ConformanceCoverage;
     ancestry: ConformanceCoverage;
@@ -58,31 +50,29 @@ export interface ContainerConformanceProfile {
     focusBubble: ConformanceCoverage;
     terminatorCollision: ConformanceCoverage;
 }
-export type ConformanceCell = 'localIndex' | 'ancestry' | 'multiScope' | 'focusBubble' | 'terminatorCollision' | 'declarations';
-export interface ConformanceCellReport {
-    cell: ConformanceCell;
-    status: 'asserted' | 'exempt' | 'boundary';
-    reason?: string;
+/** The built-in profiles' hooks for the ops only a built-in kind's own context can drive (a table
+ *  column insert, a list indent). Internal: no published API can perform either op. */
+export interface BuiltinContainerProfile extends ContainerConformanceProfile {
+    drivers?: {
+        gridLocalIndex?: () => Promise<void>;
+        multiScope?: () => Promise<void>;
+    };
 }
+export type ConformanceCell = 'localIndex' | 'ancestry' | 'multiScope' | 'focusBubble' | 'terminatorCollision' | 'titleRow' | 'declarations';
 export interface ContainerConformanceReport {
     kind: AnyBlockKind;
-    cells: ConformanceCellReport[];
+    cells: CellReport<ConformanceCell>[];
 }
-export interface ContainerConformanceCell {
-    cell: ConformanceCell;
-    /** The profile's declaration for this cell; `declarations` answers unconditionally. */
-    coverage: (profile: ContainerConformanceProfile) => ConformanceCoverage;
-    run: (kind: AnyBlockKind, profile: ContainerConformanceProfile) => void | Promise<void>;
+export interface ContainerCellContext {
+    kind: AnyBlockKind;
+    profile: BuiltinContainerProfile;
 }
+/** The kit's cells as data, so {@link runContainerConformance} and the built-in sweep run the
+ *  same set; `titleRow` and `declarations` declare no coverage and always run. */
+export declare const CONTAINER_CONFORMANCE_CELLS: readonly KitCell<ConformanceCell, ContainerCellContext>[];
 /**
- * The kit's cells as data, so every sweep runs the same set: {@link runContainerConformance} and
- * the registry-derived built-in sweep both iterate this rather than listing cells by hand, which
- * is what makes cell N+1 unmissable at either caller.
- */
-export declare const CONTAINER_CONFORMANCE_CELLS: readonly ContainerConformanceCell[];
-/**
- * A profile owes at least one asserting behavioral cell. `declarations` is excluded on purpose:
- * it asserts for every kind, so counting it would let an all-excused profile clear the floor.
+ * A profile must assert at least one cell it declares. `declarations` doesn't count: it asserts
+ * for every kind, so counting it would let a profile that excuses everything pass.
  */
 export declare function assertProfileCoverageFloor(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;
 /**
@@ -90,48 +80,22 @@ export declare function assertProfileCoverageFloor(kind: AnyBlockKind, profile:
  * `Error` naming every failed cell.
  */
 export declare function runContainerConformance(kind: AnyBlockKind, profile: ContainerConformanceProfile): Promise<ContainerConformanceReport>;
-/**
- * Assert the addressed child is the one that mutated (by content) and that the emitted
- * path is the chain of LOCAL indices. The non-first / non-zero setup is what
- * discriminates local from global addressing; at chain [0,0] child 0 the two coincide.
- */
-export declare function checkStripLocalIndexAddressing(profile: ContainerConformanceProfile): Promise<void>;
-/**
- * Grid local addressing: a table column op addresses cells by (rowIdx, colIdx) and emits
- * the table's own local path. The leading paragraph keeps the table at a non-zero doc
- * index, so a flat global offset would not coincide with the local one.
- */
-export declare function checkGridLocalIndexAddressing(): Promise<void>;
+/** Asserts the addressed child is the one removed and the emitted path is the chain of local
+ *  indices; the fixture avoids chain [0,0] child 0, where local and global indices coincide. */
+export declare function checkStripLocalIndexAddressing(kind: AnyBlockKind, profile: ContainerConformanceProfile): Promise<void>;
 export declare function checkInnermostFirstAncestry(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;
-/**
- * Mutation probe proving the ancestry check is non-vacuous: a reversed (outer→inner)
- * rebuild leaves the root stale for a strip/opaque container. Returns false for a
- * container that re-derives its whole subtree (grid), which is why grid excuses ancestry.
- */
+/** Shows the ancestry check can fail: an outer-to-inner rebuild leaves a strip or opaque root
+ *  stale. False for a grid, which re-derives its whole subtree and so excuses ancestry. */
 export declare function reversedAncestryLeavesRootStale(profile: ContainerConformanceProfile): boolean;
-/**
- * A multi-scope op is kind-specific: it drives through the kind's own context, not a
- * generic bundle, so only the built-ins that own one are dispatched here.
- */
-export declare function checkOneUndoPerMultiScope(kind: AnyBlockKind): Promise<void>;
-/**
- * Bubble an out-of-range ArrowUp through a real 2-level chain (kind-under-test → strip
- * outer at its own top edge → recording root) and assert it reaches the root exactly
- * once. Driving the kind's own bundle rather than `dispatchMoveFocus` is what catches a
- * container whose focus wiring re-enters or double-escapes.
- */
+/** Bubbles an out-of-range ArrowUp through the kind's own focus bundle, under a blockquote at its
+ *  top edge, and asserts the root sees it once, catching wiring that re-enters or escapes twice. */
 export declare function checkFocusBubbleTermination(kind: AnyBlockKind, profile: ContainerConformanceProfile): Promise<void>;
-/**
- * Write a terminator-shaped line into the container's body through `bodyWrite` (the door the
- * commit path uses) and require the live tree to still converge with a fresh parse. Convergence
- * is the oracle, not byte round-trip: `serialize(parse(s)) === s` holds throughout a collision
- * while the container silently stops containing what it says it does. A childless container
- * (body in metadata) seats the same bytes through the fixture's own `writeBody`.
- */
+/** Writes a terminator-shaped body line through `bodyWrite`, as the commit path does, and requires
+ *  the tree to match a fresh parse, since byte round-trip holds even through a collision. */
 export declare function checkTerminatorCollision(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;
-/**
- * Hold the kind to its schema declarations. A declared `unwrapRole` must name implemented
- * strategies because the nested dispatcher indexes them unguarded, and a capability whose only
- * job is a cell's repair may not ship behind that cell's excuse.
- */
+/** A title keystroke skips an opaque container's metadata re-read, so the row is written through
+ *  that keystroke's rebuild and the tree has to match a fresh parse, every metadata key included. */
+export declare function checkTitleRowFeedsNoMetadata(kind: AnyBlockKind): CellOutcome;
+/** Holds the kind to its declarations: an `unwrapRole` names implemented strategies, which the
+ *  nested dispatcher indexes unguarded. */
 export declare function checkDeclarationSanity(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;