feat(radls): immutable DocumentVersion snapshots per document

Replace the in-place-mutated DocState with an immutable
DocumentVersion built fresh on every didOpen/didChange. A Document
owns the current snapshot via sync/atomic.Pointer; readers grab the
snapshot lock-free, writers serialize through the Document's mutex.

The load-bearing guarantee: once an LSP request handler has a
*DocumentVersion, the world it observes is frozen for the duration
of the request. Today the mux dispatches handlers serially so no
concurrency exists, but the next phase needs to spawn goroutines
per request to plumb context cancellation - and you absolutely do
not want hover racing against the next keystroke.

State.docs is now URI -> *Document. Per-document writes coordinate
via Document.mu; parser access goes through State.parserMu since
tree-sitter parsers are not goroutine-safe. The docs map is itself
guarded by an RWMutex so concurrent reads from different documents
don't block each other.

Diagnostics conversion moves into document.go's runChecker, which
takes (checker, LineIndex, encoding) - the canonical boundary
between check.Diagnostic (utf-8 byte cols) and lsp.Diagnostic
(client's negotiated encoding). The previous resolveDiagnostics
helper in diagnostics.go is gone; snapshot construction now owns
the translation end-to-end.

Tests: snapshot stability (pointer doesn't observe later writes),
concurrent readers + writers (race-clean under -race), guard
against UpdateDoc before AddDoc. Run with -race; passes.

Author: amterp

radls/analysis/diagnostics.go

@@ -3,74 +3,66 @@ package analysis
 import (
 	"testing"
 
+	"github.com/amterp/rad/radls/lsp"
+	"github.com/amterp/rad/rts"
 	"github.com/amterp/rad/rts/check"
+	"github.com/amterp/rad/rts/rl"
 )
 
-// TestToLspRangeUTF16 verifies the byte->utf-16 boundary conversion.
-// Documents the contract: check.Range carries utf-8 byte columns (the
-// tree-sitter native); resolveDiagnostics translates to the client's
-// negotiated encoding before publishing.
-func TestToLspRangeUTF16(t *testing.T) {
+// TestRunCheckerConvertsUTF16 verifies the byte->utf-16 boundary
+// conversion that runChecker applies when translating check
+// diagnostics into the wire format. Documents the contract:
+// check.Range carries utf-8 byte columns (tree-sitter native);
+// buildVersion translates to the client's negotiated encoding.
+func TestRunCheckerConvertsUTF16(t *testing.T) {
 	// Line 0: `x = "中"`  (9 bytes; 中 = 3 bytes, 1 utf-16 unit)
 	// Line 1: `y = "🎉"` (10 bytes; 🎉 = 4 bytes, 2 utf-16 units)
 	text := "x = \"中\"\ny = \"🎉\""
-
-	s := NewState()
-	s.SetEncoding(EncodingUTF16)
-	doc := &DocState{lineIndex: NewLineIndex(text)}
+	idx := NewLineIndex(text)
 
 	cases := []struct {
-		name     string
-		in       check.Range
-		wantSL   int
-		wantSC   int
-		wantEL   int
-		wantEC   int
+		name   string
+		in     check.Range
+		enc    PositionEncoding
+		wantSC int
+		wantEC int
 	}{
-		{
-			name:   "ascii range untouched",
-			in:     mkRange(0, 0, 0, 3),
-			wantSL: 0, wantSC: 0, wantEL: 0, wantEC: 3,
-		},
-		{
-			name:   "byte col after CJK char compresses to utf-16",
-			in:     mkRange(0, 4, 0, 9), // covers `"中"` (5 bytes -> 3 utf-16 units)
-			wantSL: 0, wantSC: 4, wantEL: 0, wantEC: 7,
-		},
-		{
-			name:   "byte col after astral char compresses",
-			in:     mkRange(1, 4, 1, 10), // covers `"🎉"` (6 bytes -> 4 utf-16 units)
-			wantSL: 1, wantSC: 4, wantEL: 1, wantEC: 8,
-		},
+		{"ascii range untouched utf-16", mkRange(0, 0, 0, 3), EncodingUTF16, 0, 3},
+		{"byte col after CJK -> utf-16", mkRange(0, 4, 0, 9), EncodingUTF16, 4, 7},
+		{"byte col after astral -> utf-16", mkRange(1, 4, 1, 10), EncodingUTF16, 4, 8},
+		{"utf-8 passthrough", mkRange(0, 4, 0, 9), EncodingUTF8, 4, 9},
 	}
 
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			got := s.toLspRange(tc.in, doc)
-			if got.Start.Line != tc.wantSL || got.Start.Character != tc.wantSC ||
-				got.End.Line != tc.wantEL || got.End.Character != tc.wantEC {
-				t.Errorf("got %d:%d-%d:%d, want %d:%d-%d:%d",
-					got.Start.Line, got.Start.Character, got.End.Line, got.End.Character,
-					tc.wantSL, tc.wantSC, tc.wantEL, tc.wantEC)
+			ck := &stubChecker{result: check.Result{Diagnostics: []check.Diagnostic{
+				{Range: tc.in, Severity: check.Error, Message: "x"},
+			}}}
+			diags := runChecker(ck, idx, tc.enc)
+			if len(diags) != 1 {
+				t.Fatalf("expected 1 diagnostic, got %d", len(diags))
+			}
+			got := diags[0].Range
+			if got.Start.Character != tc.wantSC || got.End.Character != tc.wantEC {
+				t.Errorf("got %d-%d, want %d-%d",
+					got.Start.Character, got.End.Character,
+					tc.wantSC, tc.wantEC)
 			}
 		})
 	}
 }
 
-// TestToLspRangeUTF8 verifies utf-8 is a passthrough (with clamping).
-// A client that negotiates utf-8 should get byte columns unchanged.
-func TestToLspRangeUTF8(t *testing.T) {
-	text := "x = \"中\""
-
-	s := NewState()
-	s.SetEncoding(EncodingUTF8)
-	doc := &DocState{lineIndex: NewLineIndex(text)}
-
-	in := mkRange(0, 4, 0, 9)
-	got := s.toLspRange(in, doc)
-	if got.Start.Character != 4 || got.End.Character != 9 {
-		t.Errorf("utf-8 passthrough: got %d-%d, want 4-9",
-			got.Start.Character, got.End.Character)
+// TestRunCheckerEmpty verifies the no-diagnostics path still returns
+// a non-nil (zero-length) slice, since the LSP wire format wants an
+// explicit [] for "no diagnostics."
+func TestRunCheckerEmpty(t *testing.T) {
+	ck := &stubChecker{result: check.Result{Diagnostics: nil}}
+	got := runChecker(ck, NewLineIndex(""), EncodingUTF16)
+	if got == nil {
+		t.Errorf("expected non-nil empty slice, got nil")
+	}
+	if len(got) != 0 {
+		t.Errorf("expected zero diagnostics, got %d", len(got))
 	}
 }
 
@@ -80,3 +72,18 @@ func mkRange(sl, sc, el, ec int) check.Range {
 		End:   check.Pos{Line: el, Character: ec},
 	}
 }
+
+// stubChecker is a minimal RadChecker for testing the conversion path
+// without needing a real parser/tree.
+type stubChecker struct {
+	result check.Result
+}
+
+func (s *stubChecker) UpdateSrc(string)                             {}
+func (s *stubChecker) Update(*rts.RadTree, string, *rl.SourceFile)  {}
+func (s *stubChecker) Check() (check.Result, error)                 { return s.result, nil }
+
+// Compile-time interface check. lsp import keeps the file honest if
+// the test ever drops its only lsp reference.
+var _ check.RadChecker = (*stubChecker)(nil)
+var _ = lsp.Diagnostic{}

radls/analysis/diagnostics_test.go

@@ -0,0 +1,135 @@
+package analysis
+
+import (
+	"sync"
+	"sync/atomic"
+
+	"github.com/amterp/rad/radls/lsp"
+
+	"github.com/amterp/rad/rts"
+	"github.com/amterp/rad/rts/check"
+	"github.com/amterp/rad/rts/rl"
+)
+
+// DocumentVersion is an immutable snapshot of a single parse of a
+// document. Multiple readers can hold the same *DocumentVersion
+// concurrently without coordination: the data inside is guaranteed
+// not to mutate. The next didChange produces a NEW DocumentVersion
+// (built off the old) and atomically swaps the owning Document's
+// current pointer; old versions remain valid for any reader still
+// holding them, and are GC'd once unreferenced.
+//
+// This is the load-bearing piece of Phase 8: it lets LSP request
+// handlers (hover, goto-def, completion, etc.) grab a snapshot once
+// and reason about a frozen world for the duration of the request,
+// rather than racing against the next keystroke.
+type DocumentVersion struct {
+	uri         string
+	version     int64
+	text        string
+	tree        *rts.RadTree
+	ast         *rl.SourceFile
+	lineIndex   *LineIndex
+	diagnostics []lsp.Diagnostic
+}
+
+func (v *DocumentVersion) URI() string                  { return v.uri }
+func (v *DocumentVersion) Version() int64               { return v.version }
+func (v *DocumentVersion) Text() string                 { return v.text }
+func (v *DocumentVersion) Tree() *rts.RadTree           { return v.tree }
+func (v *DocumentVersion) AST() *rl.SourceFile          { return v.ast }
+func (v *DocumentVersion) LineIndex() *LineIndex        { return v.lineIndex }
+func (v *DocumentVersion) Diagnostics() []lsp.Diagnostic { return v.diagnostics }
+
+// GetLine returns the source of the line at the given index, or "" if
+// out of range. Kept on DocumentVersion (not LineIndex) because callers
+// usually want both the text and the index together.
+func (v *DocumentVersion) GetLine(line int) string {
+	idx := v.lineIndex
+	if line < 0 || line >= idx.LineCount() {
+		return ""
+	}
+	return idx.lineSlice(line)
+}
+
+// Document owns the current snapshot of one LSP document. The snapshot
+// pointer is read lock-free; writers serialize through `mu` to ensure
+// a coherent prev->next chain (tree-sitter parsing today is wholesale,
+// but a future incremental-parse path would still want this invariant).
+type Document struct {
+	snapshot atomic.Pointer[DocumentVersion]
+	mu       sync.Mutex
+}
+
+// Snapshot returns the current immutable version of this document.
+// Lock-free; safe to call from any goroutine.
+func (d *Document) Snapshot() *DocumentVersion {
+	return d.snapshot.Load()
+}
+
+// Update runs `produce` under the writer lock to compute the next
+// version from the previous (nil on first open), then atomically swaps
+// it into place. Returns the new version.
+func (d *Document) Update(produce func(prev *DocumentVersion) *DocumentVersion) *DocumentVersion {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	prev := d.snapshot.Load()
+	next := produce(prev)
+	d.snapshot.Store(next)
+	return next
+}
+
+// buildVersion is the canonical way to construct a DocumentVersion: it
+// parses the source, builds the AST, indexes lines, runs the static
+// checker, and translates diagnostics into the negotiated encoding.
+// Caller (typically State) owns the parser and encoding it passes in.
+func buildVersion(
+	parser *rts.RadParser,
+	encoding PositionEncoding,
+	uri string,
+	version int64,
+	text string,
+) *DocumentVersion {
+	tree := parser.Parse(text)
+	ast := safeConvertCST(tree, text, uri)
+	lineIndex := NewLineIndex(text)
+
+	checker := check.NewCheckerWithTree(tree, parser, text, ast)
+	diags := runChecker(checker, lineIndex, encoding)
+
+	return &DocumentVersion{
+		uri:         uri,
+		version:     version,
+		text:        text,
+		tree:        tree,
+		ast:         ast,
+		lineIndex:   lineIndex,
+		diagnostics: diags,
+	}
+}
+
+// runChecker is the boundary between check.Diagnostic (utf-8 byte
+// columns) and lsp.Diagnostic (negotiated encoding). Lives here so the
+// snapshot construction path owns the translation, rather than scatter
+// it across the analysis package.
+func runChecker(checker check.RadChecker, idx *LineIndex, enc PositionEncoding) []lsp.Diagnostic {
+	out := make([]lsp.Diagnostic, 0)
+	result, err := checker.Check()
+	if err != nil {
+		return out
+	}
+	for _, cd := range result.Diagnostics {
+		rang := lsp.Range{
+			Start: lsp.Pos{
+				Line:      cd.Range.Start.Line,
+				Character: idx.ByteColumnTo(cd.Range.Start.Line, cd.Range.Start.Character, enc),
+			},
+			End: lsp.Pos{
+				Line:      cd.Range.End.Line,
+				Character: idx.ByteColumnTo(cd.Range.End.Line, cd.Range.End.Character, enc),
+			},
+		}
+		out = append(out, lsp.NewDiagnosticFromCheckWithRange(cd, rang))
+	}
+	return out
+}