@executablemd/testing 0.3.1 → 0.4.0

package/esm/runtime/apis.js

@@ -1,237 +0,0 @@
-/**
- * Runtime Context APIs — platform I/O operations with pluggable middleware.
- *
- * Five domain-specific context APIs built on `@effectionx/context-api`.
- * Each API provides default Node.js implementations. Use `.around()` to
- * install middleware (mocking, instrumentation, sandboxing) scoped to the
- * current Effection scope.
- *
- * ## Architecture
- *
- * Import operation functions for normal calls, and use `API` only when
- * installing middleware with `.around()`:
- *
- * ```typescript
- * import { readTextFile, stat, API } from "@executablemd/runtime";
- *
- * // normal calls
- * const file = yield* readTextFile("doc.md");
- *
- * // middleware
- * yield* API.Fs.around({
- *   *readTextFile([path], next) {
- *     return yield* next(path);
- *   },
- * });
- * ```
- *
- * ## Why four separate APIs?
- *
- * - **Process** — subprocess lifecycle has its own cancellation semantics
- *   (killing processes on scope teardown). Middleware targets exec only.
- * - **Fs** — readTextFile, stat, and glob form a cohesive file-IO surface
- *   used together for component resolution and replay guards.
- * - **Fetch** — HTTP has distinct timeout/body/abort semantics. Merging
- *   with Fs or Process would blur cancellation boundaries.
- * - **Env** — synchronous host metadata (env vars, platform). Kept as a
- *   context-api despite being sync because tests use `.around()` to mock
- *   platform/env for deterministic replay testing.
- *
- * ## Middleware
- *
- * ```typescript
- * yield* API.Fs.around({
- *   *readTextFile([path], next) {
- *     return "mocked content";
- *   },
- * });
- * ```
- *
- * Middleware is **scoped** — it only affects operations within the
- * current Effection scope and its children. Install before calling
- * `execute()` or `durableRun()`.
- *
- * ## Test stubs
- *
- * Common stubs are provided by `@executablemd/runtime/test`:
- * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
- */
-import { createApi } from "@effectionx/context-api";
-import { relative, sep } from "node:path";
-import process from "node:process";
-import { fetch as effectionFetch } from "@effectionx/fetch";
-import { readTextFile as fsReadTextFile, stat as fsStat, globToRegExp, walk } from "@effectionx/fs";
-import { exec as processExec } from "@effectionx/process";
-import { each, race, sleep } from "effection";
-// ---------------------------------------------------------------------------
-// Private helpers
-// ---------------------------------------------------------------------------
-function* withTimeout(label, timeout, operation) {
-    if (timeout === undefined) {
-        return yield* operation;
-    }
-    if (!Number.isFinite(timeout) || timeout < 0) {
-        throw new Error(`${label}: timeout must be a non-negative finite number`);
-    }
-    return (yield* race([
-        operation,
-        (function* () {
-            yield* sleep(timeout);
-            throw new Error(`${label} timed out after ${timeout}ms`);
-        })(),
-    ]));
-}
-// ---------------------------------------------------------------------------
-// Context APIs
-// ---------------------------------------------------------------------------
-export const API = {
-    /**
-     * Subprocess execution.
-     *
-     * Default implementation uses `@effectionx/process`.
-     * Cancellation kills the process via Effection scope teardown.
-     */
-    Process: createApi("runtime.process", {
-        *exec(options) {
-            const { command, cwd, env, timeout } = options;
-            const [cmd, ...args] = command;
-            if (!cmd) {
-                throw new Error("exec: command array must not be empty");
-            }
-            const result = yield* withTimeout(`exec(${cmd})`, timeout, processExec(cmd, {
-                arguments: args,
-                cwd,
-                env,
-            }).join());
-            return {
-                exitCode: result.code ?? 1,
-                stdout: result.stdout,
-                stderr: result.stderr,
-            };
-        },
-    }),
-    /**
-     * Filesystem operations.
-     *
-     * Default implementation uses `@effectionx/fs`.
-     */
-    Fs: createApi("runtime.fs", {
-        *readTextFile(path) {
-            return yield* fsReadTextFile(path);
-        },
-        *stat(path) {
-            try {
-                const s = yield* fsStat(path);
-                return {
-                    exists: true,
-                    isFile: s.isFile(),
-                    isDirectory: s.isDirectory(),
-                };
-            }
-            catch (err) {
-                if (err.code === "ENOENT") {
-                    return { exists: false, isFile: false, isDirectory: false };
-                }
-                throw err;
-            }
-        },
-        *glob(options) {
-            const { patterns, root, exclude = [] } = options;
-            const results = [];
-            // Convert include/exclude patterns to RegExp for matching
-            // against relative paths from root
-            const includeRegexes = patterns.map((p) => globToRegExp(p, { extended: true, globstar: true }));
-            const excludeRegexes = exclude.map((e) => globToRegExp(e, { extended: true, globstar: true }));
-            // Walk the directory tree and match relative paths
-            const stream = walk(root, {
-                includeFiles: true,
-                includeDirs: false,
-                skip: excludeRegexes.length > 0 ? excludeRegexes : undefined,
-            });
-            for (const entry of yield* each(stream)) {
-                // Normalize to POSIX separators for consistent matching across platforms
-                const relPath = relative(root, entry.path).split(sep).join("/");
-                const matches = includeRegexes.some((re) => re.test(relPath));
-                if (matches) {
-                    results.push({ path: relPath, isFile: entry.isFile });
-                }
-                yield* each.next();
-            }
-            return results;
-        },
-    }),
-    /**
-     * HTTP requests.
-     *
-     * Default implementation uses `@effectionx/fetch`.
-     * Cancellation aborts the request via Effection scope teardown.
-     */
-    Fetch: createApi("runtime.fetch", {
-        *fetch(input, init) {
-            const timeout = init?.timeout;
-            const response = yield* withTimeout(`fetch(${input})`, timeout, effectionFetch(input, {
-                method: init?.method,
-                headers: init?.headers,
-                body: init?.body,
-            }));
-            return {
-                status: response.status,
-                headers: response.headers,
-                *text() {
-                    return yield* withTimeout(`fetch(${input}).text()`, timeout, response.text());
-                },
-            };
-        },
-    }),
-    /**
-     * Environment variables and platform information.
-     *
-     * These are synchronous lookups wrapped as Operations to satisfy
-     * context-api handler constraints.
-     */
-    Env: createApi("runtime.env", {
-        // deno-lint-ignore require-yield
-        *cwd() {
-            return process.cwd();
-        },
-        // deno-lint-ignore require-yield
-        *env(name) {
-            return process.env[name];
-        },
-        // deno-lint-ignore require-yield
-        *platform() {
-            return {
-                os: process.platform,
-                arch: process.arch,
-            };
-        },
-    }),
-    /**
-     * Block compilation.
-     *
-     * Default handler throws — platform-specific middleware must be
-     * installed via `yield* API.Compiler.around(...)` before use.
-     * See `core/src/deno-compiler.ts` for the Deno implementation.
-     */
-    Compiler: createApi("runtime.compiler", {
-        // deno-lint-ignore require-yield
-        *compile(_source, _options) {
-            throw new Error("compiler not installed — install platform-specific middleware via API.Compiler.around()");
-        },
-    }),
-};
-// ---------------------------------------------------------------------------
-// Convenience operation exports
-//
-// Use these for normal operation calls. Use API.* only when installing
-// middleware with .around().
-// ---------------------------------------------------------------------------
-export const exec = API.Process.operations.exec;
-export const readTextFile = API.Fs.operations.readTextFile;
-export const stat = API.Fs.operations.stat;
-export const glob = API.Fs.operations.glob;
-export const fetch = API.Fetch.operations.fetch;
-export const env = API.Env.operations.env;
-export const cwd = API.Env.operations.cwd;
-export const platform = API.Env.operations.platform;
-export const compile = API.Compiler.operations.compile;

package/esm/runtime/find-free-port.js

@@ -1,33 +0,0 @@
-/**
- * findFreePort — find an available TCP port using the OS.
- */
-import { race } from "effection";
-import { once } from "@effectionx/node";
-import { createServer } from "node:net";
-/**
- * Find an available TCP port by binding to port 0 and reading the
- * OS-assigned port number.
- */
-export function* findFreePort() {
-    const server = createServer();
-    const listening = once(server, "listening");
-    const error = once(server, "error");
-    server.listen(0);
-    try {
-        const rethrowError = {
-            *[Symbol.iterator]() {
-                const [err] = yield* error;
-                throw err;
-            },
-        };
-        yield* race([listening, rethrowError]);
-        const addr = server.address();
-        if (!addr || typeof addr !== "object") {
-            throw new Error("findFreePort: unexpected address format");
-        }
-        return addr.port;
-    }
-    finally {
-        server.close();
-    }
-}

package/esm/runtime/mod.js

@@ -1,20 +0,0 @@
-/**
- * @module
- * Runtime Context APIs for executable markdown.
- *
- * `API` is available for middleware (`.around()`).
- * For normal calls, import operations directly.
- *
- * Six domain APIs:
- * - `API.Process` — subprocess execution (`exec`)
- * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
- * - `API.Fetch` — HTTP requests (`fetch`)
- * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
- * - `API.Compiler` — block compilation (`compile`)
- *
- * See `apis.ts` for architecture rationale.
- * See `@executablemd/runtime/test` for composable test stubs.
- */
-export { API } from "./apis.ts";
-export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.ts";
-export { findFreePort } from "./find-free-port.ts";