ttsc 0.33.0 → 0.34.0

package/src/launcher/internal/compilerArgsAsConfigOptions.ts

@@ -0,0 +1,112 @@
+import path from "node:path";
+
+import { normalizeCompilerEnumValue } from "../../flags/normalizeCompilerEnumValue";
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+
+/**
+ * Translate compiler command-line arguments into the `compilerOptions` of a
+ * tsconfig that extends the project, so that a build which opens that tsconfig
+ * alone sees the options the arguments would have given it.
+ *
+ * TypeScript applies command-line options over the options of the config it
+ * builds, and an extending config's own `compilerOptions` override the config
+ * it extends in the same way. So the assignments of `args`, written into the
+ * extending config, win over the project exactly as they would on the command
+ * line. Each value is converted the way the compiler parses it from argv: the
+ * last occurrence of an option wins; `null` resets an inherited value; enum
+ * values are trimmed and lowercased; a list value is split at commas and loses
+ * its empty members; and a value that names a path is resolved against `cwd`,
+ * because the compiler resolves a command-line path against its working
+ * directory while a config path resolves against the config's directory.
+ *
+ * Arguments that a config cannot carry make the translation unavailable, so the
+ * caller keeps a build that passes them on the command line: a response file, a
+ * positional file name, an unknown option, an option the compiler accepts only
+ * on the command line, a project selection, the trace and profile options whose
+ * artifacts the compiler writes itself, and a value containing `${configDir}`,
+ * which a config would substitute and the command line does not. The
+ * translation assumes valid arguments; the caller confirms them with the same
+ * compiler's own command-line parser before using the result.
+ *
+ * @param args Compiler arguments without the leading `-p <tsconfig>`.
+ * @param cwd The directory the compiler would run in.
+ * @returns The assignments by canonical option name, or `undefined` when the
+ *   arguments cannot be carried by a config.
+ * @evidence contracts/common.md#principled-implementation Each occurrence is classified by the pinned native grammar (readCompilerOptionOccurrence) and its value converted by the native command-line rules: null resets, last occurrence wins, enum trim and lowercase, list TrimSpace and comma split with empty members dropped, and paths resolved against the working directory. Command-line options override the configured ones as an extending config's options override its base, so writing them into the extending config preserves precedence. Premise: the arguments are valid; the caller verifies that with the consumer compiler's parseCommandLine. Options newer than the pinned table are unknown here and make the translation unavailable.
+ * @evidence contracts/common.md#clear-and-simple-design One pure function owns the argv-to-config translation; the build that consumes it owns compiler selection, validation and emission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported argument classes return undefined so the caller keeps the command-line build instead of approximating them; no option is special-cased by consumer or fixture.
+ * @evidence contracts/common.md#meaningful-documentation The prose states the precedence premise, every conversion rule, each class that makes the translation unavailable and the validity premise.
+ * @evidence contracts/portability.md#os-neutral-implementation Path values are resolved with node:path against the supplied working directory, so drive letters and separators follow the host; no other value is touched as a path.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over the arguments with a constant-time table lookup per option and a split per list value.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The translation depends only on its arguments and is computed once per build.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned record is the only allocation and transfers to the caller.
+ */
+export function compilerArgsAsConfigOptions(
+  args: readonly string[],
+  cwd: string,
+): Record<string, unknown> | undefined {
+  const options: Record<string, unknown> = {};
+  for (let index = 0; index < args.length; ) {
+    if (args[index]!.startsWith("@")) return undefined;
+    const occurrence = readCompilerOptionOccurrence(args, index);
+    const option = occurrence.option;
+    if (
+      option === undefined ||
+      option.commandLineOnly ||
+      COMMAND_LINE_OUTPUTS.has(option.name)
+    )
+      return undefined;
+    const next = occurrence.width === 2 ? args[index + 1]! : undefined;
+    let value: unknown;
+    if (next === "null") value = null;
+    else if (option.configOnly) {
+      // The command line accepts only `null`, or `false` for a boolean.
+      if (option.kind !== "boolean" || next !== "false") return undefined;
+      value = false;
+    } else if (option.kind === "boolean") value = occurrence.booleanValue;
+    else if (next === undefined)
+      // A list whose value is empty; any other kind is an invalid argument.
+      value = [];
+    else if (next.includes("${configDir}")) return undefined;
+    else if (option.kind === "number") value = Number(next);
+    else if (option.kind === "enum")
+      value = normalizeCompilerEnumValue(next, "cli");
+    else if (option.kind === "list")
+      value = splitList(next, option.element === "enum", option.filePath, cwd);
+    else value = option.filePath ? path.resolve(cwd, next) : next;
+    options[option.name] = value;
+    index += occurrence.width;
+  }
+  return options;
+}
+
+/**
+ * Options whose output the compiler writes itself, outside the emit: a config
+ * route that only collects emitted files cannot produce them.
+ */
+const COMMAND_LINE_OUTPUTS: ReadonlySet<string> = new Set([
+  "project",
+  "generateTrace",
+  "generateCpuProfile",
+  "pprofDir",
+]);
+
+/** Members of a command-line list value, as the native parser reads them. */
+function splitList(
+  value: string,
+  enumMembers: boolean,
+  filePath: boolean,
+  cwd: string,
+): string[] {
+  // Go strings.TrimSpace follows Unicode White_Space for the whole value;
+  // enum members are then trimmed with the compiler's IsWhiteSpaceLike set.
+  const trimmed = value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "");
+  if (trimmed === "" || trimmed.startsWith("-")) return [];
+  const members: string[] = [];
+  for (const part of trimmed.split(",")) {
+    const member = enumMembers ? normalizeCompilerEnumValue(part, "cli") : part;
+    if (member === null || member === "") continue;
+    members.push(filePath ? path.resolve(cwd, member) : member);
+  }
+  return members;
+}

package/src/plugin/CapabilityPluginResolver.ts

@@ -69,7 +69,10 @@ export class CapabilityPluginResolver {
     return {
       status: value.status,
       plugins: value.plugins,
-      isCurrent: async ({ signal } = {}) =>
+      // TypeScript 7.1 nightlies drop the contextual type of a defaulted
+      // binding pattern (microsoft/TypeScript#64431, fix in #64671), so the
+      // option type is spelled out for both compiler lines.
+      isCurrent: async ({ signal }: { signal?: AbortSignal } = {}) =>
         released || this.closed
           ? false
           : ((await this.request(

package/src/plugin/internal/load/loadProjectPlugins.ts

@@ -24,6 +24,7 @@ import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITts
 import type { TtscPluginSourceInputsHandler } from "../../../structures/internal/TtscSingleFileEmitOptions";
 import { pluginDescriptorFailureReason } from "../pluginDescriptorFailureReason";
 import { pluginDescriptorProcessFailure } from "../pluginDescriptorProcessFailure";
+import { CompilerTarget } from "../source/CompilerTarget";
 import { NativeSourcePackages } from "../source/NativeSourcePackages";
 import type { PluginBuildEnvironmentWitness } from "../source/PluginBuildEnvironmentWitness";
 import { PluginContentIdentities } from "../source/PluginContentIdentities";
@@ -242,7 +243,7 @@ export namespace loadProjectPlugins {
     // host-owned Node/ttsx locators into process.env. Under a Bun parent the
     // direct descriptor evaluator must remain Bun unless the caller explicitly
     // selected another runtime.
-    const effectiveEnv = SidecarEnvironment.merge(options.env ?? process.env);
+    const callerEnv = SidecarEnvironment.merge(options.env ?? process.env);
     const projectSnapshot = readProjectHostInputSnapshot({
       cwd: options.cwd,
       file: options.file,
@@ -285,6 +286,13 @@ export namespace loadProjectPlugins {
       };
     }
 
+    // Every Go command of this load compiles the compiler target of the
+    // project's TypeScript line; the target travels in the environment.
+    const effectiveEnv = CompilerTarget.buildEnv(
+      callerEnv,
+      CompilerTarget.resolve(project.root, callerEnv),
+      project.root,
+    );
     const cwd = path.resolve(options.cwd ?? process.cwd());
     const context = {
       binary: options.binary,
@@ -462,7 +470,9 @@ export namespace loadProjectPlugins {
         candidate.packageDir,
         ...(candidate.contributors ?? []).map((input) => input.source),
       ]),
-      ...SourcePluginWorkspace.findTtscOverlayDirs(),
+      ...SourcePluginWorkspace.findTtscOverlayDirs(
+        CompilerTarget.ofEnv(effectiveEnv),
+      ),
     ]);
     // One fixed-effective-environment load owns manifest syntax sharing from the
     // first watch query through metadata and builds. Do not allocate this after

package/src/plugin/internal/source/CompilerTarget.ts

@@ -0,0 +1,249 @@
+import { outputText } from "../../../compiler/internal/outputText";
+import { resolveTsgo } from "../../../compiler/internal/resolveTsgo";
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import { spawnNative } from "../../../compiler/internal/spawnNative";
+import { GoSourceInputs } from "./GoSourceInputs";
+import { GoToolResolution } from "./GoToolResolution";
+import { resolveGoCompiler } from "./resolveGoCompiler";
+import { spawnGoTool } from "./spawnGoTool";
+
+/**
+ * The compiler target a source build compiles against, chosen from the
+ * TypeScript line the project installs.
+ *
+ * Each ttsc release ships one shim tree per supported TypeScript minor line:
+ * the 7.0 tree over `github.com/microsoft/typescript-go` and the 7.1 bridges
+ * and facades over `github.com/microsoft/TypeScript/tsc`. A plugin, the
+ * in-memory compiler host and the linked plugin host all build against the
+ * target of the project's line, so their checker is the compiler the project's
+ * own `tsc` runs. A line newer than every target builds with the newest one,
+ * after a warning; a version ttsc cannot read builds with the 7.0 target, which
+ * every installation ships.
+ *
+ * @evidence contracts/common.md#principled-implementation The target follows the installed compiler's major.minor line, the unit at which the shim API is audited; a prerelease of a line such as 7.1.0-dev belongs to that line. A newer line falls back to the newest audited target rather than to an unaudited commit.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns line parsing, version reading and the target's build tag, leaving overlay discovery to SourcePluginWorkspace and builds to buildSourcePlugin.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No project, plugin or fixture name selects a target; only the compiler version does.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the supported lines, the newer-line fallback and the unreadable-version default.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace declaration itself performs no native operation; its members state their own boundaries.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace declaration executes nothing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace declaration coordinates no work.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace declaration retains nothing.
+ */
+export namespace CompilerTarget {
+  /**
+   * A supported compiler line: the major.minor of the TypeScript releases one
+   * shipped shim tree targets.
+   *
+   * @evidence contracts/common.md#principled-implementation Each member names a line whose shims this release ships and audits.
+   * @evidence contracts/common.md#clear-and-simple-design A closed union lets every switch over targets be checked for completeness.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Members are shipped lines, not installed versions.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states what a member names.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation A type performs no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A type executes nothing.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type coordinates no work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type retains nothing.
+   */
+  export type Line = "7.0" | "7.1";
+
+  /** The newest supported line, which a newer installed line falls back to. */
+  export const NEWEST: Line = "7.1";
+
+  /**
+   * The build tag a 7.1 build compiles with; 7.0 builds carry none, so a file
+   * marked `!ttsc_typescript_7_1` is the 7.0 side.
+   */
+  export const TYPESCRIPT_7_1_TAG = "ttsc_typescript_7_1";
+
+  /**
+   * The line a compiler version belongs to, and whether that version is newer
+   * than every supported line. A version without a readable major.minor maps to
+   * 7.0.
+   *
+   * @evidence contracts/common.md#principled-implementation Reads the leading major.minor of a semver-shaped version, so a prerelease such as 7.1.0-dev.20261019.1 maps to its own line; 7.0 and 7.1 map to themselves, and any later line is newer than the newest target.
+   * @evidence contracts/common.md#clear-and-simple-design One pure mapping serves both the manifest and the custom-binary version source.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreadable text maps to the shipped 7.0 target instead of being guessed.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the prerelease, newer-line and unreadable cases.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The mapping reads its argument only.
+   * @evidence contracts/performance.md#efficient-algorithms One anchored regular-expression match over the version text.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The pure mapping coordinates no shared work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The mapping retains nothing.
+   */
+  export function lineOf(version: string): { line: Line; newer: boolean } {
+    const match = /^\s*(?:Version\s+)?(\d+)\.(\d+)/.exec(version);
+    if (match === null) return { line: "7.0", newer: false };
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (major === 7 && minor === 0) return { line: "7.0", newer: false };
+    if (major === 7 && minor === 1) return { line: "7.1", newer: false };
+    if (major < 7) return { line: "7.0", newer: false };
+    return { line: NEWEST, newer: true };
+  }
+
+  /**
+   * The target for a project: the line of the TypeScript compiler it installs,
+   * or of `TTSC_TSGO_BINARY` when that names a custom compiler. A version newer
+   * than every target selects the newest and warns once per version on stderr.
+   *
+   * @evidence contracts/common.md#principled-implementation resolveTsgo locates the same compiler the project's build runs; its manifest version is used, and a custom binary is asked for --version since it has no manifest. An unresolvable compiler maps to the 7.0 default, leaving the build's own resolution to report it.
+   * @evidence contracts/common.md#clear-and-simple-design Version reading stays here and line mapping in lineOf; callers receive only the line.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The project's real compiler decides the target; no fixture name or path pattern does.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the two version sources and the warning.
+   * @evidence contracts/portability.md#os-neutral-implementation resolveTsgo and spawnNative own the native lookup and process launch; the version text is read without shell interpretation.
+   * @evidence contracts/performance.md#efficient-algorithms A manifest version costs resolveTsgo's lookup; only a custom binary adds one --version process.
+   * @evidence contracts/performance.md#reuse-equivalent-work Custom-binary versions are remembered per binary path for the process, since the binary at a path does not change its line mid-process; manifest versions are read afresh because projects differ.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The remembered map grows with distinct custom binary paths and the warned set with distinct newer versions, both for the process lifetime; the spawned process is synchronous and released on return.
+   */
+  export function resolve(projectRoot: string, env: NodeJS.ProcessEnv): Line {
+    const version = installedVersion(projectRoot, env);
+    const { line, newer } = lineOf(version);
+    if (newer && !warned.has(version)) {
+      warned.add(version);
+      process.stderr.write(
+        `ttsc: TypeScript ${version} is newer than every compiler target this ttsc supports; ` +
+          `using the TypeScript ${line} compiler target.\n`,
+      );
+    }
+    return line;
+  }
+
+  /**
+   * The environment a build of line runs Go with: env itself for 7.0, and for
+   * 7.1 env with the 7.1 build tag added to the GOFLAGS Go would use, merged
+   * into any -tags already set there.
+   *
+   * A GOFLAGS variable replaces the value `go env -w` stored rather than adding
+   * to it, so when env sets no GOFLAGS the stored value is asked of Go from cwd
+   * and the tag joins that.
+   *
+   * @evidence contracts/common.md#principled-implementation GOFLAGS reaches every go command a build runs, so go list, the package-artifact probe and go build select the same tagged files; an existing -tags list gains the tag instead of being replaced, and flags stored by go env -w survive because Go reports them before the variable is set.
+   * @evidence contracts/common.md#clear-and-simple-design One environment transform per target replaces threading tags through each command.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Other GOFLAGS entries are kept unchanged and in order, and the stored value comes from Go itself rather than a handwritten environment-file location.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the per-line result, the merge and why the stored value is read.
+   * @evidence contracts/portability.md#os-neutral-implementation Go locates and reads its own environment file; resolveGoCompiler, GoToolResolution and spawnGoTool own the native lookup and launch.
+   * @evidence contracts/performance.md#efficient-algorithms One pass over the GOFLAGS fields; only a 7.1 build whose env sets no GOFLAGS adds one go env process.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The stored value is read afresh because go env -w can change it between loads.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned environment is a caller-owned copy, and the go env process is synchronous and released on return.
+   */
+  export function buildEnv(
+    env: NodeJS.ProcessEnv,
+    line: Line,
+    cwd: string,
+  ): NodeJS.ProcessEnv {
+    if (line !== "7.1") return env;
+    const current =
+      SidecarEnvironment.read(env, "GOFLAGS") || storedGoFlags(env, cwd);
+    const fields = current.split(/\s+/).filter((field) => field !== "");
+    let tagged = false;
+    const next = fields.map((field) => {
+      const match = /^(-{1,2}tags=)(.*)$/.exec(field);
+      if (match === null) return field;
+      tagged = true;
+      const tags = match[2]!.split(",").filter((tag) => tag !== "");
+      if (!tags.includes(TYPESCRIPT_7_1_TAG)) tags.push(TYPESCRIPT_7_1_TAG);
+      return `${match[1]}${tags.join(",")}`;
+    });
+    if (!tagged) next.push(`-tags=${TYPESCRIPT_7_1_TAG}`);
+    const result = SidecarEnvironment.merge(env);
+    SidecarEnvironment.write(result, "GOFLAGS", next.join(" "));
+    return result;
+  }
+
+  /**
+   * The line a build environment compiles: 7.1 when its GOFLAGS carries the 7.1
+   * build tag, otherwise 7.0. A build reads its overlays through this, so the
+   * overlaid shim tree is always the one the tagged files were written for.
+   *
+   * @evidence contracts/common.md#principled-implementation The tag decides which target files Go compiles, so the same tag decides which shim tree they are compiled against; a workspace can never pair 7.1 files with 7.0 shims.
+   * @evidence contracts/common.md#clear-and-simple-design The environment a build already carries names its target, so no separate target parameter is threaded through package selection and builds.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the Go-defined -tags fields are read; other GOFLAGS text cannot select a target.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the tag rule and why builds read it.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation GOFLAGS is a Go-defined space-separated value; the reading touches no native resource.
+   * @evidence contracts/performance.md#efficient-algorithms One pass over the GOFLAGS fields.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The pure reading coordinates no shared work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The reading retains nothing.
+   */
+  export function ofEnv(env: NodeJS.ProcessEnv): Line {
+    const flags = SidecarEnvironment.read(env, "GOFLAGS") ?? "";
+    for (const field of flags.split(/\s+/)) {
+      const match = /^-{1,2}tags=(.*)$/.exec(field);
+      if (match !== null && match[1]!.split(",").includes(TYPESCRIPT_7_1_TAG))
+        return "7.1";
+    }
+    return "7.0";
+  }
+
+  /**
+   * GOFLAGS without the 7.1 build tag ttsc adds: the tag leaves every -tags
+   * list, an emptied list leaves the flags, and every other field stays in
+   * order.
+   *
+   * @evidence contracts/common.md#principled-implementation The target tag is ttsc's own selection, not the caller's Go environment; the environment digest of a source state omits it so a reader with the caller's environment reproduces the state, while the build key still separates targets through their overlay modules.
+   * @evidence contracts/common.md#clear-and-simple-design The inverse of buildEnv's merge lives beside it, so the two cannot disagree on the tag or the -tags syntax.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the exact ttsc tag is removed; every other tag and flag is kept.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states what is removed and what is kept.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation GOFLAGS is a Go-defined space-separated value; the transform touches no native resource.
+   * @evidence contracts/performance.md#efficient-algorithms One pass over the GOFLAGS fields.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The pure transform coordinates no shared work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The transform retains nothing.
+   */
+  export function withoutTag(flags: string): string {
+    return flags
+      .split(/\s+/)
+      .filter((field) => field !== "")
+      .flatMap((field) => {
+        const match = /^(-{1,2}tags=)(.*)$/.exec(field);
+        if (match === null) return [field];
+        const tags = match[2]!
+          .split(",")
+          .filter((tag) => tag !== "" && tag !== TYPESCRIPT_7_1_TAG);
+        return tags.length === 0 ? [] : [`${match[1]}${tags.join(",")}`];
+      })
+      .join(" ");
+  }
+
+  /** The GOFLAGS Go reports from cwd, or empty when Go cannot answer. */
+  function storedGoFlags(env: NodeJS.ProcessEnv, cwd: string): string {
+    const goBinary = GoToolResolution.resolveGoToolForBuild(
+      resolveGoCompiler(env).binary,
+      env,
+      cwd,
+    );
+    const result = spawnGoTool(goBinary, ["env", "GOFLAGS"], {
+      cwd,
+      encoding: "utf8",
+      env: GoSourceInputs.goBuildEnv(goBinary, undefined, env),
+      windowsHide: true,
+    });
+    return result.error === undefined && result.status === 0
+      ? result.stdout.trim()
+      : "";
+  }
+
+  const warned = new Set<string>();
+  const customVersions = new Map<string, string>();
+
+  function installedVersion(
+    projectRoot: string,
+    env: NodeJS.ProcessEnv,
+  ): string {
+    let tsgo: ReturnType<typeof resolveTsgo>;
+    try {
+      tsgo = resolveTsgo({ cwd: projectRoot, env });
+    } catch {
+      return "unknown";
+    }
+    if (tsgo.version !== "custom") return tsgo.version;
+    const known = customVersions.get(tsgo.binary);
+    if (known !== undefined) return known;
+    const result = spawnNative(tsgo.binary, ["--version"], {
+      cwd: projectRoot,
+      env,
+    });
+    const version =
+      result.error === undefined && result.status === 0
+        ? outputText(result.stdout).trim()
+        : "unknown";
+    customVersions.set(tsgo.binary, version);
+    return version;
+  }
+}

package/src/plugin/internal/source/NativeSourcePackages.ts

@@ -6,6 +6,7 @@ import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/Sideca
 import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
 import { SourceNativeRetirement } from "../../../internal/SourceNativeRetirement";
 import { createCanonicalTempDirectory } from "../../../internal/createCanonicalTempDirectory";
+import { CompilerTarget } from "./CompilerTarget";
 import { GoSourceInputs } from "./GoSourceInputs";
 import { GoToolResolution } from "./GoToolResolution";
 import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
@@ -211,7 +212,7 @@ export namespace NativeSourcePackages {
       );
       SourcePluginWorkspace.writeGoWork(
         scratch,
-        SourcePluginWorkspace.findTtscOverlayDirs(),
+        SourcePluginWorkspace.findTtscOverlayDirs(CompilerTarget.ofEnv(env)),
         goBinary,
         opts.pluginName,
         env,
@@ -228,7 +229,7 @@ export namespace NativeSourcePackages {
         identity !== undefined &&
         copiesKeyed &&
         observed.every((input) => input.Error === undefined) &&
-        JSON.stringify(overlayDigests(opts.identities)) ===
+        JSON.stringify(overlayDigests(env, opts.identities)) ===
           JSON.stringify(identity.overlays)
       )
         PluginLoadAnswers.write(
@@ -622,7 +623,9 @@ function selectionIdentity(
           : ["go.mod", "go.sum"].map((name) =>
               fileDigest(path.join(host, name)),
             ),
-      overlays: SourcePluginWorkspace.findTtscOverlayDirs().map(directory),
+      overlays: SourcePluginWorkspace.findTtscOverlayDirs(
+        CompilerTarget.ofEnv(env),
+      ).map(directory),
       entries: opts.packages.map((input) => [
         input.entry,
         input.name ?? null,
@@ -637,9 +640,12 @@ function selectionIdentity(
 
 /** The digest of every overlay module, in the generated workspace's order. */
 function overlayDigests(
+  env: NodeJS.ProcessEnv,
   identities: PluginContentIdentities.Store | undefined,
 ): string[] {
-  return SourcePluginWorkspace.findTtscOverlayDirs().map((directory) =>
+  return SourcePluginWorkspace.findTtscOverlayDirs(
+    CompilerTarget.ofEnv(env),
+  ).map((directory) =>
     PluginContentIdentities.sourceDirectory(identities, directory),
   );
 }

package/src/plugin/internal/source/SourcePluginAdmission.ts

@@ -77,7 +77,7 @@ export namespace SourcePluginAdmission {
    * Identify compiler/shim module names whose replacement ttsc owns. This is
    * module-name policy, not a lookup of a physical Go module.
    *
-   * @evidence contracts/common.md#principled-implementation Exact ttsc/compiler roots and the compiler shim namespace retain the existing managed-module discriminants.
+   * @evidence contracts/common.md#principled-implementation Exact ttsc and compiler roots of both targets and every shim namespace are the managed-module discriminants.
    * @evidence contracts/common.md#clear-and-simple-design Both replacement rejection and workspace filtering use this same predicate.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts Module-name policy does not fabricate filesystem module identity or compiled provenance.
    * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module-name classification from physical lookup.
@@ -90,7 +90,33 @@ export namespace SourcePluginAdmission {
     return (
       modulePath === "github.com/samchon/ttsc/packages/ttsc" ||
       modulePath === "github.com/microsoft/typescript-go" ||
-      modulePath.startsWith("github.com/microsoft/typescript-go/shim/")
+      modulePath === "github.com/microsoft/TypeScript/tsc" ||
+      isManagedShimModule(modulePath)
+    );
+  }
+
+  /** The module-path prefix of the TypeScript 7.1 target's bridges. */
+  export const BRIDGE_MODULE_PREFIX =
+    "github.com/microsoft/TypeScript/tsc/shim/";
+
+  /**
+   * Identify a ttsc-owned shim module of any compiler target: a 7.0 shim or a
+   * 7.1 facade, both `github.com/microsoft/typescript-go/shim/*`, or a 7.1
+   * bridge. This is module-name policy, not a lookup of a physical Go module.
+   *
+   * @evidence contracts/common.md#principled-implementation Both shim namespaces are ttsc-owned module names; a prefix test classifies each.
+   * @evidence contracts/common.md#clear-and-simple-design isManagedModule and workspace writing share this predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Module-name policy does not fabricate filesystem module identity.
+   * @evidence contracts/common.md#meaningful-documentation Native prose names the three shim kinds.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Go module identifiers are supplied strings, not native filesystem paths.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Two prefix comparisons own no population-processing strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current module text is classified without retained lookup results.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No native handle, module registry or task is acquired or retained.
+   */
+  export function isManagedShimModule(modulePath: string): boolean {
+    return (
+      modulePath.startsWith("github.com/microsoft/typescript-go/shim/") ||
+      modulePath.startsWith(BRIDGE_MODULE_PREFIX)
     );
   }
 

package/src/plugin/internal/source/SourcePluginWorkspace.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 
 import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
 import { runtimeExecutableIdentity } from "../../../internal/runtimeExecutableIdentity";
+import type { CompilerTarget } from "./CompilerTarget";
 import { GoEnvironmentReading } from "./GoEnvironmentReading";
 import { GoSourceInputs } from "./GoSourceInputs";
 import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
@@ -86,26 +87,44 @@ export namespace SourcePluginWorkspace {
   ): void {
     validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
     const sourceInfo = goModReader.read(scratchDir);
-    const effectiveUseDirs =
-      sourceInfo.modulePath === TTSC_GO_MODULE_PATH
-        ? useDirs.filter((dir) => {
-            OwnedSynchronousProcess.checkpoint();
-            const modulePath = goModReader.read(dir).modulePath;
-            return (
-              modulePath !== null &&
-              !SourcePluginAdmission.isManagedModule(modulePath)
-            );
-          })
-        : useDirs;
+    // A TypeScript 7.1 target overlays bridges and facades. Each facade shares
+    // its module path with a 7.0 shim that the ttsc module's own go.mod
+    // replaces, so the shims become workspace replacements, which override
+    // module replacements, rather than workspace modules.
+    const bridged = useDirs.some((dir) =>
+      (goModReader.read(dir).modulePath ?? "").startsWith(
+        SourcePluginAdmission.BRIDGE_MODULE_PREFIX,
+      ),
+    );
+    const shimReplaceLines: string[] = [];
+    const effectiveUseDirs = useDirs.filter((dir) => {
+      OwnedSynchronousProcess.checkpoint();
+      const modulePath = goModReader.read(dir).modulePath;
+      if (
+        bridged &&
+        modulePath !== null &&
+        SourcePluginAdmission.isManagedShimModule(modulePath)
+      ) {
+        shimReplaceLines.push(
+          `replace ${modulePath} => ${formatGoWorkPath(dir)}`,
+        );
+        return false;
+      }
+      return (
+        sourceInfo.modulePath !== TTSC_GO_MODULE_PATH ||
+        (modulePath !== null &&
+          !SourcePluginAdmission.isManagedModule(modulePath))
+      );
+    });
     const useLines = ["\t."];
     for (const dir of effectiveUseDirs) {
       OwnedSynchronousProcess.checkpoint();
       useLines.push(`\t${formatGoWorkPath(dir)}`);
     }
-    const replaceLines = sourceBuildWorkspaceReplacements(
-      effectiveUseDirs,
-      goModReader,
-    );
+    const replaceLines = [
+      ...sourceBuildWorkspaceReplacements(effectiveUseDirs, goModReader),
+      ...shimReplaceLines.sort(),
+    ];
     const replaceBlock =
       replaceLines.length === 0 ? "" : `\n\n${replaceLines.join("\n")}\n`;
     const goWork = `use (\n${useLines.join("\n")}\n)${replaceBlock}`;
@@ -683,9 +702,11 @@ export namespace SourcePluginWorkspace {
   }
 
   /**
-   * Discover the installed native compiler/shim module overlays.
+   * Discover the installed native compiler/shim module overlays of a compiler
+   * target: the ttsc module and, for 7.0, the shim tree, or for 7.1 its bridges
+   * and facades. Omitting line selects 7.0.
    *
-   * @evidence contracts/common.md#principled-implementation Existing ttsc and shim go.mod files enter overlay selection under shared directory pruning policy.
+   * @evidence contracts/common.md#principled-implementation Existing ttsc and target shim go.mod files enter overlay selection under shared directory pruning policy; each line's tree is a separate directory, so one target's modules never enter another's workspace.
    * @evidence contracts/common.md#clear-and-simple-design One recursive walker gathers modules and one sort stabilizes ordering.
    * @evidence contracts/common.md#prohibited-implementation-shortcuts No guessed list of shim modules replaces current filesystem discovery.
    * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
@@ -694,13 +715,18 @@ export namespace SourcePluginWorkspace {
    * @evidence contracts/performance.md#reuse-equivalent-work Each call observes installed layout afresh; contextual module readers separately reuse manifest content observations.
    * @evidence contracts/performance.md#bound-retention-and-release-resources Directory arrays/path strings live only for this call/result; synchronous fs calls retain no open handle.
    */
-  export function findTtscOverlayDirs(): readonly string[] {
+  export function findTtscOverlayDirs(
+    line: CompilerTarget.Line = "7.0",
+  ): readonly string[] {
     const ttscRoot = path.resolve(__dirname, "..", "..", "..", "..");
     const dirs: string[] = [];
     if (fs.existsSync(path.join(ttscRoot, "go.mod"))) {
       dirs.push(ttscRoot);
     }
-    const shimRoot = path.join(ttscRoot, "shim");
+    const shimRoot =
+      line === "7.0"
+        ? path.join(ttscRoot, "shim")
+        : path.join(ttscRoot, "targets", line);
     if (fs.existsSync(shimRoot)) {
       walkForGoMod(shimRoot, dirs);
     }

package/src/plugin/internal/source/buildSourcePlugin.ts

@@ -8,6 +8,7 @@ import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProce
 import { SourceNativeRetirement } from "../../../internal/SourceNativeRetirement";
 import { createCanonicalTempDirectory } from "../../../internal/createCanonicalTempDirectory";
 import { runHoldingLock } from "../../../internal/runHoldingLock";
+import { CompilerTarget } from "./CompilerTarget";
 import { GoSourceInputs } from "./GoSourceInputs";
 import { GoToolResolution } from "./GoToolResolution";
 import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
@@ -208,7 +209,8 @@ function buildSourcePluginAttempt(
   OwnedSynchronousProcess.checkpoint();
   const { dir, entry, source } = resolveSourceBuildTarget(opts);
   const overlayDirs = [
-    ...(opts.overlayDirs ?? SourcePluginWorkspace.findTtscOverlayDirs()),
+    ...(opts.overlayDirs ??
+      SourcePluginWorkspace.findTtscOverlayDirs(CompilerTarget.ofEnv(env))),
   ].sort();
   const contributors = opts.contributors ?? [];
   const compiler = resolveGoCompiler(env);