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

# CODE-REVIEW-535-r1

Issue: #535 · Заход r1 · блокирующих циклов израсходовано 0/4
Материал ревью: `063de0eef4bfb96802e8ff94fcc0e35177cfde0b` (`origin/dev...HEAD`, один коммит `063de0ee`, база `1ca3b5fa`)
Ревьюер: Claude (код-ревью) · Автор кода: Codex

## Скоуп

Правка меняет один плагин сборки, `entryFallbackPlugin` в `scripts/bundle-manifest.mjs`:
панель (`houseplan-panel.js`) теперь импортирует реализацию карточки по
content-hashed адресу (`houseplan-assets/houseplan-card-<hash>.js`) напрямую, а не
через стабильный фасад `houseplan-card.js`, — устраняя единственный адрес в
дистрибутиве, по которому карточка отдаётся без токена версии. `try/catch` и
фолбэк («House Plan обновился — перезагрузите страницу», 4 языка) сохраняются;
при недоступном чанке теперь срабатывает панельный фолбэк, а не карточный внутри
живой панели.

Диапазон изменённых файлов: `scripts/bundle-manifest.mjs`, `scripts/bundle-tree.mjs`
(инвариант манифеста переформулирован под новую топологию), `scripts/mutation-gate.mjs`
(новый мутант + переоформление существующего), четыре тестовых файла
(`bundle-assets`, `bundle-freshness`, `bundle-sync`, `houseplan-zip`), `docs/ARCHITECTURE.md`,
оба `CHANGELOG`, три копии бандла (`dist/`, `custom_components/houseplan/frontend/`,
манифест `houseplan-assets.json`) и отпечаток скриншотов документации (только
отпечаток исходников, кадры не менялись).

По механическому признаку §1 диапазон файлов класса A не задет (только B/C/D) —
классификация полным треком по продуктовому доводу автора (видимое поведение
на устаревшем загрузчике) была спорной точкой ревью ТЗ r1 и признана
обоснованной; я согласен с этим выводом (см. «Ответ на продуктовый вопрос» ниже).

`src/**` не тронут вовсе — подтверждено `git diff origin/dev...HEAD --stat -- src/`
(пусто).

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

Дешёвые гейты (`tsc`, `npm test`, `npm run build` + сверка бандла) уже
подтверждены зелёным Validate на этом SHA
(https://github.com/Matysh/houseplan-card/actions/runs/34652944181) — не
перегонялись целиком. Дальше — то, что Validate не покрывает и что нужно
именно этой правке, прогнано лично, командой и результатом:

| Гейт | Команда | Результат |
|---|---|---|
| Юниты по изменённым файлам (перепроверка независимо от Validate) | `node --test test/bundle-assets.test.mjs test/bundle-freshness.test.mjs test/bundle-sync.test.mjs test/houseplan-zip.test.mjs test/mutation-gate.test.mjs` | 91/91 pass |
| Мутант AC1/AC2 | `node scripts/mutation-gate.mjs --id=panel-imports-unversioned-card-entry` | поймано 1 из 1 |
| Мутант AC4 | `node scripts/mutation-gate.mjs --id=panel-entry-bypasses-card-graph` | поймано 1 из 1 |
| Мутант AC3 | `node scripts/mutation-gate.mjs --id=panel-entry-fallback-rewrite-skipped` | поймано 1 из 1 |
| Бюджет панели (К4) | `node scripts/bundle-budget.mjs` | exit 0; `initial panel-only: 2325 B` при потолке 8192 B (запас 5867 Б) |
| Инвентарь манифеста (К4) | ручное чтение `dist/houseplan-assets.json` | `initialPanelFiles` не содержит `houseplan-card.js`; `initialViewFiles` минус фасад ⊆ `initialPanelFiles` |
| Три копии бандла в синхроне | `cmp dist/houseplan-card.js custom_components/.../houseplan-card.js`, `cmp … houseplan-panel.js`, sha256 по `houseplan-assets/*.js` | совпадают |
| Реальный build детерминирован | `node scripts/bundle-sync.mjs` поверх коммита | 0 изменений в рабочем дереве после — сборка воспроизводима |
| Документация (доп. проверка, `src/**` не тронут, но диффит `docs/`) | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 12 external links)» — совпадает с заявленным |
| Скриншоты (отпечаток исходников) | сверка `docs/images/screenshots.json` в диффе | `sourceFingerprint` обновлён на `3eba35b1…`, байты PNG и `imageSha256` не менялись — соответствует заявленному `docs:accept --identical` |
| Смок панели (браузер, счастливый путь) | `node demo/smoke_houseplan_panel.mjs` (после `node scripts/bundle-sync.mjs`, стенд не был синхронизирован) | OK, все проверки true |
| Смок устаревшего входа (браузер, AC3 «чем краснеет» на реальном dist) | `node demo/smoke_entry_stale.mjs` | OK — панельный и карточный фолбэки, все 4 языка, без необработанных ошибок страницы |

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

- `npx tsc --noEmit`, полный `npm test`, `npm run build` со сверкой копий — приняты по зелёному Validate на этом SHA (§ дешёвые гейты).
- `python -m pytest tests_backend` — бэкенд (`custom_components/**/*.py`) не тронут.
- `npm run golden:verify` — диффом не задет ни один пиксель карточки (правка — только адрес импорта и текст комментария/лога), сам автор это заявил, и `docs:accept --identical` (нулевые попиксельные различия по 11 кадрам) независимо это подтверждает.
- perf-профили — в AC не названы, диапазон файлов их не касается.
- `npm run invariants` (геометрия/toolThickness/layout) — диффом не задет: правка не касается ни рёбер комнат, ни `layout`, ни `marker.space`.
- Полный набор `demo/smoke_*.mjs` — `smoke-select.mjs --base origin/dev --head HEAD` отвечает «исполняемого frontend-диффа нет» (`src/**` не менялся), выбор двух смоков выше сделан вручную по факту, что именно они гоняют реальный собранный `dist/houseplan-panel.js` и `dist/houseplan-card.js` через браузер — это ровно то, что диффит правка. Остальные ~табор смоков карточки/редакторов не относятся к маршрутизации входов и не выбраны.

## AC · чем доказан · чем краснеет

| # | AC | Доказательство (перепроверено) | Чем краснеет (прогнано лично) |
|---|---|---|---|
| AC1 | Плагин переписывает импорт панели на content-hashed чанк, `imports` содержит чанк | `#486 both stable entries install a visible stale-load fallback` (юнит на плагине напрямую, без сборки) — прочитан и перепрогнан | мутант `panel-imports-unversioned-card-entry` — лично: «поймано 1 из 1» |
| AC2 | В собранном `dist/houseplan-panel.js` нет ссылки на карточку без версии | `#535 panel entry reaches the card implementation by its hashed name` (читает `dist/`) + лично: `grep -o 'try{await import(...)}' dist/houseplan-panel.js` → `houseplan-assets/houseplan-card-B09T8YNT.js`; `grep -c houseplan-card.js dist/houseplan-panel.js` → 0 | тот же мутант (юнит-гвард на плагине; дист-тест не пересобирается на мутанте — законно для чистого юнита, §2.7) |
| AC3 | Фолбэк цел: элемент определяется, сообщение на месте (4 языка), статических рёбер нет | поведенческая часть теста без изменений + **браузерный** `demo/smoke_entry_stale.mjs` на реальном `dist/houseplan-panel.js` с 404 на все хешированные чанки | мутант `panel-entry-fallback-rewrite-skipped` — лично: «поймано 1 из 1»; смок независимо воспроизводит тот же сценарий против настоящего собранного файла |
| AC4 | Манифест: граф панели содержит граф реализации карточки, не содержит фасад; бюджет соблюдён | `scripts/bundle-tree.mjs` (`assertBundleManifest`, переформулирован) + `scripts/bundle-budget.mjs` — лично прогнан, exit 0, `initial panel-only: 2325 B` (потолок 8192 Б) | мутант `panel-entry-bypasses-card-graph` — лично: «поймано 1 из 1» |
| AC5 | Ни один входной файл не ссылается на карточку по адресу без версии | новый тест `#535 no built entry reaches the card by an address without a version` + лично: `grep -rl "houseplan-card.js" dist/` → только сам фасад и манифест, никаких других файлов | мутант AC1/AC2 задевает тот же код-путь; дополнительно — ручной `grep` по всему `dist/` подтвердил отсутствие иных ссылок |
| AC6 | Оба чейнджлога и `ARCHITECTURE.md` описывают новую маршрутизацию | построчная сверка (см. ниже) + `node scripts/check-docs.mjs` — «passed (7 files, 12 external links)», лично воспроизведено | — (не защитный AC) |

## Находки

### Low — L1: текст `console.error` панели изменён вопреки букве К2 ТЗ

`scripts/bundle-manifest.mjs`, панельная ветвь `entryFallbackPlugin`.

К2 ТЗ дословно: «Текст, четыре языка, класс элемента и `console.error` не
меняются.» Дифф меняет именно `console.error`:

```
- 'console.error("[houseplan] stale houseplan-panel.js: the card entry is unavailable",e)}',
+ 'console.error("[houseplan] stale houseplan-panel.js: the card implementation '
+ 'chunk is unavailable",e)}',
```

Это не покрыто ни одним тестом (ни один `assert` не проверяет содержимое этой
строки) и не названо в разделе «Отклонения от ТЗ — называю сам» хендоффа, хотя
там перечислены четыре других отклонения. По существу изменение оправдано:
после #535 недоступен именно chunk реализации, а не «card entry» — старый текст
стал бы неточным. Строка видна только в консоли разработчика, не пользователю,
и никак не входит в измеряемый функционал AC1–AC6.

**Решение ревьюера:** снимаю без цикла — фактическая точность лога важнее
буквы «дословно» применительно к диагностической строке, которую К2 явно
перечисляет вместе с пользовательским текстом (это, возможно, недосмотр самого
К2, а не сознательный контракт). Отмечаю как принятое отклонение, чтобы
дальнейшие ревью не искали здесь скрытую регрессию.

Других High/Medium/Low не найдено.

## Одно число — один источник

Дифф не добавляет и не меняет ни одной пользователем видимой величины
(строку с толщиной, площадью, размером и т.п.) — только адрес импорта и
служебные тексты (лог, комментарии, changelog). Проверка неприменима к этой
задаче.

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

- **К1** — построчно: `dist/houseplan-panel.js` содержит ровно
  `try{await import("./houseplan-assets/houseplan-card-B09T8YNT.js")}catch(e){…}`,
  ссылок на `./houseplan-card.js` — ноль.
- **К2** — фолбэк (4 языка, класс элемента, стили) не тронут; см. L1 про
  единственное отклонение — сам текст лога, не сам фолбэк.
- **К3** — `dist/houseplan-card.js` не изменился по контракту: тот же
  `try{await import("./houseplan-assets/houseplan-card-B09T8YNT.js")}catch` в
  фасаде, отдельная функция `cardEntry`/`cardPattern` в диффе не тронута.
- **К4** — манифест и рантайм-валидатор согласованы: `initialPanelFiles` не
  содержит фасад, `initialViewFiles` (минус сам фасад) ⊆ `initialPanelFiles`,
  бюджет 2325 Б при потолке 8192 Б.
- **К5** — оба теста `#486` действительно перевёрнуты по смыслу (не
  подогнаны): `assert.doesNotMatch(panel, /houseplan-card\.js/)` появился там,
  где раньше стоял `assert.match` на тот же паттерн; переименование второго
  теста в `#535 …` оправдано сменой контракта, поведенческая часть (customElements,
  фолбэк) не ослаблена.
- **К6** — новый тест на весь дистрибутив плюс ручной `grep -rl
  "houseplan-card.js" dist/` подтверждают: во всём собранном дереве
  единственная ссылка на карточку без версии — она же сам стабильный вход,
  что и требуется контрактом (фасад продолжает существовать для Lovelace).
- **Мутанты** — все три названных автором (`panel-imports-unversioned-card-entry`,
  `panel-entry-bypasses-card-graph`, `panel-entry-fallback-rewrite-skipped`)
  лично перепрогнаны, каждый «поймано 1 из 1»; четвёртый пинned-тест
  (`#486 bundle topology and both stale entries have mutation witnesses`)
  подтверждает, что реестр не потерял старые id.
  Новый мутант `panel-imports-unversioned-card-entry` не входит в pinned-список
  `test/mutation-gate.test.mjs` — это нормально: список пиннует только уже
  существовавшие до #535 id, новый свидетель добавлять туда не требовалось.
- **Отклонения от ТЗ, названные автором** (файл `bundle-tree.mjs`, девять
  задетых фикстур, переоформление мутанта, отсутствие сдвига
  `initialPanelOnlyGzipBytes`) — все проверены по диффу и корректны; ни одно
  не ослабляет проверяемое утверждение (арифметика gzip-сумм в фикстурах
  `bundle-freshness`/`houseplan-zip` сходится: убранный из графа фасад вычтен
  из `initialPanelGzipBytes` ровно на его размер).
- **Документация**: `ARCHITECTURE.md` описывает ровно новую маршрутизацию и
  причину (единственный неверсионированный адрес, отсутствие
  `Cache-Control`, `immutable`-чанки); `CHANGELOG.md`/`CHANGELOG.ru.md`
  синхронны по смыслу, ссылка на #535 в обоих, `User-Visible: yes` в коммите
  соответствует правкам в обоих чейнджлогах в том же коммите. `USER-GUIDE.ru.md`
  не тронут и не должен быть: описывает только фасад карточки (К3, не
  изменился), к панели напрямую не относится.
- **Трейлеры и трассируемость**: один коммит, `Issue: #535`,
  `User-Visible: yes`, ветка `issue/535-panel-card-url` (хендофф) слита без
  дополнительных пушей — ровно то, что заявлено в хендоффе.
- **Сборка воспроизводима**: `node scripts/bundle-sync.mjs` поверх коммита не
  дал ни одного изменения в рабочем дереве — три копии бандла (`dist/`,
  `custom_components/.../frontend/`, стенд `demo/srv/assets/`) детерминированы
  и синхронны.

## Ответ на продуктовый вопрос автора

Автор спрашивает, согласен ли я, что громкое сообщение лучше тихой работы на
старом коде, и не стоит ли отдельной задачей различать «фронтенд новее» и
«бэкенд новее» в самой плашке. Согласен с первым — это и есть суть задачи, она
уже была продуктово одобрена на ревью ТЗ r1. Второе — разумное предложение, но
оно за скоуп #535 (и уже названо автором как таковое в ТЗ и аналитике); отдельным
issue его заводить не обязываю, это на усмотрение владельца/автора при следующей
итерации плашки.

## Чего не проверял

- Полный `npm test` (2530 тестов) — не перегонял целиком, принят по зелёному
  Validate на этом SHA; перепрогнал только пять файлов, прямо затронутых
  диффом (91 тест, все зелёные).
- `pytest tests_backend`, golden, perf-профили, model-invariants — не
  запускал: diff их не касается (см. таблицу гейтов выше).
- Полный список `demo/smoke_*.mjs` — не прогонял; выбрал два по факту, что они
  гоняют именно собранные `dist/houseplan-panel.js`/`dist/houseplan-card.js`
  в браузере (`smoke_houseplan_panel`, `smoke_entry_stale`), `smoke-select.mjs`
  подтвердил отсутствие исполняемого frontend-диффа.
- Поведение в реальном Home Assistant (proxy-кэш, заголовки боевого стенда) —
  вне возможностей код-ревью; измерения из issue (заголовки боевого стенда)
  приняты как представленный автором факт, независимая браузерная проверка
  (`smoke_entry_stale.mjs`) подтверждает механику фолбэка на уровне
  собранного кода.

## Вердикт

Зелёный. Контракт К1–К6 реализован и подтверждён чтением кода, юнитами,
лично перепрогнанными мутантами и двумя независимыми браузерными смоками
против настоящего `dist`. Единственная находка — Low (L1, текст лога),
снята без цикла с записью выше. Медиум/High нет.

---

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

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

- Ветка: `issue/535-panel-card-url`, коммит `063de0eef4bf` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `40cb7affb33a6e9975239d4d9ac9b87fb92b7daa`
  ```
  git log --all --format='%H %T' | grep 40cb7affb33a
  ```
- Тело issue: `77204930eaea05482f2a7da2bac3af79247e7d7356e0449551cb997da2c76fc8`
- Вердикт конвейера: `green` · High 0