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

CODE-REVIEW-372-r1

Issue: #372 — «Компактное верхнее кадрирование houseplan-space-card без заголовка» Этап: code (PROCESS.md §2.7) · заход r1 · блокирующих циклов израсходовано 0 из 4 SHA материала ревью: 2bb7dfca5fa744a25f3af4d70260e2c41c42611f (ветка issue/372-space-card-empty-title, git rev-parse HEAD перепроверен в конце разбора) Диапазон: origin/dev..HEAD, коммиты d696541a…2bb7dfca (spec → spec-review → feat → docs: accept screenshots → test) Трек: полный (аналитика назвала непройденный критерий small)

Скоуп ревью

Первый заход по коду — предыдущего вердикта код-ревью нет, разбор полный. Проверено: соответствие реализации ТЗ docs/specs/372-space-card-empty-title.md и его 8 AC, docs/SCOPE.md (J1), docs/USER-GUIDE.ru.md (терминология title), канонический docs/CANVAS.md §4/§4.1/§4.2/§6 (контракт content frame / icon unit, который расширяет эта задача), трейлеры и release-артефакты всех 5 коммитов диапазона.

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

1. Прочитаны issue #372 целиком (описание + 2 комментария аналитики/решения владельца), ТЗ, SPEC-REVIEW-372-r1.md (зелёный вердикт), docs/SCOPE.md, AGENTS.md, PROCESS.md §2, §4, §7, §8, docs/USER-GUIDE.ru.md §18, docs/CANVAS.md §4/§4.1/§4.2/§6.
2. Полный git diff origin/dev...HEAD прочитан построчно: src/space-card.ts, src/space-geometry.ts, src/space-render.ts, test/canvas.test.mjs, demo/smoke_space_card.mjs, оба changelog, оба user-guide, dist/** и зеркала класса D.
3. Прочитан весь render() в src/space-card.ts:763-840 — порядок вычисления title/compactTopFrame и порядок DOM (title → body/stage → footer) сверены с контрактом ТЗ п.9 и разделом UX.
4. Прочитан padRect/contentFrame/spaceFrame целиком (src/space-geometry.ts:338-446): per-edge FramePad применяется одинаково в ветке core, в ветке all и в ветке sane.length < MIN_VOTERS; ветка stored-view_box-fallback (когда f.core === null) паддинг не применяет вовсе — контракт ТЗ п.6 подтверждён чтением, а не только словами автора.
5. Прочитан iconUnit/iconCqw (src/space-geometry.ts:474-517): масштаб иконок считается через собственный contentFrame(items, {pad:0}).core и делится на ширину (vb[2]), высоты compactTopFrame не касается — независимость иконок от компакт-режима подтверждена чтением.
6. Прочитан src/space-render.ts:270-620: единственный vb вычисляется один раз (строка 279 диапазона) и переиспользуется для viewBox, процентных координат маркеров/labels, aspect-ratio и --icon-size devlayer — SVG, devlayer и backdrop используют один и тот же compact viewBox (контракт п.8, «одно число — один источник» подтверждено чтением).
7. Проверены все 5 коммитов диапазона git show -s --format=full — трейлеры Issue: #372 и User-Visible: yes|no корректны на каждом; единственный User-Visible: yes (3c733c39) несёт правки в оба changelog и оба user-guide в этом же коммите.
8. gh run list для workflow «Скриминот документации»: успешный workflow_dispatch-прогон в 10:22:06Z предшествует коммиту 27a90dfd (10:24:33Z) — приёмка скриншотов прошла через канонический workflow, а не локальным захватом.
9. gh run list для workflow «Проверка (CI)» на ветке задачи: прогон на точном SHA 2bb7dfca в статусе in_progress на момент ревью — зелёного Validate ещё нет, гейты ниже прогнаны мной лично.

Гейты — что прогнано и с каким результатом

Гейт	Команда	Результат
typecheck	npx tsc --noEmit	зелёный, без вывода
unit	npm test	# tests 1544 · pass 1543 · fail 0 · skipped 1 (skip — известный, не из этой задачи)
build + сверка бандла	npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js	MATCH; git status --porcelain после сборки пуст — закоммиченный dist/** побайтово совпадает со свежей сборкой
bundle sync/budget	npm run bundle:sync && npm run bundle:budget	синхронизировано; initial View: 273864 B gzip (бюджет 300000, запас 26136)
docs fingerprint	node scripts/check-docs.mjs	Documentation checks passed (7 files, 10 external links)
new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	Новых any нет (30 добавленных строк в 3 файлах проверено)
выбор смоков	node scripts/smoke-select.mjs --base origin/dev --head HEAD	1 прямое совпадение (smoke_legacy_geometry.mjs ← spaceModels), 19 слабых связей (все — один общий символ _config, полные/редакторские смоки, к кадрированию static space card отношения не имеющие)
смок из AC	node demo/smoke_space_card.mjs	OK, см. числа ниже
смок прямого совпадения	node demo/smoke_legacy_geometry.mjs	OK, parity: true
проверка «тест умеет падать»	временный откат compactTopFrame: this._config.title === '' → compactTopFrame: false, пересборка, повтор смока, затем git checkout -- src/space-card.ts	смок дал FAIL space-card smoke, exit=1; после отката рабочее дерево снова чистое (git status --porcelain пуст), смок снова OK

Числа из живого браузерного прогона demo/smoke_space_card.mjs (AC1–AC4):

compactHasTitle: false, compactTopGap: 0
frame:               {x:-50, y:50,  w:1100, h:900}
namedFrame:           {x:-50, y:50,  w:1100, h:900}   (== frame, AC3)
compactFrame:         {x:-50, y:100, w:1100, h:850}
compactNoButtonFrame: {x:-50, y:100, w:1100, h:850}   (== compactFrame, AC4)
compactWidths: [320, 640]; compactOverflow: false
compactThemes: [false, true]

x и w не меняются между frame и compactFrame (левый/правый край padding сохранён), y+h совпадает (950 = 950, нижний край сохранён), y сдвинут ровно на удалённый верхний паддинг (50 → 100 при уменьшении h с 900 до 850) — то есть AC2 доказан не только unit-тестом на синтетической fixture, но и настоящим browser DOM/SVG прогоном на demo-фикстуре.

Не прогнано и почему

• Полный browser smoke (202 файла) и golden — предрелизный гейт (PROCESS.md §8), не гейт код-ревью. golden дополнительно нерелевантен по содержанию: grep -rli "space-card\|space_card" demo/golden/ не находит ни одного упоминания — houseplan-space-card не входит в golden-матрицу вообще, значит golden:verify не покрыл бы этот диф ни при каком прогоне.
• 19 «слабых связей» из вывода smoke-select (все — единственный общий символ _config, используемый в любом смоке, где карточка вообще конфигурируется: smoke_color_picker, smoke_kiosk, smoke_multiwall_junction и т. п. — полные/редакторские сценарии, не использующие spaceFrame/space-render.ts). Просмотрены по именам и назначению, ни один не имеет отношения к static space card или к padRect; не прогонялись.
• node scripts/model-invariants.mjs — диф не трогает геометрию модели или ссылки на неё (рёбра комнат, layout, marker.space, open_spans, записи толщины стен): изменение затрагивает только рендер-тайм вычисление viewBox/frame, что подтверждено чтением всего дифа space-geometry.ts (новый код — только padRect/FramePad, ни один вызов не модифицирует хранимую модель). Инварианты не запускались как нерелевантные.
• python -m pytest tests_backend — Python не тронут (custom_components/** в дифе есть только как класс D, сгенерированный бандл).
• performance-профили — не названы в AC, влияние на производительность не заявлено и неправдоподобно (одна дополнительная ветка typeof pad === 'number' в чистой функции, вызываемой раз на рендер, как и раньше).
• test/single-source-numbers.test.mjs отдельно не запускался вне общего npm test (он уже входит в набор и прошёл в нём) — диф не добавляет новую пользовательскую величину с единицей измерения, поэтому смысловая часть «одно число — один источник» здесь неприменима: единственное «число, видимое дважды» — сам frame (viewBox), и он проверен как раз тем, что все потребители (svg, проценты меток, aspect-ratio, --icon-size) читают один и тот же vb (см. «Как проверялось», п.6).
• Зелёный CI Validate на точном SHA — прогон идёт (in_progress на момент ревью), гейты выше прогнаны мной лично взамен.

Проверка AC

AC	Доказательство	Вердикт
AC1 (компактность при title:"")	browser smoke: compactHasTitle:false, compactTopGap:0; проверено, что тест умеет падать (см. таблицу гейтов)	доказан
AC2 (меняется только верх frame)	unit-тест test/canvas.test.mjs («per-edge frame padding can remove only the top inset») + browser smoke (compactFrame vs frame: тот же x/w, тот же y+h, y сдвинут на удалённый top-pad)	доказан
AC3 (omitted/non-empty совместимы)	browser smoke: omittedTitle:"Ground floor", namedTitle:"Named floor", frame === namedFrame побайтово	доказан
AC4 (SVG/devlayer/footer в одном frame, show_button не влияет)	чтение space-render.ts (один vb на все слои) + browser smoke compactFrame === compactNoButtonFrame	доказан
AC5 (edge cases без NaN/Infinity, voting не меняется)	новый unit-тест «per-edge padding keeps frame fallback and degenerate protection» (stored-view_box fallback и вырожденная точка) + весь существующий пакет canvas.test.mjs/space-geometry зелёный (1543/1543)	доказан
AC6 (desktop/touch width, light/dark, inert)	browser smoke на 320px/640px, darkMode:false/true, compactOverflow:false; pointer-events:none — общий CSS-класс .hp-static-stage, не зависящий от режима title (проверено чтением)	доказан по коду + смоком; полный Linux smoke/golden — предрелизный гейт, не здесь
AC7 (документация)	docs/CHANGELOG.md/.ru.md, docs/USER-GUIDE.md/.ru.md — правки прочитаны, ссылка на #372 на месте, различие omitted/non-empty/explicit-empty описано в обоих гайдах	доказан
AC8 (сборка и бюджет)	таблица гейтов выше (tsc, test, build+cmp, bundle:budget, check-docs, no-new-any)	доказан

Проверка по SCOPE.md

Задача остаётся в компактном read-only варианте J1: houseplan-space-card — View-поверхность, интерактивность не меняется (pointer-events:none на .hp-static-stage сохранён и не зависит от режима заголовка). Лок-инвариант не затронут. Соответствует.

Проверка скоупа и не-скоупа

• Полная houseplan-card не затронута: spaceFrame в src/houseplan-card.ts вызывается без переопределения pad (числовой дефолт 0.05 остаётся типом FramePad), подтверждено побайтовым совпадением пересобранного dist/** с закоммиченным и зелёным полным набором unit-тестов, включая тесты полной карточки/wall-geometry, не относящиеся к этой задаче.
• Боковой/нижний padding static-карточки не removed — доказано и unit-тестом, и browser-smoke (см. AC2).
• Новых UI-контролов, i18n-ключей, миграций конфигурации нет — подтверждено чтением дифа (только src/space-card.ts, src/space-geometry.ts, src/space-render.ts, тесты и документация).
• spaceFrame для других потребителей не изменена по поведению (только расширен тип параметра pad) — не-скоуп соблюдён.

Находки

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

Low (не требует правки, фиксирую с записью): FramePadding экспортирован из src/space-geometry.ts, но нигде не импортируется — space-render.ts передаёт литерал объекта, полагаясь на структурную типизацию TypeScript. Мёртвый публичный экспорт, не влияет на бандл (типы стираются на этапе сборки) и не нарушает ни один AC; ТЗ прямо разрешает автору свободу в «имени pure helper и точном месте per-edge арифметики» (раздел «Принято предположительно»). Не считаю нужным возвращать на правку.

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

• Реализация 1:1 соответствует контракту поведения ТЗ (все 9 пунктов), включая независимость масштаба иконок от compactTopFrame и общий vb для всех слоёв сцены.
• Все 8 AC доказаны — либо автотестом, для которого проверено умение падать (browser smoke, целенаправленный откат кода), либо unit-тестом с осмысленными числовыми ассертами (не тавтологичными), либо чтением кода с прямой пометкой «доказан по коду».
• DOM-порядок (title → body/stage → footer) не изменился.
• Трейлеры и release-артефакты во всех 5 коммитах диапазона корректны; User-Visible: yes несёт правки в оба changelog и оба user-guide в одном коммите с поведением.
• Приёмка скриншотов документации прошла через канонический workflow «Скриншоты документации» (проверено по времени прогона в gh run list), а не локальным захватом.
• Гейты typecheck/test/build/bundle:budget/check-docs/no-new-any зелёные, бандл трёх копий синхронизирован и побайтово совпадает со свежей сборкой.

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

• Полный browser smoke (202 файла) и golden:verify — предрелизный гейт; golden дополнительно не покрывает houseplan-space-card (см. таблицу).
• 19 «слабых связей» из smoke-select — просмотрены по именам/назначению, не прогонялись (общий символ _config, не геометрия static-карточки).
• model-invariants.mjs — диф не касается модели/геометрии, только render-time frame.
• Backend/Python — не тронут.
• Performance-профили — не заявлены и неправдоподобны для этого дифа.
• Зелёный CI Validate на точном SHA 2bb7dfca — прогон был in_progress на момент ревью; гейты выполнены мной лично вместо ожидания.

Вердикт

Зелёный. Все 8 AC доказаны автотестами (с подтверждённым умением падать) и/или прямым чтением кода; реализация точно соответствует контракту ТЗ и не выходит за его скоуп; дешёвые и относящиеся к дифу гейты прогнаны лично и зелёные; трейлеры и release-артефакты корректны. Находок уровня High/Medium нет; одна Low-находка (мёртвый экспорт типа) снята с записью, без возврата на правку.