ttsc 0.12.3 → 0.13.0

package/src/structures/ITtscCompilerTransformation.ts

@@ -22,7 +22,14 @@ export namespace ITtscCompilerTransformation {
     /** Non-fatal diagnostics reported during transformation. */
     diagnostics?: ITtscCompilerDiagnostic[];
 
-    /** Transformed TypeScript source text keyed by project file path. */
+    /**
+     * Transformed TypeScript source text keyed by project-relative file path.
+     *
+     * Values are TypeScript source text, never JavaScript, declaration files,
+     * or source maps. When no transform sidecar is configured, this map
+     * contains the unmodified TypeScript files loaded by the TypeScript-Go
+     * Program.
+     */
     typescript: Record<string, string>;
   }
 
@@ -31,7 +38,13 @@ export namespace ITtscCompilerTransformation {
     /** Indicates that transformation completed with diagnostics. */
     type: "failure";
 
-    /** Transformed or partially transformed TypeScript source text. */
+    /**
+     * Transformed or partially transformed TypeScript source text keyed by
+     * project-relative file path.
+     *
+     * May be empty or partial when diagnostics prevented the transform sidecar
+     * from completing its pass.
+     */
     typescript: Record<string, string>;
 
     /** Diagnostics reported during transformation. */

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).
@@ -96,5 +122,4 @@ export interface ITtscPlugin {
    *   unique within a single plugin build.
    */
   contributors?: ITtscPluginContributor[];
-
 }

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/src/structures/internal/TtscSingleFileEmitOptions.ts

@@ -10,6 +10,4 @@ export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
   out?: string;
   /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
   quiet?: boolean;
-  /** Normalize compiler output so diagnostics can be parsed structurally. */
-  structuredDiagnostics?: boolean;
 }

package/tools/gen_shims/main.go

@@ -56,13 +56,28 @@ var packagesToShim = []string{
   "vfs/osvfs",
 }
 
+// ExtraShim is the schema for the per-shim-directory `extra-shim.json` file.
+// It lets maintainers extend the generated output beyond what gen_shims can
+// derive automatically from the public API surface.
 type ExtraShim struct {
-  ExtraFunctions  []string
-  ExtraMethods    map[string][]string
-  ExtraFields     map[string][]string
+  // ExtraFunctions lists unexported function names that should be shimmed via
+  // go:linkname in addition to the exported ones gen_shims discovers itself.
+  ExtraFunctions []string
+  // ExtraMethods maps type name → method names for unexported or
+  // otherwise-unlinkable methods that should be forwarded.
+  ExtraMethods map[string][]string
+  // ExtraFields maps type name → field names whose values should be exposed
+  // through unsafe pointer casts (used when go:linkname cannot reach them).
+  ExtraFields map[string][]string
+  // IgnoreFunctions lists exported function names that gen_shims should skip
+  // entirely, typically because the caller supplies a hand-written alternative.
   IgnoreFunctions []string
 }
 
+// signatureHasUnexportedType reports whether any parameter of the function
+// signature refers to an unexported named type (optionally through a pointer).
+// Such functions cannot be linked safely because the shim package cannot
+// reference the unexported type by name.
 func signatureHasUnexportedType(t types.Signature) bool {
   if params := t.Params(); params != nil {
     for v := range params.Variables() {
@@ -128,6 +143,9 @@ func main() {
       extraShim.IgnoreFunctions = []string{}
     }
 
+    // importedPackages tracks every package import the generated file needs.
+    // true  = referenced by name (needs a named import).
+    // false = only needed for its side-effects (blank import "_").
     importedPackages := map[string]bool{}
     importPackage := func(path string, directly bool) {
       if directly {
@@ -137,12 +155,21 @@ func main() {
       }
     }
 
+    // qualifierOnlyPackageName records a direct import for every package the
+    // type-string references and returns just the package short name, producing
+    // output like `ast.Node` instead of a full path.
     var qualifierOnlyPackageName types.Qualifier = func(p *types.Package) string {
       importPackage(p.Path(), true)
       return p.Name()
     }
+    // qualifierEmptyPackageName omits the package qualifier entirely; used when
+    // writing the receiver type inside a go:linkname directive where the package
+    // prefix must not appear.
     var qualifierEmptyPackageName types.Qualifier = func(p *types.Package) string { return "" }
 
+    // emitGoLinknameDirective appends a `//go:linkname localName pkg.Func`
+    // pragma line to shimBuilder, registering unsafe and the source package as
+    // blank imports so the linker can resolve the symbol.
     emitGoLinknameDirective := func(localName string, fn *types.Func) {
       importPackage("unsafe", false)
       importPackage(pkg.Types.Path(), false)
@@ -161,6 +188,9 @@ func main() {
       shimBuilder.WriteByte('\n')
     }
 
+    // emitLinkedFunction emits a go:linkname directive and a matching func
+    // declaration for fn. Generic functions (TypeParams != nil) and functions
+    // with unexported parameter types are skipped (returns false).
     emitLinkedFunction := func(fn *types.Func) bool {
       if fn.Signature().TypeParams() != nil {
         return false
@@ -221,10 +251,9 @@ func main() {
         shimBuilder.WriteString("\n")
       }
 
-      switch object.(type) {
+      switch typedObj := object.(type) {
       case *types.TypeName:
-        typeName := object.(*types.TypeName)
-        t := typeName.Type()
+        t := typedObj.Type()
         named, isNamed := t.(*types.Named)
         if isNamed {
           _, nameWithTypeParams, _ := strings.Cut(types.TypeString(named, qualifierOnlyPackageName), ".")
@@ -297,6 +326,10 @@ func main() {
           matchedExtraFields[name] = true
           mirrorStructName := "extra_" + name
 
+          // emitExtraStruct emits a mirror struct (`extra_<Name>`) whose field
+          // layout matches the unexported original so that unsafe.Pointer casts
+          // in the generated accessor functions are safe. Unexported pointer
+          // fields whose element type is also unexported are recursively mirrored.
           var emitExtraStruct func(name string, s *types.Struct)
           emitExtraStruct = func(name string, s *types.Struct) {
             shimBuilder.WriteString("type extra_")
@@ -384,12 +417,14 @@ func main() {
         printReexport("var")
       case *types.Func:
         if !slices.Contains(extraShim.IgnoreFunctions, name) {
-          funcType := object.(*types.Func)
-          emitLinkedFunction(funcType)
+          emitLinkedFunction(typedObj)
         }
       }
     }
 
+    // Verify that every extra function/method requested in extra-shim.json was
+    // actually found in the package. A missing symbol means the json file is
+    // stale relative to the upstream typescript-go API.
     exit := false
     for fnName, found := range matchedExtraFunctions {
       if found {

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,
+}