houseplan-card/.github/workflows/mutation-gate.yml

name: Мутационный гейт

# Реестр известных поломок (issue #85): каждый мутант ломает продуктовый код
# известным способом, и объявленный тест ОБЯЗАН на этом покраснеть. Тест,
# оставшийся зелёным на сломанном коде, ничего не защищает — он лишь выглядит
# защитой, и это хуже его отсутствия.
#
# Прогон дорогой и проверяет не продукт, а тесты, поэтому он не входит ни в
# Validate, ни в цикл разработки, ни в релизный гейт (#513, решение владельца
# 09.09): каждую ночь по расписанию, отказ — issue с отчётом (#472).
# Мутанты, задетые диффом, конвейер ревью и слияние гоняют отдельно на своём
# кандидате (#510); кандидат беты, `full=true` и ночной Validate их не
# запрашивают (#601) — ночью достаточно этого полного реестра.
# Дешёвая половина — «якоря патчей живы, guard-файлы существуют» — идёт с
# обычными юнитами: test/mutation-gate.test.mjs.
#
# #332: бандл собирается только мутантам с браузерным гвардом (guardNeedsBundle),
# компиляция тестов в worktree стартует с тёплого test-build (инкрементальный
# tsc), а реестр режется на четыре чересполосных шарда — полный прогон
# укладывается в десятки минут вместо часов. Локальный дифф-режим:
# node scripts/mutation-gate.mjs --changed origin/dev..HEAD

on:
  workflow_dispatch:
    inputs:
      ref:
        description: Git ref whose mutation guards must be proved
        required: false
        default: dev
  schedule:
    # Каждую ночь, 01:00 UTC (04:00 MSK) — после суток правок и до ночного
    # полного Validate (nightly.yml, 02:30 UTC), чтобы не делить раннеры (#513).
    - cron: '0 1 * * *'

permissions:
  contents: read

# Группа зависит от события (#472). Прежде она была одна на всё, и ручной
# запуск (отладка гейта) отменял идущий по расписанию — так 24.08 погиб
# еженедельный прогон, а отменённый в списке выглядит «не красным». Поймать
# отмену изнутри нельзя: вместе с прогоном отменяются и не начавшиеся job,
# включая любой репортёр. Значит отмену надо не ловить, а не допускать.
concurrency:
  group: mutation-gate-${{ github.event_name }}
  cancel-in-progress: true

jobs:
  # #549: moving ref разрешается ровно один раз. Все шарды ниже получают один
  # commit/tree, а не самостоятельно читают dev в разное время.
  material:
    name: "Зафиксировать неизменяемый материал"
    runs-on: ubuntu-latest
    outputs:
      sha: ${{ steps.identity.outputs.sha }}
      tree: ${{ steps.identity.outputs.tree }}
      ref: ${{ steps.identity.outputs.ref }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || 'dev' }}
          fetch-depth: 0
      - name: Зафиксировать commit и tree
        id: identity
        run: |
          echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
          echo "tree=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_OUTPUT"
          echo "ref=${{ github.event_name == 'workflow_dispatch' && inputs.ref || 'dev' }}" >> "$GITHUB_OUTPUT"

  mutants:
    name: "Мутанты: каждый обязан красить тесты (шард ${{ matrix.shard }} из 6)"
    needs: material
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6]
    # Шесть чересполосных шардов (#604): при четырёх шард нёс ~203 мутанта из
    # 810 и рос с реестром — 42 мин 10.09, 57 мин 20.09, 61 мин 21.09, и шард
    # 2/4 был снят по потолку без единого FAIL. Делитель тот же, что у
    # `changed_mutants` в Validate; число шардов повторяется в `--shard=i/6`,
    # `--shards=6` и имени job — тест `mutation-gate.test.mjs` держит их
    # равными. Бандл собирают только браузерные гварды. Час — потолок против
    # зависшего Chromium, а не бюджет шарда: шард, упёршийся в него, — сигнал
    # снова делить, и отчёт (#472) называет такой шард прерванным, не «ok».
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: ${{ needs.material.outputs.sha }}
          fetch-depth: 0

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
        with:
          python-version: '3.14'

      - name: Установить backend test dependencies
        run: |
          # Точные версии — в tests_backend/requirements.txt (#392): без них
          # резолвер выбирает набор сам, и «зелёный backend» значит разное
          # в разные дни.
          pip install -r tests_backend/requirements.txt
          pip list --format=columns | grep -Ei 'homeassistant|voluptuous|^pytest '

      - name: Кэш браузеров Playwright
        id: pw
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Установить Chromium
        if: steps.pw.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps chromium

      - name: Реестр применим к текущему коду
        run: node scripts/mutation-gate.mjs --check

      - name: Тёплый test-build для инкрементальной компиляции мутантов
        run: npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs

      # Вывод шарда сохраняется артефактом (#472): строки
      # `FAIL <id>: тест остался зелёным…` — единственное место, где названо,
      # ЧТО сбежало. Без артефакта отказ безымянный. `PIPESTATUS` — чтобы
      # `tee` не съел код выхода раннера.
      - name: Каждый тест ловит свою поломку
        id: gate
        run: |
          mkdir -p artifacts/mutation-shard-${{ matrix.shard }}
          set -o pipefail
          node scripts/mutation-gate.mjs --shard=${{ matrix.shard }}/6 2>&1 | tee artifacts/mutation-shard-${{ matrix.shard }}/mutation-shard-${{ matrix.shard }}.log
      # Исход шага едет в evidence (#604): снятый по timeout-minutes шаг даёт
      # `cancelled`, и агрегатор отвергает такой шард как неполный — лог без
      # строк FAIL сам по себе зелёным не считается.
      - name: Записать identity шарда
        if: always()
        run: |
          node scripts/mutation-gate-report.mjs \
            --write-evidence=artifacts/mutation-shard-${{ matrix.shard }}/evidence.json \
            --sha=${{ needs.material.outputs.sha }} \
            --tree=${{ needs.material.outputs.tree }} \
            --workflow-sha=${{ github.workflow_sha }} \
            --run-id=${{ github.run_id }} --run-attempt=${{ github.run_attempt }} \
            --shard=${{ matrix.shard }} --shards=6 \
            --outcome=${{ steps.gate.outcome }}
      - name: Сохранить лог и identity шарда
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: mutation-shard-${{ matrix.shard }}-attempt-${{ github.run_attempt }}
          path: artifacts/mutation-shard-${{ matrix.shard }}
          if-no-files-found: warn
          retention-days: 30

  # Результат нельзя приписывать material, пока не доказаны все шесть шардов —
  # каждый с identity и с дошедшим до конца прогоном (#549, #604).
  # always() нужен при красном мутанте: лог красного шарда всё равно evidence.
  evidence:
    name: "Доказать единый material всех шардов"
    needs: [material, mutants]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          # CLI отчётчика принадлежит зафиксированному material. В main лежит
          # только workflow и может не быть dev-версии scripts/**.
          ref: ${{ needs.material.outputs.sha }}
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 22
      - name: Забрать evidence всех попыток
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          pattern: mutation-shard-*
          path: artifacts/mutation-logs
      - name: Проверить полноту и identity
        run: |
          node scripts/mutation-gate-report.mjs --verify-only \
            --logs=artifacts/mutation-logs --shards=6 \
            --sha=${{ needs.material.outputs.sha }} \
            --tree=${{ needs.material.outputs.tree }} \
            --workflow-sha=${{ github.workflow_sha }} \
            --run-id=${{ github.run_id }} --run-attempt=${{ github.run_attempt }}

  # Адресат у отказа (#472). Только по расписанию: ручной dispatch остаётся
  # для отладки самого гейта, его результат смотрят в прогоне — issue на
  # каждый такой отказ был бы шумом, который снова перестанут читать.
  #
  # Права job-уровня ЗАМЕНЯЮТ права workflow, а не дополняют (прецедент —
  # validate.yml, job с actions: read): перечислены все три.
  report:
    name: "Отказ расписания: issue и Telegram"
    needs: [material, mutants, evidence]
    if: always() && github.event_name == 'schedule' && (needs.mutants.result != 'success' || needs.evidence.result != 'success')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
      issues: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          # Не перечитываем moving dev: код отчётчика берётся из уже
          # зафиксированного material. В стабильном main dev-скриптов нет.
          ref: ${{ needs.material.outputs.sha }}
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 22
      - name: Забрать логи шардов
        continue-on-error: true
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          pattern: mutation-shard-*
          path: artifacts/mutation-logs
      - name: Собрать отчёт
        id: report
        env:
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          mkdir -p artifacts
          node scripts/mutation-gate-report.mjs \
            --require-evidence --logs=artifacts/mutation-logs --shards=6 \
            --sha=${{ needs.material.outputs.sha }} \
            --tree=${{ needs.material.outputs.tree }} \
            --workflow-sha=${{ github.workflow_sha }} \
            --run-id=${{ github.run_id }} --run-attempt=${{ github.run_attempt }} \
            --run-url="$RUN_URL" --ref=${{ needs.material.outputs.ref }} \
            --body-out=artifacts/mutation-report.md \
            --telegram-out=artifacts/mutation-telegram.txt >> "$GITHUB_OUTPUT"
      # Одно issue, а не одно на неделю: открытое с тем же маркером в заголовке
      # получает комментарий, новое заводится только если открытого нет.
      - name: Issue — создать или дописать
        id: issue
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
          MARKER: ${{ steps.report.outputs.marker }}
          TITLE: ${{ steps.report.outputs.title }}
        run: |
          existing=$(gh issue list --repo "$REPO" --state open --search "\"$MARKER\" in:title" \
            --json number,title --jq '[.[] | select(.title | startswith(env.MARKER))][0].number // empty')
          if [ -n "$existing" ]; then
            gh issue comment "$existing" --repo "$REPO" --body-file artifacts/mutation-report.md
            url="${{ github.server_url }}/$REPO/issues/$existing"
          else
            url=$(gh issue create --repo "$REPO" --title "$TITLE" \
              --label infra --label process --label tests \
              --body-file artifacts/mutation-report.md)
          fi
          echo "url=$url" >> "$GITHUB_OUTPUT"
          echo "issue: $url"
      # Тот же канал, что у релизов (announce.yml). Нет секретов — не отказ:
      # issue уже заведено, а Telegram — второй адресат, не единственный.
      - name: Telegram
        if: always() && steps.issue.outcome == 'success'
        env:
          TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
          ISSUE_URL: ${{ steps.issue.outputs.url }}
        run: |
          if [ -z "$TOKEN" ] || [ -z "$CHAT" ]; then
            echo "::warning::TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID не заданы — оповещение пропущено, issue заведено"
            exit 0
          fi
          TEXT=$(sed "s|(issue)|$ISSUE_URL|" artifacts/mutation-telegram.txt)
          curl -sS --fail-with-body -X POST \
            "https://api.telegram.org/bot$TOKEN/sendMessage" \
            --data-urlencode "chat_id=$CHAT" \
            --data-urlencode "text=$TEXT" \
            -d disable_web_page_preview=true