functionalscript 0.44.0 → 0.46.0

package/fjs/emergent_testing/module.f.mjs

@@ -9,32 +9,22 @@
  *   scheduling and pass/fail counting.
  *
  * @module
+ *
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Effect, NotImplemented } 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, IoChannel, 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 {
-    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 { allOk, awaitIfPromise, errorExit, errorMessage, errorSummary, exitStep, sandbox, test } from '../effects/node/module.f.mjs'
+import {
+    catchStep, history, historyStep, mapStep, pureError, pureOk, resultStep, step,
+} from '../effects/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 =>
@@ -117,10 +107,10 @@ export const collectTests = (path, throws, v) => {
  * 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>}
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void, NotImplemented>}
  */
 export const registerModule = (ctx, k, v, star) => {
-    /** @type {(ctx: TestContext, entry: _TestAndPath) => Effect<Test | All | Await, void>} */
+    /** @type {(ctx: TestContext, entry: _TestAndPath) => Effect<Test | All | Await, void, NotImplemented>} */
     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
@@ -130,28 +120,38 @@ export const registerModule = (ctx, k, v, star) => {
         // 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
-        )
+        // The registered callback panics on failure, deliberately. `Test` hands
+        // it to an external framework (node `--test`, Bun, Deno) that takes a
+        // body which either returns or throws: there is no channel to answer a
+        // failure through, so propagating it here would only discard it one
+        // level up.
+        // A throw is what that framework *does* understand — it reports the
+        // test as failed, which is the outcome a caller wants anyway. The `test`
+        // operation's own result is propagated normally, just below.
+        //
+        // `catchStep` rather than `unwrapStep`, so the absorption is visible in
+        // the type: the body answers `Effect<…, void, never>`, and the `never`
+        // is *because* this handler panics. `errorSummary` still names what is
+        // being panicked on and pins it, so if the body's channel ever widens
+        // past the node one, the compiler asks here rather than turning a new
+        // recoverable failure into a crash.
+        /** @type {(t: TestContext) => Effect<Test | All | Await, void, never>} */
+        const body = t =>
+            catchStep(step(awaitIfPromise(fn()), resolved => {
+                if (throws) {
+                    return pureOk(undefined)
+                }
+                const sub = collectTests([...path, null], false, resolved)
+                if (sub.length === 0) {
+                    return pureOk(undefined)
+                }
+                return mapStep(allOk(...sub.map(e => registerOne(t, e))), () => undefined)
+            }), e => { throw errorSummary(e) })
+        return test(ctx, name, throws, body)
     }
     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
+    if (tests.length === 0) { return pureOk(undefined) }
+    return mapStep(allOk(...tests.map(e => registerOne(ctx, e))), () => undefined)
 }
 
 /** @type {(a: _TestState, b: _TestState) => _TestState} */
@@ -164,10 +164,10 @@ 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>}
+ * @returns {(k: string, v: unknown) => (ts: _TestState) => Effect<O | All, _TestState, IoChannel>}
  */
 const runModule = ({ result, test }) => (k, v) => ts => {
-    /** @type {(entry: _TestAndPath) => Effect<O | All, _TestState>} */
+    /** @type {(entry: _TestAndPath) => Effect<O | All, _TestState, IoChannel>} */
     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.
@@ -179,28 +179,24 @@ const runModule = ({ result, test }) => (k, v) => ts => {
             ([, sr]) => {
                 const { result: [s, r], duration } = sr
                 if (s !== 'ok') {
-                    return pure(addFail(duration)(zero))
+                    return pureOk(addFail(duration)(zero))
                 }
                 if (set.throws) {
-                    return pure(addPass(duration)(zero))
+                    return pureOk(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(
+                return mapStep(
                     walk([...testPath, null], false, r),
-                    sub => pure(mergeState(addPass(duration)(zero), sub)))
+                    sub => mergeState(addPass(duration)(zero), sub))
             })
     }
-    /** @type {(path: Path, throws: boolean, v: unknown) => Effect<O | All, _TestState>} */
+    /** @type {(path: Path, throws: boolean, v: unknown) => Effect<O | All, _TestState, IoChannel>} */
     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 mapStep(allOk(...effects), states => states.reduce(mergeState, zero))
     }
-    return eff(walk([], false, v))
-        .step(delta => pure(mergeState(ts, delta)))
-        .value
+    return mapStep(walk([], false, v), delta => mergeState(ts, delta))
 }
 
 /** @type {(moduleMap: ModuleMap) => readonly (readonly [string, unknown])[]} */
@@ -215,44 +211,74 @@ const proofEntries = moduleMap =>
  *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number, IoChannel>}
  */
 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
+    const total = mapStep(
+        allOk(...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)
 }
 
+/**
+ * Ends a run with the exit code it computed, reporting a channel failure on
+ * `stderr` as exit `1`.
+ *
+ * Not `exitStep`, which answers `0` for every success: this chain's success
+ * value **is** the exit code, `1` when a test failed. The two policies differ
+ * only in what an `ok` means, and conflating them would report a failing suite
+ * as a passing run.
+ *
+ * A non-zero code therefore leaves through the *error* branch, which is what it
+ * means — a suite with failures is a failed program — and is why a caller
+ * cannot chain past it by accident.
+ *
+ * @type {<O extends Operation>(e: Effect<O, number, IoChannel>) => Effect<O | Write, 0, number>}
+ */
+const exitCodeStep = e =>
+    resultStep(e, r => {
+        /** @type {Effect<Write, 0, number>} */
+        const code = r[0] === 'error'
+            ? errorExit(errorMessage(r[1]))
+            : r[1] === 0 ? pureOk(0) : pureError(r[1])
+        return code
+    })
+
 /**
  * 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.
  *
+ * The chain leaves the error channel here, because this is where a `Program` ends
+ * and a `Program`'s answer is an exit code rather than a `Result`. A run that
+ * could not report its own results is a failed run, so it exits `1` with the
+ * reason on `stderr` instead of unwinding as a panic.
+ *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {Program<O | All | LoadModuleOperations>}
+ * @returns {Program<O | All | LoadModuleOperations | Write>}
  */
 export const testAll = reporter => options =>
-    eff(loadModuleMap(options.env))
-        .step(runModuleMap(reporter))
-        .value
+    exitCodeStep(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>}
+ * @type {(ctx: TestContext, star: string) => (moduleMap: ModuleMap) => Effect<Test | All | Await, void, NotImplemented>}
  */
 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
+    if (modules.length === 0) { return pureOk(undefined) }
+    return mapStep(allOk(...modules.map(([k, v]) => registerModule(ctx, k, v, star))), () => undefined)
 }
 
 /** @type {(c: string) => boolean} */
@@ -338,12 +364,10 @@ export const ghEscape = s =>
  * 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>>}
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>, NotImplemented>}
  */
 export const defaultTest = (file, path, { fn, throws }) =>
-    eff(sandbox(fn))
-        .step(r => pure(throws ? { ...r, result: invert(r.result) } : r))
-        .value
+    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) =>
@@ -360,7 +384,12 @@ const fmtResultLine = (file, path, color, label, duration) =>
  */
 export const defaultReporter = options => {
     const write = csiWrite(options)
-    /** @type {(w: WriteConsoles) => (s: string) => Effect<Write, void>} */
+    // A reporter that cannot emit its own output has no fallback to choose —
+    // there is nowhere left to report the failure — but it does not have to
+    // decide that here: the failure travels to the program's tail, which ends
+    // the run with the reason on `stderr` and exit `1`. That is the same
+    // outcome a panic produced, minus the stack trace.
+    /** @type {(w: WriteConsoles) => (s: string) => Effect<Write, void, NotImplemented>} */
     const line = w => {
         const x = write(w)
         return s => x(s + '\n')
@@ -375,14 +404,17 @@ export const defaultReporter = options => {
                 ? 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,
+                    // `step`, so the detail line is attempted only when the
+                    // header line was written: two halves of one report, and
+                    // half of it is worse than none.
+                    : step(
+                        csiError(fmtResultLine(file, path, fgRed, 'error', duration)),
+                        () => csiError(`${fgRed}${v}${reset}`)),
         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
+            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,
     }
@@ -407,8 +439,10 @@ export const main =
 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
+    const registered = step(loadModuleMap(o.env), registerModuleMap(ctx, star))
+    // `exitStep`, not `mapStep(…, () => 0)`: registering is the whole job here,
+    // so "registered nothing, exit 0" is the answer this used to give and the
+    // one it must not. A success has no code of its own, which is exactly the
+    // shape `exitStep` is for.
+    return exitStep(registered)
 }

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

@@ -1,15 +1,17 @@
 /**
- * @import { Effect } from '../effects/types.ts'
- * @import { NodeProgramOptions, Sandbox, Write } from '../effects/node/types.ts'
+ * @import { RunInstance } from '../effects/mock/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
+ * @import { NodeProgramOptions, OpResult, 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 { All, Await, Import, Readdir, Test, TestContext } from '../effects/node/types.ts'
  * @import { Ts } from '../types/rtti/ts/types.ts'
  */
+import type { RunInstance } from '../effects/mock/types.ts';
 import type { Effect } from '../effects/types.ts';
-import type { Sandbox, Write } from '../effects/node/types.ts';
+import type { OpResult, 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 { All, Await, Import, Readdir, 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:
@@ -39,13 +41,19 @@ export declare const defaultReporterOutput: () => void;
 export declare const defaultReporterOutputLargeDuration: () => void;
 export declare const defaultReporterFailOutput: () => void;
 export declare const githubReporterOutput: () => void;
+export type _FailOps = All | Import | Readdir | Sandbox | Write;
+/** @typedef {All | Import | Readdir | Sandbox | Write} _FailOps */
+export declare const reporterWriteFailure: () => 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 type _RegisterRunner = RunInstance<_RegisterMockOps, _RegisterMockState>;
+export type _RegisterTestOp = (runner: _RegisterRunner, ctx: TestContext, name: string, expectFailure: boolean, fn: (t: TestContext) => Effect<_RegisterMockOps, void, never>) => (s: _RegisterMockState) => readonly [_RegisterMockState, OpResult<void>];
 export declare const registerSuffixes: () => void;
+declare const registerBodyPanicsOnUndispatchableEffect: () => void;
 export declare const registerThrowsWithoutThrowing: () => void;
 export declare const registerEmptyProof: () => void;
+export declare const registerEmptyModuleMap: () => void;
+export declare const registerSelectsContextAndStar: () => void;
 export declare const helpers: {
     isInteger: () => void;
     isIdentifier: () => void;
@@ -61,6 +69,9 @@ export declare const helpers: {
 };
 declare const defaultReporterExpectedToThrow: () => void;
 export declare const proof: {
+    throw: {
+        registerBodyPanicsOnUndispatchableEffect: typeof registerBodyPanicsOnUndispatchableEffect;
+    };
     flat: typeof flat;
     nested: typeof nested;
     throwKey: typeof throwKey;
@@ -76,9 +87,12 @@ export declare const proof: {
     defaultReporterOutputLargeDuration: typeof defaultReporterOutputLargeDuration;
     defaultReporterFailOutput: typeof defaultReporterFailOutput;
     githubReporterOutput: typeof githubReporterOutput;
+    reporterWriteFailure: typeof reporterWriteFailure;
     registerSuffixes: typeof registerSuffixes;
     registerThrowsWithoutThrowing: typeof registerThrowsWithoutThrowing;
     registerEmptyProof: typeof registerEmptyProof;
+    registerEmptyModuleMap: typeof registerEmptyModuleMap;
+    registerSelectsContextAndStar: typeof registerSelectsContextAndStar;
     defaultReporterExpectedToThrow: typeof defaultReporterExpectedToThrow;
     helpers: {
         isInteger: () => void;