python-app.yml

# CI for topiary.
#
# Split by test tier (see CLAUDE.md and tests/BASELINE.md):
#
#   unit         hermetic -- no network, no subprocess, no external binary.
#                Needs nothing but a pip install, so it runs on the full
#                matrix in parallel and gives feedback in a couple of minutes.
#   smoke        real data and real file I/O. Needs muscle/blast from conda,
#                but not the compiled RAxML-NG or GeneRax.
#   integration  needs the compiled binaries *and* live network access (local
#                BLAST and Open Tree of Life -- note that --run-generax and
#                --run-raxml both reach OTL, because setting up a GeneRax run
#                annotates the species tree from it). The live NCBI Entrez
#                tests (--run-ncbi-server) are deliberately excluded; see the
#                nightly step.
#
# Only `integration` is serialized. It contends for external services, which
# was the reason the whole workflow used to run with max-parallel: 1.

name: topiary

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    # Nightly full-matrix integration run, 07:00 UTC
    - cron: '0 7 * * *'
  workflow_dispatch:

jobs:

  # ---------------------------------------------------------------------------
  # Fast, hermetic. Full matrix, fully parallel, no conda and no compilation.
  # ---------------------------------------------------------------------------
  unit:
    name: unit (${{ matrix.os }}, py${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        python-version: ['3.11', '3.12', '3.13']

    steps:
    - uses: actions/checkout@v4

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

    - name: install
      run: |
        python -m pip install --upgrade pip
        python -m pip install ".[test]" pytest-mock

    - name: flake8
      run: |
        flake8 src/topiary tests --count --select=E9,F63,F7,F82 --show-source --statistics

    - name: audit tests that verify nothing
      run: |
        ./tests/audit_tests.py tests --max-stub 0 --max-noassert 0

    - name: run unit tests
      run: |
        pytest tests -m unit -q

  # ---------------------------------------------------------------------------
  # Real data and real file I/O. Needs muscle/blast from conda, but does not
  # need RAxML-NG or GeneRax, so it skips the expensive compile.
  # ---------------------------------------------------------------------------
  smoke:
    name: smoke (${{ matrix.os }}, py${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        python-version: ['3.11', '3.12', '3.13']

    steps:
    - uses: actions/checkout@v4

    - name: set up miniconda
      uses: conda-incubator/setup-miniconda@v3
      with:
        activate-environment: topiary
        environment-file: environment.yml
        channel-priority: strict
        python-version: ${{ matrix.python-version }}
        auto-activate-base: false
        miniconda-version: "latest"

    - name: install topiary
      shell: bash -l {0}
      run: |
        python -m pip install ".[test]" pytest-mock

    - name: run smoke tests
      shell: bash -l {0}
      run: |
        pytest tests -m smoke -q

  # ---------------------------------------------------------------------------
  # External binaries and live services. This is the slow, flaky-by-nature tier,
  # so it is the only one that is serialized and the only one that compiles
  # RAxML-NG and GeneRax.
  #
  # On a push/PR: one OS, one python. Nightly: the full matrix.
  # ---------------------------------------------------------------------------
  integration:
    name: integration (${{ matrix.os }}, py${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    # Serialize across the whole repo: these tests share NCBI and Open Tree of
    # Life, and running several at once gets us rate limited.
    concurrency:
      group: topiary-integration
      cancel-in-progress: false
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        # Push/PR: one representative configuration. Nightly -- and a manual
        # workflow_dispatch, so the nightly is reproducible on demand rather
        # than only at 07:00 UTC -- the full matrix.
        os: >-
          ${{ (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
              && fromJSON('["ubuntu-latest","macos-latest"]')
              || fromJSON('["ubuntu-latest"]') }}
        python-version: >-
          ${{ (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
              && fromJSON('["3.11","3.12","3.13"]')
              || fromJSON('["3.13"]') }}

    steps:
    - uses: actions/checkout@v4

    - name: set up miniconda
      uses: conda-incubator/setup-miniconda@v3
      with:
        activate-environment: topiary
        environment-file: environment.yml
        channel-priority: strict
        python-version: ${{ matrix.python-version }}
        auto-activate-base: false
        miniconda-version: "latest"

    - name: get dependency hashes
      id: get-hashes
      shell: bash
      run: |
        GENERAX_HASH=$(git ls-remote https://github.com/harmslab/generax.git HEAD | awk '{print $1}')
        RAXML_HASH=$(git ls-remote https://github.com/harmslab/raxml-ng.git HEAD | awk '{print $1}')
        echo "generax_hash=$GENERAX_HASH" >> $GITHUB_OUTPUT
        echo "raxml_hash=$RAXML_HASH" >> $GITHUB_OUTPUT

    - name: cache generax
      id: cache-generax
      uses: actions/cache@v4
      with:
        path: bin-cache/generax
        key: ${{ runner.os }}-generax-${{ steps.get-hashes.outputs.generax_hash }}-${{ hashFiles('dependencies/compile-generax.sh') }}

    - name: cache raxml-ng
      id: cache-raxml
      uses: actions/cache@v4
      with:
        path: bin-cache/raxml-ng
        key: ${{ runner.os }}-raxml-${{ steps.get-hashes.outputs.raxml_hash }}-${{ hashFiles('dependencies/compile-raxml-ng.sh') }}

    - name: install topiary and external binaries
      shell: bash -l {0}
      run: |
        conda install -c conda-forge cmake
        python -m pip install ".[test]" pytest-mock -vv

        mkdir -p bin-cache

        # Does this binary actually run here? Uses topiary's own checker, which
        # distinguishes "not in PATH" from "present but crashes".
        validate () {
            python - "$1" <<'PYEOF'
        import sys
        from topiary._private import installed
        checker = {"raxml-ng": installed.check_raxml,
                   "generax": installed.check_generax}[sys.argv[1]]
        _, version, _ = checker()
        # (-2,-2,-2) not found; (-1,-1,-1) found but does not run
        sys.exit(1 if tuple(version) in ((-1,-1,-1),(-2,-2,-2)) else 0)
        PYEOF
        }

        # A cached binary is only usable if it runs on *this* runner. GitHub
        # runners are heterogeneous, and a binary built on a machine with a
        # newer instruction set dies with SIGILL on an older one -- which the
        # cache key cannot see. So validate before trusting the cache, and
        # rebuild on the spot if it does not run. Compiling on the machine that
        # will run it is always correct.
        install_or_build () {
            name="$1"
            script="$2"

            if [ -f "bin-cache/$name" ]; then
                cp "bin-cache/$name" "$CONDA_PREFIX/bin/"
                if validate "$name"; then
                    echo "$name: cached binary runs on this runner"
                    return 0
                fi
                echo "::warning::$name from cache does not run on this runner (likely built on a different CPU); rebuilding"
                rm -f "bin-cache/$name" "$CONDA_PREFIX/bin/$name"
            fi

            ( cd dependencies && conda run -n topiary bash "$script" )
            cp "$CONDA_PREFIX/bin/$name" bin-cache/
        }

        install_or_build generax compile-generax.sh
        install_or_build raxml-ng compile-raxml-ng.sh

    # Fail here, with topiary's own diagnostic, rather than through a dozen
    # confusing test failures further down.
    - name: verify the external stack
      shell: bash -l {0}
      run: |
        topiary-check-installed
        python -c "
        from topiary._private import installed
        installed.validate_stack([{'program':'raxml-ng','min_version':(1,1,0),'must_pass':True},
                                  {'program':'generax','min_version':(2,0,0),'must_pass':True}])
        print('external stack OK')
        "

    # --run-ncbi-server is deliberately left out of CI entirely -- see the
    # nightly step below for why.
    - name: run integration tests
      if: github.event_name != 'schedule' && github.event_name != 'workflow_dispatch'
      shell: bash -l {0}
      run: |
        pytest tests --run-raxml --run-generax --run-blast --run-network -q

    - name: run integration tests (nightly, everything)
      if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
      shell: bash -l {0}
      run: |
        # NOTE: --run-ncbi-server is deliberately absent.
        #
        # Those tests query the live NCBI Entrez server, which rate-limits
        # unauthenticated traffic to ~3 requests/second per IP. GitHub runners
        # share IP space, so CI reliably gets HTTP 429 "Too Many Requests" --
        # and serializing does not help, because the limit is per IP per unit
        # time, not per concurrent job.
        #
        # This was already decided once: 5840a38 added mocked equivalents and
        # ff068f1 removed the flag from CI. It was re-added by mistake during
        # the workflow split and is removed again here. The logic is covered by
        # tests/topiary/ncbi/entrez/*_mock.py, and dropping the flag keeps the
        # suite above the coverage floor.
        #
        # To run these against the live server, do it locally:
        #     pytest tests --run-ncbi-server
        # Setting NCBI_API_KEY raises the limit to ~10 req/s if you need it.
        # Every command's status is captured and reported by name rather than
        # letting `set -e` end the step at the first failure. A step that only
        # says "exit code 1" after an all-green test summary is unactionable --
        # it does not say whether pytest, the coverage guard, the floor check or
        # the wrapper produced the 1. Each of those now prints its own verdict.
        set +e

        coverage run -m pytest tests \
          --run-raxml --run-generax --run-blast --run-network -q
        pytest_status=$?

        echo "::group::coverage"
        # Did coverage watch the code the tests actually imported? Without this
        # a mismatch shows up as 0% everywhere and looks like a regression.
        ./tests/check_coverage_collected.py
        guard_status=$?

        # Only the --fail-under report is run: it prints the same table as a
        # bare `coverage report`, so running both just doubled the log.
        coverage report --fail-under=92
        floor_status=$?
        echo "::endgroup::"

        echo "pytest=$pytest_status coverage-guard=$guard_status coverage-floor=$floor_status"

        if [ "$pytest_status" -ne 0 ]; then
          echo "::error::pytest exited $pytest_status -- if the summary above shows no failures, that status came from the wrapper rather than from a test. Compare it with the 'pytest exit status' line tests/conftest.py prints whenever pytest itself exits nonzero: if that line is absent, pytest returned 0 and coverage.py invented the failure."
          exit "$pytest_status"
        fi

        if [ "$guard_status" -ne 0 ]; then
          echo "::error::coverage collected nothing usable (guard exited $guard_status)"
          exit "$guard_status"
        fi

        if [ "$floor_status" -ne 0 ]; then
          echo "::error::coverage is below the 92% floor (exited $floor_status)"
          exit "$floor_status"
        fi

    # A handful of real NCBI calls, to catch the API changing shape underneath
    # us -- everything else mocks NCBI, so drift would otherwise surface as a
    # broken user run rather than a red build.
    #
    # Restricted to one configuration so the nightly makes ~7 NCBI requests in
    # total rather than 7 per matrix job, which is what got us rate limited.
    # The tests themselves skip (not fail) on HTTP 429 or any other transport
    # error, so a busy NCBI cannot turn this red.
    - name: NCBI API drift check
      if: >-
        (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
        && matrix.os == 'ubuntu-latest'
        && matrix.python-version == '3.13'
      shell: bash -l {0}
      run: |
        pytest tests/topiary/ncbi/entrez/test_ncbi_api_drift.py \
          --run-ncbi-server -v