houseplan-card/docs/reviews/CODE-REVIEW-473-r1.md

# CODE-REVIEW-473-r1

- **Issue:** #473 — «Перф-регрессия Stage 3 в 6,5–17 раз прошла два раунда ревью:
  раунд постфактум на perf-дельту #160 и перф-смок в код-ревью задач отрисовки»
- **Ветка:** `issue/473-iso-perf-witnesses`, **SHA материала:** `d95255ad`
  (`git rev-parse HEAD` сверен непосредственно перед выводом вердикта)
- **Этап:** code · **Заход:** r1 (первый заход код-ревью; ревью ТЗ на этом же
  issue уже прошло два захода r1(жёлтый)/r2(зелёный) — это отдельный бюджет
  циклов, §10.4)
- **Класс изменений:** только B (`test/**`, `scripts/**`,
  `.github/workflows/**`) и C (`docs/**`, `PROCESS.md`) — **ни одного файла
  класса A**, `src/**` не тронут вовсе

## Скоуп

Диапазон `origin/dev...HEAD`, 16 файлов, +1259/−16. Две части по ТЗ
(`docs/specs/473-iso-perf-witnesses-and-smoke.md`):

1. Четыре мутанта-свидетеля в `scripts/mutation-gate.mjs` на механизмы
   перф-дельты #160 (LRU-кэш размещений, кэш по идентичности массива силуэтов,
   гард повторного использования при зуме внутрь, AABB-отсечение) плюс гарды в
   `test/iso-scene-render.test.mjs` (AC1, AC2).
2. Диффозависимый `performance_smoke` в `.github/workflows/validate.yml`:
   новые выходы `perf_iso`/`perf_interaction` job `changes`, вынесенные из
   inline-shell в `scripts/classify-changes.mjs`, условные шаги смока с
   бюджетами `demo/performance/budgets-isometric-smoke.json` /
   `budgets-interaction-smoke.json`, набор профилей в ключе `reuse` (AC3–AC5,
   AC8), плюс ручное воспроизведение AC6/AC7 и правка `PROCESS.md` §8.

Продуктовый код (`src/**`) не меняется нигде — подтверждено:
`git diff origin/dev...HEAD -- src/` пуст.

## Как проверялось

| Гейт | Команда | Результат |
|---|---|---|
| typecheck | `npx tsc --noEmit` | чисто, без вывода |
| unit | `npm test` | `tests 2092 / pass 2091 / fail 0 / skipped 1` |
| build | `npm run build` | собран, без ошибок |
| копии бандла | `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | идентичны |
| no-new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | «0 в 0 файлах» (диф не трогает `src/**`) |
| выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | «браузерных смоков не выбирается» — диф не трогает `src/**/*.ts`, выбирать нечего |
| workflow YAML | `python3 -c "yaml.safe_load(...)"` | валиден |
| свидетель W1 | `node scripts/mutation-gate.mjs --id=iso-placement-cache-ignores-selected` | чистый прогон ok, мутант «покраснел, поймано 1 из 1» |
| свидетель W2 | `--id=iso-placement-cache-survives-silhouette-change` | поймано 1 из 1 |
| свидетель W3 | `--id=iso-zoom-in-reuses-near-wall-plate` | поймано 1 из 1 |
| свидетель W4 | `--id=iso-aabb-rejects-touching-wall` | поймано 1 из 1 |
| AC3 негативный прогон | вручную снят `if: needs.changes.outputs.perf_iso == 'true'` у шага «Изометрический профиль по диффу», прогнан `node --test --test-name-pattern="перф-смок добавляет профиль ровно при своём выходе changes" test/validate-workflow.test.mjs` | падает (`AssertionError`, ожидаемый `if:` не найден); файл восстановлен, `git status` чист |
| AC5 негативный прогон | вручную убран суффикс `-${{ needs.reuse.outputs.performance_smoke_set }}` из save-ключа `reuse`, прогнан тест «ключ reuse перф-смока различает наборы профилей» | падает; файл восстановлен |
| AC8 негативный прогон | в `scripts/classify-changes.mjs` регэксп `perf_iso` испорчен (`iso-nonexistent-`), прогнан `test/classify-changes.test.mjs` | 2 из 7 тестов падают; файл восстановлен |
| AC4 | `node --test test/performance-budget.test.mjs` | оба новых smoke-бюджета проходят сравнение `hardMaxMs`/`stat`/`longTasks`/`heap`/`cacheEntries` с полными профилями, синтетический отчёт 9870 мс красит `timing.firstStableRenderMs.median` |
| весь релевантный набор одним прогоном | `node --test test/classify-changes.test.mjs test/performance-budget.test.mjs test/validate-workflow.test.mjs test/performance-workflow.test.mjs test/iso-scene-render.test.mjs` | `tests 61 / pass 61 / fail 0` |

**Не прогонял и почему:**

- `npm run golden:verify` — диф не меняет визуал (`src/**` не тронут, эталоны
  не тронуты); автор отдельно предупредил, что `dev` уже красный на golden
  из-за непересъёмки #471 (`be5eeb41`) — это не имеет отношения к дельте
  #473, отдельная проблема вне скоупа этого ревью;
- `python -m pytest tests_backend -q` — диф не трогает `custom_components/**/*.py`;
- `node scripts/check-docs.mjs` — правило требует его при диффе по `src/**`;
  здесь `src/**` не тронут, отпечаток скриншотов не может устареть от этого
  диффа;
- `node scripts/model-invariants.mjs` — диф не трогает геометрию, ссылки на
  неё, `layout`, `marker.space`, `open_spans`;
- полный перф-прогон (`benchmark:large-house` локально) — задача сама
  описывает его как «AC6/AC7 доказаны один раз при реализации», числа уже
  записаны автором в хендоффе и внутренне согласуются с бюджетами (см. ниже);
  повторный прогон стоил бы часы ради проверки арифметики, которую я сверил
  чтением;
- полный `scripts/mutation-gate.mjs` без `--id` (все ~40+ мутантов) — задача
  добавляет только 4 новых, гонять весь набор ради ревью четырёх — не
  соразмерно (§8); проверены именно новые.

Зелёного Validate на SHA `d95255ad` нет (описано в задании), поэтому дешёвые
гейты прогнаны мной лично, см. таблицу выше — все зелёные.

## AC — доказательство и «чем краснеет»

| AC | Заявлено | Чем доказан | Чем краснеет |
|---|---|---|---|
| AC1 | 4 свидетеля в реестре, каждый ловится | `mutation-gate.mjs --id=<witness>`, 4/4 «поймано 1 из 1» (прогнано мной) | сами мутации из таблицы §4 ТЗ; проверено воспроизведением |
| AC2 | envelope без коллизий = точный резолвер до nudge | код-чтение: `resolveIsoOverlayPlacement` (`src/iso-overlays.ts:449-457`) строит `baseFootprint` и решает `nearWallBefore` **до** нужного участка nudge-логики одинаково независимо от того, есть ли стены; при `resolveCollisions:false` `wallSilhouettes` подаётся пустым (`iso-scene-render.ts:849`), значит `nearWallBefore` всегда `false` и nudge не применяется — итоговые границы буквально равны `baseFootprint`, что и есть «точный резолвер до nudge». Существующий тест (строки 391–395, **добавлен исходной перф-дельтой #160, не этой задачей**) подтверждает поведенчески: `nearWallBefore=false`, отдельная запись кэша. **Проверено чтением, не исполнением** — по формулировке спеки «нет однозначной мутации», согласовано ещё на ревью ТЗ (r2) | нет однозначной мутации (заявлено в ТЗ и подтверждено чтением: обе ветки используют один и тот же `baseFootprint`) |
| AC3 | `changes` отдаёт `perf_iso`/`perf_interaction`; смок добавляет профиль ровно при своём выходе | `test/validate-workflow.test.mjs` (контрактный тест на YAML) + мой негативный прогон | снятие `if:` у шага — тест падает (проверено вручную) |
| AC4 | smoke-бюджеты валидны для `--absolute-only`, повторяют `hardMaxMs` полных | `test/performance-budget.test.mjs`, сверка JSON построчно (я перечитал оба файла — потолки идентичны) | несовпадение `hardMaxMs`/`stat`/списка метрик — тест `assert.equal`/`assert.deepEqual` красится напрямую |
| AC5 | ключ `reuse` различает наборы профилей | `test/validate-workflow.test.mjs` + мой негативный прогон (снятие `-performance_smoke_set` из save-ключа) | тест падает (проверено вручную) |
| AC6 | на `de215578` изометрический smoke-бюджет краснеет по первому кадру | ручное воспроизведение автором: артефакт CI-прогона 34013995127 (`isometric-candidate.json`, 7 образцов) прогнан через `benchmark:compare --absolute-only --budgets=...isometric-smoke.json` → 11 отказов, включая `firstStableRenderMs` 9870/3500. Числа (9870, 30545, 12000 для `maxTotalP95Ms`) я сверил построчно с committed `budgets-isometric-smoke.json` — совпадают | команда и результат названы в issue (хендофф), не «verified» без содержания |
| AC7 | текущий `dev`/ветка укладывается в потолки за 3 образца | ручной прогон автора: isometric 29 с (`firstStableRenderMs` 1241/3500, `switchCycle` 1401/8000, `modelReady` 1158/3000), interaction 36 с (`firstStableRenderMs` 2501/3000, `interactionSeries` 2350/3000, `hoverSeries` 200/500) — все числа ниже потолков в committed JSON, сверено | доказательство «в CI этой ветки» технически недостижимо (дифф без продуктовых путей) — верно и подтверждено повторно; ручной способ адекватен |
| AC8 | диффозависимость доказана на функции классификации | `test/classify-changes.test.mjs`, 7 тестов, плюс мой негативный прогон (испорченный regex `perf_iso`) | 2/7 тестов падают при испорченном паттерне (проверено вручную) |

## Что проверено и корректно

- Все 4 патча мутантов (`find`/`replace`) в `scripts/mutation-gate.mjs`
  побайтово совпадают с текущим `src/iso-scene-render.ts` /
  `src/iso-overlays.ts` — не устарели после ребейза на #471
  (`plate`→`footprint`), что подтверждается их успешным прогоном.
- `demo/performance/budgets-isometric-smoke.json` и
  `budgets-interaction-smoke.json` — `hardMaxMs`, `stat`, набор метрик,
  `longTasks`, `heap.hardMaxGrowthBytes`, `cacheEntries`, `renderedDevices`
  идентичны соответствующим `budgets-large-house-*.json` (сверено вручную и
  тестом); регрессионные коэффициенты сознательно отсутствуют, как в ТЗ.
- Изменение `.github/workflows/validate.yml`: `classify` пишет через
  `scripts/classify-changes.mjs` вместо inline-`has()`, все три fallback-ветки
  (`dev`, force-push, пустая база) переведены на `--all`; ключ `reuse`
  расширен `performance_smoke_set`, использован согласованно и в
  lookup-, и в save-шаге; `needs: changes` у `reuse` и `performance_smoke`
  корректны; YAML валиден.
- Регекспы `perf_iso`/`perf_interaction` в `scripts/classify-changes.mjs`
  покрывают все существующие файлы `src/iso-*.ts`, `src/live-*.ts`,
  `src/render-*.ts`, `houseplan-render-lifecycle.ts`, `houseplan-card.ts`
  (проверено по дереву — все плоские, без подкаталогов).
- Трейлеры на всех 9 коммитах диапазона — `Issue: #473`,
  `User-Visible: no` — корректны для infra/process-задачи без
  пользовательского поведения; ветка называется `issue/473-iso-perf-witnesses`.
- Документация — `PROCESS.md` §8 и `demo/performance/README.md` описывают
  ровно то, что реализовано; `docs/specs/README.md` получил строку. Всё в тех
  же коммитах, что и код (правило §11 PROCESS.md).
- Никаких файлов класса D (`dist/**`, `custom_components/houseplan/frontend/**`)
  в диапазоне коммитов нет — сборка/копия проверены мной локально, не
  закоммичены.
- Автор честно зафиксировал независимую проблему (красный golden на `dev` от
  #471) вместо того, чтобы скрыть или чинить её здесь — соответствует «скоуп
  не расширяется».

## Находки

Нет ни одной находки уровня High или Medium. Диапазон не меняет продуктовый
код, все заявленные механизмы свидетельствования воспроизведены мной лично с
отрицательными прогонами (AC1, AC3, AC5, AC8), AC2/AC6/AC7 разобраны по коду
и по числам и признаны корректными.

Low (не блокирует, снимается записью): хендофф-комментарий группирует AC2 с
AC1 под «свидетели (AC1, AC2)», не проговаривая явно, что AC2 доказывается
чтением, а не мутацией — из-за чего эта явная запись отсутствовала до
настоящего документа. Формально требование §2.7 («либо тест… либо явная
запись „проверено чтением“») выполнено этим документом; отдельного цикла
это не стоит.

## Чего не проверял (и почему — см. таблицу гейтов)

`golden:verify`, `pytest tests_backend`, `check-docs.mjs`,
`model-invariants.mjs`, полный `mutation-gate.mjs` без `--id`, повторный
запуск `benchmark:large-house` локально — все перечислены в таблице «Как
проверялось» с причиной непрогона.

## Вердикт

Зелёный. Очередь на пре-релиз (`S8-merged` после слияния конвейером).

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/473-iso-perf-witnesses`, коммит `d95255ada269` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `e510f97d0d84d89d12cfd1d4448c3368bd6a2475`
  ```
  git log --all --format='%H %T' | grep e510f97d0d84
  ```
- ТЗ `docs/specs/473-iso-perf-witnesses-and-smoke.md`, блоб `5e2068d0dcab862fdf8964a3ec6966f1e73c2431`
  ```
  git log --all --find-object=5e2068d0dcab862fdf8964a3ec6966f1e73c2431 -- docs/specs/473-iso-perf-witnesses-and-smoke.md
  ```