ttsc 0.8.0-dev.20260505 → 0.8.0

package/shim/ast/shim.go

@@ -92,6 +92,8 @@ type ParameterDeclaration = innerast.ParameterDeclaration
 type ParenthesizedTypeNode = innerast.ParenthesizedTypeNode
 
 const (
+  KindEndOfFile                     = innerast.KindEndOfFile
+  KindSingleLineCommentTrivia       = innerast.KindSingleLineCommentTrivia
   KindCallExpression                = innerast.KindCallExpression
   KindIdentifier                    = innerast.KindIdentifier
   KindMultiLineCommentTrivia        = innerast.KindMultiLineCommentTrivia
@@ -167,12 +169,12 @@ const (
   ModifierFlagsReadonly  = innerast.ModifierFlagsReadonly
 )
 
-func NewNodeFactory(hooks NodeFactoryHooks) *NodeFactory {
-  return innerast.NewNodeFactory(hooks)
+func NewNodeFactory(options NodeFactoryHooks) *NodeFactory {
+  return innerast.NewNodeFactory(options)
 }
 
-func NewNodeVisitor(visit func(node *Node) *Node, factory *NodeFactory, hooks NodeVisitorHooks) *NodeVisitor {
-  return innerast.NewNodeVisitor(visit, factory, hooks)
+func NewNodeVisitor(visit func(node *Node) *Node, factory *NodeFactory, options NodeVisitorHooks) *NodeVisitor {
+  return innerast.NewNodeVisitor(visit, factory, options)
 }
 
 func IsFunctionLike(node *Node) bool {

package/src/compiler/internal/runBuild.ts

@@ -323,7 +323,6 @@ function serializeNativePlugins(
   return JSON.stringify(
     plugins.map((plugin) => ({
       config: plugin.config,
-      hooks: plugin.hooks,
       name: plugin.name,
       stage: plugin.stage,
     })),
@@ -411,7 +410,7 @@ function assertCompilerHostCompatibility(
   }
   throw new Error(
     "ttsc: multiple compiler native backends cannot share one emit pass; " +
-      "compose transform hook libraries through one aggregate host",
+      "compose transform libraries through one aggregate native host",
   );
 }
 

package/src/compiler/internal/transformProjectInMemory.ts

@@ -218,7 +218,6 @@ function serializeNativePlugins(
   return JSON.stringify(
     plugins.map((plugin) => ({
       config: plugin.config,
-      hooks: plugin.hooks,
       name: plugin.name,
       stage: plugin.stage,
     })),
@@ -237,7 +236,7 @@ function assertTransformHostCompatibility(
   }
   throw new Error(
     "ttsc: multiple transform native backends cannot share one source-to-source pass; " +
-      "compose transform hook libraries through one aggregate host",
+      "compose transform libraries through one aggregate native host",
   );
 }
 

package/src/launcher/internal/runTtsc.ts

@@ -369,7 +369,7 @@ function printHelp(): void {
       "Plugin contract:",
       "  ttsc reads compilerOptions.plugins from tsconfig.json.",
       "  Plugin modules are descriptors for ordered native transformer backends.",
-      "  JS transformOutput/transformSource hooks are not part of the public contract.",
+      "  JS transformOutput/transformSource functions are not part of the public contract.",
       "",
       "Compatibility aliases:",
       "  ttsc build [options]       Same project build lane as `ttsc [options]`.",

package/src/plugin/internal/loadProjectPlugins.ts

@@ -60,7 +60,6 @@ export function loadProjectPlugins(options: {
   plugins.forEach((plugin, index) => {
     const stage = resolvePluginStage(plugin);
     validatePluginSource(plugin);
-    validatePluginHooks(plugin, stage);
     const binary = buildSourcePlugin({
       baseDir: context.projectRoot,
       cacheDir: options.cacheDir,
@@ -72,7 +71,6 @@ export function loadProjectPlugins(options: {
     nativePlugins.push({
       binary,
       config: entries[index]!,
-      hooks: plugin.hooks,
       name: plugin.name,
       source: plugin.source,
       stage,
@@ -92,7 +90,6 @@ 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 {
@@ -111,11 +108,11 @@ function loadPluginEntry(
         `ttsc: plugin "${specifier}" does not export a valid ttsc plugin`,
       );
     }
-    rejectJsTransformHooks(specifier, plugin);
+    rejectJsTransformFunctions(specifier, plugin);
     return plugin;
   }
   if (isTtscPlugin(candidate)) {
-    rejectJsTransformHooks(specifier, candidate);
+    rejectJsTransformFunctions(specifier, candidate);
     return candidate;
   }
   throw new Error(
@@ -131,35 +128,18 @@ function isTtscPlugin(value: unknown): value is ITtscPlugin {
   );
 }
 
-function rejectJsTransformHooks(specifier: string, candidate: object): void {
+function rejectJsTransformFunctions(
+  specifier: string,
+  candidate: object,
+): void {
   if ("transformSource" in candidate || "transformOutput" in candidate) {
     throw new Error(
-      `ttsc: plugin "${specifier}" declares unsupported JS transform hooks; ` +
+      `ttsc: plugin "${specifier}" declares unsupported JS transform functions; ` +
         "declare a native backend instead",
     );
   }
 }
 
-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";
@@ -168,7 +148,7 @@ function resolvePluginStage(plugin: ITtscPlugin): TtscPluginStage {
     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",
+          "upgrade the plugin to a transform-stage descriptor compatible with this ttsc version",
       );
     }
     throw new Error(
@@ -184,54 +164,6 @@ 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";
 }

package/src/structures/ITtscPlugin.ts

@@ -1,20 +1,5 @@
 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.
  *
@@ -69,9 +54,6 @@ export interface ITtscPlugin {
    * @default "transform"
    */
   stage?: TtscPluginStage;
-
-  /** Native transform hook capabilities implemented by the plugin package. */
-  hooks?: ITtscPluginHooks;
 }
 
 export function defineTtscPlugin<T extends ITtscPlugin>(plugin: T): T;

package/src/structures/TtscPluginStage.ts

@@ -2,9 +2,7 @@
  * Pipeline stage where a plugin's lazily built Go sidecar participates.
  *
  * - `"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.
+ *   plugins 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.

package/src/structures/internal/ITtscLoadedNativePlugin.ts

@@ -1,5 +1,4 @@
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
-import type { ITtscPluginHooks } from "../ITtscPlugin";
 import type { TtscPluginStage } from "../TtscPluginStage";
 
 /** Native sidecar selected and built from one plugin descriptor. */
@@ -14,6 +13,4 @@ export interface ITtscLoadedNativePlugin {
   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", hooks: { source: true } };\n',
+    'module.exports = { name: "prepare-fixture", source: "./plugin-go" };\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", hooks: { source: true } };\n',
+    'module.exports = { name: "broken-transform-fixture", source: "./plugin-go" };\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", hooks: { source: true } };\n',
+    'module.exports = { name: "compile-fixture", source: "./plugin-go" };\n',
     "utf8",
   );
   fs.mkdirSync(path.join(root, "plugin-go"), { recursive: true });

package/utility/host.go

@@ -18,7 +18,6 @@ import (
 
 type pluginEntry struct {
   Config map[string]any `json:"config"`
-  Hooks  map[string]any `json:"hooks"`
   Name   string         `json:"name"`
   Stage  string         `json:"stage"`
 }
@@ -35,9 +34,8 @@ type hostOptions struct {
 }
 
 type transformState struct {
-  banner string
-  paths  *pathsRewriter
-  strip  *stripRewriter
+  paths *pathsRewriter
+  strip *stripRewriter
 }
 
 type transformResult struct {
@@ -51,7 +49,7 @@ func RunBuild(args []string) int {
   if !ok {
     return 2
   }
-  prog, entries, state, ok := loadUtilityProgram(opts)
+  prog, entries, _, sourcePreamble, ok := loadUtilityProgram(opts)
   if !ok {
     return 2
   }
@@ -70,19 +68,7 @@ func RunBuild(args []string) int {
     eDiags []driver.Diagnostic
     err    error
   )
-  if state.banner != "" {
-    hooks := shimcompiler.EmitHooks{
-      BeforePrintJS: func(context *shimcompiler.EmitContext, file *shimast.SourceFile) *shimast.SourceFile {
-        return applyBannerJSDoc(context, file, state.banner)
-      },
-      BeforePrintDeclaration: func(context *shimcompiler.EmitContext, file *shimast.SourceFile) *shimast.SourceFile {
-        return applyBannerJSDoc(context, file, state.banner)
-      },
-    }
-    res, eDiags, err = prog.EmitAllRawWithHooks(nil, hooks)
-  } else {
-    res, eDiags, err = prog.EmitAllRaw(nil)
-  }
+  res, eDiags, err = prog.EmitAllRaw(makeSourcePreambleWriteFile(prog, sourcePreamble))
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc utility: emit failed: %v\n", err)
     return 3
@@ -96,13 +82,13 @@ func RunBuild(args []string) int {
   return 0
 }
 
-// RunTransform returns the project TypeScript text after source-hook mutations.
+// RunTransform returns the project TypeScript text after source mutations.
 func RunTransform(args []string) int {
   opts, ok := parseHostOptions("transform", args)
   if !ok {
     return 2
   }
-  prog, _, _, ok := loadUtilityProgram(opts)
+  prog, _, _, _, ok := loadUtilityProgram(opts)
   if !ok {
     return 2
   }
@@ -163,39 +149,45 @@ func parseHostOptions(command string, args []string) (hostOptions, bool) {
   }, true
 }
 
-func loadUtilityProgram(opts hostOptions) (*driver.Program, []pluginEntry, transformState, bool) {
+func loadUtilityProgram(opts hostOptions) (*driver.Program, []pluginEntry, transformState, string, bool) {
   entries, err := parsePluginEntries(opts.pluginsJSON)
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
+  }
+  sourcePreamble, err := prepareSourcePreamble(entries)
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return nil, nil, transformState{}, "", false
   }
   prog, diags, err := driver.LoadProgram(opts.cwd, opts.tsconfig, driver.LoadProgramOptions{
-    ForceEmit:   opts.emit,
-    ForceNoEmit: opts.noEmit,
-    OutDir:      opts.outDir,
+    ForceEmit:      opts.emit,
+    ForceNoEmit:    opts.noEmit,
+    OutDir:         opts.outDir,
+    SourcePreamble: sourcePreamble,
   })
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc utility: %v\n", err)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
   }
   if len(diags) > 0 {
     driver.WritePrettyDiagnostics(os.Stderr, diags, opts.cwd)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
   }
   if diags := prog.Diagnostics(); len(diags) > 0 {
     driver.WritePrettyDiagnostics(os.Stderr, diags, opts.cwd)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
   }
   state, err := prepareTransforms(prog, entries)
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
   }
   if err := applySourceTransforms(prog, state); err != nil {
     fmt.Fprintln(os.Stderr, err)
-    return nil, nil, transformState{}, false
+    return nil, nil, transformState{}, "", false
   }
-  return prog, entries, state, true
+  return prog, entries, state, sourcePreamble, true
 }
 
 func parsePluginEntries(input string) ([]pluginEntry, error) {
@@ -213,12 +205,6 @@ func prepareTransforms(prog *driver.Program, entries []pluginEntry) (transformSt
   state := transformState{}
   for _, entry := range entries {
     switch entry.Name {
-    case "@ttsc/banner":
-      banner, err := parseBanner(entry.Config)
-      if err != nil {
-        return state, err
-      }
-      state.banner = banner
     case "@ttsc/paths":
       state.paths = newPathsRewriter(prog)
     case "@ttsc/strip":
@@ -232,6 +218,54 @@ func prepareTransforms(prog *driver.Program, entries []pluginEntry) (transformSt
   return state, nil
 }
 
+func prepareSourcePreamble(entries []pluginEntry) (string, error) {
+  var preamble strings.Builder
+  for _, entry := range entries {
+    if entry.Name != "@ttsc/banner" {
+      continue
+    }
+    banner, err := parseBanner(entry.Config)
+    if err != nil {
+      return "", err
+    }
+    preamble.WriteString(banner)
+  }
+  return preamble.String(), nil
+}
+
+func makeSourcePreambleWriteFile(prog *driver.Program, sourcePreamble string) shimcompiler.WriteFile {
+  if sourcePreamble == "" || shouldRemoveComments(prog) {
+    return nil
+  }
+  return func(fileName, text string, _ *shimcompiler.WriteFileData) error {
+    if shouldEnsureSourcePreamble(fileName, text, sourcePreamble) {
+      text = sourcePreamble + text
+    }
+    return driver.DefaultWriteFile(fileName, text)
+  }
+}
+
+func shouldRemoveComments(prog *driver.Program) bool {
+  if prog == nil || prog.ParsedConfig == nil || prog.ParsedConfig.ParsedConfig == nil || prog.ParsedConfig.ParsedConfig.CompilerOptions == nil {
+    return false
+  }
+  return prog.ParsedConfig.ParsedConfig.CompilerOptions.RemoveComments.IsTrue()
+}
+
+func shouldEnsureSourcePreamble(fileName, text, sourcePreamble string) bool {
+  return isSourcePreambleOutputTarget(fileName) && !strings.Contains(text, sourcePreamble)
+}
+
+func isSourcePreambleOutputTarget(fileName string) bool {
+  lower := strings.ToLower(filepath.ToSlash(fileName))
+  for _, suffix := range []string{".d.ts", ".d.mts", ".d.cts", ".js", ".jsx", ".mjs", ".cjs"} {
+    if strings.HasSuffix(lower, suffix) {
+      return true
+    }
+  }
+  return false
+}
+
 func applySourceTransforms(prog *driver.Program, state transformState) error {
   for _, file := range prog.SourceFiles() {
     if state.paths != nil {
@@ -267,7 +301,8 @@ func parseBanner(config map[string]any) (string, error) {
   }
   var b strings.Builder
   sep := strings.Repeat("-", 64)
-  b.WriteString("*\n * ")
+  b.WriteString("/**\n")
+  b.WriteString(" * ")
   b.WriteString(sep)
   b.WriteByte('\n')
   for _, line := range lines {
@@ -277,6 +312,7 @@ func parseBanner(config map[string]any) (string, error) {
   }
   b.WriteString(" *\n")
   b.WriteString(" * @packageDocumentation\n ")
+  b.WriteString("*/\n")
   return b.String(), nil
 }
 
@@ -284,14 +320,6 @@ func sanitizeJSDocLine(line string) string {
   return strings.ReplaceAll(line, "*/", "* /")
 }
 
-func applyBannerJSDoc(context *shimcompiler.EmitContext, file *shimast.SourceFile, banner string) *shimast.SourceFile {
-  if context == nil || file == nil || banner == "" || file.Statements == nil || len(file.Statements.Nodes) == 0 {
-    return file
-  }
-  context.AddSyntheticLeadingComment(file.Statements.Nodes[0], shimast.KindMultiLineCommentTrivia, banner, true)
-  return file
-}
-
 type pathsRewriter struct {
   basePath    string
   outDir      string