Documentation
¶
Overview ¶
Package graph holds the cross-language symbol graph: nodes are symbols (functions, types, kernels, asm procedures), edges are structural or cross-language binding relations. The graph is the structural pillar of spectackle — it lets an LLM compute the impact radius of a change across language boundaries (Go -> C -> CUDA) without reading file contents.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PersonalizedRank ¶
func PersonalizedRank(g Graph, focus []NodeID, depth, iters int, damping float64) map[NodeID]float64
PersonalizedRank computes personalized PageRank over the subgraph within depth hops of the focus seeds (SPX-GRA-004). Relevance in a call graph flows both ways — a callee matters to its caller and vice versa — so the adjacency is undirected. Restart mass is split uniformly over the seeds; nodes outside the subgraph score 0. Deterministic: fixed iteration count and float sums accumulated in sorted node order (map iteration order would flip last bits).
func ValidNodeID ¶ added in v0.10.0
ValidNodeID reports whether id has the SHAPE of a node ID minted by ids.Mint: "<known-lang>:<non-empty qualified name>". It answers a different question than Graph.Node — "could this string ever name a node?", not "does this node exist right now?" — which is what lets the drift classifier tell a permanently unresolvable anchor (a file path, say) apart from one that is merely waiting on the next index (B-01KYN5ZYM1FY2). It lives in package graph because index imports graph and the reverse would cycle.
KNOWN INCOMPLETENESS: langspec.Spec.Lang is a free string minted at internal/langspec/langspec.go:266, so a third-party language spec carrying a Lang absent from the const block above would have its perfectly real nodes reported unresolvable here. That trade is deliberate — the class this guards against (a path or prose string that can never resolve) is the common, silently-permanent one — but it is the reason a new Lang const MUST be added to allLangs in the same change.
Types ¶
type Edge ¶
Edge is a directed relation between two nodes. File:Line locate the edge site (e.g. the call or launch statement), not the definitions.
type EdgeKind ¶
type EdgeKind uint8
EdgeKind classifies an edge.
const ( EUnknown EdgeKind = iota EDef // container defines symbol (file -> func, type -> method) ECall // same-language call EIncl // #include / import ECgo // Go <-> C boundary (import "C", //export) EAsm // Go decl <-> asm TEXT implementation ELaunch // host code launches GPU kernel (<<<>>>, pipeline creation) EUse // reference that is not a call (type use, var read) ESpecLink // EARS rule bound to node (from .spectackle/links.tsv) )
func EdgeKindFromString ¶
EdgeKindFromString is the inverse of EdgeKind.String; EUnknown for no match.
type Graph ¶
type Graph interface {
Upsert(nodes []Node, edges []Edge)
Node(id NodeID) (Node, bool)
// Find returns up to k nodes whose ID or name contains q (case-insensitive),
// filtered by kind (KUnknown = any), best matches first.
Find(q string, k int, kind NodeKind) []Node
// Neighbors returns edges incident to id in the given direction, filtered
// by edge kinds (empty = all).
Neighbors(id NodeID, dir Direction, kinds []EdgeKind) []Edge
// Impact runs a bounded BFS from seeds and returns the reachable subgraph.
// Each node appears exactly once, at its minimum BFS distance (SPX-GRA-002).
Impact(seeds []NodeID, depth int, dir Direction, kinds []EdgeKind) ([]Node, []Edge)
// Stats returns the total node and edge counts — a cheap size/health
// signal (no traversal), used by the `state` overview tool.
Stats() (nodes, edges int)
}
Graph is the queryable symbol graph. Implementations must be safe for concurrent readers with a single writer.
type Lang ¶
type Lang string
Lang tags the language a node belongs to.
const ( LangGo Lang = "go" LangC Lang = "c" LangCpp Lang = "cpp" LangCuda Lang = "cu" LangAsm Lang = "asm" LangObjC Lang = "objc" LangMSL Lang = "msl" LangPy Lang = "py" LangJS Lang = "js" LangTS Lang = "ts" LangRs Lang = "rs" LangJava Lang = "java" LangRb Lang = "rb" LangPHP Lang = "php" LangKt Lang = "kt" LangSwift Lang = "swift" LangCs Lang = "cs" LangScala Lang = "scala" LangSh Lang = "sh" LangLua Lang = "lua" LangZig Lang = "zig" LangPerl Lang = "pl" LangDart Lang = "dart" LangGroovy Lang = "groovy" LangEx Lang = "ex" LangErl Lang = "erl" LangJl Lang = "jl" LangHs Lang = "hs" LangMl Lang = "ml" LangR Lang = "r" LangF90 Lang = "f90" LangGLSL Lang = "glsl" )
type Node ¶
type Node struct {
ID NodeID
Kind NodeKind
Lang Lang
File string // repo-relative path
Line int // 1-based definition start line
EndLine int // 1-based definition end line (anchor span; 0 = unknown)
Sig string // compact signature, e.g. "(n int,a float32)error"
Rank float32
}
Node is a symbol in the cross-language graph.
type NodeID ¶
type NodeID string
NodeID is a stable short identifier, "<lang>:<qualified-name>", e.g. "go:saxpy.Saxpy", "cu:saxpy_kernel". See internal/ids.
Source Files