houseplan-card/docs/reviews/CODE-REVIEW-62-r2.md

CODE-REVIEW-62-r2

Issue: #62 — Инфраструктура i18n: единый реестр языков и автоматические проверки Этап: code (PROCESS.md §2.7) Заход: r2 · блокирующих циклов израсходовано 1 из 4 SHA под ревью: c755a0ef (диапазон origin/dev..HEAD, 7 коммитов) Предыдущий раунд: код-ревью r1, вердикт красный, SHA 6540474f, High: 1, Medium: 0.

Скоуп раунда

Раунд по дельте (PROCESS.md §2.9/§2.10). Дельта 6540474f..c755a0ef — один commit c755a0e "fix: normalize i18n registry lookup keys":

 .../houseplan/frontend/houseplan-card.js |   4 +-
 dist/houseplan-card.js                   |   4 +-
 docs/images/screenshots.json             |  22 +-
 docs/reviews/CODE-REVIEW-62-r1.md        | 270 +++++++++++++
 src/i18n/registry.ts                     |  13 +-
 test/i18n.test.mjs                       |  12 +
 6 files changed, 306 insertions(+), 19 deletions(-)

Дельта строго локальна: один production-файл (src/i18n/registry.ts), один тест-файл, регенерированные bundle-копии и документационный fingerprint (следствие пересборки), плюс коммит предыдущего ревью-документа (артефакт конвейера, не код). Ребейза на ушедший вперёд dev не было — dev не двигался под веткой между раундами (проверено: коммит 6540474f, на котором получен r1, лежит в текущей истории HEAD без слияний). Новая подсистема не затронута, контракт поведения не меняется — коммит явно чинит единственную находку r1. Разбор по границе «находка r1 плюс всё, до чего дотягивается дельта» — полный прогон AC1–AC9 заново не требуется.

Закрытие раунда r1

Находка r1	Чем закрыта	Где это видно
H1. LANGUAGE_BY_CODE строился как new Map(LANGUAGE_REGISTRY.map(entry => [entry.code, entry])) — ключ - «сырой» entry.code (canonical spelling, например pt-BR), а languageEntry() ищет по normalizeLanguageTag() (lowercase). Для en/ru совпадение случайное; для будущего pt-BR/zh-Hant languageEntry()/t()/hasTranslation() молча откатывались бы на English без ошибки и без падающего теста.	Ключ и поиск теперь проходят через одну и ту же чистую функцию normalizeLanguageTag: добавлена buildLanguageLookup<T extends {code: string}>(entries), которая строит Map по normalizeLanguageTag(entry.code); LANGUAGE_BY_CODE = buildLanguageLookup(LANGUAGE_REGISTRY); languageEntry() не изменился — LANGUAGE_BY_CODE.get(normalizeLanguageTag(value)). Поскольку обе стороны сопоставления проходят через одну и ту же функцию, совпадение гарантировано структурно для любого будущего кода, а не только для сегодняшних en/ru.	src/i18n/registry.ts:26-45 (diff 6540474f..c755a0ef). Добавлен тест test/i18n.test.mjs:43-51 — buildLanguageLookup([{code:'pt-BR',...}]) резолвит 'pt-br' и normalizeLanguageTag('PT_br'), плюс цикл languageEntry(entry.code.toUpperCase()) по всей продакшн LANGUAGE_REGISTRY.

Проверка не ограничилась чтением диффа. Собрал старую (r1, до фикса) реализацию languageEntry/LANGUAGE_BY_CODE в отдельном scratch-скрипте вне репозитория и прогнал реальный normalizeLanguageTag из собранного test-build/i18n/registry.js против неё:

loop over registry (with synthetic pt-BR) with OLD languageEntry: FAILED -> mismatch for pt-BR
  + undefined
  - { code: 'pt-BR', dictionary: {}, nativeLabel: 'x' }

т.е. старая реализация действительно ломалась на смешанном регистре — H1 воспроизводим, а не гипотетичен. С исправлением та же проверка (через buildLanguageLookup, которым сейчас реально построена LANGUAGE_BY_CODE) проходит: test/i18n.test.mjs зелен (см. «Гейты» ниже), и логика симметрична по построению — не привязана к тому, что сегодняшние en/ru уже lowercase.

Важный нюанс, который стоит отметить, не как блокирующую находку. Добавленный тест i18n: canonical regional codes use normalized lookup keys доказывает корректность самой функции buildLanguageLookup на синтетическом pt-BR — это единственный способ вообще проверить чувствительность к регистру, пока в продакшн-реестре только en/ru (оба уже lowercase, и поэтому цикл по реальному LANGUAGE_REGISTRY в этом же тесте не может отличить старое и новое поведение — я это тоже проверил прогоном: старая реализация проходит этот цикл на en/ru без единой ошибки). Однопроточное связывание LANGUAGE_BY_CODE = buildLanguageLookup(LANGUAGE_REGISTRY) — единственное место, которое реально несёт риск отката H1, и оно не покрыто тестом, который заметил бы регресс именно в этой строке при сегодняшних данных; страховка — то, что это буквально одна читаемая строка рядом с протестированным примитивом. Считаю это Low, не заводящим находку: раздвинуть покрытие потребовало бы либо держать в продакшн-реестре синтетическую запись не только в тестах, либо экспортировать внутреннее состояние ради теста — непропорционально риску одной строки композиции. Фиксирую для протокола, не блокирую.

Унаследовано из r1

Из docs/reviews/CODE-REVIEW-62-r1.md (SHA 6540474f, вердикт красный, High: 1 — единственная находка закрыта выше) принято без повторной проверки:

• AC3 (frontend/backend file-set parity), AC4 (registry-driven key/placeholder/help-key parity), AC5 (порядок Auto/English/Русский без ручного списка в src/editor.ts), AC7 (значения словарей и видимый selector не меняются), AC8 (нет async/dynamic import в production bundle), AC9 (CONTRIBUTING описывает актуальный flow) — дельта 6540474f..c755a0ef не касается ни src/editor.ts, ни словарей en.json/ ru.json, ни CONTRIBUTING.md, ни путей загрузки/бандлинга; доказательства r1 остаются в силе.
• Гейты r1 (typecheck/test/build/check-docs/git diff --check, сверка SHA-256 трёх bundle-копий, ручная проверка единственного изменившегося PNG 06-device-editor.png через ImageChops.difference) — перепрогнаны заново в этом раунде (см. ниже), не просто унаследованы, так как код изменился.
• Отсутствие применимости npm run invariants и golden/backend/perf гейтов — унаследовано: дельта r2 такая же не геометрическая и не HA-Python, как и весь diff r1.

Не унаследовано, перепроверено заново в этом раунде: AC1 (Lang, langOf(), options — из одного registry) и AC2 (exact/normalize/fallback матрица разрешения языка) — именно они опираются на languageEntry(), затронутый фиксом. AC6 (неизвестный сохранённый язык не ломает card/editor) косвенно затронут через languageOptions() (строка 90 вызывает languageEntry(raw) для подписи сохранённого чужого значения) — проверил чтением: ветка !options.some(...) выполняется только для значений, не совпадающих ни с одним зарегистрированным кодом буквально, так что для сегодняшних en/ru изменение не меняет наблюдаемое поведение AC6; для будущих canonical кодов фикс делает эту подпись корректной тем же структурным аргументом, что и AC1/AC2.

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

Зелёного Validate на SHA c755a0ef нет — прогнал гейты сам:

• npx tsc --noEmit — green.
• npm test — green: tests 1416 / pass 1415 / fail 0 / skipped 1 (единственный skip — issue 281 private exact fixture has no enabled zero-range handle, условный на отсутствующей приватной фикстуре, не связан с этой задачей и не связан с дельтой).
• npm run build — green; сверил dist/houseplan-card.js и custom_components/houseplan/frontend/houseplan-card.js по SHA-256 — оба 17901d69... — совпадают. Третья копия (demo/srv/assets/houseplan-card.js) генерируется рантаймом демо-сервера и в .gitignore, в бандл-инвариант не входит.
• node scripts/check-docs.mjs — green: Documentation checks passed (7 files, 10 external links). Diff трогает src/** (registry.ts), поэтому гейт обязателен; изменившийся docs/images/screenshots.json (sourceFingerprint/sourceSha256 пересчитаны на новый исходник, imageSha256 всех сценариев не изменился) — согласован с этим гейтом.
• git diff 6540474f..c755a0ef --check — green, без пробельных ошибок.
• Трейлеры коммита c755a0e: Issue: #62, User-Visible: no. Соответствует факту — фикс не меняет наблюдаемое поведение сегодняшних en/ru (подтверждено неизменностью imageSha256 во всех 9 сценариях screenshots.json), правок changelog не требуется и не сделано.

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

• npm run invariants — diff не касается геометрии/layout/marker.space/ open_spans; тот же вывод, что в r1.

• python -m pytest tests_backend -q — diff не касается custom_components/**/*.py (проверил git diff --stat по этому пути — пусто).

• npm run golden:verify — diff не может изменить видимый рендер: правка живёт внутри languageEntry(), применяется только когда сохранённый код языка отличается регистром/разделителем от canonical записи реестра; сегодняшний реестр (en, ru) уже canonical lowercase, поэтому видимый результат не меняется — независимо подтверждено imageSha256 в screenshots.json (не изменился ни в одном из 9 сценариев).

• Браузерные смоки — прогнал node scripts/smoke-select.mjs --base 6540474f --head c755a0ef:

  Изменено файлов src/**: 1 · символов проекта на изменённых строках: 5
  Матрица: 194 смоков · порог «широкого» символа: больше 38 смоков
  
  НЕОПРЕДЕЛЁННОСТЬ: дифф исполняемый, но ни один смок не связан доказуемо.
  Символы, которых нет ни в одном смоке: LANGUAGE_BY_CODE, LANGUAGE_REGISTRY,
  LanguageEntry, buildLanguageLookup, normalizeLanguageTag
  

  То же НЕОПРЕДЕЛЁННОСТЬ, что и в r1 (тогда — по всему PR, сейчас — по этой более узкой дельте, символы те же). ТЗ §11 обоснованно исключает browser smoke для этой задачи; в r1 уже принято решение не прогонять — унаследовано, дельта не меняет этот вывод.

• Performance-профили — не названы в AC, диф не трогает чувствительные к перфу пути.

• «Одно число — один источник» — не применимо: дельта не добавляет и не меняет пользовательскую видимую величину (нет чисел, только строковый lookup языка).

Находки

Нет находок High или Medium в скоупе. Один Low зафиксирован выше в разделе «Закрытие раунда r1» (тонкое место в покрытии регрессионного теста, непропорциональное риску одной строки композиции) — не блокирует, не заводится отдельным issue (не Medium и не вне скоупа).

Вывод по AC

AC1, AC2 — перепроверены в этом раунде: доказаны чтением (src/i18n/registry.ts:26-45) плюс unit test/i18n.test.mjs:43-51, тест умеет падать (продемонстрировано прогоном старой реализации против того же входа — см. «Закрытие раунда r1»). AC6 — перепроверен чтением частично (затронутая ветка languageOptions()), для сегодняшних данных поведение не меняется. AC3–AC5, AC7–AC9 — унаследованы из r1 без повторной проверки, дельта их не касается.

Вердикт

Зелёный. H1 из r1 закрыт корректно, фикс структурно общий (не завязан на то, что сегодня en/ru уже lowercase), гейты green, дельта локальна и не требует полного повторного разбора.