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 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> { ... }
}

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 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.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors