ttsc 0.12.3 → 0.13.0

package/lib/structures/index.d.ts

@@ -3,6 +3,7 @@ export * from "./ITtscCompilerDiagnostic";
 export * from "./ITtscCompilerResult";
 export * from "./ITtscCompilerTransformation";
 export * from "./ITtscPlugin";
+export * from "./ITtscPluginCapabilities";
 export * from "./ITtscPluginContributor";
 export * from "./ITtscPluginFactoryContext";
 export * from "./ITtscProjectPluginConfig";

package/lib/structures/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./ITtscCompilerDiagnostic"), exports);
 __exportStar(require("./ITtscCompilerResult"), exports);
 __exportStar(require("./ITtscCompilerTransformation"), exports);
 __exportStar(require("./ITtscPlugin"), exports);
+__exportStar(require("./ITtscPluginCapabilities"), exports);
 __exportStar(require("./ITtscPluginContributor"), exports);
 __exportStar(require("./ITtscPluginFactoryContext"), exports);
 __exportStar(require("./ITtscProjectPluginConfig"), exports);

package/lib/structures/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,4DAA0C;AAC1C,wDAAsC;AACtC,gEAA8C;AAC9C,gDAA8B;AAC9B,2DAAyC;AACzC,8DAA4C;AAC5C,6DAA2C;AAC3C,oDAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,4DAA0C;AAC1C,wDAAsC;AACtC,gEAA8C;AAC9C,gDAA8B;AAC9B,4DAA0C;AAC1C,2DAAyC;AACzC,8DAA4C;AAC5C,6DAA2C;AAC3C,oDAAkC"}

package/lib/structures/internal/ITtscLoadedNativePlugin.d.ts

@@ -1,3 +1,4 @@
+import type { ITtscPluginCapabilities } from "../ITtscPluginCapabilities";
 import type { ITtscPluginContributor } from "../ITtscPluginContributor";
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
 import type { TtscPluginStage } from "../TtscPluginStage";
@@ -5,6 +6,8 @@ import type { TtscPluginStage } from "../TtscPluginStage";
 export interface ITtscLoadedNativePlugin {
     /** Executable produced by the lazy Go source build cache. */
     binary: string;
+    /** Capability flags declared by the descriptor (see `ITtscPluginCapabilities`). */
+    capabilities?: ITtscPluginCapabilities;
     /** Original tsconfig plugin entry passed unchanged to the sidecar. */
     config: ITtscProjectPluginConfig;
     /** Contributor Go sources statically linked into the binary, if any. */
@@ -13,6 +16,8 @@ export interface ITtscLoadedNativePlugin {
     kind: "executable" | "linked";
     /** Optional human label used in diagnostics and native manifests. */
     name?: string;
+    /** Whether a check-stage plugin already emits TypeScript diagnostics. */
+    reportsTypeScriptDiagnostics?: boolean;
     /** Go source directory selected by the plugin descriptor. */
     source: string;
     /** Pipeline stage where the sidecar participates. */

package/lib/structures/internal/TtscCommonOptions.d.ts

@@ -21,6 +21,25 @@ export interface TtscCommonOptions {
     cacheDir?: string;
     /** Normalize compiler output so diagnostics can be parsed structurally. */
     structuredDiagnostics?: boolean;
+    /**
+     * Run TypeScript-Go single-threaded — one checker, serial parse/check/emit.
+     * Mirrors `tsgo --singleThreaded`. Useful for deterministic debugging and CI
+     * repro.
+     */
+    singleThreaded?: boolean;
+    /**
+     * Type-checker pool size, mirroring `tsgo --checkers`. `undefined` leaves
+     * TypeScript-Go's default; ignored when `singleThreaded` is set.
+     */
+    checkers?: number;
+    /**
+     * CLI tokens ttsc did not recognize as its own, forwarded verbatim to the
+     * underlying `tsgo` invocation. This is how a tsgo flag ttsc has no first-
+     * class option for (`--strict`, `--target es2020`, `--listFiles`, …) still
+     * reaches the compiler: ttsc owns its own flags and lets tsgo — which has the
+     * complete, arity-aware option parser — handle the rest.
+     */
+    passthrough?: readonly string[];
     /**
      * Override project plugin loading for this invocation.
      *

package/lib/structures/internal/TtscSingleFileEmitOptions.d.ts

@@ -9,6 +9,4 @@ export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
     out?: string;
     /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
     quiet?: boolean;
-    /** Normalize compiler output so diagnostics can be parsed structurally. */
-    structuredDiagnostics?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttsc",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "General-purpose TypeScript-Go compiler, plugin host, and runtime.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -28,17 +28,17 @@
   "homepage": "https://ttsc.dev",
   "devDependencies": {
     "@types/node": "^25.3.0",
-    "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "@typescript/native-preview": "7.0.0-dev.20260522.1",
     "rimraf": "^6.1.2"
   },
   "optionalDependencies": {
-    "@ttsc/linux-x64": "0.12.3",
-    "@ttsc/darwin-x64": "0.12.3",
-    "@ttsc/darwin-arm64": "0.12.3",
-    "@ttsc/linux-arm64": "0.12.3",
-    "@ttsc/win32-x64": "0.12.3",
-    "@ttsc/linux-arm": "0.12.3",
-    "@ttsc/win32-arm64": "0.12.3"
+    "@ttsc/linux-arm": "0.13.0",
+    "@ttsc/linux-x64": "0.13.0",
+    "@ttsc/linux-arm64": "0.13.0",
+    "@ttsc/darwin-arm64": "0.13.0",
+    "@ttsc/win32-x64": "0.13.0",
+    "@ttsc/win32-arm64": "0.13.0",
+    "@ttsc/darwin-x64": "0.13.0"
   },
   "sideEffects": false,
   "files": [

package/shim/ast/shim.go

@@ -177,44 +177,68 @@ const (
   ModifierFlagsReadonly  = innerast.ModifierFlagsReadonly
 )
 
+// NewNodeFactory creates an AST node factory with the supplied creation hooks.
+// Pass a zero-value NodeFactoryHooks to get the default factory behaviour.
 func NewNodeFactory(options NodeFactoryHooks) *NodeFactory {
   return innerast.NewNodeFactory(options)
 }
 
+// NewNodeVisitor creates a visitor that calls visit for each node encountered
+// during a tree walk, delegating node recreation to factory using hooks.
 func NewNodeVisitor(visit func(node *Node) *Node, factory *NodeFactory, options NodeVisitorHooks) *NodeVisitor {
   return innerast.NewNodeVisitor(visit, factory, options)
 }
 
+// IsFunctionLike reports whether node is any function-like construct
+// (function declaration, arrow function, method, constructor, accessor, etc.).
 func IsFunctionLike(node *Node) bool {
   return innerast.IsFunctionLike(node)
 }
 
+// IsPropertyAssignment reports whether node is a key:value pair inside an
+// object literal expression.
 func IsPropertyAssignment(node *Node) bool {
   return innerast.IsPropertyAssignment(node)
 }
 
+// IsPropertyDeclaration reports whether node is a class property declaration.
 func IsPropertyDeclaration(node *Node) bool {
   return innerast.IsPropertyDeclaration(node)
 }
 
+// IsModuleBlock reports whether node is the body block of a namespace or
+// module declaration.
 func IsModuleBlock(node *Node) bool {
   return innerast.IsModuleBlock(node)
 }
 
+// IsStringLiteral reports whether node is a string literal token.
 func IsStringLiteral(node *Node) bool {
   return innerast.IsStringLiteral(node)
 }
 
+// IsPropertyAccessExpression reports whether node is a dotted member access
+// (e.g. `a.b`).
 func IsPropertyAccessExpression(node *Node) bool {
   return innerast.IsPropertyAccessExpression(node)
 }
 
+// IsElementAccessExpression reports whether node is a bracket member access
+// (e.g. `a[b]`).
 func IsElementAccessExpression(node *Node) bool {
   return innerast.IsElementAccessExpression(node)
 }
 
+// GetSourceFileOfNode walks up the parent chain to return the SourceFile that
+// owns the given node. Linked from the internal package via go:linkname because
+// the function is unexported there.
+//
 //go:linkname GetSourceFileOfNode github.com/microsoft/typescript-go/internal/ast.GetSourceFileOfNode
 func GetSourceFileOfNode(node *innerast.Node) *innerast.SourceFile
 
+// GetNodeAtPosition returns the deepest AST node whose range covers position
+// in file. When includeJSDoc is true the search descends into JSDoc sub-trees.
+// Linked from the internal package via go:linkname.
+//
 //go:linkname GetNodeAtPosition github.com/microsoft/typescript-go/internal/ast.GetNodeAtPosition
 func GetNodeAtPosition(file *innerast.SourceFile, position int, includeJSDoc bool) *innerast.Node

package/shim/checker/shim.go

@@ -59,34 +59,50 @@ const (
   ElementFlagsVariadic = innerchecker.ElementFlagsVariadic
 )
 
+// IsTupleType reports whether t is a fixed-length tuple type.
 func IsTupleType(t *innerchecker.Type) bool {
   return innerchecker.IsTupleType(t)
 }
 
+// Checker_getIndexInfosOfType returns the index signatures (string/number/symbol
+// index infos) declared on t.
 func Checker_getIndexInfosOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.IndexInfo {
   return recv.GetIndexInfosOfType(t)
 }
 
+// Checker_getPropertiesOfType returns the named property symbols of t. For
+// union and intersection types this is the set of properties visible on every
+// member.
 func Checker_getPropertiesOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetPropertiesOfType(t)
 }
 
+// Checker_getApparentProperties returns the properties visible on t after
+// resolving primitive wrapper types (e.g. string → String).
 func Checker_getApparentProperties(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetApparentProperties(t)
 }
 
+// Checker_getTypeArguments returns the type arguments of a generic reference
+// type, or nil when t is not a reference.
 func Checker_getTypeArguments(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   return recv.GetTypeArguments(t)
 }
 
+// Checker_getTypeOfSymbol returns the declared type of symbol, resolving
+// aliases and following late-bound types.
 func Checker_getTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type {
   return recv.GetTypeOfSymbol(symbol)
 }
 
+// Checker_getTypeOfSymbolAtLocation returns the contextual type of symbol as
+// observed at the given AST node (useful for narrowed types in control flow).
 func Checker_getTypeOfSymbolAtLocation(recv *innerchecker.Checker, symbol *innerast.Symbol, node *innerast.Node) *innerchecker.Type {
   return recv.GetTypeOfSymbolAtLocation(symbol, node)
 }
 
+// Checker_getTypeOfPropertyOfType looks up the type of the named property on t
+// and returns nil when no such property exists.
 func Checker_getTypeOfPropertyOfType(recv *innerchecker.Checker, t *innerchecker.Type, name string) *innerchecker.Type {
   return recv.GetTypeOfPropertyOfType(t, name)
 }
@@ -94,6 +110,8 @@ func Checker_getTypeOfPropertyOfType(recv *innerchecker.Checker, t *innerchecker
 //go:linkname checkerGetAliasSymbolForTypeNode github.com/microsoft/typescript-go/internal/checker.(*Checker).getAliasSymbolForTypeNode
 func checkerGetAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol
 
+// Checker_getAliasSymbolForTypeNode returns the alias symbol that a type node
+// refers to when the node is itself a type alias reference (e.g. `type Foo = ...`).
 func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   return checkerGetAliasSymbolForTypeNode(recv, node)
 }
@@ -101,6 +119,8 @@ func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *inneras
 //go:linkname checkerGetDeclarationOfAliasSymbol github.com/microsoft/typescript-go/internal/checker.(*Checker).getDeclarationOfAliasSymbol
 func checkerGetDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node
 
+// Checker_getDeclarationOfAliasSymbol resolves an import/export alias symbol to
+// its original declaration node.
 func Checker_getDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node {
   return checkerGetDeclarationOfAliasSymbol(recv, symbol)
 }
@@ -108,6 +128,8 @@ func Checker_getDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *inn
 //go:linkname checkerGetTargetOfImportSpecifier github.com/microsoft/typescript-go/internal/checker.(*Checker).getTargetOfImportSpecifier
 func checkerGetTargetOfImportSpecifier(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol
 
+// Checker_getTargetOfImportSpecifier resolves an import specifier node to the
+// exported symbol it binds. Returns nil if recv or node is nil.
 func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   if recv == nil || node == nil {
     return nil
@@ -115,6 +137,8 @@ func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innera
   return checkerGetTargetOfImportSpecifier(recv, node)
 }
 
+// Checker_getAliasedSymbol follows an alias chain to its final target symbol.
+// Returns nil if recv or symbol is nil.
 func Checker_getAliasedSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Symbol {
   if recv == nil || symbol == nil {
     return nil
@@ -132,6 +156,11 @@ func checkerResolveEntityName(
   location *innerast.Node,
 ) *innerast.Symbol
 
+// Checker_resolveEntityName resolves a dotted entity name (identifier or
+// qualified name) to the symbol it denotes, filtered by meaning flags.
+// When ignoreErrors is true, resolution failures are silent. When
+// dontResolveAlias is true, the returned symbol may still be an alias.
+// Returns nil if recv or name is nil.
 func Checker_resolveEntityName(
   recv *innerchecker.Checker,
   name *innerast.Node,
@@ -149,6 +178,9 @@ func Checker_resolveEntityName(
 //go:linkname checkerGetTypeNameSymbol github.com/microsoft/typescript-go/internal/checker.getTypeNameSymbol
 func checkerGetTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol
 
+// Type_getTypeNameSymbol returns the symbol attached to t's type name field,
+// or nil when t has no name symbol or t is nil. Linked via go:linkname because
+// getTypeNameSymbol is a package-level unexported function in the checker.
 func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
   if t == nil {
     return nil
@@ -159,6 +191,7 @@ func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
 //go:linkname checkerIsArrayType github.com/microsoft/typescript-go/internal/checker.(*Checker).isArrayType
 func checkerIsArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool
 
+// Checker_isArrayType reports whether t is the built-in Array<T> reference type.
 func Checker_isArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool {
   return checkerIsArrayType(recv, t)
 }
@@ -166,6 +199,8 @@ func Checker_isArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool
 //go:linkname checkerGetBaseTypes github.com/microsoft/typescript-go/internal/checker.(*Checker).getBaseTypes
 func checkerGetBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type
 
+// Checker_getBaseTypes returns the list of base types (from `extends` clauses)
+// for a class or interface type. Returns nil if recv or t is nil.
 func Checker_getBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   if recv == nil || t == nil {
     return nil

package/shim/core/shim.go

@@ -1,17 +1,34 @@
+// Package core re-exports the subset of typescript-go's internal/core types
+// and constants that plugins and the ttsc driver need. It provides compiler
+// options, script-kind discrimination, tri-state booleans, and text-range
+// primitives without exposing the full internal surface.
 package core
 
 import innercore "github.com/microsoft/typescript-go/internal/core"
 
+// CompilerOptions holds the parsed tsconfig compiler options passed to the
+// TypeScript-Go program host.
 type CompilerOptions = innercore.CompilerOptions
+
+// Tristate is a three-valued boolean: TSFalse, TSTrue, or TSUnknown. Used by
+// CompilerOptions fields that can be explicitly unset.
 type Tristate = innercore.Tristate
+
+// TextPos is a zero-based byte offset into a source file's text.
 type TextPos = innercore.TextPos
+
+// TextRange is a half-open [Pos, End) byte range inside a source file.
 type TextRange = innercore.TextRange
+
+// ScriptKind identifies the syntactic flavour of a source file.
 type ScriptKind = innercore.ScriptKind
 
 const (
+  // TSFalse and TSTrue are the explicit-false and explicit-true Tristate values.
   TSFalse = innercore.TSFalse
   TSTrue  = innercore.TSTrue
 
+  // ScriptKind* constants enumerate the file flavours typescript-go recognises.
   ScriptKindUnknown  = innercore.ScriptKindUnknown
   ScriptKindJS       = innercore.ScriptKindJS
   ScriptKindJSX      = innercore.ScriptKindJSX

package/shim/diagnosticwriter/shim.go

@@ -1,3 +1,7 @@
+// Package diagnosticwriter re-exports the subset of typescript-go's
+// internal/diagnosticwriter surface that the ttsc driver uses. It provides
+// FormatASTDiagnosticsWithColorAndContext for rendering pure tsgo diagnostics
+// and delegates the mixed lint+tsgo rendering path to the adjacent lint.go.
 package diagnosticwriter
 
 import (

package/shim/lsp/shim.go

@@ -8,10 +8,10 @@
 package lsp
 
 import (
-	"io"
-	_ "unsafe"
+  "io"
+  _ "unsafe"
 
-	innerlsp "github.com/microsoft/typescript-go/internal/lsp"
+  innerlsp "github.com/microsoft/typescript-go/internal/lsp"
 )
 
 // Server is the opaque LSP server type from tsgo.

package/shim/printer/shim.go

@@ -1,3 +1,7 @@
+// Package printer re-exports the typescript-go internal/printer types and
+// wraps the three functions that the ttsc driver and transform plugins need
+// to emit source text from an AST. The surface is intentionally narrow: only
+// the construction and single-file emit path are exposed.
 package printer
 
 import (
@@ -5,19 +9,35 @@ import (
   innerprinter "github.com/microsoft/typescript-go/internal/printer"
 )
 
+// PrintHandlers provides optional hooks (e.g. substituteNode) called during
+// AST emission.
 type PrintHandlers = innerprinter.PrintHandlers
+
+// Printer holds the stateful emitter produced by NewPrinter.
 type Printer = innerprinter.Printer
+
+// PrinterOptions configures newline style, source-map generation, and other
+// emission knobs.
 type PrinterOptions = innerprinter.PrinterOptions
+
+// EmitContext accumulates per-emit metadata (source maps, comment positions)
+// and must be created fresh for each emit round via NewEmitContext.
 type EmitContext = innerprinter.EmitContext
 
+// NewPrinter creates an emitter with the supplied options, substitution hooks,
+// and emit context. Callers must pass the same EmitContext to all operations
+// in a single emit round.
 func NewPrinter(options PrinterOptions, handlers PrintHandlers, emitContext *EmitContext) *Printer {
   return innerprinter.NewPrinter(options, handlers, emitContext)
 }
 
+// NewEmitContext allocates a fresh EmitContext for a new emit round.
 func NewEmitContext() *EmitContext {
   return innerprinter.NewEmitContext()
 }
 
+// EmitSourceFile renders the full source file through the printer and returns
+// the emitted text.
 func EmitSourceFile(p *Printer, sourceFile *ast.SourceFile) string {
   return p.EmitSourceFile(sourceFile)
 }

package/src/TtscCompiler.ts

@@ -36,6 +36,13 @@ import type { TtscBuildResult } from "./structures/internal/TtscBuildResult";
 export class TtscCompiler {
   private readonly context: ITtscCompilerContext;
 
+  /**
+   * Create a new compiler instance bound to the given project context.
+   *
+   * The context is defensively copied: mutations to the original object after
+   * construction do not affect this instance. Omit `context` (or pass `{}`) to
+   * inherit all defaults from the running process.
+   */
   public constructor(context: ITtscCompilerContext = {}) {
     this.context = {
       ...context,

package/src/compiler/internal/buildNativeCompiler.ts

@@ -3,7 +3,17 @@ import path from "node:path";
 
 import { buildSourcePlugin } from "../../plugin/internal/buildSourcePlugin";
 
-/** Build the native ttsc compiler host used by in-memory API compilation. */
+/**
+ * Build (or retrieve from cache) the native ttsc compiler host binary used by
+ * the in-memory API compilation paths (`compileProjectInMemory`,
+ * `transformProjectInMemory`).
+ *
+ * The host is the `cmd/ttsc` Go entrypoint compiled with `buildSourcePlugin`.
+ * The cache key incorporates the ttsc package version and the full `go.mod`
+ * contents so a toolchain upgrade automatically produces a fresh binary.
+ *
+ * @returns Absolute path to the compiled host executable.
+ */
 export function buildNativeCompiler(options: {
   cacheBaseDir: string;
   cacheDir?: string;
@@ -22,6 +32,10 @@ export function buildNativeCompiler(options: {
   });
 }
 
+/**
+ * Read the `version` field from `package.json` inside `packageRoot`, falling
+ * back to `"0.0.0"` when the file is absent or malformed.
+ */
 function readOwnPackageVersion(packageRoot: string): string {
   try {
     const pkg = JSON.parse(
@@ -33,10 +47,16 @@ function readOwnPackageVersion(packageRoot: string): string {
   }
 }
 
+/**
+ * Read the full contents of `go.mod` inside `packageRoot` and use it as a
+ * version token for the binary cache key. Returns `"unknown"` on read error.
+ *
+ * Using the entire `go.mod` ensures that any dependency bump (including
+ * indirect ones) invalidates the cached binary.
+ */
 function readGoModuleVersion(packageRoot: string): string {
   try {
-    const goMod = fs.readFileSync(path.join(packageRoot, "go.mod"), "utf8");
-    return goMod;
+    return fs.readFileSync(path.join(packageRoot, "go.mod"), "utf8");
   } catch {
     return "unknown";
   }

package/src/compiler/internal/compileProjectInMemory.ts

@@ -9,12 +9,22 @@ import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiag
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import { buildNativeCompiler } from "./buildNativeCompiler";
+import { isOutsideRelativePath, packageRootDir } from "./paths";
 import { readProjectConfig } from "./project/readProjectConfig";
 import { runBuild } from "./runBuild";
 
 /**
  * Compile a project and capture emitted files without writing to the project
  * tree.
+ *
+ * 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.
+ *
+ * @returns A map of output path → file content plus a `TtscBuildResult` with
+ *   diagnostics and the exit status.
  */
 export function compileProjectInMemory(options: ITtscCompilerContext): {
   output: Record<string, string>;
@@ -64,6 +74,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
   };
 }
 
+/** Return true when the project or the call-level options declare any plugins. */
 function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -71,6 +82,10 @@ function hasConfiguredPlugins(
   return hasProjectPluginEntries(project, options.plugins);
 }
 
+/**
+ * Plugin-backed compilation: emit into a temp directory via `runBuild`, then
+ * read back every file the build wrote so they can be returned as strings.
+ */
 function compileProjectWithPlugins(
   options: ITtscCompilerContext,
   cwd: string,
@@ -101,6 +116,15 @@ function compileProjectWithPlugins(
   }
 }
 
+/**
+ * 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 {
@@ -116,14 +140,7 @@ function outputKeyMapper(
   return (relativePath) => pathToKey(path.join(outDir, relativePath));
 }
 
-function isOutsideRelativePath(relative: string): boolean {
-  return (
-    relative === ".." ||
-    relative.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(relative)
-  );
-}
-
+/** Read every file in `directory` recursively and return a `path→content` map. */
 function readOutputDirectory(
   directory: string,
   keyOf: (relativePath: string) => string,
@@ -141,6 +158,7 @@ function readOutputDirectory(
   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 })) {
@@ -154,10 +172,18 @@ function listFiles(directory: string): string[] {
   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.
+ */
 function parseNativeCompileOutput(
   stdout: string,
   stderr: string,
@@ -181,20 +207,3 @@ function parseNativeCompileOutput(
     );
   }
 }
-
-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;
-  }
-}

package/src/compiler/internal/paths.ts

@@ -0,0 +1,68 @@
+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` is found. This is the `packages/ttsc` root
+ * and must be passed to `buildNativeCompiler` so it can locate `cmd/ttsc`.
+ *
+ * Uses `fs.realpathSync.native` when available to resolve symlinks identically
+ * to the Go toolchain's own path resolution.
+ *
+ * Throws when the root cannot be found (i.e. the package is not in a Go
+ * workspace), which would indicate a broken installation.
+ */
+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;
+  }
+}
+
+/**
+ * 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.
+ */
+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.existsSync(candidate)) return candidate;
+    if (depth >= maxDepth) return null;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+    depth += 1;
+  }
+}
+
+/**
+ * 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.
+ */
+export function isOutsideRelativePath(relative: string): boolean {
+  return (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  );
+}