functionalscript 0.43.1 → 0.45.0

package/fjs/emergent_testing/module.f.js

@@ -1,289 +0,0 @@
-/**
- * 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.js';
-import { all, awaitIfPromise, sandbox, test } from '../effects/node/module.f.js';
-import { history, historyStep, pure, step } from '../effects/module.f.js';
-import { eff } from '../effects/eff/module.f.js';
-import { loadModuleMap, shouldLoad } from '../dev/module.f.js';
-import { invert } from '../types/result/module.f.js';
-import { definedEntries } from '../types/object/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) => {
-    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.
- */
-export const parseTestSet = (throws, x) => {
-    switch (typeof x) {
-        case 'function': {
-            if (x.length === 0) {
-                const fn = 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.
- */
-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.
- */
-export const registerModule = (ctx, k, v, star) => {
-    const registerOne = (ctx, [path, { fn, throws }]) => {
-        // ' *' (non-empty only for Bun) 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) => 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;
-};
-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 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)));
-        });
-    };
-    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;
-};
-const proofEntries = (moduleMap) => definedEntries(moduleMap)
-    .flatMap(([k, v]) => v.proof !== undefined ? [[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).
- */
-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.
- */
-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.
- */
-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;
-};
-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}]`
-        : 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`.
- */
-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.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)}).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"`.
- */
-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
- */
-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).
- */
-export const defaultTest = (file, path, { fn, throws }) => eff(sandbox(fn))
-    .step(r => pure(throws ? { ...r, result: invert(r.result) } : r))
-    .value;
-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.
- */
-export const defaultReporter = (options) => {
-    const write = csiWrite(options);
-    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`. */
-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`.
- */
-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;
-};

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

@@ -1,67 +0,0 @@
-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 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 {};