Execution Flow Tracing

Relevant source files

The following files were used as context for generating this wiki page:

• code_review_graph/flows.py
• code_review_graph/main.py
• code_review_graph/tools/review.py
• tests/test_flows.py
• tests/test_integration_v2.py
• code_review_graph/prompts.py

Execution Flow Tracing is a specialized analysis system within the code-review-graph project that identifies and maps call chains starting from specific entry points (such as HTTP handlers, CLI commands, or tests). By tracing these paths through the codebase knowledge graph, the system provides developers with an understanding of critical execution paths and the impact of changes on user-facing functionality.

This feature allows for risk-scored analysis by identifying "critical" flows—those that span multiple files, involve significant depth, or touch security-sensitive modules. It integrates directly with MCP tools to surface affected execution paths during code reviews and debugging sessions.

Sources: code_review_graph/flows.py, code_review_graph/main.py:273-285

Core Architecture and Components

The flow tracing system operates in three distinct phases: Entry Point Detection, Path Tracing (BFS), and Criticality Scoring.

Detection and Tracing Logic

The system automatically identifies "Entry Points"—functions that serve as the start of an execution chain. These include functions with specific decorators (e.g., @route, @task, @pytest.fixture), specific naming patterns (e.g., main, handle_request), or nodes that have no incoming CALLS edges from other functions. Once entry points are established, a Breadth-First Search (BFS) algorithm traverses the graph's CALLS edges to build a comprehensive map of all reachable nodes within that flow.

Sources: code_review_graph/flows.py, tests/test_flows.py:44-93

Data Models and Storage

Flows are stored in a dedicated SQLite schema. Each flow is represented by its metadata and a sequence of memberships that link nodes to the specific flow.

Field	Type	Description
name	String	Usually the name of the entry point function.
entry_point_id	Integer	Foreign key to the nodes table for the starting node.
criticality	Float	A 0.0 to 1.0 score representing the flow's importance.
node_count	Integer	Total number of unique nodes in the call chain.
file_count	Integer	Number of distinct source files touched by the flow.
depth	Integer	The maximum hop distance from the entry point.

Sources: code_review_graph/flows.py, tests/test_flows.py:246-260

Criticality Scoring

Not all execution paths are equal. The system calculates a Criticality Score to prioritize flows that are architecturally significant or high-risk.

The scoring algorithm considers several factors:

1. File Spread: Flows that cross multiple file boundaries are considered more complex and significant.
2. Security Sensitivity: If a flow touches nodes in files with names like auth, login, security, or permission, its score is boosted.
3. Depth and Volume: Deeper call chains with more nodes contribute to a higher architectural weight.

Sources: code_review_graph/flows.py, tests/test_flows.py:293-333

Integration with MCP Tools

The Execution Flow Tracing system is exposed via several Model Context Protocol (MCP) tools, enabling AI assistants to perform complex architectural queries.

Key Tools and Functions

• list_flows_tool: Lists all detected flows, allowing sorting by criticality or depth.
• get_flow_tool: Retrieves the full sequence of steps (function names, file paths, line numbers) for a specific flow.
• get_affected_flows_tool: Crucial for code review; it identifies which flows pass through files that have been modified in a git diff.

Sources: code_review_graph/main.py:273-330, code_review_graph/tools/review.py:231-270

Usage in Code Review

When reviewing a PR, the system identifies "Affected Flows." If a developer modifies a low-level utility, the system traces upward to show that an API Handler in routes.py is now at risk.

# Example logic for finding affected flows
def get_affected_flows_func(changed_files=None, repo_root=None):
    store, root = _get_store(repo_root)
    # Convert relative paths from git to absolute paths for graph
    abs_files = [str(root / f) for f in changed_files]
    # Query database for flows intersecting these files
    result = _get_affected_flows(store, abs_files)
    return result

Sources: code_review_graph/tools/review.py:255-270, tests/test_flows.py:382-411

Incremental Updates

The flow tracing system supports incremental updates to maintain performance on large codebases. When files are changed, only the flows that previously touched those files are cleared and re-traced.

• Atomic Operations: Deletions and re-traces are wrapped in SQLite transactions to prevent orphaned flow memberships if the process is interrupted.
• New Entry Discovery: The incremental process also scans changed files for any newly introduced entry points.

Sources: code_review_graph/flows.py, tests/test_flows.py:432-484

Summary

Execution Flow Tracing transforms a static code graph into a dynamic map of runtime possibilities. By identifying entry points and tracing call chains, code-review-graph provides a "user-centric" view of the codebase. This allows AI tools to move beyond simple file-level diffs and instead report on the potential disruption to critical business logic and system-wide execution paths.

Sources: code_review_graph/prompts.py:59-75, tests/test_integration_v2.py:125-145