ttsc 0.30.3 → 0.31.0

package/src/compiler/internal/build/NativePluginArguments.ts

@@ -0,0 +1,302 @@
+import path from "node:path";
+
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOptions";
+import type { TtscCommonOptions } from "../../../structures/internal/TtscCommonOptions";
+import { createNativeProjectContextArgs } from "../project/createNativeProjectContextArgs";
+import { selectSharedHostPlugin } from "../sharedHost/selectSharedHostPlugin";
+import type { BuildExecution } from "./BuildExecution";
+import { PassthroughFlags } from "./PassthroughFlags";
+import type { RunBuildOptions } from "./RunBuildOptions";
+import { isAbsoluteLocalProjectInputPath } from "./isAbsoluteLocalProjectInputPath";
+
+/**
+ * The argv ttsc hands to a native plugin host.
+ *
+ * A native host speaks its own subcommands (`build`, `check`, `fix`, `format`,
+ * `project-inputs`) and receives the project, the plugin list, and the compiler
+ * flags as separate arguments rather than one tsgo command line. Optional
+ * capabilities a host declares (threading, diagnostics timing) decide which of
+ * ttsc's optional arguments are sent. This negotiation avoids sending those
+ * extensions to undeclared hosts; it does not certify every host's acceptance
+ * of the core protocol or the truth of its capability declaration.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace separates the host subcommand protocol from compiler forwarding and uses declared capabilities for optional host fields.
+ * @evidence contracts/common.md#clear-and-simple-design Build, check and input-query composers share descriptor serialization while preserving each command's own supported modifiers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional protocol extensions require capabilities instead of mutating foreign flag sets or dispatching on a particular plugin name.
+ * @evidence contracts/common.md#meaningful-documentation Namespace prose states protocol separation and capability purpose; composer comments explain project context, command effects and payload fields.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The grouping itself defines no native path representation; its selected argv composers address the paths they carry.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace contains no processing strategy apart from its separately selected composers and serializer.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This API grouping retains no completed or in-flight host query or payload.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No native host, buffer history or handle is owned by the namespace.
+ */
+export namespace NativePluginArguments {
+  /**
+   * Compose a shared transform host's build or no-emit check command.
+   * Project-context arguments require the selected host's capability; quiet
+   * modifiers remain absent on the compatibility check lane.
+   *
+   * A supplied provenancePath is a private absolute artifact destination and
+   * requires explicit emitProvenance support from the selected host.
+   *
+   * @evidence contracts/common.md#principled-implementation Emit selection chooses build versus check; the selected host's independent capabilities gate explicit project context and a supplied absolute emit-proof artifact destination.
+   * @evidence contracts/common.md#clear-and-simple-design Core protocol argv precedes optional project/output/verbosity fields; compiler passthrough travels separately through the environment.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability checks and omission of build-only modifiers protect actual strict-host protocol differences without recognizing plugin names or altering foreign flag parsers.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain shared-host selection, no-emit compatibility modifiers and the optional private provenance path's capability/absolute-path premise.
+   * @evidence contracts/portability.md#os-neutral-implementation Native output paths resolve against execution cwd and remain individual argv elements; JSON serialization preserves plugin payload without shell escaping.
+   * @evidence contracts/performance.md#efficient-algorithms Plugin projection/JSON encoding follows plugin count, name/stage text and configuration serialization work. Selected-host capability lookups may each scan the plugin list; optional project-context serialization and native output-path resolution add payload/path-text costs. Returned argv storage follows composed bytes.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure argv composition coordinates no shared producer or retained cross-request result.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Arguments are returned to the process owner and no process or persistent buffer is acquired here.
+   */
+  export function createNativeBuildArgs(
+    execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
+    options: RunBuildOptions,
+    plugins: readonly ITtscLoadedNativePlugin[],
+    provenancePath?: string,
+  ): string[] {
+    const args = [
+      options.emit === false ? "check" : "build",
+      "--tsconfig=" + execution.tsconfig,
+      "--plugins-json=" + serializeNativePlugins(plugins),
+      "--cwd=" + execution.projectRoot,
+    ];
+    if (provenancePath !== undefined) {
+      if (selectSharedHostPlugin(plugins).capabilities?.emitProvenance !== true)
+        throw new Error(
+          "ttsc: native compiler host does not support emit provenance",
+        );
+      if (!isAbsoluteLocalProjectInputPath(provenancePath))
+        throw new Error(
+          "ttsc: emit provenance destination must be an absolute native path",
+        );
+      args.push("--emit-provenance-json=" + provenancePath);
+    }
+    if (
+      selectSharedHostPlugin(plugins).capabilities?.projectContextArgs === true
+    ) {
+      args.push(
+        ...createNativeProjectContextArgs(
+          execution.project,
+          execution.pluginConfigDir,
+        ),
+      );
+    }
+    if (options.emit === true) {
+      args.push("--emit");
+    }
+    if (options.outDir) {
+      args.push("--outDir=" + path.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;
+  }
+
+  /**
+   * Compose one check-stage host's check, fix or format command. The full
+   * plugin configuration accompanies the command; optional threading, timing
+   * and project-context fields require that host's declared support.
+   *
+   * @evidence contracts/common.md#principled-implementation Subcommand selection follows format/fix options while capability-gated fields preserve the selected host's accepted protocol.
+   * @evidence contracts/common.md#clear-and-simple-design Shared core fields are assembled before small helpers add threading and timing, separating host capability policy from compiler argv.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional flags use descriptor capabilities rather than special plugin names or monkey-patched foreign flag sets.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains command effects, full configuration delivery and capability-dependent fields.
+   * @evidence contracts/portability.md#os-neutral-implementation cwd and output locations retain native path semantics; each protocol flag is a separate argv element and plugin configuration is JSON, not shell text.
+   * @evidence contracts/performance.md#efficient-algorithms Composition serializes plugin count/name/stage/config fields; capability-gated timing selection projects the unexpanded forwarded argv frame with token/name/value costs. Optional project-context encoding and native output-path resolution add text work; returned storage follows argv bytes.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Building one command does not coordinate completed or in-flight execution across consumers.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No sidecar or persistent argument cache is owned by this composer.
+   */
+  export function createNativeCheckArgs(
+    execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
+    options: TtscBuildOptions,
+    plugin: ITtscLoadedNativePlugin,
+  ): string[] {
+    const args = [
+      nativeCheckSubcommand(options),
+      "--tsconfig=" + execution.tsconfig,
+      "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
+      "--cwd=" + execution.projectRoot,
+    ];
+    if (plugin.capabilities?.projectContextArgs === true) {
+      args.push(
+        ...createNativeProjectContextArgs(
+          execution.project,
+          execution.pluginConfigDir,
+        ),
+      );
+    }
+    if (options.outDir) {
+      args.push("--outDir=" + path.resolve(execution.cwd, options.outDir));
+    }
+    if (options.quiet === false) {
+      args.push("--verbose");
+    } else if (options.quiet === true) {
+      args.push("--quiet");
+    }
+    args.push(...createNativeCheckThreadingArgs(options, plugin));
+    args.push(...createNativeCheckDiagnosticsArgs(options, plugin));
+    return args;
+  }
+
+  /**
+   * Build the argv of a native host's `project-inputs` query, which reports the
+   * non-TypeScript files (documents, schemas, configs) the host's rules read,
+   * so watch and cache invalidation can observe them.
+   *
+   * The caller must check projectInputs capability before launching this query.
+   *
+   * @evidence contracts/common.md#principled-implementation Project selection and complete plugin configuration let the host report its actual rule inputs; optional project context is sent only when supported.
+   * @evidence contracts/common.md#clear-and-simple-design This composer owns query argv while the discovery operation owns capability selection, execution and snapshot validation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The explicit project-inputs protocol queries declared dependencies instead of guessing files from plugin names or dropping unsupported inputs.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains non-TypeScript dependencies, invalidation purpose and the caller's capability premise.
+   * @evidence contracts/portability.md#os-neutral-implementation Selected tsconfig/cwd spellings travel as separate native argv fields; no slash rewriting or shell construction is applied to paths.
+   * @evidence contracts/performance.md#efficient-algorithms Plugin descriptors are projected and JSON-encoded once, with plugin count, name/stage/config serialization costs. Optional project-context encoding and composed native path-field text add work/storage; fixed field count does not make payload cost constant.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Query composition establishes no cross-request reuse of host dependency discovery.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned argv has caller ownership; this function acquires no native resource or retained snapshot.
+   */
+  export function createNativeProjectInputsArgs(
+    execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
+    plugin: ITtscLoadedNativePlugin,
+  ): string[] {
+    const args = [
+      "project-inputs",
+      "--tsconfig=" + execution.tsconfig,
+      "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
+      "--cwd=" + execution.projectRoot,
+    ];
+    if (plugin.capabilities?.projectContextArgs === true) {
+      args.push(
+        ...createNativeProjectContextArgs(
+          execution.project,
+          execution.pluginConfigDir,
+        ),
+      );
+    }
+    return args;
+  }
+
+  /**
+   * Send threading options only to check hosts declaring support. An unknown
+   * strict host may reject optional flags before it can analyze the project;
+   * transform hosts use the separate build/compiler-options channel.
+   */
+  function createNativeCheckThreadingArgs(
+    options: TtscCommonOptions,
+    plugin: ITtscLoadedNativePlugin,
+  ): string[] {
+    if (!nativeHostAcceptsThreadingArgs(plugin)) return [];
+    const args: string[] = [];
+    if (options.singleThreaded === true) {
+      args.push("--singleThreaded");
+    }
+    if (options.checkers !== undefined) {
+      args.push("--checkers=" + String(options.checkers));
+    }
+    return args;
+  }
+
+  /**
+   * Return true when the loaded native check-stage host has declared
+   * `capabilities.threadingArgs` in its plugin descriptor.
+   *
+   * An absent declaration means unsupported, regardless of package ownership or
+   * plugin name, because the host's native flag set is otherwise unknown.
+   */
+  function nativeHostAcceptsThreadingArgs(
+    plugin: ITtscLoadedNativePlugin,
+  ): boolean {
+    return plugin.capabilities?.threadingArgs === true;
+  }
+
+  function createNativeCheckDiagnosticsArgs(
+    options: TtscCommonOptions,
+    plugin: ITtscLoadedNativePlugin,
+  ): string[] {
+    if (!nativeHostAcceptsDiagnosticsTiming(plugin)) return [];
+    if (!PassthroughFlags.hasDiagnosticsFlag(options)) return [];
+    return ["--diagnostics"];
+  }
+
+  function nativeHostAcceptsDiagnosticsTiming(
+    plugin: ITtscLoadedNativePlugin,
+  ): boolean {
+    return plugin.capabilities?.diagnosticsTiming === true;
+  }
+
+  /**
+   * The `--diagnostics` timing label of one transform-host run, naming every
+   * plugin that shared the host so a slow run can be attributed.
+   *
+   * @evidence contracts/common.md#principled-implementation Names of all selected participants form one label for the shared execution, rather than attributing its duration to only one plugin.
+   * @evidence contracts/common.md#clear-and-simple-design A single name projection and join supplies timing attribution without coupling labels to process selection.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Participant names come from the actual loaded selection, not a fixed benchmark label or special plugin list.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies the shared-host timing purpose and attribution scope.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Formatting participant names touches no native path, filesystem or process boundary.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms One projection and join cost O(P plus participant-name/output bytes) for P plugins, with no repeated string-prefix rebuilding.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A label formatter coordinates no shared computation beyond the supplied participant list.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The formatter returns text without retaining selection history or handles.
+   */
+  export function transformHostTimingLabel(
+    plugins: readonly ITtscLoadedNativePlugin[],
+  ): string {
+    return (
+      `ttsc transform host [` +
+      `${plugins.map((plugin) => plugin.name).join(", ")}] time`
+    );
+  }
+
+  /**
+   * 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: TtscBuildOptions): string {
+    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.
+   *
+   * @evidence contracts/common.md#principled-implementation Projection retains config, name and stage, the protocol's declared plugin descriptor fields, without serializing host-loader implementation details.
+   * @evidence contracts/common.md#clear-and-simple-design One explicit projection defines the JSON wire representation separately from in-memory plugin metadata.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Standard JSON encoding preserves configuration structure without handcrafted quoting or mutation of foreign descriptors.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the compact protocol purpose and deliberate field restriction.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation JSON descriptor serialization accesses no native filesystem or process and applies no path normalization.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms One projection visits P plugins and standard JSON serialization traverses config/name/stage values into returned bytes. Custom getters/toJSON and exceptional or cyclic config values follow ordinary JSON semantics and can add work or throw; no serialization work ceiling is supplied here. Only required descriptor fields are explicitly projected.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable plugin configuration is serialized for the current invocation without establishing cross-request equivalence.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local projections become returned text; no persistent descriptor cache or handle is retained.
+   */
+  export function serializeNativePlugins(
+    plugins: readonly ITtscLoadedNativePlugin[],
+  ): string {
+    return JSON.stringify(
+      plugins.map((plugin) => ({
+        config: plugin.config,
+        name: plugin.name,
+        stage: plugin.stage,
+      })),
+    );
+  }
+}

package/src/compiler/internal/build/PassthroughFlags.ts

@@ -0,0 +1,229 @@
+import type { FlagSpec } from "../../../flags/FlagSpec";
+import { readCompilerOptionOccurrence } from "../../../flags/readCompilerOptionOccurrence";
+import { resolveFlagSpec } from "../../../flags/resolveFlagSpec";
+import type { TtscCommonOptions } from "../../../structures/internal/TtscCommonOptions";
+
+/**
+ * Questions about the compiler flags a user forwarded through ttsc.
+ *
+ * Ttsc forwards every flag it does not own to TypeScript-Go verbatim, then has
+ * to answer a few questions about them itself: whether timing was asked for,
+ * whether a flag turns the build into a terminal command, whether a flag is one
+ * ttsc consumes internally. Every answer resolves the token through the flag
+ * schema, so a question is decided by the flag's identity (any case, one or two
+ * dashes) and, for a boolean flag, by the value TypeScript-Go gives it.
+ *
+ * Classification observes this unexpanded argv frame. It does not read response
+ * files; their contents and effects remain owned by the native compiler and
+ * cannot be certified by these predicates.
+ *
+ * @evidence contracts/common.md#principled-implementation Schema identities and compiler-compatible boolean occurrence parsing distinguish effective flags from mere user-owned presence.
+ * @evidence contracts/common.md#clear-and-simple-design The grouping centralizes forwarding classification and preservation policy so higher build layers do not maintain parallel literal flag sets.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared schema metadata replaces producer-name or exact-spelling exceptions, and malformed argv remains under compiler diagnostic ownership.
+ * @evidence contracts/common.md#meaningful-documentation Namespace prose explains why forwarding also needs classification; public comments document precedence, preservation and distinct presence semantics.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups APIs; selected predicates and argv transformation functions own their scans and allocations.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No completed or in-flight computation is retained by this API grouping.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no persistent map, task or handle; helper parser state is invocation-local.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation A namespace only groups the declarations inside it; each carries its own acknowledgments.
+ */
+export namespace PassthroughFlags {
+  /**
+   * Whether a visible `--diagnostics` or `--extendedDiagnostics` occurrence
+   * remains enabled in this unexpanded argv frame, using native boolean rules.
+   *
+   * @evidence contracts/common.md#principled-implementation Last-occurrence boolean interpretation matches compiler option assignment, so a later false or null disables earlier diagnostics selection.
+   * @evidence contracts/common.md#clear-and-simple-design Shared boolean parsing resolves schema identities; this predicate asks only whether either timing flag remains enabled.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual forwarded tokens and schema determine timing rather than exact-spelling checks or benchmark-only flag handling.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies effective rather than merely present flags and compiler-compatible precedence.
+   * @evidence contracts/performance.md#efficient-algorithms One native-occurrence cursor records final values per schema flag, then scans enabled schema references. Work includes argv count, token-name normalization and list-lookahead text bytes; local maps/arrays are bounded by distinct schema flags and transient parsing by the current value's bytes.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate inspects current mutable options and coordinates no retained or in-flight computation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Boolean state is local to the call; no argument history or resource is retained.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation hasDiagnosticsFlag computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+   */
+  export function hasDiagnosticsFlag(options: TtscCommonOptions): boolean {
+    const enabled = effectiveBooleanFlags(options);
+    return enabled.some(
+      (flag) =>
+        flag.name === "--diagnostics" || flag.name === "--extendedDiagnostics",
+    );
+  }
+
+  /**
+   * Report whether this unexpanded argv frame includes an enabled
+   * print-and-exit tsgo flag (`--showConfig`, `--listFilesOnly`, `--all`,
+   * `--init`, `-?`) that is in effect, 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: adding a new terminal flag means editing `FLAG_SCHEMA.ts` and
+   * re-running `pnpm run gen:flags`; this predicate needs no edit. A terminal
+   * flag the user turned off (`--showConfig false`) is an ordinary compile to
+   * TypeScript-Go, so it must not lift the emit guards of one.
+   *
+   * @evidence contracts/common.md#principled-implementation Only enabled boolean flags carrying schema terminal semantics classify a print-and-exit request; disabled occurrences cannot lift compilation guards.
+   * @evidence contracts/common.md#clear-and-simple-design Schema metadata owns terminal classification and the shared parser owns value precedence, avoiding parallel flag lists in build orchestration.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts This uses supported flag metadata rather than selected spelling exceptions or treating malformed argv as a successful terminal request.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain terminal effects, schema ownership and the significance of a disabled occurrence.
+   * @evidence contracts/performance.md#efficient-algorithms A native-occurrence cursor interprets argv once, including token-name and list-lookahead bytes, then short-circuits on an enabled terminal schema flag. Local final-value references are bounded by distinct schema flags; transient parsing scales with the current lookahead value.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Classification reads one options value and establishes no reusable producer or cross-request state.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only invocation-local parser state is allocated; no process or retained history is owned.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Terminal metadata and native-compatible boolean assignments classify compiler argv only; no native path is resolved or process/OS capability acquired here.
+   */
+  export function forwardsTerminalTsgoFlag(
+    options: TtscCommonOptions,
+  ): boolean {
+    return effectiveBooleanFlags(options).some(
+      (flag) => flag.terminal === true,
+    );
+  }
+
+  /**
+   * Report whether an enabled terminal flag visible in this unexpanded frame
+   * has project-independent meaning (`--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. Project dependence stays owned by the schema.
+   *
+   * @evidence contracts/common.md#principled-implementation Project-free classification requires both enabled terminal behavior and schema projectFree metadata, distinguishing config-independent commands from show-config requests.
+   * @evidence contracts/common.md#clear-and-simple-design The same final boolean interpretation serves all classifications while schema metadata owns which commands require a project.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Project bypass is granted by declared flag semantics, not by catching arbitrary setup failures and pretending compilation succeeded.
+   * @evidence contracts/common.md#meaningful-documentation The preceding native prose explains the project-independent meaning and schema source; acknowledgments are kept apart from descriptive paragraphs.
+   * @evidence contracts/performance.md#efficient-algorithms The shared occurrence cursor scans token names and list-lookahead text before a short-circuit scan of distinct enabled schema references. Parsing and local value/reference arrays remain invocation-bound; no project read or response-file expansion is added.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This classification does not coordinate repeated production or retain option interpretation between requests.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources All parser state is local and no native resource is acquired.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation A schema projectFree boolean classifies option meaning without resolving configs, reading paths or probing executables; those native capabilities belong to the execution owner.
+   */
+  export function forwardsProjectFreeTerminalTsgoFlag(
+    options: TtscCommonOptions,
+  ): boolean {
+    return effectiveBooleanFlags(options).some(
+      (flag) => flag.terminal === true && flag.projectFree === true,
+    );
+  }
+
+  /**
+   * Report whether this unexpanded frame visibly names a flag ttsc adds
+   * 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`.
+   *
+   * Presence identifies a user-owned option spelling, including malformed
+   * inline-value spelling that must remain available for the compiler to
+   * reject. This predicate does not decide whether the boolean occurrence is
+   * enabled.
+   *
+   * @evidence contracts/common.md#principled-implementation Schema identity plus internalShadow metadata distinguishes user-owned output/option selection from flags introduced only for internal collection.
+   * @evidence contracts/common.md#clear-and-simple-design Presence recognition is separate from effective boolean parsing because preservation and execution classification have different requirements.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Recognizing malformed user spelling prevents internally supplied values from erasing its compiler error; no producer method or argv is patched.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes presence from enabled state and explains why malformed inline spelling is still recognized.
+   * @evidence contracts/performance.md#efficient-algorithms A short-circuit native-occurrence cursor resolves visible flag names and skips consumed operands; work includes visited token-name and list-lookahead bytes. Only transient current-value parsing is allocated, with no final flag table or argv copy.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current argv presence is inspected directly without coordinating a shared or retained producer.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This lookup owns no persistent state or handle.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Canonical shadow identity and argv consumption are compiler-token policy; no token is resolved as a native filesystem path and no process or OS capability is accessed.
+   */
+  export function forwardsInternalShadowFlag(
+    options: TtscCommonOptions,
+    flag: string,
+  ): boolean {
+    const passthrough = options.passthrough;
+    if (passthrough === undefined) return false;
+    // Resolution covers the bare form (`--pretty`), the inline-value form
+    // (`--pretty=true`), and case variants (`--PRETTY`). This is identity
+    // recognition, not acceptance of an inline boolean value by tsgo.
+    for (let index = 0; index < passthrough.length; ) {
+      const spec = resolveFlagSpec(passthrough[index]!);
+      if (spec?.internalShadow === true && spec.name === flag) return true;
+      index += readCompilerOptionOccurrence(passthrough, index).width;
+    }
+    return false;
+  }
+
+  /**
+   * This unexpanded argv frame without visible occurrences of the named boolean
+   * flags, each removed with the value token TypeScript-Go would consume for
+   * it.
+   *
+   * Only an occurrence TypeScript-Go itself accepts is removed. An inline
+   * spelling it rejects (`--diagnostics=false`) stays for native diagnosis.
+   * Unconsumed data also stays: `--diagnostics TRUE` removes the enabled option
+   * but leaves `TRUE` as a native input file. Its acceptance or failure belongs
+   * to the compiler, rather than being certified as a malformed boolean here.
+   *
+   * An empty token preserves an unconsumed lookahead boundary when deletion
+   * would otherwise bind later data to a retained boolean, list or config-only
+   * option. A surviving dash option already preserves that boundary; adjacent
+   * removals defer the fence until they expose data or the end of the frame.
+   * Native parsing ignores the empty token as a positional input.
+   *
+   * @evidence contracts/common.md#principled-implementation The native cursor identifies valid boolean assignments and skips scalar operands. Removal retains malformed spelling and inserts a native-ignored empty lookahead fence when needed to preserve the remaining options, files and diagnostics.
+   * @evidence contracts/common.md#clear-and-simple-design One indexed argv walk uses the shared occurrence parser and builds a fresh output array without modifying caller tokens.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid argv is preserved for the compiler's real diagnostic instead of being normalized into a successful request.
+   * @evidence contracts/common.md#meaningful-documentation Native examples explain inline rejection and unconsumed uppercase values, giving the reason preservation matters.
+   * @evidence contracts/performance.md#efficient-algorithms The cursor visits A argv tokens with linear membership checks over D supplied removal names, giving O(A times D) membership work plus visited token/lookahead text bytes. Production consumers supply one or two names; consumed operands are skipped. Returned references grow with A, and transient list parsing with the current value's bytes.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This transforms one argv sequence without retaining or coordinating equivalent computation across requests.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The new array is transferred to the caller and no token history or handle remains owned here.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Removing compiler-token occurrences and inserting native-ignored empty fences interprets no filesystem path and accesses no process, shell or OS capability; the downstream compiler owns response-file expansion and execution.
+   */
+  export function withoutBooleanFlags(
+    passthrough: readonly string[],
+    names: readonly string[],
+  ): string[] {
+    const out: string[] = [];
+    let previousNeedsFence = false;
+    for (let i = 0; i < passthrough.length; ) {
+      const occurrence = readCompilerOptionOccurrence(passthrough, i);
+      const flag = resolveFlagSpec(passthrough[i]!);
+      if (
+        occurrence.booleanValue !== undefined &&
+        flag !== undefined &&
+        names.includes(flag.name)
+      ) {
+        // Native ignores an empty positional token. It also prevents a
+        // retained boolean/list/config-only option from consuming newly
+        // adjacent data after the removed option disappears.
+        const next = passthrough[i + occurrence.width];
+        if (
+          previousNeedsFence &&
+          (next === undefined || !next.startsWith("-"))
+        ) {
+          out.push("");
+          previousNeedsFence = false;
+        }
+        i += occurrence.width;
+        continue;
+      }
+      out.push(...passthrough.slice(i, i + occurrence.width));
+      previousNeedsFence = occurrence.needsFence;
+      i += occurrence.width;
+    }
+    return out;
+  }
+
+  /**
+   * Every schema boolean flag whose last forwarded occurrence turns it on.
+   * TypeScript-Go assigns an option at each occurrence, so the last one wins.
+   */
+  function effectiveBooleanFlags(options: TtscCommonOptions): FlagSpec[] {
+    const passthrough = options.passthrough ?? [];
+    const values = new Map<FlagSpec, boolean>();
+    for (let i = 0; i < passthrough.length; ) {
+      const occurrence = readCompilerOptionOccurrence(passthrough, i);
+      if (occurrence.booleanValue !== undefined) {
+        const flag = resolveFlagSpec(passthrough[i]!);
+        if (flag !== undefined) values.set(flag, occurrence.booleanValue);
+      }
+      i += occurrence.width;
+    }
+    return [...values].filter(([, value]) => value).map(([flag]) => flag);
+  }
+}

package/src/compiler/internal/build/PluginFailureDiagnostics.ts

@@ -0,0 +1,70 @@
+import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
+import { PassthroughFlags } from "./PassthroughFlags";
+import type { RunBuildOptions } from "./RunBuildOptions";
+import { appendBuildOutput } from "./appendBuildOutput";
+import { createProcessDiagnostic } from "./createProcessDiagnostic";
+
+/**
+ * Select and merge the independent diagnostic recovery after a plugin failure.
+ * The build engine still owns the native check and report filtering. These
+ * supplied results do not establish how either producer acquired its output.
+ *
+ * @evidence contracts/common.md#principled-implementation Mode exclusions and original failure ownership remain distinct from native execution and report deduplication.
+ * @evidence contracts/common.md#clear-and-simple-design One concern groups the recovery gate and final merge used by the actual build engine.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The namespace supplies no executor or synthetic producer and never turns recovery into a successful plugin build.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes policy inputs from producer execution and acquisition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This grouping performs no native path, filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own policy composition; the namespace selects no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This namespace owns no computed-result cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This grouping holds no runtime registry, handle or task.
+ */
+export namespace PluginFailureDiagnostics {
+  /**
+   * Permit the independent check unless the selected mode omits diagnostics.
+   * Failure admission belongs to the caller; this gate neither changes status
+   * nor classifies a successful producer as failed.
+   *
+   * @evidence contracts/common.md#principled-implementation Exact true format/skip controls and the existing forwarded terminal selector preserve the build engine's recovery exclusions.
+   * @evidence contracts/common.md#clear-and-simple-design One predicate owns the mode gate while the caller retains execution and exception ordering.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied options use the real terminal flag policy, without a fake compiler or test-only execution callback.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the caller's failure premise and this predicate's diagnostic-mode responsibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied option values and forwarded argument semantics are inspected without native paths, filesystem or process calls.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This gate composes scalar checks and the existing terminal selector; argument interpretation belongs to that selector.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current supplied options are evaluated directly, without caching or cross-call reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This predicate retains no option population, handle or task.
+   */
+  export function shouldCollect(options: RunBuildOptions): boolean {
+    return !(
+      options.format === true ||
+      options.skipDiagnosticsCheck === true ||
+      PassthroughFlags.forwardsTerminalTsgoFlag(options)
+    );
+  }
+
+  /**
+   * Keep the original failure when no new diagnostic batch remains. Otherwise
+   * seed its unparsed process failure before the recovered reports and retain
+   * its status, even if the independent check returned another status.
+   *
+   * @evidence contracts/common.md#principled-implementation A null filtered batch preserves failure identity; an empty original diagnostic list receives the shared process diagnostic before phase merging, and the original status replaces the merged status.
+   * @evidence contracts/common.md#clear-and-simple-design Seeding, delegated output merge and status restoration form one result adaptation, separate from native execution and filtering.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Reports come from supplied producer results; process seeding exposes the original failure rather than inventing a successful compiler response.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes null-batch identity from seeded merging and states status ownership.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied result records and text are composed without resolving paths or invoking native filesystem/process APIs.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This adapter delegates record/text/witness merging to appendBuildOutput and message selection to createProcessDiagnostic, without another traversal strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The already filtered batch is consumed once; this adapter owns no producer capture or cross-request cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Constructed result records transfer to the caller; this adapter retains no historical population, native handle or task.
+   */
+  export function append(
+    failure: TtscBuildResult,
+    fallback: TtscBuildResult | null,
+  ): TtscBuildResult {
+    if (fallback === null) return failure;
+    const seeded =
+      failure.diagnostics.length === 0
+        ? { ...failure, diagnostics: [createProcessDiagnostic(failure)] }
+        : failure;
+    const status = failure.status;
+    return { ...appendBuildOutput(seeded, fallback), status };
+  }
+}

package/src/compiler/internal/build/ResidentCheckEntryPlan.ts

@@ -0,0 +1,42 @@
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+
+/**
+ * How one configured check-stage plugin entry runs during a watch cycle.
+ *
+ * Produced by {@link planResidentCheckEntries}. Entries with the same `key`
+ * share one resident sidecar; an entry without a key runs as an ordinary
+ * one-shot check every cycle.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate entryIndex and optional process key represent configured delivery identity versus capability-dependent sidecar identity.
+ * @evidence contracts/common.md#clear-and-simple-design The record carries command selection, configured position and plugin metadata together without owning the scheduler or process.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An absent capability is represented by an absent key, not an invented resident identity or patched plugin metadata.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments explain argv, duplicate positions and the undefined key; documented members are separated by blank lines.
+ * @evidence contracts/portability.md#os-neutral-implementation The record preserves native executable selection separately from argv and environment-carried compiler flags; consumers own native spawning and filesystem identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type ResidentCheckEntryPlan = {
+  /**
+   * Full argv of the entry's one-shot check command. The resident consumer
+   * substitutes `check-serve` for the first argument when it starts a sidecar.
+   */
+  args: string[];
+
+  /**
+   * Position of the entry among the configured check-stage plugins. Two entries
+   * that share a resident process are still reported in configuration order,
+   * and pending watch changes are buffered per entry by this index.
+   */
+  entryIndex: number;
+
+  /**
+   * Resident process identity: binary, plugin name, argv, and the forwarded
+   * compiler flags. `undefined` when the plugin does not declare the
+   * `residentCheck` capability.
+   */
+  key: string | undefined;
+
+  /** The configured plugin this entry runs. */
+  plugin: ITtscLoadedNativePlugin;
+};