# CLAUDE.md

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

## Development Commands

### Testing and Linting
```bash
# Run all tests and linting (primary development command)
make ci_unit_lint

# Individual commands
uv run ruff check 
uv run ruff format
uv run pytest -v tests/unit/

# Run a single test
uv run pytest -v tests/unit/test_tf_infra.py::test_deemphasize_text_basic_string

# Setup test environment
make env_test  # or uv sync --group test
```

### Local Development
```bash
# Build and run locally (requires env vars)
make docker_run

# Just build the Docker image
make docker_build
```

### Required Environment Variables for Local Testing
- `GITHUB_TOKEN`: GitHub token with PR read permissions
- `GITHUB_PR_NUMBER`: PR number from URL
- `GITHUB_REPO_NAME`: Repository name including organization (e.g., "theorchard/terraform-infra", "theorchard/database") - defaults to "theorchard/terraform-infra"
- `GITHUB_REPO_OWNER`: Repository owner - defaults to "theorchard"
- `PROJECT_TYPE`: Fallback project type when repo not in REPO_CONFIGS ("python", "terraform", "database", "generic", "javascript", "php")
- `Environment=dev` (prints to terminal instead of posting to GitHub)
- `TIMEOUT`: Analysis timeout in seconds - defaults to 600
- AWS credentials via `aswume` role assumption in shared/dev/prod accounts

## Architecture Overview

This is a modular, repo-agnostic PR review automation framework that uses AI to analyze code changes. The framework supports multiple repository types with repo-specific implementations.

### Framework Architecture

**Base Framework** (`pr_review/`):
- `base.py`: Abstract base classes for extensible PR analysis
- `github_client.py`: Generic GitHub API client with configurable comment filters
- `llm_client.py`: AWS Bedrock client for AI analysis
- `config.py`: Repository configuration and factory pattern

**Repository-Specific Implementations**:
- `terraform_infra.py`: Terraform infrastructure analysis with Atlantis integration

### Workflow

1. **Factory Creation**: `PRAnalyzerFactory` creates repo-specific analyzer based on `GITHUB_REPO_NAME`
2. **PR Waiting**: Repo-specific waiter (e.g., `AtlantisPRWaiter`) polls for analysis prerequisites
3. **Prompt Building**: Repo-specific prompt builder creates tailored review prompts
4. **AI Analysis**: Generic LLM client sends prompts to AWS Bedrock
5. **Post-Processing**: Repo-specific analyzer applies formatting (e.g., header de-emphasis)
6. **Comment Posting**: Generic GitHub client posts results

### Supported Repositories

**terraform-infra**:
- **Waiter**: `AtlantisPRWaiter` - Polls for Terraform plan comments with 10-minute timeout
- **Prompt**: `TerraformInfraPromptBuilder` - Comprehensive Terraform-specific review guidelines
- **Filters**: Extracts Atlantis plan comments posted after last commit
- **Post-processing**: De-emphasizes headers for GitHub markdown compatibility

**pull-request-review-tools**:
- **Waiter**: `StandardPRWaiter` - Proceeds immediately (no special waiting required)
- **Prompt**: `PythonGeneralPromptBuilder` - Python/general code review focusing on best practices, security, testing
- **Filters**: No special comment filtering
- **Post-processing**: De-emphasizes headers for GitHub markdown compatibility

**database**:
- **Waiter**: `DatabasePRWaiter` - Proceeds immediately (no special waiting required)
- **Prompt**: `DatabasePromptBuilder` - Database migration review for Liquibase/Liquigraph focusing on safety, performance, schema design
- **Filters**: No special comment filtering
- **Post-processing**: De-emphasizes headers for GitHub markdown compatibility

### Adding New Repositories

**Option 1: Use Project Type (Recommended for standard projects)**
1. Set `PROJECT_TYPE` environment variable to one of: "python", "terraform", "database", "generic", "javascript", "php"
2. No code changes required - uses default configurations

**Option 2: Custom Repository Configuration**
1. Create repo-specific classes extending base classes in `pr_review/`
2. Add configuration to `REPO_CONFIGS` in `config.py`
3. Set `GITHUB_REPO_NAME` environment variable

The framework first checks `REPO_CONFIGS` for repo-specific configurations, then falls back to `PROJECT_TYPE` configurations for standard project types.

### Configuration Details
- Python 3.13+ required
- Uses `uv` for dependency management
- AWS Bedrock region: `us-east-1`
- Default model: `claude-sonnet-4-20250514-v1:0`