ttsc 0.12.3 → 0.13.0

package/lib/compiler/internal/runBuild.js

@@ -6,15 +6,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runBuild = runBuild;
 exports.appendBuildOutput = appendBuildOutput;
 exports.normalizeBuildOutput = normalizeBuildOutput;
-const node_child_process_1 = require("node:child_process");
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const schema_1 = require("../../flags/schema");
 const loadProjectPlugins_1 = require("../../plugin/internal/loadProjectPlugins");
-const resolveProjectConfig_1 = require("./project/resolveProjectConfig");
+const readProjectConfig_1 = require("./project/readProjectConfig");
 const resolveBinary_1 = require("./resolveBinary");
 const resolveTsgo_1 = require("./resolveTsgo");
 const sharedHostHelpers_1 = require("./sharedHostHelpers");
-/** Merge spawn env without clobbering unrelated vars. */
+const spawnNative_1 = require("./spawnNative");
+/**
+ * Merge extra environment variables over `process.env`, always injecting
+ * `TTSC_NODE_BINARY` so child processes can re-invoke the same Node.js binary
+ * without searching `PATH`.
+ */
 function mergeEnv(extra) {
     const base = {
         ...process.env,
@@ -24,6 +28,12 @@ function mergeEnv(extra) {
         return base;
     return { ...base, ...extra };
 }
+/**
+ * Build the environment for a native plugin spawn. Injects `TTSC_TSGO_BINARY`
+ * and `TTSC_TTSX_BINARY` alongside the base env from `mergeEnv`. For
+ * transform-stage plugins, also passes `TTSC_LINKED_PLUGINS_JSON` containing
+ * any linked sources so they run inside the same process as the host plugin.
+ */
 function nativePluginEnv(extra, execution, plugin) {
     const env = mergeEnv({
         TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? execution.tsgo.binary,
@@ -39,54 +49,21 @@ function nativePluginEnv(extra, execution, plugin) {
     }
     return env;
 }
-function spawnBinary(binary, args, options) {
-    const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
-    if (!viaNode) {
-        ensureExecutable(binary);
-    }
-    return (0, node_child_process_1.spawnSync)(viaNode ? process.execPath : binary, viaNode ? [binary, ...args] : [...args], {
-        cwd: options.cwd,
-        env: options.env,
-        encoding: options.encoding,
-        maxBuffer: 1024 * 1024 * 256,
-        windowsHide: true,
-    });
-}
-function ensureExecutable(binary) {
-    if (process.platform === "win32") {
-        return;
-    }
-    try {
-        const mode = node_fs_1.default.statSync(binary).mode & 0o777;
-        if ((mode & 0o111) !== 0) {
-            return;
-        }
-        node_fs_1.default.chmodSync(binary, mode | 0o755);
-    }
-    catch {
-        /* keep the original spawn error path */
-    }
-}
-function outputText(value) {
-    if (value == null) {
-        return "";
-    }
-    return typeof value === "string" ? value : value.toString("utf8");
-}
 /**
  * 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.
  */
 function runBuild(options = {}) {
     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
@@ -103,31 +80,36 @@ function runBuild(options = {}) {
             }
             if (compilers.length !== 0) {
                 (0, sharedHostHelpers_1.assertSharedHostCompatibility)(compilers, "emit");
-                return appendBuildOutput(checked, buildWithNativeCompilerPlugins(options, execution, compilers));
+                return appendBuildOutput(checked, buildWithNativeCompilerPlugins(buildOptions, execution, compilers));
             }
-            return appendBuildOutput(checked, runTsgo(execution, ["--noEmit"], options));
+            if (checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins)) {
+                return checked;
+            }
+            return appendBuildOutput(checked, runTsgo(execution, ["--noEmit"], buildOptions));
         }
         let result;
         if (compilers.length !== 0) {
             (0, sharedHostHelpers_1.assertSharedHostCompatibility)(compilers, "emit");
-            result = appendBuildOutput(checked, buildWithNativeCompilerPlugins(options, execution, compilers));
+            result = appendBuildOutput(checked, 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
@@ -141,27 +123,102 @@ function runBuild(options = {}) {
             stderr: "",
         };
     }
-    if (options.emit !== false && options.skipDiagnosticsCheck !== true) {
-        const checked = runTsgo(execution, ["--noEmit"], options);
-        if (checked.status !== 0) {
-            return checked;
-        }
-    }
-    const args = createTsgoBuildArgs(execution, options, {
-        listEmittedFiles: options.emit !== false && options.forceListEmittedFiles === true,
+    const args = createTsgoBuildArgs(execution, buildOptions, {
+        listEmittedFiles: 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, execution) {
+    if (options.emit !== undefined || execution.projectNoEmit !== true) {
+        return options;
+    }
+    return { ...options, emit: false };
+}
+function checkPluginsReportTypeScriptDiagnostics(plugins) {
+    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 = (() => {
+    // 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(schema_1.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) {
+    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, flag) {
+    if (!schema_1.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));
+}
+/**
+ * Dispatch a build through the shared-host native plugin. The host plugin is
+ * the one that owns the process (non-linked); all other transform plugins ride
+ * inside it via the `--plugins-json` flag.
+ */
 function buildWithNativeCompilerPlugins(options, execution, plugins) {
     const host = (0, sharedHostHelpers_1.selectSharedHostPlugin)(plugins);
     return runNativePluginCommand(host, createNativeBuildArgs(execution, options, plugins), options, execution, "ttsc.build");
 }
+/**
+ * Run `tsgo -p <tsconfig> [extraArgs]` and return the normalized result. Used
+ * for the no-emit type-check pass that precedes file emission.
+ */
 function runTsgo(execution, extraArgs, options) {
-    const res = spawnBinary(execution.tsgo.binary, [
+    const res = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, [
         "-p",
         execution.tsconfig,
         ...extraArgs,
         ...createTsgoDiagnosticArgs(options),
+        ...createTsgoThreadingArgs(options),
+        ...(options.passthrough ?? []),
     ], {
         cwd: execution.projectRoot,
         env: mergeEnv(options.env),
@@ -175,12 +232,17 @@ function runTsgo(execution, extraArgs, options) {
     }
     return normalizeBuildOutput({
         status: res.status ?? 1,
-        stdout: outputText(res.stdout),
-        stderr: outputText(res.stderr),
+        stdout: (0, spawnNative_1.outputText)(res.stdout),
+        stderr: (0, spawnNative_1.outputText)(res.stderr),
     }, execution.projectRoot);
 }
+/**
+ * Run `tsgo` with the full emit arguments and parse `TSFILE:` lines from stdout
+ * into `emittedFiles`. The TSFILE lines are stripped before the result is
+ * returned so they do not appear in the user-facing output.
+ */
 function runTsgoBuild(execution, options, args) {
-    const res = spawnBinary(execution.tsgo.binary, args, {
+    const res = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, args, {
         cwd: execution.projectRoot,
         env: mergeEnv(options.env),
         encoding: "utf8",
@@ -193,19 +255,31 @@ function runTsgoBuild(execution, options, args) {
     }
     const result = {
         status: res.status ?? 1,
-        stdout: outputText(res.stdout),
-        stderr: outputText(res.stderr),
+        stdout: (0, spawnNative_1.outputText)(res.stdout),
+        stderr: (0, spawnNative_1.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({ ...result, emittedFiles }, execution.projectRoot);
 }
+/** Build the argument list for a direct `tsgo` build invocation. */
 function createTsgoBuildArgs(execution, options, flags) {
     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");
@@ -217,11 +291,51 @@ function createTsgoBuildArgs(execution, options, flags) {
         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) {
-    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) {
+    const args = [];
+    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. */
 function createNativeBuildArgs(execution, options, plugins) {
     const args = [
         options.emit === false ? "check" : "build",
@@ -232,21 +346,25 @@ function createNativeBuildArgs(execution, options, plugins) {
     if (options.emit === true) {
         args.push("--emit");
     }
-    else if (options.emit === false) {
-        args.push("--noEmit");
-    }
     if (options.outDir) {
         args.push("--outDir=" + node_path_1.default.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;
 }
-function createNativeCheckArgs(execution, options) {
+/** Build the argument list for a native plugin check/fix/format invocation. */
+function createNativeCheckArgs(execution, options, plugin) {
     const args = [
         nativeCheckSubcommand(options),
         "--tsconfig=" + execution.tsconfig,
@@ -262,8 +380,77 @@ function createNativeCheckArgs(execution, options) {
     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, plugin) {
+    if (!nativeHostAcceptsThreadingArgs(plugin))
+        return [];
+    const args = [];
+    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) {
+    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) {
+    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` /
@@ -277,6 +464,10 @@ function nativeCheckSubcommand(options) {
         return "fix";
     return "check";
 }
+/**
+ * Serialize the plugin list to a compact JSON string for `--plugins-json=`.
+ * Only the fields the native binary protocol requires are included.
+ */
 function serializeNativePlugins(plugins) {
     return JSON.stringify(plugins.map((plugin) => ({
         config: plugin.config,
@@ -284,6 +475,10 @@ function serializeNativePlugins(plugins) {
         stage: plugin.stage,
     })));
 }
+/**
+ * Run every check-stage plugin in order, short-circuiting on the first non-zero
+ * exit. Aggregates diagnostics and output across all check plugins.
+ */
 function runNativeCheckPlugins(options, execution) {
     let out = {
         diagnostics: [],
@@ -292,7 +487,7 @@ function runNativeCheckPlugins(options, execution) {
         stderr: "",
     };
     for (const plugin of execution.nativePlugins.filter((plugin) => plugin.stage === "check")) {
-        const result = runNativePluginCommand(plugin, createNativeCheckArgs(execution, options), options, execution, "ttsc.check");
+        const result = runNativePluginCommand(plugin, createNativeCheckArgs(execution, options, plugin), options, execution, "ttsc.check");
         out = appendBuildOutput(out, result);
         if (result.status !== 0) {
             return out;
@@ -300,8 +495,13 @@ function runNativeCheckPlugins(options, execution) {
     }
     return out;
 }
+/**
+ * Spawn a single native plugin binary with the given args and return the
+ * normalized build result. `label` is used in the thrown error message so the
+ * caller's context (e.g. `"ttsc.check"` or `"ttsc.build"`) is preserved.
+ */
 function runNativePluginCommand(plugin, args, options, execution, label) {
-    const res = spawnBinary(plugin.binary, args, {
+    const res = (0, spawnNative_1.spawnNative)(plugin.binary, args, {
         cwd: execution.projectRoot,
         env: nativePluginEnv(options.env, execution, plugin),
         encoding: "utf8",
@@ -311,10 +511,18 @@ function runNativePluginCommand(plugin, args, options, execution, label) {
     }
     return normalizeBuildOutput({
         status: res.status ?? 1,
-        stdout: outputText(res.stdout),
-        stderr: outputText(res.stderr),
+        stdout: (0, spawnNative_1.outputText)(res.stdout),
+        stderr: (0, spawnNative_1.outputText)(res.stderr),
     }, execution.projectRoot);
 }
+/**
+ * Merge two `TtscBuildResult` values into one.
+ *
+ * - `status`: the right status wins unless it is 0 (failure propagates).
+ * - `diagnostics`: concatenated left then right.
+ * - `emittedFiles`: right wins when present, otherwise left is kept.
+ * - `stdout`/`stderr`: concatenated left then right.
+ */
 function appendBuildOutput(left, right) {
     return normalizeBuildOutput({
         diagnostics: [...left.diagnostics, ...right.diagnostics],
@@ -324,33 +532,47 @@ function appendBuildOutput(left, right) {
         stderr: left.stderr + right.stderr,
     });
 }
+/**
+ * Resolve all runtime context needed for a build: cwd, tsconfig path, project
+ * root, tsgo binary location, and the loaded native plugin list. Centralised
+ * here so every code path in `runBuild` shares the same resolution logic.
+ */
 function resolveExecutionContext(options) {
     const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
-    const tsconfig = (0, resolveProjectConfig_1.resolveProjectConfig)({
+    const project = (0, readProjectConfig_1.readProjectConfig)({
         cwd,
+        projectRoot: options.projectRoot,
         tsconfig: options.tsconfig,
     });
-    const projectRoot = options.projectRoot
-        ? node_path_1.default.resolve(cwd, options.projectRoot)
-        : node_path_1.default.dirname(tsconfig);
+    const tsconfig = project.path;
+    const projectRoot = project.root;
     const tsgo = (0, resolveTsgo_1.resolveTsgo)({ ...options, cwd: projectRoot });
-    const fallbackBinary = (0, resolveBinary_1.resolveBinary)(options);
-    const loaded = (0, loadProjectPlugins_1.loadProjectPlugins)({
-        binary: fallbackBinary ?? "",
-        cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
-        cwd,
-        entries: options.plugins,
-        projectRoot,
-        tsconfig,
-    });
+    const hasPlugins = (0, loadProjectPlugins_1.hasProjectPluginEntries)(project, options.plugins);
+    const loaded = hasPlugins
+        ? (0, loadProjectPlugins_1.loadProjectPlugins)({
+            binary: (0, resolveBinary_1.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,
     };
 }
+/**
+ * Extract `TSFILE: <path>` lines from tsgo stdout and return the absolute
+ * paths. tsgo emits these when `--listEmittedFiles` is passed.
+ */
 function parseEmittedFiles(stdout) {
     const out = [];
     for (const line of stdout.split(/\r?\n/)) {
@@ -361,6 +583,10 @@ function parseEmittedFiles(stdout) {
     }
     return out;
 }
+/**
+ * Remove `TSFILE:` lines from tsgo stdout so they do not appear in the
+ * user-facing output after they have been parsed into `emittedFiles`.
+ */
 function stripEmittedFileLines(stdout) {
     return stdout
         .split(/\r?\n/)
@@ -368,6 +594,13 @@ function stripEmittedFileLines(stdout) {
         .join("\n")
         .replace(/\n+$/, "");
 }
+/**
+ * Normalise a raw spawn result into a `TtscBuildResult`.
+ *
+ * When `diagnostics` is absent they are parsed from the text output. When the
+ * process exited non-zero but stderr is empty and stdout is non-empty, stdout
+ * is moved to stderr so the error is visible to callers who only check stderr.
+ */
 function normalizeBuildOutput(result, cwd) {
     const diagnostics = result.diagnostics ?? parseCompilerDiagnostics(result, cwd);
     if (result.status === 0 || result.stderr.trim().length !== 0) {
@@ -384,6 +617,11 @@ function normalizeBuildOutput(result, cwd) {
         stderr: result.stdout,
     };
 }
+/**
+ * Parse structured diagnostics from the combined stderr+stdout text when the
+ * caller did not supply pre-parsed diagnostics. ANSI escape codes are stripped
+ * and `TSFILE:` / `Found N errors` summary lines are skipped.
+ */
 function parseCompilerDiagnostics(result, cwd) {
     const lines = stripAnsi(`${result.stderr}\n${result.stdout}`).split(/\r?\n/);
     const out = [];
@@ -407,6 +645,16 @@ function parseCompilerDiagnostics(result, cwd) {
     }
     return out;
 }
+/**
+ * Try to parse a single line as a TypeScript compiler diagnostic in one of
+ * three formats:
+ *
+ * - `file:line:col - category TSxxxx: message` (colon-separated, tsgo style)
+ * - `file(line,col): category TSxxxx: message` (paren style, classic tsc)
+ * - `category TSxxxx: message` (global, no file)
+ *
+ * Returns `null` when the line does not match any format.
+ */
 function parseDiagnosticLine(line, cwd) {
     const colonMatch = line.match(/^(.+):(\d+):(\d+)\s+-\s+(error|warning|suggestion|message)\s+([A-Z]+)?(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
     if (colonMatch) {
@@ -441,12 +689,21 @@ function parseDiagnosticLine(line, cwd) {
         messageText: globalMatch[4],
     };
 }
+/**
+ * Return an absolute file path. When `file` is already absolute it is returned
+ * unchanged; relative paths are resolved against `cwd` when available.
+ */
 function normalizeDiagnosticFile(file, cwd) {
     if (node_path_1.default.isAbsolute(file) || cwd === undefined) {
         return file;
     }
     return node_path_1.default.resolve(cwd, file);
 }
+/**
+ * Map a raw category string (`"error"`, `"warning"`, `"suggestion"`,
+ * `"message"`) to the canonical `ITtscCompilerDiagnostic.Category`. Any
+ * unrecognised value is coerced to `"error"`.
+ */
 function normalizeDiagnosticCategory(value) {
     const lowered = value.toLowerCase();
     return lowered === "warning" ||
@@ -455,9 +712,14 @@ function normalizeDiagnosticCategory(value) {
         ? lowered
         : "error";
 }
+/**
+ * Parse a diagnostic code as a number when it is all digits (TS numeric codes
+ * like `2322`), or keep it as a string for plugin-defined alphanumeric codes.
+ */
 function normalizeDiagnosticCode(value) {
     return /^\d+$/.test(value) ? Number(value) : value;
 }
+/** Strip ANSI escape sequences from `text` for line-by-line diagnostic parsing. */
 function stripAnsi(text) {
     return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
 }