ttsc 0.30.3 → 0.31.0

package/src/compiler/internal/project/resolveTsconfigExtends.ts

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { readJsonFile } from "./readJsonFile";
+import { tsconfigExtendsFileCandidates } from "./tsconfigExtendsFileCandidates";
+
+/**
+ * Resolve one `extends` specifier using ttsc's shared file-candidate rule and
+ * Node package resolution from the declaring config.
+ *
+ * - A specifier naming a file (host-absolute, `./`, or `../`, after `\` is folded
+ *   into `/`) resolves to the first candidate that is a regular file
+ *   (`tsconfigExtendsFileCandidates`), under the spelling it was reached by.
+ * - Any other specifier is resolved like a module from the declaring config: a
+ *   bare package root selects its preset through `package.json#tsconfig`, then
+ *   Node's resolver is asked for the specifier and for the specifier with
+ *   `.json` appended. Selected module paths use realpath when it succeeds and
+ *   retain the selected spelling when it fails. Node's resolver does not
+ *   reproduce every TypeScript-Go module condition or expose its full search
+ *   topology; observers therefore cannot certify module-chain freshness.
+ *
+ * The one rule both of the workspace's config readers use: ttsc's project
+ * reader canonicalizes the answer before it reads the chain further, and
+ * `@ttsc/unplugin` keeps the spelling, since TypeScript anchors a relatively
+ * extended config at the path it was reached by.
+ *
+ * @param tsconfig The declaring config, as the reader named it.
+ * @param specifier The `extends` value as written.
+ * @param onInput Optional observer of lexical file candidates and selected
+ *   module/manifest paths. Module search topology is not completely observed.
+ * @returns The extended config's path.
+ * @throws When the specifier names nothing, or a preset's `package.json` does
+ *   not parse, naming what failed in ttsc's voice.
+ * @evidence contracts/common.md#principled-implementation File inheritance uses exact/.json candidates within the shared host-native classification; bare preset manifests and Node's module resolver supply package selection without claiming universal compiler module-condition parity or complete observed search topology.
+ * @evidence contracts/common.md#clear-and-simple-design One shared config resolver owns file-versus-module selection, with a small manifest-preset helper and an optional input observer rather than a parallel package resolver.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The .json fallback and manifest tsconfig field address supported compiler differences; selected malformed manifests are errors rather than swallowed faults or fixture-specific paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc distinguishes lexical file spelling, physical module identity, preset selection and observation limits; param and acknowledgment spacing follows the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Config separators are folded before native file resolution, package presets use createRequire from their declaring config, and filesystem identities use native realpath instead of POSIX path parsing.
+ * @evidence contracts/performance.md#efficient-algorithms File selection performs at most two native stats plus path text construction; package branches can make manifest and entrypoint resolution attempts, parse the selected manifest bytes, test config candidates and attempt realpath. Node's ancestor/package search and native operations have delegated costs, not fixed costs implied by a bounded local branch count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This resolver owns no result cache; Node's internal module-resolution cache is outside its control and therefore cannot justify an owning freshness proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources All paths, require objects and parsed manifest data belong to this invocation; no cache registry or process handle is acquired here.
+ */
+export function resolveTsconfigExtends(
+  tsconfig: string,
+  specifier: string,
+  onInput?: (file: string) => void,
+): string {
+  const files = tsconfigExtendsFileCandidates(tsconfig, specifier);
+  if (files !== undefined) {
+    for (const candidate of files) {
+      onInput?.(candidate);
+      if (isFile(candidate)) return candidate;
+    }
+    throw new Error(`ttsc: extended tsconfig not found: ${files[0]}`);
+  }
+  const normalized = specifier.replaceAll("\\", "/");
+  const resolver = createRequire(tsconfig);
+  // A bare package root selects its preset through `package.json#tsconfig`,
+  // matching TypeScript's config resolution. Presets shipped this way often
+  // have no JavaScript/JSON entrypoint at all, so Node's entrypoint resolver
+  // and the `<specifier>.json` fallback below both miss them.
+  const viaManifest = resolvePackageManifestTsconfig(
+    resolver,
+    normalized,
+    onInput,
+  );
+  if (viaManifest !== undefined) {
+    for (const candidate of viaManifest.endsWith(".json")
+      ? [viaManifest]
+      : [viaManifest, `${viaManifest}.json`]) {
+      onInput?.(candidate);
+      if (isFile(candidate)) return resolveRealPath(candidate);
+    }
+    throw new Error(`ttsc: extended tsconfig not found: ${viaManifest}`);
+  }
+  try {
+    const selected = resolver.resolve(normalized);
+    onInput?.(selected);
+    return resolveRealPath(selected);
+  } catch {
+    const selected = resolver.resolve(`${normalized}.json`);
+    onInput?.(selected);
+    return resolveRealPath(selected);
+  }
+}
+
+/**
+ * When `specifier` names a bare package root, resolve the config file its
+ * `package.json#tsconfig` field selects (anchored at the package directory).
+ * Returns `undefined` when the specifier is a subpath, the manifest cannot be
+ * resolved at all, or it declares no `tsconfig` field, so the caller falls back
+ * to Node entrypoint resolution. A manifest that resolves but does not parse
+ * throws, naming the file.
+ */
+function resolvePackageManifestTsconfig(
+  resolver: NodeRequire,
+  specifier: string,
+  onInput?: (file: string) => void,
+): string | undefined {
+  if (!isBarePackageRoot(specifier)) {
+    return undefined;
+  }
+  let manifestPath: string;
+  try {
+    manifestPath = resolver.resolve(`${specifier}/package.json`);
+  } catch (error) {
+    // Node parses a package's manifest while resolving into it, so a malformed
+    // preset manifest fails here rather than at the read below. Swallowing it
+    // would turn a broken manifest into a confusing downstream
+    // "Cannot find module 'example-preset.json'" from the `extends` fallback,
+    // which names a file that was never the problem. Node's own message names
+    // the real one, so report it in ttsc's voice instead of continuing.
+    if (
+      (error as NodeJS.ErrnoException | undefined)?.code ===
+      "ERR_INVALID_PACKAGE_CONFIG"
+    ) {
+      throw new Error(
+        `ttsc: failed to parse the package manifest of ${JSON.stringify(specifier)}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    return undefined;
+  }
+  // A manifest that exists but does not parse is a real configuration error:
+  // falling back to Node entrypoint resolution would tell the user nothing
+  // about the file that actually broke. A manifest that parses to something
+  // other than an object carries no `tsconfig` field to read, so it falls back
+  // rather than throwing on a property access.
+  onInput?.(manifestPath);
+  const manifest = readJsonFile(manifestPath);
+  const field =
+    typeof manifest === "object" && manifest !== null
+      ? (manifest as { tsconfig?: unknown }).tsconfig
+      : undefined;
+  if (typeof field !== "string" || field.length === 0) {
+    return undefined;
+  }
+  return path.resolve(path.dirname(manifestPath), field.replaceAll("\\", "/"));
+}
+
+/**
+ * Return true when `specifier` is a bare package root (no subpath): a plain
+ * package name (`preset`) or a scoped name (`@scope/preset`). Subpaths such as
+ * `@scope/preset/base.json` resolve directly and keep their current meaning.
+ */
+function isBarePackageRoot(specifier: string): boolean {
+  if (specifier.startsWith("@")) {
+    return specifier.split("/").length === 2;
+  }
+  return !specifier.includes("/");
+}
+
+/** Whether a path is a regular file; any failure to stat counts as not. */
+function isFile(location: string): boolean {
+  try {
+    return fs.statSync(location).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve symlinks on `location`, returning the original path when
+ * `realpathSync` fails.
+ */
+function resolveRealPath(location: string): string {
+  try {
+    return fs.realpathSync(location);
+  } catch {
+    return location;
+  }
+}

package/src/compiler/internal/project/selectReferencedProject.ts

@@ -0,0 +1,54 @@
+/**
+ * Select the first observed owning config in declaration-order depth-first
+ * traversal, retaining discovery when no positive membership was observed.
+ *
+ * The caller supplies current direct references, observed identity keys and
+ * membership observations. Native reference resolution, compiler expansion and
+ * retry policy remain with those owners. A fresh visited set belongs to each
+ * lookup; matching keys terminate cycles without a cross-request cache.
+ *
+ * @evidence contracts/common.md#principled-implementation Discovery membership takes precedence; each unseen reference is checked before its children, so declaration-order DFS preserves the first observed owner and discovered fallback.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns ordering and lookup-local visited keys; supplied operations retain native reference and membership responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection consumes actual observations rather than guessed include patterns, fixture layouts or persistent pathname-only answers.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish positive membership, fallback, cycles and delegated native observations.
+ * @evidence contracts/portability.md#os-neutral-implementation Config spellings pass unchanged through actual reference and identity owners; observed keys, rather than platform-name case assumptions, decide repeated states.
+ * @evidence contracts/performance.md#efficient-algorithms Each unseen observed identity receives at most one membership request and reference visit; edge iteration, string-key set work and delegated identity, config and compiler costs remain part of the lookup. Recursive stack depth follows the explored chain and is not bounded here.
+ * @evidence contracts/performance.md#reuse-equivalent-work Initial references are reused only for discovery, and the fresh visited set avoids repeated observed identities within this lookup. No state or failed observation is reused across calls; key quality remains the identity owner's premise.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The visited keys and recursion frames live only for this synchronous lookup. Returned spelling transfers to the caller; native handles, subprocess capture and their lifetime remain delegated, with no deadline introduced here.
+ */
+export function selectReferencedProject(
+  discovered: string,
+  discoveredReferences: readonly string[],
+  observations: {
+    /** Current best-effort native identity key for a config spelling. */
+    identity(config: string): string;
+
+    /** Positive observation that expanded roots contain this lookup's target. */
+    contains(config: string): boolean;
+
+    /** Current direct reference configs in declaration order. */
+    readReferences(config: string): readonly string[];
+  },
+): string {
+  if (discoveredReferences.length === 0) return discovered;
+  if (observations.contains(discovered)) return discovered;
+  const seen = new Set<string>([observations.identity(discovered)]);
+
+  /** DFS checks each unseen reference before descending into its children. */
+  function search(config: string): string | null {
+    const references =
+      config === discovered
+        ? discoveredReferences
+        : observations.readReferences(config);
+    for (const reference of references) {
+      const key = observations.identity(reference);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      if (observations.contains(reference)) return reference;
+      const nested = search(reference);
+      if (nested !== null) return nested;
+    }
+    return null;
+  }
+  return search(discovered) ?? discovered;
+}

package/src/compiler/internal/project/tsconfigExtendsFileCandidates.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+
+/**
+ * The file candidates ttsc tries for an `extends` specifier recognized as
+ * host-absolute or dot-relative, or `undefined` for module selection.
+ *
+ * TypeScript-Go's `getExtendsConfigPath` first folds every `\` of the specifier
+ * into `/`. A rooted specifier, or one starting with `./` or `../`, then names
+ * a file below the declaring config's directory, kept under the spelling it was
+ * reached by: the file itself, and, unless it already ends in `.json`, the file
+ * with `.json` appended. A directory is never expanded to its `tsconfig.json`.
+ * Every other specifier is resolved like a module (`resolveTsconfigExtends`). A
+ * bare `.` or `..` is taken as a file path too, as ttsc's readers treat it.
+ * Classification and normalization here use the host's native path API;
+ * TypeScript-Go's host-independent DOS-root recognition is not reproduced for
+ * foreign drive spellings or a bare drive such as `C:`.
+ *
+ * A reader that records what an `extends` it could not resolve would take to
+ * appear, as `@ttsc/unplugin` does to observe a missing base config, asks this
+ * rather than repeating the rule.
+ *
+ * @param tsconfig The declaring config, as the reader named it.
+ * @param specifier The `extends` value as written.
+ * @returns Ordered native candidates, or undefined when this reader delegates
+ *   the normalized specifier to module resolution.
+ * @evidence contracts/common.md#principled-implementation Backslash normalization followed by host-absolute/dot-relative classification uses the compiler's exact-then-json candidate order for those paths; bare dot spellings retain the existing reader extension, and native root classification is not universal compiler DOS-root parity.
+ * @evidence contracts/common.md#clear-and-simple-design This helper constructs candidates without reading them or resolving packages, so both readers share the spelling rule while retaining their own observation and selection responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The dot-relative prefixes and json suffix express config grammar rather than named consumers or fixtures; no directory-to-tsconfig guess is inserted.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain candidate order, lexical anchoring, module classification and the deliberate bare-dot extension; params state whose spelling is retained.
+ * @evidence contracts/portability.md#os-neutral-implementation Compiler-style slash normalization precedes host-native isAbsolute/dirname/resolve operations; no realpath or case folding discards the lexical anchor needed for relative extends.
+ * @evidence contracts/performance.md#efficient-algorithms Normalization scans the specifier and native dirname/resolve process path text; at most two output strings are constructed, but their bytes are not bounded by the array length. No filesystem candidates are read here.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns caller-owned path strings and an array, with no independent handle, task or historical retention.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This candidate adapter owns no coordinated config lifecycle or cache; relative declaring paths also depend on the native current-directory resolution context.
+ */
+export function tsconfigExtendsFileCandidates(
+  tsconfig: string,
+  specifier: string,
+): string[] | undefined {
+  const normalized = specifier.replaceAll("\\", "/");
+  if (
+    !path.isAbsolute(normalized) &&
+    normalized !== "." &&
+    normalized !== ".." &&
+    !normalized.startsWith("./") &&
+    !normalized.startsWith("../")
+  ) {
+    return undefined;
+  }
+  const location = path.resolve(path.dirname(tsconfig), normalized);
+  return location.endsWith(".json")
+    ? [location]
+    : [location, `${location}.json`];
+}

package/src/compiler/internal/readEffectiveCompilerOptions.ts

@@ -0,0 +1,126 @@
+import { COMPILER_OPTIONS } from "../../flags/COMPILER_OPTIONS";
+import { normalizeCompilerEnumValue } from "../../flags/normalizeCompilerEnumValue";
+import { readCompilerOptionValues } from "../../flags/readCompilerOptionValues";
+import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
+import { CompilerArgumentsInspection } from "./CompilerArgumentsInspection";
+import { outputText } from "./outputText";
+import { resolveTsgo } from "./resolveTsgo";
+import { spawnNative } from "./spawnNative";
+
+/**
+ * A reader of the compiler options a build will actually use: the project's
+ * config with the flags forwarded on the command line applied over it, in the
+ * order the compiler applies them.
+ *
+ * Several decisions ttsc makes about a build depend on an option the user can
+ * override from the command line: whether the runtime build lowers `target:
+ * ESNext` or a preserved `jsx`, and which `rootDir` the compiler mirrors
+ * outputs against. Reading the config alone answers for a build that is not the
+ * one that runs.
+ *
+ * A forwarded `@file` response file is expanded by the compiler itself through
+ * `--showConfig`, which owns its quoting, nesting, and ordering; replaying only
+ * the visible flags would miss the options inside it. Path values are returned
+ * as written: a config path is already absolute, a forwarded one is relative to
+ * the build's working directory, and a response-file one to the config's
+ * directory. The optional compilerArgsCwd preserves that original base when
+ * project selection redirects to another configuration. The supplied project
+ * remains the authority for this query, including reference-child queries.
+ *
+ * A separate observed safety tokenizer checks response frames before reporting
+ * flags are appended; the native compiler still owns expansion and value
+ * validation. Inspection uses the caller-provided child environment when
+ * supplied.
+ *
+ * Native shown properties remain authoritative, including paths and enums.
+ * Reporting booleans omitted from showConfig retain their observed ordered
+ * response assignments or configured boolean; an explicit null is still
+ * present. Other omissions remain undefined rather than reviving a configured
+ * value.
+ *
+ * Visible arguments share one native-frame projection. Enum discriminants
+ * follow their origin: CLI values are trimmed before lookup, while config
+ * values retain whitespace. A present reset wins over the configured value.
+ *
+ * @returns The reader, or `null` when safe response inspection is unavailable
+ *   or the compiler rejects the arguments. The caller forwards the original
+ *   request untouched and retains the compiler diagnostic. Binary resolution,
+ *   capture/read and malformed JSON failures can still throw; null is not a
+ *   universal failure conversion. Safety observation does not pin response-file
+ *   state across the later native inspection or actual build.
+ * @evidence contracts/common.md#principled-implementation Actual response-file frames are validated by native showConfig, whose present properties remain authoritative; omitted booleans use observed shared-frame assignments before configured booleans without reviving present null resets; one native-frame projection applies visible assignments in order over resolved config values, including bare booleans and explicit resets, while config enums are lowercased without trimming or arbitrary schema validation.
+ * @evidence contracts/common.md#clear-and-simple-design One returned reader exposes effective values to rootDir, runtime-profile and display consumers. Shared observed tokenization owns safe inspection admission, while native showConfig remains authoritative for response expansion and option values.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable safety inspection or rejected response arguments yield null instead of fabricated effective values; shared generated occurrence metadata determines option arity and boolean assignment, while the separate conservative response tokenizer does not replace native validation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain precedence, response-file ownership, path bases and the null outcome before acknowledgment tags following documentation guidance.
+ * @evidence contracts/performance.md#efficient-algorithms Visible arguments are projected once; response mode additionally observes/decodes/hashes expanded response bytes and reprojects them before one showConfig child. Complete capture/JSON parsing, delegated binary selection and native launch costs remain part of this operation. Each query performs option-name/alias normalization and lookups; config enum normalization adds value-text costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work One invocation shares the argument projection or compiler-expanded result across option queries; a new build invocation creates a reader because config and response-file state may change.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned closure retains the compiler-options reference, assignment Map and optional shown record until its caller discards it; they are not a deep snapshot of mutable configuration. The invocation owns no historical reader cache. Response inspection and spawnNative own synchronous observation/capture cleanup attempts; child duration and expanded/captured bytes have no ceiling supplied here.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Executable and argument arrays are passed through the supported native runner; path values preserve compiler-selected bases instead of shell interpolation or an OS-specific rewrite.
+ */
+export function readEffectiveCompilerOptions(
+  project: ITtscParsedProjectConfig,
+  passthrough: readonly string[] = [],
+  binary?: string,
+  env?: NodeJS.ProcessEnv,
+  compilerArgsCwd: string = project.root,
+): ((name: string, aliases?: readonly string[]) => unknown) | null {
+  const projected = readCompilerOptionValues(passthrough);
+  let assignments = projected.values;
+  let shown: Record<string, unknown> | undefined;
+  if (projected.responseFiles.length !== 0) {
+    let observations: ReadonlyMap<string, string>;
+    try {
+      const inspected = CompilerArgumentsInspection.inspect(
+        ["-p", project.path, ...passthrough],
+        compilerArgsCwd,
+      );
+      observations = inspected.observations;
+      assignments = readCompilerOptionValues(inspected.args).values;
+      for (const [file, observation] of inspected.observations)
+        if (CompilerArgumentsInspection.observeInputFile(file) !== observation)
+          return null;
+    } catch {
+      return null;
+    }
+    const tsgo = resolveTsgo({ cwd: project.root, binary });
+    const result = spawnNative(
+      tsgo.binary,
+      ["-p", project.path, ...passthrough, "-p", project.path, "--showConfig"],
+      { cwd: compilerArgsCwd, env, encoding: "utf8" },
+    );
+    if (result.status !== 0) return null;
+    for (const [file, observation] of observations)
+      if (CompilerArgumentsInspection.observeInputFile(file) !== observation)
+        return null;
+    shown = JSON.parse(outputText(result.stdout)).compilerOptions as Record<
+      string,
+      unknown
+    >;
+  }
+  const compilerOptions = project.compilerOptions as Record<string, unknown>;
+  return (name, aliases = []) => {
+    const spec =
+      COMPILER_OPTIONS.get(name.toLowerCase()) ??
+      aliases
+        .map((alias) => COMPILER_OPTIONS.get(alias.toLowerCase()))
+        .find((candidate) => candidate !== undefined);
+    const canonical = spec?.name ?? name;
+    if (shown !== undefined) {
+      if (Object.prototype.hasOwnProperty.call(shown, canonical))
+        return shown[canonical];
+      // showConfig omits reporting booleans even when explicitly enabled.
+      // Paths and enums stay native-owned; omission must not revive a reset.
+      if (spec?.kind !== "boolean") return undefined;
+      if (assignments.has(canonical)) return assignments.get(canonical);
+      const configured = compilerOptions[canonical];
+      return typeof configured === "boolean" ? configured : undefined;
+    }
+    if (assignments.has(canonical)) return assignments.get(canonical);
+    const configured = compilerOptions[canonical];
+    return spec?.kind === "enum" && typeof configured === "string"
+      ? normalizeCompilerEnumValue(configured, "json")
+      : configured;
+  };
+}

package/src/compiler/internal/resolveBinary.ts

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
+
 /**
  * Resolve the ttsc helper binary path, or null when unavailable.
  *
@@ -8,14 +10,31 @@ import path from "node:path";
  *
  * 1. `TTSC_BINARY` env var — must be an absolute path when set.
  * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttsc[.exe]`.
- * 3. A `ttsc-native[.exe]` sibling of this package's root (dev/CI layout).
+ * 3. `native/ttsc-native[.exe]` inside this package (local Go build layout).
+ *
+ * A relative TTSC_BINARY is ignored; an absolute override is returned without a
+ * filesystem probe so the spawn operation owns its executable error.
+ * Platform-package lookup failures fall through to the local candidate. Local
+ * source/lib realpath errors can propagate instead of returning null, and a
+ * selected existing path is not an executable or ABI compatibility check.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit absolute authority precedes Node's platform-package resolution and then the package-local Go build output, matching the helper binary ownership exported through ttsc/binary.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver owns precedence for compiler and external helper consumers; the local-path helper separates source/lib layout from installed platform-package lookup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Platform package names and executable suffixes follow the published package contract; the resolver uses supported require.resolve without replacing foreign resolution methods.
+ * @evidence contracts/common.md#meaningful-documentation Ordered resolution and override behavior are documented separately; the corrected development path matches go:build, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform and architecture select the native package and executable suffix; native path APIs establish the development path, and override lookup follows Windows environment-name identity even in a caller's ordinary object.
+ * @evidence contracts/performance.md#efficient-algorithms Precedence has a fixed branch count, but Windows environment-name lookup scans key bytes, native path normalization processes text, Node package lookup has delegated search costs, and local fallback realpaths the source/lib root before checking candidate existence. No compiler executes merely to select this path.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Environment overrides and development binaries may change between calls; the resolver owns no invalidation protocol beyond Node's own module resolver and introduces no stale path cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resolution owns no persistent map, descriptor or task and returns only the selected path spelling.
  */
 export function resolveBinary(
   opts: { env?: NodeJS.ProcessEnv } = {},
 ): string | null {
   const env = opts.env ?? process.env;
-  if (env.TTSC_BINARY && path.isAbsolute(env.TTSC_BINARY)) {
-    return env.TTSC_BINARY;
+  const explicit = SidecarEnvironment.read(env, "TTSC_BINARY");
+  if (explicit && path.isAbsolute(explicit)) {
+    return explicit;
   }
 
   try {
@@ -32,10 +51,7 @@ export function resolveBinary(
   return null;
 }
 
-/**
- * Return the path to the dev-layout `ttsc-native[.exe]` binary adjacent to the
- * package root, or null when the file does not exist.
- */
+/** Return the package-local Go build output, or null when it does not exist. */
 function defaultLocalBinaryPath(): string | null {
   const root = packageRootDir();
   const candidate = path.resolve(
@@ -48,8 +64,8 @@ function defaultLocalBinaryPath(): string | null {
 }
 
 /**
- * Return the real, absolute path of the `packages/ttsc` package root by walking
- * two levels up from `__dirname` (which lives in `src/compiler/internal`).
+ * Return the physical src or lib directory above this compiler module. The
+ * local build output is in the sibling native directory of that tree.
  */
 function packageRootDir(): string {
   const moduleDir = path.resolve(__dirname, "..", "..");

package/src/compiler/internal/resolveTsgo.ts

@@ -2,37 +2,57 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
+
 /**
  * Resolve the consumer project's native TypeScript (`tsc`) binary and metadata.
  *
  * Resolution order:
  *
- * 1. `opts.binary` or `TTSC_TSGO_BINARY` env var — must be an existing absolute
- *    path; returns `{ binary, packageJson: "", packageRoot, version: "custom"
- *    }`.
+ * 1. Select `opts.binary`, or consult `TTSC_TSGO_BINARY` only when it is absent. A
+ *    nonempty override must be an existing absolute path; returns `{ binary,
+ *    packageJson: "", packageRoot, version: "custom" }`.
  * 2. `typescript` resolved from the project `cwd`.
  * 3. `typescript` resolved from `opts.resolveFrom` (for test harnesses and
  *    embedders that anchor to a different directory).
  *
- * Throws a descriptive error when the package or platform binary is missing so
- * callers never have to reason about undefined binary paths.
+ * Throws a descriptive error when the package or platform path is missing.
+ * Manifest read/parse failures can propagate directly. Existence does not
+ * certify a regular executable, native ABI or compiler version compatibility;
+ * this operation selects paths and metadata without executing them. Platform
+ * package resolution is anchored at the chosen TypeScript manifest and can
+ * follow Node's ancestor search, rather than proving both packages occupy one
+ * physical installation or declare matching versions.
+ *
+ * @evidence contracts/common.md#principled-implementation Selected nonempty binary authority precedes project-relative TypeScript lookup; the chosen manifest anchors Node resolution of the platform package. Returned metadata describes the selected TypeScript manifest, without certifying native executable compatibility or matching platform-package versions.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution returns one existing selected path with provenance metadata; package lookup and JSON reading are private helpers rather than independent policy copies in launcher consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package names and lib/tsc suffixes follow the native TypeScript distribution contract. Missing dependencies remain descriptive errors rather than invented compiler paths or fixture-specific substitutes.
+ * @evidence contracts/common.md#meaningful-documentation Ordered precedence, custom metadata and failures are documented separately, and the fallback anchor member explains its filename semantics following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs validate absolute overrides and select the Windows executable suffix; createRequire anchors resolution to actual package files without shell quoting or OS-derived case policy.
+ * @evidence contracts/performance.md#efficient-algorithms A precedence sequence makes at most two TypeScript resolution attempts, one platform resolution and one manifest parse of M bytes. Node ancestor/package lookup, native existence checks and path text work have delegated costs; Windows environment override selection scans environment keys through SidecarEnvironment. Returned metadata does not retain the full parsed manifest.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Overrides and consumer installations are mutable filesystem authority; this resolver owns no dependency invalidation source that could justify retaining a custom result across calls.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous package reads retain no handles or tasks; returned path and version strings transfer to the caller without a historical metadata table.
  */
 export function resolveTsgo(
   opts: {
     /** Explicit path to a native `tsc` binary; bypasses package resolution. */
     binary?: string;
+
     /** Directory from which to discover `typescript`. */
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+
     /**
-     * Fallback resolution anchor used when the package is not found at `cwd`.
-     * Useful in test harnesses that install the package into a different tree.
+     * Absolute filename used to anchor fallback resolution when the package is
+     * absent at cwd. Pass a package.json or module filename, not a directory.
      */
     resolveFrom?: string;
   } = {},
 ) {
   const env = opts.env ?? process.env;
-  const explicit = opts.binary ?? env.TTSC_TSGO_BINARY;
+  const explicit =
+    opts.binary ?? SidecarEnvironment.read(env, "TTSC_TSGO_BINARY");
   if (explicit) {
     if (!path.isAbsolute(explicit) || !fs.existsSync(explicit)) {
       throw new Error(
@@ -107,9 +127,9 @@ export function resolveTsgo(
 }
 
 /**
- * Attempt to resolve the `package.json` of `typescript` starting from `from` (a
- * package.json path or directory). Returns `undefined` when the package is not
- * resolvable from that location.
+ * Resolve TypeScript relative to an absolute filename accepted by
+ * createRequire. Returns undefined when the anchor or package cannot be
+ * resolved.
  */
 function resolveTypeScriptPackageJson(from: string): string | undefined {
   try {