# diff-explainer

AI-powered git diff analysis: human-readable explanations, risk flags, and review checklists.

Works as a **CLI**, **Python library**, and **MCP server tool**.

## Setup

```bash
pip install -r requirements.txt

# Optional: set for LLM-powered summaries
export OPENAI_API_KEY="sk-..."
```

Risk detection works without an API key. Only summaries and review checklists require the LLM.

## Usage

### CLI

```bash
# Pipe from git diff
git diff | python cli.py

# Read from file
python cli.py --file examples/sample.diff

# Auto-run git diff in current repo
python cli.py --git

# JSON output
python cli.py --file examples/sample.diff --format json
```

### Python Library

```python
from explainer import explain_diff

with open("changes.diff") as f:
    diff_text = f.read()

result = explain_diff(diff_text)
print(result.summary)
print(result.risk_flags)
print(result.files_changed)
```

### MCP Server (opencode integration)

Add to your `opencode.json`:

```json
{
  "mcpServers": {
    "diff-explainer": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/diff-explainer"
    }
  }
}
```

Available tools:
- `explain_diff_tool(diff_text)` — Explain any diff text
- `explain_staged()` — Explain currently staged git changes

Run standalone: `python server.py`

## Features

- **Hybrid analysis**: Regex risk detection (offline) + LLM summaries (optional)
- **7 risk patterns**: Removed error handling, changed timeouts, auth modifications, missing env defaults, large changes, tech debt markers, hardcoded secrets
- **Graceful degradation**: Works without API key — risk flags and file stats always available
- **Multiple interfaces**: CLI, library import, MCP server

## Output Example

```
# Diff Explanation

## Summary
This change reduces retry resilience in the auth service and introduces a hardcoded API key.

**Category:** config_change

## Files Changed
- `src/auth.py` — +3/-7 lines
- `src/config.py` — +5/-1 lines

## Risk Flags
- 🔴 **HIGH**: Removed error handling code
- 🔴 **HIGH**: Modified auth/permission checks
- 🔴 **HIGH**: Possible hardcoded secret
- 🟡 **MEDIUM**: Changed retry/timeout values
- 🟢 **LOW**: Added TODO/FIXME/HACK comment

## Review Checklist
- [ ] Is removing the try/except intentional? What handles AuthError now?
- [ ] Why were retries reduced from 3 to 1?
- [ ] The hardcoded API key should be moved to a secrets manager.
```