functionalscript 0.45.0 → 0.46.1

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

@@ -6,43 +6,35 @@
 import type { CodePoint } from '../../text/utf16/types.ts';
 import type { RangeMapArray } from '../../types/range_map/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
-import type { EmptyTag } from '../data/types.ts';
-/** @internal */
+import type { Ast } from '../matcher/types.ts';
+/**
+ * A rule's dispatch entry: its first set as a range map, and — for a variant
+ * that can match empty — the branch a dispatch miss selects.
+ *
+ * @internal
+ */
 export type _DispatchRule = {
-    readonly emptyTag: EmptyTag;
+    readonly empty: _DispatchBranch | undefined;
     readonly rangeMap: _Dispatch;
 };
 /** @internal */
 export type _Dispatch = RangeMapArray<_DispatchResult>;
 /** @internal */
-export type _DispatchResult = _DispatchRuleCollection | null;
+export type _DispatchResult = _DispatchBranch | null;
 /**
- * The rules a dispatched symbol selects, to be matched one after another. They
- * are names into the {@link _DispatchMap}: the builder only ever appends rule
- * names, so the matcher resolves each one there.
+ * A branch as dispatch selects it: the name of the rule to invoke — a name
+ * into the {@link _DispatchMap} — and the tag its node gets. Only a variant's
+ * entries are ever read as branches; every other rule kind consults its range
+ * map solely for first-set membership.
  *
  * @internal
  */
-export type _DispatchRuleCollection = {
+export type _DispatchBranch = {
     readonly tag: string | undefined;
-    readonly rules: readonly string[];
+    readonly name: string;
 };
 /** @internal */
 export type _DispatchMap = StringMap<_DispatchRule>;
-/**
- * Represents a parsed AST rule, consisting of a rule name and its parsed sequence.
- *
- * @internal
- */
-export type _AstRule = {
-    readonly tag: AstTag;
-    readonly sequence: AstSequence;
-};
-/**
- * Represents a parsed AST sequence.
- */
-export type AstSequence = readonly (_AstRule | CodePoint)[];
-export type AstTag = string | true | undefined;
 /**
  * Represents the remaining input after a match attempt, or `null` if no match is possible.
  *
@@ -55,7 +47,7 @@ export type Remainder = readonly CodePoint[] | null;
  *
  * Represents the result of a match operation, including the parsed AST rule and the remainder of the input.
  */
-export type MatchResult = readonly [_AstRule, boolean, Remainder];
+export type MatchResult = readonly [Ast<CodePoint>, boolean, Remainder];
 /**
  * LL(1) parser function for matching by rule name.
  *

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

@@ -0,0 +1,66 @@
+/**
+ * The layer every BNF matcher backend shares: the {@link Cursor} it matches at,
+ * the {@link Ast} it builds, and the constructors that pair them.
+ *
+ * `fjs/bnf/ll1` and `fjs/bnf/descent` are two machines over one contract, and
+ * the contract is what lives here — not the machines. Backtracking, frame
+ * shapes, failure reporting and the public result type are each backend's own,
+ * and deliberately different; where the input sits, what a consumed symbol
+ * contributes to the AST, and how a node is built are not.
+ *
+ * The three are one module rather than three because they are interdependent:
+ * {@link leafAt} produces AST leaves, and {@link mrSuccess} builds AST nodes
+ * positioned by a cursor. Splitting them would put one concept behind three
+ * imports.
+ *
+ * See `./types.ts` for the type-level API and `./README.md` for the contract
+ * this implements.
+ *
+ * @module
+ *
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from './types.ts'
+ */
+import type { AstResult, AstSequence, AstTag, Cursor } from './types.ts';
+/**
+ * What consuming the symbol at a cursor contributes to the AST: the leaf
+ * itself, and nothing for the synthesized end-of-input symbol — it has no
+ * physical source element, so it never reaches an AST.
+ *
+ * @type {<L>(input: readonly L[], pos: Cursor) => AstSequence<L>}
+ */
+export declare const leafAt: <L>(input: readonly L[], pos: Cursor) => AstSequence<L>;
+/**
+ * The semantic symbol a cursor points at: one read out of the physical input,
+ * and the synthesized {@link eofSymbol} at its end. Only meaningful where the
+ * cursor still has a symbol, `pos <= input.length`.
+ *
+ * `symbolOf` is the one place backends differ — it is how a leaf yields its
+ * symbol, `identity` where the leaf *is* the code point and a destructuring
+ * where it carries metadata alongside. Each backend binds its own partial
+ * application once at module scope.
+ *
+ * @type {<L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number}
+ */
+export declare const symbolAt: <L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number;
+/**
+ * The public, physical index of a cursor. Consuming the synthesized
+ * end-of-input symbol moves the cursor past the physical end, and both cursors
+ * report `length`.
+ *
+ * @type {(length: number) => (pos: Cursor) => number}
+ */
+export declare const physicalIdx: (length: number) => (pos: Cursor) => number;
+export type _Mr<L, P> = (tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;
+/**
+ * A matched node at a position.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export declare const mrSuccess: <L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;
+/**
+ * A node that did not match, at the position the caller should resume from —
+ * which a backtracking backend rewinds and a predictive one does not.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export declare const mrFail: <L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;

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

@@ -0,0 +1,81 @@
+/**
+ * The layer every BNF matcher backend shares: the {@link Cursor} it matches at,
+ * the {@link Ast} it builds, and the constructors that pair them.
+ *
+ * `fjs/bnf/ll1` and `fjs/bnf/descent` are two machines over one contract, and
+ * the contract is what lives here — not the machines. Backtracking, frame
+ * shapes, failure reporting and the public result type are each backend's own,
+ * and deliberately different; where the input sits, what a consumed symbol
+ * contributes to the AST, and how a node is built are not.
+ *
+ * The three are one module rather than three because they are interdependent:
+ * {@link leafAt} produces AST leaves, and {@link mrSuccess} builds AST nodes
+ * positioned by a cursor. Splitting them would put one concept behind three
+ * imports.
+ *
+ * See `./types.ts` for the type-level API and `./README.md` for the contract
+ * this implements.
+ *
+ * @module
+ *
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from './types.ts'
+ */
+
+import { eofSymbol } from '../module.f.mjs'
+
+/**
+ * What consuming the symbol at a cursor contributes to the AST: the leaf
+ * itself, and nothing for the synthesized end-of-input symbol — it has no
+ * physical source element, so it never reaches an AST.
+ *
+ * @type {<L>(input: readonly L[], pos: Cursor) => AstSequence<L>}
+ */
+export const leafAt = (input, pos) => pos < input.length ? [input[pos]] : []
+
+/**
+ * The semantic symbol a cursor points at: one read out of the physical input,
+ * and the synthesized {@link eofSymbol} at its end. Only meaningful where the
+ * cursor still has a symbol, `pos <= input.length`.
+ *
+ * `symbolOf` is the one place backends differ — it is how a leaf yields its
+ * symbol, `identity` where the leaf *is* the code point and a destructuring
+ * where it carries metadata alongside. Each backend binds its own partial
+ * application once at module scope.
+ *
+ * @type {<L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number}
+ */
+export const symbolAt = symbolOf => (input, pos) =>
+    pos < input.length ? symbolOf(input[pos]) : eofSymbol
+
+/**
+ * The public, physical index of a cursor. Consuming the synthesized
+ * end-of-input symbol moves the cursor past the physical end, and both cursors
+ * report `length`.
+ *
+ * @type {(length: number) => (pos: Cursor) => number}
+ */
+export const physicalIdx = length => pos => Math.min(pos, length)
+
+/**
+ * @template L
+ * @template P
+ * @typedef {(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>} _Mr
+ */
+
+/** @type {<L, P>(success: boolean) => _Mr<L, P>} */
+const mr = success => (tag, sequence, pos) => ({ ast: { tag, sequence }, success, pos })
+
+/**
+ * A matched node at a position.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export const mrSuccess = mr(true)
+
+/**
+ * A node that did not match, at the position the caller should resume from —
+ * which a backtracking backend rewinds and a predictive one does not.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export const mrFail = mr(false)

package/fjs/bnf/matcher/proof.f.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @import { CodePointMeta } from '../descent/types.ts'
+ */
+export declare const proof: {
+    leafAt: (() => void)[];
+    symbolAt: (() => void)[];
+    physicalIdx: () => void;
+    mrSuccess: () => void;
+    mrFail: () => void;
+};

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

@@ -0,0 +1,79 @@
+/**
+ * @import { CodePointMeta } from '../descent/types.ts'
+ */
+
+import { assertEq } from '../../asserts/module.f.mjs'
+import { identity } from '../../types/function/module.f.mjs'
+import { eofSymbol } from '../module.f.mjs'
+import { leafAt, mrFail, mrSuccess, physicalIdx, symbolAt } from './module.f.mjs'
+
+/** @type {readonly CodePointMeta<string>[]} */
+const withMeta = [[0x41, 'a'], [0x42, 'b']]
+
+/** @type {(leaf: CodePointMeta<string>) => number} */
+const metaSymbolOf = ([symbol]) => symbol
+
+export const proof = {
+    leafAt: [
+        () => {
+            // Inside the physical input a leaf is contributed whole, whatever a
+            // backend chose a leaf to be.
+            assertEq(JSON.stringify(leafAt([65, 66], 0)), '[65]')
+            assertEq(JSON.stringify(leafAt([65, 66], 1)), '[66]')
+            assertEq(JSON.stringify(leafAt(withMeta, 0)), '[[65,"a"]]')
+        },
+        () => {
+            // At and past the physical end there is nothing to contribute: the
+            // synthesized end-of-input symbol has no source element, so it never
+            // reaches an AST.
+            assertEq(JSON.stringify(leafAt([65, 66], 2)), '[]')
+            assertEq(JSON.stringify(leafAt([65, 66], 3)), '[]')
+            assertEq(JSON.stringify(leafAt([], 0)), '[]')
+        },
+    ],
+    symbolAt: [
+        () => {
+            // `identity` is the leaf reader of a backend whose leaf *is* the
+            // symbol; a pair's reader takes its first half. Same positions, same
+            // symbols.
+            /** @type {(leaf: number) => number} */
+            const symbolOf = identity
+            assertEq(symbolAt(symbolOf)([65, 66], 0), 65)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 0), 65)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 1), 66)
+        },
+        () => {
+            // The one synthesized end-of-input symbol sits at the physical end,
+            // for either leaf shape.
+            /** @type {(leaf: number) => number} */
+            const symbolOf = identity
+            assertEq(symbolAt(symbolOf)([65, 66], 2), eofSymbol)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 2), eofSymbol)
+            assertEq(symbolAt(symbolOf)([], 0), eofSymbol)
+        },
+    ],
+    physicalIdx: () => {
+        const physical = physicalIdx(2)
+        assertEq(physical(0), 0)
+        assertEq(physical(2), 2)
+        // Consuming the end-of-input symbol moves the cursor past the physical
+        // end, and both cursors report the same public index — which is what
+        // keeps a public position physical.
+        assertEq(physical(3), 2)
+    },
+    mrSuccess: () => {
+        assertEq(
+            JSON.stringify(mrSuccess('some', [65], 1)),
+            '{"ast":{"tag":"some","sequence":[65]},"success":true,"pos":1}')
+        // The position type is the backend's own: `null` is how a predictive
+        // backend says it ran out of input.
+        assertEq(
+            JSON.stringify(mrSuccess(undefined, [], null)),
+            '{"ast":{"sequence":[]},"success":true,"pos":null}')
+    },
+    mrFail: () => {
+        assertEq(
+            JSON.stringify(mrFail(true, [], 0)),
+            '{"ast":{"tag":true,"sequence":[]},"success":false,"pos":0}')
+    },
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Type-level API for the layer every BNF matcher backend shares: the position
+ * it matches at, the AST it builds, and the result that pairs them.
+ *
+ * @module
+ */
+/**
+ * Tag of an AST node: the variant branch that matched, `true` where a rule
+ * matched empty input without naming a branch, and `undefined` where the rule
+ * is not a choice at all.
+ */
+export type AstTag = string | true | undefined;
+/**
+ * An AST over leaves of type `L`. A backend picks `L` for what it keeps of a
+ * consumed symbol — the code point alone, or the code point with metadata.
+ */
+export type Ast<L> = {
+    readonly tag: AstTag;
+    readonly sequence: AstSequence<L>;
+};
+/** The children of an {@link Ast} node: nested nodes and consumed leaves. */
+export type AstSequence<L> = readonly (Ast<L> | L)[];
+/**
+ * A match position over input of `length` leaves: `0 .. length` are the
+ * physical positions, and `length + 1` is where the one synthesized
+ * end-of-input symbol has been consumed.
+ *
+ * This is the complete cursor `(idx, eofConsumed)` of
+ * [the BNF contract](../README.md#logical-eof-in-parser-input) written as one
+ * number. `eofConsumed` can only be true at the physical end, so the pair and
+ * the extended position hold the same information — and being one number is
+ * what makes every ordering a backend needs a plain `<`, because consuming EOF
+ * *is* progress even though the public index does not move. A backend that
+ * treated it as no progress would loop forever on a repetition over a rule that
+ * can match EOF.
+ *
+ * Public positions are physical, so a cursor is converted back with
+ * `physicalIdx` before it leaves a backend.
+ */
+export type Cursor = number;
+/**
+ * A matcher's own result: the AST built so far, whether it matched, and where
+ * it stopped.
+ *
+ * `P` is the position type. A backend whose match always has one uses
+ * {@link Cursor}; one that also reports running out of input uses
+ * `Cursor | null`. Public results are each backend's own type — this is the
+ * shape they are built from, not the shape they return.
+ */
+export type AstResult<L, P> = {
+    readonly ast: Ast<L>;
+    readonly success: boolean;
+    readonly pos: P;
+};

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/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

@@ -14,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;
 };