# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

OpenRabbit is an enterprise-grade AI code review system for Gitea (and GitHub). It provides automated PR review, issue triage, interactive chat, and codebase analysis through a collection of specialized AI agents.

## Commands

### Development

```bash
# Run tests
pytest tests/ -v

# Run specific test file
pytest tests/test_ai_review.py -v

# Install dependencies
pip install -r tools/ai-review/requirements.txt

# Run a PR review locally
cd tools/ai-review
python main.py pr owner/repo 123

# Run issue triage
python main.py issue owner/repo 456

# Test chat functionality
python main.py chat owner/repo "How does authentication work?"

# Run with custom config
python main.py pr owner/repo 123 --config /path/to/config.yml
```

### Testing Workflows

```bash
# Validate workflow YAML syntax
python -c "import yaml; yaml.safe_load(open('.github/workflows/ai-review.yml'))"

# Test security scanner
python -c "from security.security_scanner import SecurityScanner; s = SecurityScanner(); print(list(s.scan_content('password = \"secret123\"', 'test.py')))"

# Test webhook sanitization
cd tools/ai-review
python -c "from utils.webhook_sanitizer import sanitize_webhook_data; print(sanitize_webhook_data({'user': {'email': 'test@example.com'}}))"

# Test safe dispatch
python utils/safe_dispatch.py issue_comment owner/repo '{"action": "created", "issue": {"number": 1}, "comment": {"body": "test"}}'
```

## Architecture

### Agent System

The codebase uses an **agent-based architecture** where specialized agents handle different types of events:

1. **BaseAgent** (`agents/base_agent.py`) - Abstract base class providing:
   - Gitea API client integration
   - LLM client integration with rate limiting
   - Common comment management (upsert, find AI comments)
   - Prompt loading from `prompts/` directory
   - Standard execution flow with error handling

2. **Specialized Agents** - Each agent implements:
   - `can_handle(event_type, event_data)` - Determines if agent should process the event
   - `execute(context)` - Main execution logic
   - Returns `AgentResult` with success status, message, data, and actions taken

   - **PRAgent** - Reviews pull requests with inline comments and security scanning
   - **IssueAgent** - Triages issues and responds to @ai-bot commands
   - **CodebaseAgent** - Analyzes entire codebase health and tech debt
   - **ChatAgent** - Interactive assistant with tool calling (search_codebase, read_file, search_web)

3. **Dispatcher** (`dispatcher.py`) - Routes events to appropriate agents:
   - Registers agents at startup
   - Determines which agents can handle each event
   - Executes agents (supports concurrent execution)
   - Returns aggregated results

### Multi-Provider LLM Client

The `LLMClient` (`clients/llm_client.py`) provides a unified interface for multiple LLM providers:

- **OpenAI** - Primary provider (gpt-4.1-mini default)
- **OpenRouter** - Multi-provider access (claude-3.5-sonnet)
- **Ollama** - Self-hosted models (codellama:13b)

Key features:
- Tool/function calling support via `call_with_tools(messages, tools)`
- JSON response parsing with fallback extraction
- Provider-specific configuration via `config.yml`

### Platform Abstraction

The `GiteaClient` (`clients/gitea_client.py`) provides a unified REST API client for **Gitea** (also compatible with GitHub API):

- Issue operations (create, update, list, get, comments, labels)
- PR operations (get, diff, files, reviews)
- Repository operations (get repo, file contents, branches)

Environment variables:
- `AI_REVIEW_API_URL` - API base URL (e.g., `https://api.github.com` or `https://gitea.example.com/api/v1`)
- `AI_REVIEW_TOKEN` - Authentication token

### Security Scanner

The `SecurityScanner` (`security/security_scanner.py`) uses **pattern-based detection** with 17 built-in rules covering:

- OWASP Top 10 categories (A01-A10)
- Common vulnerabilities (SQL injection, XSS, hardcoded secrets, weak crypto)
- Returns `SecurityFinding` objects with severity (HIGH/MEDIUM/LOW), CWE references, and recommendations

Can scan:
- File content via `scan_content(content, filename)`
- Git diffs via `scan_diff(diff)` - only scans added lines

### Chat Agent Tool Calling

The `ChatAgent` implements an **iterative tool calling loop**:

1. Send user message + system prompt to LLM with available tools
2. If LLM returns tool calls, execute each tool and append results to conversation
3. Repeat until LLM returns a final response (max 5 iterations)

Available tools:
- `search_codebase` - Searches repository files and code patterns
- `read_file` - Reads specific file contents (truncated at 8KB)
- `search_web` - Queries SearXNG instance (requires `SEARXNG_URL`)

## Configuration

### Primary Config File: `tools/ai-review/config.yml`

Critical settings:

```yaml
provider: openai  # openai | openrouter | ollama

model:
  openai: gpt-4.1-mini
  openrouter: anthropic/claude-3.5-sonnet
  ollama: codellama:13b

interaction:
  mention_prefix: "@codebot"  # Bot trigger name - update workflows too!
  commands:
    - explain      # Explain what the issue is about
    - suggest      # Suggest solutions or next steps
    - security     # Security analysis
    - summarize    # Summarize the issue
    - triage       # Full triage with labeling
    - review-again # Re-run PR review (PR comments only)
  
review:
  fail_on_severity: HIGH  # Fail CI if HIGH severity issues found
  max_diff_lines: 800     # Skip review if diff too large
  
agents:
  chat:
    max_iterations: 5  # Tool calling loop limit
```

**Important**: When changing `mention_prefix`, also update all workflow files in `.gitea/workflows/`:
- `ai-comment-reply.yml`
- `ai-chat.yml`
- `ai-issue-triage.yml`

Look for: `if: contains(github.event.comment.body, '@codebot')` and update to your new bot name.

Current bot name: `@codebot`

### Environment Variables

Required:
- `AI_REVIEW_API_URL` - Platform API URL
- `AI_REVIEW_TOKEN` - Bot authentication token
- `OPENAI_API_KEY` - OpenAI API key (or provider-specific key)

Optional:
- `SEARXNG_URL` - SearXNG instance for web search
- `OPENROUTER_API_KEY` - OpenRouter API key
- `OLLAMA_HOST` - Ollama server URL

## Workflow Architecture

Workflows are located in `.gitea/workflows/` and are **mutually exclusive** to prevent duplicate runs:

- **enterprise-ai-review.yml** - Triggered on PR open/sync
- **ai-issue-triage.yml** - Triggered ONLY on `@codebot triage` in comments
- **ai-comment-reply.yml** - Triggered on specific commands: `help`, `explain`, `suggest`, `security`, `summarize`, `review-again`, `setup-labels`
- **ai-chat.yml** - Triggered on `@codebot` mentions that are NOT specific commands (free-form questions)
- **ai-codebase-review.yml** - Scheduled weekly analysis

**Workflow Routing Logic:**
1. If comment contains `@codebot triage` → ai-issue-triage.yml only
2. If comment contains specific command (e.g., `@codebot help`) → ai-comment-reply.yml only
3. If comment contains `@codebot <question>` (no command) → ai-chat.yml only

This prevents the issue where all three workflows would trigger on every `@codebot` mention, causing massive duplication.

**Note**: Issue triage is now **opt-in** via `@codebot triage` command, not automatic on issue creation.

Key workflow pattern:
1. Checkout repository
2. Setup Python 3.11
3. Install dependencies (`pip install requests pyyaml`)
4. Set environment variables
5. Run `python main.py <command> <args>`

## Prompt Templates

Prompts are stored in `tools/ai-review/prompts/` as Markdown files:

- `base.md` - Base instructions for all reviews
- `pr_summary.md` - PR summary generation template
- `issue_triage.md` - Issue classification template
- `issue_response.md` - Issue response template

**Important**: JSON examples in prompts must use **double curly braces** (`{{` and `}}`) to escape Python's `.format()` method. This is tested in `tests/test_ai_review.py::TestPromptFormatting`.

## Code Patterns

### Creating a New Agent

```python
from agents.base_agent import BaseAgent, AgentContext, AgentResult

class MyAgent(BaseAgent):
    def can_handle(self, event_type: str, event_data: dict) -> bool:
        # Check if agent is enabled in config
        if not self.config.get("agents", {}).get("my_agent", {}).get("enabled", True):
            return False
        return event_type == "my_event_type"
    
    def execute(self, context: AgentContext) -> AgentResult:
        # Load prompt template
        prompt = self.load_prompt("my_prompt")
        formatted = prompt.format(data=context.event_data.get("field"))
        
        # Call LLM with rate limiting
        response = self.call_llm(formatted)
        
        # Post comment to issue/PR
        self.upsert_comment(
            context.owner,
            context.repo,
            issue_index,
            response.content
        )
        
        return AgentResult(
            success=True,
            message="Agent completed",
            actions_taken=["Posted comment"]
        )
```

### Calling LLM with Tools

```python
messages = [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Search for authentication code"}
]

tools = [{
    "type": "function",
    "function": {
        "name": "search_code",
        "description": "Search codebase",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]
        }
    }
}]

response = self.llm.call_with_tools(messages, tools=tools)

if response.tool_calls:
    for tc in response.tool_calls:
        result = execute_tool(tc.name, tc.arguments)
        messages.append({
            "role": "tool",
            "tool_call_id": tc.id,
            "content": result
        })
```

### Adding Security Rules

Edit `tools/ai-review/security/security_scanner.py` or create `security/security_rules.yml`:

```yaml
rules:
  - id: SEC018
    name: Custom Rule Name
    pattern: 'regex_pattern_here'
    severity: HIGH  # HIGH, MEDIUM, LOW
    category: A03:2021 Injection
    cwe: CWE-XXX
    description: What this detects
    recommendation: How to fix it
```

## Security Best Practices

**CRITICAL**: Always follow these security guidelines when modifying workflows or handling webhook data.

### Workflow Security Rules

1. **Never pass full webhook data to environment variables**
   ```yaml
   # ❌ NEVER DO THIS
   env:
     EVENT_DATA: ${{ toJSON(github.event) }}  # Exposes emails, tokens, etc.
   
   # ✅ ALWAYS DO THIS
   run: |
     EVENT_DATA=$(cat <<EOF
     {
       "issue": {"number": ${{ github.event.issue.number }}},
       "comment": {"body": $(echo '${{ github.event.comment.body }}' | jq -Rs .)}
     }
     EOF
     )
     python utils/safe_dispatch.py issue_comment "$REPO" "$EVENT_DATA"
   ```

2. **Always validate repository format**
   ```bash
   # Validate before use
   if ! echo "$REPO" | grep -qE '^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$'; then
       echo "Error: Invalid repository format"
       exit 1
   fi
   ```

3. **Use safe_dispatch.py for webhook processing**
   ```bash
   # Instead of inline Python with os.environ, use:
   python utils/safe_dispatch.py issue_comment owner/repo "$EVENT_JSON"
   ```

### Input Validation

Always use `webhook_sanitizer.py` utilities:

```python
from utils.webhook_sanitizer import (
    sanitize_webhook_data,      # Remove sensitive fields
    validate_repository_format,  # Validate owner/repo format
    extract_minimal_context,     # Extract only necessary fields
)

# Validate repository input
owner, repo = validate_repository_format(repo_string)  # Raises ValueError if invalid

# Sanitize webhook data
sanitized = sanitize_webhook_data(raw_event_data)

# Extract minimal context (reduces attack surface)
minimal = extract_minimal_context(event_type, sanitized)
```

### Pre-commit Security Scanning

Install pre-commit hooks to catch security issues before commit:

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

The hooks will:
- Scan Python files for security vulnerabilities
- Validate workflow files for security anti-patterns
- Detect hardcoded secrets
- Run security scanner on code changes

### Security Resources

- **SECURITY.md** - Complete security guidelines and best practices
- **tools/ai-review/utils/webhook_sanitizer.py** - Input validation utilities
- **tools/ai-review/utils/safe_dispatch.py** - Safe webhook dispatch wrapper
- **.pre-commit-config.yaml** - Pre-commit hook configuration

## Testing

The test suite covers:

1. **Prompt Formatting** (`tests/test_ai_review.py`) - Ensures prompts don't have unescaped `{}` that break `.format()`
2. **Module Imports** - Verifies all modules can be imported
3. **Security Scanner** - Tests pattern detection and false positive rate
4. **Agent Context** - Tests dataclass creation and validation
5. **Security Utilities** (`tests/test_security_utils.py`) - Tests webhook sanitization, validation, and safe dispatch
6. **Safe Dispatch** (`tests/test_safe_dispatch.py`) - Tests secure event dispatching
5. **Metrics** - Tests enterprise metrics collection

Run specific test classes:
```bash
pytest tests/test_ai_review.py::TestPromptFormatting -v
pytest tests/test_ai_review.py::TestSecurityScanner -v
```

## Common Development Tasks

### PR Summary Generation

The PR summary feature automatically generates comprehensive summaries for pull requests.

**Key Features:**
- Auto-generates summary for PRs with empty descriptions
- Can be manually triggered with `@codebot summarize` in PR comments
- Analyzes diff to extract key changes, files affected, and impact
- Categorizes change type (Feature/Bugfix/Refactor/Documentation/Testing)
- Posts as comment or updates PR description (configurable)

**Implementation Details:**

1. **Auto-Summary on PR Open** - `PRAgent.execute()`:
   - Checks if PR body is empty and `auto_summary.enabled` is true
   - Calls `_generate_pr_summary()` automatically
   - Continues with normal PR review after posting summary

2. **Manual Trigger** - `@codebot summarize` in PR comments:
   - `PRAgent.can_handle()` detects `summarize` command in PR comments
   - Routes to `_handle_summarize_command()`
   - Generates and posts summary on demand

3. **Summary Generation** - `_generate_pr_summary()`:
   - Fetches PR diff using `_get_diff()`
   - Loads `prompts/pr_summary.md` template
   - Calls LLM with diff to analyze changes
   - Returns structured JSON with summary data
   - Formats using `_format_pr_summary()`
   - Posts as comment or updates description based on config

4. **Configuration** - `config.yml`:
   ```yaml
   agents:
     pr:
       auto_summary:
         enabled: true  # Auto-generate for empty PRs
         post_as_comment: true  # true = comment, false = update description
   ```

**Summary Structure:**
- Brief 2-3 sentence overview
- Change type categorization (Feature/Bugfix/Refactor/etc)
- Key changes (Added/Modified/Removed)
- Files affected with descriptions
- Impact assessment (scope: small/medium/large)

**Common Use Cases:**
- Developers who forget to write PR descriptions
- Quick understanding of complex changes
- Standardized documentation format
- Pre-review context for reviewers

### Review-Again Command Implementation

The `@codebot review-again` command allows manual re-triggering of PR reviews without new commits.

**Key Features:**
- Detects `@codebot review-again` in PR comments (not issue comments)
- Compares new review with previous review to show resolved/new issues
- Updates existing AI review comment instead of creating duplicates
- Updates PR labels based on new severity assessment

**Implementation Details:**

1. **PRAgent.can_handle()** - Handles `issue_comment` events on PRs containing "review-again"
2. **PRAgent._handle_review_again()** - Main handler that:
   - Fetches previous review comment
   - Re-runs full PR review (security scan + AI analysis)
   - Compares findings using `_compare_reviews()`
   - Generates diff report with `_format_review_update()`
   - Updates comment and labels

3. **Review Comparison** - Uses finding keys (file:line:description) to match issues:
   - **Resolved**: Issues in previous but not in current review
   - **New**: Issues in current but not in previous review
   - **Still Present**: Issues in both reviews
   - **Severity Changed**: Same issue with different severity

4. **Workflow Integration** - `.gitea/workflows/ai-comment-reply.yml`:
   - Detects if comment is on PR or issue
   - Uses `dispatch` command for PRs to route to PRAgent
   - Preserves backward compatibility with issue commands

**Usage:**
```bash
# In a PR comment:
@codebot review-again
```

**Common Use Cases:**
- Re-evaluate after explaining false positives in comments
- Test new `.ai-review.yml` configuration
- Update severity after code clarification
- Faster iteration without empty commits

### Adding a New Command to @codebot

1. Add command to `config.yml` under `interaction.commands`
2. Add handler method in `IssueAgent` (e.g., `_command_yourcommand()`)
3. Update `_handle_command()` to route the command to your handler
4. Update README.md with command documentation
5. Add tests in `tests/test_ai_review.py`

Example commands:
- `@codebot help` - Show all available commands with examples
- `@codebot triage` - Full issue triage with labeling
- `@codebot explain` - Explain the issue
- `@codebot suggest` - Suggest solutions
- `@codebot summarize` - Generate PR summary or issue summary (works on both)
- `@codebot setup-labels` - Automatic label setup (built-in, not in config)
- `@codebot review-again` - Re-run PR review without new commits (PR comments only)

### Changing the Bot Name

1. Edit `config.yml`: `interaction.mention_prefix: "@newname"`
2. Update all Gitea workflow files in `.gitea/workflows/` (search for `contains(github.event.comment.body`)
3. Update README.md and documentation

### Supporting a New LLM Provider

1. Create provider class in `clients/llm_client.py` inheriting from `BaseLLMProvider`
2. Implement `call()` and optionally `call_with_tools()`
3. Register in `LLMClient.PROVIDERS` dict
4. Add model config to `config.yml`
5. Document in README.md

## Repository Labels

### Automatic Label Setup (Recommended)

Use the `@codebot setup-labels` command to automatically configure labels. This command:

**For repositories with existing labels:**
- Detects naming patterns: `Kind/Bug`, `Priority - High`, `type: bug`
- Maps existing labels to OpenRabbit schema using aliases
- Creates only missing labels following detected pattern
- Zero duplicate labels

**For fresh repositories:**
- Creates OpenRabbit's default label set
- Uses standard naming: `type:`, `priority:`, status labels

**Example with existing `Kind/` and `Priority -` labels:**
```
@codebot setup-labels

✅ Found 18 existing labels with pattern: prefix_slash

Proposed Mapping:
| OpenRabbit Expected | Your Existing Label | Status |
|---------------------|---------------------|--------|
| type: bug          | Kind/Bug            | ✅ Map |
| type: feature      | Kind/Feature        | ✅ Map |
| priority: high     | Priority - High     | ✅ Map |
| ai-reviewed        | (missing)           | ⚠️ Create |

✅ Created Kind/Question
✅ Created Status - AI Reviewed

Setup Complete! Auto-labeling will use your existing label schema.
```

### Manual Label Setup

The system expects these labels to exist in repositories for auto-labeling:

- `priority: critical`, `priority: high`, `priority: medium`, `priority: low`
- `type: bug`, `type: feature`, `type: question`, `type: documentation`, `type: security`, `type: testing`
- `ai-approved`, `ai-changes-required`, `ai-reviewed`

Labels are mapped in `config.yml` under the `labels` section.

### Label Configuration Format

Labels support two formats for backwards compatibility:

**New format (with colors and aliases):**
```yaml
labels:
  type:
    bug:
      name: "type: bug"
      color: "d73a4a"  # Red
      description: "Something isn't working"
      aliases: ["Kind/Bug", "bug", "Type: Bug"]  # For auto-detection
```

**Old format (strings only):**
```yaml
labels:
  type:
    bug: "type: bug"  # Still works, uses default blue color
```

### Label Pattern Detection

The `setup-labels` command detects these patterns (configured in `label_patterns`):

1. **prefix_slash**: `Kind/Bug`, `Type/Feature`, `Category/X`
2. **prefix_dash**: `Priority - High`, `Status - Blocked`
3. **colon**: `type: bug`, `priority: high`

When creating missing labels, the bot follows the detected pattern to maintain consistency.