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

CODE-REVIEW-117-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/117
• ТЗ: docs/specs/117-registryless-opening-entity.md, зелёное docs/reviews/SPEC-REVIEW-117-r1.md (High 0, Medium 0)
• Диапазон: git log --oneline origin/dev..HEAD — три коммита:
  • 03cca97 fix: support registryless opening entities (Issue: #117, User-Visible: yes)
  • 3bd80ff docs: review document for #117 (Issue: #117, User-Visible: no)
  • cc22988 docs: specify registryless opening entities (Issue: #117, User-Visible: no)
• Роль: ревьюер кода (не автор), этап S7-code-review, цикл r1/4

Скоуп ревью

Диф (git diff origin/dev...HEAD --stat, 16 файлов):

Класс	Файлы
A (продукт)	src/ha-binding-status.ts
B (гейты/инструменты)	demo/smoke_registryless_opening.mjs (новый), scripts/mutation-gate.mjs, test/ha-binding-status.test.mjs, test/render-device-snapshot.test.mjs
C (документация)	docs/ARCHITECTURE.md, docs/CHANGELOG.md, docs/CHANGELOG.ru.md, docs/TESTING.md, docs/USER-GUIDE.ru.md, docs/reviews/SPEC-REVIEW-117-r1.md, docs/specs/117-registryless-opening-entity.md, docs/specs/README.md
D (сгенерированное)	dist/houseplan-card.js, custom_components/houseplan/frontend/houseplan-card.js, demo/srv/assets/houseplan-card.js

Продуктовая правка — ровно одна логическая точка: renderOpeningEntityAvailable() в src/ha-binding-status.ts:533-545 больше не требует projectedHass.entities[entityId] одновременно с projectedHass.states[entityId]; сохранена проверка только наличия state в замороженной активной проекции. _openingAmt() и _renderOpeningLocks() в src/houseplan-card.ts не менялись — оба уже шли через единственную точку _renderOpeningEntityAvailable(), поэтому фикс закрывает contact и lock одновременно без риска рассинхронизации.

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

Гейты, которые прогнал я лично (не со слов автора):

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный, без вывода
Unit	npm test	804/804 pass
Build + сверка бандлов	npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js && cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js	зелёный; sha256sum всех трёх копий совпадает: 73fffed183e23ab015cb0dd43ee0b3d2b277822bdd2f44813af6a1051398c881
Целевой smoke (AC1/2/3/7/8/9)	node demo/smoke_registryless_opening.mjs	OK, все 13 подпроверок true
Регрессия opening-биндинга	node demo/smoke_opening_binding.mjs	OK, все 15 подпроверок true
Регрессия lock action	node demo/smoke_lock_action.mjs	OK, все 8 подпроверок true
Регрессия lock invariant (SCOPE.md)	node demo/smoke_lock_invariant.mjs	OK, все 7 подпроверок true
Mutation-guard	node scripts/mutation-gate.mjs --id=registryless-opening-requires-registry-row	поймано 1 из 1 — мутант (возврат .entities[entityId]) красит smoke, чистый прогон зелёный

Дополнительно — доказательство «тест умеет падать» для unit-покрытия, не только для smoke (§2.7 требует это явно): временно вернул проверку !!projectedHass?.entities?.[entityId] в src/ha-binding-status.ts, пересобрал test-build (npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs) и прогнал node --test test/ha-binding-status.test.mjs test/render-device-snapshot.test.mjs — результат 18 pass / 1 fail, упал именно новый тест 'opening render availability trusts one frozen active projection' (assert на binary_sensor.yaml_only === true). После проверки восстановил src/ha-binding-status.ts из git, пересобрал test-build и перепрогнал npm test — снова 804/804, дерево чистое (git status --short пусто, npx tsc -p tsconfig.test.json — сгенерированный test-build/ не версионируется).

Что не прогонял и почему (соразмерность гейтов, PROCESS.md §8):

• Полный набор из 127 browser-смоков — diff задевает ровно одну точку (renderOpeningEntityAvailable) и один потребитель (opening contact/lock); прогнал новый целевой smoke плюс три регрессионных, напрямую покрывающих opening-биндинг и lock-security — этого достаточно для поверхности изменения, полный прогон здесь не добавил бы сигнала.
• npm run golden:verify — не прогонял. Обоснование не «со слов автора», а по коду: space-render.ts/logic.ts/любой геометрический или стилевой путь не тронуты; единственная правка убирает одно &&-условие, которое для уже зарегистрированных сущностей (у них entities[eid] и states[eid] совпадают одновременно) не меняет результат вообще — registry-backed painted frame буквально не может стать другим. Влияет только на entity без registry row, которых ни в одном golden-сценарии нет (не заведены YAML-only fixtures). Golden-эталоны диф не трогает.
• python -m pytest tests_backend -q — не прогонял, диф не касается custom_components/houseplan/**/*.py (нет таких файлов в списке изменений).
• Performance-профили — не прогонял. ТЗ §14 явно заявляет «нет», и правка добавляет один and-член в уже читаемый на каждом кадре boolean — не новый проход по данным, не новая структура.

Находки

Находок уровня High и Medium нет.

Low не завожу: код, тесты и документация построены по написанному в ТЗ без отклонений, я не нашёл ни одного места, которое стоило бы поправить или снять с запиской.

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

• AC1 (registry-less live contact меняет presentation) — доказано smoke: closedContactControlsPresentation (closed) и stateTickSwapsOneAtomicFrame (open) на binary_sensor.hp117_yaml_contact без registry row (card.hass.entities[...] == null подтверждено смоком).
• AC2 (registry-less live lock badge) — доказано smoke: yamlLockBadgeRendersLocked, затем .oplock.unlocked после смены состояния, unknownKeepsExistingTypeSemantics для unknown.
• AC3 (frame — только immutable projection, не raw hass) — доказано и чтением, и исполнением: _renderOpeningEntityAvailable (src/houseplan-card.ts:16283) — однострочная делегация в renderOpeningEntityAvailable(this._renderPlanHass, eid), this.hass не упоминается; source-contract тест test/render-device-snapshot.test.mjs проверяет это регексом (assert.doesNotMatch(..., /this\.hass\b/)) и подтверждает через methodBody. Мутационный гейт и мой ручной revert показывают, что тест красится при регрессии — не косметическая проверка.
• AC4 (active registry entity — прежнее поведение) — не могло измениться логически (см. «Что не прогонял», golden) и подтверждено smoke-регрессией smoke_opening_binding.mjs (exactOpeningReferencesStayActive и другие).
• AC5 (disabled/orphan/missing остаются unavailable) — доказано unit (test/ha-binding-status.test.mjs, ветки lock.disabled_entity, lock.disabled_parent, lock.orphan, lock.missing — все false) и smoke (explicitDisabledRowsRemoveStaleStates, включая ожидание паузы на дебаунс реестра 220ms перед проверкой). Логика опирается на уже существующий (не изменённый этим дифом) activeRegistryHass() (src/ha-binding-status.ts:323-354) — прочитано построчно: state registry-less сущности проходит проекцию, только когда для неё нет соответствующей записи entities[eid] вовсе (значит проверки disabled не применяются), либо запись есть и явно не отключена.
• AC6 (limited-registry live exact entity работает) — доказано unit (limitedFrame в тесте, authoritative: false).
• AC7 (marker tombstone не блокирует opening reference) — доказано unit (markerTombstoneIsNotAnInput) и smoke (markerTombstonesDoNotBlockOpening, который дополнительно контрастирует с !card._planEntityAvailable(...) — показывает, что общий marker-путь по-прежнему блокируется, а opening-путь — нет, то есть сужение скоупа из ТЗ §4 не создало разрыва).
• AC8 (lock security/unlock confirmation не меняются) — подтверждено чтением: _lockAction() (src/houseplan-card.ts:16411-16424) не входит в диф, по-прежнему проверяет live _openingEntityAvailable() перед callService, требует confirm() только для unlock. Регрессия подтверждена исполнением: smoke_lock_action.mjs, smoke_lock_invariant.mjs зелёные, плюс новый smoke явно проверяет planOpeningAndBadgeNeverActuate (тап по проёму/badge не вызывает callService) и explicitInfoActionStillWorks (только явное действие в открытой info-карточке вызывает lock.unlock). Инвариант SCOPE.md «The lock invariant, stated precisely» не ослаблен.
• AC9 (state update не пересобирает geometry/config) — доказано smoke: stateTickDoesNotRebuildGeometryOrConfig сравнивает _physicalBodiesCache, _cfgEpoch и сериализованный _serverCfg до/после тика состояния.
• AC10 (существующие opening golden/interactions без регресса) — golden baseline в дифе не тронут; логическое обоснование неизменности registry-backed пути дано выше (AC4); smoke_opening_binding.mjs зелёный подтверждает поведенческую регрессию отдельно от golden.
• Трейлеры и changelog: все три коммита несут терминальные Issue: #117 и User-Visible: yes|no; коммит с User-Visible: yes (03cca97) правит docs/CHANGELOG.md и docs/CHANGELOG.ru.md в том же коммите (проверено git show --stat 03cca97, оба файла присутствуют).
• Документация: docs/USER-GUIDE.ru.md описывает новое поведение словами, согласующимися с уже принятой терминологией раздела («Контактный датчик», «замок»); docs/ARCHITECTURE.md фиксирует правило проекции; docs/TESTING.md добавляет пункт с явным списком [auto: ...], все перечисленные файлы существуют и были прогнаны выше.
• Соответствие ТЗ и SCOPE.md: правка не расширяет скоуп (§4 «не входит» дословно соблюдён — picker, миграция, marker lifecycle, generic registry-less для прочих marker-биндингов, geometry не тронуты), лежит внутри уже закрытых J4/J6, лок-инвариант не ослаблен.

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

• Полный набор из 127 browser-smoke (см. обоснование сужения выше) — предрелизный гейт, не гейт ревью.
• npm run golden:verify — обоснование дано выше (логическая неизменность registry-backed пути плюс отсутствие изменений в geometry/render-стилях).
• python -m pytest tests_backend -q — Python не тронут этим дифом.
• Performance-профили — ТЗ явно исключает влияние, изменение не добавляет новый проход по кадру.
• Реальную установку Home Assistant с живой YAML-сущностью без unique_id — вне возможностей этого ревью; демо-стенд (demo/srv/demo.html) и его фейковый hass/registry являются каноническим суррогатом по AGENTS.md/docs/DEVELOPMENT.md, и я прогнал его лично, а не со слов автора.
• Историю ветки/ребейз на dev — вне обязанностей код-ревью; это забота конвейера при слиянии (риск отмечен автором в хендоффе).

Вердикт

Зелёный. High: 0, Medium: 0. Каждый AC либо доказан автотестом, который я лично прогнал и для которого лично подтвердил способность падать (unit — ручным откатом фикса, smoke — mutation-гейтом), либо разобран чтением кода с явной пометкой выше. Регрессионные lock-security смоки и SCOPE.md-инвариант подтверждены исполнением, а не только чтением ТЗ. Продуктовый диф — одна точка (renderOpeningEntityAvailable), в точности соответствующая описанию и границам ТЗ; трейлеры, changelog (RU+EN) и три копии бандла в порядке.