ttsc 0.3.1 → 0.4.0-dev.20260425

package/src/cli.ts

@@ -0,0 +1,492 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  type BuildOptions,
+  type TransformOptions,
+  build,
+  check,
+  transform,
+  version,
+} from "./api";
+import { installHint, resolveBinary } from "./platform";
+import { resolveProjectConfig, resolveProjectRoot } from "./project";
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+  try {
+    if (argv.length === 0) {
+      return runCompatibleBuild([], false);
+    }
+
+    const [command, ...rest] = argv as [string, ...string[]];
+    switch (command) {
+      case "-h":
+      case "--help":
+      case "help":
+        printHelp();
+        return 0;
+      case "-v":
+      case "--version":
+      case "version":
+        process.stdout.write(`${version()}\n`);
+        return 0;
+      case "build":
+        return runCompatibleBuild(rest, false);
+      case "check":
+        return runCompatibleBuild(rest, true);
+      case "transform":
+        return runTransform(rest);
+      case "demo":
+        return delegateToNative(argv);
+      case "-p":
+      case "--project":
+        return runCompatibleBuild(argv, false);
+      default:
+        if (isBuildAlias(command)) {
+          return runCompatibleBuild(argv, false);
+        }
+        process.stderr.write(
+          `ttsc: unknown command ${JSON.stringify(command)}\n`,
+        );
+        process.stderr.write(
+          `ttsc: run "ttsc --help" to see supported commands\n`,
+        );
+        return 2;
+    }
+  } catch (error) {
+    process.stderr.write(`${formatError(error)}\n`);
+    return 2;
+  }
+}
+
+function isBuildAlias(command: string): boolean {
+  if (command.startsWith("-")) return true;
+  return [".json", ".ts", ".tsx", ".mts", ".cts"].some((ext) =>
+    command.endsWith(ext),
+  );
+}
+
+interface BuildInvocation extends BuildOptions {
+  files: string[];
+  preserveWatchOutput: boolean;
+  watch: boolean;
+}
+
+function runCompatibleBuild(
+  argv: readonly string[],
+  checkOnly: boolean,
+): number {
+  const options = parseBuildArgs(argv, checkOnly);
+  if (options.watch) {
+    return runWatch(options, checkOnly);
+  }
+  if (options.files.length !== 0) {
+    return runSingleFile(options);
+  }
+  const result = checkOnly ? check(options) : build(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 {
+  const options = parseTransformArgs(argv);
+  const text = transform(options);
+  if (!options.out) {
+    process.stdout.write(text);
+  }
+  return 0;
+}
+
+function delegateToNative(argv: readonly string[]): number {
+  const bin = resolveBinary();
+  if (!bin) {
+    process.stderr.write(`${installHint()}\n`);
+    return 1;
+  }
+  const viaNode = /\.(?:[cm]?js|ts)$/i.test(bin);
+  const result = spawnSync(
+    viaNode ? process.execPath : bin,
+    viaNode ? [bin, ...argv] : [...argv],
+    {
+      stdio: "inherit",
+      env: process.env,
+      windowsHide: true,
+    },
+  );
+  if (result.error) {
+    process.stderr.write(`${result.error.message}\n`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+function parseBuildArgs(
+  argv: readonly string[],
+  checkOnly: boolean,
+): BuildInvocation {
+  let binary: string | undefined;
+  let cwd: string | undefined;
+  let emit: boolean | undefined = checkOnly ? false : undefined;
+  const files: string[] = [];
+  let outDir: string | undefined;
+  let preserveWatchOutput = false;
+  let quiet = true;
+  let rewriteMode: string | undefined;
+  let tsconfig: string | undefined;
+  let watch = false;
+
+  const rest = [...argv];
+  while (rest.length !== 0) {
+    const current = rest.shift()!;
+    switch (current) {
+      case "--emit":
+        emit = true;
+        break;
+      case "--noEmit":
+        emit = false;
+        break;
+      case "--quiet":
+        quiet = true;
+        break;
+      case "--verbose":
+        quiet = false;
+        break;
+      case "-w":
+      case "--watch":
+        watch = true;
+        break;
+      case "--preserveWatchOutput":
+        preserveWatchOutput = true;
+        break;
+      case "--rewrite-mode":
+        rewriteMode = takeRewriteMode(takeValue(current, rest));
+        break;
+      case "--cwd":
+        cwd = takeValue(current, rest);
+        break;
+      case "--outDir":
+        outDir = takeValue(current, rest);
+        break;
+      case "-p":
+      case "--tsconfig":
+      case "--project":
+        tsconfig = takeValue(current, rest);
+        break;
+      case "--binary":
+        binary = takeValue(current, rest);
+        break;
+      default:
+        if (current.startsWith("--cwd=")) {
+          cwd = current.slice("--cwd=".length);
+        } else if (current.startsWith("--outDir=")) {
+          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=")) {
+          tsconfig = current.slice("--project=".length);
+        } else if (current.startsWith("--preserveWatchOutput=")) {
+          preserveWatchOutput =
+            current.slice("--preserveWatchOutput=".length) !== "false";
+        } else if (current.startsWith("--binary=")) {
+          binary = current.slice("--binary=".length);
+        } else if (current === "--verbose") {
+          quiet = false;
+        } else if (current.startsWith("-")) {
+          throw new Error(`ttsc: unknown option ${current}`);
+        } else {
+          files.push(current);
+        }
+        break;
+    }
+  }
+  return {
+    binary,
+    cwd,
+    emit,
+    files,
+    outDir,
+    preserveWatchOutput,
+    quiet,
+    rewriteMode,
+    tsconfig,
+    watch,
+  };
+}
+
+function parseTransformArgs(argv: readonly string[]): TransformOptions {
+  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];
+  while (rest.length !== 0) {
+    const current = rest.shift()!;
+    switch (current) {
+      case "--binary":
+        binary = takeValue(current, rest);
+        break;
+      case "--cwd":
+        cwd = takeValue(current, rest);
+        break;
+      case "--file":
+        file = takeValue(current, rest);
+        break;
+      case "--out":
+        out = takeValue(current, rest);
+        break;
+      case "--rewrite-mode":
+        rewriteMode = takeRewriteMode(takeValue(current, rest));
+        break;
+      case "--tsconfig":
+      case "--project":
+        tsconfig = takeValue(current, rest);
+        break;
+      default:
+        if (current.startsWith("--binary=")) {
+          binary = current.slice("--binary=".length);
+        } else if (current.startsWith("--cwd=")) {
+          cwd = current.slice("--cwd=".length);
+        } else if (current.startsWith("--file=")) {
+          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=")) {
+          tsconfig = current.slice("--project=".length);
+        } else {
+          throw new Error(`ttsc: unknown option ${current}`);
+        }
+        break;
+    }
+  }
+  if (!file) {
+    throw new Error("ttsc: transform requires --file");
+  }
+  return {
+    binary,
+    cwd,
+    file,
+    out,
+    rewriteMode,
+    tsconfig,
+  };
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      "ttsc — standalone compiler adapter and plugin host for tsgo.",
+      "",
+      "Usage:",
+      "  ttsc",
+      "  ttsc -p tsconfig.json",
+      "  ttsc --watch",
+      "  ttsc --noEmit",
+      "  ttsc transform --file <path> [options]",
+      "  ttsc version",
+      "  ttsc --help",
+      "",
+      "Options:",
+      "  -p, --project <file>   Resolve project settings from this tsconfig",
+      "  --tsconfig <file>      Resolve project settings from this tsconfig",
+      "  --cwd <dir>            Resolve project-relative paths from this directory",
+      "  --emit                 Force emitted files during build",
+      "  --noEmit               Force analysis-only build with no file writes",
+      "  -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>  Native rewrite backend id",
+      "  --quiet                Keep native build output quiet (default)",
+      "  --verbose              Print the native build summary and emitted files",
+      "  --out <path>           Write transform output to a file instead of stdout",
+      "  --binary <path>        Use an explicit native backend binary",
+      "",
+      "Plugin contract:",
+      "  ttsc reads compilerOptions.plugins from tsconfig.json.",
+      "  TS plugins may export `definePlugin(...)` from ttsc.",
+      "  Native consumer plugins may also provide their own binary path.",
+      "",
+      "Compatibility aliases:",
+      "  ttsc build [options]       Same project build lane as `ttsc [options]`.",
+      "  ttsc check [options]       Same as `ttsc --noEmit [options]`.",
+    ].join("\n"),
+  );
+  process.stdout.write("\n");
+}
+
+function runSingleFile(options: BuildInvocation): number {
+  if (options.files.length !== 1) {
+    throw new Error(
+      "ttsc: single-file mode currently accepts exactly one input file",
+    );
+  }
+  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({
+    binary: options.binary,
+    cwd,
+    file,
+    out,
+    rewriteMode: options.rewriteMode,
+    tsconfig: options.tsconfig,
+  });
+  if (!fs.existsSync(out)) {
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, text, "utf8");
+  }
+  process.stdout.write(`${path.relative(cwd, out) || path.basename(out)}\n`);
+  return 0;
+}
+
+function resolveSingleFileOut(
+  file: string,
+  cwd: string,
+  outDir?: string,
+): string {
+  const relative = path.relative(cwd, file);
+  const jsRelative = relative.replace(/\.[cm]?tsx?$/i, ".js");
+  if (outDir) {
+    return path.resolve(cwd, outDir, jsRelative);
+  }
+  return file.replace(/\.[cm]?tsx?$/i, ".js");
+}
+
+function runWatch(options: BuildInvocation, checkOnly: boolean): number {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const invocation: BuildInvocation = {
+    ...options,
+    cwd,
+    quiet: true,
+  };
+  const root = path.dirname(
+    resolveProjectConfig({
+      cwd,
+      tsconfig: options.tsconfig,
+    }),
+  );
+  const watchRoot = resolveProjectRoot({
+    cwd,
+    tsconfig: options.tsconfig,
+  });
+  const directories = collectWatchDirectories(watchRoot);
+  const watchers = directories.map((dir) =>
+    fs.watch(dir, { persistent: true }, () => trigger()),
+  );
+  let running = false;
+  let rerun = false;
+  let timer: NodeJS.Timeout | null = null;
+
+  const runOnce = () => {
+    running = true;
+    if (!options.preserveWatchOutput) {
+      process.stdout.write("\x1bc");
+    }
+    process.stdout.write(
+      `[ttsc] rebuilding at ${new Date().toLocaleTimeString()}\n`,
+    );
+    const status =
+      invocation.files.length !== 0
+        ? runSingleFile(invocation)
+        : (() => {
+            const result = checkOnly ? check(invocation) : build(invocation);
+            if (result.stdout) process.stdout.write(result.stdout);
+            if (result.stderr) process.stderr.write(result.stderr);
+            return result.status;
+          })();
+    process.stdout.write(
+      `[ttsc] ${status === 0 ? "watch build complete" : "watch build failed"}\n`,
+    );
+    running = false;
+    if (rerun) {
+      rerun = false;
+      trigger();
+    }
+  };
+  const trigger = () => {
+    if (running) {
+      rerun = true;
+      return;
+    }
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(runOnce, 60);
+  };
+
+  const close = () => {
+    if (timer) clearTimeout(timer);
+    for (const watcher of watchers) watcher.close();
+  };
+  process.on("SIGINT", () => {
+    close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    close();
+    process.exit(0);
+  });
+
+  process.stdout.write(`[ttsc] watching ${path.relative(cwd, root) || "."}\n`);
+  runOnce();
+  return 0;
+}
+
+function collectWatchDirectories(root: string): string[] {
+  const out: string[] = [];
+  const stack: string[] = [root];
+  while (stack.length !== 0) {
+    const current = stack.pop()!;
+    out.push(current);
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (
+        entry.name === "node_modules" ||
+        entry.name === ".git" ||
+        entry.name === "lib" ||
+        entry.name === "dist"
+      ) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        stack.push(path.join(current, entry.name));
+      }
+    }
+  }
+  return out;
+}
+
+function takeValue(flag: string, rest: string[]): string {
+  const value = rest.shift();
+  if (!value) {
+    throw new Error(`ttsc: ${flag} requires a value`);
+  }
+  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;
+  }
+  return String(error);
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * ttsc — public TypeScript entry.
+ *
+ * Exports:
+ *   - platform helpers (`resolveBinary`, `installHint`, …) — used by the
+ *     public launcher and any external tool that wants to know where
+ *     the native binary lives without spawning it.
+ *   - programmatic API (`transform`, `build`, `check`, `version`) — a thin
+ *     TS wrapper around the Go binary that bundler adapters (unplugin, vite,
+ *     webpack, rollup, esbuild, rspack, farm) delegate to. Adapters never
+ *     have to shell out themselves; they call these helpers and get back
+ *     a string or a result record.
+ */
+
+export * from "./platform";
+export * from "./api";
+export * from "./project";
+export * from "./plugin";
+export * from "./runner/register";

package/src/launcher/ttsc-dev.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const root = fs.realpathSync.native?.(__dirname) ?? fs.realpathSync(__dirname);
+const packageRoot = path.resolve(root, "..", "..");
+const command = process.platform === "win32" ? "go.exe" : "go";
+const invocationCwd = process.cwd();
+const argv = [...process.argv.slice(2)];
+
+if (needsInvocationCwd(argv) && !argv.some((value) => value === "--cwd" || value.startsWith("--cwd="))) {
+  argv.push(`--cwd=${invocationCwd}`);
+}
+
+const result = spawnSync(command, ["run", "./cmd/ttsc", ...argv], {
+  cwd: packageRoot,
+  env: process.env,
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+if (result.error) {
+  process.stderr.write(`ttsc: failed to launch source checkout via ${command}: ${result.error.message}\n`);
+  process.exitCode = 1;
+} else {
+  process.exitCode = result.status ?? 1;
+}
+
+function needsInvocationCwd(args) {
+  if (args.length === 0) return true;
+  const commandName = args[0];
+  return (
+    commandName === "build" ||
+    commandName === "check" ||
+    commandName === "transform" ||
+    commandName === "-p" ||
+    commandName === "--project"
+  );
+}

package/src/launcher/ttsc.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const builtCli = path.resolve(__dirname, "..", "..", "lib", "cli.js");
+if (fs.existsSync(builtCli)) {
+  const { main } = require(builtCli);
+  const code = main(process.argv.slice(2));
+  if (typeof code === "number") {
+    process.exitCode = code;
+  }
+} else {
+  process.stderr.write(
+    "ttsc: lib/cli.js is missing. Build ttsc first with `pnpm run build`.\n",
+  );
+  process.exitCode = 1;
+}

package/src/launcher/ttsx.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const builtCli = path.resolve(__dirname, "..", "..", "lib", "runner", "cli.js");
+if (fs.existsSync(builtCli)) {
+  const { main } = require(builtCli);
+  const code = main(process.argv.slice(2));
+  if (typeof code === "number") {
+    process.exitCode = code;
+  }
+} else {
+  process.stderr.write(
+    "ttsx: lib/runner/cli.js is missing. Build ttsc first with `pnpm run build`.\n",
+  );
+  process.exitCode = 1;
+}

package/src/native.ts

@@ -0,0 +1,60 @@
+export type NativeRewriteMode = string;
+export type NativePluginContractVersion = 1;
+
+export interface TtscNativeBackend {
+  mode: NativeRewriteMode;
+  binary?: string;
+  contractVersion?: NativePluginContractVersion;
+  capabilities?: readonly string[];
+}
+
+export interface TtscNativePluginShape {
+  name: string;
+  native?: TtscNativeBackend;
+  nativeMode?: NativeRewriteMode;
+  nativeBinary?: string;
+}
+
+export function resolveNativeBackend(
+  plugin: TtscNativePluginShape,
+): TtscNativeBackend | null {
+  if (plugin.native && (plugin.nativeMode || plugin.nativeBinary)) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" must use either native or nativeMode/nativeBinary, not both`,
+    );
+  }
+  if (!plugin.native) {
+    if (
+      plugin.nativeBinary &&
+      (!plugin.nativeMode || plugin.nativeMode === "none")
+    ) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" declared nativeBinary without a non-empty nativeMode`,
+      );
+    }
+    if (!plugin.nativeMode || plugin.nativeMode === "none") {
+      return null;
+    }
+    return {
+      binary: plugin.nativeBinary,
+      contractVersion: 1,
+      mode: plugin.nativeMode,
+    };
+  }
+
+  const backend = plugin.native;
+  if (!backend.mode || backend.mode === "none") {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" declared native without a non-empty mode`,
+    );
+  }
+  if (backend.contractVersion !== undefined && backend.contractVersion !== 1) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" requested unsupported native contract version ${backend.contractVersion}`,
+    );
+  }
+  return {
+    ...backend,
+    contractVersion: backend.contractVersion ?? 1,
+  };
+}