@ttsc/wasm 0.19.3 → 0.20.0

package/src/createMemFS.ts

@@ -64,6 +64,12 @@ function normalize(p: string): string {
  * `globalThis.fs` before loading `wasm_exec.js`) and convenience helpers
  * (`writeFile`, `readFile`, `mkdirp`, …) for seeding source files and reading
  * compiler output without touching the real filesystem.
+ *
+ * Every successful mutation leaves a valid tree: `/` stays a directory, each
+ * proper ancestor of a node exists and is a directory, and a file has no
+ * 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.
  */
 export function createMemFS(): IMemFSHost {
   const nodes = new Map<string, INode>();
@@ -72,19 +78,53 @@ export function createMemFS(): IMemFSHost {
   const stdout = { buffer: "" };
   const stderr = { buffer: "" };
 
-  const fdTable = new Map<
-    number,
-    { path: string; position: number; isStdout?: boolean; isStderr?: boolean }
-  >();
+  /**
+   * One open descriptor.
+   *
+   * `node` retains the object opened even after its pathname is unlinked or
+   * replaced. `readable`, `writable`, and `append` are the access mode and
+   * `O_APPEND` flag captured at `open`; without them no descriptor mutation can
+   * distinguish an allowed operation from a forbidden one. `position` is the
+   * cursor a `position: null` read or write uses and advances.
+   */
+  interface IDescriptor {
+    path: string;
+    node?: INode;
+    position: number;
+    readable: boolean;
+    writable: boolean;
+    append: boolean;
+    isStdout?: boolean;
+    isStderr?: boolean;
+  }
+  const fdTable = new Map<number, IDescriptor>();
   let nextFd = 100;
   // Reserve 1/2 for stdout/stderr writeSync routing.
-  fdTable.set(1, { path: "/dev/stdout", position: 0, isStdout: true });
-  fdTable.set(2, { path: "/dev/stderr", position: 0, isStderr: true });
+  fdTable.set(1, {
+    path: "/dev/stdout",
+    position: 0,
+    readable: false,
+    writable: true,
+    append: true,
+    isStdout: true,
+  });
+  fdTable.set(2, {
+    path: "/dev/stderr",
+    position: 0,
+    readable: false,
+    writable: true,
+    append: true,
+    isStderr: true,
+  });
 
   // Pipe state. fs.pipe2 mints a pair of fds backed by a shared queue;
   // writes append, reads consume. The state is keyed by fd so a single Map
   // lookup in read/write/close can detect "this is a pipe end" without
   // changing the existing fdTable entries.
+  //
+  // These fds only ever come from a direct JavaScript `fs.pipe2` call. Go's
+  // wasm `os.Pipe` returns ENOSYS without crossing the `globalThis.fs` bridge,
+  // so the Go runtime never reaches this state — see IWasmExecFS.pipe2.
   interface IPipeState {
     buffers: Uint8Array[];
     pendingReaders: Array<{
@@ -143,21 +183,62 @@ export function createMemFS(): IMemFSHost {
     }
   }
 
-  /** Silently create any missing ancestor directories for path `p`. */
-  function ensureParentDirs(p: string): void {
-    const segments = normalize(p).split("/").filter(Boolean);
-    segments.pop();
+  /** Root-to-leaf path of every segment of `norm` (`/a/b` → `["/a", "/a/b"]`). */
+  function pathChain(norm: string): string[] {
+    const chain: string[] = [];
     let cursor = "";
-    for (const seg of segments) {
+    for (const seg of norm.split("/").filter(Boolean)) {
       cursor += "/" + seg;
-      if (!nodes.has(cursor)) {
-        nodes.set(cursor, {
-          kind: "dir",
-          data: new Uint8Array(),
-          mtimeMs: Date.now(),
-        });
-      }
+      chain.push(cursor);
     }
+    return chain;
+  }
+
+  /**
+   * Validate that every path in root-to-leaf `chain` is or can become a
+   * directory, and report the ones that do not exist yet.
+   *
+   * A segment that exists as a file makes everything below it impossible: a
+   * file has no descendants, so creating one there would leave a node map that
+   * is not a tree. Validation is deliberately separate from creation so every
+   * caller can reject before touching anything, and so a rejected operation
+   * never leaves half a directory chain behind.
+   */
+  function missingDirs(chain: string[], syscall: string): string[] {
+    const missing: string[] = [];
+    for (const path of chain) {
+      const existing = nodes.get(path);
+      if (!existing) missing.push(path);
+      else if (existing.kind !== "dir")
+        throw new MemFSError("ENOTDIR", syscall, path);
+    }
+    return missing;
+  }
+
+  /** Materialize the directories `missingDirs` reported. */
+  function createDirs(paths: string[]): void {
+    for (const path of paths)
+      nodes.set(path, {
+        kind: "dir",
+        data: new Uint8Array(),
+        mtimeMs: Date.now(),
+      });
+  }
+
+  /**
+   * Validate that normalized path `norm` may hold a regular file, returning the
+   * node already there when one exists.
+   *
+   * A directory is never silently replaced by a file — including the root,
+   * which is a directory node like any other. POSIX answers `EISDIR`, and
+   * overwriting the node here would strand every descendant in the map behind a
+   * path `readdir` can no longer walk.
+   */
+  function assertFileTarget(norm: string, syscall: string): INode | undefined {
+    const existing = nodes.get(norm);
+    if (existing && existing.kind !== "file")
+      throw new MemFSError("EISDIR", syscall, norm);
+    return existing;
   }
 
   /** Absolute parent directory of a normalized path (`/` for a top-level path). */
@@ -185,6 +266,43 @@ export function createMemFS(): IMemFSHost {
     return next;
   }
 
+  /**
+   * Write `view` through descriptor `entry` and return the bytes stored.
+   *
+   * Three offsets are possible and only one of them is right per call: an
+   * `O_APPEND` descriptor always writes at end-of-file, an explicit `position`
+   * writes exactly there without disturbing the cursor (POSIX `pwrite`), and
+   * `position: null` writes at the cursor and advances it. A write that starts
+   * past end-of-file zero-fills the gap rather than silently relocating.
+   *
+   * A zero-byte write changes nothing at all, so a cursor sitting past
+   * end-of-file cannot extend the file by writing nothing into it.
+   */
+  function writeThroughDescriptor(
+    entry: IDescriptor,
+    view: Uint8Array,
+    position: number | null,
+    syscall: string,
+  ): number {
+    if (!entry.writable) throw new MemFSError("EBADF", syscall, entry.path);
+    const node = entry.node;
+    if (!node) throw new MemFSError("ENOENT", syscall, entry.path);
+    if (node.kind !== "file")
+      throw new MemFSError("EISDIR", syscall, entry.path);
+    const start = entry.append
+      ? node.data.byteLength
+      : (position ?? entry.position);
+    if (!Number.isInteger(start) || start < 0)
+      throw new MemFSError("EINVAL", syscall, entry.path);
+    if (view.byteLength === 0) return 0;
+    const end = start + view.byteLength;
+    if (end > node.data.byteLength) node.data = resizeFileData(node.data, end);
+    node.data.set(view, start);
+    node.mtimeMs = Date.now();
+    if (position === null || entry.append) entry.position = end;
+    return view.byteLength;
+  }
+
   /**
    * Move the entire subtree rooted at `src` to `dest`, overwriting any existing
    * `dest` node. Every descendant key is re-parented so no old-prefix node is
@@ -214,29 +332,26 @@ export function createMemFS(): IMemFSHost {
   }
 
   function mkdirp(p: string): void {
-    const segments = normalize(p).split("/").filter(Boolean);
-    let cursor = "";
-    for (const seg of segments) {
-      cursor += "/" + seg;
-      const existing = nodes.get(cursor);
-      if (!existing) {
-        nodes.set(cursor, {
-          kind: "dir",
-          data: new Uint8Array(),
-          mtimeMs: Date.now(),
-        });
-      } else if (existing.kind !== "dir") {
-        throw new MemFSError("ENOTDIR", "mkdir", cursor);
-      }
-    }
+    // Validate the whole chain before creating any of it: a rejected mkdirp
+    // must not leave the prefix it had already walked past behind.
+    createDirs(missingDirs(pathChain(normalize(p)), "mkdir"));
   }
 
   function writeFile(p: string, data: string | Uint8Array): void {
     const norm = normalize(p);
-    ensureParentDirs(norm);
+    // Resolve left to right the way POSIX does: an impossible ancestor is
+    // reported before the target, and both are checked before any mutation.
+    const missing = missingDirs(pathChain(norm).slice(0, -1), "open");
+    const existing = assertFileTarget(norm, "open");
     const bytes =
       typeof data === "string" ? encoder.encode(data) : new Uint8Array(data);
-    nodes.set(norm, { kind: "file", data: bytes, mtimeMs: Date.now() });
+    createDirs(missing);
+    // Overwriting keeps the same node so descriptors already pointing at this
+    // file observe the replacement instead of a detached predecessor.
+    if (existing) {
+      existing.data = bytes;
+      existing.mtimeMs = Date.now();
+    } else nodes.set(norm, { kind: "file", data: bytes, mtimeMs: Date.now() });
   }
 
   function readFile(p: string): Uint8Array | null {
@@ -334,40 +449,19 @@ export function createMemFS(): IMemFSHost {
           console.error("[wasm]", line);
         return buf.length;
       }
-      // Open-file fds (>= 100): append to the underlying file. Browser-hosted
-      // tools use this path for ordinary virtual files and explicit outputs.
+      // Open-file fds (>= 100): write at the descriptor cursor, the way Node's
+      // own `writeSync` without a position does. Browser-hosted tools use this
+      // path for ordinary virtual files and explicit outputs.
+      //
+      // An unknown or already-closed fd throws instead of being diverted into
+      // the captured stderr: reporting the byte count of a write nobody
+      // performed made the caller continue on a false success and quietly
+      // contaminated a diagnostic channel consumers read.
       const entry = fdTable.get(fd);
-      if (entry) {
-        const node = nodes.get(entry.path);
-        if (node && node.kind === "file") {
-          // subarray(0) is a zero-copy view over the full incoming buffer; the
-          // bytes are copied into `next` before writeSync returns.
-          const incoming = buf.subarray(0);
-          const existing = node.data;
-          const next = new Uint8Array(
-            existing.byteLength + incoming.byteLength,
-          );
-          next.set(existing, 0);
-          next.set(incoming, existing.byteLength);
-          node.data = next;
-          node.mtimeMs = Date.now();
-          entry.position = next.byteLength;
-          return incoming.byteLength;
-        }
-      }
-      // Unknown fd. Fall back to the stderr buffer so the bytes aren't lost
-      // entirely (and surface as a console.error so the regression is
-      // visible to whoever's looking).
-      stderr.buffer += decoder.decode(buf);
-      // eslint-disable-next-line no-console
-      console.error(
-        "[wasm] writeSync to unknown fd " +
-          fd +
-          " (" +
-          buf.byteLength +
-          " bytes); routed to stderr buffer",
-      );
-      return buf.length;
+      if (!entry) throw new MemFSError("EBADF", "write");
+      // subarray(0) is a zero-copy view over the full incoming buffer; the
+      // bytes are copied into the node before writeSync returns.
+      return writeThroughDescriptor(entry, buf.subarray(0), null, "write");
     },
 
     write(fd, buf, offset, length, position, callback) {
@@ -390,44 +484,83 @@ export function createMemFS(): IMemFSHost {
           callback(null, length);
           return;
         }
-        if (position !== null && position !== 0) {
-          callback(new MemFSError("ESPIPE", "write"), 0);
+        const view = buf.subarray(offset, offset + length);
+        // The stdout/stderr capture buffers are streams, not files: they have
+        // no seekable offset, so an explicit position is meaningless on them.
+        if (fd === 1 || fd === 2) {
+          if (position !== null && position !== 0)
+            throw new MemFSError("ESPIPE", "write");
+          callback(null, this.writeSync(fd, view));
           return;
         }
-        const view = buf.subarray(offset, offset + length);
-        const written = this.writeSync(fd, view);
-        callback(null, written);
+        const entry = fdTable.get(fd);
+        if (!entry) throw new MemFSError("EBADF", "write");
+        callback(null, writeThroughDescriptor(entry, view, position, "write"));
       } catch (err) {
         callback(err as NodeJS.ErrnoException, 0);
       }
     },
 
+    // Every rejection happens before the first mutation and before a
+    // descriptor is minted, so a refused open leaves neither a half-created
+    // node nor a leaked fd behind.
     open(p, flags, _mode, callback) {
-      const norm = normalize(p);
-      const node = nodes.get(norm);
-      const creating = (flags & (this.constants.O_CREAT ?? 0)) !== 0;
-      if (!node) {
-        if (!creating) {
-          callback(new MemFSError("ENOENT", "open", norm), -1);
-          return;
+      try {
+        const norm = normalize(p);
+        const creating = (flags & (this.constants.O_CREAT ?? 0)) !== 0;
+        const exclusive = (flags & (this.constants.O_EXCL ?? 0)) !== 0;
+        const truncating = (flags & (this.constants.O_TRUNC ?? 0)) !== 0;
+        const appending = (flags & (this.constants.O_APPEND ?? 0)) !== 0;
+        const directoryOnly = (flags & (this.constants.O_DIRECTORY ?? 0)) !== 0;
+        // The access mode is the low bits of `flags`: absent both means
+        // read-only, and `O_RDWR` alongside `O_WRONLY` still grants both.
+        const writeOnly = (flags & (this.constants.O_WRONLY ?? 0)) !== 0;
+        const readWrite = (flags & (this.constants.O_RDWR ?? 0)) !== 0;
+        const writable = writeOnly || readWrite;
+        const readable = !writeOnly || readWrite;
+
+        let node = nodes.get(norm);
+        if (!node) {
+          if (!creating) throw new MemFSError("ENOENT", "open", norm);
+          // `open` can only ever create a regular file, so a caller demanding a
+          // directory cannot be satisfied by creating one.
+          if (directoryOnly) throw new MemFSError("ENOTDIR", "open", norm);
+          // Creating the missing ancestor chain is the documented job of
+          // `writeFile` and `mkdirp`; the low-level `open` never promised it.
+          const missing = missingDirs(pathChain(norm).slice(0, -1), "open");
+          if (missing.length > 0)
+            throw new MemFSError("ENOENT", "open", missing[0]!);
+          node = { kind: "file", data: new Uint8Array(), mtimeMs: Date.now() };
+          nodes.set(norm, node);
+        } else {
+          if (creating && exclusive)
+            throw new MemFSError("EEXIST", "open", norm);
+          if (node.kind === "dir") {
+            // A directory opens read-only — Go stats the fd and lists the path
+            // that way. Writing to it or truncating it would turn it into a
+            // file and orphan every descendant.
+            if (writable || truncating)
+              throw new MemFSError("EISDIR", "open", norm);
+          } else if (directoryOnly)
+            throw new MemFSError("ENOTDIR", "open", norm);
         }
-        ensureParentDirs(norm);
-        nodes.set(norm, {
-          kind: "file",
-          data: new Uint8Array(),
-          mtimeMs: Date.now(),
-        });
-      }
-      const fd = nextFd++;
-      fdTable.set(fd, { path: norm, position: 0 });
-      if ((flags & (this.constants.O_TRUNC ?? 0)) !== 0) {
-        nodes.set(norm, {
-          kind: "file",
-          data: new Uint8Array(),
-          mtimeMs: Date.now(),
+        if (truncating) {
+          node.data = new Uint8Array();
+          node.mtimeMs = Date.now();
+        }
+        const fd = nextFd++;
+        fdTable.set(fd, {
+          path: norm,
+          node,
+          position: 0,
+          readable,
+          writable,
+          append: appending,
         });
+        callback(null, fd);
+      } catch (err) {
+        callback(err as NodeJS.ErrnoException, -1);
       }
-      callback(null, fd);
     },
 
     close(fd, callback) {
@@ -475,16 +608,29 @@ export function createMemFS(): IMemFSHost {
         callback(new MemFSError("EBADF", "read"), 0);
         return;
       }
-      const node = nodes.get(entry.path);
+      // A write-only descriptor is not a readable one. POSIX answers EBADF for
+      // an operation the descriptor's access mode never granted.
+      if (!entry.readable) {
+        callback(new MemFSError("EBADF", "read", entry.path), 0);
+        return;
+      }
+      const node = entry.node;
       if (!node || node.kind !== "file") {
         callback(new MemFSError("ENOENT", "read", entry.path), 0);
         return;
       }
       const start = position ?? entry.position;
+      if (!Number.isInteger(start) || start < 0) {
+        callback(new MemFSError("EINVAL", "read", entry.path), 0);
+        return;
+      }
       const end = Math.min(start + length, node.data.byteLength);
       const slice = node.data.subarray(start, end);
       buffer.set(slice, offset);
-      if (position === null) entry.position = end;
+      // The cursor advances by the bytes actually read. Assigning `end` would
+      // rewind a cursor already past end-of-file (after `ftruncate`, say) back
+      // onto live bytes and make the next sequential write overwrite them.
+      if (position === null) entry.position = start + slice.byteLength;
       callback(null, slice.byteLength);
     },
 
@@ -498,7 +644,17 @@ export function createMemFS(): IMemFSHost {
 
     mkdir(p, _perm, callback) {
       try {
-        mkdirp(p);
+        const norm = normalize(p);
+        if (nodes.has(norm)) throw new MemFSError("EEXIST", "mkdir", norm);
+        const parent = nodes.get(parentDir(norm));
+        if (!parent) throw new MemFSError("ENOENT", "mkdir", parentDir(norm));
+        if (parent.kind !== "dir")
+          throw new MemFSError("ENOTDIR", "mkdir", parentDir(norm));
+        nodes.set(norm, {
+          kind: "dir",
+          data: new Uint8Array(),
+          mtimeMs: Date.now(),
+        });
         callback(null);
       } catch (err) {
         callback(err as NodeJS.ErrnoException);
@@ -521,9 +677,9 @@ export function createMemFS(): IMemFSHost {
     },
 
     fstat(fd, callback) {
-      // fstat against a pipe end returns a synthetic file-stat. Go's
-      // os.Pipe-backed File uses fstat at construction time to populate
-      // Stat_t; without this it errors and falls back to invalid fds.
+      // fstat against a pipe end returns a synthetic file-stat so a direct
+      // JavaScript caller that wraps the fd in a file-like abstraction can
+      // populate its stat fields. A pipe end has no node in the tree.
       if (pipes.has(fd)) {
         callback(
           null,
@@ -544,7 +700,8 @@ export function createMemFS(): IMemFSHost {
         return;
       }
       try {
-        callback(null, statSync(entry.path));
+        if (!entry.node) throw new MemFSError("ENOENT", "fstat", entry.path);
+        callback(null, makeStats(entry.node));
       } catch (err) {
         callback(
           err as NodeJS.ErrnoException,
@@ -713,7 +870,11 @@ export function createMemFS(): IMemFSHost {
         callback(new MemFSError("EINVAL", "ftruncate"));
         return;
       }
-      const node = nodes.get(entry.path);
+      if (!entry.writable) {
+        callback(new MemFSError("EBADF", "ftruncate", entry.path));
+        return;
+      }
+      const node = entry.node;
       if (!node || node.kind !== "file") {
         callback(new MemFSError("EINVAL", "ftruncate", entry.path));
         return;

package/src/structures/ITtscApi.ts

@@ -83,18 +83,21 @@ export interface ITtscApi {
     opts: ITtscSnapshotHandle & { file?: string },
   ): Promise<ITtscResult>;
 
-  /** Return the deepest AST node whose range covers `position` (byte offset). */
+  /**
+   * Return the syntax token touching `position` (byte offset), including
+   * punctuation. Returns `{node: null}` for whitespace and comments.
+   */
   getNodeAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;
 
   /**
-   * Run the TypeScript-Go type checker against the node at `position` and
-   * return its printed type string + flags. Returns `{type: null}` when there
-   * is no node at that position.
+   * Resolve the token at `position` and return the enclosing TypeScript-Go
+   * semantic node's printed type string + flags. Returns `{type: null}` when
+   * the position has no token or no type-bearing token.
    */
   getTypeAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;
 
   /**
-   * Resolve the symbol the node at `position` refers to, including up to 16
+   * Resolve the symbol the token at `position` refers to, including up to 16
    * declaration sites. Returns `{symbol: null}` when no symbol is bound.
    */
   getSymbolAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;

package/src/structures/ITtscNodeAtPositionResult.ts

@@ -2,6 +2,6 @@ import type { ITtscNodeInfo } from "./ITtscNodeInfo";
 
 /** Payload inside `ITtscResult.result` for `getNodeAtPosition`. */
 export interface ITtscNodeAtPositionResult {
-  /** `null` when no node covers the position. */
+  /** `null` when no syntax token touches the position. */
   node: ITtscNodeInfo | null;
 }

package/src/structures/ITtscNodeInfo.ts

@@ -1,4 +1,4 @@
-/** AST node shape returned by `getNodeAtPosition`. */
+/** Syntax-token shape returned by `getNodeAtPosition`. */
 export interface ITtscNodeInfo {
   /** Numeric `ast.Kind` from TypeScript-Go. */
   kind: number;

package/src/structures/ITtscPositionQuery.ts

@@ -6,8 +6,10 @@ import type { ITtscFileQuery } from "./ITtscFileQuery";
  */
 export interface ITtscPositionQuery extends ITtscFileQuery {
   /**
-   * Byte offset into the file's source text. JS callers with a UTF-16
-   * line/character pair must resolve it to a byte offset first.
+   * Byte offset into the file's source text. It must satisfy `0 <= position <
+   * sourceText's UTF-8 byte length`; the offset immediately after the final
+   * byte is out of range. JS callers with a UTF-16 line/character pair must
+   * resolve it to a byte offset first.
    */
   position: number;
 }

package/src/structures/ITtscSymbolAtPositionResult.ts

@@ -2,6 +2,6 @@ import type { ITtscSymbolInfo } from "./ITtscSymbolInfo";
 
 /** Payload inside `ITtscResult.result` for `getSymbolAtPosition`. */
 export interface ITtscSymbolAtPositionResult {
-  /** `null` when the node has no associated symbol. */
+  /** `null` when no touching token has an associated symbol. */
   symbol: ITtscSymbolInfo | null;
 }

package/src/structures/ITtscTypeAtPositionResult.ts

@@ -2,6 +2,6 @@ import type { ITtscTypeInfo } from "./ITtscTypeInfo";
 
 /** Payload inside `ITtscResult.result` for `getTypeAtPosition`. */
 export interface ITtscTypeAtPositionResult {
-  /** `null` when the node has no associated type. */
+  /** `null` when no touching token has a type. */
   type: ITtscTypeInfo | null;
 }

package/src/structures/IWasmExecFS.ts

@@ -135,10 +135,20 @@ export interface IWasmExecFS {
     callback: (err: NodeJS.ErrnoException | null) => void,
   ): void;
   /**
-   * `pipe2` is what Go's wasm `os.Pipe()` calls. Returns two fds: a read end
-   * and a write end. The host's stdout/stderr capture currently uses MemFS temp
-   * files, but this keeps direct pipe callers compatible with the wasm fs
-   * surface.
+   * JavaScript-only pipe emulation. Returns two fds: a read end and a write
+   * end.
+   *
+   * Installing this does **not** make Go's wasm `os.Pipe()` work. Under the
+   * pinned Go toolchain neither `GOOS=js` nor `GOOS=wasip1` has pipes:
+   * `os.Pipe` returns an `ENOSYS` syscall error and `syscall.Pipe` returns
+   * `ENOSYS`, and neither one crosses the `globalThis.fs` bridge, so no
+   * JavaScript method is ever consulted. A custom Go/wasm host cannot reach
+   * this shim.
+   *
+   * The host captures wasm output without pipes: process-level writes to fd 1
+   * and fd 2 land in `stdout.buffer` and `stderr.buffer` through `writeSync`,
+   * and a plugin's output is collected by the Go-side `host.InvokePlugin` into
+   * invocation-owned in-process buffers.
    */
   pipe2(
     flags: number,