docs: review document for #472

Issue: #472
User-Visible: no

docs/reviews/CODE-REVIEW-472-r1.md

@@ -0,0 +1,228 @@
+# 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` разводит каждый по
+  подпапке `<artifact-name>/…` — итоговый путь `artifacts/mutation-logs/
+  mutation-shard-<N>/mutation-shard-<N>.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 main>` `` — SHA существующего коммита, но не того дерева, что
+тестировали. Юнит-тест AC4 не ловит это: в него подставляется руками заданный
+`sha: 'abcdef1234567890'`, минуя реальный источник значения.
+
+**Практическое следствие.** Не ломает ни один из уже упомянутых AC (issue всё
+ещё заводится/комментируется, мутанты названы верно, дедуп работает); теряется
+только точная привязка «что именно тестировали» — при попытке
+`git checkout <SHA>` для расследования человек попадёт на коммит `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) — на усмотрение автора, не блокирует.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/472-mutation-gate-report`, коммит `a8ea3b8a2dcf` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `8fb963c4bfed17b31222ba6ce224af960009cdd0`
+  ```
+  git log --all --format='%H %T' | grep 8fb963c4bfed
+  ```