functionalscript 0.38.0 → 0.40.0

package/fjs/common/monoid/module.f.d.ts

@@ -1,11 +1,13 @@
 /**
  * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
- * binary operation) and `repeat`, which applies the operation `n` times using
- * exponentiation by squaring.
+ * binary operation), `repeat`, which applies the operation `n` times using
+ * exponentiation by squaring, and `fold`, which applies it across every element
+ * of a list.
  *
  * @module
  */
 import type { Fold, Reduce } from '../../types/function/operator/module.f.ts';
+import { type List } from '../../types/list/module.f.ts';
 /**
  * Represents a monoid, an algebraic structure with a binary operation
  * and an identity (neutral) element.
@@ -80,3 +82,45 @@ export type Monoid<T> = {
  * ```
  */
 export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<bigint, T>;
+/**
+ * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
+ * `identity`. An empty list folds to `identity`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param monoid The monoid structure, including the identity and binary operation.
+ * @returns A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+export declare const fold: <T>({ identity, operation }: Monoid<T>) => (list: List<T>) => T;

package/fjs/common/monoid/module.f.js

@@ -1,3 +1,5 @@
+import { reduce } from '../../types/list/module.f.js';
+import { flip } from '../../types/function/module.f.js';
 /**
  * Repeats a monoid operation `n` times on the given element `a`.
  * This function efficiently performs the operation using exponentiation by squaring.
@@ -42,3 +44,45 @@ export const repeat = ({ identity, operation }) => n => a => {
         ai = operation(ai)(ai);
     }
 };
+/**
+ * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
+ * `identity`. An empty list folds to `identity`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param monoid The monoid structure, including the identity and binary operation.
+ * @returns A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+export const fold = ({ identity, operation }) => reduce(flip(operation))(identity);

package/fjs/common/monoid/proof.f.d.ts

@@ -1,4 +1,9 @@
 export declare const proof: {
     numberAdd: () => void;
     stringConcat: () => void;
+    fold: {
+        nonEmpty: () => void;
+        order: () => void;
+        empty: () => void;
+    };
 };

package/fjs/common/monoid/proof.f.js

@@ -1,4 +1,4 @@
-import { repeat } from "./module.f.js";
+import { repeat, fold } from "./module.f.js";
 import { assertEq } from '../../asserts/module.f.js';
 export const proof = {
     numberAdd: () => {
@@ -18,5 +18,31 @@ export const proof = {
         };
         const resultConcat = repeat(concat)(3n)('ha'); // 'hahaha'
         assertEq(resultConcat, 'hahaha');
+    },
+    fold: {
+        nonEmpty: () => {
+            const add = {
+                identity: 0,
+                operation: a => b => a + b,
+            };
+            assertEq(fold(add)([1, 2, 3, 4]), 10);
+        },
+        order: () => {
+            // a non-commutative monoid: `fold` must preserve left-to-right order
+            // (`((('' + 'a') + 'b') + 'c')`), not reverse it to `'cba'`.
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            assertEq(fold(concat)(['a', 'b', 'c']), 'abc');
+        },
+        empty: () => {
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            // an empty list folds to the identity
+            assertEq(fold(concat)([]), '');
+        },
     }
 };

package/fjs/dev/module.f.d.ts

@@ -42,4 +42,5 @@ export type LoadModuleOperations = Access | Import | All | Readdir;
 export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap>;
 export declare const proof: {
     isSourceFile: () => void;
+    allFilesSkipsNodeModules: () => void;
 };

package/fjs/dev/module.f.js

@@ -6,9 +6,10 @@
 import { all, import_, readdir } from '../effects/node/module.f.js';
 import { cmp as strCmp } from '../types/string/module.f.js';
 import { unwrap } from '../types/result/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 import { join, relativize, toPosix } from '../path/module.f.js';
-import { assert } from '../asserts/module.f.js';
+import { assert, assertEq } from '../asserts/module.f.js';
+import { emptyState, virtual } from '../effects/node/virtual/module.f.js';
 /**
  * Returns `true` if the file should be loaded for proof discovery.
  *
@@ -25,32 +26,33 @@ export const shouldLoad = (s) => s.endsWith('.f.ts') || s.endsWith('.f.js') ||
     s.endsWith('proof.mts') || s.endsWith('proof.mjs');
 const isSourceFile = (path) => path.endsWith('.js') || path.endsWith('.ts') || path.endsWith('.mts') || path.endsWith('.mjs');
 const allFiles = (s, predicate) => {
-    const load = (p) => readdir(p, {})
-        .step(d => {
-        let result = [];
-        for (const i of unwrap(d)) {
-            const { name } = i;
-            if (name.startsWith('.')) {
-                continue;
-            }
-            const file = join(p, name);
-            if (!i.isFile) {
-                if (name === 'node_modules') {
+    const load = (p) => {
+        const x0 = step(readdir(p, {}), d => {
+            let result = [];
+            for (const i of unwrap(d)) {
+                const { name } = i;
+                if (name.startsWith('.')) {
                     continue;
                 }
-                result = [...result, load(file)];
-                continue;
-            }
-            if (predicate(file)) {
-                result = [...result, pure([file])];
+                const file = join(p, name);
+                if (!i.isFile) {
+                    if (name === 'node_modules') {
+                        continue;
+                    }
+                    result = [...result, load(file)];
+                    continue;
+                }
+                if (predicate(file)) {
+                    result = [...result, pure([file])];
+                }
             }
-        }
-        return all(...result);
-    })
-        .step(v => pure(v.flat()));
+            return all(...result);
+        });
+        return step(x0, v => pure(v.flat()));
+    };
     return load(s);
 };
-const loadFile = (f) => import_(f).step(r => pure([[f, unwrap(r)]]));
+const loadFile = (f) => step(import_(f), r => pure([[f, unwrap(r)]]));
 const { fromEntries } = Object;
 /**
  * Discovers all source files under `INIT_CWD` (or `.` if unset) that match
@@ -71,12 +73,11 @@ export const loadModuleMap = (env) => {
     const s = initCwd === undefined ? '.' : toPosix(initCwd);
     const prefix = s === '.' ? '' : s;
     // TODO: there are multiple `all` effects here,
-    //       we should consider optimize them by ALIQ technique or something similar.
+    //       we should consider optimizing them by ALIQ technique or something similar.
     //       For example, we should be able to write it like `allFiles(s).flatMap(loadFile)`,
     //       then an effect runner can batch all file loading operations together.
-    return allFiles(s, shouldLoad)
-        .step(files => all(...files.map(loadFile)))
-        .step(entries => pure(fromEntries(entries
+    const x0 = step(allFiles(s, shouldLoad), files => all(...files.map(loadFile)));
+    return step(x0, entries => pure(fromEntries(entries
         .flat()
         .map(([k, v]) => [relativize(prefix, k), v])
         .toSorted(([a], [b]) => strCmp(a)(b)))));
@@ -90,4 +91,14 @@ export const proof = {
         assert(!isSourceFile('readme.md'));
         assert(!isSourceFile('module.json'));
     },
+    allFilesSkipsNodeModules: () => {
+        // `node_modules` is skipped without descending into it, even though
+        // it contains a file that would otherwise match the predicate.
+        const root = {
+            'node_modules': { 'pkg.f.ts': [] },
+            'a.f.ts': [],
+        };
+        const [, result] = virtual({ ...emptyState, root })(allFiles('.', shouldLoad));
+        assertEq(result.join(','), './a.f.ts');
+    },
 };

package/fjs/dev/update/module.f.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { type Effect } from '../../effects/module.f.ts';
+import { type Mkdir, type NodeProgram, type ReadFile, type WriteFile } from '../../effects/node/module.f.ts';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void>;
+/** Runs all local development configuration generators. */
+export declare const main: NodeProgram;

package/fjs/dev/update/module.f.js

@@ -0,0 +1,20 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { history, historyStep, mapStep, step } from '../../effects/module.f.js';
+import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
+const source = '.copilot/mcp.json';
+const targetDirectory = '.vscode';
+const target = '.vscode/mcp.json';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export const syncMcp = () => {
+    const sourceText = history(mapStep(readUtf8File(source), unwrap));
+    const targetDirectoryReady = historyStep(sourceText, () => mapStep(mkdir(targetDirectory, { recursive: true }), unwrap));
+    const targetWritten = step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text));
+    return mapStep(targetWritten, unwrap);
+};
+/** Runs all local development configuration generators. */
+export const main = () => mapStep(syncMcp(), () => 0);

package/fjs/dev/update/proof.f.d.ts

@@ -0,0 +1,7 @@
+export declare const proof: {
+    syncMcp: () => void;
+    main: () => void;
+    throw: {
+        missingSource: () => readonly [import("../../effects/node/virtual/module.f.ts").State, void];
+    };
+};

package/fjs/dev/update/proof.f.js

@@ -0,0 +1,35 @@
+/**
+ * Proofs for local development configuration generation.
+ *
+ * @module
+ */
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { utf8 } from '../../text/module.f.js';
+import { readUtf8File } from '../../effects/node/module.f.js';
+import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { main, syncMcp } from './module.f.js';
+import { step } from '../../effects/module.f.js';
+const mcp = '{"servers":{}}';
+const initial = {
+    ...emptyState,
+    root: {
+        '.copilot': {
+            'mcp.json': [utf8(mcp)],
+        },
+    },
+};
+export const proof = {
+    syncMcp: () => {
+        const generatedMcp = step(syncMcp(), () => readUtf8File('.vscode/mcp.json'));
+        const [, [tag, result]] = virtual(initial)(generatedMcp);
+        assert(tag === 'ok', result);
+        assertEq(result, mcp);
+    },
+    main: () => {
+        const [, result] = virtual(initial)(main(defaultNodeProgramOptions));
+        assertEq(result, 0);
+    },
+    throw: {
+        missingSource: () => virtual(emptyState)(syncMcp()),
+    },
+};

package/fjs/djs/ast/module.f.d.ts

@@ -4,12 +4,59 @@
  * @module
  */
 import type { Primitive, Array, Unknown } from '../module.f.ts';
+/**
+ * A parsed DJS module: its imported module specifiers, in source order, and
+ * its body.
+ *
+ * The specifier list indexes `['aref', i]`.
+ */
 export type AstModule = [readonly string[], AstBody];
+/** A value in a module body: a primitive, a reference, an array, or an object. */
 export type AstConst = Primitive | AstModuleRef | AstArray | AstObject;
+/**
+ * A reference to a value defined outside this `AstConst`.
+ *
+ * - `['aref', i]` — the `i`-th argument of the body, i.e. the `i`-th imported
+ *   module of the enclosing `AstModule`.
+ * - `['cref', i]` — the `i`-th entry of the enclosing `AstBody`.
+ *
+ * Both indices are absolute and zero-based, **not** offsets from the
+ * referencing entry: in the body `[a, b, ['cref', 0]]` the reference resolves
+ * to `a`, not to the nearest preceding entry `b`.
+ *
+ * A `cref` index must be smaller than the index of the entry holding it —
+ * `run` evaluates a body left to right, so a reference to the current or a
+ * later entry is unsatisfiable. It is not rejected: it resolves to the most
+ * recently evaluated entry instead.
+ */
 export type AstModuleRef = ['aref' | 'cref', number];
+/** An array value; its elements are evaluated in order. */
 export type AstArray = ['array', readonly AstConst[]];
+/** An object value, keyed by property name. */
 export type AstObject = {
     readonly [k in string]?: AstConst;
 };
+/**
+ * The constants of a module body, in declaration order. The **last** entry is
+ * the value the module yields; the preceding entries exist to be named by
+ * `['cref', i]`.
+ *
+ * A body describes the function
+ *
+ * ```js
+ * (...args) => { const c0 = ...; const c1 = ...; return <last> }
+ * ```
+ *
+ * where `args` are the imported modules.
+ */
 export type AstBody = readonly AstConst[];
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ */
 export declare const run: (body: AstBody) => (args: Array) => Unknown;

package/fjs/djs/ast/module.f.js

@@ -42,6 +42,15 @@ const toDjs = state => ast => {
         }
     }
 };
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ */
 export const run = body => args => {
     const state = fold(foldOp)({ body, args, consts: null })(body);
     return last(null)(state.consts);

package/fjs/djs/module.f.js

@@ -1,25 +1,22 @@
 import { transpile } from './transpiler/module.f.js';
 import { stringify, stringifyAsTree } from './serializer/module.f.js';
 import { sort } from '../types/object/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 import { writeUtf8File, error, } from '../effects/node/module.f.js';
 export const compile = args => {
     if (args.length < 2) {
-        return error('Error: Requires 2 or more arguments')
-            .step(() => pure(1));
+        return step(error('Error: Requires 2 or more arguments'), () => pure(1));
     }
     const inputFileName = args[0];
     const outputFileName = args[1];
-    return transpile(inputFileName).step((result) => {
+    return step(transpile(inputFileName), (result) => {
         if (result[0] === 'error') {
             const metadata = result[1].metadata;
-            return error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`)
-                .step(() => pure(0));
+            return step(error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`), () => pure(0));
         }
         const content = outputFileName.endsWith('.json')
             ? stringifyAsTree(sort)(result[1])
             : stringify(sort)(result[1]);
-        return writeUtf8File(outputFileName, content)
-            .step(() => pure(0));
+        return step(writeUtf8File(outputFileName, content), () => pure(0));
     });
 };

package/fjs/djs/parser/module.f.d.ts

@@ -17,4 +17,7 @@ export declare const proof: {
     pushKey: {
         nonObjectTop: () => void;
     };
+    endArray: {
+        nonArrayTop: () => void;
+    };
 };

package/fjs/djs/parser/module.f.js

@@ -380,4 +380,21 @@ export const proof = {
             assertEq(result.state, 'error');
         },
     },
+    endArray: {
+        // `endArray` is only ever invoked while `state.top` is an array (the
+        // `'['`/`'[v'`/`'[,'` value-states guarantee it), so its non-array
+        // guard is a defensive branch unreachable through `parseFromTokens`.
+        // Call it directly to cover that branch.
+        nonArrayTop: () => {
+            const state = {
+                state: 'exportValue',
+                module: { refs: null, modules: null, consts: null },
+                valueState: '[,',
+                top: null,
+                stack: null,
+            };
+            const result = endArray(state);
+            assertEq(result.state, 'result');
+        },
+    },
 };

package/fjs/djs/tokenizer/module.f.js

@@ -364,7 +364,7 @@ export const tokenizeString = s => {
     }
     const m = descentParser(jsGrammar());
     const cpm = codePointsWithMetadata('')(cp);
-    const [ast, ok, len] = m('', cpm);
+    const { ast, success: ok, idx: len } = m('', cpm);
     if (!ok || len !== cp.length)
         return 'error';
     const flatTokens = toArray(getTokensFromAstRule(ast));
@@ -394,7 +394,7 @@ export const tokenizeJs = input => path => {
         return [{ token: { kind: 'eof' }, metadata: initial }];
     const m = descentParser(jsGrammar());
     const cpm = codePointsWithMetadata(path)(cp);
-    const [ast, ok, len] = m('', cpm);
+    const { ast, success: ok, idx: len } = m('', cpm);
     const finalMetadata = fold(advanceMetadata)(initial)(cp);
     if (!ok || len !== cp.length) {
         const errorMetadata = len < cpm.length ? cpm[len][1] : finalMetadata;

package/fjs/djs/tokenizer/proof.f.d.ts

@@ -8,6 +8,7 @@ export declare const proof: {
     keywords: (() => void)[];
     comments: (() => void)[];
     metadata: (() => void)[];
+    errorPosition: (() => void)[];
     djsTokenize: (() => void)[];
     largeInputs: (() => void)[];
 };