git-diff-ai-reviewer 1.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # required for provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Publish to NPM
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,204 @@
+# git-diff-ai-reviewer
+
+AI-powered code review tool using **Claude** or **Gemini** APIs. Reviews git branch diffs and generates structured, actionable feedback with severity levels.
+
+## Installation
+
+> **`--save-dev` is correct** — this is a development tool (like ESLint or Prettier) used only during development and CI. It should never be in your production bundle.
+
+```bash
+# From npm (recommended)
+npm install --save-dev git-diff-ai-reviewer
+
+# Or directly from GitHub
+npm install --save-dev github:andrii-posia/git-diff-ai-reviewer
+```
+
+Then install **only the SDK for the provider you want to use** (also as devDependencies):
+
+```bash
+# If using Claude (Anthropic)
+npm install --save-dev @anthropic-ai/sdk
+
+# If using Gemini (Google)
+npm install --save-dev @google/genai
+
+# If you want both available
+npm install --save-dev @anthropic-ai/sdk @google/genai
+
+```
+
+> Neither SDK is installed automatically. You only pay for what you use.
+
+## Setup
+
+Set the API key for your chosen provider:
+
+```bash
+# For Claude (Anthropic)
+export ANTHROPIC_API_KEY=your-key-here
+
+# For Gemini (Google)
+export GEMINI_API_KEY=your-key-here
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Review with auto-detected provider (based on which env var is set)
+git-diff-ai-reviewer review
+
+# Explicitly choose a provider
+git-diff-ai-reviewer review --provider claude
+git-diff-ai-reviewer review --provider gemini
+
+# Review against a specific base branch
+git-diff-ai-reviewer review --base develop
+
+# Preview diff without calling API
+git-diff-ai-reviewer review --dry-run
+
+# Generate fix prompt from latest review
+git-diff-ai-reviewer fix
+```
+
+### npm scripts
+
+Add to your `package.json`:
+```json
+{
+  "scripts": {
+    "review": "git-diff-ai-reviewer review",
+    "review:fix": "git-diff-ai-reviewer fix",
+    "review:dry": "git-diff-ai-reviewer review --dry-run"
+  }
+}
+```
+
+## Providers
+
+| Provider | Env Variable | Default Model |
+|----------|-------------|---------------|
+| Claude | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| Gemini | `GEMINI_API_KEY` | `gemini-2.0-flash` |
+
+The provider is auto-detected from which API key is set. You can also set it explicitly in the config or via `--provider` flag.
+
+## Severity Levels
+
+Each review finding is tagged with a severity:
+
+- 🔴 **CRITICAL** — Bugs, security vulnerabilities, data loss risks. Must fix before merging.
+- 🟡 **WARNING** — Performance issues, bad practices, potential bugs. Should be addressed.
+- 🔵 **SUGGESTION** — Style improvements, readability, refactoring opportunities. Nice to have.
+
+The CLI exits with code `1` if CRITICAL issues are found (useful for CI gates).
+
+## Review Rule Presets
+
+Three built-in rule presets control what the AI checks for:
+
+### `basic` — Quick, lightweight review
+- Syntax errors, typos, unused variables
+- Debug statements left in code
+- Hardcoded secrets
+- Basic error handling
+
+### `standard` (default) — Balanced everyday review
+- Everything in `basic`, plus:
+- Input validation, null checks
+- Code duplication, naming conventions
+- Async/await correctness
+- Resource cleanup
+
+### `comprehensive` — Full audit for critical code
+- Everything in `standard`, plus:
+- Security (SQL injection, XSS, auth)
+- Race conditions, memory leaks
+- API design, backward compatibility
+- Accessibility, test coverage
+- Performance analysis
+
+Use a preset name or provide custom rules in your config.
+
+## Configuration
+
+Create `.ai-review.config.json` in your project root:
+
+```json
+{
+  "provider": "claude",
+  "baseBranch": "main",
+  "model": "",
+  "maxTokens": 4096,
+  "outputDir": "./reviews",
+  "reviewRules": "standard"
+}
+```
+
+### Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | string | auto-detect | `"claude"` or `"gemini"` |
+| `baseBranch` | string | `"main"` | Branch to compare against |
+| `model` | string | per-provider | Override the AI model |
+| `maxTokens` | number | `4096` | Max response tokens |
+| `outputDir` | string | `"./reviews"` | Where to write output files |
+| `reviewRules` | string\|array | `"standard"` | Preset name or custom rules array |
+
+### Custom Rules Example
+
+```json
+{
+  "provider": "gemini",
+  "reviewRules": [
+    "Use camelCase for variable names",
+    "All functions must have JSDoc comments",
+    "No inline styles in React components",
+    "Database queries must use parameterized statements"
+  ]
+}
+```
+
+## Programmatic API
+
+```javascript
+const {
+  reviewCode,
+  getDiff,
+  getChangedFiles,
+  detectProvider,
+  STANDARD_RULES,
+} = require('git-diff-ai-reviewer');
+
+const diff = getDiff('main');
+const files = getChangedFiles('main');
+const provider = detectProvider({ provider: 'gemini' });
+const review = await reviewCode(diff, {
+  provider,
+  changedFiles: files,
+  branchName: 'feature/xyz',
+  reviewRules: STANDARD_RULES,
+});
+```
+
+## Output Files
+
+Review outputs are saved to `./reviews/` (configurable):
+- `review-output-<timestamp>.txt` — Full review with severity-tagged findings
+- `fix-prompt-<timestamp>.txt` — AI agent-ready prompt to auto-fix issues
+
+## CI Integration
+
+```yaml
+# GitHub Actions example
+- name: AI Code Review
+  run: npx git-diff-ai-reviewer review --provider claude
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+The CLI exits with code `1` on CRITICAL findings, making it suitable as a CI gate.

package/bin/review.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { getDiff, getChangedFiles, getBranchName, isGitRepo } = require('../src/git');
+const { reviewCode, parseSeverityCounts, detectProvider, PROVIDERS, DEFAULT_MODELS } = require('../src/provider');
+const { buildFixPrompt } = require('../src/prompts');
+const { loadConfig } = require('../src/config');
+const { writeReviewOutput, writeFixPrompt, findLatestReview } = require('../src/output');
+
+// ─── Argument Parsing ────────────────────────────────────────────────
+
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const flags = {};
+    let command = null;
+
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--base':
+            case '-b':
+                flags.baseBranch = args[++i];
+                break;
+            case '--output':
+            case '-o':
+                flags.outputDir = args[++i];
+                break;
+            case '--config':
+            case '-c':
+                flags.configPath = args[++i];
+                break;
+            case '--model':
+            case '-m':
+                flags.model = args[++i];
+                break;
+            case '--provider':
+            case '-p':
+                flags.provider = args[++i];
+                break;
+            case '--dry-run':
+                flags.dryRun = true;
+                break;
+            case '--help':
+            case '-h':
+                flags.help = true;
+                break;
+            default:
+                if (!args[i].startsWith('-') && !command) {
+                    command = args[i];
+                } else {
+                    console.warn(`Unknown option: ${args[i]}`);
+                }
+        }
+    }
+
+    return { command: command || 'review', flags };
+}
+
+// ─── Help ────────────────────────────────────────────────────────────
+
+function showHelp() {
+    console.log(`
+╔══════════════════════════════════════════════════════╗
+║              🤖 AI Code Review CLI                   ║
+╚══════════════════════════════════════════════════════╝
+
+Usage: ai-review <command> [options]
+
+Commands:
+  review    Review code changes using AI (default)
+  fix       Generate a fix prompt from the latest review
+
+Options:
+  -b, --base <branch>      Base branch to compare against (default: main)
+  -p, --provider <name>    AI provider: 'claude' or 'gemini' (auto-detected from env)
+  -m, --model <model>      Model name (defaults per provider)
+  -o, --output <dir>       Output directory for review files (default: ./reviews)
+  -c, --config <path>      Path to config file
+  --dry-run                Extract diff and show prompt without calling AI API
+  -h, --help               Show this help message
+
+Providers:
+  claude    Uses ANTHROPIC_API_KEY  (default model: claude-sonnet-4-20250514)
+  gemini    Uses GEMINI_API_KEY     (default model: gemini-2.0-flash)
+
+Severity Levels:
+  🔴 CRITICAL    Bugs, security issues, data loss — must fix
+  🟡 WARNING     Performance, bad practices — should fix
+  🔵 SUGGESTION  Style, readability — nice to have
+
+Review Rule Presets:
+  basic           Quick lint-level checks
+  standard        Balanced everyday review (default)
+  comprehensive   Full audit for critical code
+
+Examples:
+  ai-review review                          Review with auto-detected provider
+  ai-review review --provider gemini        Review using Gemini
+  ai-review review --base develop           Review against develop branch
+  ai-review review --dry-run                Preview without calling API
+  ai-review fix                             Generate fix prompt from latest review
+
+Config File (.ai-review.config.json):
+  {
+    "provider": "claude",
+    "baseBranch": "main",
+    "model": "",
+    "maxTokens": 4096,
+    "outputDir": "./reviews",
+    "reviewRules": "standard"
+  }
+`);
+}
+
+// ─── Review Command ─────────────────────────────────────────────────
+
+async function commandReview(config, flags) {
+    const baseBranch = flags.baseBranch || config.baseBranch;
+    const outputDir = path.resolve(flags.outputDir || config.outputDir);
+
+    // Detect provider
+    const provider = flags.provider || detectProvider(config);
+    const model = flags.model || config.model || DEFAULT_MODELS[provider];
+
+    console.log('');
+    console.log('🔍 AI Code Review');
+    console.log('─'.repeat(40));
+    console.log(`  Provider:   ${provider}`);
+    console.log(`  Model:      ${model}`);
+
+    // Get branch and diff info
+    const branchName = getBranchName();
+    console.log(`  Branch:     ${branchName}`);
+    console.log(`  Base:       ${baseBranch}`);
+
+    const changedFiles = getChangedFiles(baseBranch);
+    if (changedFiles.length === 0) {
+        console.log('\n✅ No changes detected. Nothing to review.');
+        process.exit(0);
+    }
+    console.log(`  Changed:    ${changedFiles.length} file(s)`);
+    changedFiles.forEach(f => console.log(`              - ${f}`));
+
+    const diff = getDiff(baseBranch);
+    if (!diff.trim()) {
+        console.log('\n✅ Empty diff. Nothing to review.');
+        process.exit(0);
+    }
+    console.log(`  Diff size:  ${diff.length} characters`);
+    console.log('─'.repeat(40));
+
+    // Dry run mode — show what would be sent
+    if (flags.dryRun) {
+        console.log('\n📋 DRY RUN — Diff extracted, API not called.\n');
+        console.log(`Provider: ${provider} | Model: ${model}`);
+        console.log(`Rules:    ${config.reviewRules.length} active`);
+        console.log('Changed files:');
+        changedFiles.forEach(f => console.log(`  - ${f}`));
+        console.log(`\nDiff preview (first 500 chars):\n${diff.slice(0, 500)}...`);
+        console.log('\n💡 Remove --dry-run to send to AI for review.');
+        process.exit(0);
+    }
+
+    // Send to AI provider
+    console.log(`\n⏳ Sending to ${provider} (${model}) for review...\n`);
+
+    try {
+        const reviewText = await reviewCode(diff, {
+            provider,
+            changedFiles,
+            branchName,
+            model,
+            maxTokens: config.maxTokens,
+            reviewRules: config.reviewRules,
+        });
+
+        // Parse severity counts
+        const severityCounts = parseSeverityCounts(reviewText);
+
+        // Write output
+        const outputPath = writeReviewOutput(reviewText, outputDir, {
+            branchName,
+            changedFiles,
+            severityCounts,
+            provider,
+            model,
+        });
+
+        // Summary
+        console.log('═'.repeat(40));
+        console.log('  Review Complete!');
+        console.log('═'.repeat(40));
+        console.log(`  🔴 Critical:   ${severityCounts.critical}`);
+        console.log(`  🟡 Warning:    ${severityCounts.warning}`);
+        console.log(`  🔵 Suggestion: ${severityCounts.suggestion}`);
+        console.log('─'.repeat(40));
+        console.log(`  📄 Output: ${outputPath}`);
+        console.log('');
+        console.log('💡 Run "ai-review fix" to generate an AI fix prompt.');
+        console.log('');
+
+        // Exit with non-zero if critical issues found
+        if (severityCounts.critical > 0) {
+            process.exit(1);
+        }
+    } catch (error) {
+        console.error(`\n❌ Review failed: ${error.message}`);
+        process.exit(2);
+    }
+}
+
+// ─── Fix Command ────────────────────────────────────────────────────
+
+async function commandFix(config, flags) {
+    const baseBranch = flags.baseBranch || config.baseBranch;
+    const outputDir = path.resolve(flags.outputDir || config.outputDir);
+
+    console.log('');
+    console.log('🔧 Generate Fix Prompt');
+    console.log('─'.repeat(40));
+
+    // Find latest review
+    const latestReview = findLatestReview(outputDir);
+    if (!latestReview) {
+        console.error('❌ No review output found. Run "ai-review review" first.');
+        process.exit(1);
+    }
+
+    console.log(`  Using review: ${latestReview}`);
+
+    const reviewText = fs.readFileSync(latestReview, 'utf-8');
+    const diff = getDiff(baseBranch);
+
+    // Build fix prompt
+    const fixPromptText = buildFixPrompt(reviewText, diff);
+
+    // Write fix prompt
+    const fixPath = writeFixPrompt(fixPromptText, outputDir);
+
+    console.log('─'.repeat(40));
+    console.log(`  📄 Fix prompt: ${fixPath}`);
+    console.log('');
+    console.log('💡 Paste the contents of this file into your AI agent to auto-fix issues.');
+    console.log('');
+}
+
+// ─── Main ───────────────────────────────────────────────────────────
+
+async function main() {
+    const { command, flags } = parseArgs(process.argv);
+
+    if (flags.help) {
+        showHelp();
+        process.exit(0);
+    }
+
+    // Verify git repo
+    if (!isGitRepo()) {
+        console.error('❌ Not a git repository. Run this command from within a git project.');
+        process.exit(1);
+    }
+
+    // Load config
+    const config = loadConfig(flags.configPath);
+
+    switch (command) {
+        case 'review':
+            await commandReview(config, flags);
+            break;
+        case 'fix':
+            await commandFix(config, flags);
+            break;
+        default:
+            console.error(`❌ Unknown command: ${command}`);
+            console.error('   Run "ai-review --help" for usage info.');
+            process.exit(1);
+    }
+}
+
+main().catch(err => {
+    console.error(`\n❌ Unexpected error: ${err.message}`);
+    process.exit(2);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "git-diff-ai-reviewer",
+  "version": "1.1.0",
+  "description": "AI-powered code review using Claude or Gemini API. Reviews git branch diffs and generates actionable fix prompts.",
+  "main": "src/index.js",
+  "bin": {
+    "git-diff-ai-reviewer": "./bin/review.js"
+  },
+  "scripts": {
+    "test": "node bin/review.js --help"
+  },
+  "keywords": [
+    "code-review",
+    "ai",
+    "claude",
+    "gemini",
+    "linter",
+    "git",
+    "diff"
+  ],
+  "author": "Andrii Posia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrii-posia/git-diff-ai-reviewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andrii-posia/git-diff-ai-reviewer/issues"
+  },
+  "homepage": "https://github.com/andrii-posia/git-diff-ai-reviewer#readme",
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@google/genai": "^0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    }
+  }
+}

package/src/claude.js

@@ -0,0 +1,95 @@
+const { buildReviewSystemPrompt, buildReviewUserPrompt } = require('./prompts');
+
+/**
+ * Dynamically load the Anthropic SDK.
+ * @returns {Object} The Anthropic class
+ */
+function loadAnthropicSDK() {
+    try {
+        return require('@anthropic-ai/sdk');
+    } catch {
+        throw new Error(
+            'Claude SDK not installed. Run: npm install @anthropic-ai/sdk'
+        );
+    }
+}
+
+/**
+ * Create an Anthropic client instance.
+ * @returns {Anthropic}
+ */
+function createClient() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new Error(
+            'ANTHROPIC_API_KEY environment variable is not set.\n' +
+            'Get your API key at https://console.anthropic.com/settings/keys\n' +
+            'Then set it: export ANTHROPIC_API_KEY=your-key-here'
+        );
+    }
+    const Anthropic = loadAnthropicSDK();
+    return new Anthropic({ apiKey });
+}
+
+/**
+ * Send code diff to Claude for review.
+ * @param {string} diff - The git diff content
+ * @param {Object} options
+ * @param {string[]} options.changedFiles - List of changed file paths
+ * @param {string} options.branchName - Current branch name
+ * @param {string} [options.model] - Claude model to use
+ * @param {number} [options.maxTokens] - Max response tokens
+ * @param {string[]} [options.reviewRules] - Custom review rules
+ * @returns {Promise<string>} The review text
+ */
+async function reviewCode(diff, options = {}) {
+    const {
+        changedFiles = [],
+        branchName = 'unknown',
+        model = 'claude-sonnet-4-20250514',
+        maxTokens = 4096,
+        reviewRules = [],
+    } = options;
+
+    const client = createClient();
+
+    const systemPrompt = buildReviewSystemPrompt({ reviewRules });
+    const userMessage = buildReviewUserPrompt(diff, changedFiles, branchName);
+
+    console.log(`🤖 Sending ${diff.length} chars of diff to Claude (${model})...`);
+
+    const response = await client.messages.create({
+        model,
+        max_tokens: maxTokens,
+        system: systemPrompt,
+        messages: [
+            { role: 'user', content: userMessage },
+        ],
+    });
+
+    const reviewText = response.content
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('\n');
+
+    return reviewText;
+}
+
+/**
+ * Parse review text to extract severity counts.
+ * @param {string} reviewText - Raw review text from Claude
+ * @returns {{ critical: number, warning: number, suggestion: number }}
+ */
+function parseSeverityCounts(reviewText) {
+    const critical = (reviewText.match(/\[SEVERITY\]\s*CRITICAL/gi) || []).length;
+    const warning = (reviewText.match(/\[SEVERITY\]\s*WARNING/gi) || []).length;
+    const suggestion = (reviewText.match(/\[SEVERITY\]\s*SUGGESTION/gi) || []).length;
+
+    return { critical, warning, suggestion };
+}
+
+module.exports = {
+    createClient,
+    reviewCode,
+    parseSeverityCounts,
+};

package/src/config.js

@@ -0,0 +1,52 @@
+const fs = require('fs');
+const path = require('path');
+const { resolveRules } = require('./rules');
+
+const CONFIG_FILENAME = '.ai-review.config.json';
+
+const DEFAULT_CONFIG = {
+    provider: '',       // 'claude' or 'gemini' — auto-detected from env vars if empty
+    baseBranch: 'main',
+    model: '',          // per-provider default applied at runtime
+    maxTokens: 4096,
+    outputDir: './reviews',
+    reviewRules: 'standard',  // preset name ('basic', 'standard', 'comprehensive') or custom array
+};
+
+/**
+ * Load configuration from .ai-review.config.json in the project root.
+ * Falls back to defaults for missing values.
+ * @param {string} [configPath] - Explicit path to config file
+ * @param {string} [cwd] - Working directory to search for config
+ * @returns {Object} Merged configuration
+ */
+function loadConfig(configPath, cwd = process.cwd()) {
+    const resolvedPath = configPath
+        ? path.resolve(cwd, configPath)
+        : path.join(cwd, CONFIG_FILENAME);
+
+    let fileConfig = {};
+
+    if (fs.existsSync(resolvedPath)) {
+        try {
+            const raw = fs.readFileSync(resolvedPath, 'utf-8');
+            fileConfig = JSON.parse(raw);
+            console.log(`📋 Loaded config from ${resolvedPath}`);
+        } catch (error) {
+            console.warn(`⚠️  Failed to parse config file ${resolvedPath}: ${error.message}`);
+        }
+    }
+
+    const merged = { ...DEFAULT_CONFIG, ...fileConfig };
+
+    // Resolve rule presets to actual rule arrays
+    merged.reviewRules = resolveRules(merged.reviewRules);
+
+    return merged;
+}
+
+module.exports = {
+    loadConfig,
+    DEFAULT_CONFIG,
+    CONFIG_FILENAME,
+};

package/src/gemini.js

@@ -0,0 +1,76 @@
+const { buildReviewSystemPrompt, buildReviewUserPrompt } = require('./prompts');
+
+/**
+ * Dynamically load the Gemini SDK.
+ * @returns {Object} The GoogleGenAI class
+ */
+function loadGeminiSDK() {
+    try {
+        return require('@google/genai');
+    } catch {
+        throw new Error(
+            'Gemini SDK not installed. Run: npm install @google/genai'
+        );
+    }
+}
+
+/**
+ * Create a Gemini client instance.
+ * @returns {Object} GoogleGenAI instance
+ */
+function createGeminiClient() {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+        throw new Error(
+            'GEMINI_API_KEY environment variable is not set.\n' +
+            'Get your API key at https://aistudio.google.com/apikey\n' +
+            'Then set it: export GEMINI_API_KEY=your-key-here'
+        );
+    }
+    const { GoogleGenAI } = loadGeminiSDK();
+    return new GoogleGenAI({ apiKey });
+}
+
+/**
+ * Send code diff to Gemini for review.
+ * @param {string} diff - The git diff content
+ * @param {Object} options
+ * @param {string[]} options.changedFiles - List of changed file paths
+ * @param {string} options.branchName - Current branch name
+ * @param {string} [options.model] - Gemini model to use
+ * @param {number} [options.maxTokens] - Max response tokens
+ * @param {string[]} [options.reviewRules] - Custom review rules
+ * @returns {Promise<string>} The review text
+ */
+async function reviewCodeWithGemini(diff, options = {}) {
+    const {
+        changedFiles = [],
+        branchName = 'unknown',
+        model = 'gemini-2.0-flash',
+        maxTokens = 4096,
+        reviewRules = [],
+    } = options;
+
+    const client = createGeminiClient();
+
+    const systemPrompt = buildReviewSystemPrompt({ reviewRules });
+    const userMessage = buildReviewUserPrompt(diff, changedFiles, branchName);
+
+    console.log(`🤖 Sending ${diff.length} chars of diff to Gemini (${model})...`);
+
+    const response = await client.models.generateContent({
+        model,
+        contents: userMessage,
+        config: {
+            systemInstruction: systemPrompt,
+            maxOutputTokens: maxTokens,
+        },
+    });
+
+    return response.text;
+}
+
+module.exports = {
+    createGeminiClient,
+    reviewCodeWithGemini,
+};

package/src/git.js

@@ -0,0 +1,113 @@
+const { execSync } = require('child_process');
+
+/**
+ * Get the diff between the current branch and a base branch.
+ * @param {string} baseBranch - The base branch to compare against (default: 'main')
+ * @param {string} cwd - Working directory (default: process.cwd())
+ * @returns {string} The git diff output
+ */
+function getDiff(baseBranch = 'main', cwd = process.cwd()) {
+    try {
+        // First try three-dot diff (for branch comparison)
+        const diff = execSync(`git diff ${baseBranch}...HEAD`, {
+            cwd,
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024, // 10MB buffer for large diffs
+        });
+
+        if (!diff.trim()) {
+            // Fallback: try two-dot diff (for uncommitted changes)
+            const uncommitted = execSync('git diff HEAD', {
+                cwd,
+                encoding: 'utf-8',
+                maxBuffer: 10 * 1024 * 1024,
+            });
+
+            if (!uncommitted.trim()) {
+                // Also check staged changes
+                const staged = execSync('git diff --cached', {
+                    cwd,
+                    encoding: 'utf-8',
+                    maxBuffer: 10 * 1024 * 1024,
+                });
+                return staged;
+            }
+            return uncommitted;
+        }
+
+        return diff;
+    } catch (error) {
+        throw new Error(`Failed to get git diff: ${error.message}`);
+    }
+}
+
+/**
+ * Get list of changed files between current branch and base branch.
+ * @param {string} baseBranch - The base branch to compare against
+ * @param {string} cwd - Working directory
+ * @returns {string[]} Array of changed file paths
+ */
+function getChangedFiles(baseBranch = 'main', cwd = process.cwd()) {
+    try {
+        const output = execSync(`git diff --name-only ${baseBranch}...HEAD`, {
+            cwd,
+            encoding: 'utf-8',
+        });
+
+        const files = output.trim().split('\n').filter(Boolean);
+
+        if (files.length === 0) {
+            // Fallback to uncommitted changes
+            const uncommitted = execSync('git diff --name-only HEAD', {
+                cwd,
+                encoding: 'utf-8',
+            });
+            return uncommitted.trim().split('\n').filter(Boolean);
+        }
+
+        return files;
+    } catch (error) {
+        throw new Error(`Failed to get changed files: ${error.message}`);
+    }
+}
+
+/**
+ * Get the current branch name.
+ * @param {string} cwd - Working directory
+ * @returns {string} Current branch name
+ */
+function getBranchName(cwd = process.cwd()) {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd,
+            encoding: 'utf-8',
+        }).trim();
+    } catch (error) {
+        throw new Error(`Failed to get branch name: ${error.message}`);
+    }
+}
+
+/**
+ * Check if we are inside a git repository.
+ * @param {string} cwd - Working directory
+ * @returns {boolean}
+ */
+function isGitRepo(cwd = process.cwd()) {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+module.exports = {
+    getDiff,
+    getChangedFiles,
+    getBranchName,
+    isGitRepo,
+};

package/src/index.js

@@ -0,0 +1,41 @@
+const { getDiff, getChangedFiles, getBranchName, isGitRepo } = require('./git');
+const { reviewCode, parseSeverityCounts, detectProvider, PROVIDERS, DEFAULT_MODELS } = require('./provider');
+const { buildFixPrompt, buildReviewSystemPrompt, buildReviewUserPrompt } = require('./prompts');
+const { loadConfig } = require('./config');
+const { writeReviewOutput, writeFixPrompt, findLatestReview } = require('./output');
+const { BASIC_RULES, STANDARD_RULES, COMPREHENSIVE_RULES, RULE_PRESETS, resolveRules } = require('./rules');
+
+module.exports = {
+    // Git utilities
+    getDiff,
+    getChangedFiles,
+    getBranchName,
+    isGitRepo,
+
+    // AI providers
+    reviewCode,
+    parseSeverityCounts,
+    detectProvider,
+    PROVIDERS,
+    DEFAULT_MODELS,
+
+    // Prompts
+    buildFixPrompt,
+    buildReviewSystemPrompt,
+    buildReviewUserPrompt,
+
+    // Config
+    loadConfig,
+
+    // Output
+    writeReviewOutput,
+    writeFixPrompt,
+    findLatestReview,
+
+    // Rules
+    BASIC_RULES,
+    STANDARD_RULES,
+    COMPREHENSIVE_RULES,
+    RULE_PRESETS,
+    resolveRules,
+};

package/src/output.js

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Ensure the output directory exists.
+ * @param {string} dir - Directory path
+ */
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+
+/**
+ * Generate a timestamped filename.
+ * @param {string} prefix - File prefix (e.g., 'review-output')
+ * @param {string} ext - File extension (e.g., '.txt')
+ * @returns {string}
+ */
+function timestampedFilename(prefix, ext = '.txt') {
+    const now = new Date();
+    const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    return `${prefix}-${ts}${ext}`;
+}
+
+/**
+ * Write the review output to a text file.
+ * @param {string} reviewText - The review content
+ * @param {string} outputDir - Output directory path
+ * @param {Object} meta - Metadata to include in the header
+ * @param {string} meta.branchName - Branch name
+ * @param {string[]} meta.changedFiles - List of changed files
+ * @param {{ critical: number, warning: number, suggestion: number }} meta.severityCounts
+ * @returns {string} Path to the written file
+ */
+function writeReviewOutput(reviewText, outputDir, meta = {}) {
+    ensureDir(outputDir);
+
+    const filename = timestampedFilename('review-output');
+    const filePath = path.join(outputDir, filename);
+
+    const header = [
+        '═'.repeat(60),
+        '  AI CODE REVIEW',
+        '═'.repeat(60),
+        `  Provider: ${meta.provider || 'unknown'}`,
+        `  Model:    ${meta.model || 'unknown'}`,
+        `  Branch:   ${meta.branchName || 'unknown'}`,
+        `  Date:     ${new Date().toISOString()}`,
+        `  Files:    ${(meta.changedFiles || []).length} changed`,
+        '',
+    ];
+
+    if (meta.severityCounts) {
+        const sc = meta.severityCounts;
+        header.push(
+            '  Severity Summary:',
+            `    🔴 CRITICAL:   ${sc.critical}`,
+            `    🟡 WARNING:    ${sc.warning}`,
+            `    🔵 SUGGESTION: ${sc.suggestion}`,
+            '',
+        );
+    }
+
+    header.push('═'.repeat(60), '');
+
+    const content = header.join('\n') + '\n' + reviewText + '\n';
+
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+}
+
+/**
+ * Write the fix prompt to a text file.
+ * @param {string} promptText - The fix prompt content
+ * @param {string} outputDir - Output directory path
+ * @returns {string} Path to the written file
+ */
+function writeFixPrompt(promptText, outputDir) {
+    ensureDir(outputDir);
+
+    const filename = timestampedFilename('fix-prompt');
+    const filePath = path.join(outputDir, filename);
+
+    const header = [
+        '═'.repeat(60),
+        '  AI FIX PROMPT — paste this into your AI agent',
+        '═'.repeat(60),
+        `  Generated: ${new Date().toISOString()}`,
+        '═'.repeat(60),
+        '',
+    ].join('\n');
+
+    fs.writeFileSync(filePath, header + '\n' + promptText + '\n', 'utf-8');
+    return filePath;
+}
+
+/**
+ * Find the most recent review output file in the output directory.
+ * @param {string} outputDir - Output directory path
+ * @returns {string|null} Path to the latest review file, or null
+ */
+function findLatestReview(outputDir) {
+    if (!fs.existsSync(outputDir)) return null;
+
+    const files = fs.readdirSync(outputDir)
+        .filter(f => f.startsWith('review-output-') && f.endsWith('.txt'))
+        .sort()
+        .reverse();
+
+    return files.length > 0 ? path.join(outputDir, files[0]) : null;
+}
+
+module.exports = {
+    writeReviewOutput,
+    writeFixPrompt,
+    findLatestReview,
+    ensureDir,
+};

package/src/prompts.js

@@ -0,0 +1,108 @@
+/**
+ * Severity levels for review findings.
+ */
+const SEVERITY_LEVELS = {
+    CRITICAL: 'CRITICAL',   // Bugs, security issues, data loss risks
+    WARNING: 'WARNING',     // Performance issues, bad practices, potential bugs
+    SUGGESTION: 'SUGGESTION', // Style, readability, minor improvements
+};
+
+/**
+ * Build the system prompt for code review.
+ * @param {Object} options
+ * @param {string[]} [options.reviewRules] - Additional custom review rules
+ * @returns {string}
+ */
+function buildReviewSystemPrompt(options = {}) {
+    const customRules = options.reviewRules
+        ? `\n\nAdditional review rules provided by the project:\n${options.reviewRules.map((r, i) => `${i + 1}. ${r}`).join('\n')}`
+        : '';
+
+    return `You are an expert code reviewer. You review git diffs and provide actionable, specific feedback.
+
+Your review MUST follow this exact output format for each finding:
+
+---
+[SEVERITY] CRITICAL | WARNING | SUGGESTION
+[FILE] <filename>
+[LINE] <line number or range, e.g., 42 or 42-50>
+[TITLE] <short summary of the issue>
+[DESCRIPTION]
+<detailed explanation of the issue>
+[FIX]
+<specific code or instructions to fix the issue>
+---
+
+Severity definitions:
+- CRITICAL: Bugs, security vulnerabilities, data loss risks, crashes, broken functionality. These MUST be fixed before merging.
+- WARNING: Performance issues, bad practices, potential future bugs, missing error handling. Should be addressed.
+- SUGGESTION: Code style, readability improvements, refactoring opportunities, documentation. Nice to have.
+
+Rules:
+1. Be specific — reference exact file names and line numbers from the diff.
+2. Provide concrete fix suggestions, not vague advice.
+3. Focus on what changed in the diff, not preexisting code.
+4. Group related issues together if they share the same root cause.
+5. At the end, provide a SUMMARY section with counts by severity level.
+6. If the code looks good, say so — don't invent issues.${customRules}`;
+}
+
+/**
+ * Build the user message for code review.
+ * @param {string} diff - The git diff content
+ * @param {string[]} changedFiles - List of changed files
+ * @param {string} branchName - Current branch name
+ * @returns {string}
+ */
+function buildReviewUserPrompt(diff, changedFiles, branchName) {
+    return `Please review the following code changes on branch "${branchName}".
+
+Changed files:
+${changedFiles.map(f => `- ${f}`).join('\n')}
+
+Git diff:
+\`\`\`diff
+${diff}
+\`\`\`
+
+Provide your review following the structured format specified in your instructions.`;
+}
+
+/**
+ * Build a prompt that an AI agent can use to automatically fix issues found in the review.
+ * @param {string} reviewText - The review output text
+ * @param {string} diff - The original git diff
+ * @returns {string}
+ */
+function buildFixPrompt(reviewText, diff) {
+    return `You are an AI coding agent. Below is a code review of recent changes, followed by the original diff.
+Your task is to fix ALL issues marked as CRITICAL and WARNING. For SUGGESTION items, fix them only if they are trivial.
+
+Apply the fixes directly to the source files. For each fix:
+1. State which file and line you are modifying.
+2. Show the exact change (before → after).
+3. Explain briefly why the change is needed.
+
+=== CODE REVIEW ===
+${reviewText}
+
+=== ORIGINAL DIFF ===
+\`\`\`diff
+${diff}
+\`\`\`
+
+=== INSTRUCTIONS ===
+- Fix CRITICAL issues first, then WARNING, then SUGGESTION.
+- Do not introduce new bugs or change unrelated code.
+- If a fix requires refactoring, explain the approach before applying.
+- Output each fix in a clear, copy-pasteable format.
+
+Begin fixing the issues now.`;
+}
+
+module.exports = {
+    SEVERITY_LEVELS,
+    buildReviewSystemPrompt,
+    buildReviewUserPrompt,
+    buildFixPrompt,
+};

package/src/provider.js

@@ -0,0 +1,84 @@
+const { reviewCode: reviewWithClaude, parseSeverityCounts } = require('./claude');
+const { reviewCodeWithGemini } = require('./gemini');
+
+/**
+ * Supported AI providers.
+ */
+const PROVIDERS = {
+    CLAUDE: 'claude',
+    GEMINI: 'gemini',
+};
+
+/**
+ * Default models per provider.
+ */
+const DEFAULT_MODELS = {
+    [PROVIDERS.CLAUDE]: 'claude-sonnet-4-20250514',
+    [PROVIDERS.GEMINI]: 'gemini-2.0-flash',
+};
+
+/**
+ * Detect which provider to use based on config and available env vars.
+ * Priority: explicit config > available API key.
+ * @param {Object} config - Loaded config
+ * @returns {string} provider name
+ */
+function detectProvider(config) {
+    // Explicit config takes priority
+    if (config.provider) {
+        return config.provider.toLowerCase();
+    }
+
+    // Auto-detect from available API keys
+    if (process.env.ANTHROPIC_API_KEY) return PROVIDERS.CLAUDE;
+    if (process.env.GEMINI_API_KEY) return PROVIDERS.GEMINI;
+
+    throw new Error(
+        'No AI provider configured.\n' +
+        'Either set "provider" in .ai-review.config.json, or set one of:\n' +
+        '  - ANTHROPIC_API_KEY for Claude\n' +
+        '  - GEMINI_API_KEY for Gemini'
+    );
+}
+
+/**
+ * Review code using the configured AI provider.
+ * @param {string} diff - The git diff content
+ * @param {Object} options - Review options
+ * @param {string} options.provider - AI provider ('claude' or 'gemini')
+ * @param {string[]} options.changedFiles
+ * @param {string} options.branchName
+ * @param {string} [options.model]
+ * @param {number} [options.maxTokens]
+ * @param {string[]} [options.reviewRules]
+ * @returns {Promise<string>} Review text
+ */
+async function reviewCode(diff, options = {}) {
+    const provider = options.provider || PROVIDERS.CLAUDE;
+
+    // Use provider-specific default model if not explicitly set
+    const model = options.model || DEFAULT_MODELS[provider];
+
+    const reviewOptions = { ...options, model };
+
+    switch (provider) {
+        case PROVIDERS.CLAUDE:
+            return reviewWithClaude(diff, reviewOptions);
+
+        case PROVIDERS.GEMINI:
+            return reviewCodeWithGemini(diff, reviewOptions);
+
+        default:
+            throw new Error(
+                `Unknown provider: "${provider}". Supported: ${Object.values(PROVIDERS).join(', ')}`
+            );
+    }
+}
+
+module.exports = {
+    PROVIDERS,
+    DEFAULT_MODELS,
+    detectProvider,
+    reviewCode,
+    parseSeverityCounts,
+};

package/src/rules.js

@@ -0,0 +1,97 @@
+/**
+ * Default review rule sets that can be used out of the box.
+ * Users can reference these by name in .ai-review.config.json
+ * or customize their own rules.
+ */
+
+/**
+ * Basic rules — lightweight, fast review for quick PRs.
+ */
+const BASIC_RULES = [
+    'Check for syntax errors and typos',
+    'Flag unused variables and dead code',
+    'Check for console.log or debug statements left in production code',
+    'Verify error handling exists for async operations',
+    'Check for hardcoded secrets, API keys, or passwords',
+];
+
+/**
+ * Standard rules — balanced review covering common issues.
+ */
+const STANDARD_RULES = [
+    ...BASIC_RULES,
+    'Check for proper input validation and sanitization',
+    'Verify functions have clear, descriptive names',
+    'Flag overly complex functions (too many parameters, deep nesting, long functions)',
+    'Check for missing or incorrect error messages',
+    'Verify proper use of const/let (no unnecessary var usage)',
+    'Check for potential null/undefined reference errors',
+    'Flag duplicated code that could be extracted into reusable functions',
+    'Verify that async/await and Promises are used correctly',
+    'Check for proper resource cleanup (event listeners, timers, connections)',
+];
+
+/**
+ * Comprehensive rules — thorough review for critical code.
+ */
+const COMPREHENSIVE_RULES = [
+    ...STANDARD_RULES,
+    'Check for SQL injection, XSS, and other security vulnerabilities',
+    'Verify proper authentication and authorization checks',
+    'Review error handling strategy — are errors logged, reported, and recoverable?',
+    'Check for race conditions in concurrent or async code',
+    'Verify proper memory management (no memory leaks, large object retention)',
+    'Check for proper HTTP status codes and API response formats',
+    'Review database queries for N+1 problems and missing indexes',
+    'Verify backward compatibility — will this break existing clients or APIs?',
+    'Check for accessibility issues in UI code (ARIA labels, keyboard navigation)',
+    'Review test coverage — are edge cases and error paths tested?',
+    'Check for proper logging with appropriate log levels',
+    'Verify that environment-specific config is not hardcoded',
+    'Check for proper handling of edge cases (empty arrays, zero values, boundary conditions)',
+    'Review for performance issues (unnecessary re-renders, expensive computations in loops)',
+];
+
+/**
+ * Named rule presets that can be referenced in config.
+ */
+const RULE_PRESETS = {
+    basic: BASIC_RULES,
+    standard: STANDARD_RULES,
+    comprehensive: COMPREHENSIVE_RULES,
+};
+
+/**
+ * Resolve review rules from config.
+ * Accepts a preset name (string) or custom rules array.
+ * @param {string|string[]} rulesConfig - Preset name or custom rules
+ * @returns {string[]} Resolved rules
+ */
+function resolveRules(rulesConfig) {
+    if (!rulesConfig || (Array.isArray(rulesConfig) && rulesConfig.length === 0)) {
+        return STANDARD_RULES; // Default to standard if nothing specified
+    }
+
+    if (typeof rulesConfig === 'string') {
+        const preset = RULE_PRESETS[rulesConfig.toLowerCase()];
+        if (!preset) {
+            console.warn(`⚠️  Unknown rule preset: "${rulesConfig}". Using "standard".`);
+            return STANDARD_RULES;
+        }
+        return preset;
+    }
+
+    if (Array.isArray(rulesConfig)) {
+        return rulesConfig;
+    }
+
+    return STANDARD_RULES;
+}
+
+module.exports = {
+    BASIC_RULES,
+    STANDARD_RULES,
+    COMPREHENSIVE_RULES,
+    RULE_PRESETS,
+    resolveRules,
+};