chore: import upstream snapshot with attribution

internal/graph/reader.go

@@ -0,0 +1,83 @@
+package graph
+
+// Reader is the read-only contract every graph consumer (query
+// engine, MCP tool handlers, analyzers, resolver introspection) depends
+// on. *Graph satisfies it directly; OverlaidView (overlay.go) wraps a
+// base Reader plus a per-session overlay layer to deliver a non-
+// mutating shadow view for editor-buffer queries.
+//
+// Mutation methods (AddNode, AddEdge, EvictFile, ReindexEdge, …) live
+// on *Graph and are NOT part of this interface. Only the indexer and
+// the resolver mutate; everyone else reads, and reads must go through
+// Reader so the same call site transparently switches between base
+// and overlay views.
+//
+// New read methods on *Graph should be added here too — keeping the
+// surfaces in sync is what guarantees that a tool migrated to read
+// through the Reader will keep working for both base and overlay
+// queries.
+type Reader interface {
+	// Identity lookups.
+	GetNode(id string) *Node
+	GetNodeByQualName(qualName string) *Node
+	FindNodesByName(name string) []*Node
+	// FindNodesByNameContaining returns nodes whose Name (case-
+	// insensitive) contains substr. The filter is pushed into the
+	// backend so only matching rows cross the boundary on a disk backend;
+	// the search hot path's substring fallback uses this instead of
+	// the old AllNodes()-then-filter pattern (which materialised the
+	// whole node set per call and didn't scale). limit caps the
+	// result; 0 means "no limit".
+	FindNodesByNameContaining(substr string, limit int) []*Node
+
+	// GetNodesByIDs is the batched sibling of GetNode. The disk-backed
+	// store collapses N individual point lookups into a
+	// single bulk query — critical on the search hot path where one
+	// query materialises 60+ candidate IDs. The in-memory backend
+	// forwards to per-id GetNode, so the cost matches an inline loop
+	// there. Missing IDs are simply absent from the map (no nil
+	// values); duplicates dedupe naturally.
+	GetNodesByIDs(ids []string) map[string]*Node
+
+	// File / repo scopes.
+	GetFileNodes(filePath string) []*Node
+	GetRepoNodes(repoPrefix string) []*Node
+
+	// Edge walks.
+	GetOutEdges(nodeID string) []*Edge
+	GetInEdges(nodeID string) []*Edge
+
+	// GetInEdgesByNodeIDs / GetOutEdgesByNodeIDs are the batched
+	// siblings of GetInEdges / GetOutEdges. The disk-backed store collapses
+	// N per-id queries into one bulk query over an `id IN $ids`
+	// filter; the in-memory backend forwards to per-id walks (no
+	// concurrency win — same algorithmic cost as an inline loop). On
+	// the rerank hot path this drops ~150 round-trips per
+	// search_symbols call down to ~4 (prepare collects every
+	// candidate's ids and fans them out in one inbound + one outbound
+	// batch). Missing nodes get nil slices in the returned map so
+	// callers can `for _, e := range m[id]` without an ok-check.
+	GetInEdgesByNodeIDs(ids []string) map[string][]*Edge
+	GetOutEdgesByNodeIDs(ids []string) map[string][]*Edge
+
+	// Bulk reads — used by analyzers (hotspots, cycles, dead code,
+	// communities, …) and by the embedded query engine's whole-graph
+	// passes.
+	AllNodes() []*Node
+	AllEdges() []*Edge
+
+	// Counters & stats.
+	NodeCount() int
+	EdgeCount() int
+	// EdgeIdentityRevisions is the running count of provenance-bearing
+	// edge-identity changes — see Graph.EdgeIdentityRevisions.
+	EdgeIdentityRevisions() int
+	Stats() GraphStats
+	RepoStats() map[string]GraphStats
+}
+
+// Compile-time assertion that *Graph satisfies Reader. If a new
+// Reader method is added without a corresponding *Graph method (or
+// the *Graph signature drifts), the build breaks here rather than at
+// a far-away callsite.
+var _ Reader = (*Graph)(nil)