cube-ms/GIT-HOOKS.md

Production-ready microservice framework with health monitoring, validation, error handling, and Docker Swarm support

# 🔒 Git Hooks & Code Quality Enforcement

Cube-MS projects come with **mandatory git hooks** that enforce code quality and testing standards. This ensures that **all code pushed to the repository has been tested and validated**.

## 🎯 What Git Hooks Do

### ✅ **Enforced Standards**
- **Unit tests must pass** before code can be pushed
- **Environment validation** before every commit/push  
- **Code linting** must pass before commits
- **Commit message format** must follow conventions
- **No sensitive data** allowed in commits

### 🚫 **What Gets Blocked**
- Commits with linting errors
- Commits with failing tests
- Pushes without passing full test suite
- Commits with invalid message format
- Commits containing potential secrets

## 📋 Hook Types

### 1. **Pre-Commit Hook** 
Runs before each commit:
```bash
✅ Environment validation
✅ ESLint code formatting
✅ Unit tests on staged files only
✅ Sensitive data detection
```

### 2. **Pre-Push Hook**
Runs before each push:
```bash
✅ Environment validation
✅ Full linting check
✅ Complete unit test suite  
✅ Test coverage analysis
✅ Docker build validation
✅ Security scan
✅ Branch-specific validations
```

### 3. **Commit Message Hook**
Validates commit message format:
```bash
✅ Conventional commits format
✅ Minimum message length
✅ Descriptive content
```

## 🚀 Automatic Setup

### During Project Creation
```bash
# Git hooks are automatically installed when you create a project
cube-ms create my-app
cd my-app
# Hooks are already active! ✅
```

### Manual Setup (if needed)
```bash
# Install hooks manually
npm run postinstall

# Or run full setup
npm run setup
```

## 📝 Commit Message Format

### ✅ **Accepted Formats**

**Conventional Commits (Recommended):**
```bash
feat(auth): implement JWT authentication system
fix(api): resolve validation error in user endpoint  
docs(readme): update installation instructions
test(auth): add unit tests for auth service
chore(deps): update dependencies to latest versions
refactor(user): simplify user service logic
style(format): fix code formatting issues
perf(db): optimize database query performance
```

**Basic Format (Minimum):**
```bash
Add user registration functionality
Fix database connection timeout issue
Update API documentation with examples
Implement rate limiting for API endpoints
```

### ❌ **Rejected Formats**
```bash
fix               # Too short
update            # Not descriptive  
changes           # Vague
wip              # Work in progress
minor fixes       # Not specific
test             # What kind of test?
```

## 🧪 Testing Commands

### Run Tests Manually
```bash
# Run unit tests only
npm run test:unit

# Run with coverage
npm run test:coverage  

# Run CI test suite (what pre-push runs)
npm run test:ci

# Test pre-commit hook
npm run pre-commit

# Test pre-push hook  
npm run pre-push
```

### Validate Environment
```bash
# Check environment configuration
npm run validate-env

# Fix linting issues
npm run lint:fix
```

## 🚨 Bypassing Hooks (Emergency Only)

### ⚠️ **Bypass Options**
```bash
# Skip commit hooks (emergency only)
git commit --no-verify -m "emergency fix"

# Skip push hooks (emergency only)  
git push --no-verify

# Disable all hooks temporarily
HUSKY=0 git commit -m "bypass all hooks"
HUSKY=0 git push
```

### 🔥 **When to Bypass**
- **Production outages** requiring immediate fixes
- **Critical security vulnerabilities** 
- **Infrastructure failures**

### 🎯 **Best Practice**
1. Fix the issue with bypass
2. **Immediately** create a follow-up commit that passes all tests
3. Document why bypass was needed

## 🛠️ Troubleshooting

### Common Issues & Solutions

#### 1. **"Tests failing" Error**
```bash
❌ Unit tests failed!

# Solutions:
npm run test:unit              # See which tests fail
npm run test:coverage          # Check test coverage
npm run validate-env           # Fix environment issues
```

#### 2. **"Linting errors" Error**  
```bash
❌ Linting failed!

# Solutions:
npm run lint:fix               # Auto-fix most issues
npm run lint                   # See specific errors
```

#### 3. **"Environment validation failed" Error**
```bash
❌ Environment validation failed!

# Solutions:
cp .env.example .env           # Copy environment template
npm run validate-env           # See specific issues
```

#### 4. **"Invalid commit message" Error**
```bash
❌ Invalid commit message format!

# Solutions:
git commit --amend -m "feat(api): your descriptive message"
```

#### 5. **"Docker build failed" Error**
```bash
❌ Docker build failed!

# Solutions:
docker build -t test .         # Test Docker build
docker-compose up --build      # Rebuild containers
```

### Hooks Not Working?

```bash
# Re-install hooks
npm run postinstall

# Check if hooks exist
ls -la .husky/

# Make hooks executable
chmod +x .husky/*

# Test hook manually
./.husky/pre-commit
```

## 🎯 Branch-Specific Rules

### **Main/Master Branch**
- ✅ Extra production readiness checks
- ✅ Commit message format validation
- ✅ Docker build validation
- ✅ Full security scan

### **Development Branch**
- ✅ Standard checks
- ✅ All tests must pass
- ✅ Environment validation

### **Feature Branches**
- ✅ Standard checks
- ✅ Unit tests for changed files
- ✅ Basic validations

## 📊 CI/CD Integration

### GitHub Actions
Git hooks work seamlessly with CI/CD:

```yaml
# .github/workflows/ci.yml
- name: 🧪 Run tests (same as pre-push hook)
  run: npm run test:ci

- name: 🧹 Lint code (same as pre-commit hook)  
  run: npm run lint

- name: 🔍 Validate environment
  run: npm run validate-env
```

### Docker Integration
```bash
# Hooks validate Docker builds
docker build -t my-app .       # Tested in pre-push
docker-compose up --build      # Tested in CI
```

## 🎉 Benefits

### ✅ **Code Quality**
- No failing tests reach the repository
- Consistent code formatting
- Proper commit history

### ✅ **Team Collaboration**  
- Everyone follows same standards
- Reduced code review time
- Less bugs in production

### ✅ **DevOps Ready**
- CI/CD pipelines run faster
- Docker builds are validated
- Environment issues caught early

## 💡 Tips & Best Practices

### 🚀 **Developer Workflow**
```bash
# 1. Make changes
vim src/my-feature.js

# 2. Test locally (optional but recommended)
npm run test:unit

# 3. Commit (hooks run automatically)
git add .
git commit -m "feat(api): add new endpoint"
# ✅ Pre-commit hook runs: lint + tests + validation

# 4. Push (hooks run automatically)  
git push
# ✅ Pre-push hook runs: full test suite + coverage + security
```

### 🎯 **Writing Commit Messages**
```bash
# Good examples:
feat(auth): add JWT token refresh endpoint
fix(db): resolve connection pool timeout issue
docs(api): update authentication examples  
test(user): add comprehensive user service tests
chore(deps): upgrade express to v4.21.2

# Include context when needed:
fix(auth): resolve JWT expiration causing 401 errors
feat(api): add user profile update with avatar upload
test(integration): add end-to-end API workflow tests
```

### 🔒 **Security Best Practices**
- Never bypass hooks to commit secrets
- Use environment variables for sensitive data
- Regularly update dependencies
- Review security warnings in pre-push

---

## 🎯 Quick Reference

| Command | Purpose |
|---------|---------|
| `npm run test:ci` | Full test suite (same as pre-push) |
| `npm run lint:fix` | Fix code formatting |
| `npm run validate-env` | Check environment config |
| `git commit --no-verify` | Bypass commit hooks (emergency) |
| `git push --no-verify` | Bypass push hooks (emergency) |
| `HUSKY=0 git push` | Disable all hooks |

**Remember**: Git hooks are there to help you write better code and catch issues early! 🚀