Documentation
¶
Overview ¶
Package query implements the L1 read-side primitives over a core.Store. See FOUNDATION §5.
Index ¶
- type KCLister
- type LineageLister
- type ListFilter
- type Query
- func (q *Query) AsOf(commit string) *Query
- func (q *Query) Blame(ctx context.Context, id core.Hash) ([]core.KnowledgeCommit, error)
- func (q *Query) Drift(ctx context.Context, sourceSha string) (core.DriftResult, error)
- func (q *Query) History(ctx context.Context, id core.Hash) ([]core.Symbol, error)
- func (q *Query) Impact(ctx context.Context, id core.Hash, maxDepth int) ([]core.Symbol, error)
- func (q *Query) ListSymbols(ctx context.Context, f ListFilter) ([]core.Symbol, error)
- func (q *Query) Neighbors(ctx context.Context, id core.Hash, kind core.EdgeKind, dir core.Direction) ([]core.Symbol, error)
- func (q *Query) Symbol(ctx context.Context, id core.Hash) (core.Symbol, error)
- func (q *Query) Why(ctx context.Context, id core.Hash) ([]core.WhyEvent, error)
- type SymbolDrifter
- type SymbolLister
- type WhyTracer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type KCLister ¶
type KCLister interface {
ListKnowledgeCommits(ctx context.Context) ([]core.KnowledgeCommit, error)
}
KCLister is an optional Store capability used by Blame / History.
type LineageLister ¶
LineageLister is an optional Store capability used by History.
type ListFilter ¶
type ListFilter struct {
Kind core.SymbolKind // 0 = any
Language string // "" = any
PackagePrefix string // "" = any (substring match on FQN)
Limit int // 0 = default (50)
}
ListFilter narrows a ListSymbols call. Zero values mean "no filter." limit caps the result; 0 or negative means use the default (50). The MCP / CLI layers cap the maximum at 500 before passing in.
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query implements core.Query. It is a thin layer over core.Store: each method either reads a single record, walks edges, or composes those.
func (*Query) AsOf ¶
AsOf returns a Query scoped to the given source commit. Reads on the returned Query reflect the graph state at that commit. See FOUNDATION §5.
func (*Query) Blame ¶
Blame returns the chain of KCs that touched the given symbol, in chronological order (oldest first). Defined as: every KC whose Added, Updated, or Removed list contains id (or a Lineage record involving id).
In v0.1 the implementation requires a Store that exposes a list of all KCs; for backends that don't support that, returns an empty slice. The memory store and SQLite store both implement KCLister.
func (*Query) Drift ¶
Drift returns the symbol-level diff between sourceSha and HEAD. Errors with core.ErrUnknownCommit if sourceSha isn't indexed (i.e., the user ran analyze without --full-history). Backends that don't support drift return a clear error.
func (*Query) History ¶
History walks Lineage records to return the full chain of identities a symbol has had over time. Includes the input symbol. Order: oldest first.
func (*Query) Impact ¶
Impact returns symbols transitively reachable from id via CALLS+REFERENCES edges, up to maxDepth hops. Direction reversed: callers, not callees. (Common usage: "if I change Symbol X, what's the blast radius?" — that's upstream callers, i.e., DirIn on CALLS.)
Returns the deduplicated set excluding the start node.
func (*Query) ListSymbols ¶
ListSymbols returns symbols active at the current scope, narrowed by the filter. Sorted by FQN for deterministic output.
This is the discovery primitive — agents and humans use it to find what's in a repo without knowing names ahead of time.
func (*Query) Neighbors ¶
func (q *Query) Neighbors(ctx context.Context, id core.Hash, kind core.EdgeKind, dir core.Direction) ([]core.Symbol, error)
Neighbors returns symbols connected to id via edges of the given Kind in the given Direction. DirOut returns To-symbols; DirIn returns From-symbols.
func (*Query) Symbol ¶
Symbol returns the Symbol with the given logical ID at the current scope. Returns ErrNotFound when no revision is active at the scope.
func (*Query) Why ¶
Why returns the chronological list of KCs that touched the given symbol, with commit message + author when the index has them. This is `blame` enriched — same KC set, plus the metadata. Older KCs (pre-v0.4.1) return empty strings for message + author; callers should treat those as "metadata not captured" rather than "commit had no message."
type SymbolDrifter ¶
type SymbolDrifter interface {
DriftSince(ctx context.Context, sourceSha string) (core.DriftResult, error)
}
SymbolDrifter is an optional Store capability used by Query.Drift (and the crowl_drift MCP tool). Returns the symbol-level diff between sourceSha and HEAD. The SQLite store implements this by querying the revisions tables with seq filters; the memory store is fine without it (drift on an in-memory store isn't a v0.4.1 use case).
Source Files