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

CODE-REVIEW-244-r1

• Issue: #244 — восстановление маркеров с мёртвой ссылкой на пространство
• Кандидат: a09338f (ветка issue/244-orphan-space-references)
• ТЗ: docs/specs/244-orphan-space-references.md, утверждено SPEC-REVIEW-244-r2 (зелёное)
• Заход: код-ревью r1, блокирующих циклов израсходовано 0/4
• Диапазон: git diff origin/dev...HEAD (origin/dev = b49983f)

Скоуп

Normal-трек (метки bug, P2, без small/trivial). Диапазон трогает: новый чистый helper src/space-reference-repair.ts (Optimize reference-repair pass), src/space-deletion.ts (preflight-кандидат удаления пространства), интеграцию в src/plan-optimizer.ts (PLAN_MODEL_VERSION 6→7), редактор карточки (src/editor.ts + новый src/card-editor-validation.ts), backend custom_components/houseplan/websocket_api.py (новая команда houseplan/space/delete) и import_export.py (_repair_target_space_refs), плюс тесты (unit/backend/smoke/golden/mutation) и документацию. 40 файлов, +3193/-858.

Полный разбор (не по дельте): это первый заход код-ревью по этапу (спек-ревью — другой этап, его бюджет не пересекается с код-ревью, #227/§10.4).

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

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	PASS
Unit	npm test	1112/1112 PASS, 0 skipped (на Linux docs-accept.test.mjs не падает — заявленные автором 3 FAIL/1 skipped специфичны для Windows path-separator, #246)
Build + bundle sync	npm run build && cmp ×3	PASS, все три копии побайтово совпадают, SHA-256 7db489bf…f2203 — совпадает с заявленным в хендоффе
Docs fingerprint	node scripts/check-docs.mjs (diff трогает src/**)	PASS
Backend	python -m pytest tests_backend -q (поднял pytest-homeassistant-custom-component + home-assistant-frontend==20250109.2 в сессии ревьюера — на Linux, полный HA-харнесс)	350 passed, 1 error — test_ha_upload.py::test_upload_ok, воспроизведён и на чистом origin/dev (тот же _run_safe_shutdown_loop teardown-артефакт), не связан с диффом
node scripts/smoke-select.mjs --base origin/dev --head HEAD	—	19 прямых совпадений, 29 слабых связей (вывод ниже)
Целевой smoke по AC	node demo/smoke_orphan_space_references.mjs	FAIL — см. находку H1
Смежный smoke (прямое совпадение на _deleteSpace)	node demo/smoke_optional_space_model.mjs	FAIL, 5/9 — см. находку H2, регрессия относительно origin/dev (проверено: тот же smoke зелёный на b49983f)
Смежный smoke (прямое совпадение на Optimize-диалог)	node demo/smoke_optimize_geometry_preflight.mjs	PASS
Смежный smoke (прямое совпадение на _formData/_valueChanged)	node demo/smoke_fixed_floor.mjs	PASS
npm run golden:verify, полный smoke-набор (167), mutation-gate.mjs (backend-мутанты), performance	—	не прогонялись целиком — см. «Чего не проверял»

Решение по каждой строке smoke-select

Прямое совпадение (19) — прогнаны 4 (см. таблицу выше: smoke_orphan_space_references, smoke_optional_space_model, smoke_optimize_geometry_preflight, smoke_fixed_floor), это единственные, где символ прямо принадлежит изменённой логике удаления/Optimize/редактора, а не общей инфраструктуре записи. Остальные 15 (smoke_linked_virtual_light, smoke_save_race, smoke_virtual_light_toggle, smoke_audit_1490, smoke_bg_color, smoke_config_writer, smoke_device_preview_parity, smoke_dialog_footer_width, smoke_general_settings, smoke_layout_sync, smoke_plan_upload_race, smoke_climate_once, smoke_editor_tabs, smoke_infinite_canvas, smoke_ws_resilience) не прогнаны: совпадение только по общей плумбингу (_cfgRev, _layoutRev, _config, _persistLayout, _reloadConfigOnly, buildDevices, Layout), который #244 не переопределяет — эти символы читаются, а не переписываются новым кодом. Риск ложноотрицательного результата счёл низким, но именно эта экономия и не поймала находки этого документа (H1/H2 нашлись на прямых совпадениях, которые я всё-таки прогнал) — сигнал в пользу того, что общий плумбинг здесь надёжен, а не наоборот.

Слабая связь (29) — не прогнаны. Все совпадения по одному распространённому имени (_config, _spaceDialog, _cfgRev), диалоги пространства/цвета/тегов не меняли контракт в этом диффе.

Находки

H1 (High). Именованный в АС смок demo/smoke_orphan_space_references.mjs красный

node demo/smoke_orphan_space_references.mjs:

"deleteExplainsBlockerWithoutConfirmOrWrite": false
FAILED (1): deleteExplainsBlockerWithoutConfirmOrWrite: expected true, got false

Этот файл — единственная браузерная улика для AC1, AC7, AC9, AC10, AC11 (спек §15). Причина красного: сценарий делает Optimize-Apply (маркер orphan детачится, marker.space становится undefined) → Undo (мок возвращает исходную пару, marker.space снова 'gone') → затем открывает диалог пространства 'home' и вызывает _deleteSpace(). Но у маркера orphan в этот момент space === 'gone', а не 'home' — он никогда не ссылался на удаляемое 'home'. collectSpaceMarkerDependencies(serverCfg, layout, 'home') честно возвращает count: 0, код идёт в confirm() (что должно быть nativeConfirmCalls === 0 по тесту) и затем в hass.callWS('houseplan/space/delete', …), который мок безусловно бросает space_in_use — попадает в другую (catch) ветку, а не в ожидаемый preflight-блокер.

Сам механизм блокировки удаления работает верно — проверено отдельно, воспроизведением на чистой фикстуре (маркер реально ссылается на удаляемое пространство):

node /tmp/smoke_delete_isolated.mjs
{ "blockerText": "This space is still used by 1 device(s). …", "nativeConfirmCalls": 0,
  "calls": [], "deleteBlockers": 1 }

Это подтверждено и space-deletion.test.mjs, и test_ha_websocket.py (unit/backend зелёные). Дефект — в фикстуре смока (несвязанные 'gone'/'home'), не в продуктовом коде. Но: (а) это именно тот артефакт, который спек называет доказательством пяти AC разом; (б) хендофф прямо говорит, что браузерные smoke в implementation-цикле не запускались, хотя demo/smoke_orphan_space_references.mjs прямо назван в AC1/AC7/AC9/AC10/AC11 и AGENTS.md требует прогонять AC-смоки локально перед S7-code-review; локальный прогон занял бы секунды и поймал бы фикстуру до подачи на ревью. «Verified» по этим пяти AC без названной команды и результата не является доказательством — здесь команда есть, и она красная.

Что нужно: починить фикстуру demo/smoke_orphan_space_references.mjs — дать _deleteSpace блокатор, реально ссылающийся на удаляемое пространство (например, отдельный второй маркер с space: 'home', не участвующий в Optimize-цикле), и убедиться, что смок целиком зелёный.

H2 (High). Регрессия контракта #113: последнее занятое пространство больше не удаляется

node demo/smoke_optional_space_model.mjs (не тронут диффом, прямое совпадение по _deleteSpace):

"deleteLastRendersEmpty": false, "deleteLastClearsSelection": false,
"deleteLastAbortsEditorState": false, "deleteLastCancelsPendingWrite": false,
"createFlowSurvivesEmpty": false
FAILED (5)

На origin/dev (b49983f, тот же smoke, тот же билд-процесс) — зелёный:

node demo/smoke_optional_space_model.mjs   # на чистом origin/dev
OK

Т.е. это не флейк среды, а воспроизводимая регрессия, внесённая именно этим диффом.

Причина: смок вызывает _deleteSpace() на единственном оставшемся пространстве demo-фикстуры, у которого есть реальные маркеры (обычные demo-устройства). Новый preflight (collectSpaceMarkerDependencies, §10 спека, решение владельца по Q2 — «заблокировать удаление… показать число зависимых маркеров») находит зависимости и безусловно блокирует удаление — без исключения для случая «это единственное оставшееся пространство». confirm() не вызывается, запись не идёт — ни один из пяти шагов теста не выполняется, потому что диалог остаётся открытым с блокером вместо перехода в пустое состояние.

До этого диффа (docs-комментарий смока: «#113: deleting the final space and receiving an empty plan over WS must be a supported lifecycle state») удаление последнего населённого пространства было гарантированным способом получить состояние «Пусто» и начать заново. Спек §10 защищает явно только один частный случай — «Удаление последнего пустого пространства сохраняет действующий контракт #111» — молча оставляя населённый последний случай без какого-либо пути назад: у пользователя с одним пространством и хотя бы одним устройством нет ни другого пространства, куда перенести маркер, ни кнопки «удалить всё равно». Это деградация ранее работавшего, покрытого тестом сценария (#113), не названная ни в ТЗ как сознательно отменяемая, ни в docs/CHANGELOG*.md/CONFIG-COMPATIBILITY.md (там документируется только общее правило блокировки, без слова про последнее пространство). Она прошла оба раунда ревью ТЗ незамеченной.

Это ровно тот класс: «правка… способна сломать AC/контракт, который предыдущий раунд признал выполненным» — деградация смежного сценария при полностью выполненных AC самой задачи.

Что нужно (варианты для автора/владельца, не мой выбор):

1. Для единственного оставшегося пространства не блокировать, а применить тот же safe-detach, что Optimize уже делает при отсутствии сигнатуры/Area (Q1-семантика) — маркеры теряют только мёртвую привязку, пространство всё равно удаляется, состояние «Пусто» достижимо как раньше; либо
2. Явное продуктовое решение владельца: контракт #113 сознательно сужается только до пустых пространств, задокументировать это в USER-GUIDE.md/CHANGELOG и обновить demo/smoke_optional_space_model.mjs, чтобы он не утверждал более неверное поведение.

Оставлять как есть (спорный молчаливый выбор + красный регрессионный тест) нельзя.

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

• AC2–AC6 (граф ссылок Optimize) — test/space-reference-repair.test.mjs, 8 тестов, прочитаны построчно: exact signature (обрезанный stem >35, коллизия двух кандидатов, валидный оригинал блокирует ремап), Area-remap с точным совпадением-ровно-одна-комната, detach только marker.space+позиции с сохранением остальных полей маркера (binding, icon, pdfs), room_id/vacuum.segment_map/rl_<room> синхронно, removed-tombstone принимает только доказуемую сигнатуру. Тесты умеют падать — проверено запуском (npm test, все зелёные) и чтением: логика в src/space-reference-repair.ts использует Map/Set с точными критериями (reversibleStem, spaceSignatures.get(oldId)?.length === 1), не эвристику.
• AC12 (immutability/idempotence) — оба unit-файла явно проверяют, что входной config/layout не мутируется (assert.equal(input.markers[0].space, 'gone', 'config input is immutable')), повторный прогон changed:false; plan-optimizer.test.mjs добавляет «reference repair is part of exact Optimize candidate and bumps model version» — подтверждено, что repair выполняется до проверки model_version (src/plan-optimizer.ts:380 вызывает repairSpaceReferences первой строкой), т.е. не пропускается при уже актуальной версии.
• AC13 (линейность) — прочитано: repairSpaceReferences строит все индексы (spaceSignatures, roomSignaturesBySpace, roomsByArea, activeMarkerIds) один раз, дальше только Map/Set lookup на маркер/layout-запись — O(n). Синтетический тест на 120 пространств × 2400 маркеров проходит быстро внутри npm test (общее время прогона 1112 тестов — 5.6 с).
• AC8 (импорт одного пространства) — _repair_target_space_refs в import_export.py прочитан и прогнан (test_issue_244_space_import_repairs_existing_target_refs_with_exact_map, ..._does_not_repair_target_while_source_exists) — оба PASS изолированно и в полном прогоне с настоящим HA. Ремап marker.space/room_id/vacuum.segment_map/layout[*].s/rl_* по точному id_map этого импорта, без эвристики; при существующем old_space_id target не трогается — подтверждено.
• AC9/AC10 (backend delete) — test_issue_244_space_delete_is_authoritative_and_revision_guarded прогнан с полным HA-харнессом (PASS): блокер оставляет обе revision без изменений, после устранения зависимости (tombstone) удаление проходит под revision guard, снимает только placement-поля с tombstone, оставляет его name. _space_delete_candidate/_commit_import_pair переиспользуют существующий crash-safe pending/rollback механизм Optimize/импорта — код прочитан, семантика (retry-once → rollback-intent) идентична уже принятому паттерну.
• AC11 (default_floor) — card-editor-validation.test.mjs (PASS) плюс smoke-проверка editorKeepsRawInvalidDefault (PASS в общем прогоне smoke, несмотря на H1/H2 в других ассершенах того же файла) подтверждают: raw id сохраняется, alert для RU/EN формируется только после авторитетной загрузки. Логика «несвязанное поле не стирает raw id» проверена чтением (_formData — полный {...config}, оба ha-form получают его целиком, _valueChanged мержит ev.detail.value в текущий _config) — отдельного browser-теста именно на этот сценарий нет (см. «Чего не проверял»).
• AC14 — check-docs.mjs зелёный, три копии бандла побайтово идентичны, RU/EN changelog и USER-GUIDE.*/CONFIG-COMPATIBILITY.md обновлены по существу (не только версия), скриншот- fingerprint принят коммитом ecb55d1 со ссылкой на настоящий прогон workflow (не выдумана).
• i18n — все новые ключи (space.delete_blocked, editor.default_floor_missing, gs.optimize_references, gs.optimize_reference_warning, gs.optimize_reference_more, backup.repaired_target_refs) присутствуют параллельно в en.json/ru.json, текст совпадает с тем, что смок и golden-харнесс проверяют побуквенно.
• Трейлеры/классы файлов — коммиты несут Issue: #244, User-Visible: yes с правками в оба changelog в соответствующем коммите; dist/**/custom_components/.../frontend/** (класс D) идут вместе с исходниками в том же коммите реализации — не отдельным «само по себе» коммитом.

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

• npm run golden:verify / golden:accept — не прогонял: новые сценарии (optimize-orphan-references-*, card-editor-invalid-default-floor-*) добавлены в матрицу и проверены golden-matrix.test.mjs (структурно, PASS), но реальный визуальный рендер не снимался — это предрелizный гейт по правилу владельца (§8), эталоны принимаются только на полном Linux CI артефакте.
• Полный smoke-набор (167 файлов) — прогнаны только 4 прямых совпадения плюс целевой AC-смок; остальные 14 прямых и 29 слабых — не прогонялись, решение по каждой строке дано выше.
• scripts/mutation-gate.mjs для трёх новых frontend-мутантов (orphan-space-detach-disabled, orphan-space-ambiguous-signature-guessed, orphan-space-area-keeps-stale-position) — не прогонял сам мутационный прогон (полный прогон гейта требует backend-мутанты и упал в моей сессии на отсутствии backend-харнесса до его установки; после установки HA не переповторял весь mutation-gate из-за времени). Прочитаны patches/guards — синтаксически и по смыслу соответствуют трём рискам из спека §16.
• Backend-mutation-мутанты (не относящиеся к #244) и performance-профили — не запускал, не названы в AC #244 как влияющие.
• Браузерный тест на «несвязанное редактирование другого поля ha-form не стирает raw default_floor» — только чтением кода (см. AC11 выше), отдельного smoke/golden-шага именно на этот пограничный случай нет. Не блокирую отдельно — логика простая и однозначная, но фиксирую как пробел покрытия.
• docs/images/screenshots.json PNG-содержимое — не скачивал артефакт workflow, доверился тому, что imageSha256 не изменился (0 PNG) и ссылка на прогон настоящая (не выдуманная).

Итог

Продуктовый диагноз, контракт репаунда ссылок и большинство AC подтверждены чтением и исполнением тестов — работа сделана добросовестно и по существу. Но два независимых прогона браузерных smoke, которые сам автор не запустил перед подачей на ревью, оказались красными: один — из-за дефекта фикстуры в named AC-evidence файле, другой — из-за настоящей регрессии ранее работавшего контракта (#113) без единого слова об этом в ТЗ/changelog. Оба блокируют.

Вердикт: красный · заход r1 · блокирующих циклов 0/4 · High: 2 · Medium: 0 → в задаче

Документ: docs/reviews/CODE-REVIEW-244-r1.md