ttsc 0.12.2 → 0.12.4

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

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { TtscCompiler } from "../../TtscCompiler";
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
 import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
 import { resolveBinary } from "../../compiler/internal/resolveBinary";
 import { runBuild } from "../../compiler/internal/runBuild";
@@ -10,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 {
@@ -66,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) =>
@@ -361,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);
@@ -374,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}`);
@@ -455,7 +476,12 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   }
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const file = path.resolve(cwd, options.files[0]!);
-  const out = resolveSingleFileOut(file, cwd, options.outDir);
+  const out = resolveSingleFileOut({
+    cliOutDir: options.outDir,
+    cwd,
+    file,
+    tsconfig: options.tsconfig,
+  });
   const text = runSingleFileEmit({
     binary: options.binary,
     cwd,
@@ -471,17 +497,99 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   return 0;
 }
 
-function resolveSingleFileOut(
-  file: string,
-  cwd: string,
-  outDir?: string,
-): string {
-  const relative = path.relative(cwd, file);
-  const jsRelative = relative.replace(/\.[cm]?tsx?$/i, ".js");
-  if (outDir) {
-    return path.resolve(cwd, outDir, jsRelative);
+function resolveSingleFileOut(opts: {
+  cliOutDir?: string;
+  cwd: string;
+  file: string;
+  tsconfig?: string;
+}): string {
+  const jsBasename =
+    path.basename(opts.file).replace(/\.[cm]?tsx?$/i, "") +
+    singleFileJsExtension(opts.file);
+
+  // Explicit CLI --outDir wins. Mirrors the CWD-relative source layout under
+  // the requested directory so existing single-file invocations don't shift.
+  if (opts.cliOutDir) {
+    const relative = path.relative(opts.cwd, opts.file);
+    const jsRelative =
+      relative.slice(0, relative.length - path.extname(relative).length) +
+      singleFileJsExtension(opts.file);
+    return path.resolve(opts.cwd, opts.cliOutDir, jsRelative);
+  }
+
+  // No CLI override: honor tsconfig's outDir so `ttsc src/foo.ts` lands the
+  // emitted JS at `<outDir>/<relative-from-rootDir>.js` instead of dropping
+  // it next to the source file. This matches how project mode emits and how
+  // `tsc <file>` would behave with the same tsconfig.
+  const projectOutDir = readProjectOutDir({
+    cwd: opts.cwd,
+    file: opts.file,
+    tsconfig: opts.tsconfig,
+  });
+  if (projectOutDir !== null) {
+    const fromRoot = path.relative(projectOutDir.rootDir, opts.file);
+    if (fromRoot !== "" && !isOutsideSingleFileLayout(fromRoot)) {
+      const jsRelative =
+        fromRoot.slice(0, fromRoot.length - path.extname(fromRoot).length) +
+        singleFileJsExtension(opts.file);
+      return path.resolve(projectOutDir.outDir, jsRelative);
+    }
+    return path.resolve(projectOutDir.outDir, jsBasename);
+  }
+
+  // Last resort (no tsconfig outDir at all): emit next to the source. This
+  // preserves the legacy `ttsc <file.ts>` → `<file.js>` behavior for projects
+  // that intentionally don't configure outDir.
+  return opts.file.replace(/\.[cm]?tsx?$/i, singleFileJsExtension(opts.file));
+}
+
+function readProjectOutDir(opts: {
+  cwd: string;
+  file: string;
+  tsconfig?: string;
+}): { outDir: string; rootDir: string } | null {
+  try {
+    const project = readProjectConfig({
+      cwd: opts.cwd,
+      file: opts.file,
+      tsconfig: opts.tsconfig,
+    });
+    const outDir = project.compilerOptions.outDir;
+    if (typeof outDir !== "string" || outDir.length === 0) {
+      return null;
+    }
+    const rawRoot = project.compilerOptions.rootDir;
+    const rootDir =
+      typeof rawRoot === "string" && rawRoot.length !== 0
+        ? path.isAbsolute(rawRoot)
+          ? rawRoot
+          : path.resolve(project.root, rawRoot)
+        : project.root;
+    return { outDir, rootDir };
+  } catch {
+    // Missing or unreadable tsconfig: fall back to the legacy behavior so
+    // `ttsc <file>` still works outside a configured project.
+    return null;
+  }
+}
+
+function isOutsideSingleFileLayout(relative: string): boolean {
+  return (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  );
+}
+
+function singleFileJsExtension(file: string): string {
+  switch (path.extname(file).toLowerCase()) {
+    case ".mts":
+      return ".mjs";
+    case ".cts":
+      return ".cjs";
+    default:
+      return ".js";
   }
-  return file.replace(/\.[cm]?tsx?$/i, ".js");
 }
 
 function runWatch(
@@ -500,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()),
   );
@@ -564,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;

package/src/plugin/internal/loadProjectPlugins.ts

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import { findNearestGoMod } from "../../compiler/internal/paths";
 import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
-import type { ITtscPluginContributor } from "../../structures/ITtscPluginContributor";
 import type { ITtscPlugin } from "../../structures/ITtscPlugin";
+import type { ITtscPluginContributor } from "../../structures/ITtscPluginContributor";
 import type { ITtscPluginFactoryContext } from "../../structures/ITtscPluginFactoryContext";
 import type { ITtscProjectPluginConfig } from "../../structures/ITtscProjectPluginConfig";
 import type { TtscPluginStage } from "../../structures/TtscPluginStage";
@@ -30,6 +31,24 @@ type PackageManifest = {
   ttsc?: unknown;
 };
 
+/**
+ * Resolve, load, and build all native plugin sidecars for a TypeScript project.
+ *
+ * Reads the project config, discovers plugin entries (from tsconfig and package
+ * auto-discovery), validates and composes their descriptors, then invokes
+ * `buildSourcePlugin` to compile each Go source package into a cached binary.
+ * Returns the ordered set of loaded native plugins alongside the parsed project
+ * config.
+ *
+ * @param options.binary - Absolute path to the ttsc native helper binary.
+ * @param options.cacheDir - Override the plugin binary cache directory.
+ * @param options.cwd - Working directory for resolving relative paths.
+ * @param options.entries - Explicit plugin entries; `false` disables all
+ *   plugins (skips both tsconfig entries and package auto-discovery).
+ * @param options.file - Path to the tsconfig/jsconfig file.
+ * @param options.projectRoot - Override the project root directory.
+ * @param options.tsconfig - Alias for `file`.
+ */
 export function loadProjectPlugins(options: {
   binary: string;
   cacheDir?: string;
@@ -85,14 +104,21 @@ export function loadProjectPlugins(options: {
     validatePluginSource(plugin);
     const contributors = validatePluginContributors(plugin);
     const source = resolvePluginSource(plugin.source, context.projectRoot);
-    const kind = resolveNativeSourceKind(source, plugin, entries[index]!.config, index);
+    const kind = resolveNativeSourceKind(
+      source,
+      plugin,
+      entries[index]!.config,
+      index,
+    );
     if (kind === "linked" && stage !== "transform") {
       throw new Error(
         `ttsc: plugin "${pluginLabel(plugin, entries[index]!.config, index)}" source is a linked Go package, but only transform-stage plugins can be linked into a compiler host`,
       );
     }
     const linkedContributorName =
-      kind === "linked" ? `linked_${String(index).padStart(6, "0")}` : undefined;
+      kind === "linked"
+        ? `linked_${String(index).padStart(6, "0")}`
+        : undefined;
     return {
       contributors,
       config: entries[index]!.config,
@@ -261,6 +287,7 @@ function composePluginSources(
     return {
       ...plugin,
       source: aggregate.plugin.source,
+      contributors: aggregate.plugin.contributors,
     };
   });
 }
@@ -276,6 +303,14 @@ function matchesPluginAlias(
   );
 }
 
+/**
+ * Return `true` when the project has at least one enabled plugin entry.
+ *
+ * Used by callers that need to skip plugin-specific work when no plugins are
+ * configured, without paying the full cost of `loadProjectPlugins`.
+ *
+ * @param entries - Explicit entries; `false` always returns `false`.
+ */
 export function hasProjectPluginEntries(
   project: ITtscParsedProjectConfig,
   entries?: readonly ITtscProjectPluginConfig[] | false,
@@ -610,7 +645,10 @@ function resolveNativeSourceKind(
   config: ITtscProjectPluginConfig,
   index: number,
 ): "executable" | "linked" {
-  const packageDir = resolveGoPackageDir(source, pluginLabel(plugin, config, index));
+  const packageDir = resolveGoPackageDir(
+    source,
+    pluginLabel(plugin, config, index),
+  );
   if (findNearestGoMod(packageDir, GO_MOD_SEARCH_MAX_DEPTH) === null) {
     throw new Error(
       `ttsc: plugin "${pluginLabel(plugin, config, index)}" source must be inside a Go module with go.mod within ${GO_MOD_SEARCH_MAX_DEPTH} parent directories: ${source}`,
@@ -625,20 +663,6 @@ function resolveNativeSourceKind(
   return packageName === "main" ? "executable" : "linked";
 }
 
-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 resolveGoPackageDir(source: string, label: string): string {
   if (!fs.existsSync(source)) {
     throw new Error(`ttsc: plugin "${label}" source does not exist: ${source}`);

package/src/structures/ITtscCompilerTransformation.ts

@@ -22,7 +22,14 @@ export namespace ITtscCompilerTransformation {
     /** Non-fatal diagnostics reported during transformation. */
     diagnostics?: ITtscCompilerDiagnostic[];
 
-    /** Transformed TypeScript source text keyed by project file path. */
+    /**
+     * Transformed TypeScript source text keyed by project-relative file path.
+     *
+     * Values are TypeScript source text, never JavaScript, declaration files,
+     * or source maps. When no transform sidecar is configured, this map
+     * contains the unmodified TypeScript files loaded by the TypeScript-Go
+     * Program.
+     */
     typescript: Record<string, string>;
   }
 
@@ -31,7 +38,13 @@ export namespace ITtscCompilerTransformation {
     /** Indicates that transformation completed with diagnostics. */
     type: "failure";
 
-    /** Transformed or partially transformed TypeScript source text. */
+    /**
+     * Transformed or partially transformed TypeScript source text keyed by
+     * project-relative file path.
+     *
+     * May be empty or partial when diagnostics prevented the transform sidecar
+     * from completing its pass.
+     */
     typescript: Record<string, string>;
 
     /** Diagnostics reported during transformation. */

package/src/structures/ITtscPlugin.ts

@@ -96,5 +96,4 @@ export interface ITtscPlugin {
    *   unique within a single plugin build.
    */
   contributors?: ITtscPluginContributor[];
-
 }

package/src/structures/internal/TtscSingleFileEmitOptions.ts

@@ -10,6 +10,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;
 }