functionalscript 0.19.0 → 0.21.0

package/fs/{dev/tf → emergent-testing}/module.f.d.ts

@@ -1,13 +1,33 @@
-import { type All, 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;
+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 '../dev/module.f.ts';
+/** 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: 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];
 /**
@@ -26,16 +46,42 @@ export declare const collectTests: (path: Path, throws: boolean, v: unknown) =>
  * contained `inner`.
  */
 export type Reporter<O extends Operation> = {
-    readonly result: (file: string, path: Path, r: SandboxResult<unknown>) => Effect<O, void>;
+    readonly result: (file: string, path: Path, r: SandboxResult<unknown>, throws: boolean) => Effect<O, void>;
     readonly summary: (pass: number, fail: number, time: number) => Effect<O, void>;
     readonly test: (file: string, path: Path, set: TestEntry) => Effect<O, SandboxResult<unknown>>;
 };
-export declare const registerModule: (ctx: TestContext, k: string, v: unknown) => Effect<Test | All, void>;
+/**
+ * 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, 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).
+ */
 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.
+ */
 export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
-export declare const registerModuleMap: (ctx: TestContext, moduleMap: ModuleMap) => Effect<Test | All, void>;
+/**
+ * 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
@@ -46,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;
@@ -63,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
@@ -72,6 +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 → emergent-testing}/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, test } from "../../types/effects/node/module.f.js";
-import { pure, do_ } from "../../types/effects/module.f.js";
-import { loadModuleMap } 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');
+import { reset, fgGreen, fgRed, bold, csiWrite } from "../text/sgr/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, shouldLoad } from "../dev/module.f.js";
+import { invert } from "../types/result/module.f.js";
 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,19 +65,36 @@ export const collectTests = (path, throws, v) => {
     }
     return [[path, set]];
 };
-export const registerModule = (ctx, k, v) => {
-    const registerOne = (ctx, [path, { fn, throws }]) => test(ctx, fmtImport(k, path), throws, (t) => {
-        if (throws) {
-            fn();
-            return pure(undefined);
-        }
-        const r = fn();
-        const sub = collectTests([...path, null], false, r);
-        if (sub.length === 0) {
-            return pure(undefined);
-        }
-        return all(...sub.map(e => registerOne(t, e))).step(() => pure(undefined));
-    });
+/**
+ * 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, star) => {
+    const registerOne = (ctx, [path, { fn, throws }]) => {
+        // ' *' (non-empty only for Bun/Playwright) signals that all sub-tests run
+        // inline inside this single registration. 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, (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);
@@ -76,7 +107,7 @@ const runModule = ({ result, test }) => (k, v) => (ts) => {
     const one = ([testPath, set]) => test(k, testPath, set)
         .step(sr => {
         const { result: [s, r], duration } = sr;
-        return result(k, testPath, sr)
+        return result(k, testPath, sr, set.throws)
             .step(() => {
             if (s === 'ok') {
                 if (set.throws) {
@@ -99,24 +130,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)));
 };
+/**
+ * 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));
-export const registerModuleMap = (ctx, moduleMap) => {
-    const modules = entries(moduleMap).filter(([k]) => isTest(k));
+/**
+ * Registers all modules in `moduleMap` that export a `proof` property with
+ * `ctx`. Delegates to `registerModule` for each matching entry.
+ */
+const registerModuleMap = (ctx, star) => (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));
+    return all(...modules.map(([k, v]) => registerModule(ctx, k, v, star))).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}]`
@@ -131,10 +181,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
@@ -160,6 +210,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)}`;
@@ -181,8 +235,8 @@ export const defaultReporter = (options) => {
     const isGitHub = options.env['GITHUB_ACTION'] !== undefined;
     return {
         // https://github.com/OndraM/ci-detector/blob/main/src/Ci/GitHubActions.php
-        result: (file, path, { result: [s, v], duration }) => s === 'ok'
-            ? csiLog(fmtResultLine(file, path, fgGreen, 'ok', duration))
+        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))}`)
                 : csiError(fmtResultLine(file, path, fgRed, 'error', duration))
@@ -195,9 +249,22 @@ export const defaultReporter = (options) => {
         test: defaultTest,
     };
 };
+/** The `fjs t` entry point: runs all tests using `defaultReporter`. */
 export const main = options => testAll(defaultReporter(options))(options);
-export const register = o => loadModuleMap(o.env)
-    .step(m => registerModuleMap(o.engine === 'bun' ? o.bunTestContext :
-    o.engine === 'playwright' ? o.playwrightTestContext :
-        o.testContext, m))
-    .step(() => pure(0));
+/**
+ * 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 star = o.engine === 'bun' || o.engine === 'playwright' ? ' ...' : '';
+    const ctx = o.engine === 'bun' ? o.bunTestContext :
+        o.engine === 'playwright' ? o.playwrightTestContext :
+            o.testContext;
+    const r = registerModuleMap(ctx, star);
+    return loadModuleMap(o.env)
+        .step(r)
+        .step(() => pure(0));
+};

package/fs/{dev/tf → emergent-testing}/module.js

@@ -1,4 +1,4 @@
-import { io } from "../../io/module.js";
+import { io } from "../io/module.js";
 import { register } from "./module.f.js";
-import { runProgram } from "../../io/module.f.js";
+import { runProgram } from "../io/module.f.js";
 export const run = () => runProgram(io)([])(register);

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

@@ -12,11 +12,39 @@ export declare const namedExports: () => void;
 export declare const defaultReporterOutput: () => void;
 export declare const defaultReporterFailOutput: () => void;
 export declare const githubReporterOutput: () => void;
+export declare const registerSuffixes: () => 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;
+    registerSuffixes: () => void;
+    helpers: {
+        isInteger: () => void;
+        isIdentifier: () => void;
+        shouldLoad: () => void;
+        fmtImport: () => void;
+        fmtPath: () => void;
+        fmtTerm: () => void;
+        ghEscape: () => void;
+    };
+};