ttsc 0.7.3 → 0.8.0-dev.20260505

package/src/compiler/internal/transformProjectInMemory.ts

@@ -118,7 +118,7 @@ function transformProjectWithPlugins(
   if (transformers.length === 0) {
     return transformProjectWithNativeHost(options, project);
   }
-  assertSingleTransformHost(transformers);
+  assertTransformHostCompatibility(transformers);
 
   const plugin = transformers[0]!;
   const res = spawnNative(
@@ -218,21 +218,66 @@ function serializeNativePlugins(
   return JSON.stringify(
     plugins.map((plugin) => ({
       config: plugin.config,
+      hooks: plugin.hooks,
       name: plugin.name,
       stage: plugin.stage,
     })),
   );
 }
 
-function assertSingleTransformHost(
+function assertTransformHostCompatibility(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): void {
   const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
-  if (binaries.length > 1) {
-    throw new Error(
-      "ttsc: multiple transform native backends cannot share one source-to-source pass",
-    );
+  if (binaries.length <= 1) {
+    return;
+  }
+  if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
+    return;
+  }
+  throw new Error(
+    "ttsc: multiple transform native backends cannot share one source-to-source pass; " +
+      "compose transform hook libraries through one aggregate host",
+  );
+}
+
+function isFirstPartyUtilityTransformPlugin(
+  plugin: ITtscLoadedNativePlugin,
+): boolean {
+  if (plugin.stage !== "transform") return false;
+  if (!firstPartyUtilityPluginNames.has(plugin.name)) return false;
+  const manifest = readNearestPackageManifest(plugin.source);
+  return manifest?.name === plugin.name;
+}
+
+const firstPartyUtilityPluginNames = new Set([
+  "@ttsc/banner",
+  "@ttsc/paths",
+  "@ttsc/strip",
+]);
+
+function readNearestPackageManifest(
+  source: string,
+): { name?: unknown } | undefined {
+  try {
+    let current = fs.statSync(source).isDirectory()
+      ? source
+      : path.dirname(source);
+    for (let i = 0; i < 4; i += 1) {
+      const manifest = path.join(current, "package.json");
+      if (fs.existsSync(manifest)) {
+        return JSON.parse(fs.readFileSync(manifest, "utf8")) as {
+          name?: unknown;
+        };
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  } catch {
+    return undefined;
   }
+  return undefined;
 }
 
 function appendBuildResult(

package/src/launcher/internal/runTtsc.ts

@@ -89,6 +89,7 @@ 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,
   });
@@ -118,6 +119,7 @@ function runClean(argv: readonly string[]): number {
   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")]
       : []),
@@ -204,6 +206,7 @@ function ensureExecutable(binary: string): void {
 }
 
 function parseProjectArgs(argv: readonly string[]) {
+  let cacheDir: string | undefined;
   let cwd: string | undefined;
   let tsconfig: string | undefined;
 
@@ -214,6 +217,9 @@ function parseProjectArgs(argv: readonly string[]) {
       case "--cwd":
         cwd = takeValue(current, rest);
         break;
+      case "--cache-dir":
+        cacheDir = takeValue(current, rest);
+        break;
       case "-p":
       case "--tsconfig":
       case "--project":
@@ -222,6 +228,8 @@ function parseProjectArgs(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=")) {
@@ -232,11 +240,12 @@ function parseProjectArgs(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[] = [];
@@ -283,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);
@@ -299,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("-")) {
@@ -311,6 +325,7 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   }
   return {
     binary,
+    cacheDir,
     cwd,
     emit,
     files,
@@ -349,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.",

package/src/plugin/internal/buildSourcePlugin.ts

@@ -348,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,
     "..",
@@ -361,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/tsgo.test.ts

@@ -30,7 +30,7 @@ test("resolveTsgo resolves the consumer native-preview platform package", () =>
     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 });
@@ -46,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);
 });