@executablemd/testing 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Mankovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/esm/core/mod.js

@@ -0,0 +1,55 @@
+/**
+ * Executable MDX — public API.
+ *
+ * Treats markdown documents as durable workflows: text is emitted immediately,
+ * component references are resolved and expanded recursively, and code blocks
+ * marked as executable are run via durableExec.
+ */
+export { ephemeral } from "@executablemd/durable-streams";
+export { healSegment } from "./src/heal.ts";
+export { combine } from "@effectionx/middleware";
+export { useCodeBlock } from "./src/modifiers.ts";
+export { Component, importComponent, applyModifiers, raise, env, evalScope, expandInvocation, codeBlock, persistent, content, } from "./src/component-api.ts";
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+export { renderSegments } from "./src/render.ts";
+// ---------------------------------------------------------------------------
+// Replay-safe stream
+// ---------------------------------------------------------------------------
+export { createReplayStream } from "./src/replay-stream.ts";
+export { compileBlock } from "./src/eval-context.ts";
+// ---------------------------------------------------------------------------
+// executable.md Globals (for generated eval modules)
+// ---------------------------------------------------------------------------
+export { useContent } from "./src/content-context.ts";
+export { Sample } from "./src/sample-api.ts";
+export { evalFactory } from "./src/eval-handler.ts";
+export { persistFactory } from "./src/modifiers/persist.ts";
+export { timeoutFactory, parseDuration } from "./src/modifiers/timeout.ts";
+export { daemonFactory } from "./src/modifiers/daemon.ts";
+// ---------------------------------------------------------------------------
+// Eval binding interpolation
+// ---------------------------------------------------------------------------
+export { interpolateEvalBindings } from "./src/eval-interpolate.ts";
+// ---------------------------------------------------------------------------
+// Port allocation
+// ---------------------------------------------------------------------------
+export { findFreePort } from "@executablemd/runtime";
+export { transformBlock, serializeExports, isJson } from "./src/eval-transform.ts";
+// ---------------------------------------------------------------------------
+// Output Api & middleware
+// ---------------------------------------------------------------------------
+export { DocumentOutput } from "./src/api.ts";
+export { useNormalizedOutput } from "./src/output/normalize.ts";
+export { useTerminalOutput } from "./src/output/terminal.ts";
+// ---------------------------------------------------------------------------
+// Document runner
+// ---------------------------------------------------------------------------
+export { execute, Execution } from "./src/execute.ts";
+export { useDenoCompiler } from "./src/deno-compiler.ts";
+export { useTempFileCompiler } from "./src/temp-file-compiler.ts";
+// ---------------------------------------------------------------------------
+// Stream consumption
+// ---------------------------------------------------------------------------
+export { collect } from "./src/collect.ts";

package/esm/core/src/api.js

@@ -0,0 +1,31 @@
+/**
+ * Document Output Api — Effection Api for streaming document output (spec §9).
+ *
+ * A single Api with one operation: `output`. The core handler is a no-op.
+ * Behavior comes from middleware installed via `yield* DocumentOutput.around(...)`
+ * and channel delivery.
+ *
+ * Call sites use `DocumentOutput.operations.output(text)` inside `yield* ephemeral(...)`.
+ */
+import { createApi } from "@effectionx/context-api";
+/**
+ * The Document Output Api instance.
+ *
+ * Usage in middleware:
+ * ```js
+ * yield* DocumentOutput.around({
+ *   *output([text], next) {
+ *     const transformed = transform(text);
+ *     yield* next(transformed);
+ *   },
+ * });
+ * ```
+ *
+ * Usage in the emission loop:
+ * ```js
+ * yield* ephemeral(DocumentOutput.operations.output(text));
+ * ```
+ */
+export const DocumentOutput = createApi("DocumentOutput", {
+    *output(_text) { },
+});

package/esm/core/src/collect.js

@@ -0,0 +1,24 @@
+/**
+ * collect — wait for a document execution to complete and return the output.
+ *
+ * Convenience wrapper that unwraps the completion `Result<string>`:
+ * the output string on `Ok`, a throw on `Err`.
+ *
+ * ```ts
+ * const output = yield* collect(yield* execute(options));
+ * ```
+ */
+/**
+ * Wait for a document execution to complete and return the full output.
+ * Throws the failure when the execution completed with `Err`.
+ *
+ * @param execution - A `DocumentExecution` as returned by `execute`.
+ * @returns The full output string.
+ */
+export function* collect(execution) {
+    const result = yield* execution;
+    if (!result.ok) {
+        throw result.error;
+    }
+    return result.value;
+}

package/esm/core/src/component-api.js

@@ -0,0 +1,47 @@
+/**
+ * Component Api — contextual operations for component expansion.
+ *
+ * One public Api replaces the former dependency container (ExpansionContext)
+ * and raw Effection context keys. Context-dependent behavior is installed as
+ * scope-local middleware via `Component.around(...)`:
+ *
+ * - Runtime implementations (document import, modifier execution, component
+ *   state) install at `{ at: "min" }`. Middleware installed in a nested scope
+ *   runs before inherited middleware, so a component that installs its own
+ *   `env` shadows its ancestors without leaking into siblings — install
+ *   inside `scoped()` for automatic removal.
+ * - Caller instrumentation and overrides wrap at the default `"max"`.
+ */
+import { createApi } from "@effectionx/context-api";
+export const Component = createApi("Component", {
+    // deno-lint-ignore require-yield
+    *importComponent(name) {
+        throw new Error(`Component.importComponent("${name}") has no provider. Install one with ` +
+            `Component.around({ importComponent }, { at: "min" }) before expansion.`);
+    },
+    // deno-lint-ignore require-yield
+    *applyModifiers(_modifiers, block) {
+        throw new Error(`Component.applyModifiers() has no provider for block "${block.blockId}". Install one ` +
+            `with Component.around({ applyModifiers }, { at: "min" }) before expansion.`);
+    },
+    // deno-lint-ignore require-yield
+    *raise(error) {
+        return error;
+    },
+    env: undefined,
+    evalScope: undefined,
+    // deno-lint-ignore require-yield
+    *expandInvocation() {
+        return undefined;
+    },
+    // deno-lint-ignore require-yield
+    *codeBlock() {
+        throw new Error("Component.codeBlock() has no provider: no code block is executing in this scope.");
+    },
+    persistent: false,
+    // deno-lint-ignore require-yield
+    *content(_slot) {
+        throw new Error("Component.content() has no provider: not inside a function component invocation.");
+    },
+});
+export const { importComponent, applyModifiers, raise, env, evalScope, expandInvocation, codeBlock, persistent, content, } = Component.operations;

package/esm/core/src/content-context.js

@@ -0,0 +1,23 @@
+/**
+ * useContent() — the function component equivalent of `<Content />` in
+ * markdown components. Ergonomic alias for the Component `content()`
+ * operation; the expansion engine installs the slot-rendering middleware
+ * around each function component invocation.
+ */
+import { content } from "./component-api.ts";
+/**
+ * Render children content from the invoking component.
+ *
+ * @param slotName - Optional slot name. If provided, renders only the
+ *   content assigned to that slot (matching `<Content slot="name" />`).
+ *   If omitted, renders the default slot.
+ *
+ * @example
+ * ```ts
+ * const body = yield* useContent();
+ * const header = yield* useContent("header");
+ * ```
+ */
+export function useContent(slotName) {
+    return content(slotName);
+}

package/esm/core/src/deno-compiler.js

@@ -0,0 +1,51 @@
+/**
+ * Deno-specific eval block compiler middleware.
+ *
+ * Compiles eval block source into generator functions via data: URIs.
+ * Standard imports (Effection, executable.md APIs) are captured in the middleware
+ * closure — they are not part of the Compiler API interface.
+ *
+ * Install via `yield* useDenoCompiler()` inside a document execution
+ * scope before any eval blocks are processed.
+ */
+import { call } from "effection";
+import { API } from "@executablemd/runtime";
+// STANDARD_IMPORTS below resolve at runtime from generated eval modules;
+// without these static anchors, `deno compile --exclude-unused-npm` prunes
+// the packages from the binary and every eval block using them fails.
+import "@effectionx/converge";
+import "@effectionx/fetch";
+/**
+ * Standard import statements prepended to every generated eval module.
+ * Captured in the middleware closure — not exposed on the public API.
+ */
+const STANDARD_IMPORTS = [
+    'import { sleep, spawn, call, resource, useScope, createChannel, each, suspend, createSignal } from "effection";',
+    'import { when } from "@effectionx/converge";',
+    'import { fetch } from "@effectionx/fetch";',
+    'import { useContent, Sample } from "@executablemd/core";',
+    'import { findFreePort } from "@executablemd/runtime";',
+];
+/**
+ * Install the Deno data: URI compiler as middleware on the current scope.
+ *
+ * Must be called inside an Effection scope (e.g., inside `execute`'s
+ * spawned task) before any eval blocks execute.
+ */
+export function* useDenoCompiler() {
+    yield* API.Compiler.around({
+        *compile([source, options], next) {
+            void next; // terminal middleware — does not delegate
+            const userImports = options?.imports ?? [];
+            const allImports = [...STANDARD_IMPORTS, ...userImports];
+            const importLines = allImports.join("\n");
+            const moduleSource = [importLines, `export default function*(env) {`, source, `}`].join("\n");
+            const dataUri = `data:application/typescript,${encodeURIComponent(moduleSource)}`;
+            const mod = yield* call(() => import(dataUri));
+            if (typeof mod.default !== "function") {
+                throw new Error(`useDenoCompiler: expected default export to be a generator function, got ${typeof mod.default}`);
+            }
+            return mod.default;
+        },
+    });
+}

package/esm/core/src/errors.js

@@ -0,0 +1,13 @@
+/**
+ * Thrown by suppressed-documentation raise middleware (spec §6.9). Generic
+ * catches in the engine rethrow it instead of converting it into an
+ * ErrorSegment, so documentation fail-fast is never swallowed.
+ */
+export class DocumentationError extends Error {
+    segment;
+    constructor(segment) {
+        super(segment.message);
+        this.name = "DocumentationError";
+        this.segment = segment;
+    }
+}

package/esm/core/src/eval-context.js

@@ -0,0 +1,13 @@
+/**
+ * Eval block compilation (spec §5).
+ */
+import { compile as runtimeCompile } from "@executablemd/runtime";
+/**
+ * Compile transformed source code into a generator function.
+ *
+ * Delegates to `@executablemd/runtime` so platform-specific
+ * compilation can be provided via API.Compiler middleware.
+ */
+export function compileBlock(transformedBodyCode, userImports) {
+    return runtimeCompile(transformedBodyCode, { imports: userImports });
+}

package/esm/core/src/eval-handler.js

@@ -0,0 +1,79 @@
+import { createDurableOperation, ephemeral } from "@executablemd/durable-streams";
+import { unbox } from "@effectionx/scope-eval";
+import { useCodeBlock } from "./modifiers.ts";
+import { env, evalScope, persistent } from "./component-api.ts";
+import { compileBlock } from "./eval-context.ts";
+import { transformBlock, serializeExports } from "./eval-transform.ts";
+// ---------------------------------------------------------------------------
+// evalFactory — terminal modifier (spec §6.2)
+// ---------------------------------------------------------------------------
+export const evalFactory = (_params) => (_args, _next) => (function* () {
+    const ctx = yield* useCodeBlock();
+    const evalEnv = yield* ephemeral(env);
+    if (!evalEnv) {
+        throw new Error(`eval block "${ctx.blockId}" requires a binding environment; none is in scope.`);
+    }
+    const persist = yield* ephemeral(persistent);
+    // Inject output() function into env so eval blocks can produce
+    // rendered output. The function is a plain synchronous call:
+    //   output("some text")
+    // The mutable ref is block-local; serializeExports silently
+    // omits non-JSON values (functions), so output won't pollute
+    // the journal. The output text itself is journaled alongside
+    // exports as __output.
+    const outputRef = { text: "" };
+    evalEnv.values.output = (text) => {
+        outputRef.text = String(text);
+    };
+    const transformed = transformBlock(ctx.content, ctx.blockId, Object.keys(evalEnv.values));
+    const bindings = serializeExports(evalEnv.values, transformed.imports);
+    const result = (yield createDurableOperation({
+        type: "eval",
+        name: `eval:${ctx.blockId}`,
+        ...(ctx.language ? { language: ctx.language } : {}),
+    }, function* () {
+        // Merge incoming bindings snapshot into env before execution
+        Object.assign(evalEnv.values, bindings);
+        // Compile the eval block via data: URI module import.
+        // compileBlock is async (returns Operation) — it generates a
+        // TypeScript module and imports it via data: URI.
+        const fn = yield* compileBlock(transformed.code, transformed.userImports ?? []);
+        if (persist) {
+            // Persist mode: run the compiled block inside the eval scope
+            // so spawned resources are retained in the persistent EvalScope.
+            const scope = yield* evalScope;
+            if (!scope) {
+                throw new Error(`persist eval block "${ctx.blockId}" requires a component eval scope; none is in scope.`);
+            }
+            const blockResult = yield* scope.eval(() => fn(evalEnv.values));
+            const returnValue = unbox(blockResult);
+            if (!outputRef.text && returnValue != null) {
+                outputRef.text = String(returnValue);
+            }
+        }
+        else {
+            // Normal mode: run the compiled block in the current scope.
+            // Resources are torn down when this operation completes.
+            const returnValue = yield* fn(evalEnv.values);
+            if (!outputRef.text && returnValue != null) {
+                outputRef.text = String(returnValue);
+            }
+        }
+        const exports = serializeExports(evalEnv.values, transformed.exports);
+        if (outputRef.text) {
+            exports.__output = outputRef.text;
+        }
+        return { value: exports };
+    }));
+    if (result.value && typeof result.value === "object") {
+        const restored = result.value;
+        // Extract __output before merging into env
+        if (typeof restored.__output === "string") {
+            outputRef.text = restored.__output;
+        }
+        // Remove __output from exports before assigning to env
+        const { __output: _, ...exports } = restored;
+        Object.assign(evalEnv.values, exports);
+    }
+    return { output: outputRef.text, exitCode: 0, stderr: "" };
+})();

package/esm/core/src/eval-interpolate.js

@@ -0,0 +1,63 @@
+/**
+ * Eval binding interpolation (spec §6.6).
+ *
+ * Substitutes `{name}` and `{name.path.chain}` references in content
+ * with values from the eval binding environment (`env.values`). This
+ * runs in the expansion engine for both code block content and text
+ * segments.
+ *
+ * References use JavaScript identifier syntax with optional dot paths:
+ *   /\{([a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*)\}/g
+ *
+ * The first segment of a dotted path must be a key in `env.values`.
+ * Subsequent segments traverse nested properties. If any intermediate
+ * value is null/undefined, the reference is left verbatim.
+ *
+ * No collision with `{meta.key}` / `{props.key}`: those are consumed
+ * by the `interpolate()` pass which runs first. By the time this
+ * function runs, namespaced references are already resolved.
+ *
+ * If `env.values` has no key matching the root reference, it is left
+ * verbatim. Non-string values are converted via `String()`.
+ *
+ * Escaped braces (`\{name}`) are preserved as literal `{name}` in the
+ * output — the backslash is consumed. This is consistent with
+ * `interpolate()` which handles `\{meta.key}` the same way.
+ */
+const BARE_BINDING_RE = /\{([a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*)\}/g;
+/**
+ * Unicode private-use placeholder for escaped opening braces.
+ * Used to protect `\{` from interpolation, then restored as `{`.
+ */
+const ESCAPED_BRACE_PLACEHOLDER = "\uE000";
+/**
+ * Replace bare `{name}` references with values from the binding environment.
+ * Respects `\{` escaping — `\{name}` is left as literal `{name}`.
+ *
+ * @param content - The content to interpolate
+ * @param bindings - The current eval binding environment (env.values)
+ * @returns Content with resolved bindings substituted
+ */
+export function interpolateEvalBindings(content, bindings) {
+    // Protect escaped braces: \{ → placeholder
+    const escaped = content.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
+    // Run interpolation on the protected content.
+    // Supports dotted paths: {pr.meta.number} traverses bindings.pr.meta.number
+    const interpolated = escaped.replace(BARE_BINDING_RE, (match, key) => {
+        const parts = key.split(".");
+        if (!(parts[0] in bindings))
+            return match;
+        let value = bindings;
+        for (let i = 0; i < parts.length; i++) {
+            if (value == null || typeof value !== "object")
+                return match;
+            const obj = value;
+            if (i < parts.length - 1 && !(parts[i] in obj))
+                return match;
+            value = obj[parts[i]];
+        }
+        return String(value);
+    });
+    // Restore escaped braces: placeholder → literal {
+    return interpolated.replaceAll(ESCAPED_BRACE_PLACEHOLDER, "{");
+}