ttsc 0.19.3 → 0.20.0

package/src/launcher/internal/runTtsc.ts

@@ -12,6 +12,8 @@ import {
   getString,
   parseFlags,
 } from "../../flags/parser";
+import { resolveFlagSpec } from "../../flags/schema";
+import { assertSafeExplicitCacheDirectory } from "../../internal/assertSafeExplicitCacheDirectory";
 import {
   isPathWithin,
   legacyGlobalCacheTargets,
@@ -21,6 +23,7 @@ import {
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import { getCompilerVersionText } from "./getCompilerVersionText";
 import { resolveCacheDir } from "./resolveCacheDir";
+import { WatchTopology } from "./watchTopology";
 
 /**
  * CLI entry point for `ttsc`. Dispatches argv to the appropriate build lane
@@ -41,13 +44,17 @@ export function runTtsc(
     }
 
     const [command, ...rest] = argv as [string, ...string[]];
-    switch (command) {
-      case "-h":
+    // A leading flag is dispatched by its schema identity, so every spelling the
+    // compiler accepts (`--HELP`, `-Version`) reaches the same branch instead of
+    // falling through to the build lane where nothing reads it back out.
+    // `resolveFlagSpec` ignores dash-less tokens, so the bare `help` / `version`
+    // subcommand words below keep their own meaning.
+    const leadingFlag = resolveFlagSpec(command)?.name;
+    switch (leadingFlag ?? command) {
       case "--help":
       case "help":
         printHelp();
         return 0;
-      case "-v":
       case "--version":
       case "version":
         process.stdout.write(`${getCompilerVersionText()}\n`);
@@ -66,8 +73,7 @@ export function runTtsc(
         return runClean(rest);
       case "prepare":
         return runPrepare(rest);
-      case "-p":
-      case "--project":
+      case "--tsconfig":
         return runCompatibleBuild(argv, "build");
       default:
         if (isBuildAlias(command)) {
@@ -104,7 +110,7 @@ type TtscMode = "build" | "check" | "fix" | "format";
 
 function runCompatibleBuild(argv: readonly string[], mode: TtscMode): number {
   const checkOnly = mode !== "build";
-  const options = normalizeBuildOptions(parseBuildArgs(argv, checkOnly));
+  const options = normalizeBuildOptions(parseBuildArgs(argv));
   if (mode === "fix") {
     if (options.emit === true) {
       throw new Error("ttsc: fix and --emit are mutually exclusive");
@@ -132,16 +138,17 @@ function runCompatibleBuild(argv: readonly string[], mode: TtscMode): number {
     }
     return runWatch(options, checkOnly);
   }
-  if (options.files.length !== 0) {
+  const buildOptions = checkOnly ? { ...options, emit: false } : options;
+  if (buildOptions.files.length !== 0) {
     if (mode === "fix") {
       throw new Error("ttsc: fix requires a project, not single-file mode");
     }
     if (mode === "format") {
       throw new Error("ttsc: format requires a project, not single-file mode");
     }
-    return runSingleFile(options);
+    return runSingleFile(buildOptions);
   }
-  const result = runBuild(checkOnly ? { ...options, emit: false } : options);
+  const result = runBuild(buildOptions);
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   return result.status;
@@ -189,12 +196,18 @@ function runClean(argv: readonly string[]): number {
   const options = parseProjectArgs(argv);
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const projectRoot = resolveCleanProjectRoot(cwd, options.tsconfig);
-  const targets = options.cacheDir
+  const explicitCacheDir = options.cacheDir
+    ? path.resolve(cwd, options.cacheDir)
+    : undefined;
+  if (explicitCacheDir !== undefined) {
+    assertSafeExplicitCacheDirectory(projectRoot, explicitCacheDir);
+  }
+  const targets = explicitCacheDir
     ? // Explicit `ttsc clean --cache-dir X`: the user names X as the cache to
       // remove for this command, so remove it wholesale plus the legacy
       // project-local caches.
       [
-        path.resolve(cwd, options.cacheDir),
+        explicitCacheDir,
         path.join(projectRoot, "node_modules", ".ttsc"),
         path.join(projectRoot, ".ttsc"),
       ]
@@ -303,8 +316,14 @@ function parseCachePathsArgs(argv: readonly string[]): {
   const rest = [...argv];
   while (rest.length !== 0) {
     const token = rest.shift()!;
-    const [flag, inlineValue] = splitInlineFlag(token);
-    switch (flag) {
+    const [rawFlag, inlineValue] = splitInlineFlag(token);
+    const flag = resolveFlagSpec(rawFlag);
+    if (flag?.subcommands.includes("cache") !== true) {
+      throw new Error(
+        `ttsc: cache paths does not support ${JSON.stringify(token)}`,
+      );
+    }
+    switch (flag.name) {
       case "--json":
         if (inlineValue !== undefined) {
           throw new Error("ttsc: --json does not take a value");
@@ -312,15 +331,13 @@ function parseCachePathsArgs(argv: readonly string[]): {
         out.json = true;
         break;
       case "--cache-dir":
-        out.cacheDir = readCachePathsValue(flag, inlineValue, rest);
+        out.cacheDir = readCachePathsValue(flag.name, inlineValue, rest);
         break;
       case "--cwd":
-        out.cwd = readCachePathsValue(flag, inlineValue, rest);
+        out.cwd = readCachePathsValue(flag.name, inlineValue, rest);
         break;
-      case "-p":
-      case "--project":
       case "--tsconfig":
-        out.tsconfig = readCachePathsValue(flag, inlineValue, rest);
+        out.tsconfig = readCachePathsValue(flag.name, inlineValue, rest);
         break;
       default:
         throw new Error(
@@ -405,7 +422,7 @@ function parseProjectArgs(argv: readonly string[]) {
   };
 }
 
-function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
+function parseBuildArgs(argv: readonly string[]) {
   const result = parseFlags({
     argv,
     errorPrefix: "ttsc:",
@@ -418,17 +435,15 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
     subcommand: "build",
   });
   // Defaults: pinned by the previous hand-parser. `quiet` defaults true,
-  // `--verbose` flips it to false; `emit` defaults `undefined` in build
-  // mode (let tsconfig decide) and `false` in check/fix/format mode.
+  // `--verbose` flips it to false; `emit` defaults `undefined` so the resolved
+  // project controls ordinary build mode. `runCompatibleBuild` applies the
+  // check/fix/format no-emit decision before either execution lane runs.
   const verbose = getBoolean(result, "--verbose");
   const quietFlag = getBoolean(result, "--quiet");
   const quiet = verbose === true ? false : (quietFlag ?? true);
   const explicitEmit = getBoolean(result, "--emit");
   const explicitNoEmit = getBoolean(result, "--noEmit");
-  let emit: boolean | undefined;
-  if (explicitEmit === true) emit = true;
-  else if (explicitNoEmit === true) emit = false;
-  if (emit === undefined && checkOnly) emit = false;
+  const emit = resolveExplicitEmit(explicitEmit, explicitNoEmit);
 
   // `isPositional: looksLikeInputFile` guarantees every `result.positional`
   // token is a TypeScript input file; forwarded flag values already live in
@@ -457,6 +472,21 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   };
 }
 
+/**
+ * Collapse the two launcher-owned emit switches into the tri-state consumed by
+ * `runBuild` and the single-file lane. A specified boolean is significant even
+ * when it is `false`: `--emit=false` is analysis-only and `--noEmit=false`
+ * explicitly overrides a project's `noEmit`. `--emit` retains precedence when
+ * callers supply both switches, matching the legacy true-only resolution.
+ */
+function resolveExplicitEmit(
+  explicitEmit: boolean | undefined,
+  explicitNoEmit: boolean | undefined,
+): boolean | undefined {
+  if (explicitEmit !== undefined) return explicitEmit;
+  return explicitNoEmit === undefined ? undefined : !explicitNoEmit;
+}
+
 /**
  * Report whether a bare CLI token is a TypeScript source file ttsc should
  * compile in single-file mode. Anything without a TypeScript source extension
@@ -548,12 +578,15 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   }
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const file = path.resolve(cwd, options.files[0]!);
-  const out = resolveSingleFileOut({
-    cliOutDir: options.outDir,
-    cwd,
-    file,
-    tsconfig: options.tsconfig,
-  });
+  const emit = singleFileShouldEmit(options, cwd, file);
+  const out = emit
+    ? resolveSingleFileOut({
+        cliOutDir: options.outDir,
+        cwd,
+        file,
+        tsconfig: options.tsconfig,
+      })
+    : undefined;
   const text = runSingleFileEmit({
     binary: options.binary,
     checkers: options.checkers,
@@ -564,14 +597,37 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
     singleThreaded: options.singleThreaded,
     tsconfig: options.tsconfig,
   });
-  if (!fs.existsSync(out)) {
+  if (out !== undefined && !fs.existsSync(out)) {
     fs.mkdirSync(path.dirname(out), { recursive: true });
     fs.writeFileSync(out, text, "utf8");
   }
-  process.stdout.write(`${path.relative(cwd, out) || path.basename(out)}\n`);
+  if (out !== undefined) {
+    process.stdout.write(`${path.relative(cwd, out) || path.basename(out)}\n`);
+  }
   return 0;
 }
 
+/**
+ * Resolve the same effective emit decision used by the project lane before
+ * entering the single-file compatibility path. The compatibility path still
+ * emits into a private temporary directory to obtain transformed text and
+ * diagnostics, but only this boundary is allowed to write into the user's
+ * tree.
+ */
+function singleFileShouldEmit(
+  options: ReturnType<typeof parseBuildArgs>,
+  cwd: string,
+  file: string,
+): boolean {
+  if (options.emit !== undefined) return options.emit;
+  const project = readProjectConfig({
+    cwd,
+    file,
+    tsconfig: options.tsconfig,
+  });
+  return project.compilerOptions.noEmit !== true;
+}
+
 function resolveSingleFileOut(opts: {
   cliOutDir?: string;
   cwd: string;
@@ -672,9 +728,13 @@ function runWatch(
   checkOnly: boolean,
 ): number {
   const cwd = path.resolve(options.cwd ?? process.cwd());
+  let topology: WatchTopology | undefined;
   const invocation = {
-    ...options,
+    ...(checkOnly ? { ...options, emit: false } : options),
     cwd,
+    onWatchInputs: (inputs: readonly string[]) => {
+      topology?.setExtraInputs(inputs);
+    },
     quiet: true,
   };
   const root = path.dirname(
@@ -692,6 +752,7 @@ function runWatch(
 
   const runOnce = () => {
     running = true;
+    let completed = false;
     try {
       if (!options.preserveWatchOutput) {
         process.stdout.write("\x1bc");
@@ -717,6 +778,7 @@ function runWatch(
               return result.status;
             })();
       lastStatus = status;
+      completed = true;
       process.stdout.write(
         `[ttsc] ${status === 0 ? "watch build complete" : "watch build failed"}\n`,
       );
@@ -726,6 +788,19 @@ function runWatch(
       process.stdout.write(`[ttsc] watch build failed\n`);
     } finally {
       running = false;
+      if (completed) {
+        try {
+          // A filesystem event can arrive after the build reports completion
+          // but before this synchronous cleanup reaches its re-resolution.
+          // Notify for a membership change here as well, otherwise that new
+          // input is silently absorbed into the watch set without a rebuild.
+          topology?.refresh(true);
+        } catch (error) {
+          process.stderr.write(
+            `[ttsc] watch error on ${path.relative(cwd, root) || "."}: ${formatError(error)}\n`,
+          );
+        }
+      }
     }
     if (rerun) {
       rerun = false;
@@ -741,23 +816,20 @@ function runWatch(
     timer = setTimeout(runOnce, 60);
   };
 
-  const directories = collectWatchDirectories(root);
-  const watchers = directories.map((dir) => {
-    const watcher = fs.watch(dir, { persistent: true }, () => trigger());
-    // Without an error handler Node rethrows watcher errors as uncaught
-    // exceptions, which would crash the session. inotify limits (ENOSPC) and
-    // transient FS errors should be logged while the session stays alive.
-    watcher.on("error", (err) => {
+  topology = new WatchTopology(invocation, {
+    onError: (location, error) => {
       process.stderr.write(
-        `[ttsc] watch error on ${path.relative(cwd, dir) || "."}: ${formatError(err)}\n`,
+        `[ttsc] watch error on ${path.relative(cwd, location) || "."}: ${formatError(error)}\n`,
       );
-    });
-    return watcher;
+    },
+    onInputChange: trigger,
+    onTopologyChange: trigger,
   });
+  topology.refresh(false);
 
   const close = () => {
     if (timer) clearTimeout(timer);
-    for (const watcher of watchers) watcher.close();
+    topology?.close();
   };
   process.on("SIGINT", () => {
     close();
@@ -789,29 +861,6 @@ function toExitCode(status: number): number {
   return Number.isInteger(status) && status >= 0 && status <= 255 ? status : 1;
 }
 
-function collectWatchDirectories(root: string): string[] {
-  const out: string[] = [];
-  const stack: string[] = [root];
-  while (stack.length !== 0) {
-    const current = stack.pop()!;
-    out.push(current);
-    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-      if (
-        entry.name === "node_modules" ||
-        entry.name === ".git" ||
-        entry.name === "lib" ||
-        entry.name === "dist"
-      ) {
-        continue;
-      }
-      if (entry.isDirectory()) {
-        stack.push(path.join(current, entry.name));
-      }
-    }
-  }
-  return out;
-}
-
 function formatError(error: unknown): string {
   if (error instanceof Error) {
     return error.message;

package/src/launcher/internal/runTtsx.ts

@@ -7,8 +7,10 @@ import {
   getBoolean,
   getNumber,
   getString,
+  getStringList,
   parseFlags,
 } from "../../flags/parser";
+import { resolveFlagSpec } from "../../flags/schema";
 import { getCompilerVersionText } from "./getCompilerVersionText";
 import { prepareExecution } from "./prepareExecution";
 import { resolveCacheDir } from "./resolveCacheDir";
@@ -98,26 +100,23 @@ function parseCLI(argv: readonly string[]) {
   // tokens (entry file + flag values that aren't `.ts`) and a passthrough
   // list mirroring the pre-schema behaviour.
   //
-  // Order pin: ttsx accepts `-P` as an alias for `--project`. The schema
-  // declares `-p` for ttsc; ttsx's lowercase shape would collide on `-p`
-  // → `--tsconfig`, so the legacy `-P` (uppercase) is treated as `--project`
-  // via a manual rewrite before the engine sees argv. We preserve the
-  // historical behaviour and emit a structural error otherwise.
-  const rewritten = argv.map((token) =>
-    token === "-P"
-      ? "--project"
-      : token.startsWith("-P=")
-        ? `--project=${token.slice("-P=".length)}`
-        : token,
-  );
+  // The legacy uppercase `-P` spelling ttsx has always accepted needs no
+  // rewrite: the engine resolves a token to the flag the compiler resolves it
+  // to, so `-P` and `-P=<file>` reach `--tsconfig` by the same rule that makes
+  // `-p` reach it. A textual pre-rewrite here would be a second rule for a job
+  // the engine owns.
+  //
   // Terminal flags (--help / --version) short-circuit before parsing so
-  // ttsx prints help text even when the entry file is missing.
-  for (const token of rewritten) {
-    if (token === "-h" || token === "--help") return "help" as const;
-    if (token === "-v" || token === "--version") return "version" as const;
+  // ttsx prints help text even when the entry file is missing. Resolved
+  // through the schema so every spelling the compiler accepts (`--HELP`,
+  // `-Version`) reaches the same branch.
+  for (const token of argv) {
+    const flag = resolveFlagSpec(token)?.name;
+    if (flag === "--help") return "help" as const;
+    if (flag === "--version") return "version" as const;
   }
   const result = parseFlags({
-    argv: rewritten,
+    argv,
     errorPrefix: "ttsx:",
     forwardAfterFirstPositional: true,
     honorDoubleDashSeparator: true,
@@ -145,34 +144,20 @@ function parseCLI(argv: readonly string[]) {
   // which MUST NOT reach tsgo.
   const postEntryArgs: string[] = [...result.tail];
 
-  const preload: string[] = [];
-  // `--require` accepts repeated values; the schema engine writes the
-  // LAST one into `values`, so reconstruct the full list by scanning the
-  // raw argv. Mirrors the legacy parser's `preload.push(takeValue(...))`
-  // behaviour.
+  // `--require` is declared `repeatable`, so the engine records every accepted
+  // value in argv order and the launcher reads the list straight off the parse
+  // result.
   //
-  // Stop the rescue scan at the first token that begins tail mode —
-  // either the entry file or the `--` separator. Without this guard,
-  // `ttsx entry.ts -r preload.cjs` would BOTH preload `preload.cjs` AND
-  // forward `-r preload.cjs` to the entry's argv, double-effecting the
-  // module load. The schema engine already routes post-entry tokens to
-  // `result.tail`; the rescue scan must respect the same boundary.
-  const scanEnd = rewritten.findIndex(
-    (token) => looksLikeEntryFile(token) || token === "--",
-  );
-  const scanLimit = scanEnd === -1 ? rewritten.length : scanEnd;
-  for (let i = 0; i < scanLimit; i += 1) {
-    const token = rewritten[i]!;
-    if (token === "-r" || token === "--require") {
-      const value = rewritten[i + 1];
-      if (value !== undefined && !value.startsWith("-")) {
-        preload.push(value);
-        i += 1;
-      }
-    } else if (token.startsWith("--require=")) {
-      preload.push(token.slice("--require=".length));
-    }
-  }
+  // This replaces a second, hand-written scan over raw argv that re-derived the
+  // pre-entry boundary with `looksLikeEntryFile`. Applied to raw tokens that
+  // predicate cannot tell an entry from a `--require` value carrying a
+  // TypeScript extension, nor from an inline `--require=<x>.ts` token, so the
+  // scan stopped before the tokens it existed to collect and preloads were
+  // dropped silently. The engine already owns that boundary:
+  // `forwardAfterFirstPositional` routes every post-entry token to
+  // `result.tail` without parsing it, so `ttsx entry.ts -r preload.cjs` still
+  // forwards the pair to the program instead of preloading it.
+  const preload = getStringList(result, "--require");
 
   return {
     binary: getString(result, "--binary"),

package/src/launcher/internal/runtimeHooks.ts

@@ -1,6 +1,11 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
-import { Module, registerHooks, stripTypeScriptTypes } from "node:module";
+import {
+  Module,
+  isBuiltin,
+  registerHooks,
+  stripTypeScriptTypes,
+} from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -294,7 +299,10 @@ function resolve(
 ): ResolveResult {
   try {
     return rememberCommonJsNamedInterop(
-      nextResolve(specifier, context),
+      restoreStrippedNodeBuiltinScheme(
+        specifier,
+        nextResolve(specifier, context),
+      ),
       context,
     );
   } catch (error) {
@@ -309,6 +317,26 @@ function resolve(
   }
 }
 
+/**
+ * Restore a `node:` builtin URL when affected Node releases return the exact
+ * prefix-stripped spelling from their synchronous CommonJS resolver.
+ *
+ * Every other result passes through unchanged. In particular, a user hook that
+ * intentionally remaps a `node:` specifier to another URL retains ownership of
+ * that mapping, while ordinary and ESM builtin results already carrying the
+ * scheme avoid an unnecessary copy.
+ */
+export function restoreStrippedNodeBuiltinScheme(
+  specifier: string,
+  result: ResolveResult,
+): ResolveResult {
+  return isBuiltin(specifier) &&
+    specifier.startsWith("node:") &&
+    result.url === specifier.slice("node:".length)
+    ? { ...result, url: specifier }
+    : result;
+}
+
 /** Cache of built projects keyed by owning tsconfig path. */
 interface BuiltProject {
   emitDir: string;