functionalscript 0.16.1 → 0.18.0

package/fs/asn.1/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * ASN.1 BER/DER encoding and decoding over bit vectors. Includes tag/class
+ * helpers, length-prefixed payloads, and OID conversion via Base-128.
+ *
+ * @module
+ */
 import { bitLength, max } from "../types/bigint/module.f.js";
 import { empty, isVec, length, listToVec, msb, uint, unpack, vec, vec8 } from "../types/bit_vec/module.f.js";
 import { identity } from "../types/function/module.f.js";

package/fs/ci/bun/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * CI step builder for Bun: installs the pinned Bun version (with a PowerShell
+ * fallback for Windows ARM) and runs `bun install` and `bun test`.
+ *
+ * @module
+ */
 import { bun } from "../config/module.f.js";
 import { clean, install, test } from "../common/module.f.js";
 const installOnWindowsArm = ({ def, name, path }) => (v) => (a) => install(v === 'windows' && a === 'arm'

package/fs/ci/common/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Shared CI types and helpers: GitHub Actions step/job RTTI schemas, the
+ * `MetaStep` representation used by tool-specific modules, and assemblers like
+ * `install`, `test`, `clean`, `ubuntu`, and `toSteps`.
+ *
+ * @module
+ */
 import { images } from '../config/module.f.ts';
 import { type Ts } from '../../types/rtti/ts/module.f.ts';
 export declare const os: readonly ["ubuntu", "macos", "windows"];
@@ -5,12 +12,12 @@ export type Os = typeof os[number];
 export declare const architecture: readonly ["intel", "arm"];
 export type Architecture = typeof architecture[number];
 export type Image = typeof images[Os][Architecture];
-declare const stepSchema: {
+export declare const stepSchema: {
     readonly run: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
     readonly uses: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
     readonly with: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
 };
-declare const jobSchema: {
+export declare const jobSchema: {
     readonly 'runs-on': import("../../types/rtti/module.f.ts").String;
     readonly steps: import("../../types/rtti/module.f.ts").Type1<"array", {
         readonly run: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
@@ -18,7 +25,7 @@ declare const jobSchema: {
         readonly with: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
     }>;
 };
-declare const jobsSchema: import("../../types/rtti/module.f.ts").Type1<"record", {
+export declare const jobsSchema: import("../../types/rtti/module.f.ts").Type1<"record", {
     readonly 'runs-on': import("../../types/rtti/module.f.ts").String;
     readonly steps: import("../../types/rtti/module.f.ts").Type1<"array", {
         readonly run: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
@@ -26,7 +33,7 @@ declare const jobsSchema: import("../../types/rtti/module.f.ts").Type1<"record",
         readonly with: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
     }>;
 }>;
-declare const gitHubActionSchema: {
+export declare const gitHubActionSchema: {
     readonly name: import("../../types/rtti/module.f.ts").String;
     readonly on: {
         readonly pull_request: import("../../types/rtti/module.f.ts").Or<readonly [{}, undefined]>;
@@ -75,4 +82,3 @@ export declare const clean: (steps: readonly MetaStep[]) => readonly MetaStep[];
 export declare const toSteps: (m: readonly MetaStep[]) => readonly Step[];
 export declare const ubuntu: (ms: readonly MetaStep[]) => Job;
 export declare const findTgz: (v: Os) => "(Get-ChildItem *.tgz).FullName" | "./*.tgz";
-export {};

package/fs/ci/common/module.f.js

@@ -1,20 +1,27 @@
+/**
+ * Shared CI types and helpers: GitHub Actions step/job RTTI schemas, the
+ * `MetaStep` representation used by tool-specific modules, and assemblers like
+ * `install`, `test`, `clean`, `ubuntu`, and `toSteps`.
+ *
+ * @module
+ */
 import { images, rust } from "../config/module.f.js";
 import { option, array, record, string } from "../../types/rtti/module.f.js";
 import {} from "../../types/rtti/ts/module.f.js";
 import { parse as rttiParse } from "../../types/rtti/parse/module.f.js";
 export const os = ['ubuntu', 'macos', 'windows'];
 export const architecture = ['intel', 'arm'];
-const stepSchema = {
+export const stepSchema = {
     run: option(string),
     uses: option(string),
     with: option(record(string))
 };
-const jobSchema = {
+export const jobSchema = {
     'runs-on': string,
     steps: array(stepSchema)
 };
-const jobsSchema = record(jobSchema);
-const gitHubActionSchema = {
+export const jobsSchema = record(jobSchema);
+export const gitHubActionSchema = {
     name: string,
     on: { pull_request: option({}) },
     jobs: jobsSchema

package/fs/ci/config/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Centralized version pins and OS images used by the CI generator: runner
+ * images, tool versions (Bun, Deno, Playwright, Rust, Node, Wasmtime, Wasmer,
+ * TSGO).
+ *
+ * @module
+ */
 export declare const images: {
     readonly ubuntu: {
         readonly intel: "ubuntu-24.04";
@@ -13,13 +20,13 @@ export declare const images: {
     };
 };
 export declare const bun = "1.3.14";
-export declare const deno = "2.7.14";
+export declare const deno = "2.8.0";
 export declare const playwright = "1.60.0";
 export declare const rust = "1.95.0";
 export declare const node: {
-    readonly default: "26.1.0";
-    readonly others: readonly ["22.22.3", "24.15.0"];
+    readonly default: "26.2.0";
+    readonly others: readonly ["22.22.3", "24.16.0"];
 };
 export declare const wasmtime = "44.0.1";
 export declare const wasmer = "7.1.0";
-export declare const tsgo = "7.0.0-dev.20260517.1";
+export declare const tsgo = "7.0.0-dev.20260526.1";

package/fs/ci/config/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * Centralized version pins and OS images used by the CI generator: runner
+ * images, tool versions (Bun, Deno, Playwright, Rust, Node, Wasmtime, Wasmer,
+ * TSGO).
+ *
+ * @module
+ */
 // https://docs.github.com/en/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for-public-repositories
 export const images = {
     ubuntu: {
@@ -16,19 +23,19 @@ export const images = {
 // https://bun.sh/
 export const bun = '1.3.14';
 // https://deno.com/
-export const deno = '2.7.14';
+export const deno = '2.8.0';
 // https://www.npmjs.com/package/playwright
 export const playwright = '1.60.0';
 // https://rust-lang.org/
 export const rust = '1.95.0';
 // https://nodejs.org/en/download
 export const node = {
-    default: '26.1.0',
-    others: ['22.22.3', '24.15.0'],
+    default: '26.2.0',
+    others: ['22.22.3', '24.16.0'],
 };
 // https://github.com/bytecodealliance/wasmtime/releases
 export const wasmtime = '44.0.1';
 // https://github.com/wasmerio/wasmer/releases
 export const wasmer = '7.1.0';
 // https://www.npmjs.com/package/@typescript/native-preview?activeTab=versions
-export const tsgo = '7.0.0-dev.20260517.1';
+export const tsgo = '7.0.0-dev.20260526.1';

package/fs/ci/deno/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * CI step builder for Deno: installs the pinned Deno version and runs
+ * `deno install` followed by `deno task test`.
+ *
+ * @module
+ */
 import { deno } from "../config/module.f.js";
 import { clean, install, test } from "../common/module.f.js";
 export const denoSteps = (extra) => clean([

package/fs/ci/node/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * CI step builders for Node.js: setup-node installation, common npm
+ * install/test sequences, per-version job matrices, and the main TSGO step.
+ *
+ * @module
+ */
 import { node, tsgo } from "../config/module.f.js";
 import { clean, findTgz, install, test, ubuntu } from "../common/module.f.js";
 export const major = (v) => v.split('.')[0];

package/fs/ci/playwright/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * CI job that installs Playwright (with a browser-cache step) and runs the
+ * test suite against Chromium, Firefox, and WebKit.
+ *
+ * @module
+ */
 import { images, node, playwright } from "../config/module.f.js";
 import { install, test, toSteps } from "../common/module.f.js";
 import { basicNode } from "../node/module.f.js";

package/fs/ci/rust/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * CI step builder for the Rust crate: `cargo fmt`, `cargo clippy`, native and
+ * `--release` test runs, plus matrix entries for WASM targets (Wasmtime,
+ * Wasmer) and the 32-bit `i686` targets.
+ *
+ * @module
+ */
 import { wasmer, wasmtime } from "../config/module.f.js";
 import { install, test } from "../common/module.f.js";
 const cargoTest = (target, config) => {

package/fs/ci/test.f.js

@@ -4,10 +4,8 @@ import { isVec } from "../types/bit_vec/module.f.js";
 import { test, parseGitHubAction } from "./common/module.f.js";
 import { assert } from "../dev/module.f.js";
 import { emptyState, virtual } from "../types/effects/node/virtual/module.f.js";
-import {} from "../types/rtti/ts/module.f.js";
 import { parse as jsonParse } from "../json/module.f.js";
 import { unwrap } from "../types/result/module.f.js";
-// type Gha = Ts<typeof gitHubActionSchema>
 const hasRun = (cmd) => (gha) => Object.values(gha.jobs).some(job => job.steps.some(step => step.run?.includes(cmd)));
 const hasRunInJob = (jobId, cmd) => (gha) => gha.jobs[jobId]?.steps.some(step => step.run?.includes(cmd)) ?? false;
 const githubState = {
@@ -18,9 +16,9 @@ const run = (rust, nodeExtra = () => []) => {
     const [state, result] = virtual(githubState)(ci({ rust, nodeExtra, denoExtra: [], bunExtra: [] }));
     assert(result === 0, result);
     const dotGithub = state.root['.github'];
-    assert(dotGithub !== undefined && !isVec(dotGithub), dotGithub);
+    assert(typeof dotGithub === 'object', dotGithub);
     const workflows = dotGithub['workflows'];
-    assert(workflows !== undefined && !isVec(workflows), workflows);
+    assert(typeof workflows === 'object', workflows);
     const file = workflows['ci.yml'];
     assert(isVec(file), file);
     return unwrap(parseGitHubAction(jsonParse(utf8ToString(file))));

package/fs/crypto/secp/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Short Weierstrass elliptic-curve arithmetic over a prime field: `curve`
+ * builds point negation, addition, and scalar multiplication for any
+ * `secp`-family curve from its `(p, a, g, n)` parameters.
+ *
+ * @module
+ */
 import type { Equal, Fold, Reduce } from '../../types/function/operator/module.f.ts';
 import { type PrimeField } from '../../types/prime_field/module.f.ts';
 /**

package/fs/dev/index/module.f.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Entry point for the `index` developer program: re-exports `index4` from the
+ * parent `dev` module as the default `NodeProgram`.
+ *
+ * @module
+ */
 import { index4 } from '../module.f.ts';
 export default index4;

package/fs/dev/index/module.f.js

@@ -1,2 +1,8 @@
+/**
+ * Entry point for the `index` developer program: re-exports `index4` from the
+ * parent `dev` module as the default `NodeProgram`.
+ *
+ * @module
+ */
 import { index4 } from "../module.f.js";
 export default index4;

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

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import { type Io } from '../io/module.f.ts';
-import { type All, type NodeProgram, type Readdir } from '../types/effects/node/module.f.ts';
+import type { Io } from '../io/module.f.ts';
+import { type Access, type All, type Env, type Import, type NodeProgram, type Readdir } from '../types/effects/node/module.f.ts';
 import { type Effect } from '../types/effects/module.f.ts';
 export declare const todo: () => never;
 export declare const assert: (v: boolean, msg?: unknown) => asserts v;
@@ -18,5 +18,6 @@ export type ModuleMap = {
 };
 export declare const env: (io: Io) => (v: string) => string | undefined;
 export declare const allFiles: (s: string) => Effect<Readdir | All, readonly string[]>;
-export declare const loadModuleMap: (io: Io) => Promise<ModuleMap>;
+export type LoadModuleOperations = Access | Import | All | Readdir;
+export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap>;
 export declare const index4: NodeProgram;

package/fs/dev/module.f.js

@@ -1,9 +1,3 @@
-/**
- * Development utilities for indexing modules and loading FunctionalScript files.
- *
- * @module
- */
-import { fromIo } from "../io/module.f.js";
 import { updateVersion } from "./version/module.f.js";
 import { access, all, both, import_, readdir, readFile, writeFile } from "../types/effects/node/module.f.js";
 import { utf8, utf8ToString } from "../text/module.f.js";
@@ -12,6 +6,7 @@ import { begin, pure } from "../types/effects/module.f.js";
 import { parse as jsonParse } from "../json/module.f.js";
 import { record, unknown as rttiUnknown } from "../types/rtti/module.f.js";
 import { parse as rttiParse } from "../types/rtti/parse/module.f.js";
+import { relativize } from "../path/module.f.js";
 export const todo = () => { throw 'not implemented'; };
 export const assert = (v, msg = 'assertion failed') => {
     if (!v)
@@ -63,14 +58,21 @@ const loadFile = (f) => {
     }
     return pure([]);
 };
-export const loadModuleMap = async (io) => {
-    const { process: { env } } = io;
+const { fromEntries } = Object;
+export const loadModuleMap = (env) => {
     const initCwd = env['INIT_CWD'];
     const s = initCwd === undefined ? '.' : `${initCwd.replaceAll('\\', '/')}`;
-    const effect = allFiles(s)
+    const prefix = s === '.' ? '' : s;
+    // TODO: there are multiple `all` effects here,
+    //       we should consider optimize 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)
         .step(files => all(...files.map(loadFile)))
-        .step(entries => pure(Object.fromEntries(entries.flat().toSorted(cmp))));
-    return fromIo(io)(effect);
+        .step(entries => pure(fromEntries(entries
+        .flat()
+        .map(([k, v]) => [relativize(prefix, k), v])
+        .toSorted(cmp))));
 };
 const denoJson = './deno.json';
 const parseDenoJson = rttiParse(record(rttiUnknown));

package/fs/dev/tf/module.d.ts

@@ -1 +1,2 @@
+export declare const run3: () => Promise<void>;
 export declare const run: () => Promise<void>;

package/fs/dev/tf/module.f.d.ts

@@ -1,24 +1,72 @@
-import { type CsiConsole } from '../../text/sgr/module.f.ts';
-import type * as Result from '../../types/result/module.f.ts';
-import type { Io, Performance, TryCatch } from '../../io/module.f.ts';
-import { type ModuleMap } from '../module.f.ts';
-type Log<T> = CsiConsole;
-type Measure<T> = <R>(f: () => R) => (state: T) => readonly [R, number, T];
-type Input<T> = {
-    readonly moduleMap: ModuleMap;
-    readonly log: Log<T>;
-    readonly error: Log<T>;
-    readonly measure: Measure<T>;
-    readonly state: T;
-    readonly tryCatch: <R>(f: () => R) => Result.Result<R, unknown>;
-    readonly env: (n: string) => string | undefined;
-};
+import { type All, type NodeProgram, type NodeProgramOptions, type Program, type Sandbox, type SandboxResult, type Write } from '../../types/effects/node/module.f.ts';
+import { type Effect, type Operation } from '../../types/effects/module.f.ts';
+import { type LoadModuleOperations, type ModuleMap } from '../module.f.ts';
 export declare const isTest: (s: string) => boolean;
 export type Test = () => unknown;
-export type TestSet = Test | readonly (readonly [string, unknown])[];
-export declare const parseTestSet: (t: TryCatch) => (throws: boolean) => (x: unknown) => TestSet;
-export declare const test: <T>(input: Input<T>) => readonly [number, T];
-export declare const anyLog: (f: (s: string) => void) => (s: string) => <T>(state: T) => T;
-export declare const measure: (p: Performance) => <R>(f: () => R) => <T>(state: T) => readonly [R, number, T];
-export declare const main: (io: Io) => Promise<number>;
-export {};
+export type TestEntry = {
+    readonly fn: Test;
+    readonly throws: boolean;
+};
+export type TestSet = TestEntry | readonly (readonly [string, unknown])[];
+export declare const parseTestSet: (throws: boolean, x: unknown) => TestSet;
+/**
+ * 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 declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly (readonly [Path, TestEntry])[];
+/**
+ * Receives semantic test-run events. Each method is the runner's notification
+ * of an event; the reporter decides how to render it (terminal, GitHub
+ * annotations, JSON, node `--test`, etc.). `path` is the chain of object keys
+ * leading to the current location; `null` marks a function-call boundary, e.g.
+ * `['outer', null, 'inner']` means `outer` was invoked and its return value
+ * contained `inner`.
+ */
+export type Reporter<O extends Operation> = {
+    readonly result: (file: string, path: Path, r: SandboxResult<unknown>) => Effect<O, void>;
+    readonly summary: (pass: number, fail: number, time: number) => Effect<O, void>;
+    readonly test: (file: string, path: Path, set: TestEntry) => Effect<O, SandboxResult<unknown>>;
+};
+export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number>;
+export declare const test: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+export type Path = readonly (string | null)[];
+export declare const isInteger: (s: string) => boolean;
+export declare const isIdentifier: (s: string) => boolean;
+/**
+ * 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 declare const fmtPath: (path: Path) => string;
+/**
+ * Formats a fully-qualified test identifier as a JS-like expression, e.g.
+ * `import("./math.test.f.ts").add()` or `import("./a.test.f.ts").users[3].name()`.
+ * Self-contained per line — suitable for parallel output and as a CLI filter argument.
+ */
+export declare const fmtImport: (file: string, path: Path) => string;
+/**
+ * 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 declare const fmtTerm: (path: Path) => string;
+/**
+ * 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 declare const ghEscape: (s: string) => string;
+export declare const defaultTest: (file: string, path: Path, { fn, throws }: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>;
+/**
+ * The terminal/GitHub reporter used by `fjs t`. Output goes through
+ * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
+ * `GITHUB_ACTION` 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 declare const defaultReporter: (options: NodeProgramOptions) => Reporter<Write | Sandbox>;
+export declare const main: NodeProgram;