litellm/.github/workflows/test-linting.yml

name: LiteLLM Linting

on:
  pull_request:
    branches:
      - main
      - litellm_internal_staging
      - litellm_oss_branch
      - "litellm_**"

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        # Check out the PR head, not the default refs/pull/N/merge: the merge ref
        # folds in newer base commits, which the diff-based gates (ruff delta,
        # Any-discipline) would otherwise blame on this branch.
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          clean: true
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version: "0.10.9"

      - name: Clean Python cache
        run: |
          find . -type d -name "__pycache__" -exec rm -rf {} + || true
          find . -name "*.pyc" -delete || true

      - name: Check uv.lock is up to date
        run: |
          uv lock --check || (echo "❌ uv.lock is out of sync with pyproject.toml. Run 'uv lock' locally and commit the result." && exit 1)

      - name: Install dependencies
        run: |
          uv sync --frozen

      - name: Check Black formatting
        run: |
          cd litellm
          uv run --no-sync black --check --exclude '/enterprise/' .
          cd ..

      - name: Debug - Check file state
        run: |
          echo "Current branch:"
          git branch --show-current
          echo "Last 3 commits:"
          git log --oneline -3
          echo "File content around line 43:"
          head -50 litellm/litellm_core_utils/custom_logger_registry.py | tail -10

      - name: Run Ruff linting
        run: |
          cd litellm
          uv run --no-sync ruff check .
          cd ..

      - name: Check strict-rule budget (delta vs base)
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          uv run --no-sync python scripts/ruff_strict_gate.py --base "$BASE_SHA"

      - name: Check type-discipline budget (mutable collections / casts / type guards / kwargs / unexplained suppressions, delta vs base)
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          uv run --no-sync python scripts/type_discipline_gate.py --base "$BASE_SHA"

      - name: Print OpenAI version
        run: |
          uv run --no-sync python -c "import openai; print(f'OpenAI version: {openai.__version__}')"

      - name: Run MyPy type checking
        run: |
          cd litellm
          (uv run --no-sync mypy . || true) | uv run --no-sync python ../scripts/type_check_gate.py --tool mypy

      - name: Run basedpyright type checking
        run: |
          (uv run --no-sync basedpyright --outputjson || true) | uv run --no-sync python scripts/type_check_gate.py --tool basedpyright

      - name: Check for circular imports
        run: |
          cd litellm
          uv run --no-sync python ../tests/documentation_tests/test_circular_imports.py
          cd ..

      - name: Check import safety
        run: |
          uv run --no-sync python -c "from litellm import *" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)

  # Intentionally NON-GATING. This job turns red when a *-budget.json ceiling is
  # raised (or a rule/budget is dropped) so a loosening is obvious in review, but it
  # must be kept OUT of the branch-protection required-checks list so a justified
  # bump can still be merged by a human who has seen and accepted the red.
  budget-ratchet:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"

      - name: Ratchet check (budgets may only decrease; non-gating)
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          python scripts/budget_ratchet_check.py --base "$BASE_SHA"

  any-discipline:
    # Separate job: the first run cold-builds litellm's type cache (~2 min, ~3 GB),
    # so keep it off the main lint job's time budget. Subsequent runs reuse the
    # cached .mypy_cache_any and only re-type-check the changed files.
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        # Check out the PR head, not the default refs/pull/N/merge: the merge ref
        # folds in newer base commits, which the diff-based gates (ruff delta,
        # Any-discipline) would otherwise blame on this branch.
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          clean: true
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version: "0.10.9"

      - name: Install dependencies
        run: |
          uv sync --frozen

      # Keyed on deps + mypy config (which fix the type cache's validity), not on
      # source content, so changed files always differ from the restored cache.
      # The gate also defensively invalidates each target's cache entry, so
      # correctness never depends on cache freshness -- this is purely for speed.
      - name: Restore Any-gate type cache
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: .mypy_cache_any
          key: any-mypy-cache-${{ runner.os }}-py3.12-${{ hashFiles('uv.lock', 'litellm/mypy.ini') }}
          restore-keys: |
            any-mypy-cache-${{ runner.os }}-py3.12-

      - name: Check Any discipline (per-file budget on changed files)
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          uv run --no-sync python scripts/check_any_discipline.py --changed --base "$BASE_SHA"

  secret-scan:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"

      - name: Set up uv
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          version: "0.10.9"

      - name: Run secret scan test
        run: |
          uv run --frozen --with 'pytest==9.0.2' pytest tests/litellm/test_no_hardcoded_secrets.py -v

      - name: Run ggshield secret scan
        env:
          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}
        run: |
          if [ -n "$GITGUARDIAN_API_KEY" ]; then
            uv tool run --from 'ggshield==1.48.0' ggshield secret scan repo .
          else
            echo "GITGUARDIAN_API_KEY not set, skipping ggshield scan"
          fi