Documentation
¶
Overview ¶
Package kgquery is the R4 harness's read-only adapter over the code knowledge graph. It surfaces candidate code sites (seed symbols), their call-graph neighborhoods, and a reproducible complexity proxy that the per-language task generators and the difficulty-derivation step consume.
The package is a pure consumer of the published graphstore contract: it depends only on the narrow graphstore.CodeGraphReader role and issues no writes. Holding the narrow role (rather than the whole Store) keeps the dependency honest and lets tests back the querier with a tiny in-memory fake that stubs only the read methods.
All results are deterministic: seed lists and neighborhoods are sorted by qualified name and the complexity proxy is derived from stored node spans and call edges, so re-running against the same graph state yields the same output (R4 requirement R2 — reproducible difficulty signals).
This layer performs no task synthesis. It answers "what could we build a task around?" and "how complex is this symbol?"; the generators (internal/eval/gen/<lang>) and internal/eval/difficulty own the decisions that turn these signals into a TaskSpec.
Index ¶
- type Complexity
- type Neighborhood
- type Querier
- func (q *Querier) ComplexityProxy(ctx context.Context, qualifiedName string) (Complexity, error)
- func (q *Querier) NeighborhoodFor(ctx context.Context, qualifiedName string, depth int) (Neighborhood, error)
- func (q *Querier) SeedSymbols(ctx context.Context, lang eval.Language, limit int) ([]graphstore.GraphNode, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Complexity ¶
Complexity is a reproducible complexity proxy for a single symbol, derived from stored structure only (no re-parse). SpanLines is the symbol's source extent; FanOut/FanIn are its distinct outbound/inbound CALLS relations; and Cyclomatic is a McCabe-style proxy (1 + FanOut) that treats each distinct callee as a branch. Difficulty-derivation buckets on these fields.
type Neighborhood ¶
type Neighborhood struct {
Root graphstore.GraphNode
Nodes []graphstore.GraphNode
Edges []graphstore.GraphEdge
}
Neighborhood is the call-graph vicinity of a root symbol: the root itself, every node reachable within the requested depth (including the root), and the edges among them. Nodes and Edges are sorted deterministically so the same graph state yields byte-identical downstream difficulty signals.
type Querier ¶
type Querier struct {
// contains filtered or unexported fields
}
Querier is the read-only KG adapter for the task generator. It wraps a graphstore.CodeGraphReader and exposes the three questions the generator and difficulty-derivation ask of the graph. It issues no writes and holds no mutable state, so a single Querier is safe to reuse across generations (subject to the reader's own single-goroutine ownership rule).
func New ¶
func New(reader graphstore.CodeGraphReader) (*Querier, error)
New returns a Querier backed by reader. It errors on a nil reader so a mis-wired harness fails at construction rather than at first query.
func (*Querier) ComplexityProxy ¶
ComplexityProxy computes the reproducible complexity proxy for qualifiedName. It errors when the name is empty or the symbol is absent.
func (*Querier) NeighborhoodFor ¶
func (q *Querier) NeighborhoodFor(ctx context.Context, qualifiedName string, depth int) (Neighborhood, error)
NeighborhoodFor returns the neighborhood of qualifiedName out to depth hops, traversing both outbound and inbound edges. Depth 0 is the root alone; depth 1 adds its direct neighbors; and so on. Cycles are handled via a visited set. It errors when qualifiedName is empty, depth is negative, or the root symbol is not in the graph.
func (*Querier) SeedSymbols ¶
func (q *Querier) SeedSymbols(ctx context.Context, lang eval.Language, limit int) ([]graphstore.GraphNode, error)
SeedSymbols returns up to limit candidate seed symbols for lang, sorted by qualified name. Only function/class/type nodes in the requested language are considered; files and test nodes are excluded. The language match is case-insensitive against the node's stored language, which is expected to be the canonical lowercase form (e.g. "go", "python").
The result is fully reproducible for a fixed graph state: the candidate set is the COMPLETE node population, enumerated file-by-file via GetAllFiles + GetNodesByFile (neither of which imposes a LIMIT), then deduped by qualified name and put into a total order BEFORE the cap. There is no bounded, unordered pre-filter step, so no valid seed can be silently dropped by truncation and repeated runs (or a different backend) yield the same list.
Source Files