Explore — Graph-Driven Project Understanding

Explore — Graph-Driven Project Understanding

Overview

Query the project's code knowledge graph to understand architecture, trace call chains, and analyze impact. Powered by CRG's graph.db (SQLite) + CRG Python API.

Announce at start: "I'm using the explore skill to query the project's code knowledge graph."

Prerequisites

• CRG must be installed: python -c "import code_review_graph.tools"
• Graph must exist: .code-review-graph/​graph.db
• If missing → tell user: "Please run /​graph build first"
• If graph older than 24h → suggest: "Graph may be stale, consider /​graph update"

Commands

/​explore architecture — Project Architecture Overview

Shows module decomposition, coupling relationships, and entry points.

from pathlib import Path
from code_review_graph.tools import list_communities_func, get_architecture_overview_func

# Get communities (modules) — CRG takes repo_root, not db_path
repo = Path(".")
result = list_communities_func(repo_root=repo)
communities = result.get("communities", [])

# Get architecture overview
overview = get_architecture_overview_func(repo_root=repo)

Present as: module list with node counts, inter-module coupling, key entry points.

/​explore module <name> — Module Details

Shows nodes, edges, and responsibilities of a specific module.

from pathlib import Path
from code_review_graph.tools import list_communities_func

# CRG has no single-community query API — filter from full list
result = list_communities_func(repo_root=Path("."))
communities = result.get("communities", [])
target = [c for c in communities if name.lower() in str(c).lower()]

/​explore callers <func> — Who Calls This Function?

Direct SQLite query (no CRG wrapper available for this):

import sqlite3
conn = sqlite3.connect(".code-review-graph/​graph.db")
conn.row_factory = sqlite3.Row
rows = conn.execute(
    "SELECT * FROM edges WHERE target_qualified LIKE ? AND kind='CALLS'",
    (f"%{func}%",)
).fetchall()
conn.close()

/​explore callees <func> — What Does This Function Call?

import sqlite3
conn = sqlite3.connect(".code-review-graph/​graph.db")
conn.row_factory = sqlite3.Row
rows = conn.execute(
    "SELECT * FROM edges WHERE source_qualified LIKE ? AND kind='CALLS'",
    (f"%{func}%",)
).fetchall()
conn.close()

/​explore impact <file> — Impact Analysis

Shows which flows and functions are affected by changes to a file.

from pathlib import Path
from code_review_graph.tools import get_impact_radius, get_affected_flows_func

# CRG takes changed_files (list) and repo_root, not file_path + db_path
repo = Path(".")
impact = get_impact_radius(changed_files=["<file>"], repo_root=repo)
result = get_affected_flows_func(changed_files=["<file>"], repo_root=repo)
flows = result.get("flows", result.get("affected_flows", []))

/​explore hotspots — Hub Nodes, Bridge Nodes, Knowledge Gaps

IMPORTANT: get_hub_nodes_func / get_bridge_nodes_func from code_review_graph.tools are buggy. Use code_review_graph.analysis instead:

from code_review_graph.tools._common import _get_store
from code_review_graph.analysis import find_hub_nodes, find_bridge_nodes

# CRG analysis functions take a store object, not db_path
# Must use _get_store() first to get the store
store, _ = _get_store(str(Path(".").resolve()))
hubs = find_hub_nodes(store, top_n=20)
bridges = find_bridge_nodes(store, top_n=20)

For knowledge gaps (get_knowledge_gaps has sqlite3.Row type issue), use direct SQLite:

import sqlite3
conn = sqlite3.connect(".code-review-graph/​graph.db")
# Nodes with high connectivity but no docstring/​comments
rows = conn.execute("""
    SELECT n.qualified_name, n.kind, COUNT(e.id) as edge_count
    FROM nodes n
    JOIN edges e ON n.qualified_name = e.source_qualified OR n.qualified_name = e.target_qualified
    WHERE n.docstring IS NULL OR n.docstring = ''
    GROUP BY n.qualified_name
    HAVING edge_count > 5
    ORDER BY edge_count DESC
    LIMIT 20
""").fetchall()
conn.close()

/​explore flows — Execution Flow List

from pathlib import Path
from code_review_graph.tools import list_flows

# Note: NO _func suffix — it's list_flows, not list_flows_func
result = list_flows(repo_root=Path("."))
flows = result.get("flows", [])

/​explore search <keyword> — Search Nodes by Keyword

Try CRG's search first, fallback to direct SQLite:

import sqlite3
conn = sqlite3.connect(".code-review-graph/​graph.db")
# Try FTS5 first
try:
    rows = conn.execute(
        "SELECT * FROM nodes_fts WHERE nodes_fts MATCH ?", (keyword,)
    ).fetchall()
except:
    # Fallback: LIKE query
    rows = conn.execute(
        "SELECT * FROM nodes WHERE name LIKE ?", (f"%{keyword}%",)
    ).fetchall()
conn.close()

CRG API Notes (from challenger review)

These bugs are confirmed in backend/​services/​graph_builder.py workarounds:

Development Workflow Integration

Graceful Degradation

• CRG not installed or graph missing → "Please run /​graph build first"
• Graph stale (>24h since last update) → "Graph may be outdated, suggest /​graph update"