ttsc 0.12.4 → 0.13.0

package/src/compiler/internal/runBuild.ts

@@ -1,12 +1,16 @@
 import path from "node:path";
 
-import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
+import { INTERNAL_SHADOW_FLAGS, TERMINAL_FLAGS } from "../../flags/schema";
+import {
+  hasProjectPluginEntries,
+  loadProjectPlugins,
+} from "../../plugin/internal/loadProjectPlugins";
 import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
-import { resolveProjectConfig } from "./project/resolveProjectConfig";
+import { readProjectConfig } from "./project/readProjectConfig";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
 import {
@@ -16,6 +20,11 @@ import {
 } from "./sharedHostHelpers";
 import { outputText, spawnNative } from "./spawnNative";
 
+type RunBuildOptions = TtscBuildOptions & {
+  skipDiagnosticsCheck?: boolean;
+  forceListEmittedFiles?: boolean;
+};
+
 /**
  * Merge extra environment variables over `process.env`, always injecting
  * `TTSC_NODE_BINARY` so child processes can re-invoke the same Node.js binary
@@ -61,24 +70,20 @@ function nativePluginEnv(
  * Run `ttsc` against a tsconfig. Returns once the binary exits so the CLI can
  * decide how to surface diagnostics. Does not throw on non-zero exit.
  */
-export function runBuild(
-  options: TtscBuildOptions & {
-    skipDiagnosticsCheck?: boolean;
-    forceListEmittedFiles?: boolean;
-  } = {},
-): TtscBuildResult {
+export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
   const execution = resolveExecutionContext(options);
+  const buildOptions = applyProjectNoEmit(options, execution);
   if (execution.nativePlugins.length > 0) {
     const compilers = execution.nativePlugins.filter(
       (plugin) => plugin.stage === "transform",
     );
-    const checked = runNativeCheckPlugins(options, execution);
+    const checked = runNativeCheckPlugins(buildOptions, execution);
     if (checked.status !== 0) {
       return checked;
     }
 
-    if (options.emit === false) {
-      if (options.format === true) {
+    if (buildOptions.emit === false) {
+      if (buildOptions.format === true) {
         // Format mode is write-only by contract: the lint sidecar
         // already rewrote source files and reported nothing. Running
         // tsgo --noEmit OR a transform compiler afterwards would either
@@ -97,12 +102,15 @@ export function runBuild(
         assertSharedHostCompatibility(compilers, "emit");
         return appendBuildOutput(
           checked,
-          buildWithNativeCompilerPlugins(options, execution, compilers),
+          buildWithNativeCompilerPlugins(buildOptions, execution, compilers),
         );
       }
+      if (checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins)) {
+        return checked;
+      }
       return appendBuildOutput(
         checked,
-        runTsgo(execution, ["--noEmit"], options),
+        runTsgo(execution, ["--noEmit"], buildOptions),
       );
     }
 
@@ -111,26 +119,30 @@ export function runBuild(
       assertSharedHostCompatibility(compilers, "emit");
       result = appendBuildOutput(
         checked,
-        buildWithNativeCompilerPlugins(options, execution, compilers),
+        buildWithNativeCompilerPlugins(buildOptions, execution, compilers),
       );
     } else {
-      if (options.skipDiagnosticsCheck !== true) {
-        const tsgoChecked = runTsgo(execution, ["--noEmit"], options);
+      if (
+        buildOptions.skipDiagnosticsCheck !== true &&
+        !checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins) &&
+        !forwardsTerminalTsgoFlag(buildOptions)
+      ) {
+        const tsgoChecked = runTsgo(execution, ["--noEmit"], buildOptions);
         if (tsgoChecked.status !== 0) {
           return appendBuildOutput(checked, tsgoChecked);
         }
       }
-      const args = createTsgoBuildArgs(execution, options, {
-        listEmittedFiles: options.forceListEmittedFiles === true,
+      const args = createTsgoBuildArgs(execution, buildOptions, {
+        listEmittedFiles: buildOptions.forceListEmittedFiles === true,
       });
-      const emitted = runTsgoBuild(execution, options, args);
+      const emitted = runTsgoBuild(execution, buildOptions, args);
       result = appendBuildOutput(checked, emitted);
     }
 
     return result;
   }
 
-  if (options.format === true) {
+  if (buildOptions.format === true) {
     // Format mode is write-only by contract — see the matching
     // short-circuit in the with-native-plugins branch above. When no
     // native plugin is loaded there is nothing for `ttsc format` to
@@ -145,18 +157,100 @@ export function runBuild(
     };
   }
 
-  if (options.emit !== false && options.skipDiagnosticsCheck !== true) {
-    const checked = runTsgo(execution, ["--noEmit"], options);
-    if (checked.status !== 0) {
-      return checked;
-    }
-  }
-
-  const args = createTsgoBuildArgs(execution, options, {
+  const args = createTsgoBuildArgs(execution, buildOptions, {
     listEmittedFiles:
-      options.emit !== false && options.forceListEmittedFiles === true,
+      buildOptions.emit !== false &&
+      buildOptions.forceListEmittedFiles === true,
+    noEmitOnError:
+      buildOptions.emit !== false &&
+      buildOptions.skipDiagnosticsCheck !== true &&
+      !forwardsTerminalTsgoFlag(buildOptions),
   });
-  return runTsgoBuild(execution, options, args);
+  return runTsgoBuild(execution, buildOptions, args);
+}
+
+/**
+ * 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`
+ * before composing tsgo/native-host arguments so ttsc does not add emit-only
+ * guards around projects that cannot emit.
+ */
+function applyProjectNoEmit(
+  options: RunBuildOptions,
+  execution: ReturnType<typeof resolveExecutionContext>,
+): RunBuildOptions {
+  if (options.emit !== undefined || execution.projectNoEmit !== true) {
+    return options;
+  }
+  return { ...options, emit: false };
+}
+
+function checkPluginsReportTypeScriptDiagnostics(
+  plugins: readonly ITtscLoadedNativePlugin[],
+): boolean {
+  return plugins.some(
+    (plugin) =>
+      plugin.stage === "check" && plugin.reportsTypeScriptDiagnostics === true,
+  );
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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;
+})();
+
+/**
+ * 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.
+ */
+function forwardsTerminalTsgoFlag(options: TtscCommonOptions): boolean {
+  return (
+    options.passthrough?.some((flag) => TERMINAL_TSGO_FLAGS.has(flag)) ?? false
+  );
+}
+
+/**
+ * Report whether the caller forwarded a flag ttsc adds to tsgo internally —
+ * e.g. `--listEmittedFiles` (ttsc adds it to learn emitted paths) or
+ * `--noEmit` (ttsc adds it for the pre-emit type-check). When the user
+ * also forwards the same flag, post-processing must keep the user-visible
+ * effect intact instead of stripping it as ttsc-internal noise.
+ *
+ * Schema-derived: `FLAG_SCHEMA[*].internalShadow === true`. RC-2 from the
+ * RCA (RCA section 3, `--listEmittedFiles` / `--showConfig` swallowed):
+ * the per-flag `passthrough.includes("…")` check is now one structural
+ * lookup against the schema, not one bespoke `if` per shadow flag.
+ */
+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),
+  );
 }
 
 /**
@@ -186,7 +280,7 @@ function buildWithNativeCompilerPlugins(
 function runTsgo(
   execution: ReturnType<typeof resolveExecutionContext>,
   extraArgs: readonly string[],
-  options: NonNullable<Parameters<typeof runBuild>[0]>,
+  options: RunBuildOptions,
 ): TtscBuildResult {
   const res = spawnNative(
     execution.tsgo.binary,
@@ -195,6 +289,8 @@ function runTsgo(
       execution.tsconfig,
       ...extraArgs,
       ...createTsgoDiagnosticArgs(options),
+      ...createTsgoThreadingArgs(options),
+      ...(options.passthrough ?? []),
     ],
     {
       cwd: execution.projectRoot,
@@ -227,7 +323,7 @@ function runTsgo(
  */
 function runTsgoBuild(
   execution: ReturnType<typeof resolveExecutionContext>,
-  options: NonNullable<Parameters<typeof runBuild>[0]>,
+  options: RunBuildOptions,
   args: readonly string[],
 ): TtscBuildResult {
   const res = spawnNative(execution.tsgo.binary, args, {
@@ -249,7 +345,18 @@ function runTsgoBuild(
     stderr: outputText(res.stderr),
   };
   const emittedFiles = parseEmittedFiles(result.stdout);
-  if (emittedFiles.length !== 0) {
+  // The `TSFILE:` lines are tsgo's `--listEmittedFiles` output. ttsc adds that
+  // flag internally to learn the emitted paths and strips the lines back out
+  // as noise — but when the user themselves forwarded `--listEmittedFiles`,
+  // the listing is what they asked for, so it must survive to stdout.
+  // The lookup is schema-driven (FLAG_SCHEMA marks `--listEmittedFiles` with
+  // `internalShadow: true`); see `forwardsInternalShadowFlag` for the RC-2
+  // background.
+  const userListedEmitted = forwardsInternalShadowFlag(
+    options,
+    "--listEmittedFiles",
+  );
+  if (emittedFiles.length !== 0 && !userListedEmitted) {
     result.stdout = stripEmittedFileLines(result.stdout);
   }
   return normalizeBuildOutput(
@@ -261,12 +368,15 @@ function runTsgoBuild(
 /** Build the argument list for a direct `tsgo` build invocation. */
 function createTsgoBuildArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
-  options: NonNullable<Parameters<typeof runBuild>[0]>,
-  flags: { listEmittedFiles: boolean },
+  options: RunBuildOptions,
+  flags: { listEmittedFiles: boolean; noEmitOnError?: boolean },
 ): string[] {
   const args = ["-p", execution.tsconfig];
   if (options.emit === true) {
     args.push("--noEmit", "false", "--emitDeclarationOnly", "false");
+    if (execution.rewriteRelativeImportExtensionsForEmit) {
+      args.push("--rewriteRelativeImportExtensions");
+    }
   } else if (options.emit === false) {
     args.push("--noEmit");
   }
@@ -277,15 +387,49 @@ function createTsgoBuildArgs(
     args.push("--listEmittedFiles");
   }
   args.push(...createTsgoDiagnosticArgs(options));
+  args.push(...createTsgoThreadingArgs(options));
+  args.push(...(options.passthrough ?? []));
+  if (flags.noEmitOnError === true) {
+    args.push("--noEmitOnError");
+  }
   return args;
 }
 
 /**
  * Return `["--pretty", "false"]` when structured diagnostics are requested so
  * that the output can be parsed line-by-line, or an empty array otherwise.
+ *
+ * When the user explicitly forwarded `--pretty` (any value), the internal
+ * `--pretty false` shadow is dropped so the user wins on the surface. ttsc's
+ * own diagnostic parser will then see pretty-formatted output and fall back
+ * to surfacing it verbatim — the RC-2 contract that `--pretty`'s
+ * `internalShadow: true` flag in `FLAG_SCHEMA` declares. Without this guard
+ * the order in `runTsgo` (internal flags first, passthrough last) would
+ * still let the user's `--pretty true` override at the tsgo level, but ttsc
+ * would have already committed to a structured-diagnostics post-process
+ * that no longer matches the actual output.
  */
 function createTsgoDiagnosticArgs(options: TtscCommonOptions): string[] {
-  return options.structuredDiagnostics === true ? ["--pretty", "false"] : [];
+  if (options.structuredDiagnostics !== true) return [];
+  if (forwardsInternalShadowFlag(options, "--pretty")) return [];
+  return ["--pretty", "false"];
+}
+
+/**
+ * Forward the `--singleThreaded` / `--checkers` knobs to a `tsgo` invocation.
+ * tsgo accepts both flags natively, so the no-plugin build lane only has to
+ * pass them through; the type-check and emit passes share this so the checker
+ * pool size stays consistent across both.
+ */
+function createTsgoThreadingArgs(options: TtscCommonOptions): string[] {
+  const args: string[] = [];
+  if (options.singleThreaded === true) {
+    args.push("--singleThreaded");
+  }
+  if (options.checkers !== undefined) {
+    args.push("--checkers", String(options.checkers));
+  }
+  return args;
 }
 
 /** Build the argument list for a native plugin `build`/`check` invocation. */
@@ -302,17 +446,21 @@ function createNativeBuildArgs(
   ];
   if (options.emit === true) {
     args.push("--emit");
-  } else if (options.emit === false) {
-    args.push("--noEmit");
   }
   if (options.outDir) {
     args.push("--outDir=" + path.resolve(execution.cwd, options.outDir));
   }
-  if (options.quiet === false) {
-    args.push("--verbose");
-  } else if (options.quiet === true) {
-    args.push("--quiet");
+  // Third-party transform hosts already treat the `check` subcommand as a
+  // quiet no-emit pass. Keep ttsc-owned build modifiers off that lane so older
+  // strict hosts do not reject unknown optional flags before analysis starts.
+  if (options.emit !== false) {
+    if (options.quiet === false) {
+      args.push("--verbose");
+    } else if (options.quiet === true) {
+      args.push("--quiet");
+    }
   }
+  args.push(...createNativeTsgoArgs(options));
   return args;
 }
 
@@ -320,6 +468,7 @@ function createNativeBuildArgs(
 function createNativeCheckArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
   options: TtscBuildOptions,
+  plugin: ITtscLoadedNativePlugin,
 ): string[] {
   const args = [
     nativeCheckSubcommand(options),
@@ -335,9 +484,85 @@ function createNativeCheckArgs(
   } else if (options.quiet === true) {
     args.push("--quiet");
   }
+  args.push(...createNativeCheckThreadingArgs(options, plugin));
+  args.push(...createNativeTsgoArgs(options));
+  return args;
+}
+
+// `--singleThreaded` / `--checkers` are forwarded to native check-stage hosts
+// only when the host is one ttsc itself owns (currently `@ttsc/lint`). #113
+// forwarded both flags as bare CLI tokens to every native sidecar, then
+// commit ad3443a reverted that across the board because a third-party host
+// built before #113 has no `singleThreaded` / `checkers` flag in its
+// `flag.FlagSet` and would exit 2 on the unknown flag — so
+// `ttsc --singleThreaded` failed deterministically on every typia/nestia
+// transform-plugin project.
+//
+// The performance ceiling that caused, though, is real: format/check passes
+// through the lint sidecar are dominated by parallel parse + parallel rule
+// walk, and with the threading knob silently dropped, MT and ST runs of
+// `ttsc format` produced identical wall-clock numbers — the benchmark cell
+// became a non-measurement. The lint sidecar is built and shipped from this
+// repo, accepts both flags via `parseSubcommandFlags`, and threads them down
+// to `loadProgram` (parse phase) and `engine.SetSerial` (rule walk). The host
+// is identified by name (`@ttsc/lint`) so a third-party check-stage plugin
+// keeps the strict-host behavior from ad3443a; only the host we control gets
+// the bare flag. Transform-stage hosts are never reached by this path
+// (they go through `createNativeBuildArgs`), so the typia/nestia regression
+// remains pinned by `test_plugin_corpus_single_threaded_flag_does_not_break_a_native_plugin_build`.
+function createNativeCheckThreadingArgs(
+  options: TtscCommonOptions,
+  plugin: ITtscLoadedNativePlugin,
+): string[] {
+  if (!nativeHostAcceptsThreadingArgs(plugin)) return [];
+  const args: string[] = [];
+  if (options.singleThreaded === true) {
+    args.push("--singleThreaded");
+  }
+  if (options.checkers !== undefined) {
+    args.push("--checkers=" + String(options.checkers));
+  }
   return args;
 }
 
+/**
+ * Return true when the loaded native check-stage host has declared
+ * `capabilities.threadingArgs` in its plugin descriptor.
+ *
+ * The lint sidecar (`packages/lint/src/index.ts::createTtscPlugin`) opts in
+ * because its `parseSubcommandFlags` handler accepts `--singleThreaded` and
+ * `--checkers` directly and threads them into `loadProgram` (parse phase)
+ * and `engine.SetSerial` (rule walk). Any other check-stage host that has
+ * not declared the capability is treated as a third-party binary whose flag
+ * set is unknown, matching the conservative default from commit ad3443a.
+ *
+ * The capability flag replaces the prior `plugin.name === "@ttsc/lint"`
+ * string check: routing on a descriptor field instead of the plugin name
+ * lets the next first-party check-stage plugin opt in without ttsc needing
+ * to learn its name. See `ITtscPluginCapabilities` and issue #125 for the
+ * broader CLI-parser cleanup this is the quick-win step of.
+ */
+function nativeHostAcceptsThreadingArgs(
+  plugin: ITtscLoadedNativePlugin,
+): boolean {
+  return plugin.capabilities?.threadingArgs === true;
+}
+
+/**
+ * Forward the tsgo flags ttsc did not recognize to a native sidecar as one
+ * JSON-encoded `--tsgo-args` flag. The sidecar replays them through tsgo's own
+ * option parser onto `CompilerOptions`, so a flag like `ttsc --strict` reaches
+ * a plugin build the same way it reaches the plain tsgo lane. Encoded as a
+ * single token so the sidecars' unknown-flag filters keep it intact.
+ */
+function createNativeTsgoArgs(options: TtscCommonOptions): string[] {
+  const passthrough = options.passthrough;
+  if (passthrough === undefined || passthrough.length === 0) {
+    return [];
+  }
+  return ["--tsgo-args=" + JSON.stringify(passthrough)];
+}
+
 /**
  * Decide which native plugin subcommand the lint sidecar should run for the
  * current `runBuild` invocation. The launcher selects exactly one of `fix` /
@@ -385,7 +610,7 @@ function runNativeCheckPlugins(
   )) {
     const result = runNativePluginCommand(
       plugin,
-      createNativeCheckArgs(execution, options),
+      createNativeCheckArgs(execution, options, plugin),
       options,
       execution,
       "ttsc.check",
@@ -458,30 +683,36 @@ export function appendBuildOutput(
  * here so every code path in `runBuild` shares the same resolution logic.
  */
 function resolveExecutionContext(
-  options: TtscCommonOptions & { tsconfig?: string },
+  options: TtscCommonOptions & { emit?: boolean; tsconfig?: string },
 ) {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  const tsconfig = resolveProjectConfig({
+  const project = readProjectConfig({
     cwd,
+    projectRoot: options.projectRoot,
     tsconfig: options.tsconfig,
   });
-  const projectRoot = options.projectRoot
-    ? path.resolve(cwd, options.projectRoot)
-    : path.dirname(tsconfig);
+  const tsconfig = project.path;
+  const projectRoot = project.root;
   const tsgo = resolveTsgo({ ...options, cwd: projectRoot });
-  const fallbackBinary = resolveBinary(options);
-  const loaded = loadProjectPlugins({
-    binary: fallbackBinary ?? "",
-    cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
-    cwd,
-    entries: options.plugins,
-    projectRoot,
-    tsconfig,
-  });
+  const hasPlugins = hasProjectPluginEntries(project, options.plugins);
+  const loaded = hasPlugins
+    ? loadProjectPlugins({
+        binary: resolveBinary(options) ?? "",
+        cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
+        cwd,
+        entries: options.plugins,
+        projectRoot,
+        tsconfig,
+      })
+    : { nativePlugins: [] };
   return {
     cwd,
     nativePlugins: loaded.nativePlugins,
+    projectNoEmit: project.compilerOptions.noEmit === true,
     projectRoot,
+    rewriteRelativeImportExtensionsForEmit:
+      options.emit === true &&
+      project.compilerOptions.allowImportingTsExtensions === true,
     tsgo,
     tsconfig,
   };