ci.yml

name: CI

# Runs the headless unit suite (including the strict hardware-feasibility gate that
# every effect/transition must clear) and the critical-error lint on each push/PR,
# plus a strict mkdocs build (a broken internal link or anchor fails it).
# The suite runs against the pygame simulator with a dummy SDL driver, so no display
# or audio device is needed on the runner.

on:
  push:
    branches: [main, master]
  pull_request:
  # Called by publish.yml as the release gate. The push trigger above only fires
  # for BRANCH pushes, so without this a tag's commit could reach PyPI having
  # never been tested at that exact SHA.
  workflow_call:

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.13"]
    env:
      SDL_VIDEODRIVER: dummy
      SDL_AUDIODRIVER: dummy
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip

      - name: Install dependencies
        # Editable install via the [dev] extra (which pulls in [simulator]: pygame,
        # numpy, Pillow). This exercises the real published install path, so a
        # packaging regression fails CI here. The Makefile still sets PYTHONPATH=src;
        # the editable install resolves to the same in-tree source.
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e ".[dev]"

      - name: Critical-error lint
        run: make lint-errors

      - name: Unit tests (incl. strict feasibility gate)
        run: make test-unit

  coverage:
    # New and changed library lines must be tested, without imposing a sudden
    # percentage target on pre-existing uncovered code.
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip

      - name: Install test tools
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e ".[dev]"

      - name: Measure changed-line coverage
        run: |
          PYTHONSAFEPATH=1 PYTHONPATH=src python -m pytest test/unit --cov=scrollkit --cov-report=xml:coverage.xml
          diff-cover coverage.xml --compare-branch "origin/${{ github.base_ref }}" --fail-under=100

  media:
    # Mocked recording tests run in the normal matrix. This job additionally
    # exercises a real H.264 ffmpeg pipe and inspects it with ffprobe.
    runs-on: ubuntu-latest
    env:
      SDL_VIDEODRIVER: dummy
      SDL_AUDIODRIVER: dummy
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip

      - name: Install ffmpeg and test tools
        run: |
          sudo apt-get update
          sudo apt-get install --yes ffmpeg
          python -m pip install --upgrade pip
          python -m pip install -e ".[dev]"

      - name: Encode an MP4 smoke video
        run: PYTHONSAFEPATH=1 PYTHONPATH=src python -m pytest test/unit/simulator/test_recording.py -m ffmpeg -q

  package-smoke:
    # Editable installs in the unit matrix cannot prove that package data reaches
    # users. Build a wheel, install it into an isolated venv, then render from
    # outside the checkout so Python cannot fall back to src/.
    runs-on: ubuntu-latest
    env:
      SDL_VIDEODRIVER: dummy
      SDL_AUDIODRIVER: dummy
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip

      - name: Build and install wheel in a clean environment
        run: |
          python -m pip install --upgrade pip build
          python -m build
          python -m venv /tmp/scrollkit-wheel-smoke
          WHEEL="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
          /tmp/scrollkit-wheel-smoke/bin/pip install "$WHEEL[simulator]"

      - name: Import and render from installed wheel
        run: |
          cd /tmp
          PYTHONSAFEPATH=1 /tmp/scrollkit-wheel-smoke/bin/python "$GITHUB_WORKSPACE/test/packaging/wheel_smoke.py"

  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip

      - name: Install docs dependencies
        # The docs are hand-written markdown (no mkdocstrings autodoc), so this only
        # needs the [docs] extra (mkdocs + material) — the package isn't imported.
        run: |
          python -m pip install --upgrade pip
          python -m pip install ".[docs]"

      - name: Build docs (strict)
        # --strict fails on any warning, e.g. a broken internal link or anchor.
        run: mkdocs build --strict