repos:
  # -------------------------
  # Quick sanity checks (fast, fail early)
  # -------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  # -------------------------
  # Code formatting (fast, consistent)
  # -------------------------
  - repo: https://github.com/psf/black
    rev: 24.10.0
    hooks:
      - id: black

  # isort: automatically sorts import statements for consistency
  - repo: https://github.com/pre-commit/mirrors-isort
    rev: v5.10.1
    hooks:
      - id: isort

  # formats yml/yaml/json/js files to keep them consistent
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.0.1
    hooks:
      - id: prettier
        files: \.(json|yml|yaml|md|js|ts)$

  # -------------------------
  # Lightweight linting & type checking
  # -------------------------

  # Flake8: lints Python code for style, errors, and complexity
  - repo: https://github.com/PyCQA/flake8
    rev: 7.3.0
    hooks:
      - id: flake8

  # mypy: static type checker to catch type errors before runtime.
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.19.1
    hooks:
      - id: mypy

  # -------------------------
  # Heavier analysis (more expensive)
  # -------------------------

  # pylint: Pylint checks Python code for bugs, style issues (PEP 8)
  - repo: https://github.com/pre-commit/mirrors-pylint
    rev: v2.7.4
    hooks:
      - id: pylint

  - repo: local
    hooks:
      - id: radon-cc
        name: Check Cyclomatic Complexity with Radon
        # Checks all Python files for cyclomatic complexity(CC).
        # Fails if any function exceeds CC grade C (11–20), which is industry-acceptable maximum.
        # Shows per-function and average per-file scores.
        entry: poetry run radon cc -s -a -nc . --fail C
        language: system
        types: [python]

      - id: vulture
        name: Detect unused code with vulture
        # Use Poetry to run the command in the virtual environment
        entry: poetry run vulture . --min-confidence 60
        language: system
        types: [python]

  # bandit: Analyzes code for common security vulnerabilities.
  - repo: https://github.com/PyCQA/bandit
    rev: 1.9.3
    hooks:
      - id: bandit
        args: ["-r", "."]
        # Security scan for Python code

  # -------------------------
  # Local environment & docs
  # -------------------------
  - repo: local
    hooks:
      - id: block-env-files
        name: Block .env files
        language: python
        entry: "hooks/block_env.py"
        files: (^|/)\.env(\.[a-zA-Z0-9_-]+|$)

      - id: build-sphinx
        name: Build Sphinx docs
        entry: poetry run python -m sphinx -b html docs docs/_build/html || exit 1
        language: system
        files: \.(rst|md)$

      - id: commitlint
        name: Lint commit messages
        entry: npx commitlint --edit $1
        language: system
        stages: [commit-msg]