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

CODE-REVIEW-406-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/406
• Этап: code (PROCESS.md §2.7)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (перед этим раундом)
• Ветка: issue/406-beta2-polish
• Коммит на ревью: fe385cbf9d5a0fc11f0bcfacbe4ba03e01167949
• ТЗ: docs/specs/406-beta2-polish.md, revision 4, зелёный SPEC-REVIEW-406-r4
• База сравнения: origin/dev = b04387ce914aa8559fb3bc446f99a5751f67f32c

Скоуп

Четыре независимые правки из ТЗ: (а) удаление 13 мёртвых ключей i18n + AST-гейт test/i18n-dead-keys.test.mjs; (б) role="alertdialog" + aria-describedby для hp-confirm (destructive и warning), обычные диалоги остаются на HA-ветке (src/hp-dialog.ts, src/hp-confirm.ts); (в) смок demo/smoke_danger_confirm_branches.mjs покрывает и HA-, и нативную ветку; (г) уборка marker_area_snapshot для исчезнувших устройств только при авторитетном реестре + разворот правила усечения по лимиту (src/device-area-relocation.ts).

Материал ревью — git log --oneline origin/dev..HEAD (9 коммитов, из них 5 docs: review document for #406/docs: resolve.../docs: revise... — все имеют отношение к ТЗ, не к коду) и git diff origin/dev...HEAD (42 файла: продуктовый код, тесты, смоки, мутанты, i18n, бандлы, changelog).

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

Ручного тестирования в цикле нет — правильность работы устанавливается чтением кода, автотестами и браузерными смоками.

Прогнано лично на fe385cbf (зелёного Validate на этом SHA нет):

Гейт	Результат
npx tsc --noEmit	green, без вывода
npm test	1706 passed, 0 failed, 1 skipped — совпадает с заявкой автора
npm run build	green, dist собран за 16.3s
node scripts/bundle-sync.mjs --check (после build)	green, три копии бандла синхронны
npm run bundle:budget	initial 287320 B / budget 300000 B, headroom 12680 B (>0 → AC12 выполнен); есть предупреждение о низком запасе — это фон #367, не регрессия этой задачи
node scripts/mutation-gate.mjs --check	все мутанты, включая три новых (i18n-dead-key-returns, confirm-dialog-loses-alertdialog, area-snapshot-cleanup-ignores-authority), — ok
node scripts/check-docs.mjs	RED — см. находку ниже
node demo/smoke_danger_confirm_branches.mjs	green, все 24 поля true (AC6–AC8)
node demo/smoke_area_relocation.mjs	green, все 20 полей true, включая authoritativeOrphanRemoved/nonAuthoritativeOrphanPreserved (AC9–AC10)
node scripts/smoke-select.mjs --base origin/dev --head HEAD	«НЕОПРЕДЕЛЁННОСТЬ»: изменённых символов проекта — 6 (MARKER_AREA_SNAPSHOT_LIMIT, MarkerAreaBinding, _useHaDialog, _usesHaDialog, validBinding, validText), матрица — 212 смоков, ни один не назван связанным доказуемо

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

• Полная матрица demo/smoke_*.mjs (212 файлов) — диапазон затрагивает только hp-dialog/hp-confirm и device-area-relocation, у обоих есть прямо названные в AC6–AC10 смоки, которые я прогнал. Символы из вывода smoke-select — внутренние помощники (_usesHaDialog, validBinding, MARKER_AREA_SNAPSHOT_LIMIT), уже покрытые юнитами test/device-area-relocation.test.mjs построчно (проверено чтением: тест на переполнение лимита обращается к MARKER_AREA_SNAPSHOT_LIMIT напрямую). Полный прогон матрицы — предрелизная обязанность (§8), не гейт этого раунда.
• npm run golden:verify — прочитал demo/golden/matrix.mjs: ни один сценарий не открывает destructive/warning hp-confirm (есть только device-dialog-*, decor-color, optimize-preflight-dialog — другие диалоги). Видимый рендер, который затрагивает диапазон, в голден-матрице не зафиксирован — прогон не даст сигнала по этой задаче.
• npm run invariants -- --config … — диапазон не трогает рёбра комнат, записи толщины, layout-формат, marker.space или open_spans; device-area-relocation.ts меняет только момент уборки записи снапшота и порядок среза при переполнении, не геометрию. Не применимо.
• python -m pytest tests_backend -q — custom_components/**/*.py в диффе нет (только скомпилированные frontend-бандлы).
• Перфоманс-профили — не названы в AC, чувствительные к перфу пути не тронуты.

Находки

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

node scripts/check-docs.mjs красный на fe385cbf:

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

Воспроизведение (после npm run build, который уже входит в проверки автора):

$ node scripts/check-docs.mjs
ERROR screenshot source fingerprint is stale; run npm run build && node demo/docs/capture.mjs

Причина механическая и ожидаемая: visualFingerprint(ROOT) (scripts/source-fingerprint.mjs) считается по всему src/**, а диапазон меняет src/hp-dialog.ts, src/hp-confirm.ts, src/device-area-relocation.ts и все четыре словаря src/i18n/*.json — то есть отпечаток обязан был измениться, и docs/images/screenshots.json обязан был обновиться вместе с ним, независимо от того, меняются ли реально показанные пиксели. Я дополнительно прогнал node demo/docs/capture.mjs во временной копии рабочей дерева и подтвердил: все 10 сценариев (view-desktop, view-touch, space-create, room-contour-close, plan-context-tray, device-editor, device-display-preview, background-editor, room-card, device-info) — из demo/docs/screenshots.mjs, ни один не открывает destructive/warning hp-confirm, так что заявление автора «скриншоты не меняются» по существу, вероятно, верно (файлы отличались побайтово в моей проверке, но это из-за отсутствующего в песочнице oxipng, не из-за иного содержимого кадра — само сообщение инструмента oxipng не найден: кадры пишутся как есть, без перепаковки называет причину; я откатил эту пробную капчу перед продолжением ревью). Но идентичность пикселей не отменяет обязательности шага: docs/images/screenshots.json в диффе не тронут вообще (git diff origin/dev...HEAD -- docs/images/ — пусто), а check-docs.mjs проверяет именно факт совпадения записанного отпечатка с текущим деревом, не факт визуального совпадения.

Это ровно тот класс регрессии, который уже дважды оставлял dev с красным job docs до следующей задачи (#230, #234, #237): гейт красный на коммите, который автор передаёт на ревью, и останется красным после мержа, если его не прогнать перед мержем.

Ожидаемо: npm run build && node demo/docs/capture.mjs && npm run docs:accept (или эквивалент), обновлённые docs/images/screenshots.json и (если байты правда меняются вне зависимости от oxipng) PNG — в том же PR.

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

• AC1–AC3 (мёртвые ключи, гейт, законные динамические/производные семейства). test/i18n-dead-keys.test.mjs строит множество через реальный TS AST (ts.createSourceFile по каждому файлу src/**/*.ts): литералы, шаблонные выражения с горизонтом +/`, и производное правило _help('x.help') → x.help.aria. Второй тест в файле жёстко фиксирует derivedHelpAria.size === 19 — то есть падает, если производных пар станет больше или меньше 19, а не просто «не меньше». src/i18n/en.json до/после: 13 ключей удалены (history.partition_add, confirm.delete_draft, confirm.delete_draft_segment, title.markup, history.delete_room, markup.delete, marker.display_hint, marker.display_hint_icon, confirm.delete_room, confirm.remove_marker, confirm.delete_space, confirm.unlock, confirm.delete_plan) — совпадает построчно со списком ТЗ. npm test включает оба теста файла и прошёл.
• AC4 (коллизия с test/unified-wall-tool-source.test.mjs). Строка 'history.partition_add' убрана из проверяемого списка теста тем же коммитом, что и ключ из словарей — оба гейта зелёные одновременно (проверено прогоном npm test).
• AC5 (паритет словарей). Диф по de.json/fr.json/ru.json даёт ту же тринадцатку удалённых строк, что и en.json (сверил git diff по каждому файлу построчно) — синхронно, 52 строки суммарно. test/i18n.test.mjs входит в npm test и прошёл.
• AC6/AC7 (роль и aria-describedby). src/hp-confirm.ts: оба kind (destructive и warning) получают .alert=${true} безусловно — дихотомии по виду нет, что и требовал r1/r2 SPEC-REVIEW. src/hp-dialog.ts добавляет alert/describedBy как реактивные свойства, _usesHaDialog() возвращает false, когда alert истинен, — то есть alert-подтверждение принудительно идёт в нативную ветку независимо от customElements.get('ha-dialog'); нативный <dialog> получает role=${this.alert ? 'alertdialog' : 'dialog'} и aria-describedby=${this.describedBy || nothing}. Проверил по всему src/ (grep -n '\.alert='), что .alert выставляет только hp-confirm.ts — ни один из ~30 других вызовов <hp-dialog> (маркер, калибровка, бэкдроп, импорт/экспорт, kiosk, слияние комнат и т.д.) не трогает alert/describedBy, то есть остаются обычным role="dialog" на HA-ветке. demo/smoke_danger_confirm_branches.mjs — green, поля noHaDestructiveIsDescribedAlert/noHaWarningIsDescribedAlert/ haDestructiveStaysNativeAlert/haWarningStaysNativeAlert истинны; последняя пара доказывает именно то, что было провалом в r2 SPEC-REVIEW — alert не уходит в зарегистрированный ha-dialog. Отдельный getByRole на реальном accessibility-дереве Chromium (realAccessibilityTreeIncludesConsequence) подтверждает, что текст последствий действительно долетает до дерева доступности, а не только до DOM-атрибута.
• AC8 (инварианты подтверждения в обоих окружениях). Тот же смок: фокус на «Отмена» (noHa*FocusesCancel/ha*FocusesCancel), Esc → false (noHaWarningEscapeResolvesFalse/haWarningEscapeResolvesFalse), клик по «Отмена» → false в обоих окружениях — все true.
• AC9/AC10 (уборка снапшота только при авторитетном реестре). resolveDeviceAreaRelocations строит liveIds/liveBindings из options.devices и помечает removeSnapshot: true для записей снапшота, чей id и binding не совпадают ни с одним живым устройством/маркером, — но делает это только после if (!options.authoritative) return ... в начале функции, то есть цикл недостижим при неавторитетном реестре. Проверил обоих вызывающих в продукте: houseplan-card.ts:5054/5166 передаёт devices: this._devices — полный список, только что пересобранный buildDevices(...) из актуального registry/markers/settings, а не отфильтрованное подмножество; _syncAreaRelocations (запись) вызывается только при this._haRegistry.authoritative. Читающие проекции (space-render.ts:283, space-card.ts:455) используют только .relocateIds и никогда не вызывают applyAreaRelocationResolution — то есть read-only карточка не может стереть запись сама (staticMadeNoWrites: true в смоке это подтверждает). Юниты test/device-area-relocation.test.mjs («authoritative registry removes orphan snapshots but preserves live marker ids» / «non-authoritative registry preserves orphan snapshots») и смок demo/smoke_area_relocation.mjs (authoritativeOrphanRemoved / nonAuthoritativeOrphanPreserved) оба зелёные. Мутант area-snapshot-cleanup-ignores-authority (снимает условие authoritative) ловится именно этим юнитом — проверил прогоном mutation-gate.mjs --check.
• AC11 (усечение снапшота сохраняет последние записи). Один символ правки: .slice(0, MARKER_AREA_SNAPSHOT_LIMIT) → .slice(-MARKER_AREA_SNAPSHOT_LIMIT). Новый юнит-тест строит вход LIMIT + 2 записей и проверяет, что первые две (entry-0, entry-1) исчезли, а последняя (entry-${LIMIT+1}) осталась, — тест умеет падать: на старом .slice(0, LIMIT) он утверждал бы обратное и провалился бы.
• AC12 (бюджет initial). npm run bundle:budget → 287320 B при бюджете 300000 B, положительный запас — не растёт (совпадает с ожиданием ТЗ: удаление 52 строк уменьшает бюджет, атрибуты добавляют единицы байт).
• Трейлеры и changelog. Коммит fe385cbf: Issue: #406, User-Visible: yes. docs/CHANGELOG.md/docs/CHANGELOG.ru.md получили по одному пункту про переход на нативную оболочку и alertdialog — в том же коммите, что и код (проверено git show --stat fe385cbf).
• Одно число — один источник. Диапазон не добавляет и не меняет ни одной видимой пользователю величины (роль/aria — не число; лимит 20_000 не показывается пользователю ни в каком UI) — раздел неприменим по существу, а не пропущен. test/single-source-numbers.test.mjs входит в npm test и прошёл.

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

• Полную матрицу demo/smoke_*.mjs (212 файлов) — обоснование в разделе «Как проверялось».
• npm run golden:verify — ни один голден-сценарий не открывает затронутый диалог; обоснование там же.
• npm run invariants и python -m pytest tests_backend — диапазон их не задевает (геометрия/толщина/layout не тронуты; .py-файлов в диффе нет).
• Перфоманс-профили — не названы в AC, не тронуты.
• Реальный визуальный вид нативного диалога в живом Home Assistant (смена HA-хрома на нативную оболочку, которую ТЗ прямо называет видимым компромиссом) — только по коду и accessibility-дереву Chromium; ручного просмотра в настоящем HA в этом цикле нет и не может быть.

Вердикт

Единственная находка — Medium, в скоупе задачи (устаревший отпечаток docs/images/screenshots.json после правок в src/**), чинится тем же шагом, что автор уже применяет в релизном процессе. Все 12 AC доказаны тестом или смоком, который я лично прогнал и который умеет падать (мутанты подтверждают это для трёх ключевых контрактов). High-находок нет.

Жёлтый.