ttsc 0.19.2 → 0.20.0

package/src/compiler/internal/residentTransformProcess.ts

@@ -7,6 +7,15 @@ const STDERR_TAIL_LIMIT = 64 * 1024;
 /** Cap on how much of an offending line an error message echoes back. */
 const REPLY_ECHO_LIMIT = 200;
 
+/** Default deadline for one request to the resident transform host. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 300_000;
+
+/** Node clamps timers beyond this signed 32-bit millisecond duration. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** Allow a cooperative host a short shutdown window before forcing it down. */
+const TERMINATION_GRACE_MS = 1_000;
+
 /**
  * The operation a request expects a reply for. The host answers a transform
  * request (`{"file":...}`) with `{"typescript":...,"found":...}` and an update
@@ -23,12 +32,24 @@ export interface ResidentTransformProcessOptions {
   binary: string;
   cwd?: string;
   env?: NodeJS.ProcessEnv;
+  /** Maximum time one request may wait for the resident host's reply. */
+  requestTimeoutMs?: number;
+}
+
+/** Per-request lifecycle controls for a resident transform host. */
+export interface ResidentTransformRequestOptions {
+  /** Abort this request. An in-flight abort retires the FIFO host. */
+  signal?: AbortSignal;
 }
 
 interface PendingRequest {
+  abort?: () => void;
   kind: ResidentReplyKind;
   reject: (reason: Error) => void;
   resolve: (reply: Record<string, unknown>) => void;
+  settled: boolean;
+  signal?: AbortSignal;
+  timer: NodeJS.Timeout;
 }
 
 /**
@@ -49,10 +70,12 @@ export class ResidentTransformProcess {
   private readonly child: ChildProcess;
   private readonly reader: Interface;
   private readonly pending: PendingRequest[] = [];
+  private readonly requestTimeoutMs: number;
   private stderr = "";
   private failure: Error | undefined;
 
   public constructor(options: ResidentTransformProcessOptions) {
+    this.requestTimeoutMs = normalizeRequestTimeoutMs(options.requestTimeoutMs);
     // 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.
@@ -102,25 +125,68 @@ export class ResidentTransformProcess {
   public request(
     payload: Record<string, unknown>,
     kind: ResidentReplyKind,
+    options: ResidentTransformRequestOptions = {},
   ): Promise<Record<string, unknown>> {
     if (this.failure !== undefined) {
       return Promise.reject(this.failure);
     }
+    if (options.signal?.aborted) {
+      return Promise.reject(cancelledError(options.signal));
+    }
     const stdin = this.child.stdin;
     if (stdin === null || stdin.destroyed) {
       return Promise.reject(
         new Error("ttsc: resident transform host stdin is closed"),
       );
     }
+    let line: string;
+    try {
+      line = `${JSON.stringify(payload)}\n`;
+    } catch (error) {
+      return Promise.reject(asError(error));
+    }
     return new Promise<Record<string, unknown>>((resolve, reject) => {
-      const pending: PendingRequest = { kind, reject, resolve };
+      let pending!: PendingRequest;
+      pending = {
+        kind,
+        reject,
+        resolve,
+        settled: false,
+        signal: options.signal,
+        timer: setTimeout(() => this.timeout(pending), this.requestTimeoutMs),
+      };
+      pending.timer.unref();
+      if (options.signal !== undefined) {
+        pending.abort = () => this.cancel(pending, options.signal!);
+        options.signal.addEventListener("abort", pending.abort, { once: true });
+      }
       this.pending.push(pending);
-      stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
-        if (error) {
-          this.removePending(pending);
-          reject(error);
-        }
-      });
+      if (options.signal?.aborted) {
+        pending.abort!();
+        return;
+      }
+      try {
+        stdin.write(line, (error) => {
+          if (error === null || error === undefined || pending.settled) {
+            return;
+          }
+          this.settlePending(pending, error);
+          this.fail(
+            new Error(
+              `ttsc: resident transform host could not write a request: ${error.message}`,
+            ),
+          );
+        });
+      } catch (error) {
+        if (pending.settled) return;
+        const reason = asError(error);
+        this.settlePending(pending, reason);
+        this.fail(
+          new Error(
+            `ttsc: resident transform host could not write a request: ${reason.message}`,
+          ),
+        );
+      }
     });
   }
 
@@ -129,31 +195,23 @@ export class ResidentTransformProcess {
    * 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();
-    }
+    if (this.failure !== undefined) return;
+    // If the host already died, reject with its real exit error (stderr + exit
+    // code) rather than a bland "disposed" message.
+    this.fail(
+      this.child.exitCode !== null || this.child.signalCode !== null
+        ? this.exitError()
+        : new Error("ttsc: resident transform host disposed"),
+    );
   }
 
   private onLine(line: string): void {
+    if (this.failure !== undefined) return;
     const trimmed = line.trim();
     if (trimmed.length === 0) {
       return;
     }
-    const request = this.pending.shift();
+    const request = this.pending[0];
     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
@@ -179,7 +237,7 @@ export class ResidentTransformProcess {
           trimmed,
         )}`,
       );
-      request.reject(error);
+      this.settlePending(request, error);
       this.fail(error);
       return;
     }
@@ -189,7 +247,8 @@ export class ResidentTransformProcess {
       // line consumed exactly one slot — so only this request is corrupt; later
       // replies still pair correctly. Reject just this request instead of
       // failing the whole process.
-      request.reject(
+      this.settlePending(
+        request,
         new Error(
           `ttsc: resident transform host sent an invalid ${request.kind} reply: ${echoLine(
             trimmed,
@@ -198,32 +257,93 @@ export class ResidentTransformProcess {
       );
       return;
     }
-    request.resolve(reply);
+    this.settlePending(request, reply);
   }
 
   private onReaderClose(): void {
-    if (this.pending.length === 0) {
-      return;
-    }
-    this.rejectAll(this.failure ?? this.exitError());
+    if (this.failure === undefined) this.fail(this.exitError());
   }
 
   private fail(error: Error): void {
-    this.failure ??= error;
-    this.rejectAll(this.failure);
+    if (this.failure !== undefined) return;
+    this.failure = error;
+    this.rejectAll(error);
+    this.terminate();
   }
 
   private rejectAll(error: Error): void {
     while (this.pending.length !== 0) {
-      this.pending.shift()!.reject(error);
+      this.settlePending(this.pending[0]!, error);
     }
   }
 
-  private removePending(target: PendingRequest): void {
-    const index = this.pending.indexOf(target);
-    if (index !== -1) {
-      this.pending.splice(index, 1);
+  private settlePending(
+    pending: PendingRequest,
+    result: Error | Record<string, unknown>,
+  ): void {
+    if (pending.settled) return;
+    pending.settled = true;
+    const index = this.pending.indexOf(pending);
+    if (index !== -1) this.pending.splice(index, 1);
+    clearTimeout(pending.timer);
+    if (pending.signal !== undefined && pending.abort !== undefined) {
+      pending.signal.removeEventListener("abort", pending.abort);
     }
+    if (result instanceof Error) pending.reject(result);
+    else pending.resolve(result);
+  }
+
+  private timeout(pending: PendingRequest): void {
+    if (pending.settled) return;
+    const timeout = new Error(
+      `ttsc: resident transform request timed out after ${String(
+        this.requestTimeoutMs,
+      )} ms${stderrSuffix(this.stderr)}`,
+    );
+    this.settlePending(pending, timeout);
+    this.fail(
+      new Error(
+        `ttsc: resident transform host retired after another request timed out${stderrSuffix(
+          this.stderr,
+        )}`,
+      ),
+    );
+  }
+
+  private cancel(pending: PendingRequest, signal: AbortSignal): void {
+    if (pending.settled) return;
+    this.settlePending(pending, cancelledError(signal));
+    this.fail(
+      new Error(
+        `ttsc: resident transform host retired after another request was cancelled${abortDetail(
+          signal,
+        )}${stderrSuffix(this.stderr)}`,
+      ),
+    );
+  }
+
+  private terminate(): void {
+    const stdin = this.child.stdin;
+    if (stdin !== null && !stdin.destroyed) stdin.destroy();
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    try {
+      this.child.kill();
+    } catch {
+      // The host exited between the liveness check and termination.
+      return;
+    }
+    const force = setTimeout(() => {
+      if (this.child.exitCode !== null || this.child.signalCode !== null) {
+        return;
+      }
+      try {
+        this.child.kill("SIGKILL");
+      } catch {
+        // The host exited between the liveness check and the forced signal.
+      }
+    }, TERMINATION_GRACE_MS);
+    force.unref();
+    this.child.once("exit", () => clearTimeout(force));
   }
 
   private exitError(): Error {
@@ -242,6 +362,44 @@ export class ResidentTransformProcess {
   }
 }
 
+/** Validate and normalize the caller-visible resident request deadline. */
+export function normalizeRequestTimeoutMs(requestTimeoutMs?: number): number {
+  const value = requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMER_MS) {
+    throw new TypeError(
+      `ttsc: requestTimeoutMs must be an integer between 1 and ${String(MAX_TIMER_MS)}`,
+    );
+  }
+  return value;
+}
+
+function cancelledError(signal: AbortSignal): Error {
+  const error = new Error(
+    `ttsc: resident transform request cancelled${abortDetail(signal)}`,
+  );
+  error.name = "AbortError";
+  return error;
+}
+
+function abortDetail(signal: AbortSignal): string {
+  const reason = signal.reason;
+  if (reason === undefined) return "";
+  try {
+    return `: ${reason instanceof Error ? reason.message : String(reason)}`;
+  } catch {
+    return "";
+  }
+}
+
+function stderrSuffix(stderr: string): string {
+  const detail = stderr.trim();
+  return detail.length === 0 ? "" : `: ${detail}`;
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
 /**
  * Parse one reply line into a plain object, or `undefined` when the line is not
  * a JSON object. Invalid JSON, arrays, primitives, and `null` all yield

package/src/compiler/internal/runBuild.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { INTERNAL_SHADOW_FLAGS, TERMINAL_FLAGS } from "../../flags/schema";
+import { resolveFlagSpec } from "../../flags/schema";
 import {
   hasProjectPluginEntries,
   loadProjectPlugins,
@@ -26,6 +26,12 @@ import { outputText, spawnNative } from "./spawnNative";
 type RunBuildOptions = TtscBuildOptions & {
   skipDiagnosticsCheck?: boolean;
   forceListEmittedFiles?: boolean;
+  /**
+   * Receives selected native-plugin source roots after the project resolves.
+   * The watch launcher uses these roots to invalidate a sidecar when its Go
+   * implementation changes between rebuilds.
+   */
+  onWatchInputs?: (inputs: readonly string[]) => void;
   /**
    * Emit an external source map from the direct tsgo build lane even when the
    * project configures none. Set by the ttsx runtime builds so a served emit
@@ -80,15 +86,17 @@ function hasEnabledPassthroughFlag(
   const passthrough = options.passthrough ?? [];
   for (let i = 0; i < passthrough.length; i++) {
     const token = passthrough[i]!;
-    if (token.startsWith(`${flag}=`)) {
-      return token.slice(flag.length + 1).toLowerCase() !== "false";
+    // Identity, not spelling: the user forwards their own casing and ttsc must
+    // read `--DIAGNOSTICS` the way tsgo does.
+    if (resolveFlagSpec(token)?.name !== flag) continue;
+    const equalsIndex = token.indexOf("=");
+    if (equalsIndex !== -1) {
+      return token.slice(equalsIndex + 1).toLowerCase() !== "false";
     }
-    if (token === flag) {
-      if (i + 1 < passthrough.length && isBooleanLiteral(passthrough[i + 1]!)) {
-        return passthrough[i + 1]!.toLowerCase() !== "false";
-      }
-      return true;
+    if (i + 1 < passthrough.length && isBooleanLiteral(passthrough[i + 1]!)) {
+      return passthrough[i + 1]!.toLowerCase() !== "false";
     }
+    return true;
   }
   return false;
 }
@@ -188,8 +196,16 @@ function runBuildTimed(
   options: RunBuildOptions,
   timing: BuildTiming,
 ): TtscBuildResult {
+  const projectFree = runProjectFreeTerminalFlag(options);
+  if (projectFree !== null) return projectFree;
   const setupStartedAt = process.hrtime.bigint();
   const execution = resolveExecutionContext(options);
+  options.onWatchInputs?.(
+    execution.nativePlugins.flatMap((plugin) => [
+      plugin.source,
+      ...(plugin.contributors?.map((contributor) => contributor.source) ?? []),
+    ]),
+  );
   if (
     execution.nativePlugins.length > 0 ||
     execution.pluginSetupFailure !== undefined
@@ -313,9 +329,14 @@ function runBuildTimed(
   }
 
   const args = createTsgoBuildArgs(execution, buildOptions, {
+    // `--verbose` promises the emitted-file list on every lane, and the list
+    // only exists if tsgo is asked for it. ttsc adds the flag for itself here
+    // exactly as it does for `forceListEmittedFiles`, and strips the raw
+    // `TSFILE:` lines back out below.
     listEmittedFiles:
       buildOptions.emit !== false &&
-      buildOptions.forceListEmittedFiles === true,
+      (buildOptions.forceListEmittedFiles === true ||
+        buildOptions.quiet === false),
     noEmitOnError:
       buildOptions.emit !== false &&
       buildOptions.skipDiagnosticsCheck !== true &&
@@ -324,6 +345,62 @@ function runBuildTimed(
   return runTsgoBuild(execution, buildOptions, args);
 }
 
+/**
+ * Answer a forwarded terminal flag whose meaning precedes a project, when no
+ * project can be resolved.
+ *
+ * `ttsc --init` exists to write the starter `tsconfig.json`, and `ttsc --all` /
+ * `ttsc -?` only print tsgo's help — none of them needs a project, yet all
+ * three died in project resolution because that layer ran first and
+ * unconditionally. The classification is `FLAG_SCHEMA`'s (`terminal` +
+ * `projectFree`), so marking a further flag project-free needs no edit here.
+ *
+ * A resolvable project keeps the established lane untouched: the build path
+ * still forwards the flag with `-p <tsconfig>` from the project root, so `ttsc
+ * --init` inside an existing project still reports tsgo's TS5054 instead of
+ * writing a second config into the current directory. Returns `null` when this
+ * lane does not apply.
+ */
+function runProjectFreeTerminalFlag(
+  options: RunBuildOptions,
+): TtscBuildResult | null {
+  if (!forwardsProjectFreeTerminalTsgoFlag(options)) return null;
+  if (options.resolvedProject !== undefined) return null;
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  try {
+    readProjectConfig({
+      cwd,
+      projectRoot: options.projectRoot,
+      tsconfig: options.tsconfig,
+    });
+    return null;
+  } catch {
+    // Any resolution failure takes this branch, not only "not found": a
+    // malformed config and an explicitly named missing `-p` path are equally
+    // beside the point for a flag whose meaning does not presuppose a project.
+    // Forward it to tsgo from the invocation directory instead of failing.
+  }
+  const tsgo = resolveTsgo({ ...options, cwd });
+  const res = spawnNative(tsgo.binary, [...(options.passthrough ?? [])], {
+    cwd,
+    env: mergeEnv(options.env),
+    encoding: "utf8",
+  });
+  if (res.error) {
+    throw new Error(
+      `ttsc: failed to spawn ${tsgo.binary}: ${res.error.message}`,
+    );
+  }
+  return normalizeBuildOutput(
+    {
+      status: res.status ?? 1,
+      stdout: outputText(res.stdout),
+      stderr: outputText(res.stderr),
+    },
+    cwd,
+  );
+}
+
 /**
  * A tsconfig-level `noEmit: true` is an analysis-only build unless the user
  * explicitly asks `ttsc --emit` to override it. Treat it like CLI `--noEmit`
@@ -412,11 +489,17 @@ function createPluginFailureTypecheckOptions(
   const passthrough: string[] = [];
   for (let i = 0; i < (options.passthrough?.length ?? 0); i++) {
     const token = options.passthrough![i]!;
-    if (token === "--pretty") {
-      if (isBooleanLiteral(options.passthrough![i + 1] ?? "")) i++;
+    if (resolveFlagSpec(token)?.name === "--pretty") {
+      // `--pretty` is boolean: it owns a following token only when that token
+      // is the literal `true`/`false`, and the inline form carries its own.
+      if (
+        !token.includes("=") &&
+        isBooleanLiteral(options.passthrough![i + 1] ?? "")
+      ) {
+        i++;
+      }
       continue;
     }
-    if (token.startsWith("--pretty=")) continue;
     passthrough.push(token);
   }
   return {
@@ -509,31 +592,42 @@ function diagnosticHeadline(message: string): string {
 }
 
 /**
- * Tsgo CLI flags that make `tsgo` print something and exit instead of building
- * (`--showConfig`, `--listFilesOnly`, `--help`, …). ttsc must not add
- * build-only guard flags around these because the forwarded flag asks tsgo to
- * print something and exit instead of compiling the project.
+ * Report whether the caller forwarded a print-and-exit tsgo flag
+ * (`--showConfig`, `--listFilesOnly`, `--all`, `--init`, `-?`), so ttsc can
+ * avoid adding compile-only flags to a command that is not going to compile.
  *
- * Schema-derived: the set is computed from `FLAG_SCHEMA[*].terminal === true`,
- * not hand-maintained next to runBuild. Adding a new terminal flag now means
- * editing `schema.ts` and re-running `pnpm format` — every layer learns about
- * it automatically.
+ * Schema-derived, and resolved by flag identity rather than by exact spelling:
+ * `resolveFlagSpec` applies the one normalization the parsing engine and the
+ * generated Go allow-lists use, so `--showconfig` classifies exactly like
+ * `--showConfig`. Adding a new terminal flag means editing `schema.ts` and
+ * re-running `pnpm run gen:flags`; this predicate needs no edit, and it grows
+ * no normalization of its own for the next consumer to forget.
  */
-const TERMINAL_TSGO_FLAGS: ReadonlySet<string> = (() => {
-  // Mirror the legacy hand-list: schema's terminal flags ∪ the `-?` alias
-  // tsgo accepts (kept here because it is a tsgo synonym, not a ttsc flag).
-  const out = new Set<string>(TERMINAL_FLAGS);
-  out.add("-?");
-  return out;
-})();
+function forwardsTerminalTsgoFlag(options: TtscCommonOptions): boolean {
+  return (
+    options.passthrough?.some(
+      (token) => resolveFlagSpec(token)?.terminal === true,
+    ) ?? false
+  );
+}
 
 /**
- * Report whether the caller forwarded a print-and-exit tsgo flag, so ttsc can
- * avoid adding compile-only flags to a command that is not going to compile.
+ * Report whether the caller forwarded a terminal flag whose meaning does not
+ * presuppose a resolved project (`--init`, `--all`, `-?`).
+ *
+ * Derived from `FLAG_SCHEMA[*].projectFree`, through the same identity
+ * resolution as every other classification — never a literal list of flag names
+ * beside this branch, which is the shape that let terminal-flag awareness exist
+ * in one layer and be missing from the layer above it.
  */
-function forwardsTerminalTsgoFlag(options: TtscCommonOptions): boolean {
+function forwardsProjectFreeTerminalTsgoFlag(
+  options: TtscCommonOptions,
+): boolean {
   return (
-    options.passthrough?.some((flag) => TERMINAL_TSGO_FLAGS.has(flag)) ?? false
+    options.passthrough?.some((token) => {
+      const flag = resolveFlagSpec(token);
+      return flag?.terminal === true && flag.projectFree === true;
+    }) ?? false
   );
 }
 
@@ -553,18 +647,16 @@ function forwardsInternalShadowFlag(
   options: TtscCommonOptions,
   flag: string,
 ): boolean {
-  if (!INTERNAL_SHADOW_FLAGS.has(flag)) return false;
   const passthrough = options.passthrough;
   if (passthrough === undefined) return false;
-  // Match both the bare form (`--pretty`) and the inline-value form
-  // (`--pretty=true`). The launcher's parser preserves these shapes
-  // verbatim, so a tolerant prefix compare is what we want — `passthrough`
-  // never holds a stray substring that happens to start with the flag
-  // because parser positional/passthrough sinks split on whitespace.
-  const inlinePrefix = `${flag}=`;
-  return passthrough.some(
-    (token) => token === flag || token.startsWith(inlinePrefix),
-  );
+  // Resolution covers the bare form (`--pretty`), the inline-value form
+  // (`--pretty=true`), and every casing tsgo accepts (`--PRETTY`) — the
+  // launcher forwards the user's own spelling verbatim, so comparing raw
+  // strings would miss a spelling tsgo honours.
+  return passthrough.some((token) => {
+    const spec = resolveFlagSpec(token);
+    return spec?.internalShadow === true && spec.name === flag;
+  });
 }
 
 /**
@@ -676,12 +768,46 @@ function runTsgoBuild(
   if (emittedFiles.length !== 0 && !userListedEmitted) {
     result.stdout = stripEmittedFileLines(result.stdout);
   }
+  if (options.quiet === false) {
+    result.stdout += verboseBuildSummary(execution, options, emittedFiles);
+  }
   return normalizeBuildOutput(
     { ...result, emittedFiles },
     execution.projectRoot,
   );
 }
 
+/**
+ * The `--verbose` summary for the direct-tsgo lane, in the shape
+ * `cmd/ttsc/build.go` already prints on the native-host lane.
+ *
+ * Verbosity is a launcher-owned presentation concern: which lane `runBuild`
+ * selects is an implementation detail the user cannot see, so a documented flag
+ * must not change meaning with it. This lane never consumed `quiet` at all,
+ * which is why the flag was silent on every project without a ttsc plugin.
+ *
+ * `sites=0` is a fact about this lane rather than a placeholder: it runs
+ * precisely when the project declares no native plugin. A build that emitted
+ * nothing prints the header and `emitted=0 files`, so the summary never claims
+ * files that were not written.
+ */
+function verboseBuildSummary(
+  execution: ReturnType<typeof resolveExecutionContext>,
+  options: RunBuildOptions,
+  emittedFiles: readonly string[],
+): string {
+  const lines = [
+    `// ttsc: tsconfig=${execution.tsconfig} cwd=${execution.cwd} sites=0 emit=${options.emit !== false}`,
+  ];
+  if (options.emit !== false) {
+    lines.push(`// ttsc: emitted=${emittedFiles.length} files`);
+    for (const file of emittedFiles) {
+      lines.push(`  + ${path.relative(execution.cwd, file) || file}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 /** Build the argument list for a direct `tsgo` build invocation. */
 function createTsgoBuildArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
@@ -953,12 +1079,8 @@ function nativeTsgoPassthroughArgs(
 }
 
 function isDiagnosticsPassthroughFlag(token: string): boolean {
-  return (
-    token === "--diagnostics" ||
-    token.startsWith("--diagnostics=") ||
-    token === "--extendedDiagnostics" ||
-    token.startsWith("--extendedDiagnostics=")
-  );
+  const name = resolveFlagSpec(token)?.name;
+  return name === "--diagnostics" || name === "--extendedDiagnostics";
 }
 
 function isBooleanLiteral(token: string): boolean {