pr-health-agent 2.0.9
Comprehensive GitHub PR health scoring with AI-powered analysis
Requires Python: >=3.8
Keywords: github pull-request code-review quality-analysis ai automation

# PR Health Score Agent

A comprehensive CLI tool that analyzes GitHub Pull Requests and provides AI-powered health scores with automated recommendations.

## 🌟 Key Features

- **Comprehensive 13-Category Scoring** (100 points total)
  - PR Review Criteria (70 pts): Size, Tests, Commits, Reviews, Security, Code Quality, Dependencies, Documentation
  - AI-Powered Impact Analysis (30 pts): Complexity, Impact Scope, Performance

- **AI-Powered Analysis** with multiple providers:
  - Google Gemini (Recommended - Free tier available)
  - AWS Bedrock (Claude 3.5)
  - OpenAI GPT-4

- **Automated Actions**:
  - 💬 Post detailed health reports as PR comments
  - 🏷️ Auto-label PRs (health-check:pass/fail)
  - ✅ Create status checks for merge blocking
  - 📈 Provide actionable recommendations

- **Security Scanning**:
  - Uses GitHub Dependabot API (free, no GHAS license required)
  - Detects Critical, High, Moderate, and Low severity vulnerabilities
  - Supports 9+ ecosystems (npm, pip, maven, gradle, etc.)

## 📦 Installation

### From PyPI (Recommended)

```bash
# Basic installation
pip install pr-health-agent

# With AWS Bedrock support
pip install pr-health-agent[bedrock]

# With all optional dependencies
pip install pr-health-agent[all]
```

## 🚀 Quick Start

### 1. Check Installation

```bash
pr-health --version
```

### 2. Set Environment Variables

**Required:**
```bash
export GITHUB_TOKEN="your_github_personal_access_token"
```

**Optional (for AI analysis - choose one):**
```bash
export GEMINI_API_KEY="your_gemini_api_key"        # Google Gemini
export BEDROCK_API_KEY="your_bedrock_api_key"      # AWS Bedrock
export OPENAI_API_KEY="your_openai_api_key"        # OpenAI
```

### 3. Run Analysis

**Interactive Menu (Easiest):**
```bash
pr-health-app
```

**Setup Wizard:**
```bash
pr-health-interactive
```

**Direct Analysis:**
```bash
# Basic analysis
pr-health owner/repo 123

# With AI analysis
pr-health owner/repo 123 --ai-analysis

# Full analysis with comments and labels
pr-health owner/repo 123 --ai-analysis --post-comment --add-labels
```

## 📊 Scoring System

| Category | Points | What It Measures |
|----------|--------|------------------|
| **PR Review** | **70** | |
| Size | 5 | Lines, files, commits |
| Test Quality | 10 | Coverage % and test files |
| Commit Quality | 5 | Conventional commits, messages |
| Review Quality | 5 | Reviewers, approvals, comments |
| Security | 10 | Vulnerability scanning |
| Code Quality | 8 | Complexity, duplication |
| Code Style | 3 | Linting, formatting |
| Dependencies | 4 | Vulnerability detection |
| CHANGELOG | 5 | Updates and versioning |
| CODEOWNERS | 3 | File coverage |
| Breaking Changes | 5 | Detection and documentation |
| Documentation | 7 | PR description quality |
| **AI Impact** | **30** | |
| Complexity | 10 | Architectural complexity |
| Impact Scope | 10 | Business and technical impact |
| Performance | 10 | Resource usage implications |

### Score Categories

| Score | Category | Merge Status |
|-------|----------|--------------|
| 90-100 | 🌟 Excellent | ✅ Recommended |
| 80-89 | ✅ Good | ✅ Recommended |
| 70-79 | ⚠️ Needs Improvement | ✅ Allowed |
| 60-69 | 🔴 Poor | 🚫 Blocked |
| 0-59 | 🚫 Critical Issues | 🚫 Blocked |

## 🔧 Configuration

Create `config.yaml` to customize (optional - defaults provided):

```yaml
thresholds:
  min_passing_score: 70
  excellent_score: 90

weights:
  size: 10
  commit_quality: 10
  test_quality: 20
  review_quality: 20
  complexity: 15
  security: 15
  code_quality: 5
  documentation: 5
```

## 🤖 GitHub Actions Integration

Add to `.github/workflows/pr-health.yml`:

```yaml
name: PR Health Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - name: Install PR Health Agent
        run: pip install pr-health-agent

      - name: Run Health Check
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          pr-health ${{ github.repository }} ${{ github.event.pull_request.number }} \
            --ai-analysis \
            --post-comment \
            --add-labels \
            --add-status
```

## 📋 Prerequisites

- **Python 3.8+**
- **GitHub Personal Access Token** with scopes:
  - `repo` (Full repository access)
  - `security_events` (For vulnerability scanning)
- **AI Provider API Key** (Optional):
  - [Google Gemini](https://makersuite.google.com/app/apikey) - Free tier available
  - [AWS Bedrock](https://aws.amazon.com/bedrock/) - Pay as you go
  - [OpenAI](https://platform.openai.com/api-keys) - Pay as you go

## 📚 Documentation

- [Installation Guide](INSTALLATION.md) - Detailed installation instructions
- [AI Providers Setup](AI_PROVIDERS.md) - Configure AI analysis
- [Quick Reference](QUICK_REFERENCE.md) - Command cheat sheet
- [Advanced Features](ADVANCED.md) - Customization and advanced usage

## 💡 Usage Examples

**Analyze with custom threshold:**
```bash
pr-health owner/repo 123 --threshold 80
```

**JSON output:**
```bash
pr-health owner/repo 123 --output json
```

**Custom config:**
```bash
pr-health owner/repo 123 --config custom.yaml
```

**Verbose mode:**
```bash
pr-health owner/repo 123 --ai-analysis --verbose
```

## 🆘 Troubleshooting

**"GITHUB_TOKEN not found"**
```bash
export GITHUB_TOKEN="your_token_here"
```

**"Permission denied"**
- Ensure token has `repo` and `security_events` scopes

**"AI analysis failed"**
```bash
export GEMINI_API_KEY="your_gemini_key"
```

**Check version:**
```bash
pr-health --version
```

## 🔗 Commands

| Command | Purpose |
|---------|---------|
| `pr-health` | Analyze specific PR |
| `pr-health-app` | Interactive menu |
| `pr-health-interactive` | Setup wizard |

All commands support `--version` and `--help` flags.

## 📄 License

MIT License

## 🤝 Contributing

Contributions welcome! Please check the contributing guidelines.

---

**Latest Version**: 2.0.5

**Quick Install**: `pip install pr-health-agent`

**Quick Start**: `pr-health-app`