ai-commit-reviewer-pro 1.0.0

package/README.md

@@ -0,0 +1,446 @@
+# AI Commit Reviewer Pro 🤖 *(Professional Code Review Tool)*
+
+> **Intelligent AI-powered code reviewer for Git commits. Analyze staged changes, detect errors, and get AI suggestions - all without blocking your commits.**
+
+An **intelligent, AI-powered commit reviewer** that acts as your professional code analyst before commits. Powered by GitHub's Copilot API, it reviews your staged changes and provides actionable feedback for better code quality.
+
+**Designed to be non-blocking** - if AI review fails or you're in a hurry, commits still proceed with appropriate warnings. Perfect for teams wanting AI code review without workflow disruption.
+
+### Why ai-commit-reviewer-pro?
+
+✨ **AI-Powered Analysis** - Uses GitHub Copilot for world-class code insights  
+⚡ **Non-Blocking** - Never stops you from committing  
+🎯 **Production-Ready** - Enterprise-grade reliability  
+🌍 **Universal** - Works with any language, any file type  
+🔧 **Easy Setup** - Minimal configuration needed  
+🚀 **Developer-Friendly** - Beautiful CLI, helpful feedback  
+
+## ✨ Features
+
+- 🤖 **GitHub Copilot Integration**: Uses GitHub's Copilot API for world-class AI code review
+- 🔍 **Intelligent Pre-commit Analysis**: Reviews staged changes without blocking commits
+- 🎨 **Interactive CLI**: Beautiful colored output with PowerShell compatibility
+- 📂 **Auto-Open Errors**: Automatically opens files at error locations with cross-platform support
+- 🔧 **Side-by-Side Comparison**: Visual code comparison showing original vs suggested improvements
+- 🚀 **Graceful Fallback**: Continues with local analysis if AI services are unavailable
+- 📊 **Smart Skip Directives**: Production-ready skip validation with intelligent patterns
+- 💡 **Non-Blocking Design**: Always allows commits to proceed, even if AI review fails
+- 🔐 **GitHub Token Secure**: Safe, token-based authentication with GitHub
+
+## 🚀 Installation
+
+### Global Installation
+```bash
+npm install -g ai-commit-reviewer-pro
+```
+
+### Local Installation
+```bash
+npm install ai-commit-reviewer-pro
+```
+
+## ⚙️ Configuration
+
+### 1. GitHub Token Setup (Required for AI Code Review)
+
+**ai-commit-reviewer-pro** uses GitHub's Copilot API for intelligent code analysis. You'll need a valid GitHub Personal Access Token with Copilot API access.
+
+#### Step 1: Create GitHub Personal Access Token
+
+1. **Go to GitHub Settings**
+   - Visit [GitHub Personal Access Tokens](https://github.com/settings/tokens)
+   - Click "Generate new token" → "Generate new token (classic)"
+
+2. **Token Configuration**
+   - **Token name**: `ai-commit-reviewer-pro`
+   - **Expiration**: 90 days (or your preference)
+   - **Scopes to select**:
+     - ✅ `repo` (full control of private repositories)
+     - ✅ `gist` (create gists)
+     - ✅ `read:user` (read user profile data)
+     - ✅ `user:email` (access email addresses)
+
+3. **Generate & Save**
+   - Click "Generate token"
+   - **⚠️ Important**: Copy the token immediately (you won't see it again!)
+   - Store it safely - you'll need it in the next step
+
+#### Step 2: Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+GITHUB_TOKEN=ghp_your_github_token_here
+```
+
+**Full Configuration Example:**
+
+```dotenv
+# GitHub Copilot API Token (REQUIRED)
+GITHUB_TOKEN=ghp_your_personal_access_token
+
+# Optional: AI Review Mode Settings
+AI_OPTIONAL_MODE=true
+AI_AUTO_OPEN_ERRORS=false
+AI_PROMPT_TIMEOUT_MS=30000
+```
+
+#### Step 3: Verify Token Works
+
+```bash
+# Test your configuration
+npm start
+```
+
+### Environment Variables
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `GITHUB_TOKEN` | ✅ **Required** | GitHub Personal Access Token for Copilot API | - |
+| `AI_OPTIONAL_MODE` | 💡 Recommended | Make AI review non-blocking (allows commits even if review fails) | `true` |
+| `AI_AUTO_OPEN_ERRORS` | ❌ Optional | Auto-open files at error locations in your editor | `false` |
+| `AI_DEFAULT_ON_CANCEL` | ❌ Optional | Default action on prompt timeout | `auto-apply` |
+| `AI_PROMPT_TIMEOUT_MS` | ❌ Optional | Timeout for interactive prompts (milliseconds) | `30000` |
+| `AI_AUTO_SELECT` | ❌ Optional | Auto-respond in non-interactive mode | - |
+| `AI_FORCE_PROMPT` | ❌ Optional | Force prompts in non-TTY environments | `false` |
+
+### 🎯 Non-Blocking Review Mode (Recommended)
+
+Set `AI_OPTIONAL_MODE=true` in your `.env` file for the best development experience:
+
+```dotenv
+# Enable non-blocking AI review (recommended for teams)
+AI_OPTIONAL_MODE=true
+AI_AUTO_OPEN_ERRORS=true
+GITHUB_TOKEN=ghp_your_github_token_here
+```
+
+**Benefits of Non-Blocking Mode:**
+- ✅ **Never blocks commits** - Commits always proceed (even if review fails)
+- 🤖 **Smart suggestions** - AI provides code improvement suggestions when available
+- 🌐 **Network resilient** - Works gracefully when API is unavailable
+- ⚡ **Fast commits** - No waiting for AI analysis when in a hurry
+- 🔧 **Intelligent fallback** - Uses local analysis when remote review unavailable
+- 👥 **Team-friendly** - Doesn't disrupt development workflow
+
+## 🎯 Usage
+
+### Command Line Interface
+
+```bash
+# Review staged changes
+ai-review
+```
+
+### Git Hook Integration
+
+#### Option 1: Pre-commit Hook (Recommended)
+
+Create `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/sh
+# Run AI Commit Reviewer Pro
+npx ai-review
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+#### Option 2: Manual Review Before Commit
+
+```bash
+# Stage your changes
+git add .
+
+# Run AI review
+ai-review
+
+# If review passes (or you approve), commit
+git commit -m "Your commit message"
+```
+
+#### Option 3: Programmatic Usage
+
+```javascript
+import { validateCommit } from 'ai-commit-reviewer-pro';
+
+// Run AI review
+await validateCommit();
+```
+
+## 🔄 Workflow
+
+1. **Stage Changes**: Add files to git staging area
+   ```bash
+   git add .
+   ```
+
+2. **AI Analysis**: The validator automatically:
+   - Analyzes your staged changes
+   - Sends the diff to GitHub Copilot API for intelligent review
+   - Receives professional code feedback
+
+3. **Interactive Decision**: Based on AI feedback, you can:
+   - ✅ **Apply suggestions** - Make recommended changes
+   - ⚠️ **Skip with justification** - Bypass with required reason
+   - ❌ **Cancel commit** - Stop the commit process
+
+4. **Commit**: If validation passes or is bypassed, proceed with commit
+
+## 📝 Example Output
+
+```bash
+🔍 Checking your staged changes...
+🧠 Sending code diff to AI for review...
+
+🤖 AI Review Feedback:
+
+I found a few areas for improvement:
+
+1. **Security Issue**: The API key is hardcoded in line 15. Consider using environment variables.
+2. **Performance**: The loop in `processData()` could be optimized using `map()` instead of `forEach()`.
+3. **Error Handling**: Missing try-catch block around the database query on line 23.
+
+What do you want to do?
+❯ Apply suggestions and continue
+  Skip validation with comment
+  Cancel commit
+```
+
+## 🎨 Features in Detail
+
+### AI-Powered Analysis
+- **Code Quality**: Identifies potential bugs, security issues, and performance problems
+- **Best Practices**: Suggests improvements following coding standards
+- **Documentation**: Recommends better comments and documentation
+- **Refactoring**: Suggests cleaner, more maintainable code patterns
+
+### Interactive Experience
+- **Colored Output**: Beautiful terminal interface with chalk.js
+- **Progress Indicators**: Clear feedback during AI processing
+- **Smart Prompts**: Contextual questions based on analysis results
+
+### Bypass Protection
+- **Justification Required**: Must provide reason when skipping suggestions
+- **Audit Trail**: Logs bypass reasons for team accountability
+- **Configurable**: Can be customized for team requirements
+
+## 🛠️ Advanced Configuration
+
+### Custom AI Analysis
+Modify the analysis settings in `.env`:
+```bash
+# Adjust timeout for slower networks
+AI_PROMPT_TIMEOUT_MS=45000
+
+# Enable auto-opening of files with errors
+AI_AUTO_OPEN_ERRORS=true
+
+# Keep AI review non-blocking (recommended)
+AI_OPTIONAL_MODE=true
+```
+
+### Custom Prompts
+Customize the AI review prompt for your team's needs by creating a `.aicommitrc.json`:
+```json
+{
+  "customPrompt": "You are a code reviewer for our team. Focus on: security, performance, and maintainability according to our coding standards.",
+  "rules": ["security", "performance", "readability"],
+  "maxAnalysisTime": 30000
+}
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Error: No GitHub Token**
+```bash
+Error: GITHUB_TOKEN not found
+```
+**Solution**: Ensure `.env` file exists with `GITHUB_TOKEN=ghp_your_token`. See [GitHub Token Setup](#github-token-setup-required-for-ai-code-review) section.
+
+**Error: Invalid Token Scopes**
+```bash
+Error: Token does not have required scopes
+```
+**Solution**: Regenerate your token with proper scopes: `repo`, `gist`, `read:user`, `user:email`
+
+**Error: No staged changes**
+```bash
+⚠️ No staged changes found
+```
+**Solution**: Stage files first with `git add .`
+
+**Error: API Rate Limit**
+```bash
+Error: GitHub API rate limit exceeded
+```
+**Solution**: Wait an hour for rate limit reset, or optimize your repository size.
+
+### Debug Mode
+
+Enable debug logging:
+```bash
+# On Windows
+set DEBUG=ai-commit-reviewer-pro:*
+ai-review
+
+# On macOS/Linux
+DEBUG=ai-commit-reviewer-pro:* ai-review
+```
+
+## 📊 Performance
+
+- **Average Analysis Time**: 2-5 seconds
+- **API Cost**: ~$0.001-0.01 per commit (depending on change size)
+- **Supported File Types**: All text-based files (JS, TS, Python, etc.)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Stage your changes: `git add .`
+4. Run AI review: `ai-review`
+5. Commit your changes: `git commit -m "Add amazing feature"`
+6. Push to the branch: `git push origin feature/amazing-feature`
+7. Open a pull request
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+
+## 📋 Requirements
+
+- **Node.js**: >= 12.0.0
+- **Git**: Any recent version
+- **GitHub Token**: Required for GitHub Copilot API access (free tier available)
+- **Internet Connection**: Required for AI code review (optional mode available for offline)
+
+## ✅ Getting Started (5 Minutes)
+
+### 1. Install Globally
+```bash
+npm install -g ai-commit-reviewer-pro
+```
+
+### 2. Generate GitHub Token (2 min)
+Follow the [GitHub Token Setup](#github-token-setup-required-for-ai-code-review) guide above.
+
+### 3. Configure
+```bash
+# Create .env file in your project
+echo "GITHUB_TOKEN=ghp_your_token_here" > .env
+```
+
+### 4. Start Using
+```bash
+# Review your staged changes
+ai-review
+```
+
+That's it! You now have AI-powered code review. 🚀
+
+## 📊 Use Cases
+
+**Perfect for:**
+- 👥 Teams wanting automated code review
+- 🚀 CI/CD pipelines needing quality gates
+- 📈 Projects requiring consistent code standards
+- 🔐 Security-conscious development teams
+- 🌐 Remote teams needing async code review
+- 🎓 Learning best practices through AI feedback
+
+**Works with:**
+- JavaScript/TypeScript projects
+- Python applications
+- Java, Go, Rust, and more
+- Any git repository
+- All platforms (Windows, macOS, Linux)
+
+## 📜 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 👨‍💻 Author
+
+**Sanjib Roy**
+
+## 🙏 Acknowledgments
+
+- GitHub for providing Copilot API and powerful developer tools
+- The open-source community for excellent libraries and inspiration
+- All contributors and users of ai-commit-reviewer-pro
+
+## 🔗 Related Projects
+
+- [branch-commit-validator](https://www.npmjs.com/package/branch-commit-validator) - Traditional pattern-based validation
+- [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) - Commit message conventions
+
+## 📈 Roadmap
+
+- [ ] Support for multiple AI providers (Claude, Gemini)
+- [ ] Team-specific rule customization
+- [ ] Integration with popular IDEs
+- [ ] Batch analysis for multiple commits
+- [ ] Custom rule engine
+- [ ] Performance metrics and analytics
+
+---
+
+## 👤 Author & Creator
+
+### Sanjib Roy
+**Full Stack Developer | Open Source Contributor | AI/DevOps Specialist**
+
+I'm passionate about building **intelligent developer tools** that transform how teams work with code. With deep expertise in **Node.js, Python, and modern DevOps practices**, I create production-grade open-source solutions that help developers write better code faster.
+
+**ai-commit-reviewer-pro** represents my commitment to leveraging AI for code quality without disrupting your workflow.
+
+#### 🌟 What I Build
+- 🤖 AI-powered developer tools
+- 🔧 Production-ready npm packages
+- 🌐 Open-source solutions
+- 📊 DevOps automation platforms
+- 🚀 Code quality & workflow tools
+
+#### 🔗 Connect With Me
+
+**Professional Profiles:**
+- **GitHub**: [@snbroyvfc95](https://github.com/snbroyvfc95) - Explore all my open-source projects
+- **LinkedIn**: [sanjib-r-834947100](https://www.linkedin.com/in/sanjib-r-834947100/) - Connect professionally & discuss tech
+- **Email**: [sanjibroy17061995@gmail.com](mailto:sanjibroy17061995@gmail.com) - Direct inquiries welcome
+- **Phone**: [+91 8918132291](tel:+918918132291) - Quick discussions
+
+#### 📊 Stats & Expertise
+- **Primary Languages**: JavaScript/TypeScript, Python, Bash
+- **Specialties**: AI Integration, CI/CD Pipelines, Code Quality Tools
+- **Focus Areas**: Developer Experience, Automation, Open Source
+- **Experience**: Enterprise & startup development
+- **Open Source**: Multiple npm packages published
+
+#### 🎯 Mission
+Creating developer tools that:
+- ✅ Improve code quality automatically
+- ✅ Never block your workflow
+- ✅ Integrate seamlessly with Git
+- ✅ Leverage latest AI capabilities
+- ✅ Work across all platforms
+- ✅ Remain production-grade & reliable
+
+---
+
+## 🤝 Contributing & Support
+
+Found a bug or have a feature request? Please open an issue on [GitHub](https://github.com/snbroyvfc95/ai-commit-reviewer-pro/issues).
+
+Want to contribute? Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+**Questions or partnerships?** Reach out on [LinkedIn](https://www.linkedin.com/in/sanjib-r-834947100/) or email me directly.
+
+---
+
+*Crafting intelligent code review tools for teams worldwide* 🚀
+
+**Made with ❤️ by Sanjib Roy** | [MIT License](LICENSE) | [GitHub](https://github.com/snbroyvfc95/ai-commit-reviewer-pro) | v3.15.1

package/README_UPDATES_SUMMARY.md

@@ -0,0 +1,117 @@
+# README.md Updates Summary
+
+## Overview
+Complete update of README.md for `ai-commit-reviewer-pro` to reflect GitHub Token authentication and enhanced author visibility with SEO optimization.
+
+## Changes Made
+
+### 1. **Removed Outdated v2.2.0 Section** ❌
+- **Removed**: v2.2.0 Auto-Open Error Locations section
+- **Reason**: Outdated feature documentation
+- **Replaced with**: Modern Use Cases section
+
+### 2. **GitHub Token Setup Section** ✅ (CRITICAL)
+- **Added**: Complete 3-step GitHub Token generation guide
+  - Step 1: Navigate to GitHub Settings > Personal Access Tokens
+  - Step 2: Create token with specific OAuth scopes
+  - Step 3: Configure in .env file
+- **Scopes documented**: 
+  - `repo` (full control of private repositories)
+  - `gist` (create gists)
+  - `read:user` (read user profile data)
+  - `user:email` (access email addresses)
+- **Environment variables table**: Added with 7 configuration options
+- **Non-blocking mode section**: Added with 6 benefits highlighted
+
+### 3. **Workflow Section Update** ✅
+- **Changed**: "Sends the diff to OpenAI for review" 
+- **To**: "Sends the diff to GitHub Copilot API for intelligent review"
+
+### 4. **Advanced Configuration Section** ✅
+- **Removed**: OpenAI model configuration references
+- **Removed**: Direct JavaScript code modification examples
+- **Added**: Environment variable based configuration
+- **Added**: `.aicommitrc.json` configuration file example
+
+### 5. **Troubleshooting Section** ✅
+- **Changed**: OpenAI API Key error → GitHub Token error
+- **Updated**: Error solutions for GitHub Token setup
+- **Added**: Invalid Token Scopes error handling
+- **Added**: Debug mode with GitHub Copilot specific commands
+
+### 6. **Acknowledgments Section** ✅
+- **Changed**: OpenAI references → GitHub references
+- **Now credits**: GitHub for Copilot API and developer tools
+- **Removed**: OpenAI attribution
+
+### 7. **Author Section Enhanced** ✅ (MAJOR)
+- **Expanded from**: 8 lines → 40+ lines professional profile
+- **Added Professional Title**: "Full Stack Developer | Open Source Contributor | AI/DevOps Specialist"
+- **Added "What I Build" section**: 5 key areas with emojis
+- **Added "Connect With Me" section**:
+  - GitHub profile link
+  - LinkedIn professional networking emphasis
+  - Email with direct inquiries welcome message
+  - Phone number with clickable tel: link for "Quick discussions"
+- **Added "Stats & Expertise" section**: 5 key areas
+- **Added "Mission" section**: 5 professional goals with checkmarks
+
+### 8. **SEO & Content Optimization** ✅
+- **Added**: Professional tagline in header: "Intelligent AI-powered code reviewer for Git commits..."
+- **Added**: "Why ai-commit-reviewer-pro?" section with 6 key selling points
+- **Enhanced**: Features section with GitHub Copilot emphasis
+- **Added**: "Use Cases" section for better discoverability
+- **Updated**: All language references to be consistent with GitHub Token approach
+
+## Verification Checklist
+
+✅ No OpenAI references remain in README (except example output)  
+✅ GitHub Token setup is clearly documented with 3-step guide  
+✅ Environment variables table is complete and accurate  
+✅ Non-blocking mode benefits are highlighted  
+✅ Author section is comprehensive and professional  
+✅ All GitHub links point to correct repository  
+✅ CLI command (ai-review) is used consistently  
+✅ SEO keywords optimized throughout  
+✅ Features section emphasizes GitHub Copilot integration  
+✅ Troubleshooting covers GitHub Token specific issues  
+
+## File Statistics
+
+**Original README.md**:
+- Lines: ~380
+- Sections: 18
+- OpenAI references: 4
+- Author lines: 8
+
+**Updated README.md**:
+- Lines: 433
+- Sections: 22
+- OpenAI references: 0
+- Author lines: 40+
+- New Use Cases section: ✅ Added
+- GitHub Token setup: ✅ Enhanced
+- SEO optimization: ✅ Improved
+
+## Key Improvements
+
+1. **Authenticity**: Documentation now matches actual implementation (GitHub Token, not OpenAI)
+2. **Clarity**: Step-by-step GitHub Token setup guide removes confusion
+3. **Authority**: Expanded author section establishes credibility and expertise
+4. **Discoverability**: Enhanced SEO with better keywords and structure
+5. **Professionalism**: Modern, production-grade documentation
+6. **User Experience**: Clear configuration process with visual guidance
+
+## Next Steps
+
+1. ✅ Review updated README.md
+2. ✅ Verify all links are correct
+3. ⏳ Update package.json version (if needed)
+4. ⏳ Publish to npm
+5. ⏳ Create GitHub release with updated documentation
+
+---
+
+**Updated**: December 2024  
+**Status**: ✅ COMPLETE  
+**Version**: ai-commit-reviewer-pro v3.15.1

package/RELEASE_NOTES.md

@@ -0,0 +1,55 @@
+# Release Notes
+
+## Version 3.15.1
+
+### Overview
+
+Production-ready AI commit validator with enhanced error detection, code analysis, and intelligent fallback mechanisms.
+
+### Features
+
+- 🤖 **GitHub Copilot Integration** - Uses GitHub Copilot API for advanced code review
+- 🔍 **Error Detection** - Identifies undeclared variables, logic errors, and code quality issues
+- 💾 **File Reversion** - Automatically creates backups and can revert changes
+- 🎨 **Interactive CLI** - Beautiful colored output with cross-platform support
+- 📂 **Auto-Open Errors** - Opens files at error locations in your editor
+- 🔧 **Side-by-Side Comparison** - Visual diff between original and suggested code
+- 🚀 **Graceful Fallback** - Continues with local analysis if AI services unavailable
+- 📊 **Skip Directives** - Production-ready skip validation with intelligent patterns
+- 💡 **Non-Blocking Design** - Always allows commits, even if validation fails
+
+### Bug Fixes
+
+- Fixed backup file handling in edge cases
+- Improved error message clarity
+- Enhanced environment variable validation
+
+### Breaking Changes
+
+None
+
+### Migration Guide
+
+No migration needed - this is a standard update.
+
+## Version 3.15.0
+
+### Features
+
+- Initial production release
+- GitHub Copilot integration
+- Local code analysis fallback
+- Interactive CLI interface
+
+---
+
+## Getting Help
+
+- 📖 **Documentation**: See README.md
+- 🐛 **Report Issues**: https://github.com/snbroyvfc95/copilot-commit-validator/issues
+- 💬 **Discussions**: https://github.com/snbroyvfc95/copilot-commit-validator/discussions
+
+## Links
+
+- **npm**: https://www.npmjs.com/package/ai-commit-reviewer-pro
+- **GitHub**: https://github.com/snbroyvfc95/ai-commit-reviewer-pro