ci.yml

# GitHub Actions configuration **EXAMPLE**,
# MODIFY IT ACCORDING TO YOUR NEEDS!
# Reference: https://docs.github.com/en/actions

name: tests

on:
  push:
    # Avoid using all the resources/limits available by checking only
    # relevant branches and tags. Other branches can be checked via PRs.
    branches: [main]
    tags: ['v[0-9]*', '[0-9]+.[0-9]+*']  # Match tags that resemble a version
  pull_request:  # Run in every PR
  workflow_dispatch:  # Allow manually triggering the workflow
  schedule:
    # Run roughly every 15 days at 00:00 UTC
    # (useful to check if updates on dependencies break the package)
    - cron: '0 0 1,16 * *'

permissions:
  contents: read

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

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      wheel-distribution: ${{ steps.wheel-distribution.outputs.path }}
    steps:
      - uses: actions/checkout@v3
        with: {fetch-depth: 0}  # deep clone for setuptools-scm
      - uses: actions/setup-python@v4
        id: setup-python
        with: {python-version: "3.11"}
      - name: Run static analysis and format checkers
        run: pipx run pre-commit run --all-files --show-diff-on-failure
      - name: Build package distribution files
        run: >-
          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
          tox -e clean,build
      - name: Record the path of wheel distribution
        id: wheel-distribution
        run: echo "path=$(ls dist/*.whl)" >> $GITHUB_OUTPUT
      - name: Store the distribution files for use in other stages
        # `tests` and `publish` will use the same pre-built distributions,
        # so we make sure to release the exact same package that was tested
        uses: actions/upload-artifact@v4
        with:
          name: python-distribution-files
          path: dist/
          retention-days: 1

  test:
    needs: prepare
    strategy:
      matrix:
        python:
        - "3.10"  # oldest Python supported by PSF
        - "3.13"  # newest Python that is stable
        platform:
        - ubuntu-latest
        - macos-latest
        - windows-latest
    permissions:
      contents: read
    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        id: setup-python
        with:
          python-version: ${{ matrix.python }}
      - name: Retrieve pre-built distribution files
        uses: actions/download-artifact@v4
        with: {name: python-distribution-files, path: dist/}
      - name: Run tests
        run: >-
          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
          tox -e test --installpkg '${{ needs.prepare.outputs.wheel-distribution }}'
          -- -rFEx --durations 10 --color yes  # pytest args
      - name: Generate coverage report
        run: pipx run coverage lcov -o coverage.lcov
      - name: Upload partial coverage report
        uses: coverallsapp/github-action@master
        with:
          path-to-lcov: coverage.lcov
          github-token: ${{ secrets.GITHUB_TOKEN }}
          flag-name: ${{ matrix.platform }} - py${{ matrix.python }}
          parallel: true

  benchmark:
    needs: prepare
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Need history for comparison
      - uses: actions/setup-python@v4
        id: setup-python
        with:
          python-version: "3.11"
      - name: Retrieve pre-built distribution files
        uses: actions/download-artifact@v4
        with: {name: python-distribution-files, path: dist/}

      # Run current benchmarks
      - name: Run benchmark tests
        run: >-
          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
          tox -e benchmark --installpkg '${{ needs.prepare.outputs.wheel-distribution }}'
        continue-on-error: true

      # Save current results before switching branches
      - name: Save current benchmark results
        if: github.event_name == 'pull_request'
        run: |
          if [ -f benchmark_results.json ]; then
            cp benchmark_results.json current_benchmark.json
            echo "✓ Saved current benchmark results"
          else
            echo "⚠️  No benchmark_results.json found"
            ls -la
          fi

      # Try to get baseline from main branch
      - name: Get baseline benchmarks
        if: github.event_name == 'pull_request'
        run: |
          git fetch origin main:main || true
          git checkout main || exit 0
          # Install from source (no --installpkg) to match checked-out main branch code
          # This prevents wheel/source mismatch where PR wheel is used with main branch tests
          pipx run --python '${{ steps.setup-python.outputs.python-path }}' \
            tox -e benchmark || true
          if [ -f benchmark_results.json ]; then
            mv benchmark_results.json baseline_benchmark.json
            echo "✓ Saved baseline benchmark results"
          else
            echo "⚠️  No baseline benchmarks generated"
          fi
          git checkout ${{ github.head_ref }}
        continue-on-error: true

      # Restore current results
      - name: Restore current benchmark results
        if: github.event_name == 'pull_request'
        run: |
          if [ -f current_benchmark.json ]; then
            mv current_benchmark.json benchmark_results.json
            echo "✓ Restored current benchmark results"
          fi
          echo "Files available for comparison:"
          ls -la *.json || echo "No JSON files found"

      # Compare benchmarks if baseline exists
      - name: Compare with baseline
        if: github.event_name == 'pull_request' && hashFiles('baseline_benchmark.json') != ''
        run: |
          echo "Running benchmark comparison..."
          echo "Checking files exist..."

          if [ ! -f baseline_benchmark.json ]; then
            echo "❌ baseline_benchmark.json not found!"
            exit 1
          fi

          if [ ! -f benchmark_results.json ]; then
            echo "❌ benchmark_results.json not found!"
            exit 1
          fi

          echo "✓ Both files exist, running comparison..."

          python scripts/compare_benchmarks.py \
            baseline_benchmark.json \
            benchmark_results.json \
            --threshold 1.3 \
            --quiet > benchmark_comparison.txt

          echo "Comparison output:"
          cat benchmark_comparison.txt
        continue-on-error: true

      # Comment on PR with results
      - name: Post benchmark results to PR
        if: github.event_name == 'pull_request' && hashFiles('baseline_benchmark.json') != ''
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            let comparison = 'No comparison data available';

            try {
              if (fs.existsSync('benchmark_comparison.txt')) {
                comparison = fs.readFileSync('benchmark_comparison.txt', 'utf8').trim();
                if (!comparison) {
                  comparison = 'Comparison file is empty - check workflow logs for details';
                }
              }
            } catch (e) {
              comparison = `Error reading comparison: ${e.message}`;
              console.error('Error:', e);
            }

            const body = `## 📊 Benchmark Results

            <details>
            <summary>Click to see benchmark comparison</summary>

            \`\`\`
            ${comparison}
            \`\`\`

            </details>

            **Threshold:** 1.3x (30% slower triggers a regression warning)

            **Note:** Benchmarks are informational only and won't fail the build.

            <sub>💡 Tip: Download the \`benchmark-results\` artifact for detailed JSON data</sub>
            `;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });
        continue-on-error: true

      # Upload benchmark artifacts
      - name: Upload benchmark results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: benchmark-results
          path: |
            benchmark_results.json
            baseline_benchmark.json
            .benchmarks/
          retention-days: 30

  finalize:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Finalize coverage report
        uses: coverallsapp/github-action@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          parallel-finished: true

  publish:
    needs: finalize
    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/tags/') }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with: {python-version: "3.11"}
      - name: Retrieve pre-built distribution files
        uses: actions/download-artifact@v4
        with: {name: python-distribution-files, path: dist/}
      - name: Publish Package
        env:
          # TODO: Set your PYPI_TOKEN as a secret using GitHub UI
          # - https://pypi.org/help/#apitoken
          # - https://docs.github.com/en/actions/security-guides/encrypted-secrets
          TWINE_REPOSITORY: pypi
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
        run: pipx run tox -e publish