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

# CODE-REVIEW-391-r1

Issue: #391 «refactor: type editor i18n keys»
Этап: code (S7-code-review)
Заход: r1 (первый код-ревью раунд; спек-ревью прошло зелёным на r1 отдельно)
Ветка: `issue/391-i18n-key-casts`
SHA под ревью: `81a4278aa4236cec656e473e3ff3953a05c6c5d1` (пайплайн привёл ветку к `dev`
поверх коммита `f7f088fe`; после ребейза это другой код — разбор ниже полный).
Материал: `git diff origin/dev...HEAD` относительно локально закэшированного
`origin/dev` = `eb5aa2a0f8dea5514ee2fee2dbd609457dd0fb4d`.

## Скоуп

Класс A: `src/houseplan-editor-runtime.ts` — снятие `as any` с 33 вызовов
`this.host._t(...)` в трёх семействах ключей (`device_inbox.*` — 26,
`marker.*` — 6, `gs.preflight_reason_*` — 1) и замена вычисляемых ключей на
узкий `as I18nKey`, без изменения словарей, текстов, разметки и ветвления.
Класс B: `scripts/mutation-gate.mjs` — перенос mutation-anchor #295
(`preflight-reason-lost-in-dialog`) на новый файл/сигнатуру после того, как
lazy-load рефакторинг увёл вызов из `houseplan-card.ts` в
`houseplan-editor-runtime.ts` (без изменения `guard`/`because`).
Класс D: `dist/**`, `custom_components/houseplan/frontend/**` — пересборка.
`User-Visible: no`, трейлер `Issue: #391` на месте — оба корректны для
чисто типового рефакторинга без пользовательского эффекта; изменений в
`docs/CHANGELOG*.md` нет и не требуется.

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

Зелёного Validate на этом SHA не найдено, поэтому гейты прогнаны вручную на
чистом дереве этого коммита (Node 22, зависимости уже установлены):

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | pass, без вывода |
| Unit/integration | `npm test` | 1644 pass / 0 fail / 1 skipped |
| No-new-any (#342) | `git diff origin/dev...HEAD -- src/houseplan-editor-runtime.ts \| node scripts/no-new-any.mjs --diff -` | «Проверено добавленных строк: 32 в 1 файл(ах). Новых any нет.» |
| Mutation-gate анchor (#295) | `node --test test/mutation-gate.test.mjs` | 10/10 pass |
| Build | `npm run build` | pass |
| Bundle sync | `npm run bundle:sync` | pass; `git status --porcelain` после пересборки — пусто (обе generated-копии побайтово совпадают с закоммиченными) |
| Bundle budget | `npm run bundle:budget` | initial View 283100 B / budget 300000 B; lazy editor 143903 B; lazy locale 46996 B — совпадает с числами автора |
| Inventory | `npm run inventory` | Node 1645 (было 1643 у автора; расхождение — от несвязанного коммита `eb5aa2a0`, легшего поверх после отправки на ревью, не дефект этой задачи) |
| Docs fingerprint | `node scripts/check-docs.mjs` | **FAIL** — см. находку M1 |

Diff не трогает геометрию/модель (нет правок `wall-thickness.ts`, `layout`,
`marker.space`, `open_spans`, узлов/рёбер) — `npm run invariants` не
запускался, это осознанный пропуск, а не мелочь.
Diff не трогает `custom_components/**/*.py` — `pytest tests_backend` не
запускался.
`golden:verify` не запускался: изменение не может повлиять на рендер —
это доказано не только заявлением автора, а тем, что все правки состоят
из удаления TypeScript-каста (`as any`/`as I18nKey`), который стирается на
этапе компиляции без остатка; визуальных/строковых/ветвящихся изменений в
diff нет.

### Браузерные смоки

`node scripts/smoke-select.mjs --base origin/dev --head HEAD`:

```
Изменено файлов src/**: 1 · символов проекта на изменённых строках: 4
Прямое совпадение (7): _showToast →
  smoke_help_affordance, smoke_junction_limits,
  smoke_optimize_coordinate_canonicalization, smoke_partition_openings,
  smoke_room_resize, smoke_tap_ctx, smoke_zero_wall_migration_unblocked
```

Символ `_showToast` попал в выборку механически: он встречается на той же
строке, что и переименованный `_t('device_inbox.saved' as any)` →
`_t('device_inbox.saved')`, хотя сам вызов `_showToast` не менялся. Решение:
прогнать все 7 — дёшево, а инструмент прямо предупреждает не полагаться на
тематический отбор (регресс #234 был пойман смоком, чьё название не
подсказывало связь). Все 7 — `OK`. Дополнительно прогнан
`node demo/smoke_preflight_diagnostics.mjs` — это ровно guard-команда
mutation-anchor `preflight-reason-lost-in-dialog`, который правит diff;
`OK`. Итого 8 браузерных смоков, все зелёные. Полный набор (208 смоков) не
запускался — задача не задевает ничего, кроме уже перечисленного, это
предрелизная обязанность, а не гейт код-ревью.

## Находки

### M1 (Medium, в скоупе — правится в этой же задаче) — стал протухшим отпечаток скриншотов документации

`node scripts/check-docs.mjs` на SHA `81a4278a` падает:

```
ERROR screenshot source fingerprint is stale; run npm run build && node demo/docs/capture.mjs
```

Воспроизведение и причина, а не голословно: `visualFingerprint()`
(`scripts/source-fingerprint.mjs`) хэширует весь `src/**` плюс несколько
build-input файлов. Коммит правит `src/houseplan-editor-runtime.ts`, поэтому
отпечаток обязан был измениться — и изменился (проверено прямым вызовом:
на этом SHA `visualFingerprint('.')` = `74378a15…`, а
`docs/images/screenshots.json.sourceFingerprint`, оставшийся из `dev`, —
`d27cbb20…`; для контроля тот же расчёт на чистом клоне `origin/dev`
(`eb5aa2a0`, без диффа этой задачи) даёт согласованные `d27cbb20…` с обеих
сторон — несовпадение появляется ровно с этим коммитом, а не раньше).
Коммит не содержит правок `docs/images/**`, то есть шаг
`npm run build && node demo/docs/capture.mjs` не выполнялся.

Это не гипотетическая придирка: `docs` — один из перечисленных gate-джобов
Validate (AGENTS.md), и ровно этот пропуск уже дважды оставлял `dev` с
красным `docs` до отдельной последующей задачи (#230, #234 → почищено в
#237). Смысловых изменений отпечаток не несёт (правки — чистое удаление
типовых кастов, кадры почти наверняка выйдут пиксель-в-пиксель прежними),
но манифест обязан отражать актуальный `sourceFingerprint`, иначе `docs`
red на `dev` сразу после мержа.

Почему Medium, а не High: не портит пользовательское поведение, не ломает
контракт, чинится механически. Почему в скоупе этой задачи, а не отдельный
issue: находка — прямое следствие ровно этого diff (правка src/** этой
задачи сделала отпечаток невалидным), а не постороннего дефекта соседней
подсистемы — правило «Medium вне скоупа → отдельный issue» сюда не
применяется.

Что нужно для закрытия: `npm run build && node demo/docs/capture.mjs`,
проверить, что кадры не изменились (`imageSha256` в манифесте), закоммитить
обновлённый `docs/images/screenshots.json` (и PNG, если оптимизатор дал
другие байты) в той же ветке с трейлерами `Issue: #391` / `User-Visible: no`
— это не пользовательская документация, а служебный манифест, видимое
поведение не меняется.

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

- Пересчитаны все 33 целевых вызова построчно (`grep` по
  `_t(.*as any` до/после диффа): 26 `device_inbox.*` + 6 `marker.*` + 1
  `gs.preflight_reason_*` — все убраны; ни один каст той же строки за
  пределами трёх заявленных семейств не тронут (проверено: `tap.*`,
  `fill.*`, `decor.*`, `junction.*`, `vac.*`, `run.*` и generic `message`/
  `hintKey`/`labelKey` остаются с `as any` — корректно, они вне скоупа).
- Условный `readd`/`add` (строка ~12054) переписан на литеральный union без
  каста на каждой ветке, как требует правило реализации №5 — подтверждено
  диффом.
- `I18nKey` был импортирован и `_t` уже строго типизирован до этой правки
  (строки 245, 1104 в текущем файле) — задача действительно восстанавливает
  существующий контракт, а не создаёт новый.
- Ни `as never`, ни `as unknown as`, ни новых `any`, ни расширения
  сигнатуры `_t`/`I18nKey` в diff нет — подтверждено чтением полного diff и
  `no-new-any.mjs`.
- Ключи, тексты и ветвление визуально не изменились — единственные строки
  diff это удаление/сужение каста; проверено чтением, не исполнением, для
  всех 33 мест плюс подтверждено 8 зелёными браузерными смоками и `npm
  test`, включая i18n parity/policy-тесты в общем прогоне.
- Mutation-anchor `preflight-reason-lost-in-dialog` (#295) актуализирован
  корректно: `find`-строка патча совпадает буквально со строкой 9769
  текущего файла, `guard`/`because` не изменены, `node --test
  test/mutation-gate.test.mjs` зелёный (уникальность/применимость мутантов
  проверяется этим набором), `node demo/smoke_preflight_diagnostics.mjs` —
  `OK`.
- Generated bundle (класс D) синхронизирован и совпадает побайтово: после
  `npm run build && npm run bundle:sync` `git status` пуст.
- Трейлеры коммита корректны: `Issue: #391`, `User-Visible: no`; changelog
  оправданно не тронут.
- Ремарка спек-ревью про два «нечистых» вычисляемых ключа
  (`marker.value_badge_attr_${source.attribute}`, где `attribute: string`,
  и `.replace()/.replaceAll()`, теряющие литеральный тип) — не новый риск:
  тот же профиль (произвольная строка, приведённая к `I18nKey`) был и до
  правки под `as any`; ТЗ сознательно разрешает это как единственно
  доступный вариант, когда компилятор сам не выводит ключ.

## Чего не проверял и почему

- `npm run invariants` — diff не касается геометрии/модели (нет правок
  толщины стен, `layout`, `marker.space`, `open_spans`, рёбер решётки).
- `python -m pytest tests_backend` — diff не касается
  `custom_components/**/*.py`.
- `npm run golden:verify` — правка стирается на этапе компиляции
  (`as any`/`as I18nKey` не производят рантайм-кода), рендер не может
  измениться; смоки подтверждают отсутствие видимых эффектов дешевле, чем
  полный golden-прогон.
- Полный набор из 208 браузерных смоков — не оправдано ни AC, ни объёмом
  diff (одна поверхность, 33 каста в одном файле); прогнаны все 7
  «прямых совпадений» инструмента подбора плюс guard-смок мутанта — этого
  достаточно для типовой правки такого размера.
- Performance-профили — не названы в AC, diff не касается чувствительных к
  перфу путей.
- Ручное тестирование в браузере (UI) не проводилось — не требуется:
  изменение не может изменить скомпилированную семантику, что подтверждено
  выше техническим аргументом (стирание типовых кастов), а не только словом
  автора.

## Вердикт

Единственная находка (M1) — Medium, в скоупе задачи, чинится в ней же:
`npm run build && node demo/docs/capture.mjs`, проверка, что кадры не
изменились, коммит обновлённого манифеста с теми же трейлерами. High
находок нет. Все AC из тела issue выполнены и подтверждены либо тестом,
либо построчным чтением с указанием, что именно проверено. Вердикт —
жёлтый.