ttsc 0.10.2 → 0.11.0-dev.20260517

package/src/plugin/internal/buildSourcePlugin.ts

@@ -12,12 +12,43 @@ const TSGO_GO_MODULE_PATH = "github.com/microsoft/typescript-go";
 const PRUNE_DIRS = new Set(["node_modules", ".git", ".ttsc"]);
 const GENERATED_WORKSPACE_FILES = new Set(["go.work", "go.work.sum"]);
 
+// Go env vars that change the produced binary. Hashed into the plugin
+// build cache key so cross-compile target / build tags / cgo toggle
+// don't collide with the native-platform key.
+const GO_BUILD_ENV_KEYS: readonly string[] = [
+  "GOOS",
+  "GOARCH",
+  "GOAMD64",
+  "GOARM",
+  "GO386",
+  "GOMIPS",
+  "GOMIPS64",
+  "GOPPC64",
+  "GORISCV64",
+  "GOWASM",
+  "GOFLAGS",
+  "GOEXPERIMENT",
+  "CGO_ENABLED",
+  "GOTOOLCHAIN",
+];
+const CONTRIBUTIONS_FILE_NAME = "ttsc_contributions.go";
+const CONTRIB_DIRNAME = "contrib";
+
+/** One contributor's resolved Go source plus its target sub-package name. */
+export interface ITtscBuildContributor {
+  /** Sub-package suffix: scratch lands at `<host>/contrib/<name>/`. */
+  name: string;
+  /** Absolute path to the contributor's source directory. */
+  source: string;
+}
+
 /** Build one Go source plugin into a cached executable. */
 export function buildSourcePlugin(opts: {
   source: string;
   pluginName: string;
   baseDir: string;
   cacheDir?: string;
+  contributors?: readonly ITtscBuildContributor[];
   label?: string;
   overlayDirs?: readonly string[];
   quiet?: boolean;
@@ -26,9 +57,11 @@ export function buildSourcePlugin(opts: {
 }): string {
   const { dir, entry, source } = resolveSourceBuildTarget(opts);
   const overlayDirs = opts.overlayDirs ?? findTtscOverlayDirs();
+  const contributors = opts.contributors ?? [];
   const goBinary = resolveGoCompiler();
   ensureExecutableGoToolchain(goBinary);
   const key = computeCacheKey({
+    contributors,
     dir,
     entry,
     goBinary,
@@ -46,8 +79,14 @@ export function buildSourcePlugin(opts: {
   fs.mkdirSync(cacheDir, { recursive: true });
   const label = opts.label ?? "source plugin";
   if (opts.quiet !== true) {
+    const extra =
+      contributors.length === 0
+        ? ""
+        : ` + ${contributors.length} contributor(s): ${contributors
+            .map((c) => c.name)
+            .join(", ")}`;
     process.stderr.write(
-      `ttsc: building ${label} "${opts.pluginName}" from ${source} (this runs once per cache key)\n`,
+      `ttsc: building ${label} "${opts.pluginName}" from ${source}${extra} (this runs once per cache key)\n`,
     );
   }
 
@@ -56,6 +95,16 @@ export function buildSourcePlugin(opts: {
   );
   try {
     materializeScratchDir(dir, scratchDir);
+    const goModReader = createGoModReader(goBinary, opts.pluginName);
+    if (contributors.length > 0) {
+      mergeContributors({
+        contributors,
+        entry,
+        goModReader,
+        pluginName: opts.pluginName,
+        scratchDir,
+      });
+    }
     writeGoWork(scratchDir, overlayDirs, goBinary, opts.pluginName);
     const scratchBinaryName =
       process.platform === "win32" ? ".ttsc-plugin.exe" : ".ttsc-plugin";
@@ -68,6 +117,128 @@ export function buildSourcePlugin(opts: {
   }
 }
 
+/**
+ * Copy every contributor's Go source into a sub-package of the host module and
+ * synthesize a blank-import file alongside the host's entry package so each
+ * contributor's `init()` runs before `main`.
+ *
+ * - Sources land at `<scratch>/<CONTRIB_DIRNAME>/<name>/` (recursive copy with
+ *   the same pruning rules used for the host source).
+ * - The entry directory receives `<CONTRIBUTIONS_FILE_NAME>` containing one
+ *   blank-import per contributor. The host's module path is read from the
+ *   materialized go.mod, so the import path is always correct for the host
+ *   plugin's actual module declaration.
+ * - Contributors that ship their own `go.mod` are rejected — the design relies on
+ *   the contributor living inside the host's module so that workspace overlay
+ *   rules and the host's `go.sum` cover transitive dependencies. This also
+ *   closes the supply-chain hole where a contributor could otherwise pull in
+ *   arbitrary Go modules.
+ */
+function mergeContributors(opts: {
+  contributors: readonly ITtscBuildContributor[];
+  entry: string;
+  goModReader: GoModReader;
+  pluginName: string;
+  scratchDir: string;
+}): void {
+  const hostModulePath = opts.goModReader.read(opts.scratchDir).modulePath;
+  if (hostModulePath === null || hostModulePath === "") {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" cannot accept contributors because its module ` +
+        `root has no resolvable go.mod module path`,
+    );
+  }
+  const contribRoot = path.join(opts.scratchDir, CONTRIB_DIRNAME);
+  // Refuse to merge when the host plugin's own source already owns a
+  // `contrib/` directory. We'd otherwise silently merge contributor
+  // files into a pre-populated host package and ship a hybrid binary
+  // whose contents nobody declared. Loud failure is the only safe
+  // option — the host plugin must rename its directory or the
+  // contributor system must use a different sub-package root.
+  if (fs.existsSync(contribRoot)) {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" already ships a ${CONTRIB_DIRNAME}/ directory in its source; ` +
+        `contributor merge would silently overwrite. Rename the host plugin's directory to a different name.`,
+    );
+  }
+  fs.mkdirSync(contribRoot, { recursive: true });
+  // Sort contributors by name so the synthesized `ttsc_contributions.go`
+  // emits blank imports in a deterministic order independent of
+  // declaration order. The cache key is already sort-stable
+  // (`computeCacheKey` sorts contributors by name), so without this
+  // matching sort the SAME cache key could correspond to two distinct
+  // binaries whose `init()` sequence across contributors differs by
+  // import order.
+  const sortedContributors = [...opts.contributors].sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+  const imports: string[] = [];
+  for (const contributor of sortedContributors) {
+    if (fs.existsSync(path.join(contributor.source, "go.mod"))) {
+      throw new Error(
+        `ttsc: plugin "${opts.pluginName}" contributor "${contributor.name}" must ship Go ` +
+          `source as a package, not a module (go.mod found at ${contributor.source}/go.mod). ` +
+          `Remove go.mod so the contributor compiles inside the host module's dependency graph.`,
+      );
+    }
+    const target = path.join(contribRoot, contributor.name);
+    if (fs.existsSync(target)) {
+      // Defensive: validatePluginContributors already rejects duplicate
+      // names, and the contribRoot-existence guard above blocks the
+      // host plugin from pre-shipping a `contrib/` directory. Reaching
+      // this branch implies an upstream contract break. Fail loud
+      // rather than overwrite.
+      throw new Error(
+        `ttsc: plugin "${opts.pluginName}" contributor "${contributor.name}" target ${target} already exists; ` +
+          `contributor names must be unique within one plugin build`,
+      );
+    }
+    fs.cpSync(contributor.source, target, {
+      recursive: true,
+      filter: (src) => {
+        const base = path.basename(src);
+        if (shouldPruneDirectory(base)) return false;
+        if (shouldOmitSourceFile(base)) return false;
+        return true;
+      },
+    });
+    imports.push(`${hostModulePath}/${CONTRIB_DIRNAME}/${contributor.name}`);
+  }
+  const entryDir = path.resolve(opts.scratchDir, opts.entry);
+  fs.mkdirSync(entryDir, { recursive: true });
+  const contributionsPath = path.join(entryDir, CONTRIBUTIONS_FILE_NAME);
+  // Same reasoning as the contribRoot guard: when entry resolves to the
+  // module root (`entry === "."`), entryDir == scratchDir and a
+  // pre-existing `ttsc_contributions.go` from the host plugin's own
+  // source would be silently overwritten by the generator below.
+  if (fs.existsSync(contributionsPath)) {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" already ships ${CONTRIBUTIONS_FILE_NAME} in its entry package; ` +
+        `that filename is reserved for the contributor blank-import generator. Rename the host's file.`,
+    );
+  }
+  writeContributionsFile(contributionsPath, imports);
+}
+
+function writeContributionsFile(filePath: string, imports: string[]): void {
+  const importLines = imports
+    .map((spec) => `\t_ ${JSON.stringify(spec)}`)
+    .join("\n");
+  const body = `// Code generated by ttsc — DO NOT EDIT.
+//
+// This file is synthesized by ttsc's plugin builder when the host plugin
+// descriptor declares "contributors". The blank imports below pull each
+// contributor sub-package into the build so its init() runs before main.
+
+package main
+
+import (
+${importLines}
+)
+`;
+  fs.writeFileSync(filePath, body, "utf8");
+}
+
 function publishBuiltBinary(builtBinary: string, binaryPath: string): void {
   const pending = `${binaryPath}.${process.pid}.${Date.now()}-${Math.random()
     .toString(16)
@@ -88,6 +259,30 @@ function publishBuiltBinary(builtBinary: string, binaryPath: string): void {
       return;
     }
     throw error;
+  } finally {
+    // Best-effort sweep of any leftover `.tmp` siblings from a prior
+    // crash between copyFileSync and renameSync. Same-directory pending
+    // names guarantee the rename stays a same-filesystem atomic op, so
+    // we accept the GC cost rather than move pending files to os.tmpdir.
+    pruneOrphanPendingBinaries(binaryPath);
+  }
+}
+
+function pruneOrphanPendingBinaries(binaryPath: string): void {
+  // Only sweep pending files owned by THIS process. Concurrent ttsc
+  // invocations (two `ttsc --watch` shells against the same project)
+  // may have their own `<binary>.<their-pid>.*.tmp` mid-flight, and
+  // deleting them would race their renameSync into ENOENT.
+  try {
+    const dir = path.dirname(binaryPath);
+    const prefix = `${path.basename(binaryPath)}.${process.pid}.`;
+    for (const name of fs.readdirSync(dir)) {
+      if (name.startsWith(prefix) && name.endsWith(".tmp")) {
+        fs.rmSync(path.join(dir, name), { force: true });
+      }
+    }
+  } catch {
+    // Best-effort; never mask the underlying publish outcome.
   }
 }
 
@@ -171,20 +366,12 @@ function writeGoWork(
   pluginName: string,
 ): void {
   const goModReader = createGoModReader(goBinary, pluginName);
-  validateSourceReplacements(
-    scratchDir,
-    useDirs,
-    goModReader,
-    pluginName,
-  );
+  validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
   const useLines = ["\t."];
   for (const dir of useDirs) {
     useLines.push(`\t${dir.replace(/\\/g, "/")}`);
   }
-  const replaceLines = sourceBuildWorkspaceReplacements(
-    useDirs,
-    goModReader,
-  );
+  const replaceLines = sourceBuildWorkspaceReplacements(useDirs, goModReader);
   const replaceBlock =
     replaceLines.length === 0 ? "" : `\n\n${replaceLines.join("\n")}\n`;
   const goWork = `go 1.26\n\nuse (\n${useLines.join("\n")}\n)${replaceBlock}`;
@@ -582,6 +769,7 @@ function resolveGoCompiler(): string {
 }
 
 export function computeCacheKey(inputs: {
+  contributors?: readonly ITtscBuildContributor[];
   dir: string;
   entry: string;
   goBinary?: string;
@@ -597,10 +785,34 @@ export function computeCacheKey(inputs: {
   if (inputs.goBinary !== undefined) {
     hash.update(`go=${resolveGoCompilerIdentity(inputs.goBinary)}\n`);
   }
+  // Hash the Go env vars that change `go build`'s output (cross-compile
+  // target, build tags, cgo toggle, etc.). Without this, a user setting
+  // `GOOS=linux GOARCH=arm64` on a darwin host would write a Linux-arm64
+  // binary into the same cache slot as the native build, and the next
+  // native invocation would spawn an unrunnable artifact.
+  for (const key of GO_BUILD_ENV_KEYS) {
+    const value = process.env[key];
+    if (value !== undefined && value !== "") {
+      hash.update(`${key}=${value}\n`);
+    }
+  }
   hashSourceDirectory(hash, "plugin", inputs.dir);
   for (const [index, dir] of [...(inputs.overlayDirs ?? [])].sort().entries()) {
     hashSourceDirectory(hash, `overlay:${index}`, dir);
   }
+  // Hash contributors in sorted-by-name order so two consumers with the
+  // same logical set produce the same key regardless of declaration order
+  // in the host's plugin descriptor.
+  const sortedContributors = [...(inputs.contributors ?? [])].sort((a, b) =>
+    a.name === b.name ? 0 : a.name < b.name ? -1 : 1,
+  );
+  for (const contributor of sortedContributors) {
+    hashSourceDirectory(
+      hash,
+      `contributor:${contributor.name}`,
+      contributor.source,
+    );
+  }
   return hash.digest("hex").slice(0, 32);
 }
 
@@ -651,7 +863,14 @@ function shouldPruneDirectory(name: string): boolean {
 }
 
 function shouldOmitSourceFile(name: string): boolean {
-  return GENERATED_WORKSPACE_FILES.has(name);
+  if (GENERATED_WORKSPACE_FILES.has(name)) return true;
+  // npm-pack tarballs and macOS/Windows editor sidecars are local
+  // build artifacts that drift independently of the Go source. They
+  // would otherwise enter the cache key and bust the cached binary on
+  // every unrelated `npm pack` or editor save.
+  if (name.endsWith(".tgz") || name.endsWith(".tar.gz")) return true;
+  if (name === ".DS_Store" || name === "Thumbs.db") return true;
+  return false;
 }
 
 function isHashableFile(name: string): boolean {

package/src/plugin/internal/loadProjectPlugins.ts

@@ -1,8 +1,9 @@
-import { createRequire } from "node:module";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
 import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
+import { FIRST_PARTY_UTILITY_PLUGIN_NAMES } from "../../compiler/internal/sharedHostHelpers";
 import type { ITtscPlugin } from "../../structures/ITtscPlugin";
 import type { ITtscPluginFactoryContext } from "../../structures/ITtscPluginFactoryContext";
 import type { ITtscProjectPluginConfig } from "../../structures/ITtscProjectPluginConfig";
@@ -10,7 +11,6 @@ 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>,
@@ -82,9 +82,11 @@ export function loadProjectPlugins(options: {
   plugins.forEach((plugin, index) => {
     const stage = resolvePluginStage(plugin);
     validatePluginSource(plugin);
+    const contributors = validatePluginContributors(plugin);
     const binary = buildSourcePlugin({
       baseDir: context.projectRoot,
       cacheDir: options.cacheDir,
+      contributors,
       pluginName: plugin.name,
       source: plugin.source,
       ttscVersion,
@@ -93,6 +95,7 @@ export function loadProjectPlugins(options: {
     nativePlugins.push({
       binary,
       config: entries[index]!.config,
+      contributors,
       name: plugin.name,
       source: plugin.source,
       stage,
@@ -179,12 +182,25 @@ function composePluginSources(
       );
     }
     const aggregate = matchingAggregates[0];
-    return aggregate === undefined
-      ? plugin
-      : {
-          ...plugin,
-          source: aggregate.plugin.source,
-        };
+    if (aggregate === undefined) {
+      return plugin;
+    }
+    // A composed plugin's source is rerouted to the aggregate's binary,
+    // so its own `contributors` would link into a different host than
+    // it was authored against. The "one binary" guarantee in the
+    // protocol doc holds only when the composed plugin defers entirely
+    // to the aggregate; reject early instead of silently producing two
+    // diverging binaries.
+    if (plugin.contributors && plugin.contributors.length > 0) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" is composed by "${aggregate.plugin.name}" but declares its own "contributors"; ` +
+          `move the contributors onto the aggregate plugin or drop the composes redirect`,
+      );
+    }
+    return {
+      ...plugin,
+      source: aggregate.plugin.source,
+    };
   });
 }
 
@@ -511,10 +527,94 @@ function validatePluginSource(plugin: ITtscPlugin): void {
   }
 }
 
+const CONTRIBUTOR_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+function validatePluginContributors(
+  plugin: ITtscPlugin,
+): readonly { name: string; source: string }[] | undefined {
+  const contributors = plugin.contributors;
+  if (contributors === undefined) return undefined;
+  if (!Array.isArray(contributors)) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" "contributors" must be an array of { name, source } entries`,
+    );
+  }
+  if (contributors.length === 0) return undefined;
+  const seen = new Set<string>();
+  const out: { name: string; source: string }[] = [];
+  for (const [index, entry] of contributors.entries()) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}] must be an object`,
+      );
+    }
+    const { name, source } = entry as { name?: unknown; source?: unknown };
+    if (typeof name !== "string" || !CONTRIBUTOR_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].name must match /^[a-z][a-z0-9_]*$/; ` +
+          `got ${JSON.stringify(name)}`,
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}] duplicate name ${JSON.stringify(name)}`,
+      );
+    }
+    seen.add(name);
+    if (typeof source !== "string" || source.length === 0) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be a non-empty string`,
+      );
+    }
+    if (!path.isAbsolute(source)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be an absolute path; ` +
+          `got ${JSON.stringify(source)}`,
+      );
+    }
+    if (!fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be an existing directory: ${source}`,
+      );
+    }
+    // Pre-flight check that the directory actually carries a buildable
+    // contributor package. Without this, an accidentally-empty directory
+    // (or a directory containing only `_test.go` files, which `go build`
+    // silently skips) reaches the synthesized blank-import step and Go's
+    // compile error surfaces with a scratch-tempdir path that doesn't
+    // name the contributor entry. Catching it here lets us name the
+    // entry the user actually authored.
+    if (!hasBuildableGoSource(source)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must contain at least one non-test ".go" file: ${source}`,
+      );
+    }
+    out.push({ name, source: resolveRealPath(source) });
+  }
+  return out;
+}
+
 function isPluginStage(value: string): value is TtscPluginStage {
   return value === "transform" || value === "check";
 }
 
+function hasBuildableGoSource(dir: string): boolean {
+  // `go build` consumes `.go` files but silently ignores `_test.go`. A
+  // contributor whose source dir holds only test files would compile to
+  // an empty package and surface as an opaque scratch-tempdir error;
+  // require at least one production `.go` file so the validator can
+  // name the contributor entry instead.
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return false;
+  }
+  return entries.some(
+    (name) => name.endsWith(".go") && !name.endsWith("_test.go"),
+  );
+}
+
 function resolvePluginRequest(specifier: string, projectRoot: string): string {
   if (path.isAbsolute(specifier)) {
     return resolveRealPath(specifier);

package/src/structures/ITtscCompilerContext.ts

@@ -88,7 +88,7 @@ export interface ITtscCompilerContext {
    *   directly installed package markers.
    * - `false`: ignore project config plugins and package markers for this
    *   compiler instance.
-   * - array: use these plugin entries instead of project config entries and
+   * - Array: use these plugin entries instead of project config entries and
    *   package markers.
    *
    * Plugin entries are resolved once per operation from this instance context.

package/src/structures/ITtscCompilerDiagnostic.ts

@@ -11,11 +11,11 @@
  */
 export interface ITtscCompilerDiagnostic {
   /**
-   * The filename where the diagnostic originated, or null if not
-   * file-specific.
+   * The filename where the diagnostic originated, or null if not file-specific.
    *
    * Global diagnostics such as invalid compiler options or host-level failures
-   * are reported with `null` because they are not tied to a single source file.
+   * are reported with `null` because they are not tied to a single source
+   * file.
    */
   file: string | null;
 

package/src/structures/ITtscCompilerResult.ts

@@ -3,8 +3,8 @@ import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
 /**
  * Result of a ttsc TypeScript-Go compilation operation.
  *
- * Represents the possible outcomes of {@link TtscCompiler.compile}, which can
- * be either a successful compilation, a compilation that completed with
+ * Represents the possible outcomes of {@link TtscCompiler.compile}, which can be
+ * either a successful compilation, a compilation that completed with
  * diagnostics, or an unexpected host error during the compilation process.
  *
  * This type follows the legacy `embed-typescript` result model, but stores all
@@ -25,18 +25,14 @@ export namespace ITtscCompilerResult {
    * Represents a successful ttsc compilation result.
    *
    * This interface is returned when TypeScript-Go completes without
-   * diagnostics, containing every text output captured from the native
-   * compiler host's `WriteFile` callback.
+   * diagnostics, containing every text output captured from the native compiler
+   * host's `WriteFile` callback.
    */
   export interface ISuccess {
-    /**
-     * Indicates that the compilation was successful.
-     */
+    /** Indicates that the compilation was successful. */
     type: "success";
 
-    /**
-     * Non-fatal diagnostics reported during compilation.
-     */
+    /** Non-fatal diagnostics reported during compilation. */
     diagnostics?: ITtscCompilerDiagnostic[];
 
     /**
@@ -59,14 +55,10 @@ export namespace ITtscCompilerResult {
    * diagnostics.
    */
   export interface IFailure {
-    /**
-     * Indicates that compilation completed with diagnostics.
-     */
+    /** Indicates that compilation completed with diagnostics. */
     type: "failure";
 
-    /**
-     * Array of diagnostic messages describing the compilation issues.
-     */
+    /** Array of diagnostic messages describing the compilation issues. */
     diagnostics: ITtscCompilerDiagnostic[];
 
     /**
@@ -86,14 +78,10 @@ export namespace ITtscCompilerResult {
    * {@link IFailure}; this variant is reserved for host-level exceptions.
    */
   export interface IException {
-    /**
-     * Indicates that an unexpected host error occurred.
-     */
+    /** Indicates that an unexpected host error occurred. */
     type: "exception";
 
-    /**
-     * The error that was thrown while preparing or running the compiler host.
-     */
+    /** The error that was thrown while preparing or running the compiler host. */
     error: unknown;
   }
 }

package/src/structures/ITtscCompilerTransformation.ts

@@ -4,8 +4,8 @@ import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
  * Result of a TypeScript source-to-source transformation operation.
  *
  * This mirrors `embed-typescript`'s `IEmbedTypeScriptTransformation` model.
- * Unlike {@link ITtscCompilerResult}, this contract is not an emit contract:
- * the `typescript` map must contain TypeScript source text, not generated
+ * Unlike {@link ITtscCompilerResult}, this contract is not an emit contract: the
+ * `typescript` map must contain TypeScript source text, not generated
  * JavaScript, declaration files, or source maps.
  */
 export type ITtscCompilerTransformation =

package/src/structures/ITtscPlugin.ts

@@ -1,3 +1,4 @@
+import type { ITtscPluginContributor } from "./ITtscPluginContributor";
 import type { TtscPluginStage } from "./TtscPluginStage";
 
 /**
@@ -28,7 +29,7 @@ export interface ITtscPlugin {
   /**
    * Go command package directory, or a `go.mod` file, that ttsc lazily builds.
    *
-   * ttsc accepts source only. It does not accept a prebuilt binary path: the
+   * Ttsc accepts source only. It does not accept a prebuilt binary path: the
    * package-local Go compiler builds this source into the ttsc plugin cache on
    * demand.
    *
@@ -60,19 +61,44 @@ export interface ITtscPlugin {
    * Pipeline stage implemented by the sidecar.
    *
    * Omit this field for normal compiler-transform plugins. The only explicit
-   * non-transform stage is `"check"`.
+   * non-transform stage is `"check"`. Check-stage plugins receive `check`
+   * during normal builds and may implement `fix` for `ttsc fix` and `format`
+   * for `ttsc format`.
    *
    * @default "transform"
    */
   stage?: TtscPluginStage;
-}
 
-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;
+  /**
+   * Additional Go source packages to statically link into this plugin's binary
+   * at build time ("plugin-within-plugin" composition).
+   *
+   * Each contributor's Go source directory is copied into the scratch build
+   * tree as a sub-package of this plugin's module and reached by a synthesized
+   * blank import. The contributor's `init()` runs before the host binary's
+   * `main`, registering whatever state the host expects to find at startup
+   * (e.g. lint rules through `github.com/samchon/ttsc/packages/lint/rule`).
+   *
+   * Differs from `composes`:
+   *
+   * - `composes` is horizontal — many plugin entries dispatch to one binary by
+   *   name. Each entry is still a top-level `compilerOptions.plugins[]` citizen
+   *   with its own lifecycle slot.
+   * - `contributors` is vertical — one binary statically links additional Go
+   *   sources that never appear as top-level plugin entries. The contributing
+   *   npm packages are discovered through the host plugin's own config file
+   *   (e.g. `lint.config.ts` for `@ttsc/lint`).
+   *
+   * Constraints:
+   *
+   * - Contributors ship Go source as a package (no `go.mod`); the host plugin's
+   *   module supplies every transitive Go dependency. This is also a
+   *   supply-chain feature — contributors cannot pull in arbitrary Go modules
+   *   at build time.
+   * - Contributor source paths must be absolute (the host plugin's JS factory
+   *   typically resolves them through `require.resolve`).
+   * - Contributor names are used as the sub-package import suffix and must be
+   *   unique within a single plugin build.
+   */
+  contributors?: ITtscPluginContributor[];
 }