ci.yml

name: CI

on:
  push:
    branches: [master, develop]
  pull_request:
  workflow_dispatch:
  # Allows publish.yml to run the full test suite as a release gate.
  workflow_call:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ${{ matrix.os }}
    timeout-minutes: 10
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version:
          ['3.10', '3.11', '3.12', '3.13', '3.14', 'pypy-3.11']
        exclude:
          - os: macos-latest
            python-version: 'pypy-3.11'
          - os: windows-latest
            python-version: 'pypy-3.11'
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          activate-environment: true
          python-version: ${{ matrix.python-version }}
      - name: Install tox
        run: uv pip install '.[tox]'
      - name: Run tests
        run: tox
        env:
          TOX_SKIP_MISSING_INTERPRETERS: 'false'
      - name: Upload coverage data
        uses: actions/upload-artifact@v7
        with:
          name: coverage-${{ matrix.os }}-${{ matrix.python-version }}
          path: .tox/.coverage.*
          include-hidden-files: true

  coverage:
    needs: [test]
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          activate-environment: true
      - name: Install tox
        run: uv pip install '.[tox]'
      - uses: actions/download-artifact@v8
        with:
          pattern: coverage-*
          path: .tox
          merge-multiple: true
      - name: Combine coverage and enforce the threshold
        run: tox -e coverage
      - name: Upload combined coverage to Coveralls
        if: github.event_name != 'pull_request' && startsWith(github.ref, 'refs/heads/')
        uses: coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8
        with:
          file: .tox/coverage.lcov
          format: lcov
          fail-on-error: true

  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          activate-environment: true
      - name: Install tox
        run: uv pip install '.[tox]'
      - name: Apply Ruff fixes to pull requests
        if: github.event_name == 'pull_request'
        run: tox -e ruff-fix
      - name: Lint
        env:
          RUFF_OUTPUT_FORMAT: >-
            ${{ github.event_name == 'pull_request' && 'github' || 'full' }}
        run: tox -e lint

  type-check:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          activate-environment: true
      - name: Install tox
        run: uv pip install '.[tox]'
      - name: Type-check
        run: tox -e mypy,basedpyright,pyrefly,ty

  docs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          activate-environment: true
      - name: Install tox
        run: uv pip install '.[tox]'
      - name: Build docs
        run: tox -e docs

  # Dependabot opens against the default branch whenever target-branch is
  # absent, and its security updates ignore target-branch entirely and always
  # use the default branch. Either route lands a commit on master, which
  # re-diverges it from develop and turns the next release merge into a
  # conflict resolution. Both invariants are one line of config each and
  # neither announces itself when it changes, so assert them here.
  repo-config:
    name: Repository configuration
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@v10.1.0
        with:
          python-version: '3.13'
          enable-cache: false
      - name: Dependabot and the default branch both point at develop
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          default_branch="$(gh api "repos/${GITHUB_REPOSITORY}" --jq '.default_branch')"
          export DEFAULT_BRANCH="$default_branch"
          uv run --no-project --with pyyaml python - <<'PY'
          import os
          import pathlib
          import sys

          import yaml

          WANTED = 'develop'
          problems: list[str] = []

          default_branch: str = os.environ['DEFAULT_BRANCH']
          if default_branch != WANTED:
              problems.append(
                  f'the default branch is {default_branch!r}, not {WANTED!r}. '
                  f'Dependabot security updates always open against the '
                  f'default branch and cannot be redirected.'
              )

          # The config file is optional: without it Dependabot still runs
          # security updates, and those follow the default branch checked
          # above. Once it exists, every entry has to name develop, because an
          # entry without target-branch falls back to the default branch of
          # the day rather than to develop by name.
          config_path: pathlib.Path = pathlib.Path('.github/dependabot.yml')
          updates: list[dict[str, object]] = []
          if config_path.exists():
              config: dict[str, object] = yaml.safe_load(
                  config_path.read_text()
              )
              updates = config.get('updates') or []
              if not updates:
                  problems.append('.github/dependabot.yml declares no updates')

              for entry in updates:
                  ecosystem: object = entry.get('package-ecosystem', '<unnamed>')
                  directory: object = entry.get('directory', '<unset>')
                  target: object = entry.get('target-branch')
                  if target != WANTED:
                      problems.append(
                          f'{ecosystem} in {directory} targets {target!r}, '
                          f'not {WANTED!r}'
                      )

          if problems:
              for problem in problems:
                  print(f'error: {problem}', file=sys.stderr)
              sys.exit(1)

          print(
              f'The default branch and {len(updates)} Dependabot update(s) '
              f'all point at {WANTED!r}.'
          )
          PY