detect_changes_tool in code-review-graph: Automated Risk Analysis for Code Changes

TLDR: The detect_changes_tool is an asynchronous MCP utility in the code-review-graph framework that parses GitHub pull request diffs, maps changes to knowledge graph nodes, and generates risk-scored impact reports to prioritize code review efforts.

The detect_changes_tool serves as the primary analysis engine in the tirth8205/code-review-graph repository, transforming raw diff text into actionable intelligence. According to the source code in code_review_graph/main.py, this asynchronous tool bridges the gap between version control changes and the repository's internal knowledge graph. By quantifying the blast radius of every modification, it enables reviewers to focus on high-risk changes while filtering out noise.

What Is detect_changes_tool?

detect_changes_tool is a built-in Model Context Protocol (MCP) tool designed to convert textual diffs into structured risk assessments. Unlike simple diff viewers, this tool leverages the repository's knowledge graph—which stores import relationships, call graphs, and test-coverage data—to understand the semantic impact of code changes.

The tool operates asynchronously to handle potentially large diffs without blocking the event loop. As implemented in code_review_graph/main.py, the function uses asyncio.to_thread to offload heavy parsing work to a separate thread, a design change introduced specifically to improve stability on Windows and other platforms (see CHANGELOG.md lines 443-449).

How detect_changes_tool Analyzes Code Changes

The analysis pipeline follows a four-step process that transforms raw diff text into a prioritized review queue.

Step 1: Parse and Map Changes to Graph Nodes

The tool first ingests the textual diff of changed files—covering added, removed, or modified lines. It then utilizes the graph and graph_diff modules (particularly logic defined in code_review_graph/graph_diff.py) to identify specific functions, classes, and modules affected by the diff. This mapping translates line-level changes into semantic entities within the knowledge graph.

Step 2: Compute Risk Scores

For each changed node, the tool evaluates multiple heuristics to produce a numeric risk score:

• Change magnitude: Lines added and removed
• API surface exposure: Whether the node is public or internal
• Coverage gaps: Presence of missing transitive test coverage
• Historical data: Previous bug density or churn rates (when available)

Scores range from low (minimal impact) to high (standard review required), allowing the system to categorize changes automatically.

Step 3: Expand the Blast Radius

Based on the calculated risk scores, the tool traverses the knowledge graph to identify downstream dependencies and affected test suites. This expansion leverages complementary tools such as get_impact_radius_tool and query_graph_tool to collect the full set of functions that could break due to the proposed changes, even if those functions weren't directly modified.

Step 4: Generate Structured Reports

The final output organizes findings into a machine-readable format optimized for LLM consumption or CI integration. The report includes:

• Changed entities with their risk classifications
• Transitive impact frontiers (downstream affected code)
• Lists of missing test coverage
• Recommendations for review focus

Implementation and Performance

The detect_changes_tool implementation prioritizes non-blocking execution. The core logic runs via asyncio.to_thread, preventing the async event loop from stalling during intensive diff parsing operations. This architectural decision, documented in CHANGELOG.md lines 443-449, ensures the tool remains responsive when analyzing large pull requests or complex refactoring operations.

Usage Examples

Programmatic Invocation

Invoke the tool programmatically using the async API with two primary detail levels:

# Low-risk changes - concise summary

result = await detect_changes_tool(detail_level="minimal")
print(result.summary)

# Medium/high-risk changes - comprehensive analysis

result = await detect_changes_tool(detail_level="standard")
for item in result.items:
    print(f"{item.function}: risk={item.risk_score}")
    print(f"  Affected downstream: {item.transitive_frontier}")
    if item.missing_tests:
        print("  Missing tests:", item.missing_tests)

These detail levels correspond to the recommendations found in docs/LLM-OPTIMIZED-REFERENCE.md lines 17-23, where minimal detail provides quick summaries for trivial changes while standard detail delivers full impact analysis for complex modifications.

Command Line Activation

When running the code-review-graph server, enable the tool via the allow-list flag:

code-review-graph serve --tools query_graph_tool,detect_changes_tool

This CLI configuration option is documented in docs/COMMANDS.md lines 214-218, demonstrating how to selectively expose tools to the MCP server environment.

Summary

• detect_changes_tool is an async MCP tool in code_review_graph/main.py that bridges Git diffs and the repository knowledge graph.
• It maps changes to semantic nodes using code_review_graph/graph_diff.py, then calculates risk scores based on change magnitude, API exposure, and test coverage.
• The tool expands blast radius by traversing the graph to find downstream impacts via get_impact_radius_tool and query_graph_tool.
• It offers two detail levels (minimal and standard) to optimize reporting for different risk scenarios, as specified in docs/LLM-OPTIMIZED-REFERENCE.md lines 17-23.
• The implementation uses asyncio threading (asyncio.to_thread) to prevent event loop blocking during diff parsing, documented in CHANGELOG.md lines 443-449.

Frequently Asked Questions

What output format does detect_changes_tool produce?

The tool generates a structured report object containing changed entities, numeric risk scores, transitive impact frontiers, and lists of missing tests. This output is designed for direct consumption by LLMs or integration into CI/CD pipelines for automated gating decisions.

How does detect_changes_tool handle large diffs without blocking?

According to CHANGELOG.md lines 443-449, the tool offloads heavy diff-parsing operations to a separate thread using asyncio.to_thread. This async architecture prevents the main event loop from freezing when processing extensive refactoring operations or bulk file changes.

Can I use detect_changes_tool without enabling other graph tools?

While the tool can be invoked independently, its full capability requires the knowledge graph infrastructure. However, you can control exposure via the CLI allow-list. As shown in docs/COMMANDS.md lines 214-218, you can enable only detect_changes_tool alongside essential utilities like query_graph_tool using the --tools flag.

What is the difference between minimal and standard detail levels?

The minimal detail level generates concise summaries suitable for low-risk changes, while standard detail provides comprehensive analysis including full transitive frontiers and missing test identification. These levels are optimized for different AI consumption patterns as documented in docs/LLM-OPTIMIZED-REFERENCE.md lines 17-23.

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