preflight-ai 0.1.0__tar.gz

preflight_ai-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: preflight-ai
+Version: 0.1.0
+Summary: AI-powered code review before you open a PR
+Author: Jinsung Park
+License: MIT
+Project-URL: Homepage, https://github.com/jsliapark/preflight
+Project-URL: Repository, https://github.com/jsliapark/preflight
+Project-URL: Issues, https://github.com/jsliapark/preflight/issues
+Keywords: code-review,ai,git,cli,anthropic,claude,pull-request
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.25.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: PyGithub>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# Preflight
+
+Instant senior-level AI code review before you open a PR.
+
+Preflight analyzes your git diff through 4 focused AI review passes—each a separate Claude API call for higher quality than a single giant prompt. Get actionable feedback on correctness, security, style, and performance issues before your code even reaches human reviewers.
+
+## Features
+
+- **4 Focused Review Passes** — Correctness, Security, Style, and Performance checks run concurrently for fast, thorough analysis
+- **Smart Diff Analysis** — Automatically extracts modified functions/classes and classifies intent (feature, bugfix, refactor)
+- **PR Description Generation** — Creates complete PR writeups with summary, motivation, approach, and testing notes
+- **Severity-Based Output** — Color-coded findings (critical, warning, suggestion) with specific line references and suggested fixes
+- **Repo Standards Learning** — Optional ChromaDB integration to learn patterns from your merged PRs
+- **CLI-First Design** — Simple commands that integrate into your existing workflow
+
+## Tech Stack
+
+| Category | Technology |
+|----------|------------|
+| Language | Python 3.11+ |
+| AI | Anthropic Claude API |
+| CLI | Click |
+| Output | Rich |
+| Data Validation | Pydantic v2 |
+| Vector DB | ChromaDB |
+| GitHub API | PyGithub |
+| Config | python-dotenv |
+
+## Prerequisites
+
+- **Python 3.11 or higher**
+- **Git** — Must be run from within a git repository
+- **Anthropic API key** — Get one at [console.anthropic.com](https://console.anthropic.com/)
+- **GitHub CLI** (optional) — Required for `preflight pr` to create PRs directly. Install from [cli.github.com](https://cli.github.com/)
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/your-username/preflight.git
+cd preflight
+```
+
+2. Install the package:
+
+```bash
+pip install -e .
+```
+
+For development (includes pytest):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Create a `.env` file in the project root (or copy from `.env.example`):
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+GITHUB_TOKEN=ghp_your-github-token-here
+GITHUB_REPO=owner/repo-name
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key for Claude |
+| `GITHUB_TOKEN` | No | GitHub token for Standards Indexer (repo pattern learning) |
+| `GITHUB_REPO` | No | Repository in `owner/repo` format for Standards Indexer |
+
+## Usage
+
+### Code Review
+
+Run all 4 review passes on your current branch's diff against `main`:
+
+```bash
+preflight review
+```
+
+Diff against a different base branch:
+
+```bash
+preflight review --base develop
+```
+
+Example output:
+
+```
+Intent: feature · 3 file(s) changed
+
+── CORRECTNESS ──
+No issues found.
+
+── SECURITY ──
+[WARNING] src/auth.py:45
+  Potential SQL injection vulnerability in user query
+  → Use parameterized queries instead of string formatting
+
+── STYLE ──
+[SUGGESTION] src/utils.py:12
+  Magic number 86400 should be a named constant
+  → Define SECONDS_PER_DAY = 86400
+
+── PERFORMANCE ──
+No issues found.
+```
+
+### PR Description Generation
+
+Generate a PR description and create a PR via GitHub CLI:
+
+```bash
+preflight pr
+```
+
+Options:
+
+```bash
+# Diff against a different branch
+preflight pr --base develop
+
+# Override the generated title
+preflight pr --title "Add user authentication"
+
+# Copy to clipboard instead of creating PR
+preflight pr --copy
+```
+
+When you run `preflight pr`, it will:
+1. Generate a title, summary, motivation, approach, testing notes, and TODOs
+2. Show a preview panel
+3. Prompt for confirmation
+4. Push your branch and create the PR via `gh pr create`
+
+## Project Structure
+
+```
+preflight/
+├── core/
+│   ├── cli.py              # Main CLI entry point (Click commands)
+│   ├── diff_parser.py      # Parses raw git diff into ChangeSet
+│   └── models.py           # Pydantic models (ChangeSet, ReviewResult, etc.)
+├── agents/
+│   ├── diff_analyzer.py    # Extracts intent and function/class changes
+│   ├── review_agent.py     # 4 review passes (correctness, security, style, performance)
+│   ├── pr_description.py   # PR description generation
+│   ├── standards_agent.py  # Reviews against repo-specific patterns
+│   └── standards_indexer.py # Indexes merged PRs into ChromaDB
+├── prompts/
+│   ├── diff_analyzer.md
+│   ├── correctness_review.md
+│   ├── security_review.md
+│   ├── style_review.md
+│   ├── performance_review.md
+│   ├── pr_description.md
+│   └── standards_review.md
+├── test_*.py               # Test files
+├── pyproject.toml          # Package configuration
+├── .env.example            # Example environment variables
+└── SAFETY.md               # Safety considerations and limitations
+```
+
+## Review Passes
+
+Each pass focuses on a specific category:
+
+| Pass | What It Catches |
+|------|-----------------|
+| **Correctness** | Logic bugs, null dereferences, off-by-one errors, unhandled exceptions, race conditions |
+| **Security** | SQL/command injection, hardcoded secrets, auth issues, sensitive data exposure |
+| **Style** | Readability, naming conventions, magic numbers, dead code, missing docstrings |
+| **Performance** | N+1 queries, unbounded memory, missing caching opportunities, sync vs async issues |
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test files
+python test_diff_parser.py
+python test_diff_analyzer.py
+python test_agent.py
+python test_evals.py
+```
+
+## Safety & Limitations
+
+Preflight is **advisory only**—it does not block merges or execute any code.
+
+- Diffs are sent to Anthropic's API; no external storage of your code
+- Large diffs may be truncated to fit context limits
+- The Security pass flags potential hardcoded secrets
+- Standards Agent quality depends on the quality of indexed PRs
+
+See [SAFETY.md](SAFETY.md) for full details.
+
+## Contributing
+
+Contributions are welcome! To get started:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Make your changes
+4. Run tests (`pytest`)
+5. Commit your changes (`git commit -m "Add your feature"`)
+6. Push to the branch (`git push origin feature/your-feature`)
+7. Open a Pull Request
+

preflight_ai-0.1.0/README.md

@@ -0,0 +1,218 @@
+# Preflight
+
+Instant senior-level AI code review before you open a PR.
+
+Preflight analyzes your git diff through 4 focused AI review passes—each a separate Claude API call for higher quality than a single giant prompt. Get actionable feedback on correctness, security, style, and performance issues before your code even reaches human reviewers.
+
+## Features
+
+- **4 Focused Review Passes** — Correctness, Security, Style, and Performance checks run concurrently for fast, thorough analysis
+- **Smart Diff Analysis** — Automatically extracts modified functions/classes and classifies intent (feature, bugfix, refactor)
+- **PR Description Generation** — Creates complete PR writeups with summary, motivation, approach, and testing notes
+- **Severity-Based Output** — Color-coded findings (critical, warning, suggestion) with specific line references and suggested fixes
+- **Repo Standards Learning** — Optional ChromaDB integration to learn patterns from your merged PRs
+- **CLI-First Design** — Simple commands that integrate into your existing workflow
+
+## Tech Stack
+
+| Category | Technology |
+|----------|------------|
+| Language | Python 3.11+ |
+| AI | Anthropic Claude API |
+| CLI | Click |
+| Output | Rich |
+| Data Validation | Pydantic v2 |
+| Vector DB | ChromaDB |
+| GitHub API | PyGithub |
+| Config | python-dotenv |
+
+## Prerequisites
+
+- **Python 3.11 or higher**
+- **Git** — Must be run from within a git repository
+- **Anthropic API key** — Get one at [console.anthropic.com](https://console.anthropic.com/)
+- **GitHub CLI** (optional) — Required for `preflight pr` to create PRs directly. Install from [cli.github.com](https://cli.github.com/)
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/your-username/preflight.git
+cd preflight
+```
+
+2. Install the package:
+
+```bash
+pip install -e .
+```
+
+For development (includes pytest):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Create a `.env` file in the project root (or copy from `.env.example`):
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+GITHUB_TOKEN=ghp_your-github-token-here
+GITHUB_REPO=owner/repo-name
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key for Claude |
+| `GITHUB_TOKEN` | No | GitHub token for Standards Indexer (repo pattern learning) |
+| `GITHUB_REPO` | No | Repository in `owner/repo` format for Standards Indexer |
+
+## Usage
+
+### Code Review
+
+Run all 4 review passes on your current branch's diff against `main`:
+
+```bash
+preflight review
+```
+
+Diff against a different base branch:
+
+```bash
+preflight review --base develop
+```
+
+Example output:
+
+```
+Intent: feature · 3 file(s) changed
+
+── CORRECTNESS ──
+No issues found.
+
+── SECURITY ──
+[WARNING] src/auth.py:45
+  Potential SQL injection vulnerability in user query
+  → Use parameterized queries instead of string formatting
+
+── STYLE ──
+[SUGGESTION] src/utils.py:12
+  Magic number 86400 should be a named constant
+  → Define SECONDS_PER_DAY = 86400
+
+── PERFORMANCE ──
+No issues found.
+```
+
+### PR Description Generation
+
+Generate a PR description and create a PR via GitHub CLI:
+
+```bash
+preflight pr
+```
+
+Options:
+
+```bash
+# Diff against a different branch
+preflight pr --base develop
+
+# Override the generated title
+preflight pr --title "Add user authentication"
+
+# Copy to clipboard instead of creating PR
+preflight pr --copy
+```
+
+When you run `preflight pr`, it will:
+1. Generate a title, summary, motivation, approach, testing notes, and TODOs
+2. Show a preview panel
+3. Prompt for confirmation
+4. Push your branch and create the PR via `gh pr create`
+
+## Project Structure
+
+```
+preflight/
+├── core/
+│   ├── cli.py              # Main CLI entry point (Click commands)
+│   ├── diff_parser.py      # Parses raw git diff into ChangeSet
+│   └── models.py           # Pydantic models (ChangeSet, ReviewResult, etc.)
+├── agents/
+│   ├── diff_analyzer.py    # Extracts intent and function/class changes
+│   ├── review_agent.py     # 4 review passes (correctness, security, style, performance)
+│   ├── pr_description.py   # PR description generation
+│   ├── standards_agent.py  # Reviews against repo-specific patterns
+│   └── standards_indexer.py # Indexes merged PRs into ChromaDB
+├── prompts/
+│   ├── diff_analyzer.md
+│   ├── correctness_review.md
+│   ├── security_review.md
+│   ├── style_review.md
+│   ├── performance_review.md
+│   ├── pr_description.md
+│   └── standards_review.md
+├── test_*.py               # Test files
+├── pyproject.toml          # Package configuration
+├── .env.example            # Example environment variables
+└── SAFETY.md               # Safety considerations and limitations
+```
+
+## Review Passes
+
+Each pass focuses on a specific category:
+
+| Pass | What It Catches |
+|------|-----------------|
+| **Correctness** | Logic bugs, null dereferences, off-by-one errors, unhandled exceptions, race conditions |
+| **Security** | SQL/command injection, hardcoded secrets, auth issues, sensitive data exposure |
+| **Style** | Readability, naming conventions, magic numbers, dead code, missing docstrings |
+| **Performance** | N+1 queries, unbounded memory, missing caching opportunities, sync vs async issues |
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test files
+python test_diff_parser.py
+python test_diff_analyzer.py
+python test_agent.py
+python test_evals.py
+```
+
+## Safety & Limitations
+
+Preflight is **advisory only**—it does not block merges or execute any code.
+
+- Diffs are sent to Anthropic's API; no external storage of your code
+- Large diffs may be truncated to fit context limits
+- The Security pass flags potential hardcoded secrets
+- Standards Agent quality depends on the quality of indexed PRs
+
+See [SAFETY.md](SAFETY.md) for full details.
+
+## Contributing
+
+Contributions are welcome! To get started:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Make your changes
+4. Run tests (`pytest`)
+5. Commit your changes (`git commit -m "Add your feature"`)
+6. Push to the branch (`git push origin feature/your-feature`)
+7. Open a Pull Request
+

preflight_ai-0.1.0/agents/diff_analyzer.py

@@ -0,0 +1,68 @@
+import json
+from anthropic import Anthropic
+from dotenv import load_dotenv
+import os
+from core.models import ChangeSet, ChangeIntent, FileChange
+
+load_dotenv()
+client = Anthropic()
+
+
+def analyze_diff(changeset: ChangeSet) -> ChangeSet:
+    """
+    Enriches a ChangeSet with:
+    - intent classification (feature / bugfix / refactor / unknown)
+    - function and class level changes extracted by Claude
+    """
+    prompt = _load_prompt("diff_analyzer")
+
+    response = client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=1024,
+        system=prompt,
+        messages=[
+            {"role": "user", "content": f"Analyze this diff:\n\n{changeset.raw_diff}"}
+        ]
+    )
+
+    raw = response.content[0].text.strip()
+
+    if raw.startswith("```"):
+        start = raw.find("\n") + 1
+        end = raw.rfind("```")
+        raw = raw[start:end].strip()
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        print("WARNING: diff analyzer could not parse Claude response, using defaults")
+        return changeset
+
+    # Classify intent
+    try:
+        intent = ChangeIntent(parsed.get("intent", "unknown"))
+    except ValueError:
+        intent = ChangeIntent.UNKNOWN
+
+    # Enrich each file with extracted functions and classes
+    updated_files = []
+    for f in changeset.files:
+        updated_files.append(f.model_copy(update={
+            "functions_added": parsed.get("functions_added", []),
+            "functions_modified": parsed.get("functions_modified", []),
+            "functions_deleted": parsed.get("functions_deleted", []),
+            "classes_added": parsed.get("classes_added", []),
+            "classes_modified": parsed.get("classes_modified", []),
+            "classes_deleted": parsed.get("classes_deleted", []),
+        }))
+
+    return changeset.model_copy(update={
+        "intent": intent,
+        "files": updated_files,
+    })
+
+
+def _load_prompt(name: str) -> str:
+    path = os.path.join(os.path.dirname(__file__), "..", "prompts", f"{name}.md")
+    with open(path) as f:
+        return f.read()

preflight_ai-0.1.0/agents/pr_description.py

@@ -0,0 +1,78 @@
+import json
+from anthropic import Anthropic
+from dotenv import load_dotenv
+import os
+from core.models import ChangeSet, PRDescription
+
+load_dotenv()
+client = Anthropic()
+
+
+def generate_pr_description(changeset: ChangeSet) -> PRDescription:
+    prompt = _load_prompt("pr_description")
+    context = _build_context(changeset)
+
+    response = client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=2048,
+        system=prompt,
+        messages=[
+            {"role": "user", "content": f"Generate a PR description for this change:\n\n{context}"}
+        ]
+    )
+
+    raw = response.content[0].text.strip()
+
+    if raw.startswith("```"):
+        start = raw.find("\n") + 1
+        end = raw.rfind("```")
+        raw = raw[start:end].strip()
+
+    parsed = json.loads(raw)
+
+    return PRDescription(
+        title=parsed["title"],
+        summary=_to_string(parsed["summary"]),
+        motivation=_to_string(parsed["motivation"]),
+        approach=_to_string(parsed["approach"]),
+        testing_notes=_to_string(parsed["testing_notes"]),
+        todos=_to_string(parsed["todos"]),
+    )
+
+
+def _to_string(value) -> str:
+    """Convert a value to string, joining list items with newlines if needed."""
+    if isinstance(value, list):
+        return "\n".join(str(item) for item in value)
+    return str(value)
+
+
+def _build_context(changeset: ChangeSet) -> str:
+    lines = [f"Intent: {changeset.intent.value}", "", "Files changed:"]
+
+    for f in changeset.files:
+        lines.append(f"- {f.path} ({f.change_type.value})")
+        if f.functions_added:
+            lines.append(f"  functions_added: {', '.join(f.functions_added)}")
+        if f.functions_modified:
+            lines.append(f"  functions_modified: {', '.join(f.functions_modified)}")
+        if f.functions_deleted:
+            lines.append(f"  functions_deleted: {', '.join(f.functions_deleted)}")
+        if f.classes_added:
+            lines.append(f"  classes_added: {', '.join(f.classes_added)}")
+        if f.classes_modified:
+            lines.append(f"  classes_modified: {', '.join(f.classes_modified)}")
+        if f.classes_deleted:
+            lines.append(f"  classes_deleted: {', '.join(f.classes_deleted)}")
+
+    lines.append("")
+    lines.append("Raw diff:")
+    lines.append(changeset.raw_diff)
+
+    return "\n".join(lines)
+
+
+def _load_prompt(name: str) -> str:
+    path = os.path.join(os.path.dirname(__file__), "..", "prompts", f"{name}.md")
+    with open(path) as f:
+        return f.read()

preflight_ai-0.1.0/agents/review_agent.py

@@ -0,0 +1,75 @@
+import os
+import json
+from anthropic import Anthropic
+from dotenv import load_dotenv
+from core.models import ChangeSet, ReviewComment, ReviewResult, Severity
+
+load_dotenv()
+
+client = Anthropic()
+
+def _run_pass(changeset: ChangeSet, prompt_name: str, category: str) -> ReviewResult:
+    prompt = _load_prompt(prompt_name)
+    diff_content = _format_diff_for_review(changeset)
+    
+    response = client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=1024,
+        system=prompt,
+        messages=[
+            {"role": "user", "content": f"Please review this diff:\n\n{diff_content}"}
+        ]
+    )
+    
+    raw = response.content[0].text
+    
+    if raw.startswith("```"):
+        start = raw.find("\n") + 1
+        end = raw.rfind("```")
+        raw = raw[start:end].strip()
+    
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        print(f"ERROR: Failed to parse JSON response from Claude")
+        print(f"Raw response:\n{raw}")
+        raise
+    
+    comments = [ReviewComment(
+        file=c["file"],
+        line=c.get("line"),
+        severity=Severity(c["severity"]),
+        category=category,
+        message=c["message"],
+        suggested_fix=c.get("suggested_fix")
+    ) for c in parsed["comments"]]
+    
+    return ReviewResult(
+        comments=comments,
+        summary=parsed["summary"],
+        pass_name=category
+    )
+
+
+# Public API — one line each
+def run_correctness_pass(changeset: ChangeSet) -> ReviewResult:
+    return _run_pass(changeset, "correctness_review", "correctness")
+
+def run_security_pass(changeset: ChangeSet) -> ReviewResult:
+    return _run_pass(changeset, "security_review", "security")
+
+def run_style_pass(changeset: ChangeSet) -> ReviewResult:
+    return _run_pass(changeset, "style_review", "style")
+
+def run_performance_pass(changeset: ChangeSet) -> ReviewResult:
+    return _run_pass(changeset, "performance_review", "performance")
+
+# Helper functions
+def _load_prompt(name: str) -> str:
+    path = os.path.join(os.path.dirname(__file__), "..", "prompts", f"{name}.md")
+    with open(path) as f:
+        return f.read()
+
+
+def _format_diff_for_review(changeset: ChangeSet) -> str:
+    return changeset.raw_diff