ttsc 0.12.4 → 0.13.0

package/src/structures/ITtscPlugin.ts

@@ -1,3 +1,4 @@
+import type { ITtscPluginCapabilities } from "./ITtscPluginCapabilities";
 import type { ITtscPluginContributor } from "./ITtscPluginContributor";
 import type { TtscPluginStage } from "./TtscPluginStage";
 
@@ -64,6 +65,31 @@ export interface ITtscPlugin {
    */
   stage?: TtscPluginStage;
 
+  /**
+   * Optional capability flags declared by the sidecar.
+   *
+   * ttsc carries a few cross-cutting flags (`--singleThreaded`, `--checkers`,
+   * …) the lint sidecar parses but a typical third-party transform host
+   * does not. Capability flags let the plugin author opt into those flags
+   * explicitly, instead of ttsc keeping a hard-coded allow-list keyed by
+   * plugin name. Every capability defaults to `false`.
+   *
+   * @see ITtscPluginCapabilities
+   */
+  capabilities?: ITtscPluginCapabilities;
+
+  /**
+   * Whether a check-stage sidecar reports the normal TypeScript diagnostics for
+   * the project as part of its `check` subcommand.
+   *
+   * Leave this unset for ordinary check plugins that only report their own
+   * diagnostics; ttsc will keep running a separate `tsgo --noEmit` guard so
+   * TypeScript errors are not suppressed. Set it only when the sidecar builds
+   * the project Program and emits the same TypeScript diagnostics the guard
+   * would have produced.
+   */
+  reportsTypeScriptDiagnostics?: boolean;
+
   /**
    * Additional Go source packages to statically link into this plugin's binary
    * at build time ("plugin-within-plugin" composition).

package/src/structures/ITtscPluginCapabilities.ts

@@ -0,0 +1,29 @@
+/**
+ * Optional capability flags declared by a native ttsc plugin descriptor.
+ *
+ * ttsc owns a small set of cross-cutting flags (`--singleThreaded`,
+ * `--checkers`, …) that the lint sidecar accepts but a typical third-party
+ * transform host (built with bare `flag.FlagSet`) would reject with exit 2.
+ * Capabilities let the plugin author tell ttsc up front which of those flags
+ * the sidecar understands, instead of ttsc hard-checking the plugin name and
+ * silently dropping the flag for anything else.
+ *
+ * Every field is optional and defaults to `false`. Plugin authors opt in by
+ * setting only the capabilities their sidecar actually implements; ttsc
+ * keeps the conservative default for everything else.
+ */
+export interface ITtscPluginCapabilities {
+  /**
+   * Whether the sidecar accepts `--singleThreaded` and `--checkers` on its
+   * command line. The lint sidecar parses both flags via
+   * `parseSubcommandFlags` and threads them into `loadProgram` (parse phase)
+   * and `engine.SetSerial` (rule walk); other check-stage hosts may not.
+   *
+   * When `false` (the default), ttsc strips both flags from the sidecar's
+   * arg list — the conservative behavior that ad3443a restored after
+   * `#113` over-forwarded them to typia/nestia hosts.
+   *
+   * @default false
+   */
+  threadingArgs?: boolean;
+}

package/src/structures/index.ts

@@ -3,6 +3,7 @@ export * from "./ITtscCompilerDiagnostic";
 export * from "./ITtscCompilerResult";
 export * from "./ITtscCompilerTransformation";
 export * from "./ITtscPlugin";
+export * from "./ITtscPluginCapabilities";
 export * from "./ITtscPluginContributor";
 export * from "./ITtscPluginFactoryContext";
 export * from "./ITtscProjectPluginConfig";

package/src/structures/internal/ITtscLoadedNativePlugin.ts

@@ -1,3 +1,4 @@
+import type { ITtscPluginCapabilities } from "../ITtscPluginCapabilities";
 import type { ITtscPluginContributor } from "../ITtscPluginContributor";
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
 import type { TtscPluginStage } from "../TtscPluginStage";
@@ -6,6 +7,8 @@ import type { TtscPluginStage } from "../TtscPluginStage";
 export interface ITtscLoadedNativePlugin {
   /** Executable produced by the lazy Go source build cache. */
   binary: string;
+  /** Capability flags declared by the descriptor (see `ITtscPluginCapabilities`). */
+  capabilities?: ITtscPluginCapabilities;
   /** Original tsconfig plugin entry passed unchanged to the sidecar. */
   config: ITtscProjectPluginConfig;
   /** Contributor Go sources statically linked into the binary, if any. */
@@ -14,6 +17,8 @@ export interface ITtscLoadedNativePlugin {
   kind: "executable" | "linked";
   /** Optional human label used in diagnostics and native manifests. */
   name?: string;
+  /** Whether a check-stage plugin already emits TypeScript diagnostics. */
+  reportsTypeScriptDiagnostics?: boolean;
   /** Go source directory selected by the plugin descriptor. */
   source: string;
   /** Pipeline stage where the sidecar participates. */

package/src/structures/internal/TtscCommonOptions.ts

@@ -22,6 +22,25 @@ export interface TtscCommonOptions {
   cacheDir?: string;
   /** Normalize compiler output so diagnostics can be parsed structurally. */
   structuredDiagnostics?: boolean;
+  /**
+   * Run TypeScript-Go single-threaded — one checker, serial parse/check/emit.
+   * Mirrors `tsgo --singleThreaded`. Useful for deterministic debugging and CI
+   * repro.
+   */
+  singleThreaded?: boolean;
+  /**
+   * Type-checker pool size, mirroring `tsgo --checkers`. `undefined` leaves
+   * TypeScript-Go's default; ignored when `singleThreaded` is set.
+   */
+  checkers?: number;
+  /**
+   * CLI tokens ttsc did not recognize as its own, forwarded verbatim to the
+   * underlying `tsgo` invocation. This is how a tsgo flag ttsc has no first-
+   * class option for (`--strict`, `--target es2020`, `--listFiles`, …) still
+   * reaches the compiler: ttsc owns its own flags and lets tsgo — which has the
+   * complete, arity-aware option parser — handle the rest.
+   */
+  passthrough?: readonly string[];
   /**
    * Override project plugin loading for this invocation.
    *

package/utility/flags_gen.go

@@ -0,0 +1,30 @@
+// Code generated by packages/ttsc/scripts/gen-flags.mts. DO NOT EDIT.
+//
+// Source of truth: packages/ttsc/src/flags/schema.ts.
+// Regenerate with:    pnpm format
+// Verify in CI with:  node packages/ttsc/scripts/check-flags.cjs
+
+package utility
+
+// HostFlagAllowList is the allow-list of CLI flags this Go layer accepts. The map's
+// value is true when the flag carries a separate value token (--flag VALUE
+// or --flag=VALUE) and false when the flag is boolean (--flag).
+//
+// Generated from packages/ttsc/src/flags/schema.ts. Edit the schema, not
+// this file.
+var HostFlagAllowList = map[string]bool{
+  "checkers":       true,
+  "cwd":            true,
+  "emit":           false,
+  "manifest":       true,
+  "noEmit":         false,
+  "outDir":         true,
+  "p":              true,
+  "plugins-json":   true,
+  "project":        true,
+  "quiet":          false,
+  "singleThreaded": false,
+  "tsconfig":       true,
+  "tsgo-args":      true,
+  "verbose":        false,
+}

package/utility/host.go

@@ -17,14 +17,17 @@ import (
 // hostOptions is the parsed form of the flags accepted by all three
 // subcommands (check, build, transform).
 type hostOptions struct {
-  cwd         string
-  emit        bool
-  noEmit      bool
-  outDir      string
-  pluginsJSON string
-  quiet       bool
-  tsconfig    string
-  verbose     bool
+  cwd            string
+  emit           bool
+  noEmit         bool
+  outDir         string
+  pluginsJSON    string
+  quiet          bool
+  tsconfig       string
+  verbose        bool
+  singleThreaded bool
+  checkers       int
+  tsgoArgs       []string
 }
 
 // transformResult is the JSON envelope written to stdout by RunTransform.
@@ -134,9 +137,19 @@ func parseHostOptions(command string, args []string) (hostOptions, bool) {
   quiet := fs.Bool("quiet", true, "suppress summary")
   tsconfig := fs.String("tsconfig", "tsconfig.json", "project tsconfig")
   verbose := fs.Bool("verbose", false, "print summary")
+  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
+  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
+  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
   if err := fs.Parse(filterHostArgs(args)); err != nil {
     return hostOptions{}, false
   }
+  var tsgoArgs []string
+  if *tsgoArgsRaw != "" {
+    if err := json.Unmarshal([]byte(*tsgoArgsRaw), &tsgoArgs); err != nil {
+      fmt.Fprintf(os.Stderr, "ttsc utility: invalid --tsgo-args: %v\n", err)
+      return hostOptions{}, false
+    }
+  }
   if *emit && *noEmit {
     fmt.Fprintln(os.Stderr, "ttsc utility: --emit and --noEmit are mutually exclusive")
     return hostOptions{}, false
@@ -159,14 +172,17 @@ func parseHostOptions(command string, args []string) (hostOptions, bool) {
     resolvedCwd = abs
   }
   return hostOptions{
-    cwd:         filepath.Clean(resolvedCwd),
-    emit:        *emit,
-    noEmit:      *noEmit,
-    outDir:      *outDir,
-    pluginsJSON: *pluginsJSON,
-    quiet:       *quiet,
-    tsconfig:    *tsconfig,
-    verbose:     *verbose,
+    cwd:            filepath.Clean(resolvedCwd),
+    emit:           *emit,
+    noEmit:         *noEmit,
+    outDir:         *outDir,
+    pluginsJSON:    *pluginsJSON,
+    quiet:          *quiet,
+    tsconfig:       *tsconfig,
+    verbose:        *verbose,
+    singleThreaded: *singleThreaded,
+    checkers:       *checkers,
+    tsgoArgs:       tsgoArgs,
   }, true
 }
 
@@ -175,20 +191,11 @@ func parseHostOptions(command string, args []string) (hostOptions, bool) {
 // cause flag.FlagSet to error. Flags not in the known set are consumed together
 // with their value argument when they clearly take one (no inline "=" and the
 // next token does not start with "-").
+//
+// The allow-list itself is generated from packages/ttsc/src/flags/schema.ts
+// (see flags_gen.go); editing it means editing the schema and re-running
+// `pnpm format`, not patching this file.
 func filterHostArgs(args []string) []string {
-  // known maps flag name → whether it takes a separate value token.
-  // true  = the flag accepts a value (--flag value or --flag=value).
-  // false = the flag is boolean (no following value token).
-  known := map[string]bool{
-    "cwd":          true,
-    "emit":         false,
-    "noEmit":       false,
-    "outDir":       true,
-    "plugins-json": true,
-    "quiet":        false,
-    "tsconfig":     true,
-    "verbose":      false,
-  }
   filtered := make([]string, 0, len(args))
   for i := 0; i < len(args); i++ {
     current := args[i]
@@ -200,7 +207,7 @@ func filterHostArgs(args []string) []string {
       continue
     }
     name, hasInlineValue := flagName(current)
-    takesValue, ok := known[name]
+    takesValue, ok := HostFlagAllowList[name]
     if ok {
       filtered = append(filtered, current)
       if takesValue && !hasInlineValue && i+1 < len(args) {
@@ -238,9 +245,12 @@ func loadUtilityProgram(opts hostOptions) (*driver.Program, []driver.PluginEntry
   defer restoreEnv()
 
   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,
+    SingleThreaded: opts.singleThreaded,
+    Checkers:       opts.checkers,
+    TsgoArgs:       opts.tsgoArgs,
   })
   if err != nil {
     fmt.Fprintf(os.Stderr, "ttsc utility: %v\n", err)