ttsc 0.16.3 → 0.16.6

package/src/TtscService.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+import type { ResidentTransformProcess } from "./compiler/internal/residentTransformProcess";
+import { startResidentTransform } from "./compiler/internal/startResidentTransform";
+import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
+
+/**
+ * Resident, incremental transform service for the `ttsc` TypeScript-Go
+ * pipeline.
+ *
+ * Where {@link TtscCompiler.transform} spawns a fresh process and recompiles the
+ * whole project on every call, `TtscService` keeps one long-lived host warm: it
+ * compiles the project once and then answers per-file transform requests from
+ * that warm program. A single service instance transforms many files (a watch
+ * server, an editor session, a codegen tool) while paying the project compile
+ * once instead of once per file. Sharing one host across separate worker
+ * processes (a Metro worker pool) is tracked in samchon/ttsc#255.
+ *
+ * The shape mirrors a legacy TypeScript `LanguageService`: construct it against
+ * a project context, ask it to transform individual files, and dispose it when
+ * done. Construction is synchronous (it launches the host); the host compiles
+ * in the background, so the first {@link transformFile} resolves once that
+ * compile lands.
+ *
+ * Resident mode runs through the linked-plugin shared host, so the project must
+ * declare at least one transform-stage plugin; the constructor throws
+ * otherwise. It does not run check-stage plugins (unlike
+ * {@link TtscCompiler.transform}); only the program's own type-checking gates an
+ * {@link updateFile}.
+ */
+export class TtscService {
+  private readonly resident: ResidentTransformProcess;
+  private readonly projectRoot: string;
+
+  /**
+   * Create a service bound to the given project context and launch its resident
+   * host. The context is the same shape {@link TtscCompiler} accepts; it is not
+   * replaceable per call.
+   */
+  public constructor(context: ITtscCompilerContext = {}) {
+    const started = startResidentTransform({
+      ...context,
+      env: context.env ? { ...context.env } : undefined,
+      plugins: Array.isArray(context.plugins)
+        ? [...context.plugins]
+        : context.plugins,
+    });
+    this.resident = started.process;
+    this.projectRoot = started.projectRoot;
+  }
+
+  /**
+   * Return the transformed TypeScript source for one file, or `undefined` when
+   * the resident program does not contain it (for example a file excluded from
+   * the tsconfig). A relative `fileName` is resolved against the project root.
+   *
+   * Rejects when the resident host failed to compile the project; the rejection
+   * carries the host's diagnostics so callers can surface a real build error.
+   */
+  public async transformFile(fileName: string): Promise<string | undefined> {
+    const reply = await this.resident.request({
+      file: this.absolutePath(fileName),
+    });
+    return reply.found === true && typeof reply.typescript === "string"
+      ? reply.typescript
+      : undefined;
+  }
+
+  /**
+   * Apply new in-memory content for one file and re-transform the project, so a
+   * subsequent {@link transformFile} reflects the edit without restarting the
+   * host. Returns whether the re-transform succeeded; `false` means the edit
+   * did not compile and the previous transform is still in effect. A relative
+   * `fileName` is resolved against the project root.
+   */
+  public async updateFile(fileName: string, content: string): Promise<boolean> {
+    const reply = await this.resident.request({
+      content,
+      update: this.absolutePath(fileName),
+    });
+    return reply.updated === true;
+  }
+
+  /** Terminate the resident host and reject any in-flight requests. */
+  public dispose(): void {
+    this.resident.dispose();
+  }
+
+  private absolutePath(fileName: string): string {
+    return path.isAbsolute(fileName)
+      ? fileName
+      : path.resolve(this.projectRoot, fileName);
+  }
+}

package/src/compiler/internal/residentTransformProcess.ts

@@ -0,0 +1,216 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type Interface, createInterface } from "node:readline";
+
+/** Cap on retained stderr so a long-lived host cannot grow it without bound. */
+const STDERR_TAIL_LIMIT = 64 * 1024;
+
+/** Options for spawning the resident transform host. */
+export interface ResidentTransformProcessOptions {
+  args: readonly string[];
+  binary: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface PendingRequest {
+  reject: (reason: Error) => void;
+  resolve: (reply: Record<string, unknown>) => void;
+}
+
+/**
+ * Async client for the long-lived `utility-host serve` process.
+ *
+ * The host transforms the whole project once at startup, caches every file's
+ * transformed TypeScript, then answers newline-delimited requests. This class
+ * speaks that protocol: each {@link request} writes one JSON line and the host
+ * replies with one line, matched FIFO. A transform request (`{"file":...}`) is
+ * answered with `{"typescript":...,"found":...}`, and an update request
+ * (`{"update":...,"content":...}`) with `{"updated":...}`.
+ *
+ * One resident process answers every request from one service instead of
+ * spawning a fresh `transform` subprocess per call, so a single process pays
+ * the project compile once (samchon/ttsc#255).
+ */
+export class ResidentTransformProcess {
+  private readonly child: ChildProcess;
+  private readonly reader: Interface;
+  private readonly pending: PendingRequest[] = [];
+  private stderr = "";
+  private failure: Error | undefined;
+
+  public constructor(options: ResidentTransformProcessOptions) {
+    // Default stdio is "pipe" for stdin/stdout/stderr, which is exactly what the
+    // line protocol needs; spelling it out as a string[] would not narrow to
+    // StdioOptions, so it is left implicit.
+    this.child = spawn(options.binary, [...options.args], {
+      cwd: options.cwd,
+      env: options.env,
+      windowsHide: true,
+    });
+    const stdout = this.child.stdout;
+    const stdin = this.child.stdin;
+    if (stdout === null || stdin === null) {
+      this.child.kill();
+      throw new Error("ttsc: resident transform host has no stdio pipes");
+    }
+    this.reader = createInterface({ input: stdout });
+    this.reader.on("line", (line) => this.onLine(line));
+    // Drive completion off stdout's end, not the process "exit" event: every
+    // buffered "line" is delivered before "close", so a reply that arrived just
+    // before the host exited still resolves its request instead of racing the
+    // exit-time rejection.
+    this.reader.on("close", () => this.onReaderClose());
+    this.child.stderr?.on("data", (chunk: Buffer | string) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      // Keep only the tail: stderr is consulted for the crash message, and a
+      // long resident session can write diagnostics on every failed update.
+      this.stderr = (this.stderr + text).slice(-STDERR_TAIL_LIMIT);
+    });
+    this.child.on("error", (error) => this.fail(error));
+    // A dead host's pipes emit "error" (EPIPE on POSIX, often ECONNRESET on
+    // Windows). Without these listeners Node turns a pipe error into an uncaught
+    // exception that crashes the whole consumer process; route them through
+    // fail() (stderr is non-critical) so a pipe death fails in-flight requests
+    // instead, and also closes the window where stdin.destroyed has not flipped.
+    stdin.on("error", (error) => this.fail(error));
+    stdout.on("error", (error) => this.fail(error));
+    this.child.stderr?.on("error", () => {});
+  }
+
+  /**
+   * Send one request to the host and resolve with its parsed JSON reply. The
+   * host answers in FIFO order, so the caller interprets the reply shape by the
+   * payload it sent (a transform reply vs an update reply). Rejects when the
+   * host has already failed or exited, or if writing the request fails.
+   */
+  public request(
+    payload: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    if (this.failure !== undefined) {
+      return Promise.reject(this.failure);
+    }
+    const stdin = this.child.stdin;
+    if (stdin === null || stdin.destroyed) {
+      return Promise.reject(
+        new Error("ttsc: resident transform host stdin is closed"),
+      );
+    }
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const pending: PendingRequest = { reject, resolve };
+      this.pending.push(pending);
+      stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+        if (error) {
+          this.removePending(pending);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  /**
+   * Terminate the resident process and reject any in-flight requests. Safe to
+   * call more than once.
+   */
+  public dispose(): void {
+    if (this.failure === undefined) {
+      // If the host already died, reject with its real exit error (stderr +
+      // exit code) rather than a bland "disposed" message.
+      this.failure =
+        this.child.exitCode !== null || this.child.signalCode !== null
+          ? this.exitError()
+          : new Error("ttsc: resident transform host disposed");
+    }
+    const stdin = this.child.stdin;
+    if (stdin !== null && !stdin.destroyed) {
+      stdin.end();
+    }
+    this.reader.close();
+    this.rejectAll(this.failure);
+    if (this.child.exitCode === null && this.child.signalCode === null) {
+      this.child.kill();
+    }
+  }
+
+  private onLine(line: string): void {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    const request = this.pending.shift();
+    if (request === undefined) {
+      // The host must emit exactly one reply per request, so an unmatched line
+      // is a protocol violation that would desync every later reply into the
+      // wrong request. Fail fast rather than silently returning wrong output.
+      // A line arriving after teardown (failure already set) is benign.
+      if (this.failure === undefined) {
+        this.fail(
+          new Error("ttsc: resident transform host sent an unsolicited reply"),
+        );
+      }
+      return;
+    }
+    request.resolve(parseReply(trimmed));
+  }
+
+  private onReaderClose(): void {
+    if (this.pending.length === 0) {
+      return;
+    }
+    this.rejectAll(this.failure ?? this.exitError());
+  }
+
+  private fail(error: Error): void {
+    this.failure ??= error;
+    this.rejectAll(this.failure);
+  }
+
+  private rejectAll(error: Error): void {
+    while (this.pending.length !== 0) {
+      this.pending.shift()!.reject(error);
+    }
+  }
+
+  private removePending(target: PendingRequest): void {
+    const index = this.pending.indexOf(target);
+    if (index !== -1) {
+      this.pending.splice(index, 1);
+    }
+  }
+
+  private exitError(): Error {
+    const detail = this.stderr.trim();
+    if (detail.length !== 0) {
+      return new Error(detail);
+    }
+    // Read the child's own exit fields (set synchronously by Node) so the
+    // message is accurate even before this instance's "exit" handler would run.
+    const code = this.child.exitCode;
+    const signalCode = this.child.signalCode;
+    const signal = signalCode === null ? "" : `, signal ${signalCode}`;
+    return new Error(
+      `ttsc: resident transform host exited (code ${code ?? "null"}${signal})`,
+    );
+  }
+}
+
+/**
+ * Parse one reply line into a plain object. A malformed line degrades to an
+ * empty object rather than throwing, so one bad line never rejects a request
+ * the FIFO has already advanced past; the caller reads missing fields as
+ * absent.
+ */
+function parseReply(line: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // A non-object or unparseable line is treated as an empty reply.
+  }
+  return {};
+}

package/src/compiler/internal/startResidentTransform.ts

@@ -0,0 +1,126 @@
+import path from "node:path";
+
+import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
+import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import { readProjectConfig } from "./project/readProjectConfig";
+import { ResidentTransformProcess } from "./residentTransformProcess";
+import { resolveBinary } from "./resolveBinary";
+import { resolveTsgo } from "./resolveTsgo";
+import {
+  assertSharedHostCompatibility,
+  linkedTransformPlugins,
+  selectSharedHostPlugin,
+} from "./sharedHostHelpers";
+
+/**
+ * A started resident transform host plus the project root its keys are relative
+ * to.
+ */
+export interface StartedResidentTransform {
+  process: ResidentTransformProcess;
+  projectRoot: string;
+}
+
+/**
+ * Start a resident `serve` host for the configured project.
+ *
+ * Mirrors the plugin spawn of `transformProjectInMemory`, but launches the
+ * shared host's `serve` subcommand as one long-lived process instead of a
+ * per-call `transform` subprocess. The host compiles the whole project once at
+ * startup and then answers per-file requests, so one caller pays the project
+ * compile once and reuses it across its own per-file requests.
+ *
+ * Resident mode runs through the linked-plugin shared host
+ * (`cmd/utility-host`), which is the only binary that exposes `serve`. It
+ * therefore requires at least one transform-stage plugin; executable transform
+ * hosts that own their own process are not served and must use the per-call
+ * transform path. Check-stage plugins are not run by the resident host.
+ */
+export function startResidentTransform(
+  context: ITtscCompilerContext,
+): StartedResidentTransform {
+  const cwd = path.resolve(context.cwd ?? process.cwd());
+  const project = readProjectConfig({
+    cwd,
+    projectRoot: context.projectRoot,
+    tsconfig: context.tsconfig,
+  });
+  const loaded = loadProjectPlugins({
+    binary: resolveBinary(context) ?? "",
+    cacheDir: context.cacheDir ?? context.env?.TTSC_CACHE_DIR,
+    cwd,
+    entries: context.plugins,
+    projectRoot: context.projectRoot,
+    tsconfig: project.path,
+  });
+  const transformers = loaded.nativePlugins.filter(
+    (plugin) => plugin.stage === "transform",
+  );
+  if (transformers.length === 0) {
+    throw new Error(
+      "ttsc: TtscService resident mode requires at least one transform-stage plugin; " +
+        "use TtscCompiler.transform for projects with only check-stage plugins or none",
+    );
+  }
+  assertSharedHostCompatibility(transformers, "source-to-source");
+
+  const host = selectSharedHostPlugin(transformers);
+  const tsgoBinary = resolveTsgo({ ...context, cwd: project.root }).binary;
+  const resident = new ResidentTransformProcess({
+    args: [
+      "serve",
+      `--tsconfig=${project.path}`,
+      `--plugins-json=${serializeNativePlugins(transformers)}`,
+      `--cwd=${project.root}`,
+    ],
+    binary: host.binary,
+    cwd: project.root,
+    env: residentEnv(context, tsgoBinary, loaded.nativePlugins),
+  });
+  return { process: resident, projectRoot: project.root };
+}
+
+/**
+ * Build the environment for the resident host spawn. Matches the per-call
+ * transform spawn: injects the Node, tsgo, and ttsx binaries so the host never
+ * searches PATH, and forwards linked transform plugins via
+ * `TTSC_LINKED_PLUGINS_JSON`.
+ */
+function residentEnv(
+  context: ITtscCompilerContext,
+  tsgoBinary: string,
+  nativePlugins: readonly ITtscLoadedNativePlugin[],
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    TTSC_NODE_BINARY: process.env.TTSC_NODE_BINARY ?? process.execPath,
+    TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? tsgoBinary,
+    TTSC_TTSX_BINARY:
+      process.env.TTSC_TTSX_BINARY ??
+      path.join(__dirname, "..", "..", "launcher", "ttsx.js"),
+    ...context.env,
+  };
+  const linked = linkedTransformPlugins(nativePlugins);
+  if (linked.length !== 0) {
+    env.TTSC_LINKED_PLUGINS_JSON = serializeNativePlugins(linked);
+  }
+  return env;
+}
+
+/**
+ * Serialize the plugin list to the `--plugins-json` /
+ * `TTSC_LINKED_PLUGINS_JSON` shape the native host reads: only the fields it
+ * needs, to keep the arg short.
+ */
+function serializeNativePlugins(
+  plugins: readonly ITtscLoadedNativePlugin[],
+): string {
+  return JSON.stringify(
+    plugins.map((plugin) => ({
+      config: plugin.config,
+      name: plugin.name,
+      stage: plugin.stage,
+    })),
+  );
+}

package/src/index.ts

@@ -8,4 +8,5 @@
  */
 
 export * from "./TtscCompiler";
+export * from "./TtscService";
 export * from "./structures/index";

package/utility/host.go

@@ -10,12 +10,13 @@ import (
 
   shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
   shimprinter "github.com/microsoft/typescript-go/shim/printer"
+  "github.com/microsoft/typescript-go/shim/vfs"
 
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// hostOptions is the parsed form of the flags accepted by all three
-// subcommands (check, build, transform).
+// hostOptions is the parsed form of the flags accepted by the subcommands
+// (check, build, transform, serve).
 type hostOptions struct {
   cwd            string
   emit           bool
@@ -28,6 +29,10 @@ type hostOptions struct {
   singleThreaded bool
   checkers       int
   tsgoArgs       []string
+  // fs overrides the filesystem the program loads from. Only the resident serve
+  // host sets it (to an OverlayFS), so build/check/transform leave it nil and
+  // LoadProgram falls back to the default filesystem.
+  fs vfs.FS
 }
 
 // transformResult is the JSON envelope written to stdout by RunTransform.
@@ -251,6 +256,7 @@ func loadUtilityProgram(opts hostOptions) (*driver.Program, []driver.PluginEntry
     SingleThreaded: opts.singleThreaded,
     Checkers:       opts.checkers,
     TsgoArgs:       opts.tsgoArgs,
+    FS:             opts.fs,
   })
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc utility: %v\n", err)

package/utility/serve.go

@@ -0,0 +1,158 @@
+package utility
+
+import (
+  "bufio"
+  "encoding/json"
+  "fmt"
+  "io"
+  "os"
+  "path/filepath"
+  "strings"
+
+  shimprinter "github.com/microsoft/typescript-go/shim/printer"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// serveRequest is one newline-delimited request the resident host reads from its
+// input stream. It is either a transform request (File set) for the transformed
+// TypeScript of a file, or an update request (Update set) that applies new
+// in-memory content for a file and re-transforms the project.
+type serveRequest struct {
+  Content string `json:"content"`
+  File    string `json:"file"`
+  Update  string `json:"update"`
+}
+
+// serveResponse is the reply to a transform request: the transformed TypeScript
+// for the requested file and whether the resident program had it.
+type serveResponse struct {
+  TypeScript string `json:"typescript"`
+  Found      bool   `json:"found"`
+}
+
+// serveUpdateResponse is the reply to an update request: whether re-transforming
+// the project with the new content succeeded. A false reply leaves the previous
+// transform in place (for example the edit introduced a type error); the host's
+// diagnostics are written to stderr.
+type serveUpdateResponse struct {
+  Updated bool `json:"updated"`
+}
+
+// RunServe is the resident transform host. It transforms the whole project once
+// (the expensive compile plus linked-plugin pass) over an in-memory overlay,
+// caches every file's transformed text, then answers newline-delimited requests
+// read from in by writing one JSON reply per line to out, until in reaches EOF:
+//
+//   - {"file":"<path>"} returns that file's transformed TypeScript.
+//   - {"update":"<path>","content":"<text>"} applies new content for the file
+//     and re-transforms, so subsequent transform requests reflect the edit.
+//
+// One resident process answers a request stream without recompiling the project
+// per call and reflects edits without respawning the host. Sharing one host
+// across separate worker processes (a Metro worker pool) is tracked in
+// samchon/ttsc#255.
+//
+// in and out are explicit so the request loop is testable; the utility-host
+// command wires them to os.Stdin and os.Stdout.
+func RunServe(in io.Reader, out io.Writer, args []string) int {
+  opts, ok := parseHostOptions("serve", args)
+  if !ok {
+    return 2
+  }
+  overlay := driver.NewOverlayFS(driver.DefaultFS())
+  opts.fs = overlay
+  cache, ok := buildServeCache(opts)
+  if !ok {
+    return 2
+  }
+  encoder := json.NewEncoder(out)
+  // ReadString imposes no line-length limit. An update request carries a whole
+  // file's content on one line, so the line is as large as that content; a
+  // bufio.Scanner cap would be an arbitrary ceiling at which the resident host
+  // dies, and there is no such natural ceiling on source size.
+  reader := bufio.NewReader(in)
+  for {
+    raw, err := reader.ReadString('\n')
+    if line := strings.TrimSpace(raw); line != "" {
+      cache = handleServeLine(line, opts, overlay, cache, encoder)
+    }
+    if err != nil {
+      if err != io.EOF {
+        fmt.Fprintf(os.Stderr, "ttsc utility serve: read error: %v\n", err)
+        return 2
+      }
+      return 0
+    }
+  }
+}
+
+// handleServeLine answers one request line and returns the cache to use for the
+// next request: the rebuilt cache after a successful update, the unchanged cache
+// otherwise.
+func handleServeLine(
+  line string,
+  opts hostOptions,
+  overlay *driver.OverlayFS,
+  cache map[string]string,
+  encoder *json.Encoder,
+) map[string]string {
+  var req serveRequest
+  if err := json.Unmarshal([]byte(line), &req); err != nil {
+    _ = encoder.Encode(serveResponse{})
+    return cache
+  }
+  if req.Update != "" {
+    abs := resolveServePath(opts.cwd, req.Update)
+    prev, had := overlay.Get(abs)
+    overlay.Set(abs, req.Content)
+    if rebuilt, ok := buildServeCache(opts); ok {
+      _ = encoder.Encode(serveUpdateResponse{Updated: true})
+      return rebuilt
+    }
+    // Roll the failed edit back so a file that does not compile does not poison
+    // every later rebuild; the previous transform stays in effect.
+    if had {
+      overlay.Set(abs, prev)
+    } else {
+      overlay.Unset(abs)
+    }
+    _ = encoder.Encode(serveUpdateResponse{Updated: false})
+    return cache
+  }
+  key := apiOutputKey(opts.cwd, resolveServePath(opts.cwd, req.File))
+  text, found := cache[key]
+  _ = encoder.Encode(serveResponse{TypeScript: text, Found: found})
+  return cache
+}
+
+// buildServeCache runs the whole-project transform once over the current overlay
+// state and returns the transformed text keyed exactly like the transform
+// subcommand's JSON envelope.
+func buildServeCache(opts hostOptions) (map[string]string, bool) {
+  prog, _, ok := loadUtilityProgram(opts)
+  if !ok {
+    return nil, false
+  }
+  defer prog.Close()
+  if err := prog.ApplyLinkedPlugins(); err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return nil, false
+  }
+  printer := shimprinter.NewPrinter(shimprinter.PrinterOptions{}, shimprinter.PrintHandlers{}, nil)
+  cache := map[string]string{}
+  for _, file := range prog.SourceFiles() {
+    cache[apiOutputKey(opts.cwd, file.FileName())] = shimprinter.EmitSourceFile(printer, file)
+  }
+  return cache, true
+}
+
+// resolveServePath turns a request's file into an absolute path so apiOutputKey
+// computes the same key buildServeCache stored, and so overlay overrides are
+// keyed the way the program asks for them.
+func resolveServePath(cwd, file string) string {
+  if filepath.IsAbs(file) {
+    return file
+  }
+  return filepath.Join(cwd, file)
+}