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

CODE-REVIEW-384-r1

Issue: #384 · «hidden architecture no longer widens the fit: house frame» Заход: r1 · трек small (лимит циклов код-ревью — 2) · блокирующих циклов израсходовано 0/2 Материал: git diff origin/dev...HEAD, диапазон origin/dev..HEAD (2 коммита) SHA на момент вердикта: 4f28bf4f7f1699a7fb094ab05c72348c9a66acb2 (проверено git rev-parse HEAD непосредственно перед выводом) Ветка: issue/384-fit-house-hidden-walls

Первый раунд код-ревью — раздел «объём по дельте» (§2.10) не применяется, разбор полный.

Скоуп

Коммиты:

• 16133394 fix: hidden architecture no longer widens the fit: house frame (#384) — User-Visible: yes, Issue: #384. Меняет src/space-render.ts, расширяет demo/smoke_space_card.mjs, добавляет мутант в scripts/mutation-gate.mjs, правит docs/CANVAS.md, docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md, docs/CHANGELOG.md, docs/CHANGELOG.ru.md.
• 4f28bf4f build: refresh bundle trees for #384 — User-Visible: no, класс D (пересборка бандла + скриншоты документации).

ТЗ — лёгкий трек, тело issue (редакция 2 после SPEC-REVIEW-384-r1/r2, оба ревью ТЗ уже пройдены: r1 жёлтый M1 закрыт, r2 зелёный). AC1–AC4 из тела issue проверялись против этого диффа.

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

Прогнано лично на SHA 4f28bf4f (зелёного Validate на этом SHA не найдено, поэтому дешёвые и относящиеся к делу гейты прогнаны самостоятельно):

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	чисто, без вывода
Юнит	npm test	# tests 1585 / pass 1584 / fail 0 / skipped 1 — совпадает с заявленным в хендоффе
Build + сверка бандла	npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js	MATCH; дополнительно npm run bundle:sync — git status/git diff --stat после пересборки пуст, дерево уже синхронно
Бюджет	npm run bundle:budget	initial View 277 978 Б / 300 000 (запас 22 022 Б) — совпадает с заявленным «+14 Б» (277 951 в хендоффе), расхождение в пределах шума хешей чанков
any на новых строках	node scripts/no-new-any.mjs --base origin/dev --head HEAD	«Новых any нет» (8 добавленных строк в 1 файле)
Доки-отпечаток	node scripts/check-docs.mjs (diff трогает src/** → обязателен)	«Documentation checks passed (7 files, 10 external links)»
Выбор смоков	node scripts/smoke-select.mjs --base origin/dev --head HEAD	«НЕОПРЕДЕЛЁННОСТЬ» — символ на изменённых строках не совпал ни с одним смоком автоматически (в диффе нет нового именованного символа проекта — правка сидит внутри уже существующей функции renderSpaceStatic). Решение по строкам ниже принято вручную, не автоматом
Целевой смок (AC1/AC2/AC3)	node demo/smoke_space_card.mjs	OK space-card: ... — прогнан, зелёный; hiddenTwinFrames.hidden.w = 752 против hiddenTwinFrames.shown.w = 300938 (см. ниже)
Смежный смок (Glow/viewBox)	node demo/smoke_glow_blending.mjs	{"ok":true,"blend":"screen","pools":60,"staticParity":true,"staticPools":60} — совпадает с заявленным «parity 60/60»; прогнан, т.к. риск-раздел ТЗ утверждает независимость Glow от структуры кадра, а Glow рисуется в том же viewBox, который эта задача меняет
Мутационный гейт (целевой мутант)	node scripts/mutation-gate.mjs --id=fit-house-hidden-walls-vote	ok чистый прогон: node demo/smoke_space_card.mjs → ok fit-house-hidden-walls-vote: тест покраснел, как обязан → поймано 1 из 1
Процесс-гейт	node scripts/process-gate.mjs	«гейт пройден, предупреждений 1» (п.3: ТЗ для класса A не найдено файлом — ожидаемо для метки small, ТЗ в теле issue)

Не прогонялись и почему:

• golden:verify — диф меняет видимый кадр (viewBox), но проверено grep -n "fit:" demo/golden/matrix.mjs: ни один golden-сценарий не задаёт fit: 'house' вовсе (только showBorders:false в изометрических сценариях без fit, которые используют другой, независимый путь кадрирования — см. «Один голос — один источник» ниже). Полный прогон golden не покрыл бы изменённую ветку и не доказал бы ничего сверх уже прогнанных смоков; прогон предрелизный (PROCESS §8) в любом случае.
• python -m pytest tests_backend — диф не трогает custom_components/**/*.py.
• npm run invariants -- --config ... — диф не меняет модель геометрии (рёбра комнат, записи толщины, layout, marker.space, open_spans); меняется только то, что уже посчитанная геометрия отдаёт в подсчёт кадра. npm test (зелёный) уже гоняет инварианты на всех моделях проекта.
• Полный набор demo/smoke_*.mjs (205 файлов) — задача — один модуль, один цикл кадрирования; smoke-select.mjs не нашёл автоматической связи («НЕОПРЕДЕЛЁННОСТЬ»), а smoke_wall_junctions (похожее по названию, но нерелевантное — прецедент #234) сюда не подходит по смыслу: там про геометрию стыков, здесь — про то, участвует ли уже готовая геометрия в подсчёте bbox. Прогнаны только два смока, чью связь с диффом я установил по чтению кода (прямое совпадение — smoke_space_card сам расширен этим коммитом; зарегистрированная связь — smoke_glow_blending из-за общего viewBox).
• Performance-профили — не названы в AC, диф не задевает горячий путь (условие плюс пропуск цикла, не новый проход по геометрии).

Находки

Нет находок уровня High или Medium — ни в скоупе, ни вне его.

Дополнительная проверка (сделана ревьюером сверх AC, результат — отрицательный)

При чтении обнаружил, что параллельная (не структурная) «content»-рамка fit: content/по умолчанию тоже безусловно включает extras/zeroWalls.lines в список placed (src/space-render.ts:355-365) — то есть на первый взгляд тот же класс дефекта («невидимая архитектура голосует в кадре») мог существовать и для дефолтного режима, вне скоупа #384. Эмпирически проверил отдельным сценарием (твин-карточки без fit, с тем же удалённым столбом, show_borders true/false): рамки совпали побайтово ({x:-50,y:50,w:1100,h:900} в обоих случаях). Причина — contentFrame использует core (статистическое отбрасывание выбросов, §4.1 CANVAS.md), а не «сохранить каждый структурный элемент», как fit: house; удалённый столбец в обоих случаях отбрасывается как выброс независимо от видимости. Это не дефект — отдельного issue не заводил.

Что проверено и корректно (AC1–AC4)

• AC1 (далеко выступающая стена/колонна-extra + show_borders:false + fit:house → кадр по комнатам): доказано автотестом — новый блок hiddenTwinFrames в demo/smoke_space_card.mjs клонирует снапшот конфига, добавляет wall_columns с дальним столбцом и разнится только show_borders; ассерт hidden.x+hidden.w < shown.x+shown.w - 100 прошёл (752 против 300938 по ширине на живом прогоне). Тест умеет падать — подтверждено мутационным гейтом (--id=fit-house-hidden-walls-vote, патч снимает if (disp.showBorders) перед циклом extras → смок красный, поймано 1/1).
• AC2 (show_borders:true → кадр байт-в-байт как раньше): доказано и чтением, и исполнением. По коду: все три новых гварда — if (disp.showBorders) for (...) — при showBorders === true строго эквивалентны прежнему безусловному циклу (условие не меняет тело, только пропускает его при false); needsCanonicalWallGeometry новой формы walls.length || (extras.length && disp.showBorders) при showBorders === true даёт то же логическое значение, что старая ... || (extras.length && (disp.showBorders || fit === 'house')) — обе истинны на этой ветке ИЛИ. Исполнением: существующие ассерты tightFrame, tightNoTitleFrame, containment ±0.51px, tightPaintedEnvelope в том же прогоне smoke_space_card.mjs не изменились и остались зелёными (значения tightFrame и tightNoTitleFrame идентичны в выводе прогона).
• AC3 (show_borders:false + видимые проёмы → проёмы всё ещё голосуют): проверено чтением, не исполнением. Гвард проёмов (if (!disp.hideOpenings) for (const resolved of resolvedHosted), :453) диффом не тронут; в обоих твинах hideOpenings не установлен (по умолчанию false), то есть проёмы формально видимы и участвуют в обоих сценариях смока, но тест не изолирует это отдельным ассертом (например, не сравнивает hidden-кадр с эталонным «только комнаты+проёмы»). Symmetричность с рендер-гвардом проёмов подтверждена и в docs (CANVAS.md, USER-GUIDE) — формулировки согласованы с кодом.
• AC4 (полный гейт зелёный, бюджет ≈0): подтверждено таблицей выше; бюджет 277 978/300 000 Б (запас 22 022 Б, дельта от заявленных автором 277 951 в пределах хеш-шума).

Асимметрия проверки трёх симметричных гвардов (Low, не блокирует, не правится)

Диф добавляет один и тот же гвард if (disp.showBorders) в трёх местах: тела стен из canonicalWallGeometry.components, extras, zeroWalls.lines. Мутационный тест и новый твин-смок доказывают исполнением только гвард extras (демо-фикстура smoke_space_card.mjs никогда не задаёт spCfg.walls — проверено отдельным прогоном houseplan/config/get на пространстве f1: wallsLen: 0 до патчей смока), поэтому гварды canonicalWallGeometry.components и zeroWalls.lines доказаны только чтением: та же механическая конструкция if (disp.showBorders) for (...), тело циклов не изменено, риск опечатки симметричен и низок. AC1 это покрывает буквой («стена ИЛИ колонна-extra»), так что это не невыполненный AC, а точечный пробел мутационного покрытия. Снимаю без правки: расширение демо-фикстуры настоящими walls/нулевыми стенами ради этого — по объёму сравнимо с отдельной задачей, не стоит того здесь.

Один голос — один источник

Диф не добавляет и не меняет ни одной пользовательской величины (нет новых чисел/подписей/превью) — правило неприменимо. Затронутая величина — viewBox (геометрический кадр), а не отображаемое число; test/single-source-numbers.test.mjs входит в зелёный npm test и не задет по существу.

Трейлеры и трассируемость

• 16133394: Issue: #384, User-Visible: yes — оба changelog (docs/CHANGELOG.md, docs/CHANGELOG.ru.md) правлены в этом же коммите, запись под ## Unreleased, ссылка на #384 есть в обоих.
• 4f28bf4f: Issue: #384, User-Visible: no — только класс D (бандл + скриншоты документации), корректно.
• Ветка issue/384-fit-house-hidden-walls соответствует issue/<NN>-slug.
• process-gate.mjs — зелёный (1 некритичное предупреждение, ожидаемое для лёгкого трека).

Документация

docs/CANVAS.md:232-236, docs/USER-GUIDE.md:798-803, docs/USER-GUIDE.ru.md:1546-1552 — все три обновлены оговоркой «участвуют только пока видимы (show_borders)», согласовано с кодом и друг с другом; это ровно то, что требовало M1 из SPEC-REVIEW-384-r1. check-docs.mjs подтверждает отпечаток скриншотов (7 файлов) в порядке.

Вердикт

Зелёный. High: 0, Medium: 0. Единственная заметка — Low по асимметрии мутационного покрытия трёх симметричных гвардов — снята решением ревьюера без правки (см. выше), в документ занесена с обоснованием.