feat: Add @codebot explain-diff command for plain-language PR explanations
All checks were successful
Enterprise AI Code Review / ai-review (pull_request) Successful in 39s

Implements code diff explainer that translates technical changes into
plain language for non-technical stakeholders (PMs, designers, new team members).

Features:
- Plain-language explanations without jargon
- File-by-file breakdown with 'what' and 'why' context
- Architecture impact analysis
- Breaking change detection
- Perfect for onboarding and cross-functional reviews

Implementation:
- Added explain_diff.md prompt template with plain-language guidelines
- Implemented _handle_explain_diff_command() in PRAgent
- Added _format_diff_explanation() for readable markdown
- Updated PRAgent.can_handle() to route explain-diff commands
- Added 'explain-diff' to config.yml commands list

Workflow Safety (prevents duplicate runs):
- Added '@codebot explain-diff' to ai-comment-reply.yml conditions
- Excluded from ai-chat.yml to prevent duplication
- Only triggers on PR comments (not issues)
- Manual command only (no automatic triggering)

Testing:
- 9 comprehensive tests in TestDiffExplanation class
- Tests command detection, formatting, plain-language output
- Verifies prompt formatting and empty section handling

Documentation:
- Updated README.md with explain-diff command and examples
- Added detailed implementation guide in CLAUDE.md
- Included plain-language rules and use cases

Related: Milestone 2 high-priority feature - code diff explainer
This commit is contained in:
2025-12-29 12:44:54 +00:00
parent 1d468e360e
commit 37f3eb45d0
8 changed files with 680 additions and 3 deletions

View File

@@ -12,7 +12,7 @@ Enterprise-grade AI code review system for **Gitea** with automated PR review, i
| **PR Summaries** | Auto-generate comprehensive PR summaries with change analysis and impact assessment |
| **Issue Triage** | On-demand classification, labeling, priority assignment via `@codebot triage` |
| **Chat** | Interactive AI chat with codebase search and web search tools |
| **@codebot Commands** | `@codebot summarize`, `changelog`, `explain`, `suggest`, `triage`, `review-again` in comments |
| **@codebot Commands** | `@codebot summarize`, `changelog`, `explain-diff`, `explain`, `suggest`, `triage`, `review-again` in comments |
| **Codebase Analysis** | Health scores, tech debt tracking, weekly reports |
| **Security Scanner** | 17 OWASP-aligned rules for vulnerability detection |
| **Enterprise Ready** | Audit logging, metrics, Prometheus export |
@@ -192,6 +192,7 @@ In any PR comment:
|---------|-------------|
| `@codebot summarize` | Generate a comprehensive PR summary with changes, files affected, and impact |
| `@codebot changelog` | Generate Keep a Changelog format entries ready for CHANGELOG.md |
| `@codebot explain-diff` | Explain code changes in plain language for non-technical stakeholders |
| `@codebot review-again` | Re-run AI code review on current PR state without new commits |
#### PR Summary (`@codebot summarize`)
@@ -281,6 +282,65 @@ Adds new feature without affecting existing functionality
- **Main components:** auth/, api/users/, database/
```
#### Diff Explainer (`@codebot explain-diff`)
**Features:**
- 📖 Translates technical changes into plain language
- 🎯 Perfect for non-technical stakeholders (PMs, designers)
- 🔍 File-by-file breakdown with "what" and "why"
- 🏗️ Architecture impact analysis
- ⚠️ Breaking change detection
- 📊 Technical summary for reference
**When to use:**
- New team members reviewing complex PRs
- Non-technical reviewers need to understand changes
- Documenting architectural decisions
- Learning from others' code
**Example output:**
```markdown
## 📖 Code Changes Explained (PR #123)
### 🎯 Overview
This PR adds user authentication using secure tokens that expire after 24 hours, enabling users to log in securely without storing passwords in the application.
### 🔍 What Changed
#### `auth/jwt.py` (new)
**What changed:** Creates secure tokens for logged-in users
**Why it matters:** Enables the app to remember who you are without constantly asking for your password
#### 📝 `api/users.py` (modified)
**What changed:** Added a login page where users can sign in
**Why it matters:** Users can now create accounts and access their personal data
---
### 🏗️ Architecture Impact
Introduces a security layer across the entire application, ensuring only authenticated users can access protected features.
**New dependencies:**
- PyJWT (for creating secure tokens)
- bcrypt (for password encryption)
**Affected components:**
- API (all endpoints now check authentication)
- Database (added user credentials storage)
---
### ⚠️ Breaking Changes
- **All API endpoints now require authentication - existing scripts need to be updated**
---
### 📊 Technical Summary
- **Files changed:** 5
- **Lines:** +200 / -10
- **Components:** auth/, api/
```
#### Review Again (`@codebot review-again`)
**Features:**