houseplan-card/docs/reviews/SPEC-REVIEW-62-r1.md

# SPEC-REVIEW-62-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/62
- **ТЗ:** `docs/specs/062-i18n-registry.md`
- **Материал ревью:** ветка `issue/62-i18n-registry`, SHA `21d47c52`
  (совпадает с SHA, названным автором в хендоффе на ревью)
- **Заход:** r1 (первый формальный проход; issue шёл `S3-spec` с 2026-08-15,
  ТЗ актуализировано и отправлено на `S4-spec-review` 2026-08-27)
- **Трек:** полный. Аналитика и сам документ явно называют нарушенный критерий
  `small` («одна поверхность») — задета class A i18n сразу в нескольких
  поверхностях (registry, resolver, editor selector, frontend/backend gate,
  CONTRIBUTING). Соответствует текущему умолчанию AGENTS.md (#338): отказ от
  лёгкого трека обосновывается названным критерием, что и сделано.

## Скоуп

Диапазон `origin/dev...HEAD` содержит только два документных коммита класса C:
`docs/specs/062-i18n-registry.md` (новый файл, 292 строки) и добавление одной
строки-ссылки в `docs/specs/README.md`. Продуктового кода (class A) в диапазоне
нет — это ожидаемо для этапа ТЗ, реализация ещё не начиналась.

Задача: убрать дублирование списка языков (`src/i18n.ts` вручную задаёт `Lang`/
`DICTS`, `src/editor.ts` вручную перечисляет `en`/`ru` в selector,
`test/i18n.test.mjs` вручную проверяет только эту пару, frontend/backend
translation-каталоги никак не сверяются) через единый `src/i18n/registry.ts`,
без изменения видимого поведения English/Russian.

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

1. Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком.
2. Прочитано тело issue #62 и все три комментария (аналитика 2026-08-14,
   заведение ТЗ 2026-08-15, актуализация и отправка на ревью 2026-08-27) —
   через `gh issue view` (MCP `get_issue`/`get_issue_comments` были недоступны
   без выданного разрешения).
3. Прочитан ТЗ `docs/specs/062-i18n-registry.md` целиком, сверен на разделы
   §7.1 PROCESS.md.
4. Каждое фактическое утверждение ТЗ о текущем коде сверено с реальным
   деревом, а не принято на слово:
   - `src/i18n.ts` — подтверждён ручной `Lang`, ручные imports, ручной `DICTS`,
     докстрока действительно обещает добавление языка без правок TypeScript,
     что не соответствует коду (`langOf`/`t`/`DICTS` требуют правки);
   - `src/editor.ts` — подтверждён ручной перечень `en`/`ru` в
     `selector.select.options` (строки 100–104), без обработки неизвестного
     сохранённого значения;
   - `test/i18n.test.mjs` — подтверждено прямое чтение `en.json`/`ru.json`,
     без registry, без backend file-set проверки;
   - `custom_components/houseplan/translations/` — подтверждён набор
     `en.json`/`ru.json`, структурно отличный от frontend-словарей (вложенный
     HA config_flow формат против плоского key→string) — ТЗ говорит о паритете
     **набора файлов**, а не содержимого, поэтому структурное различие не
     противоречит контракту;
   - `tsconfig.test.json` — подтверждено отсутствие `src/i18n.ts` в `include`,
     то есть заявленный в §6.4 шаг «включить в tsconfig.test.json» реален и
     нужен; подтверждён существующий паттерн импорта скомпилированных модулей
     тестами из `../test-build/*.js` (`npm test` = `tsc -p tsconfig.test.json`
     → `node --test`), на который ТЗ опирается для registry-driven gate —
     это не техническая догадка, а перенос уже работающего паттерна;
   - `src/types.ts:276` — подтверждён комментарий
     `language?: string; // 'en' | 'ru' | '' (auto — HA profile)`, который ТЗ
     обещает исправить (цель 6);
   - `CONTRIBUTING.md` — прочитан целиком (см. находку ниже);
   - `docs/USER-GUIDE.ru.md` — единственное упоминание `language` (строка 129)
     ограничено таблицей `auto`/`ru`/`en`; ТЗ не меняет эту строку, что
     согласуется с заявлением «пользователь en/ru изменений не увидит»;
   - `docs/CONFIG-COMPATIBILITY.md` — прочитан целиком; поле `language` не
     геометрическое и не относится к категориям, которые реестр обязан
     покрывать (модель стен/layout/marker.space), поэтому отсутствие записи в
     этом реестре не является пробелом ТЗ.
5. Грепом по `src/**` подтверждено, что знание о конкретных кодах `en`/`ru`
   вне `src/i18n.ts`/`src/editor.ts`/`src/types.ts` больше нигде не зашито —
   заявленный ТЗ список затронутых файлов полон.
6. Продуктового кода в диапазоне нет, поэтому `typecheck`/`test`/`build` не
   применимы к этому ревью — гонять их не на чем: диапазон не содержит ни
   одного файла `src/**`/`custom_components/**/*.py`. `check-docs.mjs`
   аналогично не запускался: скриншотный отпечаток зависит от `src/**`, а этот
   диапазон его не трогает.

## Находки

### Medium (в скоупе задачи — чинится в этом же ТЗ)

**M1. `CONTRIBUTING.md` останется противоречить новому contribution flow —
AC9 не покрывает существующую строку.**

- **Файл:** `docs/specs/062-i18n-registry.md`, §9 (и AC9, §10)
- **Воспроизведение:** текущий `CONTRIBUTING.md` уже содержит утверждение
  (раздел «Ground rules»):
  > Adding a language = adding one JSON file + registering it in `src/i18n.ts`.

  После реализации ТЗ добавление языка = frontend JSON + backend JSON + одна
  запись в `src/i18n/registry.ts`; `src/i18n.ts` при добавлении языка больше не
  редактируется (§6.1: «`src/editor.ts`, `langOf()` и список локалей в тестах
  больше не редактируются» — но и сам `src/i18n.ts` тоже не редактируется,
  поскольку registry выносится в отдельный модуль). §9 ТЗ описывает **новый**
  раздел «Translations» в `CONTRIBUTING.md`, но нигде не говорит, что
  существующую фразу в «Ground rules» нужно убрать или привести в соответствие.
  Реализация, буквально следующая ТЗ, добавит верный раздел «Translations» и
  оставит в том же файле, несколькими экранами выше, ложную инструкцию,
  указывающую редактировать `src/i18n.ts` — то есть ровно тот файл, который
  задача выводит из процесса добавления языка.
- **Почему это находка, а не придирка:** AC9 формулируется как «CONTRIBUTING и
  комментарии описывают фактический contribution flow» — с этим пробелом AC9
  по букве может быть выполнен (новый раздел добавлен), а по смыслу нет:
  документ будет противоречить сам себе, и следующий contributor, дочитавший
  до «Ground rules» раньше «Translations», получит неверную инструкцию.
- **Как закрыть:** добавить в §9 явное указание убрать/переписать эту строку
  «Ground rules» так, чтобы она либо ссылалась на новый раздел «Translations»,
  либо была удалена как дублирующая его.
- **Серьёзность:** Medium, в скоупе (документация — часть DoD этой же задачи,
  правка тривиальна, отдельный issue не заводится согласно #202).

### Low (снимается с записью)

**L1. AC2 не имеет явного маркера «Доказательство:» в отличие от остальных
восьми AC.** Формулировка «покрыты матрицей unit-тестов» по смыслу эквивалентна
`Доказательство: unit`, метод проверки не теряется. Косметика, не блокирует.

**L2. AC5 и AC8 подмешивают в доказательство слово «inspection» (`inspection
compiled schema`, `production build inspection») — не входит в канонический
словарь `unit`/`backend`/`smoke`/`golden`/«ревью кода».** По содержанию это и
есть «проверено чтением кода/бандла, не исполнением» — допустимая категория
для code-review, но на этапе ТЗ стоило явно назвать её этим термином, а не
свободным словом. Обе AC при этом дополнительно подкреплены конкретным
автотестом (unit) или диффом, так что решение проверяемо в любом случае.
Снимается без правки текста ТЗ.

Оба Low не блокируют переход и не создают риска молчаливого пропуска: метод
проверки в обоих случаях восстановим по тексту без домысливания.

## Что проверено и признано корректным

- Обязательные разделы §7.1 присутствуют все: сценарий, что человек увидит,
  проблема, скоуп/не-скоуп, контракт поведения, UX, модель данных и миграция,
  i18n, AC1–AC9 с доказательствами, план автотестов, риски, откат,
  release-артефакты — плюс два необязательных (план реализации, «технические
  предположения, можно менять»).
- **Продуктовые вопросы отсутствуют по делу, а не по недосмотру.** Единственный
  пограничный случай с пользовательской видимостью — что видит редактор
  карточки при неизвестном сохранённом `language` (§6.3, §7, AC6) — решён
  автором явно и обоснованно (защита от тихой потери значения при
  редактировании несвязанного поля, в духе уже принятого в `docs/SCOPE.md`
  принципа «не терять данные пользователя на догадке»), а не спрятан как
  открытый вопрос. Формулировка достаточно точна для реализации и
  автотеста без дополнительных уточнений: временная option появляется только
  для незарегистрированного кода, исчезает после явного выбора, не переживает
  несвязанное изменение формы в смысле «взаимодействие не должно её стереть».
  Эскалации владельцу это решение не требовало — оно не меняет поведение
  English/Russian и не вводит новый пользовательский сценарий, только
  расширяет обработку уже существующего (произвольная строка в
  `CardConfig.language`, доступная через YAML) случая.
- Резолюция языка (§6.2: exact tag → primary subtag → English fallback,
  регистронезависимо, `_`→`-`) при двух текущих локалях **эквивалентна**
  нынешнему `l.startsWith('ru') ? 'ru' : 'en'` для всех обычных значений HA
  locale (`ru`, `ru-RU`, `ru_RU`, `en`, `en-US`, что угодно ещё → `en`) —
  проверено разбором обеих реализаций построчно. AC7 («видимый selector и
  значения словарей не меняются») этим не нарушается.
- Заявление «`en`/`ru` пользователь изменений не увидит» подтверждено:
  единственная новая видимая ветвь (временная option) активируется только для
  кода, отсутствующего в registry, то есть никогда для нынешних инсталляций.
- Тестовая стратегия (§11) реалистична: паттерн «скомпилированный TS-модуль
  импортируется тестом из `test-build/`» уже используется в проекте (проверено
  на пяти существующих тестовых файлах), а не изобретается заново.
- Non-scope (§5) закрывает именно те пункты, которые в issue были спорными —
  явно снят lazy loading (ранее упомянутый в заголовке issue и вычеркнутый
  самим автором из формулировки), явно исключены RTL, plural rules, Weblate/
  Crowdin, привязка backend runtime к frontend registry.
- Откат (§13) и release-артефакты (§14) заполнены осмысленно, не шаблонной
  фразой; `User-Visible: no` обоснован отсутствием видимого изменения.
- Трек и его обоснование (полный, а не `small`) соответствуют текущему
  умолчанию AGENTS.md/#338 — критерий назван прямо.

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

- **Гейты `typecheck`/`npm test`/`npm run build`/`check-docs.mjs`/browser
  smoke/golden/backend pytest** — не запускались. Диапазон `origin/dev...HEAD`
  не содержит ни одного файла class A/B (`src/**`, `test/**`,
  `custom_components/**`), только два файла `docs/**`. Гонять их не на чем:
  это этап ТЗ, продуктовый код ещё не написан. Они будут первым осмысленным
  гейтом на этапе код-ревью этой же задачи.
- **Инварианты модели / `smoke-select.mjs`** — не применимо: диапазон не
  трогает геометрию, `layout`, `marker.space`, `open_spans` и не содержит
  browser-исполняемого кода.
- **Реализуемость `Lang`, выведенного из `as const`-массива registry, без
  отдельного union** — не проверялась компиляцией (кода ещё нет), только
  разбором формулировки на внутреннюю непротиворечивость; это TypeScript-паттерн
  без выявленных противоречий, но окончательное слово — у код-ревью, когда
  появится реальный `.d.ts`.

## Вердикт

Один Medium-дефект в скоупе задачи (документация, AC9), без High. Дефект
конкретный, воспроизводимый цитатой существующего файла и правится без
пересмотра контракта — не требует нового цикла продуктового мышления, только
дополнения §9 одной фразой про существующую строку `CONTRIBUTING.md`.

**Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 1 →
в задаче**