@executablemd/testing 0.3.1

package/esm/testing/npm/src/src/handlers.js

@@ -0,0 +1,245 @@
+/**
+ * `<Testing>` and `<Test>` handlers (specs/testing-spec.md).
+ *
+ * `createTestHandlers` is the internal dependency-injection seam for the
+ * fixed 20-second test timeout: the public vocabulary always constructs
+ * handlers with 20_000; tests construct them directly with a small timeout.
+ */
+import { ensure, scoped, spawn, suspend, withResolvers } from "effection";
+import { timebox } from "@effectionx/timebox";
+import { unbox, useEvalScope } from "@effectionx/scope-eval";
+import { AssertionError } from "../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { Component, env, evalScope } from "@executablemd/core";
+import { Test, boundary, inTest, record, testing } from "./test-api.js";
+import { AssertionDiagnostic, expandAssertion } from "./assertions.js";
+import { persistBoundaryOutcome, persistTestResult } from "./journal.js";
+// ---------------------------------------------------------------------------
+// Contained-failure carriers
+// ---------------------------------------------------------------------------
+/** An ErrorSegment raised anywhere inside a test body. */
+class RaisedSegmentError extends Error {
+    name = "RaisedSegmentError";
+    segment;
+    constructor(segment) {
+        super(segment.message);
+        this.segment = segment;
+    }
+}
+/** A failure while dismantling an established test scope or lease. */
+class TeardownError extends Error {
+    name = "TeardownError";
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+    }
+}
+/**
+ * Host a child EvalScope in a dedicated task inside the parent EvalScope.
+ * The child inherits the parent's middleware, but its lifetime belongs to
+ * the TEST: `parentScope.eval(() => useEvalScope())` alone would tie the
+ * worker to the parent scope, leaking test-installed middleware into later
+ * tests. The suspended task keeps the child alive until the lease is halted.
+ */
+function* leaseChildEvalScope(parentScope) {
+    const published = withResolvers();
+    const boxed = yield* parentScope.eval(function* () {
+        return yield* spawn(function* () {
+            published.resolve(yield* useEvalScope());
+            yield* suspend();
+        });
+    });
+    return { scope: yield* published.operation, task: unbox(boxed) };
+}
+export function createTestHandlers(options) {
+    const { timeoutMs } = options;
+    function* expandTesting(invocation, ctx) {
+        return yield* scoped(function* () {
+            const local = [];
+            yield* Test.around({
+                testing: () => true,
+                // deno-lint-ignore require-yield
+                *results() {
+                    return local;
+                },
+                *record([result], next) {
+                    local.push(result);
+                    yield* next(result);
+                },
+            }, { at: "min" });
+            const report = yield* ctx.expand(invocation.children);
+            // Journal the outcome before the root Close so a full replay can
+            // restore it without re-expanding this boundary.
+            const outcome = yield* persistBoundaryOutcome({
+                tests: local.length,
+                failed: local.filter((result) => result.status === "fail").length,
+            }, formatLocation(invocation));
+            yield* boundary(outcome);
+            return report;
+        });
+    }
+    function* expandTest(invocation, ctx) {
+        if (!(yield* testing)) {
+            return [];
+        }
+        if (yield* inTest) {
+            // Returned while the ENCLOSING test's raise interceptor is still
+            // active — the hook's re-raise fails the current test.
+            const error = {
+                type: "error",
+                message: "Nested <Test> elements are invalid.",
+                source: "Test",
+            };
+            return [error];
+        }
+        const name = typeof invocation.props.name === "string" ? invocation.props.name : undefined;
+        const location = formatLocation(invocation);
+        const parentEnv = yield* env;
+        const parentScope = yield* evalScope;
+        if (!parentScope) {
+            const result = yield* persistTestResult(failResult(name, location, {
+                kind: "error",
+                message: "<Test> requires an eval scope in context.",
+            }));
+            yield* record(result);
+            return [failureDiagnostic(result, { detail: true })];
+        }
+        // ONE stable binding environment, created before middleware install —
+        // the accessor returns the same object on every read, so <Capture>
+        // writes persist for the assertion that follows. Caller-projected
+        // bindings merge UNDER the current environment (core's precedence,
+        // expand.ts §content projection), so a <Test> projected through
+        // <Content /> still sees the caller's eval bindings.
+        const testEnv = {
+            values: {
+                ...(ctx.projectedEnv?.values ?? {}),
+                ...(parentEnv?.values ?? {}),
+            },
+        };
+        const testOutput = [];
+        let bodyError;
+        let timedOut = false;
+        let established = false;
+        try {
+            yield* scoped(function* () {
+                const lease = yield* leaseChildEvalScope(parentScope);
+                // Halt the lease during this scope's teardown, before the next test
+                // can start. A throwing halt propagates as a teardown failure.
+                yield* ensure(() => lease.task.halt());
+                yield* Component.around({
+                    env: () => testEnv,
+                    evalScope: () => lease.scope,
+                }, { at: "min" });
+                yield* Test.around({ inTest: () => true }, { at: "min" });
+                // ErrorSegments fail the test. Outer instrumentation (default "max")
+                // so nested { at: "min" } policies cannot shadow it: every raise in
+                // the body — components, <Output> regions, code blocks, imports,
+                // validation, nested <Test> — arrives here first.
+                yield* Component.around({
+                    // deno-lint-ignore require-yield
+                    *raise([segment]) {
+                        throw new RaisedSegmentError(segment);
+                    },
+                });
+                established = true;
+                const boxed = yield* timebox(timeoutMs, function* () {
+                    for (const child of invocation.children) {
+                        try {
+                            testOutput.push(...(yield* ctx.expand([child])));
+                        }
+                        catch (error) {
+                            bodyError = error;
+                            throw error;
+                        }
+                    }
+                });
+                if (boxed.timeout) {
+                    timedOut = true;
+                }
+            });
+        }
+        catch (outer) {
+            if (bodyError === undefined && !timedOut) {
+                // Setup failures (lease creation, middleware install) are unexpected
+                // errors; only failures dismantling an ESTABLISHED scope/lease are
+                // teardown failures.
+                bodyError = established ? new TeardownError(outer) : outer;
+            }
+        }
+        // Journal the result before the root Close. On partial replay the
+        // stored record wins over the recomputation (short-circuited effects
+        // can change what the re-run observes, e.g. a halted exec no longer
+        // times out), keeping the original outcome authoritative.
+        const result = yield* persistTestResult(classify(name, location, bodyError, timedOut, timeoutMs));
+        yield* record(result);
+        if (result.status === "fail") {
+            // Containment invariant: a completed test returns only text segments.
+            // The hook re-raises returned ErrorSegments under the AMBIENT policy —
+            // after this test's interception scope has ended — so raised segments
+            // are formatted into the diagnostic instead of returned raw.
+            if (bodyError instanceof AssertionDiagnostic) {
+                // The assertion's own diagnostic (built when it threw) follows the
+                // output produced before the failure, then the test-level line.
+                testOutput.push({ type: "text", content: bodyError.diagnostic });
+                testOutput.push(failureDiagnostic(result, { detail: false }));
+            }
+            else {
+                testOutput.push(failureDiagnostic(result, { detail: true }));
+            }
+        }
+        return testOutput;
+    }
+    return { expandTesting, expandTest, expandAssertion };
+}
+// ---------------------------------------------------------------------------
+// Result classification and diagnostics
+// ---------------------------------------------------------------------------
+function formatLocation(invocation) {
+    const position = invocation.position;
+    if (!position) {
+        return "unknown";
+    }
+    const at = `${position.line}:${position.column}`;
+    return position.path ? `${position.path}:${at}` : at;
+}
+function failResult(name, location, error) {
+    return { status: "fail", name, location, error };
+}
+function classify(name, location, bodyError, timedOut, timeoutMs) {
+    if (bodyError === undefined && !timedOut) {
+        return { status: "pass", name, location };
+    }
+    if (timedOut && bodyError === undefined) {
+        return failResult(name, location, {
+            kind: "timeout",
+            message: `test timed out after ${timeoutMs / 1000} seconds`,
+        });
+    }
+    if (bodyError instanceof AssertionDiagnostic) {
+        return failResult(name, location, {
+            kind: "assertion",
+            message: bodyError.message,
+            actual: bodyError.detail.actual,
+            expected: bodyError.detail.expected,
+        });
+    }
+    if (bodyError instanceof AssertionError) {
+        return failResult(name, location, { kind: "assertion", message: bodyError.message });
+    }
+    if (bodyError instanceof TeardownError) {
+        return failResult(name, location, { kind: "teardown", message: bodyError.message });
+    }
+    const message = bodyError instanceof Error ? bodyError.message : String(bodyError);
+    return failResult(name, location, { kind: "error", message });
+}
+function failureDiagnostic(result, options) {
+    const title = result.name ? `**${result.name}**` : `test at ${result.location}`;
+    const error = result.error;
+    const lines = [`> ❌ Test ${title} failed (${error?.kind ?? "error"}): ${error?.message ?? ""}`];
+    if (options.detail && error?.actual !== undefined) {
+        lines.push(`> actual: ${error.actual}`);
+    }
+    if (options.detail && error?.expected !== undefined) {
+        lines.push(`> expected: ${error.expected}`);
+    }
+    return { type: "text", content: `\n${lines.join("\n")}\n` };
+}

package/esm/testing/npm/src/src/journal.js

@@ -0,0 +1,152 @@
+/**
+ * Durable testing records (specs/testing-spec.md §Testing Mode).
+ *
+ * Completed tests and explicit `<Testing>` boundary outcomes are journaled
+ * as testing-owned durable operations while document expansion runs —
+ * before the root Close event. On a full replay of a completed journal,
+ * `durableRun` returns the stored root result without re-expanding the
+ * document, so no test would ever re-record; the stored records are
+ * restored from the stream instead. On partial replay the document
+ * re-expands and each record replays in place, recording exactly once in
+ * discovery order.
+ *
+ * Record identities are deterministic, derived from source position.
+ */
+import { createDurableOperation } from "@executablemd/durable-streams";
+const TEST_RESULT = "test_result";
+const TESTING_BOUNDARY = "testing_boundary";
+export function* persistTestResult(result) {
+    const stored = yield createDurableOperation({ type: TEST_RESULT, name: `test:${result.location}` }, 
+    // deno-lint-ignore require-yield
+    function* () {
+        return serializeTestResult(result);
+    });
+    const parsed = parseTestResult(stored);
+    if (!parsed) {
+        throw new Error(`journaled test_result for "${result.location}" has an unexpected shape`);
+    }
+    return parsed;
+}
+export function* persistBoundaryOutcome(outcome, location) {
+    const stored = yield createDurableOperation({ type: TESTING_BOUNDARY, name: `testing:${location}` }, 
+    // deno-lint-ignore require-yield
+    function* () {
+        return { tests: outcome.tests, failed: outcome.failed };
+    });
+    const parsed = parseBoundaryOutcome(stored);
+    if (!parsed) {
+        throw new Error(`journaled testing_boundary for "${location}" has an unexpected shape`);
+    }
+    return parsed;
+}
+/**
+ * Read testing records from a journal that already holds a root Close
+ * event — the confirmed-full-replay case. Returns undefined for a live or
+ * partial journal, where expansion itself (re)records each result.
+ */
+export function* readCompletedRun(stream) {
+    const events = yield* stream.readAll();
+    const completed = events.some((event) => event.type === "close" && event.coroutineId === "root");
+    if (!completed) {
+        return undefined;
+    }
+    const results = [];
+    const boundaries = [];
+    for (const event of events) {
+        if (event.type !== "yield" || event.result.status !== "ok") {
+            continue;
+        }
+        if (event.description.type === TEST_RESULT) {
+            const parsed = parseTestResult(event.result.value);
+            if (parsed) {
+                results.push(parsed);
+            }
+        }
+        else if (event.description.type === TESTING_BOUNDARY) {
+            const parsed = parseBoundaryOutcome(event.result.value);
+            if (parsed) {
+                boundaries.push(parsed);
+            }
+        }
+    }
+    return { results, boundaries };
+}
+function serializeTestResult(result) {
+    const payload = {
+        status: result.status,
+        location: result.location,
+    };
+    if (result.name !== undefined) {
+        payload.name = result.name;
+    }
+    if (result.error) {
+        const error = {
+            kind: result.error.kind,
+            message: result.error.message,
+        };
+        if (result.error.actual !== undefined) {
+            error.actual = result.error.actual;
+        }
+        if (result.error.expected !== undefined) {
+            error.expected = result.error.expected;
+        }
+        payload.error = error;
+    }
+    return payload;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+const ERROR_KINDS = ["assertion", "timeout", "teardown", "error"];
+function parseTestResult(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const { status, location, name, error } = value;
+    if (status !== "pass" && status !== "fail") {
+        return undefined;
+    }
+    if (typeof location !== "string" || !optionalString(name)) {
+        return undefined;
+    }
+    const result = { status, location };
+    if (name !== undefined) {
+        result.name = name;
+    }
+    if (error !== undefined) {
+        if (!isRecord(error)) {
+            return undefined;
+        }
+        const { kind, message, actual, expected } = error;
+        if (typeof kind !== "string" || !ERROR_KINDS.includes(kind)) {
+            return undefined;
+        }
+        if (typeof message !== "string" ||
+            !optionalString(actual) ||
+            !optionalString(expected) ||
+            (kind !== "assertion" && kind !== "timeout" && kind !== "teardown" && kind !== "error")) {
+            return undefined;
+        }
+        result.error = { kind, message };
+        if (actual !== undefined) {
+            result.error.actual = actual;
+        }
+        if (expected !== undefined) {
+            result.error.expected = expected;
+        }
+    }
+    return result;
+}
+function parseBoundaryOutcome(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const { tests, failed } = value;
+    if (typeof tests !== "number" || typeof failed !== "number" || tests < 0 || failed < 0) {
+        return undefined;
+    }
+    return { tests, failed };
+}

package/esm/testing/npm/src/src/test-api.js

@@ -0,0 +1,33 @@
+/**
+ * Test Api — contextual operations for testing mode (specs/testing-spec.md).
+ *
+ * `testing` is the activation switch: false by default, true beneath
+ * `<Testing>` (or root activation via a `useTesting()` session).
+ * Both perform the identical `Test.around({ testing: () => true })` install,
+ * which is what makes `xmd test` equivalent to wrapping the entrypoint in
+ * `<Testing>`.
+ *
+ * `record` delegates outward through nested collectors, so every enclosing
+ * `<Testing>` boundary and the run-level collector observe each completed
+ * test. `boundary` reports each `<Testing>` element's aggregate outcome.
+ */
+import { createApi } from "@effectionx/context-api";
+export const Test = createApi("Test", {
+    testing: false,
+    inTest: false,
+    verbose: false,
+    sessionActive: false,
+    // deno-lint-ignore require-yield
+    *record(_result) { },
+    // deno-lint-ignore require-yield
+    *results() {
+        return [];
+    },
+    // deno-lint-ignore require-yield
+    *boundary(_outcome) { },
+});
+export const { testing, inTest, verbose, sessionActive, record, results, boundary } = Test.operations;
+/** A document execution failed its testing outcome (test failures or zero tests). */
+export class TestFailureError extends Error {
+    name = "TestFailureError";
+}

package/esm/testing/npm/src/src/use-testing.js

@@ -0,0 +1,79 @@
+/**
+ * useTesting — scope-local testing composition (specs/testing-spec.md).
+ *
+ * One `useTesting()` session per execution scope: it installs the testing
+ * vocabulary, the collection and completion-policy middleware, and root
+ * activation, then returns a session handle whose `results` operation
+ * snapshots completed tests in discovery order. Every install is removed
+ * with the session's Effection scope.
+ *
+ * ```ts
+ * const tests = yield* useTesting();
+ * const execution = yield* execute(options);
+ * const outcome = yield* execution;          // Result<string>
+ * const results = yield* tests.results;
+ * ```
+ */
+import { Execution } from "@executablemd/core";
+import { sessionActive, Test, TestFailureError } from "./test-api.js";
+import { decorateCompletion, installTestingVocabulary } from "./vocabulary.js";
+export function* useTesting(options) {
+    if (yield* sessionActive) {
+        throw new Error("useTesting() is already active in this scope — use one session per execution scope");
+    }
+    yield* Test.around({ sessionActive: () => true });
+    yield* installTestingVocabulary(options);
+    const collected = [];
+    yield* Test.around({
+        // deno-lint-ignore require-yield
+        *results() {
+            return [...collected];
+        },
+        *record([result], next) {
+            collected.push(result);
+            yield* next(result);
+        },
+    });
+    // Root activation — the same install <Testing> performs for its subtree,
+    // applied to the whole execution (`xmd test` ≡ root <Testing>).
+    yield* Test.around({ testing: () => true });
+    // Completion policy: an otherwise successful execution becomes
+    // Err(TestFailureError) after its output closes when tests failed or none
+    // were discovered. A core Err passes through unchanged, and `results`
+    // stays available either way.
+    //
+    // One execute() per session: results are cumulative across the session,
+    // so a second document would inherit the first document's outcomes (a
+    // zero-test document after a passing one would succeed). Fail clearly
+    // BEFORE a handle exists — the pre-handle throw path.
+    let executed = false;
+    yield* Execution.around({
+        *execute([executeOptions], next) {
+            if (executed) {
+                throw new Error("a useTesting() session supports one execute() call — start a new session for another document");
+            }
+            executed = true;
+            const inner = yield* next(executeOptions);
+            return decorateCompletion(inner, () => {
+                if (collected.length === 0) {
+                    return new TestFailureError("no tests were discovered");
+                }
+                const failed = collected.filter((result) => result.status === "fail");
+                if (failed.length > 0) {
+                    const details = failed
+                        .map((result) => `  ${result.name ?? result.location}: ${result.error?.message ?? "failed"}`)
+                        .join("\n");
+                    return new TestFailureError(`${failed.length} of ${collected.length} tests failed\n${details}`);
+                }
+                return undefined;
+            });
+        },
+    });
+    return {
+        results: {
+            *[Symbol.iterator]() {
+                return Object.freeze([...collected]);
+            },
+        },
+    };
+}

package/esm/testing/npm/src/src/vocabulary.js

@@ -0,0 +1,111 @@
+/**
+ * Vocabulary registration (specs/testing-spec.md).
+ *
+ * Teaches the expansion loop the testing words — `<Testing>`, `<Test>`, and
+ * the assertion components — via the core `expandInvocation` hook, and
+ * decorates the core Execution Api so explicit `<Testing>` boundaries affect
+ * the execution outcome even when root testing is inactive.
+ *
+ * Registration is distinct from activation: installing the vocabulary
+ * leaves `testing` false, so `<Test>` skips and assertions stay usable.
+ * Root activation is `useTesting()`'s job.
+ *
+ * Installs are scope-local — call this inside a bounded scope (one CLI
+ * command invocation, one `scoped()` block).
+ */
+import { Err } from "effection";
+import { Component, Execution } from "@executablemd/core";
+import { boundary, record, Test, TestFailureError } from "./test-api.js";
+import { readCompletedRun } from "./journal.js";
+import { ASSERTIONS } from "./assertions.js";
+import { createTestHandlers } from "./handlers.js";
+const TEST_TIMEOUT_MS = 20_000;
+export function* installTestingVocabulary(options) {
+    yield* installHandlers(createTestHandlers({ timeoutMs: TEST_TIMEOUT_MS }), options);
+}
+/**
+ * Install a specific handler set. Internal seam: tests inject handlers built
+ * with a short timeout; the public path always uses the fixed 20 seconds.
+ */
+export function* installHandlers(handlers, options) {
+    if (options?.verbose) {
+        yield* Test.around({ verbose: () => true });
+    }
+    yield* Component.around({
+        *expandInvocation([invocation, ctx], next) {
+            if (invocation.name === "Testing") {
+                return { segments: yield* handlers.expandTesting(invocation, ctx) };
+            }
+            if (invocation.name === "Test") {
+                return { segments: yield* handlers.expandTest(invocation, ctx) };
+            }
+            const assertion = ASSERTIONS.get(invocation.name);
+            if (assertion) {
+                return { segments: yield* handlers.expandAssertion(assertion, invocation, ctx) };
+            }
+            return yield* next(invocation, ctx);
+        },
+    });
+    yield* Execution.around({
+        *execute([executeOptions], next) {
+            // Fresh boundary collection per execution: outcomes reported by
+            // explicit <Testing> elements in THIS run decide this run's Result.
+            const boundaries = [];
+            yield* Test.around({
+                *boundary([outcome], nextBoundary) {
+                    boundaries.push(outcome);
+                    yield* nextBoundary(outcome);
+                },
+            });
+            // Confirmed full replay: durableRun returns the stored root result
+            // without re-expanding, so nothing would re-record. Restore the
+            // journaled testing records into the current collectors — through
+            // the same record/boundary operations live expansion uses, so every
+            // session collector and observer sees them in discovery order. A
+            // live or partial journal (no root Close) hydrates nothing;
+            // re-expansion records each result exactly once via its durable
+            // operation.
+            const replayed = yield* readCompletedRun(executeOptions.stream);
+            if (replayed) {
+                for (const result of replayed.results) {
+                    yield* record(result);
+                }
+                for (const outcome of replayed.boundaries) {
+                    yield* boundary(outcome);
+                }
+            }
+            const inner = yield* next(executeOptions);
+            return decorateCompletion(inner, () => {
+                const failed = boundaries.filter((b) => b.failed > 0);
+                if (failed.length > 0) {
+                    return new TestFailureError(`${failed.reduce((n, b) => n + b.failed, 0)} test(s) failed in <Testing>`);
+                }
+                if (boundaries.some((b) => b.tests === 0)) {
+                    return new TestFailureError("a <Testing> boundary discovered no tests");
+                }
+                return undefined;
+            });
+        },
+    });
+}
+/**
+ * Map an execution's completion: an `Ok` becomes `Err(failure())` when the
+ * policy reports one, after the inner completion — and therefore its closed
+ * output stream — settles. An existing `Err` passes through unchanged.
+ */
+export function decorateCompletion(inner, failure) {
+    return {
+        output: inner.output,
+        *[Symbol.iterator]() {
+            const result = yield* inner;
+            if (!result.ok) {
+                return result;
+            }
+            const error = failure();
+            if (error) {
+                return Err(error);
+            }
+            return result;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@executablemd/testing",
+  "version": "0.3.1",
+  "description": "Testing vocabulary for executable.md documents: <Testing>, <Test>, and assertion components.",
+  "homepage": "https://executable.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taras/executable.md.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/taras/executable.md/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    }
+  },
+  "scripts": {},
+  "dependencies": {
+    "@effectionx/context-api": "0.6.0",
+    "@effectionx/scope-eval": "0.1.3",
+    "@effectionx/timebox": "0.4.3",
+    "@executablemd/core": "^0.3.1",
+    "@executablemd/durable-streams": "^0.3.1",
+    "effection": "4.1.0-alpha.7",
+    "@std/assert": "npm:@jsr/std__assert@^1.0.17"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/types/_dnt.polyfills.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};

package/types/_dnt.shims.d.ts

@@ -0,0 +1 @@
+export declare const dntGlobalThis: Omit<typeof globalThis, never>;