functionalscript 0.44.0 → 0.46.0

package/fjs/crypto/vdf/module.f.mjs

@@ -15,12 +15,14 @@
  * const y = sloth.eval(steps)(x)
  * if (y === null || !sloth.verify(steps)(x)(y)) { throw y }
  * ```
+ *
+ * @import { PrimeField } from '../../types/prime_field/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Unary } from '../../types/bigint/types.ts'
+ * @import { Sloth } from './types.ts'
  */
+
 import { modSqrt, prime_field } from '../../types/prime_field/module.f.mjs'
-/** @import { PrimeField } from '../../types/prime_field/types.ts' */
-/** @import { Nullable } from '../../types/nullable/types.ts' */
-/** @import { Unary } from '../../types/bigint/types.ts' */
-/** @import { Sloth } from './types.ts' */
 
 /** Sloth VDF modulus (3072-bit safe prime, same as reference implementations). */
 export const p =

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

@@ -2,12 +2,15 @@
  * Development utilities for indexing modules and loading FunctionalScript files.
  *
  * @module
+ *
+ * @import { Access, All, Env, Import, IoChannel, Readdir } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Module, ModuleMap, LoadModuleOperations } from './types.ts'
  */
-import type { Env } from '../effects/node/types.ts';
+import type { Env, IoChannel } from '../effects/node/types.ts';
 import type { Effect } from '../effects/types.ts';
 import type { ModuleMap, LoadModuleOperations } from './types.ts';
-/** @import { Dir } from '../effects/node/virtual/types.ts' */
-/** @import { Module, ModuleMap, LoadModuleOperations } from './types.ts' */
 /**
  * Returns `true` if the file should be loaded for proof discovery.
  *
@@ -45,12 +48,21 @@ export declare const shouldLoad: (s: string) => boolean;
  * The result is sorted by path key using `string.cmp` so the order is
  * deterministic regardless of filesystem traversal order.
  *
- * @type {(env: Env) => Effect<LoadModuleOperations, ModuleMap>}
+ * A failure — a directory that cannot be listed, a module that will not import
+ * — propagates instead of panicking, so the program that asked for the map
+ * decides what a partial view of the source tree means for it. Discovery reads
+ * the whole tree, and a map missing the file it was asked about is worse than
+ * no map at all.
+ *
+ * @type {(env: Env) => Effect<LoadModuleOperations, ModuleMap, IoChannel>}
  */
-export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap>;
+export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap, IoChannel>;
 export declare const proof: {
     isSourceFile: () => void;
     allFilesFindsFunctionalScript: () => void;
     allFilesSkipsNodeModules: () => void;
     loadModuleMapDefaultsToCwdWhenInitCwdUnset: () => void;
+    loadModuleMapReportsUnreadableRoot: () => void;
+    loadModuleMapReportsUnimportableModule: () => void;
+    loadModuleMapStripsInitCwdPrefix: () => void;
 };

package/fjs/dev/module.f.mjs

@@ -2,19 +2,20 @@
  * Development utilities for indexing modules and loading FunctionalScript files.
  *
  * @module
+ *
+ * @import { Access, All, Env, Import, IoChannel, Readdir } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Module, ModuleMap, LoadModuleOperations } from './types.ts'
  */
 
-import { all, import_, readdir } from '../effects/node/module.f.mjs'
-/** @import { Access, All, Env, Import, Readdir } from '../effects/node/types.ts' */
+import { allOk, import_, readdir } from '../effects/node/module.f.mjs'
 import { cmp as strCmp } from '../types/string/module.f.mjs'
 import { unwrap } from '../types/result/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
-/** @import { Effect } from '../effects/types.ts' */
+import { mapStep, pureOk, step } from '../effects/module.f.mjs'
 import { join, relativize, toPosix } from '../path/module.f.mjs'
 import { assert, assertEq } from '../asserts/module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
-/** @import { Dir } from '../effects/node/virtual/types.ts' */
-/** @import { Module, ModuleMap, LoadModuleOperations } from './types.ts' */
 
 /**
  * Returns `true` if the file should be loaded for proof discovery.
@@ -48,16 +49,16 @@ export const shouldLoad = s =>
 const isSourceFile = path =>
     path.endsWith('.js') || path.endsWith('.ts') || path.endsWith('.mts') || path.endsWith('.mjs')
 
-/** @type {(s: string, predicate: (path: string) => boolean) => Effect<Readdir | All, readonly string[]>} */
+/** @type {(s: string, predicate: (path: string) => boolean) => Effect<Readdir | All, readonly string[], IoChannel>} */
 const allFiles = (s, predicate) => {
-    /** @type {(p: string) => Effect<Readdir | All, readonly string[]>} */
+    /** @type {(p: string) => Effect<Readdir | All, readonly string[], IoChannel>} */
     const load = p => {
-        const x0 = step(
+        const listed = step(
             readdir(p, {}),
             d => {
-                /** @type {readonly Effect<Readdir | All, readonly string[]>[]} */
+                /** @type {readonly Effect<Readdir | All, readonly string[], IoChannel>[]} */
                 let result = []
-                for (const i of unwrap(d)) {
+                for (const i of d) {
                     const { name } = i
                     if (name.startsWith('.')) { continue }
                     const file = join(p, name)
@@ -67,23 +68,19 @@ const allFiles = (s, predicate) => {
                         continue
                     }
                     if (predicate(file)) {
-                        result = [...result, pure([file])]
+                        result = [...result, pureOk([file])]
                     }
                 }
-                return all(...result)
+                return allOk(...result)
             })
-        return step(
-            x0,
-            v => pure(v.flat()))
+        return mapStep(listed, v => v.flat())
     }
     return load(s)
 }
 
-/** @type {(f: string) => Effect<Access | Import, readonly (readonly [string, Module])[]>} */
+/** @type {(f: string) => Effect<Access | Import, readonly (readonly [string, Module])[], IoChannel>} */
 const loadFile = f =>
-    step(
-        import_(f),
-        r => pure([/** @type {const} */ ([f, unwrap(r)])]))
+    mapStep(import_(f), m => [/** @type {const} */ ([f, m])])
 
 const { fromEntries } = Object
 
@@ -101,7 +98,13 @@ const { fromEntries } = Object
  * The result is sorted by path key using `string.cmp` so the order is
  * deterministic regardless of filesystem traversal order.
  *
- * @type {(env: Env) => Effect<LoadModuleOperations, ModuleMap>}
+ * A failure — a directory that cannot be listed, a module that will not import
+ * — propagates instead of panicking, so the program that asked for the map
+ * decides what a partial view of the source tree means for it. Discovery reads
+ * the whole tree, and a map missing the file it was asked about is worse than
+ * no map at all.
+ *
+ * @type {(env: Env) => Effect<LoadModuleOperations, ModuleMap, IoChannel>}
  */
 export const loadModuleMap = env => {
     const initCwd = env['INIT_CWD']
@@ -111,17 +114,17 @@ export const loadModuleMap = env => {
     //       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.
-    const x0 = step(
+    const loaded = step(
         allFiles(s, shouldLoad),
-        files => all(...files.map(loadFile)))
-    return step(
-        x0,
-        entries => pure(fromEntries(
+        files => allOk(...files.map(loadFile)))
+    return mapStep(
+        loaded,
+        entries => fromEntries(
             entries
                 .flat()
                 .map(([k, v]) => /** @type {const} */ ([relativize(prefix, k), v]))
                 .toSorted(([a], [b]) => strCmp(a)(b))
-        )))
+        ))
 }
 
 export const proof = {
@@ -145,7 +148,7 @@ export const proof = {
             'd.mjs': [],
         }
         const [, result] = virtual({ ...emptyState, root })(allFiles('.', shouldLoad))
-        assertEq(result.join(','), './a.f.ts,./b.f.mjs,./c.f.mts')
+        assertEq(unwrap(result).join(','), './a.f.ts,./b.f.mjs,./c.f.mts')
     },
     allFilesSkipsNodeModules: () => {
         // `node_modules` is skipped without descending into it, even though
@@ -156,7 +159,7 @@ export const proof = {
             'a.f.ts': [],
         }
         const [, result] = virtual({ ...emptyState, root })(allFiles('.', shouldLoad))
-        assertEq(result.join(','), './a.f.ts')
+        assertEq(unwrap(result).join(','), './a.f.ts')
     },
     loadModuleMapDefaultsToCwdWhenInitCwdUnset: () => {
         // With no `INIT_CWD` (e.g. `fjs t` invoked outside `npm run`), `env`
@@ -165,6 +168,33 @@ export const proof = {
         /** @type {Dir} */
         const root = { 'a.f.ts': () => ({}) }
         const [, result] = virtual({ ...emptyState, root })(loadModuleMap({}))
-        assertEq(Object.keys(result).join(','), './a.f.ts')
+        assertEq(Object.keys(unwrap(result)).join(','), './a.f.ts')
+    },
+    loadModuleMapReportsUnreadableRoot: () => {
+        // A directory that cannot be listed is no longer a panic. Discovery
+        // hands the failure back, and the program that asked for the map is
+        // the one that decides what a source tree it cannot read means — for
+        // `fjs t` that is a message on `stderr` and exit `1`.
+        const [, result] = virtual({ ...emptyState, root: {} })(loadModuleMap({ INIT_CWD: 'missing' }))
+        assert(result[0] === 'error', result)
+    },
+    loadModuleMapReportsUnimportableModule: () => {
+        // The other half of the same breaking change, and the half `readdir`
+        // does not cover: discovery lists the file, then the import of it
+        // fails. `'a.f.ts': []` is content rather than a module, so the
+        // virtual runner's `import` refuses it. Without this, a `loadFile`
+        // that turned every import failure into a success would still pass
+        // every other proof here.
+        const [, result] = virtual({ ...emptyState, root: { 'a.f.ts': [] } })(loadModuleMap({}))
+        assert(result[0] === 'error', result)
+    },
+    loadModuleMapStripsInitCwdPrefix: () => {
+        // With `INIT_CWD` set (the normal `npm run` case), discovery starts
+        // from that subdirectory and each key is relativized against it, so
+        // keys are still `./`-relative to `INIT_CWD` rather than carrying it.
+        /** @type {Dir} */
+        const root = { 'sub': { 'a.f.ts': () => ({}) } }
+        const [, result] = virtual({ ...emptyState, root })(loadModuleMap({ INIT_CWD: 'sub' }))
+        assertEq(Object.keys(unwrap(result)).join(','), './a.f.ts')
     },
 }

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

@@ -2,15 +2,23 @@
  * Synchronizes local development configuration generated from canonical repository files.
  *
  * @module
+ *
+ * @import { IoChannel, Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
  */
+import type { IoChannel, Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts';
 import type { Effect } from '../../effects/types.ts';
-import type { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts';
 /**
  * Regenerates VS Code's local MCP configuration from the canonical Copilot configuration.
  *
- * @type {() => Effect<Mkdir | ReadFile | WriteFile, void>}
+ * The source text is still needed after the directory has been created, so it
+ * is carried forward in a history rather than closed over by a nested
+ * continuation — and the history holds the text itself, not the `Result` the
+ * read returned.
+ *
+ * @type {() => Effect<Mkdir | ReadFile | WriteFile, void, IoChannel>}
  */
-export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void>;
+export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void, IoChannel>;
 /**
  * Runs all local development configuration generators.
  *

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

@@ -2,13 +2,14 @@
  * Synchronizes local development configuration generated from canonical repository files.
  *
  * @module
+ *
+ * @import { IoChannel, Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
  */
 
-import { history, historyStep, mapStep, step } from '../../effects/module.f.mjs'
-/** @import { Effect } from '../../effects/types.ts' */
-import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.mjs'
-/** @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts' */
-import { unwrap } from '../../types/result/module.f.mjs'
+
+import { exitStep, mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { history, historyStep, step } from '../../effects/module.f.mjs'
 
 const source = /** @type {const} */ ('.copilot/mcp.json')
 const targetDirectory = /** @type {const} */ ('.vscode')
@@ -17,15 +18,19 @@ const target = /** @type {const} */ ('.vscode/mcp.json')
 /**
  * Regenerates VS Code's local MCP configuration from the canonical Copilot configuration.
  *
- * @type {() => Effect<Mkdir | ReadFile | WriteFile, void>}
+ * The source text is still needed after the directory has been created, so it
+ * is carried forward in a history rather than closed over by a nested
+ * continuation — and the history holds the text itself, not the `Result` the
+ * read returned.
+ *
+ * @type {() => Effect<Mkdir | ReadFile | WriteFile, void, IoChannel>}
  */
 export const syncMcp = () => {
-    const sourceText = history(mapStep(readUtf8File(source), unwrap))
+    const sourceText = history(readUtf8File(source))
     const targetDirectoryReady = historyStep(
         sourceText,
-        () => mapStep(mkdir(targetDirectory, { recursive: true }), unwrap))
-    const targetWritten = step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text))
-    return mapStep(targetWritten, unwrap)
+        () => mkdir(targetDirectory, { recursive: true }))
+    return step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text))
 }
 
 /**
@@ -33,4 +38,4 @@ export const syncMcp = () => {
  *
  * @type {NodeProgram}
  */
-export const main = () => mapStep(syncMcp(), () => 0)
+export const main = () => exitStep(syncMcp())

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

@@ -1,7 +1,8 @@
+/**
+ * Proofs for local development configuration generation.
+ */
 export declare const proof: {
     syncMcp: () => void;
     main: () => void;
-    throw: {
-        missingSource: () => readonly [import("../../effects/node/virtual/types.ts").State, void];
-    };
+    missingSource: () => void;
 };

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

@@ -1,14 +1,14 @@
 /**
  * Proofs for local development configuration generation.
- *
- * @module
  */
+
+import { exitCode } from '../../effects/node/module.f.mjs'
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { utf8 } from '../../text/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'
 import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.mjs'
 import { main, syncMcp } from './module.f.mjs'
-import { step } from '../../effects/module.f.mjs'
+import { step as ioStep } from '../../effects/module.f.mjs'
 
 const mcp = /** @type {const} */ ('{"servers":{}}')
 const initial = /** @type {const} */ ({
@@ -21,16 +21,20 @@ const initial = /** @type {const} */ ({
 })
 export const proof = {
     syncMcp: () => {
-        const generatedMcp = step(syncMcp(), () => readUtf8File('.vscode/mcp.json'))
+        const generatedMcp = ioStep(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)
+        assertEq(exitCode(result), 0)
     },
-    throw: {
-        missingSource: () => virtual(emptyState)(syncMcp()),
+    // A missing source is no longer a panic: it propagates through the chain
+    // and the program reports it and exits 1.
+    missingSource: () => {
+        const [state, code] = virtual(emptyState)(main(defaultNodeProgramOptions))
+        assertEq(exitCode(code), 1)
+        assertEq(state.stderr, 'no such file or directory\n', state.stderr)
     },
 }

package/fjs/djs/module.f.d.mts

@@ -3,15 +3,23 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { WriteFile, ReadFile, Write } from '../effects/node/types.ts'
  * @import { Result } from '../types/result/types.ts'
  * @import { Unknown } from './types.ts'
  * @import { ParseError } from './parser/types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
-import type { Effect } from '../effects/types.ts';
 import type { WriteFile, ReadFile, Write } from '../effects/node/types.ts';
+import type { Effect } from '../effects/types.ts';
 export type _CompileOp = ReadFile | WriteFile | Write;
-/** @typedef {ReadFile | WriteFile | Write} _CompileOp */
-/** @type {(args: readonly string[]) => Effect<_CompileOp, number>} */
-export declare const compile: (args: readonly string[]) => Effect<_CompileOp, number>;
+/**
+ * Compiles the DJS module `args[0]` into `args[1]`, serializing as a JSON tree
+ * when the output name ends with `.json` and as a module otherwise.
+ *
+ * Returns the process exit code: `0` once the output file is written, `1` on
+ * every failure — too few arguments, a missing input file, or a parse error —
+ * so a caller can detect a failed compile from the exit status alone.
+ *
+ * @type {(args: readonly string[]) => Effect<_CompileOp, 0, number>}
+ */
+export declare const compile: (args: readonly string[]) => Effect<_CompileOp, 0, number>;

package/fjs/djs/module.f.mjs

@@ -3,45 +3,60 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { WriteFile, ReadFile, Write } from '../effects/node/types.ts'
  * @import { Result } from '../types/result/types.ts'
  * @import { Unknown } from './types.ts'
  * @import { ParseError } from './parser/types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
 
 import { transpile } from './transpiler/module.f.mjs'
 import { stringify, stringifyAsTree } from './serializer/module.f.mjs'
 import { sort } from '../types/object/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
-import { writeUtf8File, error } from '../effects/node/module.f.mjs'
+import { resultStep } from '../effects/module.f.mjs'
+import { errorExit, exitStep, writeUtf8File } from '../effects/node/module.f.mjs'
 
 /** @typedef {ReadFile | WriteFile | Write} _CompileOp */
 
-/** @type {(args: readonly string[]) => Effect<_CompileOp, number>} */
+/**
+ * Where an error happened, as much of it as is known: the token's
+ * `path:line:column` when the reader tracks positions, and otherwise the name
+ * of the file being compiled. A `.json` input is read by `fjs/media/json`,
+ * whose errors carry no position, and a missing file or a circular dependency
+ * has no token to point at either.
+ *
+ * @type {(inputFileName: string) => (parseError: ParseError) => string}
+ */
+const errorLocation = inputFileName => ({ metadata }) => metadata === null
+    ? inputFileName
+    : `${metadata.path}:${metadata.line}:${metadata.column}`
+
+/**
+ * Compiles the DJS module `args[0]` into `args[1]`, serializing as a JSON tree
+ * when the output name ends with `.json` and as a module otherwise.
+ *
+ * Returns the process exit code: `0` once the output file is written, `1` on
+ * every failure — too few arguments, a missing input file, or a parse error —
+ * so a caller can detect a failed compile from the exit status alone.
+ *
+ * @type {(args: readonly string[]) => Effect<_CompileOp, 0, number>}
+ */
 export const compile = args => {
     if (args.length < 2) {
-        return step(
-            error('Error: Requires 2 or more arguments'),
-            () => pure(1))
+        return errorExit('Error: Requires 2 or more arguments')
     }
     const inputFileName = args[0]
     const outputFileName = args[1]
-    return step(
+    return resultStep(
         transpile(inputFileName),
-        /** @type {(result: Result<Unknown, ParseError>) => Effect<_CompileOp, number>} */
+        /** @type {(result: Result<Unknown, ParseError>) => Effect<_CompileOp, 0, number>} */
         (result) => {
             if (result[0] === 'error') {
-                const metadata = result[1].metadata
-                return step(
-                    error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`),
-                    () => pure(0))
+                return errorExit(`${errorLocation(inputFileName)(result[1])} - error: ${result[1].message}`)
             }
             const content = outputFileName.endsWith('.json')
                 ? stringifyAsTree(sort)(result[1])
                 : stringify(sort)(result[1])
-            return step(
-                writeUtf8File(outputFileName, content),
-                () => pure(0))
+            return exitStep(writeUtf8File(outputFileName, content))
         })
 }

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

@@ -10,7 +10,7 @@
  * @import { OrderedMap } from '../../types/ordered_map/types.ts'
  * @import { AstArray, AstConst, AstModule, AstModuleRef } from '../ast/types.ts'
  * @import { TokenMetadata } from '../../js/tokenizer/types.ts'
- * @import { ParseError } from './types.ts'
+ * @import { ParseError, _ValueToken } from './types.ts'
  */
 import type { Result } from '../../types/result/types.ts';
 import type { List } from '../../types/list/types.ts';
@@ -48,10 +48,11 @@ export type _ExportState = {
     readonly state: 'export';
     readonly module: _ModuleState;
 };
+export type _ValueState = '' | '[' | '[v' | '[,' | '{' | '{[' | '{[k' | '{k' | '{:' | '{v' | '{,';
 export type _ParseValueState = {
     readonly state: 'constValue' | 'exportValue';
     readonly module: _ModuleState;
-    readonly valueState: '' | '[' | '[v' | '[,' | '{' | '{k' | '{:' | '{v' | '{,';
+    readonly valueState: _ValueState;
     readonly top: _DjsStackElement | null;
     readonly stack: _DjsStack;
 };
@@ -63,7 +64,16 @@ export type _ErrorState = {
     readonly state: 'error';
     readonly error: ParseError;
 };
-/** @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>} */
+/**
+ * Reads the token list as a FunctionalScript module: `import` statements, then
+ * `const` statements, then one `export default`.
+ *
+ * This is the only language the parser reads. A JSON document is data, not a
+ * module, and `fjs/media/json` is its reader
+ * ([spec: JSON input](../../../spec/README.md#json-input)).
+ *
+ * @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>}
+ */
 export declare const parseFromTokens: (tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>;
 export declare const proof: {
     pushKey: {
@@ -72,4 +82,7 @@ export declare const proof: {
     endArray: {
         nonArrayTop: () => void;
     };
+    endObject: {
+        nonObjectTop: () => void;
+    };
 };