ttsc 0.12.4 → 0.13.1

package/README.md

@@ -11,6 +11,9 @@
 
 A `typescript-go` toolchain for compiler-powered plugins and type-safe execution.
 
+Benchmarked on the VS Code fixture: up to **10x** faster type checks and a
+**500x** faster measured lint pass.
+
 - **`ttsc`**: build, check, and transform.
 - **`ttsx`**: execute TypeScript with type checking.
   - native TypeScript-Go execution instead of transpile-only runners.

package/cmd/ttsc/api_compile.go

@@ -47,7 +47,11 @@ func runAPICompile(args []string) int {
   fs.SetOutput(stderr)
   tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
   cwdOverride := fs.String("cwd", "", "override the working directory")
-  if err := fs.Parse(args); err != nil {
+  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")
+  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
+  if err := fs.Parse(filterHostArgs(args)); err != nil {
     return 2
   }
 
@@ -57,8 +61,17 @@ func runAPICompile(args []string) int {
     return 2
   }
 
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return 2
+  }
+
   prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceEmit: true,
+    ForceEmit:      true,
+    SingleThreaded: *singleThreaded,
+    Checkers:       *checkers,
+    TsgoArgs:       tsgoArgs,
   })
   if err != nil {
     fmt.Fprintf(stderr, "ttsc api-compile: %v\n", err)

package/cmd/ttsc/api_transform.go

@@ -32,7 +32,11 @@ func runAPITransform(args []string) int {
   fs.SetOutput(stderr)
   tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
   cwdOverride := fs.String("cwd", "", "override the working directory")
-  if err := fs.Parse(args); err != nil {
+  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")
+  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
+  if err := fs.Parse(filterHostArgs(args)); err != nil {
     return 2
   }
 
@@ -42,8 +46,17 @@ func runAPITransform(args []string) int {
     return 2
   }
 
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return 2
+  }
+
   prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceNoEmit: true,
+    ForceNoEmit:    true,
+    SingleThreaded: *singleThreaded,
+    Checkers:       *checkers,
+    TsgoArgs:       tsgoArgs,
   })
   if err != nil {
     fmt.Fprintf(stderr, "ttsc api-transform: %v\n", err)

package/cmd/ttsc/build.go

@@ -35,7 +35,19 @@ func runBuild(args []string) int {
   noEmit := fs.Bool("noEmit", false, "force analysis-only run with no file writes")
   outDir := fs.String("outDir", "", "override compilerOptions.outDir for this build")
   manifestPath := fs.String("manifest", "", "write emitted file list as JSON to this path")
-  if err := fs.Parse(args); err != nil {
+  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")
+  // Strip unknown forwarded tsgo options before fs.Parse so a flag like
+  // `--strict` (which tsgo accepts but cmd/ttsc's FlagSet does not declare)
+  // does not exit 2 before reaching the tsgo lane via `--tsgo-args=<JSON>`.
+  // See packages/ttsc/cmd/ttsc/filter.go for the allow-list source.
+  if err := fs.Parse(filterHostArgs(args)); err != nil {
+    return 2
+  }
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
     return 2
   }
   if *emit && *noEmit {
@@ -57,9 +69,12 @@ func runBuild(args []string) int {
   }
 
   prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceEmit:   *emit,
-    ForceNoEmit: *noEmit,
-    OutDir:      *outDir,
+    ForceEmit:      *emit,
+    ForceNoEmit:    *noEmit,
+    OutDir:         *outDir,
+    SingleThreaded: *singleThreaded,
+    Checkers:       *checkers,
+    TsgoArgs:       tsgoArgs,
   })
   if err != nil {
     fmt.Fprintf(stderr, "ttsc: %v\n", err)
@@ -135,3 +150,18 @@ func runBuild(args []string) int {
   }
   return 0
 }
+
+// decodeTsgoArgs decodes the JSON-array value of the `--tsgo-args` flag — the
+// tsgo CLI flags the `ttsc` launcher forwarded — into a string slice. An empty
+// flag yields a nil slice. Shared by the build / api-compile / api-transform
+// subcommands, which all hand the result to driver.LoadProgram.
+func decodeTsgoArgs(raw string) ([]string, error) {
+  if raw == "" {
+    return nil, nil
+  }
+  var args []string
+  if err := json.Unmarshal([]byte(raw), &args); err != nil {
+    return nil, fmt.Errorf("invalid --tsgo-args: %w", err)
+  }
+  return args, nil
+}

package/cmd/ttsc/filter.go

@@ -0,0 +1,70 @@
+// Argument filtering for cmd/ttsc subcommand parsers.
+//
+// `flag.NewFlagSet(..., flag.ContinueOnError).Parse` exits with non-zero on
+// the first unknown flag it sees, which is exactly the failure mode RCA
+// #4 in `.discussions/cli-parser-rca/report.md` flagged: a forwarded tsgo
+// option from the JS launcher would crash the build before tsgo's own
+// option table got a chance to consume it. Mirror the strategy that
+// `packages/ttsc/utility/host.go` already uses for the utility host —
+// strip flags that the local FlagSet does not declare, swallowing the
+// next token when the unknown flag clearly takes one. The allow-list is
+// the same generated `HostFlagAllowList` shared by both consumers
+// (`packages/ttsc/cmd/ttsc/flags_gen.go` and
+// `packages/ttsc/utility/flags_gen.go`).
+
+package main
+
+import "strings"
+
+// filterHostArgs strips flags that the cmd/ttsc FlagSet does not declare,
+// so a forwarded tsgo option from the JS launcher (e.g. `--strict`) does
+// not make `fs.Parse` exit 2 before the build can hand it to tsgo via
+// `--tsgo-args=<JSON>`. Flags absent from `HostFlagAllowList` are
+// dropped together with their value token 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 {
+  filtered := make([]string, 0, len(args))
+  for i := 0; i < len(args); i++ {
+    current := args[i]
+    if current == "--" {
+      // Forward `--` and everything after verbatim. The Go flag parser
+      // treats `--` as "end of options" and stops there; mirroring that
+      // behavior here keeps trailing positional tokens intact.
+      filtered = append(filtered, args[i:]...)
+      break
+    }
+    if !strings.HasPrefix(current, "--") {
+      filtered = append(filtered, current)
+      continue
+    }
+    name, hasInlineValue := splitFlagName(current)
+    takesValue, ok := HostFlagAllowList[name]
+    if ok {
+      filtered = append(filtered, current)
+      if takesValue && !hasInlineValue && i+1 < len(args) {
+        i++
+        filtered = append(filtered, args[i])
+      }
+      continue
+    }
+    if !hasInlineValue && i+1 < len(args) && !strings.HasPrefix(args[i+1], "-") {
+      i++
+    }
+  }
+  return filtered
+}
+
+// splitFlagName strips the leading `--` from a flag argument and reports
+// whether the argument carries an inline value (`--foo=value`).
+func splitFlagName(arg string) (string, bool) {
+  name := strings.TrimPrefix(arg, "--")
+  if i := strings.IndexByte(name, '='); i != -1 {
+    return name[:i], true
+  }
+  return name, false
+}

package/cmd/ttsc/filter_strips_unknown_forwarded_flag_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+  "reflect"
+  "testing"
+)
+
+// TestFilterHostArgsStripsUnknownForwardedFlag verifies cmd/ttsc's
+// filterHostArgs drops forwarded tsgo options before fs.Parse so the
+// FlagSet does not exit 2.
+//
+// `cmd/ttsc/{build,api_compile,api_transform}.go` use
+// `flag.NewFlagSet(..., flag.ContinueOnError)` which exits non-zero on
+// the first unknown flag it sees. The schema-generated allow-list in
+// `flags_gen.go` (`HostFlagAllowList`) feeds this filter so a forwarded
+// `--strict` from the JS launcher reaches the tsgo lane via
+// `--tsgo-args=<JSON>` instead of crashing the build. This pins the
+// behavior RCA #4 flagged as "next likely bug — `cmd/ttsc/build.go:42`
+// uses bare `flag.FlagSet` with no filter and will exit".
+//
+//  1. Known flags + values survive (long form and `=` form).
+//  2. Unknown flag with separate value (`--strict true`) is dropped
+//     together with its value.
+//  3. Unknown flag with inline value (`--target=ES2022`) is dropped.
+//  4. `--` separator and everything after survives verbatim.
+func TestFilterHostArgsStripsUnknownForwardedFlag(t *testing.T) {
+  cases := []struct {
+    name string
+    in   []string
+    want []string
+  }{
+    {
+      name: "keeps known flags including values",
+      in:   []string{"--tsconfig", "tsconfig.json", "--cwd=.", "--emit"},
+      want: []string{"--tsconfig", "tsconfig.json", "--cwd=.", "--emit"},
+    },
+    {
+      name: "drops unknown flag with separate value",
+      in:   []string{"--tsconfig", "tsconfig.json", "--strict", "true", "--emit"},
+      want: []string{"--tsconfig", "tsconfig.json", "--emit"},
+    },
+    {
+      name: "drops unknown flag with inline value",
+      in:   []string{"--tsconfig=tsconfig.json", "--target=ES2022"},
+      want: []string{"--tsconfig=tsconfig.json"},
+    },
+    {
+      name: "double dash preserves trailing tokens",
+      in:   []string{"--tsconfig=tsconfig.json", "--", "--anything", "src/main.ts"},
+      want: []string{"--tsconfig=tsconfig.json", "--", "--anything", "src/main.ts"},
+    },
+  }
+  for _, tc := range cases {
+    t.Run(tc.name, func(t *testing.T) {
+      got := filterHostArgs(tc.in)
+      if !reflect.DeepEqual(got, tc.want) {
+        t.Fatalf("filterHostArgs(%v):\n  want %v\n  got  %v", tc.in, tc.want, got)
+      }
+    })
+  }
+}

package/cmd/ttsc/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 main
+
+// 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/driver/program.go

@@ -204,6 +204,17 @@ type LoadProgramOptions struct {
   ForceNoEmit    bool
   OutDir         string
   SourcePreamble string
+  // SingleThreaded forces TypeScript-Go's single-threaded mode (one checker,
+  // serial parse/check/emit), mirroring `tsgo --singleThreaded`.
+  SingleThreaded bool
+  // Checkers overrides the type-checker pool size, mirroring `tsgo --checkers`.
+  // Zero leaves TypeScript-Go's default; ignored when SingleThreaded is set.
+  Checkers int
+  // TsgoArgs carries tsgo CLI flags the `ttsc` launcher did not recognize as
+  // its own (`--strict`, `--target es2020`, …). They are parsed through
+  // TypeScript-Go's own command-line parser into a CompilerOptions overlay
+  // that wins over the tsconfig, exactly as `tsgo`'s CLI merges them.
+  TsgoArgs []string
 }
 
 // Close releases the checker pool lease acquired by LoadProgram.
@@ -221,12 +232,19 @@ func (p *Program) Close() error {
 // The absolute path is resolved against cwd before any VFS lookups because
 // tsgo's filesystem APIs require absolute paths — mirrors what tsc does when
 // you pass a relative `--project` flag.
-func ParseTSConfig(fs vfs.FS, cwd, tsconfigPath string, host shimcompiler.CompilerHost) (*tsoptions.ParsedCommandLine, []Diagnostic, error) {
+//
+// cliOptions is a CompilerOptions overlay (from forwarded `tsgo` CLI flags);
+// TypeScript-Go merges its non-zero fields over the tsconfig so the CLI wins,
+// the same precedence tsgo's own command line uses. Pass nil for none.
+func ParseTSConfig(fs vfs.FS, cwd, tsconfigPath string, host shimcompiler.CompilerHost, cliOptions *core.CompilerOptions) (*tsoptions.ParsedCommandLine, []Diagnostic, error) {
   resolved := tspath.ResolvePath(cwd, tsconfigPath)
   if !fs.FileExists(resolved) {
     return nil, nil, fmt.Errorf("tsconfig not found: %s", resolved)
   }
-  parsed, diags := tsoptions.GetParsedCommandLineOfConfigFile(resolved, &core.CompilerOptions{}, nil, host, nil)
+  if cliOptions == nil {
+    cliOptions = &core.CompilerOptions{}
+  }
+  parsed, diags := tsoptions.GetParsedCommandLineOfConfigFile(resolved, cliOptions, nil, host, nil)
   allDiags := append(diags, parsed.Errors...)
   if len(allDiags) > 0 {
     return nil, convertDiagnostics(allDiags), nil
@@ -234,14 +252,48 @@ func ParseTSConfig(fs vfs.FS, cwd, tsconfigPath string, host shimcompiler.Compil
   return parsed, nil, nil
 }
 
+// parseTsgoArgs runs forwarded tsgo CLI flags through TypeScript-Go's own
+// command-line parser, yielding a CompilerOptions overlay ParseTSConfig merges
+// over the tsconfig. This is how a plugin build — which constructs its Program
+// in-process rather than shelling out to `tsgo` — still honors flags like
+// `ttsc --strict`. Returns (nil, nil, nil) when there are no forwarded flags.
+func parseTsgoArgs(args []string, host shimcompiler.CompilerHost) (*core.CompilerOptions, []Diagnostic, error) {
+  if len(args) == 0 {
+    return nil, nil, nil
+  }
+  cli := tsoptions.ParseCommandLine(args, host)
+  if cli == nil {
+    return nil, nil, fmt.Errorf("driver: tsgo argument parser returned nil")
+  }
+  if len(cli.Errors) > 0 {
+    return nil, convertDiagnostics(cli.Errors), nil
+  }
+  return cli.CompilerOptions(), nil, nil
+}
+
 // CreateProgramFromConfig builds a tsgo Program from the parsed config.
+//
+// SingleThreaded is intentionally left unset so the program keeps
+// TypeScript-Go's parallel source parsing and parallel emit. The checker
+// pool, however, is pinned to a single checker (see forceSingleChecker):
+// every phase ttsc layers on top — plugin transforms and the output
+// rewriter — walks the program serially against the one checker returned by
+// Program.GetTypeChecker, and then asks that checker to resolve types in
+// nodes drawn from *every* source file. TypeScript-Go's multi-checker pool
+// affinitizes each file to a different checker and forbids mixing types
+// across them; a circular type whose declarations span files on different
+// checkers resolves to `any` on the borrowed checker. Pinning the pool to
+// one checker keeps prog.Checker consistent with how every file was checked
+// while leaving parse and emit parallel. Both EmitAll and EmitAllRaw
+// serialize the WriteFile callback under a mutex so the emit-stage rewriter
+// never observes the parallel emit either.
 func CreateProgramFromConfig(parsed *tsoptions.ParsedCommandLine, host shimcompiler.CompilerHost) (*shimcompiler.Program, []Diagnostic, error) {
   if parsed == nil {
     return nil, nil, fmt.Errorf("driver: nil parsed command line")
   }
+  forceSingleChecker(parsed)
   opts := shimcompiler.ProgramOptions{
     Config:                      parsed,
-    SingleThreaded:              core.TSTrue,
     Host:                        host,
     UseSourceOfProjectReference: true,
   }
@@ -249,6 +301,24 @@ func CreateProgramFromConfig(parsed *tsoptions.ParsedCommandLine, host shimcompi
   return p, nil, nil
 }
 
+// forceSingleChecker pins the TypeScript-Go checker pool to a single checker.
+//
+// ttsc's transform and rewrite phases run serially and obtain types through
+// the single checker that Program.GetTypeChecker hands back. Those phases
+// query types on nodes from arbitrary source files, so the checker must be
+// the same one that checked every file. A pool of size > 1 affinitizes files
+// to distinct checkers; resolving a type whose declarations cross that
+// boundary (e.g. a circular indexed-access alias) yields `any`. Parallel
+// parsing and emit are unaffected — they do not consult the checker count.
+func forceSingleChecker(parsed *tsoptions.ParsedCommandLine) {
+  options := parsed.ParsedConfig.CompilerOptions
+  if options.SingleThreaded == core.TSTrue {
+    return
+  }
+  one := 1
+  options.Checkers = &one
+}
+
 // LoadProgram is the one-shot convenience used by `ttsc`.
 // It parses the tsconfig, creates a program and a type-checker, and returns
 // the wrapped facade.
@@ -281,7 +351,15 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   }
   host := DefaultHost(cwd, fs)
 
-  parsed, diags, err := ParseTSConfig(fs, cwd, tsconfigPath, host)
+  cliOptions, cliDiags, err := parseTsgoArgs(options.TsgoArgs, host)
+  if err != nil {
+    return nil, nil, err
+  }
+  if len(cliDiags) > 0 {
+    return nil, cliDiags, nil
+  }
+
+  parsed, diags, err := ParseTSConfig(fs, cwd, tsconfigPath, host, cliOptions)
   if err != nil {
     return nil, nil, err
   }
@@ -297,6 +375,7 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   if options.OutDir != "" {
     overrideOutDir(cwd, parsed, options.OutDir)
   }
+  applyThreadingOptions(parsed, options.SingleThreaded, options.Checkers)
 
   tsProgram, _, _ := CreateProgramFromConfig(parsed, host)
 
@@ -333,6 +412,28 @@ func overrideOutDir(cwd string, parsed *tsoptions.ParsedCommandLine, outDir stri
   parsed.ParsedConfig.CompilerOptions.OutDir = tspath.ResolvePath(cwd, outDir)
 }
 
+// applyThreadingOptions forwards the CLI threading knobs onto the parsed
+// compiler options. ttsc mirrors tsgo here: `--singleThreaded` / `--checkers`
+// land in CompilerOptions, and both Program.SingleThreaded() and the checker
+// pool read them from there — ProgramOptions is left untouched, exactly as
+// tsgo's own CLI does. SingleThreaded wins over Checkers, matching the pool's
+// own precedence.
+//
+// Note that CreateProgramFromConfig calls forceSingleChecker afterwards, so a
+// `--checkers N` greater than 1 is recorded here but then clamped back to a
+// single checker: ttsc's serial transform/rewrite phases require one checker
+// (see forceSingleChecker). `--singleThreaded` still takes full effect.
+func applyThreadingOptions(parsed *tsoptions.ParsedCommandLine, singleThreaded bool, checkers int) {
+  options := parsed.ParsedConfig.CompilerOptions
+  if singleThreaded {
+    options.SingleThreaded = core.TSTrue
+  }
+  if checkers > 0 {
+    n := checkers
+    options.Checkers = &n
+  }
+}
+
 // sourcePreambleFS wraps a vfs.FS and prepends the preamble string to every
 // source file read by tsgo's parser. Declaration files (.d.ts etc.) are
 // excluded so injected code never appears in type definitions.

package/driver/rewrite.go

@@ -73,11 +73,24 @@ const RewriteSentinel = "/* @ttsc-rewritten */"
 // the output. Returns the tsgo diagnostics and any patch-time error. When
 // `writeFile` is nil, the patched JS is written to disk via the standard
 // tsgo WriteFile.
+//
+// `writeFile` does not need to be concurrency-safe: emit() funnels every
+// invocation through one mutex, so the callback never runs on two goroutines
+// at once even though TypeScript-Go emits files in parallel.
 func (p *Program) EmitAll(rs *RewriteSet, writeFile shimcompiler.WriteFile) (*shimcompiler.EmitResult, []Diagnostic, error) {
   return p.emit(rs, nil, writeFile)
 }
 
 // EmitAllRaw runs TypeScript-Go emit without ttsc output-text rewrites.
+//
+// `writeFile` does not need to be concurrency-safe: like EmitAll, EmitAllRaw
+// funnels every invocation through one mutex, so the callback never runs on
+// two goroutines at once even though TypeScript-Go emits files in parallel.
+// This is the contract a plugin's output rewriter relies on — it is the
+// emit-stage phase ttsc guarantees runs single-threaded (a plugin's WriteFile
+// is the standard place to carry per-file cursors or an output map), so ttsc
+// owns the serialization rather than pushing goroutine-safety onto every
+// plugin author. See the emit-concurrency contract in the plugin docs.
 func (p *Program) EmitAllRaw(writeFile shimcompiler.WriteFile) (*shimcompiler.EmitResult, []Diagnostic, error) {
   if p == nil || p.TSProgram == nil {
     return nil, nil, errors.New("driver: nil program")
@@ -85,11 +98,22 @@ func (p *Program) EmitAllRaw(writeFile shimcompiler.WriteFile) (*shimcompiler.Em
   if err := p.ApplyLinkedPlugins(); err != nil {
     return nil, nil, err
   }
-  wf := writeFile
-  if wf == nil {
-    wf = func(fileName, text string, data *shimcompiler.WriteFileData) error {
-      return DefaultWriteFile(fileName, text)
+  // TypeScript-Go's parallel emit invokes WriteFile once per emitted file,
+  // concurrently — one goroutine per source file. Serialize the whole callback
+  // under wfMu so a plugin's output rewriter sees one writer at a time: a
+  // callback that mutates shared state (e.g. @nestia/core's per-file rewrite
+  // cursors and runtime-alias cache) would otherwise trip `fatal error:
+  // concurrent map read and map write`. The callback is cheap I/O, so
+  // serializing it costs ~nothing while parse/check/emit-text still parallelize
+  // — the same trade EmitAll makes for its own WriteFile.
+  var wfMu sync.Mutex
+  wf := func(fileName, text string, data *shimcompiler.WriteFileData) error {
+    wfMu.Lock()
+    defer wfMu.Unlock()
+    if writeFile != nil {
+      return writeFile(fileName, text, data)
     }
+    return DefaultWriteFile(fileName, text)
   }
   result := p.TSProgram.Emit(context.Background(), shimcompiler.EmitOptions{
     WriteFile: wf,
@@ -114,7 +138,18 @@ func (p *Program) emit(rs *RewriteSet, target *ast.SourceFile, writeFile shimcom
     rs = NewRewriteSet()
   }
   cursors := map[string]int{}
+  // TypeScript-Go's parallel emit invokes this WriteFile callback once per
+  // emitted file, concurrently — one goroutine per source file. Serialize the
+  // whole callback body under wfMu: the `cursors` map would otherwise trip
+  // `fatal error: concurrent map writes`, and the wrapped `writeFile` (which a
+  // caller may back with its own non-thread-safe state, e.g. api-compile's
+  // output map) must likewise see one writer at a time. The patch work here is
+  // cheap, so serializing only the callback costs ~nothing while parsing,
+  // checking, and emit-text generation still parallelize.
+  var wfMu sync.Mutex
   wf := func(fileName, text string, data *shimcompiler.WriteFileData) error {
+    wfMu.Lock()
+    defer wfMu.Unlock()
     // A patched file is idempotent: once the sentinel exists, the emitted text
     // is passed through unchanged. This matters for watch/rebuild loops and
     // tests that re-run emit over the same output directory.

package/lib/compiler/internal/project/resolveProjectConfig.js

@@ -26,6 +26,24 @@ function resolveProjectConfig(opts = {}) {
         if (!node_fs_1.default.existsSync(resolved)) {
             throw new Error(`ttsc: tsconfig not found: ${resolved}`);
         }
+        // `-p <directory>` is the documented tsgo shorthand for the
+        // directory that contains a `tsconfig.json`. Mirror that — without
+        // this branch a forwarded `--tsconfig=sub` would feed the directory
+        // path into `readResolvedCompilerOptions`, which calls
+        // `fs.readFileSync` and throws `EISDIR` (the RCA's predicted
+        // RC-3 §5 #2 bug, pinned by
+        // `test_ttsc_dash_p_directory_path_is_accepted`).
+        if (isDirectory(resolved)) {
+            const tsconfigInDir = node_path_1.default.join(resolved, "tsconfig.json");
+            if (node_fs_1.default.existsSync(tsconfigInDir)) {
+                return resolveRealPath(tsconfigInDir);
+            }
+            const jsconfigInDir = node_path_1.default.join(resolved, "jsconfig.json");
+            if (node_fs_1.default.existsSync(jsconfigInDir)) {
+                return resolveRealPath(jsconfigInDir);
+            }
+            throw new Error(`ttsc: directory has no tsconfig.json / jsconfig.json: ${resolved}`);
+        }
         return resolveRealPath(resolved);
     }
     const start = opts.file

package/lib/compiler/internal/project/resolveProjectConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveProjectConfig.js","sourceRoot":"","sources":["../../../../src/compiler/internal/project/resolveProjectConfig.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAI7B;;;;;;;;;;;;GAYG;AACH,8BACE,IAAI,GAA+B,EAAE;IAErC,MAAM,GAAG,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI;QACrB,CAAC,CAAC,eAAe,CAAC,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC,CAAC,GAAG,CAAC;IACR,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,qEAAqE,IAAI,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,sEAAsE;AACtE,SAAS,mBAAmB,CAAC,GAAW,EAAE,MAAc;IACtD,OAAO,mBAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,mBAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,OAAO,iBAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,KAAwB;IACpD,IAAI,OAAO,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,iBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7B,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,CAAC;QACH,OAAO,iBAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"resolveProjectConfig.js","sourceRoot":"","sources":["../../../../src/compiler/internal/project/resolveProjectConfig.ts"],"names":[],"mappings":"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"}

package/lib/compiler/internal/runBuild.d.ts

@@ -1,14 +1,15 @@
 import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+type RunBuildOptions = TtscBuildOptions & {
+    skipDiagnosticsCheck?: boolean;
+    forceListEmittedFiles?: boolean;
+};
 /**
  * Run `ttsc` against a tsconfig. Returns once the binary exits so the CLI can
  * decide how to surface diagnostics. Does not throw on non-zero exit.
  */
-export declare function runBuild(options?: TtscBuildOptions & {
-    skipDiagnosticsCheck?: boolean;
-    forceListEmittedFiles?: boolean;
-}): TtscBuildResult;
+export declare function runBuild(options?: RunBuildOptions): TtscBuildResult;
 /**
  * Merge two `TtscBuildResult` values into one.
  *