ttsc 0.19.2 → 0.20.0

package/internal/lspserver/lsp_hints_refresh_replaces_the_session_snapshot_test.go

@@ -0,0 +1,66 @@
+package lspserver
+
+import (
+  "reflect"
+  "testing"
+)
+
+// TestLSPHintsRefreshReplacesTheSessionSnapshot pins the lifecycle the corpus
+// channel shipped without.
+//
+// The first release fetched the corpus once, in a goroutine started by
+// NewNativePluginSource, and every later read was that same slice. A rule
+// enabled after startup, or a contributor index rebuilt from a saved document,
+// could not reach the editor without restarting the language server — which is
+// precisely when a project-derived corpus is most wrong. Each stage below is a
+// state the proxy must serve correctly, including the two that are easy to get
+// backwards: a corpus that shrinks must shrink, and one that never arrived must
+// stay silent rather than fail open.
+//
+//  1. Read the corpus before any producer has answered.
+//  2. Let a producer answer, and read again through the proxy's completion seam.
+//  3. Let the same producer answer differently, then answer with nothing.
+func TestLSPHintsRefreshReplacesTheSessionSnapshot(t *testing.T) {
+  plugin := NativeLSPPluginEntry{Binary: "ttsc-lint", Name: "@ttsc/lint"}
+  source := &NativePluginSource{plugins: []NativeLSPPluginEntry{plugin}}
+  proxy := &Proxy{source: source}
+
+  if hints := proxy.pluginCompletionHints(); len(hints) != 0 {
+    t.Fatalf("a source whose producers have not answered published %d hints", len(hints))
+  }
+  if triggers := proxy.pluginCompletionTriggerCharacters(); len(triggers) != 0 {
+    t.Fatalf("an empty corpus advertised trigger characters %v", triggers)
+  }
+
+  source.storeCompletionHints(plugin, 1, []LSPCompletionHint{
+    {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "param"}}},
+  })
+  hints := proxy.pluginCompletionHints()
+  if len(hints) != 1 || hints[0].After != "@" || len(hints[0].Items) != 1 {
+    t.Fatalf("a corpus that arrived after startup did not reach the proxy: %#v", hints)
+  }
+  if got := proxy.pluginCompletionTriggerCharacters(); !reflect.DeepEqual(got, []string{"@"}) {
+    t.Fatalf("trigger characters = %#v, want [\"@\"]", got)
+  }
+
+  // The same producer, re-asked, is the whole point: its answer replaces the
+  // previous one rather than accumulating beside it.
+  source.storeCompletionHints(plugin, 2, []LSPCompletionHint{
+    {Scope: "jsdoc", After: "@evidence ", Items: []LSPCompletionItem{{Insert: "docs/rfc.md"}}},
+  })
+  hints = proxy.pluginCompletionHints()
+  if len(hints) != 1 || hints[0].After != "@evidence " {
+    t.Fatalf("a changed corpus did not replace the previous one: %#v", hints)
+  }
+  if got := proxy.pluginCompletionTriggerCharacters(); !reflect.DeepEqual(got, []string{" "}) {
+    t.Fatalf("trigger characters = %#v, want [\" \"] from the new corpus", got)
+  }
+
+  // A rule turned off publishes nothing. Treating an empty successful answer as
+  // "keep what you had" would leave a disabled rule's items in the popup for the
+  // rest of the session.
+  source.storeCompletionHints(plugin, 3, nil)
+  if hints := proxy.pluginCompletionHints(); len(hints) != 0 {
+    t.Fatalf("a producer that stopped publishing left %d hints behind", len(hints))
+  }
+}

package/internal/lspserver/lsp_hints_refresh_scheduled_by_editor_events_test.go

@@ -0,0 +1,90 @@
+package lspserver
+
+import (
+  "io"
+  "sync/atomic"
+  "testing"
+)
+
+// refreshCountingSource records how often the proxy asked for a corpus
+// rediscovery. It counts atomically because didSave also starts an asynchronous
+// diagnostics publication against the same source.
+type refreshCountingSource struct {
+  NullPluginSource
+  refreshes atomic.Int64
+}
+
+func (s *refreshCountingSource) CompletionHints() []LSPCompletionHint { return nil }
+
+func (s *refreshCountingSource) RefreshCompletionHints() { s.refreshes.Add(1) }
+
+// TestLSPHintsRefreshScheduledByEditorEvents pins which editor notifications
+// rediscover the corpus.
+//
+// The corpus projects what a rule's Check found on the saved project, so the
+// events that can invalidate it are the ones that change that project: a saved
+// document, a config change from the editor, a watched file rewritten outside
+// it. The negative half matters just as much. didChange fires per keystroke and
+// leaves disk untouched, and a refresh spawns a sidecar per plugin, so
+// refreshing there would put a process spawn on the typing path — the one thing
+// this channel must never do.
+//
+//  1. Send each notification that must schedule a refresh.
+//  2. Assert one refresh per notification.
+//  3. Send the notifications that must not, and assert the count is unchanged.
+func TestLSPHintsRefreshScheduledByEditorEvents(t *testing.T) {
+  source := &refreshCountingSource{}
+  proxy := NewProxy(ProxyOptions{
+    EditorOut:  io.Discard,
+    UpstreamIn: io.Discard,
+    Source:     source,
+  })
+
+  refreshing := []string{
+    `{"jsonrpc":"2.0","method":"textDocument/didSave","params":{"textDocument":{"uri":"file:///a.ts"}}}`,
+    `{"jsonrpc":"2.0","method":"workspace/didChangeConfiguration","params":{"settings":{}}}`,
+    `{"jsonrpc":"2.0","method":"workspace/didChangeWatchedFiles","params":{"changes":[{"uri":"file:///lint.config.ts","type":2}]}}`,
+    // Params the proxy cannot read take the conservative branch: it cannot tell
+    // which inputs changed, so it assumes they all did — the same answer it
+    // gives the resident daemon there.
+    `{"jsonrpc":"2.0","method":"workspace/didChangeWatchedFiles"}`,
+  }
+  for index, body := range refreshing {
+    handleHintRefreshEditorFrame(t, proxy, body)
+    if got := source.refreshes.Load(); got != int64(index+1) {
+      t.Fatalf("after %s the source had been refreshed %d times, want %d", body, got, index+1)
+    }
+  }
+
+  quiet := []string{
+    // An editor that reports no change gets no refresh: the proxy already
+    // refuses to drop the resident daemon's warm Program for that notification,
+    // and a corpus refresh costs a whole Program load per plugin.
+    `{"jsonrpc":"2.0","method":"workspace/didChangeWatchedFiles","params":{"changes":[]}}`,
+    `{"jsonrpc":"2.0","method":"textDocument/didChange","params":{"textDocument":{"uri":"file:///a.ts","version":2},"contentChanges":[{"text":"const a = 1;"}]}}`,
+    `{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":{"uri":"file:///a.ts","languageId":"typescript","version":1,"text":"const a = 1;"}}}`,
+    `{"jsonrpc":"2.0","method":"textDocument/didClose","params":{"textDocument":{"uri":"file:///a.ts"}}}`,
+    `{"jsonrpc":"2.0","id":7,"method":"textDocument/completion","params":{"textDocument":{"uri":"file:///a.ts"},"position":{"line":0,"character":0}}}`,
+  }
+  for _, body := range quiet {
+    handleHintRefreshEditorFrame(t, proxy, body)
+  }
+  if got := source.refreshes.Load(); got != int64(len(refreshing)) {
+    t.Fatalf(
+      "an event that cannot change the saved project refreshed the corpus (%d refreshes, want %d); "+
+        "a refresh spawns a sidecar per plugin",
+      got, len(refreshing),
+    )
+  }
+}
+
+func handleHintRefreshEditorFrame(t *testing.T, proxy *Proxy, body string) {
+  t.Helper()
+  env, err := ParseEnvelope([]byte(body))
+  if err != nil {
+    t.Fatalf("test frame is not a valid envelope: %v", err)
+  }
+  if _, err := proxy.handleEditorEnvelope(env, []byte(body)); err != nil {
+    t.Fatalf("handling %s failed: %v", env.Method, err)
+  }
+}

package/internal/lspserver/lsp_hints_refresh_serves_completion_while_running_test.go

@@ -0,0 +1,91 @@
+package lspserver
+
+import (
+  "sync"
+  "testing"
+)
+
+// TestLSPHintsRefreshServesCompletionWhileRunning pins the reader's view during
+// a refresh.
+//
+// Completion is answered from the corpus on the request path while a refresh
+// writes it from a background goroutine, so this is a real concurrent
+// reader/writer pair rather than a theoretical one — the user types while their
+// save is still being re-indexed. Two failures hide here that a single-threaded
+// test cannot see: a data race on the snapshot, and a reader catching the corpus
+// mid-rebuild and offering a truncated list. Run with -race.
+//
+//  1. Seed two producers so a torn snapshot is distinguishable from a whole one.
+//  2. Rewrite both producers' corpora repeatedly while readers ask for them.
+//  3. Assert every snapshot a reader saw was a whole corpus of known hints.
+func TestLSPHintsRefreshServesCompletionWhileRunning(t *testing.T) {
+  first := NativeLSPPluginEntry{Binary: "ttsc-lint", Name: "@ttsc/lint"}
+  second := NativeLSPPluginEntry{Binary: "ttsc-evidence", Name: "@samchon/evidence"}
+  source := &NativePluginSource{plugins: []NativeLSPPluginEntry{first, second}}
+  proxy := &Proxy{source: source}
+
+  corpus := func(plugin NativeLSPPluginEntry, insert string) []LSPCompletionHint {
+    after := "@"
+    if plugin.Binary == second.Binary {
+      after = "@evidence "
+    }
+    return []LSPCompletionHint{
+      {Scope: "jsdoc", After: after, Items: []LSPCompletionItem{{Insert: insert}}},
+    }
+  }
+  source.storeCompletionHints(first, 1, corpus(first, "param"))
+  source.storeCompletionHints(second, 1, corpus(second, "docs/rfc.md"))
+
+  const cycles = 200
+  var writers sync.WaitGroup
+  writers.Add(2)
+  for _, plugin := range []NativeLSPPluginEntry{first, second} {
+    go func(plugin NativeLSPPluginEntry) {
+      defer writers.Done()
+      for generation := uint64(2); generation < cycles; generation++ {
+        source.storeCompletionHints(plugin, generation, corpus(plugin, "refreshed"))
+      }
+    }(plugin)
+  }
+
+  var readers sync.WaitGroup
+  failures := make(chan string, 16)
+  for reader := 0; reader < 4; reader++ {
+    readers.Add(1)
+    go func() {
+      defer readers.Done()
+      for i := 0; i < cycles; i++ {
+        hints := proxy.pluginCompletionHints()
+        if len(hints) != 2 {
+          select {
+          case failures <- "a completion request saw a partially rebuilt corpus":
+          default:
+          }
+          return
+        }
+        if hints[0].After != "@" || hints[1].After != "@evidence " {
+          select {
+          case failures <- "a completion request saw producers out of manifest order":
+          default:
+          }
+          return
+        }
+        for _, hint := range hints {
+          if len(hint.Items) != 1 || hint.Items[0].Insert == "" {
+            select {
+            case failures <- "a completion request saw an empty hint group":
+            default:
+            }
+            return
+          }
+        }
+      }
+    }()
+  }
+  writers.Wait()
+  readers.Wait()
+  close(failures)
+  for failure := range failures {
+    t.Error(failure)
+  }
+}

package/internal/lspserver/lsp_index_byte_from_bounds_its_search_start_test.go

@@ -0,0 +1,38 @@
+package lspserver
+
+import "testing"
+
+// TestLSPIndexByteFromBoundsItsSearchStart verifies the line scanner behind
+// offsetForPosition answers identically at and past the edges of the buffer.
+//
+// The hand-rolled loop this replaced started at `from` and compared `from <
+// len(text)` on every step, so an out-of-range start simply fell out of the
+// loop. Slicing before delegating to strings.IndexByte would panic on the same
+// input, and the position path reaches it for a cursor on the last line of a
+// buffer that has no trailing newline.
+//
+//  1. Search from inside, at, and past the end of a buffer.
+//  2. Search from a negative start.
+//  3. Assert every answer is the offset the caller can index with, or -1.
+func TestLSPIndexByteFromBoundsItsSearchStart(t *testing.T) {
+  const text = "alpha\nbeta\ngamma"
+  for _, entry := range []struct {
+    name string
+    from int
+    want int
+  }{
+    {"from the start", 0, 5},
+    {"past the first newline", 6, 10},
+    {"after the last newline", 11, -1},
+    {"exactly at the end", len(text), -1},
+    {"past the end", len(text) + 8, -1},
+    {"negative start", -4, 5},
+  } {
+    if got := indexByteFrom(text, entry.from, '\n'); got != entry.want {
+      t.Fatalf("%s: want %d, got %d", entry.name, entry.want, got)
+    }
+  }
+  if got := indexByteFrom("", 0, '\n'); got != -1 {
+    t.Fatalf("empty buffer: want -1, got %d", got)
+  }
+}

package/internal/lspserver/lsp_initialize_constrains_position_encoding_to_utf16_test.go

@@ -0,0 +1,205 @@
+package lspserver
+
+import (
+  "bytes"
+  "encoding/json"
+  "errors"
+  "io"
+  "testing"
+)
+
+// TestLSPInitializeConstrainsPositionEncodingToUTF16 verifies that the offer
+// forwarded to tsgo can only ever select UTF-16, and that a client which did not
+// offer UTF-8 reaches tsgo byte for byte as before.
+//
+// LSP 3.17 negotiates one PositionEncodingKind per session. The pinned
+// typescript-go selects `utf-8` whenever a client offers it and advertises that
+// choice back through the proxy, while every position ttsc computes itself — the
+// incremental buffer cache, plugin completion, the lint sidecar's ranges, the
+// graph symbol provider — counts UTF-16 code units. ttscserver therefore settles
+// the negotiation at the initialize request instead of tracking it, so the two
+// halves of one editor response cannot disagree.
+//
+//  1. Forward an initialize request offering UTF-8 first and assert the upstream
+//     frame offers UTF-16 alone while every sibling field survives verbatim.
+//  2. Assert an offer of UTF-16 alone, an absent offer, and a non-initialize
+//     envelope are returned unchanged.
+//  3. Drive the real editor-to-upstream pump and assert the rewrite is what tsgo
+//     actually receives.
+func TestLSPInitializeConstrainsPositionEncodingToUTF16(t *testing.T) {
+  const offeringUTF8 = `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+    `{"processId":4242,"rootUri":"file:///project","capabilities":` +
+    `{"general":{"markdown":{"parser":"marked"},"positionEncodings":["utf-8","utf-16"]},` +
+    `"textDocument":{"completion":{"dynamicRegistration":true}}}}}`
+
+  rewritten := constrainInitializePositionEncoding(mustParseEnvelope(t, offeringUTF8), []byte(offeringUTF8))
+  assertPositionEncodings(t, rewritten, []string{positionEncodingUTF16})
+  assertInitializeSiblingsSurvive(t, rewritten)
+
+  const offeringUTF8Only = `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+    `{"capabilities":{"general":{"positionEncodings":["utf-8"]}}}}`
+  assertPositionEncodings(
+    t,
+    constrainInitializePositionEncoding(mustParseEnvelope(t, offeringUTF8Only), []byte(offeringUTF8Only)),
+    []string{positionEncodingUTF16},
+  )
+
+  const offeringUTF32 = `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+    `{"capabilities":{"general":{"positionEncodings":["utf-32","utf-8"]}}}}`
+  assertPositionEncodings(
+    t,
+    constrainInitializePositionEncoding(mustParseEnvelope(t, offeringUTF32), []byte(offeringUTF32)),
+    []string{positionEncodingUTF16},
+  )
+
+  // Negative twins: a client that never offered UTF-8 must reach tsgo exactly as
+  // it wrote its request, so no existing session changes shape.
+  unchanged := []struct {
+    name string
+    body string
+  }{
+    {
+      name: "utf-16 alone is already the settlement",
+      body: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+        `{"capabilities":{"general":{"positionEncodings":["utf-16"]}}}}`,
+    },
+    {
+      name: "no offer means the LSP default",
+      body: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+        `{"capabilities":{"general":{"markdown":{"parser":"marked"}}}}}`,
+    },
+    {
+      name: "an empty offer already means the LSP default",
+      body: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+        `{"capabilities":{"general":{"positionEncodings":[]}}}}`,
+    },
+    {
+      name: "a null offer already means the LSP default",
+      body: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":` +
+        `{"capabilities":{"general":{"positionEncodings":null}}}}`,
+    },
+    {
+      name: "no general capabilities at all",
+      body: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}`,
+    },
+    {
+      name: "a later request is never rewritten",
+      body: `{"jsonrpc":"2.0","id":2,"method":"textDocument/completion","params":` +
+        `{"capabilities":{"general":{"positionEncodings":["utf-8"]}}}}`,
+    },
+    {
+      name: "an initialized notification is not the initialize request",
+      body: `{"jsonrpc":"2.0","method":"initialize","params":` +
+        `{"capabilities":{"general":{"positionEncodings":["utf-8"]}}}}`,
+    },
+  }
+  for _, testCase := range unchanged {
+    t.Run(testCase.name, func(t *testing.T) {
+      got := constrainInitializePositionEncoding(
+        mustParseEnvelope(t, testCase.body),
+        []byte(testCase.body),
+      )
+      if !bytes.Equal(got, []byte(testCase.body)) {
+        t.Errorf("forwarded frame was rewritten:\n got %s\nwant %s", got, testCase.body)
+      }
+    })
+  }
+
+  // The helper is only correct if it sits on the forwarding path, so drive the
+  // real pump and read what tsgo would have received.
+  var editorIn bytes.Buffer
+  if err := WriteFrame(&editorIn, []byte(offeringUTF8)); err != nil {
+    t.Fatalf("write editor frame: %v", err)
+  }
+  var upstream bytes.Buffer
+  proxy := NewProxy(ProxyOptions{
+    EditorIn:   &editorIn,
+    EditorOut:  io.Discard,
+    UpstreamIn: &upstream,
+  })
+  if err := proxy.pumpEditorToUpstream(t.Context()); !errors.Is(err, ErrFrameClosed) {
+    t.Fatalf("pump editor to upstream: %v", err)
+  }
+  _, forwarded, err := NewFrameReader(bytes.NewReader(upstream.Bytes())).Read()
+  if err != nil {
+    t.Fatalf("read forwarded initialize: %v", err)
+  }
+  assertPositionEncodings(t, forwarded, []string{positionEncodingUTF16})
+}
+
+func mustParseEnvelope(t *testing.T, body string) Envelope {
+  t.Helper()
+  env, err := ParseEnvelope([]byte(body))
+  if err != nil {
+    t.Fatalf("parse envelope %s: %v", body, err)
+  }
+  return env
+}
+
+func assertPositionEncodings(t *testing.T, body []byte, want []string) {
+  t.Helper()
+  var decoded struct {
+    Params struct {
+      Capabilities struct {
+        General struct {
+          PositionEncodings []string `json:"positionEncodings"`
+        } `json:"general"`
+      } `json:"capabilities"`
+    } `json:"params"`
+  }
+  if err := json.Unmarshal(body, &decoded); err != nil {
+    t.Fatalf("decode forwarded initialize: %v\n%s", err, body)
+  }
+  got := decoded.Params.Capabilities.General.PositionEncodings
+  if len(got) != len(want) {
+    t.Fatalf("positionEncodings = %v, want %v", got, want)
+  }
+  for index := range want {
+    if got[index] != want[index] {
+      t.Fatalf("positionEncodings = %v, want %v", got, want)
+    }
+  }
+}
+
+func assertInitializeSiblingsSurvive(t *testing.T, body []byte) {
+  t.Helper()
+  var decoded struct {
+    ID     json.RawMessage `json:"id"`
+    Method string          `json:"method"`
+    Params struct {
+      ProcessID    int    `json:"processId"`
+      RootURI      string `json:"rootUri"`
+      Capabilities struct {
+        General struct {
+          Markdown struct {
+            Parser string `json:"parser"`
+          } `json:"markdown"`
+        } `json:"general"`
+        TextDocument struct {
+          Completion struct {
+            DynamicRegistration bool `json:"dynamicRegistration"`
+          } `json:"completion"`
+        } `json:"textDocument"`
+      } `json:"capabilities"`
+    } `json:"params"`
+  }
+  if err := json.Unmarshal(body, &decoded); err != nil {
+    t.Fatalf("decode rewritten initialize: %v\n%s", err, body)
+  }
+  if string(decoded.ID) != "1" || decoded.Method != methodInitialize {
+    t.Errorf("envelope identity changed: id=%s method=%q", decoded.ID, decoded.Method)
+  }
+  if decoded.Params.ProcessID != 4242 {
+    t.Errorf("processId = %d, want 4242 (re-encoded, not preserved)", decoded.Params.ProcessID)
+  }
+  if decoded.Params.RootURI != "file:///project" {
+    t.Errorf("rootUri = %q, want file:///project", decoded.Params.RootURI)
+  }
+  if decoded.Params.Capabilities.General.Markdown.Parser != "marked" {
+    t.Errorf("general.markdown.parser = %q, want marked",
+      decoded.Params.Capabilities.General.Markdown.Parser)
+  }
+  if !decoded.Params.Capabilities.TextDocument.Completion.DynamicRegistration {
+    t.Error("textDocument.completion.dynamicRegistration was dropped")
+  }
+}

package/internal/lspserver/lsp_late_completion_trigger_is_reported_once_test.go

@@ -0,0 +1,105 @@
+package lspserver
+
+import (
+  "bytes"
+  "strings"
+  "sync"
+  "testing"
+)
+
+// mutableCompletionHintSource stands in for a plugin source whose corpus changes
+// mid-session. The lock is real: the proxy reads the corpus from the completion
+// path while a refresh rewrites it.
+type mutableCompletionHintSource struct {
+  NullPluginSource
+  mu    sync.RWMutex
+  hints []LSPCompletionHint
+}
+
+func (s *mutableCompletionHintSource) CompletionHints() []LSPCompletionHint {
+  s.mu.RLock()
+  defer s.mu.RUnlock()
+  return append([]LSPCompletionHint(nil), s.hints...)
+}
+
+func (s *mutableCompletionHintSource) publish(hints ...LSPCompletionHint) {
+  s.mu.Lock()
+  defer s.mu.Unlock()
+  s.hints = hints
+}
+
+// TestLSPLateCompletionTriggerIsReportedOnce pins the one thing a corpus refresh
+// still cannot deliver on its own.
+//
+// Trigger characters are merged into the initialize response, and the editor has
+// already consumed it by the time a refresh runs. LSP's only remedy is
+// client/registerCapability, which VS Code implements by adding a second
+// completion provider beside the static one — every item tsgo returns would then
+// be offered twice. Corrupting the compiler's list to advertise one character is
+// the worse trade, so the proxy states the gap instead of hiding it. Saying it
+// once per character is the whole design: a refresh runs on every save, and a
+// notice repeated per save would be noise the user learns to ignore.
+//
+//  1. Answer initialize with tsgo's trigger characters and no corpus.
+//  2. Publish a corpus whose trigger is new and refresh; expect one notice.
+//  3. Refresh again, and publish a trigger tsgo already advertised; expect none.
+func TestLSPLateCompletionTriggerIsReportedOnce(t *testing.T) {
+  var editor bytes.Buffer
+  source := &mutableCompletionHintSource{}
+  proxy := NewProxy(ProxyOptions{EditorOut: &editor, Source: source})
+
+  // Before initialize nothing is late: the corpus is still in time to be merged
+  // into the response the editor has not received yet.
+  source.publish(LSPCompletionHint{Scope: "jsdoc", After: "@evidence ", Items: []LSPCompletionItem{{Insert: "docs/rfc.md"}}})
+  proxy.completionHintsRefreshed()
+  if editor.Len() != 0 {
+    t.Fatalf("a corpus discovered before initialize was reported as late:\n%s", editor.String())
+  }
+
+  source.publish()
+  env, err := ParseEnvelope([]byte(`{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"completionProvider":{"triggerCharacters":["@","."]}}}}`))
+  if err != nil {
+    t.Fatalf("initialize fixture is not a valid envelope: %v", err)
+  }
+  proxy.augmentInitializeResult(env)
+
+  source.publish(LSPCompletionHint{Scope: "jsdoc", After: "@evidence ", Items: []LSPCompletionItem{{Insert: "docs/rfc.md"}}})
+  proxy.completionHintsRefreshed()
+  notices := logMessageNotices(editor.String())
+  if len(notices) != 1 {
+    t.Fatalf("a trigger character discovered after initialize produced %d notices, want 1:\n%s", len(notices), editor.String())
+  }
+  // The trigger is the LAST rune of After, a space here, and the notice quotes
+  // it so an invisible character is still identifiable in the output channel.
+  if !strings.Contains(notices[0], `\" \"`) {
+    t.Errorf("the notice does not name the trigger character it is about:\n%s", notices[0])
+  }
+  if !strings.Contains(notices[0], "restart") {
+    t.Errorf("the notice does not say what the user has to do:\n%s", notices[0])
+  }
+
+  editor.Reset()
+  proxy.completionHintsRefreshed()
+  if editor.Len() != 0 {
+    t.Fatalf("the same late trigger was reported again on the next refresh:\n%s", editor.String())
+  }
+
+  // A trigger tsgo already advertises is not late at all — the editor is already
+  // asking for completion on it, so the hint works with no restart.
+  source.publish(LSPCompletionHint{Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "param"}}})
+  proxy.completionHintsRefreshed()
+  if editor.Len() != 0 {
+    t.Fatalf("a trigger character upstream already advertises was reported as late:\n%s", editor.String())
+  }
+}
+
+// logMessageNotices extracts the window/logMessage frames written to the editor.
+func logMessageNotices(stream string) []string {
+  var notices []string
+  for _, chunk := range strings.Split(stream, "\r\n\r\n") {
+    if strings.Contains(chunk, `"window/logMessage"`) {
+      notices = append(notices, chunk)
+    }
+  }
+  return notices
+}

package/internal/lspserver/lsp_native_completion_hints_decode_flat_lint_wire_test.go

@@ -0,0 +1,66 @@
+package lspserver
+
+import (
+  "reflect"
+  "testing"
+)
+
+// TestNativeCompletionHintsDecodeFlatLintWire verifies the real lint boundary.
+//
+// @ttsc/lint publishes a flat []rule.Hint rather than the proxy's grouped
+// matching shape. Repeated triggers must coalesce without moving the group or
+// reordering its items, because slice order is the publisher's ranking channel.
+//
+//  1. Decode interleaved flat hints using the exact public rule.Hint JSON shape.
+//  2. Assert first-trigger group order and per-trigger item order are preserved.
+//  3. Feed the decoded corpus to the live matcher and verify it is offerable.
+func TestNativeCompletionHintsDecodeFlatLintWire(t *testing.T) {
+  body := []byte(`[
+    {
+      "insert":"docs/stable.md",
+      "label":"stable",
+      "detail":"pinned document",
+      "trigger":{"scope":"jsdoc","after":"@evidence "}
+    },
+    {
+      "insert":"param",
+      "detail":"JSDoc tag",
+      "trigger":{"scope":"jsdoc","after":"@"}
+    },
+    {
+      "insert":"docs/derived.md",
+      "label":"derived",
+      "trigger":{"scope":"jsdoc","after":"@evidence "}
+    }
+  ]`)
+
+  got, err := decodeNativeCompletionHints(body)
+  if err != nil {
+    t.Fatalf("decode flat lint hint wire: %v", err)
+  }
+  want := []LSPCompletionHint{
+    {
+      Scope: "jsdoc",
+      After: "@evidence ",
+      Items: []LSPCompletionItem{
+        {Insert: "docs/stable.md", Label: "stable", Detail: "pinned document"},
+        {Insert: "docs/derived.md", Label: "derived"},
+      },
+    },
+    {
+      Scope: "jsdoc",
+      After: "@",
+      Items: []LSPCompletionItem{
+        {Insert: "param", Detail: "JSDoc tag"},
+      },
+    },
+  }
+  if !reflect.DeepEqual(got, want) {
+    t.Fatalf("decoded flat hints:\n got %#v\nwant %#v", got, want)
+  }
+
+  items, filter := matchCompletionHints(got, " * @evidence docs/", true)
+  if filter != "docs/" || !reflect.DeepEqual(items, want[0].Items) {
+    t.Errorf("decoded corpus did not reach matcher: filter=%q items=%#v", filter, items)
+  }
+}