@voithos-labs/aragonite 0.10.1

package/dist/testing/conformance-core.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import { parse } from '../core/parser';
+// ── Assertion kit ────────────────────────────────────────────────────────────
+export function fail(message) {
+    throw new Error(message);
+}
+export function assert(condition, message) {
+    if (!condition)
+        fail(message);
+}
+export function assertIs(actual, expected, message) {
+    if (!Object.is(actual, expected)) {
+        fail(`${message} — expected ${show(expected)}, got ${show(actual)}`);
+    }
+}
+export function assertIndices(actual, expected, message) {
+    if (actual.length !== expected.length || actual.some((v, i) => v !== expected[i])) {
+        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. */
+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. */
+export function assertExemptionDocumented(cell, label) {
+    if (cell.mode === 'assert') {
+        fail(`assertExemptionDocumented called on an 'assert' 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.
+ */
+export function assertRebuildIsParseCanonical(descriptor, node, label) {
+    const before = node.raw;
+    try {
+        descriptor.rebuildRaw(node);
+    }
+    catch (error) {
+        fail(`${label} rebuildRaw throws over a parsed fixture: ${error.message}`);
+    }
+    if (descriptor.containerContract !== 'grid') {
+        assertIs(node.raw, before, `${label} rebuildRaw reproduces the parse-canonical raw`);
+    }
+}
+// ── Tree walks ───────────────────────────────────────────────────────────────
+export function firstChildOfKind(source, kind) {
+    const node = parse(source).children[0];
+    assertIs(node.kind, kind, `sample's first child is "${kind}"`);
+    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;
+}
+/** First node of `kind` in a pre-order walk (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;
+}
+/** Doc-rooted path of the first node of `kind` in a pre-order walk, 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;
+}
+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;
+}

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

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+import type { AnyBlockKind, CstNode } from '../core/nodes';
+import { type ConformanceCoverage } 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`).
+ */
+export interface LocalIndexFixture {
+    source: string;
+    containerChain: number[];
+    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).
+ */
+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.
+     */
+    writeBody?: (node: CstNode, body: string) => void;
+}
+export interface ContainerConformanceProfile {
+    /** A nesting where this kind is an intermediate ancestor of the doc-rooted `leafPath`. */
+    deepNesting: {
+        source: string;
+        leafPath: number[];
+    };
+    /** Required when `localIndex` asserts (strip/opaque kinds; grid has its own path). */
+    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. */
+    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.
+     */
+    wholeProfileExemption?: string;
+    localIndex: ConformanceCoverage;
+    ancestry: ConformanceCoverage;
+    multiScope: ConformanceCoverage;
+    focusBubble: ConformanceCoverage;
+    terminatorCollision: ConformanceCoverage;
+}
+export type ConformanceCell = 'localIndex' | 'ancestry' | 'multiScope' | 'focusBubble' | 'terminatorCollision' | 'declarations';
+export interface ConformanceCellReport {
+    cell: ConformanceCell;
+    status: 'asserted' | 'exempt' | 'boundary';
+    reason?: string;
+}
+export interface ContainerConformanceReport {
+    kind: AnyBlockKind;
+    cells: ConformanceCellReport[];
+}
+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>;
+}
+/**
+ * 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.
+ */
+export declare function assertProfileCoverageFloor(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;
+/**
+ * Run every conformance cell for `kind`. Resolves with the coverage report, or throws an
+ * `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>;
+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.
+ */
+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.
+ */
+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`.
+ */
+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.
+ */
+export declare function checkDeclarationSanity(kind: AnyBlockKind, profile: ContainerConformanceProfile): void;