Documentation
¶
Overview ¶
Package grove is the public, in-process Go API for the Grove code knowledge graph. Prism, Fuse, and Relay import this package and call it directly — there is no HTTP server, no port, no shared-secret token, no auto-start.
Index data lives in <repoRoot>/.grove/grove.db. SQLite WAL mode handles concurrent readers; only one writer at a time per database file.
Index ¶
- Constants
- type CertificationFinding
- type CertificationPolicy
- type CertificationReport
- type ChangeImpactResult
- type Config
- type CoverageSite
- type DeadCodeResult
- type DiffInput
- type Edge
- type EdgeType
- type Engine
- func (e *Engine) CertifyDiff(ctx context.Context, input DiffInput) (CertificationReport, error)
- func (e *Engine) ChangeImpact(ctx context.Context, query string) (ChangeImpactResult, error)
- func (e *Engine) Close() error
- func (e *Engine) DeadCode(ctx context.Context, extraRoots []string) (DeadCodeResult, error)
- func (e *Engine) Deps(ctx context.Context, filePath string) ([]Edge, error)
- func (e *Engine) DiffAgainstFileContent(before []Symbol, relPath string, content []byte) (GraphDiff, error)
- func (e *Engine) DiffSince(ctx context.Context, before []Symbol) GraphDiff
- func (e *Engine) FileSymbols(ctx context.Context, relPath string) []Symbol
- func (e *Engine) ICR(ctx context.Context, intent string) IsolatedChangeRegion
- func (e *Engine) Impact(ctx context.Context, query string, maxDepth int) ([]Symbol, error)
- func (e *Engine) Index(ctx context.Context, dir string) (IndexResult, error)
- func (e *Engine) MissingImplementations(ctx context.Context, query string) (MissingImplementationsResult, error)
- func (e *Engine) Neighbors(ctx context.Context, query, direction string, kinds ...EdgeType) ([]Neighbor, error)
- func (e *Engine) PreviewFileSymbols(relPath string, content []byte) ([]Symbol, error)
- func (e *Engine) Query(ctx context.Context, intent string, limit int) ([]Symbol, error)
- func (e *Engine) References(ctx context.Context, name string) (ReferenceResult, error)
- func (e *Engine) RenamePlan(ctx context.Context, query, newName string) (RenamePlanResult, error)
- func (e *Engine) Root() string
- func (e *Engine) Semantic(ctx context.Context, query string, limit int) ([]Scored, error)
- func (e *Engine) SnapshotSymbols(ctx context.Context) []Symbol
- func (e *Engine) Status(ctx context.Context) (Status, error)
- func (e *Engine) Symbols(ctx context.Context, query string, limit int) ([]Symbol, error)
- func (e *Engine) Tests(ctx context.Context, query string) ([]Symbol, error)
- func (e *Engine) TestsWithEvidence(ctx context.Context, query string) ([]Symbol, map[string]int, error)
- func (e *Engine) UntestedSurface(ctx context.Context, query string) (UntestedSurfaceResult, error)
- type EvidenceRef
- type GraphDiff
- type IndexResult
- type IsolatedChangeRegion
- type MissingImplementationsResult
- type Neighbor
- type Reference
- type ReferenceResult
- type RenameEdit
- type RenamePlanResult
- type Scored
- type Status
- type Symbol
- type SymbolChange
- type UntestedSurfaceResult
- type Verdict
Constants ¶
const ( EdgeDefines = core.EdgeDefines EdgeImports = core.EdgeImports EdgeCalls = core.EdgeCalls EdgeExtends = core.EdgeExtends EdgeImplements = core.EdgeImplements EdgeUsesType = core.EdgeUsesType EdgeTests = core.EdgeTests EdgeContains = core.EdgeContains EdgeOverrides = core.EdgeOverrides )
Edge-type constants re-exported so consumers can filter Neighbors() without importing internal/core.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CertificationFinding ¶ added in v0.4.5
type CertificationFinding = core.CertificationFinding
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type CertificationPolicy ¶ added in v0.4.5
type CertificationPolicy = core.CertificationPolicy
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type CertificationReport ¶ added in v0.4.5
type CertificationReport = core.CertificationReport
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type ChangeImpactResult ¶ added in v0.14.1
type ChangeImpactResult struct {
Query string
Declarations []Symbol
Supers []Symbol
Family []Symbol
Callers []Symbol
// DeclaringTypes: type declarations whose bodies contain a change-set
// member signature that is not indexed as its own symbol (Go and TS
// interface members) — the type's declaration block is itself a change
// site. Empty for languages whose member declarations are real symbols.
DeclaringTypes []Symbol
// ExternalSupers: supertype names declared in the hierarchy that resolve
// to no indexed type (JDK / dependency types). Informational.
ExternalSupers []string
// OverridesExternal: "Type#method" entries when the queried method is a
// member of an external supertype's contract — changing its signature
// breaks a contract the project does not own, and the change-set is the
// project-local closure only.
OverridesExternal []string
// Completeness: "closed" (family fully rooted in indexed types) or
// "project-local" (bounded by an external contract).
Completeness string
}
ChangeImpactResult is the deterministic change-set for a method signature change: declaration(s), the override/implementation family in the subtype closure, super-declarations up the hierarchy, and every method with a resolved call edge into the set. Computed in the engine so no agent has to orchestrate references → overrides → callers over primitives.
func (ChangeImpactResult) Sites ¶ added in v0.14.1
func (r ChangeImpactResult) Sites() []Symbol
Sites returns the change-set methods (declarations ∪ family ∪ callers ∪ supers) as one deduplicated, file-ordered list. Supers are included so a sibling/supertype contract's member is not silently dropped; DeclaringTypes (type declarations, not methods) is intentionally excluded here.
type Config ¶
type Config struct {
// RepoRoot is the absolute path to the repository whose .grove/ directory
// holds the index. Required.
RepoRoot string
// NativeAnalyzers overrides native graph enrichment when non-nil.
NativeAnalyzers *bool
// NativeLanguages limits native analyzers to these languages/analyzer names.
NativeLanguages []string
// NativeDisabledLanguages disables these languages/analyzer names.
NativeDisabledLanguages []string
// NativeTimeout bounds each analyzer invocation. Zero uses Grove's default.
NativeTimeout time.Duration
}
Config controls how Engine opens a repository's Grove index.
type CoverageSite ¶ added in v0.15.0
type CoverageSite struct {
Symbol Symbol
TestCount int
Tests []Symbol // capped; TestCount carries the truth
}
CoverageSite pairs a change-set site with the tests that reach it.
type DeadCodeResult ¶ added in v0.15.0
type DeadCodeResult struct {
RootCount int
ReachableCount int
Considered int
Dead []Symbol // unreachable, non-exported, name unreferenced: deletion candidates
ExportedUnreferenced []Symbol // exported with zero in-project reference; external liveness unknown
Caveats []string
}
DeadCodeResult reports production functions/methods nothing reaches. Precision-first; Caveats are part of the result and must be relayed.
type DiffInput ¶ added in v0.4.5
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type Edge ¶
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type EdgeType ¶
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the embedded Grove API consumed by Prism, Fuse, and Relay. Methods are safe for concurrent use.
func Open ¶
Open initialises the on-disk store, runs migrations, and rebuilds the in-memory graph from whatever symbols are already persisted.
func (*Engine) CertifyDiff ¶ added in v0.4.5
CertifyDiff maps a unified diff onto the indexed graph and returns a conservative structural certification report. The report is additive: retrieval, MCP, and Provasign behavior do not change unless callers opt in. Changed files whose indexed content no longer matches the working tree are reported as index_stale and escalate the verdict to manual_review.
func (*Engine) ChangeImpact ¶ added in v0.14.1
ChangeImpact resolves a "Type.method" or "Type.method(ParamType, ...)" query to the exact change-set for that method's signature — type-resolved seeding, not name-substring seeding (contrast Impact).
func (*Engine) DeadCode ¶ added in v0.15.0
DeadCode computes forward reachability from every entry point (main/init, tests, exported symbols, plus extraRoots by name) and reports what nothing reaches.
func (*Engine) DiffAgainstFileContent ¶ added in v0.6.0
func (e *Engine) DiffAgainstFileContent(before []Symbol, relPath string, content []byte) (GraphDiff, error)
DiffAgainstFileContent diffs a snapshot against itself with one file's symbols replaced by those parsed from content: "what would change structurally if relPath had these bytes?".
func (*Engine) DiffSince ¶ added in v0.6.0
DiffSince diffs a previously captured snapshot against the engine's current graph.
func (*Engine) FileSymbols ¶ added in v0.6.1
FileSymbols returns the symbols currently indexed for one repo-relative file path, ordered by span. Use this instead of SnapshotSymbols when only a handful of files matter (e.g. working-set drift checks).
func (*Engine) ICR ¶
func (e *Engine) ICR(ctx context.Context, intent string) IsolatedChangeRegion
ICR computes the Isolated Change Region for a given intent.
func (*Engine) Index ¶
Index walks dir (defaults to RepoRoot), parses changed files via delta SHA, updates the persistent store, and refreshes the in-memory graph.
func (*Engine) MissingImplementations ¶ added in v0.15.0
func (e *Engine) MissingImplementations(ctx context.Context, query string) (MissingImplementationsResult, error)
MissingImplementations resolves a "Type.method" or "Type.method(ParamType, ...)" query to every type in the subtype closure that fails to implement the member.
func (*Engine) Neighbors ¶ added in v0.13.0
func (e *Engine) Neighbors(ctx context.Context, query, direction string, kinds ...EdgeType) ([]Neighbor, error)
Neighbors returns a symbol's direct typed neighbors with edge types preserved — the precise "what does X call / who calls X / what tests X" answer, as opposed to Impact's flattened, type-erased blast radius. direction is "out", "in", or "both"; kinds filters by edge type (empty = all).
func (*Engine) PreviewFileSymbols ¶ added in v0.6.0
PreviewFileSymbols parses in-memory content as if it lived at relPath (repo-relative) and returns the symbols Grove would index for it. Combine with Diff to compute the structural delta of content that is not on disk yet — e.g. a git merge driver's result, which git writes to the worktree only after the driver exits.
func (*Engine) Query ¶
Query resolves a natural-language intent into ranked symbols by blending TF-IDF semantic search with substring keyword matches.
func (*Engine) References ¶ added in v0.12.0
References answers "where is NAME used?" by scanning code occurrences of the name (comments/strings excluded), each attributed to its enclosing symbol. Unlike Impact (which walks the resolved call graph), this is the resolution- free reference layer: near-complete for types/classes/constants that calls edges never capture. ReferenceResult.Ambiguous reports whether several definitions share the name. Catches syntactic references only — reflection / dynamic usage is invisible, so "no references" is best-effort, not proof of dead code.
func (*Engine) RenamePlan ¶ added in v0.16.0
RenamePlan computes the change-impact set for query and converts it into line edits renaming the member to newName.
func (*Engine) SnapshotSymbols ¶ added in v0.6.0
SnapshotSymbols returns a deep copy of every symbol in the current graph. Capture one before a merge/reindex and pass it to Diff afterwards to get the structural delta.
func (*Engine) Symbols ¶
Symbols returns symbols whose name/qualified-name matches query (substring).
func (*Engine) TestsWithEvidence ¶ added in v0.11.0
func (e *Engine) TestsWithEvidence(ctx context.Context, query string) ([]Symbol, map[string]int, error)
TestsWithEvidence returns the covering tests plus the per-reason counts of edges the traversal policy excluded — the weak evidence Grove chose not to trust. Lets a consumer report "related tests" alongside what was withheld.
func (*Engine) UntestedSurface ¶ added in v0.15.0
UntestedSurface computes the change-set for a "Type.method" query and partitions it by covering-test evidence.
type EvidenceRef ¶ added in v0.4.5
type EvidenceRef = core.EvidenceRef
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type GraphDiff ¶ added in v0.6.0
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
func Diff ¶ added in v0.6.0
Diff computes the structural delta between two symbol snapshots, matched by stable identity (file path + qualified name + kind) so line shifts and content-SHA churn don't register as changes. This is the primitive behind the stale-context loop: diff the graph across a merge, intersect the changed/breaking symbols with another agent's working set, and you know exactly whose ground shifted.
type IndexResult ¶
type IndexResult = core.IndexResult
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type IsolatedChangeRegion ¶
type IsolatedChangeRegion = core.IsolatedChangeRegion
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type MissingImplementationsResult ¶ added in v0.15.0
type MissingImplementationsResult struct {
Query string
Contract []Symbol // the member's declaration(s) on the named type
Missing []Symbol // concrete closure types with no impl, own or inherited: compile errors
AbstractMissing []Symbol // abstract classes without an impl (their concrete subtypes are in Missing)
Unverifiable []Symbol // types whose class-extends chain leaves the index (an external base may provide it)
ImplementedCount int // closure types that do carry a compatible implementation
DefaultProvided bool // the contract supplies a body every subtype inherits; nothing can be missing
ExternalSupers []string
OverridesExternal []string
Completeness string // "closed" | "project-local"
}
MissingImplementationsResult is the deterministic answer to "which types claiming this contract do not implement Type.method" — the companion to ChangeImpact for interface evolution: ChangeImpact returns what must change when a signature changes; this returns who is broken once the member is required.
type Neighbor ¶ added in v0.13.0
type Neighbor struct {
Symbol Symbol
EdgeType EdgeType
Direction string // "out" = seed→symbol; "in" = symbol→seed
Confidence float64
}
Neighbor is a symbol reached from a seed by one typed edge.
type Reference ¶ added in v0.12.0
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type ReferenceResult ¶ added in v0.12.0
type ReferenceResult = parser.ReferenceResult
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type RenameEdit ¶ added in v0.16.0
type RenameEdit struct {
FilePath string
Line int // 1-based
Before string // source line as indexed
After string // with the rename applied
SiteID string // containing symbol ID
Site string // "relpath:name" for relay
}
RenameEdit is one suggested line edit in a rename plan.
type RenamePlanResult ¶ added in v0.16.0
type RenamePlanResult struct {
Query string
NewName string
Edits []RenameEdit
Ambiguous []RenameEdit
// Unresolved lists change-set sites for which no line edit could be
// derived — the agent must handle these manually.
Unresolved []string
SitesTotal int
ExternalSupers []string
OverridesExternal []string
Completeness string // "closed" | "project-local"
}
RenamePlanResult converts a ChangeImpact set into concrete line edits. Edits are confirmed (apply as-is); Ambiguous lines belong to methods that also call a same-named non-family method and need receiver-type verification before applying. Precision-first: nothing is silently included or dropped.
type Scored ¶
type Scored = struct {
Symbol *core.SymbolRecord
Score float64
}
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type Status ¶
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type Symbol ¶
type Symbol = core.SymbolRecord
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type SymbolChange ¶ added in v0.6.0
type SymbolChange = core.SymbolChange
Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.
type UntestedSurfaceResult ¶ added in v0.15.0
type UntestedSurfaceResult struct {
Query string
Untested []Symbol // change-set sites with no covering test
Covered []CoverageSite
TotalSites int
ExternalSupers []string
OverridesExternal []string
Completeness string
}
UntestedSurfaceResult partitions a method's change-set by test coverage: "before I change Type.method, what in its blast radius has no test?"