ttsc 0.12.3 → 0.12.4

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

@@ -3,7 +3,19 @@ import path from "node:path";
 
 import type { ITtscProjectLocatorOptions } from "../../../structures/internal/ITtscProjectLocatorOptions";
 
-/** Resolve the tsconfig/jsconfig that owns a ttsc invocation. */
+/**
+ * Resolve the tsconfig/jsconfig that owns a ttsc invocation.
+ *
+ * Resolution order:
+ *
+ * 1. `opts.tsconfig` — resolved absolute and checked for existence.
+ * 2. `opts.file` — the nearest ancestor config that contains the file is found by
+ *    walking up from the file's directory.
+ * 3. `opts.cwd` — the nearest ancestor config walking up from cwd.
+ *
+ * Always returns a real (symlink-resolved) absolute path. Throws when no config
+ * is found or the explicitly supplied path does not exist.
+ */
 export function resolveProjectConfig(
   opts: ITtscProjectLocatorOptions = {},
 ): string {
@@ -29,10 +41,15 @@ export function resolveProjectConfig(
   return resolveRealPath(found);
 }
 
+/** 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);
 }
 
+/**
+ * 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);
@@ -41,6 +58,11 @@ function resolveRealPath(location: string): string {
   }
 }
 
+/**
+ * Walk up the directory tree from `from`, returning the first directory that
+ * contains a file whose name is in `names`. Returns `null` when the filesystem
+ * root is reached without finding a match.
+ */
 function findUp(from: string, names: readonly string[]): string | null {
   let current = path.resolve(from);
   while (true) {
@@ -58,6 +80,7 @@ function findUp(from: string, names: readonly string[]): string | null {
   }
 }
 
+/** Return true when `location` exists and is a directory. */
 function isDirectory(location: string): boolean {
   try {
     return fs.statSync(location).isDirectory();

package/src/compiler/internal/resolveBinary.ts

@@ -1,7 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
 
-/** Resolve the ttsc helper binary path, or null when unavailable. */
+/**
+ * Resolve the ttsc helper binary path, or null when unavailable.
+ *
+ * Resolution order:
+ *
+ * 1. `TTSC_BINARY` env var — must be an absolute path when set.
+ * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttsc[.exe]`.
+ * 3. A `ttsc-native[.exe]` sibling of this package's root (dev/CI layout).
+ */
 export function resolveBinary(
   opts: { env?: NodeJS.ProcessEnv } = {},
 ): string | null {
@@ -24,6 +32,10 @@ export function resolveBinary(
   return null;
 }
 
+/**
+ * Return the path to the dev-layout `ttsc-native[.exe]` binary adjacent to the
+ * package root, or null when the file does not exist.
+ */
 function defaultLocalBinaryPath(): string | null {
   const root = packageRootDir();
   const candidate = path.resolve(
@@ -35,6 +47,10 @@ function defaultLocalBinaryPath(): string | null {
   return fs.existsSync(candidate) ? candidate : null;
 }
 
+/**
+ * Return the real, absolute path of the `packages/ttsc` package root by walking
+ * two levels up from `__dirname` (which lives in `src/compiler/internal`).
+ */
 function packageRootDir(): string {
   const moduleDir = path.resolve(__dirname, "..", "..");
   return fs.realpathSync.native?.(moduleDir) ?? fs.realpathSync(moduleDir);

package/src/compiler/internal/resolveEmittedJavaScript.ts

@@ -1,8 +1,25 @@
 import fs from "node:fs";
 import path from "node:path";
 
-/** Locate the JavaScript file emitted for a TypeScript source file. */
+import { isOutsideRelativePath } from "./paths";
+
+/**
+ * Locate the JavaScript file emitted for a TypeScript source file.
+ *
+ * Resolution strategy:
+ *
+ * 1. Try to derive the exact output path by mirroring the source's relative
+ *    position inside `projectRoot` into `outDir`, applying the correct JS
+ *    extension (`.js` / `.mjs` / `.cjs`). Use this path if it exists on disk.
+ * 2. Fall back to scoring each candidate in `emittedFiles` (or a recursive
+ *    directory scan of `outDir`) by the number of trailing path-stem segments
+ *    shared with the source file name, and pick the highest-scoring existing
+ *    file.
+ *
+ * Returns `null` when no matching output file is found on disk.
+ */
 export function resolveEmittedJavaScript(options: {
+  /** Pre-computed list of emitted paths; when absent `outDir` is scanned. */
   emittedFiles?: readonly string[];
   outDir: string;
   projectRoot: string;
@@ -31,6 +48,11 @@ export function resolveEmittedJavaScript(options: {
   return best && fs.existsSync(best) ? best : null;
 }
 
+/**
+ * Derive the exact output path for `sourceFile` by mirroring its position
+ * relative to `projectRoot` into `outDir`. Returns `null` when the source is
+ * not inside the project root or when the path cannot be determined.
+ */
 function resolveExactEmittedFile(
   outDir: string,
   projectRoot: string,
@@ -47,6 +69,11 @@ function resolveExactEmittedFile(
   );
 }
 
+/**
+ * Recursively enumerate every JavaScript output file under `root`. Uses an
+ * explicit stack instead of recursion to avoid call-stack overflow on deep
+ * directory trees. Non-existent roots are silently skipped.
+ */
 function listJavaScriptFiles(root: string): string[] {
   const out: string[] = [];
   const stack = [root];
@@ -65,15 +92,22 @@ function listJavaScriptFiles(root: string): string[] {
   return out;
 }
 
+/**
+ * Count the number of consecutive trailing path-stem segments that `outPath`
+ * and `srcPath` share when both are stripped of their extensions and normalised
+ * to forward slashes.
+ *
+ * Example: `dist/lib/foo.js` vs `src/lib/foo.ts` → 2 (`lib`, `foo`).
+ */
 function sharedSourceStemSegments(outPath: string, srcPath: string): number {
-  const trim = (location: string): string[] => {
+  const stripExtAndSplit = (location: string): string[] => {
     const normalized = location.replace(/\\/g, "/");
     return normalized
       .slice(0, normalized.length - path.extname(normalized).length)
       .split("/");
   };
-  const a = trim(outPath);
-  const b = trim(srcPath);
+  const a = stripExtAndSplit(outPath);
+  const b = stripExtAndSplit(srcPath);
   const count = Math.min(a.length, b.length);
   let shared = 0;
   for (let i = 1; i <= count; i += 1) {
@@ -83,14 +117,10 @@ function sharedSourceStemSegments(outPath: string, srcPath: string): number {
   return shared;
 }
 
-function isOutsideRelativePath(relative: string): boolean {
-  return (
-    relative === ".." ||
-    relative.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(relative)
-  );
-}
-
+/**
+ * Map a TypeScript source extension to its JavaScript output counterpart.
+ * `.mts` → `.mjs`, `.cts` → `.cjs`, everything else → `.js`.
+ */
 function emittedJavaScriptExtension(filename: string): string {
   switch (path.extname(filename).toLowerCase()) {
     case ".mts":
@@ -102,6 +132,7 @@ function emittedJavaScriptExtension(filename: string): string {
   }
 }
 
+/** Return true when `filename` has a `.js`, `.mjs`, or `.cjs` extension. */
 function isJavaScriptOutput(filename: string): boolean {
   return /\.(?:[cm]?js)$/i.test(filename);
 }

package/src/compiler/internal/resolveTsgo.ts

@@ -2,12 +2,32 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
-/** Resolve the consumer project's TypeScript-Go preview binary. */
+/**
+ * Resolve the consumer project's TypeScript-Go preview binary and metadata.
+ *
+ * Resolution order:
+ *
+ * 1. `opts.binary` or `TTSC_TSGO_BINARY` env var — must be an existing absolute
+ *    path; returns `{ binary, packageJson: "", packageRoot, version: "custom"
+ *    }`.
+ * 2. `@typescript/native-preview` resolved from the project `cwd`.
+ * 3. `@typescript/native-preview` resolved from `opts.resolveFrom` (for test
+ *    harnesses and embedders that anchor to a different directory).
+ *
+ * Throws a descriptive error when the package or platform binary is missing so
+ * callers never have to reason about undefined binary paths.
+ */
 export function resolveTsgo(
   opts: {
+    /** Explicit path to a tsgo binary; bypasses package resolution. */
     binary?: string;
+    /** Directory from which to discover `@typescript/native-preview`. */
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Fallback resolution anchor used when the package is not found at `cwd`.
+     * Useful in test harnesses that install the package into a different tree.
+     */
     resolveFrom?: string;
   } = {},
 ) {
@@ -28,6 +48,8 @@ export function resolveTsgo(
   }
 
   const cwd = path.resolve(opts.cwd ?? process.cwd());
+  // Resolve the package.json of @typescript/native-preview.
+  // Try cwd first, then the optional resolveFrom anchor.
   let packageJson: string;
   packageJson =
     resolveNativePreviewPackageJson(path.join(cwd, "package.json")) ??
@@ -84,6 +106,11 @@ export function resolveTsgo(
   };
 }
 
+/**
+ * Attempt to resolve the `package.json` of `@typescript/native-preview`
+ * starting from `from` (a package.json path or directory). Returns `undefined`
+ * when the package is not resolvable from that location.
+ */
 function resolveNativePreviewPackageJson(from: string): string | undefined {
   try {
     return createRequire(from).resolve(
@@ -94,6 +121,7 @@ function resolveNativePreviewPackageJson(from: string): string | undefined {
   }
 }
 
+/** Parse a JSON file and return the result as a plain object. */
 function readPackageJson(file: string): Record<string, unknown> {
   return JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
 }

package/src/compiler/internal/runBuild.ts

@@ -1,6 +1,3 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 
 import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
@@ -17,8 +14,13 @@ import {
   linkedTransformPlugins,
   selectSharedHostPlugin,
 } from "./sharedHostHelpers";
+import { outputText, spawnNative } from "./spawnNative";
 
-/** Merge spawn env without clobbering unrelated vars. */
+/**
+ * Merge extra environment variables over `process.env`, always injecting
+ * `TTSC_NODE_BINARY` so child processes can re-invoke the same Node.js binary
+ * without searching `PATH`.
+ */
 function mergeEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const base = {
     ...process.env,
@@ -28,6 +30,12 @@ function mergeEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   return { ...base, ...extra };
 }
 
+/**
+ * Build the environment for a native plugin spawn. Injects `TTSC_TSGO_BINARY`
+ * and `TTSC_TTSX_BINARY` alongside the base env from `mergeEnv`. For
+ * transform-stage plugins, also passes `TTSC_LINKED_PLUGINS_JSON` containing
+ * any linked sources so they run inside the same process as the host plugin.
+ */
 function nativePluginEnv(
   extra: NodeJS.ProcessEnv | undefined,
   execution: ReturnType<typeof resolveExecutionContext>,
@@ -49,54 +57,6 @@ function nativePluginEnv(
   return env;
 }
 
-function spawnBinary(
-  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,
-      env: options.env,
-      encoding: options.encoding,
-      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");
-}
-
 /**
  * Run `ttsc` against a tsconfig. Returns once the binary exits so the CLI can
  * decide how to surface diagnostics. Does not throw on non-zero exit.
@@ -199,6 +159,11 @@ export function runBuild(
   return runTsgoBuild(execution, options, args);
 }
 
+/**
+ * Dispatch a build through the shared-host native plugin. The host plugin is
+ * the one that owns the process (non-linked); all other transform plugins ride
+ * inside it via the `--plugins-json` flag.
+ */
 function buildWithNativeCompilerPlugins(
   options: TtscBuildOptions,
   execution: ReturnType<typeof resolveExecutionContext>,
@@ -214,12 +179,16 @@ function buildWithNativeCompilerPlugins(
   );
 }
 
+/**
+ * Run `tsgo -p <tsconfig> [extraArgs]` and return the normalized result. Used
+ * for the no-emit type-check pass that precedes file emission.
+ */
 function runTsgo(
   execution: ReturnType<typeof resolveExecutionContext>,
   extraArgs: readonly string[],
   options: NonNullable<Parameters<typeof runBuild>[0]>,
 ): TtscBuildResult {
-  const res = spawnBinary(
+  const res = spawnNative(
     execution.tsgo.binary,
     [
       "-p",
@@ -251,12 +220,17 @@ function runTsgo(
   );
 }
 
+/**
+ * Run `tsgo` with the full emit arguments and parse `TSFILE:` lines from stdout
+ * into `emittedFiles`. The TSFILE lines are stripped before the result is
+ * returned so they do not appear in the user-facing output.
+ */
 function runTsgoBuild(
   execution: ReturnType<typeof resolveExecutionContext>,
   options: NonNullable<Parameters<typeof runBuild>[0]>,
   args: readonly string[],
 ): TtscBuildResult {
-  const res = spawnBinary(execution.tsgo.binary, args, {
+  const res = spawnNative(execution.tsgo.binary, args, {
     cwd: execution.projectRoot,
     env: mergeEnv(options.env),
     encoding: "utf8",
@@ -284,6 +258,7 @@ function runTsgoBuild(
   );
 }
 
+/** Build the argument list for a direct `tsgo` build invocation. */
 function createTsgoBuildArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
   options: NonNullable<Parameters<typeof runBuild>[0]>,
@@ -305,10 +280,15 @@ function createTsgoBuildArgs(
   return args;
 }
 
+/**
+ * Return `["--pretty", "false"]` when structured diagnostics are requested so
+ * that the output can be parsed line-by-line, or an empty array otherwise.
+ */
 function createTsgoDiagnosticArgs(options: TtscCommonOptions): string[] {
   return options.structuredDiagnostics === true ? ["--pretty", "false"] : [];
 }
 
+/** Build the argument list for a native plugin `build`/`check` invocation. */
 function createNativeBuildArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
   options: TtscBuildOptions,
@@ -336,6 +316,7 @@ function createNativeBuildArgs(
   return args;
 }
 
+/** Build the argument list for a native plugin check/fix/format invocation. */
 function createNativeCheckArgs(
   execution: ReturnType<typeof resolveExecutionContext>,
   options: TtscBuildOptions,
@@ -369,6 +350,10 @@ function nativeCheckSubcommand(options: TtscBuildOptions): string {
   return "check";
 }
 
+/**
+ * Serialize the plugin list to a compact JSON string for `--plugins-json=`.
+ * Only the fields the native binary protocol requires are included.
+ */
 function serializeNativePlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): string {
@@ -381,6 +366,10 @@ function serializeNativePlugins(
   );
 }
 
+/**
+ * Run every check-stage plugin in order, short-circuiting on the first non-zero
+ * exit. Aggregates diagnostics and output across all check plugins.
+ */
 function runNativeCheckPlugins(
   options: TtscBuildOptions,
   execution: ReturnType<typeof resolveExecutionContext>,
@@ -409,6 +398,11 @@ function runNativeCheckPlugins(
   return out;
 }
 
+/**
+ * Spawn a single native plugin binary with the given args and return the
+ * normalized build result. `label` is used in the thrown error message so the
+ * caller's context (e.g. `"ttsc.check"` or `"ttsc.build"`) is preserved.
+ */
 function runNativePluginCommand(
   plugin: ITtscLoadedNativePlugin,
   args: readonly string[],
@@ -416,7 +410,7 @@ function runNativePluginCommand(
   execution: ReturnType<typeof resolveExecutionContext>,
   label: string,
 ): TtscBuildResult {
-  const res = spawnBinary(plugin.binary, args, {
+  const res = spawnNative(plugin.binary, args, {
     cwd: execution.projectRoot,
     env: nativePluginEnv(options.env, execution, plugin),
     encoding: "utf8",
@@ -436,6 +430,14 @@ function runNativePluginCommand(
   );
 }
 
+/**
+ * Merge two `TtscBuildResult` values into one.
+ *
+ * - `status`: the right status wins unless it is 0 (failure propagates).
+ * - `diagnostics`: concatenated left then right.
+ * - `emittedFiles`: right wins when present, otherwise left is kept.
+ * - `stdout`/`stderr`: concatenated left then right.
+ */
 export function appendBuildOutput(
   left: TtscBuildResult,
   right: TtscBuildResult,
@@ -450,6 +452,11 @@ export function appendBuildOutput(
   });
 }
 
+/**
+ * Resolve all runtime context needed for a build: cwd, tsconfig path, project
+ * root, tsgo binary location, and the loaded native plugin list. Centralised
+ * here so every code path in `runBuild` shares the same resolution logic.
+ */
 function resolveExecutionContext(
   options: TtscCommonOptions & { tsconfig?: string },
 ) {
@@ -480,6 +487,10 @@ function resolveExecutionContext(
   };
 }
 
+/**
+ * Extract `TSFILE: <path>` lines from tsgo stdout and return the absolute
+ * paths. tsgo emits these when `--listEmittedFiles` is passed.
+ */
 function parseEmittedFiles(stdout: string): string[] {
   const out: string[] = [];
   for (const line of stdout.split(/\r?\n/)) {
@@ -491,6 +502,10 @@ function parseEmittedFiles(stdout: string): string[] {
   return out;
 }
 
+/**
+ * Remove `TSFILE:` lines from tsgo stdout so they do not appear in the
+ * user-facing output after they have been parsed into `emittedFiles`.
+ */
 function stripEmittedFileLines(stdout: string): string {
   return stdout
     .split(/\r?\n/)
@@ -499,10 +514,21 @@ function stripEmittedFileLines(stdout: string): string {
     .replace(/\n+$/, "");
 }
 
+/**
+ * `TtscBuildResult` with `diagnostics` made optional. Used internally when
+ * diagnostics are parsed lazily from stdout/stderr by `normalizeBuildOutput`.
+ */
 type PartialBuildResult = Omit<TtscBuildResult, "diagnostics"> & {
   diagnostics?: ITtscCompilerDiagnostic[];
 };
 
+/**
+ * Normalise a raw spawn result into a `TtscBuildResult`.
+ *
+ * When `diagnostics` is absent they are parsed from the text output. When the
+ * process exited non-zero but stderr is empty and stdout is non-empty, stdout
+ * is moved to stderr so the error is visible to callers who only check stderr.
+ */
 export function normalizeBuildOutput(
   result: PartialBuildResult,
   cwd?: string,
@@ -524,6 +550,11 @@ export function normalizeBuildOutput(
   };
 }
 
+/**
+ * Parse structured diagnostics from the combined stderr+stdout text when the
+ * caller did not supply pre-parsed diagnostics. ANSI escape codes are stripped
+ * and `TSFILE:` / `Found N errors` summary lines are skipped.
+ */
 function parseCompilerDiagnostics(
   result: Pick<TtscBuildResult, "stderr" | "stdout">,
   cwd: string | undefined,
@@ -553,6 +584,16 @@ function parseCompilerDiagnostics(
   return out;
 }
 
+/**
+ * Try to parse a single line as a TypeScript compiler diagnostic in one of
+ * three formats:
+ *
+ * - `file:line:col - category TSxxxx: message` (colon-separated, tsgo style)
+ * - `file(line,col): category TSxxxx: message` (paren style, classic tsc)
+ * - `category TSxxxx: message` (global, no file)
+ *
+ * Returns `null` when the line does not match any format.
+ */
 function parseDiagnosticLine(
   line: string,
   cwd: string | undefined,
@@ -599,6 +640,10 @@ function parseDiagnosticLine(
   };
 }
 
+/**
+ * Return an absolute file path. When `file` is already absolute it is returned
+ * unchanged; relative paths are resolved against `cwd` when available.
+ */
 function normalizeDiagnosticFile(
   file: string,
   cwd: string | undefined,
@@ -609,6 +654,11 @@ function normalizeDiagnosticFile(
   return path.resolve(cwd, file);
 }
 
+/**
+ * Map a raw category string (`"error"`, `"warning"`, `"suggestion"`,
+ * `"message"`) to the canonical `ITtscCompilerDiagnostic.Category`. Any
+ * unrecognised value is coerced to `"error"`.
+ */
 function normalizeDiagnosticCategory(
   value: string,
 ): ITtscCompilerDiagnostic.Category {
@@ -620,10 +670,15 @@ function normalizeDiagnosticCategory(
     : "error";
 }
 
+/**
+ * Parse a diagnostic code as a number when it is all digits (TS numeric codes
+ * like `2322`), or keep it as a string for plugin-defined alphanumeric codes.
+ */
 function normalizeDiagnosticCode(value: string): number | string {
   return /^\d+$/.test(value) ? Number(value) : value;
 }
 
+/** Strip ANSI escape sequences from `text` for line-by-line diagnostic parsing. */
 function stripAnsi(text: string): string {
   return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
 }

package/src/compiler/internal/runSingleFileEmit.ts

@@ -7,7 +7,16 @@ import { resolveProjectConfig } from "./project/resolveProjectConfig";
 import { resolveEmittedJavaScript } from "./resolveEmittedJavaScript";
 import { runBuild } from "./runBuild";
 
-/** Emit one source file by building its project into a temporary directory. */
+/**
+ * Emit one source file by building its project into a temporary directory.
+ *
+ * The full project is compiled with `forceListEmittedFiles` so that the emitted
+ * file list is available for `resolveEmittedJavaScript`. The temp directory is
+ * always cleaned up in the `finally` block, even on error.
+ *
+ * @returns The transformed JavaScript source text.
+ * @throws When the build exits non-zero or no output is produced for the file.
+ */
 export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const sourceFile = realpathIfExists(
@@ -64,6 +73,10 @@ export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
   }
 }
 
+/**
+ * Resolve symlinks on `file` when it exists; return the original path when the
+ * file is not yet on disk (e.g. a synthetic path used in tests).
+ */
 function realpathIfExists(file: string): string {
   try {
     return fs.realpathSync(file);

package/src/compiler/internal/sharedHostHelpers.ts

@@ -4,9 +4,7 @@ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoa
  * Reports whether the given transform source is linked into another compiler
  * host instead of owning the process itself.
  */
-export function isLinkedTransform(
-  plugin: ITtscLoadedNativePlugin,
-): boolean {
+export function isLinkedTransform(plugin: ITtscLoadedNativePlugin): boolean {
   return plugin.stage === "transform" && plugin.kind === "linked";
 }
 
@@ -59,12 +57,14 @@ export function assertSharedHostCompatibility(
 export function selectSharedHostPlugin(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): ITtscLoadedNativePlugin {
-  return (
-    plugins.find((plugin) => !isLinkedTransform(plugin)) ??
-    plugins[0]!
-  );
+  return plugins.find((plugin) => !isLinkedTransform(plugin)) ?? plugins[0]!;
 }
 
+/**
+ * Return every plugin whose transform source is linked into another host binary
+ * rather than owning the process. The host binary passes these via
+ * `TTSC_LINKED_PLUGINS_JSON` so their Go code runs inside the same process.
+ */
 export function linkedTransformPlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): ITtscLoadedNativePlugin[] {