mutation.yml

# SPDX-License-Identifier: Apache-2.0
# nearmiss — ADVISORY mutation testing (backlog #15).
#
# This workflow is intentionally NOT part of the merge gate. It never runs on
# `pull_request` or `push`, so it can never block a PR. It runs only:
#   * on demand   (workflow_dispatch), and
#   * once a week  (schedule), as a slow-drift signal on the correctness of the
#     spatial-statistics core (the Getis-Ord Gi* hotspot + the rate CIs).
#
# Mutation score is a health signal, not a gate: `make mutation` swallows a
# non-zero exit, and this job is `continue-on-error` on top of that, so a dip in
# the score surfaces in the run summary WITHOUT ever turning a required check red.
# The blocking correctness gate remains `make test` (branch-coverage floor) in
# ci.yml. See docs/MUTATION-TESTING.md for the baseline and how to read survivors.

name: mutation (advisory)

on:
  workflow_dispatch: {}
  schedule:
    # Mondays at 06:00 UTC. Weekly cadence — mutation runs are slow and advisory.
    - cron: "0 6 * * 1"

permissions:
  contents: read

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

jobs:
  mutation:
    name: mutation (mutmut on stats core — advisory, non-blocking)
    runs-on: ubuntu-24.04
    # Belt-and-suspenders: even though this workflow never runs on a PR, mark the
    # job non-failing so it is impossible to wire it up as a required check.
    continue-on-error: true
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev + mutation dependencies
        run: python -m pip install -e ".[dev,mutation]"

      - name: Run advisory mutation testing (mutmut, scoped to stats core)
        # `make mutation` is advisory by construction (it never returns non-zero on
        # surviving mutants); the extra `|| true` documents that this step is a
        # signal, not a gate.
        run: make mutation || true