git-diff-ai-reviewer 1.1.3 → 1.2.0

package/README.md

@@ -1,6 +1,15 @@
 # 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.
+AI-powered code review tool using **Claude** or **Gemini** APIs. Reviews git branch diffs with full code context, iterative AI follow-ups, and structured severity-tagged feedback.
+
+## Features
+
+- 🔍 **Context-aware review** — sends not just the diff, but the full functions, imports, and callers of changed code
+- 🔄 **Iterative context gathering** — if the AI needs more context, it asks for it automatically (configurable rounds)
+- 🚀 **Pre-push hook** — automatically review code before every `git push`
+- 🎯 **Severity levels** — CRITICAL, WARNING, SUGGESTION with CI-friendly exit codes
+- 🔧 **Fix prompt generation** — auto-generate prompts for AI agents to fix issues
+- ⚙️ **Configurable rules** — built-in presets or custom review rules
 
 ## Installation
 
@@ -59,7 +68,7 @@ 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
+# Preview diff and context without calling API
 git-diff-ai-reviewer review --dry-run
 
 # Generate fix prompt from latest review
@@ -79,6 +88,71 @@ Add to your `package.json`:
 }
 ```
 
+## Pre-Push Hook (Review on Push)
+
+Automatically run an AI code review before every `git push`. If CRITICAL issues are found, the push is blocked.
+
+### Install the hook
+
+```bash
+git-diff-ai-reviewer hook install
+```
+
+This creates a `.git/hooks/pre-push` script that runs the review before each push.
+
+### Skip a review
+
+Sometimes you need to push without waiting for a review:
+
+```bash
+# Option 1: Environment variable
+GIT_SKIP_REVIEW=1 git push
+
+# Option 2: Git's built-in flag (skips all hooks)
+git push --no-verify
+```
+
+### Uninstall the hook
+
+```bash
+git-diff-ai-reviewer hook uninstall
+```
+
+### Check hook status
+
+```bash
+git-diff-ai-reviewer hook status
+```
+
+### How it works
+
+| Review result | Push behavior |
+|---------------|---------------|
+| ✅ No critical issues | Push proceeds |
+| ❌ CRITICAL issues found | Push blocked (exit code 1) |
+| ⚠️ Review error (API down, etc.) | Push proceeds (fails open) |
+
+## Context-Aware Review
+
+Unlike simple diff-only review tools, `git-diff-ai-reviewer` automatically gathers context for each change:
+
+1. **Function context** — extracts the full body of every function/class that was modified
+2. **Imports** — includes the import/require statements from each changed file
+3. **Callers** — finds where modified functions are used across the project (via `git grep`)
+
+This context is sent alongside the diff, giving the AI a much deeper understanding of the changes.
+
+### Iterative Context Requests
+
+If the AI determines it needs more context to give a thorough review, it can request:
+
+- Specific file ranges (`FILE: path/to/file.js LINES: 10-50`)
+- Function definitions (`FILE: path/to/file.js FUNCTION: helperName`)
+- Caller/usage information (`CALLERS: functionName`)
+- Full file contents (`FILE: path/to/config.json`)
+
+The tool automatically fulfills these requests and continues the conversation, up to `maxContextRounds` times (default: 3).
+
 ## Providers
 
 | Provider | Env Variable | Default Model |
@@ -135,8 +209,12 @@ Create `.ai-review.config.json` in your project root:
   "baseBranch": "main",
   "model": "gemini-2.0-flash",
   "maxTokens": 4096,
+  "maxContextRounds": 3,
   "outputDir": "./reviews",
-  "reviewRules": "standard"
+  "reviewRules": {
+    "preset": "standard",
+    "extend": []
+  }
 }
 ```
 
@@ -148,23 +226,39 @@ Create `.ai-review.config.json` in your project root:
 | `baseBranch` | string | `"main"` | Branch to compare against |
 | `model` | string | per-provider | Override the AI model |
 | `maxTokens` | number | `4096` | Max response tokens |
+| `maxContextRounds` | number | `3` | Max iterative context follow-up rounds |
 | `outputDir` | string | `"./reviews"` | Where to write output files |
 | `reviewRules` | string\|array | `"standard"` | Preset name or custom rules array |
 
 ### Custom Rules Example
 
+You can completely replace the rules by providing an array:
+
 ```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"
+    "All functions must have JSDoc comments"
   ]
 }
 ```
 
+Or **extend** an existing preset with your own project-specific rules:
+
+```json
+{
+  "provider": "gemini",
+  "reviewRules": {
+    "preset": "standard",
+    "extend": [
+      "No inline styles in React components",
+      "Database queries must use parameterized statements"
+    ]
+  }
+}
+```
+
 ## Programmatic API
 
 ```javascript
@@ -173,18 +267,30 @@ const {
   getDiff,
   getChangedFiles,
   detectProvider,
+  buildInitialContext,
+  formatContextForPrompt,
+  installHook,
   STANDARD_RULES,
 } = require('git-diff-ai-reviewer');
 
+// Review with context
 const diff = getDiff('main');
 const files = getChangedFiles('main');
-const provider = detectProvider({ provider: 'gemini' });
+const context = buildInitialContext(diff, files);
+const formattedContext = formatContextForPrompt(context);
+
 const review = await reviewCode(diff, {
-  provider,
+  provider: 'gemini',
   changedFiles: files,
   branchName: 'feature/xyz',
+  formattedContext,
+  maxContextRounds: 3,
   reviewRules: STANDARD_RULES,
 });
+
+// Install pre-push hook programmatically
+const result = installHook();
+console.log(result.message);
 ```
 
 ## Output Files

package/bin/review.js

@@ -8,6 +8,8 @@ const { reviewCode, parseSeverityCounts, detectProvider, PROVIDERS, DEFAULT_MODE
 const { buildFixPrompt } = require('../src/prompts');
 const { loadConfig } = require('../src/config');
 const { writeReviewOutput, writeFixPrompt, findLatestReview } = require('../src/output');
+const { buildInitialContext, formatContextForPrompt } = require('../src/context');
+const { installHook, uninstallHook, hookStatus } = require('../src/hooks');
 
 // ─── Argument Parsing ────────────────────────────────────────────────
 
@@ -45,10 +47,15 @@ function parseArgs(argv) {
             case '-h':
                 flags.help = true;
                 break;
+            case '--skip-review':
+                flags.skipReview = true;
+                break;
             default:
                 if (!args[i].startsWith('-') && !command) {
                     command = args[i];
-                } else {
+                } else if (!args[i].startsWith('-') && command === 'hook') {
+                    // Hook subcommands are parsed separately
+                } else if (args[i].startsWith('-')) {
                     console.warn(`Unknown option: ${args[i]}`);
                 }
         }
@@ -65,11 +72,14 @@ function showHelp() {
 ║              🤖 AI Code Review CLI                   ║
 ╚══════════════════════════════════════════════════════╝
 
-Usage: ai-review <command> [options]
+Usage: git-diff-ai-reviewer <command> [options]
 
 Commands:
-  review    Review code changes using AI (default)
-  fix       Generate a fix prompt from the latest review
+  review          Review code changes using AI (default)
+  fix             Generate a fix prompt from the latest review
+  hook install    Install pre-push git hook (review before push)
+  hook uninstall  Remove the pre-push git hook
+  hook status     Check if the pre-push hook is installed
 
 Options:
   -b, --base <branch>      Base branch to compare against (default: main)
@@ -94,12 +104,19 @@ Review Rule Presets:
   standard        Balanced everyday review (default)
   comprehensive   Full audit for critical code
 
+Pre-Push Hook:
+  Install:   git-diff-ai-reviewer hook install
+  Uninstall: git-diff-ai-reviewer hook uninstall
+  Skip once: GIT_SKIP_REVIEW=1 git push
+  Skip once: git push --no-verify
+
 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
+  git-diff-ai-reviewer review                    Review with auto-detected provider
+  git-diff-ai-reviewer review --provider gemini   Review using Gemini
+  git-diff-ai-reviewer review --base develop      Review against develop branch
+  git-diff-ai-reviewer review --dry-run           Preview without calling API
+  git-diff-ai-reviewer fix                        Generate fix prompt from latest review
+  git-diff-ai-reviewer hook install               Enable review-on-push
 
 Config File (.ai-review.config.json):
   {
@@ -107,6 +124,7 @@ Config File (.ai-review.config.json):
     "baseBranch": "main",
     "model": "",
     "maxTokens": 4096,
+    "maxContextRounds": 3,
     "outputDir": "./reviews",
     "reviewRules": "standard"
   }
@@ -150,14 +168,30 @@ async function commandReview(config, flags) {
     console.log(`  Diff size:  ${diff.length} characters`);
     console.log('─'.repeat(40));
 
+    // Gather code context
+    console.log('\n📦 Gathering code context...');
+    const context = buildInitialContext(diff, changedFiles);
+    const formattedContext = formatContextForPrompt(context);
+
+    const contextFunctions = context.files.reduce((sum, f) => sum + f.functions.length, 0);
+    const contextCallers = context.files.reduce((sum, f) => sum + f.callers.length, 0);
+    console.log(`   ${contextFunctions} function(s) extracted, ${contextCallers} caller group(s) found`);
+    if (formattedContext) {
+        console.log(`   Context size: ${formattedContext.length} characters`);
+    }
+
     // 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(`Context:  ${contextFunctions} function(s), ${contextCallers} caller group(s)`);
         console.log('Changed files:');
         changedFiles.forEach(f => console.log(`  - ${f}`));
         console.log(`\nDiff preview (first 500 chars):\n${diff.slice(0, 500)}...`);
+        if (formattedContext) {
+            console.log(`\nContext preview (first 500 chars):\n${formattedContext.slice(0, 500)}...`);
+        }
         console.log('\n💡 Remove --dry-run to send to AI for review.');
         process.exit(0);
     }
@@ -173,6 +207,8 @@ async function commandReview(config, flags) {
             model,
             maxTokens: config.maxTokens,
             reviewRules: config.reviewRules,
+            formattedContext,
+            maxContextRounds: config.maxContextRounds,
         });
 
         // Parse severity counts
@@ -245,6 +281,67 @@ async function commandFix(config, flags) {
     console.log('');
 }
 
+// ─── Hook Command ───────────────────────────────────────────────────
+
+function commandHook(subcommand) {
+    switch (subcommand) {
+        case 'install': {
+            const result = installHook();
+            if (result.success) {
+                console.log('');
+                console.log('✅ ' + result.message);
+                console.log(`   📄 ${result.path}`);
+                console.log('');
+                console.log('   The AI review will run automatically before each push.');
+                console.log('   To skip a review:');
+                console.log('     GIT_SKIP_REVIEW=1 git push');
+                console.log('     git push --no-verify');
+                console.log('');
+            } else {
+                console.error('');
+                console.error('❌ ' + result.message);
+                console.error('');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'uninstall': {
+            const result = uninstallHook();
+            if (result.success) {
+                console.log('');
+                console.log('✅ ' + result.message);
+                console.log('');
+            } else {
+                console.error('');
+                console.error('❌ ' + result.message);
+                console.error('');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'status': {
+            const result = hookStatus();
+            console.log('');
+            if (!result.installed) {
+                console.log('📋 Pre-push hook: not installed');
+                console.log('   Run "git-diff-ai-reviewer hook install" to enable.');
+            } else if (result.ours) {
+                console.log('📋 Pre-push hook: ✅ installed (by git-diff-ai-reviewer)');
+                console.log(`   📄 ${result.path}`);
+            } else {
+                console.log('📋 Pre-push hook: ⚠️  installed (by another tool)');
+                console.log(`   📄 ${result.path}`);
+            }
+            console.log('');
+            break;
+        }
+        default:
+            console.error('❌ Unknown hook subcommand: ' + (subcommand || '(none)'));
+            console.error('   Usage: git-diff-ai-reviewer hook <install|uninstall|status>');
+            process.exit(1);
+    }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────
 
 async function main() {
@@ -264,6 +361,15 @@ async function main() {
     // Load config
     const config = loadConfig(flags.configPath);
 
+    // Handle 'hook' command — parse subcommand from argv
+    if (command === 'hook') {
+        const args = process.argv.slice(2);
+        const hookIdx = args.indexOf('hook');
+        const subcommand = args[hookIdx + 1];
+        commandHook(subcommand);
+        return;
+    }
+
     switch (command) {
         case 'review':
             await commandReview(config, flags);
@@ -273,7 +379,7 @@ async function main() {
             break;
         default:
             console.error(`❌ Unknown command: ${command}`);
-            console.error('   Run "ai-review --help" for usage info.');
+            console.error('   Run "git-diff-ai-reviewer --help" for usage info.');
             process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-diff-ai-reviewer",
-  "version": "1.1.3",
+  "version": "1.2.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": {

package/src/claude.js

@@ -1,4 +1,5 @@
-const { buildReviewSystemPrompt, buildReviewUserPrompt } = require('./prompts');
+const { buildReviewSystemPrompt, buildReviewUserPromptWithContext, buildReviewUserPrompt, buildFollowUpContextMessage } = require('./prompts');
+const { fulfillContextRequest, formatFollowUpContext } = require('./context');
 
 /**
  * Dynamically load the Anthropic SDK.
@@ -32,7 +33,7 @@ function createClient() {
 }
 
 /**
- * Send code diff to Claude for review.
+ * Send code diff to Claude for review with iterative context gathering.
  * @param {string} diff - The git diff content
  * @param {Object} options
  * @param {string[]} options.changedFiles - List of changed file paths
@@ -40,6 +41,8 @@ function createClient() {
  * @param {string} [options.model] - Claude model to use
  * @param {number} [options.maxTokens] - Max response tokens
  * @param {string[]} [options.reviewRules] - Custom review rules
+ * @param {string} [options.formattedContext] - Pre-formatted context string
+ * @param {number} [options.maxContextRounds] - Max follow-up context rounds
  * @returns {Promise<string>} The review text
  */
 async function reviewCode(diff, options = {}) {
@@ -49,28 +52,74 @@ async function reviewCode(diff, options = {}) {
         model = 'claude-sonnet-4-20250514',
         maxTokens = 4096,
         reviewRules = [],
+        formattedContext = '',
+        maxContextRounds = 3,
     } = options;
 
     const client = createClient();
 
     const systemPrompt = buildReviewSystemPrompt({ reviewRules });
-    const userMessage = buildReviewUserPrompt(diff, changedFiles, branchName);
+
+    // Build initial message — with or without context
+    const userMessage = formattedContext
+        ? buildReviewUserPromptWithContext(diff, changedFiles, branchName, formattedContext)
+        : buildReviewUserPrompt(diff, changedFiles, branchName);
 
     console.log(`🤖 Sending ${diff.length} chars of diff to Claude (${model})...`);
+    if (formattedContext) {
+        console.log(`📦 Including code context (${formattedContext.length} chars)`);
+    }
+
+    // Conversation history for multi-turn
+    const messages = [
+        { role: 'user', content: userMessage },
+    ];
+
+    let reviewText = '';
+    let round = 0;
+
+    while (round <= maxContextRounds) {
+        const response = await client.messages.create({
+            model,
+            max_tokens: maxTokens,
+            system: systemPrompt,
+            messages,
+        });
+
+        const responseText = response.content
+            .filter(block => block.type === 'text')
+            .map(block => block.text)
+            .join('\n');
 
-    const response = await client.messages.create({
-        model,
-        max_tokens: maxTokens,
-        system: systemPrompt,
-        messages: [
-            { role: 'user', content: userMessage },
-        ],
-    });
+        // Check if AI is requesting more context
+        const { hasRequest, contextData, cleanResponse } = fulfillContextRequest(responseText);
 
-    const reviewText = response.content
-        .filter(block => block.type === 'text')
-        .map(block => block.text)
-        .join('\n');
+        if (hasRequest && round < maxContextRounds) {
+            round++;
+            console.log(`🔄 AI requested more context (round ${round}/${maxContextRounds})...`);
+            console.log(`   Fulfilling ${contextData.length} context request(s)...`);
+
+            // Add assistant response to history
+            messages.push({ role: 'assistant', content: responseText });
+
+            // Fulfill the request and add as user message
+            const followUpText = formatFollowUpContext(contextData);
+            const followUpMessage = buildFollowUpContextMessage(followUpText);
+            messages.push({ role: 'user', content: followUpMessage });
+
+            // If there was a partial review in the response, keep it
+            if (cleanResponse.trim()) {
+                reviewText = cleanResponse + '\n\n';
+            }
+        } else {
+            // No more context requests — this is the final review
+            reviewText += hasRequest ? cleanResponse : responseText;
+            if (round > 0) {
+                console.log(`✅ Context gathering complete after ${round} round(s).`);
+            }
+            break;
+        }
+    }
 
     return reviewText;
 }
@@ -93,3 +142,4 @@ module.exports = {
     reviewCode,
     parseSeverityCounts,
 };
+

package/src/config.js

@@ -11,6 +11,7 @@ const DEFAULT_CONFIG = {
     maxTokens: 4096,
     outputDir: './reviews',
     reviewRules: 'standard',  // preset name ('basic', 'standard', 'comprehensive') or custom array
+    maxContextRounds: 3,      // max follow-up context rounds for iterative review
 };
 
 /**