ttsc 0.30.3 → 0.31.0

package/lib/compiler/internal/runBuild.js

@@ -1,1694 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResidentCheckWatchSession = void 0;
-exports.runBuild = runBuild;
-exports.planResidentCheckEntries = planResidentCheckEntries;
-exports.bufferResidentCheckEntryRequests = bufferResidentCheckEntryRequests;
-exports.takeResidentCheckEntryRequest = takeResidentCheckEntryRequest;
-exports.residentCheckRequest = residentCheckRequest;
-exports.mergeProjectInputSnapshots = mergeProjectInputSnapshots;
-exports.parseProjectInputSnapshot = parseProjectInputSnapshot;
-exports.isAbsoluteLocalProjectInputPath = isAbsoluteLocalProjectInputPath;
-exports.appendBuildOutput = appendBuildOutput;
-exports.createProcessDiagnostic = createProcessDiagnostic;
-exports.normalizeBuildOutput = normalizeBuildOutput;
-const node_path_1 = __importDefault(require("node:path"));
-const schema_1 = require("../../flags/schema");
-const projectInputPathIdentity_1 = require("../../internal/projectInputPathIdentity");
-const resolveNodeBinary_1 = require("../../internal/resolveNodeBinary");
-const loadProjectPlugins_1 = require("../../plugin/internal/loadProjectPlugins");
-const createNativeProjectContextArgs_1 = require("./project/createNativeProjectContextArgs");
-const readProjectConfig_1 = require("./project/readProjectConfig");
-const residentCheckProcess_1 = require("./residentCheckProcess");
-const resolveBinary_1 = require("./resolveBinary");
-const resolveTsgo_1 = require("./resolveTsgo");
-const sharedHostHelpers_1 = require("./sharedHostHelpers");
-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, cwd = process.cwd()) {
-    const env = {
-        ...process.env,
-        ...extra,
-    };
-    const node = (0, resolveNodeBinary_1.resolveNodeBinary)(env, cwd);
-    if (node === undefined)
-        delete env.TTSC_NODE_BINARY;
-    else
-        env.TTSC_NODE_BINARY = node;
-    return env;
-}
-function createBuildTiming(options) {
-    return {
-        enabled: hasDiagnosticsFlag(options),
-        lines: [],
-        startedAt: process.hrtime.bigint(),
-    };
-}
-function hasDiagnosticsFlag(options) {
-    return (hasEnabledPassthroughFlag(options, "--diagnostics") ||
-        hasEnabledPassthroughFlag(options, "--extendedDiagnostics"));
-}
-function hasEnabledPassthroughFlag(options, flag) {
-    const passthrough = options.passthrough ?? [];
-    for (let i = 0; i < passthrough.length; i++) {
-        const token = passthrough[i];
-        // Identity, not spelling: the user forwards their own casing and ttsc must
-        // read `--DIAGNOSTICS` the way tsgo does.
-        if ((0, schema_1.resolveFlagSpec)(token)?.name !== flag)
-            continue;
-        const equalsIndex = token.indexOf("=");
-        if (equalsIndex !== -1) {
-            return token.slice(equalsIndex + 1).toLowerCase() !== "false";
-        }
-        if (i + 1 < passthrough.length && isBooleanLiteral(passthrough[i + 1])) {
-            return passthrough[i + 1].toLowerCase() !== "false";
-        }
-        return true;
-    }
-    return false;
-}
-function recordTiming(timing, label, startedAt) {
-    if (!timing.enabled)
-        return;
-    timing.lines.push(`${label}: ${formatTimingSeconds(hrtimeMs(startedAt))}`);
-}
-function appendTimingOutput(result, timing) {
-    if (!timing.enabled)
-        return result;
-    const lines = [
-        ...timing.lines,
-        `ttsc total time: ${formatTimingSeconds(hrtimeMs(timing.startedAt))}`,
-    ];
-    return {
-        ...result,
-        stdout: appendStdout(result.stdout, lines.join("\n") + "\n"),
-    };
-}
-function appendStdout(stdout, text) {
-    if (stdout.length === 0 || stdout.endsWith("\n"))
-        return stdout + text;
-    return `${stdout}\n${text}`;
-}
-function hrtimeMs(startedAt) {
-    return Number(process.hrtime.bigint() - startedAt) / 1e6;
-}
-function formatTimingSeconds(ms) {
-    return `${(ms / 1000).toFixed(3)}s`;
-}
-/**
- * Build the environment for a native plugin spawn. Injects `TTSC_TSGO_BINARY`
- * and `TTSC_TTSX_BINARY` alongside the base env from `mergeEnv`, plus
- * `TTSC_PLUGIN_CONFIG_DIR` when the caller declared a plugin config anchor (an
- * embedder compiling through a generated wrapper tsconfig) so config-file
- * discovery walks the real project instead of the wrapper's temp-dir ancestry.
- * 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, tsgoArgs) {
-    const env = mergeEnv({
-        ...(execution.pluginConfigDir === undefined
-            ? {}
-            : { TTSC_PLUGIN_CONFIG_DIR: execution.pluginConfigDir }),
-        TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? execution.tsgo.binary,
-        TTSC_TTSX_BINARY: process.env.TTSC_TTSX_BINARY ??
-            node_path_1.default.join(__dirname, "..", "..", "launcher", "ttsx.js"),
-        ...extra,
-    }, execution.projectRoot);
-    // Forwarded tsgo argv is per-invocation state this host owns, exactly like
-    // the config anchor below: publish this run's payload, or drop whatever an
-    // ancestor ttsc process left behind when this lane forwards nothing.
-    if (tsgoArgs !== undefined) {
-        env[sharedHostHelpers_1.TSGO_ARGS_ENV] = tsgoArgs;
-    }
-    else {
-        (0, sharedHostHelpers_1.clearInheritedTsgoArgs)(env, extra);
-    }
-    (0, sharedHostHelpers_1.clearInheritedSemanticConfigPath)(env, extra);
-    // The anchor is per-invocation state owned by this host: when this run
-    // declared none (and the caller's env does not name one), drop any value
-    // inherited from an ancestor ttsc process so a nested build never
-    // mis-anchors its plugins at the outer project.
-    if (execution.pluginConfigDir === undefined &&
-        extra?.TTSC_PLUGIN_CONFIG_DIR === undefined) {
-        delete env.TTSC_PLUGIN_CONFIG_DIR;
-    }
-    if (plugin?.stage === "transform") {
-        const linked = (0, sharedHostHelpers_1.linkedTransformPlugins)(execution.nativePlugins);
-        if (linked.length !== 0) {
-            env.TTSC_LINKED_PLUGINS_JSON = serializeNativePlugins(linked);
-        }
-    }
-    return env;
-}
-/**
- * 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 timing = createBuildTiming(options);
-    const result = runBuildTimed(options, timing);
-    return appendTimingOutput(result, timing);
-}
-/**
- * Analysis-only watch coordinator.
- *
- * The selected project and compatible check-stage processes stay resident
- * across ordinary source/data edits. A config, root-set, contributor, or plugin
- * topology transition calls for a full reset before the next cycle. Emit and
- * transform lanes can pass through the coordinator, but compatibility checks
- * keep them on the established one-shot path without starting sidecars.
- */
-class ResidentCheckWatchSession {
-    execution;
-    pendingChanges = new Map();
-    projectInputs;
-    processes = new Map();
-    async run(options, change = {}) {
-        if (change.reload === true)
-            this.reset();
-        const timing = createBuildTiming(options);
-        const projectFree = runProjectFreeTerminalFlag(options);
-        if (projectFree !== null) {
-            this.reset();
-            return appendTimingOutput(projectFree, timing);
-        }
-        let execution = this.execution;
-        const reusedExecution = execution !== undefined;
-        let buildOptions;
-        if (execution === undefined) {
-            const setupStartedAt = process.hrtime.bigint();
-            execution = resolveExecutionContext(options);
-            const discoveryOptions = this.captureProjectInputs(options);
-            const prepared = prepareBuildExecution(discoveryOptions, timing, execution, setupStartedAt);
-            buildOptions = prepared.buildOptions;
-            if (prepared.result !== undefined) {
-                this.reset();
-                return appendTimingOutput(prepared.result, timing);
-            }
-            if (!residentCheckExecutionIsCompatible(buildOptions, execution)) {
-                this.reset();
-                return appendTimingOutput(runPreparedBuild(options, timing, execution, buildOptions), timing);
-            }
-            this.execution = execution;
-        }
-        else {
-            buildOptions = applyProjectNoEmit(options, execution);
-        }
-        if (reusedExecution &&
-            this.refreshProjectInputTopology(options, execution)) {
-            this.reset();
-            return this.run(options);
-        }
-        const checked = await this.runCheckPlugins(buildOptions, execution, timing, change);
-        let result;
-        if (checked.status !== 0) {
-            result = appendTypeScriptDiagnosticsAfterPluginFailure(checked, buildOptions, execution);
-        }
-        else if (checkPluginsReportTypeScriptDiagnostics(execution.nativePlugins)) {
-            result = checked;
-        }
-        else {
-            result = appendBuildOutput(checked, runTsgo(execution, ["--noEmit"], buildOptions));
-        }
-        return appendTimingOutput(result, timing);
-    }
-    /** Terminate every sidecar and discard the cached selection context. */
-    dispose() {
-        this.reset();
-    }
-    reset() {
-        for (const process of this.processes.values())
-            process.dispose();
-        this.processes.clear();
-        this.pendingChanges.clear();
-        this.execution = undefined;
-        this.projectInputs = undefined;
-    }
-    captureProjectInputs(options) {
-        const onProjectInputs = options.onProjectInputs;
-        if (onProjectInputs === undefined)
-            return options;
-        return {
-            ...options,
-            onProjectInputs: (snapshot) => {
-                this.projectInputs = snapshot;
-                onProjectInputs(snapshot);
-            },
-        };
-    }
-    refreshProjectInputTopology(options, execution) {
-        if (options.onProjectInputs === undefined)
-            return false;
-        const next = discoverNativeProjectInputs(options, execution);
-        const changed = this.projectInputs !== undefined &&
-            !projectInputSnapshotsEqual(this.projectInputs, next);
-        this.projectInputs = next;
-        options.onProjectInputs(next);
-        return changed;
-    }
-    async runCheckPlugins(options, execution, timing, change) {
-        let out = {
-            diagnostics: [],
-            status: 0,
-            stderr: "",
-            stdout: "",
-        };
-        const tsgoArgs = createNativeTsgoArgs(options);
-        const checks = planResidentCheckEntries(execution.nativePlugins, (plugin) => createNativeCheckArgs(execution, options, plugin), tsgoArgs);
-        const request = residentCheckRequest(change, execution.projectRoot);
-        // Buffer the cycle for every resident plugin before running any of them.
-        // An earlier plugin may fail and short-circuit diagnostics, but a later
-        // sidecar must still receive every filesystem transition when it resumes.
-        bufferResidentCheckEntryRequests(this.pendingChanges, checks, request);
-        for (const { args, entryIndex, key, plugin } of checks) {
-            let result;
-            if (key === undefined) {
-                result = runNativePluginCommand(plugin, args, options, execution, "ttsc.check", timing, `ttsc check plugin ${plugin.name} time`, tsgoArgs);
-            }
-            else {
-                const startedAt = process.hrtime.bigint();
-                let resident = this.processes.get(key);
-                if (resident === undefined) {
-                    resident = new residentCheckProcess_1.ResidentCheckProcess({
-                        args: ["check-serve", ...args.slice(1)],
-                        binary: plugin.binary,
-                        cwd: execution.projectRoot,
-                        env: nativePluginEnv(options.env, execution, plugin, tsgoArgs),
-                    });
-                    this.processes.set(key, resident);
-                }
-                try {
-                    const reply = await resident.request(takeResidentCheckEntryRequest(this.pendingChanges, entryIndex));
-                    result = normalizeBuildOutput({
-                        status: reply.status,
-                        stderr: reply.stderr,
-                        stdout: reply.stdout,
-                    }, execution.projectRoot);
-                }
-                catch {
-                    resident.dispose();
-                    this.processes.delete(key);
-                    // The one-shot fallback observes the complete current filesystem,
-                    // and a later sidecar starts cold, so neither needs old deltas.
-                    // A capability-aware host may still disappear or violate framing.
-                    // Preserve correctness by running the established one-shot command
-                    // for this cycle; the next cycle gets one clean respawn attempt.
-                    result = runNativePluginCommand(plugin, args, options, execution, "ttsc.check", { ...timing, enabled: false }, "");
-                }
-                recordTiming(timing, `ttsc check plugin ${plugin.name} time`, startedAt);
-            }
-            out = appendBuildOutput(out, result);
-            if (result.status !== 0)
-                return out;
-        }
-        return out;
-    }
-}
-exports.ResidentCheckWatchSession = ResidentCheckWatchSession;
-function projectInputSnapshotsEqual(left, right) {
-    const leftReloadFiles = left.reloadFiles ?? [];
-    const rightReloadFiles = right.reloadFiles ?? [];
-    const leftReloadDirectories = left.reloadDirectories ?? [];
-    const rightReloadDirectories = right.reloadDirectories ?? [];
-    return (left.root === right.root &&
-        left.files.length === right.files.length &&
-        left.globs.length === right.globs.length &&
-        leftReloadDirectories.length === rightReloadDirectories.length &&
-        leftReloadFiles.length === rightReloadFiles.length &&
-        left.files.every((value, index) => value === right.files[index]) &&
-        left.globs.every((value, index) => value === right.globs[index]) &&
-        leftReloadDirectories.every((value, index) => value === rightReloadDirectories[index]) &&
-        leftReloadFiles.every((value, index) => value === rightReloadFiles[index]));
-}
-function residentCheckExecutionIsCompatible(options, execution) {
-    return (options.emit === false &&
-        options.fix !== true &&
-        options.format !== true &&
-        forwardsTerminalTsgoFlag(options) === false &&
-        execution.nativePlugins.every((plugin) => plugin.stage === "check"));
-}
-function residentCheckProcessKey(plugin, args, tsgoArgs) {
-    return `${plugin.binary}\0${plugin.name}\0${JSON.stringify(args)}\0${tsgoArgs ?? ""}`;
-}
-/**
- * Plan every configured check entry while sharing resident processes only by
- * binary/name/argument identity.
- */
-function planResidentCheckEntries(plugins, createArgs, 
-// Part of the process identity even though it never appears in argv: the
-// forwarded tsgo payload rides the environment, and a resident process holds
-// the compiler options it was started with. Two cycles that forward different
-// flags must not share one warm Program.
-tsgoArgs) {
-    return plugins
-        .filter((candidate) => candidate.stage === "check")
-        .map((plugin, entryIndex) => {
-        const args = createArgs(plugin);
-        return {
-            args,
-            entryIndex,
-            key: plugin.capabilities?.residentCheck === true
-                ? residentCheckProcessKey(plugin, args, tsgoArgs)
-                : undefined,
-            plugin,
-        };
-    });
-}
-/** Retain one complete change stream per configured resident check entry. */
-function bufferResidentCheckEntryRequests(pending, checks, request) {
-    for (const check of checks) {
-        if (check.key === undefined)
-            continue;
-        pending.set(check.entryIndex, mergeResidentCheckRequests(pending.get(check.entryIndex), request));
-    }
-}
-/** Consume exactly one configured entry's buffered request. */
-function takeResidentCheckEntryRequest(pending, entryIndex) {
-    const request = pending.get(entryIndex);
-    if (request === undefined) {
-        throw new Error(`ttsc: resident check entry ${String(entryIndex)} has no buffered request`);
-    }
-    pending.delete(entryIndex);
-    return request;
-}
-function residentCheckRequest(change, cwd) {
-    const normalize = (values) => [...new Set(values?.map((value) => node_path_1.default.resolve(cwd, value)) ?? [])].sort();
-    const changed = normalize(change.changed);
-    const external = normalize(change.external);
-    return {
-        ...(change.invalidate === true ? { invalidate: true } : {}),
-        ...(changed.length === 0 ? {} : { changed }),
-        ...(external.length === 0 ? {} : { external }),
-    };
-}
-function mergeResidentCheckRequests(previous, current) {
-    const merge = (left, right) => [...new Set([...(left ?? []), ...(right ?? [])])].sort();
-    const changed = merge(previous?.changed, current.changed);
-    const external = merge(previous?.external, current.external);
-    return {
-        ...(changed.length === 0 ? {} : { changed }),
-        ...(external.length === 0 ? {} : { external }),
-        ...(previous?.invalidate === true || current.invalidate === true
-            ? { invalidate: true }
-            : {}),
-    };
-}
-function runBuildTimed(options, timing) {
-    const projectFree = runProjectFreeTerminalFlag(options);
-    if (projectFree !== null)
-        return projectFree;
-    const setupStartedAt = process.hrtime.bigint();
-    const execution = resolveExecutionContext(options);
-    return runBuildWithExecution(options, timing, execution, setupStartedAt);
-}
-function runBuildWithExecution(options, timing, execution, setupStartedAt) {
-    const prepared = prepareBuildExecution(options, timing, execution, setupStartedAt);
-    if (prepared.result !== undefined)
-        return prepared.result;
-    return runPreparedBuild(options, timing, execution, prepared.buildOptions);
-}
-function prepareBuildExecution(options, timing, execution, setupStartedAt) {
-    if (execution.nativePlugins.length > 0 ||
-        execution.pluginSetupFailure !== undefined) {
-        recordTiming(timing, "ttsc plugin setup time", setupStartedAt);
-    }
-    const buildOptions = applyProjectNoEmit(options, execution);
-    if (execution.pluginSetupFailure !== undefined) {
-        return {
-            buildOptions,
-            result: appendTypeScriptDiagnosticsAfterPluginFailure(execution.pluginSetupFailure, buildOptions, execution),
-        };
-    }
-    if (options.onProjectInputs !== undefined) {
-        options.onProjectInputs(discoverNativeProjectInputs(options, execution));
-    }
-    return { buildOptions };
-}
-function runPreparedBuild(options, timing, execution, buildOptions) {
-    if (execution.nativePlugins.length > 0) {
-        const compilers = execution.nativePlugins.filter((plugin) => plugin.stage === "transform");
-        const checked = runNativeCheckPlugins(buildOptions, execution, timing);
-        if (checked.status !== 0) {
-            return appendTypeScriptDiagnosticsAfterPluginFailure(checked, buildOptions, execution);
-        }
-        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
-                // surface unrelated type errors as if they were format failures
-                // (tsgo path) or apply transform-stage rewrites on top of the
-                // formatted source (transform path), both of which break the
-                // documented "ttsc format only formats" guarantee. The
-                // short-circuit fires before either branch so format mode is a
-                // single concern regardless of how many compilers the project
-                // configures. Callers that want a recheck or a transform pass
-                // after format should run `ttsc check` / `ttsc build` as a
-                // separate invocation.
-                return checked;
-            }
-            if (compilers.length !== 0) {
-                (0, sharedHostHelpers_1.assertSharedHostCompatibility)(compilers, "emit");
-                const compiled = buildWithNativeCompilerPlugins(buildOptions, execution, compilers, timing);
-                const result = appendBuildOutput(checked, compiled);
-                return compiled.status === 0
-                    ? result
-                    : appendTypeScriptDiagnosticsAfterPluginFailure(result, buildOptions, execution);
-            }
-            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");
-            const compiled = buildWithNativeCompilerPlugins(buildOptions, execution, compilers, timing);
-            result = appendBuildOutput(checked, compiled);
-            if (compiled.status !== 0) {
-                result = appendTypeScriptDiagnosticsAfterPluginFailure(result, buildOptions, execution);
-            }
-        }
-        else {
-            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, buildOptions, {
-                listEmittedFiles: buildOptions.forceListEmittedFiles === true,
-            });
-            const emitted = runTsgoBuild(execution, buildOptions, args);
-            result = appendBuildOutput(checked, emitted);
-        }
-        return result;
-    }
-    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
-        // rewrite, so emit an empty success result rather than falling
-        // through to a tsgo pass that would surface unrelated type errors
-        // as if they were format failures.
-        return {
-            diagnostics: [],
-            status: 0,
-            stdout: "",
-            stderr: "",
-        };
-    }
-    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.quiet === false),
-        noEmitOnError: buildOptions.emit !== false &&
-            buildOptions.skipDiagnosticsCheck !== true &&
-            !forwardsTerminalTsgoFlag(buildOptions),
-    });
-    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) {
-    if (!forwardsProjectFreeTerminalTsgoFlag(options))
-        return null;
-    if (options.resolvedProject !== undefined)
-        return null;
-    const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
-    try {
-        (0, readProjectConfig_1.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 = (0, resolveTsgo_1.resolveTsgo)({ ...options, cwd });
-    const res = (0, spawnNative_1.spawnNative)(tsgo.binary, [...(options.passthrough ?? [])], {
-        cwd,
-        env: mergeEnv(options.env, cwd),
-        encoding: "utf8",
-    });
-    if (res.error) {
-        throw new Error(`ttsc: failed to spawn ${tsgo.binary}: ${res.error.message}`);
-    }
-    return normalizeBuildOutput({
-        status: res.status ?? 1,
-        stdout: (0, spawnNative_1.outputText)(res.stdout),
-        stderr: (0, spawnNative_1.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`
- * 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);
-}
-/**
- * Preserve a failed plugin's output and status while collecting TypeScript
- * diagnostics through an independent no-emit pass.
- *
- * A sidecar can fail before it loads the project Program, including when a Go
- * panic or another runtime error terminates the process. The plugin failure
- * must still block emit, but it must not hide unrelated errors in the user's
- * TypeScript source. The fallback runs only after a plugin failure, skips modes
- * whose contract intentionally omits diagnostics, and avoids appending a batch
- * the plugin already reported itself.
- */
-function appendTypeScriptDiagnosticsAfterPluginFailure(failure, options, execution) {
-    if (options.format === true ||
-        options.skipDiagnosticsCheck === true ||
-        forwardsTerminalTsgoFlag(options)) {
-        return failure;
-    }
-    const typechecked = runTsgo(execution, ["--noEmit"], createPluginFailureTypecheckOptions(options));
-    const fallback = filterReportedTypeScriptDiagnostics(failure, typechecked, execution.projectRoot);
-    if (fallback === null) {
-        return failure;
-    }
-    // Structured consumers (the public API's `IFailure.diagnostics`) never see
-    // stdout/stderr, so a plugin failure that reported no parsable diagnostics
-    // must be seeded as one before recovered TypeScript diagnostics are appended
-    // — otherwise the recovery would replace the plugin error with unrelated
-    // type errors instead of surfacing both.
-    const seeded = failure.diagnostics.length === 0
-        ? { ...failure, diagnostics: [createProcessDiagnostic(failure)] }
-        : failure;
-    const status = failure.status;
-    return {
-        ...appendBuildOutput(seeded, fallback),
-        status,
-    };
-}
-/**
- * Make the recovery pass parseable regardless of the user's display flags. This
- * is an internal second pass, so plain output is required to remove only
- * diagnostics that the failed plugin already printed.
- */
-function createPluginFailureTypecheckOptions(options) {
-    const passthrough = [];
-    for (let i = 0; i < (options.passthrough?.length ?? 0); i++) {
-        const token = options.passthrough[i];
-        if ((0, schema_1.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;
-        }
-        passthrough.push(token);
-    }
-    return {
-        ...options,
-        passthrough,
-        structuredDiagnostics: true,
-    };
-}
-/** Return only fallback diagnostics the failed plugin did not already report. */
-function filterReportedTypeScriptDiagnostics(failure, typechecked, cwd) {
-    if (typechecked.diagnostics.length === 0) {
-        return typechecked.status === 0 ? null : typechecked;
-    }
-    const diagnostics = typechecked.diagnostics.filter((diagnostic) => !failure.diagnostics.some((existing) => compilerDiagnosticsEqual(existing, diagnostic)));
-    if (diagnostics.length === 0)
-        return null;
-    if (diagnostics.length === typechecked.diagnostics.length)
-        return typechecked;
-    return {
-        ...typechecked,
-        diagnostics,
-        stderr: filterCompilerDiagnosticText(typechecked.stderr, diagnostics, cwd),
-        stdout: filterCompilerDiagnosticText(typechecked.stdout, diagnostics, cwd),
-    };
-}
-/** Remove diagnostic lines absent from the selected structured result. */
-function filterCompilerDiagnosticText(text, diagnostics, cwd) {
-    const out = [];
-    let keepContinuation = true;
-    for (const line of text.split(/\r?\n/)) {
-        const plain = stripAnsi(line);
-        const diagnostic = parseDiagnosticLine(plain, cwd);
-        if (diagnostic !== null) {
-            keepContinuation = diagnostics.some((selected) => compilerDiagnosticsEqual(selected, diagnostic));
-            if (keepContinuation)
-                out.push(line);
-            continue;
-        }
-        if (/^Found\s+\d+\s+errors?/i.test(plain))
-            continue;
-        if (!keepContinuation && /^\s+/.test(line))
-            continue;
-        keepContinuation = true;
-        out.push(line);
-    }
-    return out.join("\n");
-}
-/** Compare normalized compiler diagnostics before appending fallback output. */
-function compilerDiagnosticsEqual(left, right) {
-    return (left.category === right.category &&
-        left.code === right.code &&
-        left.file === right.file &&
-        diagnosticPositionsEqual(left, right) &&
-        diagnosticHeadline(left.messageText) ===
-            diagnosticHeadline(right.messageText));
-}
-/** Compare offsets when available, otherwise compare rendered line/column. */
-function diagnosticPositionsEqual(left, right) {
-    if (left.start !== undefined && right.start !== undefined) {
-        return left.start === right.start;
-    }
-    return left.line === right.line && left.character === right.character;
-}
-/** Remove pretty-rendered source context from a diagnostic message. */
-function diagnosticHeadline(message) {
-    return message.split(/\r?\n/, 1)[0].trim();
-}
-/**
- * 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, 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.
- */
-function forwardsTerminalTsgoFlag(options) {
-    return (options.passthrough?.some((token) => (0, schema_1.resolveFlagSpec)(token)?.terminal === true) ?? false);
-}
-/**
- * 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 forwardsProjectFreeTerminalTsgoFlag(options) {
-    return (options.passthrough?.some((token) => {
-        const flag = (0, schema_1.resolveFlagSpec)(token);
-        return flag?.terminal === true && flag.projectFree === true;
-    }) ?? 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) {
-    const passthrough = options.passthrough;
-    if (passthrough === undefined)
-        return false;
-    // 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 = (0, schema_1.resolveFlagSpec)(token);
-        return spec?.internalShadow === true && spec.name === flag;
-    });
-}
-/**
- * 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, timing) {
-    const host = (0, sharedHostHelpers_1.selectSharedHostPlugin)(plugins);
-    return runNativePluginCommand(host, createNativeBuildArgs(execution, options, plugins), options, execution, "ttsc.build", timing, transformHostTimingLabel(plugins), createNativeBuildTsgoArgs(execution, options));
-}
-/**
- * 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 = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, [
-        "-p",
-        execution.tsconfig,
-        ...extraArgs,
-        ...createTsgoDiagnosticArgs(options),
-        ...createTsgoThreadingArgs(options),
-        ...(options.passthrough ?? []),
-    ], {
-        cwd: execution.projectRoot,
-        env: mergeEnv(options.env, execution.projectRoot),
-        encoding: "utf8",
-    });
-    if (res.error) {
-        throw new Error("ttsc: failed to spawn " +
-            execution.tsgo.binary +
-            ": " +
-            res.error.message);
-    }
-    return normalizeBuildOutput({
-        status: res.status ?? 1,
-        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 = (0, spawnNative_1.spawnNative)(execution.tsgo.binary, args, {
-        cwd: execution.projectRoot,
-        env: mergeEnv(options.env, execution.projectRoot),
-        encoding: "utf8",
-    });
-    if (res.error) {
-        throw new Error("ttsc.build: failed to spawn " +
-            execution.tsgo.binary +
-            ": " +
-            res.error.message);
-    }
-    const result = {
-        status: res.status ?? 1,
-        stdout: (0, spawnNative_1.outputText)(res.stdout),
-        stderr: (0, spawnNative_1.outputText)(res.stderr),
-    };
-    const emittedFiles = parseEmittedFiles(result.stdout);
-    // 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);
-    }
-    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, options, emittedFiles) {
-    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(`  + ${node_path_1.default.relative(execution.cwd, file) || file}`);
-        }
-    }
-    return `${lines.join("\n")}\n`;
-}
-/** 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");
-        }
-        // The ttsx runtime build asks for an external map when the project emits
-        // none, so its served emit carries a map to inline under the source URL.
-        // Pushed before passthrough so an explicit user `--sourceMap` still wins.
-        if (options.forceRuntimeSourceMap === true) {
-            args.push("--sourceMap", "true");
-        }
-        // Pushed before passthrough for the same reason: a user `--rootDir` still
-        // wins over the value ttsc pins for its own injected `outDir`.
-        args.push(...pinnedRootDirArgs(execution, options));
-    }
-    else if (options.emit === false) {
-        args.push("--noEmit");
-    }
-    if (options.outDir) {
-        args.push("--outDir", node_path_1.default.resolve(execution.cwd, options.outDir));
-    }
-    if (flags.listEmittedFiles) {
-        args.push("--listEmittedFiles");
-    }
-    args.push(...createTsgoDiagnosticArgs(options));
-    args.push(...createTsgoThreadingArgs(options));
-    args.push(...(options.passthrough ?? []));
-    args.push(...isolatedTsgoOutputArgs(options));
-    if (flags.noEmitOnError === true) {
-        args.push("--noEmitOnError");
-    }
-    return args;
-}
-/**
- * The explicit `--rootDir` a caller-injected `outDir` needs, or nothing.
- *
- * See {@link RunBuildOptions.pinInferredRootDir} for why an injected `outDir`
- * needs one at all. Three conditions gate it, and each one is load-bearing:
- *
- * - The caller injected the `outDir` itself, so a user `--outDir` keeps tsgo's
- *   own TS5011 answer;
- * - This pass emits, because a no-emit pass has no layout to pin (tsgo skips the
- *   check for `noEmit` too);
- * - The project declares no `rootDir` of its own, so a declared layout is never
- *   overridden.
- *
- * `execution.projectRoot` is the directory of the tsconfig ttsc resolved and
- * hands tsgo as `-p`, which is exactly the directory tsgo infers, and it is
- * spelled the way tsgo will spell the input file names it compares against it —
- * both come from the same `fs.realpathSync` pass. Resolving it any further (a
- * Windows 8.3 expansion, say) would leave the comparison lexically mixed, and
- * `ContainsPath` is lexical: every input would count as outside `rootDir` and
- * tsgo would emit it beside the user's source instead of under `outDir`.
- */
-function pinnedRootDirArgs(execution, options) {
-    if (options.pinInferredRootDir !== true)
-        return [];
-    if (options.emit !== true)
-        return [];
-    if (typeof execution.project.compilerOptions.rootDir === "string")
-        return [];
-    return ["--rootDir", execution.projectRoot];
-}
-/**
- * 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) {
-    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",
-        "--tsconfig=" + execution.tsconfig,
-        "--plugins-json=" + serializeNativePlugins(plugins),
-        "--cwd=" + execution.projectRoot,
-    ];
-    if ((0, sharedHostHelpers_1.selectSharedHostPlugin)(plugins).capabilities?.projectContextArgs === true) {
-        args.push(...(0, createNativeProjectContextArgs_1.createNativeProjectContextArgs)(execution.project, execution.pluginConfigDir));
-    }
-    if (options.emit === true) {
-        args.push("--emit");
-    }
-    if (options.outDir) {
-        args.push("--outDir=" + node_path_1.default.resolve(execution.cwd, options.outDir));
-    }
-    // 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");
-        }
-    }
-    return args;
-}
-/**
- * The forwarded-tsgo payload for a native `build`/`check` emit invocation.
- *
- * The sidecar builds its Program in-process, so the pinned `rootDir` has to
- * travel the same channel every other tsgo option takes to it — the host flag
- * set does not declare `--rootDir`, and `filterHostArgs` would strip it.
- */
-function createNativeBuildTsgoArgs(execution, options) {
-    return createNativeTsgoArgs(options, pinnedRootDirArgs(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,
-        "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
-        "--cwd=" + execution.projectRoot,
-    ];
-    if (plugin.capabilities?.projectContextArgs === true) {
-        args.push(...(0, createNativeProjectContextArgs_1.createNativeProjectContextArgs)(execution.project, execution.pluginConfigDir));
-    }
-    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");
-    }
-    args.push(...createNativeCheckThreadingArgs(options, plugin));
-    args.push(...createNativeCheckDiagnosticsArgs(options, plugin));
-    return args;
-}
-function createNativeProjectInputsArgs(execution, plugin) {
-    const args = [
-        "project-inputs",
-        "--tsconfig=" + execution.tsconfig,
-        "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
-        "--cwd=" + execution.projectRoot,
-    ];
-    if (plugin.capabilities?.projectContextArgs === true) {
-        args.push(...(0, createNativeProjectContextArgs_1.createNativeProjectContextArgs)(execution.project, execution.pluginConfigDir));
-    }
-    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
-// opts in through `capabilities.threadingArgs`, so a third-party check-stage
-// plugin keeps the strict-host behavior from ad3443a unless it declares the
-// same contract. 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;
-}
-function createNativeCheckDiagnosticsArgs(options, plugin) {
-    if (!nativeHostAcceptsDiagnosticsTiming(plugin))
-        return [];
-    if (!hasDiagnosticsFlag(options))
-        return [];
-    return ["--diagnostics"];
-}
-function nativeHostAcceptsDiagnosticsTiming(plugin) {
-    return plugin.capabilities?.diagnosticsTiming === true;
-}
-function transformHostTimingLabel(plugins) {
-    return (`ttsc transform host [` +
-        `${plugins.map((plugin) => plugin.name).join(", ")}] time`);
-}
-/**
- * Forward the tsgo flags ttsc did not recognize to a native sidecar as one
- * JSON-encoded payload. 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.
- *
- * The payload travels in the `TTSC_TSGO_ARGS` environment variable, not on the
- * sidecar's command line. #113 shipped it as a `--tsgo-args` flag, which is an
- * addition to a plugin protocol third-party hosts had already frozen: a Go
- * `flag.FlagSet` created with `flag.ContinueOnError` treats an undeclared flag
- * as fatal, so every pre-#113 sidecar answered `flag provided but not defined:
- * -tsgo-args` and exited 2. That took down `ttsc --strict`, `ttsc
- * --declaration`, `ttsx --strict` and — because {@link isolatedTsgoOutputArgs}
- * makes this payload non-empty on its own — plain `ttsc <file.ts>`, on every
- * project carrying a typia/nestia-era transform host (issue #1188).
- *
- * The environment is the channel ttsc already uses for host-owned payloads that
- * must not collide with a third-party flag set (`TTSC_LINKED_PLUGINS_JSON`,
- * `TTSC_PLUGIN_CONFIG_DIR`). It reaches those hosts without any change on their
- * side, because `buildSourcePlugin.ts::sourceBuildWorkspaceReplacements` builds
- * every source plugin against the installed ttsc's own driver, and
- * `driver.LoadProgram` reads the variable whenever the caller supplied no
- * explicit argv. It is strictly better than the capability gate `ad3443a` used
- * for `--singleThreaded` / `--checkers`: that one drops the flag for hosts that
- * cannot take it, which is acceptable for a threading knob and not for
- * `--strict`.
- *
- * Returns the JSON payload, or `undefined` when this lane forwards nothing.
- */
-function createNativeTsgoArgs(options, leading = []) {
-    const passthrough = [
-        // Ahead of the user's own flags, so the same precedence holds here as on
-        // the direct tsgo lane: whatever the user forwarded wins.
-        ...leading,
-        ...(nativeTsgoPassthroughArgs(options) ?? []),
-        ...isolatedTsgoOutputArgs(options),
-    ];
-    if (passthrough.length === 0) {
-        return undefined;
-    }
-    return JSON.stringify(passthrough);
-}
-function isolatedTsgoOutputArgs(options) {
-    const target = "isolateOutputsTo" in options &&
-        typeof options.isolateOutputsTo === "string"
-        ? node_path_1.default.resolve(options.isolateOutputsTo)
-        : undefined;
-    if (target === undefined)
-        return [];
-    return [
-        "--outFile",
-        "null",
-        "--declarationDir",
-        "null",
-        "--tsBuildInfoFile",
-        "null",
-        "--outDir",
-        target,
-    ];
-}
-function nativeTsgoPassthroughArgs(options) {
-    const passthrough = options.passthrough;
-    if (passthrough === undefined)
-        return undefined;
-    const out = [];
-    for (let i = 0; i < passthrough.length; i++) {
-        const token = passthrough[i];
-        if (isDiagnosticsPassthroughFlag(token)) {
-            if (!token.includes("=") &&
-                i + 1 < passthrough.length &&
-                isBooleanLiteral(passthrough[i + 1])) {
-                i++;
-            }
-            continue;
-        }
-        out.push(token);
-    }
-    return out;
-}
-function isDiagnosticsPassthroughFlag(token) {
-    const name = (0, schema_1.resolveFlagSpec)(token)?.name;
-    return name === "--diagnostics" || name === "--extendedDiagnostics";
-}
-function isBooleanLiteral(token) {
-    const normalized = token.toLowerCase();
-    return normalized === "true" || normalized === "false";
-}
-/**
- * Decide which native plugin subcommand the lint sidecar should run for the
- * current `runBuild` invocation. The launcher selects exactly one of `fix` /
- * `format` / `check` via subcommand dispatch, so at most one of the
- * `options.fix` / `options.format` booleans is true.
- */
-function nativeCheckSubcommand(options) {
-    if (options.format === true)
-        return "format";
-    if (options.fix === true)
-        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,
-        name: plugin.name,
-        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, timing) {
-    let out = {
-        diagnostics: [],
-        status: 0,
-        stdout: "",
-        stderr: "",
-    };
-    for (const plugin of execution.nativePlugins.filter((plugin) => plugin.stage === "check")) {
-        const result = runNativePluginCommand(plugin, createNativeCheckArgs(execution, options, plugin), options, execution, "ttsc.check", timing, `ttsc check plugin ${plugin.name} time`, createNativeTsgoArgs(options));
-        out = appendBuildOutput(out, result);
-        if (result.status !== 0) {
-            return out;
-        }
-    }
-    return out;
-}
-function discoverNativeProjectInputs(options, execution) {
-    const snapshots = [];
-    for (const plugin of execution.nativePlugins.filter((candidate) => candidate.stage === "check" &&
-        candidate.capabilities?.projectInputs === true)) {
-        const res = (0, spawnNative_1.spawnNative)(plugin.binary, createNativeProjectInputsArgs(execution, plugin), {
-            cwd: execution.projectRoot,
-            env: nativePluginEnv(options.env, execution, plugin),
-            encoding: "utf8",
-        });
-        if (res.error) {
-            throw new Error(`ttsc.project-inputs: failed to spawn ${plugin.binary}: ${res.error.message}`);
-        }
-        const stdout = (0, spawnNative_1.outputText)(res.stdout).trim();
-        if (res.status !== 0) {
-            const detail = (0, spawnNative_1.outputText)(res.stderr).trim() || stdout;
-            throw new Error(`ttsc.project-inputs: ${plugin.name ?? plugin.binary} failed${detail ? `: ${detail}` : ""}`);
-        }
-        const snapshot = parseProjectInputSnapshot(stdout, plugin);
-        snapshots.push(snapshot);
-    }
-    return mergeProjectInputSnapshots(execution.projectRoot, snapshots);
-}
-function arraysEqual(left, right) {
-    return (left.length === right.length && left.every((item, i) => item === right[i]));
-}
-/**
- * Keep every declared spelling of one identity, ordered without regard to which
- * producer ran first.
- *
- * Two contributors can name the same file through different aliases, and each
- * alias is a path a watcher has to observe: keeping only one of them would
- * discard the link whose retarget the other spelling exists to catch. Insertion
- * order is not canonical, so the caller sorts the flattened result.
- */
-function retainDeclaredSpelling(target, key, declared) {
-    const previous = target.get(key);
-    if (previous === undefined) {
-        target.set(key, [declared]);
-        return;
-    }
-    if (previous.includes(declared))
-        return;
-    previous.push(declared);
-}
-function mergeProjectInputSnapshots(fallbackRoot, snapshots, identities = (0, projectInputPathIdentity_1.createProjectInputPathIdentityContext)()) {
-    const files = new Map();
-    const globs = new Map();
-    const reloadDirectories = new Map();
-    const reloadFiles = new Map();
-    // Deduplicated on the same identity keys, but holding what the contributors
-    // wrote. Normalization resolves a declaration through its symlinks, which is
-    // right for every comparison and wrong for the watcher that has to observe
-    // the link itself being retargeted.
-    const declaredFiles = new Map();
-    const declaredGlobs = new Map();
-    const declaredReloadDirectories = new Map();
-    const declaredReloadFiles = new Map();
-    const rootIdentity = identities.resolve(fallbackRoot);
-    for (const snapshot of snapshots) {
-        const candidateRoot = identities.resolve(snapshot.root);
-        if (rootIdentity.key !== candidateRoot.key) {
-            throw new Error(`ttsc.project-inputs: plugin root ${candidateRoot.path} differs from the selected project root ${rootIdentity.path}`);
-        }
-        for (const file of snapshot.files) {
-            const identity = identities.resolve(file);
-            files.set(identity.key, identity.path);
-            retainDeclaredSpelling(declaredFiles, identity.key, node_path_1.default.resolve(file));
-        }
-        for (const glob of snapshot.globs) {
-            const identity = identities.resolve(glob);
-            globs.set(identity.key, identity.path.split(node_path_1.default.sep).join("/"));
-            retainDeclaredSpelling(declaredGlobs, identity.key, node_path_1.default.resolve(glob).split(node_path_1.default.sep).join("/"));
-        }
-        for (const reloadFile of snapshot.reloadFiles ?? []) {
-            const identity = identities.resolve(reloadFile);
-            reloadFiles.set(identity.key, identity.path);
-            retainDeclaredSpelling(declaredReloadFiles, identity.key, node_path_1.default.resolve(reloadFile));
-        }
-        for (const reloadDirectory of snapshot.reloadDirectories ?? []) {
-            const identity = identities.resolve(reloadDirectory);
-            reloadDirectories.set(identity.key, identity.path);
-            retainDeclaredSpelling(declaredReloadDirectories, identity.key, node_path_1.default.resolve(reloadDirectory));
-        }
-    }
-    const normalized = {
-        root: rootIdentity.path,
-        files: [...files.values()].sort(),
-        globs: [...globs.values()].sort(),
-        reloadDirectories: [...reloadDirectories.values()].sort(),
-        reloadFiles: [...reloadFiles.values()].sort(),
-    };
-    const declared = {
-        files: [...declaredFiles.values()].flat().sort(),
-        globs: [...declaredGlobs.values()].flat().sort(),
-        reloadDirectories: [...declaredReloadDirectories.values()].flat().sort(),
-        reloadFiles: [...declaredReloadFiles.values()].flat().sort(),
-    };
-    // Carried only when it says something the normalized arrays do not. A tree
-    // with no alias on any declaration produces the same four lists, and a
-    // consumer that has to scan both would pay twice for one population.
-    return arraysEqual(declared.files, normalized.files) &&
-        arraysEqual(declared.globs, normalized.globs) &&
-        arraysEqual(declared.reloadDirectories, normalized.reloadDirectories) &&
-        arraysEqual(declared.reloadFiles, normalized.reloadFiles)
-        ? normalized
-        : { ...normalized, declared };
-}
-function parseProjectInputSnapshot(text, plugin) {
-    let value;
-    try {
-        value = JSON.parse(text);
-    }
-    catch (error) {
-        throw new Error(`ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (typeof value !== "object" ||
-        value === null ||
-        typeof value.root !== "string" ||
-        !isStringArray(value.files) ||
-        !isStringArray(value.globs) ||
-        (value.reloadDirectories !==
-            undefined &&
-            !isStringArray(value.reloadDirectories)) ||
-        (value.reloadFiles !== undefined &&
-            !isStringArray(value.reloadFiles))) {
-        throw new Error(`ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned an invalid snapshot`);
-    }
-    const snapshot = value;
-    const invalid = [
-        ["root", snapshot.root],
-        ...snapshot.files.map((file) => ["file", file]),
-        ...snapshot.globs.map((glob) => ["glob", glob]),
-        ...(snapshot.reloadDirectories ?? []).map((directory) => ["reload directory", directory]),
-        ...(snapshot.reloadFiles ?? []).map((file) => ["reload file", file]),
-    ].find(([, location]) => location.length === 0 || !isAbsoluteLocalProjectInputPath(location));
-    if (invalid !== undefined) {
-        throw new Error(`ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned an invalid snapshot: ${invalid[0]} ${JSON.stringify(invalid[1])} is not an absolute local path`);
-    }
-    return {
-        ...snapshot,
-        reloadDirectories: snapshot.reloadDirectories ?? [],
-        reloadFiles: snapshot.reloadFiles ?? [],
-    };
-}
-function isAbsoluteLocalProjectInputPath(location, platform = process.platform) {
-    if (location.includes("\0"))
-        return false;
-    if (platform !== "win32")
-        return node_path_1.default.posix.isAbsolute(location);
-    const normalized = location.replaceAll("/", "\\");
-    if (/^[A-Za-z]:\\/.test(normalized))
-        return true;
-    if (normalized.startsWith("\\\\?\\")) {
-        const extended = normalized.slice(4);
-        if (/^[A-Za-z]:\\/.test(extended))
-            return true;
-        if (extended.toLowerCase().startsWith("unc\\")) {
-            return isWindowsUncProjectInputPath(`\\\\${extended.slice(4)}`);
-        }
-        return false;
-    }
-    if (normalized.startsWith("\\\\.\\"))
-        return false;
-    return isWindowsUncProjectInputPath(normalized);
-}
-function isWindowsUncProjectInputPath(location) {
-    const matched = /^\\\\([^\\]+)\\([^\\]+)(?:\\|$)/.exec(location);
-    return (matched !== null &&
-        isWindowsUncVolumeSegment(matched[1]) &&
-        isWindowsUncVolumeSegment(matched[2]));
-}
-function isWindowsUncVolumeSegment(segment) {
-    return segment !== "." && segment !== ".." && !/[\0<>:"/\\|?*]/.test(segment);
-}
-function isStringArray(value) {
-    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
-}
-/**
- * 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, timing, timingLabel, tsgoArgs) {
-    const startedAt = process.hrtime.bigint();
-    const res = (0, spawnNative_1.spawnNative)(plugin.binary, args, {
-        cwd: execution.projectRoot,
-        env: nativePluginEnv(options.env, execution, plugin, tsgoArgs),
-        encoding: "utf8",
-    });
-    recordTiming(timing, timingLabel, startedAt);
-    if (res.error) {
-        throw new Error(`${label}: failed to spawn ${plugin.binary}: ${res.error.message}`);
-    }
-    return normalizeBuildOutput({
-        status: res.status ?? 1,
-        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],
-        emittedFiles: right.emittedFiles !== undefined ? right.emittedFiles : left.emittedFiles,
-        status: right.status !== 0 ? right.status : left.status,
-        stdout: left.stdout + right.stdout,
-        stderr: left.stderr + right.stderr,
-    });
-}
-/**
- * Synthesize one structured diagnostic from a non-zero process result that
- * produced no parsable diagnostics, carrying the captured stderr/stdout as the
- * message. Shared by the public API result mapping and the plugin-failure
- * recovery pass so the failure text is never dropped from structured output.
- */
-function createProcessDiagnostic(result) {
-    const messageText = (result.stderr || result.stdout).trim() ||
-        `ttsc exited with status ${result.status}`;
-    return {
-        category: "error",
-        code: "TTSC_PROCESS",
-        file: null,
-        messageText,
-    };
-}
-/**
- * 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 project = options.resolvedProject ??
-        (0, readProjectConfig_1.readProjectConfig)({
-            cwd,
-            projectRoot: options.projectRoot,
-            tsconfig: options.tsconfig,
-        });
-    const tsconfig = project.path;
-    const projectRoot = project.root;
-    const tsgo = (0, resolveTsgo_1.resolveTsgo)({ ...options, cwd: projectRoot });
-    let pluginSetupFailure;
-    let nativePlugins = [];
-    try {
-        if ((0, loadProjectPlugins_1.hasProjectPluginEntries)(project, options.plugins)) {
-            nativePlugins = (0, loadProjectPlugins_1.loadProjectPlugins)({
-                binary: (0, resolveBinary_1.resolveBinary)(options) ?? "",
-                cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
-                cwd,
-                entries: options.plugins,
-                env: (0, sharedHostHelpers_1.inheritedSidecarEnv)(options.env),
-                onWatchInputs: options.onWatchInputs,
-                pluginConfigDir: options.pluginConfigDir,
-                projectRoot,
-                tsconfig,
-            }).nativePlugins;
-        }
-        else {
-            options.onWatchInputs?.([]);
-        }
-    }
-    catch (error) {
-        pluginSetupFailure = {
-            diagnostics: [],
-            status: 2,
-            stdout: "",
-            stderr: `${error instanceof Error ? error.message : String(error)}\n`,
-        };
-    }
-    return {
-        cwd,
-        nativePlugins,
-        pluginConfigDir: (0, sharedHostHelpers_1.resolvePluginConfigDir)({
-            cwd,
-            pluginConfigDir: options.pluginConfigDir,
-        }),
-        pluginSetupFailure,
-        project,
-        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/)) {
-        const match = line.match(/^TSFILE:\s*(.+)$/);
-        if (match?.[1]) {
-            out.push(node_path_1.default.resolve(match[1].trim()));
-        }
-    }
-    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/)
-        .filter((line) => !/^TSFILE:\s*/.test(line))
-        .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) {
-        return { ...result, diagnostics };
-    }
-    if (result.stdout.trim().length === 0) {
-        return { ...result, diagnostics };
-    }
-    return {
-        diagnostics,
-        emittedFiles: result.emittedFiles,
-        status: result.status,
-        stdout: "",
-        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 = [];
-    let current;
-    for (const line of lines) {
-        if (line.length === 0 || /^TSFILE:\s*/.test(line)) {
-            continue;
-        }
-        if (/^Found\s+\d+\s+errors?/i.test(line)) {
-            continue;
-        }
-        const diagnostic = parseDiagnosticLine(line, cwd);
-        if (diagnostic !== null) {
-            current = diagnostic;
-            out.push(current);
-            continue;
-        }
-        if (current !== undefined && /^\s+/.test(line)) {
-            current.messageText += `\n${line.trimEnd()}`;
-        }
-    }
-    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) {
-        return {
-            category: normalizeDiagnosticCategory(colonMatch[4]),
-            character: Number(colonMatch[3]),
-            code: normalizeDiagnosticCode(colonMatch[6]),
-            file: normalizeDiagnosticFile(colonMatch[1], cwd),
-            line: Number(colonMatch[2]),
-            messageText: colonMatch[7],
-        };
-    }
-    const fileMatch = line.match(/^(.+?)\((\d+),(\d+)\):\s+(error|warning|suggestion|message)\s+([A-Z]+)?(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
-    if (fileMatch) {
-        return {
-            category: normalizeDiagnosticCategory(fileMatch[4]),
-            character: Number(fileMatch[3]),
-            code: normalizeDiagnosticCode(fileMatch[6]),
-            file: normalizeDiagnosticFile(fileMatch[1], cwd),
-            line: Number(fileMatch[2]),
-            messageText: fileMatch[7],
-        };
-    }
-    const globalMatch = line.match(/^(error|warning|suggestion|message)\s+([A-Z]+)?(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
-    if (!globalMatch) {
-        return null;
-    }
-    return {
-        category: normalizeDiagnosticCategory(globalMatch[1]),
-        code: normalizeDiagnosticCode(globalMatch[3]),
-        file: null,
-        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" ||
-        lowered === "suggestion" ||
-        lowered === "message"
-        ? 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, "");
-}
-//# sourceMappingURL=runBuild.js.map