CI.yml

name: CI

# Minimal permissions following the principle of least privilege
permissions:
  contents: read

# Trigger CI on pushes to main and pull requests targeting main or release branches
on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - 'tests/**'
      - '.github/workflows/CI.yml'
      - 'pyproject.toml'
      - 'docs/**'
  pull_request:
    branches:
      - main
      - 'release**'
    paths:
      - 'src/**'
      - 'tests/**'
      - '.github/workflows/CI.yml'
      - 'pyproject.toml'
      - 'docs/**'

jobs:
  # Job to test core dependencies without optional (soft) dependencies
  test-core-dependencies:
    name: Test Core Dependencies
    runs-on: ubuntu-latest
    steps:
      # Step 1: Checkout the repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Ensure full history for accurate branch information

      # Step 2: Set up Python 3.11
      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      # Step 3: Cache pip dependencies to speed up builds
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      # Step 4: Setup virtual environment using the composite action
      - name: Setup Virtual Environment
        uses: ./.github/actions/setup-venv
        with:
          python-version: '3.11'

      # Step 5: Install package without optional dependencies
      - name: Install Package and Core Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip install . --no-cache-dir
        shell: bash

      - name: Install Package and Core Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip install . --no-cache-dir
        shell: pwsh

      # Step 6: Display installed dependencies for verification
      - name: Show Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip list
        shell: bash

      - name: Show Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip list
        shell: pwsh

      # Step 7: Run pytest-free tests
      - name: Run pytest-free Tests (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          python tests/_nopytest_tests.py
        shell: bash

      - name: Run pytest-free Tests (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          python tests/_nopytest_tests.py
        shell: pwsh

  # Job to test without optional dependencies across multiple Python versions and OSes
  test-no-optional-dependencies:
    name: Test Without Optional Dependencies
    needs: test-core-dependencies
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']
        os: [ubuntu-latest, macos-13, windows-latest]
    steps:
      # Step 1: Checkout the repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Step 2: Set up Python with the specified version
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      # Step 3: Cache pip dependencies to speed up builds
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      # Step 4: Setup virtual environment using the composite action
      - name: Setup Virtual Environment
        uses: ./.github/actions/setup-venv
        with:
          python-version: ${{ matrix.python-version }}

      # Step 5: Install package and dev dependencies
      - name: Install Package and Dev Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip install .[dev] --no-cache-dir
        shell: bash

      - name: Install Package and Dev Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip install .[dev] --no-cache-dir
        shell: pwsh

      # Step 6: Display installed dependencies for verification
      - name: Show Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip list
        shell: bash

      - name: Show Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip list
        shell: pwsh

      # Step 7: Show available branches for debugging
      - name: Show Available Branches
        run: git branch -a

      # Step 8: Run tests using pytest
      - name: Run Tests (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          python -m pytest src/ tests/ -vv
        shell: bash

      - name: Run Tests (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          python -m pytest src/ tests/ -vv
        shell: pwsh

  # Job to test with all optional dependencies across multiple Python versions and OSes
  test-all-optional-dependencies:
    name: Test With All Optional Dependencies
    needs: test-no-optional-dependencies
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']
        os: [ubuntu-latest, macos-13, windows-latest]
    steps:
      # Step 1: Checkout the repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Step 2: Set up Python with the specified version
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      # Step 3: Cache pip dependencies to speed up builds
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      # Step 4: Setup virtual environment using the composite action
      - name: Setup Virtual Environment
        uses: ./.github/actions/setup-venv
        with:
          python-version: ${{ matrix.python-version }}

      # Step 5: Install package and all dependencies including optional ones
      - name: Install Package and All Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip install .[all_extras,dev] --no-cache-dir
        shell: bash

      - name: Install Package and All Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip install .[all_extras,dev] --no-cache-dir
        shell: pwsh

      # Step 6: Display installed dependencies for verification
      - name: Show Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip list
        shell: bash

      - name: Show Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip list
        shell: pwsh

      # Step 7: Show available branches for debugging
      - name: Show Available Branches
        run: git branch -a

      # Step 8: Run tests using pytest
      - name: Run Tests (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          python -m pytest src/ tests/ -vv
        shell: bash

      - name: Run Tests (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          python -m pytest src/ tests/ -vv
        shell: pwsh

      # Step 9: Upload code coverage report to GitHub artifacts
      - name: Upload Coverage Report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-${{ matrix.python-version }}-${{ runner.os }}
          path: coverage.md

      # Step 10: Publish code coverage to Codecov
      - name: Publish Code Coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}  # Ensure this secret is set in your repository
          fail_ci_if_error: true
          verbose: true

  # Job to build and test documentation
  docs:
    name: Test Docs Build
    runs-on: ubuntu-latest
    steps:
      # Step 1: Checkout the repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Step 2: Set up Python 3.11
      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      # Step 3: Cache pip dependencies to speed up builds
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      # Step 4: Install uv and update PATH
      - name: Install uv and Update PATH
        run: |
          pip install uv
          echo "$(python -m site --user-base)/bin" >> $GITHUB_PATH
        shell: bash

      # Step 5: Setup virtual environment using the composite action
      - name: Setup Virtual Environment
        uses: ./.github/actions/setup-venv
        with:
          python-version: '3.11'

      # Step 6: Install package and documentation dependencies
      - name: Install Package and Dependencies (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          uv pip install .[dev,docs] --no-cache-dir
        shell: bash

      - name: Install Package and Dependencies (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          uv pip install .[dev,docs] --no-cache-dir
        shell: pwsh

      # Step 7: Build Sphinx documentation
      - name: Build Sphinx Documentation (Linux/macOS)
        if: runner.os != 'Windows'
        run: |
          source .venv/bin/activate
          cd docs
          make clean
          make html --debug --jobs 2 SPHINXOPTS=" -W -v"
        shell: bash

      - name: Build Sphinx Documentation (Windows)
        if: runner.os == 'Windows'
        run: |
          .\.venv\Scripts\Activate.ps1
          cd docs
          make clean
          make html --debug --jobs 2 SPHINXOPTS=" -W -v"
        shell: pwsh

      # Step 8: Upload built documentation as an artifact
      - name: Upload Built Docs
        uses: actions/upload-artifact@v4
        with:
          name: docs-results-${{ runner.os }}
          path: docs/build/html/
        # Ensure this step runs even if previous steps fail
        if: success()