# How Execution Flow Tracing Finds Critical Code Paths in code-review-graph

> Learn how execution flow tracing finds critical code paths by using heuristics, breadth-first search, and scoring weighted factors. Understand code paths for better analysis.

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

---

**Execution flow tracing identifies critical code paths by detecting entry points through three heuristics, performing breadth-first search traversal of call graphs, and scoring each path against five weighted factors including file spread, external calls, security sensitivity, test coverage gaps, and depth.**

The `code-review-graph` open-source tool surfaces high-impact execution paths that span multiple files, invoke external dependencies, touch security-sensitive code, or lack adequate test coverage. This article examines the exact implementation in the source code, walking through entry-point detection, BFS-based flow tracing, criticality scoring, and result persistence.

## Detecting Entry Points

The `detect_entry_points` function ([`code_review_graph/flows.py:65‑78`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L65‑L78)) identifies where execution flows begin using three complementary heuristics:

### True Roots

Functions with **no incoming `CALLS` edges** are classified as true roots—these are never invoked by other code in the repository and typically represent standalone scripts or top-level handlers.

### Framework Decorators

Functions whose `extra["decorators"]` metadata match patterns in [`_FRAMEWORK_DECORATOR_PATTERNS`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L27‑L72) are flagged as entry points. This captures common web framework patterns like `@app.route`, `@click.command`, and similar decorators that mark callable endpoints.

### Conventional Naming Patterns

Functions matching patterns in [`_ENTRY_NAME_PATTERNS`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L75‑L114)—such as `main`, `handle_*`, `on_*`, `run`, and `start_*`—are recognized as conventional entry points even without decorator metadata or incoming call edges.

## Tracing Execution Flows with BFS

Once entry points are identified, `_trace_single_flow` ([`flows.py:23‑38`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L23‑L38)) performs **forward breadth-first search** along `CALLS` edges to reconstruct complete execution paths:

- **Traversal depth**: Controlled by `max_depth` parameter (default **15**)
- **Path recording**: Builds ordered lists of `path_ids` (node IDs) and `path_qnames` (qualified names)
- **Filtering**: Single-node flows with no outgoing calls are discarded as trivial

Each traced flow captures metadata including `depth`, `node_count`, `file_count`, and the complete list of touched files.

## Criticality Scoring Algorithm

The `compute_criticality` function ([`flows.py:25‑94`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L25‑L94)) assigns each flow a **0-1 score** using a weighted combination of five factors, rounded to four decimal places:

| Factor | Measurement | Weight |
|--------|-------------|--------|
| **File spread** | Distinct files touched (`file_count`): 1 file → 0.0, 5+ files → 1.0 | 0.30 |
| **External calls** | Calls to targets not present in graph: 0 calls → 0.0, 5+ → 1.0 | 0.20 |
| **Security sensitivity** | Nodes matching `SECURITY_KEYWORDS` in [[`constants.py`](https://github.com/tirth8205/code-review-graph/blob/main/constants.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/constants.py) (e.g., `auth`, `token`, `encrypt`) | 0.25 |
| **Test-coverage gap** | 1 − (covered nodes / total nodes), where coverage is determined by `TESTED_BY` edges | 0.15 |
| **Call depth** | BFS depth capped at 10 for full credit | 0.10 |

The **0.30 weight on file spread** makes cross-cutting flows the strongest signal of criticality, while **security sensitivity at 0.25** ensures high-risk code paths receive elevated attention regardless of other factors.

## Storing and Accessing Flow Results

After scoring, `trace_flows` sorts all flows by descending criticality score ([`flows.py:86‑100`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L86‑L100)). The results flow through a persistence layer:

- `store_flows` ([`flows.py:402‑453`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py#L402‑453)): Persists discovered flows to the graph store
- `get_flows`: Retrieves flows with optional sorting and pagination
- `get_flow_by_id`: Fetches detailed view of a single execution path
- `get_affected_flows`: Identifies which flows are impacted by specific file changes

## Practical Usage Examples

```python
from code_review_graph.flows import trace_flows, get_flow, get_affected_flows, store_flows
from code_review_graph.main import load_store

# Trace all execution flows with default depth of 15

store = load_store("/path/to/repo")
all_flows = trace_flows(store)  # Returns list sorted by criticality score

# Persist results for later analysis

stored_count = store_flows(store, all_flows)

# Retrieve top 5 most critical flows for review

top_critical = get_flows(store, sort_by="criticality", limit=5)

# Examine detailed execution path

flow_id = top_critical[0]["id"]
detail = get_flow(store, flow_id)  # Includes each step in path_ids/path_qnames

# Find flows affected by recent changes

changed_files = ["src/auth.py", "src/utils/http.py"]
impact = get_affected_flows(store, changed_files)

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`code_review_graph/flows.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/flows.py) | Entry-point detection (`detect_entry_points`), BFS tracing (`_trace_single_flow`), criticality scoring (`compute_criticality`), and persistence |
| [`code_review_graph/constants.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/constants.py) | `SECURITY_KEYWORDS` and configurable defaults for scoring weights |

## Summary

- **Entry-point detection** uses three heuristics—true roots, framework decorators, and conventional naming—to identify where flows start
- **BFS traversal** with configurable depth (default 15) traces forward through `CALLS` edges to build complete execution paths
- **Criticality scoring** weights file spread highest (0.30), followed by security sensitivity (0.25), external calls (0.20), test gaps (0.15), and depth (0.10)
- **Results are persisted** and queryable by criticality, individual flow ID, or file-affected status

## Frequently Asked Questions

### What makes a code path "critical" in code-review-graph?

A path is critical based on five weighted factors: how many files it spans, whether it calls external libraries, if it touches security-sensitive functions, how much test coverage it lacks, and how deep the call chain runs. The composite 0-1 score surfaces paths that are broadly impactful, risky, or under-tested.

### How does the tool distinguish entry points from regular functions?

The `detect_entry_points` function applies three heuristics: functions with no incoming calls (true roots), functions decorated with recognized framework patterns, and functions with conventional names like `main` or `handle_request`. Any match qualifies as an entry point.

### Why use breadth-first search instead of depth-first search?

BFS explores execution paths layer by layer, which naturally supports the depth-based scoring factor and ensures shallow, high-impact paths are discovered before deeper, potentially less critical chains. The explicit `max_depth` parameter also prevents unbounded traversal in complex codebases.

### Can the scoring weights be customized?

Yes. While the default weights are hardcoded in `compute_criticality`, the `SECURITY_KEYWORDS` list and other configuration values reside in [`constants.py`](https://github.com/tirth8205/code-review-graph/blob/main/constants.py). Users can modify these constants or fork the scoring algorithm to adjust factor priorities for their specific review workflows.