ci.yml

name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  release:
    types: [published]

jobs:
  lint-python:
    name: Lint Python
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python 3.x
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"
          cache: "pip"
      - name: Install Hatch
        run: |
          pip3 --quiet install --upgrade hatch uv
          hatch --version
          uv --version
      - name: Lint project
        run: |
          hatch fmt --check
      - name: Check files with pre-commit
        uses: pre-commit/action@v3.0.1

  lint-docs:
    name: Lint Documentation
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
          cache: pip
      - name: Install dependencies
        run: |
          pip install --upgrade hatch uv
      - name: Check documentation links
        run: |
          hatch run docs:linkcheck
      - name: Check docs build
        run: |
          hatch run docs:build
      - name: Validate changelog format
        run: |
          hatch run scripts/validate_changelog.py

  test-python:
    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    needs:
      - lint-python

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest
        python-version:
          - "3.9"
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          allow-prereleases: true
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip hatch uv

      - name: Show environment
        run: |
          hatch test --show --python ${{ matrix.python-version }}

      - name: Run tests
        run: |
          hatch test --cover --python ${{ matrix.python-version }}
          mv .coverage ".coverage.py${{ matrix.python-version }}"

      - name: Upload coverage data
        if: matrix.os != 'windows-latest'
        uses: actions/upload-artifact@v4
        with:
          name: "coverage-data-py${{ matrix.python-version }}"
          path: ".coverage.py${{ matrix.python-version }}"
          if-no-files-found: error
          include-hidden-files: true
          retention-days: 7

  build-python:
    name: Build Python
    runs-on: ubuntu-latest
    permissions:
      contents: read
    needs:
      - lint-python
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python 3.x
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"
          cache: "pip"
      - name: Install Hatch
        run: |
          pip3 --quiet install --upgrade hatch uv
          hatch --version
          uv --version
      - name: Build release files
        run: |
          hatch build --clean
      - uses: actions/upload-artifact@v4
        with:
          name: artifacts
          path: dist/*
          if-no-files-found: error
          retention-days: 7

  coverage-python:
    name: Check Python Coverage
    runs-on: ubuntu-latest
    needs:
      - test-python
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"
          cache: pip

      - name: Install dependencies
        run: python -m pip install --upgrade coverage[toml]

      - name: Download data
        uses: actions/download-artifact@v4
        with:
          merge-multiple: true

      - name: Combine coverage and fail if it's <95%
        run: |
          python -m coverage combine
          python -m coverage html --skip-covered --skip-empty
          python -m coverage report --fail-under=95

      - name: Upload HTML report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: htmlcov

  publish-docs:
    name: Publish Documentation
    runs-on: ubuntu-latest
    if: github.ref_name == 'main' || startsWith(github.ref, 'refs/tags/')
    needs:
      - lint-docs
    permissions:
      contents: write
    concurrency:
      group: publish-docs
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
          cache: pip
      - name: Install dependencies
        run: |
          pip install --upgrade hatch uv
      - name: Configure Git
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
      - name: Publish Develop Docs
        if: github.ref_name == 'main'
        run: |
          hatch run docs:deploy_develop
      - name: Publish Develop Docs
        if: startsWith(github.ref, 'refs/tags/')
        run: |
          hatch run docs:deploy_latest ${{ github.ref_name }}

  # This workflow relies on the user manually creating a "stub release" on GitHub with the correct version number in the tag.
  publish-github:
    name: Publish GitHub Release
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/')
    permissions:
      contents: write
    concurrency:
      group: publish-github
    needs:
      - build-python
      - coverage-python
      - publish-docs
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/download-artifact@v4
        with:
          name: artifacts
          path: dist
      - name: Get latest release info
        id: query-release-info
        uses: release-flow/keep-a-changelog-action@v3
        with:
          command: query
          version: ${{ github.ref_name }}
      - name: Display release info
        run: |
          echo "Version: ${{ steps.query-release-info.outputs.version }}"
          echo "Date: ${{ steps.query-release-info.outputs.release-date }}"
          echo "${{ steps.query-release-info.outputs.release-notes }}"
      - uses: ncipollo/release-action@v1
        with:
          artifacts: "dist/*.tar.gz,dist/*.whl"
          body: ${{ steps.query-release-info.outputs.release-notes }}
          allowUpdates: true

  publish-pypi:
    name: Publish PyPi Package
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/')
    permissions:
      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
    concurrency:
      group: publish-pypi
    needs:
      - publish-github
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: artifacts
          path: dist
      - name: Publish build to PyPI
        uses: pypa/gh-action-pypi-publish@v1.10.1