# Grid Review GitHub Action

AI-powered code review using The Grid and Claude.

## Overview

Grid Review brings intelligent code analysis to your CI/CD pipeline. Powered by Claude and The Grid's Recognizer pattern, it automatically reviews pull requests for:

- Security vulnerabilities
- Code quality issues
- Potential bugs
- Test coverage gaps
- Performance concerns

## Quick Start

```yaml
name: Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Grid Review
        uses: JamesWeatherhead/grid/action@main
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```

## Inputs

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `anthropic-api-key` | Anthropic API key for Claude | **Yes** | - |
| `review-type` | Review type: `full`, `security`, `quality` | No | `full` |
| `model-tier` | Model tier: `quality`, `balanced`, `budget` | No | `balanced` |
| `fail-on` | Fail threshold: `error`, `warning`, `none` | No | `error` |
| `output-format` | Output: `json`, `markdown`, `sarif` | No | `markdown` |
| `files` | Files to review (glob pattern) | No | Changed files |

### Review Types

- **full**: Comprehensive review covering security, quality, bugs, tests, and performance
- **security**: Focus exclusively on security vulnerabilities and risks
- **quality**: Focus on code quality, maintainability, and best practices

### Model Tiers

- **quality**: Uses Claude Opus for most thorough analysis (higher cost)
- **balanced**: Uses Claude Sonnet for good balance of quality and cost
- **budget**: Uses Claude Haiku for fast, cost-effective reviews

### Fail Thresholds

- **error**: Fail only if critical errors are found
- **warning**: Fail if warnings or errors are found
- **none**: Never fail the check (informational only)

## Outputs

| Output | Description |
|--------|-------------|
| `status` | Review status: `pass`, `warn`, `fail` |
| `issues-count` | Total number of issues found |
| `security-issues` | Number of security-related issues |
| `report-path` | Path to the generated report file |

## Examples

### Security-Only Review

Focus on security vulnerabilities with stricter thresholds:

```yaml
- name: Security Review
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    review-type: security
    fail-on: warning
```

### SARIF for GitHub Code Scanning

Integrate with GitHub's code scanning feature:

```yaml
- name: Grid Review (SARIF)
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    output-format: sarif
```

Results appear in the Security tab of your repository.

### Budget-Conscious Review

For high-volume repositories:

```yaml
- name: Quick Review
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    model-tier: budget
    fail-on: error
```

### Review Specific Files

```yaml
- name: Review API Changes
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    files: 'src/api/**/*.ts'
```

### Informational Review (Never Fail)

```yaml
- name: Informational Review
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    fail-on: none
```

### Use Review Outputs

```yaml
- name: Grid Review
  id: review
  uses: JamesWeatherhead/grid/action@main
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    output-format: json

- name: Check Results
  run: |
    echo "Review Status: ${{ steps.review.outputs.status }}"
    echo "Issues Found: ${{ steps.review.outputs.issues-count }}"
    echo "Security Issues: ${{ steps.review.outputs.security-issues }}"

    if [ "${{ steps.review.outputs.security-issues }}" -gt "0" ]; then
      echo "::warning::Security issues detected!"
    fi
```

## Setting Up Your Repository

1. **Add your Anthropic API key as a secret:**
   - Go to Settings > Secrets and variables > Actions
   - Click "New repository secret"
   - Name: `ANTHROPIC_API_KEY`
   - Value: Your Anthropic API key

2. **Create the workflow file:**
   - Create `.github/workflows/grid-review.yml`
   - Copy one of the examples above

3. **Open a pull request** to see Grid Review in action!

## How It Works

1. **File Detection**: Identifies changed files in the PR (or uses provided glob pattern)
2. **Analysis**: Claude Code analyzes each file using The Grid's Recognizer pattern
3. **Report Generation**: Creates structured report in your chosen format
4. **PR Comment**: Posts review findings as a PR comment (markdown format)
5. **Status Check**: Passes or fails based on your configured threshold

## Cost Considerations

Each review makes API calls to Claude. Approximate costs per PR:

| Model Tier | Typical Cost | Best For |
|------------|--------------|----------|
| budget (Haiku) | $0.01-0.05 | High-volume repos, quick checks |
| balanced (Sonnet) | $0.05-0.25 | Most repositories |
| quality (Opus) | $0.25-1.00 | Critical code, security audits |

Actual costs depend on PR size and complexity.

## Troubleshooting

### "ANTHROPIC_API_KEY not set"

Ensure you've added the secret to your repository settings.

### Review times out

Large PRs may need more time. Consider:
- Using `files` input to limit scope
- Using `budget` model tier for faster reviews

### No PR comment appears

Check that:
- `output-format` is set to `markdown` (default)
- The workflow has `pull-requests: write` permission

## License

MIT

## Links

- [The Grid Repository](https://github.com/JamesWeatherhead/grid)
- [The Grid on npm](https://www.npmjs.com/package/the-grid-cc)
- [Claude Code Documentation](https://docs.anthropic.com/claude-code)

---

*Powered by The Grid - End of Line.*