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

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

- Issue: https://github.com/Matysh/houseplan-card/issues/51
- Материал раунда: `git diff 042af520fe4f6cc47d78ae6ccbb105580382e961..HEAD`
  (материал r2 объявлен в `docs/reviews/CODE-REVIEW-51-r2.md`).
- SHA материала: `043aa0d826cf1e1490a02feb4cc28f50cb96245b` (сверено с
  `git rev-parse HEAD` — совпадает).
- SHA предыдущего раунда (r2): `042af520fe4f6cc47d78ae6ccbb105580382e961` —
  жив, `git cat-file -t` → `commit`, `git merge-base --is-ancestor` подтверждает:
  прямой предок `HEAD`, ребейза не было.
- Трейлеры всех пяти коммитов дельты (`5a93fc2a`, `a5f28c3a`, `db08b92a`,
  `424a133b`, `043aa0d8`) — `Issue: #51`, `User-Visible: no`. Корректно: ни
  один не меняет наблюдаемое пользователем поведение (типизация без изменения
  рантайма, ruff-лint, публикация документа r2, пересъёмка отпечатка
  скриншотов, регенерация `config-schema.json`) — правок в `docs/CHANGELOG*`
  не требуется и не сделано.

## Скоуп раунда

Единственная предметная находка r2 (Medium, в скоупе: устаревший
`scripts/config-schema.json`) закрыта одним коммитом. Дельта — 9 предметных
файлов (без учёта бандлов), +361/-28: регенерация манифеста схемы,
`ruff`-порядок импортов в трёх backend-модулях, типизация трёх frontend-мест
(`decor-assets.ts`, `houseplan-editor-runtime.ts`, `space-render.ts`, ранее
помеченных `any`), обновлённый отпечаток документационных скриншотов и
публикация `CODE-REVIEW-51-r2.md`. Ребейза на ушедший вперёд `dev` не было,
контракт поведения не менялся, новая подсистема не задета, объём дельты
(9 файлов) на порядок меньше исходной задачи (63 файла) — критерий «разбор
остаётся полным» не выполняется, сокращение объёма правомерно.

Прочитал все пять диффов не-бандловых файлов построчно (см. «Проверено и
корректно») — это не декларативная типизация: `any` заменён на конкретные
локальные типы (`ContentItem`, `DecorAssetConfig`), добавлен non-null
assertion (`shape.asset_id!`) там, где рантайм уже гарантировал непустое
значение (тот же `if` guard, что и раньше), поведение не изменилось.

## Закрытие раунда r2

| Находка r2 | Чем закрыта | Где это видно |
|---|---|---|
| **Medium (в скоупе)** — `scripts/config-schema.json` устарел, `tests_backend/test_config_schema_manifest.py::test_issue_33_manifest_is_fresh_and_deterministic` красный после того, как `38205d87` добавил decor kind `image` в `validation.py` | `scripts/config-schema.json` регенерирован штатным `scripts/dump-config-schema.py`; добавлены 76 строк контракта `config.spaces[].decor[]<image>.*` | `scripts/config-schema.json` (диф `042af520..043aa0d8`); **воспроизведено лично**: `python3 scripts/dump-config-schema.py` (voluptuous доступен в песочнице без Home Assistant) перезаписал файл по тому же пути — `git status`/`git diff` после прогона пустые, то есть закоммиченный манифест побайтово совпадает со свежесгенерированным — детерминированность подтверждена, не только словом автора |

Единственная находка r2 закрыта предметно.

## Унаследовано из r2

Без повторной проверки приняты как есть — материал `docs/reviews/CODE-REVIEW-51-r2.md`
на SHA `042af520fe4f6cc47d78ae6ccbb105580382e961`, поскольку дельта r3 их код
не задевает:

- Весь High/Medium/Low реестр r1, закрытый и адверсариально проверенный в r2
  (UTF-16/32 DTD/entity SVG guard, `smoke_decor.mjs`, единая
  `projectDecorImage`, positive/negative resolve-кэш, touch pointerType,
  SVG per-attribute bounds, `javascript:`/`data:`-substring — сознательно
  оставлено Low).
- AC1, AC2, AC4, AC6, AC8–AC13 — унаследованы из r1 через r2, дельта r3 их не
  трогает.
- Golden (`npm run golden:verify`, 153/153 в r1) и полный HA-harness — не
  перепрогонял: дельта r3 не меняет визуальные числа и не меняет вызывающий
  контракт HA-специфичных тестов (только порядок импортов и типы).
- Bundle budget — известный долг #367 (запас < 15000 Б) остаётся, число
  практически не изменилось (291041 Б → 291018 Б).

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

Дешёвые гейты прогнал сам (зелёного Validate на `043aa0d8` на момент начала
ревью не было — CI ещё не завершился):

| Гейт | Команда | Результат |
|---|---|---|
| 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` после — чисто |
| Bundle budget | `npm run bundle:budget` | initial View 291018 B / 300000 B, запас 8982 Б — прошёл, тот же долг #367 |
| `no-new-any` по дельте раунда | `node scripts/no-new-any.mjs --base 042af520 --head HEAD` | зелёный: 16 добавленных строк в 3 файлах, новых `any` нет |
| `no-new-any` по всей задаче | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | зелёный: 808 строк в 10 файлах |
| Docs fingerprint (обязателен: дельта трогает `src/**`) | `node scripts/check-docs.mjs --external` | зелёный: «Documentation checks passed (7 files, 10 external links)», включая сверку `sourceFingerprint`/`captureScriptSha256`/побайтовых хешей 10 PNG |
| Регенерация config-schema (целевая проверка находки r2) | `python3 scripts/dump-config-schema.py` (voluptuous есть в песочнице) | манифест перезаписан по тому же пути; `git diff`/`git status` после — пусто → закоммиченный файл идентичен свежесгенерированному |
| Backend pure lint | `ruff check` | **не прогнан**: `ruff` не установлен в песочнице ревьюера и не ставится через `pip`/`python -m ruff` (нет пакета); см. ниже, чем компенсировано |
| **Backend: `pytest tests_backend` + coverage-порог** (обязателен: дельта трогает `.py`) | не смог прогнать локально: `pytest-homeassistant-custom-component==0.13.357`/`homeassistant==2026.8.3` требуют Python ≥3.14, в песочнице только 3.12.3, `pip install` за пином падает `No matching distribution` | **воспроизведено через реальный прогон CI на этом же SHA** — см. находку ниже, это не пропуск гейта, а его результат |
| Model invariants | не прогонял | дельта не трогает `marker.space`, `open_spans`, thickness-записи, `layout` — весь diff `042af520..HEAD` вне бандлов состоит из импортов, типов и данных манифеста/скриншотов, геометрии не касается |
| Целевые смоки/`smoke-select` | `node scripts/smoke-select.mjs --base 042af520 --head 043aa0d8` | «НЕОПРЕДЕЛЁННОСТЬ»: изменено 3 файла `src/**`, 5 символов на изменённых строках (`ContentItem`, `DECOR_ASSET_ID_RE`, `DecorAssetConfig`, `DecorShape`, `decorAssetIds`), ни один смок не привязан. Не прогонял: все пять символов — либо локальные типы, стираемые при компиляции (`ContentItem`, `DecorAssetConfig`, `DecorShape` — только аннотации, без изменения рантайма), либо неизменная сигнатура существующей функции (`decorAssetIds`, `DECOR_ASSET_ID_RE`), которую уже покрывает `test/decor-assets.test.mjs:18` (юнит зелёный в `npm test` выше) |
| Golden / HA full harness / performance | не прогонял | см. «Унаследовано из r2» — дельта не меняет визуальные числа и HA-специфичный контракт |

### Как проверялось: реальный CI-прогон на `043aa0d8`

Поскольку локальный backend-гейт недоступен (Python 3.14 нет в песочнице),
проверил статус актуального прогона `Проверка (CI)` для этого SHA напрямую
через `gh api`/`gh run view`:

- `run 33685317804`, `headSha 043aa0d826cf1e1490a02feb4cc28f50cb96245b`,
  итог `completed / cancelled`.
- Job **«Бэкенд: pytest в Home Assistant»** (`100431708612`) — **failure**.
  Сам `pytest tests_backend/ -q --cov=... --cov-branch` зелёный: `526 passed,
  2 skipped`. Падает следующий шаг, сравнивающий покрытие с
  `scripts/backend-coverage-baseline.txt`:
  ```
  coverage: 86.9% (baseline 87.2%)
  Process completed with exit code 1
  ```
  (порог — `actual >= baseline - 0.1`, см. `custom_components` job логи;
  механизм описан в `docs/specs/042-backend-engineering-quality.md` §4:
  «одно число, шаг CI сравнивает: ниже baseline − 0.1 п.п. → красный»,
  ratchet **не должен снижаться**).
- Остальные job'ы на этом SHA: «Предполётные проверки» — success (значит,
  проверка свежести `config-schema.json` теперь тоже зелёная в CI, совпадает
  с моим локальным воспроизведением находки r2); «Фронтенд: типы, юниты,
  мутанты, синхрон бандла» — success; «Hassfest», «HACS» — success; смоки
  шард 1/3 — success, шард 2/3 — cancelled (следствие общего fail-fast после
  красного backend-job, не отдельная находка); Golden/perf-smoke — skipped
  по той же причине.

## Находки

### Finding 1 (Medium, в скоупе) — backend coverage ratchet красный на `HEAD`: 86.9% < baseline 87.2% − 0.1

**Гейт:** `python -m pytest tests_backend -q --cov=custom_components/houseplan
--cov-branch` + шаг сравнения с `scripts/backend-coverage-baseline.txt` —
стандартный гейт код-ревью для задач, трогающих `custom_components/**/*.py`
(PROCESS.md §8), встроенный в тот же job CI. Все 526 тестов зелёные — падает
именно порог покрытия.

**Причина, воспроизведённая по логам реального прогона (не только словом
автора):** сравнил построчную таблицу `coverage --cov-report=term` на
`043aa0d8` (job `100431708612`) с последним зелёным прогоном этого же job на
`origin/dev` до фичи #51 (`cfa5c779`, job `100381072223`):

| Файл | dev (`cfa5c779`) | `HEAD` (`043aa0d8`) |
|---|---|---|
| `decor_assets.py` | файла не существовало | 292 стат., 71 непокрыт (**71%**) |
| `http_api.py` | 185 стат., 56 непокрыт (68%) | 304 стат., 87 непокрыт (69%) |
| `websocket_api.py` | 1069 стат., 155 непокрыт (84%) | 1145 стат., 169 непокрыт (83%) |
| **TOTAL проекта** | **87.2%** (зафиксировано как baseline) | **86.9%** |

Фича #51 добавила крупный новый модуль (`decor_assets.py` — SVG/raster
security-валидация, ровно тот код, где в r1 нашли обходимый DTD/entity-фильтр)
с покрытием заметно ниже среднего по проекту (71% против ~85-87%), плюс
расширила `http_api.py`/`websocket_api.py` без пропорционального прироста
тестов на новые ветки. Взвешенное среднее по всему backend просело на 0.3 п.п.
и вышло за допуск ratchet-гейта (0.1 п.п.).

**Не воспроизведено мной построчно (какие именно 71 из 292 statements
`decor_assets.py` не покрыты)** — `coverage.xml` в артефактах прогона не
публикуется, а локальный запуск `pytest --cov` недоступен: пин
`pytest-homeassistant-custom-component==0.13.357`/`homeassistant==2026.8.3`
требует Python ≥3.14 (см. `tests_backend/requirements.txt` — пины
преднамеренные, менять их ради ревью нельзя), в песочнице только 3.12.3;
`pip install -r tests_backend/requirements.txt` в отдельном venv (проверил)
падает `No matching distribution`. Табличные Miss-числа выше — это реальные
данные CI на этом SHA, не догадка, но точные номера строк я не устанавливал.

**Не архитектурный риск** — существующий malicious/regression corpus
`tests_backend/test_decor_assets.py` (27 тестов) уже ловит все находки r1/r2
(UTF-16/32 DTD/entity, oversized attrs, unit-interval). Но именно потому, что
это security-критичный модуль (метка `security` на issue, r1 уже нашёл
обходимый фильтр в непокрытом углу), 29% непокрытых statements в нём — это
плоскость, где обходы прячутся, а не косметика.

**В скоупе задачи, фикс не архитектурный:** добавить backend-тесты на
непокрытые ветки `decor_assets.py`/`http_api.py` (или обосновать `# pragma:
no cover` для реально недостижимого кода) до восстановления ≥87.1%; по
правилу ratchet baseline **нельзя** просто занизить — механизм специально
задуман монотонным (docs/specs/042 §4: «Пороги 90%→95%: … меняющие ОДНО число
… baseline»; вниз это число двигать не предполагается).

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

- Единственная находка r2 закрыта и лично перепроверена: регенерация
  `scripts/config-schema.json` детерминирована (перегенерировал сам —
  `git diff` пуст).
- Все пять правок дельты — типизация/порядок импортов без изменения
  поведения: прочитал построчно `decor-assets.ts`, `houseplan-editor-runtime.ts`,
  `space-render.ts`, `decor_assets.py`, `http_api.py`, `websocket_api.py`.
  Non-null assertion (`shape.asset_id!`) и приведения типов (`as ContentItem[]`)
  не меняют рантайм-путь — тот же `if`/`filter`-guard, что и раньше; `ruff`
  и `import` reordering — механические. Подтверждено тем, что `npm test`
  (1777) и `npx tsc --noEmit` зелёные на этом же дереве.
- `check-docs.mjs` подтверждает: отпечаток скриншотов пересчитан по всему
  `src/**` (обязателен, т.к. дельта трогает `src/**`), 10/10 PNG совпадают
  побайтово с принятыми — регрессии класса #230/#234/#237 в этом раунде нет.
- Три копии бандла синхронны (`bundle:sync` не изменил дерево), бюджет не
  превышен (тот же известный долг #367).
- Реальный CI-прогон на `HEAD` подтверждает и «Предполётные проверки»
  (включая свежесть `config-schema.json`) зелёными, и фронтенд-job зелёным —
  независимое от меня подтверждение моих локальных гейтов.

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

- **Точные номера непокрытых строк** `decor_assets.py`/`http_api.py` —
  `coverage.xml` не публикуется как артефакт, локальный прогон недоступен
  (Python 3.14 нет в песочнице). Табличные агрегаты Miss/Stmts взяты из
  реального лога CI (job `100431708612`), это не догадка, но не построчный
  разбор.
- `ruff check custom_components/houseplan` — пакет `ruff` не ставится в
  песочнице (`pip`/`python -m ruff` не находят модуль); компенсировано тем,
  что job «Предполётные проверки»/лint на актуальном `HEAD` в реальном CI —
  success (виден в прогоне `33685317804`).
- Полный HA-harness (`test_ha_websocket.py`, `test_ha_import_export.py`,
  `test_coordinate_canonicalization.py`) и Golden — не прогонял; дельта r3 их
  не касается (см. «Унаследовано из r2»), для полноты вижу по реальному CI,
  что до backend-failure остальные job'ы (Hassfest, HACS, фронтенд, 2 из 3
  смок-шардов) зелёные.
- 4 из 5 символов `smoke-select`-выборки — не прогонял отдельно; все они
  типо-стираемые аннотации либо неизменная сигнатура, уже покрытая юнитом
  (см. таблицу гейтов). Отдельного смок-прогона не потребовалось.
- Model invariants — не прогонял: дельта не касается геометрии (сверено
  чтением всего non-bundle diff).

## Вердикт

Единственная находка r2 закрыта предметно и лично перепроверена. Новая
находка этого раунда — Finding 1, Medium, в скоупе: backend coverage ratchet
красный на актуальном `HEAD` (86.9% < 87.2% − 0.1), обнаружено не декларацией
автора, а чтением реального прогона CI на этом же SHA (job
`100431708612`, run `33685317804`), поскольку локальный пере-прогон
`pytest tests_backend` в песочнице ревьюера недоступен по версии Python.
Причина — новый security-критичный модуль `decor_assets.py` с покрытием
заметно ниже среднего по проекту. Фикс не архитектурный (добавить backend-
тесты на непокрытые ветки), но не косметический как в r2 — реальный объём
работы. Без High это жёлтый вердикт по правилу §2.7: возврат автору, фикс
проходит следующий цикл ревью, отдельный issue не заводится (Medium в
скоупе).

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

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `issue/51-custom-decor-images`, коммит `043aa0d826cf` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `576c3e884af13ca0395b0cf943111e3654f3eddd`
  ```
  git log --all --format='%H %T' | grep 576c3e884af1
  ```