ai-commit-guard

v1.3.1

Published

6 months ago

AI-powered pre-commit code review tool that works with any programming language and framework

AI Commit Guard

🤖 Universal AI-powered pre-commit code review tool that automatically checks your code changes before commit using multiple AI providers.

🎯 Stop bugs before they reach your repository! Get instant AI feedback on every commit across all your projects - from JavaScript to Python, from Dockerfiles to YAML configs.

✨ Features

🌍 Universal Language Support - Works with ANY file type (JavaScript, Python, Go, Rust, C++, HTML, CSS, YAML, Dockerfile, Markdown, etc.)
🤖 5 AI Providers - OpenAI GPT-4, Anthropic Claude, Google Gemini, Cohere, Ollama (local)
🚀 Lightning Fast - Cached results with smart binary file detection
🎯 Custom Rules - Define your own coding standards in natural language
🛡️ Security First - Auto-masks secrets, ignores sensitive files, smart filtering
🔧 Zero Config - Works out of the box with sensible defaults
⏱️ Timeout Protection - Graceful handling with configurable timeouts
🎨 Beautiful Output - Colorized, readable feedback with smart formatting
📊 Commit Tracking - Flags show which commits were AI-reviewed
🔄 Modern Husky Support - No deprecated warnings, clean setup

🚀 Quick Start

1. Install Globally

npm install -g ai-commit-guard

2. Setup in Your Project

# One command setup - works in any git repository
ai-commit-guard --setup

3. Set Your AI API Key

Choose your preferred AI provider:

# OpenAI (Recommended)
export OPENAI_API_KEY="sk-your-openai-key-here"

# Anthropic Claude
export CLAUDE_API_KEY="sk-ant-your-claude-key-here"
export AI_PROVIDER="claude"

# Google Gemini
export GEMINI_API_KEY="your-gemini-api-key"
export AI_PROVIDER="gemini"

# Cohere
export COHERE_API_KEY="your-cohere-api-key"
export AI_PROVIDER="cohere"

# Ollama (Local - Free!)
export AI_PROVIDER="ollama"
# No API key needed - runs locally

4. That's It! 🎉

Now AI Guard will automatically review your code on every commit:

git add .
git commit -m "feat: add user authentication system"
# → AI Guard automatically reviews your changes

🌐 Universal Language Support

Works with ANY programming language and file type - no configuration needed!

💻 Programming Languages

✅ JavaScript, TypeScript, Python, Go, Rust, Java, C++, C#, PHP, Ruby
✅ Kotlin, Swift, Dart, Scala, Clojure, Elixir, Haskell, F#
✅ Shell scripts, PowerShell, Batch files

🌐 Web Technologies

✅ HTML, CSS, SCSS, SASS, Less, Stylus
✅ React (JSX/TSX), Vue, Angular, Svelte, Next.js, Nuxt.js
✅ Node.js, Express, FastAPI, Django, Rails

⚙️ DevOps & Infrastructure

✅ Docker (Dockerfile, docker-compose.yml)
✅ Kubernetes (YAML manifests, Helm charts)
✅ Terraform, Ansible, CloudFormation, Pulumi
✅ GitHub Actions, GitLab CI, Jenkins, CircleCI

📄 Configuration & Data

✅ JSON, YAML, TOML, INI, XML, HCL
✅ Environment files (.env, .envrc)
✅ Config files (nginx.conf, apache.conf, etc.)

📚 Documentation & Database

✅ Markdown, reStructuredText, AsciiDoc
✅ SQL, NoSQL queries, Prisma schema, GraphQL
✅ API specs (OpenAPI, Swagger, Postman)

📊 Example Output

✅ Clean Code (Passes Review):

ℹ️  🔍 Checking staged files...
ℹ️  🔒 Ignored 2 binary/sensitive files
ℹ️  📝 Reviewing 3 files using OPENAI...
🤖 Sending to OPENAI for review (timeout: 30s)...
✅ Code review passed!
ℹ️  Added flag: [AI-REVIEW-PASSED]

❌ Issues Found (Blocks Commit):

ℹ️  🔍 Checking staged files...
ℹ️  📝 Reviewing 2 files using CLAUDE...
🤖 Sending to CLAUDE for review (timeout: 45s)...
❌ Code review failed!

  1. **Exposed Secret**: API key hardcoded in config.js line 12
     Fix: Move to environment variable process.env.API_KEY

  2. **Magic String**: 'active' used directly in user.js line 25  
     Fix: Use named constant USER_STATUS.ACTIVE

  3. **Missing Error Handling**: No try-catch in async function
     Fix: Add proper error handling for database operations

⏱️ Timeout (Allows Commit with Flag):

🤖 Sending to GEMINI for review (timeout: 30s)...
⚠️  AI review timed out after 30 seconds
ℹ️  Added flag: [AI-REVIEW-FAILED-TIMEOUT]
✅ Commit completed with AI review flag

📋 Configuration (Optional)

🎯 Custom Coding Rules (`.code-rules.md`)

Create project-specific rules in natural language:

# My Project Code Review Rules

## Security Requirements
- Never commit API keys, passwords, or tokens
- All user inputs must be validated and sanitized
- Use parameterized queries for database operations
- Implement proper authentication for all endpoints

## Code Quality Standards  
- Functions should be under 25 lines
- Use TypeScript interfaces for all data structures
- Add JSDoc comments for public functions
- Follow single responsibility principle

## Project-Specific Rules
- All React components must have PropTypes or TypeScript types
- Use our custom error handling utility for async operations
- Database queries must include proper indexing considerations
- API responses must follow our standard format

## Framework Guidelines
### React/Next.js
- Use hooks instead of class components
- Implement proper loading and error states
- Use Next.js Image component for optimization

### Node.js/Express
- Always use middleware for request validation
- Implement rate limiting for public endpoints
- Use structured logging with correlation IDs

🚫 Ignore Patterns (`.ai-guard-ignore`)

Exclude files from AI review:

# Sensitive files (automatically ignored by default)
*.env*
*.key
*secret*
*password*
*credential*

# Generated/Build files
dist/*
build/*
out/*
coverage/*
node_modules/*

# Large dependencies
vendor/*
public/vendor/*
*.min.js
*.bundle.*
package-lock.json

# Project-specific
legacy-code/*
third-party/*
generated-schema.ts
*.generated.*

⚙️ Environment Variables

Fine-tune AI Guard behavior:

# AI Provider Configuration
export AI_PROVIDER="openai"              # openai|claude|gemini|cohere|ollama
export AI_MODEL="gpt-4"                  # Specific model to use
export OPENAI_API_KEY="sk-your-key"      # Your API key

# Performance Tuning
export AI_GUARD_TIMEOUT=45000            # Review timeout (45 seconds)
export AI_GUARD_MAX_FILE_SIZE=100000     # Max file size (100KB)

# Advanced Configuration
export AI_GUARD_CACHE_DURATION=86400000  # Cache duration (24 hours)
export AI_GUARD_RETRY_COUNT=3            # Number of retries on failure

🔧 Advanced Usage

🎛️ Multiple AI Providers

Switch between providers based on your needs:

# Use OpenAI for general code review
export AI_PROVIDER="openai"
export OPENAI_API_KEY="sk-your-openai-key"

# Switch to Claude for complex logic review  
export AI_PROVIDER="claude"
export CLAUDE_API_KEY="sk-ant-your-claude-key"

# Use Ollama for private/sensitive code (runs locally)
export AI_PROVIDER="ollama"
export AI_MODEL="codellama"  # or deepseek-coder, starcoder, etc.

⏱️ Timeout Configuration

Adjust timeouts based on project size:

# Quick reviews for small changes
export AI_GUARD_TIMEOUT=15000  # 15 seconds

# Longer timeout for large refactors
export AI_GUARD_TIMEOUT=60000  # 60 seconds

# Maximum timeout for complex projects
export AI_GUARD_TIMEOUT=120000 # 2 minutes

🎯 Project-Specific Setup

Different configurations for different projects:

# Frontend project - focus on React/TypeScript
echo "Focus on React best practices, TypeScript usage, and accessibility" > .code-rules.md

# Backend API - focus on security and performance  
echo "Prioritize security, error handling, and API design" > .code-rules.md

# DevOps repository - focus on infrastructure
echo "Review Terraform syntax, security groups, and resource naming" > .code-rules.md

🔄 CI/CD Integration

Use in continuous integration:

# GitHub Actions example
name: AI Code Review
on: [pull_request]
jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g ai-commit-guard
      - run: ai-commit-guard --setup
      - run: git add . && ai-commit-guard
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

🏷️ Commit Message Flags

AI Guard automatically adds flags to track review status:

| Flag | Meaning | Action Needed | |------|---------|---------------| | [AI-REVIEW-PASSED] | ✅ AI approved the changes | None - code is good | | [AI-REVIEW-FAILED-TIMEOUT] | ⏱️ Review timed out | Manual review recommended | | [AI-REVIEW-SKIPPED-ERROR] | ❌ Error occurred (no API key, etc.) | Check configuration | | No flag | 🚫 AI review failed - commit blocked | Fix issues and retry |

📊 Team Analytics

Track AI review coverage across your team:

# Check review coverage in recent commits
git log --oneline --grep="AI-REVIEW" | wc -l

# Find commits that need manual review
git log --oneline --grep="TIMEOUT\|ERROR" --since="1 week ago"

# Show successful AI reviews
git log --oneline --grep="AI-REVIEW-PASSED" --since="1 month ago"

🆚 Why Choose AI Commit Guard?

vs ESLint/Prettier

✅ Language Agnostic - Works with any language, not just JavaScript
✅ Context Aware - Understands business logic, not just syntax
✅ Custom Rules - Natural language rules vs complex configuration
✅ Security Focus - Automatically detects exposed secrets and vulnerabilities

vs SonarQube

✅ Instant Feedback - Pre-commit vs post-commit analysis
✅ Zero Setup - No server installation or complex configuration
✅ AI-Powered - Intelligent analysis vs pattern matching
✅ Cost Effective - Pay-per-use vs enterprise licensing

vs Manual Code Review

✅ Consistent - Same standards applied every time
✅ Fast - Instant feedback vs waiting for reviewers
✅ Educational - Teaches best practices to junior developers
✅ 24/7 Available - No dependency on team availability

🎯 Use Cases

🏢 Enterprise Teams

Enforce consistent coding standards across multiple teams
Catch security vulnerabilities before they reach production
Reduce code review time by pre-filtering obvious issues
Onboard new developers with automated mentoring

🚀 Startups

Move fast without breaking quality standards
Catch issues early when you can't afford technical debt
Scale code quality as your team grows
Focus senior developers on architecture, not basic reviews

👨‍🎓 Educational

Learn best practices through immediate feedback
Understand security concepts through real examples
Improve code quality incrementally
Get explanations for why changes are needed

🔒 Security-Critical Projects

Automatically detect exposed secrets and credentials
Catch injection vulnerabilities before commit
Enforce secure coding practices consistently
Maintain audit trail of all code changes

🐛 Troubleshooting

Common Issues

"No AI API key found"

# Check if environment variables are set
env | grep -E "(OPENAI|CLAUDE|GEMINI|COHERE)_API_KEY"

# Set API key for current session
export OPENAI_API_KEY="sk-your-actual-key"

# Make permanent (add to shell profile)
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc

"AI review timed out"

# Increase timeout for large projects
export AI_GUARD_TIMEOUT=60000  # 60 seconds

# Check network connectivity
curl -I https://api.openai.com

# Try with smaller changesets
git add specific-file.js  # Instead of git add .

# Use faster provider
export AI_PROVIDER="gemini"  # Often faster than OpenAI

# Use local Ollama for no network dependency
export AI_PROVIDER="ollama"

"Too many files being reviewed"

# Check what files are being processed
git diff --cached --name-only

# Add patterns to ignore large files
echo "dist/*" >> .ai-guard-ignore
echo "*.min.js" >> .ai-guard-ignore
echo "package-lock.json" >> .ai-guard-ignore

# Reduce file size limit
export AI_GUARD_MAX_FILE_SIZE=25000  # 25KB

# Stage files incrementally
git add src/components/  # Review by directory
git commit -m "feat: update components"
git add src/utils/
git commit -m "feat: update utilities"

"Husky deprecated warnings"

# Remove old husky configuration
rm -rf .husky
rm .huskyrc*

# Reinstall with modern setup
npx ai-commit-guard --setup

# Manual fix if needed
echo "npx ai-commit-guard" > .husky/pre-commit
echo 'npx ai-commit-guard --commit-msg "$1"' > .husky/commit-msg
chmod +x .husky/*

"Binary files being reviewed"

# Check git's binary detection
git diff --cached --numstat

# Add file types to ignore
echo "*.pdf" >> .ai-guard-ignore
echo "*.jpg" >> .ai-guard-ignore
echo "*.png" >> .ai-guard-ignore

# Check current ignore patterns
cat .ai-guard-ignore

"Cache issues"

# Clear cache to force fresh review
rm -rf .ai-guard-cache

# Check cache size
du -sh .ai-guard-cache

# Disable cache temporarily
export AI_GUARD_CACHE_DURATION=0

Performance Tips

# ⚡ Optimize for speed
export AI_PROVIDER="gemini"          # Fastest provider
export AI_GUARD_TIMEOUT=20000        # Shorter timeout
export AI_GUARD_MAX_FILE_SIZE=30000  # Smaller files

# 🎯 Optimize for accuracy  
export AI_PROVIDER="claude"          # Best code understanding
export AI_GUARD_TIMEOUT=60000        # Longer timeout
export AI_MODEL="claude-3-opus"      # Most capable model

# 🔒 Optimize for privacy
export AI_PROVIDER="ollama"          # Local processing
export AI_MODEL="codellama"          # Good code model
# No API key needed, runs entirely local

📊 Analytics & Monitoring

Review Statistics

Track your AI review effectiveness:

# Total commits with AI review
git log --grep="AI-REVIEW" --oneline | wc -l

# Success rate
git log --grep="AI-REVIEW-PASSED" --oneline | wc -l

# Timeout rate  
git log --grep="TIMEOUT" --oneline | wc -l

# Recent review activity
git log --grep="AI-REVIEW" --since="1 week ago" --pretty=format:"%h %s"

Team Dashboard Script

#!/bin/bash
# ai-guard-stats.sh - Team AI review dashboard

echo "🤖 AI Commit Guard Team Statistics"
echo "=================================="

# Total commits in last 30 days
total=$(git log --since="30 days ago" --oneline | wc -l)
echo "📊 Total commits (30 days): $total"

# AI reviewed commits
reviewed=$(git log --since="30 days ago" --grep="AI-REVIEW" --oneline | wc -l)
echo "🤖 AI reviewed commits: $reviewed"

# Success rate
passed=$(git log --since="30 days ago" --grep="AI-REVIEW-PASSED" --oneline | wc -l)
echo "✅ Successful reviews: $passed"

# Calculate percentage
if [ $total -gt 0 ]; then
  coverage=$((reviewed * 100 / total))
  echo "📈 AI review coverage: ${coverage}%"
fi

echo ""
echo "🚨 Recent issues found:"
git log --since="7 days ago" --grep="AI-REVIEW" --invert-grep --grep="AI-REVIEW-PASSED" --oneline | head -5

🚀 Advanced Integrations

VS Code Extension (Coming Soon)

Real-time AI feedback as you type
Inline suggestions and fixes
Integration with VS Code problems panel

IDE Plugins (Roadmap)

IntelliJ IDEA / WebStorm / PyCharm support
Real-time code analysis
Contextual suggestions in editor

GitHub Actions Integration

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          
      - name: Install AI Commit Guard
        run: npm install -g ai-commit-guard
        
      - name: Run AI Review on Changes
        run: |
          # Get changed files in PR
          git diff --name-only origin/main...HEAD > changed_files.txt
          
          # Stage changed files for review
          cat changed_files.txt | xargs git add
          
          # Run AI review
          ai-commit-guard
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          AI_GUARD_TIMEOUT: 60000
          
      - name: Comment on PR
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🤖 AI Code Review found issues that need attention. Please check the workflow logs for details.'
            });

GitLab CI Integration

# .gitlab-ci.yml
ai-code-review:
  stage: test
  image: node:18
  before_script:
    - npm install -g ai-commit-guard
  script:
    - git diff --name-only $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA | xargs git add
    - ai-commit-guard
  variables:
    AI_PROVIDER: "openai"
    AI_GUARD_TIMEOUT: "60000"
  only:
    - merge_requests

🔮 Roadmap

[ ] Code Generation - AI suggests fixes automatically
[ ] Real-time IDE Extensions - VS Code, IntelliJ support
[ ] Team Analytics Dashboard - Web-based review statistics
[ ] Custom AI Models - Fine-tune for your codebase
[ ] Batch Review Mode - Review multiple commits at once
[ ] GitHub App - Native GitHub integration
[ ] Slack/Discord Integration - Review notifications
[ ] Multi-reviewer Mode - Get consensus from multiple AIs
[ ] Learning Mode - Improve rules from team feedback
[ ] Compliance Scanning - OWASP, CWE, NIST standards
[ ] Performance Analysis - Detect performance bottlenecks
[ ] Architecture Review - High-level design feedback

🤝 Contributing

We love contributions! Here's how to get involved:

🐛 Bug Reports

Use our issue template
Include AI provider, OS, and Node.js version
Provide minimal reproduction case

💡 Feature Requests

Check existing discussions
Explain the use case and expected behavior
Consider implementation complexity

🔧 Code Contributions

# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/ademalkan/ai-commit-guard.git
cd ai-commit-guard

# 3. Install dependencies
npm install

# 4. Run tests
npm test

# 5. Make your changes
# Follow existing code style and patterns

# 6. Test your changes
npm run test:full

# 7. Submit a pull request
# Use conventional commit messages
git commit -m "feat: add support for new AI provider"

📚 Documentation

Improve README examples
Add use case tutorials
Create video guides
Translate to other languages

📄 License

🌟 Support

💬 Community

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions

📞 Professional Support

🏢 Enterprise Support: Available for teams and organizations
🎓 Training Sessions: Custom workshops for your team
🔧 Custom Integration: Tailored solutions for your workflow

☕ Show Your Appreciation

If AI Commit Guard saves you time and improves your code quality:

⭐ Star this repository on GitHub
🐦 Share on Twitter - Tag us @ai_commit_guard
📝 Write a blog post about your experience
💰 Sponsor the project on GitHub Sponsors

🚀 Ready to revolutionize your code quality?

Get Started →

"Code quality should be universal, not language-specific"

Made with ❤️ by developers, for developers