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

> Learn to debug effectively with code-review-graph. Trace execution paths by building a knowledge graph and mapping call flows to pinpoint critical code during debugging.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```bash
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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```bash
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:

```bash

# 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:

```bash
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:

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) provides the connection handle for queries.