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

# CODE-REVIEW-354-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/354
- **Этап:** код-ревью (PROCESS.md §2.7)
- **Заход:** r1 · блокирующих циклов израсходовано 0 из 2 (лёгкий трек, лимит 2)
- **SHA материала:** `1397afefd5564abf76cb6ed87b9f5eaee074361b` (`git rev-parse HEAD` на момент вердикта)
- **Ветка:** `issue/354-language-runtime`
- **Вердикт: жёлтый**

## Скоуп

ТЗ в теле issue #354, ревизия 2 (принята SPEC-REVIEW-354-r2, зелёный). Три контракта:

- **К1** — `LANGUAGE_RUNTIME` в `src/i18n/registry.ts` становится экземпляром
  тестируемого класса `LanguageRuntime`, рукописный `germanDictionary/germanPending/
  germanFailed/settleGerman` удаляется.
- **К2 (N7)** — отказ загрузки словаря виден тостом `toast.locale_load_failed`
  только в `houseplan-card` (View); остальные три поверхности (`space-card.ts`,
  `editor.ts`, `space-editor.ts`) остаются при `console.warn`.
- **К3** — возврат дубля ловится контракт-юнитом (`instanceof` + grep источника)
  и мутационным тестом.

Диапазон: `git diff origin/dev...HEAD` — единственный продуктовый коммит
`1397afef`. Файлы: `src/i18n/registry.ts`, `src/i18n/language-runtime.ts`,
`src/houseplan-card.ts`, `src/i18n/{en,ru,de}.json`, `test/i18n-runtime.test.mjs`,
`scripts/mutation-gate.mjs`, `demo/smoke_german_locale.mjs`, оба CHANGELOG,
синхронизированные копии бандла (`dist/**`, `custom_components/houseplan/frontend/**`,
`docs/images/*`, `docs/images/screenshots.json`).

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

| Гейт | Результат | Команда |
|---|---|---|
| typecheck | зелёный | `npx tsc --noEmit` |
| unit-тесты (полный набор) | зелёный, 1487 pass / 0 fail / 1 skip (не связан с #354) | `npm test` |
| build + сверка 3 копий бандла | зелёный, `git status --porcelain` пуст после сборки | `npm run build && npm run bundle:sync` |
| docs-гейт (скриншоты/фингерпринт) | зелёный | `node scripts/check-docs.mjs` |
| bundle:budget | зелёный, 257222 B < 282000 B бюджета (справочно, в AC не заявлен) | `npm run bundle:budget` |
| мутант К3 `language-runtime-handwritten-duplicate` | поймана 1/1 — тест «умеет падать» | `node scripts/mutation-gate.mjs --id=language-runtime-handwritten-duplicate` |
| мутант К2 `locale-failure-toast-dropped` | поймана 1/1 | `node scripts/mutation-gate.mjs --id=locale-failure-toast-dropped` |
| `demo/smoke_german_locale.mjs` (полный прогон) | зелёный, включая новую проверку `failureShowsToast` | `node demo/smoke_german_locale.mjs` |
| adversarial-проверка юнита «подписка получает код» | тест НЕ падает при выключенном fan-out — см. находку M1 | ручной мутант в `src/i18n/registry.ts`, откачен |
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | см. ниже | — |

**smoke-select:** прямое совпадение по символу `_showToast` дало 6 несвязанных
смоков (`smoke_help_affordance`, `smoke_junction_limits`,
`smoke_optimize_coordinate_canonicalization`, `smoke_partition_openings`,
`smoke_room_resize`, `smoke_zero_wall_migration_unblocked`) — это слабая связь:
`_showToast` не менялся (не тронута ни сигнатура, ни реализация метода в
`src/houseplan-card.ts:6373`), диф лишь добавляет новый вызов с новым ключом.
Ни один не прогонялся — решение, а не пропуск. Зарегистрированная связь —
`demo/smoke_german_locale.mjs` (единственный смок, реально завязанный на
`LanguageRuntime`/`LanguageRuntimeContract`) — прогнан, зелёный.

**Не прогонялось и почему:** `npm run golden:verify` (диф не меняет геометрию,
рендер, стили и слои — только текстовая строка тоста и внутренняя разводка
i18n); `python -m pytest tests_backend` (ни один `*.py` не тронут);
`npm run invariants` (геометрия/`layout`/`marker.space`/`open_spans` не
затронуты); performance-профили (не названы в AC, чувствительные пути не
тронуты). Ручного тестирования в браузере (кроме прогона смоков через
Playwright) не проводилось — доказательства ниже отмечены как «прочитано» либо
«доказано автотестом/смоком».

## Находки

### M1 (Medium, в скоупе задачи) — юнит AC4 не проверяет то, что заявляет

**Файл:** `test/i18n-runtime.test.mjs:166-176`

АС4 текстом ТЗ требует три отдельных доказательства: смок с видимым тостом,
**юнит на `subscribeLanguageLoadFailures` («подписка получает код, отписка
работает»)**, и мутант «тост выброшен», красящий смок или юнит. Смок и мутант
на месте и оба проверены (см. таблицу выше). Юнит — нет.

```js
test('language load failure subscription delivers codes and unsubscribes (#354)', async () => {
  const { subscribeLanguageLoadFailures } = await import('../test-build/i18n/registry.js');
  const seen = [];
  const unsubscribe = subscribeLanguageLoadFailures((code) => seen.push(code));
  const second = subscribeLanguageLoadFailures((code) => seen.push(`2:${code}`));
  unsubscribe();
  second();                       // ← это ОТПИСКА второго слушателя, не триггер
  assert.deepEqual(seen, [], 'listeners removed before any failure stay silent');
  assert.equal(typeof unsubscribe, 'function');
});
```

`second` — это возвращаемая функция отписки второго слушателя (сигнатура
`subscribeLanguageLoadFailures` возвращает `() => void`), а не способ вызвать
доставку кода. Тест ни разу не проводит код через
`languageLoadFailureListeners` (`src/i18n/registry.ts:49-56, 65-72*) — он
проверяет только «отписанные слушатели молчат», то есть половину заявленного
в названии.

**Воспроизведение (тест умеет НЕ падать там, где должен):** временно вырезал
итерацию по подписчикам в продакшн-инстанции —

```diff
-  (code) => {
-    for (const listener of languageLoadFailureListeners) listener(code);
-  },
+  (_code) => {
+    // fan-out отключён
+  },
```

и прогнал `node --test --test-name-pattern="#354" test/i18n-runtime.test.mjs`
— все три `#354`-юнита остались зелёными (3/3 ok), в том числе тест из
находки. Правка отката (не коммитилась, `src/i18n/registry.ts` восстановлен из
бэкапа). Реальную поломку fan-out ловит только браузерный
`demo/smoke_german_locale.mjs` (подтверждено отдельно: мутант
`locale-failure-toast-dropped`, который выключает подписку карточки, а не
сам fan-out, тоже красит только смок) — то есть единственная быстрая, не
браузерная защита от регрессии в строке `for (const listener of
languageLoadFailureListeners) listener(code);` отсутствует, хотя АС явно
просит юнит на этот случай.

Это ровно тот класс дефекта, из-за которого заведён сам #354 (N6, «тест
выглядит защитой, а не ту цель проверяет», #85): название и комментарий теста
обещают проверку доставки кода, а тело её не делает.

**Почему Medium, не High:** реальное поведение карточки доказано
(smoke зелёный, мутант К2 ловится смоком) — пользователь тост увидит.
Дефект в надёжности матрицы гейтов, не в продукте: до релиза поломка
fan-out будет поймана медленным браузерным смоком, а не мгновенным юнитом,
как того хотел АС4.

**Как чинить (в этом же issue, без нового цикла на продукт):** переписать
тело теста так, чтобы `second` вызывался как слушатель, получающий код
(например, дать `subscribeLanguageLoadFailures` слушатель, инициировать
доставку через реальный сбой `LanguageRuntime` с фейковой `de`-записью — как
уже сделано в соседнем тесте «a settled dictionary failure reaches the
load-failed hook once» — либо экспортировать тестовый триггер). Минимально:
переименовать тест и явно ограничить его заявленную гарантию до «отписка
работает», раз доставка проверяется только смоком — но тогда стоит явно
сослаться на смок в комментарии, чтобы не терять доказательство из виду.

### L1 (Low, снята с запиской) — `docs/USER-GUIDE.ru.md` не упоminает новый тост

**Файл:** `docs/USER-GUIDE.ru.md:153-158`

Абзац прямо описывает тот же сценарий, который меняет К2: «если обе
ограниченные попытки загрузки не удались, карточка остаётся работоспособной
на английском» — без упоминания, что теперь при этом показывается тост
`toast.locale_load_failed`. Раздел `USER-GUIDE.ru.md` — канонический источник
формулировок интерфейса (AGENTS.md, «Read this first»), и он расходится с
новым поведением ровно там, где раньше был точным.

Не блокирую: цепочка артефактов (PROCESS.md §7.1) не включает
`USER-GUIDE.ru.md` как обязательное звено — только `changelog`, который
актуален (RU+EN, см. таблицу гейтов). ТЗ #354 не называет обновление гайда
частью контракта. Снимаю с запиской: стоит дополнить абзац одним предложением
о тосте при следующей правке этого раздела (например, вместе с #348, чей
canonical-документ он же расширяет).

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

- **AC1** (=К1, К3): `LANGUAGE_RUNTIME` — экземпляр `new LanguageRuntime(...)`
  (`src/i18n/registry.ts:65-72`); `germanPending|germanFailed|settleGerman`
  вне тестового регэкспа в репозитории отсутствуют (`grep -rn` — единственное
  совпадение это сам паттерн в `test/i18n-runtime.test.mjs:143`). Контракт-юнит
  `instanceof` и grep-юнит зелёные; мутант «рукописный дубль» красит юнит
  (1/1, воспроизведено локально). Проверено автотестом + мутантом.
- **AC2**: `test/i18n-runtime.test.mjs` — только дополнения, ни одна старая
  строка не удалена и не изменена (`git diff` по файлу содержит только `+`);
  полный набор зелёный (1487/1487, 0 fail); паритет-тест ключей локалей
  (`test/i18n.test.mjs:109-112`, `Object.keys(en) === Object.keys(dictionary)`
  для каждого языка) прошёл в общем прогоне — новый ключ
  `toast.locale_load_failed` присутствует во всех трёх словарях
  (`en.json`, `ru.json`, `de.json`), несовпадений не было бы иначе. `demo/
  smoke_german_locale.mjs` зелёный целиком, включая старые проверки
  (нейтральный холодный кадр, ровно одна загрузка, атомарный коммит текста,
  повторное использование словаря вторым инстансом, ровно два ретрая,
  ровно один `console.warn`). Проверено автотестом.
- **AC3**: мутант `language-runtime-handwritten-duplicate` (возврат литерала
  вместо `new LanguageRuntime(...)`) красит юнит К3 — поймана 1/1, командой
  `node scripts/mutation-gate.mjs --id=language-runtime-handwritten-duplicate`.
  Проверено автотестом (мутационным).
- **AC4, часть 1 и 3**: смок проверяет `card._toast === card._t('toast.locale_load_failed')`
  в сценарии «оба ретрая упали» (`demo/smoke_german_locale.mjs:83-85`) —
  зелёный. Мутант `locale-failure-toast-dropped` (подписка карточки удалена)
  красит смок — поймана 1/1. Проверено автотестом/смоком + мутантом.
  Часть 2 (юнит на доставку кода) — см. **M1**.
- **К2 периметр**: только `src/houseplan-card.ts` импортирует
  `subscribeLanguageLoadFailures` и вызывает `_showToast`; `space-card.ts`,
  `editor.ts`, `space-editor.ts` используют `LANGUAGE_RUNTIME` напрямую и не
  содержат `toast`/`_showToast` (`grep` пуст). Подписка идёт в
  `connectedCallback` (`src/houseplan-card.ts:2480-2484`, с защитой от
  повторной подписки через `?.()` перед переприсваиванием, тот же паттерн, что
  и у соседнего `_continuityUnsub`), отписка в `disconnectedCallback`
  (`:2557-2560`). Проверено чтением + смоком.
- **Паритет поведения кодов реестра** (en/ru eager, de lazy; `state()`/
  `dictionary()`/`ensure()` для зарегистрированных кодов): построчное сравнение
  старой и новой логики (retry-цикл на 2 попытки, проверка `fingerprint`,
  текст warn `[houseplan] unable to load ${code} locale; using English`
  байт-в-байт с прежним `de`-текстом) — проверено чтением, не исполнением, плюс
  общий прогон существующего `test/i18n-runtime.test.mjs` (доказывающего класс
  с #348) не изменил ожиданий.
- **Трейлеры и changelog**: коммит `1397afef` несёt `Issue: #354` и
  `User-Visible: yes`; `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md` правлены в
  том же коммите (см. `git show 1397afef --stat`). Соответствует правилу №10/11.
- **Генерируемые копии бандла**: после `npm run build && npm run bundle:sync`
  рабочее дерево чистое (`git status --porcelain` пуст) — три копии
  (`dist/**`, `custom_components/houseplan/frontend/**`,
  `demo/srv/assets/**`) синхронны с закоммиченным состоянием.
- **check-docs**: `node scripts/check-docs.mjs` зелёный — скриншоты и их
  фингерпринт актуальны относительно текущего `src/**`.
- **«Одно число — один источник»**: диф не добавляет и не меняет ни одну
  видимую пользователю величину (только строковый текст тоста и внутренняя
  разводка подписки) — правило не применимо к этой задаче.

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

- `npm run golden:verify` — диф не меняет геометрию/рендер/стили/слои, только
  текст тоста и внутреннюю разводку i18n; решение, не пропуск.
- `python -m pytest tests_backend` — ни один `custom_components/**/*.py` не
  тронут.
- `npm run invariants` — геометрия, `layout`, `marker.space`, `open_spans` не
  затронуты этим дифом.
- Performance-профили — не названы в AC, чувствительные к перфу пути не
  задеты.
- 5 из 6 «прямых совпадений» `smoke-select` по символу `_showToast`
  (`smoke_help_affordance`, `smoke_junction_limits`,
  `smoke_optimize_coordinate_canonicalization`, `smoke_partition_openings`,
  `smoke_room_resize`, `smoke_zero_wall_migration_unblocked`) — слабая связь,
  сам метод не менялся; не прогонялись.
- Ручной просмотр карточки в живом браузере HA (только Playwright-смоки
  демо-стенда) — визуальная проверка текста тоста в интерфейсе не
  проводилась, доверился рендер-тексту в DOM через смок-ассерт.