functionalscript 0.43.0 → 0.44.0

package/fjs/nanvm/rust/module.f.mjs

@@ -0,0 +1,166 @@
+/**
+ * Prints the shared operator test data as Rust.
+ *
+ * The output is `nanvm-lib/tests/test/generated.rs`: one statement per case,
+ * calling the hand-written helpers in `nanvm-lib/tests/test/harness.rs`. Only
+ * the helpers are written by hand — a new operator case is added to
+ * [`../module.f.mjs`](../module.f.mjs) and appears on both the JavaScript and
+ * the Rust side at once.
+ *
+ * Literal syntax comes from [`fjs/media/rust`](../../media/rust/module.f.mjs);
+ * what is specific to this module is the `nanvm-lib` API the statements target.
+ *
+ * Every emitted function carries `#[rustfmt::skip]`: the line layout here is
+ * one statement per case, and `cargo fmt -- --check` runs in CI, so the
+ * printer would otherwise have to reproduce rustfmt's wrapping exactly.
+ *
+ * @module
+ *
+ * @import { Case, Data, Eq, Group, Op, Value } from '../types.ts'
+ *
+ * @example
+ *
+ * ```js
+ * import { generate } from './module.f.mjs'
+ * import { data } from '../module.f.mjs'
+ *
+ * generate(data) // the contents of `nanvm-lib/tests/test/generated.rs`
+ * ```
+ */
+
+import {
+    f64Literal,
+    i64Literal,
+    snakeCase,
+    stringLiteral,
+} from '../../media/rust/module.f.mjs'
+
+const { entries } = Object
+
+const indent = '    '
+
+/**
+ * Where this printer's output goes, relative to the repository root.
+ *
+ * `tests/test/` rather than `tests/`: cargo turns every `tests/*.rs` into its
+ * own test target, so a generated file directly in `tests/` would be built as
+ * a second, harness-less crate. Inside `tests/test/` it is an ordinary
+ * submodule of the `tests/test/main.rs` target.
+ */
+export const directory = 'nanvm-lib/tests/test'
+
+/** @type {string} */
+export const path = `${directory}/generated.rs`
+
+/**
+ * A Rust expression of type `Any<A>`.
+ *
+ * Every use site fixes `A`, so no expression needs a turbofish: the harness
+ * helpers take `Any<A>` arguments and the shared `let` bindings are annotated.
+ *
+ * @type {(v: Value) => string}
+ */
+export const valueExpr = v => {
+    if (v === null) { return 'Nullish::Null.to_any()' }
+    if (typeof v === 'function') {
+        const info = v()
+        switch (info[0]) {
+            case 'function': { return 'function_any()' }
+            case 'ref': { return `${snakeCase(info[1])}.clone()` }
+            case 'throw': { throw ['`throws` is not a value', info] }
+        }
+    }
+    switch (typeof v) {
+        case 'undefined': { return 'Nullish::Undefined.to_any()' }
+        case 'boolean': { return `${v}.to_any()` }
+        case 'number': { return `(${f64Literal(v)}).to_any()` }
+        case 'string': { return `string_any(${stringLiteral(v)})` }
+        case 'bigint': { return `bigint_any(${i64Literal(v)})` }
+    }
+    if (Array.isArray(v)) {
+        const items = /** @type {readonly Value[]} */(v)
+        return items.length === 0
+            ? 'Array::default().to_any()'
+            : `[${items.map(valueExpr).join(', ')}].to_array().to_any()`
+    }
+    const properties = entries(v)
+    return properties.length === 0
+        ? 'Object::default().to_any()'
+        : `[${properties.map(
+            ([k, p]) => `(string_key(${stringLiteral(k)}), ${valueExpr(p)})`).join(', ')}].to_object().to_any()`
+}
+
+/** @type {(op: Op) => (args: readonly string[]) => string} */
+export const call = op => args => {
+    switch (op) {
+        case 'unaryPlus': { return `Any::unary_plus(${args[0]})` }
+        case 'unaryMinus': { return `-(${args[0]})` }
+        case 'mul': { return `${args[0]} * ${args[1]}` }
+        case 'stringCoercion': { return `${args[0]}.to_string().map(|v| v.to_any())` }
+    }
+}
+
+/**
+ * Comments out a statement `nanvm-lib` cannot pass yet, keeping the case
+ * visible in the generated file as the work still to do.
+ *
+ * @type {(reason: string|undefined) => (statement: string) => readonly string[]}
+ */
+const emit = reason => statement => reason === undefined
+    ? [`${indent}${statement}`]
+    : [`${indent}// TODO: ${reason}`, `${indent}// ${statement}`]
+
+/**
+ * Every argument order a case is checked in — both for a commutative
+ * operator, matching what the JavaScript proof does.
+ *
+ * @type {(commutative: boolean) => (c: Case) => readonly (readonly[string, readonly Value[]])[]}
+ */
+const orders = commutative => c => commutative
+    ? [[c.name, c.args], [`${c.name}Swapped`, c.args.toReversed()]]
+    : [[c.name, c.args]]
+
+/** @type {(expected: Value) => (name: string) => (result: string) => string} */
+const assertion = expected => name => result =>
+    typeof expected === 'function' && expected()[0] === 'throw'
+        ? `check_throws::<A>(${stringLiteral(name)}, ${result});`
+        : `check::<A>(${stringLiteral(name)}, ${result}, ${valueExpr(expected)});`
+
+/** @type {(g: Group) => readonly string[]} */
+const groupFn = g => [
+    '#[rustfmt::skip]',
+    `fn ${snakeCase(g.op)}<A: IVm>() {`,
+    ...g.cases.flatMap(c => orders(g.commutative === true)(c).flatMap(
+        ([name, args]) => emit(c.rust)(
+            assertion(c.expected)(name)(call(g.op)(args.map(valueExpr)))))),
+    '}',
+    '',
+]
+
+/** @type {(eq: Eq) => readonly string[]} */
+const eqFn = eq => [
+    '#[rustfmt::skip]',
+    'fn eq<A: IVm>() {',
+    ...entries(eq.shared).map(
+        ([k, v]) => `${indent}let ${snakeCase(k)}: Any<A> = ${valueExpr(v)};`),
+    ...eq.cases.flatMap(c => emit(c.rust)(
+        `check_eq::<A>(${stringLiteral(c.name)}, ${valueExpr(c.a)}, ${valueExpr(c.b)}, ${c.eq});`)),
+    '}',
+    '',
+]
+
+/** @type {(data: Data) => string} */
+export const generate = data => [
+    '// @generated by `npm run ci-update` from `fjs/nanvm/module.f.mjs`.',
+    '// Do not edit: change the shared operator test data and regenerate.',
+    '',
+    'use super::harness::*;',
+    '',
+    ...eqFn(data.eq),
+    ...data.groups.flatMap(groupFn),
+    'pub fn all<A: IVm>() {',
+    `${indent}eq::<A>();`,
+    ...data.groups.map(g => `${indent}${snakeCase(g.op)}::<A>();`),
+    '}',
+    '',
+].join('\n')

package/fjs/nanvm/rust/proof.f.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Proofs for the Rust printer.
+ *
+ * The interesting assertion is `generate`'s on a tiny synthetic corpus: it
+ * pins the exact text of every construct the printer can emit, so a change in
+ * layout is a visible diff here and not only in the generated file.
+ *
+ * @module
+ *
+ * @import { Data } from '../types.ts'
+ */
+export declare const proof: {
+    path: () => void;
+    valueExpr: () => void;
+    call: () => void;
+    generate: () => void;
+    generateData: () => void;
+    throw: {
+        throwsIsNotAValue: () => string;
+    };
+};

package/fjs/nanvm/rust/proof.f.mjs

@@ -0,0 +1,119 @@
+/**
+ * Proofs for the Rust printer.
+ *
+ * The interesting assertion is `generate`'s on a tiny synthetic corpus: it
+ * pins the exact text of every construct the printer can emit, so a change in
+ * layout is a visible diff here and not only in the generated file.
+ *
+ * @module
+ *
+ * @import { Data } from '../types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { data, functionValue, ref, throws } from '../module.f.mjs'
+import { call, directory, generate, path, valueExpr } from './module.f.mjs'
+import { snakeCase } from '../../media/rust/module.f.mjs'
+
+/**
+ * One case of every shape the printer can emit: a shared value and a
+ * reference to it, a skipped case, a throwing case, and a commutative binary
+ * operator.
+ *
+ * @type {Data}
+ */
+const sample = {
+    eq: {
+        shared: { emptyArray: [] },
+        cases: [
+            { name: 'itself', a: ref('emptyArray'), b: ref('emptyArray'), eq: true },
+            { name: 'skipped', a: null, b: null, eq: true, rust: 'not yet' },
+        ],
+    },
+    groups: [
+        { op: 'unaryPlus', cases: [{ name: 'bigint', args: [0n], expected: throws }] },
+        {
+            op: 'mul',
+            commutative: true,
+            cases: [{ name: 'oneByTwo', args: [1, 2], expected: 2 }],
+        },
+    ],
+}
+
+const expected = `// @generated by \`npm run ci-update\` from \`fjs/nanvm/module.f.mjs\`.
+// Do not edit: change the shared operator test data and regenerate.
+
+use super::harness::*;
+
+#[rustfmt::skip]
+fn eq<A: IVm>() {
+    let empty_array: Any<A> = Array::default().to_any();
+    check_eq::<A>("itself", empty_array.clone(), empty_array.clone(), true);
+    // TODO: not yet
+    // check_eq::<A>("skipped", Nullish::Null.to_any(), Nullish::Null.to_any(), true);
+}
+
+#[rustfmt::skip]
+fn unary_plus<A: IVm>() {
+    check_throws::<A>("bigint", Any::unary_plus(bigint_any(0)));
+}
+
+#[rustfmt::skip]
+fn mul<A: IVm>() {
+    check::<A>("oneByTwo", (1f64).to_any() * (2f64).to_any(), (2f64).to_any());
+    check::<A>("oneByTwoSwapped", (2f64).to_any() * (1f64).to_any(), (2f64).to_any());
+}
+
+pub fn all<A: IVm>() {
+    eq::<A>();
+    unary_plus::<A>();
+    mul::<A>();
+}
+`
+
+export const proof = {
+    path: () => {
+        assertEq(directory, 'nanvm-lib/tests/test')
+        assertEq(path, 'nanvm-lib/tests/test/generated.rs')
+    },
+    valueExpr: () => {
+        assertEq(valueExpr(null), 'Nullish::Null.to_any()')
+        assertEq(valueExpr(undefined), 'Nullish::Undefined.to_any()')
+        assertEq(valueExpr(true), 'true.to_any()')
+        assertEq(valueExpr(false), 'false.to_any()')
+        assertEq(valueExpr(-0.3), '(-0.3f64).to_any()')
+        assertEq(valueExpr('a'), 'string_any("a")')
+        assertEq(valueExpr(-1n), 'bigint_any(-1)')
+        assertEq(valueExpr([]), 'Array::default().to_any()')
+        assertEq(valueExpr([null]), '[Nullish::Null.to_any()].to_array().to_any()')
+        assertEq(valueExpr({}), 'Object::default().to_any()')
+        assertEq(
+            valueExpr({ k: null }),
+            '[(string_key("k"), Nullish::Null.to_any())].to_object().to_any()')
+        assertEq(valueExpr(functionValue), 'function_any()')
+        assertEq(valueExpr(ref('stringArray')), 'string_array.clone()')
+    },
+    call: () => {
+        assertEq(call('unaryPlus')(['x']), 'Any::unary_plus(x)')
+        assertEq(call('unaryMinus')(['x']), '-(x)')
+        assertEq(call('mul')(['x', 'y']), 'x * y')
+        assertEq(call('stringCoercion')(['x']), 'x.to_string().map(|v| v.to_any())')
+    },
+    generate: () => {
+        assertEq(generate(sample), expected)
+    },
+    generateData: () => {
+        // The real corpus, which is what `ci-update` writes. Only its shape is
+        // asserted here: its contents are checked by `cargo test`.
+        const result = generate(data)
+        assert(result.endsWith('}\n'), result)
+        assert(result.includes('pub fn all<A: IVm>() {'), result)
+        for (const g of data.groups) {
+            assert(result.includes(`fn ${snakeCase(g.op)}<A: IVm>() {`), g.op)
+            assert(result.includes(`${snakeCase(g.op)}::<A>();`), g.op)
+        }
+    },
+    throw: {
+        throwsIsNotAValue: () => valueExpr(throws),
+    },
+}

package/fjs/nanvm/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Type-level API for the shared operator test data.
+ *
+ * The data described here is the single source of truth for operator
+ * behaviour: [`proof.f.mjs`](./proof.f.mjs) runs it against a standard
+ * JavaScript engine, and [`rust/module.f.mjs`](./rust/module.f.mjs) prints it
+ * as the Rust tests in [`test/generated.rs`](./test/generated.rs).
+ *
+ * @module
+ */
+/**
+ * A value under test, written as itself.
+ *
+ * The shape follows `fjs/types/rtti`, where a constant is its own schema and a
+ * thunk describes anything that needs a tag: `2.3`, `'a'`, `12n`, `[1, 2]`,
+ * and `{ a: 1 }` mean exactly what they look like, and the only tagged forms
+ * are the ones a literal cannot express — see {@link Special}.
+ *
+ * Writing operands as plain JavaScript is what makes the corpus readable
+ * (`args: [[2.3]], expected: 2.3` rather than a tree of constructor calls) and
+ * costs nothing: both consumers already have to walk the value, and `typeof`
+ * plus `Array.isArray` recovers everything a tag would have carried.
+ */
+export type Value = Const | Special;
+/** A value that is its own description. */
+export type Const = null | undefined | boolean | number | string | bigint | readonly Value[] | Struct;
+/** An object value. Property order is the order the Rust printer emits. */
+export type Struct = {
+    readonly [k in string]?: Value;
+};
+/**
+ * Something no literal can express, described by a thunk.
+ *
+ * A function in the data is therefore always a *description*, never a value
+ * that happens to be a function — `functionValue` is how the data says "a
+ * function".
+ */
+export type Special = () => Info;
+/**
+ * What a {@link Special} describes.
+ *
+ * - `function` — a function value. Every operator here coerces one through
+ *   `ToPrimitive`, which never inspects it, so there is nothing to carry.
+ * - `ref` — one of the {@link Eq} `shared` values, so the *same* object
+ *   reaches both sides of a comparison.
+ * - `throw` — not a value at all: the case must throw. Valid only as a
+ *   {@link Case}'s `expected`.
+ */
+export type Info = readonly ['function'] | readonly ['ref', string] | readonly ['throw'];
+/** The operators covered by the shared data. */
+export type Op = 'unaryPlus' | 'unaryMinus' | 'mul' | 'stringCoercion';
+/**
+ * One operator test case.
+ *
+ * `expected` is compared with `Object.is`, so `NaN` matches `NaN` and `0` does
+ * not match `-0`; `throws` there means the operation must throw, and the
+ * exception value — being engine-specific — is not part of the data.
+ *
+ * `rust` marks a case `nanvm-lib` does not implement yet: the value is the
+ * reason, the generated Rust keeps the case as a commented-out `TODO`, and
+ * the JavaScript proof still runs it. Removing the property is what turns the
+ * case on for Rust — the gap list is data, not prose in a README.
+ */
+export type Case = {
+    readonly name: string;
+    readonly args: readonly Value[];
+    readonly expected: Value;
+    readonly rust?: string;
+};
+/**
+ * The cases of one operator.
+ *
+ * `commutative` additionally checks every case with its arguments swapped,
+ * which is what the hand-written tests did for `*`.
+ */
+export type Group = {
+    readonly op: Op;
+    readonly commutative?: boolean;
+    readonly cases: readonly Case[];
+};
+/** One strict-equality (`===`) case; `eq` is the expected result. */
+export type EqCase = {
+    readonly name: string;
+    readonly name2?: string;
+    readonly a: Value;
+    readonly b: Value;
+    readonly eq: boolean;
+    readonly rust?: string;
+};
+/**
+ * Strict-equality cases plus the values they share.
+ *
+ * Equality of arrays and objects is reference equality in both JavaScript and
+ * `nanvm-lib`, so a case can only express "the same object" by naming a value
+ * in `shared` and reaching it with a `ref`.
+ */
+export type Eq = {
+    readonly shared: Struct;
+    readonly cases: readonly EqCase[];
+};
+/** The whole shared test corpus. */
+export type Data = {
+    readonly eq: Eq;
+    readonly groups: readonly Group[];
+};

package/fjs/nanvm/types.js

@@ -0,0 +1,11 @@
+/**
+ * Type-level API for the shared operator test data.
+ *
+ * The data described here is the single source of truth for operator
+ * behaviour: [`proof.f.mjs`](./proof.f.mjs) runs it against a standard
+ * JavaScript engine, and [`rust/module.f.mjs`](./rust/module.f.mjs) prints it
+ * as the Rust tests in [`test/generated.rs`](./test/generated.rs).
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,23 @@
+/**
+ * Writes the generated Rust operator tests.
+ *
+ * The printer in [`../rust/module.f.mjs`](../rust/module.f.mjs) is pure; this
+ * module is the thin effectful shell around it, invoked from `ci-update` so
+ * the CI drift check regenerates the file on every pull request and fails
+ * when the committed copy is stale.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
+ */
+import type { Effect } from '../../effects/types.ts';
+import type { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts';
+/**
+ * Regenerates `nanvm-lib/tests/test/generated.rs` from the shared test data.
+ *
+ * @type {() => Effect<Mkdir | WriteFile, void>}
+ */
+export declare const generateRustTests: () => Effect<Mkdir | WriteFile, void>;
+/** @type {NodeProgram} */
+export declare const main: NodeProgram;

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

@@ -0,0 +1,33 @@
+/**
+ * Writes the generated Rust operator tests.
+ *
+ * The printer in [`../rust/module.f.mjs`](../rust/module.f.mjs) is pure; this
+ * module is the thin effectful shell around it, invoked from `ci-update` so
+ * the CI drift check regenerates the file on every pull request and fails
+ * when the committed copy is stale.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
+ */
+
+import { mapStep, step } from '../../effects/module.f.mjs'
+import { mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { unwrap } from '../../types/result/module.f.mjs'
+import { data } from '../module.f.mjs'
+import { directory, generate, path } from '../rust/module.f.mjs'
+
+/**
+ * Regenerates `nanvm-lib/tests/test/generated.rs` from the shared test data.
+ *
+ * @type {() => Effect<Mkdir | WriteFile, void>}
+ */
+export const generateRustTests = () => {
+    const directoryReady = mapStep(mkdir(directory, { recursive: true }), unwrap)
+    const written = step(directoryReady, () => writeUtf8File(path, generate(data)))
+    return mapStep(written, unwrap)
+}
+
+/** @type {NodeProgram} */
+export const main = () => mapStep(generateRustTests(), () => 0)

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

@@ -0,0 +1,9 @@
+/**
+ * Proofs for the generated-Rust writer.
+ *
+ * @module
+ */
+export declare const proof: {
+    generateRustTests: () => void;
+    main: () => void;
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Proofs for the generated-Rust writer.
+ *
+ * @module
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { step } from '../../effects/module.f.mjs'
+import { readUtf8File } from '../../effects/node/module.f.mjs'
+import {
+    defaultNodeProgramOptions,
+    emptyState,
+    virtual,
+} from '../../effects/node/virtual/module.f.mjs'
+import { data } from '../module.f.mjs'
+import { generate, path } from '../rust/module.f.mjs'
+import { generateRustTests, main } from './module.f.mjs'
+
+export const proof = {
+    generateRustTests: () => {
+        // The target directory does not exist in `emptyState`, so this also
+        // covers the `mkdir` the writer does before the file write.
+        const written = step(generateRustTests(), () => readUtf8File(path))
+        const [, [tag, result]] = virtual(emptyState)(written)
+        assert(tag === 'ok', result)
+        assertEq(result, generate(data))
+    },
+    main: () => {
+        const [, result] = virtual(emptyState)(main(defaultNodeProgramOptions))
+        assertEq(result, 0)
+    },
+}

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

@@ -0,0 +1,55 @@
+import type { Reduce, Unary } from '../types/function/operator/types.ts';
+/**
+ * Converts Windows separators (`\`) to POSIX separators (`/`).
+ *
+ * @type {(path: string) => string}
+ */
+export declare const toPosix: (path: string) => string;
+/**
+ * Splits a path into normalized segments.
+ *
+ * Empty (`""`) and current-directory (`"."`) segments are removed, parent-directory
+ * (`".."`) segments collapse the previous segment when possible, and Windows
+ * separators are converted to POSIX separators.
+ *
+ * @type {(path: string) => readonly string[]}
+ */
+export declare const parse: (path: string) => readonly string[];
+/**
+ * Normalizes a path string by parsing and rejoining it with POSIX separators.
+ *
+ * @type {Unary<string, string>}
+ */
+export declare const normalize: Unary<string, string>;
+/**
+ * Concatenates two path fragments and returns a normalized path.
+ *
+ * @type {Reduce<string>}
+ */
+export declare const concat: Reduce<string>;
+/**
+ * Joins path segments with single POSIX `/` separators, without
+ * normalization. Unlike {@link concat}, the result is not parsed/collapsed,
+ * so absolute roots and `.`/`..` segments are preserved verbatim. Use this
+ * for building paths from already-clean segments (directory walks, store
+ * layouts); use {@link concat} when normalization is desired.
+ *
+ * @type {(...list: readonly string[]) => string}
+ */
+export declare const join: (...list: readonly string[]) => string;
+/**
+ * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
+ * if it does not start with `base` or `base` is empty.
+ * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
+ *
+ * @type {(base: string, path: string) => string}
+ */
+export declare const relativize: (base: string, path: string) => string;
+/**
+ * Returns `true` when `prefix` is a strict ancestor of `path` in segment space:
+ * every segment of `prefix` matches the corresponding segment of `path`, and
+ * `path` has at least one additional segment.
+ *
+ * @type {(prefix: readonly string[], path: readonly string[]) => boolean}
+ */
+export declare const isProperPrefix: (prefix: readonly string[], path: readonly string[]) => boolean;

package/fjs/path/module.f.mjs

@@ -0,0 +1,96 @@
+/**
+ * Path parsing and normalization helpers for portable module paths.
+ *
+ * @module
+ */
+/** @import { Fold, Reduce, Unary } from '../types/function/operator/types.ts' */
+/** @import { List } from '../types/list/types.ts' */
+import { fold, last, take, length, concat as listConcat, toArray } from '../types/list/module.f.mjs'
+import { join as listJoin, concat as stringConcat } from '../types/string/module.f.mjs'
+
+/** @type {Fold<string, List<string>>} */
+const foldNormalizeOp = input => state => {
+    switch(input) {
+        case '': case '.': { return state }
+        case '..': {
+            switch(last(undefined)(state)) {
+                case undefined:
+                case '..': { return listConcat(state)([input]) }
+            }
+            return take(length(state) - 1)(state)
+        }
+        default: { return listConcat(state)([input]) }
+    }
+}
+
+/**
+ * Converts Windows separators (`\`) to POSIX separators (`/`).
+ *
+ * @type {(path: string) => string}
+ */
+export const toPosix = path => path.replaceAll('\\', '/')
+
+/**
+ * Splits a path into normalized segments.
+ *
+ * Empty (`""`) and current-directory (`"."`) segments are removed, parent-directory
+ * (`".."`) segments collapse the previous segment when possible, and Windows
+ * separators are converted to POSIX separators.
+ *
+ * @type {(path: string) => readonly string[]}
+ */
+export const parse = path => {
+    const split = toPosix(path).split('/')
+    return toArray(fold(foldNormalizeOp)([])(split))
+}
+
+/**
+ * Normalizes a path string by parsing and rejoining it with POSIX separators.
+ *
+ * @type {Unary<string, string>}
+ */
+export const normalize = path => {
+    const foldResult = parse(path)
+    return listJoin('/')(foldResult)
+}
+
+/**
+ * Concatenates two path fragments and returns a normalized path.
+ *
+ * @type {Reduce<string>}
+ */
+export const concat = a => b => {
+    const s = stringConcat([a, '/', b])
+    return normalize(s)
+}
+
+/**
+ * Joins path segments with single POSIX `/` separators, without
+ * normalization. Unlike {@link concat}, the result is not parsed/collapsed,
+ * so absolute roots and `.`/`..` segments are preserved verbatim. Use this
+ * for building paths from already-clean segments (directory walks, store
+ * layouts); use {@link concat} when normalization is desired.
+ *
+ * @type {(...list: readonly string[]) => string}
+ */
+export const join = (...list) => list.join('/')
+
+/**
+ * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
+ * if it does not start with `base` or `base` is empty.
+ * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
+ *
+ * @type {(base: string, path: string) => string}
+ */
+export const relativize = (base, path) =>
+    base !== '' && path.startsWith(base) ? `.${path.slice(base.length)}` : path
+
+/**
+ * Returns `true` when `prefix` is a strict ancestor of `path` in segment space:
+ * every segment of `prefix` matches the corresponding segment of `path`, and
+ * `path` has at least one additional segment.
+ *
+ * @type {(prefix: readonly string[], path: readonly string[]) => boolean}
+ */
+export const isProperPrefix = (prefix, path) =>
+    prefix.length < path.length && prefix.every((seg, i) => seg === path[i])