Trait GraphStore 

pub trait GraphStore: Send + Sync {
    // Required methods
    fn apply_diff(&mut self, branch: &str, diff: &GraphDiff) -> Result<()>;
    fn lookup_symbol(
        &self,
        branch: &str,
        name: &str,
        fuzzy: bool,
    ) -> Result<Vec<Node>>;
    fn find_callers(
        &self,
        branch: &str,
        function_name: &str,
    ) -> Result<Vec<Node>>;
    fn find_callers_deep(
        &self,
        branch: &str,
        function_name: &str,
        depth: u8,
    ) -> Result<CallersDeep>;
    fn symbol_context(&self, branch: &str, name: &str) -> Result<SymbolContext>;
    fn list_definitions(&self, branch: &str, file: &Path) -> Result<Vec<Node>>;
    fn list_all_nodes(&self, branch: &str) -> Result<Vec<Node>>;
    fn list_all_edges(&self, branch: &str) -> Result<Vec<Edge>>;
    fn branch_diff(&self, from: &str, to: &str) -> Result<GraphDiff>;
    fn find_callees(
        &self,
        branch: &str,
        function_name: &str,
        depth: u8,
    ) -> Result<CallersDeep>;
    fn find_implementors(
        &self,
        branch: &str,
        trait_or_interface_name: &str,
    ) -> Result<Vec<Node>>;
    fn trace_path(
        &self,
        branch: &str,
        from: &str,
        to: &str,
    ) -> Result<Vec<Node>>;
    fn list_symbols_in_range(
        &self,
        branch: &str,
        file: &Path,
        start_line: u32,
        end_line: u32,
    ) -> Result<Vec<Node>>;
    fn find_unused_symbols(
        &self,
        branch: &str,
        kind: Option<NodeKind>,
    ) -> Result<Vec<Node>>;
    fn get_subgraph(
        &self,
        branch: &str,
        seed_name: &str,
        depth: u8,
        direction: &str,
    ) -> Result<SubGraph>;
    fn last_indexed_sha(&self, branch: &str) -> Result<Option<String>>;
    fn set_last_indexed_sha(&mut self, branch: &str, sha: &str) -> Result<()>;

    // Provided methods
    fn find_callers_with_confidence(
        &self,
        branch: &str,
        function_name: &str,
    ) -> Result<Vec<(Node, EdgeConfidence)>> { ... }
    fn find_callers_by_id_with_confidence(
        &self,
        branch: &str,
        target_id: &str,
    ) -> Result<Vec<(Node, EdgeConfidence)>> { ... }
    fn list_nodes_page(
        &self,
        branch: &str,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<Node>> { ... }
    fn list_edges_page(
        &self,
        branch: &str,
        offset: usize,
        limit: usize,
    ) -> Result<Vec<Edge>> { ... }
    fn list_edges_by_kind(
        &self,
        branch: &str,
        kind: EdgeKind,
    ) -> Result<Vec<Edge>> { ... }
    fn search_by_attributes(
        &self,
        branch: &str,
        filter: &AttributeFilter,
        limit: usize,
    ) -> Result<Vec<Node>> { ... }
    fn graph_stats(&self, branch: &str) -> Result<GraphStats> { ... }
    fn search_nodes(
        &self,
        branch: &str,
        query: &str,
        limit: usize,
    ) -> Result<Vec<Node>> { ... }
    fn get_nodes_by_ids(
        &self,
        branch: &str,
        ids: &[String],
    ) -> Result<Vec<Node>> { ... }
    fn module_dependencies(
        &self,
        branch: &str,
        module_name: &str,
    ) -> Result<Vec<Node>> { ... }
    fn find_type_usages(
        &self,
        branch: &str,
        type_name: &str,
    ) -> Result<Vec<Node>> { ... }
    fn find_call_sites(
        &self,
        branch: &str,
        function_name: &str,
    ) -> Result<Vec<CallSite>> { ... }
    fn find_importers(
        &self,
        branch: &str,
        symbol_name: &str,
    ) -> Result<Vec<Node>> { ... }
    fn type_hierarchy(&self, branch: &str, name: &str) -> Result<TypeHierarchy> { ... }
    fn get_subgraph_by_id(
        &self,
        branch: &str,
        seed_id: &str,
        depth: u8,
        direction: &str,
    ) -> Result<SubGraph> { ... }
    fn get_neighborhood_by_id(
        &self,
        branch: &str,
        seed_id: &str,
        direction: &str,
        limit: usize,
    ) -> Result<SubGraph> { ... }
}

Backend-agnostic interface for the knowledge graph store.

The v0.1 implementation is KuzuGraphStore (local embedded DB). A remote backend can be plugged in by implementing this trait without touching the indexer or MCP layers.

Required Methods

fn apply_diff(&mut self, branch: &str, diff: &GraphDiff) -> Result<()>

Apply an incremental diff to the named branch’s graph.

fn lookup_symbol( &self, branch: &str, name: &str, fuzzy: bool, ) -> Result<Vec<Node>>

Find all nodes matching name on branch. When fuzzy is true, matches any node whose name contains name (case-sensitive substring). When false, exact match only.

fn find_callers(&self, branch: &str, function_name: &str) -> Result<Vec<Node>>

Find all call-site nodes whose outgoing Calls edge points to a node named function_name on branch (single hop).

fn find_callers_deep( &self, branch: &str, function_name: &str, depth: u8, ) -> Result<CallersDeep>

Multi-hop BFS: find callers up to depth hops away. Returns callers grouped by hop distance (1..=depth). depth is capped at 5 to prevent runaway queries.

fn symbol_context(&self, branch: &str, name: &str) -> Result<SymbolContext>

Return a 360° view of a symbol: its definition, direct callers, direct callees, and nodes that reference it via Uses edges.

fn list_definitions(&self, branch: &str, file: &Path) -> Result<Vec<Node>>

List all top-level definitions in file on branch.

fn list_all_nodes(&self, branch: &str) -> Result<Vec<Node>>

Return all nodes in branch’s graph.

fn list_all_edges(&self, branch: &str) -> Result<Vec<Edge>>

Return all edges in branch’s graph.

fn branch_diff(&self, from: &str, to: &str) -> Result<GraphDiff>

Return the graph delta between two branches as a GraphDiff. Nodes/edges present in to but not from are in added_*. Nodes/edges present in from but not to are in removed_*.

fn find_callees( &self, branch: &str, function_name: &str, depth: u8, ) -> Result<CallersDeep>

Find all functions/methods called by function_name up to depth hops. Returns callees grouped by hop distance (1..=depth). Capped at 5.

fn find_implementors( &self, branch: &str, trait_or_interface_name: &str, ) -> Result<Vec<Node>>

Find all structs/classes that implement/inherit trait_or_interface_name.

fn trace_path(&self, branch: &str, from: &str, to: &str) -> Result<Vec<Node>>

Find all call paths between from and to using BFS. Returns at most one path (the shortest), as a sequence of nodes.

fn list_symbols_in_range( &self, branch: &str, file: &Path, start_line: u32, end_line: u32, ) -> Result<Vec<Node>>

Find all nodes in file whose span overlaps [start_line, end_line].

fn find_unused_symbols( &self, branch: &str, kind: Option<NodeKind>, ) -> Result<Vec<Node>>

Find symbols with no incoming Calls or Uses edges (potential dead code). If kind is provided, filters to only that NodeKind.

fn get_subgraph( &self, branch: &str, seed_name: &str, depth: u8, direction: &str, ) -> Result<SubGraph>

Return a subgraph centred on seed_name up to depth hops. direction: “in” (callers), “out” (callees), or “both”.

fn last_indexed_sha(&self, branch: &str) -> Result<Option<String>>

Last commit SHA successfully indexed for branch. None if the branch has never been indexed.

fn set_last_indexed_sha(&mut self, branch: &str, sha: &str) -> Result<()>

Persist the commit SHA after a successful index run.

Provided Methods

fn find_callers_with_confidence( &self, branch: &str, function_name: &str, ) -> Result<Vec<(Node, EdgeConfidence)>>

Like find_callers but also returns each caller’s edge confidence. The default conservatively marks all callers as Inferred; backends should override with a query that reads e.confidence from the edge.

fn find_callers_by_id_with_confidence( &self, branch: &str, target_id: &str, ) -> Result<Vec<(Node, EdgeConfidence)>>

Find direct callers for one exact target node ID, including edge confidence. Agent-facing queries use this after symbol disambiguation so common names such as get cannot merge unrelated call graphs.

The default implementation filters the full graph in memory. Stores should override this with an indexed query.

fn list_nodes_page( &self, branch: &str, offset: usize, limit: usize, ) -> Result<Vec<Node>>

Return a deterministic page of nodes ordered by stable node ID.

The default implementation slices list_all_nodes for compatibility. Stores should override this with query-level OFFSET/LIMIT push-down so visualization clients can progressively load very large graphs.

fn list_edges_page( &self, branch: &str, offset: usize, limit: usize, ) -> Result<Vec<Edge>>

Return a deterministic page of edges ordered by source, destination, kind, and source line. See GraphStore::list_nodes_page.

fn list_edges_by_kind(&self, branch: &str, kind: EdgeKind) -> Result<Vec<Edge>>

Return edges of a specific kind in branch’s graph. The default filters list_all_edges in-memory; backends should override with a WHERE-clause push-down for large graphs.

fn search_by_attributes( &self, branch: &str, filter: &AttributeFilter, limit: usize, ) -> Result<Vec<Node>>

Find nodes matching a structural filter (kind, async, visibility, complexity range, name substring), up to limit results.

The default filters list_all_nodes in-memory; backends should override with a WHERE-clause push-down.

fn graph_stats(&self, branch: &str) -> Result<GraphStats>

Aggregate node/edge counts (total + per-kind) for branch.

The default counts in-memory from list_all_nodes/list_all_edges; backends should override with a COUNT push-down.

fn search_nodes( &self, branch: &str, query: &str, limit: usize, ) -> Result<Vec<Node>>

Return nodes whose name or qualified_name contains query (case- sensitive substring), up to limit results. Implementations should push the filter to the store rather than scanning all nodes in memory.

The default falls back to list_all_nodes for stores that don’t override this method (e.g. the in-memory test stub).

fn get_nodes_by_ids(&self, branch: &str, ids: &[String]) -> Result<Vec<Node>>

Resolve a set of node IDs to full nodes. Order is not guaranteed; IDs that don’t exist on branch are silently skipped.

The default falls back to list_all_nodes; backends should override with an indexed ID lookup.

fn module_dependencies( &self, branch: &str, module_name: &str, ) -> Result<Vec<Node>>

Return the in-repo modules that a module named module_name depends on, resolved by following its Imports edges to the defining module of each imported symbol. Answers “what does this module depend on”.

External/stdlib imports are not graphed, so only intra-repo dependencies appear. The default walks nodes + edges in-memory; backends should override with a join query.

fn find_type_usages(&self, branch: &str, type_name: &str) -> Result<Vec<Node>>

Find functions/methods that reference a type named type_name as a parameter or return type (following Uses edges). Answers “where is type T used in a signature” — the type-level analogue of find_callers.

The default walks list_all_edges; backends should override with a directed Cypher match.

fn find_call_sites( &self, branch: &str, function_name: &str, ) -> Result<Vec<CallSite>>

Find every call site of the function named function_name: the calling symbol plus the source line of each call expression (following Calls edges). Where find_callers returns only the calling symbols, this also pinpoints the line each call happens on.

The default walks list_all_edges; backends should override with a directed Cypher match that returns the edge line.

fn find_importers(&self, branch: &str, symbol_name: &str) -> Result<Vec<Node>>

Find the module/file nodes that import a symbol named symbol_name (following Imports edges). Answers “who imports X”.

The default walks list_all_edges; backends should override with a directed Cypher match.

fn type_hierarchy(&self, branch: &str, name: &str) -> Result<TypeHierarchy>

Return both directions of the type relation for name: the types it implements/extends (supertypes) and the types that implement/extend it (subtypes), following Implements and Inherits edges.

The default walks list_all_edges; backends should override with a directed Cypher match.

fn get_subgraph_by_id( &self, branch: &str, seed_id: &str, depth: u8, direction: &str, ) -> Result<SubGraph>

Return a subgraph around one exact seed node ID. Agent-facing queries use this after disambiguation so repeated short names cannot merge unrelated neighborhoods.

The default scans the graph in memory. Stores should override this with indexed traversal.

fn get_neighborhood_by_id( &self, branch: &str, seed_id: &str, direction: &str, limit: usize, ) -> Result<SubGraph>

Return one bounded hop around an exact seed ID. Visualization clients use repeated calls to expand large graphs without materializing an unbounded multi-hop neighborhood.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors