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

CODE-REVIEW — issue #341 · заход r1

Скоуп

Issue #341 (трек trivial, метки bug/P3/polish): аудит C5 нашёл, что src/labs.ts защищает подписку на hashchange/popstate только модульным флагом listening. Home Assistant может перезагрузить ресурс карточки без перезагрузки страницы (обновление через HACS, dev-режим, повторная регистрация ресурса) — новая инстанция модуля не видит старый флаг и добавляет вторую пару обработчиков на тот же window, что даёт повторную обработку одного события.

AC1–AC3 из тела issue:

• AC1/AC2 — после двух инициализаций Labs в одном window одно событие hashchange/popstate вызывает обработчик только актуальной инициализации.
• AC3 — обычная одиночная инициализация и разрешение флагов не меняются.

Диапазон: git log --oneline origin/dev..HEAD / git diff origin/dev...HEAD. Коммиты:

• 5f6bddea fix: deduplicate Labs location listeners — src/labs.ts, test/labs.test.mjs.
• 2b6db4c8 docs: refresh screenshot fingerprint — dist/**, custom_components/houseplan/frontend/**, docs/images/**, docs/images/screenshots.json (следствие правки src/**, не отдельная задача).

Продуктовая рамка (SCOPE.md): фикс внутренний, к Core user jobs не привязан напрямую — это защита контракта Labs («One module-level browser listener; card instances only subscribe to its snapshot»), которым управляется presentation-only флаг iso (#89, J1-презентация). Правка не меняет UX, URL/storage-грамматику Labs, жизненный цикл карточки — всё согласно разделу «Не входит» issue. Изменение точечное: только src/labs.ts (class A) + test/labs.test.mjs (class B) + сгенерированные class D/C артефакты. Постороннего кода в диффе нет.

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

Дешёвые гейты на SHA 2b6db4c8 подтверждены Validate (https://github.com/Matysh/houseplan-card/actions/runs/33168458678, success) — npx tsc --noEmit, npm test, npm run build со сверкой бандла не перегонял.

Сам прогнал точечно (диапазон правки узкий, стоимость минимальна):

• npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && node --test test/labs.test.mjs → green, 6/6, включая новый тест «a reloaded Labs module replaces both browser location listeners».
• Тест умеет падать: временно убрал вызов window.__hpLabsListenerCleanup?.() из собранного test-build/labs.js (эмуляция кода до фикса) и перезапустил — новый тест краснеет (2 !== 1, ожидание firstPublishes === 1, фактически 2, т.к. обработчик снятой инстанции продолжает публиковать на hashchange). Откатил файл обратно, git status подтвердил чистое дерево.
• node scripts/check-docs.mjs → green (7 файлов, 10 внешних ссылок) — обязателен, т.к. диф трогает src/**.
• Байт-в-байт сверка dist/** ↔ custom_components/houseplan/frontend/** (houseplan-card.js, houseplan-assets.json, все файлы houseplan-assets/*) → идентичны, bundle:sync не разошёлся.
• node scripts/smoke-select.mjs --base origin/dev --head HEAD → НЕОПРЕДЕЛЁННОСТЬ: 1 файл src/**, ни один из 196 смоков не связан доказуемо; символ без покрытия — onLocationChange. Решение: не прогонять браузерные смоки — onLocationChange не рендерит и не меняет DOM/маршрутизацию, это чистая функция диспетчеризации на publishBrowserLabs, а контракт «ровно одна активная пара обработчиков» полностью воспроизведён и провёрен модульным тестом с двумя реальными ES-module инстанциями (через import(...'?listener-instance=...')), что ближе к реальному сценарию (повторная загрузка ресурса), чем любой браузерный смок мог бы дать.
• Чтение кода (src/labs.ts:147–212): прослежен путь ensureBrowserLabs → window.__hpLabsListenerCleanup для 1, 2 и 3 последовательных инстанций — каждая новая инстанция снимает ровно предыдущую пару обработчиков (через замыкание cleanup, ссылающееся на её же onLocationChange) и кладёт на window свой cleanup; guard if (window.__hpLabsListenerCleanup === cleanup) предотвращает случайное затирание чужого cleanup при непоследовательном вызове. Повторный вызов ensureBrowserLabs в РАМКАХ ОДНОЙ инстанции (обычный случай — несколько карточек на одной странице) не трогает if (!listening) вовсе — поведение AC3 не изменено кодом, а не только заявлением.

Не прогонял: npm run golden:verify (диф не меняет рендер/геометрию/стили — onLocationChange не рисует ничего), npm run invariants (геометрия, layout, толщина стен, open_spans не затронуты), python -m pytest tests_backend (custom_components/**/*.py не менялся), performance-профили (не названы в AC, путь не в горячей точке рендера). npm run bundle:budget не перегонял — автор привёл число (256046 B при бюджете 282000 B) и разница от iso-строки правки незначительна; независимо сверил байт-идентичность копий бандла, что покрывает риск рассинхронизации сильнее, чем повторный бюджет-прогон.

Находки

Нет находок High или Medium. Мелких Low-находок, требующих правки или явного отказа, не нашёл — код и тест соответствуют предложенному в issue решению («хранить состояние подписки на window под приватным глобальным ключом») буквально.

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

• AC1/AC2 доказаны автотестом, тест умеет падать (см. выше) — это не «verified» на честном слове, а воспроизведённый красный/зелёный цикл.
• AC3 — код, отвечающий за одиночную инициализацию, не тронут (if (!listening) guard и его тело для случая true остаются пустой веткой); резолвер флагов (resolveLabs, liveLabsFlags и т.д.) вообще не в диффе — старые тесты резолвера все зелёные без изменений.
• Три и более последовательных инстанций разобраны построчно — не только «два», как в тесте, — инвариант «ровно одна активная пара» держится по индукции для N инстанций.
• window.__hpLabsListenerCleanup — новое глобальное свойство описано в declare global, именование согласовано с существующим __hpLabs, двойное подчёркивание держит приватность соглашения.
• Labs-правила AGENTS.md соблюдены: изменение не вводит новый флаг, не трогает грамматику URL/storage, не гейтит данные/HA-действия — чисто presentation-инфраструктура регистрации слушателей.
• Трейлеры обоих коммитов корректны: Issue: #341, User-Visible: no — согласился с оценкой автора: фикс невидим при обычном использовании (устраняет задвоение реакций на скрытый Labs-флаг iso, а не меняет какое-либо наблюдаемое поведение), changelog обоснованно не трогался.
• Байты бандла (dist ↔ integration copy) и docs-фингерпринт (check-docs.mjs) сошлись — вторая правка 2b6db4c8 не оставила dev с красным docs-джобом (прецедент #230/#234 не повторился).
• Диф нигде не выходит за нужные классы файлов: A (src/labs.ts), B (test/labs.test.mjs), C/D (сгенерированные скриншоты/бандл) — без постороннего кода.
• Единственное новое число, видимое в тесте (счётчики публикаций), не дублирует какую-либо пользовательскую величину — сравнение «одно число, один источник» здесь неприменимо: change не вводит новых значений на экране.

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

• Полный npm test/npm run build/npx tsc --noEmit по всему проекту — положился на зелёный Validate на этом же SHA (см. «Как проверялось»).
• Браузерные смоки — инструмент дал НЕОПРЕДЕЛЁННОСТЬ, обосновал отказ выше; ручного захода в demo-стенд не делал.
• golden, backend pytest, performance — вне зоны дифа, см. обоснование выше.
• Реальный сценарий HACS-перезагрузки ресурса в живом Home Assistant — вне возможностей цикла ревью (нет ручного тестирования); заменено точной симуляцией через две независимые ES-module инстанции, что и является механизмом бага (новая инстанция модуля = новый listening).

Вердикт

Зелёный. Все три AC выполнены и доказаны (автотест + чтение кода), фикс не выходит за скоуп issue, гейты, относящиеся к дифу, зелёные, трейлеры и byte-sync корректны. Блокирующих находок нет.