checks.yml

name: Checks

on:
  push:
    branches:
      - master
      - '*_rel'
  repository_dispatch:
    # to run this, send a POST API call at repos/<user>/<repo>/dispatches with the specified event_type
    # e.g. `gh repos/CCSI-Toolset/FOQUS/dispatches -F event_type=ci_run_tests`
    types: [ci_run_tests]
  workflow_dispatch:
  pull_request:
    types:
      - opened
      # ready_for_review occurs when a draft PR is turned to non-draft
      - ready_for_review
      # synchronize occurs whenever commits are pushed to the PR branch
      - synchronize

defaults:
  run:
    # the -l flag is needed for the Conda environment to be activated properly
    shell: bash -l -eo pipefail {0}

env:
  FOQUS_CONDA_ENV_NAME_DEV: ccsi-foqus-dev
  PYTEST_BASETEMP: .pytest
  DEFAULT_PYTHON_VERSION: '3.10'

jobs:
  code-formatting:
    name: Code formatting (Black)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install Black
        # unlike the other jobs, we don't need to install FOQUS and/or all the dev dependencies,
        # but we still want to specify the Black version to use in requirements-dev.txt for local development
        # so we extract the relevant line and pass it to a simple `pip install`
        run: |
          # we store the version
          black_requirement="$(grep '^black.*$' requirements-dev.txt)"
          pip --no-cache-dir install --progress-bar off "$black_requirement"
      - name: Run Black to verify that the committed code is formatted
        run: |
          black --check .
  spell-check:
    name: Check Spelling
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v4
      - name: Run Spell Checker
        uses: crate-ci/typos@master
        with: 
          config: .typos.toml
  pytest:
    name: pytest (py${{ matrix.python-version }}/${{ matrix.os }})
    runs-on: ${{ matrix.os-version }}
    strategy:
      fail-fast: false
      matrix:
        python-version:
          - '3.8'
          - '3.9'
          - '3.10'
          - '3.11'
          - '3.12'
        os:
          - linux
          - win64
          - macos-x86_64
          - macos
        include:
          - os: macos-x86_64
            os-version: macos-13
          - os: macos
            os-version: macos-14
          - os: linux
            os-version: ubuntu-20.04
          - os: win64
            os-version: windows-2019
          - python-version: '3.10'  # avoid uploading coverage for full matrix
            use_coverage: true
          - python-version: '3.10'  # install ML AI dependencies with coverage run
            optional-dependencies: -r requirements-mlai.txt
          - python-version: '3.11'  # install ML AI dependencies with a newer Python version
            optional-dependencies: -r requirements-mlai.txt
    env:
      # uncomment this to debug Qt initialization errors
      # QT_DEBUG_PLUGINS: '1'
      MPLBACKEND: AGG
    steps:
      - uses: actions/checkout@v4
      - name: Set up Conda
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.FOQUS_CONDA_ENV_NAME_DEV }}
          python-version: ${{ matrix.python-version }}
          miniconda-version: latest
      - name: Set up FOQUS
        uses: ./.github/actions/setup-foqus
        with:
          pip-install-target: -r requirements-dev.txt ${{ matrix.optional-dependencies }}
      - name: Set up GUI test environment (Linux)
        if: contains(matrix.os, 'linux')
        run: |
          echo "QT_QPA_PLATFORM=minimal" >> $GITHUB_ENV
      - name: Set common pytest flags
        run:
          echo 'PYTEST_ADDOPTS=--pyargs foqus_lib --maxfail=3 --verbose --color=yes --basetemp "${{ env.PYTEST_BASETEMP }}"' >> $GITHUB_ENV
      - name: Add pytest coverage flags
        if: matrix.use_coverage
        run:
          echo "PYTEST_ADDOPTS=$PYTEST_ADDOPTS --cov=./ --cov-report=xml --cov-report=term" >> $GITHUB_ENV
      - name: Run pytest
        run: |
          pytest foqus_lib/
      - name: Upload pytest artifacts
        uses: actions/upload-artifact@v4
        if: always()
        with:
          # TODO decide if we need a separate upload for each Python version
          name: pytest-dir-${{ matrix.os }}-py${{ matrix.python-version }}
          path: ${{ env.PYTEST_BASETEMP }}
          retention-days: 7
      - name: Upload coverage report as job artifact
        if: always() && matrix.use_coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report-${{ matrix.os }}
          path: coverage.xml
          if-no-files-found: error

  upload-coverage:
    name: Upload coverage report (Codecov)
    needs: [pytest]
    runs-on: ubuntu-latest
    steps:
      # the checkout step is needed to have access to codecov.yml
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          pattern: coverage-report-*
      - name: Upload coverage report to Codecov
        uses: codecov/codecov-action@v4
        with:
          fail_ci_if_error: true
          verbose: true
          # NOTE: secrets are not available for pull_request workflows
          # However, as of 2024-02-10, Codecov is still allowing tokenless upload from PRs
          # but does require token for other workflows e.g. merge to `main`
          # see https://github.com/codecov/codecov-action/issues/1274#issuecomment-1934437359
          token: ${{ secrets.CODECOV_TOKEN }}
          # pinning version after v0.7.0 broke tokenless upload
          # see codecov/codecov-action#1487
          version: v0.7.2

  pylint:
    name: pylint (py${{ matrix.python-version }})
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        python-version:
          - '3.8'
          - '3.9'
          - '3.10'
          - '3.11'
          - '3.12'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Conda
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.FOQUS_CONDA_ENV_NAME_DEV }}
          python-version: ${{ matrix.python-version }}
      - name: Set up FOQUS
        uses: ./.github/actions/setup-foqus
        with:
          pip-install-target: -r requirements-dev.txt
      - name: Run pylint
        run: |
          pylint --rcfile=.pylint/pylintrc --disable=all --enable=E --enable=wrong-import-order foqus_lib/

  docs:
    name: Build docs
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
      - name: Set up Conda
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.FOQUS_CONDA_ENV_NAME_DEV }}
          python-version: ${{ matrix.python-version }}
      - name: Set up FOQUS
        uses: ./.github/actions/setup-foqus
        with:
          pip-install-target: -r requirements-dev.txt
      - name: Build docs
        run: |
          cd docs/
          make CLOPTS="-qW --keep-going" clean dummy