ttsc 0.12.2 → 0.12.4

package/src/compiler/internal/compileProjectInMemory.ts

@@ -9,12 +9,22 @@ import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiag
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import { buildNativeCompiler } from "./buildNativeCompiler";
+import { isOutsideRelativePath, packageRootDir } from "./paths";
 import { readProjectConfig } from "./project/readProjectConfig";
 import { runBuild } from "./runBuild";
 
 /**
  * Compile a project and capture emitted files without writing to the project
  * tree.
+ *
+ * When no plugins are configured the fast path spawns the native ttsc compiler
+ * host (`cmd/ttsc api-compile`) which returns a structured JSON response
+ * containing diagnostics and an output file map. When plugins are present the
+ * slow path goes through `runBuild` into a temp directory and reads the files
+ * back from disk.
+ *
+ * @returns A map of output path → file content plus a `TtscBuildResult` with
+ *   diagnostics and the exit status.
  */
 export function compileProjectInMemory(options: ITtscCompilerContext): {
   output: Record<string, string>;
@@ -64,6 +74,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
   };
 }
 
+/** Return true when the project or the call-level options declare any plugins. */
 function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -71,6 +82,10 @@ function hasConfiguredPlugins(
   return hasProjectPluginEntries(project, options.plugins);
 }
 
+/**
+ * Plugin-backed compilation: emit into a temp directory via `runBuild`, then
+ * read back every file the build wrote so they can be returned as strings.
+ */
 function compileProjectWithPlugins(
   options: ITtscCompilerContext,
   cwd: string,
@@ -101,6 +116,15 @@ function compileProjectWithPlugins(
   }
 }
 
+/**
+ * Build a function that maps a path relative to the temp output directory to
+ * the key used in the returned `output` map.
+ *
+ * When `outDir` is inside the project root the key is relative to the project
+ * root (preserving the `outDir` prefix). When `outDir` is outside the project
+ * root the key is absolute-style (`/absolute/outDir/relative`). When `outDir`
+ * is absent the key is the bare relative path.
+ */
 function outputKeyMapper(
   project: ITtscParsedProjectConfig,
 ): (relativePath: string) => string {
@@ -116,14 +140,7 @@ function outputKeyMapper(
   return (relativePath) => pathToKey(path.join(outDir, relativePath));
 }
 
-function isOutsideRelativePath(relative: string): boolean {
-  return (
-    relative === ".." ||
-    relative.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(relative)
-  );
-}
-
+/** Read every file in `directory` recursively and return a `path→content` map. */
 function readOutputDirectory(
   directory: string,
   keyOf: (relativePath: string) => string,
@@ -141,6 +158,7 @@ function readOutputDirectory(
   return output;
 }
 
+/** Recursively list all files under `directory`, sorted for stable output. */
 function listFiles(directory: string): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
@@ -154,10 +172,18 @@ function listFiles(directory: string): string[] {
   return out.sort();
 }
 
+/** Normalise a file path to a forward-slash key suitable for the output map. */
 function pathToKey(file: string): string {
   return file.replace(/\\/g, "/");
 }
 
+/**
+ * Parse the JSON envelope written by the native compiler host to stdout.
+ *
+ * On success returns `{ diagnostics, output }`. On JSON parse failure throws a
+ * descriptive error using stderr (preferred) or stdout as context, so callers
+ * see the original compiler error rather than a generic JSON parse message.
+ */
 function parseNativeCompileOutput(
   stdout: string,
   stderr: string,
@@ -181,20 +207,3 @@ function parseNativeCompileOutput(
     );
   }
 }
-
-function packageRootDir(): string {
-  let current = path.resolve(__dirname);
-  while (true) {
-    if (
-      fs.existsSync(path.join(current, "package.json")) &&
-      fs.existsSync(path.join(current, "go.mod"))
-    ) {
-      return fs.realpathSync.native?.(current) ?? fs.realpathSync(current);
-    }
-    const parent = path.dirname(current);
-    if (parent === current) {
-      throw new Error("ttsc: package root not found for native compiler build");
-    }
-    current = parent;
-  }
-}

package/src/compiler/internal/paths.ts

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Walk up the directory tree from `__dirname` until a directory that contains
+ * both `package.json` and `go.mod` is found. This is the `packages/ttsc` root
+ * and must be passed to `buildNativeCompiler` so it can locate `cmd/ttsc`.
+ *
+ * Uses `fs.realpathSync.native` when available to resolve symlinks identically
+ * to the Go toolchain's own path resolution.
+ *
+ * Throws when the root cannot be found (i.e. the package is not in a Go
+ * workspace), which would indicate a broken installation.
+ */
+export function packageRootDir(): string {
+  let current = path.resolve(__dirname);
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, "package.json")) &&
+      fs.existsSync(path.join(current, "go.mod"))
+    ) {
+      return fs.realpathSync.native?.(current) ?? fs.realpathSync(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error("ttsc: package root not found for native compiler build");
+    }
+    current = parent;
+  }
+}
+
+/**
+ * Walk up the directory tree from `from` looking for a `go.mod` file. Stops
+ * after `maxDepth` hops so callers can bound the search to a known
+ * neighbourhood of the plugin source directory.
+ *
+ * Returns the absolute path to the first `go.mod` found, or `null` when no
+ * `go.mod` exists within the depth limit or filesystem root is reached first.
+ */
+export function findNearestGoMod(
+  from: string,
+  maxDepth: number,
+): string | null {
+  let current = path.resolve(from);
+  let depth = 0;
+  while (true) {
+    const candidate = path.join(current, "go.mod");
+    if (fs.existsSync(candidate)) return candidate;
+    if (depth >= maxDepth) return null;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+    depth += 1;
+  }
+}
+
+/**
+ * Return `true` when a relative path escapes its base directory — i.e. starts
+ * with `..` or is an absolute path. Used by callers that need to guard against
+ * path traversal before building output keys or spawning subprocesses.
+ */
+export function isOutsideRelativePath(relative: string): boolean {
+  return (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  );
+}

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

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

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