commit-guard-cli/README.md

Commit validation, security audits, and dependency checks for Node.js projects. Enforces conventional commits with beautiful terminal output.

# Commit Guard CLI

🛡️ A comprehensive, high-performance commit validation and security audit tool for Node.js projects. Choose from **4 powerful modes** to match your project's needs - from dependency-free setups to full-featured validation suites.

## 🚀 Quick Start

### One Command Setup

```bash
cd your-project
npx commit-guard-cli setup
```

### Choose Your Mode

```bash
# Interactive Mode (recommended - full features, beautiful UI)
npx commit-guard-cli setup

# Minimal Mode (clean output, essential checks)
npx commit-guard-cli setup --minimal

# Fast Mode (ultra-fast validation, optimized for CI/CD)
npx commit-guard-cli setup --fast

# Vanilla Mode (zero dependencies, native git hooks)
npx commit-guard-cli setup --vanilla
```

## 🎯 Choose the Right Mode for Your Project

| Mode | Dependencies | Speed | Features | Best For |
|------|-------------|--------|----------|----------|
| **Interactive** | Full suite | Standard | Complete validation, beautiful UI | Development teams, full-featured projects |
| **Minimal** | Essential only | Fast | Core checks, clean output | CI/CD environments, streamlined workflows |
| **Fast** | Optimized | Ultra-fast | Speed-optimized checks | Large repositories, performance-critical |
| **Vanilla** | Zero | Instant | Native git hooks, no npm deps | Strict dependency policies, embedded systems |

## ✨ What You Get (All Modes)

- ✅ **Commit Message Validation** - Enforces conventional commit format
- ✅ **Security Audits** - Fast npm audit with vulnerability counts
- ✅ **Dependency Health** - Optimized outdated package detection
- ✅ **TypeScript Validation** - Lightning-fast type checking with `tsc --noEmit`
- ✅ **Performance Optimized** - All operations tuned for speed
- ✅ **Smart Timeouts** - Prevents hanging on network issues
- ✅ **Beautiful Feedback** - Progress indicators and operation timing

## 🔧 Detailed Mode Comparison

### 🎨 Interactive Mode
**The Full Experience**
- **Dependencies**: Full suite (husky, commitlint, commitizen)
- **Hook Type**: Husky-managed git hooks
- **Features**: Complete validation with beautiful, colorful output
- **Output**: Rich terminal UI with detailed security reports
- **Best For**: Development environments, teams wanting full features

```bash
npx commit-guard-cli setup
# or explicitly:
npx commit-guard-cli setup --interactive
```

**Includes**: Interactive commit prompts, full audit reports, detailed dependency analysis

### 🧹 Minimal Mode
**Clean and Essential**
- **Dependencies**: Core tools only (husky, commitlint)
- **Hook Type**: Husky-managed git hooks
- **Features**: Essential checks with clean, minimal output
- **Output**: Focused summaries and counts
- **Best For**: CI/CD environments, minimal terminal output preferences

```bash
npx commit-guard-cli setup --minimal
```

**Includes**: Clean validation messages, summarized audit results, essential dependency checks

### ⚡ Fast Mode
**Ultra-Performance**
- **Dependencies**: Optimized subset
- **Hook Type**: Husky-managed git hooks
- **Features**: Speed-optimized checks with minimal overhead
- **Output**: Rapid feedback with essential information only
- **Best For**: Large repositories, performance-critical environments, CI/CD pipelines

```bash
npx commit-guard-cli setup --fast
```

**Performance Features**:
- JSON-only audit parsing (no formatted output processing)
- Skip unnecessary npm audit categories
- Optimized TypeScript checking with `--skipLibCheck`
- Minimal console output
- Fastest possible validation cycle

### 🚀 Vanilla Mode
**Zero Dependencies**
- **Dependencies**: None (truly dependency-free)
- **Hook Type**: Native git hooks (no Husky)
- **Features**: Shell-based validation, no external tools
- **Output**: Basic shell output, no npm dependencies
- **Best For**: Strict dependency policies, embedded systems, minimal installs

```bash
npx commit-guard-cli setup --vanilla
```

**What makes it special**:
- Pure shell script git hooks
- No modifications to package.json dependencies
- No Husky installation
- Native git commit-msg hook
- Zero npm package overhead

## 📖 Usage

### Setup Commands

```bash
# Complete setup with mode selection
npx commit-guard-cli setup

# Direct mode setup
npx commit-guard-cli setup --interactive  # Full features
npx commit-guard-cli setup --minimal      # Clean output  
npx commit-guard-cli setup --fast         # Ultra-fast
npx commit-guard-cli setup --vanilla      # Zero dependencies

# Advanced options
npx commit-guard-cli setup --no-install   # Skip dependency installation
npx commit-guard-cli setup --force        # Overwrite existing configuration

# Step-by-step setup
npx commit-guard-cli init                  # Configure files only
npx commit-guard-cli install              # Install dependencies
```

### Making Commits

```bash
# Interactive guided commits (Interactive/Minimal modes)
npm run commit

# Regular git commits (validated in all modes)
git commit -m "feat: add new feature"
git commit -m "fix(auth): resolve login timeout"
git commit -m "docs: update API documentation"
```

### Commit Message Format

All modes enforce conventional commit format:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Examples:**
```bash
feat: add user authentication
fix(api): resolve timeout issue  
docs: update README with new examples
style(ui): improve button spacing
refactor: extract auth logic to separate module
test: add unit tests for user service
chore: update dependencies
```

## 🔧 What Gets Added to Your Project

### All Modes (except Vanilla)
- `.husky/` directory with optimized git hooks
- `commitlint.config.js` for commit message validation
- Updated `.gitignore` with husky entries

### Vanilla Mode Only
- `.git/hooks/commit-msg` native git hook (no Husky)
- No package.json modifications
- No additional dependencies

### Package.json Scripts Added
**Interactive & Minimal Modes:**
```json
{
  "scripts": {
    "commit": "cz",
    "prepare": "husky install",
    "typecheck": "tsc --noEmit"
  }
}
```

**Fast Mode:**
```json
{
  "scripts": {
    "prepare": "husky install", 
    "typecheck": "tsc --noEmit --skipLibCheck"
  }
}
```

**Vanilla Mode:**
```json
// No changes to package.json
```

### Dependencies Added

| Mode | Dependencies |
|------|-------------|
| **Interactive** | `husky`, `@commitlint/cli`, `@commitlint/config-conventional`, `commitizen`, `cz-conventional-changelog` |
| **Minimal** | `husky`, `@commitlint/cli`, `@commitlint/config-conventional` |
| **Fast** | `husky`, `@commitlint/cli`, `@commitlint/config-conventional` |
| **Vanilla** | None |

## 🚀 Performance Optimizations

### Speed Improvements
- **JSON-only parsing** for npm audit and outdated checks
- **Optimized TypeScript checking** with `--noEmit --skipLibCheck`
- **Smart timeouts** on all network operations (30 seconds)
- **Minimal output processing** in Fast mode
- **Direct tsc usage** when available instead of npm scripts
- **Parallel operations** where possible
- **Operation timing** displayed for transparency

### Network Optimizations
- `--no-audit --no-fund` flags for faster npm installs
- Timeout protection on hanging operations
- Cached dependency resolution
- Minimal audit scope in Fast mode

### Memory & CPU Optimizations
- Reduced shell command overhead
- Optimized regular expressions for commit validation
- Streamlined JSON parsing
- Minimal dependency trees

## 🔍 Features in Detail

### 🛡️ Security Audit (All Modes)
- **Fast vulnerability scanning** with `npm audit --json`
- **Categorized threat levels**: Critical, High, Moderate, Low
- **Quick fix suggestions** with npm commands
- **Clean, readable output** format
- **Performance optimized** JSON parsing only

### 📦 Dependency Health (All Modes)
- **Optimized outdated package detection** with `npm outdated --json`
- **Smart update recommendations**
- **Breaking change warnings**
- **Performance-focused** minimal output processing

### 📝 Commit Validation (All Modes)
- **Conventional commit format** enforcement
- **Shell-based validation** in Vanilla mode
- **Clear error messages** with examples
- **Format guidance** and help
- **Supports all standard conventional types**

### 🔧 TypeScript Integration (If Detected)
- **Automatic type checking** on commits
- **Fast `tsc --noEmit`** execution
- **Optimized with `--skipLibCheck`** in Fast mode
- **Direct tsc usage** when available
- **Fallback to npm scripts** if needed

### 🎨 Output Modes

#### Interactive Mode Output
```
🛡️  Security & Health Check (2.3s)
─────────────────────────────────

🔐 Security Audit
─────────────────
✅ No security vulnerabilities detected
   └─ All dependencies are secure

📦 Dependency Status  
─────────────────────
📋 3 packages have newer versions available:
   └─ Run 'npm outdated' for details

📝 Commit Message Validation
──────────────────────────────
✅ Commit message validation passed
   └─ Message follows conventional commit format

🚀 Ready to commit! Happy coding! 🎉
```

#### Fast Mode Output
```
✓ Security: 0 vulnerabilities (0.8s)
✓ Dependencies: 3 updates available (0.4s)  
✓ TypeScript: No errors (0.6s)
✓ Commit format: Valid (0.1s)
✓ Ready to commit! (1.9s total)
```

#### Vanilla Mode Output
```
Security & Health Check
=======================

Security Check
✓ Lock file detected
✓ Basic security checks passed

Dependencies  
✓ package.json found with dependencies
ℹ  Tip: Run 'npm outdated' to check for updates

TypeScript Check
✓ No TypeScript files to check

Commit Validation
=================
✓ Commit message format is valid

✓ Ready to commit!
```

## 📦 Installation Options

### Option 1: npx (Recommended)

No installation required:
```bash
npx commit-guard-cli setup
```

### Option 2: Global Installation

```bash
npm install -g commit-guard-cli
commit-guard-cli setup
```

### Option 3: Project Dependency

```bash
npm install --save-dev commit-guard-cli
npx commit-guard-cli setup
```

## 🌍 Supported Projects

Works with any Node.js project:

- ✅ **Next.js** - Full compatibility with all modes
- ✅ **React** - All React applications
- ✅ **Vue.js** - Frontend projects  
- ✅ **TanStack Router** - Complete support
- ✅ **Express.js** - Backend Node.js projects
- ✅ **TypeScript** - Enhanced TypeScript validation
- ✅ **Monorepos** - Works in any package directory
- ✅ **Any Node.js project** - Universal compatibility

## 📚 Commit Types Reference

| Type | Description | Version Bump | Examples |
|------|-------------|--------------|----------|
| `feat` | New features | Minor | `feat: add user authentication` |
| `fix` | Bug fixes | Patch | `fix(auth): resolve login timeout` |
| `docs` | Documentation | Patch | `docs: update API documentation` |
| `style` | Code style/formatting | Patch | `style(ui): improve button spacing` |
| `refactor` | Code refactoring | Patch | `refactor: extract auth logic` |
| `test` | Adding tests | Patch | `test: add unit tests for user service` |
| `chore` | Maintenance tasks | Patch | `chore: update dependencies` |
| `perf` | Performance improvements | Patch | `perf: optimize database queries` |
| `ci` | CI/CD changes | Patch | `ci: add automated testing workflow` |
| `build` | Build system changes | Patch | `build: update webpack configuration` |

## 🎯 Choosing the Right Mode

### When to Use Each Mode

**🎨 Interactive Mode**
- Development environments
- Teams wanting full commit guidance
- Projects needing rich validation feedback
- When you want beautiful terminal output

**🧹 Minimal Mode**  
- CI/CD pipelines requiring clean output
- Automated environments
- When you want essential checks without visual noise
- Projects with existing commit workflows

**⚡ Fast Mode**
- Large repositories with performance concerns
- High-frequency commit environments
- CI/CD systems with time constraints
- When speed is the top priority

**🚀 Vanilla Mode**
- Strict dependency policies
- Embedded or constrained environments
- Projects that cannot add npm dependencies
- Maximum simplicity and zero overhead

### Migration Between Modes

You can easily switch between modes by running setup again:

```bash
# Switch from any mode to another
npx commit-guard-cli setup --fast     # Switch to Fast mode
npx commit-guard-cli setup --vanilla  # Switch to Vanilla mode
npx commit-guard-cli setup            # Switch to Interactive mode
```

## 🔧 Advanced Configuration

### Environment Variables

```bash
# Disable specific checks (all modes)
export COMMIT_GUARD_SKIP_AUDIT=true
export COMMIT_GUARD_SKIP_OUTDATED=true  
export COMMIT_GUARD_SKIP_TYPECHECK=true

# Performance tuning
export COMMIT_GUARD_TIMEOUT=30  # Timeout in seconds
export COMMIT_GUARD_AUDIT_LEVEL=moderate  # Skip low-level audits
```

### Custom Commit Types

Edit `commitlint.config.js` to add custom commit types:

```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor', 
        'test', 'chore', 'perf', 'ci', 'build',
        'custom',  // Add your custom types
        'hotfix'
      ]
    ]
  }
};
```

## 🐛 Troubleshooting

### Common Issues

**Hook not running?**
```bash
# Check if hooks are executable
ls -la .git/hooks/
# or for Husky:
ls -la .husky/

# Reinstall if needed
npx commit-guard-cli setup --force
```

**Performance issues?**
```bash
# Switch to Fast mode
npx commit-guard-cli setup --fast

# Or add timeouts
export COMMIT_GUARD_TIMEOUT=15
```

**Network timeouts?**
```bash
# Increase timeout
export COMMIT_GUARD_TIMEOUT=60

# Or skip network checks temporarily
export COMMIT_GUARD_SKIP_AUDIT=true
export COMMIT_GUARD_SKIP_OUTDATED=true
```

**Vanilla mode not working?**
```bash
# Check hook installation
ls -la .git/hooks/commit-msg

# Verify executable permissions
chmod +x .git/hooks/commit-msg
```

## 📊 Performance Benchmarks

Typical execution times on a standard Node.js project:

| Mode | Average Time | Audit | Outdated | TypeCheck | Total |
|------|-------------|-------|----------|-----------|--------|
| **Interactive** | 2-4s | 1.2s | 0.8s | 0.6s | ~2.6s |
| **Minimal** | 1.5-3s | 1.0s | 0.6s | 0.6s | ~2.2s |
| **Fast** | 0.8-2s | 0.4s | 0.3s | 0.3s | ~1.0s |
| **Vanilla** | 0.1-0.5s | N/A | N/A | Shell | ~0.2s |

*Times may vary based on project size, network speed, and system performance*

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### Development Setup

```bash
# Clone the repository
git clone https://github.com/your-org/commit-guard-cli.git
cd commit-guard-cli

# Install dependencies
npm install

# Run in development
npm run dev

# Build the project
npm run build

# Test all modes
npm test
```

### Testing Changes

```bash
# Test each mode in a sample project
mkdir test-project && cd test-project
npm init -y

# Test your changes
npx ../commit-guard-cli setup --interactive
npx ../commit-guard-cli setup --minimal  
npx ../commit-guard-cli setup --fast
npx ../commit-guard-cli setup --vanilla
```

## 📈 Changelog

### v2.0.0 (Latest)
- ✨ **New Fast Mode** - Ultra-performance optimized validation
- ✨ **True Vanilla Mode** - Zero dependencies, native git hooks
- 🚀 **Performance Optimizations** - JSON-only parsing, optimized TypeScript checking
- 🔧 **Smart Timeouts** - Network operation protection
- 💫 **Enhanced UI** - Better progress feedback and timing
- 🛠️ **Improved Error Handling** - Graceful fallbacks and user guidance

### v1.x.x
- Initial release with Interactive and Minimal modes
- Basic Husky integration
- Conventional commit validation

## 🆘 Support

### Get Help

- 📖 **Documentation**: Full details in this README
- 🐛 **Issues**: [GitHub Issues](https://github.com/your-org/commit-guard-cli/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/your-org/commit-guard-cli/discussions)

### Reporting Issues

When reporting issues, please include:

1. **Mode used** (Interactive/Minimal/Fast/Vanilla)
2. **Node.js version** (`node --version`)
3. **Package manager** (npm/yarn/pnpm)
4. **Error output** (full terminal output)
5. **Project type** (Next.js, React, etc.)

## 📄 License

MIT License - feel free to use in any project!

---

**Made with ❤️ for developers who care about code quality and security** 🚀

*Commit Guard CLI - Fast, Flexible, Dependency-Smart* ⚡