docs: review document for #475

Issue: #475
User-Visible: no

docs/reviews/CODE-REVIEW-475-r2.md

@@ -0,0 +1,201 @@
+# CODE-REVIEW-475-r2
+
+Issue: #475 · «mutation-gate --check не отличает живого свидетеля от мёртвого»
+Трек: `small` (лёгкий) · Этап: код-ревью · Заход: r2 · блокирующих циклов 0/2
+
+**Разбор — полный, не по дельте.** Ветка приведена конвейером к `dev` до
+ревью: поверх позиции r1 (`3ed8c920`) легло 5 коммитов `dev`, итог —
+`0540901c`. После ребейза это другой код (§7.2): полный разбор обязателен, а
+не сокращение по дельте §2.10, хотя раунд формально второй. Проверено: сами
+5 коммитов `dev` (`isometric overlay plates`, ревью #471/#472, обновление
+скриншотов) не пересекаются ни по одному файлу с диапазоном задачи
+(`git diff origin/dev...HEAD` — 5 файлов, все из диапазона `origin/dev..HEAD`
+для этой ветки, см. «Скоуп») — риск скрытого конфликта, ради которого
+предписан полный разбор, не материализовался, но раздел «Унаследовано»
+всё равно фиксирует это явно, а не тихо.
+
+## Скоуп
+
+`git diff origin/dev...HEAD` — 5 файлов, класс B (issue переиспользован,
+класса A нет ни одного файла):
+
+- `.github/workflows/validate.yml` — выход `mutants` у job `changes`, третий
+  дизъюнкт в триггере `changed_mutants`, сама job (уже существовала с r1,
+  фикс только про триггер);
+- `scripts/mutation-gate.mjs` — `guardFiles()`, расширенный
+  `selectChangedMutants()`, 2 мутанта (без изменений с r1);
+- `test/mutation-gate.test.mjs` — AC1–AC3, AC5–AC7; AC7 переписан (фикс r1);
+- `test/validate-workflow.test.mjs` — контракт на YAML (AC4), дополнен
+  проверкой третьего дизъюнкта и классификатора `mutants` (фикс r1);
+- `docs/reviews/CODE-REVIEW-475-r1.md` — артефакт предыдущего раунда,
+  контенту не рецензируется повторно.
+
+## Как проверялось
+
+Зелёного Validate на `0540901c` нет — прогон не найден, гейты прогнаны
+самостоятельно. Объём соразмерен классу B без правок в `src/**` (issue #127,
+PROCESS.md §8):
+
+| Гейт | Команда | Результат |
+|---|---|---|
+| Typecheck | `npx tsc --noEmit` | зелёный |
+| Юниты | `npm test` | **2083 pass / 0 fail / 1 skip** |
+| Юниты по затронутым файлам отдельно | `node --test test/mutation-gate.test.mjs` · `node --test test/validate-workflow.test.mjs` | 17/17 и 11/11 pass, все `#475 AC*`-тесты и новый `AC4`-тест зелёные |
+| Сборка + синхрон бандла | `npm run build` → `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | зелёный, байт-в-байт; `git status` после сборки чист — правка не задевает `src/**`, бандл не изменился |
+| Новый код не добавляет `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | «добавленных строк в `src/**/*.ts`: 0» — diff не касается `src/**` |
+| Отбор браузерных смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | «Browser-smoke этим диффом не выбираются… src/**/*.ts не тронут» |
+| Реестр мутантов применим | `node scripts/mutation-gate.mjs --check` | **509/509 `ok`**, включая оба новых мутанта, дублей якоря нет |
+| Мутант `changed-selection-ignores-guard-files` | `node scripts/mutation-gate.mjs --id=changed-selection-ignores-guard-files` | чистый прогон ok → патч красит тест: «поймано 1 из 1» |
+| Мутант `changed-selection-matches-any-token` | `node scripts/mutation-gate.mjs --id=changed-selection-matches-any-token` | то же, «поймано 1 из 1» |
+| Самоприменение отбора к своему же диффу | `node scripts/mutation-gate.mjs --changed=origin/dev..HEAD` | «файлов в диффе 5, мутантов затронуто 4 из 509»: оба новых #475-мутанта плюс два не связанных с задачей (`workflow-scan-hardcodes-the-list`, `typing-gate-stops-running` — патчат тот же `validate.yml`); механизм отбирает сам себя корректно |
+| AC7 напрямую по реальному реестру | `node -e "...MUTANTS.filter(patch.file==='.../frontend_registration.py')..."` | ровно 4 id, включая `frontend-reload-notice-forgets-persisted-flag` — тот самый пропущенный в Low r1 |
+| Процессный гейт | `node scripts/process-gate.mjs --range fc5973c2..HEAD` | «гейт пройден, предупреждений 0»; ветка `issue/475-changed-mutants-on-push`, трейлеры `Issue:`/`User-Visible: no` на всех 3 коммитах диапазона |
+
+**Не прогонялось и почему:**
+
+- `python -m pytest tests_backend -q` — окружения ревью `.venv-backend`/`pytest`
+  не содержит (`pip show pytest` → not found), задокументированное ограничение
+  (AGENTS.md «Environments», PROCESS.md «Backend»), не следствие задачи.
+  Диф не трогает ни один `.py`-файл продукта; самоприменение отбора наткнулось
+  на ту же нехватку pytest на **чужом** мутанте (`typing-gate-stops-running`,
+  не из #475) — это подтверждает ограничение среды, а не пробел задачи.
+  Оба мутанта #475 проверены индивидуально через `--id=`, их гварды — `node --test`,
+  pytest не требуют.
+- `check-docs.mjs`, `golden:verify`, `model-invariants`, performance-профили,
+  `single-source-numbers` — diff не трогает `src/**`, визуал, геометрию или
+  пользовательские числа; неприменимо, не пропуск.
+
+## Находки
+
+Блокирующих находок нет.
+
+**Low, снят без правки (новый, не из r1):** `AGENTS.md:398-400` перечисляет
+«Gate jobs, matching the actual `validate.yml`» поимённо (`docs`, `provenance`,
+`process-gate`, `hacs`, `hassfest`, `frontend`, `smoke`, `golden`,
+`performance_smoke`, `backend`) и не включает новую `changed_mutants`, хотя
+она блокирующая (без `continue-on-error`, проверено `test/validate-workflow.test.mjs`).
+Проверено чтением `scripts/release-gate.mjs:9` (`classifyValidateRuns`) —
+критерий готовности релиза читает **общий вывод workflow-прогона** Validate
+через GitHub Actions API, а не имена отдельных job; красная `changed_mutants`
+красит весь прогон и блокирует релиз тем же путём, что и остальные job из
+списка. AC4 («job… входит в итоговый check») выполнен по факту — список в
+AGENTS.md чисто описательный для человека и не читается никаким скриптом
+(проверено: `grep -rn "Gate jobs, matching"` вне `AGENTS.md` пусто, синхронности
+с кодом никто не проверяет). Обновление списка не входило в DoD ТЗ (документация
+класса C не предмет этой задачи), и его отсутствие не создаёт функционального
+дефекта — только неполноту одного предложения в другом документе. Снимаю без
+правки.
+
+## Проверка AC — таблица «чем доказан / чем краснеет»
+
+| AC | Доказано | Чем | Чем краснеет |
+|---|---|---|---|
+| AC1 | unit | `test/mutation-gate.test.mjs` `#475 AC1` | не защитный AC (сравнение множества) |
+| AC2 | unit + мутант | `#475 AC2` | `changed-selection-ignores-guard-files`: «поймано 1 из 1» (прогнано лично) |
+| AC3 | unit + мутант | `#475 AC3` | `changed-selection-matches-any-token`: «поймано 1 из 1» (прогнано лично) |
+| AC4 | unit (YAML-контракт) + чтение | `test/validate-workflow.test.mjs` (новый тест `#475 AC4`) + чтение `validate.yml:411-465` | не защитный AC (расположение/текст job) — обычное сравнение ожидаемого текста с фактическим; тест прогнан лично, зелёный |
+| AC5 | unit + чтение | `#475 AC5` + `guardNeedsBundle` вызывается только для отобранных (чтение, не исполнение полного CI) | не защитный AC — расположение раннего выхода |
+| AC6 | unit | `#475 AC6`, реальный реестр | не защитный AC — сравнение множества id |
+| AC7 | unit (полный, фикс r1) + независимая проверка | `#475 AC7` (теперь фильтр по `patch.file`, не по префиксу id) + прямой запрос к `MUTANTS` (см. таблицу гейтов) | не защитный AC — сравнение множества id, но полнота множества (4, не 3) проверена мной по факту, а не на слово |
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где видно |
+|---|---|---|
+| **Medium** — триггер `changed_mutants` не покрывал изменение `scripts/mutation-gate.mjs` (третий дизъюнкт контракта §2 отсутствовал и в `if:`, и в контрактном тесте) | Классификатор получил выход `mutants` по точному пути `^scripts/mutation-gate\.mjs$`; триггер job — `frontend \|\| backend \|\| mutants`; все 3 fallback-ветки полного прогона выставляют `mutants=true` | `validate.yml:185,241,265,275,287,414` (прочитано построчно) + `test/validate-workflow.test.mjs` тест `#475 AC4` (прогнан лично, зелёный, проверяет все три места) |
+| **Low** — тест AC7 фильтровал бэкенд-мутанты по префиксу id (`frontend-registration-*`) и пропускал 4-й (`frontend-reload-notice-forgets-persisted-flag`), хотя код отбирал все 4 | Тест переписан на фильтр по `patch.file === 'custom_components/houseplan/frontend_registration.py'`, что автоматически включает все 4 | `test/mutation-gate.test.mjs` тест `#475 AC7` (прогнан лично) + независимый запрос к `MUTANTS` в этом раунде подтвердил ровно 4 id, включая четвёртый |
+
+Обе находки закрыты кодом, а не заявлением автора — обе перепроверены
+самостоятельным прогоном/чтением в этом раунде.
+
+## Унаследовано из r1
+
+Формально не применимо в смысле «сокращения объёма» — разбор в этом раунде
+полный (см. причину в шапке документа), каждый AC1–AC7 и обе находки r1
+перепроверены заново на `0540901c`, а не приняты на слово. Из документа
+`docs/reviews/CODE-REVIEW-475-r1.md` (SHA материала `c0207af4`) взяты без
+повторного вывода только два факта, не подлежащие пересмотру кодом: перечень
+файлов диапазона (сверен заново и совпал) и формулировки самих находок
+(процитированы дословно в разделе «Закрытие раунда r1» — их текст не
+переизобретается, а их **закрытие** доказано отдельно). Спор о продуктовом
+контракте (что должен покрывать триггер) на этапе ТЗ решён в
+`SPEC-REVIEW-475-r1`/`r2` (жёлтый → зелёный) — это другой этап (§2.4, а не
+§2.7) и не переоткрывается здесь; код-ревью проверяло только соответствие
+уже принятому контракту, а не сам контракт.
+
+## Что проверено и корректно
+
+- `guardFiles()` — только токены `[\w./-]+\.(mjs|py)`, не начинающиеся с `-`,
+  существующие в репозитории; проверено на `--test-name-pattern="magnet
+  presses|x.mjs"` (юнит `#475 AC3`, прогнан лично) — фрагмент шаблона
+  `presses|x.mjs"` корректно не считается файлом гарда (несуществующий
+  символ `|` вне допустимого набора).
+- `selectChangedMutants(mutants, changedFiles, exists)` обратно совместима:
+  вызов без третьего параметра (как в CLI, `mutation-gate.mjs:6891`)
+  использует дефолтный `existsSync` внутри `guardFiles`; старый тест `#332`
+  (шардирование) по-прежнему проходит без правок сигнатуры.
+- Мутанты #475 верно устроены: якорь `changed-selection-ignores-guard-files`
+  собран из двух конкатенированных строк ровно затем, чтобы `--check` не
+  находил его дважды (в коде и в определении) — подтверждено: `--check` даёт
+  `ok`, дублей нет, реестр 507 → 509.
+- База диапазона в `changed_mutants` (`PROVEN_BASE`/`BEFORE_SHA`/
+  `merge-base`-фолбэк) побайтово идентична уже работающему блоку в job
+  `frontend` (гейт «новый код не добавляет any», #387/#388) — не новая
+  логика, а переиспользованная; сверено построчно чтением обоих мест.
+- Установка Python и Chromium в `changed_mutants` дословно повторяет шаги
+  `mutation-gate.yml` (checkout → setup-node → npm ci → setup-python 3.14 →
+  `pip install -r tests_backend/requirements.txt` → кэш Playwright →
+  установка при промахе) — сверено построчно.
+- Триггер `mutants` — точный путь (`^scripts/mutation-gate\.mjs$`), не
+  расширяет отбор ложно на соседние файлы; регресса для уже принятых
+  `frontend`/`backend`-веток нет — они лишь дополнены третьим условием
+  через `||`, не заменены.
+- Трейлеры всех 3 коммитов диапазона (`Issue: #475`, `User-Visible: no`) —
+  корректны для инфраструктурной правки без пользовательского эффекта;
+  changelog не тронут, что верно при `User-Visible: no`; `process-gate.mjs`
+  подтверждает нулём предупреждений.
+- Ни один другой файл репозитория не вызывает `selectChangedMutants`/
+  `guardFiles` — изменение сигнатуры не создаёт риска регрессии на стороне
+  вызывающего кода (проверено `grep` по `*.mjs`/`*.ts`).
+
+## Чего не проверял
+
+- Полный `pytest tests_backend` (среда без `.venv-backend`) — см. «Как
+  проверялось». Ограничение среды, не задачи.
+- Поведение `changed_mutants` job живьём в GitHub Actions (реальный запуск
+  runner, кэш Playwright, реальный `github.event.before` на push-событии) —
+  логика веток `EVENT_NAME`/`REF`/`PROVEN_BASE` проверена чтением и сверкой
+  с идентичным уже работающим кодом job `frontend`, не отдельным прогоном
+  workflow (это доступно только через реальный CI прогон на push, вне
+  ревью).
+- Полноту списка «Gate jobs» в `AGENTS.md` как автоматизированного контракта
+  — там нет читающего его скрипта; см. Low.
+
+## Вердикт
+
+Зелёный. Обе находки r1 (Medium и Low) закрыты и проверены самостоятельно, а
+не на слово автора. Новых High/Medium находок нет. Единственная новая
+находка — Low вне блокирующего порога, снята без правки с объяснением, почему
+функционального дефекта нет. Полный разбор всех AC подтверждает, что задача
+решает заявленный сценарий: разрыв «неделя–релиз» для отбора мутантов по
+диффу закрыт, включая триггер по правке самого реестра и по бэкенд-мутантам.
+
+---
+
+## Материал раунда
+
+- Ветка: `issue/475-changed-mutants-on-push`, вершина `0540901cda486724a65ebcd9c4cb4f6d36bde906`.
+- Диапазон разбора: `origin/dev..HEAD` (`fc5973c2..0540901c`), 3 коммита задачи.
+- Предыдущий заход: `docs/reviews/CODE-REVIEW-475-r1.md`, SHA материала `c0207af4` (осиротевший после ребейза — ожидаемо, §2.10).
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/475-changed-mutants-on-push`, коммит `3ed8c9204473` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `12506be1e214ea1080a510d34089b505127c22bb`
+  ```
+  git log --all --format='%H %T' | grep 12506be1e214
+  ```