Struct GraphDb 

pub struct GraphDb {
    pub conn: Connection,
    pub repo_id: String,
    pub db_path: PathBuf,
}

Handle to the DuckDB database that stores the code knowledge graph.

Each repository gets its own .db file under ~/.cgx/repos/<repo_id>.db. All methods operate on the embedded DuckDB connection and are synchronous.

Fields

conn: Connection

repo_id: String

SHA-256–derived stable identifier for the repository path.

db_path: PathBuf

Implementations

impl GraphDb

pub fn open(repo_path: &Path) -> Result<Self>

Open (or create) the graph database for the repository at repo_path.

Creates all required tables and runs forward migrations on existing databases.

pub fn upsert_nodes(&self, nodes: &[Node]) -> Result<usize>

Insert or replace nodes in the nodes table, returning the count written.

pub fn upsert_edges(&self, edges: &[Edge]) -> Result<usize>

Insert or replace edges in the edges table, returning the count written.

pub fn upsert_tags(&self, tags: &[TagRow]) -> Result<usize>

Insert or replace comment annotation tags, returning the count written.

pub fn get_tags( &self, tag_type_filter: Option<&str>, comment_type_filter: Option<&str>, ) -> Result<Vec<TagRow>>

Query comment annotation tags with optional filters on tag type and comment kind.

pub fn clear_all_tags(&self) -> Result<()>

Drop and recreate the tags table, removing all stored annotations.

pub fn delete_tags_for_paths(&self, paths: &[String]) -> Result<()>

Delete all tags whose file_path is in paths (used during incremental re-index).

pub fn get_node(&self, id: &str) -> Result<Option<Node>>

Fetch a single node by its stable id, returning None if not found.

pub fn get_neighbors(&self, id: &str, depth: u8) -> Result<Vec<Node>>

BFS outward from id following edges in both directions, up to depth hops (max 3).

pub fn get_all_nodes(&self) -> Result<Vec<Node>>

Return every node in the graph.

pub fn get_all_edges(&self) -> Result<Vec<Edge>>

Return every edge in the graph.

pub fn node_count(&self) -> Result<u64>

Total number of nodes in the graph.

pub fn edge_count(&self) -> Result<u64>

Total number of edges in the graph.

pub fn clear(&self) -> Result<()>

Truncate nodes, edges, and communities tables (does not remove file hashes).

pub fn get_language_breakdown(&self) -> Result<HashMap<String, f64>>

Fraction of nodes per language, normalised to sum to 1.0.

pub fn get_node_counts_by_kind(&self) -> Result<HashMap<String, u64>>

Count of nodes per [NodeKind] string, e.g. {"Function": 412, "File": 38}.

pub fn upsert_node_scores( &self, node_id: &str, churn: f64, coupling: f64, ) -> Result<()>

Write normalised churn and coupling scores back to a single node.

pub fn update_in_out_degrees(&self) -> Result<()>

Recompute and persist in_degree / out_degree for every node.

pub fn get_hotspots(&self, limit: usize) -> Result<Vec<(String, f64, f64, i64)>>

Return the top limit file hotspots ranked by churn × coupling + in_degree.

Each tuple is (path, churn, coupling, in_degree).

pub fn get_ownership(&self) -> Result<Vec<(String, i64)>>

Return (author_name, file_count) pairs sorted by file count descending.

pub fn compute_coupling(&self) -> Result<()>

Recompute coupling for every File node as in_degree / max_in_degree.

pub fn update_node_communities( &self, communities: &HashMap<String, i64>, ) -> Result<usize>

Write Louvain community assignments from detect_communities back to the DB.

pub fn get_stats(&self) -> Result<RepoStats>

Return a RepoStats summary for the currently indexed repository.

pub fn get_entry_points(&self, limit: usize) -> Result<Vec<Node>>

Return up to limit nodes with in_degree == 0 — likely entry points or roots.

pub fn get_god_nodes(&self, limit: usize) -> Result<Vec<Node>>

Return up to limit nodes with the highest in_degree — the most-depended-on symbols.

pub fn get_communities(&self) -> Result<Vec<CommunityRow>>

Return all communities as CommunityRow tuples, sorted by size descending.

pub fn clear_communities(&self) -> Result<()>

Reset all community assignments to 0 and clear the communities table.

pub fn get_dependents(&self, id: &str, depth: u8) -> Result<Vec<Node>>

BFS following only incoming edges — returns all nodes that depend on id. Used for blast-radius analysis: if id changes, these nodes are affected.

pub fn get_nodes_by_community(&self, community: i64) -> Result<Vec<Node>>

Return all nodes that belong to the given community ID.

pub fn mark_dead_candidates(&self, items: &[(String, String)]) -> Result<()>

Set is_dead_candidate = true and dead_reason for each (node_id, reason) pair.

pub fn get_dead_code_stats(&self) -> Result<(i64, i64)>

Return (total_dead_candidates, high_confidence_count) from the DB.

pub fn get_edges_by_community(&self, community: i64) -> Result<Vec<Edge>>

Return all edges where both endpoints belong to the given community.

pub fn get_file_hashes(&self) -> Result<HashMap<String, String>>

Load the SHA-256 content hashes of all previously indexed files (used for incremental indexing).

pub fn set_file_hash(&self, path: &str, hash: &str) -> Result<()>

Record or update the SHA-256 hash for a single file path.

pub fn remove_file_hashes(&self, paths: &[String]) -> Result<()>

Remove stored file hashes for deleted or moved files.

pub fn delete_nodes_by_paths(&self, paths: &[String]) -> Result<usize>

Delete all nodes (and their connected edges) whose path is in paths.

Used during incremental re-indexing to remove stale data for changed files.

pub fn update_node_doc_comment(&self, id: &str, doc: &str) -> Result<()>

Store a doc comment string on a node (used by the docs-coverage analysis pass).

pub fn update_node_complexity(&self, id: &str, complexity: f64) -> Result<()>

Write a cyclomatic-complexity score back to a single node.

pub fn get_nodes_by_complexity( &self, limit: usize, min_score: f64, ) -> Result<Vec<Node>>

Return up to limit Function nodes with complexity >= min_score, sorted descending.

pub fn get_docs_coverage(&self) -> Result<DocsCoverage>

Returns (overall_pct, Vec<(community_id, documented, total)>, Vec)

pub fn upsert_clones(&self, clones: &[CloneRow]) -> Result<usize>

Insert or replace clone-pair records, returning the count written.

pub fn get_clones( &self, min_similarity: f64, kind_filter: Option<&str>, ) -> Result<Vec<CloneRow>>

Query clone pairs above min_similarity, optionally filtered by kind ("exact" or "near").

pub fn clear_clones(&self) -> Result<()>

Delete all clone-pair records from the database.

pub fn mark_test_files(&self, paths: &[String]) -> Result<()>

Flag every node whose path is in paths as a test file (is_test_file = true).

pub fn update_test_coverage(&self) -> Result<()>

After inserting TESTS edges, compute test_count and is_tested for non-test nodes.

pub fn get_test_coverage_summary( &self, top_n: usize, ) -> Result<(f64, i64, i64, Vec<Node>)>

Returns (overall_pct, tested_count, untested_count, gaps ranked by risk)

pub fn upsert_snapshot(&self, entry: &SnapshotEntry) -> Result<()>

Insert or replace a timeline snapshot entry.

pub fn get_snapshots(&self, limit: usize) -> Result<Vec<SnapshotEntry>>

Return up to limit timeline snapshots, most recent first.

pub fn get_snapshot_by_sha(&self, sha: &str) -> Result<Option<SnapshotEntry>>

Look up a snapshot by full SHA or short prefix, returning None if not cached.

pub fn snapshot_count(&self) -> i64

Total number of cached timeline snapshots.