.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/|(^|/)tests/load/|.*\.(jinja|j2)$'  # ignore these files, all templates, load tests, and jinja files

repos:
  # -----------------------------------------------------------------------------
  # 🔐 Security and Secret Detection Hooks
  # -----------------------------------------------------------------------------
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.27.2
    hooks:
      - id: gitleaks
        name: 🔐 Gitleaks - Detect hardcoded secrets
        description: Scans for hardcoded secrets like API keys and passwords.

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      #   - id: detect-aws-credentials
      #     name: 🔐 Detect AWS Credentials
      #     description: Detects *your* aws credentials from the aws cli credentials file.
      #     types: [text]

      - id: detect-private-key
        name: 🔐 Detect Private Key
        description: Detects the presence of private keys.
        types: [text]

  #   - repo: https://github.com/Yelp/detect-secrets
  #     rev: v1.5.0
  #     hooks:
  #       - id: detect-secrets
  #         name: 🔐 Detect Secrets
  #         description: Detects secrets within a repository.
  #         args: ['--baseline', '.secrets.baseline']

  # -----------------------------------------------------------------------------
  # ❌ Forbid Specific AI / LLM Patterns
  # -----------------------------------------------------------------------------
  # Local hooks that block the most common "AI artefacts" before they enter
  # the repository - including:
  #
  #   - `:contentReference`
  #   - `[oaicite:??<digits>]` or filecite (e.g. `[oaicite:??12345]`)
  #   - source=chatgpt.com
  #   - Stock phrases such as
  #       - "As an AI language model"
  #       - "I am an AI developed by"
  #       - "This response was generated by"
  #       - "In conclusion," / "To summarize," / "It is important to note that"
  #       - "Remember that" / "Keep in mind that"
  #   - Placeholder citations like `(Author, 2023)` and `(Source: ...)`
  #   - Any code-fence of **four or more** consecutive back-ticks: ```` , ``````, ...
  # -----------------------------------------------------------------------------
  - repo: local
    hooks:
      - 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:'
        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-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]


  # -----------------------------------------------------------------------------
  # 🔤 Unicode Text Normalization (via texthooks)
  # -----------------------------------------------------------------------------
  # A collection of hooks to clean up problematic Unicode characters:
  #
  # 📝 fix-smartquotes: Converts curly quotes (" " ' ') to standard ASCII quotes.
  # 🔡 fix-ligatures: Replaces typographic ligatures (fi, ff) with ASCII equivalents.
  # ␣ fix-spaces: Normalizes non-breaking and exotic spaces to regular spaces.
  # 🚫 forbid-bidi-controls: Prevents Unicode BiDi control characters used to
  #     obscure code logic or directionality.
  #
  # These prevent copy-paste artifacts, invisible formatting errors, and
  # encoding bugs from creeping into the codebase.
  # -----------------------------------------------------------------------------
  - repo: https://github.com/sirosen/texthooks
    rev: 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: 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: "^$"

  # Optional: Uncomment to enable Prettier formatting
  # - repo: https://github.com/pre-commit/mirrors-prettier
  #   rev: v3.0.3
  #   hooks:
  #     - id: prettier
  #       name: 🧹 Prettier - Code Formatter
  #       description: Formats JavaScript, TypeScript, CSS, HTML, JSON, Markdown, and more.
  #       types_or: [javascript, jsx, ts, tsx, css, less, scss, json, markdown, yaml]

  # -----------------------------------------------------------------------------
  # ✅ Code Quality and Validation Hooks (LINTING ONLY)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: 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/)

      - 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: check-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: v1.37.1
    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/

  #   - repo: https://github.com/igorshubovych/markdownlint-cli
  #     rev: v0.45.0
  #     hooks:
  #       - id: markdownlint
  #         name: ✅ Markdownlint - Markdown Linter
  #         description: A tool to check markdown files and flag style issues.

  # -----------------------------------------------------------------------------
  # 🐍 Python Code Quality Hooks (LINTING ONLY)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: 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: ^tests/(.*/)?(pages|helpers|fuzzers|scripts|fixtures|migration|utils|manual|async|load)/.*\.py$
        args: [--pytest-test-first] # `test_.*\.py`

  - repo: https://github.com/pycqa/flake8
    rev: 7.2.0
    hooks:
      - id: flake8
        name: 🐍 Flake8 - Python Linter
        description: Tool for style guide enforcement.

  # - repo: https://github.com/pycqa/bandit
  #   rev: 1.8.3
  #   hooks:
  #     - id: bandit
  #       name: 🐍 Bandit - Security Linter
  #       description: A tool designed to find common security issues in Python code.
  #       args: [--skip, "B101,B601"]

  # - repo: https://github.com/pre-commit/mirrors-mypy
  #   rev: v1.16.0
  #   hooks:
  #     - id: mypy
  #       name: 🐍 MyPy - Static Type Checker
  #       description: Optional static typing for Python.
  #       additional_dependencies: [types-all]

  # - repo: https://github.com/pycqa/pydocstyle
  #   rev: 6.3.0
  #   hooks:
  #     - id: pydocstyle
  #       name: 🐍 PyDocStyle - Docstring Checker
  #       description: A static analysis tool for checking compliance with Python docstring conventions.

  # -----------------------------------------------------------------------------
  # 🐍 Python Formatting Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/astral-sh/ruff-pre-commit
    # Ruff version.
    rev: v0.11.12
    hooks:
      # Run the linter.
      - id: ruff-check
        types_or: [ python, pyi ]
        args: [ --fix ]
        files: ^mcpgateway/
      # Run the formatter.
      # - id: ruff-format
      #   types_or: [ python, pyi ]
      #   files: ^mcpgateway/

  - repo: https://github.com/psf/black
    rev: 25.1.0
    hooks:
      - id: black
        name: 🐍 Black - Python Code Formatter
        description: The uncompromising Python code formatter.
        language_version: python3

  # - repo: https://github.com/pycqa/isort
  #   rev: 6.0.1
  #   hooks:
  #     - id: isort
  #       name: 🐍 isort - Import Sorter
  #       description: A Python utility / library to sort imports.
  #       args: [--profile=black]

  # - repo: https://github.com/asottile/pyupgrade
  #   rev: v3.20.0
  #   hooks:
  #     - id: pyupgrade
  #       name: 🐍 PyUpgrade - Python Syntax Upgrader
  #       description: Automatically upgrade syntax for newer versions of the language.
  #       args: [--py38-plus]

  # Optional: Uncomment to enforce single quotes in Python
  # - repo: https://github.com/pre-commit/pre-commit-hooks
  #   rev: v5.0.0
  #   hooks:
  #     - id: double-quote-string-fixer
  #       name: 🐍 Fix Double Quoted Strings
  #       description: Replaces double quoted strings with single quoted strings.
  #       types: [python]

  # -----------------------------------------------------------------------------
  # 🌐 Web Development Hooks (LINTING ONLY)
  # -----------------------------------------------------------------------------
  # - repo: https://github.com/pre-commit/mirrors-eslint
  #   rev: v8.50.0
  #   hooks:
  #     - id: eslint
  #       name: 🌐 ESLint - JavaScript/TypeScript Linter
  #       description: Find and fix problems in your JavaScript code.
  #       files: \.(js|jsx|ts|tsx)$
  #       types: [file]

  # - repo: https://github.com/thibaudcolas/pre-commit-stylelint
  #   rev: v16.20.0
  #   hooks:
  #     - id: stylelint
  #       name: 🌐 Stylelint - CSS Linter
  #       description: A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.
  #       files: \.(css|scss|sass|less)$

  # -----------------------------------------------------------------------------
  # 🚀 Performance and Optimization Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  - repo: https://github.com/Lucas-C/pre-commit-hooks
    rev: 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 or .mk or .jinja
        exclude: '(^|/)Makefile$|(\.mk|\.jinja)$'

  # -----------------------------------------------------------------------------
  # 🚫 Branch Protection Hooks
  # -----------------------------------------------------------------------------
  # - repo: https://github.com/pre-commit/pre-commit-hooks
  #   rev: v5.0.0
  #   hooks:
  #     - id: no-commit-to-branch
  #       name: 🚫 Prevent Commits to Protected Branches
  #       description: Prevents commits to specified branches.
  #       pass_filenames: false
  #       always_run: true
  #       args: [--branch, main, --branch, master, --branch, develop]

  # -----------------------------------------------------------------------------
  # 📝 Documentation Hooks (MODIFIES FILES)
  # -----------------------------------------------------------------------------
  # - repo: https://github.com/executablebooks/mdformat
  #   rev: 0.7.17
  #   hooks:
  #     - id: mdformat
  #       name: 📝 MDFormat - Markdown Formatter
  #       description: An opinionated Markdown formatter.
  #       additional_dependencies:
  #         - mdformat-gfm
  #         - mdformat-tables
  #         - mdformat-black

  # -----------------------------------------------------------------------------
  # 🧪 DOCTEST VALIDATION
  # -----------------------------------------------------------------------------
  # - repo: local
  #   hooks:
  #     - id: doctest
  #       name: 🧪 Doctest - Validate Documentation Examples
  #       description: Runs doctest on all Python modules to ensure documentation examples work.
  #       entry: python3 -m pytest --doctest-modules mcpgateway/ --tb=short
  #       language: system
  #       pass_filenames: false
  #       always_run: true
  #       types: [python]

  # -----------------------------------------------------------------------------
  #  Interrogate
  # -----------------------------------------------------------------------------
  - repo: https://github.com/econchick/interrogate
    rev: 1.7.0  # or master if you're bold
    hooks:
      - id: interrogate
        args: [--quiet, --fail-under=100]
        files: ^mcpgateway/