# Pre-commit Setup Summary

This document summarizes the pre-commit configuration and security measures implemented for the MCP ADR Analysis Server.

## Implemented Security Features

### 1. Secret Detection

- **Tool**: Gitleaks v8.28.0
- **Configuration**: `.gitleaks.toml`
- **Features**:
  - Scans for common secrets (API keys, tokens, credentials)
  - Custom rules for Twilio SID, Stripe keys, OpenRouter keys
  - Smart allowlist for test files and placeholders
  - Integrated into both pre-commit and pre-push hooks

### 2. Pre-commit Hooks (`.husky/pre-commit`)

- **Security checks**:
  - Gitleaks secret scanning
  - Private key detection (excluding test patterns)
- **Code quality**:
  - Code formatting with Prettier via lint-staged
  - TypeScript type checking
  - Project build validation
  - Smoke test execution

### 3. Pre-push Hooks (`.husky/pre-push`)

- **Final security scan**: Comprehensive gitleaks check
- **Dependency security**: npm audit for vulnerabilities
- **Build validation**: Ensures clean build before push
- **Test suite**: Runs full test suite (allows performance test failures)

### 4. Configuration Files

#### `.gitleaks.toml`

- Extends default gitleaks configuration
- Custom rules for project-specific secrets
- Smart allowlisting for test files and safe patterns

#### `.pre-commit-config.yaml`

- Comprehensive pre-commit framework configuration
- Multiple hooks for security, formatting, and quality
- Integrates with existing tools

## Fixed Issues

1. **Secret Detection Issue**:
   - Fixed Twilio Account SID in `tests/utils/tree-sitter-analyzer.test.ts:781`
   - Replaced test credentials with safe placeholder patterns

2. **Security Gaps**:
   - Added comprehensive secret scanning
   - Implemented private key detection
   - Added dependency vulnerability checks

3. **Hook Optimization**:
   - Enhanced error handling and user feedback
   - Balanced security with developer experience
   - Graceful handling of test failures

## Installation and Usage

### Prerequisites

```bash
brew install gitleaks  # For secret scanning
npm install           # Install project dependencies
```

### Hooks are automatically active via Husky

- Pre-commit: Runs on every commit
- Pre-push: Runs before pushing to remote

### Manual Testing

```bash
# Test secret scanning
gitleaks detect --source . --verbose

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

# Test pre-push hook
./.husky/pre-push
```

## Best Practices

1. **For Developers**:
   - Use placeholder values for secrets in tests (e.g., `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
   - Review security warnings before bypassing
   - Keep dependencies updated

2. **For Test Files**:
   - Use clearly identifiable placeholder patterns
   - Document test data as non-real in comments
   - Follow established patterns for consistency

3. **For CI/CD**:
   - Hooks run locally and in CI environments
   - Build failures block pushes for security
   - Test failures are logged but don't block (for known performance test issues)

## Troubleshooting

### Common Issues

1. **Gitleaks false positives**: Add patterns to `.gitleaks.toml` allowlist
2. **Build failures**: Check TypeScript compilation and dependencies
3. **Test failures**: Performance tests may fail intermittently (allowed)

### Bypassing Hooks (Emergency Only)

```bash
git commit --no-verify    # Skip pre-commit
git push --no-verify      # Skip pre-push
```

**Note**: Only use `--no-verify` in emergencies and address issues immediately after.
