query

package
v0.8.0-beta.25 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2026 License: MIT Imports: 9 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Ask added in v0.6.0

func Ask(g *Graph, question string, dfs bool, depth, tokenBudget int) string

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

func Merge(currentPath, otherPath string) error

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

func Validate(path string) (issues []string, nodes, links int, err error)

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

type AffectedResult struct {
	Changed  []Node
	Impacted []Node
}

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 DiffNode added in v0.6.0

type DiffNode struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

DiffNode identifies a node 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

type Explanation struct {
	Node      *Node
	Neighbors []Neighbor
}

Explanation is a node plus its grouped neighbours.

func Explain

func Explain(g *Graph, id string) (*Explanation, error)

Explain returns a node and its neighbours, labelled by relation and direction (-> outgoing, <- incoming). id may be a full node ID or a label substring with a unique match.

type Graph

type Graph struct {
	Nodes []Node `json:"nodes"`
	Links []Link `json:"links"`
	// contains filtered or unexported fields
}

Graph is a loaded graph.json.

func Load

func Load(path string) (*Graph, error)

Load reads and validates a graph.json at path. The path must resolve inside a graphify-out directory and stay under the size cap.

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 Match

type Match struct {
	ID, Label, Location string
}

Match is a node found by Query.

func Query

func Query(g *Graph, pattern string) ([]Match, error)

Query returns nodes whose id, label, or normalised label matches the given regular expression (case-insensitive). Results are sorted by label.

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.

func Path

func Path(g *Graph, from, to string) ([]Node, error)

Path returns the shortest path (by node labels/ids) between two nodes via BFS on the undirected graph, or an error if no path exists.

type PathEdge added in v0.8.1

type PathEdge struct {
	Relation   string
	Confidence string
	Forward    bool
}

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

type PathResult struct {
	Nodes []Node
	Edges []PathEdge
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL