ttsc 0.6.0 → 0.7.0

package/src/index.ts

@@ -1,20 +1,11 @@
 /**
  * ttsc — public TypeScript entry.
  *
- * Exports:
- *   - tsgo helpers (`resolveTsgo`, …) — resolve the consuming project's
- *     `@typescript/native-preview` compiler binary.
- *   - platform helpers (`resolveBinary`, `installHint`, …) — compatibility
- *     helper resolution for commands such as `ttsc demo`.
- *   - programmatic API (`transform`, `build`, `check`, `version`) — a thin
- *     TS wrapper around the consumer `tsgo` binary and native plugin
- *     descriptors. Adapters never have to shell out themselves; they call
- *     these helpers and get back a string or a result record.
+ * The package root intentionally exposes only the programmatic compiler class
+ * and the plugin-author contracts. CLI launcher functions, binary resolution,
+ * project parsing helpers, and native build helpers stay internal so the
+ * public package surface remains small and stable.
  */
 
-export * from "./platform";
-export * from "./api";
-export * from "./project";
-export * from "./plugin";
-export * from "./tsgo";
-export * from "./runner/register";
+export * from "./TtscCompiler";
+export * from "./structures/index";

package/src/launcher/internal/getCompilerVersionText.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
+import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+
+/** Format the CLI version banner from the wrapper package and resolved tsgo. */
+export function getCompilerVersionText(
+  options: TtscCommonOptions = {},
+): string {
+  const tsgo = resolveTsgo(options);
+  const res = spawnSync(tsgo.binary, ["--version"], {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024 * 16,
+    windowsHide: true,
+  });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      "ttsc.version: failed: " +
+        (outputText(res.stderr) || res.error?.message),
+    );
+  }
+  return `ttsc ${readOwnPackageVersion()} (${outputText(res.stdout).trim()})`;
+}
+
+function outputText(value: string | Buffer | null | undefined): string {
+  if (value == null) {
+    return "";
+  }
+  return typeof value === "string" ? value : value.toString("utf8");
+}
+
+function readOwnPackageVersion(): string {
+  try {
+    const file = path.resolve(__dirname, "..", "..", "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(file, "utf8")) as {
+      version?: string;
+    };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/launcher/internal/prepareExecution.ts

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { resolveEmittedJavaScript } from "../../compiler/internal/resolveEmittedJavaScript";
+import { runBuild } from "../../compiler/internal/runBuild";
+import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
+import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+
+const PROCESS_CACHE_KEY = String(process.pid);
+
+/** Build the owning project and locate the emitted JavaScript entry for `ttsx`. */
+export function prepareExecution(
+  entryFile: string,
+  options: TtscCommonOptions & {
+    cacheDir?: string;
+    project?: string;
+  } = {},
+): {
+  emitDir: string;
+  entryFile: string;
+  moduleKind: "cjs" | "esm";
+} {
+  const context = createProjectContext(
+    path.resolve(options.cwd ?? process.cwd()),
+    entryFile,
+    options,
+  );
+  buildProject(context, options);
+  const emittedEntry = resolveEmittedJavaScript({
+    emittedFiles: context.emittedFiles ?? undefined,
+    outDir: context.emitDir,
+    projectRoot: context.root,
+    sourceFile: entryFile,
+  });
+  if (emittedEntry === null) {
+    throw new Error(`ttsx: emitted entry not found for ${entryFile}`);
+  }
+  const output = fs.readFileSync(emittedEntry, "utf8");
+  return {
+    emitDir: context.emitDir,
+    entryFile: emittedEntry,
+    moduleKind: looksLikeESM(output) ? "esm" : "cjs",
+  };
+}
+
+function createProjectContext(
+  cwd: string,
+  filename: string,
+  options: NonNullable<Parameters<typeof prepareExecution>[1]>,
+) {
+  const tsconfig = options.project
+    ? resolveProjectConfig({ cwd, tsconfig: path.resolve(cwd, options.project) })
+    : resolveProjectConfig({ cwd, file: filename });
+  const root = path.dirname(tsconfig);
+  const cacheDir =
+    options.cacheDir ?? path.join(root, "node_modules", ".cache", "ttsc", "ttsx");
+  return {
+    tsconfig,
+    root,
+    cacheDir,
+    emitDir: path.join(cacheDir, "project", PROCESS_CACHE_KEY),
+    built: false,
+    emittedFiles: undefined as string[] | undefined,
+  };
+}
+
+function buildProject(
+  context: ReturnType<typeof createProjectContext>,
+  options: NonNullable<Parameters<typeof prepareExecution>[1]>,
+): void {
+  if (context.built) return;
+
+  fs.mkdirSync(context.cacheDir, { recursive: true });
+  fs.rmSync(context.emitDir, { recursive: true, force: true });
+  const result = runBuild({
+    binary: options.binary,
+    cwd: context.root,
+    emit: true,
+    env: options.env,
+    forceListEmittedFiles: true,
+    outDir: context.emitDir,
+    plugins: options.plugins,
+    quiet: true,
+    tsconfig: context.tsconfig,
+  });
+  if (result.status === 0) {
+    context.built = true;
+    context.emittedFiles =
+      result.emittedFiles && result.emittedFiles.length !== 0
+        ? result.emittedFiles
+        : undefined;
+    return;
+  }
+
+  fs.rmSync(context.emitDir, { recursive: true, force: true });
+  const detail = [
+    `ttsx: project check failed for ${context.tsconfig}`,
+    result.stderr || result.stdout,
+  ]
+    .filter((line) => line.trim().length !== 0)
+    .join("\n");
+  throw new Error(detail);
+}
+
+function looksLikeESM(output: string): boolean {
+  if (
+    /\bObject\.defineProperty\(exports\b/.test(output) ||
+    /\bmodule\.exports\b/.test(output) ||
+    /\brequire\(/.test(output) ||
+    /\bexports\./.test(output)
+  ) {
+    return false;
+  }
+  return /^\s*(import|export)\s/m.test(output);
+}

package/src/{cli.ts → launcher/internal/runTtsc.ts}

@@ -2,19 +2,15 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import {
-  type ITtscBuildOptions,
-  type ITtscTransformOptions,
-  build,
-  check,
-  transform,
-  version,
-} from "./api";
-import { installHint, resolveBinary } from "./platform";
-import { resolveProjectConfig, resolveProjectRoot } from "./project";
-import { pluginCacheCleanupTargets } from "./source-build";
+import { resolveBinary } from "../../compiler/internal/resolveBinary";
+import { runBuild } from "../../compiler/internal/runBuild";
+import { runTransform } from "../../compiler/internal/runTransform";
+import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
+import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
+import type { TtscTransformOptions } from "../../structures/internal/TtscTransformOptions";
+import { getCompilerVersionText } from "./getCompilerVersionText";
 
-export function main(argv: readonly string[] = process.argv.slice(2)): number {
+export function runTtsc(argv: readonly string[] = process.argv.slice(2)): number {
   try {
     if (argv.length === 0) {
       return runCompatibleBuild([], false);
@@ -30,7 +26,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
       case "-v":
       case "--version":
       case "version":
-        process.stdout.write(`${version()}\n`);
+        process.stdout.write(`${getCompilerVersionText()}\n`);
         return 0;
       case "build":
         return runCompatibleBuild(rest, false);
@@ -39,7 +35,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
       case "clean":
         return runClean(rest);
       case "transform":
-        return runTransform(rest);
+        return runTransformCommand(rest);
       case "demo":
         return delegateToNative(argv);
       case "-p":
@@ -70,12 +66,6 @@ function isBuildAlias(command: string): boolean {
   );
 }
 
-interface ITtscBuildInvocation extends ITtscBuildOptions {
-  files: string[];
-  preserveWatchOutput: boolean;
-  watch: boolean;
-}
-
 function runCompatibleBuild(
   argv: readonly string[],
   checkOnly: boolean,
@@ -87,31 +77,32 @@ function runCompatibleBuild(
   if (options.files.length !== 0) {
     return runSingleFile(options);
   }
-  const result = checkOnly ? check(options) : build(options);
+  const result = runBuild(checkOnly ? { ...options, emit: false } : options);
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   return result.status;
 }
 
-function runTransform(argv: readonly string[]): number {
+function runTransformCommand(argv: readonly string[]): number {
   const options = parseTransformArgs(argv);
-  const text = transform(options);
+  const text = runTransform(options);
   if (!options.out) {
     process.stdout.write(text);
   }
   return 0;
 }
 
-interface ITtscCleanInvocation {
-  cwd?: string;
-  tsconfig?: string;
-}
-
 function runClean(argv: readonly string[]): number {
   const options = parseCleanArgs(argv);
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const projectRoot = resolveCleanProjectRoot(cwd, options.tsconfig);
-  const targets = pluginCacheCleanupTargets(projectRoot);
+  const targets = [
+    path.join(projectRoot, "node_modules", ".ttsc"),
+    path.join(projectRoot, ".ttsc"),
+    ...(process.env.TTSC_CACHE_DIR
+      ? [path.resolve(process.env.TTSC_CACHE_DIR, "plugins")]
+      : []),
+  ];
   const removed: string[] = [];
   for (const target of targets) {
     if (!fs.existsSync(target)) continue;
@@ -119,7 +110,9 @@ function runClean(argv: readonly string[]): number {
     removed.push(target);
   }
   if (removed.length === 0) {
-    process.stdout.write(`ttsc: no cache directories found under ${projectRoot}\n`);
+    process.stdout.write(
+      `ttsc: no cache directories found under ${projectRoot}\n`,
+    );
     return 0;
   }
   for (const target of removed) {
@@ -148,10 +141,18 @@ function formatCleanPath(cwd: string, target: string): string {
 function delegateToNative(argv: readonly string[]): number {
   const bin = resolveBinary();
   if (!bin) {
-    process.stderr.write(`${installHint()}\n`);
+    process.stderr.write(
+      [
+        `ttsc: platform-specific helper binary not found (@ttsc/${process.platform}-${process.arch}).`,
+        `Set TTSC_BINARY to an absolute helper path or reinstall with optional dependencies enabled.`,
+      ].join("\n") + "\n",
+    );
     return 1;
   }
   const viaNode = /\.(?:[cm]?js|ts)$/i.test(bin);
+  if (!viaNode) {
+    ensureExecutable(bin);
+  }
   const result = spawnSync(
     viaNode ? process.execPath : bin,
     viaNode ? [bin, ...argv] : [...argv],
@@ -168,7 +169,22 @@ function delegateToNative(argv: readonly string[]): number {
   return result.status ?? 1;
 }
 
-function parseCleanArgs(argv: readonly string[]): ITtscCleanInvocation {
+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 parseCleanArgs(argv: readonly string[]) {
   let cwd: string | undefined;
   let tsconfig: string | undefined;
 
@@ -203,7 +219,7 @@ function parseCleanArgs(argv: readonly string[]): ITtscCleanInvocation {
 function parseBuildArgs(
   argv: readonly string[],
   checkOnly: boolean,
-): ITtscBuildInvocation {
+) {
   let binary: string | undefined;
   let cwd: string | undefined;
   let emit: boolean | undefined = checkOnly ? false : undefined;
@@ -211,7 +227,6 @@ function parseBuildArgs(
   let outDir: string | undefined;
   let preserveWatchOutput = false;
   let quiet = true;
-  let rewriteMode: string | undefined;
   let tsconfig: string | undefined;
   let watch = false;
 
@@ -238,9 +253,6 @@ function parseBuildArgs(
       case "--preserveWatchOutput":
         preserveWatchOutput = true;
         break;
-      case "--rewrite-mode":
-        rewriteMode = takeRewriteMode(takeValue(current, rest));
-        break;
       case "--cwd":
         cwd = takeValue(current, rest);
         break;
@@ -262,10 +274,6 @@ function parseBuildArgs(
           outDir = current.slice("--outDir=".length);
         } else if (current === "-w") {
           watch = true;
-        } else if (current.startsWith("--rewrite-mode=")) {
-          rewriteMode = takeRewriteMode(
-            current.slice("--rewrite-mode=".length),
-          );
         } else if (current.startsWith("--tsconfig=")) {
           tsconfig = current.slice("--tsconfig=".length);
         } else if (current.startsWith("--project=")) {
@@ -293,18 +301,16 @@ function parseBuildArgs(
     outDir,
     preserveWatchOutput,
     quiet,
-    rewriteMode,
     tsconfig,
     watch,
   };
 }
 
-function parseTransformArgs(argv: readonly string[]): ITtscTransformOptions {
+function parseTransformArgs(argv: readonly string[]): TtscTransformOptions {
   let binary: string | undefined;
   let cwd: string | undefined;
   let file: string | undefined;
   let out: string | undefined;
-  let rewriteMode: string | undefined;
   let tsconfig: string | undefined;
 
   const rest = [...argv];
@@ -323,9 +329,6 @@ function parseTransformArgs(argv: readonly string[]): ITtscTransformOptions {
       case "--out":
         out = takeValue(current, rest);
         break;
-      case "--rewrite-mode":
-        rewriteMode = takeRewriteMode(takeValue(current, rest));
-        break;
       case "--tsconfig":
       case "--project":
         tsconfig = takeValue(current, rest);
@@ -339,10 +342,6 @@ function parseTransformArgs(argv: readonly string[]): ITtscTransformOptions {
           file = current.slice("--file=".length);
         } else if (current.startsWith("--out=")) {
           out = current.slice("--out=".length);
-        } else if (current.startsWith("--rewrite-mode=")) {
-          rewriteMode = takeRewriteMode(
-            current.slice("--rewrite-mode=".length),
-          );
         } else if (current.startsWith("--tsconfig=")) {
           tsconfig = current.slice("--tsconfig=".length);
         } else if (current.startsWith("--project=")) {
@@ -361,7 +360,6 @@ function parseTransformArgs(argv: readonly string[]): ITtscTransformOptions {
     cwd,
     file,
     out,
-    rewriteMode,
     tsconfig,
   };
 }
@@ -390,7 +388,6 @@ function printHelp(): void {
       "  -w, --watch            Rebuild when project files change",
       "  --preserveWatchOutput  Do not clear the screen between watch rebuilds",
       "  --outDir <dir>         Override compilerOptions.outDir for this invocation",
-      "  --rewrite-mode <mode>  Plugin-selected native rewrite backend id",
       "  --quiet                Keep build output quiet (default)",
       "  --verbose              Print the build summary and emitted files",
       "  --out <path>           Write transform output to a file instead of stdout",
@@ -410,7 +407,7 @@ function printHelp(): void {
   process.stdout.write("\n");
 }
 
-function runSingleFile(options: ITtscBuildInvocation): number {
+function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   if (options.files.length !== 1) {
     throw new Error(
       "ttsc: single-file mode currently accepts exactly one input file",
@@ -419,12 +416,11 @@ function runSingleFile(options: ITtscBuildInvocation): 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 text = transform({
+  const text = runTransform({
     binary: options.binary,
     cwd,
     file,
     out,
-    rewriteMode: options.rewriteMode,
     tsconfig: options.tsconfig,
   });
   if (!fs.existsSync(out)) {
@@ -448,9 +444,12 @@ function resolveSingleFileOut(
   return file.replace(/\.[cm]?tsx?$/i, ".js");
 }
 
-function runWatch(options: ITtscBuildInvocation, checkOnly: boolean): number {
+function runWatch(
+  options: ReturnType<typeof parseBuildArgs>,
+  checkOnly: boolean,
+): number {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  const invocation: ITtscBuildInvocation = {
+  const invocation = {
     ...options,
     cwd,
     quiet: true,
@@ -461,10 +460,7 @@ function runWatch(options: ITtscBuildInvocation, checkOnly: boolean): number {
       tsconfig: options.tsconfig,
     }),
   );
-  const watchRoot = resolveProjectRoot({
-    cwd,
-    tsconfig: options.tsconfig,
-  });
+  const watchRoot = root;
   const directories = collectWatchDirectories(watchRoot);
   const watchers = directories.map((dir) =>
     fs.watch(dir, { persistent: true }, () => trigger()),
@@ -485,7 +481,9 @@ function runWatch(options: ITtscBuildInvocation, checkOnly: boolean): number {
       invocation.files.length !== 0
         ? runSingleFile(invocation)
         : (() => {
-            const result = checkOnly ? check(invocation) : build(invocation);
+            const result = runBuild(
+              checkOnly ? { ...invocation, emit: false } : invocation,
+            );
             if (result.stdout) process.stdout.write(result.stdout);
             if (result.stderr) process.stderr.write(result.stderr);
             return result.status;
@@ -557,13 +555,6 @@ function takeValue(flag: string, rest: string[]): string {
   return value;
 }
 
-function takeRewriteMode(value: string): string {
-  if (value.length === 0) {
-    throw new Error("ttsc: rewrite mode must not be empty");
-  }
-  return value;
-}
-
 function formatError(error: unknown): string {
   if (error instanceof Error) {
     return error.message;

package/src/{runner/cli.ts → launcher/internal/runTtsx.ts}

@@ -1,23 +1,11 @@
 import * as fs from "node:fs";
-import Module = require("node:module");
 import { spawnSync } from "node:child_process";
 import * as path from "node:path";
 
-import { version } from "../api";
-import {
-  prepareExecution,
-  register,
-  type ITtscPreparedExecution,
-  type ITtscRegisterOptions,
-} from "./register";
+import { getCompilerVersionText } from "./getCompilerVersionText";
+import { prepareExecution } from "./prepareExecution";
 
-interface ITtscParsedCLI extends ITtscRegisterOptions {
-  entry: string;
-  passthrough: string[];
-  preload: string[];
-}
-
-export function main(argv: readonly string[] = process.argv.slice(2)): number {
+export function runTtsx(argv: readonly string[] = process.argv.slice(2)): number {
   try {
     return run(argv);
   } catch (error) {
@@ -33,7 +21,9 @@ function run(argv: readonly string[]): number {
     return 0;
   }
   if (parsed === "version") {
-    process.stdout.write(`${version().replace(/^ttsc\b/, "ttsx")}\n`);
+    process.stdout.write(
+      `${getCompilerVersionText().replace(/^ttsc\b/, "ttsx")}\n`,
+    );
     return 0;
   }
 
@@ -48,29 +38,9 @@ function run(argv: readonly string[]): number {
     binary: parsed.binary,
     cacheDir: parsed.cacheDir,
     cwd,
-    env: parsed.env,
-    extensions: parsed.extensions,
     project: parsed.project,
   });
-  if (prepared.moduleKind === "esm") {
-    return runEsmEntry(parsed, prepared, cwd);
-  }
-
-  const unregister = register({
-    binary: parsed.binary,
-    cacheDir: parsed.cacheDir,
-    cwd,
-    env: parsed.env,
-    extensions: parsed.extensions,
-    project: parsed.project,
-  });
-  process.once("exit", unregister);
-  for (const preload of parsed.preload) {
-    require(resolvePreload(cwd, preload));
-  }
-  process.argv = [process.execPath, entry, ...parsed.passthrough];
-  Module.runMain();
-  return 0;
+  return runPreparedEntry(parsed, prepared, cwd);
 }
 
 function formatError(error: unknown): string {
@@ -80,7 +50,7 @@ function formatError(error: unknown): string {
   return String(error);
 }
 
-function parseCLI(argv: readonly string[]): ITtscParsedCLI | "help" | "version" {
+function parseCLI(argv: readonly string[]) {
   const preload: string[] = [];
   const passthroughIndex = argv.indexOf("--");
   const head = passthroughIndex === -1 ? [...argv] : [...argv.slice(0, passthroughIndex)];
@@ -172,10 +142,6 @@ function printHelp(): void {
       "  -h, --help             Show this help",
       "  -v, --version          Print the runner version",
       "",
-      "Runtime:",
-      "  CommonJS projects execute in-process via the require hook.",
-      "  ESM projects execute the cached emitted entry in a child Node process.",
-      "",
       "Examples:",
       "  ttsx src/index.ts",
       "  ttsx --project tsconfig.json src/index.ts -- --port 3000",
@@ -199,14 +165,20 @@ function takeValue(flag: string, rest: string[]): string {
   return value;
 }
 
-function runEsmEntry(parsed: ITtscParsedCLI, execution: ITtscPreparedExecution, cwd: string): number {
+function runPreparedEntry(
+  parsed: Exclude<ReturnType<typeof parseCLI>, "help" | "version">,
+  execution: ReturnType<typeof prepareExecution>,
+  cwd: string,
+): number {
   fs.mkdirSync(execution.emitDir, { recursive: true });
-  rewriteEsmSpecifiers(execution.emitDir);
-  fs.writeFileSync(
-    path.join(execution.emitDir, "package.json"),
-    JSON.stringify({ type: "module" }),
-    "utf8",
-  );
+  if (execution.moduleKind === "esm") {
+    rewriteEsmSpecifiers(execution.emitDir);
+    fs.writeFileSync(
+      path.join(execution.emitDir, "package.json"),
+      JSON.stringify({ type: "module" }),
+      "utf8",
+    );
+  }
   const args = [
     ...parsed.preload.flatMap((preload) => ["-r", resolvePreload(cwd, preload)]),
     execution.entryFile,

package/src/launcher/ttsc.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import { main } from "../cli";
+import { runTtsc } from "./internal/runTtsc";
 
-const code = main(process.argv.slice(2));
+const code = runTtsc(process.argv.slice(2));
 if (typeof code === "number") {
   process.exitCode = code;
 }

package/src/launcher/ttsx.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import { main } from "../runner/cli";
+import { runTtsx } from "./internal/runTtsx";
 
-const code = main(process.argv.slice(2));
+const code = runTtsx(process.argv.slice(2));
 if (typeof code === "number") {
   process.exitCode = code;
 }