@executablemd/testing 0.3.1

package/esm/runtime/apis.js

@@ -0,0 +1,237 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+/**
+ * @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";

package/esm/testing/npm/src/_dnt.polyfills.js

@@ -0,0 +1 @@
+export {};

package/esm/testing/npm/src/_dnt.shims.js

@@ -0,0 +1,57 @@
+const dntGlobals = {};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/testing/npm/src/deps/jsr.io/@std/assert/1.0.19/almost_equals.js

@@ -0,0 +1,47 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+import { AssertionError } from "./assertion_error.js";
+/**
+ * Make an assertion that `actual` and `expected` are almost equal numbers
+ * through a given tolerance. It can be used to take into account IEEE-754
+ * double-precision floating-point representation limitations. If the values
+ * are not almost equal then throw.
+ *
+ * The default tolerance is one hundred thousandth of a percent of the
+ * expected value.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { assertAlmostEquals } from "@std/assert";
+ *
+ * assertAlmostEquals(0.01, 0.02); // Throws
+ * assertAlmostEquals(1e-8, 1e-9); // Throws
+ * assertAlmostEquals(1.000000001e-8, 1.000000002e-8); // Doesn't throw
+ * assertAlmostEquals(0.01, 0.02, 0.1); // Doesn't throw
+ * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16); // Doesn't throw
+ * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17); // Throws
+ * ```
+ *
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param tolerance The tolerance to consider the values almost equal. The
+ * default is one hundred thousandth of a percent of the expected value.
+ * @param msg The optional message to include in the error.
+ * @throws {AssertionError} If the values are not almost equal.
+ */
+export function assertAlmostEquals(actual, expected, tolerance, msg) {
+    if (Object.is(actual, expected)) {
+        return;
+    }
+    const delta = Math.abs(expected - actual);
+    if (tolerance === undefined) {
+        tolerance = isFinite(expected) ? Math.abs(expected * 1e-7) : 1e-7;
+    }
+    if (delta <= tolerance) {
+        return;
+    }
+    const msgSuffix = msg ? `: ${msg}` : ".";
+    const f = (n) => Number.isInteger(n) ? n : n.toExponential();
+    throw new AssertionError(`Expected actual: "${f(actual)}" to be close to "${f(expected)}": \
+delta "${f(delta)}" is greater than "${f(tolerance)}"${msgSuffix}`);
+}

package/esm/testing/npm/src/deps/jsr.io/@std/assert/1.0.19/array_includes.js

@@ -0,0 +1,65 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+import { equal } from "./equal.js";
+import { format } from "../../internal/1.0.14/format.js";
+import { AssertionError } from "./assertion_error.js";
+function isPrimitive(value) {
+    return value === null ||
+        typeof value !== "object" && typeof value !== "function";
+}
+/**
+ * Asserts that `actual` contains all values in `expected`, using deep equality
+ * for non-primitive values.
+ *
+ * @example Usage with primitives
+ * ```ts ignore
+ * import { assertArrayIncludes } from "@std/assert";
+ *
+ * assertArrayIncludes([1, 2, 3], [2, 3]); // Passes
+ * assertArrayIncludes([1, 2, 3], [4]); // Throws
+ * ```
+ *
+ * @example Usage with objects (deep equality)
+ * ```ts ignore
+ * import { assertArrayIncludes } from "@std/assert";
+ *
+ * assertArrayIncludes([{ a: 1 }, { b: 2 }], [{ a: 1 }]); // Passes
+ * ```
+ *
+ * @typeParam T The element type of the arrays.
+ * @param actual The array-like object to search within.
+ * @param expected The values that must be present in `actual`.
+ * @param msg Optional message to display on failure.
+ * @throws {AssertionError} If any value in `expected` is not found in `actual`.
+ */
+export function assertArrayIncludes(actual, expected, msg) {
+    const missing = [];
+    const expectedLen = expected.length;
+    const actualLen = actual.length;
+    for (let i = 0; i < expectedLen; i++) {
+        const item = expected[i];
+        let found;
+        if (isPrimitive(item)) {
+            // Fast path
+            found = Array.prototype.includes.call(actual, item);
+        }
+        else {
+            found = false;
+            for (let j = 0; j < actualLen; j++) {
+                if (equal(item, actual[j])) {
+                    found = true;
+                    break;
+                }
+            }
+        }
+        if (!found) {
+            missing.push(item);
+        }
+    }
+    if (missing.length === 0) {
+        return;
+    }
+    const msgSuffix = msg ? `: ${msg}` : ".";
+    msg = `Expected actual: "${format(actual)}" to include: "${format(expected)}"${msgSuffix}\nmissing: ${format(missing)}`;
+    throw new AssertionError(msg);
+}

package/esm/testing/npm/src/deps/jsr.io/@std/assert/1.0.19/assert.js

@@ -0,0 +1,23 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+import { AssertionError } from "./assertion_error.js";
+/**
+ * Make an assertion, an error will be thrown if `expr` does not have a truthy value.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { assert } from "@std/assert";
+ *
+ * assert("hello".includes("ello")); // Doesn't throw
+ * assert("hello".includes("world")); // Throws
+ * ```
+ *
+ * @param expr The expression to test.
+ * @param msg The optional message to display if the assertion fails.
+ * @throws {AssertionError} If `expr` is falsy.
+ */
+export function assert(expr, msg = "") {
+    if (!expr) {
+        throw new AssertionError(msg);
+    }
+}

package/esm/testing/npm/src/deps/jsr.io/@std/assert/1.0.19/assertion_error.js

@@ -0,0 +1,30 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+/**
+ * Error thrown when an assertion fails.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { AssertionError } from "@std/assert";
+ *
+ * try {
+ *   throw new AssertionError("foo", { cause: "bar" });
+ * } catch (error) {
+ *   if (error instanceof AssertionError) {
+ *     error.message === "foo"; // true
+ *     error.cause === "bar"; // true
+ *   }
+ * }
+ * ```
+ */
+export class AssertionError extends Error {
+    /** Constructs a new instance.
+     *
+     * @param message The error message.
+     * @param options Additional options. This argument is still unstable. It may change in the future release.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AssertionError";
+    }
+}