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

CODE-REVIEW-42-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/42
• ТЗ: docs/specs/042-backend-engineering-quality.md, ревизия 6 (принята арбитражем владельца после исчерпания бюджета SPEC-REVIEW, 4/4)
• Диапазон материала: origin/dev..HEAD, HEAD = ab337193abb8c629322313a0bf2d747105942db4
• Коммиты: 313dfd07 (feat, User-Visible: yes) · ffe8c3d1 (test) · cfa8b5af (test) · ab337193 (build: bundle sync)
• Заход код-ревью: r1, блокирующих циклов израсходовано 0 из 4 до этого вердикта
• Трейлеры: у всех 4 коммитов корректны (Issue: #42, User-Visible: yes|no); User-Visible: yes на 313dfd07 сопровождён правками обоих changelog в том же коммите — выполнено.

Скоуп

Полный трек (не small), диапазон затрагивает класс A (custom_components/houseplan/**/*.py, src/houseplan-card.ts, src/i18n/*.json), класс B (.github/workflows/validate.yml, .github/workflows/mutation-gate.yml, scripts/mutation-gate.mjs, test/**, tests_backend/**, pyproject.toml, requirements_test.txt), класс C (docs/**) и класс D (dist/**, custom_components/houseplan/frontend/**, коммит ab337193 — bundle-sync после feat, по правилу класса D корректен). Первый код-ревью раунда — разбор полный по всем пяти блокам ТЗ, дельта по спецификации (§2.10) здесь неприменима: это код-ревью, а не повторный спек-раунд.

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

Зелёного Validate на HEAD (ab337193) не существует — оба прогона CI на этой ветке (33316584357, 33316653216) красные на фронтенд- и **бэкенд-**джобах. Прогнал дешёвые гейты сам и независимо воспроизвёл обе причины красноты локально (см. таблицу и находки High).

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	чисто
Frontend unit	npm test	1636/0, 1 skipped — совпадает с хендоффом
Build + bundle sync	npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js	совпадает байт-в-байт
Bundle budget	npm run bundle:budget	282 738 / 300 000 B gzip — совпадает с хендоффом
no-new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	КРАСНЫЙ — см. Finding H1
check-docs (src/** тронут)	node scripts/check-docs.mjs	чисто (7 файлов, 10 внешних ссылок)
i18n паритет	скрипт сверки ключей en/ru/de/fr	22/22/22/22 добавленных ключа идентичны по имени во всех 4 словарях
Backend install (как в CI)	pip install -r requirements_test.txt в чистом venv	КРАСНЫЙ — воспроизведено независимо от CI, см. Finding H2
Backend pure pytest (изолированный venv без застрявшего requirements_test.txt)	pytest tests_backend/test_backend_quality.py -q	3/3 пройдено
— то же, test_validation.py	pytest tests_backend/test_validation.py -q	142 passed, 1 skipped
ruff (узкий набор, установлен вручную вне сломанного requirements_test.txt)	ruff check custom_components/houseplan --config pyproject.toml	«All checks passed!»
mypy strict (6 модулей allowlist)	mypy -p const -p projection -p coordinate_canonicalization -p frontend_asset_manifest -p junction_limits -p plans	«Success: no issues found in 6 source files»
Мутанты AC5 (ручная проверка m1c)	удалил invalid_light_entity из ERROR_CODES, перезапустил test_backend_quality.py	тест упал ожидаемо, затем восстановлено (git status чист)
smoke-select	node scripts/smoke-select.mjs --base origin/dev --head HEAD	«НЕОПРЕДЕЛЁННОСТЬ»: диф трогает 1 файл src/**, единственный широкий символ _serverCfg — ни один смок не привязан доказуемо. Решение: не гонять смоки — AC6 покрыт юнитом, поведение _errText не имеет отдельного визуального следа
golden / performance / полный HA-harness	—	не гонялись: не изменяют визуал/перф; предрелizный гейт (§8)
python -m pytest tests_backend -q (полный, с HA)	—	невозможно в песочнице — homeassistant не установлен, .venv-backend отсутствует (см. AGENTS.md «Backend»); эквивалент — независимая проверка через изолированный venv + чтение кода

Находки

High H1 — no-new-any красный на HEAD: новый необоснованный any

src/houseplan-card.ts:9743 (добавлено 313dfd07):

const space = this._serverCfg?.spaces?.find((item: any) => String(item.id) === spaceId);

_serverCfg типизирован (ServerConfig), и везде рядом spaces используется без нового any (this._serverCfg?.spaces || [], .spaces.length и т.д. — уже типизированный массив). Аннотация : any здесь не обоснована ни отсутствием типа, ни комментарием // any-ok: …. Гейт scripts/no-new-any.mjs (обязательная часть локального набора, §8) красный и на CI (job «Фронтенд: типы, юниты, мутанты, синхрон бандла», оба прогона ветки), и локально — воспроизведено дословно тем же выводом.

Чинится в скоупе: убрать : any (тип элемента spaces выводится сам) либо использовать точный тип элемента.

High H2 — requirements_test.txt невозможно установить: бэкенд-CI не работал ни разу

requirements_test.txt пинует одновременно:

pytest==9.1.1
pytest-homeassistant-custom-component==0.13.45
pytest-cov==7.1.0

но pytest-homeassistant-custom-component==0.13.45 сам жёстко требует pytest==7.3.1 и pytest-cov==3.0.0 (проверено чтением METADATA пакета). Это неразрешимый конфликт версий, а не транзиентная сетевая ошибка:

• воспроизведено в CI дважды подряд, на обоих прогонах ветки (30f45e53, ab337193): pip install -r requirements_test.txt → ResolutionImpossible;
• воспроизведено независимо в чистом sandbox-venv (не CI-окружение) той же командой — идентичная ошибка.

Это ровно Блок 1 ТЗ («requirements_test.txt — единая точка правды зависимостей»), и он ломает весь бэкенд-джоб CI: до pytest дело не доходит вообще — ни ruff-шаг, ни guard тихого скипа harness, ни сам pytest с --cov, ни сравнение с baseline. Следствия:

• AC1 (coverage.xml + сравнение с baseline) не доказан прогоном ветки, как того явно требует сама формулировка AC1 — прогона просто не было ни разу;
• AC2 (защита от тихого скипа harness) не доказан по той же причине;
• scripts/backend-coverage-baseline.txt остаётся плейсхолдером 80.0, который автор в хендоффе прямо назвал заглушкой и обещал заменить «после зелёного CI» — зелёного CI не случилось, обещание не выполнено, а нормативный текст ТЗ (раздел «Принятые предположения») требует закоммитить фактическое число до код-ревью;
• заявление хендоффа «pytest pure 243/0» не могло быть получено прогоном именно этого requirements_test.txt (независимо перепроверено: сборка зависимостей по этому файлу невозможна в принципе, а не «медленная» или «требует HA»); откуда взято число — не сказано, и с той же командой из ТЗ оно не воспроизводится;
• зеркало в .github/workflows/mutation-gate.yml:67 ставит зависимости той же командой — мутационный гейт по Python-гвардам (error-code-dropped-from-contract, error-scanner-loses-a-class-source, error-code-via-variable-dropped) в CI тоже не может выполниться.

Логика самих CI-шагов (сравнение с baseline, порог ≥50 для test_ha_*, upload артефакта) прочитана и выглядит корректной — проблема ровно в пиннинге зависимостей, не в механизме.

Чинится в скоупе: привести requirements_test.txt к разрешимому набору (например, снять собственный пин pytest-cov/pytest до версий, совместимых с pytest-homeassistant-custom-component==0.13.45, либо поднять pytest-homeassistant-custom-component до версии, допускающей pytest-cov==7.1.0 — выбор версии оставлен автору), прогнать реальный CI на итоговом коммите и закоммитить фактический baseline до повторного ревью.

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

• Блок 5 (WS error contract), логика сканера — прочитан построчно и проверен исполнением в изолированном venv: ERROR_CODES/ERROR_CODE_FAMILIES (const.py) и сканер (tests_backend/test_backend_quality.py) корректно находят оба пути эмиссии — литералы send_error, четыре validation-класса с code = "...", JunctionLimitError (f-string семейство), MarkerControlError литералами И через переменные (source_error/attribute_error, кортеж code). Мутант m1c (удаление invalid_light_entity из ERROR_CODES) вручную воспроизведён — тест падает с понятной ошибкой, затем код восстановлен и git status чист.
• i18n: 22 новых ключа backup.error.* добавлены идентично и полно во всех 4 словарях (en/ru/de/fr) — сверено скриптом, не только заявлением автора.
• _errText code-first (AC6, M2 r1): порядок проверок в houseplan-card.ts:9765 — код проверяется раньше e.message; JSON.parse первым, legacy regex — read-compat fallback с deprecated-комментарием и датой; неизвестный код рендерит err.code/err.unknown, а не сырой e.message (уходит в console.warn). Прочитано построчно, поведение соответствует тексту ТЗ блока 5.
• mypy strict allowlist (AC4): прогнан исполнением на всех 6 модулях — чисто. junction_limits.py (геометрия!) проверен построчно на предмет поведенческих изменений: диф — исключительно добавление type hints (dict[str, Any], list[float] и т.п.), логика функций не тронута ни в одной строке — инварианты модели (npm run model-invariants) не требуются, т.к. геометрическое поведение не менялось (проверено чтением, не исполнением).
• ruff narrow (AC3): прогнан исполнением — чисто; noqa-контракт-тест (test_issue_42_every_noqa_carries_a_reason) проверен — все новые noqa: BLE001 в websocket_api.py/http_api.py несут причину ≥10 символов.
• Structured JSON details: OpeningPassageError/PartitionOpeningJambMarginError теперь сериализуют json.dumps(...); test_validation.py обновлён на json.loads(...) и по-прежнему проверяет отсутствие утечки binary_sensor в сообщении; прогнан исполнением — зелёный.
• quality_scale.yaml: docs-troubleshooting/docs-examples → done — проверено, что docs/USER-GUIDE.ru.md уже содержит «## 22. Диагностика» до начала работы над #42 (введено в v1.59.0-rc.2, задолго до этого issue) — заявление хендоффа о ложном пробеле («инвентаризация грепала английское слово») подтверждено; никакой недостающей работы по документации не скрыто.
• Changelog×2, ARCHITECTURE.md: правки внесены в том же коммите 313dfd07, что и поведение; описывают ровно видимое изменение (локализованные тексты ошибок).
• Одно число — один источник: этот дифф не вводит новую пользователем видимую величину, дублируемую в двух местах. margin_cm/fields — единственное место рендера (_errText), источник один (JSON от бэкенда), изменился только формат парсинга (JSON вместо regex), а не число мест вычисления. test/single-source-numbers.test.mjs не входит в затронутый диапазон и не требовал перепрогона.
• Коммиты класса B (ffe8c3d1, cfa8b5af) корректно переиспользуют Issue: #42, User-Visible: no.

Чего не проверял и почему

• Полный pytest tests_backend/ -q с реальным HA-harness — недоступен в песочнице (homeassistant не установлен, .venv-backend отсутствует); по AGENTS.md это ожидаемо для этого окружения. Компенсировано изолированным venv для «чистых» файлов (test_backend_quality.py, test_validation.py) и чтением остального с исполнением мутанта.
• Полный код websocket_api.py (925 строк) построчно — диф в этом файле (168 строк) целиком мехнический (реордер импортов + noqa-причины); прочитан полностью, поведенческих изменений вне диффа не искал построчно по всему файлу — вне скоупа диффа.
• Браузерные смоки — не гонялись; smoke-select.mjs вернул «НЕОПРЕДЕЛЁННОСТЬ» (единственный тронутый src-файл, единственный широкий символ _serverCfg), в АС ни один смок не назван. Решение снять — риск узкий (текстовый рендер ошибки), покрыт юнитом AC6.
• golden/performance/полный HA-harness — предрелизные гейты (§8, §11.4), не гейт этого ревью; диф не меняет визуал/геометрию рендера.
• import_export.py, http_api.py, __init__.py, frontend_assets.py, trails.py — прочитаны целиком по своим (коротким, 1–22 строк) диффам: везде реордер импортов / удаление неиспользуемых (F401) / добавление причины к noqa, поведенческих изменений не обнаружено.

Вердикт

Красный. Оба High-находки — не стилистические придирки: no-new-any красный на HEAD и requirements_test.txt невозможно установить — это ровно те «дешёвые гейты», которые обязаны быть зелёными перед выходом из «В разработке» (§8), и они не были зелёными ни разу за оба прогона CI этой ветки. Раз ревью кода отвечает на вопрос «оно вообще работает» вместо ручного тестирования — ответ по бэкенд-блоку (Блок 1/4, AC1/AC2) сейчас «не проверено ни разу», а не «работает». Оба фикса локальны и в скоупе задачи (одна аннотация типа; пересборка одного файла зависимостей), пятого повторного цикла не требуют технически, но по букве процесса должны пройти повторный код-ревью после исправления (§4).