ttsc 0.30.4 → 0.31.1

package/internal/lspserver/lsp_completion_gate_never_refuses_a_matching_line_test.go

@@ -3,7 +3,8 @@ package lspserver
 import "testing"
 
 // TestLSPCompletionGateNeverRefusesAMatchingLine verifies the cheap line test
-// that now guards the document scan admits everything the full match would.
+// admits the seven selected literal line outcomes and never refuses a nonempty
+// full-match result for those inputs. This is not universal admission proof.
 //
 // completionItemsFor decides the cursor's lexical scope by scanning the document
 // from byte zero, and that answer is only ever read by a hint whose trigger is
@@ -15,6 +16,11 @@ import "testing"
 //  2. For each candidate line, run the gate and the full match together.
 //  3. Assert the gate is open wherever the match produced items, and closed on
 //     lines holding no trigger at all.
+//
+// @evidence contracts/testing.md#behavioral-verification For each candidate line the cheap trigger gate is open wherever the full hint match produces items and closed on lines holding no trigger.
+// @evidence contracts/testing.md#independent-expectations Each of the seven lines has an independently authored gate boolean. The additional comparison uses the production matcher, which shares completionHintCouldApply with the gate, so it is a correlated consistency check rather than an independent admission oracle. The broad @ trigger also masks the nil-item @nothing entry's isolated behavior.
+// @evidence contracts/testing.md#distinguishing-cases A layered corpus of broad and narrow triggers and lines with and without any trigger separate a too-strict gate from a correct one.
+// @evidence contracts/testing.md#execution-ownership Directly supplies one authored hint corpus and seven strings to the maintained gate and matcher with inJSDoc=true in this process. It substitutes no seam, creates no native fixture, loads no Program, resolves no sidecar, and runs no document scan, completion request, consumer, or process.
 func TestLSPCompletionGateNeverRefusesAMatchingLine(t *testing.T) {
   hints := []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "param"}}},

package/internal/lspserver/lsp_completion_hints_longest_trigger_wins_test.go

@@ -7,7 +7,9 @@ import "testing"
 //
 // A plugin publishes broad and narrow triggers at once — `@`, `@evidence `,
 // `@evidence docs/spec.md#` — because it cannot ask a question per keystroke and
-// so must describe every position up front. Only the longest match may answer.
+// so describes the selected positions up front. These nested matches begin at
+// the same occurrence, where the longest wins; different occurrences also have
+// a nearest-trigger policy that this fixture does not exercise.
 // Without that, typing `@evidence docs/spec.md#pri` would offer tag names,
 // document paths, and anchors together, and the narrow corpus the user actually
 // wants would be buried under the broad one that also matches.
@@ -16,6 +18,11 @@ import "testing"
 //  2. Ask at a cursor inside the narrowest.
 //  3. Assert only the narrowest answers, and that the filter is the text after
 //     it rather than the whole line.
+//
+// @evidence contracts/testing.md#behavioral-verification At a cursor inside the narrowest of three nested triggers only the narrowest hint answers, and its filter is the text after that trigger.
+// @evidence contracts/testing.md#independent-expectations The expected items and filter are literals for the published nested triggers.
+// @evidence contracts/testing.md#distinguishing-cases Broad, middle and narrow triggers all match the same line, so a matcher that merged them would offer all three.
+// @evidence contracts/testing.md#execution-ownership Directly supplies an authored hint corpus and four line prefixes to matchCompletionHints with inJSDoc=true in this process. Literal ordered Insert strings and filters are observed; other item fields, native scope classification, and request publication are not asserted. It substitutes no seam, creates no directory, resolves no sidecar, and starts no Program, process, consumer, or editor connection.
 func TestLSPCompletionHintsLongestTriggerWins(t *testing.T) {
   hints := []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "evidence"}}},
@@ -61,10 +68,18 @@ func TestLSPCompletionHintsLongestTriggerWins(t *testing.T) {
 //  1. Ask the same line outside a JSDoc block.
 //  2. Ask with a scope this host does not know.
 //  3. Assert silence in both.
+//
+// @evidence contracts/testing.md#behavioral-verification The same supplied @Inj line and hint yields evidence with inJSDoc=true but no items with false; an authored unknown scope and empty-trigger/nil-item corpus also yield no items. This observes admission booleans, not actual decorator/JSDoc lexical classification or completion publication.
+// @evidence contracts/testing.md#independent-expectations The correct-scope control requires the literal evidence Insert; wrong/unknown scope and degenerate hint inputs require empty item lists. Filters and other item fields are not asserted.
+// @evidence contracts/testing.md#distinguishing-cases The first positive/negative pair differs only in supplied inJSDoc; unknown-scope and degenerate corpora are separate inputs. The positive control rejects blanket empty output, without authenticating scope parsing.
+// @evidence contracts/testing.md#execution-ownership Directly supplies strings, hint records, and inJSDoc booleans to matchCompletionHints in this process. It substitutes no seam, creates no directory, resolves no sidecar, loads no Program, and starts no product process, consumer, or editor connection.
 func TestLSPCompletionHintsRefuseOutsideScope(t *testing.T) {
   hints := []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "evidence"}}},
   }
+  if items, _ := matchCompletionHints(hints, "@Inj", true); !equalStrings(inserts(items), []string{"evidence"}) {
+    t.Errorf("correct-scope control offered %v, want evidence", inserts(items))
+  }
   if items, _ := matchCompletionHints(hints, "@Inj", false); len(items) != 0 {
     t.Errorf("a decorator position was offered %v, want nothing", inserts(items))
   }
@@ -87,13 +102,18 @@ func TestLSPCompletionHintsRefuseOutsideScope(t *testing.T) {
 
 // TestCursorInJSDocTracksTheBlock pins the scope test itself.
 //
-// It is a backward scan rather than a parse, so the cases that matter are the
-// ones where a naive "is there a /** before me" would be wrong: after the block
-// closed, and inside a line comment that only looks like one.
+// Six authored end cursors distinguish open and closed JSDoc, a second open
+// block, a line comment, and code. The maintained helper scans forward; this
+// test observes booleans, not its algorithm, all comment forms, or a request.
 //
 //  1. A cursor inside an open block is in scope.
 //  2. A cursor after the block closed is not.
-//  3. A line comment is never a doc comment.
+//  3. The authored line-comment and ordinary-code cursors are not in JSDoc.
+//
+// @evidence contracts/testing.md#behavioral-verification cursorInJSDoc is true inside an open doc block, including a second block after a closed one, and false after the block closed, in a line comment and in ordinary code.
+// @evidence contracts/testing.md#independent-expectations Each source string carries its expected boolean written literally.
+// @evidence contracts/testing.md#distinguishing-cases Cases where a naive search for '/**' would be wrong, a closed block and a line comment, sit beside the open blocks.
+// @evidence contracts/testing.md#execution-ownership Directly calls cursorInJSDoc on six authored strings and literal booleans in this process. It substitutes no seam, creates no directory, resolves no sidecar, loads no Program, and starts no consumer, child process, or LSP connection.
 func TestCursorInJSDocTracksTheBlock(t *testing.T) {
   cases := []struct {
     text string
@@ -118,6 +138,11 @@ func TestCursorInJSDocTracksTheBlock(t *testing.T) {
 //
 // A trigger matched against the whole document would let a `@evidence` three
 // lines up offer anchors on an unrelated line.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct linePrefixAt calls return the literal last-line prefix at one multiline end offset and no at byte offset two of no newline. This checks text only up to the supplied cursor, not the entire single-line document or actual trigger matching.
+// @evidence contracts/testing.md#independent-expectations The expected prefixes are literal strings.
+// @evidence contracts/testing.md#distinguishing-cases A multi-line text and a single line distinguish line-local from document-wide matching.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit directly calls actual linePrefixAt with two authored strings and offsets. It uses no substitute operation, native process, temporary directory, installed consumer or product host; CR boundaries and invalid offsets are outside its two cases.
 func TestLinePrefixStopsAtTheLine(t *testing.T) {
   text := "/**\n * @evidence docs/spec.md#pri"
   if got, want := linePrefixAt(text, len(text)), " * @evidence docs/spec.md#pri"; got != want {

package/internal/lspserver/lsp_completion_hints_nearest_trigger_wins_test.go

@@ -6,6 +6,11 @@ import "testing"
 // nearest the cursor, not merely the longest text somewhere earlier on the
 // line. At one occurrence, nested triggers remain layerable and duplicate
 // producers of the same trigger may contribute together.
+//
+// @evidence contracts/testing.md#behavioral-verification Four direct matcher outcomes observe a later broad trigger, one nested trigger, later equal-length trigger selection, and merged same-trigger records, with literal ordered Insert strings and filters. Actual producer discovery, other item fields, scope parsing, and request publication are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expected item lists and filters are literal per line.
+// @evidence contracts/testing.md#distinguishing-cases Lines with an earlier long trigger and a later short one, a later broad trigger and duplicate producers separate nearest from longest-earlier.
+// @evidence contracts/testing.md#execution-ownership Directly supplies six authored hint records and four line prefixes to matchCompletionHints with inJSDoc=true in this process. Ordered Insert/filter expectations are literal; no seam is substituted, directory created, sidecar resolved, Program loaded, process started, or editor/plugin connection made.
 func TestLSPCompletionHintsNearestTriggerWins(t *testing.T) {
   hints := []LSPCompletionHint{
     {Scope: "jsdoc", After: "@", Items: []LSPCompletionItem{{Insert: "broad"}}},

package/internal/lspserver/lsp_completion_merges_into_upstream_response_test.go

@@ -6,17 +6,21 @@ import (
   "testing"
 )
 
-// TestLSPCompletionMergesIntoUpstreamResponse pins the response merge.
+// TestLSPCompletionMergesIntoUpstreamResponse checks three authored response shapes.
 //
-// tsgo answers completion in three shapes — a bare item array, a CompletionList,
-// or null — and picks per request. Each has to be handled rather than assumed,
-// because guessing wrong does not error: it silently drops either the plugin's
-// items or the compiler's, and the user simply sees a shorter list than they
-// should. That is the failure this whole channel is most likely to ship with.
+// A bare item array, a CompletionList and null must accept the supplied hint.
+// This unit checks ordered labels and isIncomplete, then checks the label
+// fallback and insertText in a null-result merge. It does not run tsgo or an
+// editor, or assert preservation of every upstream item or envelope field.
 //
 //  1. Merge into each of the three shapes.
-//  2. Assert upstream's items survive alongside the plugin's in every one.
-//  3. Assert isIncomplete stays upstream's answer, not ours.
+//  2. Assert the literal upstream and plugin label order for each shape.
+//  3. Assert the supplied list's true flag and array/null false flags.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual mergeCompletionResponse calls produce the literal ordered labels for an authored bare array, CompletionList and null result; the list's true isIncomplete survives and array/null yield false. A separate null-result call asserts the supplied Insert becomes label and insertText. Other item and envelope fields are not compared.
+// @evidence contracts/testing.md#independent-expectations The expected label lists and incompleteness are literals per response shape.
+// @evidence contracts/testing.md#distinguishing-cases Each of the three upstream shapes takes a different decode path, so a merge that handled only one drops items in the others.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls the actual package-local merge function with authored JSON bytes and one supplied item, then decodes the returned bytes. It creates no filesystem fixture, substitutes no operation and starts no compiler, process or product host; upstream response production and editor handling are outside its observations.
 func TestLSPCompletionMergesIntoUpstreamResponse(t *testing.T) {
   items := []LSPCompletionItem{{Insert: "pricing", Detail: "Pricing"}}
 
@@ -38,8 +42,7 @@ func TestLSPCompletionMergesIntoUpstreamResponse(t *testing.T) {
       incomplete: true,
     },
     {
-      // Not an edge case: tsgo returns null for completion in JSDoc prose,
-      // which is exactly where these hints live. This is the common shape.
+      // A null response has no upstream item to retain.
       name:       "null result",
       body:       `{"jsonrpc":"2.0","id":1,"result":null}`,
       wantLabels: []string{"pricing"},
@@ -91,6 +94,11 @@ func TestLSPCompletionMergesIntoUpstreamResponse(t *testing.T) {
 // An upstream error is upstream's to report. Appending completions to it would
 // turn a failure into a half-answer that looks like it worked, which is worse
 // than the error the user was supposed to see.
+//
+// @evidence contracts/testing.md#behavioral-verification An upstream error response is returned byte for byte, and merging no items leaves the body unchanged.
+// @evidence contracts/testing.md#independent-expectations The expected output is the input body itself.
+// @evidence contracts/testing.md#distinguishing-cases An error body and an empty contribution are the two cases that must not be rewritten.
+// @evidence contracts/testing.md#execution-ownership This Go unit invokes the actual package-local merge function on two authored JSON bodies and compares returned bytes to each original. It substitutes no seam and creates no directory or sidecar; no upstream compiler, editor, process or product host runs. The changing merge cases are owned by TestLSPCompletionMergesIntoUpstreamResponse.
 func TestLSPCompletionLeavesUpstreamErrorsAlone(t *testing.T) {
   body := `{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"boom"}}`
   if got := string(mergeCompletionResponse([]byte(body), []LSPCompletionItem{{Insert: "x"}})); got != body {
@@ -115,6 +123,11 @@ func TestLSPCompletionLeavesUpstreamErrorsAlone(t *testing.T) {
 //  1. Convert an ASCII position.
 //  2. Convert past CJK text, which is one UTF-16 unit but three bytes.
 //  3. Convert past an emoji, which is a surrogate pair — two units, four bytes.
+//
+// @evidence contracts/testing.md#behavioral-verification offsetForPosition counts an LSP character in UTF-16 units: ASCII, CJK text (one unit, three bytes) and an emoji (two units, four bytes) all yield the right text prefix.
+// @evidence contracts/testing.md#independent-expectations The expected prefixes are literal strings derived from the UTF-16 definition in the LSP specification.
+// @evidence contracts/testing.md#distinguishing-cases Four positive rows cover ASCII, a second LF-separated line, two BMP CJK characters and an astral emoji; a separate line-five request on one line must fail. Surrogate-interior columns and malformed text are not exercised.
+// @evidence contracts/testing.md#execution-ownership The discoverable Go unit directly calls actual offsetForPosition and compares string slices with authored literal prefixes. Its delegating lspPositionToByteOffset runs in the same process; no substitute operation, native child, temporary project, installed consumer or product host is used.
 func TestOffsetForPositionCountsUTF16(t *testing.T) {
   cases := []struct {
     text      string

package/internal/lspserver/lsp_completion_nearest_hint_replaces_nearest_filter_test.go

@@ -16,7 +16,13 @@ func (nearestCompletionHintSource) CompletionHints() []LSPCompletionHint {
 
 // TestLSPCompletionNearestHintReplacesNearestFilter exercises the request path:
 // a later short trigger beats an earlier long trigger and replaces only the
-// filter immediately after the winning occurrence.
+// filter immediately after the winning occurrence in the returned range.
+// No response is emitted and no editor applies that range in this unit.
+//
+// @evidence contracts/testing.md#behavioral-verification completionItemsFor returns only the nearest trigger's item and a replacement range that covers just the filter after that trigger.
+// @evidence contracts/testing.md#independent-expectations The expected item and range columns are literals computed from the literal document text.
+// @evidence contracts/testing.md#distinguishing-cases An earlier long trigger and a later short one share the line, so the earlier one's filter would give a different range.
+// @evidence contracts/testing.md#execution-ownership This Go unit directly calls Proxy.completionItemsFor with an owned CompletionHints source, a supplied document-text map and authored request JSON. The actual cursor classification, hint matching and range construction execute; no directory, sidecar, compiler, process or LSP transport runs, and client application of the range is unobserved.
 func TestLSPCompletionNearestHintReplacesNearestFilter(t *testing.T) {
   const uri = "file:///project/src/main.ts"
   const text = "/** @evidence first @pa"

package/internal/lspserver/lsp_completion_preserves_completion_list_extensions_test.go

@@ -6,15 +6,23 @@ import (
   "testing"
 )
 
-// TestLSPCompletionPreservesCompletionListExtensions verifies lossless merging.
+// TestLSPCompletionPreservesCompletionListExtensions checks selected JSON members.
 //
-// TypeScript-Go uses CompletionList.itemDefaults, and newer protocol versions
-// may add more list-level fields. Decoding into a closed local struct silently
-// removed those fields whenever a plugin contributed even one completion.
+// An authored CompletionList supplies defaults, merge apply kinds and an
+// extension field. Assertions compare decoded JSON values, not verbatim bytes
+// or every item field. No TypeScript-Go response producer runs here.
 //
 //  1. Build an upstream CompletionList with itemDefaults, applyKind, and a future field.
 //  2. Merge one plugin completion.
-//  3. Assert every upstream list field and both items survive.
+//  3. Assert itemDefaults, the future field, and isIncomplete retain their values,
+//     the upstream item receives the defaults it relied on, and applyKind is
+//     rewritten to replace (1) because those defaults are now materialized into
+//     each item and must not merge a second time.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual mergeCompletionResponse retains the decoded values of itemDefaults, x-future and isIncomplete, rewrites the two applyKind members to replace (1), and returns two items. Literal checks distinguish upstream commit-character union and item-over-default data from the plugin's empty commit characters and private data marker. Other item fields and serialized byte identity are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expected JSON members are literals written from the upstream CompletionList body.
+// @evidence contracts/testing.md#distinguishing-cases A closed local struct would drop the future field; the defaults-materialization and applyKind rewrite are separate assertions.
+// @evidence contracts/testing.md#execution-ownership This Go unit directly invokes the actual package-local merge function with authored JSON bytes and a supplied item, then compares selected decoded members to independent literal JSON. It substitutes no operation and creates no directory or sidecar; no compiler, process, installed consumer or product host runs.
 func TestLSPCompletionPreservesCompletionListExtensions(t *testing.T) {
   body := []byte(`{
     "jsonrpc":"2.0",

package/internal/lspserver/lsp_completion_refuses_hints_inside_a_string_literal_test.go

@@ -18,16 +18,20 @@ func (jsdocTagCompletionHintSource) CompletionHints() []LSPCompletionHint {
 // TestLSPCompletionRefusesHintsInsideAStringLiteral verifies the scope decision
 // where it is observable.
 //
-// The lexical table proves the scanner; this proves the request path still asks
-// it. A refactor that recomputed scope from the line prefix, or that passed the
-// wrong offset, would put `jsdoc/check-tag-names` tags into ordinary source
-// text — a position the owning rule never inspects — and no unit test of the
-// matcher alone would notice.
+// The actual request helper classifies two supplied documents: a string
+// containing a JSDoc opener and a real doc comment. A prefix-only classifier
+// would incorrectly admit the first. These observations do not run the owning
+// lint rule, publish an LSP response or certify every scanner boundary.
 //
 //  1. Ask for completion after `@par` inside a string literal that contains the
 //     JSDoc opener.
 //  2. Ask again at the same tag inside a real doc comment.
-//  3. Assert silence for the first and the published item for the second.
+//  3. Assert silence for the first and the supplied item/range for the second.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual Proxy.completionItemsFor returns no items at the supplied string-literal cursor, then returns the supplied param item and literal line-1 range 4..7 for the real doc-comment cursor. The negative branch asserts item absence, not the reason for refusal or its range.
+// @evidence contracts/testing.md#independent-expectations Empty items, the supplied param insertion and the real comment's literal range columns are authored expectations, not computed from the scanner or matcher.
+// @evidence contracts/testing.md#distinguishing-cases Both cursors follow @par with the same supplied hint source; the containing documents, URI and cursor positions differ. The positive comment prevents unconditional empty results from satisfying the pair; the quoted opener distinguishes a prefix-only classifier.
+// @evidence contracts/testing.md#execution-ownership This Go unit invokes the actual request helper on an owned CompletionHints source, a supplied document map and authored JSON params. Actual position conversion, lexical classification, matching and range construction run in-process; no directory, sidecar, compiler, lint rule, process or LSP transport runs.
 func TestLSPCompletionRefusesHintsInsideAStringLiteral(t *testing.T) {
   const literalURI = "file:///project/src/literal.ts"
   const blockURI = "file:///project/src/block.ts"
@@ -61,7 +65,7 @@ func TestLSPCompletionRefusesHintsInsideAStringLiteral(t *testing.T) {
   if got := inserts(pending.items); !equalStrings(got, []string{"param"}) {
     t.Fatalf("a real doc comment was offered %v, want [param]", got)
   }
-  // The refusal must not have come from a broken filter range either.
+  // The admitted comment also has the literal replacement range.
   if pending.replaceRange.Start != (LSPPosition{Line: 1, Character: 4}) ||
     pending.replaceRange.End != (LSPPosition{Line: 1, Character: 7}) {
     t.Errorf("replacement range = %+v, want character 4..7", pending.replaceRange)

package/internal/lspserver/lsp_completion_replaces_full_filter_in_rank_order_test.go

@@ -23,11 +23,17 @@ func (rankedCompletionHintSource) CompletionHints() []LSPCompletionHint {
 // A completion label containing slashes cannot rely on the editor's default
 // word range: replacing only the last segment of `文档/sp` would duplicate the
 // path prefix. The range is measured in UTF-16 units, and explicit sort keys
-// preserve the publisher's ranking instead of letting the client alphabetize it.
+// must order the supplied items. This unit observes returned edits and keys,
+// not a client's sorting or application of those edits.
 //
 //  1. Match two ranked hints after a non-BMP character and a CJK path prefix.
-//  2. Merge them into the null completion response tsgo uses in JSDoc prose.
+//  2. Merge them into an authored null completion response.
 //  3. Assert both text edits replace the full filter and sort in slice order.
+//
+// @evidence contracts/testing.md#behavioral-verification Two ranked hints after a non-BMP character and a CJK path prefix merge into a null upstream response as text edits that replace the full filter, in publisher order.
+// @evidence contracts/testing.md#independent-expectations Literal UTF-16 columns 17..22 and ordered insertion strings docs/stable.md then docs/derived.md are independent expected values; sort-key ordering is compared separately. FilterText equality with NewText is a consistency check, not an independent content oracle.
+// @evidence contracts/testing.md#distinguishing-cases A path filter containing slashes and wide characters distinguishes a full-filter range from a last-segment range.
+// @evidence contracts/testing.md#execution-ownership This Go unit invokes actual Proxy.completionItemsFor and mergeCompletionResponseWithRequest on an owned hint source, supplied document map and authored JSON. It decodes the returned edits and keys; no directory, sidecar, compiler, process, installed consumer or LSP transport runs, and editor sorting/application is unobserved.
 func TestLSPCompletionReplacesFullFilterInRankOrder(t *testing.T) {
   const uri = "file:///project/src/main.ts"
   const text = "/** 😀 @evidence 文档/sp"
@@ -66,7 +72,11 @@ func TestLSPCompletionReplacesFullFilterInRankOrder(t *testing.T) {
   if len(response.Result.Items) != 2 {
     t.Fatalf("merged %d completion items, want 2", len(response.Result.Items))
   }
+  wantInsertions := []string{"docs/stable.md", "docs/derived.md"}
   for index, item := range response.Result.Items {
+    if item.TextEdit.NewText != wantInsertions[index] {
+      t.Errorf("item %d inserted text = %q, want %q", index, item.TextEdit.NewText, wantInsertions[index])
+    }
     if item.TextEdit.Range.Start != (LSPPosition{Line: 0, Character: 17}) ||
       item.TextEdit.Range.End != (LSPPosition{Line: 0, Character: 22}) {
       t.Errorf("item %d replacement range = %+v, want character 17..22", index, item.TextEdit.Range)

package/internal/lspserver/lsp_completion_request.go

@@ -158,35 +158,14 @@ func utf16Length(text string) int {
 // the cursor mid-token if counted as bytes. The conversion walks the line's runes
 // and spends the position's UTF-16 budget as it goes.
 func offsetForPosition(text string, line int, character int) (int, bool) {
-  offset := 0
-  for current := 0; current < line; current++ {
-    next := indexByteFrom(text, offset, '\n')
-    if next == -1 {
-      return 0, false
-    }
-    offset = next + 1
-  }
-  units := 0
-  for index, symbol := range text[offset:] {
-    if units >= character {
-      return offset + index, true
-    }
-    if symbol == '\n' || symbol == '\r' {
-      return offset + index, true
-    }
-    if symbol > 0xFFFF {
-      units += 2
-    } else {
-      units++
-    }
-  }
-  return len(text), true
+  return lspPositionToByteOffset(text, lspPositionWire{Line: line, Character: character})
 }
 
 // indexByteFrom returns the offset of the first target byte at or after from, or
-// -1. It delegates to strings.IndexByte rather than looping: this runs once per
-// line walked on the completion path, and the standard library's scan is the
-// platform's vectorized one where a hand-rolled loop is a byte at a time.
+// -1, normalizing a negative start to zero and refusing starts at or past EOF.
+// The remaining substring search delegates to strings.IndexByte. This helper
+// is exercised directly by its unit; offsetForPosition currently delegates to
+// lspPositionToByteOffset instead, so this is not its active line scanner.
 func indexByteFrom(text string, from int, target byte) int {
   if from < 0 {
     from = 0

package/internal/lspserver/lsp_completion_scope.go

@@ -1,5 +1,7 @@
 package lspserver
 
+import "strings"
+
 // lexicalScope names the kind of token a byte offset sits in.
 //
 // It is what a scanner can decide without a parse: comments, string and
@@ -56,7 +58,7 @@ type regexContext struct {
   last byte
 
   lastAdjacent       bool
-  word               string
+  word               strings.Builder
   previousWord       string
   beforePreviousWord string
   wordMember         bool
@@ -115,11 +117,11 @@ func (context *regexContext) separator() {
 
 func (context *regexContext) writeCode(symbol byte) {
   if isIdentifierByte(symbol) {
-    if context.word == "" {
+    if context.word.Len() == 0 {
       context.wordExpression = context.expressionPosition()
       context.wordMember = context.last == '.'
     }
-    context.word += string(symbol)
+    context.word.WriteByte(symbol)
     context.kind = regexPredecessorWord
     context.last = symbol
     context.lastAdjacent = true
@@ -256,26 +258,27 @@ func (context *regexContext) expressionPosition() bool {
 }
 
 func (context *regexContext) finishWord() {
-  if context.word == "" {
+  if context.word.Len() == 0 {
     return
   }
-  if context.word == "function" && !context.wordMember {
+  word := context.word.String()
+  if word == "function" && !context.wordMember {
     context.pendingFunction = true
     context.functionExpression = context.wordExpression
-  } else if context.word == "class" && !context.wordMember {
+  } else if word == "class" && !context.wordMember {
     context.classExpressions = append(context.classExpressions, context.wordExpression)
   }
   context.beforePreviousWord = context.previousWord
-  context.previousWord = context.word
+  context.previousWord = word
   context.previousMember = context.wordMember
   context.previousExpression = context.wordExpression
-  context.word = ""
+  context.word.Reset()
   context.wordMember = false
 }
 
 func (context *regexContext) lastWord() (string, bool) {
-  if context.word != "" {
-    return context.word, context.wordMember
+  if context.word.Len() != 0 {
+    return context.word.String(), context.wordMember
   }
   return context.previousWord, context.previousMember
 }

package/internal/lspserver/lsp_completion_scope_bench_test.go

@@ -5,16 +5,22 @@ import (
   "testing"
 )
 
-// BenchmarkCursorInJSDoc measures the scope decision on the completion hot path.
+// BenchmarkCursorInJSDoc times direct scope classification and its true check
+// for one repeated buffer exceeding one MiB, ending inside an open JSDoc block.
 //
-// Completion asks it per request on the live buffer, so its cost has to stay
-// small against the round trip to tsgo that the same request makes. The buffer
-// here is deliberately larger than a real source file and the cursor sits at its
-// end, which is the worst case for a forward scan: the whole prefix is walked.
+// The end cursor requires scanning this full authored prefix. This is not a
+// universal worst-case source or a measured real-file distribution; no latency
+// bound, completion request, tsgo round trip, or relative performance is asserted.
+// Buffer setup precedes ResetTimer; the timed loop includes the scope check.
 //
 // Usage:
 //
 //  go test ./internal/lspserver -run=^$ -bench=^BenchmarkCursorInJSDoc$
+//
+// @evidence contracts/testing.md#behavioral-verification The timed loop calls cursorInJSDoc at the end of one buffer exceeding one MiB and fails unless the trailing open JSDoc is recognized. Timing includes that check, has no asserted threshold, and does not certify universal worst-case cost, real-file size, completion latency, or tsgo comparison.
+// @evidence contracts/testing.md#independent-expectations The in-loop check that the cursor is in a doc comment is the literal oracle; the timing itself is only measured, not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Only this end-of-buffer open-JSDoc position is timed. Repeated chunks contain closed JSDoc, quoted delimiter text, regex, and template interpolation; no negative scope outcome or alternate cursor position is asserted here.
+// @evidence contracts/testing.md#execution-ownership Owns constructed strings and direct in-process cursorInJSDoc calls through Go's benchmark entry. Ordinary go test does not invoke the benchmark without selection; Evidence's configured source inventory still selects its declaration. No native fixture, Program, completion protocol, child process, or installed consumer is owned.
 func BenchmarkCursorInJSDoc(b *testing.B) {
   chunk := strings.Join([]string{
     "/**",

package/internal/lspserver/lsp_completion_scope_classifies_regex_statement_and_operator_boundaries_test.go

@@ -4,7 +4,14 @@ import "testing"
 
 // TestLSPCompletionScopeClassifiesRegexStatementAndOperatorBoundaries keeps
 // JSDoc-shaped bytes inside regexes from escaping into completion scope while
-// preserving real comments after expressions and live-buffer recovery.
+// preserving the expected end-of-string scope for authored expression,
+// declaration, template and CR-recovery examples. It does not observe scope
+// at an interior regex cursor or execute completion requests.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual lexicalScopeAt at len(text) returns literal code or JSDoc scopes for eighteen authored statement-header, operator, declaration/member, template and CR-recovery strings. Closed-regex rows observe the final code scope, not the interior lexicalScopeRegex state; positive unfinished comments distinguish an always-code result.
+// @evidence contracts/testing.md#independent-expectations Each case's expected scope is a literal written next to its source text.
+// @evidence contracts/testing.md#distinguishing-cases Statement headers (if, while, for, with), division and unary operators decide whether a slash starts a regex, so each is its own row.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls the actual package-local lexical scanner on supplied strings and compares the returned enum to each literal expectation. It substitutes no operation and creates no directory or sidecar; no compiler, native process, product host or LSP transport runs, and request matching/publication is outside this table.
 func TestLSPCompletionScopeClassifiesRegexStatementAndOperatorBoundaries(t *testing.T) {
   cases := []struct {
     name string

package/internal/lspserver/lsp_completion_scope_ignores_jsdoc_bytes_in_literals_test.go

@@ -5,18 +5,19 @@ import "testing"
 // TestLSPCompletionScopeIgnoresJSDocBytesInLiterals pins the lexical table the
 // JSDoc scope decision rests on.
 //
-// `/**` is three ordinary bytes. A string, a template, a regex class, and a line
-// comment can all contain them, and a backward search for the nearest opener
-// calls every one of those positions a doc comment — which is how
-// `const example = "/** @par"` came to be offered JSDoc tag completions. Every
-// impostor below is a position that search answered wrongly; every real block
-// below is what stops a replacement from passing by refusing everything.
+// Strings, templates, regex classes and line comments can contain `/**`
+// without starting JSDoc. Authored non-doc and real-doc cases distinguish that
+// boundary and selected escape/interpolation/line-recovery decisions. This
+// table does not establish a historical failure or all JavaScript token forms.
 //
-//  1. Put the cursor after JSDoc-shaped bytes in every token kind that can hold
-//     them.
+//  1. Put the cursor at the end of each authored string.
 //  2. Assert the scanner's scope and the `cursorInJSDoc` answer derived from it.
-//  3. Keep a real block adjacent to each impostor, so a scanner that simply
-//     refused everything could not pass.
+//  3. Include real blocks, an interior regex cursor and offset boundaries.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual lexicalScopeAt returns each literal end-cursor scope for authored literal/comment, escape, interpolation and recovery cases. Separate checks assert code at offset zero, regex at interior offset 15, and cursorInJSDoc refusal outside the buffer. No completion request or editor behavior is observed.
+// @evidence contracts/testing.md#independent-expectations Expected lexical enums and the zero/interior/invalid offset expectations are authored literals. The expected cursorInJSDoc boolean is derived from the literal expected enum, not the scanner result; cursorInJSDoc delegates to the same scanner, so agreement is not an independent parser oracle.
+// @evidence contracts/testing.md#distinguishing-cases Non-doc literal/comment cases and positive real-doc cases reject unconditional admission or refusal. Escape, CRLF continuation, interpolation, division and keyword-member rows distinguish selected transitions; they are a bounded corpus, not a pair for every possible token form.
+// @evidence contracts/testing.md#execution-ownership This Go unit directly invokes the actual package-local scanner and cursor predicate on supplied strings. It substitutes no operation and creates no directory or sidecar; no compiler, process, installed consumer, product host or LSP transport runs.
 func TestLSPCompletionScopeIgnoresJSDocBytesInLiterals(t *testing.T) {
   cases := []struct {
     name string

package/internal/lspserver/lsp_completion_scope_refuses_regex_hints_test.go

@@ -16,9 +16,13 @@ func (regexScopeCompletionHintSource) CompletionHints() []LSPCompletionHint {
   }}
 }
 
-// TestLSPCompletionScopeRefusesRegexHints verifies the request path never
-// offers JSDoc hints inside a regex while still offering one in a real JSDoc
-// block immediately after executable code.
+// TestLSPCompletionScopeRefusesRegexHints checks one regex cursor refusal and
+// one real JSDoc cursor admission through the actual request helper.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual Proxy.completionItemsFor returns zero items at the authored regex-class cursor and one item at the authored real-doc cursor. This unit asserts counts, not item content, replacement range, the refusal's internal reason or all regex contexts.
+// @evidence contracts/testing.md#independent-expectations Zero items for the regex and one item for the block are literal expectations.
+// @evidence contracts/testing.md#distinguishing-cases The two documents contain the same '@tag' text in different lexical contexts.
+// @evidence contracts/testing.md#execution-ownership This Go unit uses an owned CompletionHints source and completionScopePending to replace the supplied document map and author request JSON before invoking the actual request helper. Cursor conversion/classification and matching run in-process; no directory, sidecar, compiler, process or LSP transport runs, and no response reaches an editor.
 func TestLSPCompletionScopeRefusesRegexHints(t *testing.T) {
   const uri = "file:///project/src/main.ts"
   proxy := &Proxy{source: regexScopeCompletionHintSource{}}

package/internal/lspserver/lsp_completion_trigger_uses_last_rune_test.go

@@ -14,6 +14,12 @@ func (unicodeCompletionTriggerSource) CompletionHints() []LSPCompletionHint {
   }
 }
 
+// TestLSPCompletionTriggerUsesLastRune checks two supplied trigger endings.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual pluginCompletionTriggerCharacters returns the ordered literal pair @ and fullwidth slash from the two supplied After strings. The result does not establish client trigger registration, duplicate/empty-trigger handling or malformed UTF-8 behavior.
+// @evidence contracts/testing.md#independent-expectations The expected list is the literal pair '@' and the fullwidth slash.
+// @evidence contracts/testing.md#distinguishing-cases A multi-byte final rune distinguishes last-rune from last-byte extraction.
+// @evidence contracts/testing.md#execution-ownership This Go unit supplies an owned CompletionHints source on a Proxy and directly invokes its actual trigger projection. It substitutes no projection operation and creates no directory or sidecar; no compiler, process, product host, initialization message or editor runs. Items are intentionally absent because this projection reads After rather than request admission.
 func TestLSPCompletionTriggerUsesLastRune(t *testing.T) {
   proxy := &Proxy{source: unicodeCompletionTriggerSource{}}
   got := proxy.pluginCompletionTriggerCharacters()

package/internal/lspserver/lsp_deleted_watched_file_withdraws_plugin_diagnostics_test.go

@@ -8,19 +8,22 @@ import (
 )
 
 // TestLSPDeletedWatchedFileWithdrawsPluginDiagnostics verifies that deleting a
-// file on disk removes the findings ttsc last published for it, while leaving
-// the compiler's own diagnostics for the same document alone.
+// reported watched-file URI withdraws its supplied cached plugin finding while
+// retaining a supplied cached upstream message in the emitted frame.
 //
-// Dropping the warm Program is not enough on its own. An open document's content
-// belongs to the client rather than to disk, so the compiler has no reason to
-// republish for a URI whose file was deleted underneath it, and without that
-// republish nothing triggers the merge that would replace ttsc's cached set. The
-// user would keep looking at lint findings for a file that no longer exists.
+// This unit supplies deletion/change notifications without creating or deleting
+// a physical file. It observes the buffered notification and handler return,
+// not a compiler Program, actual upstream forwarding or editor presentation.
 //
 //  1. Seed one upstream and one plugin diagnostic for a document.
 //  2. Send a watched-file deletion for that document.
 //  3. Assert the republished set keeps the upstream diagnostic and drops the
 //     plugin one, and that a plain change publishes nothing by itself.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual handleEditorEnvelope on a supplied deletion notification returns handled=false and emits a publishDiagnostics frame for the expected URI containing only the literal cached upstream message. A subsequent supplied change notification emits no editor bytes; that branch does not inspect retained plugin-cache contents or recomputation.
+// @evidence contracts/testing.md#independent-expectations The expected published diagnostic sets are literals for the deleted document.
+// @evidence contracts/testing.md#distinguishing-cases Plugin findings and compiler diagnostics for one URI are separate sets, and only the plugin set is cleared.
+// @evidence contracts/testing.md#execution-ownership This Go unit creates an actual Proxy with supported bytes.Buffer editor output, io.Discard upstream input and NullPluginSource, seeds its caches through their owning methods and invokes the actual notification handler. The emitted frame is decoded through actual frame/envelope readers and compared to literal URI/message expectations. No physical file, sidecar, compiler, process or product host runs; handled=false does not itself observe upstream forwarding.
 func TestLSPDeletedWatchedFileWithdrawsPluginDiagnostics(t *testing.T) {
   const uri = "file:///project/src/gone.ts"
   var editor bytes.Buffer
@@ -64,9 +67,7 @@ func TestLSPDeletedWatchedFileWithdrawsPluginDiagnostics(t *testing.T) {
     t.Errorf("republished diagnostic = %q, want the compiler's", published.Diagnostics[0].Message)
   }
 
-  // Negative twin: an ordinary edit withdraws nothing. Its findings are still
-  // valid until the sidecar recomputes them, and the ordinary republish path
-  // owns that replacement.
+  // Negative twin: a supplied ordinary change emits no notification here.
   editor.Reset()
   proxy.rememberPluginDiagnostics(uri, nil, []LSPDiagnostic{{Message: "from the rule"}})
   change, _ := json.Marshal(map[string]any{