functionalscript 0.43.1 → 0.45.0

package/fjs/emergent_testing/module.f.mjs

@@ -0,0 +1,388 @@
+/**
+ * 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 { Effect, Operation } from '../effects/types.ts'
+ * @import { LoadModuleOperations, ModuleMap } from '../dev/types.ts'
+ * @import { TestFn, TestEntry, TestSet, Path, Reporter, _TestState, _TestAndPath } from './types.ts'
+ * @import { All, Await, Env, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
+ */
+
+import { reset, fgGreen, fgRed, bold, csiWrite } from '../text/sgr/module.f.mjs'
+import { all, awaitIfPromise, sandbox, test } from '../effects/node/module.f.mjs'
+import { history, historyStep, mapStep, pure, step } from '../effects/module.f.mjs'
+import { loadModuleMap } from '../dev/module.f.mjs'
+import { invert } from '../types/result/module.f.mjs'
+import { definedEntries } from '../types/object/module.f.mjs'
+
+/** @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) =>
+            step(awaitIfPromise(fn()), resolved => {
+                if (throws) {
+                    return pure(undefined)
+                }
+                const sub = collectTests([...path, null], false, resolved)
+                if (sub.length === 0) {
+                    return pure(undefined)
+                }
+                return mapStep(all(...sub.map(e => registerOne(t, e))), () => undefined)
+            })
+        )
+    }
+    const tests = collectTests([], false, v)
+    if (tests.length === 0) { return pure(undefined) }
+    return mapStep(all(...tests.map(e => registerOne(ctx, e))), () => undefined)
+}
+
+/** @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 mapStep(all(...effects), states => states.reduce(mergeState, zero))
+    }
+    return mapStep(walk([], false, v), delta => mergeState(ts, delta))
+}
+
+/** @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)
+    const total = mapStep(
+        all(...modules.map(([k, v]) => runModule(reporter)(k, v)(zero))),
+        m => m.reduce(mergeState, zero))
+    // The totals are still needed after the summary has been printed, so they
+    // are carried forward in a history rather than closed over by a nested
+    // continuation.
+    const reported = historyStep(
+        history(total),
+        ts => summary(ts.pass, ts.fail, ts.time))
+    return mapStep(reported, ([, ts]) => ts.fail !== 0 ? 1 : 0)
+}
+
+/**
+ * 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 =>
+    step(loadModuleMap(options.env), runModuleMap(reporter))
+
+/**
+ * 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 mapStep(all(...modules.map(([k, v]) => registerModule(ctx, k, v, star))), () => undefined)
+}
+
+/** @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 }) =>
+    mapStep(sandbox(fn), r => throws ? { ...r, result: invert(r.result) } : r)
+
+/** @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))}`)
+                    : step(
+                        csiError(fmtResultLine(file, path, fgRed, 'error', duration)),
+                        () => csiError(`${fgRed}${v}${reset}`)),
+        summary: (pass, fail, time) => {
+            const fgFail = fail === 0 ? fgGreen : fgRed
+            return step(
+                csiLog(`${bold}Number of tests: pass: ${fgGreen}${pass}${reset}${bold}, fail: ${fgFail}${fail}${reset}${bold}, total: ${pass + fail}${reset}`),
+                () => csiLog(`${bold}Time: ${timeFormat(time)}${reset}`))
+        },
+        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
+    const registered = step(loadModuleMap(o.env), registerModuleMap(ctx, star))
+    return mapStep(registered, () => 0)
+}

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

@@ -0,0 +1,97 @@
+/**
+ * @import { Effect } from '../effects/types.ts'
+ * @import { NodeProgramOptions, Sandbox, Write } from '../effects/node/types.ts'
+ * @import { JsModule } from '../effects/node/virtual/types.ts'
+ * @import { Reporter } from './types.ts'
+ * @import { All, Await, Test, TestContext } from '../effects/node/types.ts'
+ * @import { Ts } from '../types/rtti/ts/types.ts'
+ */
+import type { Effect } from '../effects/types.ts';
+import type { Sandbox, Write } from '../effects/node/types.ts';
+import type { Reporter } from './types.ts';
+import type { All, Await, Test, TestContext } from '../effects/node/types.ts';
+import type { Ts } from '../types/rtti/ts/types.ts';
+/**
+ * The mock reporter's stdout lines. A schema rather than a hand-written type:
+ * the events round-trip through JSON, and this is what turns a line back into
+ * a typed value without an `as` cast — a shape change fails at the parse
+ * instead of silently at an assertion.
+ *
+ * `Reporter.result` also receives the test's `SandboxResult`, which is not
+ * written: no assertion here reads it, and its `undefined` payloads have no
+ * JSON representation to round-trip through anyway.
+ */
+declare const event: import("../types/rtti/types.ts").Or<[readonly ["result", import("../types/rtti/types.ts")._Type0<"string">, import("../types/rtti/types.ts").Type1<"array", import("../types/rtti/types.ts").Or<[import("../types/rtti/types.ts")._Type0<"string">, null]>>], readonly ["summary", import("../types/rtti/types.ts")._Type0<"number">, import("../types/rtti/types.ts")._Type0<"number">, import("../types/rtti/types.ts")._Type0<"number">]]>;
+export type _Event = Ts<typeof event>;
+export type _TestReporter = Reporter<Sandbox | Write>;
+export declare const flat: () => void;
+export declare const nested: () => void;
+export declare const throwKey: () => void;
+export declare const throwKeyFail: () => void;
+export declare const mixedPassFail: () => void;
+export declare const returnValueSubTree: () => void;
+export declare const arrayKeys: () => void;
+export declare const nonTestFilesSkipped: () => void;
+export declare const multipleFiles: () => void;
+export declare const throwByFunctionName: () => void;
+export declare const namedExports: () => void;
+export declare const defaultReporterOutput: () => void;
+export declare const defaultReporterOutputLargeDuration: () => void;
+export declare const defaultReporterFailOutput: () => void;
+export declare const githubReporterOutput: () => void;
+export type _RegisterMockState = readonly string[];
+export type _RegisterMockOps = Test | All | Await;
+export type _RegisterRunner = (s: _RegisterMockState) => <T>(e: Effect<_RegisterMockOps, T>) => readonly [_RegisterMockState, T];
+export type _RegisterTestOp = (runner: _RegisterRunner, ctx: TestContext, name: string, expectFailure: boolean, fn: (t: TestContext) => Effect<_RegisterMockOps, void>) => (s: _RegisterMockState) => readonly [_RegisterMockState, void];
+export declare const registerSuffixes: () => void;
+export declare const registerThrowsWithoutThrowing: () => void;
+export declare const registerEmptyProof: () => void;
+export declare const helpers: {
+    isInteger: () => void;
+    isIdentifier: () => void;
+    shouldLoad: () => void;
+    fmtImport: () => void;
+    fmtPath: () => void;
+    fmtTerm: () => void;
+    ghEscape: () => void;
+    parseTestSet: {
+        nullReturnsEmpty: () => void;
+        functionWithParamsReturnsEmpty: () => void;
+    };
+};
+declare const defaultReporterExpectedToThrow: () => void;
+export declare const proof: {
+    flat: typeof flat;
+    nested: typeof nested;
+    throwKey: typeof throwKey;
+    throwKeyFail: typeof throwKeyFail;
+    mixedPassFail: typeof mixedPassFail;
+    returnValueSubTree: typeof returnValueSubTree;
+    arrayKeys: typeof arrayKeys;
+    nonTestFilesSkipped: typeof nonTestFilesSkipped;
+    multipleFiles: typeof multipleFiles;
+    throwByFunctionName: typeof throwByFunctionName;
+    namedExports: typeof namedExports;
+    defaultReporterOutput: typeof defaultReporterOutput;
+    defaultReporterOutputLargeDuration: typeof defaultReporterOutputLargeDuration;
+    defaultReporterFailOutput: typeof defaultReporterFailOutput;
+    githubReporterOutput: typeof githubReporterOutput;
+    registerSuffixes: typeof registerSuffixes;
+    registerThrowsWithoutThrowing: typeof registerThrowsWithoutThrowing;
+    registerEmptyProof: typeof registerEmptyProof;
+    defaultReporterExpectedToThrow: typeof defaultReporterExpectedToThrow;
+    helpers: {
+        isInteger: () => void;
+        isIdentifier: () => void;
+        shouldLoad: () => void;
+        fmtImport: () => void;
+        fmtPath: () => void;
+        fmtTerm: () => void;
+        ghEscape: () => void;
+        parseTestSet: {
+            nullReturnsEmpty: () => void;
+            functionWithParamsReturnsEmpty: () => void;
+        };
+    };
+};
+export {};