.pre-commit-config.yaml

# -----------------------------------------------------------------------------
# 🛠️ Pre-commit Configuration
# -----------------------------------------------------------------------------
# This configuration file sets up various pre-commit hooks to enforce code quality,
# security, and formatting standards before commits are made.
#
# Installation:
#   pip install --user --upgrade pre-commit
#   pre-commit install
#   pre-commit run --all-files
# Update:
#   pre-commit autoupdate
#
# To skip pre-commit checks:
#   git commit -m "Your message" --no-verify
#
# NOTE: Some hooks modify files automatically (formatters), while others only
# report issues (linters). Modified files will need to be staged again.
# -----------------------------------------------------------------------------

exclude: '(^|/)(\.pre-commit-.*\.yaml|normalize_special_characters\.py|test_input_validation\.py|ai_artifacts_normalizer\.py)$|(^|/)mcp-servers/templates/|(^|/)plugin_templates/|(^|/)tests/load/|.*\.(jinja|j2)$'  # ignore these files, all templates, load tests, and jinja files
fail_fast: true

default_language_version:
  python: python3.12

repos:
  # -----------------------------------------------------------------------------
  # 🔐 Security - Detect Private Keys
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b #v5.0.0
    hooks:
      - id: detect-private-key
        name: 🔐 Detect Private Key
        description: Detects the presence of private keys.
        types: [text]
        exclude: 'mcpgateway/utils/generate_keys\.py|tests/unit/mcpgateway/plugins/framework/external/mcp/test_tls_utils.py|tests/unit/mcpgateway/utils/test_generate_keys.py|tests/unit/mcpgateway/test_oauth_manager\.py'

  - repo: local
    hooks:
      - id: alembic-check-heads
        name: 🔄 Alembic - Check for Multiple Heads
        description: Ensures there is only one Alembic migration head (prevents migration conflicts).
        entry: 'bash -c ''heads=$(uv run alembic -c mcpgateway/alembic.ini heads | grep -E "^\S+.*\(head\)" | wc -l); if [ "$heads" -ne 1 ]; then echo "ERROR Multiple Alembic heads detected ($heads heads found) Run uv run alembic -c mcpgateway/alembic.ini heads"; exit 1; fi'''
        language: system
        pass_filenames: false
        always_run: true
        files: ^mcpgateway/alembic/versions/.*\.py$

      - id: alembic-check-branches
        name: 🔄 Alembic - Check for Branches
        description: Ensures there are no Alembic migration branches (prevents migration conflicts).
        entry: bash -c 'branches=$(uv run alembic -c mcpgateway/alembic.ini branches); if [ -n "$branches" ]; then echo "ERROR Alembic branches detected Run uv run alembic -c mcpgateway/alembic.ini branches"; exit 1; fi'
        language: system
        pass_filenames: false
        always_run: true
        files: ^mcpgateway/alembic/versions/.*\.py$

      - id: forbid-content-reference
        name: ❌ Forbid :contentReference
        description: Prevents :contentReference patterns from being committed.
        entry: ':contentReference'
        language: pygrep
        types: [text]
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: forbid-oai-citations
        name: ❌ Forbid OpenAI Citations
        description: Prevents [oaicite:??digits] patterns from being committed.
        entry: '\[oaicite:\?\?\d+\]'
        language: pygrep
        types: [text]
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: forbid-ai-stock-phrases
        name: ❌ Forbid AI Stock Phrases
        description: Prevents common AI-generated phrases from being committed.
        entry: '(?i)(brevity|source=chatgpt.com|turn0search0|filecite|as an ai language model|i am an ai developed by|this response was generated by|i don''t have real-time information|i don''t have access to real-time|i can''t browse the internet|i cannot browse the internet|my knowledge cutoff|my training data|i''m not able to access|i don''t have the ability to)'
        language: pygrep
        types: [text]
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: forbid-placeholder-citations
        name: ❌ Forbid Placeholder Citations
        description: Prevents placeholder citations like (Author, 2023) from being committed.
        entry: '\([A-Z][a-z]+,?\s+\d{4}\)'
        language: pygrep
        types: [text]
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: forbid-source-placeholders
        name: ❌ Forbid Source Placeholders
        description: Prevents (Source:...) placeholders from being committed.
        entry: '(?i)\(source:'
        exclude: '(^\.pre-commit-config\.yaml$|\.pyi?$)'
        language: pygrep
        types: [text]
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: forbid-malformed-code-fences
        name: ❌ Forbid Malformed Code Fences
        description: Prevents code fences with 4+ backticks from being committed.
        entry: '````+'
        language: pygrep
        types: [text]
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]

      - id: warn-ai-transitions
        name: ⚠️ Warn AI Transition Phrases
        description: Warns about common AI transition phrases (non-blocking).
        entry: '(?i)(brevity|in conclusion,|to summarize,|it is important to note that|remember that|keep in mind that|it''s worth noting that|please note that)'
        language: pygrep
        types: [text]
        verbose: true
        exclude: ^\.pre-commit-config\.yaml$
        stages: [pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-checkout, post-commit, post-merge, pre-push, manual]


  - repo: https://github.com/pycqa/bandit
    rev: 92ae8b82fb422a639f0ed8d99e96cea769594e08 #1.8.3
    hooks:
      - id: bandit
        name: 🐍 Bandit - Security Linter
        description: Finds common security issues in Python code.
        args: [--skip, "B101,B601", --severity-level, medium, --confidence-level, high]
        files: ^(mcpgateway|plugins)/

  # 🔤 Unicode Text Normalization (via texthooks)
  - repo: https://github.com/sirosen/texthooks
    rev: c1a669453f31baa33e32761cb670aa1f10141937 #0.6.8
    hooks:
      - id: fix-smartquotes
        name: 📝 Normalize Smart Quotes
        description: Replaces smart/curly quotes with standard ASCII quotes.
      - id: fix-ligatures
        name: 🔡 Normalize Ligatures
        description: Replaces typographic ligatures with standard characters.
      - id: fix-spaces
        name: ␣ Normalize Unicode Spaces
        description: Replaces non-breaking or exotic space characters with regular spaces.
      - id: forbid-bidi-controls
        name: 🚫 Forbid BiDi Unicode Controls
        description: Prevents bidirectional control characters that can obscure code meaning.

  # -----------------------------------------------------------------------------
  # 🧹 Formatting Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b #v5.0.0
    hooks:
      - id: end-of-file-fixer
        name: 🧹 Fix End of Files
        description: Ensures that a file is either empty, or ends with one newline.
        types: [text]
        stages: [pre-commit, pre-push, manual]

      - id: trailing-whitespace
        name: 🧹 Trim Trailing Whitespace
        description: Trims trailing whitespace.
        types: [text]
        stages: [pre-commit, pre-push, manual]

      - id: fix-byte-order-marker
        name: 🧹 Fix UTF-8 Byte Order Marker
        description: Removes UTF-8 byte order marker.
        types: [text]

      - id: mixed-line-ending
        name: 🧹 Mixed Line Ending
        description: Replaces or checks mixed line ending.
        types: [text, python]
        args: [--fix=lf]

      - id: requirements-txt-fixer
        name: 🧹 Fix requirements.txt
        description: Sorts entries in requirements.txt.
        files: (requirements|constraints).*\.txt$

      - id: file-contents-sorter
        name: 🧹 File Contents Sorter
        description: Sorts the lines in specified files (defaults to alphabetical).
        language: python
        files: "^$"

      - id: sort-simple-yaml
        name: 🧹 Sort Simple YAML Files
        description: Sorts simple YAML files which consist only of top-level keys.
        files: "^$"

  # -----------------------------------------------------------------------------
  # ✅ Code Quality and Validation Hooks (LINTING ONLY)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b #v5.0.0
    hooks:
      - id: check-added-large-files
        name: ✅ Check Added Large Files
        description: Prevents committing large files.
        stages: [pre-commit, pre-push, manual]

      - id: check-case-conflict
        name: ✅ Check Case Conflicts
        description: Checks for files that would conflict in case-insensitive filesystems.

      - id: check-merge-conflict
        name: ✅ Check Merge Conflicts
        description: Checks for files that contain merge conflict strings.
        types: [text]

      - id: check-symlinks
        name: ✅ Check Symlinks
        description: Checks for symlinks which do not point to anything.
        types: [symlink]

      - id: destroyed-symlinks
        name: ✅ Detect Destroyed Symlinks
        description: Detects symlinks which are changed to regular files.
        types: [file]

      - id: check-executables-have-shebangs
        name: ✅ Check Executables Have Shebangs
        description: Ensures that (non-binary) executables have a shebang.
        types: [text, executable]
        stages: [pre-commit, pre-push, manual]

      - id: check-shebang-scripts-are-executable
        name: ✅ Check Shebang Scripts Are Executable
        description: Ensures that (non-binary) files with a shebang are executable.
        types: [text]
        stages: [pre-commit, pre-push, manual]

      - id: forbid-new-submodules
        name: ✅ Forbid New Submodules
        description: Prevents addition of new git submodules.
        types: [directory]

      - id: forbid-submodules
        name: ✅ Forbid Submodules
        description: Forbids any submodules in the repository.
        language: fail
        entry: "submodules are not allowed in this repository:"
        types: [directory]

      - id: check-vcs-permalinks
        name: ✅ Check VCS Permalinks
        description: Ensures that links to VCS websites are permalinks.
        types: [text]

      # File Format Validation
      - id: check-json
        name: ✅ Check JSON
        description: Checks JSON files for parseable syntax.
        types: [json]

      - id: check-yaml
        name: ✅ Check YAML
        description: Checks YAML files for parseable syntax.
        types: [yaml]
        exclude: ^(docs/|charts/)
        args: ['--allow-multiple-documents']

      - id: check-toml
        name: ✅ Check TOML
        description: Checks TOML files for parseable syntax.
        types: [toml]

      - id: check-xml
        name: ✅ Check XML
        description: Checks XML files for parseable syntax.
        types: [xml]

      - id: fix-byte-order-marker
        name: ✅ Check Byte Order Marker
        description: Forbids files which have a UTF-8 byte-order marker.
        types: [text]

  - repo: https://github.com/adrienverge/yamllint
    rev: 79a6b2b1392eaf49cdd32ac4f14be1a809bbd8f7 #v1.38.0
    hooks:
      - id: yamllint
        name: ✅ YAMLlint - YAML Linter
        description: A linter for YAML files.
        args: [-c, .yamllint]
        # Lint *.yml|*.yaml everywhere EXCEPT charts/**
        files: ^.*\.(yml|yaml)$
        exclude: ^charts/

  # -----------------------------------------------------------------------------
  # 🐍 Python Code Quality Hooks (LINTING ONLY)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b #v5.0.0
    hooks:
      - id: check-ast
        name: 🐍 Check Python AST
        description: Simply checks whether the files parse as valid python.
        language: python
        types: [python]
        exclude: ^templates/

      - id: check-builtin-literals
        name: 🐍 Check Builtin Literals
        description: Requires literal syntax when initializing empty or zero Python builtin types.
        language: python
        types: [python]
        exclude: ^templates/

      - id: check-docstring-first
        name: 🐍 Check Docstring is First
        description: Checks a common error of defining a docstring after code.
        language: python
        types: [python]

      - id: debug-statements
        name: 🐍 Debug Statements (Python)
        description: Checks for debugger imports and py37+ `breakpoint()` calls.
        types: [python]
        language: python
        exclude: ^templates/

      - id: name-tests-test
        name: 🐍 Python Tests Naming
        description: Verifies test files in tests/ directories start with `test_`.
        language: python
        files: (^|/)tests/.+\.py$
        exclude: |
          (?x)^(
            tests/(.*/)?(pages|helpers|fuzzers|scripts|fixtures|migration|utils|manual|async|load|loadtest|jmeter|client|populate|targets)/.*\.py|
            tests/.*/_[^/]+\.py|
            tests/.*/make_[^/]+\.py|
            mcp-servers/python/url_to_markdown_server/tests/e2e_verify_ssrf_fix\.py
          )$
        args: [--pytest-test-first] # `test_.*\.py`

  # -----------------------------------------------------------------------------
  # 🐍 Python Formatting Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/astral-sh/ruff-pre-commit
    # Ruff version.
    rev: 0671d8ab202c4ac093b78433ae5baf74f3fc7246 #v0.15.16
    hooks:
      # Run the linter.
      - id: ruff-check
        types_or: [ python, pyi ]
        args: [ --fix ]
        files: ^(mcpgateway|plugins)/
        exclude: ^.*/alembic/versions/

      # Run the formatter.
      - id: ruff-format
        types_or: [ python, pyi ]
        files: ^(mcpgateway|plugins)/
        exclude: ^.*/alembic/versions/

  # -----------------------------------------------------------------------------
  # 🚀 Performance and Optimization Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/Lucas-C/pre-commit-hooks
    rev: a30f0d816e5062a67d87c8de753cfe499672b959  #v1.5.5
    hooks:
      - id: remove-crlf
        name: 🚀 Remove CRLF
        description: Replaces CRLF line endings by LF.

      - id: remove-tabs
        name: 🚀 Remove Tabs
        description: Replaces tabs by whitespaces.
        # exclude root-level Makefiles and any path ending in /Makefile, Makefile.*, .mk or .jinja
        exclude: '(^|/)Makefile(\.[^/]*)?$|(\.mk|\.jinja)$'


  - repo: local
    hooks:
      - id: correct-file-headers
        name: 📄 Correct Python File Headers
        description: Ensures mcpgateway/ and tests/ .py files have the correct license header.
        entry: >-
          bash -c '
          uv run .github/tools/fix_file_headers.py --fix-all "$@";
          ' --
        language: system
        types: [python]
        files: ^(mcpgateway|tests)/
        pass_filenames: true

  # -----------------------------------------------------------------------------
  #  Interrogate
  # -----------------------------------------------------------------------------
  - repo: https://github.com/econchick/interrogate
    rev: 4894019dc8876092bc9b6d56878798c550fad998  #v1.7.0
    hooks:
      - id: interrogate
        files: ^(mcpgateway|plugins)/
        exclude: _pb2(_grpc)?\.py$

  # -----------------------------------------------------------------------------
  #  🔐 Security - Detect Secrets
  # -----------------------------------------------------------------------------
  #  IBM Detect Secrets - https://github.com/ibm/detect-secrets
  #  This tool must be run after all other tools have completed.
  # -----------------------------------------------------------------------------
  - repo: https://github.com/ibm/detect-secrets
    rev: 076672a9a01abdfc7ecee2e7d14f08cdccb73976 # "0.13.1+ibm.64.dss"
    hooks:
      - id: detect-secrets
        name: 🔐 IBM Detect Secrets
        description: Detects secrets within a repository using IBM's detect-secrets.
        args: ['--baseline', '.secrets.baseline', --use-all-plugins, --fail-on-unaudited]
        types: [text]