Skip to content

HOOKS_SETUP.md

Latest commit

 

History

History
199 lines (137 loc) · 4.95 KB

HOOKS_SETUP.md

File metadata and controls

199 lines (137 loc) · 4.95 KB

Git Hooks Setup Summary 🎣

This document summarizes the comprehensive git hooks and CI pipeline setup for the AI Command Auditor project.

✅ What's Been Implemented

1. Pre-commit Hooks (Python-based, no Node.js required)

  • Tool: pre-commit (Python package)
  • Configuration: .pre-commit-config.yaml
  • Setup Script: scripts/setup-hooks.sh

Automated Checks on Every Commit

  • Code Formatting: Black (Python), auto-fixes formatting
  • Import Sorting: isort with Black profile
  • Code Quality: Pylint for code analysis
  • Type Checking: MyPy for static type analysis
  • Security Scanning: Bandit for security vulnerabilities
  • Shell Linting: ShellCheck for bash scripts
  • File Hygiene: Trailing whitespace, end-of-file fixes
  • YAML/JSON Validation: Syntax checking
  • Markdown Linting: Documentation consistency

2. Pre-push Hooks (Git native)

  • Script: scripts/hooks/pre-push.sh
  • Runs: Unit tests, integration tests, comprehensive validation
  • Prevents: Pushing broken code to remote repository

3. GitHub Actions CI Pipeline

  • File: .github/workflows/ci.yml
  • Triggers: On push and pull requests to main/develop
  • Jobs:
    • Python linting (Black, isort, Pylint, MyPy)
    • Bash linting (ShellCheck)
    • Testing (pytest with coverage, multiple Python versions)
    • Security scanning (Bandit, Safety)
    • Integration tests

4. Development Dependencies

  • File: requirements-dev.txt
  • Includes: All testing, linting, and formatting tools
  • Coverage: pytest, coverage, pre-commit, security tools

🚀 Installation & Usage

Quick Setup

# Run the setup script (installs everything)
./scripts/setup-hooks.sh

Manual Commands

# Install dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

# Run specific hook
pre-commit run black --all-files

Testing the Setup

# Test pre-commit hooks
git add . && git commit -m "test commit"

# Test pre-push hooks
git push origin develop

# Run CI checks locally
pytest scripts/python/tests/

🛡️ Security & Quality Gates

Pre-commit (Blocking)

  • Code must be formatted (Black, isort)
  • No trailing whitespace or file issues
  • YAML/JSON must be valid
  • Basic file checks pass

Pre-push (Blocking)

  • All unit tests must pass
  • Linting checks must pass
  • Security scans must be clean
  • Integration tests must pass

CI Pipeline (Required for PR)

  • Multi-version Python testing
  • Comprehensive security scanning
  • Full test suite with coverage
  • Code quality metrics

📁 Key Files

Configuration

  • .pre-commit-config.yaml - Pre-commit hook configuration
  • .github/workflows/ci.yml - GitHub Actions CI pipeline
  • requirements-dev.txt - Development dependencies

Scripts

  • scripts/setup-hooks.sh - One-command setup script
  • scripts/hooks/pre-commit.sh - Custom pre-commit validation
  • scripts/hooks/pre-push.sh - Pre-push testing script

Git Hooks (Auto-installed)

  • .git/hooks/pre-commit - Runs pre-commit tool
  • .git/hooks/pre-push - Runs comprehensive tests

🎯 Benefits

For Developers

  • Automatic Code Formatting: Never worry about style again
  • Early Error Detection: Catch issues before they reach CI
  • Security Awareness: Automatic vulnerability scanning
  • Quality Assurance: Consistent code quality standards

For the Project

  • Consistent Code Style: All code follows same standards
  • Reduced CI Failures: Issues caught locally first
  • Security by Default: Automatic security scanning
  • Documentation Quality: Markdown and YAML validation

For Collaboration

  • Clean Git History: No formatting-only commits
  • Reliable Builds: CI passes consistently
  • Quality PRs: All submissions meet quality standards
  • Faster Reviews: Focus on logic, not style

🔧 Customization

Adding New Hooks

Edit .pre-commit-config.yaml:

- repo: https://github.com/new-tool/repo
  rev: v1.0.0
  hooks:
    - id: new-hook
      args: ["--option", "value"]

Modifying CI Pipeline

Edit .github/workflows/ci.yml to add new jobs or steps.

Bypassing Hooks (Emergency Only)

# Skip pre-commit (not recommended)
git commit --no-verify

# Skip pre-push (not recommended)
git push --no-verify

🎉 Success Metrics

The hooks are working correctly when you see:

  • ✅ All pre-commit checks pass
  • ✅ Code is automatically formatted
  • ✅ Security scans complete successfully
  • ✅ CI pipeline passes consistently
  • ✅ No style-related PR comments

📚 Learn More

Ready for development! 🚀

The git hooks are now fully configured and ready to ensure code quality for the AI Command Auditor project.