Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrGraphLocked = errors.New("graph is locked by another process (daemon running?); stop the daemon first")
ErrGraphLocked is returned when another process holds the graph lock.
Functions ¶
func GodNodes ¶
GodNodes returns the topN nodes sorted by total degree (in + out). These are the most-connected concepts in the graph — architectural hubs.
func RunLeiden ¶
RunLeiden runs Leiden community detection on the graph by delegating to the bundled Python script (scripts/leiden.py). Returns a map of node ID → community ID (0-indexed integers).
If Python or the script is unavailable, a clear error is returned (no panic). The script itself falls back to connected-components if graspologic is missing.
func SuggestedQuestions ¶
SuggestedQuestions returns 4–5 question templates populated with the names of the top god nodes. These are questions the graph is uniquely positioned to answer through path-finding and community analysis.
func SurpriseEdges ¶
SurpriseEdges returns the topN edges that cross community boundaries, ranked by the product of the degrees of their endpoints (a proxy for betweenness centrality: high-degree nodes in different communities that are directly connected are architecturally "surprising").
Types ¶
type Graph ¶
type Graph struct {
Directed *simple.DirectedGraph
NodeIndex map[string]int64 // node ID string → gonum int64 ID
NodeByID map[int64]types.Node // gonum int64 ID → types.Node
ResolvedEdges []types.Edge // only edges where both endpoints resolved
Nodes []types.Node
}
Graph wraps a gonum directed graph with auxiliary indexes for fast lookup.
func Build ¶
Build constructs a Graph from the provided nodes and edges.
Edge resolution:
- e.Source must match a node ID exactly (it is always in "<file>:<name>" format).
- e.Target is first tried as an exact ID, then as a bare label via labelIndex.
Only edges where BOTH endpoints resolve to known nodes are stored in ResolvedEdges and added to the gonum graph. Dangling edges (targeting stdlib/external symbols) are silently dropped — they add noise and break Obsidian graph view by creating isolated satellite dots.
func (*Graph) ApplyCommunities ¶
ApplyCommunities writes community IDs back onto the graph's node metadata and populates the community → []nodeID index for report generation.
func (*Graph) Communities ¶
Communities returns a map of communityID → list of node IDs (empty until clustering is run).
func (*Graph) Degree ¶
Degree returns the total degree (in + out) of the node with the given ID string.
type GraphLock ¶ added in v1.3.0
type GraphLock struct {
// contains filtered or unexported fields
}
GraphLock holds an exclusive advisory flock on ~/.vela/graph.lock so the daemon and vela extract cannot write graph.json concurrently.
func AcquireGraphLock ¶ added in v1.3.0
AcquireGraphLock opens the lock file and acquires a non-blocking exclusive lock. Returns ErrGraphLocked if another process already holds the lock.
type HealthMetrics ¶ added in v1.2.0
type HealthMetrics struct {
Path string `json:"path"`
GeneratedAt string `json:"generated_at,omitempty"`
// Size
Nodes int `json:"nodes"`
Edges int `json:"edges"`
// Coverage — breakdowns
NodesByKind map[string]int `json:"nodes_by_kind"`
EdgesByRelation map[string]int `json:"edges_by_relation"`
// Quality / resolution
BrokenEdges int `json:"broken_edges"`
SelfLoops int `json:"self_loops"`
DuplicateEdges int `json:"duplicate_edges"`
ResolutionRate float64 `json:"resolution_rate"` // 0..1
// Confidence
ConfidenceDist map[string]int `json:"confidence_dist"`
ExtractedRate float64 `json:"extracted_rate"` // 0..1
// Degree
AvgDegree float64 `json:"avg_degree"`
MedianDegree int `json:"median_degree"`
P95Degree int `json:"p95_degree"`
MaxDegree int `json:"max_degree"`
IsolatedNodes int `json:"isolated_nodes"`
HubNodes int `json:"hub_nodes"` // total degree >= 10
LeafNodes int `json:"leaf_nodes"` // total degree == 1
ConnectedPct int `json:"connected_pct"`
// Communities
Communities int `json:"communities"`
LargestCommunitySize int `json:"largest_community_size"`
SingletonCommunities int `json:"singleton_communities"`
Modularity float64 `json:"modularity"`
// Top nodes (length fixed via TopN when loading)
TopByOutDegree []NodeRank `json:"top_by_out_degree"`
}
HealthMetrics is the full set of graph-health signals computed from an on-disk graph.json. It is the single source of truth consumed by both `vela bench` and the TUI Graph Status screen.
func LoadHealthMetrics ¶ added in v1.2.0
func LoadHealthMetrics(path string, topN int) (HealthMetrics, error)
LoadHealthMetrics reads graph.json at path and computes every signal. topN controls the length of TopByOutDegree (5 is a reasonable default).
type NodeRank ¶ added in v1.2.0
type NodeRank struct {
ID string `json:"id"`
Label string `json:"label"`
File string `json:"file,omitempty"`
Kind string `json:"kind,omitempty"`
OutDeg int `json:"out_degree"`
InDeg int `json:"in_degree"`
}
NodeRank is a compact row used in metric leaderboards (top-N by degree).
Source Files