ci.yml

name: CI

# Python jobs (lint/test/build) skip when a change touches only prose or
# metadata -- Markdown, the docs site, the JOSS paper (paper.md/paper.bib), and
# citation/archive metadata (CITATION.cff, .zenodo.json, LICENSE) -- none of
# which affect the package. Spell-checking (typos.yml) and the paper PDF build
# (draft-pdf.yml) have their own triggers, so prose is still checked.
on:
  push:
    branches: [main]
    paths-ignore:
      - "**.md"
      - "**.bib"
      - "docs/**"
      - "mkdocs.yml"
      - "CITATION.cff"
      - ".zenodo.json"
      - "LICENSE"
  pull_request:
    paths-ignore:
      - "**.md"
      - "**.bib"
      - "docs/**"
      - "mkdocs.yml"
      - "CITATION.cff"
      - ".zenodo.json"
      - "LICENSE"

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    name: Lint (ruff)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
          enable-cache: true
      - run: uv sync
      - name: ruff check
        run: uv run ruff check .
      - name: ruff format --check
        run: uv run ruff format --check .

  typecheck:
    name: Type check (ty)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
          enable-cache: true
      # ty is in the dev dependency group and version-locked via uv.lock, so
      # `uv sync` installs the same version used locally and by the pre-commit
      # hook. Optional-extra imports absent from the base env (mlx, mne) carry
      # scoped `# ty: ignore` comments, so this runs on the plain base env like
      # the other jobs (issue #119).
      - run: uv sync
      - name: ty check
        run: uv run ty check .

  test:
    name: Test (Python 3.12)
    needs: [lint, typecheck]
    runs-on: ubuntu-latest
    env:
      PYTORCH_ENABLE_MPS_FALLBACK: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
          enable-cache: true
      - run: uv sync
      # Build the dependency-free native binary (epic #165) so the AMICANative
      # engine's end-to-end tests run for real on Linux (they skip without
      # PAMICA_NATIVE_BINARY). Static reference LAPACK/BLAS, same as the release.
      - name: Build native AMICA binary (for engine E2E tests)
        run: |
          sudo apt-get update
          sudo apt-get install -y gfortran liblapack-dev libblas-dev
          LAPACK_LIBS="-l:liblapack.a -l:libblas.a" EXTRA_LDFLAGS="-static-libquadmath" \
            bash native/build.sh
          echo "PAMICA_NATIVE_BINARY=$PWD/native/amica15_shim" >> "$GITHUB_ENV"
      # Exclude the "slow" parity tests: they invoke the macOS-only Fortran
      # reference binary (pamica/sample_data/amica15mac), which cannot run on
      # the Linux runner. MPS-specific tests self-skip when MPS is absent.
      # -n auto parallelizes the (independent) torch fits across runner cores;
      # pytest-cov combines per-worker branch coverage automatically. Coverage
      # config + the fail-under gate live in pyproject.toml / the flag below.
      - name: pytest (excluding slow / Fortran-binary parity tests)
        run: uv run pytest -m "not slow" -n auto --cov-fail-under=80
      - name: Upload coverage HTML report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-html
          path: htmlcov/
          retention-days: 14
      # Codecov is informational (badge + PR coverage-diff comments); the hard
      # gate is --cov-fail-under in the pytest step above, so a flaky upload
      # (fail_ci_if_error: false) never breaks the build.
      - name: Upload coverage to Codecov
        if: always()
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: coverage.xml
          fail_ci_if_error: false

  test-mne:
    name: Test MNE wrapper (optional [mne] extra)
    needs: [lint, typecheck]
    runs-on: ubuntu-latest
    env:
      PYTORCH_ENABLE_MPS_FALLBACK: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
          enable-cache: true
      # mne IS pip-installable on Linux (unlike the Apple-only mlx extra), so the
      # AMICAICA wrapper (issue #139) is exercised for real in CI here. Its tests
      # live in pamica/tests/mne_tests and self-skip in the base `test` job
      # (importorskip on mne); this job installs the [mne] extra so they run on
      # the real sample EEG. pamica/mne_compat is omitted from coverage in
      # pyproject (the base env has no mne), so no fail-under gate applies here.
      - run: uv sync --extra mne
      - name: pytest (mne wrapper, real sample EEG)
        run: uv run pytest pamica/tests/mne_tests

  build:
    name: Build + import (Python ${{ matrix.python-version }})
    needs: [lint, typecheck]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
      - name: Build sdist + wheel
        run: uv build
      # Verify requires-python>=3.12 compatibility: install the built wheel and
      # its declared dependencies into a clean environment and import it.
      - name: Install wheel into a clean env and import
        run: |
          uv venv --python ${{ matrix.python-version }} .import-venv
          uv pip install --python .import-venv dist/*.whl
          .import-venv/bin/python -c "import pamica; print('pamica', pamica.__version__)"