ttsc 0.10.0 → 0.10.2

package/shim/checker/shim.go

@@ -1,3 +1,11 @@
+// gen_shims:hand-maintained
+//
+// This shim file mixes generated re-exports with hand-written `go:linkname`
+// declarations targeting unexported `*Checker` methods that the @ttsc/lint
+// engine relies on. gen_shims detects the marker on the first line and skips
+// this file. Remove the marker only if you are intentionally regenerating and
+// willing to re-add the hand-maintained content.
+
 package checker
 
 import (

package/src/compiler/internal/compileProjectInMemory.ts

@@ -29,7 +29,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
   const tsconfig = project.path;
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
-    cacheDir: options.cacheDir,
+    cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
     packageRoot: packageRootDir(),
   });
   const res = spawnSync(

package/src/compiler/internal/runBuild.ts

@@ -12,6 +12,7 @@ import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOpti
 import { resolveProjectConfig } from "./project/resolveProjectConfig";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
+import { assertSharedHostCompatibility } from "./sharedHostHelpers";
 
 /** Merge spawn env without clobbering unrelated vars. */
 function mergeEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -106,7 +107,7 @@ export function runBuild(
 
     if (options.emit === false) {
       if (compilers.length !== 0) {
-        assertCompilerHostCompatibility(compilers);
+        assertSharedHostCompatibility(compilers, "emit");
         return appendBuildOutput(
           checked,
           buildWithNativeCompilerPlugins(options, execution, compilers),
@@ -120,7 +121,7 @@ export function runBuild(
 
     let result: TtscBuildResult;
     if (compilers.length !== 0) {
-      assertCompilerHostCompatibility(compilers);
+      assertSharedHostCompatibility(compilers, "emit");
       result = appendBuildOutput(
         checked,
         buildWithNativeCompilerPlugins(options, execution, compilers),
@@ -394,61 +395,6 @@ export function appendBuildOutput(
   });
 }
 
-function assertCompilerHostCompatibility(
-  plugins: readonly ITtscLoadedNativePlugin[],
-): void {
-  const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
-  if (binaries.length <= 1) {
-    return;
-  }
-  if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
-    return;
-  }
-  throw new Error(
-    "ttsc: multiple compiler native backends cannot share one emit pass; " +
-      "compose transform libraries through one aggregate native 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 resolveExecutionContext(
   options: TtscCommonOptions & { tsconfig?: string },
 ) {

package/src/compiler/internal/sharedHostHelpers.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+
+/**
+ * Names of the first-party utility transform plugins that are allowed to share
+ * one compiler emit / one source-to-source pass even when their resolved
+ * binaries differ. Each entry must be both name-pinned and manifest-pinned: the
+ * plugin must declare itself with one of these names AND its source path must
+ * resolve to a `package.json` whose `name` field matches.
+ *
+ * This whitelist exists because `@ttsc/banner`, `@ttsc/paths`, and `@ttsc/strip`
+ * are AST-only mutators that operate on the same `*shimast.SourceFile` graph
+ * and do not own emit. They are composed through `packages/ttsc/utility/host.go`,
+ * so any one of their binaries can host the shared run. Third-party plugins
+ * cannot participate in this fast path; they must opt into composition through
+ * the explicit `ITtscPlugin.composes` field.
+ */
+export const FIRST_PARTY_UTILITY_PLUGIN_NAMES: ReadonlySet<string> = new Set([
+  "@ttsc/banner",
+  "@ttsc/paths",
+  "@ttsc/strip",
+]);
+
+/**
+ * Reports whether the given plugin is a first-party utility transform plugin
+ * that may participate in the shared compiler host alongside other first-party
+ * utility transforms. Returns `false` for `check`-stage plugins, for unknown
+ * names, and for plugins whose `source` does not resolve to a matching
+ * `package.json`.
+ */
+export function isFirstPartyUtilityTransformPlugin(
+  plugin: ITtscLoadedNativePlugin,
+): boolean {
+  if (plugin.stage !== "transform") return false;
+  if (!FIRST_PARTY_UTILITY_PLUGIN_NAMES.has(plugin.name)) return false;
+  const manifest = readNearestPackageManifest(plugin.source);
+  return manifest?.name === plugin.name;
+}
+
+/**
+ * Walks upward from `source` (a directory or file path) up to four parent
+ * levels searching for the nearest `package.json`. Returns the parsed manifest
+ * object on success, or `undefined` when no manifest is found or parsing
+ * fails. The depth bound mirrors the pre-existing inline implementations in
+ * `runBuild.ts` and `transformProjectInMemory.ts`.
+ */
+export 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;
+}
+
+/**
+ * Verifies that all transform plugins in `plugins` either resolve to the same
+ * native binary (the common case) or are all first-party utility plugins (the
+ * shared compiler-host fast path).
+ *
+ * Two callers exist with subtly different error wording: the build path
+ * (`runBuild.ts`) reports "multiple compiler native backends cannot share one
+ * emit pass" while the source-to-source path
+ * (`transformProjectInMemory.ts`) reports "cannot share one source-to-source
+ * pass". The `pass` argument selects the appropriate phrase so the error
+ * message remains diagnostic-grade instead of generic.
+ */
+export function assertSharedHostCompatibility(
+  plugins: readonly ITtscLoadedNativePlugin[],
+  pass: "emit" | "source-to-source",
+): void {
+  const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
+  if (binaries.length <= 1) {
+    return;
+  }
+  if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
+    return;
+  }
+  const phrase =
+    pass === "emit"
+      ? "multiple compiler native backends cannot share one emit pass"
+      : "multiple transform native backends cannot share one source-to-source pass";
+  throw new Error(
+    "ttsc: " +
+      phrase +
+      "; compose transform libraries through one aggregate native host",
+  );
+}

package/src/compiler/internal/transformProjectInMemory.ts

@@ -16,6 +16,7 @@ import { readProjectConfig } from "./project/readProjectConfig";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
 import { appendBuildOutput, normalizeBuildOutput } from "./runBuild";
+import { assertSharedHostCompatibility } from "./sharedHostHelpers";
 
 /** Transform a project and capture TypeScript source output in memory. */
 export function transformProjectInMemory(options: ITtscCompilerContext): {
@@ -50,7 +51,7 @@ function transformProjectWithNativeHost(
 } {
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
-    cacheDir: options.cacheDir,
+    cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
     packageRoot: packageRootDir(),
   });
   const res = spawnNative(
@@ -123,7 +124,7 @@ function transformProjectWithPlugins(
       typescript: transformed.typescript,
     };
   }
-  assertTransformHostCompatibility(transformers);
+  assertSharedHostCompatibility(transformers, "source-to-source");
 
   const plugin = transformers[0]!;
   const res = spawnNative(
@@ -235,61 +236,6 @@ function serializeNativePlugins(
   );
 }
 
-function assertTransformHostCompatibility(
-  plugins: readonly ITtscLoadedNativePlugin[],
-): void {
-  const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
-  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 libraries through one aggregate native 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 nativePluginEnv(
   options: ITtscCompilerContext,
   projectRoot: string,

package/src/plugin/internal/loadProjectPlugins.ts

@@ -10,6 +10,7 @@ import type { TtscPluginStage } from "../../structures/TtscPluginStage";
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import { buildSourcePlugin } from "./buildSourcePlugin";
+import { FIRST_PARTY_UTILITY_PLUGIN_NAMES } from "../../compiler/internal/sharedHostHelpers";
 
 type TtscPluginFactory<T = ITtscProjectPluginConfig> = (
   context: ITtscPluginFactoryContext<T>,
@@ -64,11 +65,14 @@ export function loadProjectPlugins(options: {
     projectRoot: project.root,
     tsconfig: project.path,
   };
-  const plugins = entries.map((entry) =>
-    loadPluginEntry(
-      entry.config,
-      { ...context, plugin: entry.config },
-      entry.baseDir,
+  const plugins = composePluginSources(
+    entries,
+    entries.map((entry) =>
+      loadPluginEntry(
+        entry.config,
+        { ...context, plugin: entry.config },
+        entry.baseDir,
+      ),
     ),
   );
 
@@ -100,6 +104,101 @@ export function loadProjectPlugins(options: {
   };
 }
 
+function composePluginSources(
+  entries: readonly ProjectPluginEntry[],
+  plugins: readonly ITtscPlugin[],
+): ITtscPlugin[] {
+  const aggregates = plugins
+    .map((plugin, index) => ({ index, plugin }))
+    .filter(({ plugin }) => Array.isArray(plugin.composes));
+  if (aggregates.length === 0) {
+    return [...plugins];
+  }
+  for (const { plugin } of aggregates) {
+    for (const target of plugin.composes!) {
+      if (typeof target !== "string" || target.trim() === "") {
+        throw new Error(
+          `ttsc: plugin "${plugin.name}" has an invalid "composes" target; ` +
+            `targets must be non-empty plugin names or transform specifiers`,
+        );
+      }
+    }
+  }
+  // First-party utility plugin names are never legal composes targets for
+  // user / third-party plugins. The first-party shared compiler host has its
+  // own opt-in path through the manifest-pinned whitelist in
+  // `sharedHostHelpers.ts::isFirstPartyUtilityTransformPlugin`. Letting any
+  // descriptor borrow the binary of `@ttsc/banner` etc. would bypass that
+  // pin and turn `composes` into a supply-chain redirect vector.
+  for (const { plugin } of aggregates) {
+    for (const target of plugin.composes!) {
+      if (FIRST_PARTY_UTILITY_PLUGIN_NAMES.has(target)) {
+        throw new Error(
+          `ttsc: plugin "${plugin.name}" cannot compose first-party utility "${target}"; ` +
+            `first-party utility plugins are composed automatically through their shared compiler host`,
+        );
+      }
+    }
+  }
+  // Composition is intentionally one hop only: A.composes=[B] sends B to A's
+  // binary, but if B.composes=[C] then C uses B's original source and does NOT
+  // cascade to A. Detect cycles (A.composes=[B] && B.composes=[A]) and throw,
+  // otherwise the silent reswap below would mis-route both plugins.
+  for (const { index: i, plugin: a } of aggregates) {
+    for (const { index: j, plugin: b } of aggregates) {
+      if (i === j) continue;
+      const aTransform = entries[i]?.config.transform;
+      const bTransform = entries[j]?.config.transform;
+      const aComposesB = a.composes!.some((alias) =>
+        matchesPluginAlias(alias, b, bTransform),
+      );
+      const bComposesA = b.composes!.some((alias) =>
+        matchesPluginAlias(alias, a, aTransform),
+      );
+      if (aComposesB && bComposesA) {
+        throw new Error(
+          `ttsc: plugin composes cycle detected between "${a.name}" and "${b.name}"; ` +
+            `each plugin lists the other in its "composes" array — composition is one hop only, not transitive`,
+        );
+      }
+    }
+  }
+  return plugins.map((plugin, index) => {
+    const transform = entries[index]?.config.transform;
+    const matchingAggregates = aggregates.filter(
+      ({ index: aggregateIndex, plugin: aggregatePlugin }) =>
+        aggregateIndex !== index &&
+        aggregatePlugin.composes!.some((alias) =>
+          matchesPluginAlias(alias, plugin, transform),
+        ),
+    );
+    if (matchingAggregates.length > 1) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" is composed by multiple aggregate plugins; ` +
+          `each plugin entry can be redirected to only one aggregate native host`,
+      );
+    }
+    const aggregate = matchingAggregates[0];
+    return aggregate === undefined
+      ? plugin
+      : {
+          ...plugin,
+          source: aggregate.plugin.source,
+        };
+  });
+}
+
+function matchesPluginAlias(
+  alias: string,
+  plugin: ITtscPlugin,
+  transform: ITtscProjectPluginConfig["transform"],
+): boolean {
+  return (
+    alias === plugin.name ||
+    (typeof transform === "string" && alias === transform)
+  );
+}
+
 export function hasProjectPluginEntries(
   project: ITtscParsedProjectConfig,
   entries?: readonly ITtscProjectPluginConfig[] | false,

package/src/structures/ITtscPlugin.ts

@@ -45,6 +45,17 @@ export interface ITtscPlugin {
    */
   source: string;
 
+  /**
+   * Other transform plugin names or transform specifiers that this native
+   * sidecar can execute in the same compiler pass.
+   *
+   * Package auto-discovery may find multiple transform packages that must share
+   * one emit host. When one descriptor lists another entry here, ttsc keeps the
+   * original plugin config in `--plugins-json` but points the composed entry at
+   * this descriptor's native source so both entries resolve to one binary.
+   */
+  composes?: string[];
+
   /**
    * Pipeline stage implemented by the sidecar.
    *

package/tools/gen_shims/main.go

@@ -429,18 +429,38 @@ func main() {
     shimHeaderBuilder.WriteString("\n")
 
     shimGoPath := path.Join(shimDirPath, "shim.go")
-    file, err := os.Create(shimGoPath)
-    if err != nil {
-      log.Fatalf("gen_shims: opening %v for write: %v", shimGoPath, err)
-    }
-    file.WriteString(shimHeaderBuilder.String())
-    file.WriteString(shimBuilder.String())
-    if err := file.Close(); err != nil {
-      log.Fatalf("gen_shims: closing %v: %v", shimGoPath, err)
+    if isHandMaintained(shimGoPath) {
+      fmt.Fprintf(os.Stderr, "gen_shims: skipping %s (hand-maintained marker present; remove '// gen_shims:hand-maintained' to regenerate)\n", shimGoPath)
+    } else {
+      file, err := os.Create(shimGoPath)
+      if err != nil {
+        log.Fatalf("gen_shims: opening %v for write: %v", shimGoPath, err)
+      }
+      file.WriteString(shimHeaderBuilder.String())
+      file.WriteString(shimBuilder.String())
+      if err := file.Close(); err != nil {
+        log.Fatalf("gen_shims: closing %v: %v", shimGoPath, err)
+      }
+      fmt.Fprintf(os.Stdout, "gen_shims: wrote %s (%d bytes)\n", shimGoPath, len(shimBuilder.String()))
     }
-    fmt.Fprintf(os.Stdout, "gen_shims: wrote %s (%d bytes)\n", shimGoPath, len(shimBuilder.String()))
 
     shimHeaderBuilder.Reset()
     shimBuilder.Reset()
   }
 }
+
+// isHandMaintained reports whether the given shim file opts out of regeneration
+// by carrying the magic marker `// gen_shims:hand-maintained` within its first
+// 200 bytes. Hand-maintained shim files combine generated re-exports with
+// `go:linkname` declarations or other content that gen_shims cannot reproduce;
+// silently overwriting them would break consumers (e.g. @ttsc/lint).
+func isHandMaintained(shimGoPath string) bool {
+  file, err := os.Open(shimGoPath)
+  if err != nil {
+    return false
+  }
+  defer file.Close()
+  buf := make([]byte, 200)
+  n, _ := file.Read(buf)
+  return strings.Contains(string(buf[:n]), "gen_shims:hand-maintained")
+}