ttsc 0.12.3 → 0.12.4

package/src/compiler/internal/spawnNative.ts

@@ -0,0 +1,64 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+
+/**
+ * Spawn a native binary (or a Node.js script when the path has a JS/TS
+ * extension) with the given args and return the `spawnSync` result. Sets a
+ * generous 256 MiB output buffer so large projects do not truncate.
+ *
+ * When `options.encoding` is omitted it defaults to `"utf8"`. Pass an explicit
+ * value when the caller needs a different encoding or raw `Buffer` output.
+ */
+export function spawnNative(
+  binary: string,
+  args: readonly string[],
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    encoding?: BufferEncoding;
+  },
+) {
+  const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
+  if (!viaNode) {
+    ensureExecutable(binary);
+  }
+  return spawnSync(
+    viaNode ? process.execPath : binary,
+    viaNode ? [binary, ...args] : [...args],
+    {
+      cwd: options.cwd,
+      encoding: options.encoding ?? "utf8",
+      env: options.env,
+      maxBuffer: 1024 * 1024 * 256,
+      windowsHide: true,
+    },
+  );
+}
+
+/**
+ * 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.
+ */
+export function ensureExecutable(binary: string): void {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    const mode = fs.statSync(binary).mode & 0o777;
+    if ((mode & 0o111) !== 0) {
+      return;
+    }
+    fs.chmodSync(binary, mode | 0o755);
+  } catch {
+    /* keep the original spawn error path */
+  }
+}
+
+/** Coerce a `spawnSync` output value to a plain string, defaulting to `""`. */
+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/transformProjectInMemory.ts

@@ -1,5 +1,3 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 
 import {
@@ -12,6 +10,7 @@ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoa
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import { buildNativeCompiler } from "./buildNativeCompiler";
+import { packageRootDir } from "./paths";
 import { readProjectConfig } from "./project/readProjectConfig";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
@@ -21,8 +20,23 @@ import {
   linkedTransformPlugins,
   selectSharedHostPlugin,
 } from "./sharedHostHelpers";
+import { outputText, spawnNative } from "./spawnNative";
 
-/** Transform a project and capture TypeScript source output in memory. */
+/**
+ * Transform a project and capture TypeScript source output in memory.
+ *
+ * When no plugins are configured the fast path spawns the native ttsc compiler
+ * host (`cmd/ttsc api-transform`) which returns a JSON map of transformed
+ * TypeScript sources. When plugins are present:
+ *
+ * 1. Check-stage plugins run first and abort on failure.
+ * 2. If there are no transform-stage plugins the host is used as the transformer.
+ * 3. If transform plugins exist they are dispatched through the shared-host binary
+ *    with linked plugins passed via `TTSC_LINKED_PLUGINS_JSON`.
+ *
+ * @returns A `{ result, typescript }` pair where `typescript` maps output paths
+ *   to their transformed TypeScript source text.
+ */
 export function transformProjectInMemory(options: ITtscCompilerContext): {
   result: TtscBuildResult;
   typescript: Record<string, string>;
@@ -39,6 +53,7 @@ export function transformProjectInMemory(options: ITtscCompilerContext): {
   return transformProjectWithNativeHost(options, project);
 }
 
+/** Return true when the project or the call-level options declare any plugins. */
 function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -46,6 +61,11 @@ function hasConfiguredPlugins(
   return hasProjectPluginEntries(project, options.plugins);
 }
 
+/**
+ * Transform via the built-in native compiler host (`cmd/ttsc api-transform`).
+ * Used when no user plugins are configured, or as the fallback transformer when
+ * check-stage plugins pass and no transform-stage plugins are declared.
+ */
 function transformProjectWithNativeHost(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -160,6 +180,10 @@ function transformProjectWithPlugins(
   };
 }
 
+/**
+ * Run every check-stage plugin in sequence, short-circuiting on the first
+ * failure. Returns the aggregated `TtscBuildResult` (status 0 when all pass).
+ */
 function runNativeChecks(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -204,6 +228,7 @@ function runNativeChecks(
   return result;
 }
 
+/** Build the CLI argument list for the `transform` subcommand. */
 function createNativeTransformArgs(
   project: ITtscParsedProjectConfig,
   plugins: readonly ITtscLoadedNativePlugin[],
@@ -216,6 +241,7 @@ function createNativeTransformArgs(
   ];
 }
 
+/** Build the CLI argument list for the `check` subcommand. */
 function createNativeCheckArgs(
   project: ITtscParsedProjectConfig,
   plugins: readonly ITtscLoadedNativePlugin[],
@@ -228,6 +254,10 @@ function createNativeCheckArgs(
   ];
 }
 
+/**
+ * Serialize the plugin list to a JSON string for `--plugins-json=`. Only the
+ * fields the native binary needs are included to keep the arg short.
+ */
 function serializeNativePlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): string {
@@ -240,6 +270,12 @@ function serializeNativePlugins(
   );
 }
 
+/**
+ * Build the environment for a native plugin spawn. Injects `TTSC_NODE_BINARY`,
+ * `TTSC_TSGO_BINARY`, and `TTSC_TTSX_BINARY` so the sidecar can re-invoke
+ * Node.js or tsgo without searching PATH. For transform plugins, also passes
+ * `TTSC_LINKED_PLUGINS_JSON` when linked sources are present.
+ */
 function nativePluginEnv(
   options: ITtscCompilerContext,
   projectRoot: string,
@@ -265,53 +301,13 @@ function nativePluginEnv(
   return env;
 }
 
-function spawnNative(
-  binary: string,
-  args: readonly string[],
-  options: {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-  },
-) {
-  const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
-  if (!viaNode) {
-    ensureExecutable(binary);
-  }
-  return spawnSync(
-    viaNode ? process.execPath : binary,
-    viaNode ? [binary, ...args] : [...args],
-    {
-      cwd: options.cwd,
-      encoding: "utf8",
-      env: options.env,
-      maxBuffer: 1024 * 1024 * 256,
-      windowsHide: true,
-    },
-  );
-}
-
-function ensureExecutable(binary: string): void {
-  if (process.platform === "win32") {
-    return;
-  }
-  try {
-    const mode = fs.statSync(binary).mode & 0o777;
-    if ((mode & 0o111) !== 0) {
-      return;
-    }
-    fs.chmodSync(binary, mode | 0o755);
-  } catch {
-    /* keep the original spawn error path */
-  }
-}
-
-function outputText(value: string | Buffer | null | undefined): string {
-  if (value == null) {
-    return "";
-  }
-  return typeof value === "string" ? value : value.toString("utf8");
-}
-
+/**
+ * Parse the JSON envelope written by the native transform host to stdout.
+ *
+ * The `typescript` field must be a `Record<string, string>`. Any other shape is
+ * treated as a protocol error and throws with the stderr/stdout context. JSON
+ * parse errors are also wrapped with the same context message.
+ */
 function parseNativeTransformOutput(
   stdout: string,
   stderr: string,
@@ -344,6 +340,7 @@ function parseNativeTransformOutput(
   }
 }
 
+/** Type guard: true when `value` is a non-null, non-array object of strings. */
 function isTextRecord(value: unknown): value is Record<string, string> {
   return (
     typeof value === "object" &&
@@ -352,20 +349,3 @@ function isTextRecord(value: unknown): value is Record<string, string> {
     Object.values(value).every((entry) => typeof entry === "string")
   );
 }
-
-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/launcher/internal/getCompilerVersionText.ts

@@ -23,6 +23,7 @@ export function getCompilerVersionText(
   return `ttsc ${readOwnPackageVersion()} (${outputText(res.stdout).trim()})`;
 }
 
+/** Coerce a spawnSync stdio field (string | Buffer | null) to a plain string. */
 function outputText(value: string | Buffer | null | undefined): string {
   if (value == null) {
     return "";
@@ -30,6 +31,12 @@ function outputText(value: string | Buffer | null | undefined): string {
   return typeof value === "string" ? value : value.toString("utf8");
 }
 
+/**
+ * Read the `version` field from the `@ttsc/ttsc` package.json that sits three
+ * directories above the compiled launcher output (`lib/launcher/internal/`).
+ * Returns `"0.0.0"` on any I/O or parse failure so the banner is always safe to
+ * display.
+ */
 function readOwnPackageVersion(): string {
   try {
     const file = path.resolve(__dirname, "..", "..", "..", "package.json");

package/src/launcher/internal/prepareExecution.ts

@@ -7,7 +7,14 @@ import { resolveEmittedJavaScript } from "../../compiler/internal/resolveEmitted
 import { runBuild } from "../../compiler/internal/runBuild";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
 
+/** Subdirectory name that isolates concurrent ttsx processes by PID. */
 const PROCESS_CACHE_KEY = String(process.pid);
+/**
+ * Maximum number of ancestor directories above the project root that the
+ * virtual filesystem overlay mirrors. Three levels covers the common monorepo
+ * layout (workspace-root → packages → package-root) so `node_modules` symlinks
+ * resolve correctly without reaching an unsafe boundary.
+ */
 const MAX_VIRTUAL_PARENT_DEPTH = 3;
 
 /** Build the owning project and locate the emitted JavaScript entry for `ttsx`. */
@@ -162,6 +169,7 @@ function linkVirtualEntry(
   entry: fs.Dirent,
 ): void {
   if (entry.isDirectory()) {
+    // Use junction points on Windows; plain symlinks elsewhere.
     fs.symlinkSync(
       realEntry,
       virtualEntry,
@@ -171,15 +179,25 @@ function linkVirtualEntry(
   }
   if (entry.isFile()) {
     try {
+      // Hard-link first: cheap, preserves inode, no extra disk usage.
       fs.linkSync(realEntry, virtualEntry);
     } catch {
+      // Cross-device or unsupported filesystem: fall back to a full copy.
       fs.copyFileSync(realEntry, virtualEntry);
     }
     return;
   }
+  // Symlinks (and other special entries) are re-symlinked as-is.
   fs.symlinkSync(realEntry, virtualEntry);
 }
 
+/**
+ * Walk from `projectRoot` upward (up to `MAX_VIRTUAL_PARENT_DEPTH` steps),
+ * stopping early at a workspace root (`pnpm-workspace.yaml` or `.git`). The
+ * collected directories are reversed so callers can iterate outermost-first,
+ * which lets inner symlinks override outer ones without conflicting mkdir
+ * calls.
+ */
 function collectLinkDirectories(projectRoot: string): string[] {
   const out: string[] = [];
   let current = projectRoot;
@@ -207,6 +225,14 @@ function isUnsafeVirtualParent(directory: string): boolean {
   return resolved === root || resolved === path.resolve(os.tmpdir());
 }
 
+/**
+ * Map an absolute path into a stable, filesystem-safe subtree under `root`.
+ *
+ * On POSIX the root is always `/`, so every path shares the same prefix —
+ * represented here as `"posix"`. On Windows, drive letters and UNC roots each
+ * get a sanitized label (e.g. `"C_"` for `C:\`), preventing collisions between
+ * paths from different drives inside the same virtual root.
+ */
 function virtualPath(root: string, absolute: string): string {
   const parsed = path.parse(path.resolve(absolute));
   const label =
@@ -218,6 +244,12 @@ function virtualPath(root: string, absolute: string): string {
   return path.join(root, label, relative);
 }
 
+/**
+ * Heuristic: classify emitted JS as ESM when it contains top-level `import` or
+ * `export` statements but none of the well-known CJS patterns. The CJS checks
+ * run first so that re-exported CJS bundles with both `require` calls and an
+ * `export` declaration are conservatively treated as CJS.
+ */
 function looksLikeESM(output: string): boolean {
   if (
     /\bObject\.defineProperty\(exports\b/.test(output) ||

package/src/launcher/internal/resolveCacheDir.ts

@@ -0,0 +1,19 @@
+import path from "node:path";
+
+/**
+ * Resolve a user-supplied `--cache-dir` value into an absolute path.
+ *
+ * When `cacheDir` is absent or empty, returns `undefined` so callers fall
+ * through to the environment variable and global-cache defaults handled inside
+ * `buildSourcePlugin`. When `cacheDir` is already absolute it is returned
+ * unchanged; otherwise it is resolved relative to `cwd`.
+ */
+export function resolveCacheDir(
+  cwd: string,
+  cacheDir?: string,
+): string | undefined {
+  if (!cacheDir) {
+    return undefined;
+  }
+  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
+}

package/src/launcher/internal/resolveTtscserverBinary.ts

@@ -47,5 +47,7 @@ function defaultLocalBinaryPath(): string | null {
 
 function packageRootDir(): string {
   const moduleDir = path.resolve(__dirname, "..", "..");
+  // Prefer the faster native variant; fall back to the JS implementation on
+  // platforms (or environments) where `realpathSync.native` is unavailable.
   return fs.realpathSync.native?.(moduleDir) ?? fs.realpathSync(moduleDir);
 }

package/src/launcher/internal/runTtsc.ts

@@ -11,7 +11,18 @@ import { runSingleFileEmit } from "../../compiler/internal/runSingleFileEmit";
 import { defaultPluginCacheCleanTargets } from "../../plugin/internal/buildSourcePlugin";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import { getCompilerVersionText } from "./getCompilerVersionText";
-
+import { resolveCacheDir } from "./resolveCacheDir";
+
+/**
+ * CLI entry point for `ttsc`. Dispatches argv to the appropriate build lane
+ * (build, check, fix, format, prepare, clean, or native-delegate) and returns
+ * an exit code. Errors thrown by any lane are caught here and written to stderr
+ * so the process can exit cleanly.
+ *
+ * @param argv - Command-line arguments (defaults to `process.argv.slice(2)`).
+ * @returns The exit code: `0` on success, `1` on binary-not-found, `2` on user
+ *   error or build failure.
+ */
 export function runTtsc(
   argv: readonly string[] = process.argv.slice(2),
 ): number {
@@ -67,6 +78,12 @@ export function runTtsc(
   }
 }
 
+/**
+ * Return `true` when `command` looks like a build argument rather than a
+ * subcommand name — a flag (`-p`, `--watch`, …) or a TypeScript/config file
+ * path. These are forwarded to the build lane unchanged so users can write
+ * `ttsc -p tsconfig.json` without an explicit `build` subcommand.
+ */
 function isBuildAlias(command: string): boolean {
   if (command.startsWith("-")) return true;
   return [".json", ".ts", ".tsx", ".mts", ".cts"].some((ext) =>
@@ -362,6 +379,8 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
         } else if (current.startsWith("--outDir=")) {
           outDir = current.slice("--outDir=".length);
         } else if (current === "-w") {
+          // Unreachable: `-w` is handled by the switch case above. Kept here
+          // as a guard in case the switch is refactored in the future.
           watch = true;
         } else if (current.startsWith("--tsconfig=")) {
           tsconfig = current.slice("--tsconfig=".length);
@@ -375,6 +394,7 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
         } else if (current.startsWith("--cache-dir=")) {
           cacheDir = current.slice("--cache-dir=".length);
         } else if (current === "--verbose") {
+          // Unreachable: `--verbose` is handled by the switch case above.
           quiet = false;
         } else if (current.startsWith("-")) {
           throw new Error(`ttsc: unknown option ${current}`);
@@ -588,8 +608,7 @@ function runWatch(
       tsconfig: options.tsconfig,
     }),
   );
-  const watchRoot = root;
-  const directories = collectWatchDirectories(watchRoot);
+  const directories = collectWatchDirectories(root);
   const watchers = directories.map((dir) =>
     fs.watch(dir, { persistent: true }, () => trigger()),
   );
@@ -652,13 +671,6 @@ function runWatch(
   return 0;
 }
 
-function resolveCacheDir(cwd: string, cacheDir?: string): string | undefined {
-  if (!cacheDir) {
-    return undefined;
-  }
-  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
-}
-
 function collectWatchDirectories(root: string): string[] {
   const out: string[] = [];
   const stack: string[] = [root];

package/src/launcher/internal/runTtscserver.ts

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
-import * as os from "node:os";
+import os from "node:os";
 
 import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
 import { resolveTtscserverBinary } from "./resolveTtscserverBinary";
@@ -66,8 +66,16 @@ export function runTtscserver(
   return result.status ?? 1;
 }
 
+/**
+ * Build the environment for the native binary. When running in `--stdio` (LSP)
+ * mode the Go binary needs to know which tsgo binary to wrap; inject
+ * `TTSC_TSGO_BINARY` so the native host does not have to re-resolve it from
+ * inside a potentially different working directory. Skip injection when the
+ * caller already provided the variable or passed an explicit `--tsgo` option.
+ */
 function resolveTtscserverEnv(argv: readonly string[]): NodeJS.ProcessEnv {
   if (!argv.includes("--stdio")) {
+    // Non-LSP invocations (--version, --help) do not shell out to tsgo.
     return process.env;
   }
   if (process.env.TTSC_TSGO_BINARY || hasTsgoOption(argv)) {

package/src/launcher/internal/runTtsx.ts

@@ -4,7 +4,16 @@ import path from "node:path";
 
 import { getCompilerVersionText } from "./getCompilerVersionText";
 import { prepareExecution } from "./prepareExecution";
-
+import { resolveCacheDir } from "./resolveCacheDir";
+
+/**
+ * CLI entry point for `ttsx`. Type-checks the owning project via tsgo, emits
+ * JavaScript to a PID-isolated temp directory, rewrites ESM specifiers when
+ * needed, and executes the compiled entry with the current Node.js runtime.
+ *
+ * @param argv - Command-line arguments (defaults to `process.argv.slice(2)`).
+ * @returns The child-process exit code, or `2` on a ttsx-level error.
+ */
 export function runTtsx(
   argv: readonly string[] = process.argv.slice(2),
 ): number {
@@ -172,13 +181,6 @@ function isRelativeSpecifier(specifier: string): boolean {
   );
 }
 
-function resolveCacheDir(cwd: string, cacheDir?: string): string | undefined {
-  if (!cacheDir) {
-    return undefined;
-  }
-  return path.isAbsolute(cacheDir) ? cacheDir : path.resolve(cwd, cacheDir);
-}
-
 function takeValue(flag: string, rest: string[]): string {
   const value = rest.shift();
   if (!value) {
@@ -222,6 +224,12 @@ function runPreparedEntry(
   return result.status ?? 1;
 }
 
+/**
+ * Walk every `.js`/`.mjs`/`.cjs` file in `root` and rewrite bare relative
+ * specifiers (e.g. `"./foo"`) to include the resolved file extension so Node
+ * can load them with `--input-type=module`. Files that did not change are not
+ * written back.
+ */
 function rewriteEsmSpecifiers(root: string): void {
   const stack = [root];
   while (stack.length !== 0) {
@@ -431,26 +439,37 @@ function findTemplateExpressionEnd(
   return null;
 }
 
+/**
+ * Append or fix a file extension on a relative specifier so that Node's ESM
+ * loader can resolve it. The resolution order mirrors Node's own algorithm:
+ * exact file match → directory index → `.js` fallback. Non-relative specifiers
+ * and already-extensioned paths are returned unchanged.
+ */
 function withResolvableExtension(fromFile: string, specifier: string): string {
   if (!specifier.startsWith(".")) {
+    // Bare specifiers (packages, builtins) need no rewriting.
     return specifier;
   }
   if (/\.(?:[cm]?js|json|node)$/i.test(specifier)) {
+    // Already has a concrete extension the loader understands.
     return specifier;
   }
   const [pathname, suffix = ""] = splitSpecifierSuffix(specifier);
   const fromDir = path.dirname(fromFile);
+  // 1. Try the specifier as a file path with each JS extension.
   for (const extension of [".js", ".mjs", ".cjs"]) {
     if (fs.existsSync(path.resolve(fromDir, pathname + extension))) {
       return pathname + extension + suffix;
     }
   }
+  // 2. Try interpreting it as a directory with an index file.
   const directory = pathname.replace(/\/+$/, "");
   for (const extension of [".js", ".mjs", ".cjs"]) {
     if (fs.existsSync(path.resolve(fromDir, directory, "index" + extension))) {
       return `${directory}/index${extension}${suffix}`;
     }
   }
+  // 3. Last resort: append `.js` and let Node surface the error if it's wrong.
   return `${specifier}.js`;
 }
 
@@ -553,6 +572,12 @@ function skipRegex(input: string, start: number): number {
   return input.length;
 }
 
+/**
+ * Determine whether the `/` at `start` opens a regex literal rather than a
+ * division operator. This is a conservative approximation: check the preceding
+ * non-whitespace token — if it is an operator character or a keyword that must
+ * be followed by an expression, we assume regex.
+ */
 function looksLikeRegexStart(input: string, start: number): boolean {
   let i = start - 1;
   while (i >= 0 && /\s/.test(input[i]!)) {

package/src/plugin/internal/buildSourcePlugin.ts

@@ -5,6 +5,8 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 
+import { findNearestGoMod } from "../../compiler/internal/paths";
+
 const GO_MOD_SEARCH_MAX_DEPTH = 3;
 const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
 const TSGO_GO_MODULE_PATH = "github.com/microsoft/typescript-go";
@@ -397,20 +399,6 @@ function resolveSourceBuildTarget(opts: {
   };
 }
 
-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;
-  }
-}
-
 function materializeScratchDir(source: string, scratch: string): void {
   fs.mkdirSync(scratch, { recursive: true });
   fs.cpSync(source, scratch, {
@@ -768,6 +756,19 @@ function walkForGoMod(dir: string, out: string[]): void {
   }
 }
 
+/**
+ * Resolve the directory where compiled plugin binaries are cached.
+ *
+ * Priority order:
+ *
+ * 1. `cacheDir` option (resolved relative to `projectRoot`).
+ * 2. `TTSC_CACHE_DIR` environment variable.
+ * 3. Platform-specific global user cache (XDG / AppData / Library/Caches).
+ *
+ * When falling back to the global cache, a GC pass is triggered
+ * opportunistically to evict old or oversized entries before the cache is
+ * used.
+ */
 export function resolvePluginCacheRoot(
   projectRoot: string,
   cacheDir?: string,
@@ -783,6 +784,13 @@ export function resolvePluginCacheRoot(
   return root;
 }
 
+/**
+ * Return the absolute path to the global plugin binary cache root.
+ *
+ * The path follows platform conventions (XDG on Linux, AppData on Windows,
+ * Library/Caches on macOS) and does not depend on project-local config. Used by
+ * `ttsc cache clean` to enumerate cache locations.
+ */
 export function resolveGlobalPluginCacheRoot(): string {
   return path.join(
     resolveUserCacheRoot(),
@@ -791,6 +799,13 @@ export function resolveGlobalPluginCacheRoot(): string {
   );
 }
 
+/**
+ * Return all directories that `ttsc cache clean` should wipe for a project.
+ *
+ * Covers three locations where plugin binaries may accumulate: the global user
+ * cache, the project-local `node_modules/.ttsc` cache (legacy), and the
+ * project-local `.ttsc` cache.
+ */
 export function defaultPluginCacheCleanTargets(projectRoot: string): string[] {
   return [
     resolveGlobalPluginCacheRoot(),
@@ -878,6 +893,17 @@ function resolveGoCompiler(): string {
   return "go";
 }
 
+/**
+ * Compute a deterministic SHA-256 cache key for a plugin build.
+ *
+ * The key covers every input that can produce a different binary: ttsc/tsgo
+ * versions, platform, entry package, Go compiler identity, Go build environment
+ * variables, overlay module sources, plugin source files, and contributor
+ * source files. Contributors are sorted by name so declaration order does not
+ * affect the key.
+ *
+ * Exposed for testing and for the `ttsc cache` CLI command.
+ */
 export function computeCacheKey(inputs: {
   contributors?: readonly ITtscBuildContributor[];
   dir: string;