functionalscript 0.43.1 → 0.44.0

package/fjs/effects/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for the core effect system.
+ *
+ * @module
+ */
+export {};

package/fjs/emergent_testing/all.test.js

@@ -1,5 +1,5 @@
-import { runEffect } from '../effects/node/module.js';
-import { register } from './module.f.js';
+import { runEffect } from '../effects/node/module.mjs';
+import { register } from './module.f.mjs';
 // Top-level `await`: every proof must be registered before the runner starts
 // collecting tests.
 await runEffect(register);

package/fjs/emergent_testing/example.f.d.mts

@@ -0,0 +1,16 @@
+/** @type {(a: number, b: number) => number} */
+export declare const add: (a: number, b: number) => number;
+/** @type {(a: number, b: number) => number} */
+export declare const mul: (a: number, b: number) => number;
+/** @type {(a: number) => number} */
+export declare const sqr: (a: number) => number;
+export declare const todo: () => never;
+export declare const proof: {
+    addTest: () => void;
+    mulTest: (() => void)[];
+    throw: {
+        todo: typeof todo;
+        divByZero: () => bigint;
+    };
+    generateSqrTests: () => (() => void)[];
+};

package/fjs/emergent_testing/example.f.mjs

@@ -0,0 +1,34 @@
+/** @type {(a: number, b: number) => number} */
+export const add = (a, b) => a + b
+
+/** @type {(a: number, b: number) => number} */
+export const mul = (a, b) => a * b
+
+/** @type {(a: number) => number} */
+export const sqr = a => mul(a, a)
+
+export const todo = () => { throw "not implemented" }
+
+/** @type {(a: number, b: number, r: number) => void} */
+const checkMul = (a, b, r) => {
+    if (mul(a, b) !== r) { throw `mul(${a}, ${b}) !== ${r}` } 
+}
+
+export const proof = {
+  addTest: () => {
+    if (add(2, 2) !== 4) { throw "something wrong with the math" }
+  },
+  mulTest: [
+    () => checkMul(2, 3, 6),
+    () => checkMul(22, 34, 748),
+    () => checkMul(-2, 3, -6),
+    () => checkMul(-2, -3, 6),
+  ],
+  throw: {
+     todo,
+     divByZero: () => 5n / 0n,
+  },
+  generateSqrTests: () => [1, 2, 3, 5].map(a => () => {
+    if (sqr(a) !== a * a) { throw `sqr(${a})` }
+  })
+}

package/fjs/emergent_testing/module.f.d.mts

@@ -0,0 +1,150 @@
+/**
+ * Test-framework helpers for running and reporting FunctionalScript tests.
+ *
+ * Two parallel execution paths:
+ * - `runModule` / `Reporter<O>` — self-hosted Effects runner used by `fjs t`;
+ *   sandboxes each leaf call individually and accumulates `TestState`.
+ * - `registerModule` / `TestContext` — registers tests with an external
+ *   framework (Node `--test`, Bun, Deno) at import time; the framework owns
+ *   scheduling and pass/fail counting.
+ *
+ * @module
+ */
+import type { All, Await, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write } from '../effects/node/types.ts';
+import type { Effect, Operation } from '../effects/types.ts';
+import type { LoadModuleOperations, ModuleMap } from '../dev/types.ts';
+import type { TestEntry, TestSet, Path, Reporter, _TestAndPath } from './types.ts';
+/**
+ * Converts an arbitrary JS value into a `TestSet`.
+ *
+ * - Zero-argument functions become a `TestEntry`; the `throws` flag is set if
+ *   `throws` is already `true` (i.e. a `throw` key appears in the ancestor path).
+ *   The canonical way to declare a throw-test is structural: nest it under a
+ *   `throw` property key. The secondary `fn.name === 'throw'` check is a legacy
+ *   path that only fires when a function is extracted from a `throw` key and
+ *   placed under a different key; that pattern is engine-dependent (unreliable on
+ *   Bun) and is not a supported authoring style.
+ * - Non-null objects become an array of `[key, value]` pairs to recurse into.
+ * - All other values (including functions with parameters) produce an empty array.
+ *
+ * @type {(throws: boolean, x: unknown) => TestSet}
+ */
+export declare const parseTestSet: (throws: boolean, x: unknown) => TestSet;
+/**
+ * Recursively collects all leaf tests reachable from `v` as `[path, entry]`
+ * pairs, without running anything. Return-value sub-trees are not walked
+ * (that requires execution); only the static object/array/function structure
+ * is traversed.
+ *
+ * @type {(path: Path, throws: boolean, v: unknown) => readonly _TestAndPath[]}
+ */
+export declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly _TestAndPath[];
+/**
+ * Registers all tests reachable from module export `v` (keyed by `k`) with
+ * the given `TestContext`.
+ *
+ * Unlike `runModule`, which sandboxes only the leaf function, `registerModule`
+ * lets the external framework own scheduling: each registered test callback
+ * calls `fn`, then recursively registers any sub-trees returned by the function.
+ * This is the correct model for Node `--test`, Bun, and Deno, where tests must
+ * be declared upfront and the framework drives execution.
+ *
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>}
+ */
+export declare const registerModule: (ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>;
+/**
+ * Runs all test modules in `moduleMap` whose names pass `isTest`, accumulates
+ * pass/fail/time via `reporter`, and returns an exit code (0 = all passed,
+ * 1 = at least one failure).
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ */
+export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number>;
+/**
+ * Discovers all test modules via `loadModuleMap`, then runs them through
+ * `runModuleMap`. The composed effect is a `NodeProgram` entry point for the
+ * `fjs t` test runner.
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {Program<O | All | LoadModuleOperations>}
+ */
+export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+/** Returns `true` if `s` is a non-negative decimal integer without a leading zero.
+ *
+ * @type {(s: string) => boolean}
+ */
+export declare const isInteger: (s: string) => boolean;
+/** Returns `true` if `s` is a valid JS identifier (ASCII subset: `[A-Za-z_$][A-Za-z0-9_$]*`).
+ *
+ * @type {(s: string) => boolean}
+ */
+export declare const isIdentifier: (s: string) => boolean;
+/**
+ * Renders a key chain as a JS property-access expression: identifier keys use
+ * dot notation, integer keys use `[N]`, other strings use `["key"]`, and `null`
+ * emits `()` to mark a function-call boundary.
+ * E.g. `['math', 'add']` → `.math.add`, `['outer', null, 'inner']` → `.outer().inner`.
+ *
+ * @type {(path: Path) => string}
+ */
+export declare const fmtPath: (path: Path) => string;
+/**
+ * Formats a fully-qualified test identifier as a JS-like expression, e.g.
+ * `import("./math.proof.f.ts").add()` or `import("./a.proof.f.ts").users[3].name()`.
+ * Self-contained per line — suitable for parallel output and as a CLI filter argument.
+ *
+ * @type {(file: string, path: Path) => string}
+ */
+export declare const fmtImport: (file: string, path: Path) => string;
+/**
+ * Renders a key chain for terminal output: `| ` per level of depth, followed
+ * by the last segment formatted as a bare integer, a bare identifier, or a
+ * JSON-quoted string. E.g. `['math', 'add']` → `| | add`,
+ * `['a', '0']` → `| | 0`, `['x', 'hello world']` → `| | "hello world"`.
+ *
+ * @type {(path: Path) => string}
+ */
+export declare const fmtTerm: (path: Path) => string;
+/**
+ * Percent-encodes characters that GitHub workflow-command property values
+ * treat as separators (`%`, `:`, `,`) plus newlines.
+ * https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions
+ *
+ * @type {(s: string) => string}
+ */
+export declare const ghEscape: (s: string) => string;
+/**
+ * Default `Reporter.test` implementation: sandboxes `fn` once and inverts the
+ * result when `throws` is `true` (caught error → pass, clean return → fail).
+ *
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>}
+ */
+export declare const defaultTest: (file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>;
+/**
+ * The terminal/GitHub reporter used by `fjs t`. Output goes through
+ * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
+ * `GITHUB_ACTIONS` is set, failures are emitted as `::error` workflow
+ * annotations instead of colored lines. Exported as a factory so the
+ * GitHub format path can be exercised directly from tests.
+ *
+ * @type {(options: NodeProgramOptions) => Reporter<Write | Sandbox>}
+ */
+export declare const defaultReporter: (options: NodeProgramOptions) => Reporter<Write | Sandbox>;
+/** The `fjs t` entry point: runs all tests using `defaultReporter`.
+ *
+ * @type {NodeProgram}
+ */
+export declare const main: NodeProgram;
+/**
+ * Entry point for external test frameworks (Node `--test`, Bun, Deno).
+ *
+ * Discovers test modules via `loadModuleMap`, then registers each with the
+ * framework-appropriate `TestContext` selected from `NodeProgramOptions`
+ * based on the detected `engine`.
+ *
+ * @type {NodeProgram}
+ */
+export declare const register: NodeProgram;

package/fjs/emergent_testing/module.f.mjs

@@ -0,0 +1,414 @@
+/**
+ * Test-framework helpers for running and reporting FunctionalScript tests.
+ *
+ * Two parallel execution paths:
+ * - `runModule` / `Reporter<O>` — self-hosted Effects runner used by `fjs t`;
+ *   sandboxes each leaf call individually and accumulates `TestState`.
+ * - `registerModule` / `TestContext` — registers tests with an external
+ *   framework (Node `--test`, Bun, Deno) at import time; the framework owns
+ *   scheduling and pass/fail counting.
+ *
+ * @module
+ */
+
+import { reset, fgGreen, fgRed, bold, csiWrite } from '../text/sgr/module.f.mjs'
+import { all, awaitIfPromise, sandbox, test } from '../effects/node/module.f.mjs'
+/** @import {
+    All,
+    Await,
+    Env,
+    NodeProgram,
+    NodeProgramOptions,
+    Program,
+    Sandbox,
+    SandboxResult,
+    Test,
+    TestContext,
+    Write,
+    WriteConsoles
+} from '../effects/node/types.ts' */
+import { history, historyStep, pure, step } from '../effects/module.f.mjs'
+/** @import { Effect, Operation } from '../effects/types.ts' */
+import { eff } from '../effects/eff/module.f.mjs'
+import { loadModuleMap } from '../dev/module.f.mjs'
+/** @import { LoadModuleOperations, ModuleMap } from '../dev/types.ts' */
+import { invert } from '../types/result/module.f.mjs'
+import { definedEntries } from '../types/object/module.f.mjs'
+/** @import { TestFn, TestEntry, TestSet, Path, Reporter, _TestState, _TestAndPath } from './types.ts' */
+
+/** @type {(delta: number) => (ts: _TestState) => _TestState} */
+const addPass = delta => ts =>
+    ({ ...ts, time: ts.time + delta, pass: ts.pass + 1 })
+
+/** @type {(delta: number) => (ts: _TestState) => _TestState} */
+const addFail = delta => ts =>
+    ({ ...ts, time: ts.time + delta, fail: ts.fail + 1 })
+
+/** @type {(a: number) => string} */
+const timeFormat = a => {
+    const y = Math.round(a * 10_000).toString()
+    const yl = 5 - y.length
+    const x = '0'.repeat(yl > 0 ? yl : 0) + y
+    const s = x.length - 4
+    const b = x.substring(0, s)
+    const e = x.substring(s)
+    return `${b}.${e} ms`
+}
+
+/**
+ * Converts an arbitrary JS value into a `TestSet`.
+ *
+ * - Zero-argument functions become a `TestEntry`; the `throws` flag is set if
+ *   `throws` is already `true` (i.e. a `throw` key appears in the ancestor path).
+ *   The canonical way to declare a throw-test is structural: nest it under a
+ *   `throw` property key. The secondary `fn.name === 'throw'` check is a legacy
+ *   path that only fires when a function is extracted from a `throw` key and
+ *   placed under a different key; that pattern is engine-dependent (unreliable on
+ *   Bun) and is not a supported authoring style.
+ * - Non-null objects become an array of `[key, value]` pairs to recurse into.
+ * - All other values (including functions with parameters) produce an empty array.
+ *
+ * @type {(throws: boolean, x: unknown) => TestSet}
+ */
+export const parseTestSet = (throws, x) => {
+    switch (typeof x) {
+        case 'function': {
+            if (x.length === 0) {
+                const fn = /** @type {TestFn} */ (x)
+                return { fn, throws: throws || fn.name === 'throw' }
+            }
+            break
+        }
+        case 'object': {
+            if (x !== null) {
+                return Object.entries(x)
+            }
+            break
+        }
+    }
+    return []
+}
+
+/**
+ * Recursively collects all leaf tests reachable from `v` as `[path, entry]`
+ * pairs, without running anything. Return-value sub-trees are not walked
+ * (that requires execution); only the static object/array/function structure
+ * is traversed.
+ *
+ * @type {(path: Path, throws: boolean, v: unknown) => readonly _TestAndPath[]}
+ */
+export const collectTests = (path, throws, v) => {
+    const set = parseTestSet(throws, v)
+    if (set instanceof Array) {
+        return set.flatMap(([ck, cv]) =>
+            collectTests([...path, ck], throws || ck === 'throw', cv)
+        )
+    }
+    return [[path, set]]
+}
+
+/**
+ * Registers all tests reachable from module export `v` (keyed by `k`) with
+ * the given `TestContext`.
+ *
+ * Unlike `runModule`, which sandboxes only the leaf function, `registerModule`
+ * lets the external framework own scheduling: each registered test callback
+ * calls `fn`, then recursively registers any sub-trees returned by the function.
+ * This is the correct model for Node `--test`, Bun, and Deno, where tests must
+ * be declared upfront and the framework drives execution.
+ *
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>}
+ */
+export const registerModule = (ctx, k, v, star) => {
+    /** @type {(ctx: TestContext, entry: _TestAndPath) => Effect<Test | All | Await, void>} */
+    const registerOne = (ctx, [path, { fn, throws }]) => {
+        // `star` (non-empty for Bun and for Node below the 26 baseline) signals
+        // that all sub-tests run inline inside this single registration, so an
+        // external runner reports fewer tests than `fjs t` for the same suite.
+        // Not appended to throw-tests since those never produce sub-tests. The
+        // path already contains '.throw' when a test is expected to throw, so no
+        // extra suffix is needed.
+        const base = fmtImport(k, path)
+        const name = throws ? base : `${base}${star}`
+        return test(ctx, name, throws, (/** @type {TestContext} */ t) =>
+            eff(awaitIfPromise(fn()))
+                .step(resolved => {
+                    if (throws) {
+                        return pure(undefined)
+                    }
+                    const sub = collectTests([...path, null], false, resolved)
+                    if (sub.length === 0) {
+                        return pure(undefined)
+                    }
+                    return eff(all(...sub.map(e => registerOne(t, e))))
+                        .step(() => pure(undefined))
+                        .value
+                })
+                .value
+        )
+    }
+    const tests = collectTests([], false, v)
+    if (tests.length === 0) { return pure(undefined) }
+    return eff(all(...tests.map(e => registerOne(ctx, e))))
+        .step(() => pure(undefined))
+        .value
+}
+
+/** @type {(a: _TestState, b: _TestState) => _TestState} */
+const mergeState = (a, b) =>
+    ({ time: a.time + b.time, pass: a.pass + b.pass, fail: a.fail + b.fail })
+
+/** @type {_TestState} */
+const zero = { time: 0, pass: 0, fail: 0 }
+
+/**
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {(k: string, v: unknown) => (ts: _TestState) => Effect<O | All, _TestState>}
+ */
+const runModule = ({ result, test }) => (k, v) => ts => {
+    /** @type {(entry: _TestAndPath) => Effect<O | All, _TestState>} */
+    const one = ([testPath, set]) => {
+        // The sandbox result is still needed after it has been reported, so the
+        // reporting call is captured rather than nested inside its own step.
+        const reported = historyStep(
+            history(test(k, testPath, set)),
+            sr => result(k, testPath, sr, set.throws))
+        return step(
+            reported,
+            ([, sr]) => {
+                const { result: [s, r], duration } = sr
+                if (s !== 'ok') {
+                    return pure(addFail(duration)(zero))
+                }
+                if (set.throws) {
+                    return pure(addPass(duration)(zero))
+                }
+                // Walk return-value sub-tree; null marks the call boundary so
+                // paths render as e.g. `outer().inner`. throws resets to false.
+                return step(
+                    walk([...testPath, null], false, r),
+                    sub => pure(mergeState(addPass(duration)(zero), sub)))
+            })
+    }
+    /** @type {(path: Path, throws: boolean, v: unknown) => Effect<O | All, _TestState>} */
+    const walk = (path, throws, v) => {
+        const effects = collectTests(path, throws, v).map(one)
+        return eff(all(...effects))
+            .step(states => pure(states.reduce(mergeState, zero)))
+            .value
+    }
+    return eff(walk([], false, v))
+        .step(delta => pure(mergeState(ts, delta)))
+        .value
+}
+
+/** @type {(moduleMap: ModuleMap) => readonly (readonly [string, unknown])[]} */
+const proofEntries = moduleMap =>
+    definedEntries(moduleMap)
+        .flatMap(([k, v]) => v.proof !== undefined ? [/** @type {const} */ ([k, v.proof])] : [])
+
+/**
+ * Runs all test modules in `moduleMap` whose names pass `isTest`, accumulates
+ * pass/fail/time via `reporter`, and returns an exit code (0 = all passed,
+ * 1 = at least one failure).
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ */
+export const runModuleMap = reporter => moduleMap => {
+    const { summary } = reporter
+    const modules = proofEntries(moduleMap)
+    return eff(all(...modules.map(([k, v]) => runModule(reporter)(k, v)(zero))))
+        .step(m => pure(m.reduce(mergeState, zero)))
+        .step(ts => summary(ts.pass, ts.fail, ts.time))
+        .step((_, ts) => pure(ts.fail !== 0 ? 1 : 0))
+        .value
+}
+
+/**
+ * Discovers all test modules via `loadModuleMap`, then runs them through
+ * `runModuleMap`. The composed effect is a `NodeProgram` entry point for the
+ * `fjs t` test runner.
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {Program<O | All | LoadModuleOperations>}
+ */
+export const testAll = reporter => options =>
+    eff(loadModuleMap(options.env))
+        .step(runModuleMap(reporter))
+        .value
+
+/**
+ * Registers all modules in `moduleMap` that export a `proof` property with
+ * `ctx`. Delegates to `registerModule` for each matching entry.
+ *
+ * @type {(ctx: TestContext, star: string) => (moduleMap: ModuleMap) => Effect<Test | All | Await, void>}
+ */
+const registerModuleMap = (ctx, star) => moduleMap => {
+    const modules = proofEntries(moduleMap)
+    if (modules.length === 0) { return pure(undefined) }
+    return eff(all(...modules.map(([k, v]) => registerModule(ctx, k, v, star))))
+        .step(() => pure(undefined))
+        .value
+}
+
+/** @type {(c: string) => boolean} */
+const isAlpha = c =>
+    (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '_' || c === '$'
+
+/** @type {(c: string) => boolean} */
+const isDigit = c => c >= '0' && c <= '9'
+
+/** Returns `true` if `s` is a non-negative decimal integer without a leading zero.
+ *
+ * @type {(s: string) => boolean}
+ */
+export const isInteger = s =>
+    s.length > 0 && [...s].every(isDigit) && (s === '0' || s[0] !== '0')
+
+/** Returns `true` if `s` is a valid JS identifier (ASCII subset: `[A-Za-z_$][A-Za-z0-9_$]*`).
+ *
+ * @type {(s: string) => boolean}
+ */
+export const isIdentifier = s =>
+    s.length > 0 && isAlpha(s[0]) && [...s.slice(1)].every(c => isAlpha(c) || isDigit(c))
+
+/** @type {(k: string | null) => string} */
+const fmtKey = k =>
+    k === null ? '()'
+    : isInteger(k) ? `[${k}]`
+    : isIdentifier(k) ? `.${k}`
+    : `[${JSON.stringify(k)}]`
+
+/**
+ * Renders a key chain as a JS property-access expression: identifier keys use
+ * dot notation, integer keys use `[N]`, other strings use `["key"]`, and `null`
+ * emits `()` to mark a function-call boundary.
+ * E.g. `['math', 'add']` → `.math.add`, `['outer', null, 'inner']` → `.outer().inner`.
+ *
+ * @type {(path: Path) => string}
+ */
+export const fmtPath = path =>
+    path.reduce((/** @type {string} */ acc, k) => acc + fmtKey(k), '')
+
+/**
+ * Formats a fully-qualified test identifier as a JS-like expression, e.g.
+ * `import("./math.proof.f.ts").add()` or `import("./a.proof.f.ts").users[3].name()`.
+ * Self-contained per line — suitable for parallel output and as a CLI filter argument.
+ *
+ * @type {(file: string, path: Path) => string}
+ */
+export const fmtImport = (file, path) =>
+    `import(${JSON.stringify(file)}).proof${fmtPath(path)}()`
+
+/**
+ * Renders a key chain for terminal output: `| ` per level of depth, followed
+ * by the last segment formatted as a bare integer, a bare identifier, or a
+ * JSON-quoted string. E.g. `['math', 'add']` → `| | add`,
+ * `['a', '0']` → `| | 0`, `['x', 'hello world']` → `| | "hello world"`.
+ *
+ * @type {(path: Path) => string}
+ */
+export const fmtTerm = path => {
+    const keys = path.flatMap(k => k !== null ? [k] : [])
+    const indent = '| '.repeat(keys.length)
+    if (keys.length === 0) { return `${indent}()` }
+    const last = keys[keys.length - 1]
+    return `${indent}${isInteger(last) || isIdentifier(last) ? last : JSON.stringify(last)}`
+}
+
+/**
+ * Percent-encodes characters that GitHub workflow-command property values
+ * treat as separators (`%`, `:`, `,`) plus newlines.
+ * https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions
+ *
+ * @type {(s: string) => string}
+ */
+export const ghEscape = s =>
+    s.replaceAll('%', '%25')
+        .replaceAll(':', '%3A')
+        .replaceAll(',', '%2C')
+        .replaceAll('\r', '%0D')
+        .replaceAll('\n', '%0A')
+
+/**
+ * Default `Reporter.test` implementation: sandboxes `fn` once and inverts the
+ * result when `throws` is `true` (caught error → pass, clean return → fail).
+ *
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>}
+ */
+export const defaultTest = (file, path, { fn, throws }) =>
+    eff(sandbox(fn))
+        .step(r => pure(throws ? { ...r, result: invert(r.result) } : r))
+        .value
+
+/** @type {(file: string, path: Path, color: string, label: string, duration: number) => string} */
+const fmtResultLine = (file, path, color, label, duration) =>
+    `${fmtImport(file, path)}: ${color}${label}${reset}, ${timeFormat(duration)}`
+
+/**
+ * The terminal/GitHub reporter used by `fjs t`. Output goes through
+ * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
+ * `GITHUB_ACTIONS` is set, failures are emitted as `::error` workflow
+ * annotations instead of colored lines. Exported as a factory so the
+ * GitHub format path can be exercised directly from tests.
+ *
+ * @type {(options: NodeProgramOptions) => Reporter<Write | Sandbox>}
+ */
+export const defaultReporter = options => {
+    const write = csiWrite(options)
+    /** @type {(w: WriteConsoles) => (s: string) => Effect<Write, void>} */
+    const line = w => {
+        const x = write(w)
+        return s => x(s + '\n')
+    }
+    const csiLog = line('stdout')
+    const csiError = line('stderr')
+    const isGitHub = options.env['GITHUB_ACTIONS'] !== undefined
+    return {
+        // https://github.com/OndraM/ci-detector/blob/main/src/Ci/GitHubActions.php
+        result: (file, path, { result: [s, v], duration }, throws) =>
+            s === 'ok'
+                ? csiLog(fmtResultLine(file, path, fgGreen, 'ok', duration) + (throws ? ' # EXPECTED TO THROW' : ''))
+                : isGitHub
+                    ? csiError(`::error file=${file},line=1,title=${ghEscape(fmtImport(file, path))}::${ghEscape(String(v))}`)
+                    : eff(csiError(fmtResultLine(file, path, fgRed, 'error', duration)))
+                        .step(() => csiError(`${fgRed}${v}${reset}`))
+                        .value,
+        summary: (pass, fail, time) => {
+            const fgFail = fail === 0 ? fgGreen : fgRed
+            return eff(csiLog(`${bold}Number of tests: pass: ${fgGreen}${pass}${reset}${bold}, fail: ${fgFail}${fail}${reset}${bold}, total: ${pass + fail}${reset}`))
+                .step(() => csiLog(`${bold}Time: ${timeFormat(time)}${reset}`))
+                .value
+        },
+        test: defaultTest,
+    }
+}
+
+/** The `fjs t` entry point: runs all tests using `defaultReporter`.
+ *
+ * @type {NodeProgram}
+ */
+export const main =
+    options => testAll(defaultReporter(options))(options)
+
+/**
+ * Entry point for external test frameworks (Node `--test`, Bun, Deno).
+ *
+ * Discovers test modules via `loadModuleMap`, then registers each with the
+ * framework-appropriate `TestContext` selected from `NodeProgramOptions`
+ * based on the detected `engine`.
+ *
+ * @type {NodeProgram}
+ */
+export const register = o => {
+    const star = o.inlineTestContext ? ' ...' : ''
+    const ctx = o.engine === 'bun' ? o.bunTestContext : o.testContext
+    return eff(loadModuleMap(o.env))
+        .step(registerModuleMap(ctx, star))
+        .step(() => pure(0))
+        .value
+}