# 🤖 AI Commit Toolkit

[![npm version](https://badge.fury.io/js/%40cirrusinvicta%2Fai-commit-toolkit.svg)](https://badge.fury.io/js/%40cirrusinvicta%2Fai-commit-toolkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

One-command setup for AI-powered conventional commits with OpenAI integration, automated versioning, and seamless deployment workflows.

## ⚡ Quick Start

```bash
# Navigate to your project
cd your-project

# Install locally (recommended for customization)
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup AI commit toolkit
npx ai-commit-toolkit setup

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Start using AI-powered commits
git add .
git commit  # AI generates your commit message automatically!
```

## 🎯 What You Get

- ✅ **Intelligent AI commit message generation** using OpenAI GPT-4o-mini with comprehensive change analysis
- ✅ **Smart file filtering** automatically excludes `node_modules/`, `package-lock.json`, and other noise
- ✅ **Multi-file change handling** generates cohesive messages for complex commits with multiple files
- ✅ **Conventional commit format enforcement** with commitlint integration
- ✅ **Husky hooks integration** for seamless git workflow automation
- ✅ **Centralized configuration system** for easy customization and team consistency
- ✅ **Accurate length validation** correctly validates subject line length (not total message)
- ✅ **Semantic versioning support** with automated releases
- ✅ **Robust fallback mechanisms** when AI is unavailable
- ✅ **Comprehensive testing suite** with 35+ validation tests

## 📦 Installation

### Project-Specific Installation (Recommended)

```bash
# Navigate to your project directory
cd your-project

# Install as a dev dependency
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup the toolkit in your project
npx ai-commit-toolkit setup
```

**Why Local Installation?**

- ✅ **Project-specific configuration** - Each project can have customized AI prompts and settings
- ✅ **Version consistency** - Team members use the same toolkit version
- ✅ **Better customization** - Edit `configs/ai-prompts.conf` to tailor AI behavior for your project
- ✅ **No global conflicts** - Avoid version conflicts between different projects

### Global Installation (Alternative)

```bash
npm install -g @cirrusinvicta/ai-commit-toolkit
ai-commit-toolkit setup --type generic  # or ansible, vue, react
```

> **Note on Project Types**: Currently, all project types (`generic`, `ansible`, `vue`, `react`) use identical configurations and templates. The `--type` parameter is provided for future extensibility when project-specific customizations are added. For now, using any type will result in the same setup.

## 🛠️ Usage

### Automated Usage (Recommended)

```bash
# Make your changes
git add .

# Commit with AI (hook automatically generates message)
git commit
# ✨ Editor opens with AI-generated conventional commit message
```

### Manual AI Generation

```bash
# Generate and commit in one step
npx ai-commit

# Interactive helper with guidance
npx ai-commit-helper

# Test your setup
npx ai-commit-test
```

## 🧪 Testing

```bash
# Comprehensive validation (35+ tests total)
npm test

# Individual test suites
npm run test:config      # Configuration system (23 tests)
npx ai-commit-test      # Basic validation (12 tests)

# Test with actual commit generation
npx ai-commit-test --create-test-file
```

## ⚙️ Configuration

The AI Commit Toolkit uses a centralized configuration system for easy customization.

### Project Types

The toolkit supports different project types via the `--type` parameter:

- `generic` (default) - Universal configuration suitable for any project
- `ansible` - For Ansible playbooks and roles
- `vue` - For Vue.js applications
- `react` - For React applications

**Current Status**: All project types currently use identical configurations. The framework exists for future expansion when project-specific templates and prompts are added.

## 🚀 Recent Improvements

### Enhanced AI Commit Generation

- **Comprehensive Change Analysis**: No more truncated diffs - AI now sees full context of your changes
- **Smart Multi-File Handling**: Generates cohesive messages for complex commits with many files
- **Intelligent File Filtering**: Automatically excludes noise files like `node_modules/` and `package-lock.json`
- **Accurate Length Validation**: Correctly validates only the subject line length (72 chars) instead of total message
- **Better Commit Categorization**: Improved logic for choosing appropriate conventional commit types and scopes

### Example: Before vs After

**Before** (limited context):

```
chore(husky): add commit-msg and prepare-commit-msg hooks
⚠️ Warning: Message exceeds 100 characters (false positive)
```

**After** (full context):

```
chore(setup): initialize AI commit toolkit

- Add Husky hooks for commit message validation
- Configure commitlint for conventional commits
- Create environment and configuration files
- Install project dependencies and scripts
```

### AI Prompts Configuration

After setup, all AI prompts and settings are stored in `configs/ai-prompts.conf`:

```bash
# Main AI commit generation prompt
AI_COMMIT_PROMPT="Generate a conventional commit message..."

# OpenAI API Configuration
OPENAI_MODEL="gpt-4o-mini"
OPENAI_MAX_TOKENS=100
OPENAI_TEMPERATURE=0.3

# File exclusion patterns (automatically filtered from AI context)
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env"

# Git ignore patterns (what should never be committed)
# Note: package-lock.json is NOT excluded - it should be committed for reproducible builds
GITIGNORE_EXCLUDE="node_modules .env"

# Commit message validation
MAX_COMMIT_LENGTH=100
WARN_COMMIT_LENGTH=72
```

### Customizing Prompts

To customize the AI prompts for your project:

1. **After setup**: Edit `configs/ai-prompts.conf` in your project root
2. **Modify prompts**: Update `AI_COMMIT_PROMPT` to match your project's style and requirements
3. **Adjust exclusions**: Add patterns to `AI_COMMIT_EXCLUDE` to filter out files you don't want in AI context
4. **Fine-tune settings**: Change OpenAI model, token limits, or validation rules
5. **Test changes**: Run `npx ai-commit-test` to validate your configuration

**Example Customizations:**

```bash
# For a React project
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env build/ dist/"

# For more detailed messages
OPENAI_MAX_TOKENS=150
OPENAI_TEMPERATURE=0.4

# For stricter length limits
MAX_COMMIT_LENGTH=72
WARN_COMMIT_LENGTH=60
```

### Environment Variables

Required:

- `OPENAI_API_KEY`: Your OpenAI API key

Optional:

- `OPENAI_MODEL`: Override the default model (default: gpt-4o-mini)
- `OPENAI_MAX_TOKENS`: Override token limit (default: 100)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📖 [Documentation](docs/)
- 🐛 [Issue Tracker](https://github.com/CirrusInvicta/ai-commit-toolkit/issues)

---

**Made with ❤️ by Cirrus Invicta**

Transform your commit workflow with intelligent AI that understands your full codebase context and generates meaningful, accurate commit messages for even the most complex changes.