ttsc 0.12.3 → 0.12.4

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)
+  );
+}

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

@@ -7,18 +7,36 @@ import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITts
 import type { ITtscProjectLocatorOptions } from "../../../structures/internal/ITtscProjectLocatorOptions";
 import { resolveProjectConfig } from "./resolveProjectConfig";
 
+/**
+ * Compiler option keys whose values are file-system paths that must be resolved
+ * relative to the tsconfig that declares them, not the project root.
+ */
 const PATH_OPTIONS = new Set(["baseUrl", "declarationDir", "rootDir"]);
 
+/**
+ * Intermediate type used during `extends`-chain resolution before the result is
+ * projected into `ITtscParsedProjectConfig`.
+ */
 type ResolvedCompilerOptions = {
   options: Record<string, unknown>;
+  /** Directory of the tsconfig that last declared each option key. */
   optionBaseDirs: Record<string, string>;
   outDir?: string;
   pluginBaseDirs: string[];
+  /** True when any tsconfig in the chain explicitly declared `plugins`. */
   pluginsDeclared: boolean;
   plugins: ITtscProjectPluginConfig[];
 };
 
-/** Read the resolved project config subset used by ttsc. */
+/**
+ * Read and resolve the project config subset used by ttsc.
+ *
+ * Follows `extends` chains (including arrays) and merges compiler options with
+ * later configs taking precedence. Path-typed options (`baseUrl`,
+ * `declarationDir`, `rootDir`) are resolved relative to the config that
+ * declares them. The `outDir` is resolved to an absolute path. Plugins are
+ * inherited from the nearest ancestor that declares them.
+ */
 export function readProjectConfig(
   opts: ITtscProjectLocatorOptions = {},
 ): ITtscParsedProjectConfig {
@@ -39,12 +57,20 @@ export function readProjectConfig(
   };
 }
 
+/**
+ * Type guard: accept any non-null object as a plugin config entry. This is
+ * intentionally loose because the shape is validated later by plugin loaders.
+ */
 function isProjectPluginConfig(
   value: unknown,
 ): value is ITtscProjectPluginConfig {
   return typeof value === "object" && value !== null;
 }
 
+/**
+ * Resolve symlinks on `location`, returning the original path when
+ * `realpathSync` fails (e.g. when the file does not yet exist).
+ */
 function resolveRealPath(location: string): string {
   try {
     return fs.realpathSync(location);
@@ -53,10 +79,18 @@ function resolveRealPath(location: string): string {
   }
 }
 
+/** Resolve `target` against `cwd` when it is not already absolute. */
 function resolveAbsolutePath(cwd: string, target: string): string {
   return path.isAbsolute(target) ? target : path.resolve(cwd, target);
 }
 
+/**
+ * Recursively read and merge `compilerOptions` from `tsconfig` and all configs
+ * in its `extends` chain. `seen` tracks canonical paths to detect circular
+ * `extends` references; the current config is removed from `seen` in the
+ * `finally` block so sibling-referenced configs can be visited again via a
+ * different parent.
+ */
 function readResolvedCompilerOptions(
   tsconfig: string,
   seen: Set<string> = new Set(),
@@ -117,6 +151,16 @@ function readResolvedCompilerOptions(
   }
 }
 
+/**
+ * Resolve the base compiler options from the `extends` field of a tsconfig.
+ *
+ * - String: a single base config; options are returned directly.
+ * - Array: multiple base configs merged left-to-right (later entries win).
+ * - Absent / non-string non-array: returns empty options.
+ *
+ * Plugin inheritance: when the current config in an array chain explicitly
+ * declares `plugins`, subsequent configs in the array do not override them.
+ */
 function resolveBaseCompilerOptions(
   tsconfig: string,
   extended: unknown,
@@ -172,6 +216,10 @@ function resolveBaseCompilerOptions(
   return merged;
 }
 
+/**
+ * Resolve path-typed compiler options to absolute paths using the directory of
+ * the tsconfig that declared each option (`baseDirs`).
+ */
 function resolvePathOptions(
   options: Record<string, unknown>,
   baseDirs: Record<string, string>,
@@ -187,6 +235,16 @@ function resolvePathOptions(
   return resolved;
 }
 
+/**
+ * Resolve an `extends` specifier to an absolute path using the same rules as
+ * TypeScript's config resolution:
+ *
+ * - Absolute path: used directly.
+ * - Relative specifier (`./`, `../`, `.`, `..`): resolved against the declaring
+ *   tsconfig's directory with fallback extension candidates.
+ * - Bare package specifier: resolved through Node's module resolver (the resolver
+ *   also tries appending `.json` when the first attempt fails).
+ */
 function resolveExtendsConfig(tsconfig: string, specifier: string): string {
   const baseDir = path.dirname(tsconfig);
   if (path.isAbsolute(specifier)) {
@@ -203,6 +261,10 @@ function resolveExtendsConfig(tsconfig: string, specifier: string): string {
   }
 }
 
+/**
+ * Given an on-disk location, try the path as-is, with `.json` appended, and as
+ * a directory containing `tsconfig.json`. Returns the first match or throws.
+ */
 function resolveExistingExtendsPath(location: string): string {
   const candidates = new Set<string>([
     location,
@@ -217,6 +279,10 @@ function resolveExistingExtendsPath(location: string): string {
   throw new Error(`ttsc: extended tsconfig not found: ${location}`);
 }
 
+/**
+ * Return true when `specifier` is a relative path reference: `.`, `..`, or a
+ * string starting with `./`, `../`, `.\\`, or `..\\`.
+ */
 function isRelativeSpecifier(specifier: string): boolean {
   return (
     specifier === "." ||
@@ -228,10 +294,19 @@ function isRelativeSpecifier(specifier: string): boolean {
   );
 }
 
+/**
+ * Parse a JSONC (JSON with Comments) string by stripping comments and trailing
+ * commas before handing off to `JSON.parse`.
+ */
 function parseJsonc(input: string): unknown {
   return JSON.parse(stripTrailingCommas(stripComments(input)));
 }
 
+/**
+ * Remove `//` line comments and `/* block comments *\/` from a JSONC string.
+ * Correctly handles strings that contain comment-like character sequences by
+ * tracking string boundaries and escape characters.
+ */
 function stripComments(input: string): string {
   let output = "";
   let inBlockComment = false;
@@ -292,6 +367,11 @@ function stripComments(input: string): string {
   return output;
 }
 
+/**
+ * Remove trailing commas before `}` or `]` from a JSON string (after comments
+ * have already been stripped). Handles string boundaries and escape characters
+ * to avoid removing commas inside string values.
+ */
 function stripTrailingCommas(input: string): string {
   let output = "";
   let inString = false;
@@ -330,6 +410,11 @@ function stripTrailingCommas(input: string): string {
   return output;
 }
 
+/**
+ * Return the first non-whitespace character at or after position `from` in
+ * `input`, or `undefined` when only whitespace remains. Used by
+ * `stripTrailingCommas` to detect whether a comma is trailing.
+ */
 function nextNonWhitespace(input: string, from: number): string | undefined {
   for (let i = from; i < input.length; i += 1) {
     const current = input[i]!;