ttsc 0.12.3 → 0.13.0

package/src/launcher/internal/resolveCacheDir.ts

@@ -0,0 +1,19 @@
+import path from "node:path";
+
+/**
+ * Resolve a user-supplied `--cache-dir` value into an absolute path.
+ *
+ * When `cacheDir` is absent or empty, returns `undefined` so callers fall
+ * through to the environment variable and global-cache defaults handled inside
+ * `buildSourcePlugin`. When `cacheDir` is already absolute it is returned
+ * unchanged; otherwise it is resolved relative to `cwd`.
+ */
+export function resolveCacheDir(
+  cwd: string,
+  cacheDir?: string,
+): string | undefined {
+  if (!cacheDir) {
+    return undefined;
+  }
+  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
+}

package/src/launcher/internal/resolveTtscserverBinary.ts

@@ -47,5 +47,7 @@ function defaultLocalBinaryPath(): string | null {
 
 function packageRootDir(): string {
   const moduleDir = path.resolve(__dirname, "..", "..");
+  // Prefer the faster native variant; fall back to the JS implementation on
+  // platforms (or environments) where `realpathSync.native` is unavailable.
   return fs.realpathSync.native?.(moduleDir) ?? fs.realpathSync(moduleDir);
 }

package/src/launcher/internal/runTtsc.ts

@@ -8,10 +8,27 @@ import { resolveProjectConfig } from "../../compiler/internal/project/resolvePro
 import { resolveBinary } from "../../compiler/internal/resolveBinary";
 import { runBuild } from "../../compiler/internal/runBuild";
 import { runSingleFileEmit } from "../../compiler/internal/runSingleFileEmit";
+import {
+  getBoolean,
+  getNumber,
+  getString,
+  parseFlags,
+} from "../../flags/parser";
 import { defaultPluginCacheCleanTargets } from "../../plugin/internal/buildSourcePlugin";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import { getCompilerVersionText } from "./getCompilerVersionText";
-
+import { resolveCacheDir } from "./resolveCacheDir";
+
+/**
+ * CLI entry point for `ttsc`. Dispatches argv to the appropriate build lane
+ * (build, check, fix, format, prepare, clean, or native-delegate) and returns
+ * an exit code. Errors thrown by any lane are caught here and written to stderr
+ * so the process can exit cleanly.
+ *
+ * @param argv - Command-line arguments (defaults to `process.argv.slice(2)`).
+ * @returns The exit code: `0` on success, `1` on binary-not-found, `2` on user
+ *   error or build failure.
+ */
 export function runTtsc(
   argv: readonly string[] = process.argv.slice(2),
 ): number {
@@ -67,6 +84,12 @@ export function runTtsc(
   }
 }
 
+/**
+ * Return `true` when `command` looks like a build argument rather than a
+ * subcommand name — a flag (`-p`, `--watch`, …) or a TypeScript/config file
+ * path. These are forwarded to the build lane unchanged so users can write
+ * `ttsc -p tsconfig.json` without an explicit `build` subcommand.
+ */
 function isBuildAlias(command: string): boolean {
   if (command.startsWith("-")) return true;
   return [".json", ".ts", ".tsx", ".mts", ".cts"].some((ext) =>
@@ -265,141 +288,80 @@ function ensureExecutable(binary: string): void {
 }
 
 function parseProjectArgs(argv: readonly string[]) {
-  let cacheDir: string | undefined;
-  let cwd: string | undefined;
-  let tsconfig: string | undefined;
-
-  const rest = [...argv];
-  while (rest.length !== 0) {
-    const current = rest.shift()!;
-    switch (current) {
-      case "--cwd":
-        cwd = takeValue(current, rest);
-        break;
-      case "--cache-dir":
-        cacheDir = takeValue(current, rest);
-        break;
-      case "-p":
-      case "--tsconfig":
-      case "--project":
-        tsconfig = takeValue(current, rest);
-        break;
-      default:
-        if (current.startsWith("--cwd=")) {
-          cwd = current.slice("--cwd=".length);
-        } else if (current.startsWith("--cache-dir=")) {
-          cacheDir = current.slice("--cache-dir=".length);
-        } else if (current.startsWith("--tsconfig=")) {
-          tsconfig = current.slice("--tsconfig=".length);
-        } else if (current.startsWith("--project=")) {
-          tsconfig = current.slice("--project=".length);
-        } else {
-          throw new Error(`ttsc: unknown option ${current}`);
-        }
-        break;
-    }
-  }
-  return { cacheDir, cwd, tsconfig };
+  // `prepare` and `clean` are project-shaped commands. They share the same
+  // schema as the build lane; the engine forwards unknown flags as well as
+  // build-only flags (e.g. `--strict`) to the launcher's passthrough list
+  // so the legacy "unknown option" behaviour is no longer a separate trap
+  // (RC-3 + RC-4 prevention; see issue #125 §5 in the RCA).
+  const result = parseFlags({
+    argv,
+    errorPrefix: "ttsc:",
+    subcommand: "prepare",
+  });
+  return {
+    cacheDir: getString(result, "--cache-dir"),
+    cwd: getString(result, "--cwd"),
+    tsconfig: getString(result, "--tsconfig"),
+  };
 }
 
 function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
-  let binary: string | undefined;
-  let cacheDir: string | undefined;
-  let cwd: string | undefined;
-  let emit: boolean | undefined = checkOnly ? false : undefined;
-  const files: string[] = [];
-  let fix = false;
-  let format = false;
-  let outDir: string | undefined;
-  let preserveWatchOutput = false;
-  let quiet = true;
-  let tsconfig: string | undefined;
-  let watch = false;
-
-  const rest = [...argv];
-  while (rest.length !== 0) {
-    const current = rest.shift()!;
-    switch (current) {
-      case "--emit":
-        emit = true;
-        break;
-      case "--noEmit":
-        emit = false;
-        break;
-      case "--quiet":
-        quiet = true;
-        break;
-      case "--verbose":
-        quiet = false;
-        break;
-      case "-w":
-      case "--watch":
-        watch = true;
-        break;
-      case "--preserveWatchOutput":
-        preserveWatchOutput = true;
-        break;
-      case "--cwd":
-        cwd = takeValue(current, rest);
-        break;
-      case "--outDir":
-        outDir = takeValue(current, rest);
-        break;
-      case "-p":
-      case "--tsconfig":
-      case "--project":
-        tsconfig = takeValue(current, rest);
-        break;
-      case "--binary":
-        binary = takeValue(current, rest);
-        break;
-      case "--cache-dir":
-        cacheDir = takeValue(current, rest);
-        break;
-      default:
-        if (current.startsWith("--cwd=")) {
-          cwd = current.slice("--cwd=".length);
-        } else if (current.startsWith("--outDir=")) {
-          outDir = current.slice("--outDir=".length);
-        } else if (current === "-w") {
-          watch = true;
-        } else if (current.startsWith("--tsconfig=")) {
-          tsconfig = current.slice("--tsconfig=".length);
-        } else if (current.startsWith("--project=")) {
-          tsconfig = current.slice("--project=".length);
-        } else if (current.startsWith("--preserveWatchOutput=")) {
-          preserveWatchOutput =
-            current.slice("--preserveWatchOutput=".length) !== "false";
-        } else if (current.startsWith("--binary=")) {
-          binary = current.slice("--binary=".length);
-        } else if (current.startsWith("--cache-dir=")) {
-          cacheDir = current.slice("--cache-dir=".length);
-        } else if (current === "--verbose") {
-          quiet = false;
-        } else if (current.startsWith("-")) {
-          throw new Error(`ttsc: unknown option ${current}`);
-        } else {
-          files.push(current);
-        }
-        break;
-    }
-  }
+  const result = parseFlags({
+    argv,
+    errorPrefix: "ttsc:",
+    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.
+  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 files = result.positional.filter(looksLikeInputFile);
+  // Bare non-file positionals are flag values (e.g. the `es2020` in
+  // `--target es2020`). The engine left them in `positional` because the
+  // forwarded flag is unknown to the schema; route them back into
+  // passthrough so the user's pair reaches tsgo intact.
+  const trailingValues = result.positional.filter(
+    (token) => !looksLikeInputFile(token),
+  );
+  const passthrough = [...result.passthrough, ...trailingValues];
+
   return {
-    binary,
-    cacheDir,
-    cwd,
+    binary: getString(result, "--binary"),
+    cacheDir: getString(result, "--cache-dir"),
+    checkers: getNumber(result, "--checkers"),
+    cwd: getString(result, "--cwd"),
     emit,
     files,
-    fix,
-    format,
-    outDir,
-    preserveWatchOutput,
+    fix: false,
+    format: false,
+    outDir: getString(result, "--outDir"),
+    passthrough,
+    preserveWatchOutput: getBoolean(result, "--preserveWatchOutput") === true,
     quiet,
-    tsconfig,
-    watch,
+    singleThreaded: getBoolean(result, "--singleThreaded") === true,
+    tsconfig: getString(result, "--tsconfig"),
+    watch: getBoolean(result, "--watch") === true,
   };
 }
 
+/**
+ * Report whether a bare CLI token is a TypeScript source file ttsc should
+ * compile in single-file mode. Anything without a TypeScript source extension
+ * is treated as a forwarded flag value rather than an input file.
+ */
+function looksLikeInputFile(token: string): boolean {
+  return [".ts", ".tsx", ".mts", ".cts"].some((ext) => token.endsWith(ext));
+}
+
 function printHelp(): void {
   process.stdout.write(
     [
@@ -430,6 +392,11 @@ function printHelp(): void {
       "  --verbose              Print the build summary and emitted files",
       "  --binary <path>        Use an explicit tsgo binary",
       "  --cache-dir <dir>      Use this cache root for source-plugin builds",
+      "  --singleThreaded       Run TypeScript-Go single-threaded (one checker)",
+      "  --checkers <n>         Type-checker pool size (default: TypeScript-Go's)",
+      "",
+      "  Any other flag is forwarded to tsgo as-is, so tsgo compiler options",
+      "  such as --strict or --target work directly (e.g. ttsc --strict file.ts).",
       "",
       "Plugin contract:",
       "  ttsc reads compilerOptions.plugins from tsconfig.json.",
@@ -464,9 +431,12 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   });
   const text = runSingleFileEmit({
     binary: options.binary,
+    checkers: options.checkers,
     cwd,
     file,
     out,
+    passthrough: options.passthrough,
+    singleThreaded: options.singleThreaded,
     tsconfig: options.tsconfig,
   });
   if (!fs.existsSync(out)) {
@@ -588,8 +558,7 @@ function runWatch(
       tsconfig: options.tsconfig,
     }),
   );
-  const watchRoot = root;
-  const directories = collectWatchDirectories(watchRoot);
+  const directories = collectWatchDirectories(root);
   const watchers = directories.map((dir) =>
     fs.watch(dir, { persistent: true }, () => trigger()),
   );
@@ -652,13 +621,6 @@ function runWatch(
   return 0;
 }
 
-function resolveCacheDir(cwd: string, cacheDir?: string): string | undefined {
-  if (!cacheDir) {
-    return undefined;
-  }
-  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
-}
-
 function collectWatchDirectories(root: string): string[] {
   const out: string[] = [];
   const stack: string[] = [root];
@@ -682,14 +644,6 @@ function collectWatchDirectories(root: string): string[] {
   return out;
 }
 
-function takeValue(flag: string, rest: string[]): string {
-  const value = rest.shift();
-  if (!value) {
-    throw new Error(`ttsc: ${flag} requires a value`);
-  }
-  return value;
-}
-
 function formatError(error: unknown): string {
   if (error instanceof Error) {
     return error.message;

package/src/launcher/internal/runTtscserver.ts

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
-import * as os from "node:os";
+import os from "node:os";
 
 import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
 import { resolveTtscserverBinary } from "./resolveTtscserverBinary";
@@ -66,8 +66,16 @@ export function runTtscserver(
   return result.status ?? 1;
 }
 
+/**
+ * Build the environment for the native binary. When running in `--stdio` (LSP)
+ * mode the Go binary needs to know which tsgo binary to wrap; inject
+ * `TTSC_TSGO_BINARY` so the native host does not have to re-resolve it from
+ * inside a potentially different working directory. Skip injection when the
+ * caller already provided the variable or passed an explicit `--tsgo` option.
+ */
 function resolveTtscserverEnv(argv: readonly string[]): NodeJS.ProcessEnv {
   if (!argv.includes("--stdio")) {
+    // Non-LSP invocations (--version, --help) do not shell out to tsgo.
     return process.env;
   }
   if (process.env.TTSC_TSGO_BINARY || hasTsgoOption(argv)) {