ttsc 0.30.3 → 0.31.0

package/src/compiler/internal/captureProcessOutput.ts

@@ -2,81 +2,83 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
-
-export interface CapturedProcessOutput {
-  /** Close the descriptors and remove the backing files. */
-  dispose(): void;
-  /** Read one stream's bytes, decoded unless `"buffer"` is asked for. */
-  read(
-    stream: "stdout" | "stderr",
-    encoding: BufferEncoding | "buffer" | undefined,
-  ): string | Buffer;
-  stderrFd: number;
-  stdoutFd: number;
-}
+import type { CapturedProcessOutput } from "./CapturedProcessOutput";
 
 /**
- * A pair of temporary files standing in for a child process's pipes.
+ * Acquire two private files and descriptors for a child's output.
+ *
+ * File descriptors avoid spawnSync's piped maxBuffer ceiling. Reading after
+ * exit still allocates complete output and is subject to filesystem, Buffer and
+ * string limits; file capture does not make output unbounded.
+ *
+ * The directory is per-call, so ordinary concurrent captures use separate
+ * destinations. This is not held-directory protection against namespace
+ * mutation. Descriptor acquisition failures attempt rollback; cleanup failures
+ * are suppressed, and the temp creator can leave an unclaimed postflight
+ * allocation. The caller owns the returned capture and must dispose it after
+ * reading; read failures propagate, while disposal is idempotent and cleanup is
+ * best effort.
+ *
+ * @evidence contracts/common.md#principled-implementation Precreated files receive exact child stream bytes through inherited descriptors; decoding happens on read, and I/O errors cannot masquerade as empty successful output.
+ * @evidence contracts/common.md#clear-and-simple-design One capture owns two descriptors and their private directory. Acquisition rollback and disposal share cleanup helpers, leaving consumers responsible for a finally boundary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported Node filesystem and descriptor APIs capture diagnostics without foreign mutation, expected-output substitution or an arbitrary output ceiling.
+ * @evidence contracts/common.md#meaningful-documentation Separate purpose, limits and ownership paragraphs follow the documentation skill and explain actual failure effects rather than claiming unlimited output.
+ * @evidence contracts/portability.md#os-neutral-implementation Canonical temporary-directory ownership and path.join represent native paths; Node manages native descriptors. Removal remains best effort because inherited Windows handles may keep files live.
+ * @evidence contracts/performance.md#efficient-algorithms Two streams require a fixed number of filesystem calls, including delegated canonical-parent/child observations and native creation/open work. Parent/path text and native lookup are not constant-cost; reading B bytes and optional decoding allocate complete raw/output text in O(B) storage. No output-byte quota is imposed by this capture owner.
  *
- * `spawnSync` holds a _piped_ stream in this process's memory and refuses to
- * keep more than `maxBuffer` bytes, so any piped capture has to name a ceiling
- * — and a ceiling is a number nobody chose for this machine, deciding on the
- * user's behalf that a large but legitimate build said too much. Handing the
- * child a file descriptor instead means the bytes never pass through this heap
- * on their way out of the child: how much a process may write is the
- * filesystem's business, and that is the same answer on every machine. Reading
- * the result back still materializes a string, so V8's own maximum string
- * length remains the outer bound — but that is a property of the runtime rather
- * than a budget chosen here, and it is identical everywhere this runs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each child requires independent effectful output destinations; sharing prior captures would mix bytes and ownership rather than reuse equivalent work.
  *
- * The directory is per-call, so two concurrent spawns cannot read each other's
- * bytes.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted directory and two descriptors transfer to the capture until disposal. Acquisition rollback/disposal attempt close/removal; errors are suppressed, so closure and file reclamation can remain unconfirmed. Disposal marks itself consumed before cleanup and does not retry; caller-reachable capture closures retain path/state references until discarded. Output bytes are uncapped here.
  */
 export function captureProcessOutput(): CapturedProcessOutput {
   const directory = createCanonicalTempDirectory("ttsc-spawn-");
   const stdoutPath = path.join(directory, "stdout");
   const stderrPath = path.join(directory, "stderr");
-  const stdoutFd = fs.openSync(stdoutPath, "w+");
+  let stdoutFd: number;
+  try {
+    stdoutFd = fs.openSync(stdoutPath, "w+");
+  } catch (error) {
+    removeQuietly(directory);
+    throw error;
+  }
   let stderrFd: number;
   try {
     stderrFd = fs.openSync(stderrPath, "w+");
   } catch (error) {
     // The first descriptor and the directory are already live. Nothing else
-    // will ever hold them, so they are released here rather than left for a
+    // will receive a disposer, so cleanup is attempted here rather than left for a
     // caller that never received a handle to dispose.
     closeQuietly(stdoutFd);
     removeQuietly(directory);
     throw error;
   }
+  let disposed = false;
   return {
     dispose(): void {
+      if (disposed) return;
+      disposed = true;
       closeQuietly(stdoutFd);
       closeQuietly(stderrFd);
       removeQuietly(directory);
     },
     read(stream, encoding): string | Buffer {
       const location = stream === "stdout" ? stdoutPath : stderrPath;
-      let raw: Buffer;
-      try {
-        raw = fs.readFileSync(location);
-      } catch {
-        // A spawn that never launched leaves nothing behind. Report the same
-        // empty output a failed piped capture would have.
-        raw = Buffer.alloc(0);
-      }
+      const raw = fs.readFileSync(location);
       return encoding === "buffer" ? raw : raw.toString(encoding ?? "utf8");
     },
     stderrFd,
+    stderrPath,
     stdoutFd,
+    stdoutPath,
   };
 }
 
-/** Close a descriptor, ignoring one that is already closed. */
+/** Attempt closure without replacing the acquisition or process outcome. */
 function closeQuietly(fd: number): void {
   try {
     fs.closeSync(fd);
   } catch {
-    // Already closed; removing the directory is what reclaims the space.
+    // Cleanup remains best effort, including descriptors closed by the host.
   }
 }
 

package/src/compiler/internal/compileProjectInMemory.ts

@@ -2,33 +2,60 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
-import { hasProjectPluginEntries } from "../../plugin/internal/loadProjectPlugins";
+import { hasProjectPluginEntries } from "../../plugin/internal/load/hasProjectPluginEntries";
 import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
 import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import { PrivateCompilerOutput } from "./PrivateCompilerOutput";
+import { runBuild } from "./build/runBuild";
 import { buildNativeCompiler } from "./buildNativeCompiler";
-import { isOutsideRelativePath, packageRootDir } from "./paths";
+import { outputText } from "./outputText";
+import { packageRootDir } from "./packageRootDir";
 import { readProjectConfig } from "./project/readProjectConfig";
-import { runBuild } from "./runBuild";
-import { inheritedSidecarEnv } from "./sharedHostHelpers";
-import { outputText, spawnNative } from "./spawnNative";
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
+import { inheritedSidecarEnv } from "./sharedHost/inheritedSidecarEnv";
+import { spawnNative } from "./spawnNative";
 
 /**
- * Compile a project and capture emitted files without writing to the project
- * tree.
+ * Compile a project while capturing emitted outputs instead of placing those
+ * outputs in the project tree. Compiler/plugin caches and plugin side effects
+ * remain owned by their normal paths; this is not a no-filesystem-write mode.
  *
- * When no plugins are configured the fast path spawns the native ttsc compiler
- * host (`cmd/ttsc api-compile`) which returns a structured JSON response
- * containing diagnostics and an output file map. When plugins are present the
- * slow path goes through `runBuild` into a temp directory and reads the files
- * back from disk.
+ * When no plugins are configured the native path spawns the native ttsc
+ * compiler host (`cmd/ttsc api-compile`) which returns a structured JSON
+ * response containing diagnostics and an output file map. When plugins are
+ * present the plugin path goes through `runBuild` into a temp directory and
+ * reads the files back from disk. Independent recovery checks use the same
+ * private destinations, with a separate incremental-state file that is not an
+ * emitted API artifact. Actual emission state remains in returned partial
+ * output.
+ *
+ * A native response must contain a string-valued output record. Plugin output
+ * storage removal is attempted before returning. If removal also fails after a
+ * thrown operation failure, both are retained in an AggregateError with the
+ * original cause. An unsuccessful returned build retains its diagnostics and
+ * partial output in that aggregate; removal failure after success propagates
+ * directly.
  *
  * @returns A map of output path → file content plus a `TtscBuildResult` with
  *   diagnostics and the exit status.
+ * @evidence contracts/common.md#principled-implementation The plugin-free API host supplies a required text-output record and structured diagnostics; plugin projects use the existing build owner and read its isolated emitted files with the project's output-key convention, translating private map/state coordinates back to their original artifact locations.
+ * @evidence contracts/common.md#clear-and-simple-design One router separates structured native capture from plugin-backed disk emission while project discovery, native execution and build semantics remain with their owning helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin discovery failure routes through the build's real diagnostic path, and an absent or malformed native output record cannot become an empty successful compile.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe both compile lanes and output-key ownership; separated return members explain diagnostics/status versus emitted content under documentation guidance.
+ * @evidence contracts/performance.md#efficient-algorithms Project discovery/plugin admission and native-host source/cache construction are delegated costs of this call. The native lane captures, decodes and parses complete JSON output; the plugin lane visits E entries, sorts F paths with path-text comparison costs and reads emitted bytes once. Native I/O, compiler work, output-key text and temporary storage grow with their actual inputs; no measured lane speed ranking is claimed.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each compile observes potentially changed source and plugin effects; this API owns no proven equivalent-generation cache. The native binary builder independently reuses its valid artifact.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Native capture cleanup is best effort in spawnNative; plugin emission owns one accepted temporary tree through finally removal, while temp acquisition has its own failure limitations. Cleanup failure propagates after success and aggregates with a thrown failure or a build outcome carrying nonzero status or error diagnostics, preserving its diagnostics and partial output rather than masking it.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths use Node resolution and argument arrays; inheritedSidecarEnv owns child environment spelling and the private output owner preserves native output destinations and protocol key spelling, including literal POSIX backslashes.
  */
 export function compileProjectInMemory(options: ITtscCompilerContext): {
+  /** Emitted content under the project's native API output-key convention. */
   output: Record<string, string>;
+
+  /** Compiler diagnostics, exit status and textual failure context. */
   result: TtscBuildResult;
 } {
   const cwd = path.resolve(options.cwd ?? process.cwd());
@@ -43,7 +70,9 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
   const tsconfig = project.path;
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
-    cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
+    cacheDir:
+      options.cacheDir ??
+      SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
     packageRoot: packageRootDir(),
   });
   const res = spawnNative(
@@ -51,7 +80,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     ["api-compile", "--cwd", project.root, "--tsconfig", tsconfig],
     {
       cwd: project.root,
-      env: inheritedSidecarEnv(options.env),
+      env: inheritedSidecarEnv(options.env, options.binary),
     },
   );
   if (res.error) {
@@ -68,6 +97,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     output: output.output,
     result: {
       diagnostics: output.diagnostics,
+      emittedSources: output.emittedSources,
       status: res.status ?? 1,
       stdout: "",
       stderr: outputText(res.stderr),
@@ -108,106 +138,86 @@ function compileProjectWithPlugins(
   cwd: string,
   project: ITtscParsedProjectConfig,
 ): {
+  /** Emitted content under the same project-relative keys as the native API. */
   output: Record<string, string>;
+
+  /** Compiler diagnostics, process status and textual failure context. */
   result: TtscBuildResult;
 } {
   const tempRoot = createCanonicalTempDirectory("ttsc-api-output-");
-  const tempOutDir = path.join(tempRoot, "out");
+  let outcome: ReturnType<typeof compileProjectInMemory> | undefined;
+  let failed = false;
+  let failure: unknown;
   try {
+    const layout = PrivateCompilerOutput.create(project, tempRoot);
     const result = runBuild({
       ...options,
       cwd,
       emit: true,
       forceListEmittedFiles: true,
-      outDir: tempOutDir,
-      // The temp directory is an `outDir` this lane injected so the emit can be
-      // read back as strings; the project need not declare one at all. tsgo
-      // answers an inferred common source directory with TS5011 as soon as any
-      // `outDir` is in play, so pin the root it would infer. The keys
-      // `outputKeyMapper` builds are unchanged by it — that root is exactly the
-      // layout tsgo already lays the emit out against (issue #1172).
-      pinInferredRootDir: true,
+      outDir: layout.destinations.outDir ?? undefined,
+      privateOutputDestinations: layout.destinations,
+      // Private output adds an outDir to source-adjacent projects. Pin only
+      // their layout root; configured roots and bundle-only layouts retain
+      // the compiler's containment and option validity.
+      pinInferredRootDir: layout.pinInferredRootDir,
       quiet: true,
       resolvedProject: project,
       structuredDiagnostics: true,
       tsconfig: project.path,
     });
-    return {
-      output: readOutputDirectory(tempOutDir, outputKeyMapper(project)),
+    outcome = {
+      output: PrivateCompilerOutput.read(
+        project,
+        tempRoot,
+        layout.originalPath,
+        layout.destinations.tsBuildInfoFile,
+        layout.destinations.diagnosticsTsBuildInfoFile,
+      ),
       result,
     };
+    return outcome;
+  } catch (error) {
+    failed = true;
+    failure = error;
+    throw error;
   } finally {
-    fs.rmSync(tempRoot, { force: true, recursive: true });
-  }
-}
-
-/**
- * Build a function that maps a path relative to the temp output directory to
- * the key used in the returned `output` map.
- *
- * When `outDir` is inside the project root the key is relative to the project
- * root (preserving the `outDir` prefix). When `outDir` is outside the project
- * root the key is absolute-style (`/absolute/outDir/relative`). When `outDir`
- * is absent the key is the bare relative path.
- */
-function outputKeyMapper(
-  project: ITtscParsedProjectConfig,
-): (relativePath: string) => string {
-  const outDir = project.compilerOptions.outDir;
-  if (!outDir) {
-    return (relativePath) => relativePath;
-  }
-  const relativeOutDir = path.relative(project.root, outDir);
-  if (relativeOutDir !== "" && !isOutsideRelativePath(relativeOutDir)) {
-    const prefix = pathToKey(relativeOutDir);
-    return (relativePath) => path.posix.join(prefix, relativePath);
-  }
-  return (relativePath) => pathToKey(path.join(outDir, relativePath));
-}
-
-/** Read every file in `directory` recursively and return a `path→content` map. */
-function readOutputDirectory(
-  directory: string,
-  keyOf: (relativePath: string) => string,
-): Record<string, string> {
-  const output: Record<string, string> = {};
-  if (!fs.existsSync(directory)) {
-    return output;
-  }
-  for (const file of listFiles(directory)) {
-    output[keyOf(pathToKey(path.relative(directory, file)))] = fs.readFileSync(
-      file,
-      "utf8",
-    );
-  }
-  return output;
-}
-
-/** Recursively list all files under `directory`, sorted for stable output. */
-function listFiles(directory: string): string[] {
-  const out: string[] = [];
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    const location = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      out.push(...listFiles(location));
-    } else if (entry.isFile()) {
-      out.push(location);
+    try {
+      fs.rmSync(tempRoot, { force: true, recursive: true });
+    } catch (cleanupError) {
+      if (failed) {
+        throw new AggregateError(
+          [failure, cleanupError],
+          "ttsc: project compilation and temporary output cleanup failed",
+          { cause: failure },
+        );
+      }
+      if (
+        outcome !== undefined &&
+        (outcome.result.status !== 0 ||
+          outcome.result.diagnostics.some(
+            (diagnostic) => diagnostic.category === "error",
+          ))
+      ) {
+        throw new AggregateError(
+          [outcome, cleanupError],
+          "ttsc: unsuccessful project compilation and temporary output cleanup failed",
+          { cause: outcome },
+        );
+      }
+      throw cleanupError;
     }
   }
-  return out.sort();
-}
-
-/** Normalise a file path to a forward-slash key suitable for the output map. */
-function pathToKey(file: string): string {
-  return file.replace(/\\/g, "/");
 }
 
 /**
  * Parse the JSON envelope written by the native compiler host to stdout.
  *
- * On success returns `{ diagnostics, output }`. On JSON parse failure throws a
- * descriptive error using stderr (preferred) or stdout as context, so callers
- * see the original compiler error rather than a generic JSON parse message.
+ * On success returns diagnostics, output and optional emitted-source
+ * provenance. Missing legacy provenance remains unknown. Malformed provenance
+ * is rejected. On JSON parse failure throws a descriptive error using stderr
+ * (preferred) or stdout as context, so callers see the original compiler error
+ * rather than a generic JSON parse message.
  */
 function parseNativeCompileOutput(
   stdout: string,
@@ -215,17 +225,54 @@ function parseNativeCompileOutput(
 ): {
   diagnostics: ITtscCompilerDiagnostic[];
   output: Record<string, string>;
+  emittedSources?: Record<string, readonly string[]>;
 } {
   try {
     const parsed = JSON.parse(stdout) as {
       diagnostics?: ITtscCompilerDiagnostic[];
       output?: Record<string, string>;
+      emittedSources?: Record<string, readonly string[]>;
     };
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed) ||
+      typeof parsed.output !== "object" ||
+      parsed.output === null ||
+      Array.isArray(parsed.output) ||
+      !Object.values(parsed.output).every((value) => typeof value === "string")
+    ) {
+      throw new Error(
+        "ttsc: native compiler host returned an invalid output map",
+      );
+    }
+    if (
+      parsed.emittedSources !== undefined &&
+      (typeof parsed.emittedSources !== "object" ||
+        parsed.emittedSources === null ||
+        Array.isArray(parsed.emittedSources) ||
+        !Object.entries(parsed.emittedSources).every(
+          ([output, sources]) =>
+            path.isAbsolute(output) &&
+            Array.isArray(sources) &&
+            sources.every(
+              (source) => typeof source === "string" && path.isAbsolute(source),
+            ),
+        ))
+    ) {
+      throw new Error(
+        "ttsc: native compiler host returned invalid emit provenance",
+      );
+    }
     return {
-      diagnostics: parsed.diagnostics ?? [],
-      output: parsed.output ?? {},
+      diagnostics: Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [],
+      output: parsed.output,
+      emittedSources: parsed.emittedSources,
     };
-  } catch {
+  } catch (error) {
+    if (error instanceof Error && !(error instanceof SyntaxError)) {
+      throw error;
+    }
     throw new Error(
       (stderr || stdout).trim() ||
         "ttsc: native compiler host returned no output",

package/src/compiler/internal/ensureExecutable.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+
+/**
+ * Ensure the binary has the executable bit set on POSIX systems. Silently skips
+ * on Windows and swallows `chmod` errors to let the original spawn error
+ * surface instead of masking it with a permission error.
+ *
+ * @evidence contracts/common.md#principled-implementation X_OK checks current access first; a failed check permits a best-effort POSIX repair that preserves the low nine permission bits and adds 0755. Special mode bits are not preserved by that masked repair.
+ * @evidence contracts/common.md#clear-and-simple-design This boundary attempts permission preparation only; spawning retains ownership of the definitive error and process outcome.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission preparation uses supported filesystem APIs and does not intercept spawning or turn missing binaries into success.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains the Windows branch and why chmod failure remains for the spawn path, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows execution does not use POSIX mode bits; other supported hosts use Node X_OK and chmod with the native path, isolating that real OS distinction here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous access/stat/chmod APIs do not return retained handles, and this declaration owns no live child or cache after returning.
+ * @evidence contracts/performance.md#efficient-algorithms Windows returns before I/O; other hosts attempt one access check and, only on failure, one stat and one chmod. Work includes native path lookup and permission-operation costs; the fixed call count does not bound native duration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work It does not coordinate compilation or memoize permission results: each call consults current access so an earlier successful check is not reused as authority after permission changes.
+ */
+export function ensureExecutable(binary: string): void {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    fs.accessSync(binary, fs.constants.X_OK);
+    return;
+  } catch {
+    try {
+      const mode = fs.statSync(binary).mode & 0o777;
+      fs.chmodSync(binary, mode | 0o755);
+    } catch {
+      /* keep the original spawn error path */
+    }
+  }
+}

package/src/compiler/internal/findNearestGoMod.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Walk up the directory tree from `from` looking for a `go.mod` file. Stops
+ * after `maxDepth` hops so callers can bound the search to a known
+ * neighbourhood of the plugin source directory.
+ *
+ * Returns the absolute path to the first `go.mod` found, or `null` when no
+ * `go.mod` exists within the depth limit or filesystem root is reached first.
+ * Only stat-observed regular files qualify; a directory named go.mod is not
+ * module metadata. The caller supplies a nonnegative integer parent limit (the
+ * maintained plugin caller uses 3). Other native stat errors propagate; a
+ * returned path is an observation, not a held identity or parsed module.
+ *
+ * @evidence contracts/common.md#principled-implementation Searching the starting directory then at most maxDepth parents implements the plugin module's nearest-owner rule; regular-file status distinguishes metadata from an identically named directory.
+ * @evidence contracts/common.md#clear-and-simple-design One bounded ancestry walk owns module discovery, while the caller owns plugin-source validation and interpretation of the resulting module root.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The search follows module ancestry and an explicit supported depth, without guessing a module from a particular plugin name or fixture layout.
+ * @evidence contracts/common.md#meaningful-documentation The native comment defines inclusive starting-directory search, parent limit, absence and file-kind requirements in separated prose following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and parent traversal handle platform roots; stat follows filesystem symlinks to actual regular module files without an OS-derived case assumption.
+ * @evidence contracts/performance.md#efficient-algorithms For the caller-supplied nonnegative integer limit, at most maxDepth plus one metadata probes occur, fewer at a filesystem root. Path resolution/join/parent text and native stat lookup costs accompany those probes; one current path avoids retaining all ancestors and no recursive source scan is performed.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Nearby go.mod files can appear or disappear; this query has no watcher or dependency identity authorizing persistent cross-request reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous walk owns no retained descriptors or historical state and transfers its nullable path result to the caller.
+ */
+export function findNearestGoMod(
+  from: string,
+  maxDepth: number,
+): string | null {
+  let current = path.resolve(from);
+  let depth = 0;
+  while (true) {
+    const candidate = path.join(current, "go.mod");
+    if (fs.statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
+      return candidate;
+    }
+    if (depth >= maxDepth) return null;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+    depth += 1;
+  }
+}

package/src/compiler/internal/isOutsideRelativePath.ts

@@ -0,0 +1,26 @@
+import path from "node:path";
+
+/**
+ * Return `true` when a relative path escapes its base directory — i.e. starts
+ * with `..` or is an absolute path. Used by callers that need to guard against
+ * path traversal before building output keys or spawning subprocesses.
+ *
+ * The input must be a native relative-path result such as path.relative, not an
+ * unnormalized user path or URL; embedded parent segments are not parsed.
+ *
+ * @evidence contracts/common.md#principled-implementation A normalized native relative result escapes through a leading parent component or an absolute different-root result; component boundaries prevent treating a name like ..notes as traversal.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate classifies path.relative results; normalization and filesystem identity remain the producing caller's responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification follows native path semantics without special-casing project names or converting a URL into a filesystem identity.
+ * @evidence contracts/common.md#meaningful-documentation The added input premise distinguishes this predicate from a general sanitizer, with separated paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.sep and path.isAbsolute interpret native separators and different-drive results; protocol slash syntax and physical identity are deliberately outside this lexical predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isOutsideRelativePath acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Exact-parent and fixed leading-component comparisons avoid splitting or normalizing the whole path. Native absolute classification is delegated to path.isAbsolute; the predicate makes no filesystem calls and does not claim constant work merely from a fixed number of expressions.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This call-local lexical predicate does not coordinate or retain completed work across consumers; its producer owns path normalization and any shared identity state.
+ */
+export function isOutsideRelativePath(relative: string): boolean {
+  return (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  );
+}

package/src/compiler/internal/outputText.ts

@@ -0,0 +1,21 @@
+/**
+ * Convert captured output to UTF-8 text; absent output becomes an empty string.
+ *
+ * @param value Already decoded text, captured bytes or absent output.
+ * @returns Existing text unchanged, UTF-8 decoded bytes or empty text.
+ * @evidence contracts/common.md#principled-implementation Nullish outputs denote no captured bytes; existing strings retain their decoded meaning and Buffers use Node's UTF-8 decoder.
+ * @evidence contracts/common.md#clear-and-simple-design One narrowing branch distinguishes absence from an already decoded string and raw bytes; no process policy belongs to this accessor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty text follows the nullish capture representation and never replaces a nonempty Buffer or a filesystem error.
+ * @evidence contracts/common.md#meaningful-documentation The native sentence explains absence and the decoding choice without repeating the union type, following the documentation skill.
+ * @evidence contracts/performance.md#efficient-algorithms Nullish/string branches do not decode; a Buffer branch delegates one UTF-8 decode with work and returned text storage proportional to supplied bytes.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transfers text to its caller without an independent descriptor, task or historical retained output table.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This decoding accessor owns no capture lifecycle or cache; mutable Buffer inputs and caller-selected output generations supply no coordinated equivalence authority here.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation outputText computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function outputText(value: string | Buffer | null | undefined): string {
+  if (value == null) {
+    return "";
+  }
+  return typeof value === "string" ? value : value.toString("utf8");
+}

package/src/compiler/internal/packageRootDir.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Walk up the directory tree from `__dirname` until a directory that contains
+ * both `package.json` and `go.mod` exists. Within the shipped package this
+ * selects the build root passed to `buildNativeCompiler` for `cmd/ttsc`;
+ * existence checks do not parse those entries or validate the command tree.
+ *
+ * Uses `fs.realpathSync.native` when available to produce the physical anchor
+ * passed to the Go build. It does not model every Go toolchain path
+ * convention.
+ *
+ * Throws when the shipped package metadata and Go module cannot be found,
+ * indicating an incomplete installation rather than a missing Go workspace.
+ * Native realpath errors propagate if the selected anchor cannot be resolved.
+ *
+ * @evidence contracts/common.md#principled-implementation Upward ancestry stops at the package's paired npm and Go metadata, matching the root required to locate cmd/ttsc; realpath returns the physical build anchor.
+ * @evidence contracts/common.md#clear-and-simple-design Root discovery owns one metadata predicate and one ancestry walk rather than relying on the compiler module's source-versus-lib depth.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The root is discovered from shipped metadata rather than a consumer fixture path or an assumed workspace layout.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the build consumer, physical-path choice and actual incomplete-installation failure, in paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation path.resolve, join and dirname use native path syntax, and realpath obtains physical identity without deriving case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms D visited ancestors incur at most two existence checks each plus native path joins/dirname work proportional to traversed text lengths. The selected root incurs one realpath operation with delegated filesystem costs; parent equality terminates the walk without directory enumeration. Invocation-local path storage depends on path length rather than a fixed string count bounding bytes.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This discovery does not own a stable installed-metadata identity or invalidation source; retaining a result across filesystem changes would turn a fresh root query into stale authority.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous metadata checks retain no handles, history or tasks; the returned physical string transfers to the caller.
+ */
+export function packageRootDir(): string {
+  let current = path.resolve(__dirname);
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, "package.json")) &&
+      fs.existsSync(path.join(current, "go.mod"))
+    ) {
+      return fs.realpathSync.native?.(current) ?? fs.realpathSync(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error("ttsc: package root not found for native compiler build");
+    }
+    current = parent;
+  }
+}