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

CODE-REVIEW-648-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/648 — «Sections: вертикальный resize карточки и container-owned высота плана»
• Этап: S7-code-review (код-ревью, PROCESS.md §2.7)
• Трек: полный (P2, см. SPEC-REVIEW-648-r1.md)
• Материал: git log --oneline origin/dev..HEAD и git diff origin/dev...HEAD; вершина ветки — b7fb7cf7e7bce13a44ef0e1af3b97541ddb0dffa, база — origin/dev = f68878cc44b818b6cfbdb3866302e6febaab2445. Три коммита: 7f48e690 (feat, User-Visible: yes), 102b2ed7 (test, User-Visible: no), b7fb7cf7 (test, User-Visible: no).
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (первый раунд код-ревью; предыдущий раунд — ревью ТЗ, docs/reviews/SPEC-REVIEW-648-r1.md, зелёный)
• Роль: ревьюер кода (не автор)

Скоуп ревью

Диапазон меняет:

• src/houseplan-card.ts — новое публичное реактивное свойство layout (HA-сигнал), геттер _containerOwnedHeight (panelHost || layout === 'grid'), getGridOptions() → { columns: 'full', rows: 10, min_rows: 6 }, замена panelHost на _containerOwnedHeight в четырёх местах расчёта высоты сцены (mode-transition target, measuredCardHeaderHeight, settleSoftStageLayout, inline style="height:...");
• src/boot-soft-layout.ts — переименование параметра panelHost → containerOwnedHeight в measuredCardHeaderHeight/settleSoftStageLayout (поведение не меняется, кроме нового источника true);
• src/styles/base.styles.ts — CSS-селекторы :host([layout="grid"]) добавлены рядом с существующими :host([panel-host]);
• demo/smoke_sections_resize.mjs (новый, 221 строка) — browser smoke; demo/smoke_houseplan_panel.mjs — соседний regression-oracle (AC7); test/houseplan-panel.test.mjs — обновлён текстовый oracle контракта #486;
• scripts/mutation-registry.mjs (4 новых мутанта), scripts/smoke-links.mjs (регистрация smoke по символам);
• документация: docs/ARCHITECTURE.md, docs/CHANGELOG.md, docs/CHANGELOG.ru.md, docs/STATUS-FEATURES.md, docs/TESTING.md, docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md;
• dist/**, custom_components/houseplan/frontend/** (класс D, пересобранный бандл — сверено побайтно, см. «Как проверялось» п.2).

Первый вопрос — какую строку docs/SCOPE.md задача обслуживает: прямого Core-job нет, это инфраструктурная UX-правка поверхности, на которой живут J1–J7 для персоны Home admin (Sections — основной тип dashboard в HA, задача не расширяет функциональность плана и не входит в «Out of scope»). Ровно так же было принято ревьюером ТЗ в SPEC-REVIEW-648-r1.md — конфликта со SCOPE.md нет.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, docs/process/REVIEWER.md, тело issue #648 (раздел ## ТЗ, K1–K12, AC1–AC10), и docs/reviews/SPEC-REVIEW-648-r1.md (единственный предыдущий раунд — ревью ТЗ, зелёный, без Medium/High).
2. Прочитан полный git diff origin/dev...HEAD по каждому изменённому файлу src/**, demo/smoke_sections_resize.mjs, demo/smoke_houseplan_panel.mjs, test/houseplan-panel.test.mjs, scripts/mutation-registry.mjs, scripts/smoke-links.mjs, всех изменённых docs/*.md.
3. Пересобрал бандл (npm run build → npm run bundle:sync) на материале — git status после сборки чист: committed dist/** и custom_components/houseplan/frontend/** побайтно совпадают с пересобранными, обновлять было нечего.
4. Прогнаны гейты (список — «Что прогнал» ниже); дешёвые (typecheck внутри build, npm test, npm run build) уже подтверждены зелёным Validate на этом точном SHA (см. ссылку в задании), их не переганивал; check-docs.mjs, no-new-any.mjs, no-new-private-writes.mjs, bundle:budget прогнал сам, так как диф трогает src/**, а инструкция не считает их покрытыми чужим прогоном за меня.
5. Прогнал сам smoke_sections_resize.mjs и smoke_houseplan_panel.mjs (браузерные смоки Validate не гоняет вне heavy-условий — они не в материале, который мне назвали зелёным). Оба зелёные.
6. Через node scripts/mutation-registry.mjs --id=<id> прогнал все четыре новых мутанта задачи (sections-grid-falls-back-to-viewport-height, sections-editor-transition-uses-window-height, sections-grid-drops-stage-flex-chain, sections-resize-drops-stage-refit-observer) — каждый краснит именно smoke_sections_resize.mjs, репозиторий чист после каждого прогона (скрипт сам возвращает мутант и пересобирает). Это заполняет колонку «чем краснеет» для защитных AC2/AC4/AC5/AC7/AC8 предметно, а не по заявлению автора.
7. Прогнал node scripts/smoke-select.mjs --base f68878cc4... --head b7fb7cf7e... — «прямое совпадение» вернуло 19 смоков, включая оба названных в AC (smoke_sections_resize.mjs, smoke_houseplan_panel.mjs) и ряд смоков, делящих символы _hdrH/_bootSoft/_stageEl/_warmSlot с изменённым boot-soft-layout.ts. Из них выбрал и прогнал smoke_render_invalidation.mjs (единственный, читающий _bootSoft напрямую — сигнатура settleSoftStageLayout изменилась) и smoke_warm_dialogs.mjs (_hdrH+_warmSlot, соседняя soft-layout цепочка) как точечную regression-проверку рефактора параметра panelHost → containerOwnedHeight; оба зелёные. Остальные 15 прямых совпадений и 28 слабых связей не гонял — сочтено непропорциональным для рефактора, который для существующих layout (layout не установлен) математически не меняет значение containerOwnedHeight (было panelHost, осталось panelHost || false), см. «Чего не проверял».
8. Экспериментально проверил (не для отчёта CI, а для собственной уверенности): вручную заменил language: 'ru' на 'de' в фикстуре smoke_sections_resize.mjs, прогнал — все проверки, включая minimumSixRowsStayContained, прошли и на немецкой локали; откатил правку (git status после отката чист). Это ограничивает находку Medium-1 ниже: код сейчас не ломается на German, но CI никогда не узнает, если сломается.
9. Проверил трейлеры всех трёх коммитов (git log) — Issue: #648 на каждом, User-Visible: yes только на 7f48e690, и оба changelog входят в этот же коммит (docs/CHANGELOG.md, docs/CHANGELOG.ru.md — видно в git show --stat 7f48e690).
10. Сверил термины режимов (Plan/Devices/Backdrop → «План»/«Устройства»/ «Подложка») со смоком, использующим внутренние имена plan/devices/ decor — совпадает с существующим соответствием в docs/USER-GUIDE.ru.md (уже проверено ревьюером ТЗ).
11. Проверил, что houseplan-space-card (src/space-card.ts) не получил ни getGridOptions, ни ссылок на новое свойство layout (grep) — юнит-тест это же утверждает через assert.doesNotMatch.
12. Проверил «одно число — один источник» (§8): 10/6 фигурируют только как возврат getGridOptions() (единственный источник) и как проза в changelog/USER-GUIDE/ARCHITECTURE/STATUS-FEATURES/TESTING, дословно совпадающая с этим возвратом; отдельного хардкода этих чисел или пиксельных производных (≈632/≈376 из K2) в src/** или изменённых docs/*.md не нашёл (grep).

Находки

Medium-1 (в скоупе задачи). AC3 документально обещает browser smoke

«RU/DE», а поставленный smoke проверяет минимальную высоту только на русской локали

Файл: demo/smoke_sections_resize.mjs:64-101 (секция minimumGeometry), конфиг card.setConfig(config) строка 72.

Что не так. Таблица AC issue #648 для AC3 называет доказательство буквально: «Browser smoke RU/DE, geometry + scroll oracle» — для наблюдаемого результата «На минимальных 6 строках View при узкой ширине и длинной локали не выходит за slot; header доступен...». Раздел i18n того же ТЗ поясняет зачем: «Существующие RU/DE длинные подписи входят в визуальную проверку минимальной высоты» — RU и DE выбраны вместе не случайно: docs/TESTING.md:484-485 фиксирует немецкую локаль как установленный в проекте эталон «длинных подписей», ломающих узкую/минимальную раскладку («German View... fit at desktop and 390 px without horizontal overflow or clipped actions»).

Фактически card.setConfig(config) в demo/smoke_sections_resize.mjs:72 задаёт language: 'ru' один раз на весь смок — включая блок minimumGeometry (строки 91–101), который единственный проверяет минимум 6 строк на узкой ширине 390 px. Немецкая локаль нигде в файле не упоминается (grep -n "language\|'de'" demo/smoke_sections_resize.mjs не находит de). Половина заявленного в AC3 покрытия не существует как исполняемый тест.

Почему это находка, а не блокер существующей защиты. Я не нашёл живого дефекта: ручной эксперимент (заменил 'ru' на 'de' в этом же файле, прогнал, откатил) показал, что на текущем коде minimumSixRowsStayContained и headerContained/menuReachable проходят и на немецкой локали. Это не регрессия сегодняшнего дня.

Сценарий отказа. Ближайшее изменение хедера/меню (например, более длинная подпись пункта меню, добавленная в рамках другой задачи) может сузить запас по немецкой локали на 390 px/6 строках, ничего не сломав по русской. Ни один автотест в этом дифе и ни один существующий golden/сценарий (проверено — docs/golden, demo/docs не содержат Sections/grid-сценария) это не заметит: smoke_sections_resize.mjs — единственный исполняемый свидетель AC3, и он проверяет только RU. Заявленная в согласованном ТЗ защита «длинная локаль не переполняет минимальный slot» наполовину не существует как код.

Почему в скоупе и не блокирует зелёный. Правка дешёвая — обернуть существующий блок minimumGeometry (или отдельно вызвать setConfig с language: 'de') в цикл по ['ru', 'de'] и агрегировать оба результата в minimumSixRowsStayContained; список поверхностей и файлов не меняется, не требует новой инфраструктуры. Без High-находок это делает вердикт жёлтым, а не переоткрывает задачу отдельным issue (#202).

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

• AC1 (grid defaults + getCardSize): getGridOptions() возвращает ровно { columns: 'full', rows: 10, min_rows: 6 } без max_rows (src/houseplan-card.ts:3762); подтверждено исполнением обоих браузерных смоков (executableGridDefaults, sectionsDefaultsRemainAvailableInPanel) и юнитом, не читающим монолит как единственное доказательство (юнит — дополнение к исполняемому свидетелю, не замена). space-card.ts не имеет getGridOptions — подтверждено grep и юнитом.
• AC2/AC3 (контейнерная высота, минимум 6 строк на 390 px): смок smoke_sections_resize.mjs реально измеряет getBoundingClientRect() host/card/ha-card/header/stage на живом собранном бандле — прогнан мной, зелёный (см. «Как проверялось» п.5). Кроме RU-ограничения из Medium-1, оракул содержательный: допуск 1 px, stage.height > 0, cardScroll/haCardScroll ≤ 1 (нет overflow/пустого хвоста).
• AC4 (серия 6→10→14→6, камера/аспект не сбрасываются, нет ошибок ResizeObserver): проверено исполнением; мутант sections-resize-drops-stage-refit-observer (отключение _roViewport.observe(stage)) краснит именно этот smoke — «чем краснеет» предметно подтверждено мной, не только заявлено автором.
• AC5 (переходы Plan/Devices/Backdrop не меняют внешний rect, нет busy-хвоста): смок ждёт реальный _modeTransition.state (не форсирует приватное состояние), проверяет entering.to.stageHeight <= card.clientHeight + 1 на входе и выходе для всех трёх режимов при 10 и 6 строках. Мутант sections-editor-transition-uses-window-height (возврат innerHeight вместо containerOwnedHeight ? this.clientHeight) краснит smoke — подтверждено прогоном.
• AC6 (explicit grid_options остаётся главным, config не мутируется): Object.freeze(config) в фикстуре + сверка JSON.stringify(config) === configBefore и card._config.grid_options === config.grid_options по идентичности объекта — сильнее обычного deep-equal, ловит скрытое клонирование. Не отдельный юнит-файл, а часть browser smoke (ТЗ называет «Unit + browser smoke» как два способа доказательства; по факту это один исполняемый смок) — расхождение в названии способа доказательства не снижает фактическое покрытие и не поднимается до отдельной находки (по аналогии со снятыми Low ревью ТЗ).
• AC7 (без layout=grid — старое поведение; space-card без grid defaults): card.layout = null в смоке восстанавливает 100dvh в реальном инлайн-стиле (ordinaryCardKeepsViewportHeight), проверено исполнением; smoke_houseplan_panel.mjs (panel-host, не grid) обновлён и прогнан мной отдельно — зелёный, панельная контейнерная высота не задета рефактором panelHost → containerOwnedHeight (математически containerOwnedHeight === panelHost когда layout не установлен).
• AC8 (resize не создаёт кликов/тапов, hit-coordinates верны после resize): moreInfo счётчик остаётся 0, stableMode === 'view', postResizeHitCoordinatesMatchCamera сверяет реальную матрицу getScreenCTM() SVG после шторма resize с card._view — не заявление, а геометрическая проверка через реальный DOM.
• AC9 (30 изменений высоты без ResizeObserver loop/error): цикл из 30 frame()-тиков с чередованием 6/14 строк, финальная геометрия и время (stormElapsed < 3000) проверены исполнением; finish() в demo/serve.mjs считает необработанные исключения карточки (_pageErrors) и красит прогон при их появлении — не только заявленные булевы поля.
• AC10 (документация + credit): docs/CHANGELOG.md/.ru.md, docs/USER-GUIDE.md/.ru.md, docs/ARCHITECTURE.md, docs/STATUS-FEATURES.md, docs/TESTING.md все обновлены и проверены чтением; @pando80 упомянут в обоих changelog с ссылкой на #648. check-docs.mjs --screenshots=warn (режим обычного пуша) прогнан мной — зелёный (единственная находка — WARN о неизменном скриншот- отпечатке, ожидаемо: диф не меняет визуальные пиксели плана/chrome, ТЗ прямо разрешает это в «Плане автотестов» п.7).
• Трейлеры и changelog: Issue: #648 на всех трёх коммитах, User-Visible: yes только на feat-коммите и оба changelog редактируются именно в нём — соответствует AGENTS.md.
• Одно число — один источник (§8): 10 и 6 строк существуют один раз — как возврат getGridOptions(); вся документация и тесты лишь переиздают это значение прозой/сравнением, вторичного независимого источника не заведено.
• Бандл воспроизводим: пересборка (npm run build && npm run bundle:sync) на материале не породила диффа — закоммиченный dist/** и зеркала в custom_components/houseplan/frontend/**, demo/srv/assets/** побайтно совпадают с исходниками этого SHA.
• Гейты, специфичные для src/**-дифа: no-new-any.mjs (0 новых any в 31 добавленной строке src/**), no-new-private-writes.mjs (0 новых записей в приватное состояние карточки из 223 добавленных строк смоков — только чтения, что разрешено), bundle:budget (initial View 291761 B, в пределах потолка) — все прогнаны мной и зелёные.
• Юнит-тесты: npm test — 3086 тестов, 3085 pass, 1 skip (не связан с этой задачей), 0 fail.
• Область изменений: space-card.ts, panel-host, Masonry, kiosk не тронуты кодом (только упомянуты в документации как «не меняются») — подтверждено grep по всем изменённым файлам и фактическим отсутствием правок вне houseplan-card.ts/boot-soft-layout.ts/base.styles.ts.

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

• Реальное поведение Home Assistant Sections вне этого репозитория. Весь механизм задачи опирается на внешний контракт: что настоящий HA при размещении карточки в Sections/grid-дашборде действительно устанавливает на элементе свойство layout = 'grid' (K3/K11, оставлено ревью ТЗ как «принято предположительно, поменять свободно» — технический, не продуктовый вопрос). В этой песочнице нет ни реального HA, ни доступа к инструментам веб-поиска/GitHub-поиска (запрошенные WebSearch и mcp__github__search_code не были разрешены), поэтому свериться с исходником home-assistant/frontend я не смог. Все AC2–AC10 в этом дифе проверены только против синтетической фикстуры, которая устанавливает card.layout = 'grid' вручную (demo/smoke_sections_resize. mjs:77) — они доказывают, что если HA присылает этот сигнал, карточка ведёт себя правильно, но не доказывают, что HA действительно его присылает именно так (то же имя свойства, тот же момент жизненного цикла). Это прямой риск: если предположение неверно, весь фиче-код останется мёртвым в проде при полностью зелёных гейтах. Технически это ровно то место, которое ревью ТЗ явно делегировало код-ревью — фиксирую как открытый остаточный риск, а не как находку, потому что задача не может быть проверена исполнением без реального HA, а сам код внутри доступного материала последователен и не содержит внутренних противоречий.
• 15 из 19 «прямых совпадений» и все 28 «слабых связей» smoke- select.mjs. Прогнал только smoke_sections_resize.mjs, smoke_houseplan_panel.mjs (названы в AC), smoke_render_invalidation.mjs и smoke_warm_dialogs.mjs (точечно — единственные, трогающие изменённую сигнатуру settleSoftStageLayout/_bootSoft напрямую). Остальные не гонял: рефактор panelHost → containerOwnedHeight в boot-soft-layout.ts математически не меняет значение для существующих (не-grid) карточек, поэтому регрессия там маловероятна; полный прогон матрицы — предрелизная обязанность, а не гейт код-ревью (§8).
• golden:verify — не прогонял. ТЗ прямо говорит: «Golden не требуется, если визуальные пиксели плана/chrome не меняются» — диф не трогает цвета/геометрию плана, только контейнерную высоту и CSS-flex; check-docs.mjs подтверждает отсутствие изменений в зафиксированных скриншот-сценариях документации (только WARN о фингерпринте, не ERROR).
• npm run invariants — не прогонял: диф не меняет геометрическую модель плана (стены/комнаты/устройства) и не трогает ссылки на неё, только презентационный слой карточки.
• python -m pytest tests_backend — не прогонял: диф не касается custom_components/houseplan/**/*.py.
• Performance-профили — не названы в AC этой задачи; ТЗ прямо запрещает новый observer/polling, а не вводит его (новый постоянный наблюдатель не добавлен — использован существующий _roViewport).
• typecheck/npm test/npm run build/golden/performance_smoke/ browser smoke-матрица целиком в CI — доверился зелёному Validate на точном SHA b7fb7cf7 (ссылка в задании) для typecheck/test/build; npm test и npm run build тем не менее перегнал сам (см. выше) для собственной уверенности перед прогоном смоков на пересобранном бандле — оба зелёные, совпадают с Validate.

Вердикт

0 High, 1 Medium (в скоупе задачи, Medium-1 — неполное покрытие AC3 браузерным смоком: заявлены RU/DE, реализована только RU). Без High-находок это жёлтый вердикт: автор дополняет demo/smoke_sections_resize.mjs немецкой локалью в проверке минимальной высоты и проходит повторный раунд код-ревью — отдельный issue не заводится (#202).

Всё остальное — AC1–AC2, AC4–AC10, трейлеры, changelog, гейты typecheck/ npm test/npm run build/no-new-any/no-new-private-writes/ bundle:budget/check-docs, четыре новых защитных мутанта и оба относящихся к задаче browser smoke — проверено исполнением и корректно.

Жёлтый.

---

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

---

Материал раунда

• Ветка: на момент ревью без явного имени в рабочей копии; вершина — b7fb7cf7e7bce13a44ef0e1af3b97541ddb0dffa.
• База сравнения: origin/dev = f68878cc44b818b6cfbdb3866302e6febaab2445.
• Дерево материала (git rev-parse HEAD^{tree} на момент ревью): снято на вершине b7fb7cf7e7bce13a44ef0e1af3b97541ddb0dffa, рабочая копия чиста до и после всех локальных гейтов/мутаций (git status --porcelain пуст).
• Предыдущий раунд (другой этап): docs/reviews/SPEC-REVIEW-648-r1.md, вердикт green, High 0, Medium 0.

---

Материал раунда

• Ветка: issue/648-sections-card-resize, коммит b7fb7cf7e7bc — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: a7fe21e21d802c04986cbfab31f3065266c8e9ff

  git log --all --format='%H %T' | grep a7fe21e21d80
  

• Тело issue: 8400466150bde494c01aef14b7d5961be36d721b08a28c69e800bd88ac645154
• Вердикт конвейера: yellow · High 0