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

CODE-REVIEW-42-r2

• Issue: https://github.com/Matysh/houseplan-card/issues/42
• Ветка: issue/42-backend-quality, HEAD на момент вердикта: 7e5a19376d921ba0faf9929ff040e467d0e8c0d0
• Заход: r2 (второй фактический прогон ревью кода; счётчик циклов §4 = 1/4, зелёного цикла не образуется, а два комментария «ревью не запускалось» из-за конфликта ребейза — это остановка конвейера ДО ревью, не цикл)
• Материал: git log --oneline origin/dev..HEAD / git diff origin/dev...HEAD (53 файла, 926+/321-)

Почему разбор полный, а не по дельте (§2.10)

Между r1 (SHA ab337193) и этим заходом ветка дважды ребейзилась на ушедший вперёд dev (конфликты в собранных бандлах, зафиксированы в issue дважды — прогоны 33318210024 и 33318796499). §7.2/§2.10 прямо называют этот случай границей: «после ребейза это другой код». Поэтому ниже — полный разбор всех пяти блоков ТЗ (ревизия 6), а не только диффа поверх r1.

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

r1 (SHA ab337193abb8c629322313a0bf2d747105942db4) был красным: High: 2.

Находка r1	Чем закрыта	Где это видно
H1 — новый any в src/houseplan-card.ts:9743 ((item: any))	Заменено на (item: { id?: unknown })	src/houseplan-card.ts:9757 (текущий HEAD); node scripts/no-new-any.mjs --base origin/dev --head HEAD → «Новых any нет» — перепроверено мной командой сейчас
H2 — requirements_test.txt не разрешим (pytest==9.1.1/pytest-cov==7.1.0 конфликтуют с транзитивными пинами pytest-homeassistant-custom-component)	Пины сняты, затем pytest-homeassistant-custom-component закреплён на 0.13.316 (последний релиз с Requires-Python <3.14) в коммитах 9a62182f→3b1ccb85→5b102471	Backend CI job HEAD 7e5a19376d92... (job 99276949757): pip install -r requirements_test.txt завершается Successfully installed ... pytest-homeassistant-custom-component-0.13.316 ... homeassistant-2026.2.3 — проверено чтением лога прогона, не со слов автора

Оба High закрыты по существу, независимо перепроверено исполнением/логом CI, а не по формулировке автора.

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

Ничего не наследуется без повторной проверки в этом раунде — ребейз на ушедший вперёд dev обязывает к полному разбору (см. выше), поэтому все AC ниже перепроверены заново на текущем HEAD, а не приняты по r1. Единственное, что буквально не пересчитывалось заново, а взято как решённое владельцем и не подлежащее пересмотру ревьюером кода: сам текст ТЗ ревизии 6 (арбитраж владельца от 30.08, бюджет ревью ТЗ исчерпан 4/4) — согласно роли (§6), код-ревью не ревьюит спецификацию повторно, только реализацию.

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

Гейт	Команда	Результат
Типы (frontend)	npx tsc --noEmit	чисто
Юниты (frontend)	npm test	1636 pass / 0 fail / 1 skipped (совпадает с хендоффом)
Сборка + сверка 3 копий бандла	npm run bundle:sync	без diff после сборки — dist/custom_components/demo идентичны
Бюджет бандла	npm run bundle:budget	initial View 282745 B gzip / 300000 (запас 17255 B; авторские 282738 — расхождение в 7 байт, не критично)
no-new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	новых any нет (H1 подтверждён закрытым)
Доки (docs, реальный блокер по AGENTS.md)	node scripts/check-docs.mjs --external	КРАСНО — 10 несовпадений хэшей скриншотов (см. High-1)
ruff (CI-скоуп: только custom_components/houseplan)	python -m ruff check custom_components/houseplan	чисто
ruff (полный include из pyproject: + scripts, tests_backend)	python -m ruff check custom_components/houseplan scripts tests_backend	53 находки — но CI это никогда не проверяет (см. Low-3)
mypy strict (6 модулей allowlist)	python -m mypy --config-file pyproject.toml -p ... (все 6 модулей)	Success: no issues found in 6 source files
Контракт-тесты (pure pytest)	python -m pytest tests_backend/test_backend_quality.py -q	3 passed; мутант «убрать invalid_passage_fields из ERROR_CODES» — воспроизведён вручную, тест падает (AssertionError), файл восстановлен
Фронт-юниты error-текста (AC6)	node --test test/open-passage-contract.test.mjs	8/8, включая тест _errText JSON-first/code-first fallback
mutation-gate self-test	node --test test/mutation-gate.test.mjs	10/10
i18n-паритет backup.error.*	git diff origin/dev...HEAD -- src/i18n/*.json + подсчёт	ровно 22 новых ключа в каждом из 4 словарей
CI на точном SHA 7e5a1937	gh run view / job logs	красный: backend (86 failed, унаследовано с dev — см. ниже), Предполётные проверки (провален check-docs, см. High-1); фронтенд/HACS/hassfest — зелёные
smoke-select.mjs	node scripts/smoke-select.mjs --base origin/dev --head HEAD	«НЕОПРЕДЕЛЁННОСТЬ» — 1 изменённая строка src/**, символ _serverCfg слишком широкий, доказанной связи нет
Геометрия (wall_segment_model.py, B023-фиксы)	чтение диффа + backend CI job (строка покрытия wall_segment_model.py … 87%, модуль не в списке 86 упавших)	closures (covered_by/eligible/materialize/pick) вызываются в той же итерации, где определены — биндинг по умолчанию не меняет поведение; независимо подтверждено прогоном CI (не только чтением)
junction_limits.py	чтение диффа	только type hints + перестановка импортов, поведение не менялось (подтверждает вывод r1)

Находки

High-1 — docs-гейт красный: манифест скриншотов не совпадает ни с одним закоммиченным файлом

Скоуп: в задаче (файл docs/images/screenshots.json — часть коммитов этой ветки).

Воспроизведение:

node scripts/check-docs.mjs --external

даёт 10 ошибок вида ERROR screenshot <id>: image hash does not match manifest для view-desktop, view-touch, space-create, room-contour-close, plan-context-tray, device-editor, device-display-preview, background-editor, room-card, device-info.

Причина: коммиты 3b1ccb85 («refresh the doc capture») и 7e5a1937 («the doc capture is retaken on the rebased HEAD») переписали docs/images/screenshots.json — обновили sourceFingerprint, oxipng ("oxipng 10.2.0" → null) и imageSha256 всех 10 сценариев на новые значения — но ни разу не тронули ни один PNG-файл в docs/images/:

git diff origin/dev...HEAD --stat -- docs/images/
 docs/images/screenshots.json | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

Проверено вручную (sha256 каждого файла docs/images/*.png против записи в манифесте): фактический хэш каждого из 10 файлов совпадает со старым (dev-овым) значением, а не с тем, что теперь в манифесте — то есть capture.mjs действительно перерендерил кадры (иначе sourceFingerprint не совпал бы с текущим src/**, а он совпадает — стейл-фингерпринт не выдаётся), но получившиеся PNG никогда не были закоммичены (git add пропущен). Это ровно тот класс дефекта, о котором предупреждает AGENTS.md («докс — реальный блокер») и о котором явно сказано в брифе ревью (пропуск этого шага уже дважды стоил dev красного job docs, #230/#234) — здесь это тот же паттерн, только внутри одной задачи.

Независимо подтверждено логом CI на HEAD (job Предполётные проверки, прогон 33319669425): тот же список из 10 ERROR screenshot … image hash does not match manifest, ##[error]Process completed with exit code 1.

Чинится в скоупе: перезапустить npm run build && node demo/docs/capture.mjs на актуальном HEAD и на этот раз закоммитить и манифест, и все 10 регенерированных PNG (git add docs/images/*.png docs/images/screenshots.json), затем node scripts/check-docs.mjs --external — обязательное условие зелёного раунда.

Low (снято с записью) — AC1 (coverage-baseline) недоказан прогоном ветки, но блокер внешний и уже заведён

scripts/backend-coverage-baseline.txt остаётся плейсхолдером 80.0 — тем же, что автор дважды пометил как временный («после зелёного CI закоммичу точное значение до вердикта»). Зелёного backend-job на этой ветке не было ни разу.

Причина — НЕ код этой задачи: pytest в CI job backend (HEAD, прогон 99276949757) валится 86 тестами с одинаковой ошибкой Setup failed for custom integration 'houseplan': No setup or config entry setup function defined — и на самом dev (прогон 33317335067, job 99273097390) те же 86 тестов падают с тем же сообщением, тем же числом. Уже заведено отдельно: issue #389 «Backend-тесты HA-харнесса красные на dev с 30.08». Это не регрессия #42, а внешняя блокировка.

Важная деталь для следующего раунда: pytest всё равно ДОХОДИТ до конца и пишет coverage-отчёт несмотря на 86 упавших тестов — я вижу в логе job'а TOTAL … 68% — но шаг «Порог покрытия не ниже baseline» после него не запускается, потому что предыдущий шаг (pytest) вернул ненулевой код и GitHub Actions пропускает последующие шаги без if: always(). Число 68% — не «настоящий» бейзлайн: интеграция не поднимается в 86 тестах, огромные куски кода вообще не исполняются, так что цифра занижена тем же #389 и использовать её как реальный бейзлайн нельзя.

Не блокирую этим раундом: причина полностью внешняя и уже отслеживается в #389, а плейсхолдер не ухудшает состояние dev (там backend-job и так красный по той же причине). Но снимаю не молча: как только #389 закроется и backend-job этой ветки дойдёт до сравнения с baseline, число должно быть снято заново и закоммичено настоящим — заглушка не должна доехать до бета-гейта.

Low (снято с записью) — ruff-долг scripts/+tests_backend/ шире объявленного include, но вне CI-скоупа

pyproject.toml объявляет include на custom_components/houseplan/**/*.py, scripts/*.py и tests_backend/**/*.py, но CI (validate.yml:782) реально линтит только custom_components/houseplan. При прогоне по полному include (python -m ruff check custom_components/houseplan scripts tests_backend) — 53 находки; на самом dev таких же находок 52 (проверено на чистом чекауте dev), то есть эта ветка добавила ровно одну новую — I001 (порядок импортов) в новом файле tests_backend/test_backend_quality.py:5. ТЗ явно сузило блок 2 до custom_components/houseplan (щадящий трек, «без массового rewrite»), так что это не нарушение AC. Не блокирую, но include в pyproject.toml шире, чем то, что реально проверяется — вводит в заблуждение при чтении конфига; можно поправить include или добавить одну сортировку импорта в новом файле при следующей правке.

Low (снято с записью) — golden-расхождений на самом деле 8, не 4, но все вне скоупа #42

Автор в первом фикс-комментарии назвал 4 расходящиеся golden-сцены (device-dialog-mobile-ru, device-dialog-desktop-de, toggle-entity-dialog-mobile-ru, device-ripple-color-popover-mobile-ru). Лог job Golden-кадры на прогоне того же периода (33318774716) показывает 8: те же четыре плюс device-inbox-desktop-en-light, device-inbox-desktop-ru-dark, device-inbox-narrow-ru-dark, tray-medium-group-en. Диф #42 не касается ни иконок устройств, ни inbox/tray — все 8 объясняются тем же посторонним коммитом 2e30daa3 (#74, иконки mdi:motion-play-outline/mdi:repeat/mdi:stop-circle-outline), только затрагивает больше сцен, чем автор перечислил. Не в скоупе этой задачи (golden — зона #74/пре-релизный гейт), фиксирую как неточность подсчёта, не как находку против #42.

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

• H1/H2 из r1 — закрыты по существу (см. таблицу закрытия раунда выше).
• AC3 (ruff, CI-скоуп) — чисто.
• AC4 (mypy strict, 6 модулей) — зелёный, воспроизведено --config-file pyproject.toml (strict действительно применяется, не default-профиль).
• AC5 (сканер ERROR_CODES/ERROR_CODE_FAMILIES, оба пути эмиссии) — тест проходит; мутант «убрать флагманский код из ERROR_CODES» воспроизведён вручную и красный, как и требуется методологией ревью («тест умеет падать»). i18n-паритет 22/22/22/22.
• AC6 (фронт: JSON-details + legacy regex fallback + code-first) — test/open-passage-contract.test.mjs содержит прямой тест на _errText, зелёный; диф houseplan-card.ts читаемо реализует именно это поведение (JSON.parse → legacy regex → console.warn для сырого message → err.code fallback).
• B023-рефакторинг в wall_segment_model.py/junction_limits.py — прочитан построчно: замыкания вызываются исключительно внутри той же итерации цикла, где определены, поведенческой разницы биндинг по умолчанию не создаёт; подтверждено прогоном backend CI (строка покрытия модуля, тесты этого файла не в списке 86 упавших).
• Трейлеры и changelog — feat-коммит cec11a95 несёт User-Visible: yes и правки обоих docs/CHANGELOG*.md в этом же коммите; формулировки совпадают с фактическим изменением поведения.
• quality_scale.yaml — docs-troubleshooting/docs-examples → done корректно (USER-GUIDE.ru §22 «Диагностика» действительно существует, что я проверил grep'ом, а не поверил инвентаризации автора).
• Импорт CONF_ADMIN_ONLY, убранный из websocket_api.py при isort-правке — проверено: нигде в файле не используется (используется только в auth.py, где импорт остался) — не регрессия.

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

• Полный pytest tests_backend/ с реальным HA-harness — недоступен в песочнице ревьюера (ModuleNotFoundError: No module named 'homeassistant', как и предупреждает AGENTS.md); опирался на лог CI-прогона этой же ветки на точном HEAD, полученный и прочитанный независимо (не только со слов автора).
• npm run invariants — не гонял отдельно: диф не меняет геометрию фронтенда (src/** геометрический код не тронут), а Python-геометрия (wall_segment_model.py) — только рефакторинг замыканий без изменения формул; npm test уже прогнал JS model-invariants на всех моделях проекта и прошёл.
• Браузерные смоки demo/smoke_*.mjs — не гонял. smoke-select.mjs дал «НЕОПРЕДЕЛЁННОСТЬ» на единственной изменённой строке src/** (_serverCfg — широкий символ), а сама строка — только форматирование текста ошибки, покрытое юнитом AC6; видимого рендер-пути диф не касается.
• golden:verify вручную — не гонял; диф не может изменить рендер (только backend + текст ошибок), расхождения в CI golden проверены по логу и атрибутированы постороннему коммиту #74 (см. Low выше), не пересчитывал дифф картинок сам.
• python -m pytest tests_backend -q целиком с покрытием — не запускал локально (нет HA); совпадение цифр (366 pass/86 fail, TOTAL … 68%) взято из лога CI, не пересчитано мной построчно за пределами точечных грепов.

Вердикт

Красный: High-1 (сломанный docs-гейт, самопричинён этой веткой, в скоупе, воспроизведён и локально, и по логу CI) блокирует. H1/H2 из r1 закрыты корректно. AC1 (baseline) не в счёт вердикта — блокирован внешним, уже заведённым #389, и не регрессия этой ветки, но остаётся открытым пунктом до следующего раунда.