@ttsc/wasm 0.30.3 → 0.31.0

package/lib/src/createMemFS.js

@@ -61,12 +61,110 @@ function normalize(p) {
  * descendants. An operation that cannot satisfy that throws (`writeFile`,
  * `mkdirp`) or reports a POSIX error through its callback, having changed no
  * node, byte, or descriptor.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The owned Node-shaped fs bridge uses maps for virtual node/descriptor
+ *   identity and preserves opened nodes independently from paths. The Go js/wasm
+ *   callback interface is the authority; unsupported link and metadata mutation
+ *   capabilities are explicit in IWasmExecFS.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One closure owns the tree, indexes and descriptor identities. Shared helpers
+ *   centralize path validation, insertion/removal and byte mutation; separate
+ *   stream captures and pipe queues reflect non-seekable lifetimes rather than
+ *   adding filesystem nodes that would blur their operation contracts.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Virtual flag/errno values are bridge constants, not native-host guesses.
+ *   The implementation owns its maps rather than patching foreign filesystem
+ *   methods. Directory indexes, geometric file growth and linked pipe queues
+ *   correct repeated global scans, full-buffer copies and queue shifts at their
+ *   owners, without size exceptions or benchmark-specific paths.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain installation, copying and tree ownership; helper
+ *   and interface comments state cost and unsupported capabilities. This follows
+ *   the documentation skill's paragraph, units and rationale guidance.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Directory lookup visits D direct entries and sorts them in O(D log D),
+ *   emptiness uses the indexed child count, and rename visits only S subtree
+ *   nodes plus F open descriptors. Growing file writes amortize copying through
+ *   geometric capacity; pipe enqueue/dequeue change linked endpoints in O(1).
+ *   Path normalization costs O(P) path characters; ancestor validation builds
+ *   d prefixes with total length K, costing O(K + d) time and temporary space
+ *   under expected constant-time map access after hashing each prefix. Output fragments
+ *   append without flattening prior text; reading a dirty B-byte capture costs
+ *   O(B), while an unchanged capture read reuses its materialized string.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Child membership is maintained once by node insertion/deletion rather than
+ *   reconstructed for every listing. Text decoding is cached on node identity
+ *   and invalidated by every content mutation. Open descriptors share their
+ *   actual inode; public byte reads still copy to preserve caller isolation.
+ *   Each output stream keeps its own incremental UTF-8 decoder, so a split
+ *   character is decoded once and capture reads reuse the materialized string
+ *   until another fragment arrives.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Each host owns its tree, indexes, captures and descriptors. Unlink/rmdir
+ *   remove tree entries, close releases descriptors, and consumed pipe entries
+ *   are detached. File write capacity stays at most twice logical length; truncate
+ *   and replacement release spare storage. Total input and captured output have
+ *   no fixed bound, so the caller owns deletion, resetStdio and host lifetime.
  */
 function createMemFS() {
     const nodes = new Map();
+    const children = new Map([["/", new Set()]]);
     nodes.set("/", { kind: "dir", data: new Uint8Array(), mtimeMs: Date.now() });
-    const stdout = { buffer: "" };
-    const stderr = { buffer: "" };
+    /** Keep parent membership and directory indexes with the owned node tree. */
+    function setNode(p, node) {
+        nodes.set(p, node);
+        children.get(parentDir(p)).add(p);
+        if (node.kind === "dir" && !children.has(p))
+            children.set(p, new Set());
+    }
+    /** Remove a validated node and its index; open descriptors retain the node. */
+    function deleteNode(p) {
+        nodes.delete(p);
+        children.get(parentDir(p)).delete(p);
+        children.delete(p);
+    }
+    /** Decode stream fragments incrementally and materialize capture text on read. */
+    function createCapture() {
+        let streamDecoder = new TextDecoder();
+        let chunks = [];
+        let cached = "";
+        let dirty = false;
+        const append = (text) => {
+            if (text.length > 0) {
+                chunks.push(text);
+                cached = "";
+                dirty = true;
+            }
+            return text;
+        };
+        return {
+            output: {
+                get buffer() {
+                    if (dirty) {
+                        cached = chunks.join("");
+                        chunks = cached.length > 0 ? [cached] : [];
+                        dirty = false;
+                    }
+                    return cached;
+                },
+                set buffer(value) {
+                    streamDecoder = new TextDecoder();
+                    chunks = value.length > 0 ? [value] : [];
+                    cached = value;
+                    dirty = false;
+                },
+            },
+            write(bytes) {
+                return append(streamDecoder.decode(bytes, { stream: true }));
+            },
+            flush() {
+                append(streamDecoder.decode());
+            },
+        };
+    }
+    const stdout = createCapture();
+    const stderr = createCapture();
     const fdTable = new Map();
     let nextFd = 100;
     // Reserve 1/2 for stdout/stderr writeSync routing.
@@ -86,6 +184,23 @@ function createMemFS() {
         append: true,
         isStderr: true,
     });
+    function enqueue(queue, value) {
+        const entry = { value };
+        if (queue.tail)
+            queue.tail.next = entry;
+        else
+            queue.head = entry;
+        queue.tail = entry;
+    }
+    function dequeue(queue) {
+        const entry = queue.head;
+        if (!entry)
+            return undefined;
+        queue.head = entry.next;
+        if (!queue.head)
+            queue.tail = undefined;
+        return entry.value;
+    }
     const pipes = new Map();
     /**
      * Drain buffered pipe data into `buffer[offset..offset+length]`. Returns
@@ -93,15 +208,15 @@ function createMemFS() {
      */
     function drainPipeInto(state, buffer, offset, length) {
         let written = 0;
-        while (state.buffers.length > 0 && written < length) {
-            const chunk = state.buffers[0];
+        while (state.buffers.head && written < length) {
+            const chunk = state.buffers.head.value;
             const copyLen = Math.min(chunk.byteLength, length - written);
             buffer.set(chunk.subarray(0, copyLen), offset + written);
             written += copyLen;
             if (copyLen >= chunk.byteLength)
-                state.buffers.shift();
+                dequeue(state.buffers);
             else
-                state.buffers[0] = chunk.subarray(copyLen);
+                state.buffers.head.value = chunk.subarray(copyLen);
         }
         return written;
     }
@@ -110,9 +225,9 @@ function createMemFS() {
      * signal.
      */
     function flushPipeReaders(state) {
-        while (state.pendingReaders.length > 0 &&
-            (state.buffers.length > 0 || state.writeClosed)) {
-            const reader = state.pendingReaders.shift();
+        while (state.pendingReaders.head &&
+            (state.buffers.head || state.writeClosed)) {
+            const reader = dequeue(state.pendingReaders);
             const n = drainPipeInto(state, reader.buffer, reader.offset, reader.length);
             // Even at EOF (writeClosed && empty buffers) we satisfy with n=0 which
             // signals EOF to the Go-side caller.
@@ -153,7 +268,7 @@ function createMemFS() {
     /** Materialize the directories `missingDirs` reported. */
     function createDirs(paths) {
         for (const path of paths)
-            nodes.set(path, {
+            setNode(path, {
                 kind: "dir",
                 data: new Uint8Array(),
                 mtimeMs: Date.now(),
@@ -181,22 +296,68 @@ function createMemFS() {
     }
     /** True when `dir` has at least one descendant node in the tree. */
     function hasChildren(dir) {
-        const prefix = dir === "/" ? "/" : dir + "/";
-        for (const key of nodes.keys()) {
-            if (key !== dir && key.startsWith(prefix))
-                return true;
+        return (children.get(dir)?.size ?? 0) > 0;
+    }
+    /**
+     * Allocate zero-filled storage for a file of `length` bytes.
+     *
+     * The engine refuses a length it cannot allocate with a `RangeError`, which
+     * carries no POSIX code and would escape a callback that promises one. That
+     * refusal is the virtual filesystem's maximum file size, so it is reported as
+     * `EFBIG`; the caller has not yet changed any node when this throws.
+     */
+    function allocateFileData(length, syscall, path) {
+        try {
+            return new Uint8Array(length);
+        }
+        catch (error) {
+            if (error instanceof RangeError)
+                throw new MemFSError_1.MemFSError("EFBIG", syscall, path);
+            throw error;
         }
-        return false;
     }
     /**
      * Grow or shrink a file's byte buffer to exactly `length`, zero-filling any
      * extension. Callers validate `length >= 0` first.
      */
-    function resizeFileData(data, length) {
-        const next = new Uint8Array(length);
+    function resizeFileData(data, length, syscall, path) {
+        const next = allocateFileData(length, syscall, path);
         next.set(data.subarray(0, Math.min(length, data.byteLength)));
         return next;
     }
+    /** Grow writes geometrically; the public view still exposes only file bytes. */
+    function growFileData(data, length, syscall, path) {
+        const capacity = data.buffer.byteLength - data.byteOffset;
+        if (length <= capacity) {
+            const next = new Uint8Array(data.buffer, data.byteOffset, length);
+            next.fill(0, data.byteLength);
+            return next;
+        }
+        // Spare capacity is only an optimization: when the engine refuses the
+        // doubled size, the exact length still satisfies the write.
+        let next;
+        if (data.byteLength * 2 > length) {
+            try {
+                next = allocateFileData(data.byteLength * 2, syscall, path);
+            }
+            catch {
+                next = allocateFileData(length, syscall, path);
+            }
+        }
+        else
+            next = allocateFileData(length, syscall, path);
+        next.set(data);
+        return next.subarray(0, length);
+    }
+    /** Reject invalid byte slices before a write or queued read can mutate state. */
+    function validSlice(buffer, offset, length) {
+        return (Number.isSafeInteger(offset) &&
+            Number.isSafeInteger(length) &&
+            offset >= 0 &&
+            length >= 0 &&
+            offset <= buffer.byteLength &&
+            length <= buffer.byteLength - offset);
+    }
     /**
      * Write `view` through descriptor `entry` and return the bytes stored.
      *
@@ -220,14 +381,17 @@ function createMemFS() {
         const start = entry.append
             ? node.data.byteLength
             : (position ?? entry.position);
-        if (!Number.isInteger(start) || start < 0)
+        if (!Number.isSafeInteger(start) || start < 0)
             throw new MemFSError_1.MemFSError("EINVAL", syscall, entry.path);
         if (view.byteLength === 0)
             return 0;
         const end = start + view.byteLength;
+        if (!Number.isSafeInteger(end))
+            throw new MemFSError_1.MemFSError("EINVAL", syscall, entry.path);
         if (end > node.data.byteLength)
-            node.data = resizeFileData(node.data, end);
+            node.data = growFileData(node.data, end, syscall, entry.path);
         node.data.set(view, start);
+        node.text = undefined;
         node.mtimeMs = Date.now();
         if (position === null || entry.append)
             entry.position = end;
@@ -242,21 +406,23 @@ function createMemFS() {
     function moveSubtree(src, dest) {
         const srcPrefix = src + "/";
         const moves = [];
-        for (const [key, node] of nodes) {
-            if (key === src)
-                moves.push([dest, node]);
-            else if (key.startsWith(srcPrefix))
-                moves.push([dest + "/" + key.slice(srcPrefix.length), node]);
+        const pending = [src];
+        while (pending.length > 0) {
+            const key = pending.pop();
+            const target = key === src ? dest : dest + key.slice(src.length);
+            moves.push([key, target, nodes.get(key)]);
+            for (const child of children.get(key) ?? [])
+                pending.push(child);
         }
         // Delete the whole source subtree first so a nested overwrite cannot leave
         // a stale descendant behind, then reinsert at the destination prefix. Any
         // pre-existing `dest` node is replaced by the reinsert.
-        for (const key of [...nodes.keys()]) {
-            if (key === src || key.startsWith(srcPrefix))
-                nodes.delete(key);
-        }
-        for (const [key, node] of moves)
-            nodes.set(key, node);
+        for (let i = moves.length - 1; i >= 0; --i)
+            deleteNode(moves[i][0]);
+        if (nodes.has(dest))
+            deleteNode(dest);
+        for (const [, key, node] of moves)
+            setNode(key, node);
         for (const entry of fdTable.values()) {
             if (entry.path === src)
                 entry.path = dest;
@@ -281,10 +447,11 @@ function createMemFS() {
         // file observe the replacement instead of a detached predecessor.
         if (existing) {
             existing.data = bytes;
+            existing.text = undefined;
             existing.mtimeMs = Date.now();
         }
         else
-            nodes.set(norm, { kind: "file", data: bytes, mtimeMs: Date.now() });
+            setNode(norm, { kind: "file", data: bytes, mtimeMs: Date.now() });
     }
     function readFile(p) {
         const node = nodes.get(normalize(p));
@@ -293,8 +460,10 @@ function createMemFS() {
         return new Uint8Array(node.data);
     }
     function readFileText(p) {
-        const bytes = readFile(p);
-        return bytes === null ? null : decoder.decode(bytes);
+        const node = nodes.get(normalize(p));
+        if (!node || node.kind !== "file")
+            return null;
+        return (node.text ??= decoder.decode(node.data));
     }
     function exists(p) {
         return nodes.has(normalize(p));
@@ -329,10 +498,10 @@ function createMemFS() {
         };
     }
     /**
-     * Return immediate children of directory `p`, sorted alphabetically.
+     * Return immediate children of directory `p`, sorted by UTF-16 code unit.
      *
-     * Uses a linear scan over the node map and a `Set` to deduplicate nested
-     * paths into direct-child names — O(n) in the number of total nodes.
+     * The maintained child index limits work to this directory's entries. Sorting
+     * provides deterministic output without scanning unrelated project files.
      */
     function readdirSync(p) {
         const norm = normalize(p);
@@ -341,16 +510,9 @@ function createMemFS() {
             throw new MemFSError_1.MemFSError("ENOENT", "readdir", norm);
         if (node.kind !== "dir")
             throw new MemFSError_1.MemFSError("ENOTDIR", "readdir", norm);
-        const prefix = norm === "/" ? "/" : norm + "/";
-        const direct = new Set();
-        for (const key of nodes.keys()) {
-            if (!key.startsWith(prefix) || key === norm)
-                continue;
-            const rest = key.slice(prefix.length);
-            const cut = rest.indexOf("/");
-            direct.add(cut === -1 ? rest : rest.slice(0, cut));
-        }
-        return [...direct].sort();
+        return [...children.get(norm)]
+            .map((child) => child.slice(norm === "/" ? 1 : norm.length + 1))
+            .sort();
     }
     const fs = {
         constants: {
@@ -364,12 +526,11 @@ function createMemFS() {
         },
         writeSync(fd, buf) {
             if (fd === 1) {
-                stdout.buffer += decoder.decode(buf);
+                stdout.write(buf);
                 return buf.length;
             }
             if (fd === 2) {
-                const text = decoder.decode(buf);
-                stderr.buffer += text;
+                const text = stderr.write(buf);
                 // Surface wasm-side stderr to the host console in real-time so plugin
                 // debug prints / Go panics aren't trapped inside the MemFS buffer.
                 // Stripped at end of message for cleaner display.
@@ -396,6 +557,8 @@ function createMemFS() {
         },
         write(fd, buf, offset, length, position, callback) {
             try {
+                if (!validSlice(buf, offset, length))
+                    throw new MemFSError_1.MemFSError("EINVAL", "write");
                 // Pipe write: snapshot the data (caller may reuse `buf`) and queue.
                 // Synchronously wake any blocked reader so the cooperative wasm
                 // scheduler doesn't deadlock waiting for a future fs roundtrip.
@@ -405,10 +568,14 @@ function createMemFS() {
                         callback(new MemFSError_1.MemFSError("EBADF", "write"), 0);
                         return;
                     }
+                    if (pipeState.readClosed) {
+                        callback(new MemFSError_1.MemFSError("EPIPE", "write"), 0);
+                        return;
+                    }
                     if (length > 0) {
                         const copy = new Uint8Array(length);
                         copy.set(buf.subarray(offset, offset + length));
-                        pipeState.buffers.push(copy);
+                        enqueue(pipeState.buffers, copy);
                         flushPipeReaders(pipeState);
                     }
                     callback(null, length);
@@ -463,7 +630,7 @@ function createMemFS() {
                     if (missing.length > 0)
                         throw new MemFSError_1.MemFSError("ENOENT", "open", missing[0]);
                     node = { kind: "file", data: new Uint8Array(), mtimeMs: Date.now() };
-                    nodes.set(norm, node);
+                    setNode(norm, node);
                 }
                 else {
                     if (creating && exclusive)
@@ -480,6 +647,7 @@ function createMemFS() {
                 }
                 if (truncating) {
                     node.data = new Uint8Array();
+                    node.text = undefined;
                     node.mtimeMs = Date.now();
                 }
                 const fd = nextFd++;
@@ -500,11 +668,19 @@ function createMemFS() {
         close(fd, callback) {
             const pipeState = pipes.get(fd);
             if (pipeState) {
+                pipes.delete(fd);
                 if (fd === pipeState.writeFd) {
                     pipeState.writeClosed = true;
                     flushPipeReaders(pipeState);
                 }
-                pipes.delete(fd);
+                else {
+                    pipeState.readClosed = true;
+                    pipeState.buffers = {};
+                    while (pipeState.pendingReaders.head) {
+                        const reader = dequeue(pipeState.pendingReaders);
+                        reader.callback(new MemFSError_1.MemFSError("EBADF", "read"), 0);
+                    }
+                }
                 callback(null);
                 return;
             }
@@ -512,11 +688,19 @@ function createMemFS() {
                 callback(new MemFSError_1.MemFSError("EBADF", "close"));
                 return;
             }
+            if (fd === 1)
+                stdout.flush();
+            if (fd === 2)
+                stderr.flush();
             if (fd > 2)
                 fdTable.delete(fd);
             callback(null);
         },
         read(fd, buffer, offset, length, position, callback) {
+            if (!validSlice(buffer, offset, length)) {
+                callback(new MemFSError_1.MemFSError("EINVAL", "read"), 0);
+                return;
+            }
             // Pipe read: drain queued chunks; block (defer callback) on empty.
             // Empty + writeClosed → return 0 (EOF). Position is ignored for pipes.
             const pipeState = pipes.get(fd);
@@ -525,7 +709,11 @@ function createMemFS() {
                     callback(new MemFSError_1.MemFSError("EBADF", "read"), 0);
                     return;
                 }
-                if (pipeState.buffers.length > 0) {
+                if (length === 0) {
+                    callback(null, 0);
+                    return;
+                }
+                if (pipeState.buffers.head) {
                     const n = drainPipeInto(pipeState, buffer, offset, length);
                     callback(null, n);
                     return;
@@ -534,7 +722,7 @@ function createMemFS() {
                     callback(null, 0);
                     return;
                 }
-                pipeState.pendingReaders.push({ buffer, offset, length, callback });
+                enqueue(pipeState.pendingReaders, { buffer, offset, length, callback });
                 return;
             }
             const entry = fdTable.get(fd);
@@ -554,7 +742,7 @@ function createMemFS() {
                 return;
             }
             const start = position ?? entry.position;
-            if (!Number.isInteger(start) || start < 0) {
+            if (!Number.isSafeInteger(start) || start < 0) {
                 callback(new MemFSError_1.MemFSError("EINVAL", "read", entry.path), 0);
                 return;
             }
@@ -586,7 +774,7 @@ function createMemFS() {
                     throw new MemFSError_1.MemFSError("ENOENT", "mkdir", parentDir(norm));
                 if (parent.kind !== "dir")
                     throw new MemFSError_1.MemFSError("ENOTDIR", "mkdir", parentDir(norm));
-                nodes.set(norm, {
+                setNode(norm, {
                     kind: "dir",
                     data: new Uint8Array(),
                     mtimeMs: Date.now(),
@@ -652,7 +840,7 @@ function createMemFS() {
                 callback(new MemFSError_1.MemFSError("EISDIR", "unlink", norm));
                 return;
             }
-            nodes.delete(norm);
+            deleteNode(norm);
             callback(null);
         },
         rename(from, to, callback) {
@@ -728,7 +916,7 @@ function createMemFS() {
                 callback(new MemFSError_1.MemFSError("ENOTEMPTY", "rmdir", norm));
                 return;
             }
-            nodes.delete(norm);
+            deleteNode(norm);
             callback(null);
         },
         chmod(_p, _mode, callback) {
@@ -773,7 +961,14 @@ function createMemFS() {
                 callback(new MemFSError_1.MemFSError("EINVAL", "truncate", norm));
                 return;
             }
-            node.data = resizeFileData(node.data, length);
+            try {
+                node.data = resizeFileData(node.data, length, "truncate", norm);
+            }
+            catch (err) {
+                callback(err);
+                return;
+            }
+            node.text = undefined;
             node.mtimeMs = Date.now();
             callback(null);
         },
@@ -805,7 +1000,14 @@ function createMemFS() {
                 callback(new MemFSError_1.MemFSError("EINVAL", "ftruncate", entry.path));
                 return;
             }
-            node.data = resizeFileData(node.data, length);
+            try {
+                node.data = resizeFileData(node.data, length, "ftruncate", entry.path);
+            }
+            catch (err) {
+                callback(err);
+                return;
+            }
+            node.text = undefined;
             node.mtimeMs = Date.now();
             callback(null);
         },
@@ -813,11 +1015,12 @@ function createMemFS() {
             const readFd = nextFd++;
             const writeFd = nextFd++;
             const state = {
-                buffers: [],
-                pendingReaders: [],
+                buffers: {},
+                pendingReaders: {},
                 readFd,
                 writeFd,
                 writeClosed: false,
+                readClosed: false,
             };
             pipes.set(readFd, state);
             pipes.set(writeFd, state);
@@ -831,11 +1034,11 @@ function createMemFS() {
         readFileText,
         exists,
         mkdirp,
-        stdout,
-        stderr,
+        stdout: stdout.output,
+        stderr: stderr.output,
         resetStdio() {
-            stdout.buffer = "";
-            stderr.buffer = "";
+            stdout.output.buffer = "";
+            stderr.output.buffer = "";
         },
     };
 }