ttsc 0.18.4 → 0.19.0

package/internal/graph/edges.go

@@ -37,7 +37,12 @@ func (g *Graph) addEdgeAt(from, to string, kind EdgeKind, origin string, pos, en
   // target that surface as different relationships (a call and a `new`, an
   // `extends` and an `implements` of the same base) are both kept, while
   // repeated uses of the same form collapse to one edge.
-  key := from + "\x00" + to + "\x00" + wireEdgeKind(kind, origin)
+  //
+  // The key is a struct, not a concatenation. Concatenating allocated a fresh
+  // string per *candidate* edge — including the duplicates thrown away on the
+  // next line, which on a large program are most of them — and a comparable
+  // struct of the three fields hashes just as well for nothing.
+  key := edgeKey{from: from, to: to, kind: wireEdgeKind(kind, origin)}
   if _, exists := g.seen[key]; exists {
     return
   }
@@ -101,7 +106,7 @@ func (g *Graph) heritageEdges(checker *shimchecker.Checker, path string, node *s
       if base == nil || base.Expression == nil {
         continue
       }
-      target := Resolve(checker, base.Expression)
+      target := g.resolve(checker, base.Expression)
       if target == nil || target.Symbol == nil {
         continue
       }
@@ -147,6 +152,10 @@ func forEachContainerIn(path string, statements []*shimast.Node, fn func(string,
       if id := topLevelID(path, statement, NodeFunction); id != "" {
         fn(id, statement)
       }
+      // Closure nodes are not indexed (build.go): what a function body runs is
+      // implementation, and implementation is read from the file. The walker
+      // stays for the day the caller asks for them.
+      forEachClosureIn(path, statement, fn)
     case shimast.KindTypeAliasDeclaration:
       if id := topLevelID(path, statement, NodeTypeAlias); id != "" {
         fn(id, statement)
@@ -166,10 +175,24 @@ func forEachContainerIn(path string, statements []*shimast.Node, fn func(string,
       forEachVariable(path, statement, fn)
     case shimast.KindModuleDeclaration:
       forEachContainerIn(path, moduleStatements(statement), fn)
+    default:
+      // A statement that declares nothing still runs: a test suite's
+      // `describe(() => it(() => schema.parse(x)))`, an entry file's
+      // `bootstrap()`, a registration side effect. No declaration owns those
+      // calls, so attributing edges to owners alone dropped every one of them,
+      // and with them every test the graph could have pointed at. The module
+      // runs them, so the module owns them.
+      fn(moduleID(path), statement)
     }
   }
 }
 
+// moduleID is the node id of the file's module — the owner of what its top-level
+// statements do.
+func moduleID(path string) string {
+  return nodeID(path, path, NodeModule)
+}
+
 // topLevelID returns the node id for a named declaration, or "". The name is
 // namespace-qualified, so a namespaced declaration lands on the node the build
 // pass recorded.
@@ -189,6 +212,7 @@ func topLevelID(path string, statement *shimast.Node, kind NodeKind) string {
 func forEachMember(path string, statement *shimast.Node, kind NodeKind, fn func(string, *shimast.Node)) {
   containerID := topLevelID(path, statement, kind)
   for _, member := range classMembers(statement) {
+    forEachClosureIn(path, member, fn)
     if isMethodMember(member.Kind) {
       if name := methodName(member.Symbol()); name != "" {
         fn(nodeID(path, name, NodeMethod), member)
@@ -259,14 +283,44 @@ func forEachVariable(path string, statement *shimast.Node, fn func(string, *shim
       continue
     }
     fn(nodeID(path, qualifiedName(symbol), NodeVariable), binding)
+    forEachClosureIn(path, binding, fn)
+  }
+}
+
+// forEachClosureIn pairs each function a declaration's body declares with its
+// own node, and recurses: the renderer's `patch` owns the calls it makes, not the
+// factory it closes over. `callsWithin` stops at the same boundary, so no call is
+// attributed twice.
+func forEachClosureIn(path string, declaration *shimast.Node, fn func(string, *shimast.Node)) {
+  for _, closure := range ClosuresIn(declaration) {
+    if id := closureID(path, closure); id != "" {
+      fn(id, closure)
+    }
+    forEachClosureIn(path, closure, fn)
   }
 }
 
+// closureID is the node id build.go recorded for a closure.
+func closureID(path string, closure *shimast.Node) string {
+  name, ok := ClosureName(closure)
+  if !ok {
+    return ""
+  }
+  kind := NodeFunction
+  if closure.Kind == shimast.KindVariableDeclaration {
+    kind = NodeVariable
+  }
+  return nodeID(path, name, kind)
+}
+
 // callsWithin walks node's subtree and records runtime value-use edges from
 // `from` to the resolved target: calls/new/tagged templates/JSX components as
 // value-call edges, and property or element access as value-access edges.
 func (g *Graph) callsWithin(checker *shimchecker.Checker, from string, node *shimast.Node) {
   node.ForEachChild(func(child *shimast.Node) bool {
+    // With closures unindexed, a body's calls belong to the declaration that
+    // owns the body — the walk does not stop at one. (When they are indexed, it
+    // must: a closure that is its own node owns the calls it makes.)
     switch child.Kind {
     case shimast.KindCallExpression:
       // A decorator's own factory call (`@Column()`, `@Entity()`) is metadata,
@@ -280,6 +334,7 @@ func (g *Graph) callsWithin(checker *shimchecker.Checker, from string, node *shi
       }
       if call := child.AsCallExpression(); call != nil && call.Expression != nil {
         g.callEdge(checker, from, call.Expression, "call")
+        g.handedOffValues(checker, from, call)
       }
     case shimast.KindNewExpression:
       if newExpr := child.AsNewExpression(); newExpr != nil && newExpr.Expression != nil {
@@ -334,7 +389,7 @@ func (g *Graph) assignedFunctionTarget(checker *shimchecker.Checker, from string
     !shimast.IsFunctionLike(binary.Right) {
     return ""
   }
-  target := Resolve(checker, binary.Left)
+  target := g.resolve(checker, binary.Left)
   if target == nil || target.Symbol == nil {
     return ""
   }
@@ -387,6 +442,34 @@ func (g *Graph) callEdge(checker *shimchecker.Checker, from string, callee *shim
   g.valueUseEdge(checker, from, callee, EdgeValueCall, origin)
 }
 
+// handedOffValues records the workspace functions a call is handed, as uses of
+// them.
+//
+// `React.memo(ExcalidrawBase)`, `forwardRef(Impl)`, `app.use(handler)`,
+// `pipe(map(project))` — the argument is not called here and is not a property
+// read, so the collector saw neither a call nor an access and recorded nothing.
+// The wrapper became a dead end: Excalidraw's public export, `export const
+// Excalidraw = React.memo(ExcalidrawBase)`, reached zero files in the graph while
+// the component behind it reached forty-four, so a tour of the public API opened
+// on an app-level export dialog instead, and the model went looking for the real
+// component by hand.
+//
+// A function handed to another function is a use of it, and it is the one the
+// runtime will run. Bounded to argument position: this is the callback, the
+// wrapped component, the registered handler — not every identifier in every
+// expression.
+func (g *Graph) handedOffValues(checker *shimchecker.Checker, from string, call *shimast.CallExpression) {
+  if call.Arguments == nil {
+    return
+  }
+  for _, argument := range call.Arguments.Nodes {
+    switch argument.Kind {
+    case shimast.KindIdentifier, shimast.KindPropertyAccessExpression:
+      g.valueUseEdge(checker, from, argument, EdgeValueAccess, "")
+    }
+  }
+}
+
 // accessEdge resolves a property or element access to its declaration and
 // records a value-access edge, skipping unresolved/external/self targets.
 func (g *Graph) accessEdge(checker *shimchecker.Checker, from string, access *shimast.Node) {
@@ -397,7 +480,7 @@ func (g *Graph) valueUseEdge(checker *shimchecker.Checker, from string, targetEx
   if targetExpr == nil {
     return
   }
-  target := Resolve(checker, targetExpr)
+  target := g.resolve(checker, targetExpr)
   if target == nil || target.Symbol == nil {
     return
   }
@@ -461,7 +544,7 @@ func (g *Graph) typeRefEdge(checker *shimchecker.Checker, from string, typeName
   if typeName == nil {
     return
   }
-  target := Resolve(checker, typeName)
+  target := g.resolve(checker, typeName)
   if target == nil || target.Symbol == nil {
     return
   }
@@ -511,12 +594,17 @@ func (g *Graph) ensureTargetNode(target *Target) string {
     return id
   }
   if !target.External {
-    // A workspace target Build did not record is a function-local or otherwise
-    // body-scoped declaration (Build records top-level declarations, namespace
-    // members, and class/interface members only). Its name is unqualified and
-    // position-free, so two same-named locals in different scopes would key the
-    // same id and merge into one node, fabricating false edges. Drop it — the
-    // same workspace-only discipline the NodeMethod branch already applies.
+    // A closure Build recorded is keyed by its scoped name
+    // (`baseCreateRenderer.patch`), which the symbol alone does not spell, so
+    // resolve it from the declaration the checker pointed at.
+    if id := g.closureTargetID(target); id != "" {
+      return id
+    }
+    // Any other workspace target Build did not record is body-scoped and
+    // unnameable without collisions (a local of an anonymous callback), so its
+    // name would key the same id as a same-named local of another scope and
+    // merge two nodes into one that is neither. Drop it — the same
+    // workspace-only discipline the NodeMethod branch already applies.
     return ""
   }
   g.Nodes[id] = &Node{
@@ -532,6 +620,29 @@ func (g *Graph) ensureTargetNode(target *Target) string {
   return id
 }
 
+// closureTargetID returns the node id of a closure the checker resolved to, or ""
+// when the target is not one Build recorded.
+func (g *Graph) closureTargetID(target *Target) string {
+  for _, declaration := range target.Symbol.Declarations {
+    if !IsClosure(declaration) {
+      continue
+    }
+    name, ok := ClosureName(declaration)
+    if !ok {
+      continue
+    }
+    kind := NodeFunction
+    if declaration.Kind == shimast.KindVariableDeclaration {
+      kind = NodeVariable
+    }
+    id := nodeID(target.File, name, kind)
+    if _, exists := g.Nodes[id]; exists {
+      return id
+    }
+  }
+  return ""
+}
+
 // symbolNodeKind maps a resolved symbol's declarations/flags to a NodeKind, or
 // "" when the symbol is not a kind the graph records as a node. Declaration kind
 // wins over flags because property-like accessor symbols can otherwise be

package/internal/graph/exports.go

@@ -5,18 +5,39 @@ import (
   shimchecker "github.com/microsoft/typescript-go/shim/checker"
 )
 
-// markExports flags every node reachable through a source file's export table as
-// Exported. It runs on the checker, so it sees the real public surface: an
-// inline `export class`, a separate `export { Foo }`, a re-export
+// markExports records a module's export surface: a node for the module itself
+// and an `exports` edge to every declaration its export table resolves to. It
+// runs on the checker, so it sees the real public surface — an inline
+// `export class`, a separate `export { Foo }`, a re-export
 // `export { Foo } from "./foo"`, and a barrel `export *` all land here, where a
 // purely syntactic `export`-modifier scan would miss the re-export forms that
-// carry most of a monorepo's public API.
+// carry most of a monorepo's public API. Each resolved node is also flagged
+// Exported.
+//
+// The edge is what the flag cannot say. A package's front door and its legacy
+// subpath both re-export, so both surfaces end up Exported and a ranker that
+// reads the flag alone cannot tell zod's `.` entry from its `./v3` one: it picks
+// whichever name matches the query best, which is how a tour of the current API
+// came back centered on the legacy implementation. The edge keeps the module the
+// symbol came out of, so a caller holding a package.json — which names its entry
+// file and nothing else — can ask the graph what that file, and only that file,
+// puts on the wire.
+//
+// A barrel declares nothing of its own, so without a module node it is absent
+// from the graph entirely: the file a package.json points at, the one thing that
+// answers "what is this package's public API", is the one file the index never
+// had. The module node is that anchor, and the export edges hang from it.
 func (g *Graph) markExports(checker *shimchecker.Checker, file *shimast.SourceFile) {
   moduleSymbol := checker.GetSymbolAtLocation(file.AsNode())
   if moduleSymbol == nil {
     return
   }
-  for _, export := range shimchecker.Checker_getExportsOfModule(checker, moduleSymbol) {
+  exports := shimchecker.Checker_getExportsOfModule(checker, moduleSymbol)
+  if len(exports) == 0 {
+    return
+  }
+  module := g.putModuleNode(file)
+  for _, export := range exports {
     symbol := export
     // A re-export is an alias; unwrap it to the declaration it points at so the
     // exported flag lands on the real node, not a re-exporting index file's
@@ -26,35 +47,71 @@ func (g *Graph) markExports(checker *shimchecker.Checker, file *shimast.SourceFi
         symbol = aliased
       }
     }
-    g.markExportedSymbol(symbol)
+    if id, ok := g.markExportedSymbol(symbol); ok {
+      g.addEdge(module.ID, id, EdgeExports)
+    }
   }
 }
 
-// markExportedSymbol sets Exported on the node a resolved export symbol declares,
-// when the graph recorded one. A symbol whose declaration the graph does not
-// model as a node (a re-exported value from a dependency, a kind it does not
-// track) is skipped rather than fabricated.
-func (g *Graph) markExportedSymbol(symbol *shimast.Symbol) {
+// putModuleNode records the node for a source file. Its name is the file path,
+// the only name a module has that a caller can hold.
+//
+// Every source file gets one, exporting or not, because a module is also what
+// runs a file's top-level statements — and those statements are where a test
+// file keeps everything it does. `describe(() => it(() => schema.parse(x)))` is
+// a call the checker resolves and the graph used to drop on the floor: it sits
+// inside a callback, no declaration owns it, and edges are attributed to owners.
+// A whole test suite left no trace, which is why a tour that promised the tests
+// to read next could name two of zod's and none of NestJS's, and why the model
+// went off to glob for them.
+func (g *Graph) putModuleNode(file *shimast.SourceFile) *Node {
+  path := file.FileName()
+  id := nodeID(path, path, NodeModule)
+  if existing, ok := g.Nodes[id]; ok {
+    return existing
+  }
+  node := &Node{
+    ID:     id,
+    Name:   path,
+    Simple: path,
+    Kind:   NodeModule,
+    File:   path,
+    // A module that exports is by definition part of some surface; whether it is
+    // the package's front door is the package.json's to say, not the graph's.
+    Exported: true,
+  }
+  g.Nodes[id] = node
+  return node
+}
+
+// markExportedSymbol sets Exported on the node a resolved export symbol declares
+// and returns that node's id. A symbol whose declaration the graph does not model
+// as a node (a re-exported value from a dependency, a kind it does not track) is
+// skipped rather than fabricated.
+func (g *Graph) markExportedSymbol(symbol *shimast.Symbol) (string, bool) {
   declaration := declarationNode(symbol)
   if declaration == nil {
-    return
+    return "", false
   }
   file := shimast.GetSourceFileOfNode(declaration)
   if file == nil {
-    return
+    return "", false
   }
   kind := symbolNodeKind(symbol)
   if kind == "" {
-    return
+    return "", false
   }
   name := qualifiedName(symbol)
   if kind == NodeMethod {
     name = methodName(symbol)
   }
   if name == "" {
-    return
+    return "", false
   }
-  if node, ok := g.Nodes[nodeID(file.FileName(), name, kind)]; ok {
-    node.Exported = true
+  node, ok := g.Nodes[nodeID(file.FileName(), name, kind)]
+  if !ok {
+    return "", false
   }
+  node.Exported = true
+  return node.ID, true
 }

package/internal/graph/graph.go

@@ -1,5 +1,9 @@
 package graph
 
+import (
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
 // NodeKind classifies a graph node by what its symbol declares.
 type NodeKind string
 
@@ -14,6 +18,10 @@ const (
   // accessor). Its id is class-qualified ("path#Class.method:method") so a
   // resolved method call lands on the same node the build pass recorded.
   NodeMethod NodeKind = "method"
+  // NodeModule is a source file with an export table — the surface a consumer
+  // imports from. A barrel declares nothing, so this is the only node it has,
+  // and it is the node a package.json entry path resolves to.
+  NodeModule NodeKind = "module"
 )
 
 // Node is one declared symbol. Its ID is position-invariant, built from the file
@@ -38,6 +46,12 @@ type Node struct {
   // a barrel (`export *`) counts, not only an inline `export` modifier. It is
   // the signal a public-API projection filters on.
   Exported bool
+  // Closure marks a node declared inside another declaration's body — Vue's
+  // `baseCreateRenderer.patch`, a callback bound to a const inside a method.
+  // It is a name the runtime calls, and a model that asks for it by name gets
+  // it; but an orientation tour ranks and walks the surface, so the surface is
+  // what it sees. The flag is how a projection tells the two apart.
+  Closure bool
   // Modifiers holds the declaration's syntactic modifiers as wire strings (a
   // subset of the TtscGraphNodeModifier union: export/default/declare/abstract/
   // static/readonly/async/const/public/private/protected). It is recorded from
@@ -74,6 +88,11 @@ const (
   // type it mentions (a parameter, return, property, or alias type). It is not a
   // runtime call, so an impact query can filter value edges from type edges.
   EdgeTypeRef EdgeKind = "type-ref"
+  // EdgeExports runs from a module to a declaration its export table resolves
+  // to, through re-exports and barrels. It records which surface a symbol is
+  // public on, which the Exported flag cannot: a package's front door and its
+  // legacy subpath both export, and only the edge says which one did.
+  EdgeExports EdgeKind = "exports"
 )
 
 // Edge is a directed, checker-resolved relationship from one node to another,
@@ -112,7 +131,20 @@ type Graph struct {
   bodyNodes map[string]bool
   // seen deduplicates edges in O(1) during construction, so building a graph
   // with N edges is O(N), not O(N²). Keyed by from\x00to\x00kind.
-  seen map[string]struct{}
+  seen map[edgeKey]struct{}
+
+  // resolved memoizes the checker resolution of an AST node for the length of a
+  // build: the edge pass visits the same node several times, and a resolution
+  // cannot change while the program is fixed.
+  resolved map[*shimast.Node]*Target
+}
+
+// edgeKey identifies an edge by its two ends and the wire kind it will surface
+// as: a comparable struct, so the dedup set costs no allocation per candidate.
+type edgeKey struct {
+  from string
+  to   string
+  kind string
 }
 
 // nodeID builds the position-invariant identity for a symbol named name,

package/internal/graph/node_identity_is_position_invariant_test.go

@@ -41,8 +41,10 @@ export const value = 1;
   if firstText == secondText {
     t.Fatal("the reload returned identical source text; the probe is reading a stale cache, not the shifted file")
   }
-  if len(firstIDs) != 2 {
-    t.Fatalf("expected 2 nodes, got %d: %v", len(firstIDs), firstIDs)
+  // fn, value, and the module node for main.ts, whose id is the file path and so
+  // is position-invariant like the rest.
+  if len(firstIDs) != 3 {
+    t.Fatalf("expected 3 nodes, got %d: %v", len(firstIDs), firstIDs)
   }
   if !equalStringSets(firstIDs, secondIDs) {
     t.Fatalf("node identity changed when positions shifted:\n first=%v\n second=%v", firstIDs, secondIDs)

package/internal/graph/resolve.go

@@ -35,6 +35,30 @@ type Target struct {
   End      int
 }
 
+// resolve is Resolve with the graph's memo in front of it.
+//
+// The edge pass walks the same AST more than once by construction: `collectCalls`
+// and `collectTypeRefs` each descend the whole container tree, and a closure's
+// body is walked again for every container that encloses it. Every one of those
+// visits asked the checker again, and for an identifier that is not a cheap
+// lookup — typescript-go caches a resolved property access on the node, but a
+// plain identifier goes back through `resolveEntityName` and a full scope walk
+// each time.
+//
+// A node's resolution cannot change while the program is fixed, which it is for
+// the length of a build, so the second answer is always the first one.
+func (g *Graph) resolve(checker *shimchecker.Checker, ref *shimast.Node) *Target {
+  if ref == nil {
+    return nil
+  }
+  if cached, hit := g.resolved[ref]; hit {
+    return cached
+  }
+  target := Resolve(checker, ref)
+  g.resolved[ref] = target
+  return target
+}
+
 // Resolve follows ref to the real declaration the checker binds it to. It
 // unwraps import/export alias chains so a reference through a barrel re-export
 // lands on the sibling source that declares the symbol, not the re-exporting

package/internal/graphsymbols/provider.go

@@ -1,9 +1,13 @@
 // Package graphsymbols answers the two graph-oriented LSP methods
 // (textDocument/documentSymbol and textDocument/references) from ttsc's
 // compiler-backed code graph. It is the lspserver.SymbolProvider implementation
-// ttscserver wires in so a raw-LSP graph consumer such as @samchon/graph gets
-// compiler-complete declarations (graph nodes) and usages (graph edges) instead
-// of the empty answers tsgo's native LSP returns for these methods.
+// ttscserver wires in so a raw-LSP graph consumer such as @samchon/graph can get
+// declarations (graph nodes) and usages (graph edges) computed from that graph.
+//
+// tsgo's own LSP implements both methods with its compiler-exact language
+// service, so the proxy forwards to tsgo by default and falls back to this
+// provider only when tsgo does not advertise the capability, or when a consumer
+// explicitly opts into graph-derived answers (see lspserver.Proxy).
 //
 // It lives in its own package rather than in internal/lspserver because it
 // imports internal/graph and driver, and driver already imports lspserver;
@@ -31,9 +35,9 @@ 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 for the process lifetime: the graph-indexing use case walks a project
-// once, so a single compiler load keeps indexing fast without re-checking on
-// every request. It is safe for concurrent use.
+// 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.
 type Provider struct {
   cwd      string
   tsconfig string
@@ -88,6 +92,19 @@ func (pr *Provider) load() (*graph.Graph, map[string]string, error) {
   return pr.graph, pr.sources, 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.
+func (pr *Provider) Invalidate() {
+  pr.mu.Lock()
+  defer pr.mu.Unlock()
+  pr.loaded = false
+  pr.graph = nil
+  pr.sources = 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.
 func (pr *Provider) DocumentSymbols(uri string) ([]lspserver.LSPDocumentSymbol, error) {
@@ -103,7 +120,7 @@ func (pr *Provider) DocumentSymbols(uri string) ([]lspserver.LSPDocumentSymbol,
 
   var fileNodes []*graph.Node
   for _, n := range g.Nodes {
-    if n.External {
+    if !surfaceableNode(n) {
       continue
     }
     if pathsEqual(n.File, file) {
@@ -162,8 +179,13 @@ func (pr *Provider) References(uri string, pos lspserver.LSPPosition, includeDec
   // 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).
+  //
+  // 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 {
+    if e.To != target.ID || isStructuralEdge(e.Kind) {
       continue
     }
     f := nodeFile(e.From)
@@ -228,12 +250,10 @@ func nodeToSymbol(n *graph.Node, text string) lspserver.LSPDocumentSymbol {
     Start: offsetToPosition(text, start),
     End:   offsetToPosition(text, end),
   }
-  name := n.Simple
-  if name == "" {
-    name = n.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:  name,
+    Name:  n.Simple,
     Kind:  symbolKind(n.Kind),
     Range: rng,
     // The graph does not record the identifier's own span separately, so the
@@ -289,7 +309,7 @@ func symbolKind(k graph.NodeKind) lspserver.LSPSymbolKind {
 func targetNodeAt(g *graph.Graph, file string, offset int) *graph.Node {
   var best *graph.Node
   for _, n := range g.Nodes {
-    if n.External || !pathsEqual(n.File, file) {
+    if !surfaceableNode(n) || !pathsEqual(n.File, file) {
       continue
     }
     if offset >= n.Pos && offset < n.End {
@@ -314,6 +334,22 @@ func targetNodeAt(g *graph.Graph, file string, offset int) *graph.Node {
   return nil
 }
 
+// isStructuralEdge reports an edge that records where a symbol stands rather than
+// a place it is used.
+func isStructuralEdge(kind graph.EdgeKind) bool {
+  return kind == graph.EdgeExports
+}
+
+// surfaceableNode reports whether a graph node should appear as a user-facing
+// LSP symbol or reference target. 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.
+func surfaceableNode(n *graph.Node) bool {
+  return !n.External && n.Kind != graph.NodeModule && n.Simple != ""
+}
+
 func sortNodes(nodes []*graph.Node) {
   sort.Slice(nodes, func(i, j int) bool {
     if nodes[i].Pos != nodes[j].Pos {