functionalscript 0.45.0 → 0.46.1

package/fjs/effects/node/virtual/module.f.mjs

@@ -4,18 +4,20 @@
  * @module
  *
  * @import { Vec } from '../../../types/bit_vec/types.ts'
- * @import { MemOperationMap, RunInstance } from '../../mock/types.ts'
- * @import { Key } from '../../memory/types.ts'
- * @import { Dirent, FileStat, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts'
+ * @import { PartialMemOperationMap, RunInstance } from '../../mock/types.ts'
+ * @import { Dirent, FileStat, IoError, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts'
+ * @import { Result } from '../../../types/result/types.ts'
+ * @import { Error } from '../../../types/result/types.ts'
  * @import { Dir, State, _Entity } from './types.ts'
  */
 
-import { todo } from '../../../asserts/module.f.mjs'
+import { assert, todo } from '../../../asserts/module.f.mjs'
 import { isProperPrefix, join, parse } from '../../../path/module.f.mjs'
 import { utf8ToString } from '../../../text/module.f.mjs'
 import { empty, length, maxLengthBytes, msb, vec } from '../../../types/bit_vec/module.f.mjs'
 import { error, ok } from '../../../types/result/module.f.mjs'
-import { run } from '../../mock/module.f.mjs'
+import { ioError, nodeCommands } from '../module.f.mjs'
+import { partialRun } from '../../mock/module.f.mjs'
 import { asBase, asNominal } from '../../memory/module.f.mjs'
 
 /** @type {State} */
@@ -44,10 +46,13 @@ const operation = op => {
         }
         const [first, ...rest] = path
         const subDir = dir[first]
-        if (typeof subDir !== 'object' || Array.isArray(subDir)) {
+        // `instanceof Array`, not `Array.isArray`: the latter narrows to `any[]`,
+        // which `readonly Vec[]` is not assignable to, so its negative branch never
+        // removes a `readonly` array from `_Entity`. Only `instanceof` narrows here.
+        if (typeof subDir !== 'object' || subDir instanceof Array) {
             return op(dir, path)
         }
-        const [newSubDir, r] = f(/** @type {Dir} */ (subDir), rest)
+        const [newSubDir, r] = f(subDir, rest)
         return [{ ...dir, [first]: newSubDir }, r]
     }
     return path => state => {
@@ -65,12 +70,22 @@ const readOperation = op => operation((dir, path) => [dir, op(dir, path)])
 
 const okVoid = ok(undefined)
 
+/**
+ * A virtual host failure. The virtual runner reports the same normalized
+ * {@link IoError} the Node runner does, so a program cannot tell the two apart
+ * by the shape of what it catches — which is what makes a proof against the
+ * virtual filesystem evidence about the real one.
+ *
+ * @type {(message: string) => Error<IoError>}
+ */
+const fail = message => error(ioError({ message }))
+
 /** @type {(recursive: boolean) => (dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const mkdirOp = recursive => (dir, path) => {
     let d = {}
     let i = path.length
     if (i > 1 && !recursive) {
-        return [dir, error('non-recursive')]
+        return [dir, fail('non-recursive')]
     }
     while (i > 0) {
         i -= 1
@@ -84,7 +99,7 @@ const mkdirOp = recursive => (dir, path) => {
 const mkdir = recursive => operation(mkdirOp(recursive))
 
 /** Absent-path error mirroring Node's `ENOENT`, so `isNotFound` recognizes it. */
-const enoent = error({ code: 'ENOENT' })
+const enoent = error(ioError({ code: 'ENOENT', message: 'no such file or directory' }))
 
 /** @type {(path: string) => (state: State) => readonly [State, IoResult<Vec>]} */
 const readFile = readOperation((dir, path) => {
@@ -92,15 +107,18 @@ const readFile = readOperation((dir, path) => {
     const file = dir[path[0]]
     if (typeof file === 'function') { throw new Error(`'${path[0]}' is a JsModule; readFile not supported`) }
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${path[0]}' is not a file`) }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    // `operation`'s wrapper descends into every plain-object (`Dir`) entry
+    // before this op ever runs, and the `JsModule` case already threw above,
+    // so `file` here is always a `Vec[]` — never a bare `Dir`.
+    assert(Array.isArray(file), `'${path[0]}' is not a file`)
+    const chunks = file
     const capBits = maxLengthBytes * 8n
     let result = empty
     for (const chunk of chunks) {
         const chunkLen = length(chunk)
         if (chunkLen === 0n) { continue }
         if (length(result) + chunkLen > capBits) {
-            return error(`File size exceeds maximum allowed size of ${maxLengthBytes} bytes`)
+            return fail(`File size exceeds maximum allowed size of ${maxLengthBytes} bytes`)
         }
         result = msb.concat(result)(chunk)
     }
@@ -109,13 +127,13 @@ const readFile = readOperation((dir, path) => {
 
 /** @type {(path: string) => (state: State) => readonly [State, IoResult<Module>]} */
 const import_ = readOperation((dir, path) => {
-    if (path.length !== 1) { return error('no such file') }
+    if (path.length !== 1) { return fail('no such file') }
     const entry = dir[path[0]]
-    if (typeof entry !== 'function') { return error(`'${path[0]}' is not a JsModule`) }
+    if (typeof entry !== 'function') { return fail(`'${path[0]}' is not a JsModule`) }
     return ok(entry())
 })
 
-const writeFileError = error('invalid file')
+const writeFileError = fail('invalid file')
 
 /** @type {(payload: Vec) => (dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const writeFileOp = payload => (dir, path) => {
@@ -130,7 +148,7 @@ const writeFileOp = payload => (dir, path) => {
 /** @type {(payload: Vec) => (path: string) => (state: State) => readonly [State, IoResult<void>]} */
 const writeFile = payload => operation(writeFileOp(payload))
 
-const invalidPath = error('invalid path')
+const invalidPath = fail('invalid path')
 
 const { entries } = Object
 
@@ -143,10 +161,10 @@ const readdir = (base, recursive) => readOperation((dir, path) => {
         let result = []
         for (const [name, content] of entries(d)) {
             if (content === undefined) { continue }
-            const isFile = Array.isArray(content) || typeof content !== 'object'
+            const isFile = content instanceof Array || typeof content !== 'object'
             result = [...result, { name, parentPath, isFile }]
             if (!isFile && recursive) {
-                result = [...result, ...f(join(parentPath, name), /** @type {Dir} */ (content))]
+                result = [...result, ...f(join(parentPath, name), content)]
             }
         }
         return result
@@ -163,11 +181,15 @@ const access = readOperation((dir, path) => {
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const rmOp = (dir, path) => {
-    if (path.length !== 1) { return [dir, error('invalid path')] }
+    if (path.length !== 1) { return [dir, fail('invalid path')] }
     const [name] = path
     const entry = dir[name]
-    if (entry === undefined) { return [dir, error('no such file')] }
-    if (!Array.isArray(entry) && typeof entry === 'object') { return [dir, error('is a directory')] }
+    if (entry === undefined) { return [dir, fail('no such file')] }
+    // No "is a directory" guard here: `operation`'s wrapper descends into
+    // every plain-object (`Dir`) entry before this op ever runs, so `entry`
+    // is always a `Vec[]` or a `JsModule` — never a bare `Dir` — and rm can
+    // always proceed. (`rm` on a genuinely non-empty directory instead hits
+    // `path.length !== 1` above, once the wrapper has descended into it.)
     const { [name]: _, ...rest } = dir
     return [rest, okVoid]
 }
@@ -177,7 +199,7 @@ const rm = operation(rmOp)
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<_Entity>]} */
 const extractEntity = (dir, path) => {
-    if (path.length === 0) { return [dir, error('cannot extract root')] }
+    if (path.length === 0) { return [dir, fail('cannot extract root')] }
     if (path.length === 1) {
         const [name] = path
         const entry = dir[name]
@@ -187,15 +209,21 @@ const extractEntity = (dir, path) => {
     }
     const [first, ...rest] = path
     const sub = dir[first]
-    if (sub === undefined || Array.isArray(sub) || typeof sub === 'function') { return [dir, enoent] }
-    const [newSub, result] = extractEntity(/** @type {Dir} */ (sub), rest)
+    if (sub === undefined || sub instanceof Array || typeof sub === 'function') { return [dir, enoent] }
+    const [newSub, result] = extractEntity(sub, rest)
     if (result[0] === 'error') { return [dir, result] }
     return [{ ...dir, [first]: newSub }, result]
 }
 
 /** @type {(dir: Dir, path: readonly string[], entity: _Entity) => readonly [Dir, IoResult<void>]} */
 const insertEntityAt = (dir, path, entity) => {
-    if (path.length === 0) { return [dir, error('cannot insert at root')] }
+    // `insertEntityAt`'s only external caller, `rename`, always rejects an
+    // empty `dst` earlier — `isProperPrefix([], srcParsed)` is true whenever
+    // `srcParsed` is non-empty, so renaming onto root is already caught as
+    // "onto an ancestor" before this function runs. The recursive self-calls
+    // below never pass an empty path either (they only recurse when
+    // `path.length > 1`, with a non-empty remainder).
+    assert(path.length > 0, 'cannot insert at root')
     if (path.length === 1) {
         const [name] = path
         const existing = dir[name]
@@ -203,16 +231,16 @@ const insertEntityAt = (dir, path, entity) => {
             const entityIsDir = !Array.isArray(entity) && typeof entity === 'object'
             const existingIsDir = !Array.isArray(existing) && typeof existing === 'object'
             if (entityIsDir && !existingIsDir) {
-                return [dir, error(`cannot overwrite file '${name}' with a directory`)]
+                return [dir, fail(`cannot overwrite file '${name}' with a directory`)]
             }
             if (!entityIsDir && existingIsDir) {
-                return [dir, error(`'${name}' is a directory`)]
+                return [dir, fail(`'${name}' is a directory`)]
             }
             if (entityIsDir && existingIsDir) {
-                const existingDir = /** @type {Dir} */ (existing)
+                const existingDir = existing
                 const hasContent = Object.values(existingDir).some(v => v !== undefined)
                 if (hasContent) {
-                    return [dir, error(`cannot overwrite non-empty directory '${name}'`)]
+                    return [dir, fail(`cannot overwrite non-empty directory '${name}'`)]
                 }
             }
         }
@@ -221,8 +249,8 @@ const insertEntityAt = (dir, path, entity) => {
     const [first, ...rest] = path
     const sub = dir[first]
     if (sub === undefined) { return [dir, enoent] }
-    if (Array.isArray(sub) || typeof sub === 'function') { return [dir, error('not a directory')] }
-    const [newSub, result] = insertEntityAt(/** @type {Dir} */ (sub), rest, entity)
+    if (sub instanceof Array || typeof sub === 'function') { return [dir, fail('not a directory')] }
+    const [newSub, result] = insertEntityAt(sub, rest, entity)
     if (result[0] === 'error') { return [dir, result] }
     return [{ ...dir, [first]: newSub }, result]
 }
@@ -237,7 +265,7 @@ const rename = (src, dst) => state => {
     // now that source exists, reject if dst is strictly inside src's subtree (rename into own descendant)
     // or if src is strictly inside dst's subtree (rename onto own ancestor)
     if (isProperPrefix(srcParsed, dstParsed) || isProperPrefix(dstParsed, srcParsed)) {
-        return [state, error('cannot rename a directory into its own subtree or onto an ancestor')]
+        return [state, fail('cannot rename a directory into its own subtree or onto an ancestor')]
     }
     const [dstRoot, dstResult] = insertEntityAt(srcRoot, dstParsed, srcResult[1])
     if (dstResult[0] === 'error') { return [state, dstResult] }
@@ -250,13 +278,16 @@ const readBytesOp = (path, offset, size) => readOperation((dir, p) => {
     const file = dir[p[0]]
     if (typeof file === 'function') { throw new Error(`'${p[0]}' is a JsModule; readBytes not supported`) }
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${p[0]}' is not a file`) }
-    if (!Number.isInteger(offset)) { return error(`Offset ${offset} is not an integer`) }
-    if (!Number.isInteger(size)) { return error(`Chunk size ${size} is not an integer`) }
-    if (offset < 0) { return error(`Offset ${offset} is negative`) }
-    if (size < 0) { return error(`Chunk size ${size} is negative`) }
-    if (BigInt(size) > maxLengthBytes) { return error(`Chunk size ${size} exceeds maximum allowed size of ${maxLengthBytes} bytes`) }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    // `operation`'s wrapper descends into every plain-object (`Dir`) entry
+    // before this op ever runs, and the `JsModule` case already threw above,
+    // so `file` here is always a `Vec[]` — never a bare `Dir`.
+    assert(Array.isArray(file), `'${p[0]}' is not a file`)
+    if (!Number.isInteger(offset)) { return fail(`Offset ${offset} is not an integer`) }
+    if (!Number.isInteger(size)) { return fail(`Chunk size ${size} is not an integer`) }
+    if (offset < 0) { return fail(`Offset ${offset} is negative`) }
+    if (size < 0) { return fail(`Chunk size ${size} is negative`) }
+    if (BigInt(size) > maxLengthBytes) { return fail(`Chunk size ${size} exceeds maximum allowed size of ${maxLengthBytes} bytes`) }
+    const chunks = file
     let toSkip = BigInt(offset) * 8n
     let toRead = BigInt(size) * 8n
     let result = empty
@@ -283,7 +314,7 @@ const fileSizeBytes = chunks =>
     chunks.reduce((acc, c) => acc + Number(length(c) / 8n), 0)
 
 /** Absent-path error for an already-existing exclusive create, mirroring `EEXIST`. */
-const eexist = error({ code: 'EEXIST' })
+const eexist = error(ioError({ code: 'EEXIST', message: 'file already exists' }))
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const createExclusiveOp = (dir, path) => {
@@ -308,11 +339,11 @@ const writeBytesRawOp = (offset, data) => (dir, p) => {
     const [name] = p
     const file = dir[name]
     if (file === undefined) { return [dir, enoent] }              // writeBytes never creates
-    if (!Array.isArray(file)) { return [dir, error(`'${name}' is not a file`)] }
-    if (!Number.isInteger(offset) || offset < 0) { return [dir, error(`Offset ${offset} is invalid`)] }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    if (!Array.isArray(file)) { return [dir, fail(`'${name}' is not a file`)] }
+    if (!Number.isInteger(offset) || offset < 0) { return [dir, fail(`Offset ${offset} is invalid`)] }
+    const chunks = file
     if (offset !== fileSizeBytes(chunks)) {
-        return [dir, error(`writeBytes offset ${offset} must equal the file size (append-only)`)]
+        return [dir, fail(`writeBytes offset ${offset} must equal the file size (append-only)`)]
     }
     return [{ ...dir, [name]: [...chunks, data] }, okVoid]
 }
@@ -325,43 +356,46 @@ const statOp = readOperation((dir, path) => {
     if (path.length !== 1) { return enoent }
     const file = dir[path[0]]
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${path[0]}' is not a file`) }
-    return ok({ size: fileSizeBytes(/** @type {readonly Vec[]} */ (file)) })
+    if (!Array.isArray(file)) { return fail(`'${path[0]}' is not a file`) }
+    return ok({ size: fileSizeBytes(file) })
 })
 
-/** @type {MemOperationMap<NodeOp, State>} */
+/** @type {PartialMemOperationMap<NodeOp, State>} */
 const map = {
     all: (...a) => state => {
-        /** @type {readonly unknown[]} */
+        // Each entry is the effect's whole `Result`: `all`'s own envelope says
+        // only whether the runner could dispatch it, so the inner answers pass
+        // through untouched for `allOk` to collapse.
+        /** @type {readonly Result<unknown, unknown>[]} */
         let e = []
         for (const i of a) {
             const [ns, ei] = virtual(state)(i)
             state = ns
             e = [...e, ei]
         }
-        return [state, e]
+        return [state, ok(e)]
     },
     memCreate: value => state => {
         const id = `mem${state.memoryNext}`
-        const key = /** @type {Key<unknown>} */ (asNominal(id))
+        const key = asNominal(id)
         return [{
             ...state,
             memoryNext: state.memoryNext + 1,
             memoryValues: { ...state.memoryValues, [id]: value },
-        }, key]
+        }, ok(key)]
     },
     memRead: key => state =>
-        [state, state.memoryValues[asBase(key)]],
+        [state, ok(state.memoryValues[asBase(key)])],
     memWrite: (key, value) => state => {
         const id = asBase(key)
         return [{
             ...state,
             memoryValues: { ...state.memoryValues, [id]: value },
-        }, undefined]
+        }, okVoid]
     },
     fetch: url => state => {
         const result = state.internet[url]
-        return result === undefined ? [state, error('not found')] : [state, ok(result)]
+        return result === undefined ? [state, fail('not found')] : [state, ok(result)]
     },
     mkdir: (path, p) => mkdir(p !== undefined)(path),
     readFile,
@@ -375,12 +409,8 @@ const map = {
     createExclusive,
     writeBytes: writeBytesOp,
     stat: statOp,
-    randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, state.randomNext],
-    exec: todo,
-    createServer: todo,
-    listen: todo,
-    forever: todo,
-    now: () => state => [state, state.epochNs],
+    randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, ok(state.randomNext)],
+    now: () => state => [state, ok(state.epochNs)],
     // Virtual sandbox is a pass-through: the fixture's test function is
     // expected to return a `SandboxResult` directly (encoding pass/fail and a
     // chosen duration), so the handler invokes it without try/catch or clock
@@ -388,23 +418,35 @@ const map = {
     // result instead of the runner measuring real execution. A genuine
     // exception in a fixture propagates loudly as a bug in the fixture.
     // See: issues/156-tf-virtual-tests.md
-    sandbox: f => state => [state, /** @type {SandboxResult<unknown>} */ (f())],
-    await: p => state => [state, [p]],
-    test: todo,
+    sandbox: f => state => [state, ok(/** @type {SandboxResult<unknown>} */ (f()))],
+    await: p => state => [state, ok([p])],
     write: (stream, data) => state => {
         const s = utf8ToString(data)
-        return [{ ...state, [stream]: `${state[stream]}${s}` }, undefined]
+        return [{ ...state, [stream]: `${state[stream]}${s}` }, okVoid]
     },
     read: () => state => {
         const [first, ...rest] = state.stdin
         return state.stdin.length === 0
-            ? [state, null]
-            : [{ ...state, stdin: rest }, first]
+            ? [state, ok(null)]
+            : [{ ...state, stdin: rest }, ok(first)]
     },
 }
 
-/** @type {RunInstance<NodeOp, State>} */
-export const virtual = run(map)
+/**
+ * The virtual runner.
+ *
+ * **It implements part of `NodeOp`, and says so.** `exec`, `createServer`,
+ * `listen`, `forever` and `test` have no meaning against an in-memory
+ * filesystem, and they used to be present as `todo` handlers — entries that
+ * existed only to satisfy a total operation map and threw when reached. They
+ * are simply absent now, so a program that asks for one gets
+ * `error(notImplemented)` back through its own continuation and decides what an
+ * incompatible runner means for it, which is what `NotImplemented` was
+ * introduced for. A command that is not a `NodeOp` at all still panics.
+ *
+ * @type {RunInstance<NodeOp, State>}
+ */
+export const virtual = partialRun(nodeCommands)(map)
 
 const testContext = { test: todo }
 

package/fjs/effects/node/virtual/proof.f.d.mts

@@ -1,11 +1,21 @@
 /**
- * @import { Dir, JsModule } from './types.ts'
+ * @import { Dir } from './types.ts'
+ * @import { NodeOp } from '../types.ts'
+ * @import { Effect } from '../../types.ts'
+ * @import { IoChannel } from '../types.ts'
  */
 export declare const proof: {
+    unimplemented: {
+        declaredButAbsent: () => void;
+        programChoosesAFallback: () => void;
+        throw: {
+            undeclaredCommand: () => void;
+        };
+    };
     rm: {
         success: () => void;
         notFound: () => void;
-        isDirectory: () => void;
+        onDirectory: () => void;
     };
     writeFileOnDirectory: () => void;
     writeFileOverJsModule: () => void;
@@ -18,7 +28,23 @@ export declare const proof: {
     importNonModule: () => void;
     throw: {
         readFileOnJsModule: () => void;
+        readBytesOnJsModule: () => void;
     };
+    readFileSkipsEmptyChunk: () => void;
+    readdirSkipsUndefinedEntry: () => void;
+    renameEmptySrc: () => void;
+    renameSrcThroughFile: () => void;
+    renameSrcThreeLevelsMissing: () => void;
+    renameDstMissingIntermediate: () => void;
+    renameDstThroughFile: () => void;
+    renameDstNestedError: () => void;
+    createExclusiveNestedMissing: () => void;
+    writeBytesNestedMissing: () => void;
+    writeBytesMissingFile: () => void;
+    writeBytesOnJsModule: () => void;
+    writeBytesNegativeOffset: () => void;
+    statNestedMissing: () => void;
+    statMissingFile: () => void;
     renameSamePath: () => void;
     renameIntoOwnSubtree: () => void;
     renameOntoOwnAncestor: () => void;