functionalscript 0.44.0 → 0.46.0

package/fjs/bnf/testlib.f.d.mts

@@ -1,10 +1,41 @@
 /**
  * @module
  *
+ * @import { Ast, AstTag } from './matcher/types.ts'
  * @import { Rule } from './types.ts'
  */
+import type { Ast } from './matcher/types.ts';
 import type { Rule } from './types.ts';
 /** @type {() => Rule} */
 export declare const classic: () => Rule;
 /** @type {() => Rule} */
 export declare const deterministic: () => Rule;
+export type _Leaf = number | readonly [number, unknown];
+export type _AstNode = Ast<_Leaf>;
+export type _AstChild = _AstNode | _Leaf;
+export type _Parts = {
+    readonly parts: readonly string[];
+    readonly text: string;
+};
+/**
+ * Renders a matcher AST as one line of `tag(children)`, with the code points a
+ * node consumed directly written as one quoted string.
+ *
+ * A proof that pins a whole AST is checking its *shape*, and raw JSON buries
+ * that under `{"tag":…,"sequence":[…]}` and a `[32,null]` per space — several
+ * kilobytes for an input a reader can hold in their head. This keeps the two
+ * things a repetition changes legible: how deep the nesting goes, and which
+ * tags survive. Repeated items are siblings under one node, whereas the
+ * right-recursive encoding puts each item one level deeper than the last.
+ *
+ * @type {(node: _AstNode) => string}
+ *
+ * @example
+ *
+ * ```ts
+ * // three spaces matched by a flat `repeat`, then by right-recursion
+ * '(" "(" ") " "(" ") " "(" "))'
+ * '" "(" " " "(" " " "(" " *())'
+ * ```
+ */
+export declare const showAst: (node: _AstNode) => string;

package/fjs/bnf/testlib.f.mjs

@@ -1,9 +1,11 @@
 /**
  * @module
  *
+ * @import { Ast, AstTag } from './matcher/types.ts'
  * @import { Rule } from './types.ts'
  */
 
+import { codePointToString } from '../text/utf16/module.f.mjs'
 import {
     commaJoin0Plus,
     none,
@@ -194,3 +196,81 @@ export const deterministic = () => {
 
     return json
 }
+
+//
+
+/**
+ * The leaf of either backend's AST: `bnf/ll1` keeps the code point alone and
+ * `bnf/descent` pairs it with metadata, so a renderer that takes both is
+ * generic over exactly this.
+ *
+ * @typedef {number | readonly [number, unknown]} _Leaf
+ */
+
+/** @typedef {Ast<_Leaf>} _AstNode */
+
+/** @typedef {_AstNode | _Leaf} _AstChild */
+
+/**
+ * @param {_AstChild} child
+ * @returns {child is _AstNode}
+ */
+const isAstNode = child => typeof child !== 'number' && !(child instanceof Array)
+
+/** @type {(child: _Leaf) => number} */
+const codePointOf = child => typeof child === 'number' ? child : child[0]
+
+/**
+ * A tag as `showAst` writes it: a quoted string, `*` for the tagless empty
+ * match, and nothing at all for an untagged node. `*` rather than `true`
+ * because a branch may itself be named `true` — the JSON grammars have one.
+ *
+ * @type {(tag: AstTag) => string}
+ */
+const showTag = tag =>
+    tag === undefined ? '' : tag === true ? '*' : JSON.stringify(tag)
+
+/** @typedef {{ readonly parts: readonly string[], readonly text: string }} _Parts */
+
+/**
+ * Ends the run of consumed code points being accumulated, if there is one, so
+ * that a node's text appears as one quoted string rather than one part per
+ * symbol.
+ *
+ * @type {(acc: _Parts) => readonly string[]}
+ */
+const flushText = acc =>
+    acc.text === '' ? acc.parts : [...acc.parts, JSON.stringify(acc.text)]
+
+/** @type {(acc: _Parts, child: _AstChild) => _Parts} */
+const addChild = (acc, child) =>
+    isAstNode(child)
+        ? { parts: [...flushText(acc), showAst(child)], text: '' }
+        : { parts: acc.parts, text: acc.text + codePointToString(codePointOf(child)) }
+
+/** @type {_Parts} */
+const noParts = { parts: [], text: '' }
+
+/**
+ * Renders a matcher AST as one line of `tag(children)`, with the code points a
+ * node consumed directly written as one quoted string.
+ *
+ * A proof that pins a whole AST is checking its *shape*, and raw JSON buries
+ * that under `{"tag":…,"sequence":[…]}` and a `[32,null]` per space — several
+ * kilobytes for an input a reader can hold in their head. This keeps the two
+ * things a repetition changes legible: how deep the nesting goes, and which
+ * tags survive. Repeated items are siblings under one node, whereas the
+ * right-recursive encoding puts each item one level deeper than the last.
+ *
+ * @type {(node: _AstNode) => string}
+ *
+ * @example
+ *
+ * ```ts
+ * // three spaces matched by a flat `repeat`, then by right-recursion
+ * '(" "(" ") " "(" ") " "(" "))'
+ * '" "(" " " "(" " " "(" " *())'
+ * ```
+ */
+export const showAst = node =>
+    `${showTag(node.tag)}(${flushText(node.sequence.reduce(addChild, noParts)).join(' ')})`

package/fjs/bnf/token_symbol/module.f.d.mts

@@ -4,7 +4,8 @@
  * A parser built on top of a tokenizer consumes one input symbol per token, so
  * multi-character operators (`>>>=`) and keywords (`instanceof`) each need a
  * symbol of their own. Names are registered as one fixed alphabet and get a
- * symbol from their position in it, above the Unicode range and below `eof`.
+ * symbol from their position in it, above the Unicode range and up to the last
+ * ordinary symbol.
  *
  * See `./types.ts` for the `Encoding<T>` type-level API.
  *
@@ -14,8 +15,8 @@
  */
 import type { Encoding } from './types.ts';
 /**
- * How many names one encoding holds: every symbol from {@link start} up to but
- * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ * How many names one encoding holds: every symbol from {@link start} up to and
+ * including the last ordinary symbol (`0xFFFFFE`, the top of `fullRange`).
  *
  * @type {number}
  */

package/fjs/bnf/token_symbol/module.f.mjs

@@ -4,7 +4,8 @@
  * A parser built on top of a tokenizer consumes one input symbol per token, so
  * multi-character operators (`>>>=`) and keywords (`instanceof`) each need a
  * symbol of their own. Names are registered as one fixed alphabet and get a
- * symbol from their position in it, above the Unicode range and below `eof`.
+ * symbol from their position in it, above the Unicode range and up to the last
+ * ordinary symbol.
  *
  * See `./types.ts` for the `Encoding<T>` type-level API.
  *
@@ -15,11 +16,11 @@
 
 import { assert } from '../../asserts/module.f.mjs'
 import { fromUndefined } from '../../types/nullable/module.f.mjs'
-import { eof, rangeDecode, unicodeRange } from '../module.f.mjs'
+import { fullRange, rangeDecode, unicodeRange } from '../module.f.mjs'
 
 const [, unicodeLast] = rangeDecode(unicodeRange)
 
-const [eofSymbol] = rangeDecode(eof)
+const [, lastOrdinary] = rangeDecode(fullRange)
 
 /**
  * The symbol of the first registered name: `0x110000`, one past the last
@@ -29,12 +30,12 @@ const [eofSymbol] = rangeDecode(eof)
 const start = unicodeLast + 1
 
 /**
- * How many names one encoding holds: every symbol from {@link start} up to but
- * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ * How many names one encoding holds: every symbol from {@link start} up to and
+ * including the last ordinary symbol (`0xFFFFFE`, the top of `fullRange`).
  *
  * @type {number}
  */
-export const capacity = eofSymbol - start
+export const capacity = lastOrdinary - start + 1
 
 /**
  * Builds an encoding over the complete list of token names.

package/fjs/bnf/token_symbol/proof.f.mjs

@@ -1,4 +1,5 @@
 import { assertEq } from '../../asserts/module.f.mjs'
+import { eofSymbol } from '../module.f.mjs'
 import { capacity, encoding } from './module.f.mjs'
 
 const names = /** @type {const} */ (['>>', '>>>=', 'instanceof'])
@@ -17,10 +18,12 @@ export const proof = {
         },
         () => {
             const { decode } = encoding(names)
-            // past the end of the alphabet, a code point, and `eof`
+            // past the end of the alphabet, a code point, the last ordinary
+            // symbol, and `eof`
             assertEq(decode(0x110003), null)
             assertEq(decode(0x10FFFF), null)
-            assertEq(decode(0xFFFFFF), null)
+            assertEq(decode(0xFFFFFE), null)
+            assertEq(decode(eofSymbol), null)
         },
     ],
     roundTrip: () => {

package/fjs/bnf/token_symbol/types.d.ts

@@ -20,8 +20,8 @@ export type Encoding<T extends string> = {
     readonly encode: (name: T) => number;
     /**
      * The name a symbol stands for, or `null` when the symbol belongs to no
-     * registered name — a code point, `eof`, or a symbol past the end of the
-     * alphabet.
+     * registered name — a code point, the `eof` symbol, or a symbol past the
+     * end of the alphabet.
      */
     readonly decode: (symbol: number) => Nullable<T>;
 };

package/fjs/bnf/types.d.ts

@@ -5,11 +5,18 @@
  */
 import type { StringMap } from '../types/object/types.ts';
 /**
- * A range of symbols. Two 24-bit numbers are stored in one JS number (48 bits).
+ * A range of symbols. Two 24-bit endpoint codes are stored in one JS number
+ * (48 bits).
  *
  * For example: 0xBBBBBB_EEEEEE
- * - 0xBBBBBB is the first symbol (24 bits)
- * - 0xEEEEEE is the last symbol (24 bits)
+ * - 0xBBBBBB is the first endpoint's stored code (24 bits)
+ * - 0xEEEEEE is the last endpoint's stored code (24 bits)
+ *
+ * A stored code is not the semantic terminal value: the semantic domain is
+ * `[-1] | [0, 2 ** 24 - 2]` — EOF plus every ordinary symbol — and EOF's code
+ * is `0xFFFFFF`, the top of the stored space. `rangeEncode` / `rangeDecode` in
+ * `./module.f.mjs` convert between the two, and everything that compares
+ * terminals compares decoded values.
  *
  * 24 bits per half, not 26 (the most `float64`'s 52-bit safe-integer mantissa
  * could fit two of): 24 is divisible by 4, so each half is exactly 6 hex

package/fjs/cas/cli/module.f.d.mts

@@ -14,4 +14,4 @@ import type { MemOp } from '../../effects/memory/types.ts';
 import type { FileCasOperation } from '../types.ts';
 /** @type {Commands<FileCasOperation | WriteFile | Write | All | MemOp | Read>} */
 export declare const commands: Commands<FileCasOperation | WriteFile | Write | All | MemOp | Read>;
-export declare const main: (options: import("../../effects/node/types.ts").NodeProgramOptions) => import("../../effects/types.ts").Effect<All | Read | Write | WriteFile | FileCasOperation | MemOp, number>;
+export declare const main: import("../../effects/node/types.ts").Program<All | Read | Write | WriteFile | FileCasOperation | MemOp>;

package/fjs/cas/cli/module.f.mjs

@@ -11,8 +11,9 @@
 
 import { sha256 } from '../../crypto/sha2/module.f.mjs'
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.mjs'
-import { forEachStep, pure, step } from '../../effects/module.f.mjs'
-import { errorExit, log, writeFromStream } from '../../effects/node/module.f.mjs'
+
+import { errorExit, exitStep, log, writeFromStream } from '../../effects/node/module.f.mjs'
+import { forEachStep, step as ioStep } from '../../effects/module.f.mjs'
 import { dispatch } from '../../cli/module.f.mjs'
 import { casAddFile, fileCas } from '../module.f.mjs'
 
@@ -26,15 +27,9 @@ export const commands = [
                 return errorExit("'cas add' expects one parameter")
             }
             const c = fileCas(sha256)(home)
-            return step(
-                casAddFile(c)(path),
-                hashResult => hashResult[0] === 'error'
-                    ? pure(1)
-                    : step(
-                        log(vecToCBase32(hashResult[1])),
-                        () => pure(0)
-                    )
-            )
+            const added = casAddFile(c)(path)
+            const logged = ioStep(added, hash => log(vecToCBase32(hash)))
+            return exitStep(logged)
         },
     },
     {
@@ -50,10 +45,7 @@ export const commands = [
             }
             const c = fileCas(sha256)(home)
             const x = c.read(hash)
-            return step(
-                writeFromStream(path, x),
-                ([r, v]) => r === 'error' ? errorExit(`e: ` + String(v)) : pure(0),
-            )
+            return exitStep(writeFromStream(path, x))
         },
     },
     {
@@ -61,11 +53,13 @@ export const commands = [
         description: 'List all stored content hashes',
         handler: ({ home }) => {
             const c = fileCas(sha256)(home)
-            const x0 = forEachStep(c.list(), j => log(vecToCBase32(j)))
-            return step(
-                x0,
-                () => pure(0)
-            )
+            // The fold's `items` is deliberately a raw effect, so a fallible
+            // producer composes with `step` ahead of it rather than the fold
+            // growing an error channel of its own.
+            // `c.list()` feeds the fold directly: the step that used to sit
+            // here existed only to unwrap the list so `pure` could wrap it
+            // again.
+            return exitStep(forEachStep(c.list(), j => log(vecToCBase32(j))))
         },
     },
 ]

package/fjs/cas/cli/proof.f.d.mts

@@ -1,4 +1,6 @@
-/** @import { NodeProgramOptions } from '../../effects/node/types.ts' */
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
 export declare const proof: {
     mainAdd: () => void;
     mainAddGetBig: () => void;
@@ -12,7 +14,5 @@ export declare const proof: {
     mainListEmptyStore: () => void;
     mainNoCmd: () => void;
     mainUnknownCmd: () => void;
-    throw: {
-        mainListCorruptStore: () => readonly [import("../../effects/node/virtual/types.ts").State, number];
-    };
+    mainListCorruptStore: () => void;
 };

package/fjs/cas/cli/proof.f.mjs

@@ -1,5 +1,8 @@
-/** @import { NodeProgramOptions } from '../../effects/node/types.ts' */
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
 
+import { exitCode } from '../../effects/node/module.f.mjs'
 import { commands } from './module.f.mjs'
 import { computeSync, sha256 } from '../../crypto/sha2/module.f.mjs'
 import { maxLength, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
@@ -18,8 +21,8 @@ export const proof = {
     mainAdd: () => {
         const content = vec8(0x2An)
         const state = { ...emptyState, root: { myfile: [content] } }
-        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])))
-        assertEq(exitCode, 0, ['expected exit 0', exitCode])
+        const [finalState, code] = virtual(state)(main(makeOptions(['add', 'myfile'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(finalState.stdout.length !== 0, 'expected hash in stdout')
     },
     mainAddGetBig: () => {
@@ -27,8 +30,8 @@ export const proof = {
         const content = [chunk, chunk]
         const state = { ...emptyState, root: { myfile: content } }
         //
-        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])))
-        assertEq(exitCode, 0)
+        const [finalState, code] = virtual(state)(main(makeOptions(['add', 'myfile'])))
+        assertEq(exitCode(code), 0)
         const stdout = finalState.stdout
         assert(stdout.length !== 0)
         //
@@ -38,32 +41,33 @@ export const proof = {
         //
         const [finalState2, exitCode2] = virtual(finalState)(main(makeOptions(['get', hs, 'myfile2'])))
         // console.log(finalState2.stderr)
-        assertEq(exitCode2, 0, 'e2')
+        assertEq(exitCode(exitCode2), 0, 'e2')
         const { myfile2 } = finalState2.root
         assert(myfile2 instanceof Array)
         const h2 = computeSync(sha256)(myfile2)
         assertEq(h, h2, 'h')
     },
     mainAddWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['add'])))
-        assertEq(exitCode, 1)
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['add'])))
+        assertEq(exitCode(code), 1)
         assert(finalState.stderr.length !== 0)
     },
     mainAddMissingFile: () => {
-        // The source path doesn't exist, so `streamFile`'s first read comes back as an
-        // error item; `write` fails closed with that error and the handler exits 1
-        // without ever calling `log` — covers the `hashResult[0] === 'error'` branch.
-        const [, exitCode] = virtual(emptyState)(main(makeOptions(['add', 'missing'])))
-        assertEq(exitCode, 1)
+        // The source path doesn't exist, so `streamFile`'s first read comes back as a
+        // stream failure; `write` fails closed with that error and the handler exits 1
+        // without ever calling `log` — covers `exitStep`'s error branch.
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['add', 'missing'])))
+        assertEq(exitCode(code), 1)
+        assertEq(finalState.stderr, 'no such file or directory\n', finalState.stderr)
     },
     mainGetFound: () => {
         const content = vec8(0x2An)
         const state = { ...emptyState, root: { myfile: [content] } }
         const [state1, exitCode1] = virtual(state)(main(makeOptions(['add', 'myfile'])))
-        assertEq(exitCode1, 0, ['expected add exit 0', exitCode1])
+        assertEq(exitCode(exitCode1), 0, ['expected add exit 0', exitCode1])
         const hashStr = state1.stdout.trim()
         const [, exitCode2] = virtual(state1)(main(makeOptions(['get', hashStr, 'output'])))
-        assertEq(exitCode2, 0, ['expected get exit 0', exitCode2])
+        assertEq(exitCode(exitCode2), 0, ['expected get exit 0', exitCode2])
     },
     mainGetNotFound: () => {
         // valid cBase32 hash that has not been stored
@@ -72,47 +76,56 @@ export const proof = {
         const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])))
         const hashStr = state1.stdout.trim()
         // use an empty store so the hash is not found
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', hashStr, 'output'])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
-        assert(finalState.stderr.length !== 0, 'expected error in stderr')
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get', hashStr, 'output'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
+        // The *message*, not just a non-empty line: the failure reaches the user
+        // as the host's own words. Asserting only that something was written is
+        // what let a stringified error tuple (`ioError,[object Object]`) pass.
+        assertEq(finalState.stderr, 'no such file or directory\n', finalState.stderr)
     },
     mainGetWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get'])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(finalState.stderr.length !== 0, 'expected error in stderr')
     },
     mainGetInvalidHash: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', 'not-a-valid-hash', 'output'])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get', 'not-a-valid-hash', 'output'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(finalState.stderr.length !== 0, 'expected error in stderr')
     },
     mainList: () => {
         const content = vec8(0x2An)
         const state = { ...emptyState, root: { myfile: [content] } }
         const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])))
-        const [, exitCode] = virtual(state1)(main(makeOptions(['list'])))
-        assertEq(exitCode, 0, ['expected exit 0', exitCode])
+        const [, code] = virtual(state1)(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
     },
     mainListEmptyStore: () => {
         // A fresh directory has no `.cas` yet; listing must succeed (empty),
         // not crash unwrapping a readdir ENOENT.
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['list'])))
-        assertEq(exitCode, 0, ['expected exit 0', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assertEq(finalState.stdout, '', ['expected empty stdout', finalState.stdout])
     },
     mainNoCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions([])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(finalState.stderr.length !== 0, 'expected error in stderr')
     },
     mainUnknownCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['bogus'])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['bogus'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(finalState.stderr.length !== 0, 'expected error in stderr')
     },
-    throw: {
-        // `.cas` exists but is a file, not a directory: a real storage error
-        // that must surface, not be masked as an empty list.
-        mainListCorruptStore: () => virtual({ ...emptyState, root: { '.cas': [vec8(0x2An)] } })(main(makeOptions(['list']))),
+    // `.cas` exists but is a file, not a directory: a real storage error that
+    // must surface, not be masked as an empty list. It is no longer a panic
+    // either — `list` answers with the error and the CLI reports it on stderr
+    // and exits 1, which is why this is an ordinary proof rather than a
+    // `throw` one.
+    mainListCorruptStore: () => {
+        const [state, code] = virtual({ ...emptyState, root: { '.cas': [vec8(0x2An)] } })(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 1)
+        assert(state.stderr !== '', ['expected the storage error reported on stderr', state.stderr])
+        assertEq(state.stdout, '')
     },
 }