@ttsc/lint 0.12.3 → 0.13.0

package/linthost/fix.go

@@ -1,3 +1,10 @@
+// Autofix orchestration for the `@ttsc/lint fix` subcommand.
+//
+// RunFix drives the fix cascade: it repeatedly runs the native lint engine
+// and applies any emitted TextEdit suggestions until no more fixable
+// findings remain or maxFixPasses is reached. After the cascade settles, it
+// runs a final diagnostic pass so remaining issues are surfaced in the
+// normal error stream.
 package linthost
 
 import (
@@ -9,10 +16,9 @@ import (
   shimdw "github.com/microsoft/typescript-go/shim/diagnosticwriter"
 )
 
-// maxFixPasses bounds the native cascade after the one-shot ESLint runtime
-// pass. Real-world cascades (no-var → prefer-const → eqeqeq …) settle in a
-// handful of passes; the cap exists so a buggy rule that re-reports its own
-// edit cannot loop forever.
+// maxFixPasses bounds the native fix cascade. Real-world cascades (no-var →
+// prefer-const → eqeqeq …) settle in a handful of passes; the cap exists so
+// a buggy rule that re-reports its own edit cannot loop forever.
 const maxFixPasses = 10
 
 // RunFix implements `@ttsc/lint fix` — apply autofixes, then report any
@@ -37,8 +43,11 @@ func runFix(opts *subcommandOpts) int {
     fmt.Fprintln(os.Stderr, err)
     return 2
   }
+  engine := NewEngineWithResolver(rules)
+  engine.SetSerial(opts.singleThreaded)
+  needsRuleChecker := engine.NeedsTypeChecker()
 
-  prog, code := loadFixProgram(opts)
+  prog, code := loadFixProgram(opts, needsRuleChecker)
   if code != 0 {
     return code
   }
@@ -49,16 +58,6 @@ func runFix(opts *subcommandOpts) int {
   }()
 
   totalFixes := 0
-  if fixed, err := runExternalESLintFixes(rules, opts.cwd, prog.userSourceFiles()); err != nil {
-    fmt.Fprintln(os.Stderr, err)
-    return 2
-  } else if fixed > 0 {
-    totalFixes += fixed
-    prog, code = reloadFixProgram(prog, opts)
-    if code != 0 {
-      return code
-    }
-  }
 
   // `ttsc fix` applies edits from BOTH lint-class rules and
   // format-class rules. The dual `ttsc format` subcommand exists for
@@ -67,7 +66,6 @@ func runFix(opts *subcommandOpts) int {
   // kinds of findings in one pass — no filtering needed here.
   cascadeConverged := false
   for pass := 0; pass < maxFixPasses; pass++ {
-    engine := NewEngineWithResolver(rules)
     findings := engine.Run(prog.userSourceFiles(), prog.checker)
     fixed, err := applyFindingFixes(opts.cwd, findings)
     if err != nil {
@@ -79,7 +77,7 @@ func runFix(opts *subcommandOpts) int {
       break
     }
     totalFixes += fixed
-    prog, code = reloadFixProgram(prog, opts)
+    prog, code = reloadFixProgram(prog, opts, needsRuleChecker)
     if code != 0 {
       return code
     }
@@ -96,15 +94,12 @@ func runFix(opts *subcommandOpts) int {
       maxFixPasses)
   }
 
-  engine := NewEngineWithResolver(rules)
-  astDiags, lintDiags, externalRan, err := collectDiagnostics(prog, engine)
+  astDiags, lintDiags, err := collectDiagnostics(prog, engine)
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
     return 2
   }
-  if !externalRan {
-    warnUnknownRules(os.Stderr, engine.UnknownRules())
-  }
+  warnUnknownRules(os.Stderr, engine.UnknownRules())
   errCount := shimdw.FormatMixedDiagnostics(os.Stderr, astDiags, lintDiags, opts.cwd)
   if errCount > 0 {
     return 2
@@ -121,10 +116,16 @@ func runFix(opts *subcommandOpts) int {
   return 0
 }
 
-func loadFixProgram(opts *subcommandOpts) (*program, int) {
+// loadFixProgram loads the TypeScript program for a fix/format pass with
+// NoEmit forced on. Returns (nil, 2) when loading or config parsing fails.
+func loadFixProgram(opts *subcommandOpts, needsRuleChecker bool) (*program, int) {
   prog, parseDiags, err := loadProgram(opts.cwd, opts.tsconfig, loadProgramOptions{
-    forceNoEmit: true,
-    outDir:      opts.outDir,
+    forceNoEmit:      true,
+    outDir:           opts.outDir,
+    needsRuleChecker: needsRuleChecker,
+    singleThreaded:   opts.singleThreaded,
+    checkers:         opts.checkers,
+    tsgoArgs:         opts.tsgoArgs,
   })
   if err != nil {
     fmt.Fprintf(os.Stderr, "@ttsc/lint: %v\n", err)
@@ -137,19 +138,29 @@ func loadFixProgram(opts *subcommandOpts) (*program, int) {
   return prog, 0
 }
 
-func reloadFixProgram(current *program, opts *subcommandOpts) (*program, int) {
+// reloadFixProgram closes `current` and loads a fresh program from disk.
+// Used between cascade passes so the engine sees edits applied in the
+// previous pass rather than stale in-memory AST nodes.
+func reloadFixProgram(current *program, opts *subcommandOpts, needsRuleChecker bool) (*program, int) {
   if current != nil {
     current.close()
   }
-  return loadFixProgram(opts)
+  return loadFixProgram(opts, needsRuleChecker)
 }
 
+// fileFixes groups all pending TextEdit suggestions for a single file.
+// `text` is the source content at the time the findings were collected;
+// byte offsets in `edits` are relative to this snapshot.
 type fileFixes struct {
   path  string
   text  string
   edits []TextEdit
 }
 
+// applyFindingFixes groups all fixable findings by file, resolves each
+// file path to an absolute form, then applies the edit batches in
+// deterministic order (sorted by path). Returns the total number of edits
+// written to disk.
 func applyFindingFixes(cwd string, findings []*Finding) (int, error) {
   byFile := map[string]*fileFixes{}
   for _, finding := range findings {
@@ -191,6 +202,10 @@ func applyFindingFixes(cwd string, findings []*Finding) (int, error) {
   return total, nil
 }
 
+// applyTextEditsToFile selects the non-overlapping edits from `edits`, applies
+// them to `source` in reverse order (right-to-left) to preserve earlier
+// offsets, and writes the result to `path`. Returns the number of edits
+// applied, or 0 when no edits survive selection.
 func applyTextEditsToFile(path, source string, edits []TextEdit) (int, error) {
   selected := selectTextEdits(len(source), edits)
   if len(selected) == 0 {
@@ -210,6 +225,11 @@ func applyTextEditsToFile(path, source string, edits []TextEdit) (int, error) {
   return len(selected), nil
 }
 
+// selectTextEdits filters and sorts `edits` into a non-overlapping
+// application sequence. Out-of-bounds edits and exact duplicates are
+// removed first; the remainder is sorted by start position then end
+// position (left to right). A greedy scan then keeps the earliest-starting
+// edit and drops any that overlap with it, producing a disjoint set.
 func selectTextEdits(sourceLen int, edits []TextEdit) []TextEdit {
   if len(edits) == 0 {
     return nil

package/linthost/flags_gen.go

@@ -0,0 +1,31 @@
+// 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 linthost
+
+// LintFlagAllowList 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 LintFlagAllowList = map[string]bool{
+  "checkers":       true,
+  "cwd":            true,
+  "emit":           false,
+  "file":           true,
+  "noEmit":         false,
+  "out":            true,
+  "outDir":         true,
+  "p":              true,
+  "plugins-json":   true,
+  "project":        true,
+  "quiet":          false,
+  "singleThreaded": false,
+  "tsconfig":       true,
+  "tsgo-args":      true,
+  "verbose":        false,
+}

package/linthost/format.go

@@ -33,14 +33,20 @@ func RunFormat(args []string) int {
   return runFormat(opts)
 }
 
+// runFormat is the internal implementation of RunFormat. It drives the
+// cascade loop and applies format-rule edits until convergence.
 func runFormat(opts *subcommandOpts) int {
   rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
     return 2
   }
+  resolver := formatCommandResolver{inner: rules}
+  engine := NewEngineWithResolver(resolver)
+  engine.SetSerial(opts.singleThreaded)
+  needsRuleChecker := engine.NeedsTypeChecker()
 
-  prog, code := loadFixProgram(opts)
+  prog, code := loadFixProgram(opts, needsRuleChecker)
   if code != 0 {
     return code
   }
@@ -53,7 +59,6 @@ func runFormat(opts *subcommandOpts) int {
   totalFixes := 0
   cascadeConverged := false
   for pass := 0; pass < maxFormatPasses; pass++ {
-    engine := NewEngineWithResolver(formatCommandResolver{inner: rules})
     findings := engine.Run(prog.userSourceFiles(), prog.checker)
     fixed, err := applyFindingFixes(opts.cwd, filterFormatFindings(findings))
     if err != nil {
@@ -65,7 +70,7 @@ func runFormat(opts *subcommandOpts) int {
       break
     }
     totalFixes += fixed
-    prog, code = reloadFixProgram(prog, opts)
+    prog, code = reloadFixProgram(prog, opts, needsRuleChecker)
     if code != 0 {
       return code
     }
@@ -89,15 +94,45 @@ func runFormat(opts *subcommandOpts) int {
   return 0
 }
 
+// formatCommandResolver wraps a RuleResolver and ensures every format-class
+// rule referenced in the loaded plugin options is activated at warn severity,
+// even if the user's config omitted it. This lets `ttsc format` format files
+// without requiring explicit rule declarations in the project config.
 type formatCommandResolver struct {
   inner RuleResolver
 }
 
+// ResolveRules implements RuleResolver. It delegates to the inner resolver
+// and then upgrades format-rule entries from off to warn so they are applied
+// even when the project config omits them.
+//
+// A user-authored entry whose `ignores` list matches `fileName` is honored
+// here even when the entry also carries a `rules` block: the engine already
+// skips that entry's rule contributions via `ConfigEntry.matchesFile`, so the
+// format command must skip its blanket format-rule upgrade as well. Without
+// this guard, `ttsc format` would rewrite files that the user explicitly
+// asked the lint config to ignore — the engine's lint walk would skip the
+// file but the formatter would still touch it.
+//
+// The symmetric guard applies to `files`: if every non-IgnoreOnly entry
+// carries a `files` filter and `fileName` matches none of them, the engine
+// would not run any rules on the file (`ConfigEntry.matchesFile` returns
+// false for every entry). The format command must skip its blanket
+// format-rule upgrade for the same reason — otherwise `ttsc format` would
+// rewrite files that fall outside every entry's scope, e.g. a `.json`
+// resolved into the program via `resolveJsonModule` when the only entry
+// targets `src/**/*.ts`.
 func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig {
   resolved := r.inner.ResolveRules(fileName)
   if resolved.Ignored {
     return resolved
   }
+  if r.fileIsIgnoredByEntry(fileName) {
+    return resolved
+  }
+  if !r.fileMatchesAnyEntry(fileName) {
+    return resolved
+  }
   if resolved.Rules == nil {
     resolved.Rules = RuleConfig{}
   }
@@ -109,6 +144,75 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
   return resolved
 }
 
+// fileIsIgnoredByEntry reports whether any non-IgnoreOnly entry in the inner
+// ConfigStore has an `ignores` glob that matches `fileName`. IgnoreOnly
+// entries are already handled by ResolvedRuleConfig.Ignored — they are
+// checked first by ConfigStore.ResolveRules and short-circuit the walk. This
+// helper covers the complementary case: an entry that carries both `rules`
+// and `ignores`, where the engine skips the entry's rule contributions via
+// `ConfigEntry.matchesFile` but the format command must learn the same fact
+// independently because its job is to upgrade format rules to `warn`, not to
+// read the engine's resolved severity map.
+func (r formatCommandResolver) fileIsIgnoredByEntry(fileName string) bool {
+  store, ok := r.inner.(*ConfigStore)
+  if !ok || store == nil {
+    return false
+  }
+  for _, entry := range store.entries {
+    if entry.IgnoreOnly {
+      continue
+    }
+    if entry.matchesIgnores(fileName) {
+      return true
+    }
+  }
+  return false
+}
+
+// fileMatchesAnyEntry reports whether `fileName` falls inside the `files`
+// scope of at least one non-IgnoreOnly entry. An entry without an explicit
+// `files` list matches every file by definition (eslint flat-config
+// semantics), so a config with any unrestricted non-IgnoreOnly entry returns
+// true for every file. The format command treats a `false` result the same
+// way the engine does: no entry contributes rules, so the blanket
+// format-rule upgrade must be skipped.
+//
+// Base cases:
+//
+//   - Empty entries slice: returns `true`. A store with no entries cannot
+//     skip a file by scope (the engine has nothing to walk), so format
+//     mode must be allowed to apply its default upgrade. Matching engine
+//     behavior at `ConfigStore.ResolveRules` for the same input
+//     (`Ignored = false`, empty rule map).
+//   - All entries are IgnoreOnly: returns `false`. No non-IgnoreOnly
+//     entry contributes a `files` scope, so the file is out-of-scope by
+//     construction.
+//   - Inner resolver is not a *ConfigStore: returns `true` (conservative
+//     default). The `files` concept is store-specific; an in-process
+//     custom resolver that does not surface a scope cannot have its
+//     rule-eligibility reasoned about from the outside, so the format
+//     upgrade applies the same as it does for an entry without `files`.
+func (r formatCommandResolver) fileMatchesAnyEntry(fileName string) bool {
+  store, ok := r.inner.(*ConfigStore)
+  if !ok || store == nil {
+    return true
+  }
+  if len(store.entries) == 0 {
+    return true
+  }
+  for _, entry := range store.entries {
+    if entry.IgnoreOnly {
+      continue
+    }
+    if entry.matchesFile(fileName) {
+      return true
+    }
+  }
+  return false
+}
+
+// ActiveRuleNames implements RuleResolver. Returns the union of the inner
+// resolver's active rules and every format-option rule that is registered.
 func (r formatCommandResolver) ActiveRuleNames() []string {
   active := map[string]struct{}{}
   for _, name := range r.inner.ActiveRuleNames() {
@@ -120,6 +224,8 @@ func (r formatCommandResolver) ActiveRuleNames() []string {
   return sortedKeys(active)
 }
 
+// EnabledRuleConfig implements RuleResolver. Merges the inner config with
+// the format-option rules so callers see the full active set.
 func (r formatCommandResolver) EnabledRuleConfig() RuleConfig {
   enabled := r.inner.EnabledRuleConfig()
   if enabled == nil {
@@ -133,10 +239,14 @@ func (r formatCommandResolver) EnabledRuleConfig() RuleConfig {
   return enabled
 }
 
+// RuleOptions implements RuleResolver by delegating directly to the inner resolver.
 func (r formatCommandResolver) RuleOptions(name string) json.RawMessage {
   return r.inner.RuleOptions(name)
 }
 
+// formatOptionRuleNames returns the sorted list of rule names from the inner
+// resolver's options that are registered as format rules. These are the rules
+// that formatCommandResolver promotes from off to warn.
 func (r formatCommandResolver) formatOptionRuleNames() []string {
   options := resolverOptions(r.inner)
   if len(options) == 0 {
@@ -152,6 +262,9 @@ func (r formatCommandResolver) formatOptionRuleNames() []string {
   return names
 }
 
+// resolverOptions extracts the raw options map from a resolver whose concrete
+// type exposes one. Returns nil for resolver types that don't carry per-rule
+// options (e.g. bare RuleConfig).
 func resolverOptions(resolver RuleResolver) RuleOptionsMap {
   switch r := resolver.(type) {
   case InlineRuleResolver:
@@ -163,11 +276,14 @@ func resolverOptions(resolver RuleResolver) RuleOptionsMap {
   }
 }
 
+// isRegisteredFormatRule reports whether `name` is both registered in the
+// global rule registry and tagged as a format rule via the FormatRule marker.
 func isRegisteredFormatRule(name string) bool {
   rule, ok := registered.rules[name]
   return ok && isFormatRule(rule)
 }
 
+// sortedKeys returns the sorted slice of keys from a string-keyed set.
 func sortedKeys(input map[string]struct{}) []string {
   names := make([]string, 0, len(input))
   for name := range input {

package/linthost/host.go

@@ -39,10 +39,25 @@ type loadProgramOptions struct {
   forceEmit   bool
   forceNoEmit bool
   outDir      string
+  // needsRuleChecker asks loadProgram to pin the checker pool and acquire the
+  // checker that type-aware lint rules receive through Context.Checker.
+  needsRuleChecker bool
+  // singleThreaded mirrors `tsgo --singleThreaded`: one checker, serial
+  // parse/check/emit.
+  singleThreaded bool
+  // checkers mirrors `tsgo --checkers`: type-checker pool size. Zero leaves
+  // TypeScript-Go's default; ignored when singleThreaded is set.
+  checkers int
+  // tsgoArgs carries tsgo CLI flags the `ttsc` launcher forwarded (`--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
 }
 
-// loadProgram parses the given tsconfig, builds a Program, and acquires a
-// type checker. Mirrors the canonical bootstrap pattern from
+// loadProgram parses the given tsconfig and builds a Program. When
+// needsRuleChecker is set, it also acquires a type checker for lint rules.
+// Mirrors the canonical bootstrap pattern from
 // `03-tsgo.md` — the only ttsc-specific bit is that `forceEmit`/
 // `forceNoEmit`/`outDir` overrides are merged into the parsed config
 // before the program is created so `--noEmit` and friends behave like
@@ -63,9 +78,14 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   fs := bundled.WrapFS(cachedvfs.From(osvfs.FS()))
   host := shimcompiler.NewCompilerHost(cwd, fs, bundled.LibPath(), nil, nil)
 
+  cliOptions, cliDiags := parseTsgoArgs(options.tsgoArgs, host)
+  if len(cliDiags) > 0 {
+    return nil, cliDiags, nil
+  }
+
   parsed, parseDiags := tsoptions.GetParsedCommandLineOfConfigFile(
     resolved,
-    &shimcore.CompilerOptions{},
+    cliOptions,
     nil,
     host,
     nil,
@@ -88,17 +108,34 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   if options.outDir != "" {
     overrideOutDir(cwd, parsed, options.outDir)
   }
+  applyThreading(parsed, options.singleThreaded, options.checkers)
+  if options.needsRuleChecker {
+    forceSingleChecker(parsed)
+  }
 
+  // SingleThreaded is left unset so the program keeps TypeScript-Go's parallel
+  // source parsing and parallel emit. For type-aware lint rules, the checker
+  // pool is pinned to a single checker (see forceSingleChecker): the lint
+  // engine walks files serially against the one checker GetTypeChecker hands
+  // back, and rules ask 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, so a type whose
+  // declarations span files on different checkers (e.g. a circular
+  // indexed-access alias) resolves to `any` on the borrowed checker. AST-only
+  // lint rules do not receive a checker, so they keep the user's checker pool.
   tsProgram := shimcompiler.NewProgram(shimcompiler.ProgramOptions{
     Config:                      parsed,
-    SingleThreaded:              shimcore.TSTrue,
     Host:                        host,
     UseSourceOfProjectReference: true,
   })
   if tsProgram == nil {
     return nil, nil, errors.New("compiler.NewProgram returned nil")
   }
-  checker, release := tsProgram.GetTypeChecker(context.Background())
+  var checker *shimchecker.Checker
+  var release func()
+  if options.needsRuleChecker {
+    checker, release = tsProgram.GetTypeChecker(context.Background())
+  }
   return &program{
     cwd:            cwd,
     tsProgram:      tsProgram,
@@ -108,6 +145,8 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   }, nil, nil
 }
 
+// close releases the type checker acquired by loadProgram. Safe to call on
+// a nil receiver and idempotent after the first call.
 func (p *program) close() {
   if p == nil {
     return
@@ -162,6 +201,8 @@ func (p *program) findSourceFile(target string) *shimast.SourceFile {
   return nil
 }
 
+// forceEmit clears the NoEmit and EmitDeclarationOnly flags so the
+// program emits JavaScript even when the tsconfig says otherwise.
 func forceEmit(parsed *tsoptions.ParsedCommandLine) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return
@@ -171,6 +212,9 @@ func forceEmit(parsed *tsoptions.ParsedCommandLine) {
   options.EmitDeclarationOnly = shimcore.TSFalse
 }
 
+// forceNoEmit sets the NoEmit flag regardless of what the tsconfig
+// specifies. Used by fix and check subcommands that must not write output
+// files as a side effect of type-checking.
 func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return
@@ -178,6 +222,72 @@ func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
   parsed.ParsedConfig.CompilerOptions.NoEmit = shimcore.TSTrue
 }
 
+// parseTsgoArgs runs forwarded tsgo CLI flags through TypeScript-Go's own
+// command-line parser, yielding a CompilerOptions overlay loadProgram merges
+// over the tsconfig — so a flag like `ttsc --strict` reaches the in-process
+// lint program even though @ttsc/lint never shells out to `tsgo`. Returns an
+// empty (non-nil) options value when there are no forwarded flags.
+func parseTsgoArgs(args []string, host shimcompiler.CompilerHost) (*shimcore.CompilerOptions, []*shimast.Diagnostic) {
+  if len(args) == 0 {
+    return &shimcore.CompilerOptions{}, nil
+  }
+  cli := tsoptions.ParseCommandLine(args, host)
+  if cli == nil {
+    return &shimcore.CompilerOptions{}, nil
+  }
+  if len(cli.Errors) > 0 {
+    return nil, cli.Errors
+  }
+  return cli.CompilerOptions(), nil
+}
+
+// applyThreading forwards the --singleThreaded / --checkers knobs onto the
+// parsed compiler options. ttsc mirrors tsgo here: the values land in
+// CompilerOptions, and both Program.SingleThreaded() and the checker pool read
+// them from there. SingleThreaded wins over Checkers, matching the pool.
+//
+// When a type-aware lint rule is active, loadProgram calls forceSingleChecker
+// afterwards, so a `--checkers N` greater than 1 is recorded here and then
+// clamped back to a single checker. AST-only lint runs keep the recorded
+// checker count. `--singleThreaded` still takes full effect.
+func applyThreading(parsed *tsoptions.ParsedCommandLine, singleThreaded bool, checkers int) {
+  if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+    return
+  }
+  options := parsed.ParsedConfig.CompilerOptions
+  if singleThreaded {
+    options.SingleThreaded = shimcore.TSTrue
+  }
+  if checkers > 0 {
+    n := checkers
+    options.Checkers = &n
+  }
+}
+
+// forceSingleChecker pins the TypeScript-Go checker pool to a single checker.
+//
+// The lint engine walks the program serially and obtains types through the
+// single checker GetTypeChecker hands back. Rules 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 yields `any`.
+// Parallel parsing and emit are unaffected — they do not consult the count.
+func forceSingleChecker(parsed *tsoptions.ParsedCommandLine) {
+  if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+    return
+  }
+  options := parsed.ParsedConfig.CompilerOptions
+  if options.SingleThreaded == shimcore.TSTrue {
+    return
+  }
+  one := 1
+  options.Checkers = &one
+}
+
+// overrideOutDir replaces the parsed config's OutDir with `outDir`.
+// Relative outDir values are resolved against `cwd`; absolute paths are
+// used as-is. Paths are converted to forward slashes for tsgo
+// compatibility.
 func overrideOutDir(cwd string, parsed *tsoptions.ParsedCommandLine, outDir string) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return