.pre-commit-config.yaml

exclude: 'build/'
minimum_pre_commit_version: 4.4.0
x-uv-dependency: &uv-dependency "uv==0.9.15"
default_language_version:
    python: python3.12

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0  # Latest stable version
    hooks:
    -   id: check-merge-conflict
        args: ['--assume-in-merge']
    -   id: trailing-whitespace
        exclude: '\.py$'  # Exclude Python files as Ruff already handles them
    -   id: check-added-large-files
        args: ['--maxkb=1000']
    -   id: end-of-file-fixer
        exclude: '^(.*\.svg|.*\.md|.*\.mustache)$'
    -   id: no-commit-to-branch
    -   id: check-yaml
        args: ["--unsafe"]
        exclude: 'docs/static/openai-spec-2.3.0.yml'
    -   id: detect-private-key
    -   id: mixed-line-ending
        args: [--fix=lf] # Forces to replace line ending by LF (line feed)
    -   id: check-executables-have-shebangs
    -   id: check-json
    -   id: check-shebang-scripts-are-executable
        exclude: '^.*\.mustache$'  # these are not executables, only templates of
    -   id: check-symlinks
    -   id: check-toml

-   repo: https://github.com/rhysd/actionlint
    rev: v1.7.11
    hooks:
    -   id: actionlint

-   repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.6.0
    hooks:
    -   id: conventional-pre-commit
        stages: [commit-msg]
        args: [--verbose]

-   repo: https://github.com/Lucas-C/pre-commit-hooks
    rev: v1.5.5
    hooks:
    -   id: insert-license
        files: \.py$|\.sh$
        args:
          - --license-filepath
          - docs/license_header.txt

-   repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.2
    hooks:
    -   id: ruff
        args: [ --fix ]
    -   id: ruff-format

-   repo: https://github.com/adamchainz/blacken-docs
    rev: 1.19.1
    hooks:
    -   id: blacken-docs
        additional_dependencies:
        - black==24.3.0


-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.18.2
    hooks:
    -   id: mypy
        additional_dependencies:
          - *uv-dependency
          - mypy
          - pytest
          - rich
          - types-requests
          - pydantic
        pass_filenames: false

# - repo: https://github.com/tcort/markdown-link-check
#   rev: v3.11.2
#   hooks:
#     - id: markdown-link-check
#       args: ['--quiet']

-   repo: local
    hooks:
      - id: uv-lock
        name: uv-lock
        additional_dependencies:
          - *uv-dependency
        entry: ./scripts/uv-run-with-index.sh lock
        language: python
        pass_filenames: false
        require_serial: true
        files: ^(pyproject\.toml|uv\.lock)$
      - id: mypy-full
        name: mypy (full type_checking)
        entry: ./scripts/uv-run-with-index.sh run --group dev --group type_checking mypy
        language: system
        pass_filenames: false
        stages: [manual]
      - id: distro-codegen
        name: Distribution Template Codegen
        additional_dependencies:
          - *uv-dependency
        entry: ./scripts/uv-run-with-index.sh run --group codegen ./scripts/distro_codegen.py
        language: python
        pass_filenames: false
        require_serial: true
        files: ^src/llama_stack/distributions/.*$|^src/llama_stack/providers/.*/inference/.*/models\.py$
      - id: provider-codegen
        name: Provider Codegen
        additional_dependencies:
          - *uv-dependency
        entry: sh -c 'env -i PATH="$PATH" ./scripts/uv-run-with-index.sh run --group codegen ./scripts/provider_codegen.py'
        language: python
        pass_filenames: false
        require_serial: true
        files: ^src/llama_stack/providers/.*$|^scripts/run_openapi_generator.sh$
      - id: openapi-codegen
        name: API Spec Codegen
        additional_dependencies:
          - *uv-dependency
        entry: sh -c './scripts/uv-run-with-index.sh run scripts/run_openapi_generator.sh'
        language: python
        pass_filenames: false
        require_serial: true
        files: ^src/llama_stack_api/.*$
      - id: api-conformance
        name: Check API spec for breaking changes
        entry: ./scripts/check-api-conformance.sh
        language: golang
        additional_dependencies:
          - github.com/oasdiff/oasdiff@latest
        pass_filenames: false
        require_serial: true
        files: ^docs/static/(llama-stack-spec|stable-llama-stack-spec|experimental-llama-stack-spec|deprecated-llama-stack-spec)\.yaml$
      - id: openai-coverage
        name: OpenAI API Coverage
        additional_dependencies:
          - *uv-dependency
        entry: ./scripts/uv-run-with-index.sh run python scripts/openai_coverage.py --check-regression --update --generate-docs --quiet
        language: python
        pass_filenames: false
        require_serial: true
        files: ^docs/static/(llama-stack-spec\.yaml|openai-spec.*\.yml|openresponses-spec\.json|openai-coverage\.json)$|^docs/docs/api-openai/conformance\.mdx$|^scripts/(openai_coverage|generate_openai_coverage_docs)\.py$
      - id: provider-compat-matrix
        name: Provider Compatibility Matrix
        additional_dependencies:
          - *uv-dependency
        entry: ./scripts/uv-run-with-index.sh run python scripts/provider_compat_matrix.py
        language: python
        pass_filenames: false
        require_serial: true
        files: ^tests/integration/responses/recordings/.*\.json$|^docs/docs/api-openai/provider_matrix\.md$|^scripts/provider_compat_matrix\.py$|^tests/integration/responses/test_.*\.py$
      - id: check-workflows-use-hashes
        name: Check GitHub Actions use SHA-pinned actions
        entry: ./scripts/check-workflows-use-hashes.sh
        language: system
        pass_filenames: false
        require_serial: true
        always_run: true
        files: ^\.github/workflows/.*\.ya?ml$
      - id: check-init-py
        name: Check for missing __init__.py files
        entry: ./scripts/check-init-py.sh
        language: system
        pass_filenames: false
        require_serial: true
        always_run: true
        files: ^src/llama_stack/.*$
      - id: forbid-pytest-asyncio
        name: Block @pytest.mark.asyncio and @pytest_asyncio.fixture
        entry: bash
        language: system
        types: [python]
        pass_filenames: true
        args:
          - -c
          - |
            grep -EnH '^[^#]*@pytest\.mark\.asyncio|@pytest_asyncio\.fixture' "$@" && {
              echo;
              echo "❌ Do not use @pytest.mark.asyncio or @pytest_asyncio.fixture."
              echo "   pytest is already configured with async-mode=auto."
              echo;
              exit 1;
            } || true
      - id: generate-ci-docs
        name: Generate CI documentation
        additional_dependencies:
          - *uv-dependency
        entry: ./scripts/uv-run-with-index.sh run ./scripts/gen-ci-docs.py
        language: python
        pass_filenames: false
        require_serial: true
        files: ^.github/workflows/.*$
      - id: ui-linter
        name: Format & Lint UI
        entry: bash ./scripts/run-ui-linter.sh
        language: system
        files: ^src/llama_stack_ui/.*\.(ts|tsx)$
        pass_filenames: false
        require_serial: true

      - id: check-log-usage
        name: Ensure 'llama_stack.log' usage for logging
        entry: bash
        exclude: '^client-sdks/openapi/.*$'
        language: system
        types: [python]
        pass_filenames: true
        args:
          - -c
          - |
            matches=$(grep -EnH '^[^#]*\b(import\s+logging|from\s+logging\b)' "$@" | grep -v -e '#\s*allow-direct-logging' || true)
            if [ -n "$matches" ]; then
              # GitHub Actions annotation format
              while IFS=: read -r file line_num rest; do
                echo "::error file=$file,line=$line_num::Do not use 'import logging' or 'from logging import' in $file. Use the custom log instead: from llama_stack.log import get_logger; logger = get_logger(). If direct logging is truly needed, add: # allow-direct-logging"
              done <<< "$matches"
              exit 1
            fi
            exit 0
      - id: no-fstring-logging
        name: Block f-string logging (use structlog key-value style)
        entry: ./scripts/check-no-fstring-logging.sh
        language: script
        types: [python]
        files: ^src/llama_stack/
        exclude: testing/api_recorder\.py
      - id: fips-compliance
        name: Ensure llama-stack remains FIPS compliant
        entry: bash
        language: system
        types: [python]
        pass_filenames: true
        exclude: '^tests/.*$'  # Exclude test dir as some safety tests used MD5
        args:
          - -c
          - |
            grep -EnH '^[^#]*\b(md5|sha1|uuid3|uuid5)\b' "$@" && {
              echo;
              echo "❌ Do not use any of the following functions: hashlib.md5, hashlib.sha1, uuid.uuid3, uuid.uuid5"
              echo "   These functions are not FIPS-compliant"
              echo;
              exit 1;
            } || true
      - id: no-sql-string-interpolation
        name: Block f-string SQL construction (SQL injection risk)
        entry: bash
        language: system
        types: [python]
        pass_filenames: true
        args:
          - -c
          - |
            grep -EnH 'f"""[^"]*\b(DELETE|INSERT|UPDATE|SELECT|MERGE)\b.*\{[^}]*\}' "$@" \
            | grep -v 'self\.table_name' \
            | grep -v 'self\.dimensions' \
            | grep -v 'self\.vector_datatype' \
            | grep -v '#\s*nosec' \
            && {
              echo;
              echo "SQL injection risk: f-string interpolation in SQL query detected."
              echo "Use parameterized bind variables instead:"
              echo "  oracledb:    :param_name"
              echo "  psycopg2:    %s or %(name)s"
              echo "  aiosqlite:   ? or :name"
              echo "  SQLAlchemy:  text().bindparams()"
              echo "If the interpolated value is a safe schema identifier (not user data),"
              echo "add '# nosec' to the line to suppress this check."
              echo;
              exit 1;
            } || true
      - id: check-api-independence
        name: Ensure llama_stack_api does not import llama_stack
        entry: bash
        language: system
        pass_filenames: false
        require_serial: true
        always_run: true
        files: ^src/llama_stack_api/.*$
        args:
          - -c
          - |
            API_DIR="src/llama_stack_api"
            grep -rn --include="*.py" -E '^[^#]*(import llama_stack\b|from llama_stack\b)' "$API_DIR" 2>/dev/null && {
              echo "llama_stack_api must not import llama_stack";
              exit 1;
            }
            [ -f "$API_DIR/pyproject.toml" ] && grep -n 'llama_stack[^_]' "$API_DIR/pyproject.toml" && {
              echo "llama_stack_api must not depend on llama_stack in pyproject.toml";
              exit 1;
            }
            exit 0

      - id: check-file-size
        name: Check Python file size limit
        entry: python scripts/check_file_size.py
        language: system
        types: [python]
        pass_filenames: true

# markdownlint must run after distro-codegen and provider-codegen which generate markdown files
-   repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.48.0
    hooks:
    -   id: markdownlint
        args: ['--fix']
        language_version: "22.22.1"

ci:
    autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
    autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate
    autofix_prs: true
    autoupdate_branch: ''
    autoupdate_schedule: weekly
    skip: [api-conformance]  # requires git history; covered by pre-commit.yml workflow
    submodules: false