@ttsc/wasm 0.30.4 → 0.31.1

package/README.md

@@ -118,7 +118,7 @@ There is no boot deadline. How long a fetch and instantiation take belongs to th
 
 Once `go.run` starts, JavaScript cannot terminate the Go wasm runtime. A boot failure from that point throws `BootTtscWorkerTerminationError` with code `TTSC_WASM_WORKER_TERMINATION_REQUIRED`, and later boots for the same `apiName` reject without installing another readiness bridge. Terminate and replace that Worker before retrying.
 
-Booting two wasms with the same `apiName` overwrites the previous global binding; pick a unique `apiName` per binary. `bootTtsc` also installs shared `fs` and `process` globals in its Worker, so use separate Workers when binaries need independent filesystems.
+Use one Go runtime per Worker. A different API name does not isolate the shared `Go`, `fs` and `process` globals, so another binary needs another Worker. Calls joining the same API/binary boot reuse its actual filesystem; a different explicit host or `wasmExecUrl` is rejected rather than silently ignored. The default runtime-script URL is the binary's sibling `wasm_exec.js`, without its query or fragment.
 
 ## Fountain API (snapshot, AST, type checker)
 
@@ -171,7 +171,7 @@ Verbs and payload types:
 
 `getNodeAtPosition` returns the syntax token touching `position`, including punctuation. `getTypeAtPosition` resolves that token to its enclosing semantic AST node, while `getSymbolAtPosition` queries the token directly. Both return `null` when there is no semantic answer. Whitespace and comments return `null` for all three verbs.
 
-`position` is a **byte offset** into the source text and must satisfy `0 <= position < UTF-8 byte length of sourceText`. The same coordinate TypeScript-Go uses internally. JS callers that have a UTF-16 `(line, character)` pair (e.g. From Monaco) must convert it before calling.
+`position` is a finite integer **byte offset** into the source text and must satisfy `0 <= position < UTF-8 byte length of sourceText`. This is the coordinate TypeScript-Go uses internally. Fractional and non-finite values are rejected before integer conversion. JS callers that have a UTF-16 `(line, character)` pair (e.g. From Monaco) must convert it before calling.
 
 **Lifecycle:** JS owns the handle. The wasm keeps the program (parsed AST, checker pool lease, every source file) alive until you call `releaseSnapshot`. Leaking handles leaks memory in the wasm linear heap.
 
@@ -195,7 +195,7 @@ Use `invocation.Go` for asynchronous work that belongs to the result. Register i
 The published `@ttsc/wasm` tarball ships:
 
 - A rewritten root `go.mod` whose `replace` directives point at `./shim-vendor/shim/*` (vendored at pack time from `packages/ttsc/shim/`).
-- The full `host/`, `cmd/`, `build/` Go source so consumers can `go build -tags '...'` their own wasm against your host helper.
+- The full `host/` and `cmd/` Go source and the `build/` scripts so consumers can `go build -tags '...'` their own wasm against your host helper.
 - `dist/ttsc.wasm` + `dist/wasm_exec.js`: the no-plugin sanity binary and the Go runtime loader.
 
 The tarball intentionally drops the `replace github.com/samchon/ttsc/packages/ttsc => ../ttsc` directive that the in-repo `go.mod` carries: consumers of the published module who want to rebuild the wasm must supply their own `replace` (or vendor `packages/ttsc` themselves). The published `dist/ttsc.wasm` is plug-and-play for runtime use; the Go module is for **plugin authors extending the host**, not for vanilla consumers.

package/build/build-wasm.cjs

@@ -10,7 +10,7 @@ const cp = require("child_process");
 const fs = require("fs");
 const path = require("path");
 
-const { createGoBuildCache } = require("../../../scripts/go-build-cache.cjs");
+const { createGoBuildCache } = require("./go-build-cache.cjs");
 
 const packageRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(packageRoot, "..", "..");
@@ -129,9 +129,10 @@ function buildWasm() {
 // Mirror packages/ttsc/shim/* into packages/wasm/shim-vendor/shim/* so the
 // published @ttsc/wasm tarball is self-contained: consumers extending the
 // wasm binary against the @ttsc/wasm Go module no longer need a sibling
-// `packages/ttsc/shim/` working tree. The vendored copy is checked in so
-// `pnpm pack --dry-run` agrees with what `go build` would see at install
-// time. The working-tree `go.mod` still points at `../ttsc/shim/*` for
+// `packages/ttsc/shim/` working tree. The vendored copy is a build artifact:
+// `shim-vendor/` is git-ignored and regenerated by every uncached build, and
+// its files are snapshotted with the cache artifacts, so an interrupted or
+// edited copy is rebuilt. The working-tree `go.mod` still points at `../ttsc/shim/*` for
 // local dev; the published `go.mod` is rewritten into `dist/go.mod` and
 // swapped in via prepack/postpack.
 function vendorShim() {

package/build/go-build-cache.cjs

@@ -0,0 +1,347 @@
+const cp = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SOURCE_FIELDS = [
+  "GoFiles",
+  "CgoFiles",
+  "CFiles",
+  "CXXFiles",
+  "MFiles",
+  "HFiles",
+  "FFiles",
+  "SFiles",
+  "SysoFiles",
+  "EmbedFiles",
+];
+
+function createGoBuildCache({
+  artifactPaths,
+  buildArguments,
+  cachePath,
+  cwd,
+  dependencyPackages,
+  environment,
+  extraFiles = [],
+  force = false,
+  inputDirectories = [],
+  execFileSync = cp.execFileSync,
+}) {
+  const identity = createInputIdentity({
+    buildArguments,
+    cwd,
+    dependencyPackages,
+    environment,
+    extraFiles,
+    inputDirectories,
+    execFileSync,
+  });
+
+  return {
+    identity,
+    isCurrent() {
+      if (force) return false;
+      const record = readRecord(cachePath);
+      if (record?.identity !== identity.hash) return false;
+      try {
+        return (
+          stableJson(record.artifacts) ===
+          stableJson(snapshotPaths(artifactPaths))
+        );
+      } catch {
+        return false;
+      }
+    },
+    write() {
+      const record = {
+        schema: 1,
+        identity: identity.hash,
+        artifacts: snapshotPaths(artifactPaths),
+      };
+      writeAtomically(cachePath, `${JSON.stringify(record, null, 2)}\n`);
+    },
+  };
+}
+
+function createInputIdentity({
+  buildArguments,
+  cwd,
+  dependencyPackages,
+  environment,
+  extraFiles,
+  inputDirectories,
+  execFileSync,
+}) {
+  // Dependency JSON grows with the entire selected package graph. Give stdout
+  // a file descriptor instead of execFileSync's bounded capture pipe; parse
+  // every byte only after Go succeeds, and reclaim the descriptor and file on
+  // both the success and failure paths. The temporary input is outside cwd so
+  // directory-shaped cache inputs cannot observe it.
+  const runGo = (args) => {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-go-list-"));
+    const output = path.join(directory, "stdout.json");
+    let descriptor;
+    try {
+      descriptor = fs.openSync(output, "wx");
+      execFileSync("go", args, {
+        cwd,
+        env: { ...process.env, ...environment },
+        stdio: ["ignore", descriptor, "inherit"],
+        windowsHide: true,
+      });
+      return fs.readFileSync(output, "utf8");
+    } finally {
+      try {
+        if (descriptor !== undefined) fs.closeSync(descriptor);
+      } finally {
+        fs.rmSync(directory, { recursive: true, force: true });
+      }
+    }
+  };
+  const packages = parseJsonStream(
+    runGo(["list", "-deps", "-json", ...dependencyPackages]),
+  );
+  const modules = parseJsonStream(runGo(["list", "-m", "-json", "all"]));
+  const toolchain = JSON.parse(
+    runGo([
+      "env",
+      "-json",
+      "GOVERSION",
+      "GOROOT",
+      "GOOS",
+      "GOARCH",
+      "GOFLAGS",
+      "GOEXPERIMENT",
+      "GOTOOLCHAIN",
+      "GOTOOLDIR",
+      "GOWASM",
+      "CGO_ENABLED",
+      "GOWORK",
+    ]),
+  );
+  addToolchainBinaryIdentity(toolchain);
+  const files = new Set([path.resolve(__filename)]);
+
+  for (const pkg of packages) {
+    if (!pkg.Dir) continue;
+    for (const field of SOURCE_FIELDS) {
+      for (const file of pkg[field] ?? []) {
+        files.add(path.join(pkg.Dir, file));
+      }
+    }
+    if (pkg.Module?.GoMod) addIfFile(files, pkg.Module.GoMod);
+  }
+  for (const mod of modules) {
+    if (!mod.GoMod) continue;
+    addIfFile(files, mod.GoMod);
+    addIfFile(files, path.join(path.dirname(mod.GoMod), "go.sum"));
+  }
+  if (toolchain.GOWORK && toolchain.GOWORK !== "off") {
+    addIfFile(files, toolchain.GOWORK);
+    addIfFile(files, path.join(path.dirname(toolchain.GOWORK), "go.work.sum"));
+  }
+  for (const file of extraFiles) files.add(path.resolve(file));
+  for (const directory of inputDirectories) addDirectory(files, directory);
+
+  const inputs = [...files]
+    .sort((a, b) =>
+      normalizedPath(a, cwd).localeCompare(normalizedPath(b, cwd)),
+    )
+    .map((file) => ({
+      path: normalizedPath(file, cwd),
+      sha256: fileDigest(file),
+    }));
+  const payload = {
+    schema: 1,
+    buildArguments,
+    environment,
+    toolchain,
+    inputs,
+  };
+  return {
+    hash: digest(stableJson(payload)),
+    payload,
+  };
+}
+
+function addToolchainBinaryIdentity(toolchain) {
+  const goroot = toolchain.GOROOT;
+  const goToolDir = toolchain.GOTOOLDIR;
+  delete toolchain.GOROOT;
+  delete toolchain.GOTOOLDIR;
+  if (!goroot) return;
+  const executable = path.join(
+    goroot,
+    "bin",
+    process.platform === "win32" ? "go.exe" : "go",
+  );
+  try {
+    toolchain.goBinarySha256 = fileDigest(executable);
+  } catch {
+    // `go env` supplied a toolchain root, but the compiler binary vanished
+    // before its identity could be read. Keep the miss deterministic instead
+    // of reusing an artifact built by an unknown compiler.
+    toolchain.goBinarySha256 = null;
+  }
+  if (!goToolDir) return;
+  try {
+    toolchain.goToolDirectorySha256 = directoryDigest(goToolDir);
+  } catch {
+    // The compiler driver may still be present when an incomplete toolchain
+    // loses its compile/link programs. Treat that transition as a cache miss.
+    toolchain.goToolDirectorySha256 = null;
+  }
+}
+
+function directoryDigest(directory) {
+  const files = new Set();
+  addDirectory(files, directory);
+  return digest(
+    stableJson(
+      [...files]
+        .sort()
+        .map((file) => ({
+          path: path.relative(directory, file).replaceAll(path.sep, "/"),
+          sha256: fileDigest(file),
+        })),
+    ),
+  );
+}
+
+function parseJsonStream(source) {
+  const records = [];
+  let start = 0;
+  while (start < source.length) {
+    while (/\s/.test(source[start] ?? "")) start += 1;
+    if (start >= source.length) break;
+    if (source[start] !== "{") {
+      throw new Error("go command returned a non-JSON record");
+    }
+    let depth = 0;
+    let quoted = false;
+    let escaped = false;
+    let end = start;
+    for (; end < source.length; end += 1) {
+      const character = source[end];
+      if (quoted) {
+        if (escaped) escaped = false;
+        else if (character === "\\") escaped = true;
+        else if (character === '"') quoted = false;
+        continue;
+      }
+      if (character === '"') quoted = true;
+      else if (character === "{") depth += 1;
+      else if (character === "}") {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    if (depth !== 0) throw new Error("go command returned incomplete JSON");
+    records.push(JSON.parse(source.slice(start, end + 1)));
+    start = end + 1;
+  }
+  return records;
+}
+
+function snapshotPaths(paths) {
+  return paths.map((entry) => snapshotPath(entry));
+}
+
+function snapshotPath(entry) {
+  const target = path.resolve(entry);
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch {
+    throw new Error(`cache artifact is missing: ${target}`);
+  }
+  if (stat.isFile())
+    return { path: target, type: "file", sha256: fileDigest(target) };
+  if (!stat.isDirectory())
+    throw new Error(`cache artifact is not a file or directory: ${target}`);
+  const files = new Set();
+  addDirectory(files, target);
+  return {
+    path: target,
+    type: "directory",
+    files: [...files].sort().map((file) => ({
+      path: path.relative(target, file),
+      sha256: fileDigest(file),
+    })),
+  };
+}
+
+function addDirectory(files, directory) {
+  const root = path.resolve(directory);
+  let stat;
+  try {
+    stat = fs.statSync(root);
+  } catch {
+    throw new Error(`cache input directory is missing: ${root}`);
+  }
+  if (!stat.isDirectory())
+    throw new Error(`cache input is not a directory: ${root}`);
+  const stack = [root];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const file = path.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(file);
+      else if (entry.isFile()) files.add(file);
+    }
+  }
+}
+
+function addIfFile(files, file) {
+  try {
+    if (fs.statSync(file).isFile()) files.add(file);
+  } catch {
+    // A module can be in the graph without a colocated go.sum. Its go.mod is
+    // still tracked; absent optional sums must not make every cache lookup fail.
+  }
+}
+
+function readRecord(cachePath) {
+  try {
+    const record = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    return record?.schema === 1 ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeAtomically(destination, content) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const temporary = `${destination}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, content);
+  fs.rmSync(destination, { force: true });
+  fs.renameSync(temporary, destination);
+}
+
+function normalizedPath(file, cwd) {
+  const relative = path.relative(cwd, file);
+  return (relative.startsWith("..") ? path.resolve(file) : relative).replaceAll(
+    path.sep,
+    "/",
+  );
+}
+
+function fileDigest(file) {
+  return digest(fs.readFileSync(file));
+}
+
+function digest(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function stableJson(value) {
+  return JSON.stringify(value);
+}
+
+module.exports = {
+  createGoBuildCache,
+  createInputIdentity,
+  parseJsonStream,
+};

package/build/pack-prepare.cjs

@@ -9,8 +9,9 @@
 // build-wasm.cjs emits a rewritten `dist/go.mod` that points at the
 // vendored `./shim-vendor/shim/*` tree. Pack-prepare swaps the working-tree
 // `go.mod` for that copy just before pack, then restores the original
-// afterwards. The original is stashed in `build/.go.mod.stash` so an
-// interrupted pack can be recovered by running `--restore`.
+// afterwards. The original is stashed in
+// `node_modules/.cache/ttsc-wasm/go.mod.stash` so an interrupted pack can be
+// recovered by running `--restore`.
 //
 // Usage:
 //   node build/pack-prepare.cjs --stash    # prepack: stash + swap

package/cmd/ttsc-wasm/main.go

@@ -2,8 +2,8 @@
 
 // Command ttsc-wasm is the non-wasm sanity entrypoint for `@ttsc/wasm`.
 //
-// The same binary, compiled with GOOS=js GOARCH=wasm, becomes the browser
-// wasm consumed by `bootTtsc`. For native targets we expose a minimal CLI so
+// The package has a separate GOOS=js GOARCH=wasm browser entry consumed by
+// `bootTtsc`. For native targets we expose a minimal CLI so
 // `go run ./cmd/ttsc-wasm` exercises the same host helpers without needing
 // the browser MemFS bridge.
 package main
@@ -55,39 +55,51 @@ func run(args []string) int {
   }
 }
 
-// runBuild invokes host.Build and writes the JSON result to stdout.
+// runBuild invokes host.Build and writes the JSON result to stdout. A write
+// failure returns code 3 even when compilation itself succeeded.
 func runBuild(args []string) int {
   cwd, tsconfig := parseProject(args)
   data, code, err := host.Build(cwd, tsconfig)
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc-wasm build: %v\n", err)
-    return 2
+    return code
+  }
+  if _, err := os.Stdout.Write(append(data, '\n')); err != nil {
+    fmt.Fprintf(os.Stderr, "ttsc-wasm build: write result: %v\n", err)
+    return 3
   }
-  _, _ = os.Stdout.Write(append(data, '\n'))
   return code
 }
 
-// runCheck invokes host.Check and writes the JSON result to stdout.
+// runCheck invokes host.Check and writes the JSON result to stdout. Code 3
+// reports an output failure independently of the compiler diagnostic status.
 func runCheck(args []string) int {
   cwd, tsconfig := parseProject(args)
   data, code, err := host.Check(cwd, tsconfig)
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc-wasm check: %v\n", err)
-    return 2
+    return code
+  }
+  if _, err := os.Stdout.Write(append(data, '\n')); err != nil {
+    fmt.Fprintf(os.Stderr, "ttsc-wasm check: write result: %v\n", err)
+    return 3
   }
-  _, _ = os.Stdout.Write(append(data, '\n'))
   return code
 }
 
 // runTransform invokes host.Transform and writes the JSON result to stdout.
+// Code 3 reports that the source envelope could not be written.
 func runTransform(args []string) int {
   cwd, tsconfig := parseProject(args)
   data, code, err := host.Transform(cwd, tsconfig)
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc-wasm transform: %v\n", err)
-    return 2
+    return code
+  }
+  if _, err := os.Stdout.Write(append(data, '\n')); err != nil {
+    fmt.Fprintf(os.Stderr, "ttsc-wasm transform: write result: %v\n", err)
+    return 3
   }
-  _, _ = os.Stdout.Write(append(data, '\n'))
   return code
 }
 

package/cmd/ttsc-wasm/main_wasm.go

@@ -10,8 +10,8 @@ import (
   "github.com/samchon/ttsc/packages/wasm/host"
 )
 
-// main installs the base ttsc API on globalThis and blocks forever.
-// Expose never returns; the select{} inside it keeps the wasm runtime alive.
+// main installs the base ttsc API on globalThis. A valid first registration
+// keeps the wasm runtime alive until its Worker is terminated.
 func main() {
   host.Expose("ttsc", host.Config{
     Plugins: nil,