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

CODE-REVIEW-20-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/20
• ТЗ: docs/specs/020-glow-open-door-spill.md (ревью ТЗ зелёное, docs/reviews/SPEC-REVIEW-20-r1.md, 2026-08-28)
• Ветка: issue/20-glow-open-door-spill
• SHA материала ревью: f62926fbeb9e79e850eef54f01448bdf3aed5b68 (единственный коммит с продуктовым кодом; впереди него в ветке — 72e6939f docs: review document, 3fa98a09 docs: actualize spec, оба до реализации и без изменений в src/**)
• Заход: r1 · блокирующих циклов израсходовано 0/4 (это первый заход)

Скоуп

Дифф origin/dev...HEAD: src/logic.ts, src/houseplan-card.ts, src/physical-geometry.ts, src/space-render.ts, тесты (test/logic.test.mjs, test/physical-geometry.test.mjs, test/golden-matrix.test.mjs), demo/smoke_glow.mjs, demo/golden/matrix.mjs, demo/fixtures/visual-matrix.mjs, docs/LIGHT.md, docs/ARCHITECTURE.md, changelog RU/EN, плюс сгенерированные bundle-деревья и пересобранные скриншоты документации. Ровно один коммит класса A/B (f62926fb) с трейлерами Issue: #20 / User-Visible: yes.

Задача полного трека (не small): геометрия и горячий render/cache-путь.

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

Гейт	Команда	Результат
typecheck	npx tsc --noEmit	OK
unit	npm test	1503 тестов: 1502 passed, 1 skipped, 0 failed
build + сверка копий	npm run build && npm run bundle:sync	OK; dist/, custom_components/.../frontend, demo/srv/assets идентичны, git status чист после sync
bundle budget	npm run bundle:budget	initial View 271455 B gzip / бюджет 282000 B, запас 10545 B
no-new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	111 добавленных строк в 4 файлах, новых any нет
check-docs (diff трогает src/**)	node scripts/check-docs.mjs	OK: 7 файлов, 10 внешних ссылок
smoke-select	node scripts/smoke-select.mjs --base origin/dev --head HEAD	10 прямых совпадений (список ниже)
browser smokes (все 10 прямых совпадений)	node demo/smoke_{registryless_opening,glow,opening_binding,linked_virtual_light,open_passage,opening_entity_search,opening_preview,partition_openings,plan_drawing_repairs,plan_snap_overlay}.mjs	все 10 — OK
golden	npm run golden:verify (полная матрица, 80 сцен)	79 passed, 1 different: lighting-opaque-glow-two-doorways-dark — см. «Известный пробел» ниже
invariants	не запускал	диф не меняет сохранённую геометрию/схему (см. обоснование ниже)
backend pytest	не запускал	custom_components/**/*.py не тронут
performance smoke	не запускал	AC9 сам называет доказательством exact-SHA CI performance smoke перед бетой, не код-ревью

smoke-select, вывод целиком:

Изменено файлов src/**: 4 · символов проекта на изменённых строках: 24
Прямое совпадение (10): smoke_registryless_opening.mjs (_openingAmt, _openingsR,
_renderOpeningEntityAvailable, _renderPlanHass), smoke_glow.mjs (_cmToUnits, _openingsR,
_pointInRoom), smoke_opening_binding.mjs (_openingAmt, _openingsR),
smoke_linked_virtual_light.mjs (_renderPlanHass), smoke_open_passage.mjs (_openingsR),
smoke_opening_entity_search.mjs (_openingsR), smoke_opening_preview.mjs (_openingsR),
smoke_partition_openings.mjs (_openingsR), smoke_plan_drawing_repairs.mjs (_cmToUnits),
smoke_plan_snap_overlay.mjs (_cmToUnits). Ничего не учтено как «широкий» символ (порог >40).

Прогнал все 10, а не только тематически близкие: инструкция прямо предупреждает, что тематическое сужение уже один раз пропустило регресс (#234), а здесь все 10 — прямые совпадения, не слабые связи.

Инварианты модели не прогонял. Диф не меняет сохранённую геометрию, layout, marker.space, open_spans или ключи записи толщины — вырезы, которые теперь зависят от amount, вычисляются заново на каждый рендер из НЕ сохраняемого состояния HA и не пишутся обратно в конфиг (спека прямо это фиксирует: «Модель и сохранённый JSON не меняются»). Автор указал ту же причину в хендоффе. Согласен: инварианты отвечают на вопросы про персистентную геометрию, здесь её нет.

Находки

Блокирующих (High) находок нет. Находок уровня Medium в скоупе или вне скоупа нет.

Low L1 — AC7 для контурной (не partition) стены доказан только чтением кода, не тестом

test/physical-geometry.test.mjs получил новый тест именно для перегородки («partition body uses the same full, partial and closed light aperture» — pointInOpaquePlanBody проверен для full/half/closed на партиционном хосте). Для обычного проёма в контурной стене (не partition) аналогичного прямого теста «источник внутри закрыто-схлопнутого выреза подавлен» не добавлено — существующий sourceInsideWallSuppressed в demo/smoke_glow.mjs не изменился и проверяет источник внутри обычной стеновой массы, а не внутри именно закрытой (amount<=0) двери.

Прочитал код и убеждён, что риск закрыт по конструкции, а не только по вере в автора: _lightBarriers() (src/houseplan-card.ts:10267-10410) отдаёт masonryGeometry/opaqueBodies из ТОГО ЖЕ passageStates/roomPassages, из которого строится видимость — вырез контурной стены создаётся, только если amount > 0 (см. passages = passageStates.filter(({amount}) => amount > 0) → _roomWallOpeningInputs(passages, space) → recutWallBodiesGeometry/ wallBodiesGeometry). Guard источника читает именно этот masonryGeometry (pointInOpaquePlanBody(sourcePoint, masonryGeometry, opaqueBodies), строка 10481) — то есть закрытая контурная дверь механически становится частью той же непрозрачной кладки, что и окно, для которого fail-dark уже покрыт существующими тестами (test/physical-geometry.test.mjs, test/houseplan-runtime-contract.test.mjs, оба не в этом диффе и не задеты). Это тот же код до и после диффа — диф не добавил отдельной ветки для «закрытой двери», он лишь расширил множество «непрозрачных» проёмов условием amount<=0 вместо жёсткого «окно/наружная».

Проверено чтением, не исполнением. Оставляю Low: тест — не догадка, будущая правка того же файла с меньшей вероятностью сломает это неявно проверенное свойство, если бы у контурного случая было явное assert-покрытие. Решение по Low — на усмотрение автора/следующего раунда, не блокирует.

Что проверено и корректно (по AC ТЗ)

• AC1 (закрытая привязанная дверь не пропускает Glow). Доказано: openingAmount() (src/logic.ts:305-330) возвращает 0 для закрытого бинарного контакта; при amount<=0 проём не входит в passages → не вырезается из кладки (src/houseplan-card.ts:10317-10327). demo/smoke_glow.mjs: closedDoorBlocksGlow — прогнан, OK (closedDelta <= 3).
• AC2 (открытие в течение одного render tick, без сохранения конфига). Доказано: demo/smoke_glow.mjs меняет только c.hass.states (без _cfgEpoch++/_glowClipCache.clear() вручную) и получает изменённые пиксели после updateComplete + двух rAF — то есть проверяет сам факт автоматической инвалидации кэша по сигнатуре, а не подложенную вручную очистку. OK.
• AC3 (current_position=50 → центрированный вырез вдвое короче, символ получает тот же amount). Доказано unit: openingLightApertureLength(80, 0.5) === 40 (test/logic.test.mjs); openingAmount('gate','open',false,50) === 0.5. Единый источник: и _lightBarriers() (src/houseplan-card.ts:12332-12341, _openingAmt), и видимый символ партиционного проёма (src/space-render.ts:508-514), и видимый символ обычного проёма (src/houseplan-card.ts:12392), и изометрия (строка 8753) читают ровно один и тот же _openingAmt/openingAmount() с одним и тем же entity.attributes.current_position. Проверено чтением всех вызовов (grep _openingAmt( и openingAmount(), дублирующего вычисления процента нет — «одно число, один источник» выполняется. smoke_glow.mjs: partialDoorNarrowsGlow — прогнан, OK (0 < halfWidth < openWidth).
• AC4 (invert меняет известное значение, не меняет outage-fallback). Доказано unit-матрицей test/logic.test.mjs: openingAmount('gate','unavailable',true,25) === 1 — инверсия не трогает fallback, потому что в коде (src/logic.ts:317-319) ветка unavailable/unknown возвращает результат ДО применения invert. Тест «умеет падать»: если убрать ранний return, значение стало бы 0, а не 1.
• AC5 (ворота как двери; passage всегда прозрачен; окно/неизвестный тип/наружный проём — всегда непрозрачны). Классификатор isInteriorLightOpeningType не менялся этим диффом — проверено чтением, регресс невозможен без изменения этой функции. openingAmount('passage', …) === 1 всегда — юнит подтверждает.
• AC6 (тот же контракт full/zero/partial для partition). Доказано test/physical-geometry.test.mjs: новый тест scalePartitionOpeningCut (центр сохраняется, depth/hostId неизменны, немутирующая функция) плюс physicalBodyParts full/half/closed через pointInOpaquePlanBody. smoke_partition_openings.mjs — прогнан, OK (не специфичен под Glow, но подтверждает отсутствие регрессии в общей семантике partition-openings).
• AC7 (источник внутри закрытого проёма полностью гаснет). Partition-случай — юнит (см. AC6). Контурный случай — см. Low L1 выше: проверено чтением общего fail-dark пути, дефекта не нашёл, но отдельного нового теста для этой ветки нет.
• AC8 (кэш переиспользуется при постороннем HA-апдейте, разный amount — новый ключ, LRU bounded). Структура ключа проверена чтением (fingerprint = contentFingerprint([geometryFingerprint, openingStateSignature]), cacheKey = space.id|fingerprint, lruWrite(this._lightBarrierPool, cacheKey, entry, 8) — лимит 8 не менялся) плюс существующий текстовый unit (test/golden-matrix.test.mjs: «a light source paints exactly one region…» сверяет буквальный текст сборки fingerprint — тот же приём, что уже использовался в проекте для _cfgEpoch). Поведенчески: demo/smoke_glow.mjs's setDoorPosition меняет только состояние без явной очистки кэшей — рендер обновляется, то есть сигнатура действительно входит в реальный cache key, а не только в текст. recut-путь (переиспользование стеновой геометрии) сверяет sharedFingerprint === geometryFingerprint (только геометрия, без состояния дверей) — прочитал: _wallUnionGeometry()'s sourceFingerprint считается из [this._curSpaceCfg, this._cellCm, this._gridPitch], то есть идентичен geometryFingerprint и не зависит от состояния дверей — смена состояния двери не форсирует пересборку общей wall-union геометрии, только пересчёт вырезов поверх неё. Корректно.
• AC9 (перф-бюджет на large-house). Вне скоупа код-ревью по собственной формулировке ТЗ — доказательство «exact-SHA CI performance smoke перед бетой». Не проверял.
• AC10 (golden-сцена closed/open/50%). Сценарий lighting-opaque-glow-two-doorways-dark расширен третьей дверью с current_position: 50 и второй с закрытым cover — структурно верно и соответствует AC. Baseline не обновлён — см. «Известный пробел» ниже.

Известный пробел (не блокирует, не Medium)

npm run golden:verify на этом SHA даёт 1 different из 80 сцен: lighting-opaque-glow-two-doorways-dark. Причина не в коде: сценарий (demo/golden/matrix.mjs) теперь рисует другую геометрию (2 двери → 3, изменена позиция второй), а PNG-эталон в demo/golden/baselines/lighting-opaque-glow-two-doorways-dark.png не обновлён. Диф git diff origin/dev...HEAD --stat -- demo/golden/baselines пуст — эталон действительно не менялся.

Это не находка, а корректное следование процессу: правило §13/AGENTS.md запрещает принимать golden-эталон иначе как npm run golden:accept -- --reviewed по полному Linux CI-артефакту, и автор явно зафиксировал это в хендоффе («baseline локально не обновлялся… эталон должен принять Linux CI»). Приложенный AC10 сам называет доказательством «reviewed Linux golden artefact», а не локальный прогон код-ревью. Требовать здесь зелёный golden:verify значило бы просить автора нарушить §13. Фиксирую как открытый пункт для пре-релизного гейта (Validate/CI на dev), не как дефект этой задачи.

Унаследовано / контекст ревью ТЗ

Ревью ТЗ уже зелёное (docs/reviews/SPEC-REVIEW-20-r1.md, комментарий 2026-08-28T19:07:32Z, High 0 / Medium 0). Спека не менялась после этого вердикта (единственный коммит, трогающий docs/specs/020-glow-open-door-spill.md, — 3fa98a09, который по топологии истории идёт ДО вердикта ревью ТЗ). Контракт спеки не пересматривал повторно, кроме сверки с фактическим кодом построчно по AC — раздел «Что проверено и корректно» выше.

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

• Performance smoke / large-house budget (AC9) — по формулировке AC доказывается exact-SHA CI перед бетой, не код-ревью; локального перф-фикстур-прогона не делал.
• python -m pytest tests_backend — диф не трогает custom_components/**/*.py.
• node scripts/model-invariants.mjs — диф не меняет персистентную геометрию/схему (обоснование выше); нет пользовательского export/config для конкретной конфигурации.
• Полный browser-smoke матрикс (200 файлов) — не запускал все, диф не задевает всё; прогнал ровно те 10, что smoke-select.mjs пометил прямым совпадением.
• Приёмка golden-эталона — вне полномочий код-ревью и вне возможностей локальной машины без CI-артефакта; см. «Известный пробел».
• Ручное тестирование в браузере — не проводилось (в цикле его нет); AC поддержаны автотестами/смоками, которые я прогнал сам и для ключевых — перечитал, что они умеют падать (openingAmount invert-fallback, cache-signature через отсутствие ручной очистки в смоке).

Вердикт

Зелёный. Реализация соответствует контракту ТЗ, единый источник числа amount подтверждён по всем потребителям (символ/Glow/изометрия), кэш-инвалидация проверена и поведенчески, и по формуле ключа, fail-dark для источника внутри закрытого проёма верен по конструкции для обоих типов стен. Единственная Low-находка (недостающий прямой тест для контурного варианта AC7) не блокирует и не требует правки в этом заходе. Незакрытый golden diff — ожидаемый и корректно задокументированный пункт пре-релизного гейта, не дефект этой задачи.