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

cd your-project
npx commit-guard-cli setup

Choose Your Mode

# 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

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

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

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

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

# 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

# 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:

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:

{
  "scripts": {
    "commit": "cz",
    "prepare": "husky install",
    "typecheck": "tsc --noEmit"
  }
}

Fast Mode:

{
  "scripts": {
    "prepare": "husky install", 
    "typecheck": "tsc --noEmit --skipLibCheck"
  }
}

Vanilla Mode:

// 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:

npx commit-guard-cli setup

Option 2: Global Installation

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

Option 3: Project Dependency

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:

# 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

# 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:

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?

# 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?

# Switch to Fast mode
npx commit-guard-cli setup --fast

# Or add timeouts
export COMMIT_GUARD_TIMEOUT=15

Network timeouts?

# 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?

# 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

# 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

# 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
• 💬 Discussions: GitHub 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 ⚡