houseplan-card/docs/reviews/CODE-REVIEW-51-r2.md

CODE-REVIEW — issue #51 «Custom decor images» · заход r2

• Issue: https://github.com/Matysh/houseplan-card/issues/51
• Материал раунда: git diff 38205d87a6e65bf670e214050223a9e22a9d2a42..HEAD (материал предыдущего раунда объявлен документом docs/reviews/CODE-REVIEW-51-r1.md, раздел «Материал раунда» той же ветки).
• SHA материала: 042af520fe4f6cc47d78ae6ccbb105580382e961 (сверено с git rev-parse HEAD непосредственно перед выводом — совпадает).
• SHA предыдущего раунда (r1): 38205d87a6e65bf670e214050223a9e22a9d2a42 — жив (не осиротел), git cat-file -t подтверждает.
• Трейлеры фикс-коммита 042af520: Issue: #51, User-Visible: no (правки не создают нового пользовательского поведения сверх того, что уже задокументировано для feature-коммита 38205d87; см. «Один вопрос про User-Visible» ниже).

Скоуп раунда

Автор ответил на все содержательные находки CODE-REVIEW-51-r1 (High:1, Medium:3, Low:2) одним коммитом 042af520 поверх 38205d87. Дельта: 29 файлов, +831/-307 (без учёта переносимого docs/reviews/CODE-REVIEW-51-r1.md и сгенерированных бандлов — предметных 8 файлов исходников/тестов). Разбор этого раунда — по дельте, не по задаче целиком: ребейза на ушедший вперёд dev не было (38205d87 остаётся прямым предком HEAD), контракт поведения не сменился, новая подсистема не задета. Объём дельты (8 предметных файлов, ни одного нового модуля) заметно меньше исходной задачи (63 файла) — критерий «разбор остаётся полным» не выполняется, сокращение объёма правомерно.

Закрытие раунда r1

Находка r1	Чем закрыта	Где это видно
High — DTD/entity-фильтр обходится UTF-16 кодировкой SVG, entity bomb достигает ET.fromstring в обход собственной защиты	Байтовый префильтр заменён на encoding-aware expat.ParserCreate() с хендлерами StartDoctypeDeclHandler/EntityDeclHandler/ExternalEntityRefHandler/ProcessingInstructionHandler, которые фейлят закрыто до любого построения дерева; вызывается раньше ET.fromstring	custom_components/houseplan/decor_assets.py:162-197 (_reject_svg_declarations); регрессионный тест tests_backend/test_decor_assets.py::test_svg_utf16_doctype_is_rejected_before_entity_expansion — воспроизведено лично: тест красный на 38205d87 (DID NOT RAISE, отдельный worktree), зелёный на HEAD; дополнительно я сам скормил _reject_svg_declarations/validate_asset UTF-32/UTF-32LE/UTF-32BE-кодированные billion-laughs, вариант без XML-декларации и parameter-entity/XXE-пейлоад (SYSTEM "file:///etc/passwd") — все отклонены (DTD, entities... либо The SVG is not valid XML), обхода не нашёл
Medium (в скоупе) — demo/smoke_decor.mjs вызывает убранный делегатор c._furnPlace напрямую	Вызов переведён на c._editorRuntime._furnPlace(...), тот же паттерн, что уже применён к smoke_furniture.mjs в r1	demo/smoke_decor.mjs:192; воспроизведено лично: node demo/smoke_decor.mjs зелёный на HEAD (прогнал сам, свежая сборка)
Medium (в скоупе) — AC5 «одна projection-функция» не буквальна: дублирование формулы между houseplan-card.ts и space-render.ts	Вынесена единая projectDecorImage(shape, w, h) в src/decor-assets.ts, оба сайта её вызывают; при этом static-рендерер заодно перешёл на normalizeAngle (было Number(shape.angle)||0 — визуально эквивалентно, r1 сам это установил)	src/decor-assets.ts:35-51; src/houseplan-card.ts:8762-8765; src/space-render.ts:641-644; unit test/decor-assets.test.mjs сверяет точные числа (angle 405→45, flip, opacity clamp) и fail-closed null при w=0 — прогнал сам, зелёный
Medium (в скоупе) — нет negative/positive-кэша resolve по asset_id, каждая нерелевантная правка конфига переспрашивает houseplan/assets/resolve	WeakMap-кэш в resolveDecorAssets, ключ — стабильный hass.connection (или сам hass) плюс полный отсортированный набор id; повторный вызов с тем же набором возвращает тот же Map без нового callWS	src/decor-assets.ts:23,79-90; unit test/decor-assets.test.mjs («missing asset ids are negative-cached...», calls === 1 после второго вызова) — прогнал сам, зелёный; smoke smoke_decor_images.mjs (staticResolveCachesCompleteAssetSet) подтверждает на уровне houseplan-space-card._load — прогнал сам, true
Low — тач-committed размещение картинки использовало mouse-допуск снапа	_decorImagePlace теперь принимает pointerType и форвардит его в _decorSnap; оба вызывающих места (_decorPointerDown, _furnPointerUp) прокидывают реальный pointerType	src/houseplan-editor-runtime.ts:4203,5045,5130-5134; smoke smoke_decor_images.mjs (touchCommitUsesTouchSnapTolerance) — прогнал сам, true
Low, информационно — SVG numeric/string bounds отдельных атрибутов не проверялись	Добавлен MAX_SVG_ATTR_VALUE_CHARS=65536 (лимит на одно значение атрибута) и _validate_svg_unit_interval для opacity/fill-opacity/stroke-opacity/stop-opacity/offset (конечность и диапазон 0..1 либо 0..100%)	custom_components/houseplan/decor_assets.py:38,54-56,170-181,234-244; тесты test_svg_rejects_non_finite_or_out_of_range_unit_values, test_svg_rejects_one_oversized_attribute_before_tree_use — прогнал сам, зелёные (и красные на 38205d87, см. «Как проверялось»)
Low, информационно — javascript:/data:-substring проверка тривиально обходима непечатным символом	Не тронуто. Оставляю как было принято в r1: не эксплуатируется при текущем allowlist (href — строгий ^#id, единственный URL-приёмник), не архитектурный риск. Снимаю повторно с той же записью, фикса не требую	custom_components/houseplan/decor_assets.py:246-248 (без изменений в дельте)

Все шесть находок r1, требовавшие правки, закрыты предметно, не декларативно — по каждой я либо лично проиграл регрессию (High, Medium×2 через unit/smoke), либо прочитал изменённый код и совпадающий новый тест (оставшиеся). Седьмая (Low-информационная про URL-substring) сознательно оставлена как есть, с тем же обоснованием, что и в r1 — вторичной находкой её не завожу.

Унаследовано из r1

Без повторной проверки приняты как есть — материал docs/reviews/CODE-REVIEW-51-r1.md на SHA 38205d87a6e65bf670e214050223a9e22a9d2a42, поскольку дельта их не задевает (нет изменений соответствующих файлов между 38205d87 и HEAD):

• AC1 (кнопка/palette/one-shot), AC2 (100 см/aspect/cap 200), AC4 (properties/replace/no-delete-on-replace), AC6 (raster/SVG сигнатуры, атомарность аплоада), AC8 (content-addressed id, dedup), AC9 (server-side refcount, in_use), AC10 (missing/repair placeholder), AC11 (export v2/import v1 lifecycle), AC12 (rolling compatibility gate), AC13 (i18n паритет) — все проверены r1 чтением и/или тестами, дельта r2 их кода не меняет.
• Golden-сцены (npm run golden:verify, 153/153 в r1) — не перепрогонял: дельта не меняет визуальные числа (см. AC5 в таблице выше — новая projectDecorImage даёт побитово те же x/y/w/h/opacity/transform для валидных входов, что и было до вынесения в функцию; unit-тест сверяет точные значения). Полный HA-harness (test_ha_websocket.py, test_ha_import_export.py) — не перепрогонял по той же причине, что в r1 (нет homeassistant/Pillow в песочнице ревьюера); дельта их не касается (decor_assets.py дельта — только _validate_svg/_reject_svg_declarations внутренние правки, вызывающий контракт не изменился).
• Bundle budget (291041 B / 300000 B, запас 8959 Б < порога 15000 Б, известный долг #367) — переподтверждено в этом раунде (см. «Как проверялось»), число практически не изменилось (было 291046 Б на предыдущей сборке автора).

Как проверялось (гейты этого раунда)

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный
Unit (frontend)	npm test	1778 tests, 1777 passed, 1 skipped, 0 failed
Build	npm run build	зелёный
Bundle sync (3 копии)	npm run bundle:sync	зелёный; git status после — чисто (dist / custom_components/.../frontend / build совпадают побайтово; demo/srv/assets не коммитится, #255 — сверено cmp)
Bundle budget	npm run bundle:budget	initial View 291041 B / 300000 B, запас 8959 Б — прошёл, тот же известный долг #367
no-new-any по дельте	node scripts/no-new-any.mjs --base 38205d87 --head HEAD	зелёный: 51 добавленная строка в 5 файлах, новых any нет
Backend pure (целевой)	python3 -m pytest tests_backend/test_decor_assets.py -q	27 passed
Backend pure (полный набор, без HA-only модулей)	python3 -m pytest tests_backend -q --ignore=test_ha_websocket.py --ignore=test_ha_import_export.py --ignore=test_coordinate_canonicalization.py (последний игнор — падает по отсутствию homeassistant уже при коллекции, не тема этой задачи)	1 failed, 292 passed — см. Finding 1 (новая, ниже)
Docs fingerprint (обязателен: дельта трогает src/**)	node scripts/check-docs.mjs	ERROR: screenshot source fingerprint is stale — см. Finding 1 (новая, ниже)
Model invariants	не прогонял	дельта не трогает marker.space, open_spans, thickness-записи, layout — сверено git diff 38205d87..HEAD -- src custom_components/houseplan/*.py | grep -E "marker\\.space|open_spans|layout|thickness": единственное совпадение — неизменённая строка контекста (layoutChanged continuity-note). Инварианты нерелевантны, не пропущены
Целевые смоки (названные автором)	node demo/smoke_decor_images.mjs, smoke_decor.mjs, smoke_decor_layer_order.mjs, smoke_furniture.mjs	все 4 — OK, прогнаны лично на свежей сборке
Выбор дополнительных смоков по дельте	node scripts/smoke-select.mjs --base 38205d87 --head HEAD	214 смоков в матрице, изменено 5 файлов src/**, 13 символов на изменённых строках, порог «широкого» — 42. 14 прямых совпадений: только smoke_decor_images.mjs и smoke_decor.mjs привязаны к специфичным для дельты символам (_decorImagePlace, _decorSnap) — оба уже прогнаны выше. Остальные 12 (smoke_drag_bounds, smoke_grid_snap, smoke_active_chain_ink, smoke_card_tool_conflict, smoke_edit_walk, smoke_hide_layers, smoke_infinite_canvas, smoke_island_rooms, smoke_junction_holes, smoke_junction_limits, smoke_partition_openings, smoke_wallthick_standalone) совпали только по NORM_W/_svgPoint — распространённые символы, слабая связь (аналог _mode/_config из r1); не прогонял — непропорционально узкой дельте
Golden / HA full harness / performance	не прогонял в этом раунде	см. «Унаследовано из r1» — дельта не меняет визуальные числа и не касается вызывающего контракта HA-специфичных тестов; полный набор остаётся предрелизной обязанностью

Регрессионная дисциплина «тест умеет падать» проверена мной лично, не только по словам автора: воспроизвёл красный прогон новых тестов на предыдущем SHA — git worktree add --detach <tmp> 38205d87, скопировал новый tests_backend/test_decor_assets.py поверх старого decor_assets.py → 6 упавших (test_svg_utf16_doctype_is_rejected_before_entity_expansion, 4× test_svg_rejects_non_finite_or_out_of_range_unit_values, test_svg_rejects_one_oversized_attribute_before_tree_use), на HEAD те же 27 тестов зелёные. Для demo-смоков — smoke_decor.mjs уже официально воспроизведён в r1 (красный на 38205d87, зелёный на фикс-коммите); здесь переподтверждаю зелёный на актуальном HEAD.

Отдельно проверил направление фикса High-находки на предмет обхода: скормил _reject_svg_declarations/validate_asset тем же billion-laughs payload'ом, закодированным в UTF-32 (LE/BE/BOM), вариант без XML-декларации и parameter-entity/XXE (<!ENTITY % pe SYSTEM "file:///etc/passwd">) — все шесть вариантов отклонены (DTD, entities... либо невалидный XML), самостоятельного обхода не нашёл.

Находки

Finding 1 (Medium, в скоупе) — манифест scripts/config-schema.json устарел; пере-прогон полного tests_backend красный

Файлы: custom_components/houseplan/validation.py (добавлен decor kind image, часть исходного 38205d87, не дельты r2), scripts/config-schema.json (не обновлён ни в 38205d87, ни в 042af520).

python -m pytest tests_backend -q — стандартный гейт код-ревью «если менялся бэкенд» (PROCESS.md §8) — красный: tests_backend/test_config_schema_manifest.py::test_issue_33_manifest_is_fresh_and_deterministic падает с AssertionError: scripts/config-schema.json is stale — the schema changed; run python3 scripts/dump-config-schema.py and commit the diff.

Ни автор (хендофф-комментарии обоих раундов гоняли только test_decor_assets.py -q), ни ревью r1 (тоже ограничилось test_decor_assets.py, что явно записано в его «Гейты») этот файл не запускали — находка не относится к дельте r2 буквально (сама схема не менялась между 38205d87 и HEAD), но я обязан был прогнать полный пере-набор по правилу «backend тронут → pytest tests_backend», и он красный прямо сейчас, на актуальном HEAD этого раунда.

Воспроизведено лично, включая причину и фикс:

• на origin/dev (e438c25e, отдельный worktree) тот же тест зелёный (4 passed) — устаревание манифеста началось именно с фичи #51;
• на 38205d87 (материал r1, отдельный worktree) тест уже красный (1 failed, r1 просто не заметил, так как не гонял этот файл);
• python3 scripts/dump-config-schema.py (без HA/Pillow, только voluptuous, установленный в песочнице) добавляет 76 новых строк в манифест — ровно поля новой decor-разновидности config.spaces[].decor[]<image>.{asset_id,angle,color,flip_h,flip_v,h,w,x,y, opacity,id,kind,width,width_cm} (наследуются от _DECOR_COMMON плюс новые asset_id/flip_h/flip_v); после регенерации test_config_schema_manifest.py зелёный (4 passed). Файл scripts/config-schema.json восстановлен мной обратно (git checkout --) сразу после проверки — рабочее дерево ревью чисто, коммитить фикс не мне.

Частичное смягчение: JS-паритет (test/config-schema-parity.test.mjs, все 3 подтеста) остаётся зелёным, потому что новая запись реестра scripts/config-field-registry.mjs (spaces[].decor[]<kind='image'>) адресует уже существующий в манифесте обобщённый путь decor[] через дискриминирующий селектор, а не требует нового пути буквально — поэтому баг не пойман фронтенд-паритетом, только python-снимком (#33 contract).

Не архитектурный риск и не влияет на рантайм пользователя — это контрактный снимок для #33 (детерминированность схемы для будущих потребителей манифеста). Но это реальный красный узел стандартного гейта код-ревью, введённый именно этой задачей, и если он уедет в dev как есть — это тот же класс цены, что у #230/#234/#237 («красный job до следующей задачи»), только для tests_backend вместо docs.

Фикс механический, в скоупе задачи, чинится тем же коммитом: python3 scripts/dump-config-schema.py && git add scripts/config-schema.json, без изменения продуктового кода.

Проверено и корректно

• Все шесть предметных находок r1 закрыты кодом и тестом, не только словом автора (таблица «Закрытие раунда r1» выше); High полностью снят, обхода фикса адверсариально не нашёл (UTF-32, no-declaration, parameter-entity/XXE).
• projectDecorImage — единственная точка формулы проекции для full View и houseplan-space-card, устраняет класс «одно число — два источника» (#233/#234): сверено побитово через unit-тест с конкретными числами (не тавтология).
• Negative/positive resolve-кэш не меняет наблюдаемое поведение для пользователя (та же итоговая карта ассетов), только убирает лишние WS-вызовы; единственный найденный мной остаточный (не блокирующий) кейс — если один и тот же уже закэшированный как «отсутствующий» asset_id внезапно появится на сервере (переливка того же контента) без изменения набора id, шаг resolveDecorAssets с тем же ключом вернёт закэшированный (устаревший) результат до следующего изменения набора id или перезагрузки страницы. Практически недостижимо: контент-адресация делает такой сценарий «удалили → залили обратно тот же файл» единственным триггером, а server-side refcount (AC9) не доверяет клиентскому кэшу при удалении — то есть безопасность не страдает, только витрина может на короткое время отставать. Low, снимаю с записью, фикс не требую.
• Touch-committed размещение и SVG per-attribute границы — фикс подтверждён и кодом, и тестом (unit + smoke), поведение соответствует заявленному в r1 направлению.
• Три копии бандла синхронны, бюджет не превышен (тот же известный долг #367).

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

• Полный HA-harness (test_ha_websocket.py, test_ha_import_export.py) — как и в r1, нет homeassistant/Pillow в песочнице; дельта r2 не меняет вызывающий контракт этих модулей (только внутренности _validate_svg).
• Golden (npm run golden:verify) и performance-профиль — не перепрогонял; дельта не меняет визуальные числа (см. «Унаследовано из r1»), полный набор остаётся предрелизным.
• 12 из 14 «прямых совпадений» smoke-select — не прогонял, слабая связь по распространённым символам (NORM_W, _svgPoint), не специфичным для дельты; решение по каждой строке см. таблицу «Как проверялось».
• Точный количественный эффект resolve-кэша на числе живых WS-вызовов в большом плане (AC14, 1000 записей) — принял unit-тест (calls === 1 после повторного вызова) и smoke (staticResolveCachesCompleteAssetSet) как достаточное доказательство контракта, не гонял отдельный performance-профиль.
• Не проверял, ломает ли отсутствие регенерации config-schema.json что-либо за пределами самого test_config_schema_manifest.py (например, внешние потребители манифеста вне репозитория) — вне доступного мне материала.

Один вопрос про User-Visible

Коммит 042af520 помечен User-Visible: no. Формально верно для security/perf/consolidation-правок (SVG-валидатор, кэш, дедуп formula) — они не меняют то, что видит пользователь. Но правка touch-снапа (Finding 5 из r1) меняет реально ощутимое поведение при размещении картинки пальцем/пером (допуск снапа расширяется до тач-радиуса). Поскольку вся фича #51 ещё не проходила через бету (issue остаётся в S6/S7, ни разу не публиковался с этим багом), пользователь никогда не видел прежнего (более тесного) допуска на релизе — упоминать это отдельной строкой changelog не требуется; исходная запись фичи в docs/CHANGELOG.md/.ru.md (добавленная в 38205d87) уже покрывает завершённое поведение целиком. Не находка, оставляю как рассуждение для протокола.

Вердикт

Единственная блокирующая (High) находка r1 закрыта и лично проверена адверсариально. Все Medium/Low из r1 закрыты предметно. Новая находка этого раунда — Medium в скоупе, механический фикс (scripts/config-schema.json регенерация), без архитектурного риска и без High. По правилу §2.7 это жёлтый вердикт: возврат автору, фикс проходит следующий цикл ревью.

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

---

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

• Ветка: issue/51-custom-decor-images, коммит 042af520fe4f — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 460c8f2339fbae285d0e53cb6dbb177c935ce573

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