# CODE-REVIEW-472-r1 Issue: #472 — «Полный мутационный прогон по расписанию падал дважды подряд без реакции: у отказа нет адресата». Лёгкий трек (`small`), ТЗ в теле issue, принято владельцем в арбитраже после исчерпания бюджета ревью ТЗ (2/2, SPEC-REVIEW-472-r1, -r2). Код-ревью — первый заход, бюджет циклов 0/2. ## Материал раунда - SHA материала: `dec6c03e89af48f570bf60994b99aeacba0cb966` (HEAD на момент ревью, `git rev-parse HEAD`) - Дерево: `2e66a9609af6d88f98375efdad4af8be1758a524` (`git rev-parse HEAD^{tree}`) - Один коммит на весь диапазон `origin/dev..HEAD`: `dec6c03e ci: отчёт об отказе расписания мутантов — issue и Telegram`, трейлеры `Issue: #472`, `User-Visible: no`. - **Ветка приведена к `dev` конвейером до ревью**: поверх исходного `a8ea3b8a` легло 5 коммитов `dev` (rebase), финал — `dec6c03e`. После ребейза это другой код (PROCESS.md §7.2), но поскольку это первый заход ревью кода (r1), полный разбор требовался бы в любом случае — §2.10 (объём по дельте) относится ко второму и последующим заходам. - Реализация подтверждена только рабочей веткой (`Validate` зелёный на `a8ea3b8a`, run 34030761200 — до ребейза); на `dec6c03e` отдельного зелёного прогона не было, поэтому дешёвые гейты прогнаны заново мной, ниже. ## Скоуп диффа ``` .github/workflows/mutation-gate.yml | 105 ++++++++++++++++++++- .github/workflows/validate.yml | 28 +++--- scripts/mutation-gate-report.mjs | 177 ++++++++++++++++++++++++++++++++++++ (новый) scripts/mutation-gate.mjs | 34 +++++++ (3 мутанта) test/mutation-gate-report.test.mjs | 99 ++++++++++++++++++++ (новый, 8 тестов) test/mutation-gate.test.mjs | 49 ++++++++++ (7 контрактных тестов) ``` Класс B целиком (workflows, scripts, test) — ни один файл `src/**`, `custom_components/**/*.py`, манифестов или i18n не тронут. Пользователю видимых изменений нет (`User-Visible: no` корректен). `docs/SCOPE.md` неприменим содержательно: задача обслуживает сам процесс разработки, а не персону из ядра продукта, что и объявлено меткой `process`/`infra` — скоуп-рамка не нарушена, потому что не заявлена. ## Как проверялось — гейты | Гейт | Команда | Результат | |---|---|---| | typecheck | `npx tsc --noEmit` | зелёный, 0 ошибок | | unit | `npm test` | 2091 тестов, pass 2090, fail 0, skipped 1 (существующий, не мой) | | build + сверка 3 копий бандла | `npm run build && cmp dist/… custom_components/…` затем `npm run bundle:sync && cmp` (dist / custom_components / demo/srv/assets) | все три копии побайтово совпадают | | provenance | `node scripts/validate-commit-provenance.mjs dec6c03e~1..dec6c03e` | exit 0, трейлеры корректны | | YAML-синтаксис изменённых workflow | `python3 -c "yaml.safe_load(...)"` на `mutation-gate.yml` и `validate.yml` | оба парсятся | | new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | 0 добавленных строк в `src/**` — гейт неприменим, диффа во фронтенде нет | | smoke-select | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | «Исполняемого frontend-диффа нет… смоки этим диффом не выбираются» — браузерные смоки не нужны | | check-docs | не запускал | diff не трогает `src/**` — гейт не входит в обязательную часть (PROCESS.md §8) | | golden/pytest backend/performance | не запускал | нет визуальных, Python- или perf-чувствительных изменений; ни один не назван в AC | | model-invariants | не запускал | геометрия, `layout`, `marker.space`, толщина стен не затронуты | Три мутанта задачи (`mutation-report-drops-missing-shard`, `mutation-report-duplicates-escaped`, `mutation-report-red-guard-as-mutant`) прогнаны индивидуально, не только `--check`: ``` node scripts/mutation-gate.mjs --id=mutation-report-drops-missing-shard → поймано 1 из 1 (16.4s) node scripts/mutation-gate.mjs --id=mutation-report-duplicates-escaped → поймано 1 из 1 (15.9s) node scripts/mutation-gate.mjs --id=mutation-report-red-guard-as-mutant → поймано 1 из 1 (15.9s) ``` Каждый — реальный прогон в изолированном git-worktree (патч → `test-build/` → guard), не просмотр кода: «тест умеет падать» доказано исполнением, а не заявлением автора. ## Критерии приёмки — таблица «чем доказан · чем краснеет» | AC | Доказано | Чем краснеет | |---|---|---| | AC1 (группы concurrency разные) | контрактный тест `test/mutation-gate.test.mjs` + чтение `mutation-gate.yml:37` (`group: mutation-gate-${{ github.event_name }}`) | тест матчит буквальную строку с суффиксом события; без суффикса regex не совпадёт — «проверено чтением», мутанта на YAML в реестре нет (спецификой issue не требовалось) | | AC2 (лог шарда — артефакт, `if: always()`, код выхода сохранён) | контрактный тест + чтение: `set -o pipefail` перед `tee`, `if: always()` на шаге `Сохранить лог шарда`, `if-no-files-found: warn` | то же — «чтением»; пайплайн PIPESTATUS проверен вручную: `tee` без `pipefail` замаскировал бы ненулевой код `node`, тест ловит именно строку `set -o pipefail` | | AC3 (сбор escaped/redGuards/unparsed, дедуп, `missing`) | `test/mutation-gate-report.test.mjs`, 8 юнитов + 3 мутанта на реальном прогоне (см. выше) | мутация подтверждена исполнением: снятие проверки `known.has(...)`, дедупликации и статуса `missing` красит соответствующие тесты — «поймано 1 из 1» на каждом | | AC4 (заголовок с маркером, тело — прогон/SHA/`--id=`) | юнит `#472 AC4` | прогон со снятой защитой не проводился отдельно (простая сборка строки), но структура тела читается в `mutationGateReport` — «чтением» + юнит проверяет фактическое присутствие подстрок | | AC4b (отдельные разделы redGuards/unparsed, ни один не превращается в `--id=`) | юниты «красный гард…» и «id вне реестра…» | оба закрывают M3 из SPEC-REVIEW r2; мутант `mutation-report-red-guard-as-mutant` воспроизводит именно наивный парсер и подтверждён прогоном (см. выше) | | AC5 (job `report`: только schedule+не-success, права полностью) | контрактный тест + чтение permissions-блока | тест ищет буквально три строки прав и `if:`; неполные права не совпадут — «чтением» | | AC6 (комментарий вместо второго issue) | контрактный тест на порядок `gh issue list` → `comment`/`create` + анализ `jq`-фильтра (см. ниже, воспроизведено локально) | «чтением» на структуру workflow; сама логика `startswith(env.MARKER)` проверена мной вживую `jq`-выражением на фикстуре — см. раздел «Проверено дополнительно» | | AC7 (нет Telegram-секретов — не отказ) | контрактный тест + чтение шага `Telegram` | «чтением»: `if [ -z "$TOKEN" ] || [ -z "$CHAT" ]; then … exit 0` — при отсутствии секретов шаг явно завершает `0` | | AC8 (`mutation-gate.yml` под сверкой main/dev наравне с `process.yml`) | контрактный тест + чтение `validate.yml:65-77` | «чтением»: цикл `for file in process.yml mutation-gate.yml` печатает `РАСХОЖДЕНИЕ …` и ставит `status=1` для любого из двух файлов, `exit $status` в конце — тест матчит буквальный `for`-заголовок | Все восемь AC выполнены. Мутанты «Мутанты» (issue) — три штуки, все три подтверждены прогоном, «поймано 1 из 1» на каждом. ## Проверено дополнительно (сверх минимума) - **Плюмбинг артефактов пройден логически до конца.** `actions/upload-artifact` для одиночного файла кладёт его в корень артефакта; `actions/download-artifact` с `pattern: mutation-shard-*` и без `merge-multiple` разводит каждый по подпапке `/…` — итоговый путь `artifacts/mutation-logs/ mutation-shard-/mutation-shard-.log` совпадает с тем, что читает `mutation-gate-report.mjs` (`${dir}/mutation-shard-${shard}/mutation-shard-${shard}.log`) дословно. Отсутствующий артефакт (шард упал до шага лога) не роняет `download-artifact` (`if-no-artifact-found` по умолчанию `warn`) и корректно даёт `existsSync === false` → `status: 'missing'`. - **`jq`-фильтр в шаге «Issue — создать или дописать» воспроизведён локально:** ``` echo '[{"number":1,"title":"[mutation-gate] отказ прогона по расписанию: 2026-09-06"},{"number":2,"title":"other"}]' \ | MARKER='[mutation-gate] отказ прогона по расписанию' \ jq '[.[] | select(.title | startswith(env.MARKER))][0].number // empty' → 1 ``` `env.MARKER` внутри `--jq`-выражения работает так, как рассчитывал автор. - **`workflow_sync` для двух файлов** проверен и на `git show` для текущих `origin/main`/`origin/dev`: `process.yml` и (до этой задачи) `mutation-gate.yml` сейчас идентичны в обеих ветках — гейт AC8 не будет ложно красным сразу после мержа. ## Находки ### M1 — Medium, в скоупе. SHA в отчёте — не тот, что был протестирован Контракт (issue, §3) и AC4 требуют в теле отчёта SHA `dev` — того дерева, которое реально гоняли мутанты. Job `report` берёт его так: ```yaml # mutation-gate.yml, job report env: SHA: ${{ github.sha }} run: | node scripts/mutation-gate-report.mjs … --ref=dev --sha="$SHA" … ``` `github.sha` для событий **`schedule`** — это не SHA ветки, которую явно чекаутит job (`ref: dev`, как в `mutants`), а **последний коммит ветки по умолчанию репозитория** (GitHub Actions context docs) — то есть здесь `main`, который подтверждён отдельно: `gh repo view --json defaultBranchRef` → `main`. Это ровно тот же класс путаницы, который сам issue разбирает в разделе «Уточнение» («расписание значится на `main`, но код берётся из `dev`») — только для `checkout` автор это учёл, а для `github.sha` в job `report` — нет. **Воспроизведение.** Мутанты (`mutants` job) чекаутят `dev` явно (`mutation-gate.yml:52`, `ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || 'dev' }}`), а `report` подставляет в отчёт значение контекстной переменной `github.sha`, вычисляемое GitHub независимо от шагов чекаута job'а и для `schedule` равное вершине `main`. В любую неделю, где `dev` ушёл вперёд `main` (обычное состояние между релизами — «Promotion rule» в `AGENTS.md`: `main` двигается только промоушен-коммитами), тело отчёта напечатает `` `dev` @ `` `` — SHA существующего коммита, но не того дерева, что тестировали. Юнит-тест AC4 не ловит это: в него подставляется руками заданный `sha: 'abcdef1234567890'`, минуя реальный источник значения. **Практическое следствие.** Не ломает ни один из уже упомянутых AC (issue всё ещё заводится/комментируется, мутанты названы верно, дедуп работает); теряется только точная привязка «что именно тестировали» — при попытке `git checkout ` для расследования человек попадёт на коммит `main`, который в норме на несколько релизов отстаёт от `dev` и может не содержать даже тех файлов, что упомянуты в отчёте. Ссылка на прогон (`RUN_URL`, `github.run_id`) остаётся рабочим обходным путём — открыв run, можно увидеть реальный SHA в логе шага checkout `mutants`, — поэтому это не тупик, а неверная, но не единственная нить. **Правка (в скоупе, дёшево):** в job `report` определить `SHA` из чекаутнутого дерева, а не из контекста события — тем же приёмом, что уже применяется в `process.yml`/`publish-prerelease.yml`/`release.yml` этого же репозитория (`SHA=$(git rev-parse HEAD)` **после** `actions/checkout@v7` с `ref: dev`), а не `${{ github.sha }}`. ### L1 — Low, не блокирует. Поиск открытого issue по заголовку не проверен вживую AC6 полагается на `gh issue list --search "\"$MARKER\" in:title"` с последующей фильтрацией `startswith` — сам `jq`-фильтр я воспроизвёл (см. выше) и он корректен, но полнотекстовый поиск GitHub по заголовку с кириллицей и квадратными скобками — часть, которую нельзя проверить без живого обращения к API. Если полнотекстовый индекс не найдёт точную фразу (маловероятно, но не исключено для не-ASCII), повторный отказ заведёт второе issue вместо комментария — то есть тот же класс дефекта, который решает вся задача, просто из-за внешней системы, а не кода. Контрактный тест проверяет только порядок вызовов `gh`, не результат поиска. На усмотрение автора — можно оставить и понаблюдать на первом реальном отказе по расписанию, риск невысокий, а альтернатив без сети нет ни у одной из сторон. ## Что проверено и корректно - Все восемь AC + AC4b — см. таблицу выше. - Три мутанта задачи — прогнаны индивидуально, не только `--check`, каждый «поймано 1 из 1». - Артефактный плюмбинг `upload-artifact`/`download-artifact` — прослежен путь файла от шага лога шарда до чтения в `mutation-gate-report.mjs` включительно. - `jq`-выражение шага поиска issue — воспроизведено локально на фикстуре. - `workflow_sync` в `validate.yml` — синтаксис и логика (два файла, оба проверяются, оба влияют на итоговый код выхода). - Дешёвые гейты (typecheck/test/build/сверка трёх копий бандла/provenance) — зелёные на `dec6c03e`. - Трейлеры коммита корректны; `User-Visible: no` обоснован (нет изменений `src/**`); changelog не тронут — верно. - Откат («Одним коммитом») — задача действительно один коммит, откат тривиален. ## Чего не проверял - Живое поведение `gh issue list --search` против реального GitHub API с кириллическим маркером (см. L1) — нет доступа к сети/API из среды ревью; ближайшая проверка — первый реальный отказ по расписанию. - Зеркалирование `mutation-gate.yml` в `main` после мержа — это ручной шаг вне этого коммита (как и у `process.yml` сейчас), автор сам отметил его в хендоффе («После мержа: зеркало … обязательно»); гейт AC8 проверяет факт расхождения, а не проводит его — оставляю на исполнителя/владельца постмержевого шага, это не код-ревью выявление. - `golden`, `pytest tests_backend`, performance-профили, браузерные смоки — не запускал: diff не трогает `src/**`/Python/визуал/perf-путь, ни один не назван в AC (см. таблицу гейтов). - Полный список из 255 мутантов (`node scripts/mutation-gate.mjs` без `--id`) не гонял — это предрелизный/еженедельный гейт (PROCESS.md §8), не гейт ревью; задача добавляет три мутанта, оба прогнаны точечно. ## Вердикт Жёлтый: одна находка Medium в скоупе (M1 — неверный SHA в отчёте для schedule-триггера), правится в этой же задаче без нового issue. Все AC по существу выполнены, реализация работает; дефект — в одном поле метаданных отчёта, не в основной функции (issue заводится/дополняется, мутанты названы верно). Low (L1) — на усмотрение автора, не блокирует. --- ## Материал раунда - Ветка: `issue/472-mutation-gate-report`, коммит `a8ea3b8a2dcf` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. - Дерево материала: `8fb963c4bfed17b31222ba6ce224af960009cdd0` ``` git log --all --format='%H %T' | grep 8fb963c4bfed ```