ttsc 0.12.3 → 0.13.0

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 {
@@ -13,6 +25,26 @@ export function resolveProjectConfig(
     if (!fs.existsSync(resolved)) {
       throw new Error(`ttsc: tsconfig not found: ${resolved}`);
     }
+    // `-p <directory>` is the documented tsgo shorthand for the
+    // directory that contains a `tsconfig.json`. Mirror that — without
+    // this branch a forwarded `--tsconfig=sub` would feed the directory
+    // path into `readResolvedCompilerOptions`, which calls
+    // `fs.readFileSync` and throws `EISDIR` (the RCA's predicted
+    // RC-3 §5 #2 bug, pinned by
+    // `test_ttsc_dash_p_directory_path_is_accepted`).
+    if (isDirectory(resolved)) {
+      const tsconfigInDir = path.join(resolved, "tsconfig.json");
+      if (fs.existsSync(tsconfigInDir)) {
+        return resolveRealPath(tsconfigInDir);
+      }
+      const jsconfigInDir = path.join(resolved, "jsconfig.json");
+      if (fs.existsSync(jsconfigInDir)) {
+        return resolveRealPath(jsconfigInDir);
+      }
+      throw new Error(
+        `ttsc: directory has no tsconfig.json / jsconfig.json: ${resolved}`,
+      );
+    }
     return resolveRealPath(resolved);
   }
 
@@ -29,10 +61,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 +78,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 +100,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>;
 }