ttsc 0.30.3 → 0.31.0

package/src/launcher/internal/PendingResidentCheckWatchChanges.ts

@@ -0,0 +1,94 @@
+import { type ResidentCheckWatchChange } from "../../compiler/internal/build/ResidentCheckWatchChange";
+import { type WatchInputChange } from "./watch/WatchInputChange";
+
+/**
+ * Coalesces filesystem events until the next resident check-watch cycle.
+ *
+ * A full reload dominates every narrower signal. Program invalidation remains
+ * distinct so a project-input module creation/deletion can cold-load the
+ * Program without discarding the selected execution or restarting the sidecar.
+ *
+ * @evidence contracts/common.md#principled-implementation Two path sets preserve changed versus declared external inputs, while reload dominates and clears narrower state; program invalidation remains a separate supported signal.
+ * @evidence contracts/common.md#clear-and-simple-design push folds event precedence and take transfers one deterministic batch then resets; callers own the scheduling and native path identity supplied here.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reload/compiler/config distinctions come from watcher protocol semantics rather than an event-count threshold or fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native class and method paragraphs explain signal dominance, external membership and reset ownership; members receive no checklist tags.
+ * @evidence contracts/performance.md#efficient-algorithms At most two Set insertions retain each event path, including string hashing/equality work. Draining sorts each distinct population with string comparisons and allocates returned references; retained path bytes grow with unique spellings until take or escalation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This accumulator merges delivery data, not completed or in-flight producer work; the caller owns scheduling checks and the session owns process reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The pending cycle owns distinct path strings and releases them on take or escalation; population is bounded by distinct events between cycles, without a separate numeric cap if the caller stops draining.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Coalesces event paths held as opaque strings; it resolves no path and touches no filesystem.
+ */
+export class PendingResidentCheckWatchChanges {
+  private readonly changed = new Set<string>();
+  private readonly external = new Set<string>();
+  private invalidate = false;
+  private reload = false;
+
+  /**
+   * Fold one filesystem event into the pending cycle.
+   *
+   * A config or plugin change, a compiler-topology change without a path, or an
+   * explicit `reload` escalates to a full reload and discards narrower signals.
+   * Otherwise the path is recorded as changed, and additionally as external
+   * when it is a declared project-rule input.
+   *
+   * @evidence contracts/common.md#principled-implementation Reload precedence is checked before incremental folding, and project events are included in both changed and external sets as required by resident checks.
+   * @evidence contracts/common.md#clear-and-simple-design One method updates the three signal forms and path sets, preserving the take boundary as the sole batch transfer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler events without a path conservatively select the supported full-reload operation instead of inventing a path or retrying a failed assumption.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify escalation triggers and distinguish changed from external inputs, with prose separated from tags.
+   * @evidence contracts/performance.md#efficient-algorithms Normal events use at most two Set insertions, including path-string hashing and equality; escalation releases both populations rather than rebuilding an event history.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Folding duplicate delivery paths establishes no shared computation result; actual check scheduling and resident reuse belong to consumers.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources This accumulator retains unique paths until take or full reload; no bound independent of the caller's drain rate is imposed.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Records event paths as opaque strings in sets and compares only event kinds; it resolves no path and touches no filesystem.
+   */
+  public push(change?: WatchInputChange, reload = false): void {
+    if (reload || change?.kind === "config" || change?.kind === "plugin") {
+      this.reload = true;
+      this.invalidate = false;
+      this.changed.clear();
+      this.external.clear();
+      return;
+    }
+    if (this.reload) return;
+    if (change?.invalidate === true) this.invalidate = true;
+    if (change?.path === undefined) {
+      if (change?.kind === "compiler") {
+        this.reload = true;
+        this.invalidate = false;
+        this.changed.clear();
+        this.external.clear();
+      }
+      return;
+    }
+    this.changed.add(change.path);
+    if (change.kind === "project") this.external.add(change.path);
+  }
+
+  /**
+   * Return everything accumulated since the last call, with paths sorted, and
+   * reset to empty.
+   *
+   * @evidence contracts/common.md#principled-implementation Optional fields encode only present signals, sorted arrays transfer set contents, and resetting every flag/set makes the next batch independent.
+   * @evidence contracts/common.md#clear-and-simple-design Batch construction and complete state reset stay in the same synchronous operation, without exposing mutable sets to consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent fields remain omitted in this watch batch instead of using consumer-specific sentinels; the wire adapter separately selects protocol fields and handles coordinator-only reload.
+   * @evidence contracts/common.md#meaningful-documentation The method documents deterministic path order and destructive drain semantics needed by callers.
+   * @evidence contracts/performance.md#efficient-algorithms Each distinct path population is copied and sorted once, including path-string comparison costs; returned arrays scale with unique references and reset releases the accumulator's ownership.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Draining transfers delivery ownership and resets state; reusing an earlier batch would replay effects rather than share equivalent producer work.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Ownership of arrays transfers to the caller while the accumulator clears its sets and flags; retaining returned batches is the consumer's responsibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Draining reads and clears this instance's flags and opaque path sets without resolving filesystem identity or calling a native process API.
+   */
+  public take(): ResidentCheckWatchChange {
+    const change: ResidentCheckWatchChange = {
+      ...(this.reload ? { reload: true } : {}),
+      ...(this.invalidate ? { invalidate: true } : {}),
+      ...(this.changed.size === 0 ? {} : { changed: [...this.changed].sort() }),
+      ...(this.external.size === 0
+        ? {}
+        : { external: [...this.external].sort() }),
+    };
+    this.reload = false;
+    this.invalidate = false;
+    this.changed.clear();
+    this.external.clear();
+    return change;
+  }
+}

package/src/launcher/internal/TtscBuildMode.ts

@@ -0,0 +1,14 @@
+/**
+ * Supported compiler commands sharing the launcher build adapter. Mutation
+ * commands reject watch and single-file modes; check suppresses one-shot emit.
+ *
+ * @evidence contracts/common.md#principled-implementation Four literal commands represent exactly the compiler commands that share the launcher build adapter.
+ * @evidence contracts/common.md#clear-and-simple-design A closed union lets the same command decision serve CLI execution and direct unit verification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported command strings cannot enter the adapter through this maintained type.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the supported command distinction and its mutation/check consequences.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export type TtscBuildMode = "build" | "check" | "fix" | "format";

package/src/launcher/internal/TtsxEntryOptions.ts

@@ -0,0 +1,92 @@
+import path from "node:path";
+
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+import type { parseTtsxCLI } from "./parseTtsxCLI";
+
+/**
+ * Prepares Node entry options without invoking the compiler or host.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate JavaScript build-option applicability from preload path classification; public launcher callers consume these exact results before starting native execution.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace groups two pure entry-boundary projections with one private lexical relative-path predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only supported launcher fields and native path APIs decide behavior; no consumer-specific preload, private Node method or fixture answer is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute/path.resolve own filesystem spelling; bare and scoped package specifiers retain Node module-resolution ownership without manual case or slash rewriting.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups two concrete operations; their methods describe their own input processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+ */
+export namespace TtsxEntryOptions {
+  /**
+   * Lists the options JavaScript entries cannot apply to an up-front TypeScript
+   * build.
+   *
+   * Values and program arguments are not options; their spelling remains
+   * intact.
+   *
+   * @evidence contracts/common.md#principled-implementation The parsed launcher fields name up-front build policy; native occurrence widths distinguish compiler and response-file requests from their scalar operands before JavaScript entry applicability is reported.
+   * @evidence contracts/common.md#clear-and-simple-design A fixed field projection followed by one native-frame traversal preserves original request spellings and deterministic diagnostic order.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The result is the actual caller diagnostic input, not a second CLI parser or a test-only whitelist.
+   * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This pure option record and token classification resolves no filesystem path and starts no process.
+   * @evidence contracts/performance.md#efficient-algorithms Traversing T forwarded tokens advances by each native occurrence width in O(T+B) time for their B inspected token/list bytes and retains at most O(T) returned request references; the fixed launcher fields require bounded additional work.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+   */
+  export function unsupportedJavaScriptBuildOptions(
+    parsed: Exclude<ReturnType<typeof parseTtsxCLI>, "help" | "version">,
+  ): string[] {
+    const forwarded: string[] = [];
+    for (let index = 0; index < parsed.tsgoFlags.length; ) {
+      const token = parsed.tsgoFlags[index]!;
+      if (token.startsWith("-") || token.startsWith("@")) forwarded.push(token);
+      index += readCompilerOptionOccurrence(parsed.tsgoFlags, index).width;
+    }
+    return [
+      ...(parsed.project !== undefined ? ["--project"] : []),
+      ...(parsed.cacheDir !== undefined ? ["--cache-dir"] : []),
+      ...(parsed.checkers !== undefined ? ["--checkers"] : []),
+      ...(parsed.noPlugins ? ["--no-plugins"] : []),
+      ...(parsed.singleThreaded ? ["--singleThreaded"] : []),
+      ...forwarded,
+    ];
+  }
+
+  /**
+   * Anchors file preloads to the invocation directory and leaves package names
+   * to Node.
+   *
+   * Relative file spellings and already absolute paths use native path
+   * resolution; scoped and subpath package requests must not be anchored to the
+   * launcher install.
+   *
+   * @evidence contracts/common.md#principled-implementation Native absolute paths and explicit relative spellings denote files, while other requests remain module specifiers for Node resolution.
+   * @evidence contracts/common.md#clear-and-simple-design One native absolute check and one lexical relative check precede path.resolve; package specifiers return unchanged.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No foreign resolver is patched and no installed-package lookup or guessed extension changes the caller request.
+   * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute and path.resolve preserve host path semantics; explicit dot/slash or dot/backslash relative forms are classified without case folding or manual file URLs.
+   * @evidence contracts/performance.md#efficient-algorithms Fixed prefix checks and one native path normalization cost O(P) path bytes with no filesystem traversal or per-package lookup.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+   */
+  export function resolvePreload(cwd: string, preload: string): string {
+    if (path.isAbsolute(preload) || isRelativeSpecifier(preload)) {
+      return path.resolve(cwd, preload);
+    }
+    return preload;
+  }
+
+  /**
+   * Explicit relative file spellings; bare package specifiers remain module
+   * requests.
+   */
+  function isRelativeSpecifier(specifier: string): boolean {
+    return (
+      specifier === "." ||
+      specifier === ".." ||
+      specifier.startsWith("./") ||
+      specifier.startsWith("../") ||
+      specifier.startsWith(".\\") ||
+      specifier.startsWith("..\\")
+    );
+  }
+}

package/src/launcher/internal/assertNoSolutionBuild.ts

@@ -1,18 +1,16 @@
-import { type ParseResult } from "../../flags/parser";
+import { type ParseResult } from "../../flags/ParseResult";
 
 /**
  * Refuse tsgo's solution-build mode (`--build` / `-b`) in the launcher's own
  * voice, for whichever launcher parsed the arguments.
  *
- * Every ttsc build lane hands tsgo an argument list that opens with the project
- * ttsc resolved (`-p <tsconfig>` in `createTsgoBuildArgs`), because ttsc — not
- * tsgo — owns the `extends` chain, plugin config discovery, cache keys, and the
- * resident session's identity, and pins that one resolved project instead of
- * forwarding raw argv. A forwarded `--build` therefore always arrives after
- * `-p`, and tsgo replies "Option '--build' must be the first command line
- * argument" even though the user wrote it first. No spelling of the command
- * line can satisfy that diagnostic, so the flag is rejected here rather than
- * forwarded into an error that blames the user's argument order.
+ * Project-dependent builds select one config for plugin discovery, cache keys
+ * and resident identity. The direct compiler argv opens with that selection
+ * (`-p <tsconfig>` in `createTsgoBuildArgs`); TypeScript-Go still reads its own
+ * config and inheritance. Forwarding `--build` on this lane would place it
+ * after `-p`, producing "Option '--build' must be the first command line
+ * argument" even when the user wrote it first. Rejecting the unsupported mode
+ * here preserves the single-project contract instead of blaming user order.
  *
  * Both launchers refuse it, because both reach tsgo through the same pinned
  * project. `ttsx` additionally builds one entry inside that project, so a mode
@@ -28,6 +26,15 @@ import { type ParseResult } from "../../flags/parser";
  * `forwardAfterFirstPositional` and `honorDoubleDashSeparator`, so a token
  * after the entry lands in `result.tail` and never in `result.values`; reading
  * `values` is what keeps `ttsx script.ts --build` the user program's own flag.
+ *
+ * @evidence contracts/common.md#principled-implementation Presence in the launcher's parsed values identifies a requested unsupported compiler mode; the program's post-entry arguments are outside this map.
+ * @evidence contracts/common.md#clear-and-simple-design A shared pre-build guard owns this unsupported-mode diagnostic for both launchers instead of rewriting compiler argument order.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rejection follows the supported single-project contract, including an explicit false token, without compensating for a tsgo diagnostic through a synthetic solution build.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain pinned-project semantics, presence detection and the boundary with user-program flags, with tags separated from prose.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources One presence check returns or throws without retaining the parsed map or acquiring a native resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One canonical-key membership check makes a fixed mode decision; flag parsing and compiler execution belong to their existing owners.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A mode refusal coordinates no producer computation or cross-call result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This guard inspects a canonical option key and constructs diagnostic text; native paths, processes and OS capability discovery are outside its operation.
  */
 export function assertNoSolutionBuild(
   result: ParseResult,

package/src/launcher/internal/assertTtsxNoWatch.ts

@@ -0,0 +1,49 @@
+import { CompilerArgumentsInspection } from "../../compiler/internal/CompilerArgumentsInspection";
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+import { readCompilerOptionValues } from "../../flags/readCompilerOptionValues";
+import { resolveFlagSpec } from "../../flags/resolveFlagSpec";
+
+/**
+ * Refuse `--watch` (or `-w`) before the one-shot ttsx check or build starts.
+ *
+ * A watch that restarts the program is a different feature; the message names
+ * the tools that provide its two halves. Arguments after the entry belong to
+ * the program and never reach this guard. Parsing supplies its compiler tokens
+ * without a cwd and remains in-memory. Preparation supplies the selected
+ * project's actual compiler cwd, after project/reference discovery and before
+ * effective-option reporting, cache writes or a checked build, to inspect
+ * response frames through their shared owner.
+ *
+ * Even an explicit false/null watch request is unsupported, matching direct
+ * launcher flags. Inspection failures propagate before a build starts. The
+ * observation does not pin response bytes against subsequent filesystem edits.
+ *
+ * @evidence contracts/common.md#principled-implementation The same refusal owns direct launcher requests and observed response options; native occurrence widths preserve scalar operands and preparation supplies the selected project root.
+ * @evidence contracts/common.md#clear-and-simple-design One mode guard serves parsing and the pre-build boundary, delegating response expansion to the existing inspection owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No compiler grammar or watcher behavior is replaced; unsupported watch requests throw before execution and inspection failures remain failures.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish direct parsing, project-relative response observation and program argv, and state the observation's lifetime limit.
+ * @evidence contracts/portability.md#os-neutral-implementation Response resolution and UTF decoding belong to the shared native filesystem inspector; the guard receives a native directory rather than assuming the invocation cwd.
+ * @evidence contracts/performance.md#efficient-algorithms One occurrence scan finds response requests and another finds watch. When expansion is needed its delegated path/read/hash/token costs follow all expanded bytes, depth and occurrences without a fixed cap.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each admission observes the current response contents and retains no historical answer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Inspection transfers call-local arrays and synchronous observations; this guard retains no handles, process or cache.
+ */
+export function assertTtsxNoWatch(
+  args: readonly string[],
+  compilerCwd?: string,
+): void {
+  if (
+    compilerCwd !== undefined &&
+    readCompilerOptionValues(args).responseFiles.length !== 0
+  ) {
+    args = CompilerArgumentsInspection.inspect(args, compilerCwd).args;
+  }
+  let watching = false;
+  for (let index = 0; !watching && index < args.length; ) {
+    watching = resolveFlagSpec(args[index]!)?.name === "--watch";
+    index += readCompilerOptionOccurrence(args, index).width;
+  }
+  if (!watching) return;
+  throw new Error(
+    "ttsx: --watch is not supported; ttsx type-checks once and then runs the entry. For a watching type-check use `ttsc --watch --noEmit`; to restart the program on changes use `node --watch --require ttsc/register <entry.ts>`. Arguments after the entry, including --watch, go to the program.",
+  );
+}

package/src/launcher/internal/buildSingleRootProject.ts

@@ -0,0 +1,303 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { runBuild } from "../../compiler/internal/build/runBuild";
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import { createFilesystemPathIdentityContext } from "../../internal/pathIdentity/createFilesystemPathIdentityContext";
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+import { DependencyBuildGeneration } from "./runtime/DependencyBuildGeneration";
+import { runtimeCompilerArgs } from "./runtimeCompilerArgs";
+import { runtimeEmitProfile } from "./runtimeEmitProfile";
+import { singleRootProjectConfig } from "./singleRootProjectConfig";
+
+/**
+ * Compile one TypeScript root that its owning project's file set does not
+ * contain, with every compiler option of that project.
+ *
+ * `ttsc` selects a _file set_: a project whose `include` is `src` must emit
+ * only `src` into `outDir`, and a `clear.ts`, a `build/release.ts`, or a
+ * `lint.config.ts` beside the tsconfig has no business in `lib`. `ttsx` needs
+ * that project's compiler options for a file it runs, not its file list. Those
+ * two requirements are not in conflict, but the whole-project build cannot
+ * satisfy the second, so such a root is compiled here through a project that
+ * inherits every option and declares only the root. Two lanes need it: the
+ * launcher's entry when the project build did not emit it, and a TypeScript
+ * file the running program reaches that no build compiled.
+ *
+ * Where the synthesized tsconfig lives depends on what the build reads from its
+ * location. `extends` with an absolute path resolves from anywhere, and every
+ * relative option resolves against the config that declares it, but
+ * `${configDir}` is substituted with the directory of the config tsgo was
+ * given, and the default `typeRoots` and each `types` entry are looked up from
+ * there. A checked build needs all of them exactly as the user's config sees
+ * them, so its tsconfig is written beside the real one, and a directory that
+ * refuses the write is reported by name. TypeScript-Go's command line cannot
+ * combine a project with a file list, and ttsc ships no host that replaces a
+ * project's roots in memory, so no other placement is faithful. An emit-only
+ * build ignores diagnostics, and none of those lookups changes what it emits,
+ * with one exception: `${configDir}` inside `paths` or `baseUrl` decides which
+ * module an import resolves to, and so whether a re-exported name is elided as
+ * a type. Unless its config chain uses `${configDir}`, an emit-only build's
+ * tsconfig is written beside `emitDir` instead, because such a build runs while
+ * the program is running, for an installed package whose directory may be
+ * read-only or for a plugin descriptor whose inputs are fingerprinted by their
+ * directory's metadata, and a file created and removed in the user's tree would
+ * disturb both. The overlay is created exclusively: an occupied name is refused
+ * without writing or removing that entry. After acquisition, closing its
+ * descriptor and removing the overlay are attempted on success or failure;
+ * native cleanup failures may leave the overlay behind.
+ *
+ * `rootDir` is the root of the source's volume. The layout of this emit is
+ * private, so `rootDir` decides nothing here but whether a file of the program
+ * fits under it, and every narrower choice fails some program: the inherited
+ * `rootDir` (`src`) does not contain the root, and a root that imports a
+ * sibling package's source reaches outside any ancestor it shares with the
+ * project. A file outside `rootDir` is TS6059 in a checked build and, in an
+ * emit-only one, an output written beside the user's `.ts`. The caller finds
+ * the output through `EmitOwnershipIndex` against the returned `rootDir`, so
+ * the width costs nothing in precision. A `--rootDir` forwarded on the command
+ * line still wins, as it does in every build, and the returned `rootDir` is
+ * then that one.
+ *
+ * `composite` is switched off. It exists for `tsc -b`, whose project graph
+ * needs every file listed, and inherited here it would reject each import of
+ * the root with TS6307, since only the root is listed. Declarations go with it:
+ * nothing at run time reads them, and an inherited `declarationMap` would
+ * otherwise fail with TS5069 once `composite` no longer implies `declaration`.
+ * An emit-only build also switches `noEmitOnError` off, since it fails only on
+ * an empty output and an inherited `noEmitOnError` would turn any diagnostic
+ * into one.
+ *
+ * @returns The project, effective `rootDir` and compiler-owned source
+ *   provenance for actual written outputs. Missing provenance is not
+ *   synthesized from maps.
+ * @throws When the build fails. A checked build fails on any diagnostic; an
+ *   emit-only build fails only when it produced no JavaScript at all.
+ * @evidence contracts/common.md#principled-implementation A transient extends overlay changes only roots and runtime output constraints, while preserving configDir-sensitive anchors; effective rootDir is returned for output ownership rather than inferred from emitted filenames.
+ * @evidence contracts/common.md#clear-and-simple-design This boundary owns single-root overlay construction and cleanup, delegates project parsing/building, and isolates writable-directory diagnostics in a private helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Private emit layout, disabled declaration/composite products and checked versus installed-package diagnostics are runtime contract distinctions, not source patches or tests-only compiler modes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain overlay placement, wide rootDir, diagnostics and cleanup, while separately documented input members preserve their ownership facts.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared filesystem identity selects the source volume from resolved native identity when available and retained spelling otherwise; overlay JSON converts only native separators, preserving literal POSIX backslashes. Public exclusive creation refuses an occupied overlay name without overwriting it; explicit compiler paths avoid shell interpolation and blanket case folding.
+ * @evidence contracts/performance.md#efficient-algorithms Emit-only placement parses the config chain and scans its text for configDir anchors; checked placement skips that scan. Native identity resolution, overlay serialization/write, effective-options preparation and delegated compilation contribute path/input/output byte costs; this boundary performs no source-directory mirror or second whole-project compilation.
+ * @evidence contracts/performance.md#reuse-equivalent-work One effective-options reader for this overlay and exact forwarded tokens is shared by runtime lowering, emit classification and rootDir selection, avoiding duplicate response-file compiler queries. Callers own sharing of completed build generations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Exclusive open establishes ownership of one transient tsconfig and descriptor. The descriptor is closed before parsing; finally attempts any remaining close and removal after write, close, parse or build failure, without removing a failed-acquisition entry. Native cleanup failures may retain the overlay; caller owns emit storage and delegated build lifetimes.
+ */
+export function buildSingleRootProject(props: {
+  /** The root, in the physical spelling the runtime loads it by. */
+  source: string;
+
+  /** The owning `tsconfig.json`, whose options the root inherits. */
+  tsconfig: string;
+
+  /** Directory the build runs in. */
+  projectRoot: string;
+
+  /** Directory-safe token, unique per concurrent build of one tsconfig. */
+  key: string;
+
+  /** Where the JavaScript goes. The directory must be private to this build. */
+  emitDir: string;
+
+  /**
+   * Whether diagnostics stop the build. A root of the user's program is
+   * checked; a root inside an installed package is emit-only, matching the
+   * policy for every other file of that package.
+   */
+  checked: boolean;
+
+  /** Names the root in a failure: `entry` for the launcher's own entry. */
+  role: "entry" | "root";
+
+  /** Build options forwarded to `runBuild`. */
+  options?: TtscCommonOptions & { cacheDir?: string };
+}): {
+  /** Parsed overlay project whose compiler options governed this build. */
+  project: ReturnType<typeof readProjectConfig>;
+
+  /** Effective native layout root, including any forwarded rootDir override. */
+  rootDir: string;
+
+  /** Actual written output to compile-time source ledger; absent means unknown. */
+  emittedSources?: TtscBuildResult["emittedSources"];
+
+  /** Actual output-specific proof refusal context, independent of diagnostics. */
+  emittedSourceProofFailures?: TtscBuildResult["emittedSourceProofFailures"];
+} {
+  const options = props.options ?? {};
+  // `source` already carries the one spelling the runtime decided on. tsgo
+  // compares it against `rootDir` textually — `GetCommonSourceDirectory` takes
+  // `rootDir` verbatim and `ContainsPath` is lexical — so a mismatch here is
+  // not a near miss: the file counts as outside `rootDir`, and tsgo emits it to
+  // its own source path with the extension changed instead of under `outDir`,
+  // writing a `.js` and its map beside the user's `.ts` where nothing cleans
+  // them up.
+  const volumeRoot = path.parse(
+    createFilesystemPathIdentityContext({
+      throwOnRealpathError: false,
+    }).resolve(props.source).path,
+  ).root;
+  const beside =
+    props.checked ||
+    readProjectConfig({ tsconfig: props.tsconfig }).configPaths.some((file) =>
+      fs.readFileSync(file, "utf8").includes("${configDir}"),
+    );
+  const tsconfig = path.join(
+    beside ? path.dirname(props.tsconfig) : path.dirname(props.emitDir),
+    `.ttsx-${props.role}.${props.key}.tsconfig.json`,
+  );
+  fs.mkdirSync(path.dirname(tsconfig), { recursive: true });
+  let configDescriptor: number | undefined;
+  let ownsConfig = false;
+  try {
+    try {
+      configDescriptor = fs.openSync(tsconfig, "wx");
+      ownsConfig = true;
+      fs.writeFileSync(
+        configDescriptor,
+        JSON.stringify(
+          singleRootProjectConfig({
+            tsconfig: props.tsconfig,
+            source: props.source,
+            volumeRoot,
+            checked: props.checked,
+          }),
+          null,
+          2,
+        ),
+        "utf8",
+      );
+      fs.closeSync(configDescriptor);
+      configDescriptor = undefined;
+    } catch (error) {
+      throw unwritableConfigDirectory(error, props, path.dirname(tsconfig));
+    }
+    const project = readProjectConfig({
+      cwd: props.projectRoot,
+      // A tsconfig outside the project would otherwise make its own private
+      // directory the project root.
+      projectRoot:
+        options.projectRoot ?? (beside ? undefined : props.projectRoot),
+      tsconfig,
+    });
+    fs.mkdirSync(props.emitDir, { recursive: true });
+    const effectiveOptions = readEffectiveCompilerOptions(
+      project,
+      options.passthrough,
+      options.binary,
+    );
+    const result = runBuild({
+      binary: options.binary,
+      checkers: options.checkers,
+      cwd: props.projectRoot,
+      emit: true,
+      env: options.env,
+      cacheDir: options.cacheDir,
+      outDir: props.emitDir,
+      // Every output this build writes stays in ttsx's private directory: a
+      // declared `declarationDir`, `tsBuildInfoFile`, or `outFile`, and any
+      // output location forwarded on the command line, would otherwise land in
+      // the user's tree.
+      isolateOutputsTo: props.emitDir,
+      passthrough: runtimeCompilerArgs(
+        project,
+        options.passthrough,
+        options.binary,
+        effectiveOptions,
+      ),
+      // A source map on the transient emit lets the serve path inline it under
+      // the source URL; a project that configures its own keeps it.
+      forceRuntimeSourceMap: runtimeEmitProfile(
+        project,
+        options.passthrough,
+        options.binary,
+        effectiveOptions,
+      ).forceRuntimeSourceMap,
+      forceEmitProvenance: true,
+      // Native plugins discover their config files from the tsconfig's
+      // directory, which for a private tsconfig is ttsx's cache; anchor them
+      // at the real one, as a bundler adapter's temporary overlay does.
+      pluginConfigDir:
+        options.pluginConfigDir ??
+        (beside ? undefined : path.dirname(props.tsconfig)),
+      plugins: options.plugins,
+      quiet: true,
+      resolvedProject: project,
+      singleThreaded: options.singleThreaded,
+      skipDiagnosticsCheck: !props.checked,
+      tsconfig,
+    });
+    // An emit-only build reports its diagnostics through the exit status even
+    // though it wrote the JavaScript, so only an empty output fails it — the
+    // same rule the dependency lane applies to the package's other files.
+    const failed = props.checked
+      ? result.status !== 0
+      : !DependencyBuildGeneration.emittedAnything(props.emitDir);
+    if (failed) {
+      throw new Error(
+        [
+          props.checked
+            ? `ttsx: ${props.role} check failed for ${props.source}`
+            : `ttsx: ${props.role} build produced no output for ${props.source}`,
+          result.stderr || result.stdout,
+        ]
+          .filter((line) => line.trim().length !== 0)
+          .join("\n"),
+      );
+    }
+    // The root the compiler actually laid the outputs against: the one written
+    // above unless the command line forwarded another.
+    const effective = effectiveOptions?.("rootDir");
+    return {
+      emittedSources: result.emittedSources,
+      emittedSourceProofFailures: result.emittedSourceProofFailures,
+      project,
+      rootDir:
+        typeof effective === "string"
+          ? path.resolve(project.root, effective)
+          : volumeRoot,
+    };
+  } finally {
+    if (configDescriptor !== undefined) {
+      try {
+        fs.closeSync(configDescriptor);
+      } catch {
+        // Preserve the write or close failure that reached this cleanup.
+      }
+    }
+    if (ownsConfig) {
+      try {
+        fs.rmSync(tsconfig, { force: true });
+      } catch {
+        // Best effort: native cleanup failure can leave this overlay behind.
+      }
+    }
+  }
+}
+
+/**
+ * The error for a synthesized tsconfig the filesystem refused, naming the
+ * directory and what to do instead of surfacing a bare `EPERM`. Any other
+ * failure is returned unchanged.
+ *
+ * TypeScript-Go's command line cannot combine a project with a file list, so a
+ * build that must read the anchors of a tsconfig from its own directory needs a
+ * tsconfig in that directory. A read-only checkout, mount, or volume refuses
+ * it.
+ */
+function unwritableConfigDirectory(
+  error: unknown,
+  props: { source: string; tsconfig: string },
+  directory: string,
+): unknown {
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  if (code !== "EACCES" && code !== "EPERM" && code !== "EROFS") return error;
+  return new Error(
+    [
+      `ttsx: cannot compile ${props.source} with the options of ${props.tsconfig}: ${directory} is not writable (${code}).`,
+      "The file is outside that project's file set, and ttsx compiles it through a temporary tsconfig placed beside the project's own for the length of the build.",
+      `Make the directory writable, or add the file to the project's "include" or "files".`,
+    ].join("\n"),
+  );
+}