Documentation
¶
Overview ¶
Package query answers questions against a built graph.json without rebuilding: find nodes by name, explain a node and its neighbours, and find the shortest dependency path between two nodes. These back the CLI commands the Claude skill uses instead of grepping the source tree.
Index ¶
- func Ask(g *Graph, question string, dfs bool, depth, tokenBudget int) string
- func Merge(currentPath, otherPath string) error
- func Validate(path string) (issues []string, nodes, links int, err error)
- type AffectedOptions
- type AffectedResult
- type DiffEdge
- type DiffNode
- type DiffResult
- type Explanation
- type Graph
- type Link
- type Match
- type MaxHopsError
- type Neighbor
- type Node
- type PathEdge
- type PathResult
- type SameNodeError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Ask ¶ added in v0.6.0
Ask answers a natural-language question against the graph using deterministic TF-IDF retrieval (no LLM, no network): it scores nodes against the question, picks seed nodes, runs a bounded BFS (or DFS when dfs is true) to the given depth, and renders the resulting subgraph as a token-budgeted text block.
This mirrors upstream graphify's flagship `query` command (serve.py's _query_graph_text). The Go graph carries no edge `context` data, so upstream's context-filter machinery is intentionally omitted.
func Merge ¶ added in v0.6.0
Merge resolves a graph.json merge conflict by writing the node/edge union of currentPath and otherPath back to currentPath. Nodes dedupe by id (current wins), edges by direction-aware (source, target, relation). It returns an error on corrupt or oversized input (per-file byte cap, merged-node cap) so the caller can fail the git merge instead of accepting a poisoned graph.
func Validate ¶ added in v0.3.0
Validate reads graph.json at path and reports structural problems: links that reference a missing node (dangling endpoints), duplicate node IDs, and nodes with an empty ID. It returns the issues (empty when the graph is sound) plus node and edge counts for a summary. Reading directly (rather than via Load) lets it catch duplicate IDs, which Load's id map would otherwise collapse.
Types ¶
type AffectedOptions ¶ added in v0.8.1
type AffectedOptions struct {
// Depth bounds how many reverse-dependency hops a node may sit from a changed
// node to still count as impacted: Depth 1 keeps only direct dependents, 2
// their dependents, and so on. Depth <= 0 means unbounded — the whole
// transitive closure — which is the historical (flag-absent) behaviour.
Depth int
// Relations restricts which edge relations are treated as "depends-on" when
// walking backwards. Empty uses the default dependency relation set.
Relations []string
}
AffectedOptions scopes the reverse-dependency walk performed by Affected.
type AffectedResult ¶ added in v0.3.0
AffectedResult separates the symbols defined in the changed files from the symbols transitively impacted by them.
func Affected ¶ added in v0.3.0
func Affected(g *Graph, changedFiles []string, opts AffectedOptions) AffectedResult
Affected returns the graph nodes defined in changedFiles ("changed") and every node that transitively depends on them ("impacted") — the blast radius of a change. Impact propagates backwards along dependency edges: a changed callee reaches its callers, a changed file reaches its importers. opts.Depth bounds the number of hops and opts.Relations restricts which edge kinds are followed.
type DiffEdge ¶ added in v0.6.0
type DiffEdge struct {
Source string `json:"source"`
Target string `json:"target"`
Relation string `json:"relation"`
}
DiffEdge identifies an edge added or removed between two snapshots.
type DiffResult ¶ added in v0.6.0
type DiffResult struct {
NewNodes []DiffNode `json:"new_nodes"`
RemovedNodes []DiffNode `json:"removed_nodes"`
NewEdges []DiffEdge `json:"new_edges"`
RemovedEdges []DiffEdge `json:"removed_edges"`
Summary string `json:"summary"`
}
DiffResult is the realized node/edge delta between two graph snapshots: the before/after complement to Affected's predicted blast radius.
func Diff ¶ added in v0.6.0
func Diff(old, new *Graph) DiffResult
Diff compares two loaded graph snapshots and returns the nodes and edges added or removed going from old to new. The graph is directed, so edges are compared by a direction-aware key (source, target, relation): reversing an edge counts as one removed and one added.
type Explanation ¶
Explanation is a node plus its grouped neighbours.
type Graph ¶
type Graph struct {
Nodes []Node `json:"nodes"`
Links []Link `json:"links"`
// contains filtered or unexported fields
}
Graph is a loaded graph.json.
type Link ¶
type Link struct {
Source string `json:"source"`
Target string `json:"target"`
Relation string `json:"relation"`
Confidence string `json:"confidence"`
}
Link mirrors a graph.json edge.
type MaxHopsError ¶ added in v0.8.1
type MaxHopsError struct {
MaxHops, Hops int
}
MaxHopsError is returned by PathEdges when the shortest path is longer than the caller's maxHops limit.
func (*MaxHopsError) Error ¶ added in v0.8.1
func (e *MaxHopsError) Error() string
type Neighbor ¶
type Neighbor struct {
ID, Label, Relation, Direction, Location string
}
Neighbor is an adjacent node in a given direction.
type Node ¶
type Node struct {
ID string `json:"id"`
Label string `json:"label"`
FileType string `json:"file_type"`
SourceFile string `json:"source_file"`
SourceLocation string `json:"source_location"`
Community *int `json:"community"`
NormLabel string `json:"norm_label"`
ComputedName string `json:"computed_name"`
}
Node mirrors a graph.json node.
type PathEdge ¶ added in v0.8.1
PathEdge annotates one step of a shortest path: the relation and confidence of the edge traversed to reach the step's node, and whether that edge is oriented forwards in the directed graph. In a PathResult, Edges[i] connects Nodes[i] to Nodes[i+1]; Forward is true when the recorded edge points Nodes[i] -> Nodes[i+1] and false when it points the other way.
type PathResult ¶ added in v0.8.1
PathResult is a resolved shortest path: the ordered nodes plus, for every step after the first, the edge traversed to reach it (len(Edges) == len(Nodes)-1).
func PathEdges ¶ added in v0.8.1
func PathEdges(g *Graph, from, to string, maxHops int) (*PathResult, error)
PathEdges resolves from/to and returns the shortest undirected path between them annotated with each traversed edge's relation and confidence. It uses the same resolve() semantics as Path. When both queries resolve to the same node it returns a *SameNodeError; when the path is longer than maxHops (and maxHops > 0) it returns a *MaxHopsError.
type SameNodeError ¶ added in v0.8.1
type SameNodeError struct {
From, To, ID string
}
SameNodeError is returned by PathEdges when source and target resolve to the same node, so the shortest path would be a meaningless zero hops.
func (*SameNodeError) Error ¶ added in v0.8.1
func (e *SameNodeError) Error() string