functionalscript 0.18.0 → 0.20.0

package/fs/dev/{test.f.js → proof.f.js}

@@ -1,5 +1,8 @@
-import { todo } from "./module.f.js";
-export default {
+import { todo, env } from "./module.f.js";
+export const proof = {
+    shouldPass: () => ({
+        then: () => undefined
+    }),
     ctor: () => {
         const c = (() => { })['constructor'];
         const f = c('return 5');
@@ -52,5 +55,25 @@ export default {
     },
     throw: () => {
         todo();
+    },
+    env: () => {
+        const mockIo = { process: { env: { MY_VAR: 'hello' } } };
+        // missing key → undefined
+        const r1 = env(mockIo)('MISSING');
+        if (r1 !== undefined) {
+            throw r1;
+        }
+        // regular value property → returns value
+        const r2 = env(mockIo)('MY_VAR');
+        if (r2 !== 'hello') {
+            throw r2;
+        }
+        // getter property → calls get()
+        const envWithGetter = Object.defineProperty({}, 'GETTER_VAR', { get: () => 'from-getter', enumerable: true, configurable: true });
+        const mockIo2 = { process: { env: envWithGetter } };
+        const r3 = env(mockIo2)('GETTER_VAR');
+        if (r3 !== 'from-getter') {
+            throw r3;
+        }
     }
 };

package/fs/dev/tf/module.d.ts

@@ -1,2 +1 @@
-export declare const run3: () => Promise<void>;
-export declare const run: () => Promise<void>;
+export declare const run: () => Promise<number>;

package/fs/dev/tf/module.f.d.ts

@@ -1,21 +1,42 @@
-import { type All, type NodeProgram, type NodeProgramOptions, type Program, type Sandbox, type SandboxResult, type Write } from '../../types/effects/node/module.f.ts';
+import { type All, type Await, type NodeProgram, type NodeProgramOptions, type Program, type Sandbox, type SandboxResult, type Test, type TestContext, type Write } from '../../types/effects/node/module.f.ts';
 import { type Effect, type Operation } from '../../types/effects/module.f.ts';
 import { type LoadModuleOperations, type ModuleMap } from '../module.f.ts';
-export declare const isTest: (s: string) => boolean;
-export type Test = () => unknown;
+/** A zero-argument test function whose return value may contain sub-tests. */
+export type TestFn = () => unknown;
+/**
+ * A leaf test bundled with its throw expectation.
+ *
+ * `throws: true` means the test is expected to throw; the runner inverts the
+ * `sandbox` result so a caught error becomes a pass and a clean return becomes
+ * a failure. Using a record instead of a wrapper function avoids a double
+ * `sandbox` call and gives accurate per-test timing.
+ */
 export type TestEntry = {
-    readonly fn: Test;
+    readonly fn: TestFn;
     readonly throws: boolean;
 };
+/**
+ * Either a leaf `TestEntry` (function + throw flag) or a named sub-tree of
+ * `[key, value]` pairs to recurse into. Discriminate with `Array.isArray`.
+ */
 export type TestSet = TestEntry | readonly (readonly [string, unknown])[];
+/**
+ * Converts an arbitrary JS value into a `TestSet`.
+ *
+ * - Zero-argument functions become a `TestEntry`; the `throws` flag is set if
+ *   `throws` is already `true` or the function's `.name === 'throw'`.
+ * - Non-null objects become an array of `[key, value]` pairs to recurse into.
+ * - All other values (including functions with parameters) produce an empty array.
+ */
 export declare const parseTestSet: (throws: boolean, x: unknown) => TestSet;
+type TestAndPath = readonly [Path, TestEntry];
 /**
  * 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.
  */
-export declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly (readonly [Path, TestEntry])[];
+export declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly TestAndPath[];
 /**
  * Receives semantic test-run events. Each method is the runner's notification
  * of an event; the reporter decides how to render it (terminal, GitHub
@@ -29,10 +50,38 @@ export type Reporter<O extends Operation> = {
     readonly summary: (pass: number, fail: number, time: number) => Effect<O, void>;
     readonly test: (file: string, path: Path, set: TestEntry) => Effect<O, SandboxResult<unknown>>;
 };
+/**
+ * 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 Playwright, where tests
+ * must be declared upfront and the framework drives execution.
+ */
+export declare const registerModule: (ctx: TestContext, k: string, v: unknown) => 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).
+ */
 export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number>;
-export declare const test: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+/**
+ * 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.
+ */
+export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+/**
+ * A chain of property-access keys leading to a test location. String entries
+ * are object/array keys; `null` marks a function-call boundary (the return
+ * value was walked as a sub-tree).
+ */
 export type Path = readonly (string | null)[];
+/** Returns `true` if `s` is a non-negative decimal integer without a leading zero. */
 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_$]*`). */
 export declare const isIdentifier: (s: string) => boolean;
 /**
  * Renders a key chain as a JS property-access expression: identifier keys use
@@ -43,7 +92,7 @@ export declare const isIdentifier: (s: string) => boolean;
 export declare const fmtPath: (path: Path) => string;
 /**
  * Formats a fully-qualified test identifier as a JS-like expression, e.g.
- * `import("./math.test.f.ts").add()` or `import("./a.test.f.ts").users[3].name()`.
+ * `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.
  */
 export declare const fmtImport: (file: string, path: Path) => string;
@@ -60,6 +109,10 @@ export declare const fmtTerm: (path: Path) => string;
  * https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions
  */
 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).
+ */
 export declare const defaultTest: (file: string, path: Path, { fn, throws }: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>;
 /**
  * The terminal/GitHub reporter used by `fjs t`. Output goes through
@@ -69,4 +122,14 @@ export declare const defaultTest: (file: string, path: Path, { fn, throws }: Tes
  * GitHub format path can be exercised directly from tests.
  */
 export declare const defaultReporter: (options: NodeProgramOptions) => Reporter<Write | Sandbox>;
+/** The `fjs t` entry point: runs all tests using `defaultReporter`. */
 export declare const main: NodeProgram;
+/**
+ * Entry point for external test frameworks (Node `--test`, Bun, Playwright).
+ *
+ * Discovers test modules via `loadModuleMap`, then registers each with the
+ * framework-appropriate `TestContext` selected from `NodeProgramOptions`
+ * based on the detected `engine`.
+ */
+export declare const register: NodeProgram;
+export {};

package/fs/dev/tf/module.f.js

@@ -1,14 +1,20 @@
 /**
  * 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, Playwright) at import time; the framework
+ *   owns scheduling and pass/fail counting.
+ *
  * @module
  */
 import { reset, fgGreen, fgRed, bold, csiWrite } from "../../text/sgr/module.f.js";
-import { all, sandbox } from "../../types/effects/node/module.f.js";
+import { all, awaitIfPromise, sandbox, test } from "../../types/effects/node/module.f.js";
 import { pure } from "../../types/effects/module.f.js";
-import { loadModuleMap } from "../module.f.js";
+import { loadModuleMap, shouldLoad } from "../module.f.js";
 import { invert } from "../../types/result/module.f.js";
-export const isTest = (s) => s.endsWith('test.f.js') || s.endsWith('test.f.ts');
 const addPass = (delta) => (ts) => ({ ...ts, time: ts.time + delta, pass: ts.pass + 1 });
 const addFail = (delta) => (ts) => ({ ...ts, time: ts.time + delta, fail: ts.fail + 1 });
 const timeFormat = (a) => {
@@ -20,6 +26,14 @@ const timeFormat = (a) => {
     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` or the function's `.name === 'throw'`.
+ * - Non-null objects become an array of `[key, value]` pairs to recurse into.
+ * - All other values (including functions with parameters) produce an empty array.
+ */
 export const parseTestSet = (throws, x) => {
     switch (typeof x) {
         case 'function': {
@@ -51,28 +65,56 @@ export const collectTests = (path, throws, v) => {
     }
     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 Playwright, where tests
+ * must be declared upfront and the framework drives execution.
+ */
+export const registerModule = (ctx, k, v) => {
+    const registerOne = (ctx, [path, { fn, throws }]) => test(ctx, fmtImport(k, path), throws, (t) => awaitIfPromise(fn())
+        .step(resolved => {
+        if (throws) {
+            return pure(undefined);
+        }
+        const sub = collectTests([...path, null], false, resolved);
+        if (sub.length === 0) {
+            return pure(undefined);
+        }
+        return all(...sub.map(e => registerOne(t, e))).step(() => pure(undefined));
+    }));
+    const tests = collectTests([], false, v);
+    if (tests.length === 0) {
+        return pure(undefined);
+    }
+    return all(...tests.map(e => registerOne(ctx, e))).step(() => pure(undefined));
+};
 const mergeState = (a, b) => ({ time: a.time + b.time, pass: a.pass + b.pass, fail: a.fail + b.fail });
 const zero = { time: 0, pass: 0, fail: 0 };
 const runModule = ({ result, test }) => (k, v) => (ts) => {
-    const walk = (path, throws, v) => {
-        const effects = collectTests(path, throws, v)
-            .map(([testPath, set]) => test(k, testPath, set)
-            .step(sr => {
-            const { result: [s, r], duration } = sr;
-            return result(k, testPath, sr)
-                .step(() => {
-                if (s === 'ok') {
-                    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 walk([...testPath, null], false, r)
-                        .step(sub => pure(mergeState(addPass(duration)(zero), sub)));
+    const one = ([testPath, set]) => test(k, testPath, set)
+        .step(sr => {
+        const { result: [s, r], duration } = sr;
+        return result(k, testPath, sr)
+            .step(() => {
+            if (s === 'ok') {
+                if (set.throws) {
+                    return pure(addPass(duration)(zero));
                 }
-                return pure(addFail(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 walk([...testPath, null], false, r)
+                    .step(sub => pure(mergeState(addPass(duration)(zero), sub)));
+            }
+            return pure(addFail(duration)(zero));
+        });
+    });
+    const walk = (path, throws, v) => {
+        const effects = collectTests(path, throws, v).map(one);
         return all(...effects)
             .step(states => pure(states.reduce(mergeState, zero)));
     };
@@ -80,17 +122,43 @@ const runModule = ({ result, test }) => (k, v) => (ts) => {
         .step(delta => pure(mergeState(ts, delta)));
 };
 const { entries } = Object;
+/**
+ * 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).
+ */
 export const runModuleMap = (reporter) => (moduleMap) => {
     const { summary } = reporter;
-    const modules = entries(moduleMap).filter(([k]) => isTest(k));
-    return modules.reduce((acc, [k, v]) => acc.step(runModule(reporter)(k, v)), pure({ time: 0, pass: 0, fail: 0 }))
+    const modules = entries(moduleMap)
+        .flatMap(([k, v]) => v.proof !== undefined ? [[k, v.proof]] : []);
+    return 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(() => pure(ts.fail !== 0 ? 1 : 0)));
 };
-export const test = (reporter) => options => loadModuleMap(options.env).step(runModuleMap(reporter));
+/**
+ * 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.
+ */
+export const testAll = (reporter) => options => loadModuleMap(options.env).step(runModuleMap(reporter));
+/**
+ * Registers all modules in `moduleMap` that export a `proof` property with
+ * `ctx`. Delegates to `registerModule` for each matching entry.
+ */
+const registerModuleMap = (ctx) => (moduleMap) => {
+    const modules = entries(moduleMap)
+        .flatMap(([k, v]) => v.proof !== undefined ? [[k, v.proof]] : []);
+    if (modules.length === 0) {
+        return pure(undefined);
+    }
+    return all(...modules.map(([k, v]) => registerModule(ctx, k, v))).step(() => pure(undefined));
+};
 const isAlpha = (c) => (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '_' || c === '$';
 const isDigit = (c) => c >= '0' && c <= '9';
+/** Returns `true` if `s` is a non-negative decimal integer without a leading zero. */
 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_$]*`). */
 export const isIdentifier = (s) => s.length > 0 && isAlpha(s[0]) && [...s.slice(1)].every(c => isAlpha(c) || isDigit(c));
 const fmtKey = (k) => k === null ? '()'
     : isInteger(k) ? `[${k}]`
@@ -105,10 +173,10 @@ const fmtKey = (k) => k === null ? '()'
 export const fmtPath = (path) => path.reduce((acc, k) => acc + fmtKey(k), '');
 /**
  * Formats a fully-qualified test identifier as a JS-like expression, e.g.
- * `import("./math.test.f.ts").add()` or `import("./a.test.f.ts").users[3].name()`.
+ * `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.
  */
-export const fmtImport = (file, path) => `import(${JSON.stringify(file)})${fmtPath(path)}()`;
+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
@@ -134,6 +202,10 @@ export const ghEscape = (s) => s.replaceAll('%', '%25')
     .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).
+ */
 export const defaultTest = (file, path, { fn, throws }) => sandbox(fn)
     .step(r => pure(throws ? { ...r, result: invert(r.result) } : r));
 const fmtResultLine = (file, path, color, label, duration) => `${fmtImport(file, path)}: ${color}${label}${reset}, ${timeFormat(duration)}`;
@@ -169,4 +241,20 @@ export const defaultReporter = (options) => {
         test: defaultTest,
     };
 };
-export const main = options => test(defaultReporter(options))(options);
+/** The `fjs t` entry point: runs all tests using `defaultReporter`. */
+export const main = options => testAll(defaultReporter(options))(options);
+/**
+ * Entry point for external test frameworks (Node `--test`, Bun, Playwright).
+ *
+ * Discovers test modules via `loadModuleMap`, then registers each with the
+ * framework-appropriate `TestContext` selected from `NodeProgramOptions`
+ * based on the detected `engine`.
+ */
+export const register = o => {
+    const r = registerModuleMap(o.engine === 'bun' ? o.bunTestContext :
+        o.engine === 'playwright' ? o.playwrightTestContext :
+            o.testContext);
+    return loadModuleMap(o.env)
+        .step(r)
+        .step(() => pure(0));
+};

package/fs/dev/tf/module.js

@@ -1,103 +1,4 @@
-import { io, tryCatch } from "../../io/module.js";
-import { loadModuleMap } from "../module.f.js";
-import { fmtImport, isTest, parseTestSet, runModuleMap } from "./module.f.js";
-import * as nodeTest from 'node:test';
-import { asyncImport } from "../../io/module.js";
-import { fromIo } from "../../io/module.f.js";
-import { pure } from "../../types/effects/module.f.js";
-import { asyncRun } from "../../types/effects/module.js";
-import {} from "../../types/effects/node/module.f.js";
-const isBun = typeof Bun !== 'undefined';
-const isPlaywright = typeof process !== 'undefined' && process?.env?.PLAYWRIGHT_TEST !== undefined;
-const createFramework = (fw) => (prefix, f) => fw.test(prefix, t => f((name, v) => t.test(name, v)));
-// Bun doesn't support nested tests yet.
-const createBunFramework = (fw) => (prefix, f) => f((name, v) => fw.test(`${prefix}: ${name}`, v));
-const createPlaywrightFramework = async () => {
-    const pwTest = (await asyncImport('@playwright/test')).test;
-    return (prefix, f) => f((name, v) => pwTest(`${prefix}: ${name}`, v));
-};
-const framework = isPlaywright ? await createPlaywrightFramework() :
-    isBun ? createBunFramework(nodeTest) :
-        createFramework(nodeTest);
-const scanModule = (x) => async (subTestRunner) => {
-    let subTests = [x];
-    while (true) {
-        const [first, ...rest] = subTests;
-        if (first === undefined) {
-            break;
-        }
-        subTests = rest;
-        //
-        const [name, value, throws] = first;
-        const set = parseTestSet(throws, value);
-        if (set instanceof Array) {
-            for (const [j, y] of set) {
-                const pr = `${name}/${j}`;
-                subTests = [...subTests, [pr, y, throws || j === 'throw']];
-            }
-        }
-        else {
-            await subTestRunner(name, () => {
-                if (set.throws) {
-                    let threw = false;
-                    try {
-                        set.fn();
-                    }
-                    catch (_) {
-                        threw = true;
-                    }
-                    if (!threw) {
-                        throw new Error(`${name}() expected to throw`);
-                    }
-                }
-                else {
-                    const r = set.fn();
-                    // The result of a function is walked as a fresh sub-tree;
-                    // the parent's `throws` flag does not propagate into it.
-                    subTests = [...subTests, [`${name}()`, r, false]];
-                }
-            });
-        }
-    }
-};
-const noOp = () => pure(undefined);
-const reporter = {
-    result: noOp,
-    summary: noOp,
-    test: (file, path, { throws, fn }) => {
-        nodeTest.test(fmtImport(file, path), async (_t) => {
-            const [s, r] = tryCatch(fn);
-            if (throws === (s === 'ok')) {
-                throw r;
-            }
-            if (!throws) {
-                // TODO: add subtests
-            }
-        });
-        return pure({
-            result: ['ok', undefined],
-            duration: 0,
-        });
-    }
-};
-const map = {
-    // TODO: we use the same algorithm twice. Refactor by creating a `createAll(map)`
-    // helper that takes a `map` and returns an `all` function that runs effects
-    // according to the map. There could be a problem with circular dependencies,
-    // but we can use a lazy function `() => ToAsyncOperationMap<All>` instead od `map`.
-    all: async (...effects) => Promise.all(effects.map(asyncRun(map))),
-};
-export const run3 = async () => {
-    const fio = fromIo(io);
-    const moduleMap = await fio(loadModuleMap(io.process.env));
-    const runner = runModuleMap(reporter)(moduleMap);
-    await asyncRun(map)(runner);
-};
-export const run = async () => {
-    const moduleMap = await fromIo(io)(loadModuleMap(io.process.env));
-    for (const [i, v] of Object.entries(moduleMap)) {
-        if (isTest(i)) {
-            framework(i, scanModule(['', v, false]));
-        }
-    }
-};
+import { io } from "../../io/module.js";
+import { register } from "./module.f.js";
+import { runProgram } from "../../io/module.f.js";
+export const run = () => runProgram(io)([])(register);

package/fs/dev/tf/{test.f.d.ts → proof.f.d.ts}

@@ -15,8 +15,34 @@ export declare const githubReporterOutput: () => void;
 export declare const helpers: {
     isInteger: () => void;
     isIdentifier: () => void;
+    shouldLoad: () => void;
     fmtImport: () => void;
     fmtPath: () => void;
     fmtTerm: () => void;
     ghEscape: () => void;
 };
+export declare const proof: {
+    flat: () => void;
+    nested: () => void;
+    throwKey: () => void;
+    throwKeyFail: () => void;
+    mixedPassFail: () => void;
+    returnValueSubTree: () => void;
+    arrayKeys: () => void;
+    nonTestFilesSkipped: () => void;
+    multipleFiles: () => void;
+    throwByFunctionName: () => void;
+    namedExports: () => void;
+    defaultReporterOutput: () => void;
+    defaultReporterFailOutput: () => void;
+    githubReporterOutput: () => void;
+    helpers: {
+        isInteger: () => void;
+        isIdentifier: () => void;
+        shouldLoad: () => void;
+        fmtImport: () => void;
+        fmtPath: () => void;
+        fmtTerm: () => void;
+        ghEscape: () => void;
+    };
+};