How to Use code-review-graph for Debugging by Tracing Execution Paths

code-review-graph traces execution paths by building a persistent knowledge graph of your repository, identifying entry points, and performing breadth-first search to map call flows, enabling you to pinpoint critical code paths during debugging.

Debugging complex codebases requires understanding how execution propagates from entry points through nested function calls. The code-review-graph open-source tool constructs a queryable knowledge graph where nodes represent files, classes, and functions, and edges capture relationships like CALLS and IMPORTS. By tracing these paths, you can isolate high-impact execution flows and focus debugging efforts on the most critical areas of your code.

How Execution Flow Tracing Works

The flows subsystem analyzes your repository's structure to discover how code actually runs. It operates on the graph stored in .code-review-graph/graph.db, walking relationships to map realistic execution scenarios.

Entry Point Detection

In code_review_graph/flows.py, the detect_entry_points function (lines 65-100) identifies functions that serve as gateways into your application. It locates symbols with no incoming CALLS edges, framework-specific decorators (like Flask routes or Click commands), and conventional names such as main or cli. These entry points represent the start of every traceable execution path.

BFS Path Discovery

Once entry points are identified, the _trace_single_flow function (lines 23-63) performs a breadth-first search (BFS) walking forward through CALLS edges. Each traversal collects reachable nodes until it exhausts the call graph or hits configured depth limits. The result is an ordered list of node IDs representing a complete execution flow from entry to termination.

Criticality Scoring

Not all execution paths carry equal risk. The compute_criticality function (lines 25-94) evaluates each flow and assigns a 0-1 score based on:

• File spread: Number of distinct files touched
• External calls: Invocations of third-party or system libraries
• Security-sensitive names: Matches for patterns like auth, password, or encrypt
• Test-coverage gap: Whether the flow lacks corresponding test nodes
• Depth: Total call stack depth

Higher scores indicate flows that are more complex, less tested, and potentially more dangerous to modify.

Building the Knowledge Graph

Before tracing paths, you must parse the repository into the graph database. Run this command once, or re-run it after significant code changes:

code-review-graph build

This populates the SQLite database at .code-review-graph/graph.db with nodes for every file, class, and function, plus edges for CALLS, IMPORTS, and TESTED-BY relationships. The build process also triggers store_flows (lines 102-157 in code_review_graph/flows.py) to persist flow records into the flows and flow_memberships tables.

Listing Critical Execution Flows

To see which paths warrant immediate attention during debugging, list flows sorted by criticality:

code-review-graph flows --sort criticality --limit 10

This command invokes tools.list_flows → flows.get_flows → trace_flows, returning a JSON array where each object contains:

• name: Human-readable entry point identifier
• entry_point: Qualified name (e.g., myapp.handlers.handle_request)
• depth: Maximum call stack depth
• node_count: Total functions invoked
• file_count: Distinct source files involved
• criticality: Risk score from 0 to 1

Targeting flows with high criticality scores ensures you review the most impactful code first.

Inspecting Specific Flow Source Code

After identifying a suspicious flow, inspect its exact execution steps:

# By flow name

code-review-graph flow --name myapp.handlers.handle_request --source

# Or by flow ID from the previous list

code-review-graph flow --id 3 --source

The --source flag includes source code snippets for each node in the path, showing the exact lines executed. This bridges the gap between high-level architecture and line-by-line debugging, letting you verify assumptions about data flow and state mutation.

Debugging Recent Changes

When investigating regressions, determine which execution paths are affected by modified files:

git diff --name-only HEAD~1 | xargs -n1 code-review-graph detect-changes --brief

This runs tools.get_affected_flows, which internally calls flows.get_affected_flows to locate flows containing nodes from the changed files. The output highlights high-criticality flows that intersect with your diff, directing you to the exact call chains that might have broken.

After applying a fix, re-run the flow inspection to verify that the problematic node no longer appears in critical paths or that the overall flow depth has decreased.

Using the Python API

For custom debugging scripts or Jupyter notebooks, bypass the CLI and use the Python API directly:

from code_review_graph.main import get_graph_store
from code_review_graph.flows import trace_flows, get_flows, get_affected_flows

# Load the graph database

store = get_graph_store()

# Trace all execution paths

all_flows = trace_flows(store)

# Identify the top 5 highest-risk flows

top_five = sorted(all_flows, key=lambda f: f["criticality"], reverse=True)[:5]

# Print detailed steps for the riskiest flow

flow_id = top_five[0]["id"]
flow_detail = get_flow_by_id(store, flow_id)
for step in flow_detail["steps"]:
    print(f"{step['qualified_name']} ({step['file']}:{step['line_start']})")

The code_review_graph/tools.py module (generated at runtime) provides thin wrappers like list_flows and get_flow that expose these functions to the CLI via _run_graph_tool_command in code_review_graph/cli.py (lines 31-99).

Summary

• Build the graph once with code-review-graph build to populate the SQLite database at .code-review-graph/graph.db.
• Identify high-risk paths using the criticality score, which weighs file spread, external dependencies, security sensitivity, and test coverage.
• Trace specific execution flows via CLI or Python API to see exact file paths and line numbers involved in a call chain.
• Validate fixes by re-running flow analysis to confirm reduced depth or removal of problematic nodes from critical paths.
• Integrate with git workflows using detect-changes to instantly see which execution paths are impacted by your current working directory changes.

Frequently Asked Questions

What types of relationships does code-review-graph trace?

The tool constructs edges for CALLS (function invocations), IMPORTS (module dependencies), and TESTED-BY (test coverage links). These relationships are stored as a graph in SQLite, enabling the BFS traversal logic in code_review_graph/flows.py to discover realistic execution paths.

How is the criticality score calculated?

The compute_criticality function in code_review_graph/flows.py analyzes five dimensions: the number of files touched (file spread), calls to external libraries, presence of security-sensitive keywords, lack of test coverage, and call stack depth. It aggregates these into a normalized 0-1 score where 1.0 represents the highest risk.

Can I integrate this into a CI/CD pipeline?

Yes. The CLI commands return structured JSON suitable for scripting, and the Python API allows you to call trace_flows() and get_affected_flows() programmatically. You can fail builds when pull requests modify high-criticality flows without corresponding test updates, or generate reports of affected execution paths for mandatory code reviews.

Where are the flow traces stored?

Flow records persist in the flows and flow_memberships SQLite tables within .code-review-graph/graph.db. The store_flows function handles persistence, while get_graph_store() in code_review_graph/main.py provides the connection handle for queries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}