ttsc 0.33.0 → 0.34.0

package/src/flags/COMPILER_OPTION_ASCII_FOLDS.ts

@@ -1,5 +1,5 @@
 // Code generated by packages/ttsc/scripts/gen-flags.mts. DO NOT EDIT.
-// Source of truth: pinned native OptionsDeclarations and OptionsForWatch.
+// Source of truth: pinned TypeScript 7.0 and 7.1 OptionsDeclarations and OptionsForWatch.
 // Regenerate with: pnpm format
 // Verify in CI with: node packages/ttsc/scripts/check-flags.cjs
 

package/src/flags/COMPILER_OPTION_KINDS.ts

@@ -1,5 +1,5 @@
 // Code generated by packages/ttsc/scripts/gen-flags.mts. DO NOT EDIT.
-// Source of truth: pinned native OptionsDeclarations and OptionsForWatch.
+// Source of truth: pinned TypeScript 7.0 and 7.1 OptionsDeclarations and OptionsForWatch.
 // Regenerate with: pnpm format
 // Verify in CI with: node packages/ttsc/scripts/check-flags.cjs
 import { COMPILER_OPTIONS } from "./COMPILER_OPTIONS";

package/src/flags/CompilerOptionSpec.ts

@@ -3,10 +3,10 @@
  * configuration-only options have their own lookahead rules; non-configuration
  * scalar options consume a following dash-prefixed token as data.
  *
- * @evidence contracts/common.md#principled-implementation Kind, list element and configuration-only status preserve the distinctions consumed by the pinned native parser instead of collapsing every nonboolean option into one arity.
+ * @evidence contracts/common.md#principled-implementation Kind, list element and configuration-only status preserve the distinctions consumed by the pinned native parser instead of collapsing every nonboolean option into one arity; path and command-line-only status are the declaration's own IsFilePath and IsCommandLineOnly, which decide how a command-line value moves into a tsconfig.
  * @evidence contracts/common.md#clear-and-simple-design One immutable metadata record describes grammar; occurrence reading separately owns argv lookahead and launcher FlagSpec separately owns launcher semantics.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The generator obtains these fields from exported native declarations rather than help text, spelling exceptions or source-file suffix guesses.
- * @evidence contracts/common.md#meaningful-documentation Native prose identifies the scalar, list and configuration-only distinctions; member comments state the source and optional element meaning.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the scalar, list and configuration-only distinctions; member comments state the source, optional element meaning, and which values are paths or command-line only.
  * @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.
@@ -27,4 +27,13 @@ export interface CompilerOptionSpec {
    * other kinds.
    */
   readonly configOnly: boolean;
+
+  /**
+   * Whether a command-line value names a path the compiler resolves against the
+   * working directory; for a list, whether its elements do.
+   */
+  readonly filePath: boolean;
+
+  /** Whether the compiler accepts the option only on the command line. */
+  readonly commandLineOnly: boolean;
 }

package/src/internal/pluginSource.ts

@@ -14,6 +14,7 @@
  * the one module path such a consumer imports, so the implementation keeps one
  * declaration per file.
  */
+export * from "../plugin/internal/source/CompilerTarget";
 export * from "../plugin/internal/source/collectPluginSourceFiles";
 export * from "../plugin/internal/source/pluginBuildVersions";
 export * from "../plugin/internal/source/pluginSourceCovers";

package/src/launcher/internal/TypeScriptSyncApi.ts

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+
+/**
+ * The synchronous compiler API (`typescript/sync`) of the consuming project's
+ * own TypeScript, as far as an in-memory single-root build uses it.
+ *
+ * TypeScript 7.1 publishes the API at `typescript/sync`. It drives the same
+ * native executable the command line runs, over a pipe, and adds what the
+ * command line cannot do: a snapshot whose filesystem layer supplies files that
+ * exist only in memory, and an emit that returns its files instead of writing
+ * them. TypeScript 7.0 publishes `typescript/unstable/sync`, whose program has
+ * no emit, so a 7.0 project has no such API here.
+ *
+ * The declarations are structural: they name the members this package calls,
+ * with the shapes `typescript@7.1.0-beta` gives them, rather than importing a
+ * type ttsc's own TypeScript version does not have. `load` checks each member
+ * before returning the module.
+ *
+ * @evidence contracts/common.md#principled-implementation The module is resolved through the consumer package's own exports by its manifest name, so the API is the one that package publishes and drives the executable that package ships. Member presence is checked before use; shapes are those of the published beta. Diagnostics are gathered in the compiler's own report order.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace holds the consumed API surface, its loader and the compiler's diagnostic order, apart from the build that uses them.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The API is used as published; nothing in it is patched or replaced, and a package without it yields undefined rather than an emulation.
+ * @evidence contracts/common.md#meaningful-documentation The prose states which TypeScript lines publish the API, what it adds over the command line, and why the declarations are structural.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's createRequire resolves the module from the package manifest's native path; no path is assembled by hand.
+ * @evidence contracts/performance.md#efficient-algorithms Loading reads one manifest and requires one module; Node's module cache serves later loads of the same package.
+ * @evidence contracts/performance.md#reuse-equivalent-work Node's module cache shares the loaded module across builds of one process.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The loaded module stays in Node's module cache for the process lifetime; sessions it creates are closed by their caller.
+ */
+export namespace TypeScriptSyncApi {
+  /**
+   * The loaded `typescript/sync` module.
+   *
+   * `API` starts a session whose child runs the package's native executable, or
+   * `tsserverPath` when given; the session's `close` ends it.
+   * `formatDiagnostics` renders diagnostics as the command line does without
+   * `--pretty`, with file names relative to the session's working directory.
+   *
+   * @evidence contracts/common.md#principled-implementation The members are the published 7.1 API's, typed structurally by the shapes this package calls.
+   * @evidence contracts/common.md#clear-and-simple-design Only the two members the in-memory build reaches are declared.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The type describes the published module without wrapping or replacing it.
+   * @evidence contracts/common.md#meaningful-documentation The prose states what each member starts or renders and the session's ownership of its child.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation A type declaration touches no filesystem, path or process.
+   * @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.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration holds no resource.
+   */
+  export interface Module {
+    API: new (options: { cwd?: string; tsserverPath?: string }) => Session;
+    formatDiagnostics: FormatDiagnostics;
+  }
+
+  /**
+   * Load the API of the TypeScript package whose manifest is `packageJson`.
+   *
+   * @returns The module, or `undefined` when the package publishes no `./sync`
+   *   export, it cannot be loaded, or it lacks a member the build calls.
+   * @evidence contracts/common.md#principled-implementation Node resolves `<name>/sync` through the package's own exports from its manifest; each called member is checked on the loaded classes, so a package that lacks one is refused rather than failing mid-build.
+   * @evidence contracts/common.md#clear-and-simple-design Resolution, loading and member checks form one small function returning the module or undefined.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Any load failure returns undefined so the caller keeps the command-line build; the version string is never consulted in place of the members.
+   * @evidence contracts/common.md#meaningful-documentation The returns tag names each case that yields undefined.
+   * @evidence contracts/portability.md#os-neutral-implementation createRequire takes the manifest's native path and Node's resolver handles the platform's path rules.
+   * @evidence contracts/performance.md#efficient-algorithms One manifest read and one require; later requires of the same module come from Node's cache.
+   * @evidence contracts/performance.md#reuse-equivalent-work Node's module cache shares the module across calls; a failed resolution is retried per call, costing one export lookup.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Node's module cache retains a loaded module for the process lifetime; nothing else is retained.
+   */
+  export function load(packageJson: string): Module | undefined {
+    try {
+      const { name } = JSON.parse(fs.readFileSync(packageJson, "utf8")) as {
+        name?: unknown;
+      };
+      if (typeof name !== "string") return undefined;
+      const loaded = createRequire(packageJson)(`${name}/sync`) as Record<
+        string,
+        unknown
+      >;
+      const { API, Program, formatDiagnostics } = loaded;
+      if (
+        typeof API !== "function" ||
+        typeof Program !== "function" ||
+        typeof formatDiagnostics !== "function" ||
+        !["createSnapshot", "parseCommandLine", "close"].every(
+          (member) => member in API.prototype,
+        ) ||
+        !("emitToString" in Program.prototype)
+      )
+        return undefined;
+      return loaded as unknown as Module;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * The diagnostics the command line reports for a program, in its order
+   * (`GetDiagnosticsOfAnyProgram`): configuration and syntax; then options and
+   * global diagnostics when syntax found none; then semantic diagnostics, and
+   * the global ones checking found, when those found none either.
+   *
+   * @evidence contracts/common.md#principled-implementation Mirrors TypeScript-Go's GetDiagnosticsOfAnyProgram: each later group is gathered only while no diagnostic beyond the configuration ones precedes it, and global diagnostics are asked again after checking. Declaration diagnostics are left out because the single-root build emits no declarations.
+   * @evidence contracts/common.md#clear-and-simple-design One function holds the report order the in-memory build needs for its check and failure messages.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every group comes from the compiler's own program; none is filtered or reworded.
+   * @evidence contracts/common.md#meaningful-documentation The prose gives the order and the condition for each later group.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The function exchanges diagnostics with the compiler session and touches no filesystem path itself.
+   * @evidence contracts/performance.md#efficient-algorithms At most six requests to the session; semantic checking runs only when syntax, options and global diagnostics are clean, as on the command line.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call reads one program's diagnostics once; the caller asks once per build.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The returned array holds the diagnostics until the caller discards it; the session owns everything else.
+   */
+  export function reportedDiagnostics(program: Program): Diagnostic[] {
+    const reported = [...program.getConfigFileParsingDiagnostics()];
+    const configured = reported.length;
+    reported.push(...program.getSyntacticDiagnostics());
+    if (reported.length !== configured) return reported;
+    reported.push(
+      ...program.getProgramDiagnostics(),
+      ...program.getGlobalDiagnostics(),
+    );
+    if (reported.length !== configured) return reported;
+    reported.push(
+      ...program.getSemanticDiagnostics(),
+      ...program.getGlobalDiagnostics(),
+    );
+    return reported;
+  }
+}
+
+/** Renders diagnostics, with file names relative to the host's directory. */
+type FormatDiagnostics = (
+  diagnostics: readonly Diagnostic[],
+  host: Session,
+) => string;
+
+/** One API session. */
+interface Session {
+  /** Parses argv with the session compiler's own command-line parser. */
+  parseCommandLine(args: readonly string[]): {
+    readonly errors: readonly Diagnostic[];
+  };
+
+  /**
+   * Opens projects in a new snapshot. A `layer` filesystem supplies files that
+   * take precedence over the disk.
+   */
+  createSnapshot(params: {
+    openProjects: readonly string[];
+    fileSystem: { kind: "layer"; files: Record<string, string> };
+  }): Snapshot;
+
+  /** Ends the session's child process. */
+  close(): void;
+}
+
+/** A snapshot of opened projects. */
+interface Snapshot {
+  getConfiguredProject(configFileName: string): { id: unknown } | undefined;
+  getProgram(projectId: unknown): Program | undefined;
+}
+
+/** The program of one opened project. */
+interface Program {
+  getConfigFileParsingDiagnostics(): readonly Diagnostic[];
+  getProgramDiagnostics(): readonly Diagnostic[];
+  getGlobalDiagnostics(): readonly Diagnostic[];
+  getSyntacticDiagnostics(): readonly Diagnostic[];
+  getSemanticDiagnostics(): readonly Diagnostic[];
+
+  /**
+   * Emits every file of the program the way the build would, returning the
+   * files instead of writing them. `sourceFileName` names the source an output
+   * was emitted from.
+   */
+  emitToString(): {
+    readonly emitSkipped: boolean;
+    readonly diagnostics?: readonly Diagnostic[];
+    readonly outputFiles: Iterable<
+      readonly [
+        fileName: string,
+        file: { readonly text: string; readonly sourceFileName?: string },
+      ]
+    >;
+  };
+}
+
+/** A compiler diagnostic, opaque except for rendering. */
+interface Diagnostic {
+  readonly code: number;
+}

package/src/launcher/internal/buildSingleRootInMemory.ts

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { BuildExecution } from "../../compiler/internal/build/BuildExecution";
+import { PassthroughFlags } from "../../compiler/internal/build/PassthroughFlags";
+import type { RunBuildOptions } from "../../compiler/internal/build/RunBuildOptions";
+import { TsgoArguments } from "../../compiler/internal/build/TsgoArguments";
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
+import { readCompilerOptionValues } from "../../flags/readCompilerOptionValues";
+import { hasProjectPluginEntries } from "../../plugin/internal/load/hasProjectPluginEntries";
+import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+import { TypeScriptSyncApi } from "./TypeScriptSyncApi";
+import { compilerArgsAsConfigOptions } from "./compilerArgsAsConfigOptions";
+import { DependencyBuildGeneration } from "./runtime/DependencyBuildGeneration";
+import { runtimeCompilerArgs } from "./runtimeCompilerArgs";
+import { runtimeEmitProfile } from "./runtimeEmitProfile";
+import { singleRootProjectConfig } from "./singleRootProjectConfig";
+
+/**
+ * Compile one root outside its project's file set through the consuming
+ * TypeScript's own API, with the single-root tsconfig held in memory, or report
+ * that this build cannot take that route.
+ *
+ * `buildSingleRootProject` compiles such a root through a tsconfig that extends
+ * the project and lists only the root. On the command line that tsconfig has to
+ * exist on disk, beside the project's own when a checked build needs its
+ * directory-relative lookups. TypeScript 7.1's `typescript/sync` API opens a
+ * project from a snapshot whose filesystem layer holds the tsconfig instead,
+ * and its emit returns the files rather than writing them. So here the tsconfig
+ * always sits, in memory, beside the project's own: `${configDir}`, the default
+ * `typeRoots` and every `types` entry resolve exactly as the user's config sees
+ * them, and nothing is created in the user's tree.
+ *
+ * The compiler options are the command-line build's. The arguments that build
+ * would pass after `-p` (`TsgoArguments.createTsgoBuildArgs` over the same run
+ * options) are written into the in-memory tsconfig's `compilerOptions` by
+ * `compilerArgsAsConfigOptions`, which keeps their precedence over the project.
+ * The session compiler's own command-line parser must accept them first, so an
+ * invalid argument still gets the command line's diagnostic. Outputs are
+ * written into `emitDir` only; one the options would place elsewhere is not
+ * written at all, as the command-line build's isolation keeps it inside. Each
+ * JavaScript output's source is the one the compiler emitted it from.
+ *
+ * The route is unavailable, and the caller keeps the command-line build, when
+ * the project's TypeScript publishes no such API (7.0), when a compiler binary
+ * other than that TypeScript's own or a compiler environment is selected (the
+ * binary ttsx hands its runtime is the one it resolved, so a root the running
+ * program reaches is admitted like an entry), when the build would run native
+ * plugins (they run inside ttsc's own host, which reads its tsconfig from
+ * disk), or when its arguments cannot be carried by a tsconfig: a response
+ * file, a terminal flag, or another command-line-only argument.
+ *
+ * The returned `project` is the owning project's parse. The in-memory tsconfig
+ * changes only the file set, the output layout and declaration emission, so its
+ * module options are the project's.
+ *
+ * @returns The build, or `undefined` when this route is unavailable.
+ * @throws When the build fails, with the messages of the command-line build: a
+ *   checked build fails on any diagnostic, an emit-only build only when it
+ *   produced no JavaScript.
+ * @evidence contracts/common.md#principled-implementation The command-line build's own argument composition supplies the options, translated into the extending config's compilerOptions where they keep command-line precedence, and validated by the consumer compiler's parseCommandLine. Diagnostics are gathered in the native report order (GetDiagnosticsOfAnyProgram: config and syntactic, then options and global, then semantic and the global diagnostics checking found, each later group only when no diagnostic beyond the config ones precedes), and the emit is the consumer compiler's own. Premise: a layer-filesystem config is parsed like one on disk at the same path, verified against typescript@7.1.0-beta and the 7.1 nightly the E2E lane installs.
+ * @evidence contracts/common.md#clear-and-simple-design Admission, option translation, the API session and output writing are each one step of this function, with translation and the API surface in their own modules; the caller keeps the command-line route for every refusal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every unsupported build class returns undefined to the existing command-line route instead of an approximation; no consumer or fixture is special-cased and the compiler is used through its published API.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains the in-memory placement, option equivalence, output isolation, provenance, every refusal class and the meaning of the returned project.
+ * @evidence contracts/portability.md#os-neutral-implementation Output names from the API are resolved with node:path before writing, and sources are recorded by their native real path, the spelling the command-line provenance records.
+ * @evidence contracts/performance.md#efficient-algorithms The compiler package is resolved and its API loaded first, so a 7.0 project costs one package resolution and a failed export lookup before the command-line build. An admitted build then makes one project parse, one execution resolution without plugin loading, one API session with one snapshot, one diagnostic pass when checked and one emit; an emit-only build gathers diagnostics only to explain a failure.
+ * @evidence contracts/performance.md#reuse-equivalent-work The project parse serves plugin admission, the runtime options and the execution context; the session's parse of the arguments precedes the single snapshot.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The API session is closed in finally on success and failure: close destroys its pipes and signals the child to terminate without waiting for its exit, and the API kills a child still alive when the process exits. Emitted text is held until written; the caller owns emitDir.
+ */
+export function buildSingleRootInMemory(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 naming the in-memory tsconfig. */
+  key: string;
+
+  /** Where the JavaScript goes. The directory must be private to this build. */
+  emitDir: string;
+
+  /** Whether diagnostics stop the build. */
+  checked: boolean;
+
+  /** Names the root in a failure. */
+  role: "entry" | "root";
+
+  /** Root of the source's volume, the in-memory tsconfig's `rootDir`. */
+  volumeRoot: string;
+
+  /** Build options of the caller. */
+  options: TtscCommonOptions & { cacheDir?: string };
+}):
+  | {
+      project: ReturnType<typeof readProjectConfig>;
+      rootDir: string;
+      emittedSources: Record<string, readonly string[]>;
+      emittedSourceProofFailures?: Record<string, string>;
+    }
+  | undefined {
+  const options = props.options;
+  if (
+    readCompilerOptionValues(options.passthrough).responseFiles.length !== 0 ||
+    (options.env !== undefined && Object.keys(options.env).length !== 0)
+  )
+    return undefined;
+  // Checked first: a 7.0 project, the common case, then costs one package
+  // resolution before the command-line build. The package is resolved past any
+  // selected binary, so the selection can be compared with it.
+  const packageEnv = SidecarEnvironment.merge(process.env);
+  SidecarEnvironment.write(packageEnv, "TTSC_TSGO_BINARY", undefined);
+  let compiler: ReturnType<typeof resolveTsgo>;
+  try {
+    compiler = resolveTsgo({
+      cwd: path.dirname(props.tsconfig),
+      env: packageEnv,
+    });
+  } catch {
+    // The command-line build reports a missing compiler in its own words.
+    return undefined;
+  }
+  // ttsx hands its runtime the compiler it resolved as `TTSC_TSGO_BINARY`, so
+  // only a selection naming another binary is a custom compiler.
+  const selected =
+    options.binary ?? SidecarEnvironment.read(process.env, "TTSC_TSGO_BINARY");
+  if (selected && !sameFile(selected, compiler.binary)) return undefined;
+  const api = TypeScriptSyncApi.load(compiler.packageJson);
+  if (api === undefined) return undefined;
+  const project = readProjectConfig({
+    cwd: props.projectRoot,
+    projectRoot: options.projectRoot,
+    tsconfig: props.tsconfig,
+  });
+  if (
+    hasProjectPluginEntries(project, options.plugins, options.pluginConfigDir)
+  )
+    return undefined;
+  const effectiveOptions = readEffectiveCompilerOptions(
+    project,
+    options.passthrough,
+    undefined,
+    process.env,
+  );
+  const runOptions: RunBuildOptions = {
+    checkers: options.checkers,
+    cwd: props.projectRoot,
+    emit: true,
+    outDir: props.emitDir,
+    isolateOutputsTo: props.emitDir,
+    passthrough: runtimeCompilerArgs(
+      project,
+      options.passthrough,
+      undefined,
+      effectiveOptions,
+    ),
+    forceRuntimeSourceMap: runtimeEmitProfile(
+      project,
+      options.passthrough,
+      undefined,
+      effectiveOptions,
+    ).forceRuntimeSourceMap,
+    plugins: options.plugins,
+    pluginConfigDir: options.pluginConfigDir,
+    projectRoot: options.projectRoot,
+    quiet: true,
+    resolvedProject: project,
+    singleThreaded: options.singleThreaded,
+    skipDiagnosticsCheck: !props.checked,
+    tsconfig: props.tsconfig,
+  };
+  const execution = BuildExecution.resolveExecutionContext(runOptions);
+  if (
+    execution.compilerSelection.inspectionError !== undefined ||
+    execution.pluginSetupFailure !== undefined ||
+    execution.nativePlugins.length !== 0 ||
+    !sameFile(execution.tsgo.binary, compiler.binary)
+  )
+    return undefined;
+  const buildOptions = BuildExecution.applyProjectNoEmit(runOptions, execution);
+  if (PassthroughFlags.forwardsTerminalTsgoFlag(buildOptions)) return undefined;
+  const args = TsgoArguments.createTsgoBuildArgs(execution, buildOptions, {
+    listEmittedFiles: false,
+    noEmitOnError: props.checked,
+  });
+  if (args[0] !== "-p" || args[1] !== execution.tsconfig) return undefined;
+  const assigned = compilerArgsAsConfigOptions(args.slice(2), execution.cwd);
+  if (assigned === undefined) return undefined;
+
+  const config = singleRootProjectConfig({
+    tsconfig: props.tsconfig,
+    source: props.source,
+    volumeRoot: props.volumeRoot,
+    checked: props.checked,
+  });
+  const configFile = path.join(
+    path.dirname(props.tsconfig),
+    `.ttsx-${props.role}.${props.key}.tsconfig.json`,
+  );
+  const session = new api.API({
+    cwd: execution.cwd,
+    tsserverPath: execution.tsgo.binary,
+  });
+  try {
+    if (session.parseCommandLine(args.slice(2)).errors.length !== 0)
+      return undefined;
+    const snapshot = session.createSnapshot({
+      openProjects: [configFile],
+      fileSystem: {
+        kind: "layer",
+        files: {
+          [configFile]: JSON.stringify({
+            ...config,
+            compilerOptions: { ...config.compilerOptions, ...assigned },
+          }),
+        },
+      },
+    });
+    const opened = snapshot.getConfiguredProject(configFile);
+    const program =
+      opened === undefined ? undefined : snapshot.getProgram(opened.id);
+    if (program === undefined)
+      throw new Error(
+        `ttsx: TypeScript did not open the ${props.role} project for ${props.source}`,
+      );
+    const failure = (
+      summary: string,
+      diagnostics: Parameters<TypeScriptSyncApi.Module["formatDiagnostics"]>[0],
+    ): Error =>
+      new Error(
+        [summary, api.formatDiagnostics(diagnostics, session)]
+          .filter((line) => line.trim().length !== 0)
+          .join("\n"),
+      );
+    const checkFailure = `ttsx: ${props.role} check failed for ${props.source}`;
+    if (props.checked) {
+      const diagnostics = TypeScriptSyncApi.reportedDiagnostics(program);
+      if (diagnostics.length !== 0) throw failure(checkFailure, diagnostics);
+    }
+    const emitted = program.emitToString();
+    if (props.checked && (emitted.diagnostics?.length ?? 0) !== 0)
+      throw failure(checkFailure, emitted.diagnostics!);
+    const emitDir = path.resolve(props.emitDir);
+    const emittedSources: Record<string, readonly string[]> =
+      Object.create(null);
+    const emittedSourceProofFailures: Record<string, string> =
+      Object.create(null);
+    fs.mkdirSync(emitDir, { recursive: true });
+    for (const [fileName, file] of emitted.outputFiles) {
+      const output = path.resolve(fileName);
+      const relative = path.relative(emitDir, output);
+      if (
+        relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)
+      )
+        continue;
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, file.text);
+      if (!/\.(?:js|jsx|mjs|cjs)$/i.test(output)) continue;
+      const owner = physicalSource(file.sourceFileName);
+      if (owner !== undefined) emittedSources[output] = [owner];
+      else {
+        emittedSources[output] = [];
+        emittedSourceProofFailures[output] =
+          file.sourceFileName === undefined
+            ? "TypeScript reported no source for this output."
+            : `The source TypeScript emitted this output from no longer resolves: ${JSON.stringify(file.sourceFileName)}.`;
+      }
+    }
+    if (!props.checked && !DependencyBuildGeneration.emittedAnything(emitDir))
+      throw failure(
+        `ttsx: ${props.role} build produced no output for ${props.source}`,
+        TypeScriptSyncApi.reportedDiagnostics(program),
+      );
+    return {
+      project,
+      rootDir:
+        typeof assigned.rootDir === "string"
+          ? assigned.rootDir
+          : props.volumeRoot,
+      emittedSources,
+      emittedSourceProofFailures:
+        Object.keys(emittedSourceProofFailures).length === 0
+          ? undefined
+          : emittedSourceProofFailures,
+    };
+  } finally {
+    session.close();
+  }
+}
+
+/** Whether two paths name the same existing file. */
+function sameFile(left: string, right: string): boolean {
+  try {
+    return (
+      fs.realpathSync.native(path.resolve(left)) ===
+      fs.realpathSync.native(path.resolve(right))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** The native real path of an emitted output's source, if it still exists. */
+function physicalSource(fileName: string | undefined): string | undefined {
+  if (fileName === undefined) return undefined;
+  try {
+    return fs.realpathSync.native(path.resolve(fileName));
+  } catch {
+    return undefined;
+  }
+}

package/src/launcher/internal/buildSingleRootProject.ts

@@ -8,6 +8,7 @@ import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEn
 import { createFilesystemPathIdentityContext } from "../../internal/pathIdentity/createFilesystemPathIdentityContext";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+import { buildSingleRootInMemory } from "./buildSingleRootInMemory";
 import { DependencyBuildGeneration } from "./runtime/DependencyBuildGeneration";
 import { runtimeCompilerArgs } from "./runtimeCompilerArgs";
 import { runtimeEmitProfile } from "./runtimeEmitProfile";
@@ -35,20 +36,24 @@ import { singleRootProjectConfig } from "./singleRootProjectConfig";
  * 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.
+ * combine a project with a file list, so no other placement is faithful for it.
+ * TypeScript 7.1's API can hold that tsconfig in memory, beside the real one,
+ * without creating a file: `buildSingleRootInMemory` takes the build first, and
+ * everything below runs only when that route is unavailable: for a TypeScript
+ * 7.0 project, native plugins, a custom compiler, or arguments a tsconfig
+ * cannot carry. 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
@@ -76,12 +81,12 @@ import { singleRootProjectConfig } from "./singleRootProjectConfig";
  *   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#principled-implementation The in-memory API route is tried first and owns its own admission; otherwise 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 selects the in-memory route when it is available and otherwise 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/common.md#meaningful-documentation Native paragraphs explain the in-memory route and when it is unavailable, 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#efficient-algorithms An admitted in-memory build replaces every step below with its own single API session; a refused one adds its admission (a project parse and an execution resolution without plugin loading) before them. 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.
  */
@@ -139,6 +144,8 @@ export function buildSingleRootProject(props: {
       throwOnRealpathError: false,
     }).resolve(props.source).path,
   ).root;
+  const inMemory = buildSingleRootInMemory({ ...props, options, volumeRoot });
+  if (inMemory !== undefined) return inMemory;
   const beside =
     props.checked ||
     readProjectConfig({ tsconfig: props.tsconfig }).configPaths.some((file) =>
@@ -300,6 +307,7 @@ function unwritableConfigDirectory(
       `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".`,
+      "With TypeScript 7.1 or later, a build without native plugins, a custom compiler or a response file compiles it in memory instead.",
     ].join("\n"),
   );
 }