ttsc 0.30.4 → 0.31.0

package/internal/graphsymbols/provider.go

@@ -21,6 +21,7 @@ import (
   "os"
   "path/filepath"
   "sort"
+  "strconv"
   "strings"
   "sync"
   "unicode/utf16"
@@ -35,22 +36,101 @@ import (
 
 // Provider computes documentSymbol/references from a code graph built for one
 // project (tsconfig). The graph is loaded lazily on the first request and
-// cached until Invalidate is called; the proxy invalidates on didChange/didSave
-// so a long-lived editor session reflects source edits instead of freezing at
-// the first request's snapshot. It is safe for concurrent use.
+// cached until Invalidate is called. Queries use on-disk sources, not unsaved
+// editor buffers; the proxy invalidates on source and project-state changes.
+// It is safe for concurrent use. A request already holding an immutable
+// snapshot may finish on it while the next request loads a replacement.
+//
+// @evidence contracts/common.md#principled-implementation The provider combines a compiler-backed graph, its source texts and the compiler filesystem's case policy in one snapshot; UTF-16 LSP positions are converted against those exact bytes.
+// @evidence contracts/common.md#clear-and-simple-design The project anchor and mutex own snapshot publication. Private indexes answer graph queries without coupling the LSP wire types to mutable compiler objects.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The graph comes from the supported driver and checker rather than source-pattern inference or replaced language-server methods. This fallback explicitly answers from saved files, not an invented live-buffer snapshot.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain lazy loading, saved-source semantics, invalidation and concurrent snapshot ownership under the documentation skill's state and limitation guidance.
+// @evidence contracts/portability.md#os-neutral-implementation Native project anchors remain separate from file URIs. Source identity uses the loaded compiler's case policy, not unconditional case folding or the host OS name.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The representation groups snapshot ownership; its load and query operations choose the processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The load operation authorizes sharing and invalidation; this type defines the state it protects.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Acquisition and snapshot replacement belong to load and Invalidate rather than this representation independently.
 type Provider struct {
-  cwd      string
+  // cwd anchors the compiler project independently of request URI spelling.
+  cwd string
+
+  // tsconfig selects the project rebuilt after invalidation.
   tsconfig string
 
-  mu      sync.Mutex
-  loaded  bool
-  graph   *graph.Graph
-  sources map[string]string
+  // mu protects short publication and invalidation transitions.
+  mu sync.Mutex
+
+  // buildMu permits one native compilation without blocking invalidation.
+  buildMu sync.Mutex
+
+  // loading identifies the flight authorized to publish the current generation.
+  loading *providerLoad
+
+  // loaded records either a published snapshot or a cached load failure.
+  loaded bool
+
+  // snapshot is the current immutable saved-project generation.
+  snapshot *providerSnapshot
+
+  // loadErr is retried after the same invalidation that revokes a snapshot.
   loadErr error
 }
 
+// providerLoad shares one generation's result. Closing done publishes its
+// immutable result to waiters even when invalidation revoked global retention.
+type providerLoad struct {
+  done chan struct{}
+
+  snapshot *providerSnapshot
+
+  err error
+}
+
+// providerSnapshot keeps the compiler's source identities with the graph that
+// resolved them. An in-flight request may finish on its snapshot after a later
+// invalidation without observing half of the replacement state.
+type providerSnapshot struct {
+  graph *graph.Graph
+
+  sources map[string]string
+
+  caseSensitive bool
+
+  files map[string]string
+
+  nodesByFile map[string][]*graph.Node
+
+  edgesByFile map[string][]*graph.Edge
+
+  incoming map[string][]*graph.Edge
+}
+
+func (s *providerSnapshot) fileKey(path string) string {
+  return shimtspath.GetCanonicalFileName(shimtspath.NormalizePath(path), s.caseSensitive)
+}
+
+func (s *providerSnapshot) fileFromURI(uri string) (string, bool) {
+  path, ok := filePathFromURI(uri)
+  if !ok {
+    return "", false
+  }
+  file, ok := s.files[s.fileKey(shimtspath.ResolvePath(path))]
+  return file, ok
+}
+
 // NewProvider returns a Provider that builds the graph for the project rooted at
 // cwd using tsconfig (defaulting to "tsconfig.json").
+// It acquires no compiler or file handle; the first query loads saved sources.
+// The caller keeps the provider for one project and invalidates it when that
+// project's source or configuration state changes.
+//
+// @evidence contracts/common.md#principled-implementation The constructor preserves the project anchor and selects the documented default only for a blank config selector; loading is deferred until a query needs compiler facts.
+// @evidence contracts/common.md#clear-and-simple-design Construction initializes identity only. The shared load path owns compilation, errors and snapshot indexes for both query methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The default config name is the CLI contract; no consumer identity or expected graph affects it, and no foreign server is patched.
+// @evidence contracts/common.md#meaningful-documentation Native prose states lazy acquisition, saved-source semantics and the caller's invalidation responsibility under the documentation skill's ownership guidance.
+// @evidence contracts/portability.md#os-neutral-implementation cwd and tsconfig retain native path spelling for the driver to resolve; URI decoding and actual compiler case policy belong to the loaded snapshot.
+// @evidence contracts/performance.md#efficient-algorithms Construction trims only the config selector and allocates one provider; it does not eagerly scan sources or build a graph no request needs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The constructor creates one project owner; the common load operation coordinates its later requests.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives ownership of one provider with no open handle. Lazy snapshots live until invalidation or the last provider/request reference is dropped; no global history retains past projects.
 func NewProvider(cwd, tsconfig string) *Provider {
   tsconfig = strings.TrimSpace(tsconfig)
   if tsconfig == "" {
@@ -59,16 +139,46 @@ func NewProvider(cwd, tsconfig string) *Provider {
   return &Provider{cwd: cwd, tsconfig: tsconfig}
 }
 
-// load builds (once) and returns the cached graph and per-file source texts,
-// mirroring how cmd/ttscgraph/dump.go resolves the project and drives the graph
-// package.
-func (pr *Provider) load() (*graph.Graph, map[string]string, error) {
+// load shares one flight per invalidation generation. Native compilation runs
+// outside the publication mutex so editor notifications can revoke a flight
+// without waiting for parsing or graph construction. Revoked flights may answer
+// their existing requests but cannot republish into the current generation.
+func (pr *Provider) load() (*providerSnapshot, error) {
   pr.mu.Lock()
-  defer pr.mu.Unlock()
   if pr.loaded {
-    return pr.graph, pr.sources, pr.loadErr
-  }
-  pr.loaded = true
+    snapshot, err := pr.snapshot, pr.loadErr
+    pr.mu.Unlock()
+    return snapshot, err
+  }
+  if pr.loading != nil {
+    flight := pr.loading
+    pr.mu.Unlock()
+    <-flight.done
+    return flight.snapshot, flight.err
+  }
+  flight := &providerLoad{done: make(chan struct{})}
+  pr.loading = flight
+  pr.mu.Unlock()
+
+  snapshot, err := pr.buildSnapshot()
+  pr.mu.Lock()
+  flight.snapshot, flight.err = snapshot, err
+  if pr.loading == flight {
+    pr.snapshot, pr.loadErr = snapshot, err
+    pr.loaded = true
+    pr.loading = nil
+  }
+  close(flight.done)
+  pr.mu.Unlock()
+  return snapshot, err
+}
+
+// buildSnapshot serializes native acquisition separately from publication.
+// Repeated invalidations can leave old callers waiting, but only one Program
+// is built at a time and every acquired Program closes before this returns.
+func (pr *Provider) buildSnapshot() (*providerSnapshot, error) {
+  pr.buildMu.Lock()
+  defer pr.buildMu.Unlock()
 
   cwd := pr.cwd
   if abs, err := filepath.Abs(cwd); err == nil {
@@ -78,94 +188,154 @@ func (pr *Provider) load() (*graph.Graph, map[string]string, error) {
 
   prog, _, err := driver.LoadProgram(cwd, pr.tsconfig, driver.LoadProgramOptions{})
   if err != nil {
-    pr.loadErr = err
-    return nil, nil, err
+    return nil, err
   }
   if prog == nil {
-    pr.loadErr = fmt.Errorf("graphsymbols: could not load %s/%s", cwd, pr.tsconfig)
-    return nil, nil, pr.loadErr
+    return nil, fmt.Errorf("graphsymbols: could not load %s/%s", cwd, pr.tsconfig)
   }
   defer func() { _ = prog.Close() }()
 
-  pr.graph = graph.Build(prog)
-  pr.sources = graph.SourceTexts(prog)
-  return pr.graph, pr.sources, nil
+  snapshot := &providerSnapshot{
+    graph:         graph.Build(prog),
+    sources:       graph.SourceTexts(prog),
+    caseSensitive: prog.TSProgram.UseCaseSensitiveFileNames(),
+    files:         map[string]string{},
+    nodesByFile:   map[string][]*graph.Node{},
+    edgesByFile:   map[string][]*graph.Edge{},
+    incoming:      map[string][]*graph.Edge{},
+  }
+  for file := range snapshot.sources {
+    snapshot.files[snapshot.fileKey(file)] = file
+  }
+  for _, node := range snapshot.graph.Nodes {
+    if surfaceableNode(node) {
+      key := snapshot.fileKey(node.File)
+      snapshot.nodesByFile[key] = append(snapshot.nodesByFile[key], node)
+    }
+  }
+  for _, edge := range snapshot.graph.Edges {
+    file := edgeSourceFile(edge)
+    if file != "" {
+      key := snapshot.fileKey(file)
+      snapshot.edgesByFile[key] = append(snapshot.edgesByFile[key], edge)
+    }
+    if !isStructuralEdge(edge.Kind) {
+      snapshot.incoming[edge.To] = append(snapshot.incoming[edge.To], edge)
+    }
+  }
+  return snapshot, nil
 }
 
 // Invalidate discards the cached graph so the next DocumentSymbols/References
 // call rebuilds it against the current on-disk sources. The proxy calls this on
 // didChange/didSave; without it the first request's snapshot would answer every
 // later request for the process lifetime.
+// Already-running requests retain their immutable snapshot until they return.
+// This transition never waits for native compilation; a revoked flight may
+// finish its existing requests but cannot publish over the replacement state.
+//
+// @evidence contracts/common.md#principled-implementation The publication mutex clears the snapshot and cached error so future queries acquire a new saved-source view. Flight publication is coherent, but acquisition is not an atomic filesystem snapshot.
+// @evidence contracts/common.md#clear-and-simple-design One transition resets loaded state and snapshot ownership; each query uses a single captured snapshot rather than separately mutable graph and source fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Invalidation responds to the caller's actual project-state notifications; it does not fabricate fresh facts from a quiet watcher or suppress a retained load failure.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes future requests from in-flight readers and names the saved-source rebuild boundary under documentation-skill guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This state transition performs no filesystem, path comparison or process operation; load retains the native project boundary.
+// @evidence contracts/performance.md#efficient-algorithms Resetting the owner clears a constant number of references without walking graph entries or copying retained source bytes.
+// @evidence contracts/performance.md#reuse-equivalent-work Clearing loaded state, errors and the authorized flight revokes reuse for subsequent queries. Publication checks exact flight identity under the mutex, so a revoked load cannot overwrite newer state; its existing callers can still finish on its own result.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Owner snapshot/source/index/error references are dropped together, but invalidation does not cancel running or queued native builds. Repeated invalidations can retain uncapped old flights and request-held snapshots until their work and references finish; no deadline or cancellation policy is provided here.
 func (pr *Provider) Invalidate() {
   pr.mu.Lock()
   defer pr.mu.Unlock()
   pr.loaded = false
-  pr.graph = nil
-  pr.sources = nil
+  pr.loading = nil
+  pr.snapshot = nil
   pr.loadErr = nil
 }
 
 // DocumentSymbols returns the declarations in uri as a hierarchy: top-level
 // declarations at the root, class/interface members nested under their owner.
+// Unknown files return an empty list; project-load failures return an error.
+// Declaration ranges also serve as selection ranges because the graph does
+// not separately record identifier spans. The result uses saved UTF-8 source
+// converted to fixed UTF-16 coordinates, matching the proxy's session policy.
+//
+// @evidence contracts/common.md#principled-implementation Compiler graph nodes are grouped by qualified owner, excluding file-module and external leaves. Strict owner prefixes terminate nesting; saved bytes supply valid UTF-16 ranges, with declaration spans used for selection as documented.
+// @evidence contracts/common.md#clear-and-simple-design The method selects a snapshot and file, then delegates hierarchy and range construction to focused helpers. It does not reproduce compiler declaration discovery.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Actual graph declarations determine the outline; source strings are not searched for expected names and foreign LSP methods remain unchanged.
+// @evidence contracts/common.md#meaningful-documentation Native prose specifies empty-file handling, load failure, saved-source coordinates and the selection-range limitation under the documentation skill's units and absence guidance.
+// @evidence contracts/portability.md#os-neutral-implementation File URIs are decoded to native paths and looked up using the snapshot's compiler case policy. The provider preserves the compiler's identity decisions rather than claiming to measure every directory's native case capability independently.
+// @evidence contracts/performance.md#efficient-algorithms A cold query first loads and indexes the native project. A cached query selects file-local nodes, hashes qualified-name bytes, groups owners and sorts siblings in at most O(N log N) comparisons, including tied-name comparisons. One source-byte line index is shared, but each range still skips leading trivia, binary-searches line starts and decodes its line prefixes to UTF-16; deeply nested owners also consume recursive stack depth.
+// @evidence contracts/performance.md#reuse-equivalent-work load shares one flight, graph, source set and indexes per invalidation generation, including a load error. Native builds are serialized separately from short publication/invalidation transitions; exact flight identity prevents revoked loads from republishing. Actual caller invalidation remains required on changed project state.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Graph extraction defers Program.Close but ignores its returned error. Snapshot/index/source bytes, revoked in-flight generations, hierarchy depth and returned symbols have no cap here; invalidation does not cancel queued builds. Query-local maps and line indexes are not retained as history, while results can share name strings with the captured graph. Native loading supplies no deadline in this method.
 func (pr *Provider) DocumentSymbols(uri string) ([]lspserver.LSPDocumentSymbol, error) {
-  g, sources, err := pr.load()
+  snapshot, err := pr.load()
   if err != nil {
     return nil, err
   }
-  file, ok := fileFromURI(uri, sources)
+  file, ok := snapshot.fileFromURI(uri)
   if !ok {
     return []lspserver.LSPDocumentSymbol{}, nil
   }
-  text := sources[file]
+  text := snapshot.sources[file]
 
-  var fileNodes []*graph.Node
-  for _, n := range g.Nodes {
-    if !surfaceableNode(n) {
-      continue
-    }
-    if pathsEqual(n.File, file) {
-      fileNodes = append(fileNodes, n)
-    }
-  }
+  fileNodes := snapshot.nodesByFile[snapshot.fileKey(file)]
   return buildDocumentSymbols(fileNodes, text), nil
 }
 
 // References returns the usage locations of the symbol at pos in uri. When
 // includeDeclaration is set the symbol's own declaration is added to the result.
+// A covering usage expression takes precedence over its enclosing declaration
+// body. Non-addressable files or positions return an empty list, and load
+// failures return an error. Each edge retains its explicit source-file provenance
+// when an assigned implementation lives outside the owning declaration's file.
+//
+// @evidence contracts/common.md#principled-implementation UTF-16 positions select the narrowest covering usage expression before a declaration. Incoming non-export edges provide uses, explicit edge files preserve assigned-implementation provenance, and exact URI/byte-span keys remove duplicate locations.
+// @evidence contracts/common.md#clear-and-simple-design Snapshot indexes select the file, candidate symbol and incoming edges. One location builder owns source lookup, byte-to-UTF-16 conversion and deduplication for both uses and the optional declaration.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Recorded graph endpoints supply target identity; the graph can also contain artifact relations, so an endpoint is not by itself a checker-binding certificate. Covering uses take precedence over declaration fallback without textual name guesses. Structural exports are excluded because they are publication facts without use spans.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs describe cursor precedence, declaration inclusion, empty/error outcomes and cross-file edge provenance under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation URI resolution uses compiler case-aware snapshot keys. Locations preserve the actual recorded file and encode URI spelling separately from native filesystem identity.
+// @evidence contracts/performance.md#efficient-algorithms A cold query includes native project loading and indexing. Cached target selection scans file-local edges and, when needed, nodes; converting the input position also builds its source line index. Incoming edges avoid an all-project scan. Output line indexes are shared per file, but URI/span key construction and two UTF-16 prefix decodings happen for each candidate before duplicate suppression, with source-byte, key-byte and line-prefix costs in addition to entry counts.
+// @evidence contracts/performance.md#reuse-equivalent-work Both query methods share the mutex-published graph and its source/index generation until invalidation. Within a response, immutable source text authorizes sharing each file's line index across all its locations.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Snapshot nodes, edges, names, keys, source bytes and indexes are uncapped, as are request-local candidate keys, line indexes and returned locations. Invalidation drops current owner references without cancelling old flights or requests. Extraction defers Program.Close with errors ignored; this method adds no load deadline or cancellation. Local lookup state becomes reclaimable after return, and returned URI strings remain caller-owned.
 func (pr *Provider) References(uri string, pos lspserver.LSPPosition, includeDeclaration bool) ([]lspserver.LSPLocation, error) {
-  g, sources, err := pr.load()
+  snapshot, err := pr.load()
   if err != nil {
     return nil, err
   }
-  file, ok := fileFromURI(uri, sources)
+  file, ok := snapshot.fileFromURI(uri)
   if !ok {
     return []lspserver.LSPLocation{}, nil
   }
-  text := sources[file]
+  text := snapshot.sources[file]
   offset, ok := lspPositionToOffset(text, pos)
   if !ok {
     return []lspserver.LSPLocation{}, nil
   }
-  target := targetNodeAt(g, file, offset)
+  target := targetNodeAt(snapshot, file, offset)
   if target == nil {
     return []lspserver.LSPLocation{}, nil
   }
 
   locations := []lspserver.LSPLocation{}
   seen := map[string]struct{}{}
+  lineStarts := map[string][]int{}
   add := func(f string, start, end int) {
-    t, ok := sources[f]
+    t, ok := snapshot.sources[f]
     if !ok {
       return
     }
     if end < start {
       end = start
     }
+    starts := lineStarts[f]
+    if starts == nil {
+      starts = graph.ECMALineStarts(t)
+      lineStarts[f] = starts
+    }
     loc := lspserver.LSPLocation{
       URI: uriFromFile(f),
       Range: lspserver.LSPRange{
-        Start: offsetToPosition(t, start),
-        End:   offsetToPosition(t, end),
+        Start: offsetToPositionAt(t, starts, start),
+        End:   offsetToPositionAt(t, starts, end),
       },
     }
     key := fmt.Sprintf("%s:%d:%d", loc.URI, start, end)
@@ -176,26 +346,22 @@ func (pr *Provider) References(uri string, pos lspserver.LSPPosition, includeDec
     locations = append(locations, loc)
   }
 
-  // Edges are directed From a using declaration To the referenced symbol, so an
-  // edge whose To is the target node is one usage site; its span lives in the
-  // From node's file (graph's edge-evidence contract).
+  // Edges point from a using declaration to the referenced symbol. Assigned
+  // implementations may carry an explicit File different from that declaration.
   //
   // A structural edge is not a usage. A module's `exports` edge says the symbol
   // stands on that module's public surface — a fact about the declaration, not a
   // place it is used — and it carries no span, so counting it as a usage puts a
   // phantom reference at the top of the file.
-  for _, e := range g.Edges {
-    if e.To != target.ID || isStructuralEdge(e.Kind) {
-      continue
-    }
-    f := graph.NodeFile(e.From)
+  for _, e := range snapshot.incoming[target.ID] {
+    f := edgeSourceFile(e)
     if f == "" {
       continue
     }
     add(f, e.Pos, e.End)
   }
   if includeDeclaration {
-    declText := sources[target.File]
+    declText := snapshot.sources[target.File]
     add(target.File, graph.FirstCodeOffset(declText, target.Pos), target.End)
   }
   return locations, nil
@@ -220,9 +386,10 @@ func buildDocumentSymbols(nodes []*graph.Node, text string) []lspserver.LSPDocum
     }
   }
   sortNodes(roots)
+  starts := graph.ECMALineStarts(text)
   out := make([]lspserver.LSPDocumentSymbol, 0, len(roots))
   for _, r := range roots {
-    out = append(out, buildSymbol(r, childrenOf, text))
+    out = append(out, buildSymbol(r, childrenOf, text, starts))
   }
   return out
 }
@@ -230,30 +397,35 @@ func buildDocumentSymbols(nodes []*graph.Node, text string) []lspserver.LSPDocum
 // buildSymbol materializes one node (and, recursively, the nodes owned by it)
 // as an LSPDocumentSymbol. The owner relation is a strict name-prefix, so the
 // recursion terminates (no cycles).
-func buildSymbol(n *graph.Node, childrenOf map[string][]*graph.Node, text string) lspserver.LSPDocumentSymbol {
-  sym := nodeToSymbol(n, text)
+func buildSymbol(n *graph.Node, childrenOf map[string][]*graph.Node, text string, starts []int) lspserver.LSPDocumentSymbol {
+  sym := nodeToSymbol(n, text, starts)
   kids := childrenOf[n.Name]
   sortNodes(kids)
   for _, k := range kids {
-    sym.Children = append(sym.Children, buildSymbol(k, childrenOf, text))
+    sym.Children = append(sym.Children, buildSymbol(k, childrenOf, text, starts))
   }
   return sym
 }
 
-func nodeToSymbol(n *graph.Node, text string) lspserver.LSPDocumentSymbol {
+func nodeToSymbol(n *graph.Node, text string, starts []int) lspserver.LSPDocumentSymbol {
   start := graph.FirstCodeOffset(text, n.Pos)
   end := n.End
   if end < start {
     end = start
   }
   rng := lspserver.LSPRange{
-    Start: offsetToPosition(text, start),
-    End:   offsetToPosition(text, end),
+    Start: offsetToPositionAt(text, starts, start),
+    End:   offsetToPositionAt(text, starts, end),
+  }
+  // A quoted member can have an empty or whitespace-only semantic name. Keep
+  // that graph identity, but quote its display label because LSP symbol names
+  // must contain a visible character.
+  name := n.Simple
+  if strings.TrimSpace(name) == "" {
+    name = strconv.Quote(name)
   }
-  // Callers pass only surfaceableNode candidates, so Simple is the declared
-  // identifier and never the file path a module node carries as its name.
   return lspserver.LSPDocumentSymbol{
-    Name:  n.Simple,
+    Name:  name,
     Kind:  symbolKind(n.Kind),
     Range: rng,
     // The graph does not record the identifier's own span separately, so the
@@ -268,7 +440,7 @@ func nodeToSymbol(n *graph.Node, text string) lspserver.LSPDocumentSymbol {
 // node's recorded simple name so a quoted member whose name contains a dot splits
 // exactly.
 func ownerName(n *graph.Node) string {
-  if n.Simple == "" || n.Name == n.Simple {
+  if (n.Simple == "" && !n.HasSimple) || n.Name == n.Simple {
     return ""
   }
   suffix := "." + n.Simple
@@ -302,36 +474,43 @@ func symbolKind(k graph.NodeKind) lspserver.LSPSymbolKind {
   }
 }
 
-// targetNodeAt resolves the symbol the cursor addresses: the smallest
-// declaration whose span contains offset (so a method wins over its enclosing
-// class), or, when the cursor sits on a usage rather than a declaration, the
-// node an edge whose source expression covers the offset points to.
-func targetNodeAt(g *graph.Graph, file string, offset int) *graph.Node {
-  var best *graph.Node
-  for _, n := range g.Nodes {
-    if !surfaceableNode(n) || !pathsEqual(n.File, file) {
+// targetNodeAt prefers the narrowest usage expression at the cursor, then the
+// narrowest declaration. Declaration spans include bodies, so selecting them
+// first would resolve every call in a function body to the containing function.
+func targetNodeAt(snapshot *providerSnapshot, file string, offset int) *graph.Node {
+  key := snapshot.fileKey(file)
+  var usage *graph.Edge
+  for _, edge := range snapshot.edgesByFile[key] {
+    if isStructuralEdge(edge.Kind) || offset < edge.Pos || offset >= edge.End {
+      continue
+    }
+    if snapshot.graph.Nodes[edge.To] == nil {
       continue
     }
+    if usage == nil || edge.End-edge.Pos < usage.End-usage.Pos {
+      usage = edge
+    }
+  }
+  if usage != nil {
+    return snapshot.graph.Nodes[usage.To]
+  }
+  var best *graph.Node
+  for _, n := range snapshot.nodesByFile[key] {
     if offset >= n.Pos && offset < n.End {
       if best == nil || (n.End-n.Pos) < (best.End-best.Pos) {
         best = n
       }
     }
   }
-  if best != nil {
-    return best
-  }
-  for _, e := range g.Edges {
-    if !pathsEqual(graph.NodeFile(e.From), file) {
-      continue
-    }
-    if offset >= e.Pos && offset < e.End {
-      if n, ok := g.Nodes[e.To]; ok {
-        return n
-      }
-    }
+  return best
+}
+
+// edgeSourceFile respects the graph's assigned-implementation provenance.
+func edgeSourceFile(edge *graph.Edge) string {
+  if edge.File != "" {
+    return edge.File
   }
-  return nil
+  return graph.NodeFile(edge.From)
 }
 
 // isStructuralEdge reports an edge that records where a symbol stands rather than
@@ -341,13 +520,15 @@ func isStructuralEdge(kind graph.EdgeKind) bool {
 }
 
 // surfaceableNode reports whether a graph node should appear as a user-facing
-// LSP symbol or reference target. A per-file module node (NodeModule) carries
+// LSP outline entry or declaration fallback. A per-file module node (NodeModule) carries
 // the source file path as its name and spans the whole file, so surfacing it
 // would put the absolute path in the outline and swallow whole-file reference
-// queries. External boundary leaves and nameless nodes are likewise not
-// addressable declarations.
+// queries. External boundary leaves and nodes without a recorded member name
+// are likewise omitted from declaration candidates. A recorded usage edge can
+// still identify an external reference target. HasSimple preserves valid empty
+// string names rather than treating them as absence.
 func surfaceableNode(n *graph.Node) bool {
-  return !n.External && n.Kind != graph.NodeModule && n.Simple != ""
+  return !n.External && n.Kind != graph.NodeModule && (n.Simple != "" || n.HasSimple)
 }
 
 func sortNodes(nodes []*graph.Node) {
@@ -359,28 +540,6 @@ func sortNodes(nodes []*graph.Node) {
   })
 }
 
-// fileFromURI maps a file:// uri onto the source map key for the same file,
-// returning that key so text lookups by it succeed. Paths are compared
-// case-insensitively so a Windows drive-letter case mismatch between the
-// editor's uri and tsgo's normalized path still resolves.
-func fileFromURI(uri string, sources map[string]string) (string, bool) {
-  path, ok := filePathFromURI(uri)
-  if !ok {
-    return "", false
-  }
-  resolved := shimtspath.ResolvePath(path)
-  for key := range sources {
-    if pathsEqual(key, resolved) || pathsEqual(key, path) {
-      return key, true
-    }
-  }
-  return "", false
-}
-
-func pathsEqual(a, b string) bool {
-  return strings.EqualFold(filepath.ToSlash(a), filepath.ToSlash(b))
-}
-
 // filePathFromURI decodes a file:// uri to an absolute OS path. It mirrors the
 // proxy's own unexported converter so this package stays self-contained.
 func filePathFromURI(raw string) (string, bool) {
@@ -389,7 +548,8 @@ func filePathFromURI(raw string) (string, bool) {
     return "", false
   }
   path := parsed.Path
-  if parsed.Host != "" {
+  // RFC 8089 gives localhost the same local meaning as an absent authority.
+  if parsed.Host != "" && !strings.EqualFold(parsed.Host, "localhost") {
     path = "//" + parsed.Host + path
   }
   if path == "" {
@@ -419,13 +579,18 @@ func uriFromFile(path string) string {
 // PositionEncodingKind, which the proxy's constrainInitializePositionEncoding
 // pins to UTF-16 for every ttscserver session.
 func offsetToPosition(text string, offset int) lspserver.LSPPosition {
+  return offsetToPositionAt(text, graph.ECMALineStarts(text), offset)
+}
+
+// offsetToPositionAt shares a source's line index across all ranges in a
+// response. The index and text must come from the same immutable snapshot.
+func offsetToPositionAt(text string, starts []int, offset int) lspserver.LSPPosition {
   if offset < 0 {
     offset = 0
   }
   if offset > len(text) {
     offset = len(text)
   }
-  starts := graph.ECMALineStarts(text)
   line := sort.Search(len(starts), func(i int) bool { return starts[i] > offset }) - 1
   if line < 0 {
     line = 0

package/internal/lspserver/lsp_clean_didopen_refreshes_compiler_state_test.go

@@ -67,23 +67,25 @@ func didOpenEnvelope(uri string, text string) Envelope {
   return Envelope{JSONRPC: "2.0", Method: methodDidOpen, Params: params}
 }
 
-// TestLSPCleanDidOpenRefreshesCompilerState verifies that opening a document
-// whose buffer already matches disk refreshes both compiler-backed caches, while
-// opening a dirty buffer still refreshes neither.
+// TestLSPCleanDidOpenRefreshesCompilerState checks invalidation dispatch on
+// directly supplied clean and dirty didOpen envelopes. The resident source and
+// symbol provider are recording instances, not actual compiler-backed caches.
 //
-// The resident lint Program and the graph symbol provider stay warm for the
-// whole editor session, and before this only didSave refreshed them. A document
-// closed across a branch switch, a `git pull`, or an edit from a second editor
-// therefore came back with diagnostics computed over the pre-change AST and
-// published against the new buffer. Equality with today's disk is not evidence
-// that the warm Program was built from today's disk, so the clean branch is
-// exactly the branch that must invalidate — and the dirty branch, which reports
-// nothing at all until the buffer reaches disk, must keep not invalidating.
+// Matching disk should dispatch one invalidation to each recording instance and
+// name the clean URI; a dirty second file should not increase either count.
+// Returning handled=false establishes eligibility for forwarding, not an actual
+// upstream frame. Program freshness and published diagnostic content are not
+// observed, and the scheduled NullPluginSource diagnostics are not joined here.
 //
 //  1. Write a file, open it with the same text, and assert both caches were
 //     refreshed and the resident refresh named that document's URI.
 //  2. Open a second file with text that differs from disk.
-//  3. Assert neither cache was refreshed and the notification still forwards.
+//  3. Assert neither recorder gained a call and the notification is not handled.
+//
+// @evidence contracts/testing.md#behavioral-verification A clean direct didOpen produces one recorded symbol invalidation and one resident invalidation naming its URI; a dirty second open preserves both counts. Both return handled=false. Actual compiler cache refresh, diagnostic content, upstream forwarding, and asynchronous completion are not asserted.
+// @evidence contracts/testing.md#independent-expectations The refresh counts and the named URI are literal expectations for the two opened files.
+// @evidence contracts/testing.md#distinguishing-cases Two owned files have the same disk bytes, but the clean buffer matches and the dirty buffer differs. They also have different URIs and run sequentially on one proxy; this is not a one-variable-only or reversed-order experiment.
+// @evidence contracts/testing.md#execution-ownership Owns two temporary native files and a NewProxy with supported instance-owned recording PluginSource/SymbolProvider and io.Discard streams. Direct handleEditorEnvelope reads buffer/disk state and schedules NullPluginSource diagnostics on the clean branch; no join or diagnostics-result oracle is claimed. No actual compiler Program, sidecar, product CLI, installed consumer, or upstream server runs.
 func TestLSPCleanDidOpenRefreshesCompilerState(t *testing.T) {
   dir := t.TempDir()
   clean := filepath.Join(dir, "clean.ts")