mutation-testing.yml

---
# Mutation testing — weekly scheduled run on GitHub Actions (ubuntu-latest).
#
# Purpose: Establish and track mutation score baseline for the 20 most critical
#          modules. Docker is NOT required (avoids the shell-executor unreliability
#          that affects GitLab CI).
#
# TC-SRHP-04 — Resolve Docker CI Unreliability for Mutation Testing
#
# Advisory: This job never blocks merges. Results are uploaded as artifacts.
# Target:   >= 70% killed mutation score for critical modules.

name: Mutation Testing

on:
  schedule:
    # Weekly on Sunday at 02:00 UTC (off-peak)
    - cron: "0 2 * * 0"
  workflow_dispatch:
    inputs:
      target_modules:
        description: "Comma-separated list of modules to target (default: critical set)"
        required: false
        default: ""

permissions:
  contents: read

jobs:
  mutation-testing:
    name: mutmut (ubuntu-latest)
    runs-on: ubuntu-latest
    # Advisory: never block CI
    continue-on-error: true
    timeout-minutes: 60

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
          # Pin mutmut to 2.x — v3 changed CLI interface (--paths-to-mutate deprecated)
          pip install "mutmut<3"

      - name: Run mutation testing on critical modules
        id: mutmut
        run: |
          # Targeted scope: example_scorer.py only (smallest critical module, fits in 60 min).
          # Full 3-module run timed out at 60 min (GHA run 27899842949, 2026-06-21).
          # Once baseline is established, expand scope in future runs.
          # mutmut 2.x CLI: --paths-to-mutate and --tests-dir are supported.
          mutmut run \
            --paths-to-mutate src/plugin_examples/quality/example_scorer.py \
            --tests-dir tests/unit \
            || true

          # Print results summary to log
          mutmut results || true

      - name: Save mutation results
        if: always()
        run: |
          mkdir -p workspace/evidence/mutation
          # Query .mutmut-cache SQLite directly via helper script (TC-SRHP-22).
          # Avoids bash heredoc inside YAML block scalar (YAML parse error).
          python3 scripts/mutmut_results.py > workspace/evidence/mutation/mutmut-results.json
          echo "Mutation results:"
          cat workspace/evidence/mutation/mutmut-results.json

      - name: Upload mutation results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: mutation-testing-results
          path: workspace/evidence/mutation/
          retention-days: 30