.pre-commit-config.yaml

%YAML 1.2
---
# Pre-commit Configuration
# This file configures pre-commit hooks that run automatically before git commits
# to ensure code quality, formatting, and prevent security issues.
# https://pre-commit.com/
default_install_hook_types:
  - pre-commit
  - commit-msg

repos:

  #########################################
  # General Code Quality Checks
  #########################################
  - repo: https://github.com/pre-commit/pre-commit-hooks
    # Standard collection of pre-commit hooks for various checks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
        name: "✂️ whitespace · Remove trailing whitespace"
        # Removes trailing whitespace at end of lines
      - id: check-ast
        name: "🔍 python · Check Python AST"
        # Validates Python syntax without executing code
      - id: end-of-file-fixer
        name: "📄 files · Fix end of files"
        # Ensures files end with a newline
      - id: check-yaml
        name: "📋 yaml · Validate YAML files"
        exclude: "mkdocs.yml"
        # Validates YAML syntax
      - id: check-toml
        name: "📋 toml · Validate TOML files"
        # Validates TOML syntax
      - id: check-json
        name: "📋 json · Validate JSON files"
        # Validates JSON syntax
      - id: check-added-large-files
        name: "📏 files · Check for added large files"
        # Prevents large files from being committed
      - id: detect-private-key
        name: "🔑 security · Detect private keys"
        # Prevents accidental commit of private keys
      - id: pretty-format-json
        name: "📋 json · Format JSON files"
        # Formats JSON files for readability
      - id: check-merge-conflict
        name: "🔀 git · Check for merge conflicts"
      - id: forbid-new-submodules
        name: "🌳 git · Prevent submodule creation"

      - id: no-commit-to-branch
        name: "🌳 git · Protect main branches"
        args: ["--branch", "main", "--branch", "master"]
        # Prevents direct commits to protected branches
        # Detects unresolved merge conflicts
      - id: check-executables-have-shebangs
        name: "📜 files · Check executables have shebangs"
        # Ensures executable files have proper shebangs
      - id: check-shebang-scripts-are-executable
        name: "📜 files · Check shebang scripts are executable"
        # Makes sure files with shebangs are executable
      - id: pretty-format-json
        name: "📋 json · Format JSON files"
        args: [--autofix, --no-sort-keys]  # Fix formatting but don't sort keys
      - id: name-tests-test
        name: "🧪 tests · Check test file naming"
        args: [--pytest-test-first]  # Enforces pytest naming conventions
      - id: mixed-line-ending
        name: "📄 files · Fix mixed line endings"
        args: ['--fix=lf']  # Standardize on LF line endings
      - id: check-case-conflict
        name: "📁 filesystem/📝 names · Check case sensitivity"
      - id: check-illegal-windows-names
        name: "📁 filesystem/📝 names · Validate Windows filenames"
      - id: check-symlinks
        name: "📁 filesystem/🔗 symlink · Check symlink validity"
      - id: destroyed-symlinks
        name: "📁 filesystem/🔗 symlink · Detect broken symlinks"

  #########################################
  # Python Formatting and Linting
  #########################################
  - repo: https://github.com/astral-sh/ruff-pre-commit
    # Ruff is a fast Python linter and formatter written in Rust
    rev: v0.11.2
    hooks:
      - id: ruff
        name: "🐍 python · Format with Ruff"
        args: [--fix, --exit-non-zero-on-fix]  # Automatically fix issues when possible
      - id: ruff-format
        name: "🐍 python · Format with Ruff"
        # Automatically formats Python code


  #########################################
  # Python Code Modernization
  #########################################
  - repo: https://github.com/asottile/pyupgrade
    # Automatically upgrades Python syntax to newer versions
    rev: v3.19.1
    hooks:
      - id: pyupgrade
        name: "🔄 python · Upgrade Python syntax"
        args: ["--py311-plus"]  # Use Python 3.11+ specific syntax improvements
        # Upgrades syntax to use newer Python features

  - repo: https://github.com/asottile/add-trailing-comma
    # Adds trailing commas to function calls and definitions
    rev: v3.1.0
    hooks:
      - id: add-trailing-comma
        name: "🔤 python · Add trailing commas"
        # Makes future diffs cleaner and multiline constructs more consistent

  #########################################
  # API Documentation Validation
  #########################################
  - repo: https://github.com/python-openapi/openapi-spec-validator
    rev: 0.7.1
    hooks:
      - id: openapi-spec-validator
        name: "📝 api · Validate OpenAPI Spec"
        # Ensures OpenAPI specifications are valid

  #########################################
  # Python Project Configuration Validation
  #########################################
  - repo: https://github.com/abravalheri/validate-pyproject
    # Validates pyproject.toml file format
    rev: v0.24.1
    hooks:
      - id: validate-pyproject
        name: "🐍 python · Validate pyproject.toml"
        additional_dependencies: ["validate-pyproject-schema-store[all]"]
        # Ensures pyproject.toml follows PEP specifications

  #########################################
  # Documentation Formatting
  #########################################
  - repo: https://github.com/hukkin/mdformat
    # Markdown formatter for consistent documents
    rev: 0.7.22
    hooks:
      - id: mdformat
        name: "📝 markdown · Format markdown"
        # Formats markdown files for consistency
        exclude: |
          (?x)^(
            .*\{\{.*\}\}.*
          )$
        entry: mdformat
        language: python
        types: [markdown]
        verbose: true
        log_file: .logs/mdformat.log
        fail_fast: false
        files: \.(md|markdown)$
        args:
          - "--wrap=no"  # Wrap lines at 80 characters (customize as needed)
          - "--end-of-line=lf"  # Use LF line endings (Unix-style, recommended for consistency)
          # - "--check"  # Exit with error if formatting changes are needed
        additional_dependencies:
          - mdformat-gfm==0.4.1  # GitHub Flavored Markdown support
          - mdformat-mkdocs[recommended]==4.1.2  # MkDocs-specific formatting
          - mdformat-frontmatter==2.0.8  # YAML frontmatter support
          - mdformat-footnote==0.1.1  # Footnote support
          - mdformat-tables==1.0.0  # Table formatting
          - mdformat-toc==0.3.0  # Table of contents formatting
          - mdformat-beautysh==0.1.1  # Shell code block formatting
          - mdformat-black==0.1.1  # Python code block formatting
          - mdformat-gfm-alerts==1.0.1  # GitHub-style alerts
          - mdformat-myst==0.2.1  # MyST Markdown support
          - mdformat-config==0.2.1  # Configuration file parsing
          - mdformat-ruff==0.1.3  # Ruff linting for Python code blocks
          - mdformat-web==0.2.0  # Web-related Markdown formatting
          - mdformat-simple-breaks==0.0.1  # Consistent line break handling
          - ruff

  #########################################
  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.17.2
    hooks:
      - id: markdownlint-cli2
        name: "📝 markdown · Lint markdown with markdownlint"
        args: [--fix]
        exclude: ^CHANGELOG
        # Lints markdown files for style and consistency issues

  #########################################
  # YAML File Validation
  #########################################
  - repo: https://github.com/adrienverge/yamllint.git
    rev: v1.37.0
    hooks:
      - id: yamllint
        name: "📋 yaml · Lint YAML files with yamllint"
        args: [--strict, -c=./.yamllint.yaml]
        # Validates YAML files for style and syntax issues

  #########################################
  # A pre-commit hook to format and lint TOML files
  #########################################
  - repo: https://github.com/ComPWA/taplo-pre-commit
    rev: v0.9.3
    hooks:
      - id: taplo-format
        name: "📋 toml · Format TOML files with taplo"
        # Formats TOML files for consistency
      - id: taplo-lint
        name: "📋 toml · Lint TOML files with taplo"
        # Validates TOML files for errors and style issues

  #########################################
  # Makefile Validation
  #########################################
  - repo: https://github.com/mrtazz/checkmake.git
    # Makefile linter
    rev: 0.2.2
    hooks:
      - id: checkmake
        name: "🐮 Makefile · Lint Makefile"
        # Validates Makefile structure and conventions
        # No clear documentation on how to skip certain checks.
        # Fixed as many as I could, but best option is to ignore the file.
        exclude: |
          (?x)^(
            .*\{\{.*\}\}.*|
          )$

  #########################################
  # Scanning Hardcoded Secrets
  #########################################
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks
        name: "🔒 security · Scan for hardcoded secrets"
        # Detects and prevents secrets from being committed

# Set default Python version for all hooks
default_language_version:
  python: python3.11

# Define which git hooks these run on (defaults to pre-commit)
default_stages: [pre-commit]