@executablemd/testing 0.3.1 → 0.4.0

package/esm/core/src/frontmatter.js

@@ -1,98 +0,0 @@
-/**
- * Frontmatter parsing for component definitions (spec §4.1).
- *
- * Extracts meta values and input definitions from YAML frontmatter.
- * Supports shorthand syntax (value-as-default) and full JSON Schema subset.
- */
-/**
- * Parse raw frontmatter object into meta and inputs.
- *
- * - `inputs` key: declared input interface
- * - Everything else (or `meta` key with typed definitions): component metadata
- */
-export function parseFrontmatter(raw) {
-    const rawInputs = (raw["inputs"] ?? {});
-    const inputs = {};
-    // Reserved input names — consumed by the expansion engine, not
-    // available as component inputs. See spec §6.3 (named slots).
-    const RESERVED_INPUT_NAMES = new Set(["slot", "as"]);
-    for (const [key, value] of Object.entries(rawInputs)) {
-        if (RESERVED_INPUT_NAMES.has(key)) {
-            throw new Error(`"${key}" is a reserved prop name and cannot be declared as a component input`);
-        }
-        inputs[key] = normalizeInputDef(value);
-    }
-    // Meta: everything except 'inputs'
-    // If 'meta' key exists and contains typed definitions, resolve defaults
-    const meta = {};
-    if (raw["meta"] && typeof raw["meta"] === "object" && !Array.isArray(raw["meta"])) {
-        for (const [key, value] of Object.entries(raw["meta"])) {
-            if (isTypedDefinition(value)) {
-                meta[key] = value["default"];
-            }
-            else {
-                meta[key] = value;
-            }
-        }
-    }
-    else {
-        for (const [key, value] of Object.entries(raw)) {
-            if (key !== "inputs") {
-                meta[key] = value;
-            }
-        }
-    }
-    return { meta, inputs };
-}
-/**
- * Convert shorthand or full definition to InputDefinition.
- */
-export function normalizeInputDef(value) {
-    // Full definition: object with a 'type' key
-    if (isTypedDefinition(value)) {
-        const def = value;
-        const hasDefault = "default" in def;
-        return {
-            type: def["type"] ?? "any",
-            ...(hasDefault ? { default: def["default"] } : {}),
-            required: def["required"] === true || (!hasDefault && def["required"] !== false),
-            ...(def["enum"] ? { enum: def["enum"] } : {}),
-            ...(def["description"] ? { description: def["description"] } : {}),
-        };
-    }
-    // Shorthand: null means required with no default
-    if (value === null) {
-        return { type: "any", required: true };
-    }
-    // Shorthand: value is the default, type inferred
-    return {
-        type: inferType(value),
-        default: value,
-        required: false,
-    };
-}
-/**
- * Check if a value is a typed definition object (has a `type` key).
- */
-export function isTypedDefinition(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "type" in value);
-}
-/**
- * Infer the InputDefinition type from a JavaScript value.
- */
-export function inferType(value) {
-    if (typeof value === "string")
-        return "string";
-    if (typeof value === "number")
-        return "number";
-    if (typeof value === "boolean")
-        return "boolean";
-    if (Array.isArray(value))
-        return "array";
-    if (typeof value === "object" && value !== null)
-        return "object";
-    return "any";
-}

package/esm/core/src/heal.js

@@ -1,29 +0,0 @@
-/**
- * Markdown healing (spec §2.3).
- *
- * Closes unclosed markdown constructs (bold, italic, code spans, links, etc.)
- * at segment boundaries. Runs after the boundary scanner, before interpolation.
- *
- * Pure, synchronous, stateless — no journal entry, no Effection yield.
- */
-import remend from "remend";
-/**
- * Heal incomplete markdown constructs in a text segment.
- *
- * `htmlTags: false` — the boundary scanner owns JSX/HTML completeness;
- * remend owns markdown construct completeness.
- *
- * Remend strips a single trailing space (setext heading heuristic).
- * Text segments are inline fragments where trailing spaces are
- * significant word separators (e.g., `"Before "` before `<Content />`),
- * so we preserve and restore the trailing space when remend removes it.
- */
-export function healSegment(text) {
-    const hadTrailingSpace = text.length > 0 && text.endsWith(" ");
-    const healed = remend(text, { htmlTags: false });
-    // Restore trailing space if remend stripped it (setext heading heuristic)
-    if (hadTrailingSpace && healed.length > 0 && !healed.endsWith(" ")) {
-        return healed + " ";
-    }
-    return healed;
-}

package/esm/core/src/interpolate.js

@@ -1,39 +0,0 @@
-/**
- * Frontmatter interpolation: {meta.key} and {props.key} (spec §5.4).
- *
- * Runtime operation — deterministic from inputs, no journal entry.
- */
-/**
- * Replace `{meta.key}` and `{props.key}` references in text.
- *
- * Rules:
- * - Nested access via dot notation: `{meta.config.retry.count}`
- * - Missing key → empty string (no error)
- * - Arrays → comma-joined: `{meta.tags}` → `"alpha, beta"`
- * - Escaped braces: `\{not interpolated\}` → literal `{not interpolated}`
- */
-export function interpolate(text, meta, props) {
-    return text.replace(/\\?\{(meta|props)\.([^}]+)\}/g, (match, namespace, keyPath) => {
-        // Escaped brace
-        if (match.startsWith("\\")) {
-            return match.slice(1);
-        }
-        const source = namespace === "meta"
-            ? meta
-            : props;
-        const value = getNestedValue(source, keyPath);
-        if (value === undefined || value === null)
-            return "";
-        if (Array.isArray(value))
-            return value.join(", ");
-        return String(value);
-    });
-}
-/**
- * Access a nested value via dot-separated path.
- */
-export function getNestedValue(obj, path) {
-    return path
-        .split(".")
-        .reduce((current, key) => current?.[key], obj);
-}

package/esm/core/src/modifiers/daemon.js

@@ -1,60 +0,0 @@
-/**
- * The `daemon` terminal modifier factory (spec §3).
- *
- * Forks a long-running subprocess into the component's eval scope.
- * The process is alive for the duration of component expansion and
- * killed when the component scope closes. Unlike `exec`, it produces
- * no journal entry and never waits for the process to exit.
- *
- * Detection rule: daemon blocks are written as `bash daemon exec` —
- * `exec` satisfies the §3.2 detection rule but is never invoked since
- * `daemon` is the outermost terminal modifier and ignores `next`.
- */
-import { ephemeral } from "@executablemd/durable-streams";
-import { daemon } from "@effectionx/process";
-import { useCodeBlock } from "../modifiers.ts";
-import { evalScope } from "../component-api.ts";
-// ---------------------------------------------------------------------------
-// daemonFactory — terminal modifier (spec §3.3)
-// ---------------------------------------------------------------------------
-/**
- * Terminal modifier factory for long-running background processes.
- *
- * Ignores `next` — this is the terminal handler (like `exec` and `eval`).
- * Reads code block metadata via useCodeBlock() and the eval scope via
- * the contextual `evalScope` value.
- *
- * The block's content (already interpolated with eval bindings by the
- * expansion engine) is used to build the subprocess command. The command
- * is forked into the eval scope via `evalScope.eval()` — the subprocess
- * lives for the duration of component expansion.
- *
- * If the process exits prematurely, `daemon()` throws `DaemonExitError`,
- * which propagates through the eval scope to the document expansion.
- *
- * Daemon blocks produce no rendered output and no journal entry.
- */
-export const daemonFactory = (_params) => (_args, _next) => (function* () {
-    const ctx = yield* useCodeBlock();
-    // Bridge from Workflow (durable) to Operation (ephemeral) —
-    // daemon produces no journal entry, so all its effects are ephemeral.
-    const launchDaemon = {
-        *[Symbol.iterator]() {
-            const scope = yield* evalScope;
-            if (!scope) {
-                throw new Error("daemon requires a component eval scope; none is in scope.");
-            }
-            // The block content is a raw shell command (e.g. the body of a
-            // ```bash daemon exec``` block). Pass it directly to daemon()
-            // with shell:true so @effectionx/process invokes the system
-            // shell instead of splitting with shellwords — which would
-            // mangle commands containing nested quotes.
-            yield* scope.eval(function* () {
-                yield* daemon(ctx.content, { shell: true });
-            });
-        },
-    };
-    yield* ephemeral(launchDaemon);
-    // Control returns here immediately after the fork.
-    return { output: "", exitCode: 0, stderr: "" };
-})();

package/esm/core/src/modifiers/persist.js

@@ -1,35 +0,0 @@
-/**
- * The `persist` wrapping modifier factory (spec §7.1).
- *
- * Extends resource lifetime from block scope to the component's eval-scope.
- * By default, resources spawned inside a block's operation are scoped to
- * that block's execution — they are torn down when the block's generator
- * returns. With `persist`, the eval handler runs the compiled block inside
- * evalScope.eval(), which retains spawned resources in the persistent
- * EvalScope until the component finishes expanding.
- *
- * Implementation: persist installs the contextual `persistent` value middleware that
- * the eval handler reads. The eval handler then runs fn(env) inside
- * evalScope.eval() instead of directly. This avoids wrapping the entire
- * modifier chain (which includes durable effects that can't cross the
- * evalScope channel boundary).
- */
-import { scoped } from "effection";
-import { ephemeral } from "@executablemd/durable-streams";
-import { Component } from "../component-api.ts";
-// ---------------------------------------------------------------------------
-// persistFactory (spec §7.1)
-// ---------------------------------------------------------------------------
-/**
- * Wrapping modifier that marks a block for persistent resource lifetime.
- *
- * Makes the contextual `persistent` value answer true for the duration of the inner
- * chain. The eval handler reads this and routes the compiled block
- * execution through evalScope.eval() for resource retention.
- */
-export const persistFactory = (_params) => (_args, next) => (function* () {
-    return yield* ephemeral(scoped(function* () {
-        yield* Component.around({ persistent: () => true }, { at: "min" });
-        return yield* next();
-    }));
-})();

package/esm/core/src/modifiers/timeout.js

@@ -1,55 +0,0 @@
-/**
- * The `timeout` wrapping modifier factory (spec §7.3).
- *
- * Constrains a code block's execution time using timebox() from
- * @effectionx/timebox. If the block does not complete within the
- * specified duration, the factory throws an error.
- *
- * timebox() returns a Timeboxed<T> discriminated union — not a thrown
- * error. The factory checks .timeout and raises explicitly.
- */
-import { timebox } from "@effectionx/timebox";
-import { ephemeral } from "@executablemd/durable-streams";
-// ---------------------------------------------------------------------------
-// Duration parsing
-// ---------------------------------------------------------------------------
-/**
- * Parse a duration string into milliseconds.
- *
- * Supports:
- * - `500ms` → 500
- * - `30s`   → 30000
- * - `2m`    → 120000
- * - `500`   → 500 (raw number, treated as ms)
- */
-export function parseDuration(s) {
-    if (s.endsWith("ms"))
-        return parseInt(s, 10);
-    if (s.endsWith("m"))
-        return parseInt(s, 10) * 60_000;
-    if (s.endsWith("s"))
-        return parseInt(s, 10) * 1_000;
-    return parseInt(s, 10);
-}
-// ---------------------------------------------------------------------------
-// timeoutFactory (spec §7.3)
-// ---------------------------------------------------------------------------
-/**
- * Wrapping modifier that constrains block execution time.
- *
- * Usage: `timeout=30s eval` or `timeout=500ms eval`
- * Default: 30s if no params provided.
- *
- * The timebox() call is an Operation (yields Effect values), so it
- * must be bridged into the Workflow context via ephemeral(). The
- * inner next() call returns a CodeBlockWorkflow which is cast to
- * Operation for timebox compatibility.
- */
-export const timeoutFactory = (params) => (_args, next) => (function* () {
-    const ms = parseDuration(params ?? "30s");
-    const result = yield* ephemeral(timebox(ms, () => next()));
-    if (result.timeout) {
-        throw new Error(`eval block timed out after ${params ?? "30s"}`);
-    }
-    return result.value;
-})();

package/esm/core/src/modifiers.js

@@ -1,113 +0,0 @@
-/**
- * Modifier system — middleware chain for code block execution (spec §3.3).
- *
- * Each modifier in the info string is a middleware that wraps the next
- * handler in the chain. The rightmost modifier (exec/eval) is the terminal.
- *
- * Aligns with Effection v4.1's Middleware<TArgs, TReturn> pattern:
- * - CodeBlockContext is delivered via Effection Context (scope-inherited)
- * - Each modifier's params are captured in a factory closure
- * - The middleware signature is Middleware<[], CodeBlockWorkflow>
- */
-import { scoped } from "effection";
-import { ephemeral } from "@executablemd/durable-streams";
-import { combine } from "@effectionx/middleware";
-import { Component, codeBlock } from "./component-api.ts";
-/**
- * Read the current code block context.
- *
- * Ergonomic alias for the Component `codeBlock()` operation, bridged via
- * `ephemeral` so it can be `yield*`'d inside modifier handlers that run
- * within durable workflows.
- */
-export function useCodeBlock() {
-    return ephemeral(codeBlock());
-}
-/**
- * Create a new modifier registry, optionally inheriting from a parent.
- */
-export function createModifierRegistry(parent) {
-    const registry = new Map();
-    if (parent) {
-        for (const [name, factory] of parent) {
-            registry.set(name, factory);
-        }
-    }
-    return registry;
-}
-// ---------------------------------------------------------------------------
-// Chain composition (spec §3.3)
-// ---------------------------------------------------------------------------
-/**
- * Compose a modifier chain from the info string.
- *
- * Uses the reusable `combine()` primitive from `./middleware.ts` to
- * build the chain. Each modifier's factory is called with its parsed
- * params to produce a middleware, then all middlewares are combined.
- *
- * The chain is composed **left-to-right for wrapping order**: the
- * leftmost modifier is the outermost wrapper. `combine` handles the
- * right-to-left reduction internally.
- *
- * The `context` parameter is made available to handlers via scope-local
- * `Component.operations.codeBlock()` middleware, installed for the
- * duration of the chain execution and removed when its scope exits.
- */
-export function composeModifierChain(modifiers, context, registry) {
-    // deno-lint-ignore require-yield
-    const terminal = function* () {
-        throw new Error("No terminal modifier (exec/eval) in chain");
-    };
-    // Build the middleware array — each factory is called with its params
-    const middlewares = [];
-    for (const mod of modifiers) {
-        const factory = registry.get(mod.name);
-        if (!factory) {
-            const missingName = mod.name;
-            // deno-lint-ignore require-yield
-            return function* () {
-                throw new Error(`Unknown modifier: ${missingName}`);
-            };
-        }
-        middlewares.push(factory(mod.params));
-    }
-    // Combine all middlewares into a single middleware
-    const composed = combine(middlewares);
-    // Return a thunk that provides the code block contextually for the
-    // duration of the chain, then runs the composed middleware.
-    // The cast is safe because CodeBlockWorkflow yields DurableEffect
-    // values which extend Effect — structurally compatible with Operation.
-    return function* () {
-        return yield* ephemeral(scoped(function* () {
-            yield* Component.around({
-                // deno-lint-ignore require-yield
-                *codeBlock(_args, _next) {
-                    return context;
-                },
-            }, { at: "min" });
-            return yield* composed([], terminal);
-        }));
-    };
-}
-// ---------------------------------------------------------------------------
-// Command construction (spec §3.6)
-// ---------------------------------------------------------------------------
-/**
- * Build the command array for executing a code block.
- */
-export function buildCommand(language, content) {
-    switch (language.toLowerCase()) {
-        case "bash":
-        case "sh":
-            return ["bash", "-c", content];
-        case "python":
-        case "py":
-            return ["python", "-c", content];
-        case "node":
-        case "javascript":
-        case "js":
-            return ["node", "-e", content];
-        default:
-            return [language, "-c", content];
-    }
-}

package/esm/core/src/output/normalize.js

@@ -1,33 +0,0 @@
-/**
- * Whitespace normalization middleware (spec §9.4).
- *
- * Stateful middleware that tracks trailing newlines across output() calls.
- * Collapses doubled blank lines at segment boundaries without needing the
- * full document.
- *
- * Mutable closure state (trailingNewlines) is safe because the middleware
- * is scoped per useNormalizedOutput() call — one instance per document
- * run, not shared across concurrent scopes.
- */
-import { DocumentOutput } from "../api.ts";
-export function* useNormalizedOutput() {
-    let trailingNewlines = 0;
-    yield* DocumentOutput.around({
-        *output([text], next) {
-            let normalized = text;
-            // Strip trailing whitespace on each line
-            normalized = normalized.replace(/[ \t]+\n/g, "\n");
-            // Collapse leading newlines if previous write already ended
-            // with enough to form a blank line
-            if (trailingNewlines >= 2) {
-                normalized = normalized.replace(/^\n+/, "\n");
-            }
-            // Collapse runs of 3+ newlines within a single write
-            normalized = normalized.replace(/\n{3,}/g, "\n\n");
-            // Track trailing newlines for next call
-            const match = normalized.match(/\n+$/);
-            trailingNewlines = match ? match[0].length : 0;
-            yield* next(normalized);
-        },
-    });
-}

package/esm/core/src/output/terminal.js

@@ -1,20 +0,0 @@
-/**
- * Terminal ANSI formatting middleware (spec §9.5).
- *
- * Converts markdown text to ANSI-colored terminal text using marked-terminal.
- * Synchronous only — async: false, no promises.
- */
-import { Marked } from "marked";
-// @ts-ignore -- marked-terminal has no type declarations
-import { markedTerminal } from "marked-terminal";
-import { DocumentOutput } from "../api.ts";
-export function* useTerminalOutput() {
-    // markedTerminal() returns a marked extension object ({ renderer, useNewRenderer })
-    const marked = new Marked(markedTerminal());
-    yield* DocumentOutput.around({
-        *output([text], next) {
-            const formatted = marked.parse(text, { async: false });
-            yield* next(formatted);
-        },
-    });
-}

package/esm/core/src/render.js

@@ -1,30 +0,0 @@
-/**
- * Segment rendering — converts expanded segments to output string (spec §9).
- */
-/**
- * Render an array of expanded segments into a markdown string.
- */
-export function renderSegments(segments) {
-    return segments.map(renderSegment).join("");
-}
-/**
- * Render a single segment to its string representation.
- */
-export function renderSegment(segment) {
-    switch (segment.type) {
-        case "text":
-            return segment.content;
-        case "execOutput":
-            return segment.result.stdout;
-        case "error":
-            return `<!-- ERROR: ${segment.message} -->`;
-        case "component":
-            // Unexpanded component (shouldn't appear after expansion)
-            return `<!-- UNEXPANDED: <${segment.name} /> -->`;
-        case "codeBlock":
-            // Shouldn't appear after expansion (all executable blocks are processed)
-            return `\`\`\`${segment.language}\n${segment.content}\n\`\`\``;
-        default:
-            return "";
-    }
-}

package/esm/core/src/replay-stream.js

@@ -1,58 +0,0 @@
-/**
- * Replay-safe stream — the document output transport (spec §9).
- *
- * An unbuffered channel drops values sent before a consumer subscribes. The
- * replay stream retains its full event history so late subscribers receive
- * every chunk and the close value, and multiple subscribers each get the
- * complete sequence exactly once.
- *
- * Race-free by construction: delivery appends to the history and forwards to
- * every registered subscriber queue in one synchronous step, and a new
- * subscription replays the history into its own queue and registers for live
- * events before yielding — no event can fall between replay and registration.
- */
-import { createQueue, ensure } from "effection";
-export function createReplayStream() {
-    const history = [];
-    const subscribers = new Set();
-    let closed = false;
-    function replay(queue, event) {
-        if (event.done) {
-            queue.close(event.value);
-        }
-        else {
-            queue.add(event.value);
-        }
-    }
-    function deliver(event) {
-        if (closed) {
-            return;
-        }
-        closed = event.done === true;
-        history.push(event);
-        for (const queue of subscribers) {
-            replay(queue, event);
-        }
-    }
-    return {
-        // deno-lint-ignore require-yield
-        *send(value) {
-            deliver({ done: false, value });
-        },
-        // deno-lint-ignore require-yield
-        *close(value) {
-            deliver({ done: true, value });
-        },
-        *[Symbol.iterator]() {
-            const queue = createQueue();
-            for (const event of history) {
-                replay(queue, event);
-            }
-            subscribers.add(queue);
-            yield* ensure(() => {
-                subscribers.delete(queue);
-            });
-            return queue;
-        },
-    };
-}

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

@@ -1,45 +0,0 @@
-/**
- * The Sample Api — Effection Api for LLM inference.
- *
- * Provider components (e.g., DeepInfraProvider, OllamaProvider) install
- * middleware via `yield* Sample.around(...)` to route sample calls to
- * their inference server.
- *
- * The `<Sample>` component calls `Sample.operations.sample()` to send
- * content to the LLM.
- *
- * The core handler throws by default — middleware must be installed
- * before any `<Sample>` component runs.
- */
-import { createApi } from "@effectionx/context-api";
-/**
- * The Sample Api instance.
- *
- * Usage in provider components (eval blocks):
- * ```js
- * const scope = yield* useScope();
- * yield* Sample.around({
- *   *sample([context], next) {
- *   if (context.model !== undefined && context.model !== model) {
- *     return yield* next(context);
- *   }
- *   // ... call inference API ...
- *   return result;
- *   },
- * });
- * ```
- *
- * Usage in the Sample component:
- * ```js
- * const result = yield* Sample.operations.sample(context);
- * ```
- */
-export const Sample = createApi("Sample", {
-    // deno-lint-ignore require-yield
-    *sample(_context) {
-        throw new Error("Sample Api requires provider middleware — " +
-            "install a provider (e.g., DeepInfraProvider, OllamaProvider) or " +
-            "yield* Sample.around({ *sample([ctx], next) { ... } }) " +
-            "before using <Sample> components");
-    },
-});