functionalscript 0.43.1 → 0.45.0

package/fjs/ci/config/module.f.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Centralized version pins and OS images used by the CI generator: runner
+ * images, tool versions (Bun, Deno, Rust, Node, Wasmtime, Wasmer, TSGO).
+ *
+ * @module
+ */
+export declare const images: {
+    readonly ubuntu: {
+        readonly intel: 'ubuntu-26.04';
+        readonly arm: 'ubuntu-26.04-arm';
+    };
+    readonly macos: {
+        readonly intel: 'macos-26-intel';
+        readonly arm: 'macos-26';
+    };
+    readonly windows: {
+        readonly intel: 'windows-2025';
+        readonly arm: 'windows-11-arm';
+    };
+};
+export declare const functionalscript = /** @type {const} */ "0.44.0";
+export declare const bun = "1.3.14";
+export declare const deno = "2.9.5";
+export declare const node: {
+    readonly default: '26.7.0';
+    readonly node22: '22.23.2';
+    readonly node24: '24.18.1';
+};
+export declare const nixpkgs: {
+    readonly ref: 'nixos-26.05';
+    readonly commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5';
+};
+export declare const wasmtime = "47.0.3";
+export declare const wasmer = "7.2.1";
+export declare const actions: {
+    readonly 'actions/checkout': 'v7.0.1';
+    readonly 'actions/setup-node': 'v7.0.0';
+    readonly 'actions/cache': 'v6.1.0';
+    readonly 'denoland/setup-deno': 'v2.0.5';
+    readonly 'oven-sh/setup-bun': 'v2.2.0';
+    readonly 'bytecodealliance/actions/wasmtime/setup': 'v1.1.3';
+    readonly 'wasmerio/setup-wasmer': 'v3.1';
+    readonly 'cachix/install-nix-action': 'v31.11.1';
+    readonly 'dtolnay/rust-toolchain': '1.97.1';
+};

package/fjs/ci/config/module.f.mjs

@@ -0,0 +1,89 @@
+/**
+ * Centralized version pins and OS images used by the CI generator: runner
+ * images, tool versions (Bun, Deno, 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 = /** @type {const} */({
+    ubuntu: {
+        intel: 'ubuntu-26.04',
+        arm: 'ubuntu-26.04-arm'
+    },
+    macos: {
+        intel: 'macos-26-intel',
+        arm: 'macos-26'
+    },
+    windows: {
+        intel: 'windows-2025',
+        arm: 'windows-11-arm',
+    }
+})
+
+// Bootstrap package version used by generated smoke tests. Keep this on a
+// published FunctionalScript release; do not tie it to package.json's current
+// in-repo version.
+// https://www.npmjs.com/package/functionalscript
+export const functionalscript = /** @type {const} */ '0.44.0'
+
+// https://bun.sh/
+export const bun = '1.3.14'
+
+// https://deno.com/
+export const deno = '2.9.5'
+
+// The Node versions the pinned Nixpkgs snapshot below provides — read from
+// `pkgs/development/web/nodejs/v{22,24,26}.nix` at that commit. Every runtime
+// uses these: `setup-node` on the GitHub-hosted runners and the generated
+// flakes on the Nix jobs, which assert the version they actually get. Nixpkgs
+// usually trails nodejs.org, so bump the snapshot first and copy the versions
+// it offers rather than the latest release.
+// https://nodejs.org/en/download
+export const node = /** @type {const} */({
+    default: '26.7.0',
+    node22: '22.23.2',
+    node24: '24.18.1',
+})
+
+// Official Nixpkgs snapshot used by the generated CI flakes. `ref` is the
+// stable channel the commit is accepted from; `commit` is the exact revision
+// every generated `flake.nix` pins. The Node versions above come from this
+// snapshot, so the two move together.
+// https://channels.nixos.org/nixos-26.05/git-revision
+export const nixpkgs = /** @type {const} */({
+    ref: 'nixos-26.05',
+    commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5',
+})
+
+// https://github.com/bytecodealliance/wasmtime/releases
+export const wasmtime = '47.0.3'
+
+// https://github.com/wasmerio/wasmer/releases
+export const wasmer = '7.2.1'
+
+// GitHub Action versions used by CI step builders. The key is the action
+// `owner/name`; call sites compose the full ref as
+// `` `${name}@${actions[name]}` ``.
+// Note: dtolnay/rust-toolchain value is a Rust version, not an action version.
+export const actions = /** @type {const} */({
+    // https://github.com/marketplace/actions/checkout
+    'actions/checkout': 'v7.0.1',
+    // https://github.com/marketplace/actions/setup-node-js-environment
+    'actions/setup-node': 'v7.0.0',
+    // https://github.com/marketplace/actions/cache
+    'actions/cache': 'v6.1.0',
+    // https://github.com/marketplace/actions/setup-deno
+    'denoland/setup-deno': 'v2.0.5',
+    // https://github.com/marketplace/actions/setup-bun
+    'oven-sh/setup-bun': 'v2.2.0',
+    // https://github.com/bytecodealliance/actions
+    'bytecodealliance/actions/wasmtime/setup': 'v1.1.3',
+    // https://github.com/wasmerio/setup-wasmer
+    'wasmerio/setup-wasmer': 'v3.1',
+    // https://github.com/marketplace/actions/install-nix
+    // Enables the `nix-command` and `flakes` experimental features by default.
+    'cachix/install-nix-action': 'v31.11.1',
+    // https://rust-lang.org/ - value is Rust version, not action version
+    'dtolnay/rust-toolchain': '1.97.1',
+})

package/fjs/ci/deno/module.f.d.mts

@@ -0,0 +1,16 @@
+/**
+ * CI step builder for Deno: installs the pinned Deno version and runs the
+ * FunctionalScript package smoke test plus Deno coverage in one canonical job.
+ *
+ * Coverage runs through `deno task cov`, so `deno.json` owns the permission set
+ * and the coverage filter, exactly as `npm run cov` leaves them to
+ * `package.json` for the Node jobs. The two `cov` definitions select the same
+ * modules and should stay semantically equal.
+ *
+ * @module
+ *
+ * @import { MetaStep } from '../common/types.ts'
+ */
+import type { MetaStep } from '../common/types.ts';
+/** @type {(version: string) => readonly MetaStep[]} */
+export declare const denoSteps: (version: string) => readonly MetaStep[];

package/fjs/ci/deno/module.f.mjs

@@ -0,0 +1,29 @@
+/**
+ * CI step builder for Deno: installs the pinned Deno version and runs the
+ * FunctionalScript package smoke test plus Deno coverage in one canonical job.
+ *
+ * Coverage runs through `deno task cov`, so `deno.json` owns the permission set
+ * and the coverage filter, exactly as `npm run cov` leaves them to
+ * `package.json` for the Node jobs. The two `cov` definitions select the same
+ * modules and should stay semantically equal.
+ *
+ * @module
+ *
+ * @import { MetaStep } from '../common/types.ts'
+ */
+
+import { deno } from '../config/module.f.mjs'
+import { install, test, uses } from '../common/module.f.mjs'
+
+/** @type {(version: string) => readonly MetaStep[]} */
+export const denoSteps = version => [
+    install(uses('denoland/setup-deno', { 'deno-version': deno })),
+    // We need --minimum-dependency-age=0 for functionalscript because we would like to use
+    // the latest version of the package even if it is not yet 24 hours old,
+    // which is the default minimum dependency age for Deno installs.
+    // This way we can test the latest version of the package in CI without waiting for 24 hours.
+    install({ run: `deno install -g -A --minimum-dependency-age=0 npm:functionalscript@${version}` }),
+    test({ run: `deno run -A --minimum-dependency-age=0 npm:functionalscript@${version} test` }),
+    test({ run: 'deno install --frozen' }),
+    test({ run: 'deno task cov' }),
+]

package/fjs/ci/deno/proof.f.d.mts

@@ -0,0 +1,4 @@
+export declare const proof: {
+    coverageStep: () => void;
+    installsPinnedVersion: () => void;
+};

package/fjs/ci/deno/proof.f.mjs

@@ -0,0 +1,26 @@
+import { denoSteps } from './module.f.mjs'
+import { toSteps } from '../common/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {(version: string) => readonly string[]} */
+const coverageRuns = version =>
+    toSteps(denoSteps(version))
+        .flatMap(s => s.run !== undefined && s.run.includes('cov') ? [s.run] : [])
+
+export const proof = {
+    // A regression guard: the job must delegate coverage to `deno.json`'s `cov`
+    // task. Inlining the command here instead would give the coverage filter a
+    // second owner that can silently drift from `deno.json`.
+    coverageStep: () => {
+        const runs = coverageRuns('0.0.0')
+        assertEq(runs.length, 1)
+        const [run] = runs
+        assertEq(run, 'deno task cov')
+    },
+    installsPinnedVersion: () => {
+        const runs = toSteps(denoSteps('1.2.3'))
+            .flatMap(s => s.run !== undefined && s.run.includes('npm:functionalscript@') ? [s.run] : [])
+        assertEq(runs.length, 2)
+        assert(runs.every(r => r.includes('npm:functionalscript@1.2.3')))
+    },
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Continuous integration helper commands for repository automation tasks.
+ *
+ * See `./types.ts` for the `Setup` type-level API.
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp } from '../effects/node/types.ts'
+ * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
+ * @import { NixJob } from './nix/types.ts'
+ * @import { Setup } from './types.ts'
+ */
+import type { Effect } from '../effects/types.ts';
+import type { NodeOp } from '../effects/node/types.ts';
+import type { Setup } from './types.ts';
+/** @type {(setup: Setup) => Effect<NodeOp, number>} */
+export declare const ci: (setup: Setup) => Effect<NodeOp, number>;
+export declare const main: () => Effect<NodeOp, number>;

package/fjs/ci/module.f.mjs

@@ -0,0 +1,89 @@
+/**
+ * Continuous integration helper commands for repository automation tasks.
+ *
+ * See `./types.ts` for the `Setup` type-level API.
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp } from '../effects/node/types.ts'
+ * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
+ * @import { NixJob } from './nix/types.ts'
+ * @import { Setup } from './types.ts'
+ */
+
+import { mapStep, step } from '../effects/module.f.mjs'
+import { access, writeUtf8File } from '../effects/node/module.f.mjs'
+import { functionalscript, images } from './config/module.f.mjs'
+import {
+    architecture,
+    os,
+    toSteps,
+    ubuntuArm
+} from './common/module.f.mjs'
+import { rustPlatformSteps, rustWasmSteps } from './rust/module.f.mjs'
+import { nodeMainSteps, nodeNixJobs, nodeNixVersionSteps, nodeVersionJobs } from './node/module.f.mjs'
+import { nixFlakes, nixInstall } from './nix/module.f.mjs'
+import { bunSteps } from './bun/module.f.mjs'
+import { denoSteps } from './deno/module.f.mjs'
+
+/** @type {(rust: boolean, nodeExtra: readonly MetaStep[]) => (o: Os) => (a: Architecture) => readonly [string, Job]} */
+const job = (rust, nodeExtra) => o => a => {
+    const id = `${o}-${a}`
+    const image = images[o][a]
+    const result = [
+        ...(rust ? rustPlatformSteps(o, a) : []),
+        ...nodeMainSteps(functionalscript),
+        ...nodeExtra,
+    ]
+    return [id, { 'runs-on': image, steps: toSteps(result) }]
+}
+
+// Every generated flake, across all job families that own one.
+/** @type {readonly NixJob[]} */
+const nixJobs = nodeNixJobs
+
+// Temporary: proves the not-yet-migrated flakes still evaluate. Removed once
+// the canonical Node jobs check their own flake by running through it.
+/** @type {Job} */
+const nixFlakeJob = ubuntuArm([nixInstall, ...nodeNixVersionSteps])
+
+/** @type {(rust: boolean) => Jobs} */
+const canonicalJobs = rust => ({
+    ...(rust ? { wasm: ubuntuArm(rustWasmSteps) } : {}),
+    deno: ubuntuArm(denoSteps(functionalscript)),
+    bun: ubuntuArm(bunSteps(functionalscript)),
+    ...nodeVersionJobs(functionalscript),
+    'nix-flakes': nixFlakeJob,
+})
+
+/** @type {(setup: Setup) => Effect<NodeOp, number>} */
+export const ci = ({ nodeExtra }) => step(
+    access('Cargo.toml'),
+    result => {
+        const rust = result[0] === 'ok'
+        /** @type {Jobs} */
+        const jobs = {
+            ...Object.fromEntries(os.flatMap(o => architecture.map(job(rust, nodeExtra(o))(o)))),
+            ...canonicalJobs(rust),
+        }
+        /** @type {GitHubAction} */
+        const gha = {
+            name: 'CI',
+            on: {
+                pull_request: {},
+                merge_group: {},
+            },
+            permissions: {
+                contents: 'read',
+            },
+            jobs,
+        }
+        const workflowWritten = writeUtf8File(
+            '.github/workflows/ci.yml',
+            JSON.stringify(gha, null, '  '))
+        const flakesWritten = step(workflowWritten, () => nixFlakes(nixJobs))
+        return mapStep(flakesWritten, () => 0)
+    })
+
+export const main = () => ci({ nodeExtra: () => [] })

package/fjs/ci/nix/module.f.d.mts

@@ -0,0 +1,69 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.mjs` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * See `./types.ts` for the `NixJob` type-level API.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
+ * @import { Expression } from '../../media/nix/types.ts'
+ * @import { MetaStep } from '../common/types.ts'
+ * @import { NixJob } from './types.ts'
+ */
+import type { Effect } from '../../effects/types.ts';
+import type { Mkdir, WriteFile } from '../../effects/node/types.ts';
+import type { MetaStep } from '../common/types.ts';
+import type { NixJob } from './types.ts';
+/** Directory owned by this generator. */
+export declare const generatedDirectory: 'nix/generated';
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ *
+ * @type {(job: NixJob) => string}
+ */
+export declare const flakeText: (job: NixJob) => string;
+/**
+ * Writes one generated flake per job.
+ *
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ */
+export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>;
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+export declare const flakePath: (id: string) => string;
+/** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
+export declare const nixInstall: MetaStep;
+/** Runs one command inside a job's generated development shell. */
+export declare const nixDevelop: (id: string, command: string) => string;
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ *
+ * @type {(id: string, commands: readonly string[]) => string}
+ */
+export declare const nixDevelopAll: (id: string, commands: readonly string[]) => string;
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ *
+ * @type {(id: string, version: string) => MetaStep}
+ */
+export declare const nixVersionCheckStep: (id: string, version: string) => MetaStep;

package/fjs/ci/nix/module.f.mjs

@@ -0,0 +1,136 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.mjs` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * See `./types.ts` for the `NixJob` type-level API.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
+ * @import { Expression } from '../../media/nix/types.ts'
+ * @import { MetaStep } from '../common/types.ts'
+ * @import { NixJob } from './types.ts'
+ */
+
+import { forEachStep, mapStep, pure, step } from '../../effects/module.f.mjs'
+import { mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { nixToString } from '../../media/nix/module.f.mjs'
+import { fromUndefined, unwrap as unwrapNullable } from '../../types/nullable/module.f.mjs'
+import { unwrap } from '../../types/result/module.f.mjs'
+import { install, test, uses } from '../common/module.f.mjs'
+import { nixpkgs } from '../config/module.f.mjs'
+
+/** Directory owned by this generator. */
+export const generatedDirectory = /** @type {const} */ ('nix/generated')
+
+const { commit } = nixpkgs
+
+const url = `github:NixOS/nixpkgs/${commit}`
+
+/** @type {(job: NixJob) => Expression} */
+const flake = ({ system, packages, shellHook }) => ['set',
+    ['=', ['inputs', 'nixpkgs', 'url'], url],
+    ['=', ['outputs'], ['lambda',
+        ['open-set-pattern', 'nixpkgs'],
+        ['set',
+            ['=', ['devShells', system, 'default'], ['let',
+                [['=', ['pkgs'], ['apply',
+                    ['ref', 'import'],
+                    ['ref', 'nixpkgs'],
+                    ['set', ['=', ['system'], system]]
+                ]]],
+                ['apply',
+                    ['ref', 'pkgs', 'mkShell'],
+                    ['set',
+                        ['=', ['packages'], ['list', ...packages.map(p => /** @type {const} */ (['ref', 'pkgs', p]))]],
+                        ...(shellHook === undefined
+                            ? []
+                            : [/** @type {const} */ (['=', ['shellHook'], ['indented-string', shellHook]])])
+                    ]
+                ]
+            ]]
+        ]
+    ]]
+]
+
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ *
+ * @type {(job: NixJob) => string}
+ */
+export const flakeText = job =>
+    unwrapNullable(fromUndefined(nixToString(flake(job))))
+
+/** @type {(job: NixJob) => Effect<Mkdir | WriteFile, void>} */
+const writeFlake = job => {
+    const directory = `${generatedDirectory}/${job.id}`
+    const created = mapStep(mkdir(directory, { recursive: true }), unwrap)
+    const written = step(
+        created,
+        () => writeUtf8File(`${directory}/flake.nix`, flakeText(job)))
+    return mapStep(written, unwrap)
+}
+
+/**
+ * Writes one generated flake per job.
+ *
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ */
+export const nixFlakes = jobs =>
+    forEachStep(pure(jobs), writeFlake)
+
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+export const flakePath = /** @type {(id: string) => string} */ (id => `./${generatedDirectory}/${id}`)
+
+/** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
+export const nixInstall = install(uses('cachix/install-nix-action'))
+
+/** Runs one command inside a job's generated development shell. */
+export const nixDevelop = /** @type {(id: string, command: string) => string} */
+    ((id, command) => `nix develop ${flakePath(id)} --command ${command}`)
+
+/**
+ * Wraps a string so a POSIX shell reproduces it exactly. Single quotes protect
+ * every other character, so only the quote itself needs handling: leave the
+ * literal, reopen it, and escape the quote outside (`'` becomes `'\''`).
+ *
+ * @type {(value: string) => string}
+ */
+const singleQuoted = value =>
+    `'${value.replaceAll("'", "'\\''")}'`
+
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ *
+ * @type {(id: string, commands: readonly string[]) => string}
+ */
+export const nixDevelopAll = (id, commands) =>
+    nixDevelop(id, `bash -euo pipefail -c ${singleQuoted(commands.join(' && '))}`)
+
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ *
+ * @type {(id: string, version: string) => MetaStep}
+ */
+export const nixVersionCheckStep = (id, version) =>
+    test({ run: `test "$(${nixDevelop(id, 'node --version')})" = v${version}` })

package/fjs/ci/nix/proof.f.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Proofs for generated CI flakes.
+ *
+ * @module
+ *
+ * @import { NixJob } from './types.ts'
+ */
+export declare const proof: {
+    flakeText: {
+        plain: () => void;
+        shellHook: () => void;
+    };
+    nixFlakes: {
+        write: () => void;
+        every: () => void;
+        nodeShellHook: () => void;
+        packages: () => void;
+        quotedPackage: () => void;
+        multiplePackages: () => void;
+    };
+    workflow: {
+        flakePath: () => void;
+        nixDevelop: () => void;
+        nixDevelopAll: {
+            sequence: () => void;
+            quote: () => void;
+        };
+        nixInstall: () => void;
+    };
+};