Pre-Commit Hook

Comprehensive pre-commit validation ensuring code quality, security, and standards compliance before any commit is created.

---

Purpose

The pre-commit hook is the first line of defense in the CODITECT quality pipeline. It runs automatically before every commit to:

1. Prevent security issues - Detect secrets, API keys, and credentials before they enter version control
2. Enforce code quality - Run linters for all supported languages
3. Maintain consistency - Ensure formatting and style standards are met
4. Validate documentation - Check markdown files for errors and broken links

Priority: P0 - Critical for pilot release Impact: Prevents 95%+ of quality issues from entering the codebase

---

Trigger

Event: pre-commit (git hook) Blocking: Yes - Commit will fail if checks don't pass Timeout: 30 seconds (configurable) Bypass: git commit --no-verify -m "message"

---

Checks Performed

Security Checks (P0)

• Secrets Detection - Scan for API keys, tokens, passwords, private keys
• Credential Patterns - Detect AWS, GCP, Azure credential patterns
• PII Detection - Flag potential personally identifiable information
• File Size Limits - Prevent large binary files from being committed

Python Checks (P0)

• Ruff Linting - Fast Python linter (replaces flake8, isort, pyupgrade)
• Type Hints - Validate type annotations present on functions
• Import Sorting - Ensure imports are properly organized
• Syntax Validation - Check for Python syntax errors

JavaScript/TypeScript Checks (P1)

• ESLint - JavaScript/TypeScript linting
• Prettier - Code formatting validation
• TypeScript - Type checking for .ts/.tsx files

Rust Checks (P1)

• Clippy - Rust linting with recommended warnings
• Rustfmt - Rust formatting validation
• Cargo Check - Compilation validation

Bash Checks (P1)

• ShellCheck - Bash/shell script linting
• Syntax Validation - bash -n syntax check

Markdown Checks (P1)

• Markdownlint - Markdown linting via markdownlint-cli2
• YAML Frontmatter - Validate YAML syntax in frontmatter
• Link Validation - Check for broken internal links

File Checks (P2)

• Trailing Whitespace - Remove trailing whitespace
• End of File - Ensure files end with newline
• Mixed Line Endings - Detect CRLF/LF mixing
• Large Files - Warn on files >500KB, block >5MB

---

Installation

Method 1: Pre-commit Framework (Recommended)

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml in repo root
cat > .pre-commit-config.yaml << 'EOF'
repos:
  # CODITECT hooks
  - repo: local
    hooks:
      - id: coditect-pre-commit
        name: CODITECT Pre-commit
        entry: bash .coditect/hooks/pre-commit
        language: system
        pass_filenames: false
        stages: [commit]

  # Security - Secrets detection
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

  # Python
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.6
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  # JavaScript/TypeScript
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.54.0
    hooks:
      - id: eslint
        files: \.(js|jsx|ts|tsx)$

  # Markdown
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.37.0
    hooks:
      - id: markdownlint-cli2
        args: [--fix]

  # General
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-added-large-files
        args: [--maxkb=500]
EOF

# Install hooks
pre-commit install

Method 2: Direct Git Hook

# Copy hook script
cp .coditect/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Method 3: Husky (npm projects)

# Install husky
npm install husky --save-dev
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "bash .coditect/hooks/pre-commit"

---

Configuration

Environment Variables

Variable	Default	Description
CODITECT_SKIP_SECRETS	false	Skip secrets detection
CODITECT_SKIP_LINT	false	Skip linting checks
CODITECT_SKIP_FORMAT	false	Skip formatting checks
CODITECT_MAX_FILE_SIZE	5242880	Max file size in bytes (5MB)
CODITECT_TIMEOUT	30	Hook timeout in seconds
LOG_LEVEL	info	Logging verbosity (debug/info/warn/error)

.coditect/hooks.yaml (Optional)

pre-commit:
  enabled: true
  timeout: 30
  checks:
    secrets: true
    python: true
    javascript: true
    rust: false  # Disable if not using Rust
    markdown: true
    files: true
  thresholds:
    max_file_size_kb: 500
    max_total_size_mb: 10

---

Bypass

Skip All Checks

git commit --no-verify -m "WIP: work in progress"

Skip Specific Checks

# Skip secrets check only
CODITECT_SKIP_SECRETS=true git commit -m "message"

# Skip linting only
CODITECT_SKIP_LINT=true git commit -m "message"

Temporary Disable

# Disable pre-commit temporarily
pre-commit uninstall

# Re-enable
pre-commit install

---

Examples

Success Output

$ git commit -m "feat: Add user authentication"

CODITECT Pre-commit Hook v1.0.0
================================

[1/5] Security Checks...
  ✅ Secrets detection passed (0 issues)
  ✅ Credential patterns clean

[2/5] Python Checks...
  ✅ Ruff linting passed (3 files)
  ✅ Import sorting correct

[3/5] JavaScript Checks...
  ✅ ESLint passed (2 files)
  ✅ Prettier formatting valid

[4/5] Markdown Checks...
  ✅ Markdownlint passed (5 files)
  ✅ YAML frontmatter valid

[5/5] File Checks...
  ✅ No trailing whitespace
  ✅ Files end with newline
  ✅ No large files detected

================================
✅ All pre-commit checks passed!
================================

[main abc1234] feat: Add user authentication
 5 files changed, 120 insertions(+), 15 deletions(-)

Failure Output

$ git commit -m "feat: Add API integration"

CODITECT Pre-commit Hook v1.0.0
================================

[1/5] Security Checks...
  ❌ SECRETS DETECTED - COMMIT BLOCKED

  File: src/config.py
  Line 15: Possible API key detected
    api_key = "sk-abc123xyz789..."

  File: .env.example
  Line 3: Hardcoded password detected
    DB_PASSWORD=admin123

================================
❌ Pre-commit checks FAILED
================================

Fix the issues above or bypass with:
  git commit --no-verify -m "message"

For false positives, add to .gitleaksignore:
  echo "src/config.py:15" >> .gitleaksignore

---

Troubleshooting

Hook Not Running

Symptom: Commits go through without checks Solution:

# Verify hook is installed
ls -la .git/hooks/pre-commit

# Reinstall if missing
pre-commit install
# OR
cp .coditect/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Hook Timing Out

Symptom: "Hook timed out after 30s" Solution:

# Increase timeout
export CODITECT_TIMEOUT=60
git commit -m "message"

# Or permanently in .coditect/hooks.yaml
echo "pre-commit:\n  timeout: 60" >> .coditect/hooks.yaml

False Positive Secrets

Symptom: Legitimate code flagged as secrets Solution:

# Create .gitleaksignore
echo "path/to/file.py:line_number" >> .gitleaksignore

# Or inline ignore
# gitleaks:allow
api_key = get_key_from_env()

Missing Tools

Symptom: "ruff: command not found" Solution:

# Install missing tools
pip install ruff  # Python
npm install -g eslint prettier  # JavaScript
cargo install clippy  # Rust
npm install -g markdownlint-cli2  # Markdown
brew install gitleaks  # Secrets (macOS)

---

Performance

Check	Typical Time	Max Time
Secrets Detection	500ms	5s
Python (ruff)	200ms	3s
JavaScript (eslint)	1s	10s
Markdown	300ms	2s
File Checks	100ms	1s
Total	2-3s	30s

Optimization Tips:

1. Use ruff instead of flake8+isort (10x faster)
2. Only check staged files, not entire repo
3. Run checks in parallel where possible
4. Cache tool results between runs

---

Related Hooks

• pre-push-hook - Test and build verification before push
• post-checkout-hook - Environment setup after branch switch
• ci-integration-hook - GitHub Actions integration

---

Implementation Script

The implementation script is at:

• .coditect/hooks/pre-commit (main script)
• .coditect/hooks/pre-commit-docs (documentation validation)
• .coditect/hooks/pre-commit-folder-check.sh (folder structure validation)

---

Changelog

v1.0.0 - December 8, 2025

• Initial comprehensive documentation
• Defined all check categories
• Added installation methods (pre-commit, direct, husky)
• Created configuration options
• Added troubleshooting guide

---

Status: Production Ready Owner: Hal Casteel, CEO/CTO, AZ1.AI Inc. Copyright: 2025 AZ1.AI Inc. All Rights Reserved