grove

package
v0.22.0 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source
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

type DiffInput = core.DiffInput

Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.

type Edge

type Edge = core.Edge

Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.

type EdgeType

type EdgeType = core.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

func Open(ctx context.Context, cfg Config) (*Engine, error)

Open initialises the on-disk store, runs migrations, and rebuilds the in-memory graph from whatever symbols are already persisted.

func (*Engine) AffectedTests added in v0.20.0

func (e *Engine) AffectedTests(ctx context.Context, files []string) ([]Symbol, error)

AffectedTests returns the test symbols covering any symbol defined in the given repo-relative files — "given this diff, which tests must run". The file-diff analog of Tests(query): feed it `git diff --name-only` to select exactly the tests a change can break, for a "run only affected tests" CI step.

func (*Engine) CertifyDiff added in v0.4.5

func (e *Engine) CertifyDiff(ctx context.Context, input DiffInput) (CertificationReport, error)

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

func (e *Engine) ChangeImpact(ctx context.Context, query string) (ChangeImpactResult, error)

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) Close

func (e *Engine) Close() error

Close releases the underlying SQLite handle.

func (*Engine) DeadCode added in v0.15.0

func (e *Engine) DeadCode(ctx context.Context, extraRoots []string) (DeadCodeResult, error)

DeadCode computes forward reachability from every entry point (main/init, tests, exported symbols, plus extraRoots by name) and reports what nothing reaches.

func (*Engine) Deps

func (e *Engine) Deps(ctx context.Context, filePath string) ([]Edge, error)

Deps returns the outgoing dependency edges for filePath.

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

func (e *Engine) DiffSince(ctx context.Context, before []Symbol) GraphDiff

DiffSince diffs a previously captured snapshot against the engine's current graph.

func (*Engine) FileSymbols added in v0.6.1

func (e *Engine) FileSymbols(ctx context.Context, relPath string) []Symbol

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) Impact

func (e *Engine) Impact(ctx context.Context, query string, maxDepth int) ([]Symbol, error)

Impact returns the blast radius for a symbol/file query.

func (*Engine) Index

func (e *Engine) Index(ctx context.Context, dir string) (IndexResult, error)

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

func (e *Engine) PreviewFileSymbols(relPath string, content []byte) ([]Symbol, error)

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

func (e *Engine) Query(ctx context.Context, intent string, limit int) ([]Symbol, error)

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

func (e *Engine) References(ctx context.Context, name string) (ReferenceResult, error)

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

func (e *Engine) RenamePlan(ctx context.Context, query, newName string) (RenamePlanResult, error)

RenamePlan computes the change-impact set for query and converts it into line edits renaming the member to newName.

func (*Engine) Root

func (e *Engine) Root() string

Root returns the repository root the engine is attached to.

func (*Engine) Semantic

func (e *Engine) Semantic(ctx context.Context, query string, limit int) ([]Scored, error)

Semantic returns TF-IDF-ranked symbols with cosine-similarity scores.

func (*Engine) SnapshotGraph added in v0.21.0

func (e *Engine) SnapshotGraph(ctx context.Context) ([]Symbol, []Edge)

SnapshotGraph returns a deep copy of every symbol plus every edge in the current graph. This is the bulk export consumers use to build derived projections (e.g. Prism's component-level views) without N per-symbol round-trips; edges carry their evidence Source/Reason/Confidence so derived results can report the tier of their constituent evidence.

func (*Engine) SnapshotSymbols added in v0.6.0

func (e *Engine) SnapshotSymbols(ctx context.Context) []Symbol

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) Status

func (e *Engine) Status(ctx context.Context) (Status, error)

Status reports the current persisted index summary.

func (*Engine) Symbols

func (e *Engine) Symbols(ctx context.Context, query string, limit int) ([]Symbol, error)

Symbols returns symbols whose name/qualified-name matches query (substring).

func (*Engine) Tests

func (e *Engine) Tests(ctx context.Context, query string) ([]Symbol, error)

Tests returns the test symbols that cover the given symbol/file query.

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

func (e *Engine) UntestedSurface(ctx context.Context, query string) (UntestedSurfaceResult, error)

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

type GraphDiff = core.GraphDiff

Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.

func Diff added in v0.6.0

func Diff(before, after []Symbol) GraphDiff

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

type Reference = parser.Reference

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

type Status = core.Status

Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.

func QuickStatus added in v0.21.1

func QuickStatus(ctx context.Context, repoRoot string) (Status, error)

QuickStatus reports the persisted index summary without constructing an Engine. Open() rehydrates every stored symbol and edge into the in-memory graph so reads work immediately — work Status never touches (it is three live COUNT(*) queries against the store). Opening the store alone turns a ~1.3s status call on a 500k-edge index into a few milliseconds, with byte-identical results because both paths execute the same store.Status. QuickStatus makes no freshness claim: counts reflect the last persisted index, exactly like Engine.Status.

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?"

type Verdict added in v0.4.5

type Verdict = core.Verdict

Re-exported core types — Prism/Fuse/Relay can use these directly without mirroring shapes.

Jump to

Keyboard shortcuts

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