Documentation
¶
Overview ¶
Package codegraph wraps gfy's knowledge graph pipeline for ycode. It builds, caches, and queries code structure graphs that are used by /init for AGENTS.md generation and by graph query tools during coding sessions.
Index ¶
- Constants
- func CachePath(cwd string) string
- type GraphContext
- func (gc *GraphContext) GetCommunity(communityID int) string
- func (gc *GraphContext) GetGodNodes(topN int) string
- func (gc *GraphContext) GetGraphStats() string
- func (gc *GraphContext) GetNeighbors(label, relationFilter string) string
- func (gc *GraphContext) GetNode(label string) string
- func (gc *GraphContext) MirrorTo(ctx context.Context, mg graphMirror) error
- func (gc *GraphContext) QueryGraph(question string, depth int) string
- func (gc *GraphContext) Save(path string) error
- func (gc *GraphContext) ShortestPath(source, target string, maxHops int) string
- func (gc *GraphContext) Summary() string
- type Manager
- func (m *Manager) Get() *GraphContext
- func (m *Manager) IsDirty() bool
- func (m *Manager) NotifyFileChanged(path string)
- func (m *Manager) Rebuild(ctx context.Context) error
- func (m *Manager) RebuildIfDirty(ctx context.Context)
- func (m *Manager) RebuildWithProgress(ctx context.Context, progress ProgressFunc) error
- func (m *Manager) Set(gc *GraphContext)
- func (m *Manager) SetGraphTwin(twin MirrorSink)
- type MirrorSink
- type ProgressFunc
- type Stats
Constants ¶
const DefaultCachePath = ".agents/ycode/graph.json"
DefaultCachePath is the relative path under project root where the graph is cached.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type GraphContext ¶
type GraphContext struct {
Graph *graph.Graph
Communities map[int][]string
GodNodes []analyze.GodNode
Surprises []analyze.SurprisingConnection
Stats Stats
}
GraphContext holds the built graph and derived analysis results.
func Build ¶
func Build(cwd string) (*GraphContext, error)
Build runs the full gfy pipeline: detect → extract → build → cluster → analyze. Returns the graph context. Use BuildWithProgress to receive per-phase status.
func BuildWithProgress ¶
func BuildWithProgress(cwd string, progress ProgressFunc) (*GraphContext, error)
BuildWithProgress runs the full gfy pipeline and streams a status message at the start and end of each phase via the optional progress callback.
gfy writes its own progress directly to os.Stdout/os.Stderr; those streams are intercepted for the duration of the build and forwarded through progress so they don't corrupt a Bubble Tea alt-screen.
func Load ¶
func Load(path string) (*GraphContext, error)
Load reads a cached graph and rebuilds the analysis. Returns nil, nil if the cache file doesn't exist.
func (*GraphContext) GetCommunity ¶
func (gc *GraphContext) GetCommunity(communityID int) string
GetCommunity returns all nodes in a community.
func (*GraphContext) GetGodNodes ¶
func (gc *GraphContext) GetGodNodes(topN int) string
GetGodNodes returns the most connected entities.
func (*GraphContext) GetGraphStats ¶
func (gc *GraphContext) GetGraphStats() string
GetGraphStats returns node/edge counts and community info.
func (*GraphContext) GetNeighbors ¶
func (gc *GraphContext) GetNeighbors(label, relationFilter string) string
GetNeighbors returns direct neighbors of a node with edge metadata.
func (*GraphContext) GetNode ¶
func (gc *GraphContext) GetNode(label string) string
GetNode looks up a node by label or ID.
func (*GraphContext) MirrorTo ¶
func (gc *GraphContext) MirrorTo(ctx context.Context, mg graphMirror) error
MirrorTo writes the gfy code-knowledge graph into a memex queryable store using the canonical code.* schema declared in pkg/memex/graph/schema.go.
Public entry: callers can mirror manually after Build/Rebuild. The Manager.SetGraphTwin path also calls into this asynchronously after each successful Set.
func (*GraphContext) QueryGraph ¶
func (gc *GraphContext) QueryGraph(question string, depth int) string
QueryGraph searches for nodes by keyword and returns a BFS subgraph.
func (*GraphContext) Save ¶
func (gc *GraphContext) Save(path string) error
Save caches the graph to the given path (typically .agents/ycode/graph.json).
func (*GraphContext) ShortestPath ¶
func (gc *GraphContext) ShortestPath(source, target string, maxHops int) string
ShortestPath finds the shortest path between two nodes.
func (*GraphContext) Summary ¶
func (gc *GraphContext) Summary() string
Summary renders an LLM-friendly text summary of the code graph. Designed to be included in the /init prompt context.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager provides thread-safe, session-wide access to the code knowledge graph. It tracks file changes and rebuilds the graph asynchronously when stale.
func NewManager ¶
NewManager creates a graph manager for the given project root. It attempts to load a cached graph from .agents/ycode/graph.json.
func (*Manager) Get ¶
func (m *Manager) Get() *GraphContext
Get returns the current graph context under a read lock. Returns nil if no graph has been built yet.
func (*Manager) NotifyFileChanged ¶
NotifyFileChanged marks the graph as dirty if the path is a code file. Called asynchronously by the file write hook — must be non-blocking.
func (*Manager) Rebuild ¶
Rebuild runs a synchronous full rebuild of the code knowledge graph. The graph is atomically swapped and the cache is updated.
func (*Manager) RebuildIfDirty ¶
RebuildIfDirty triggers an asynchronous rebuild if the graph is stale. Non-blocking — returns immediately. The rebuild runs in a background goroutine.
func (*Manager) RebuildWithProgress ¶
func (m *Manager) RebuildWithProgress(ctx context.Context, progress ProgressFunc) error
RebuildWithProgress runs a synchronous full rebuild and streams per-phase status messages via the optional progress callback.
func (*Manager) Set ¶
func (m *Manager) Set(gc *GraphContext)
Set atomically replaces the graph and saves the cache. If a graph twin has been wired via SetGraphTwin, the new graph is also mirrored to it. Mirror failures are logged, not returned: the gfy cache remains the source of truth.
func (*Manager) SetGraphTwin ¶
func (m *Manager) SetGraphTwin(twin MirrorSink)
SetGraphTwin wires an optional bonsai mirror target. After each Set (which fires after Rebuild), the new graph is mirrored asynchronously into the twin so DQL queries see fresh data. Pass nil to detach.
type MirrorSink ¶
type MirrorSink interface {
// contains filtered or unexported methods
}
MirrorSink is implemented by *pkg/memex/graph.Graph (or anything else that can serve as a target for codegraph mirroring). The receiver method is unexported as a tag — actual writes go through GraphContext.MirrorTo which the wiring layer invokes.
type ProgressFunc ¶
type ProgressFunc func(msg string)
ProgressFunc receives human-readable status messages emitted at each phase of the build pipeline. May be nil. Implementations must be non-blocking.
Source Files