ttsc 0.7.2 → 0.8.0-dev.20260505

package/src/launcher/internal/runTtsc.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { TtscCompiler } from "../../TtscCompiler";
 import { resolveBinary } from "../../compiler/internal/resolveBinary";
 import { runBuild } from "../../compiler/internal/runBuild";
 import { runSingleFileEmit } from "../../compiler/internal/runSingleFileEmit";
@@ -35,6 +36,8 @@ export function runTtsc(
         return runCompatibleBuild(rest, true);
       case "clean":
         return runClean(rest);
+      case "prepare":
+        return runPrepare(rest);
       case "demo":
         return delegateToNative(argv);
       case "-p":
@@ -82,13 +85,41 @@ function runCompatibleBuild(
   return result.status;
 }
 
+function runPrepare(argv: readonly string[]): number {
+  const options = parseProjectArgs(argv);
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const compiler = new TtscCompiler({
+    cacheDir: options.cacheDir,
+    cwd,
+    tsconfig: options.tsconfig,
+  });
+  const prepared = compiler.prepare();
+  if (prepared.length === 0) {
+    const projectRoot = path.dirname(
+      resolveProjectConfig({
+        cwd,
+        tsconfig: options.tsconfig,
+      }),
+    );
+    process.stdout.write(
+      `ttsc: no source plugins found under ${formatProjectPath(cwd, projectRoot)}\n`,
+    );
+    return 0;
+  }
+  for (const target of prepared) {
+    process.stdout.write(`ttsc: prepared ${formatProjectPath(cwd, target)}\n`);
+  }
+  return 0;
+}
+
 function runClean(argv: readonly string[]): number {
-  const options = parseCleanArgs(argv);
+  const options = parseProjectArgs(argv);
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const projectRoot = resolveCleanProjectRoot(cwd, options.tsconfig);
   const targets = [
     path.join(projectRoot, "node_modules", ".ttsc"),
     path.join(projectRoot, ".ttsc"),
+    ...(options.cacheDir ? [path.resolve(cwd, options.cacheDir)] : []),
     ...(process.env.TTSC_CACHE_DIR
       ? [path.resolve(process.env.TTSC_CACHE_DIR, "plugins")]
       : []),
@@ -106,7 +137,7 @@ function runClean(argv: readonly string[]): number {
     return 0;
   }
   for (const target of removed) {
-    process.stdout.write(`ttsc: removed ${formatCleanPath(cwd, target)}\n`);
+    process.stdout.write(`ttsc: removed ${formatProjectPath(cwd, target)}\n`);
   }
   return 0;
 }
@@ -120,7 +151,7 @@ function resolveCleanProjectRoot(cwd: string, tsconfig?: string): string {
   }
 }
 
-function formatCleanPath(cwd: string, target: string): string {
+function formatProjectPath(cwd: string, target: string): string {
   const relative = path.relative(cwd, target);
   if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
     return target;
@@ -174,7 +205,8 @@ function ensureExecutable(binary: string): void {
   }
 }
 
-function parseCleanArgs(argv: readonly string[]) {
+function parseProjectArgs(argv: readonly string[]) {
+  let cacheDir: string | undefined;
   let cwd: string | undefined;
   let tsconfig: string | undefined;
 
@@ -185,6 +217,9 @@ function parseCleanArgs(argv: readonly string[]) {
       case "--cwd":
         cwd = takeValue(current, rest);
         break;
+      case "--cache-dir":
+        cacheDir = takeValue(current, rest);
+        break;
       case "-p":
       case "--tsconfig":
       case "--project":
@@ -193,6 +228,8 @@ function parseCleanArgs(argv: readonly string[]) {
       default:
         if (current.startsWith("--cwd=")) {
           cwd = current.slice("--cwd=".length);
+        } else if (current.startsWith("--cache-dir=")) {
+          cacheDir = current.slice("--cache-dir=".length);
         } else if (current.startsWith("--tsconfig=")) {
           tsconfig = current.slice("--tsconfig=".length);
         } else if (current.startsWith("--project=")) {
@@ -203,11 +240,12 @@ function parseCleanArgs(argv: readonly string[]) {
         break;
     }
   }
-  return { cwd, tsconfig };
+  return { cacheDir, cwd, tsconfig };
 }
 
 function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   let binary: string | undefined;
+  let cacheDir: string | undefined;
   let cwd: string | undefined;
   let emit: boolean | undefined = checkOnly ? false : undefined;
   const files: string[] = [];
@@ -254,6 +292,9 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
       case "--binary":
         binary = takeValue(current, rest);
         break;
+      case "--cache-dir":
+        cacheDir = takeValue(current, rest);
+        break;
       default:
         if (current.startsWith("--cwd=")) {
           cwd = current.slice("--cwd=".length);
@@ -270,6 +311,8 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
             current.slice("--preserveWatchOutput=".length) !== "false";
         } else if (current.startsWith("--binary=")) {
           binary = current.slice("--binary=".length);
+        } else if (current.startsWith("--cache-dir=")) {
+          cacheDir = current.slice("--cache-dir=".length);
         } else if (current === "--verbose") {
           quiet = false;
         } else if (current.startsWith("-")) {
@@ -282,6 +325,7 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   }
   return {
     binary,
+    cacheDir,
     cwd,
     emit,
     files,
@@ -303,6 +347,7 @@ function printHelp(): void {
       "  ttsc -p tsconfig.json",
       "  ttsc --watch",
       "  ttsc --noEmit",
+      "  ttsc prepare [options]",
       "  ttsc clean [options]",
       "  ttsc version",
       "  ttsc --help",
@@ -319,6 +364,7 @@ function printHelp(): void {
       "  --quiet                Keep build output quiet (default)",
       "  --verbose              Print the build summary and emitted files",
       "  --binary <path>        Use an explicit tsgo binary",
+      "  --cache-dir <dir>      Use this cache root for source-plugin builds",
       "",
       "Plugin contract:",
       "  ttsc reads compilerOptions.plugins from tsconfig.json.",
@@ -328,6 +374,7 @@ function printHelp(): void {
       "Compatibility aliases:",
       "  ttsc build [options]       Same project build lane as `ttsc [options]`.",
       "  ttsc check [options]       Same as `ttsc --noEmit [options]`.",
+      "  ttsc prepare [options]     Build configured source-plugin binaries into cache.",
       "  ttsc clean [options]       Delete local source-plugin cache directories.",
     ].join("\n"),
   );

package/src/launcher/internal/runTtsx.ts

@@ -5,7 +5,9 @@ import * as path from "node:path";
 import { getCompilerVersionText } from "./getCompilerVersionText";
 import { prepareExecution } from "./prepareExecution";
 
-export function runTtsx(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) {
@@ -53,8 +55,10 @@ function formatError(error: unknown): string {
 function parseCLI(argv: readonly string[]) {
   const preload: string[] = [];
   const passthroughIndex = argv.indexOf("--");
-  const head = passthroughIndex === -1 ? [...argv] : [...argv.slice(0, passthroughIndex)];
-  const passthrough = passthroughIndex === -1 ? [] : [...argv.slice(passthroughIndex + 1)];
+  const head =
+    passthroughIndex === -1 ? [...argv] : [...argv.slice(0, passthroughIndex)];
+  const passthrough =
+    passthroughIndex === -1 ? [] : [...argv.slice(passthroughIndex + 1)];
 
   let binary: string | undefined;
   let cacheDir: string | undefined;
@@ -151,7 +155,11 @@ function printHelp(): void {
 }
 
 function resolvePreload(cwd: string, preload: string): string {
-  if (preload.startsWith(".") || preload.startsWith("/") || preload.includes(path.sep)) {
+  if (
+    preload.startsWith(".") ||
+    preload.startsWith("/") ||
+    preload.includes(path.sep)
+  ) {
     return path.resolve(cwd, preload);
   }
   return preload;
@@ -180,7 +188,10 @@ function runPreparedEntry(
     );
   }
   const args = [
-    ...parsed.preload.flatMap((preload) => ["-r", resolvePreload(cwd, preload)]),
+    ...parsed.preload.flatMap((preload) => [
+      "-r",
+      resolvePreload(cwd, preload),
+    ]),
     execution.entryFile,
     ...parsed.passthrough,
   ];

package/src/plugin/internal/buildSourcePlugin.ts

@@ -155,7 +155,9 @@ function writeGoWork(scratchDir: string, useDirs: readonly string[]): void {
   fs.writeFileSync(path.join(scratchDir, "go.work"), goWork, "utf8");
 }
 
-function sourceBuildWorkspaceReplacements(useDirs: readonly string[]): string[] {
+function sourceBuildWorkspaceReplacements(
+  useDirs: readonly string[],
+): string[] {
   const ttscRoot = useDirs.find((dir) =>
     hasModulePath(dir, "github.com/samchon/ttsc/packages/ttsc"),
   );
@@ -308,7 +310,10 @@ function walkForGoMod(dir: string, out: string[]): void {
   }
 }
 
-function resolvePluginCacheRoot(projectRoot: string, cacheDir?: string): string {
+function resolvePluginCacheRoot(
+  projectRoot: string,
+  cacheDir?: string,
+): string {
   if (cacheDir) {
     return path.resolve(cacheDir, "plugins");
   }
@@ -343,6 +348,20 @@ function resolveGoCompiler(): string {
     /* fall through */
   }
 
+  const platformPackage = path.resolve(
+    __dirname,
+    "..",
+    "..",
+    "..",
+    "..",
+    `ttsc-${process.platform}-${process.arch}`,
+    "bin",
+    "go",
+    "bin",
+    process.platform === "win32" ? "go.exe" : "go",
+  );
+  if (fs.existsSync(platformPackage)) return platformPackage;
+
   const local = path.resolve(
     __dirname,
     "..",
@@ -356,6 +375,15 @@ function resolveGoCompiler(): string {
   );
   if (fs.existsSync(local)) return local;
 
+  const homeSdk = path.join(
+    process.env.HOME ?? "",
+    "go-sdk",
+    "go",
+    "bin",
+    process.platform === "win32" ? "go.exe" : "go",
+  );
+  if (fs.existsSync(homeSdk)) return homeSdk;
+
   return "go";
 }
 

package/src/plugin/internal/loadProjectPlugins.ts

@@ -58,7 +58,9 @@ export function loadProjectPlugins(options: {
   const ttscVersion = readTtscVersion();
   const tsgoVersion = readTsgoVersion(context.projectRoot);
   plugins.forEach((plugin, index) => {
+    const stage = resolvePluginStage(plugin);
     validatePluginSource(plugin);
+    validatePluginHooks(plugin, stage);
     const binary = buildSourcePlugin({
       baseDir: context.projectRoot,
       cacheDir: options.cacheDir,
@@ -70,8 +72,10 @@ export function loadProjectPlugins(options: {
     nativePlugins.push({
       binary,
       config: entries[index]!,
+      hooks: plugin.hooks,
       name: plugin.name,
-      stage: resolvePluginStage(plugin),
+      source: plugin.source,
+      stage,
     });
   });
   return {
@@ -88,6 +92,7 @@ function loadPluginEntry(
   if (typeof specifier !== "string" || specifier.length === 0) {
     throw new Error(`ttsc: plugin entry is missing a string "transform" field`);
   }
+  rejectUserPhaseOptions(specifier, entry);
 
   const request = resolvePluginRequest(specifier, context.projectRoot);
   const mod = require(request) as {
@@ -135,11 +140,37 @@ function rejectJsTransformHooks(specifier: string, candidate: object): void {
   }
 }
 
+function rejectUserPhaseOptions(
+  specifier: string,
+  entry: ITtscProjectPluginConfig,
+): void {
+  for (const key of [
+    "after",
+    "afterDeclarations",
+    "before",
+    "phase",
+    "source:after",
+  ]) {
+    if (key in entry) {
+      throw new Error(
+        `ttsc: plugin entry for "${specifier}" uses unsupported ts-patch option ${JSON.stringify(key)}; ` +
+          "ttsc plugins declare source/declaration hooks in the package descriptor, not in user tsconfig",
+      );
+    }
+  }
+}
+
 function resolvePluginStage(plugin: ITtscPlugin): TtscPluginStage {
   if (plugin.stage === undefined) {
     return "transform";
   }
   if (!isPluginStage(plugin.stage)) {
+    if (plugin.stage === "output") {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" requested removed stage "output"; ` +
+          "upgrade the plugin to a transform hook descriptor compatible with this ttsc version",
+      );
+    }
     throw new Error(
       `ttsc: plugin "${plugin.name}" requested unsupported stage ${JSON.stringify(plugin.stage)}`,
     );
@@ -153,8 +184,56 @@ function validatePluginSource(plugin: ITtscPlugin): void {
   }
 }
 
+function validatePluginHooks(
+  plugin: ITtscPlugin,
+  stage: TtscPluginStage,
+): void {
+  const hooks = plugin.hooks;
+  if (hooks !== undefined && typeof hooks !== "object") {
+    throw new Error(`ttsc: plugin "${plugin.name}" hooks must be an object`);
+  }
+  if (stage === "check") {
+    if (hooks !== undefined && Object.keys(hooks).length !== 0) {
+      throw new Error(
+        `ttsc: check plugin "${plugin.name}" must not declare transform hooks`,
+      );
+    }
+    return;
+  }
+  if (hooks === undefined) {
+    throw new Error(
+      `ttsc: transform plugin "${plugin.name}" must declare source/declaration hooks in its package descriptor`,
+    );
+  }
+  for (const key of Object.keys(hooks)) {
+    if (key !== "source" && key !== "declaration") {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" requested unsupported hook ${JSON.stringify(key)}`,
+      );
+    }
+  }
+  if (hooks.source !== undefined && typeof hooks.source !== "boolean") {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" hooks.source must be boolean`,
+    );
+  }
+  if (
+    hooks.declaration !== undefined &&
+    typeof hooks.declaration !== "boolean"
+  ) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" hooks.declaration must be boolean`,
+    );
+  }
+  if (hooks.source !== true && hooks.declaration !== true) {
+    throw new Error(
+      `ttsc: transform plugin "${plugin.name}" must enable at least one source/declaration hook`,
+    );
+  }
+}
+
 function isPluginStage(value: string): value is TtscPluginStage {
-  return value === "transform" || value === "check" || value === "output";
+  return value === "transform" || value === "check";
 }
 
 function resolvePluginRequest(specifier: string, projectRoot: string): string {

package/src/structures/ITtscPlugin.ts

@@ -1,5 +1,20 @@
 import type { TtscPluginStage } from "./TtscPluginStage";
 
+export interface ITtscPluginHooks {
+  /**
+   * Runs against TypeScript SourceFile AST before TypeScript-Go's built-in emit
+   * transforms. The Program/checker are created from the original source before
+   * this hook participates in emit.
+   */
+  source?: boolean;
+
+  /**
+   * Runs against declaration AST before declaration printing. This is a
+   * plugin-package capability, never a user-facing tsconfig phase option.
+   */
+  declaration?: boolean;
+}
+
 /**
  * Runtime descriptor returned by a ttsc plugin module.
  *
@@ -48,11 +63,23 @@ export interface ITtscPlugin {
   /**
    * Pipeline stage implemented by the sidecar.
    *
-   * Omit this field for normal compiler-transform plugins. Explicit stages are
-   * intended for tools that only validate (`"check"`) or rewrite already
-   * emitted files (`"output"`).
+   * Omit this field for normal compiler-transform plugins. The only explicit
+   * non-transform stage is `"check"`.
    *
    * @default "transform"
    */
   stage?: TtscPluginStage;
+
+  /** Native transform hook capabilities implemented by the plugin package. */
+  hooks?: ITtscPluginHooks;
+}
+
+export function defineTtscPlugin<T extends ITtscPlugin>(plugin: T): T;
+export function defineTtscPlugin<TContext, T extends ITtscPlugin>(
+  factory: (context: TContext) => T,
+): (context: TContext) => T;
+export function defineTtscPlugin(
+  value: ITtscPlugin | ((context: unknown) => ITtscPlugin),
+): ITtscPlugin | ((context: unknown) => ITtscPlugin) {
+  return value;
 }

package/src/structures/TtscPluginStage.ts

@@ -1,18 +1,12 @@
 /**
  * Pipeline stage where a plugin's lazily built Go sidecar participates.
  *
- * - `"transform"`: owns the TypeScript transform/emit pass. This is the
- *   default and is the right stage for compiler-transform plugins such as
- *   typia-style source rewrites. During compilation, a transform sidecar
- *   produces the project's emitted output. During
- *   {@link TtscCompiler.transform}, the same sidecar may expose a
- *   source-to-source `transform` command that returns transformed TypeScript
+ * - `"transform"`: participates in the TypeScript-Go transform path. Transform
+ *   plugins declare their source/declaration hook capabilities in the plugin
+ *   package descriptor and do not receive emitted JavaScript or emitted file
  *   text.
  * - `"check"`: runs before emit and reports diagnostics only. Use this for
  *   lint or validation plugins that should fail the compile before JavaScript
  *   or declaration output is generated.
- * - `"output"`: runs after emit for each emitted output file. Use this for
- *   post-processing plugins such as banner insertion, import-path rewriting,
- *   or output stripping that operate on `.js`, `.d.ts`, or map files.
  */
-export type TtscPluginStage = "transform" | "check" | "output";
+export type TtscPluginStage = "transform" | "check";

package/src/structures/internal/ITtscLoadedNativePlugin.ts

@@ -1,4 +1,5 @@
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
+import type { ITtscPluginHooks } from "../ITtscPlugin";
 import type { TtscPluginStage } from "../TtscPluginStage";
 
 /** Native sidecar selected and built from one plugin descriptor. */
@@ -9,6 +10,10 @@ export interface ITtscLoadedNativePlugin {
   config: ITtscProjectPluginConfig;
   /** Stable plugin name used in diagnostics and native manifests. */
   name: string;
+  /** Go source directory selected by the plugin descriptor. */
+  source: string;
   /** Pipeline stage where the sidecar participates. */
   stage: TtscPluginStage;
+  /** Native transform hook capabilities declared by the plugin package. */
+  hooks?: ITtscPluginHooks;
 }

package/test/compiler.test.ts

@@ -274,7 +274,7 @@ function createProject(options = {}) {
 function writeSourcePlugin(root) {
   fs.writeFileSync(
     path.join(root, "plugin.cjs"),
-    'module.exports = { name: "prepare-fixture", source: "./plugin-go" };\n',
+    'module.exports = { name: "prepare-fixture", source: "./plugin-go", hooks: { source: true } };\n',
     "utf8",
   );
   fs.mkdirSync(path.join(root, "plugin-go"), { recursive: true });
@@ -293,7 +293,7 @@ function writeSourcePlugin(root) {
 function writeBrokenTransformPlugin(root) {
   fs.writeFileSync(
     path.join(root, "plugin.cjs"),
-    'module.exports = { name: "broken-transform-fixture", source: "./plugin-go" };\n',
+    'module.exports = { name: "broken-transform-fixture", source: "./plugin-go", hooks: { source: true } };\n',
     "utf8",
   );
   fs.mkdirSync(path.join(root, "plugin-go"), { recursive: true });
@@ -327,7 +327,7 @@ function writeBrokenTransformPlugin(root) {
 function writeCompilerPlugin(root) {
   fs.writeFileSync(
     path.join(root, "plugin.cjs"),
-    'module.exports = { name: "compile-fixture", source: "./plugin-go" };\n',
+    'module.exports = { name: "compile-fixture", source: "./plugin-go", hooks: { source: true } };\n',
     "utf8",
   );
   fs.mkdirSync(path.join(root, "plugin-go"), { recursive: true });

package/test/platform.test.ts

@@ -1,8 +1,6 @@
 const assert = require("node:assert/strict");
 const test = require("node:test");
-const {
-  resolveBinary,
-} = require("../lib/compiler/internal/resolveBinary.js");
+const { resolveBinary } = require("../lib/compiler/internal/resolveBinary.js");
 
 test("resolveBinary prefers TTSC_BINARY absolute override", () => {
   const resolved = resolveBinary({

package/test/tsgo.test.ts

@@ -20,12 +20,17 @@ test("resolveTsgo accepts TTSC_TSGO_BINARY as an explicit compiler", () => {
 
 test("resolveTsgo resolves the consumer native-preview platform package", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-tsgo-test-"));
-  const nativeRoot = path.join(root, "node_modules", "@typescript", "native-preview");
+  const nativeRoot = path.join(
+    root,
+    "node_modules",
+    "@typescript",
+    "native-preview",
+  );
   const platformRoot = path.join(
     root,
     "node_modules",
     "@typescript",
-    "native-preview-linux-x64",
+    `native-preview-${process.platform}-${process.arch}`,
   );
   fs.mkdirSync(nativeRoot, { recursive: true });
   fs.mkdirSync(path.join(platformRoot, "lib"), { recursive: true });
@@ -41,21 +46,24 @@ test("resolveTsgo resolves the consumer native-preview platform package", () =>
   fs.writeFileSync(
     path.join(platformRoot, "package.json"),
     JSON.stringify({
-      name: "@typescript/native-preview-linux-x64",
+      name: `@typescript/native-preview-${process.platform}-${process.arch}`,
       version: "7.0.0-dev.consumer",
     }),
     "utf8",
   );
-  fs.writeFileSync(path.join(platformRoot, "lib", "tsgo"), "", "utf8");
+  const binary = path.join(
+    platformRoot,
+    "lib",
+    process.platform === "win32" ? "tsgo.exe" : "tsgo",
+  );
+  fs.writeFileSync(binary, "", "utf8");
 
   const resolved = resolveTsgo({
-    arch: "x64",
     cwd: root,
     env: {},
-    platform: "linux",
   });
 
   assert.equal(resolved.version, "7.0.0-dev.consumer");
   assert.equal(resolved.gitHead, "abc123");
-  assert.equal(resolved.binary, path.join(platformRoot, "lib", "tsgo"));
+  assert.equal(resolved.binary, binary);
 });