.pre-commit-config.yaml

# ═══════════════════════════════════════════════════════════════
# Pre-commit Hooks Configuration
# ═══════════════════════════════════════════════════════════════
#
# Setup (first time):
#   uv sync                        # install all deps including pre-commit
#   uv run pre-commit install      # install pre-commit hook
#   uv run pre-commit install --hook-type pre-push  # install pre-push hook
#
# Usage:
#   git commit                     # hooks run automatically
#   uv run pre-commit run --all-files  # run on all files manually
#   SKIP=mypy git commit           # skip a slow hook
#
# Auto-evolution (update hook versions):
#   uv run pre-commit autoupdate   # bump all hooks to latest version
#   uv run pre-commit run --all-files  # verify after update
#
# ═══════════════════════════════════════════════════════════════

default_stages: [pre-commit]

repos:
  # ─────────────────────────────────────────────────────────────
  # 1. Standard pre-commit hooks — basic file hygiene (auto-fix)
  # ─────────────────────────────────────────────────────────────
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
        args: [--markdown-linebreak-ext=md]
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-json
        exclude: ^(htmlcov/|\.vscode/)
      - id: check-added-large-files
        args: ['--maxkb=500']
      - id: check-merge-conflict
      - id: debug-statements
      - id: detect-private-key
      - id: check-ast
      # ── New: comprehensive file & code hygiene ──────────
      - id: fix-byte-order-marker
        # Auto-removes UTF-8 BOM (auto-fix)
      - id: check-builtin-literals
        # Detects dict() instead of {}, list() instead of []
      - id: check-case-conflict
        # Detects files differing only in case (breaks on Windows/macOS)
      - id: check-docstring-first
        # Prevents code before module docstring
      - id: check-executables-have-shebangs
        # Scripts with +x must have #!/usr/bin/env
      - id: check-shebang-scripts-are-executable
        # Scripts with #! must have +x permission
      - id: check-symlinks
        # Detects broken symlinks
      - id: destroyed-symlinks
        # Detects symlinks destroyed by git checkout on Windows
      - id: check-vcs-permalinks
        # Detects non-permanent GitHub links (missing commit hash)
      - id: check-illegal-windows-names
        # Detects filenames illegal on Windows (CON, PRN, etc.)
      - id: mixed-line-ending
        args: [--fix=lf]
        # Normalizes line endings to LF (auto-fix)
      - id: no-commit-to-branch
        args: [--branch, main, --branch, master]
        # Prevents direct commits to main/master
      - id: name-tests-test
        args: [--pytest-test-first]
        files: ^tests/
        # Ensures test files follow test_*.py naming

  # ─────────────────────────────────────────────────────────────
  # 2. Ruff — ultra-fast linter + formatter (auto-fix enabled)
  #    Version should stay in sync with pyproject.toml [dependency-groups.dev]
  #    Run `uv run pre-commit autoupdate` to bump
  # ─────────────────────────────────────────────────────────────
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.13
    hooks:
      - id: ruff
        name: ruff lint (auto-fix)
        args: [--fix, --exit-non-zero-on-fix]
        types_or: [python, pyi]
      - id: ruff-format
        name: ruff format (auto-fix)
        types_or: [python, pyi]

  # ─────────────────────────────────────────────────────────────
  # 3. Security & dead code analysis
  # ─────────────────────────────────────────────────────────────
  - repo: https://github.com/PyCQA/bandit
    rev: 1.9.3
    hooks:
      - id: bandit
        name: bandit security scan
        args: [-c, pyproject.toml, -ll, --quiet]
        # Medium+ severity only. Config in [tool.bandit]
        # Skip: SKIP=bandit git commit

  - repo: local
    hooks:
      - id: vulture
        name: vulture dead code scan
        entry: uv run vulture src/ scripts/ vulture_whitelist.py --min-confidence 80
        language: system
        types: [python]
        pass_filenames: false
        files: ^(src|scripts)/
        # False positives → vulture_whitelist.py

      - id: deptry
        name: deptry dependency check
        entry: uv run deptry src/
        language: system
        pass_filenames: false
        files: ^(src/|pyproject\.toml)
        # Config in [tool.deptry] in pyproject.toml

  # semgrep moved to pre-push (see section 5) — too heavy for commit-time (~300-500MB)

  # ─────────────────────────────────────────────────────────────
  # 4. Local hooks — project-specific checks
  # ─────────────────────────────────────────────────────────────
  - repo: local
    hooks:
      # ── Type checking (moved to pre-push — uses 500MB-1GB) ──
      # See section 5 for mypy. Run manually: uv run mypy src/

      # ── Async/sync consistency ─────────────────────────────
      - id: async-test-checker
        name: async/sync test consistency
        entry: uv run python scripts/check_async_tests.py
        language: system
        pass_filenames: false
        files: ^tests/
        # Only runs when test files are staged
        # Fix: uv run python scripts/check_async_tests.py --fix

      # ── File hygiene ───────────────────────────────────────
      - id: file-hygiene
        name: file hygiene (no temp files)
        entry: uv run python scripts/hooks/check_file_hygiene.py
        language: system
        pass_filenames: false
        always_run: true

      # ── Commit size guard ──────────────────────────────────
      - id: commit-size-guard
        name: commit size guard (≤30 files)
        entry: uv run python scripts/hooks/check_commit_size.py
        language: system
        pass_filenames: false
        always_run: true
        # Prevents oversized commits; split into focused changes
        # Bypass: git commit --no-verify

      # ── MCP tool documentation sync ────────────────────────
      - id: tool-count-sync
        name: MCP tool docs sync (auto-fix)
        entry: uv run python scripts/hooks/check_tool_sync.py
        language: system
        pass_filenames: false
        files: ^src/pubmed_search/presentation/mcp_server/
        # Only runs when MCP server files are modified
        # Auto-updates docs and stages them
      # ── Future annotations enforcement (auto-fix) ──────────
      - id: future-annotations
        name: future annotations (auto-fix)
        entry: uv run python scripts/hooks/check_future_annotations.py --fix
        language: system
        pass_filenames: false
        files: ^(src|tests)/.*\.py$
        # Ensures 'from __future__ import annotations' in all files
        # Auto-inserts after module docstring

      # ── No print() in production code ──────────────────────
      - id: no-print-in-src
        name: no print() in src/
        entry: uv run python scripts/hooks/check_no_print.py
        language: system
        pass_filenames: false
        files: ^src/.*\.py$
        # print() → logger.info(). Exceptions: __main__.py

      # ── DDD layer import rules ─────────────────────────────
      - id: ddd-layer-imports
        name: DDD layer dependency check
        entry: uv run python scripts/hooks/check_ddd_layers.py
        language: system
        pass_filenames: false
        files: ^src/pubmed_search/
        # domain/ ✗→ application/, infrastructure/, presentation/
        # application/ ✗→ infrastructure/, presentation/

      # ── No bare type: ignore ───────────────────────────────
      - id: no-type-ignore-bare
        name: no bare type:ignore
        entry: uv run python scripts/hooks/check_type_ignore.py
        language: system
        pass_filenames: false
        files: ^(src|tests)/.*\.py$
        # Always specify error code: # type: ignore[assignment]

      # ── MCP tool docstrings ────────────────────────────────
      - id: docstring-tools
        name: MCP tool docstrings required
        entry: uv run python scripts/hooks/check_docstring_tools.py
        language: system
        pass_filenames: false
        files: ^src/pubmed_search/presentation/mcp_server/tools/
        # Every @tool function must have docstring ≥10 chars

      # ── No os.environ in inner DDD layers ──────────────────
      - id: no-env-inner-layers
        name: no os.environ in domain/application
        entry: uv run python scripts/hooks/check_env_config.py
        language: system
        pass_filenames: false
        files: ^src/pubmed_search/(domain|application|shared)/
        # Config via DI container, not os.environ

      # ── Per-source API count guard ─────────────────────────
      - id: source-counts-guard
        name: per-source API count display guard
        entry: uv run python scripts/hooks/check_source_counts.py
        language: system
        pass_filenames: false
        files: ^(src/pubmed_search/presentation/mcp_server/tools/unified(_formatting)?\.py|tests/test_unified_tools\.py|tests/test_pipeline\.py)$
        # Ensures per-source API return counts are always displayed
        # to the agent (critical for search coverage decisions)

      # ── TODO/FIXME scanner (warning only) ──────────────────
      - id: todo-scanner
        name: TODO/FIXME scanner (warn)
        entry: uv run python scripts/hooks/check_todo_scanner.py
        language: system
        pass_filenames: false
        files: ^(src|tests)/.*\.py$
        verbose: true
        # Non-blocking warning. Set BLOCK_ON_MARKERS=true to block.

      # ── Self-evolution cycle consistency ────────────────────
      - id: evolution-cycle
        name: instruction ↔ skill ↔ hook consistency
        entry: uv run python scripts/hooks/check_evolution_cycle.py
        language: system
        pass_filenames: false
        files: (\.pre-commit-config\.yaml|copilot-instructions\.md|SKILL\.md|CONTRIBUTING\.md|pyproject\.toml|scripts/hooks/)
        # Validates the self-evolution cycle:
        #   Instructions → Skills → Hooks → Validate → Feedback
        # Only runs when relevant config/doc files are modified
  # ─────────────────────────────────────────────────────────────
  # 5. Pre-push hooks — heavier analysis (mypy, semgrep, pytest)
  #    These are too memory-intensive for pre-commit (~1-2GB total)
  #    but essential before pushing to remote.
  # ─────────────────────────────────────────────────────────────
  - repo: https://github.com/semgrep/semgrep
    rev: v1.151.0
    hooks:
      - id: semgrep
        name: semgrep security analysis
        args: [--config, p/python, --error, --quiet]
        stages: [pre-push]

  - repo: local
    hooks:
      - id: mypy
        name: mypy type check (src/)
        entry: uv run mypy src/
        language: system
        types: [python]
        pass_filenames: false
        stages: [pre-push]

      - id: pytest
        name: pytest (multi-core)
        entry: uv run pytest tests/ -n 4 --timeout=60 -q --no-header
        language: system
        pass_filenames: false
        always_run: true
        stages: [pre-push]