npm package: @preflight-ai/cli
Description: Preflight AI code review CLI that analyzes staged changes via AI.
Author: prefl.run
Latest version: 3.9.22

# Prefl AI - Professional Code Review Tool ✨

**AI-powered code review that catches bugs before they reach production**

Website: [prefl.run](https://prefl.run)

---

## 🚀 Features

- **🤖 AI-Powered Analysis** - Deep semantic code review with OpenAI (senior architect-level analysis)
- **🐛 Production Bug Detection** - Catches critical bugs that pass code review & testing but crash in production
- **🎯 Smart Context Tracking** - Analyzes related code and imports to maintain full context
- **🚨 Critical Issue Detection** - Identifies production-critical problems
- **🌍 Multi-Language Support** - Works with any programming language (JavaScript, Python, Go, Java, C#, Ruby, PHP, Rust, etc.)
- **⚡ Lightning Fast** - AI analysis in seconds
- **🪝 Automatic Pre-commit Hook** - Installs git pre-commit hook automatically on init

---

## 📦 Installation

```bash
npm i -g @preflight-ai/cli@latest
```

---

## 🛠️ Setup

### 1. Initialize in your project

```bash
cd your-project
prefl init
```

## 🎯 Usage

### Automatic Review (Pre-commit Hook)

Once initialized, Prefl automatically reviews your code before every commit:

```bash
git add .
git commit -m "feat: add new feature"
# ✨ Prefl analyzes your changes automatically!
```

### Manual Analysis

```bash
# Analyze staged changes (default)
prefl analyze

# Analyze entire project
prefl analyze --full

# Analyze entire repository (respects ignores)
prefl analyze --all

# Save results to prefl-log.txt
prefl analyze --output
```

### Fix Issues

```bash
# Generate AI-suggested patch (saves to prefl-log.txt automatically)
prefl fix

# Apply the patch automatically
prefl fix --apply

# Validate patch without applying
prefl fix --dry-run

# Fix entire repository
prefl fix --all
```

### Get Code Suggestions

```bash
# Generate ideal, improved code suggestions
prefl suggest

# Apply suggestions automatically
prefl suggest --apply

# Validate suggestions without applying
prefl suggest --dry-run

# Suggest improvements for entire repository
prefl suggest --all
```

---

## 📊 How It Works

Prefl uses **OpenAI AI** to analyze your code like a professional code reviewer and tester:

1. **Analyzes staged files** - Reviews the code you're changing
2. **Checks related context** - Examines imports, dependencies, and connected files
3. **Tests mentally** - Thinks through various scenarios and edge cases
4. **Finds issues** - Identifies bugs, critical problems, and potential issues
5. **Reports findings** - Provides detailed explanations and fix suggestions

### Context-Aware Analysis

Prefl automatically:

- Loads staged files (the code being changed)
- Finds related files via imports and dependencies
- Maintains full context to understand how code interacts with the rest of the system
- Analyzes compatibility to ensure changes don't break related code

---

## 📋 Commands

```bash
prefl init                # Setup Prefl in your project (installs pre-commit hook automatically)
prefl analyze             # Analyze staged changes
prefl analyze --full      # Analyze entire project
prefl analyze --all       # Analyze entire repository (respects ignores)
prefl analyze --output    # Analyze and save results to prefl-log.txt
prefl fix                 # Generate AI-suggested patches (saves to prefl-log.txt)
prefl fix --apply         # Auto-apply generated fixes
prefl fix --dry-run       # Validate patch without applying
prefl fix --all           # Fix entire repository
prefl suggest             # Generate ideal, improved code suggestions
prefl suggest --apply     # Auto-apply suggestions
prefl suggest --dry-run   # Validate suggestions without applying
prefl suggest --all       # Suggest improvements for entire repository
prefl --version           # Show version
prefl --help              # Show help
```

---

## 🎨 Example Output

```
Analysis Completed ✨

🟥  CRITICAL (Must Fix)

1. src/payment.ts
   Issue:    Race condition: shared state modified in async function without locking
   Fix:      Use db.transaction() or mutex.lock() to ensure atomicity

2. src/api/user.ts
   Issue:    Missing authentication middleware on /admin/users endpoint
   Fix:      Add requireAuth and requireAdmin middleware before handler

🟨  WARNINGS (Recommended Fixes)

1. src/utils.ts
   Issue:    Function returns undefined for non-premium users
   Fix:      Add explicit return for all code paths

🛑 Commit blocked due to critical issues.
```

---

## ⚙️ Configuration

Edit `prefl.json` in your project root:

```json
{
  "ignore": {
    "globs": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "*.test.js",
      "coverage/**"
    ]
  },
  "review": {
    "blockSeverities": ["critical"],
    "showSeverities": ["critical", "warning"]
  },
  "model": "gpt-5-codex"
}
```

### Configuration Options

- **ignore.globs**: Files/folders to skip (supports glob patterns)
- **review.blockSeverities**: Which severity levels block commits (`["critical"]`, `["critical", "warning"]`, or `[]`)
- **review.showSeverities**: Which severity levels to show in output
- **model**: OpenAI model to use (default: `gpt-5-codex`)

## 🌟 Why Prefl?

Prefl uses **AI to catch bugs that humans miss** - issues that look correct in review, pass tests, but crash in production.

The AI analyzes:

- **Context** - How code interacts with related files and dependencies
- **Edge cases** - Boundary conditions, null checks, error handling
- **Security** - Authentication, authorization, input validation
- **Business logic** - Completeness, missing returns, undefined results
- **And more** - Anything that could cause problems in production

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).

---

## 📄 License

Apache 2.0 - See [LICENSE](LICENSE) for details

---

## 💬 Support

- 🌐 Website: [prefl.run](https://prefl.run)
- 📧 Email: support@prefl.run
- 🐛 Issues: [GitHub Issues](https://github.com/preflight-ai/cli/issues)

---

**Made with ❤️ by developers, for developers**