ttsc 0.19.3 → 0.20.0

package/internal/lspserver/lsp_proxy.go

@@ -12,6 +12,7 @@ import (
   "path/filepath"
   "strings"
   "sync"
+  "sync/atomic"
   "unicode/utf16"
   "unicode/utf8"
 )
@@ -36,8 +37,29 @@ const (
   methodFormatting         = "textDocument/formatting"
   methodDocumentSymbol     = "textDocument/documentSymbol"
   methodReferences         = "textDocument/references"
+  methodCompletion         = "textDocument/completion"
+  methodCompletionResolve  = "completionItem/resolve"
+  methodExit               = "exit"
+
+  // methodDidChangeWatchedFiles is the only notification an editor sends for a
+  // file it does not have open: a tsconfig edit, a generated file, a branch
+  // switch. The repository's own VS Code client registers a watcher for
+  // `**/{tsconfig,jsconfig}*.json`, which its documentSelector excludes, so
+  // those edits can reach ttsc through no other notification.
+  methodDidChangeWatchedFiles = "workspace/didChangeWatchedFiles"
+  // methodDidChangeConfiguration is the editor's own settings changing. The
+  // proxy forwards it untouched and reads it only as a signal that a plugin's
+  // completion corpus may have gone stale, since a rule can be enabled there.
+  methodDidChangeConfiguration = "workspace/didChangeConfiguration"
+  // methodLogMessage carries server-side notices to the editor's output
+  // channel. The proxy uses it for state the user has to act on and no other
+  // LSP message can express.
+  methodLogMessage = "window/logMessage"
 )
 
+// lspMessageTypeInfo is the LSP MessageType for an informational log message.
+const lspMessageTypeInfo = 3
+
 // formatDocumentCommand is the ttsc-owned workspace command that the lint
 // sidecar advertises for whole-document formatting. The textDocument/formatting
 // handler routes the cached editor buffer through this command so formatOnSave
@@ -102,8 +124,17 @@ type Proxy struct {
   upstreamWriteMu sync.Mutex // serializes writes to upstreamIn
   asyncErrCh      chan error
 
-  pendingMu                sync.Mutex
-  pendingActions           map[string]pendingCodeActionRequest
+  // editorExit records that the editor sent the LSP `exit` notification.
+  // RunLSPServer reads it to decide whether a failed upstream process is a
+  // fault to report or the expected end of an editor-requested shutdown; see
+  // editorRequestedExit.
+  editorExit atomic.Bool
+
+  pendingMu      sync.Mutex
+  pendingActions map[string]pendingCodeActionRequest
+  // pendingCompletions holds the plugin items computed for a forwarded
+  // completion request, keyed by request id, until upstream answers it.
+  pendingCompletions       map[string]pendingCompletionRequest
   pendingAugmentingActions map[string]struct{}
   pendingLocalActions      map[string]struct{}
   pendingCommands          map[string]struct{}
@@ -113,6 +144,15 @@ type Proxy struct {
   upstreamCodeActionProvider     bool
   upstreamDocumentSymbolProvider bool
   upstreamReferencesProvider     bool
+  // initializeAnswered records that the editor has received the augmented
+  // capabilities, which is what makes a later trigger character "late".
+  initializeAnswered bool
+  // advertisedCompletionTriggers is the trigger set the editor was told about:
+  // tsgo's own characters plus whatever the corpus contributed at that moment.
+  // A refresh that produces a trigger outside this set cannot reach the editor
+  // without a restart, so the proxy says so once per character.
+  advertisedCompletionTriggers map[string]struct{}
+  reportedCompletionTriggers   map[string]struct{}
 
   diagnosticsMu               sync.Mutex
   upstreamDiagnostics         map[string]cachedDiagnostics
@@ -161,7 +201,7 @@ func NewProxy(opts ProxyOptions) *Proxy {
   if source == nil {
     source = NullPluginSource{}
   }
-  return &Proxy{
+  proxy := &Proxy{
     editorIn:                       opts.EditorIn,
     editorOut:                      opts.EditorOut,
     upstreamIn:                     opts.UpstreamIn,
@@ -187,6 +227,16 @@ func NewProxy(opts ProxyOptions) *Proxy {
     dirtyVersions:                  make(map[string]*int),
     documentText:                   make(map[string]string),
   }
+  // Optional-interface assertion for the same reason pluginCompletionHints uses
+  // one: a source that publishes no corpus, NullPluginSource included, simply
+  // never reports one changing.
+  type completionHintObserverSource interface {
+    SetCompletionHintsObserver(func())
+  }
+  if observed, ok := source.(completionHintObserverSource); ok {
+    observed.SetCompletionHintsObserver(proxy.completionHintsRefreshed)
+  }
+  return proxy
 }
 
 // Run drives both pump goroutines until they return. Pumps return when
@@ -255,7 +305,7 @@ func (p *Proxy) pumpEditorToUpstream(_ context.Context) error {
     if handled {
       continue
     }
-    if err := p.writeUpstreamFrame(body); err != nil {
+    if err := p.writeUpstreamFrame(constrainInitializePositionEncoding(env, body)); err != nil {
       return err
     }
   }
@@ -289,11 +339,27 @@ func (p *Proxy) handleEditorEnvelope(env Envelope, body []byte) (bool, error) {
   case methodDidSave:
     if env.IsNotification() {
       p.invalidateSymbolProvider()
+      p.invalidateResidentPlugins(env)
+      p.refreshPluginCompletionHints()
       p.publishPluginDiagnosticsForDocumentNotification(env)
     }
+  case methodDidChangeConfiguration:
+    if env.IsNotification() {
+      // A rule can be enabled from editor settings, so the corpus may have gone
+      // stale. Watched-file changes schedule the same refresh, but from inside
+      // invalidateForWatchedFileChanges, which knows whether anything actually
+      // changed.
+      p.refreshPluginCompletionHints()
+    }
   case methodDidChange:
     if env.IsNotification() {
       p.invalidateSymbolProvider()
+      // No resident invalidation on didChange: the buffer is dirty but disk is
+      // unchanged, so the warm Program (built from disk) stays valid, and plugin
+      // diagnostics and code actions are suppressed while dirty anyway. didSave
+      // updates the Program incrementally once the edit reaches disk. No corpus
+      // refresh either, for the same reason plus a sharper one: a refresh spawns
+      // a sidecar per plugin, and completion is on the live-buffer hot path.
       p.cacheDidChangeText(env)
       if err := p.markDocumentDirty(env); err != nil {
         return false, err
@@ -304,6 +370,15 @@ func (p *Proxy) handleEditorEnvelope(env Envelope, body []byte) (bool, error) {
       p.evictDocumentText(env)
       p.clearDocumentDiagnostics(env)
     }
+  case methodDidChangeWatchedFiles:
+    if env.IsNotification() {
+      // Refresh before the notification reaches tsgo, so no read that races
+      // this frame can still be answered from the pre-change snapshot. The
+      // notification itself keeps flowing upstream.
+      if err := p.invalidateForWatchedFileChanges(env); err != nil {
+        return false, err
+      }
+    }
   case methodExecuteCommand:
     if env.IsRequest() {
       return p.tryExecuteCommand(env)
@@ -324,6 +399,14 @@ func (p *Proxy) handleEditorEnvelope(env Envelope, body []byte) (bool, error) {
     if env.IsRequest() {
       return p.handleReferencesRequest(env)
     }
+  case methodCompletion:
+    return p.handleCompletionRequest(env)
+  case methodCompletionResolve:
+    return p.handleCompletionResolveRequest(env)
+  case methodExit:
+    if env.IsNotification() {
+      p.editorExit.Store(true)
+    }
   case methodCancelRequest:
     // $/cancelRequest names an in-flight id the editor has given up on.
     // The proxy drops any pending codeAction entry for that id so the
@@ -334,6 +417,121 @@ func (p *Proxy) handleEditorEnvelope(env Envelope, body []byte) (bool, error) {
   return false, nil
 }
 
+// positionEncodingUTF16 is the one LSP PositionEncodingKind ttscserver speaks.
+//
+// LSP 3.17 negotiates the encoding of `Position.character` per session: the
+// client offers `general.positionEncodings`, the server picks one, and every
+// position on that session is counted in the winner. tsgo selects `utf-8`
+// whenever a client offers it, but ttsc computes positions of its own — the
+// incremental buffer cache, plugin completion, the lint sidecar's diagnostic,
+// fix, suggestion and formatting ranges, and the graph symbol provider — and
+// every one of those counts UTF-16 code units. Because the sidecar protocol
+// carries no encoding field, a session negotiated as `utf-8` would put tsgo's
+// half of each response on byte columns and ttsc's half on UTF-16 columns.
+//
+// ttscserver therefore settles the negotiation instead of tracking it, and
+// constrains the session to UTF-16 (see constrainInitializePositionEncoding).
+// UTF-16 is the LSP default and the encoding every conforming client supports,
+// so no client loses a capability; what is given up is tsgo's byte-oriented fast
+// path, which costs one line scan per converted position inside tsgo.
+const positionEncodingUTF16 = "utf-16"
+
+// constrainInitializePositionEncoding narrows the client's position-encoding
+// offer to UTF-16 before the initialize request is forwarded upstream, so the
+// encoding tsgo selects — and therefore the one it advertises back through the
+// proxy to the client — is the encoding every ttsc-owned conversion counts.
+//
+// It is deliberately a no-op for any envelope that is not an initialize request,
+// and for any offer that names no encoding other than UTF-16: an absent, null,
+// empty, or UTF-16-only list already means UTF-16, and rewriting it to say the
+// same thing would change bytes on the wire for nothing. Every other offer has
+// its list replaced rather than filtered, so no third encoding can be selected
+// either.
+func constrainInitializePositionEncoding(env Envelope, body []byte) []byte {
+  if env.Method != methodInitialize || !env.IsRequest() || len(env.Params) == 0 {
+    return body
+  }
+  params := map[string]json.RawMessage{}
+  if json.Unmarshal(env.Params, &params) != nil {
+    return body
+  }
+  capabilities := map[string]json.RawMessage{}
+  if raw, ok := params["capabilities"]; !ok || json.Unmarshal(raw, &capabilities) != nil {
+    return body
+  }
+  general := map[string]json.RawMessage{}
+  if raw, ok := capabilities["general"]; !ok || json.Unmarshal(raw, &general) != nil {
+    return body
+  }
+  raw, ok := general["positionEncodings"]
+  if !ok {
+    return body
+  }
+  var offered []string
+  if json.Unmarshal(raw, &offered) != nil {
+    return body
+  }
+  if !offersEncodingOtherThanUTF16(offered) {
+    // Absent, null, empty, and UTF-16-only offers all already mean UTF-16.
+    return body
+  }
+  constrained, err := json.Marshal([]string{positionEncodingUTF16})
+  if err != nil {
+    return body
+  }
+  // Re-encode only the subtree that changed: every sibling value stays the
+  // client's original bytes, so a large or unusually shaped initialize payload
+  // reaches tsgo exactly as it was sent.
+  general["positionEncodings"] = constrained
+  encodedGeneral, err := json.Marshal(general)
+  if err != nil {
+    return body
+  }
+  capabilities["general"] = encodedGeneral
+  encodedCapabilities, err := json.Marshal(capabilities)
+  if err != nil {
+    return body
+  }
+  params["capabilities"] = encodedCapabilities
+  encodedParams, err := json.Marshal(params)
+  if err != nil {
+    return body
+  }
+  env.Params = encodedParams
+  encoded, err := json.Marshal(env)
+  if err != nil {
+    return body
+  }
+  return encoded
+}
+
+// offersEncodingOtherThanUTF16 reports whether a client's position-encoding
+// offer could select anything but UTF-16. An absent, null, or empty list already
+// means the LSP default, so those offers are left exactly as the client wrote
+// them rather than rewritten to say the same thing.
+func offersEncodingOtherThanUTF16(offered []string) bool {
+  for _, encoding := range offered {
+    if encoding != positionEncodingUTF16 {
+      return true
+    }
+  }
+  return false
+}
+
+// editorRequestedExit reports whether the editor sent the LSP `exit`
+// notification.
+//
+// After `exit` the upstream process is required to terminate, and the status it
+// terminates with is not ttscserver's to report. tsgo makes that distinction
+// load-bearing rather than theoretical: its `exit` handler returns io.EOF, which
+// cancels its dispatch loop, and whether its process ends 0 or 1 depends on
+// whether that cancellation or the closed stdin reaches its errgroup first. The
+// editor sees the same clean quit either way, so ttscserver must not turn one
+// side of that race into a failed server.
+func (p *Proxy) editorRequestedExit() bool {
+  return p.editorExit.Load()
+}
+
 func (p *Proxy) rememberInitializeRequest(env Envelope) {
   key := env.IDKey()
   if key == "" {
@@ -369,6 +567,10 @@ func (p *Proxy) forgetCancelledRequest(env Envelope) {
   delete(p.pendingLocalActions, key)
   delete(p.pendingCommands, key)
   delete(p.pendingInitialize, key)
+  // Completion is cancelled constantly — every keystroke supersedes the last
+  // request — so a pending entry that outlived its cancel would leak per
+  // character typed.
+  delete(p.pendingCompletions, key)
 }
 
 func (p *Proxy) handleCodeActionRequest(env Envelope) (bool, error) {
@@ -938,7 +1140,14 @@ func (p *Proxy) augmentUpstream(env Envelope, body []byte) []byte {
     if pendingInitialize {
       delete(p.pendingInitialize, key)
     }
+    completions, hasCompletions := p.pendingCompletions[key]
+    if hasCompletions {
+      delete(p.pendingCompletions, key)
+    }
     p.pendingMu.Unlock()
+    if hasCompletions {
+      return mergeCompletionResponseWithRequest(body, completions)
+    }
     if pendingInitialize {
       if augmented, augOk := p.augmentInitializeResult(env); augOk {
         return augmented
@@ -1021,6 +1230,19 @@ func (p *Proxy) publishPluginDiagnosticsForDidOpen(env Envelope) error {
     return nil
   }
   p.markDocumentClean(params.TextDocument.URI)
+  // A clean open is a disk-snapshot boundary, not merely a diagnostics trigger.
+  // The buffer equalling disk right now says nothing about when the warm Program
+  // and the symbol graph last read that file: the document may have been closed
+  // across a branch switch, a `git pull`, a generator run, or an edit in a second
+  // editor. Refresh both compiler-backed caches for this document before the
+  // asynchronous Diagnostics call below is scheduled, so the published findings
+  // describe the text the editor just opened.
+  //
+  // The dirty branch above deliberately does not invalidate: it publishes an
+  // empty set and reports nothing until the buffer reaches disk, so there is no
+  // stale answer to prevent.
+  p.invalidateSymbolProvider()
+  p.invalidateResidentPluginsForURIs(params.TextDocument.URI)
   generation, projectGeneration := p.nextDiagnosticsGenerations(params.TextDocument.URI)
   go p.publishMergedPluginDiagnostics(params.TextDocument.URI, params.TextDocument.Version, false, generation, projectGeneration)
   return nil
@@ -1285,11 +1507,13 @@ type lspRangeWire struct {
 
 // lspPositionToByteOffset converts an LSP Position into a byte offset into text.
 //
-// LSP Position.character is a UTF-16 code-unit offset (not a byte or rune
-// offset): a rune in the astral planes (>= U+10000) counts as two UTF-16 code
-// units. The walk advances line by line over '\n' and '\r\n' endings to the
-// target line, then advances `character` UTF-16 code units within that line and
-// returns the corresponding byte index.
+// LSP Position.character is counted in the session's negotiated
+// PositionEncodingKind, which constrainInitializePositionEncoding pins to UTF-16
+// for every ttscserver session — so it is a UTF-16 code-unit offset here, not a
+// byte or rune offset: a rune in the astral planes (>= U+10000) counts as two
+// UTF-16 code units. The walk advances line by line over '\n' and '\r\n' endings
+// to the target line, then advances `character` UTF-16 code units within that
+// line and returns the corresponding byte index.
 //
 // Decision on out-of-range positions: when line/character point past the end of
 // the text the function returns (len, false) rather than clamping — the caller
@@ -1633,6 +1857,27 @@ func (p *Proxy) augmentInitializeResult(env Envelope) ([]byte, bool) {
     caps["executeCommandProvider"] = provider
     changed = true
   }
+  // Merge the plugin's trigger characters into tsgo's completionProvider
+  // rather than replacing it. tsgo already advertises `.`, `"`, `'`, backtick,
+  // `/`, `@`, `<`, and `#`, and that list is what wakes its own completion —
+  // substituting a plugin's would silence the compiler's suggestions to make
+  // room for a rule's. When upstream advertises nothing, synthesize the
+  // provider so the editor asks at all.
+  triggers := p.pluginCompletionTriggerCharacters()
+  // Record what the editor ends up being told before the merge rewrites it, so a
+  // corpus that arrives after this response can tell whether its trigger already
+  // reached the client. Recorded on every initialize, including the one where
+  // the corpus is still empty.
+  p.rememberAdvertisedCompletionTriggers(caps["completionProvider"], triggers)
+  if len(triggers) > 0 {
+    provider, _ := caps["completionProvider"].(map[string]any)
+    if provider == nil {
+      provider = map[string]any{}
+    }
+    provider["triggerCharacters"] = mergeCommandIDs(provider["triggerCharacters"], triggers)
+    caps["completionProvider"] = provider
+    changed = true
+  }
   // Advertise documentFormattingProvider when ttsc owns the document
   // formatter so editors send textDocument/formatting (formatOnSave). The
   // proxy intercepts that method and formats the live buffer, so it forces
@@ -1750,6 +1995,158 @@ func (p *Proxy) pluginCodeActionKinds() []string {
   return nil
 }
 
+// pluginCompletionHints returns the corpus a plugin published, or nil when the
+// source does not offer one.
+//
+// Optional-interface assertion for the same reason CodeActionKinds uses it: a
+// PluginSource that predates this — NullPluginSource included — must keep
+// compiling and must contribute nothing rather than break.
+func (p *Proxy) pluginCompletionHints() []LSPCompletionHint {
+  type completionHintSource interface {
+    CompletionHints() []LSPCompletionHint
+  }
+  if source, ok := p.source.(completionHintSource); ok {
+    return source.CompletionHints()
+  }
+  return nil
+}
+
+// pluginCompletionTriggerCharacters returns the characters that should wake the
+// editor for a plugin hint.
+//
+// The last character of each After is what the user types to reach the hint, so
+// that is what must be advertised. These are MERGED into whatever tsgo already
+// advertises, never substituted: tsgo's own list drives its completion, and
+// replacing it would silence the compiler's suggestions to make room for a
+// plugin's.
+func (p *Proxy) pluginCompletionTriggerCharacters() []string {
+  hints := p.pluginCompletionHints()
+  characters := make([]string, 0, len(hints))
+  for _, hint := range hints {
+    if hint.After == "" {
+      continue
+    }
+    trigger, _ := utf8.DecodeLastRuneInString(hint.After)
+    characters = append(characters, string(trigger))
+  }
+  return characters
+}
+
+// refreshPluginCompletionHints asks the source to rediscover its corpus after an
+// editor event that can invalidate it. Optional-interface assertion for the same
+// reason pluginCompletionHints uses one: a source with no corpus to refresh —
+// NullPluginSource, or one built before this — is simply unaffected.
+//
+// The call returns immediately; the source owns the scheduling, coalescing, and
+// staleness rules, so the editor's notification is never held behind a plugin.
+func (p *Proxy) refreshPluginCompletionHints() {
+  type completionHintRefresher interface {
+    RefreshCompletionHints()
+  }
+  if source, ok := p.source.(completionHintRefresher); ok {
+    source.RefreshCompletionHints()
+  }
+}
+
+// completionHintsRefreshed runs after the source finishes a corpus refresh.
+//
+// Items from the new corpus need nothing here: completion reads the corpus per
+// request, so a refreshed corpus is live the moment it is stored. Trigger
+// characters are the exception. They were merged into the initialize response,
+// which the editor has already consumed, and LSP's only way to change them
+// afterwards is client/registerCapability — which in VS Code adds a SECOND
+// completion provider beside the static one instead of amending it, so every
+// item tsgo returns would be offered twice. Rather than corrupt the compiler's
+// own list to advertise a character, the proxy says once, per character, that
+// this one needs a restart. Everything else about the hint already works: the
+// items appear on Ctrl+Space and after any trigger the editor already knows.
+func (p *Proxy) completionHintsRefreshed() {
+  for _, character := range p.takeUnadvertisedCompletionTriggers() {
+    p.reportAsyncError(p.writeLateCompletionTriggerNotice(character))
+  }
+}
+
+// takeUnadvertisedCompletionTriggers returns the corpus trigger characters the
+// editor was never told about, marking each as reported so a later refresh that
+// still carries it stays quiet. Nothing is reported before the editor has the
+// initialize response, because until then every trigger is still in time.
+func (p *Proxy) takeUnadvertisedCompletionTriggers() []string {
+  triggers := p.pluginCompletionTriggerCharacters()
+  if len(triggers) == 0 {
+    return nil
+  }
+  p.capabilityMu.Lock()
+  defer p.capabilityMu.Unlock()
+  if !p.initializeAnswered {
+    return nil
+  }
+  var late []string
+  for _, character := range triggers {
+    if _, advertised := p.advertisedCompletionTriggers[character]; advertised {
+      continue
+    }
+    if _, reported := p.reportedCompletionTriggers[character]; reported {
+      continue
+    }
+    if p.reportedCompletionTriggers == nil {
+      p.reportedCompletionTriggers = map[string]struct{}{}
+    }
+    p.reportedCompletionTriggers[character] = struct{}{}
+    late = append(late, character)
+  }
+  return late
+}
+
+// rememberAdvertisedCompletionTriggers records the completion trigger set the
+// editor is about to receive: upstream tsgo's characters plus the ones the
+// corpus contributed while initialize was in flight. Recorded even when the
+// corpus added nothing, because that is exactly the session where a later
+// refresh has something new to say.
+func (p *Proxy) rememberAdvertisedCompletionTriggers(upstream any, added []string) {
+  advertised := map[string]struct{}{}
+  if provider, ok := upstream.(map[string]any); ok {
+    if existing, ok := provider["triggerCharacters"].([]any); ok {
+      for _, value := range existing {
+        if character, ok := value.(string); ok && character != "" {
+          advertised[character] = struct{}{}
+        }
+      }
+    }
+  }
+  for _, character := range added {
+    if character != "" {
+      advertised[character] = struct{}{}
+    }
+  }
+  p.capabilityMu.Lock()
+  defer p.capabilityMu.Unlock()
+  p.advertisedCompletionTriggers = advertised
+  p.initializeAnswered = true
+}
+
+// writeLateCompletionTriggerNotice tells the editor's output channel that one
+// trigger character arrived too late to be advertised. window/logMessage rather
+// than window/showMessage: this is a state the user may want to act on, not an
+// interruption of what they are doing.
+func (p *Proxy) writeLateCompletionTriggerNotice(character string) error {
+  params, err := json.Marshal(map[string]any{
+    "type": lspMessageTypeInfo,
+    "message": fmt.Sprintf(
+      "ttscserver: a plugin now publishes completion after %q, which was not advertised when this session started. "+
+        "The items are available on explicit completion (Ctrl+Space); restart the language server to have the editor open them on that character.",
+      character,
+    ),
+  })
+  if err != nil {
+    return nil
+  }
+  body, err := json.Marshal(Envelope{JSONRPC: "2.0", Method: methodLogMessage, Params: params})
+  if err != nil {
+    return nil
+  }
+  return p.writeEditorFrame(body)
+}
+
 func (p *Proxy) setUpstreamCodeActionProvider(value any) {
   provides := true
   if boolValue, ok := value.(bool); ok {
@@ -1813,6 +2210,201 @@ func (p *Proxy) invalidateSymbolProvider() {
   }
 }
 
+// invalidateResidentPlugins tells a resident plugin source that a document
+// changed on disk, passing the saved document's URI so the daemon can update
+// that file incrementally; an unparseable notification falls back to a full
+// invalidation. Optional-interface assertion for the same reason
+// pluginCodeActionKinds uses one: a PluginSource without a resident daemon
+// (NullPluginSource, or one built before this) is simply unaffected.
+func (p *Proxy) invalidateResidentPlugins(env Envelope) {
+  source, ok := p.residentInvalidator()
+  if !ok {
+    return
+  }
+  var params struct {
+    TextDocument struct {
+      URI string `json:"uri"`
+    } `json:"textDocument"`
+  }
+  if len(env.Params) > 0 && json.Unmarshal(env.Params, &params) == nil && params.TextDocument.URI != "" {
+    source.InvalidateResidentPrograms(params.TextDocument.URI)
+    return
+  }
+  source.InvalidateResidentPrograms()
+}
+
+// residentInvalidator is the optional capability a PluginSource exposes to
+// refresh its warm compiler state. Optional-interface assertion for the same
+// reason pluginCodeActionKinds uses one: a PluginSource without a resident
+// daemon (NullPluginSource, or one built before this) is simply unaffected.
+type residentInvalidator interface {
+  InvalidateResidentPrograms(...string)
+}
+
+func (p *Proxy) residentInvalidator() (residentInvalidator, bool) {
+  source, ok := p.source.(residentInvalidator)
+  return source, ok
+}
+
+// invalidateResidentPluginsForURIs names the documents that changed on disk so
+// the daemon updates exactly those files incrementally. Calling it with no URI
+// is the deliberate full-reload request for a change the host cannot localize.
+func (p *Proxy) invalidateResidentPluginsForURIs(uris ...string) {
+  if source, ok := p.residentInvalidator(); ok {
+    source.InvalidateResidentPrograms(uris...)
+  }
+}
+
+// LSP FileChangeType. Only `changed` names an edit to a file whose place in the
+// project is unchanged; created and deleted both reshape the root set, which a
+// per-file UpdateProgram cannot express.
+const (
+  fileChangeTypeCreated = 1
+  fileChangeTypeChanged = 2
+  fileChangeTypeDeleted = 3
+)
+
+// invalidateForWatchedFileChanges refreshes both compiler-backed caches for a
+// workspace/didChangeWatchedFiles batch, which is the only notification carrying
+// an on-disk change to a file the editor does not have open.
+//
+// A batch the proxy can localize — every entry a plain `changed` event on a file
+// that is not project configuration — travels as changed URIs so the daemon
+// re-parses just those files. Anything else drops the warm Program wholesale:
+// a created or deleted file changes the root set, and a tsconfig/jsconfig edit
+// changes the compiler options and the file selection, neither of which a
+// per-file update can express. A batch the proxy cannot decode is treated the
+// same conservative way, because an unread change is indistinguishable from an
+// unlocalizable one.
+//
+// A deleted document additionally withdraws whatever ttsc last published for it,
+// because refreshing the Program alone would leave the findings on screen: an
+// open document's content belongs to the client rather than to disk, so the
+// compiler has no reason to republish for that URI and trigger the merge that
+// would replace them.
+func (p *Proxy) invalidateForWatchedFileChanges(env Envelope) error {
+  var params struct {
+    Changes []struct {
+      URI  string `json:"uri"`
+      Type *int   `json:"type"`
+    } `json:"changes"`
+  }
+  if len(env.Params) == 0 || json.Unmarshal(env.Params, &params) != nil {
+    p.invalidateSymbolProvider()
+    p.invalidateResidentPluginsForURIs()
+    p.refreshPluginCompletionHints()
+    return nil
+  }
+  if len(params.Changes) == 0 {
+    // The editor reported no change; dropping warm state here would throw away
+    // the residency the daemon exists to provide for nothing. A corpus refresh
+    // is skipped for the same reason and at higher cost: it spawns a sidecar
+    // per plugin, each loading its own Program.
+    return nil
+  }
+  uris := make([]string, 0, len(params.Changes))
+  deleted := make([]string, 0, len(params.Changes))
+  localizable := true
+  for _, change := range params.Changes {
+    if change.URI != "" && change.Type != nil && *change.Type == fileChangeTypeDeleted {
+      deleted = append(deleted, change.URI)
+    }
+    if !watchedFileChangeIsLocalizable(change.URI, change.Type) {
+      localizable = false
+      continue
+    }
+    uris = append(uris, change.URI)
+  }
+  p.invalidateSymbolProvider()
+  if !localizable || len(uris) == 0 {
+    p.invalidateResidentPluginsForURIs()
+  } else {
+    p.invalidateResidentPluginsForURIs(uris...)
+  }
+  // A completion corpus projects the whole Program, so it cannot be invalidated
+  // per URI the way the resident daemon's is: any reported change can change it.
+  p.refreshPluginCompletionHints()
+  for _, uri := range deleted {
+    if err := p.withdrawPluginDiagnosticsForDeletedDocument(uri); err != nil {
+      return err
+    }
+  }
+  return nil
+}
+
+// withdrawPluginDiagnosticsForDeletedDocument removes ttsc's findings for a
+// document that no longer exists on disk and republishes what remains, so a
+// deleted file cannot keep a plugin squiggle from the last time it was linted.
+//
+// Upstream diagnostics are left in place: the compiler owns its own answer for
+// the same document, and the editor may legitimately keep showing it while the
+// buffer is still open. Bumping the diagnostic generation discards any in-flight
+// computation started against the pre-deletion Program. A document ttsc never
+// published for is a no-op, which is the ordinary case.
+func (p *Proxy) withdrawPluginDiagnosticsForDeletedDocument(uri string) error {
+  p.writeMu.Lock()
+  defer p.writeMu.Unlock()
+  p.diagnosticsMu.Lock()
+  defer p.diagnosticsMu.Unlock()
+  if len(p.pluginDiagnostics[uri].diagnostics) == 0 {
+    return nil
+  }
+  delete(p.pluginDiagnostics, uri)
+  p.diagnosticGeneration[uri]++
+  return WriteFrame(p.editorOut, p.publishDiagnosticsBody(uri, nil, p.mergedDiagnosticsLocked(uri)))
+}
+
+// watchedFileChangeIsLocalizable reports whether one watched-file entry can be
+// delivered to the resident daemon as a changed URI, rather than forcing it to
+// drop the warm Program and reload.
+func watchedFileChangeIsLocalizable(uri string, changeType *int) bool {
+  if uri == "" || changeType == nil {
+    return false
+  }
+  switch *changeType {
+  case fileChangeTypeChanged:
+    // A configuration edit can change the compiler options and the selected root
+    // files at once, which is not a single-file update however it is spelled.
+    return !isProjectConfigURI(uri)
+  case fileChangeTypeCreated, fileChangeTypeDeleted:
+    // The root set moved, which tsgo's per-file UpdateProgram cannot express.
+    return false
+  default:
+    // A FileChangeType outside the enum LSP defines.
+    return false
+  }
+}
+
+// isProjectConfigURI reports whether uri names a TypeScript project
+// configuration file — `tsconfig.json`, `jsconfig.json`, and the
+// `tsconfig.<name>.json` spellings the VS Code client watches. Such an edit can
+// change the compiler options and the root file set at once, so it is never
+// localizable to a single source file.
+func isProjectConfigURI(uri string) bool {
+  path := uri
+  if parsed, err := url.Parse(uri); err == nil && parsed.Path != "" {
+    path = parsed.Path
+  }
+  name := strings.ToLower(path)
+  if index := strings.LastIndexAny(name, "/\\"); index >= 0 {
+    name = name[index+1:]
+  }
+  if !strings.HasSuffix(name, ".json") {
+    return false
+  }
+  return strings.HasPrefix(name, "tsconfig") || strings.HasPrefix(name, "jsconfig")
+}
+
+// shutdownResidentPlugins kills any resident plugin daemons on server teardown.
+// The children also exit on their own when the parent closes their stdin at
+// process exit, so this is the graceful path, not the only one.
+func (p *Proxy) shutdownResidentPlugins() {
+  type residentShutdown interface{ shutdownResidents() }
+  if source, ok := p.source.(residentShutdown); ok {
+    source.shutdownResidents()
+  }
+}
+
 // capabilityAdvertised reports whether an LSP server-capability value means the
 // server implements the capability: boolean true, or an options object. Absent
 // (nil), false, or any other shape counts as unsupported.