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

> Discover the detect_changes_tool in code-review-graph. This utility automates risk analysis of code changes, mapping diffs to a knowledge graph and generating impact reports to streamline code reviews.

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

---

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

```python

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

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

```

This CLI configuration option is documented in [`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/docs/LLM-OPTIMIZED-REFERENCE.md) lines 17-23.