ttsc 0.26.2 → 0.27.0

package/driver/plugins.go

@@ -5,7 +5,9 @@ import (
   "fmt"
   "os"
   "path/filepath"
+  "sort"
   "strings"
+  "sync"
 )
 
 // LinkedPluginsEnv is the environment variable ttsc sets to pass the JSON
@@ -27,6 +29,44 @@ const LinkedPluginsEnv = "TTSC_LINKED_PLUGINS_JSON"
 // still receive it.
 const PluginConfigDirEnv = "TTSC_PLUGIN_CONFIG_DIR"
 
+// TsgoArgsEnv is the environment variable through which the ttsc launcher
+// passes the tsgo CLI flags it did not consume itself (`--strict`,
+// `--declaration`, the single-file lane's output containment, …) to a native
+// sidecar. The value is a JSON array of argv tokens; an empty or absent value
+// means nothing was forwarded.
+//
+// It rides the environment for the same reason PluginConfigDirEnv does, only
+// with sharper consequences. The payload used to travel as a `--tsgo-args`
+// flag, which #113 appended to a plugin protocol third-party hosts had already
+// frozen. A Go `flag.FlagSet` created with `flag.ContinueOnError` treats an
+// undeclared flag as fatal, so every sidecar built before #113 answered
+// `flag provided but not defined: -tsgo-args` and exited 2 — including on
+// `ttsc <file.ts>`, where the launcher forwards its own output-containment
+// flags and the user passed nothing at all (issue #1188). An unknown
+// environment variable is inert to every host; an unknown flag is fatal to all
+// of them. ttsc's own hosts still accept `--tsgo-args` so an older launcher
+// paired with a newer host keeps working.
+const TsgoArgsEnv = "TTSC_TSGO_ARGS"
+
+// TsgoArgsFromEnv decodes the forwarded tsgo argv the launcher published in
+// TsgoArgsEnv. An absent or whitespace-only value yields a nil slice and no
+// error, so a host can call this unconditionally.
+//
+// Hosts that also declare a `--tsgo-args` flag should prefer the explicit flag
+// value and fall back to this; LoadProgram already does that for every
+// driver-based host.
+func TsgoArgsFromEnv() ([]string, error) {
+  raw := strings.TrimSpace(os.Getenv(TsgoArgsEnv))
+  if raw == "" {
+    return nil, nil
+  }
+  var args []string
+  if err := json.Unmarshal([]byte(raw), &args); err != nil {
+    return nil, fmt.Errorf("ttsc driver: invalid %s: %w", TsgoArgsEnv, err)
+  }
+  return args, nil
+}
+
 // PluginConfigBaseDir returns the directory where a plugin anchors its
 // config-file discovery walk and resolves relative "configFile" paths.
 // The explicit PluginConfigDirEnv channel wins when set; otherwise the
@@ -60,6 +100,90 @@ type PluginContext struct {
   Cwd      string
   Entry    PluginEntry
   Tsconfig string
+
+  reportHostInput                func(string)
+  reportHostInputHash            func(string, *string)
+  reportHostInputHashUnknown     func(string)
+  reportHostInputRealpath        func(string, *string)
+  reportHostInputRealpathUnknown func(string)
+}
+
+// ReportHostInputHash declares the exact file state consumed by a native
+// plugin. hash is a lowercase SHA-256 digest for an observed file and nil for
+// a missing candidate. Conflicting observations are retained as host inputs
+// but omitted from PluginHostInputHashes, forcing persistent adapters to
+// decline narrow reuse without failing the transform.
+func (ctx PluginContext) ReportHostInputHash(file string, hash *string) {
+  if ctx.reportHostInputHash == nil || strings.TrimSpace(file) == "" {
+    return
+  }
+  if !filepath.IsAbs(file) {
+    file = filepath.Join(ctx.Cwd, file)
+  }
+  file = filepath.Clean(file)
+  if hash != nil && !isLowerSHA256(*hash) {
+    if ctx.reportHostInputHashUnknown != nil {
+      ctx.reportHostInputHashUnknown(file)
+    } else if ctx.reportHostInput != nil {
+      ctx.reportHostInput(file)
+    }
+    return
+  }
+  ctx.reportHostInputHash(file, hash)
+}
+
+// ReportHostInputRealpath declares the physical path resolved while a native
+// plugin consumed file. realpath is absolute for an observed path and nil for
+// a missing candidate. Conflicting observations remain host inputs but are
+// omitted from PluginHostInputRealpaths so adapters cannot attach an earlier
+// result to a retargeted symlink or junction.
+func (ctx PluginContext) ReportHostInputRealpath(file string, realpath *string) {
+  if ctx.reportHostInputRealpath == nil || strings.TrimSpace(file) == "" {
+    return
+  }
+  if !filepath.IsAbs(file) {
+    file = filepath.Join(ctx.Cwd, file)
+  }
+  file = filepath.Clean(file)
+  if realpath != nil {
+    if strings.TrimSpace(*realpath) == "" || !filepath.IsAbs(*realpath) {
+      if ctx.reportHostInputRealpathUnknown != nil {
+        ctx.reportHostInputRealpathUnknown(file)
+      } else if ctx.reportHostInput != nil {
+        ctx.reportHostInput(file)
+      }
+      return
+    }
+    resolved := filepath.Clean(*realpath)
+    realpath = &resolved
+  }
+  ctx.reportHostInputRealpath(file, realpath)
+}
+
+func isLowerSHA256(value string) bool {
+  if len(value) != 64 {
+    return false
+  }
+  for _, char := range value {
+    if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
+      return false
+    }
+  }
+  return true
+}
+
+// ReportHostInput declares an absolute file whose content or presence was
+// consumed while the native plugin evaluated configuration. Native transform
+// envelopes expose the generation-wide union so persistent hosts can invalidate
+// without re-evaluating plugin config on the JavaScript side.
+func (ctx PluginContext) ReportHostInput(file string) {
+  if ctx.reportHostInput == nil || strings.TrimSpace(file) == "" {
+    return
+  }
+  if !filepath.IsAbs(file) {
+    file = filepath.Join(ctx.Cwd, file)
+  }
+  ctx.reportHostInput(filepath.Clean(file))
 }
 
 // SourcePreamblePlugin can inject source text before TypeScript-Go parses the
@@ -92,9 +216,244 @@ type EmitTransformPlugin interface {
 type linkedPluginState struct {
   cwd      string
   entries  []PluginEntry
+  inputs   *pluginHostInputScopes
   tsconfig string
 }
 
+// pluginHostInputScopes keeps one observation set per plugin hook. A hash from
+// one hook cannot prove another hook's same-file dependency when that hook only
+// reported the path, while ReportHostInput followed by ReportHostInputHash in
+// one hook remains one complete observation.
+type pluginHostInputScopes struct {
+  mu     sync.Mutex
+  scopes []*pluginHostInputs
+}
+
+type pluginHostInputs struct {
+  files     map[string]struct{}
+  hashes    map[string]pluginHostInputHash
+  realpaths map[string]pluginHostInputHash
+  mu        sync.Mutex
+}
+
+type pluginHostInputHash struct {
+  hash  *string
+  known bool
+}
+
+func newPluginHostInputScopes() *pluginHostInputScopes {
+  return &pluginHostInputScopes{}
+}
+
+func newPluginHostInputs() *pluginHostInputs {
+  return &pluginHostInputs{
+    files:     map[string]struct{}{},
+    hashes:    map[string]pluginHostInputHash{},
+    realpaths: map[string]pluginHostInputHash{},
+  }
+}
+
+func (inputs *pluginHostInputScopes) newScope() *pluginHostInputs {
+  scope := newPluginHostInputs()
+  if inputs == nil {
+    return scope
+  }
+  inputs.mu.Lock()
+  inputs.scopes = append(inputs.scopes, scope)
+  inputs.mu.Unlock()
+  return scope
+}
+
+func (inputs *pluginHostInputScopes) snapshot() []*pluginHostInputs {
+  if inputs == nil {
+    return nil
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  return append([]*pluginHostInputs(nil), inputs.scopes...)
+}
+
+func (inputs *pluginHostInputs) addHash(file string, hash *string) {
+  if inputs == nil {
+    return
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  inputs.files[file] = struct{}{}
+  previous, exists := inputs.hashes[file]
+  if !exists {
+    inputs.hashes[file] = pluginHostInputHash{hash: cloneStringPointer(hash), known: true}
+    return
+  }
+  if !previous.known || !sameStringPointer(previous.hash, hash) {
+    inputs.hashes[file] = pluginHostInputHash{known: false}
+  }
+}
+
+func (inputs *pluginHostInputs) invalidateHash(file string) {
+  if inputs == nil {
+    return
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  inputs.files[file] = struct{}{}
+  inputs.hashes[file] = pluginHostInputHash{known: false}
+}
+
+func (inputs *pluginHostInputs) addRealpath(file string, realpath *string) {
+  if inputs == nil {
+    return
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  inputs.files[file] = struct{}{}
+  previous, exists := inputs.realpaths[file]
+  if !exists {
+    inputs.realpaths[file] = pluginHostInputHash{hash: cloneStringPointer(realpath), known: true}
+    return
+  }
+  if !previous.known || !sameStringPointer(previous.hash, realpath) {
+    inputs.realpaths[file] = pluginHostInputHash{known: false}
+  }
+}
+
+func (inputs *pluginHostInputs) invalidateRealpath(file string) {
+  if inputs == nil {
+    return
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  inputs.files[file] = struct{}{}
+  inputs.realpaths[file] = pluginHostInputHash{known: false}
+}
+
+func cloneStringPointer(value *string) *string {
+  if value == nil {
+    return nil
+  }
+  cloned := *value
+  return &cloned
+}
+
+func sameStringPointer(left, right *string) bool {
+  if left == nil || right == nil {
+    return left == nil && right == nil
+  }
+  return *left == *right
+}
+
+func (inputs *pluginHostInputs) add(file string) {
+  if inputs == nil {
+    return
+  }
+  inputs.mu.Lock()
+  inputs.files[file] = struct{}{}
+  inputs.mu.Unlock()
+}
+
+func (inputs *pluginHostInputs) snapshot() (map[string]struct{}, map[string]pluginHostInputHash, map[string]pluginHostInputHash) {
+  if inputs == nil {
+    return nil, nil, nil
+  }
+  inputs.mu.Lock()
+  defer inputs.mu.Unlock()
+  files := make(map[string]struct{}, len(inputs.files))
+  for file := range inputs.files {
+    files[file] = struct{}{}
+  }
+  hashes := make(map[string]pluginHostInputHash, len(inputs.hashes))
+  for file, observation := range inputs.hashes {
+    hashes[file] = pluginHostInputHash{
+      hash:  cloneStringPointer(observation.hash),
+      known: observation.known,
+    }
+  }
+  realpaths := make(map[string]pluginHostInputHash, len(inputs.realpaths))
+  for file, observation := range inputs.realpaths {
+    realpaths[file] = pluginHostInputHash{
+      hash:  cloneStringPointer(observation.hash),
+      known: observation.known,
+    }
+  }
+  return files, hashes, realpaths
+}
+
+func (inputs *pluginHostInputScopes) list() []string {
+  union := map[string]struct{}{}
+  for _, scope := range inputs.snapshot() {
+    files, _, _ := scope.snapshot()
+    for file := range files {
+      union[file] = struct{}{}
+    }
+  }
+  files := make([]string, 0, len(union))
+  for file := range union {
+    files = append(files, file)
+  }
+  sort.Strings(files)
+  return files
+}
+
+func (inputs *pluginHostInputScopes) hashList() map[string]*string {
+  combined := map[string]pluginHostInputHash{}
+  for _, scope := range inputs.snapshot() {
+    files, hashes, _ := scope.snapshot()
+    for file := range files {
+      observation, exists := hashes[file]
+      if !exists || !observation.known {
+        combined[file] = pluginHostInputHash{known: false}
+        continue
+      }
+      previous, exists := combined[file]
+      if !exists {
+        combined[file] = observation
+      } else if !previous.known || !sameStringPointer(previous.hash, observation.hash) {
+        combined[file] = pluginHostInputHash{known: false}
+      }
+    }
+  }
+  hashes := map[string]*string{}
+  for file, observation := range combined {
+    if observation.known {
+      hashes[file] = cloneStringPointer(observation.hash)
+    }
+  }
+  if len(hashes) == 0 {
+    return nil
+  }
+  return hashes
+}
+
+func (inputs *pluginHostInputScopes) realpathList() map[string]*string {
+  combined := map[string]pluginHostInputHash{}
+  for _, scope := range inputs.snapshot() {
+    files, _, realpaths := scope.snapshot()
+    for file := range files {
+      observation, exists := realpaths[file]
+      if !exists || !observation.known {
+        combined[file] = pluginHostInputHash{known: false}
+        continue
+      }
+      previous, exists := combined[file]
+      if !exists {
+        combined[file] = observation
+      } else if !previous.known || !sameStringPointer(previous.hash, observation.hash) {
+        combined[file] = pluginHostInputHash{known: false}
+      }
+    }
+  }
+  realpaths := map[string]*string{}
+  for file, observation := range combined {
+    if observation.known {
+      realpaths[file] = cloneStringPointer(observation.hash)
+    }
+  }
+  if len(realpaths) == 0 {
+    return nil
+  }
+  return realpaths
+}
+
 var pluginRegistry []any
 
 // RegisterPlugin registers a driver-level plugin implementation. Linked Go
@@ -113,7 +472,7 @@ func RegisterPlugin(plugin any) {
 func loadLinkedPluginState(cwd, tsconfigPath string) (linkedPluginState, error) {
   input := strings.TrimSpace(os.Getenv(LinkedPluginsEnv))
   if input == "" {
-    return linkedPluginState{cwd: cwd, tsconfig: tsconfigPath}, nil
+    return linkedPluginState{cwd: cwd, inputs: newPluginHostInputScopes(), tsconfig: tsconfigPath}, nil
   }
   var entries []PluginEntry
   if err := json.Unmarshal([]byte(input), &entries); err != nil {
@@ -122,6 +481,7 @@ func loadLinkedPluginState(cwd, tsconfigPath string) (linkedPluginState, error)
   return linkedPluginState{
     cwd:      cwd,
     entries:  entries,
+    inputs:   newPluginHostInputScopes(),
     tsconfig: tsconfigPath,
   }, nil
 }
@@ -218,9 +578,29 @@ func registeredPlugin(index int) (any, bool) {
 
 // context builds the PluginContext the driver passes to each plugin hook.
 func (state linkedPluginState) context(entry PluginEntry) PluginContext {
+  inputs := state.inputs.newScope()
   return PluginContext{
-    Cwd:      state.cwd,
-    Entry:    entry,
-    Tsconfig: state.tsconfig,
+    Cwd:                            state.cwd,
+    Entry:                          entry,
+    Tsconfig:                       state.tsconfig,
+    reportHostInput:                inputs.add,
+    reportHostInputHash:            inputs.addHash,
+    reportHostInputHashUnknown:     inputs.invalidateHash,
+    reportHostInputRealpath:        inputs.addRealpath,
+    reportHostInputRealpathUnknown: inputs.invalidateRealpath,
   }
 }
+
+// hostInputs returns the exact native configuration inputs reported in this
+// generation.
+func (state linkedPluginState) hostInputs() []string {
+  return state.inputs.list()
+}
+
+func (state linkedPluginState) hostInputHashes() map[string]*string {
+  return state.inputs.hashList()
+}
+
+func (state linkedPluginState) hostInputRealpaths() map[string]*string {
+  return state.inputs.realpathList()
+}

package/driver/program.go

@@ -197,6 +197,7 @@ type Program struct {
   checkerRelease  func()
   Host            shimcompiler.CompilerHost
   FS              vfs.FS
+  inputObserver   *inputObservationFS
   SourcePreamble  string
   plugins         linkedPluginState
   pluginsApplied  bool
@@ -263,6 +264,23 @@ func ParseTSConfig(fs vfs.FS, cwd, tsconfigPath string, host shimcompiler.Compil
   return parsed, nil, nil
 }
 
+// resolveTsgoArgs picks the forwarded tsgo argv for this load: the caller's
+// explicit LoadProgramOptions.TsgoArgs when it has one, otherwise whatever the
+// launcher published in TsgoArgsEnv.
+//
+// The explicit value wins so a host that declares its own `--tsgo-args` flag
+// (cmd/ttsc, the utility host, @ttsc/lint) keeps deciding for itself, and an
+// embedder that deliberately passes an empty argv is not overridden by an
+// environment variable an ancestor ttsc process happened to set. The fallback
+// is what carries the payload into a third-party sidecar whose flag set does
+// not declare `--tsgo-args` at all — see TsgoArgsEnv and issue #1188.
+func resolveTsgoArgs(explicit []string) ([]string, error) {
+  if len(explicit) > 0 {
+    return explicit, nil
+  }
+  return TsgoArgsFromEnv()
+}
+
 // 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
@@ -357,6 +375,8 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   if fs == nil {
     fs = DefaultFS()
   }
+  inputObserver := newInputObservationFS(fs)
+  fs = inputObserver
   if options.SourcePreamble != "" {
     fs = sourcePreambleFS{
       FS:       fs,
@@ -365,7 +385,11 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
   }
   host := DefaultHost(cwd, fs)
 
-  cliOptions, cliDiags, err := parseTsgoArgs(options.TsgoArgs, host)
+  tsgoArgs, err := resolveTsgoArgs(options.TsgoArgs)
+  if err != nil {
+    return nil, nil, err
+  }
+  cliOptions, cliDiags, err := parseTsgoArgs(tsgoArgs, host)
   if err != nil {
     return nil, nil, err
   }
@@ -401,6 +425,7 @@ func LoadProgram(cwd, tsconfigPath string, options LoadProgramOptions) (*Program
     checkerRelease: done,
     Host:           host,
     FS:             fs,
+    inputObserver:  inputObserver,
     SourcePreamble: options.SourcePreamble,
   }
   prog.plugins = pluginState
@@ -563,6 +588,34 @@ func (p *Program) HasLinkedProgramPlugins() bool {
   return p != nil && p.plugins.hasProgramPlugins()
 }
 
+// PluginHostInputs returns the generation-wide native configuration files
+// reported by linked plugins while this Program was loaded or transformed.
+func (p *Program) PluginHostInputs() []string {
+  if p == nil {
+    return nil
+  }
+  return p.plugins.hostInputs()
+}
+
+// PluginHostInputHashes returns evaluation-time fingerprints for the subset of
+// native host inputs whose exact state plugins reported without conflict.
+func (p *Program) PluginHostInputHashes() map[string]*string {
+  if p == nil {
+    return nil
+  }
+  return p.plugins.hostInputHashes()
+}
+
+// PluginHostInputRealpaths returns evaluation-time physical identities for the
+// subset of native host inputs whose symlink or junction target was observed
+// without conflict.
+func (p *Program) PluginHostInputRealpaths() map[string]*string {
+  if p == nil {
+    return nil
+  }
+  return p.plugins.hostInputRealpaths()
+}
+
 // Diagnostics returns project diagnostics that must block compilation or
 // runtime execution before any JavaScript is emitted or evaluated.
 func (p *Program) Diagnostics() []Diagnostic {

package/driver/resolution_candidates.go

@@ -23,9 +23,10 @@ type ModuleResolutionContext struct {
 
 // SupersedingModuleCandidates returns, per source-file envelope key, the
 // resolution candidates strictly ahead of each module target the loaded
-// program selected. A missing member can therefore become a freshness input
-// without making the whole resolution search (including lower-priority paths)
-// an invalidation input.
+// program selected. When the selected target is reported by physical path, it
+// also retains that candidate's lexical spelling. A missing member or a link
+// retarget can therefore become a freshness input without making the whole
+// resolution search (including lower-priority paths) an invalidation input.
 //
 // Candidate enumeration is host-owned. It mirrors the resident graph session's
 // speculation for relative modules, paths, rootDirs, package imports/exports,
@@ -75,7 +76,10 @@ func SupersedingModuleCandidates(prog *Program, cwd string) map[string][]string
 }
 
 // ModuleResolutionPredecessors returns the paths in the host-owned candidate
-// search that precede resolvedFileName. An unresolved specifier keeps the full
+// search that precede resolvedFileName. When the compiler reports the winner by
+// physical realpath, the result also retains that selected candidate's lexical
+// spelling: retargeting its symlink/junction can change resolution without
+// changing the old or new target bytes. An unresolved specifier keeps the full
 // candidate list through ModuleResolutionCandidates; a resolved specifier must
 // not track a lower-priority path because creating it cannot alter resolution.
 func ModuleResolutionPredecessors(
@@ -101,7 +105,11 @@ func ModuleResolutionPredecessors(
   // spellings already agree pays nothing for it.
   for index, candidate := range candidates {
     if sameExistingPath(candidate, resolvedFileName) {
-      return compactStringsInOrder(candidates[:index])
+      end := index
+      if !sameCandidatePath(candidate, resolvedFileName, caseSensitive) {
+        end++
+      }
+      return compactStringsInOrder(candidates[:end])
     }
   }
   // Never widen freshness to candidates whose precedence relative to the

package/driver/rewrite.go

@@ -129,7 +129,7 @@ func (p *Program) EmitAllRaw(writeFile shimcompiler.WriteFile) (*shimcompiler.Em
     }
     return DefaultWriteFile(fileName, text)
   }
-  result := p.TSProgram.Emit(context.Background(), shimcompiler.EmitOptions{
+  result := p.emitProgram(shimcompiler.EmitOptions{
     WriteFile: wf,
   })
   return result, p.convertProgramDiagnostics(result.Diagnostics), nil
@@ -197,13 +197,56 @@ func (p *Program) emit(rs *RewriteSet, target *ast.SourceFile, writeFile shimcom
     return DefaultWriteFile(fileName, patched)
   }
 
-  result := p.TSProgram.Emit(context.Background(), shimcompiler.EmitOptions{
+  result := p.emitProgram(shimcompiler.EmitOptions{
     TargetSourceFile: target,
     WriteFile:        wf,
   })
   return result, p.convertProgramDiagnostics(result.Diagnostics), nil
 }
 
+// emitProgram runs one whole-program or single-file emit, taking tsgo's
+// incremental lane when the resolved compiler options ask for build
+// information.
+//
+// tsgo's own CLI branches the same way — `performIncrementalCompilation` vs
+// `performCompilation`, on `CompilerOptions.IsIncremental()` — but it branches
+// in `internal/execute`, which a host constructing its Program in-process never
+// enters. ttsc always took the plain branch, so `incremental`, `composite`, and
+// `tsBuildInfoFile` parsed, resolved, and then vanished: a plugin-carrying
+// project emitted its JavaScript and no `.tsbuildinfo` at all (issue #1188).
+// `driver/emit_containment.go` had already exempted `.tsbuildinfo` from the
+// outDir guard for a write that could not happen.
+//
+// A single-file emit stays on the plain lane. Build information describes a
+// whole program, and tsgo's incremental program returns early on a
+// `TargetSourceFile` request without writing any, so routing it there would
+// only add a snapshot computation nothing reads.
+func (p *Program) emitProgram(options shimcompiler.EmitOptions) *shimcompiler.EmitResult {
+  ctx := context.Background()
+  if options.TargetSourceFile == nil && p.emitsBuildInfo() {
+    return shimcompiler.EmitFreshWithBuildInfo(ctx, p.TSProgram, options)
+  }
+  return p.TSProgram.Emit(ctx, options)
+}
+
+// emitsBuildInfo reports whether this program's resolved options ask tsgo to
+// write build information.
+//
+// The question is delegated to `CompilerOptions.IsIncremental`, the same
+// predicate tsgo's own CLI branches on, rather than restated as
+// `Incremental || Composite` here: a second copy of the rule is a second thing
+// to keep in step with upstream.
+func (p *Program) emitsBuildInfo() bool {
+  if p == nil || p.TSProgram == nil {
+    return false
+  }
+  options := p.TSProgram.Options()
+  if options == nil {
+    return false
+  }
+  return options.IsIncremental()
+}
+
 // DefaultWriteFile is the default disk writer used when EmitAll's caller does not
 // supply a custom WriteFile callback.
 func DefaultWriteFile(fileName, text string) error {

package/lib/TtscCompiler.d.ts

@@ -48,15 +48,16 @@ export declare class TtscCompiler {
     /**
      * Remove compiled cache artifacts for this compiler instance.
      *
-     * Removes the resolved cache root (which holds both the plugin binaries and,
-     * when ttsc-owned, the Go build cache), a ttsc-owned Go build cache that
-     * lives outside that root (`TTSC_GO_CACHE_DIR`), and the two legacy
-     * project-local caches. A user-provided `GOCACHE` is never removed. The cache
+     * Removes an explicit `cacheDir` wholesale. Otherwise removes the plugin
+     * binary subdirectory, a safely identified ttsc-owned Go build cache
+     * (including an external `TTSC_GO_CACHE_DIR`), and the two legacy
+     * project-local caches. A user-provided `GOCACHE` is never removed. Every
+     * resolved deletion target is validated before the first removal. The cache
      * location comes from this instance's `cacheDir` and environment
      * (`TTSC_CACHE_DIR` / `TTSC_GO_CACHE_DIR`), defaulting to
-     * `<workspaceRoot>/node_modules/.cache/ttsc`. An explicit cache directory
-     * that equals or contains the project, or names a filesystem root, is
-     * rejected before any directory is removed.
+     * `<workspaceRoot>/node_modules/.cache/ttsc`. Any resolved cache target that
+     * equals or contains the project, or names a filesystem root, is rejected
+     * before any directory is removed.
      *
      * @returns Cache directories that were removed.
      */
@@ -107,10 +108,10 @@ export declare class TtscCompiler {
      * The effective environment for this instance's source-plugin builds and
      * clean targets: `context.env` merged over `process.env`, matching the
      * documented {@link ITtscCompilerContext.env} contract that child compiler,
-     * native-plugin, and native-host processes already receive. Returned as a
-     * fresh object so callers never mutate the shared `process.env`; when no
-     * `context.env` was supplied this is a plain copy of `process.env`, so CLI /
-     * default behavior is unchanged.
+     * native-plugin, native-host, and isolated descriptor processes already
+     * receive. Returned as a fresh object so callers never mutate the shared
+     * `process.env`; when no `context.env` was supplied this is a plain copy of
+     * `process.env`, so CLI / default behavior is unchanged.
      */
     private resolveEffectiveEnv;
 }