# pr-guardian

> Local AI code validation for GitHub PRs—catch hallucinated imports and suspicious patterns before you ship.

## What is this?

**pr-guardian** is a developer-focused tool that validates AI-generated code changes before they reach production. It runs entirely locally (no enterprise contracts required), scanning your PRs for hallucinated imports, suspicious patterns, and generating confidence scores for AI-assisted changes. Works as both a GitHub Action and browser extension to provide protection at every stage of your workflow.

## Features

- **Local AI validation** – Runs on your machine, no cloud dependencies
- **GitHub Action integration** – Automatically comments on PRs with risk scores
- **Browser extension** – Real-time validation as you edit in GitHub's web interface
- **CLI tool** – Scan files and directories from your terminal
- **Pattern detection** – Catches hallucinated imports, non-existent APIs, and suspicious code patterns
- **AI confidence scoring** – Per-file risk assessment for changed code
- **Privacy-first** – Your code never leaves your infrastructure

## Quick Start

### Installation

**Python CLI & GitHub Action:**

```bash
pip install pr-guardian
```

**Browser Extension:**

1. Download from Chrome Web Store (coming soon) or load unpacked from `extension/` directory
2. Pin the extension and configure your preferences

### GitHub Action Setup

Add to `.github/workflows/pr-guardian.yml`:

```yaml
name: PR Guardian
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install pr-guardian
        run: pip install pr-guardian
      - name: Scan PR
        run: pr-guardian scan --github-pr ${{ github.event.pull_request.number }}
```

## Usage

### CLI

```bash
# Scan a single file
pr-guardian scan path/to/file.py

# Scan entire directory
pr-guardian scan src/

# Analyze specific patterns
pr-guardian analyze --file code.py --patterns imports,apis
```

### Browser Extension

1. Open a GitHub PR in your browser
2. The extension automatically highlights suspicious code blocks
3. Click the extension icon to see detailed risk scores
4. Review confidence metrics before submitting your PR

### GitHub Action

Once configured, pr-guardian automatically:
- Scans all changed files in pull requests
- Posts inline comments on suspicious code
- Adds a summary comment with overall risk assessment
- Blocks merging if critical issues are detected (configurable)

## Tech Stack

- **Python 3.11+** – Core validation engine and CLI
- **JavaScript/TypeScript** – Browser extension
- **GitHub Actions** – CI/CD integration
- **SQLite** – Local scan history (optional)

## License

MIT License - see LICENSE file for details

---

**Built for developers navigating the AI-assisted coding era.** Protect your work, maintain transparency, and ship with confidence.