@executablemd/testing 0.3.1 → 0.4.0

package/esm/core/src/execute.js

@@ -1,378 +0,0 @@
-/**
- * Entry point — execute (spec §7).
- *
- * Wires together the boundary scanner, component import, expansion engine,
- * modifier system, and journal infrastructure. `execute` is delivered
- * through the Execution Api so extensions can decorate the execution
- * lifecycle as middleware.
- *
- * Journal runtime integration is concentrated at execution boundaries.
- * See DEC-005 in specs/decisions.md.
- */
-import { Err, Ok, scoped, spawn, withResolvers, until } from "effection";
-import { createApi } from "@effectionx/context-api";
-import { durableRun, createDurableOperation, ephemeral, } from "@executablemd/durable-streams";
-import { exec, readTextFile, stat, cwd } from "@executablemd/runtime";
-import { createReplayStream } from "./replay-stream.ts";
-import { useDenoCompiler } from "./deno-compiler.ts";
-import { useTempFileCompiler } from "./temp-file-compiler.ts";
-import { scanSegments } from "./scanner.ts";
-import { parseFrontmatter } from "./frontmatter.ts";
-import { expandSegments, expandBody, bodyHasOutput, validateOutputPlacement, createBlockCounter, } from "./expand.ts";
-import { Component, importComponent } from "./component-api.ts";
-import { renderSegment } from "./render.ts";
-import { DocumentOutput } from "./api.ts";
-import { composeModifierChain, buildCommand, createModifierRegistry, useCodeBlock, } from "./modifiers.ts";
-import { evalFactory } from "./eval-handler.ts";
-import { persistFactory } from "./modifiers/persist.ts";
-import { timeoutFactory } from "./modifiers/timeout.ts";
-import { daemonFactory } from "./modifiers/daemon.ts";
-import { useEvalScope } from "@effectionx/scope-eval";
-import { Stdio } from "@effectionx/process";
-// Re-export gray-matter — we use it for YAML frontmatter extraction
-import matter from "gray-matter";
-// ---------------------------------------------------------------------------
-// durableImportComponent (spec §4.3)
-//
-// This is a Workflow<ComponentDefinition | FunctionComponentDefinition> —
-// it yields durable import effects and returns either markdown or function
-// component definitions.
-// See DEC-001, DEC-004 in specs/decisions.md.
-// ---------------------------------------------------------------------------
-function* durableImportComponent(name, rootDocPath, searchPaths) {
-    const result = (yield createDurableOperation({ type: "import_component", name }, function* () {
-        // Resolve the path — runs inside Operation context
-        let path;
-        if (name === "__root__" && rootDocPath) {
-            path = rootDocPath;
-        }
-        else {
-            path = yield* resolveComponentPath(name, searchPaths);
-        }
-        const content = yield* readTextFile(path);
-        return { path, content };
-    }));
-    // Function component: .ts file — import() the module
-    if (result.path.endsWith(".ts")) {
-        // Resolve to absolute path for dynamic import
-        const currentDir = yield* ephemeral(cwd());
-        const absolutePath = result.path.startsWith("/") ? result.path : `${currentDir}/${result.path}`;
-        const mod = (yield* ephemeral(until(import(`file://${absolutePath}`))));
-        const fn = mod.default;
-        if (typeof fn !== "function") {
-            throw new Error(`Function component "${name}" at ${result.path} must have a default export that is a generator function`);
-        }
-        const typedFn = fn;
-        const inputs = (mod.inputs ?? {});
-        return {
-            kind: "function",
-            name,
-            path: result.path,
-            inputs,
-            fn: typedFn,
-        };
-    }
-    // Markdown component: parse at runtime — deterministic from content
-    const parsed = matter(result.content);
-    const { meta, inputs } = parseFrontmatter(parsed.data);
-    // The markdown body is a verbatim suffix of the raw file, so the body start
-    // is computed by length — never by content search, which could false-match
-    // body text repeated inside frontmatter. The invariant check turns any
-    // gray-matter normalization surprise into a loud error instead of silently
-    // wrong source positions.
-    const bodyStart = result.content.length - parsed.content.length;
-    if (result.content.slice(bodyStart) !== parsed.content) {
-        throw new Error(`frontmatter parse did not preserve the markdown body verbatim: ${result.path}`);
-    }
-    let baseLine = 1;
-    for (let i = 0; i < bodyStart; i++) {
-        if (result.content[i] === "\n") {
-            baseLine++;
-        }
-    }
-    const bodySegments = scanSegments(parsed.content, {
-        path: result.path,
-        baseOffset: bodyStart,
-        baseLine,
-    });
-    return {
-        kind: "markdown",
-        name,
-        path: result.path,
-        meta,
-        inputs,
-        bodySegments,
-    };
-}
-// ---------------------------------------------------------------------------
-// Component path resolution — runs inside Operation context (not Workflow)
-// ---------------------------------------------------------------------------
-function* resolveComponentPath(name, searchPaths) {
-    const baseName = name.replace(/\./g, "/");
-    for (const dir of searchPaths) {
-        // Try {dir}/{Name}.md (backward compat — .md wins over .ts)
-        const mdCandidate = normalizePath(dir === "." ? `${baseName}.md` : `${dir}/${baseName}.md`);
-        const mdStat = yield* stat(mdCandidate);
-        if (mdStat.exists && mdStat.isFile) {
-            return mdCandidate;
-        }
-        // Try {dir}/{Name}.ts (function component)
-        const tsCandidate = normalizePath(dir === "." ? `${baseName}.ts` : `${dir}/${baseName}.ts`);
-        const tsStat = yield* stat(tsCandidate);
-        if (tsStat.exists && tsStat.isFile) {
-            return tsCandidate;
-        }
-        // Try {dir}/{Name}/index.md
-        const indexMdCandidate = normalizePath(dir === "." ? `${baseName}/index.md` : `${dir}/${baseName}/index.md`);
-        const indexMdStat = yield* stat(indexMdCandidate);
-        if (indexMdStat.exists && indexMdStat.isFile) {
-            return indexMdCandidate;
-        }
-        // Try {dir}/{Name}/index.ts
-        const indexTsCandidate = normalizePath(dir === "." ? `${baseName}/index.ts` : `${dir}/${baseName}/index.ts`);
-        const indexTsStat = yield* stat(indexTsCandidate);
-        if (indexTsStat.exists && indexTsStat.isFile) {
-            return indexTsCandidate;
-        }
-    }
-    throw new Error(`Cannot resolve component: ${name} (searched: ${searchPaths.join(", ")})`);
-}
-/** Strip leading ./ from paths for workspace-relative normalization. */
-function normalizePath(path) {
-    return path.replace(/^\.\//, "");
-}
-// ---------------------------------------------------------------------------
-// Built-in modifier handlers (spec §3.3)
-//
-// Modifier handlers return Workflow<CodeBlockResult> since terminal
-// handlers (exec) yield DurableEffects. See DEC-003 in specs/decisions.md.
-// ---------------------------------------------------------------------------
-const execFactory = (_params) => (_args, _next) => (function* () {
-    const context = yield* useCodeBlock();
-    const command = buildCommand(context.language, context.content);
-    const result = (yield createDurableOperation({
-        type: "exec",
-        name: `exec:${context.content.slice(0, 40).replace(/\n/g, " ")}`,
-        command: command,
-    }, function* () {
-        const execResult = yield* exec({
-            command,
-            timeout: 30_000,
-        });
-        return execResult;
-    }));
-    return {
-        output: result.stdout,
-        exitCode: result.exitCode,
-        stderr: result.stderr,
-    };
-})();
-const silentFactory = (_params) => (_args, next) => (function* () {
-    yield* next(); // inner chain runs — exec journals its result
-    return { output: "", exitCode: 0, stderr: "" };
-})();
-// ---------------------------------------------------------------------------
-// Document workflow (spec §7.1)
-//
-// This is a Workflow<string> — it yields DurableEffects (via
-// durableImportComponent, exec handler). Non-journaled work
-// (interpolation, validation, parsing) runs as synchronous function
-// calls inside the expansion engine. See DEC-002.
-// ---------------------------------------------------------------------------
-function* documentWorkflow() {
-    // Import root — same pipeline as any component. The provider middleware
-    // installed by execute maps "__root__" to the document path. The
-    // ephemeral() wrapper bridges typing only — the import inside remains a
-    // durable, journaled operation.
-    const root = yield* ephemeral(importComponent("__root__"));
-    if (root.kind === "function") {
-        throw new Error("Root document must be a markdown file, not a function component");
-    }
-    const rootEnv = { values: {} };
-    // Per-root-segment emission loop (spec §9).
-    // Mutable counter preserves deterministic blockIds across
-    // per-segment expansion calls (see spec §6.1).
-    const counter = createBlockCounter();
-    // The root binding environment is installed as scope-local middleware
-    // around the entire loop so all segments share it. Resources spawned by
-    // `persist` blocks are retained in the eval scope until expansion
-    // completes, then torn down.
-    const scopedExpansion = scoped(function* () {
-        yield* Component.around({ env: () => rootEnv }, { at: "min" });
-        // Structural preflight (spec §6.9): a root with misplaced <Output>
-        // executes no body side effects; the aggregate diagnostic renders as a
-        // comment (root policy is "collect").
-        const placementError = validateOutputPlacement(root.bodySegments);
-        if (placementError) {
-            const text = renderSegment(placementError);
-            yield* ephemeral(DocumentOutput.operations.output(text));
-            return text;
-        }
-        // A root declaring top-level <Output> buffers completely (spec §5.4):
-        // execute the whole body, then emit the selected regions only after
-        // successful completion. A documentation failure throws before any emit,
-        // so no partial output is produced.
-        if (bodyHasOutput(root.bodySegments)) {
-            const expanded = yield* expandBody(root.bodySegments, [], root.meta, {}, new Set(), counter, undefined);
-            const text = expanded.map(renderSegment).join("");
-            // An empty buffered root emits no output event.
-            if (text) {
-                yield* ephemeral(DocumentOutput.operations.output(text));
-            }
-            return text;
-        }
-        // Per-root-segment emission loop for roots without <Output> (spec §5.4).
-        const chunks = [];
-        for (const segment of root.bodySegments) {
-            const expanded = yield* expandSegments([segment], root.meta, {}, new Set(), counter);
-            for (const resolved of expanded) {
-                const text = renderSegment(resolved);
-                if (text) {
-                    // Emit through the Document Output Api (spec §9).
-                    // ephemeral() bridges from Workflow (durable) to Operation
-                    // (non-durable) — output emission is a derived side effect,
-                    // not journaled.
-                    yield* ephemeral(DocumentOutput.operations.output(text));
-                    chunks.push(text);
-                }
-            }
-        }
-        return chunks.join("");
-    });
-    return yield* ephemeral(scopedExpansion);
-}
-/**
- * Execute a markdown document as a durable workflow.
- *
- * Returns a `DocumentExecution` — an operation you can `yield*` for the
- * completion `Result<string>`, with a `.output` stream for chunk-by-chunk
- * consumption. Once the handle exists, completion never throws: every
- * later failure — document, infrastructure, or policy middleware — closes
- * `output` (with the complete or partial rendered text) and resolves
- * `Err(error)`.
- *
- * Simple — get the outcome:
- *
- * ```ts
- * const execution = yield* execute(options);
- * const result = yield* execution;
- * if (result.ok) {
- *   console.log(result.value);
- * }
- * ```
- *
- * Streaming — consume chunks as they arrive:
- *
- * ```ts
- * const execution = yield* execute(options);
- * const output = yield* forEach(function* (chunk) {
- *   process.stdout.write(chunk);
- * }, execution.output);
- * ```
- */
-function* executeDocument(options) {
-    const { docPath, stream, componentDirs = ["components", "."], modifiers: customModifiers = {}, } = options;
-    // Build modifier registry — pure data, no scope side effects.
-    const registry = createModifierRegistry();
-    registry.set("exec", execFactory);
-    registry.set("silent", silentFactory);
-    registry.set("eval", evalFactory);
-    registry.set("persist", persistFactory);
-    registry.set("timeout", timeoutFactory);
-    registry.set("daemon", daemonFactory);
-    for (const [name, handler] of Object.entries(customModifiers)) {
-        registry.set(name, handler);
-    }
-    // ---------------------------------------------------------------------------
-    // Document execution.
-    //
-    // The workflow runs in a spawned child scope that contains all
-    // execution state: eval context/scope and the
-    // DocumentOutput→channel bridge. Nothing leaks onto the caller's scope.
-    //
-    // withResolvers captures the completion result so `yield* execution`
-    // can wait for it without needing to await the spawned Task directly
-    // (which would propagate errors through scope teardown).
-    // ---------------------------------------------------------------------------
-    // Replay-safe transport: late subscribers receive every chunk and the
-    // close value, so subscription readiness before first emission is never
-    // required (spec §9; see replay-stream.ts).
-    const channel = createReplayStream();
-    const { operation, resolve } = withResolvers();
-    yield* spawn(function* () {
-        let emitted = false;
-        let emittedText = "";
-        // The ENTIRE setup and workflow sit inside one error boundary: once the
-        // handle exists, any failure closes output (with whatever rendered so
-        // far) and resolves Err — completion never throws.
-        try {
-            // Install platform-appropriate compiler middleware
-            // deno-lint-ignore no-explicit-any
-            if (typeof globalThis.Deno !== "undefined") {
-                yield* useDenoCompiler();
-            }
-            else {
-                yield* useTempFileCompiler();
-            }
-            // DocumentOutput → channel bridge (innermost middleware — output flows
-            // through caller-installed normalize/terminal middleware first, then here).
-            yield* DocumentOutput.around({
-                *output([text]) {
-                    emitted = true;
-                    emittedText += text;
-                    yield* channel.send(text);
-                },
-            });
-            yield* Stdio.around({
-                *stdout() { },
-                *stderr() { },
-            });
-            // Create per-document eval scope (spec §3.1).
-            // Created in the same scope as durableRun so that DurableCtx
-            // (set by durableRun) is visible to eval code that calls
-            // renderChildren → importComponent → createDurableOperation.
-            const rootEvalScope = yield* useEvalScope();
-            // Install the document's runtime Component providers before durableRun
-            // so the workflow inherits them: component import, modifier execution,
-            // and the root eval scope.
-            yield* Component.around({
-                *importComponent([name], _next) {
-                    return yield* durableImportComponent(name, name === "__root__" ? docPath : undefined, componentDirs);
-                },
-                *applyModifiers([modifiers, context], _next) {
-                    const chain = composeModifierChain(modifiers, context, registry);
-                    return yield* chain();
-                },
-                evalScope: () => rootEvalScope,
-            }, { at: "min" });
-            const output = yield* durableRun(() => documentWorkflow(), {
-                stream,
-            });
-            // Preserve output for any synchronous completion path that did not emit
-            // through the streaming API.
-            if (!emitted && output) {
-                yield* DocumentOutput.operations.output(output);
-            }
-            yield* channel.close(output);
-            resolve(Ok(output));
-        }
-        catch (error) {
-            // Close with everything already emitted — diagnostics produced before
-            // an abort stay visible to consumers of the close value.
-            yield* channel.close(emittedText);
-            resolve(Err(error instanceof Error ? error : new Error(String(error))));
-        }
-    });
-    return {
-        *[Symbol.iterator]() {
-            return yield* operation;
-        },
-        output: channel,
-    };
-}
-export const Execution = createApi("Execution", {
-    *execute(options) {
-        return yield* executeDocument(options);
-    },
-});
-export const { execute } = Execution.operations;