grove

package
v0.21.0 Latest Latest
Warning

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

Go to latest
Published: Jul 19, 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.

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