ttsc 0.12.2 → 0.12.4

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[] {

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");