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

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) 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 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—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) 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) 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/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). The results flow through a persistence layer:

• store_flows (flows.py:402‑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

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	Entry-point detection (detect_entry_points), BFS tracing (_trace_single_flow), criticality scoring (compute_criticality), and persistence
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. Users can modify these constants or fork the scoring algorithm to adjust factor priorities for their specific review workflows.

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