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

CODE-REVIEW-42-r6

• Issue: #42 — «Измеряемое инженерное качество backend»
• Этап: code (PROCESS.md §2.7)
• Заход: r6 · блокирующих циклов израсходовано (до этого вердикта) 3 из 4
• SHA: 972e708a71d7a67e7abf2ccd7d7e3876c6cc3c50
• Вердикт: жёлтый · High: 0 · Medium: 1 (в скоупе)

Скоуп раунда и почему разбор полный, а не по дельте

r5 (SHA 718c20c4) был зелёным (High 0/Medium 0). Публикация документа r5 трижды падала не на коде задачи, а на собственном гейте процесса (лимит документов ревью считал SPEC-REVIEW и CODE-REVIEW в одну корзину — заведено и исправлено как #395, 066cf44c, уже в dev). Пока задача ждала фикса, ветку пришлось ещё раз ребейзнуть на ушедший вперёд dev (принёс сам фикс #395 плюс докс-коммиты #391) — HEAD стал 972e708a.

Ребейз на ушедший вперёд dev — по правилу этого процесса (§7.2/§2.10) означает другой код, поэтому разбор в этом раунде полный, по всем AC1– AC7, а не только по тому, что задело слияние. Заново прогнаны все дешёвые гейты и вручную воспроизведены все зарегистрированные мутанты — не только принято на слово из текста r5.

Независимо подтверждено (не только текстом issue): git merge-base origin/dev HEAD = 066cf44c (текущий tip dev), git log --oneline origin/dev..HEAD даёт ровно 16 «родных» коммитов #42, ни одного чужого. Диф собственного кода #42 (src/**, custom_components/**/*.py, tests_backend/**, test/**) относительно dev изучен построчно заново (см. ниже) — по содержанию совпадает с тем, что описывал r5 (только рефренс-SHA сменился из-за ребейза).

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

r5 был зелёным — находок для закрытия нет. Таблица ниже фиксирует не «закрытие», а то, что было перепроверено заново в этом раунде, а не унаследовано вслепую:

Из какого раунда	Что перепроверено в r6	Чем подтверждено
r4→r5, M1 (сканер AC5 не парсил кортеж структурно)	Структурный разбор (field, code, message) в test_backend_quality.py	Лично внедрил третий элемент кортежа (invalid_ghost_entity_mutant_probe) в validation.py:905-916 → тест красный; откат → зелёный
r4→r5, M1c (код через переменную)	invalid_light_entity доказан поимённо	Лично удалил код из const.ERROR_CODES → тест красный; откат → зелёный
r4→r5, M2 (реюз-ключ backend не включал новые файлы)	scripts/gate-reuse.mjs roots содержат tests_backend, pyproject.toml, scripts/backend-coverage-baseline.txt	Прочитал текущий HARNESS.backend.roots — все три входа на месте; node --test test/gate-reuse.test.mjs → 13/13
r3→r5 (mypy strict allowlist)	6/6 модулей действительно проходят mypy --strict	Прогнал mypy --config-file pyproject.toml в изолированном venv → «Success: no issues found in 6 source files»
r1→r5 (fail-closed AC5-сканер для непроверяемого источника кода)	Ветка «MarkerControlError с непрослеживаемым аргументом»	Лично внедрил MarkerControlError(untracked_mutant_var, ...) → сканер упал с явным сообщением «cannot prove»; откат

Унаследовано из r5 (без личного перезапуска тяжёлых job)

Что	Документ/SHA-источник	Почему можно не гонять заново
Полный HA-harness pytest tests_backend/ (453 passed/2 skipped, coverage 87.2%==baseline)	CODE-REVIEW-42-r5, живой Validate run 33326532290 на SHA 718c20c4	Независимо перепроверил через gh run view — job «Бэкенд: pytest в Home Assistant» = success, лог содержит точно coverage: 87.2% (baseline 87.2%), 453 passed, 2 skipped, collected HA-harness tests: 203. Вход job (tests_backend/**, custom_components/**/*.py, pyproject.toml, baseline-файл) не менялся между 718c20c4 и 972e708a — сверено построчным дифом каждого файла в этом документе ниже
golden:verify, 3 смок-шарда, perf-smoke	Тот же run 33326532290	Все 4 job = success на этом же прогоне; src/** не менялся с полностью смок-протестированных r3/r4 (единственный диф в houseplan-card.ts — тот же, что был на r1-r5, smoke-select подтверждает «1 файл, 1 символ»)
USER-GUIDE.ru §22 «Диагностика», docs-examples YAML	r3/r5	git diff origin/dev...HEAD -- docs/USER-GUIDE*.md = пусто в этом раунде — контент не менялся вообще, значит и вывод не может измениться
Живой Validate-прогон на текущем SHA 972e708a	—	Run 33328530255: reuse-job «Переиспользование: это дерево уже проверено» = success, поэтому backend/golden/3-смока/perf идут skipped — реюз, не пропуск. Проверил основание сам: входы реюз-ключа backend (tests_backend, custom_components/**/*.py, pytest.ini, pyproject.toml, baseline-файл) байт-в-байт совпадают с деревом 718c20c4, потому что единственные коммиты между ними — докс/бандл (см. дифф-статы ниже)

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

Прогнал сам (зелёного Validate на 972e708a нет — единственный завершённый прогон 33328530255 красный на «Предполётных проверках», см. находку про process-gate ниже; тяжёлые job на нём skipped по легитимному реюзу, проверено отдельно):

• npx tsc --noEmit — чисто.
• npm test — 1647 passed / 0 failed / 1 skipped.
• npm run bundle:sync (= build + bundle-sync.mjs) — git status после прогона пуст, диска не тронул (никакого diff в dist/, custom_components/houseplan/frontend/, demo/srv/assets).
• node scripts/bundle-budget.mjs — 284047/300000 (запас 15953 Б).
• node scripts/no-new-any.mjs --base origin/dev --head HEAD — «Новых any нет» (36 добавленных строк в 1 файле).
• node scripts/check-docs.mjs --external — «Documentation checks passed (7 files, 10 external links)».
• Изолированный venv (python3 -m venv, сеть в песочнице доступна):
  • ruff==0.16.5 check custom_components/houseplan (ровно CI-скоуп из validate.yml:788) — «All checks passed!».
  • mypy --config-file pyproject.toml на всех 6 модулей allowlist — «Success: no issues found in 6 source files».
  • Pure-pytest (tests_backend, кроме test_ha_websocket.py и test_coordinate_canonicalization.py — тянут homeassistant, которого в песочнице нет) — 244 passed, 1 skipped.
  • tests_backend/test_backend_quality.py отдельно — 3/3.
• Мутанты (все 5, включая незарегистрированную в mutation-gate.mjs fail-closed ветку) воспроизведены руками правкой файла, прогоном теста, откатом; git status после каждого — чист:
  • м1 (invalid_space_id удалён из ERROR_CODES) → красный.
  • м1b (регэксп class-attr в сканере затихшен) → красный.
  • м1c (invalid_light_entity, код через переменную, удалён из ERROR_CODES) → красный.
  • структурный тест кортежа (инъекция invalid_ghost_entity_mutant_probe третьим элементом) → красный.
  • fail-closed для непрослеживаемого аргумента MarkerControlError → красный с явным сообщением сканера.
  • м2 (JSON-ветка _errText вырезана) → node --test test/open-passage-contract.test.mjs красный (1 fail из 8).
• node --experimental-test-coverage --test test/gate-reuse.test.mjs — 13/13.
• i18n-паритет: en/ru/de/fr — по 1189 ключей каждый, множества ключей идентичны (сверено программно, не только count).
• node scripts/smoke-select.mjs --base origin/dev --head HEAD — НЕОПРЕДЕЛЁННОСТЬ (1 файл src/**, широкий символ _serverCfg, порог 41). Браузерные смоки и golden:verify лично не гонял — см. таблицу «Унаследовано» выше (тот же код уже зелёный в живом CI на 718c20c4, src/** не менялся с той проверки).
• EVENT_NAME=push BEFORE_SHA=$(git rev-parse origin/dev) BASE_SHA=$(git rev-parse origin/dev) HEAD_SHA=$(git rev-parse HEAD) DEVELOPMENT_BRANCH=dev node scripts/process-gate.mjs --github-range --issues — «гейт пройден, предупреждений 1» (см. WARN-находку ниже).
• Прочитал построчно (не исполнял — не геометрия/поведение): custom_components/houseplan/wall_segment_model.py, custom_components/houseplan/junction_limits.py — диф только type hints и связывание loop-переменных параметрами по умолчанию (B023-рефакторинг); одна удалённая мёртвая переменная zero_segments (F841) — подтвердил grep, что она нигде больше не читается. Behaviour-preserving; npm test уже гоняет инварианты модели на фикстурах проекта и прошёл. npm run invariants отдельно не гонял — геометрия по чтению не менялась.
• Trailers: все 16 коммитов несут Issue: #42; ровно один (323b7803) — User-Visible: yes, и он же в одном коммите правит оба docs/CHANGELOG.md/docs/CHANGELOG.ru.md.

Находки

Medium (в скоупе, чинится в этой же ветке)

Mypy strict (блок 3, AC4) не имеет механизма исполнения в CI — только текстовый контракт-тест, который его не проверяет.

Спецификация (rev6, блок 3) вводит mypy strict как один из пяти инженерных гейтов issue наравне с coverage и ruff. Реализация: pyproject.toml содержит [[tool.mypy.overrides]] с allowlist из 6 модулей и strict = true; tests_backend/test_backend_quality.py:: test_issue_42_mypy_strict_allowlist_only_grows — но этот тест не запускает mypy вообще: он текстовым regex'ом сравнивает committed-список модулей с зафиксированным множеством и падает только при удалении модуля из списка. Он не может обнаружить, что код внутри allowlist-модуля перестал проходить strict-проверку.

Ни в одном workflow (validate.yml, mutation-gate.yml — проверил оба, и вообще grep -rl mypy .github/workflows/ пуст) нет шага, который бы запускал mypy. mypy также не пиновится в tests_backend/requirements.txt — файл содержит ruff==0.16.5 с явным комментарием «#42: линт бэкенда... ставится отсюда же», но эквивалентной строки для mypy нет. То есть CI физически не может прогнать mypy сегодня — не установлен.

Итог: «mypy strict зелёный на стартовом allowlist» проверяется только вручную ревьюером в момент код-ревью (я лично прогнал — 6/6 чисто, см. выше), а не автоматически. Достаточно любого следующего PR, трогающего const.py/projection.py/plans.py/… без явного намерения нарушить типизацию, и strict-регрессия войдёт в dev полностью незамеченной: CI останется зелёным. Это прямо противоречит цели issue («измеряемое инженерное качество») — для coverage и ruff issue построил именно такой continuous-гейт (шаги «Линт бэкенда» и «Порог покрытия» в validate.yml:787-816), а для typing — нет, хотя структурно это тот же самый паттерн и добавляется тем же способом.

Формально ли это нарушение AC4? Нет — AC4 сама помечена в тексте ТЗ как «(локально)» (в отличие от AC1/AC2 — «(CI)»), и в этом узком смысле код соответствует букве. Но эта деталь формулировки ТЗ ни разу не поднималась и не обсуждалась ни в одном из 4 раундов SPEC-REVIEW (все они были посвящены исключительно блоку 5 — контракту кодов ошибок) — она не результат осознанного арбитража, а незамеченный побочный эффект формулировки. По существу задача решает сценарий «типизация может тихо деградировать без сигнала» ХУЖЕ, чем декларирует собственный заголовок issue, и это ровно тот класс вопроса («изменение не решает заявленный сценарий»), который жёлтый вердикт вправе поднимать при формально выполненных AC.

Как чинится в скоупе (маленькая, локальная правка, по образцу уже существующего ruff-шага):

1. добавить mypy с пином в tests_backend/requirements.txt (комментарий по аналогии со строкой ruff);
2. добавить шаг в validate.yml после «Линт бэкенда»: python -m mypy --config-file pyproject.toml -p custom_components.houseplan.const -p custom_components.houseplan.projection -p custom_components.houseplan.coordinate_canonicalization -p custom_components.houseplan.frontend_asset_manifest -p custom_components.houseplan.junction_limits -p custom_components.houseplan.plans (список модулей уже есть в pyproject.toml — можно даже читать его оттуда скриптом, но это опционально);
3. обновить scripts/gate-reuse.mjs не требуется — pyproject.toml уже входит в roots backend job (M2 r4).

Технический вопрос (как именно провести mypy через CI), не продуктовый — не выносится владельцу, решение предложено выше.

Low (снято с записью, не блокирует)

1. pyproject.toml [tool.ruff] include перечисляет scripts/*.py и tests_backend/**/*.py наравне с custom_components/houseplan/**/*.py, но CI линтит только custom_components/houseplan (validate.yml:788, соответствует явному тексту блока 2 спецификации). Если запустить ruff check по всему include-набору — 56 находок (E402×22, I001×12, B023×7 — в том числе в tests_backend/test_validation.py:449-456, тот же класс, что чинился в этом issue, но не исследованный, — B017×5, F401×3, E702×3, F811×2, E401×2). Все они в коде, который #42 не трогал (проверено: git diff origin/dev...HEAD -- tests_backend/test_validation.py меняет только одну JSON-ассерцию, строки 449-456 не задеты) и вне объявленного спецификацией CI-скоупа. Конфиг вводящий в заблуждение (создаёт впечатление более широкого линта, чем реально исполняется), но не является регрессией этого issue и не ломает ни один AC — оставляю без действия в рамках #42, можно поправить include отдельной мелкой задачей при следующем контакте с pyproject.toml.
2. process-gate красный на живом CI SHA 972e708a (run 33328530255, шаг «Процессный гейт»): FAIL п.8 статус issue - issue #395: статус не проставлен. Тот же класс гонки BEFORE_SHA, что уже документирован и признан не дефектом #42 в CODE-REVIEW-42-r3 и -r5 (в этот раз попутный коммит — 066cf44c вместо #392/#394). Независимо подтверждено: пересчёт с корректным BASE_SHA = текущий tip dev даёт диапазон в 16 «родных» коммитов #42 и гейт проходит (см. «Как проверялось» выше). Не блокирует; не заводил отдельный issue — класс дефекта уже задокументирован в scripts/process-gate.mjs по трём предыдущим инцидентам, четвёртый инцидент того же класса не даёт нового знания.
3. WARN п.0 классификации путей (custom_components/houseplan/ quality_scale.yaml, pyproject.toml — вне классов A/B/C/D) — тот же пункт, что отмечен Low в r5, инструментальный пробел вне скоупа #42, не блокирует.

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

• AC1/AC2 (coverage-гейт CI, защита от тихого скипа harness) — доказаны живым прогоном ветки (718c20c4, независимо перечитан лог: 453 passed/2 skipped, coverage 87.2%==87.2%, collected 203 ≥ 50).
• AC3 (ruff narrow, noqa с причиной) — чисто в объявленном CI-скоупе; каждый noqa: BLE001 в диффе несёт причину ≥10 символов (проверил все найденные noqa-строки в websocket_api.py/http_api.py глазами).
• AC4 (mypy strict, allowlist только растёт) — сам allowlist корректен и проходит strict (см. Medium выше про отсутствие continuous-проверки).
• AC5 (сканер обоих путей эмиссии кодов) — 48 кодов + 3 семейства, структурный разбор кортежа, fail-closed для непрослеживаемых источников — все ветки лично воспроизведены как красные при поломке.
• AC6 (JSON details + fallback + code-first) — _errText code-first, сырой английский текст уходит в console.warn, JSON.parse с legacy regex-фоллбэком; юнит-тест 8/8, мутант m2 воспроизведён красным.
• AC7 — pure-pytest 244 (≥240 из ТЗ), бюджет бандла в пределах, i18n 1189×4 без расхождений.
• Trailers/changelog — 16/16 коммитов с Issue: #42; единственный User-Visible: yes правит оба CHANGELOG в одном коммите.
• Unused-import/dead-code чистка (F401×~6, F841×2) в __init__.py, import_export.py, websocket_api.py, plans.py — построчно проверил, что удалённые имена (FILES_URL, PLANS_URL, CONF_ADMIN_ONLY, copy, old_refs, zero_segments) больше нигде в своих модулях не используются — не регрессия.
• wall_segment_model.py/junction_limits.py — B023-рефакторинг и type-hints, поведение не менялось (построчное чтение + npm test зелёный на фикстурах).

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

• Полный HA-harness pytest tests_backend/ лично (нет homeassistant в песочнице) — опёрся на лог живого CI-прогона 718c20c4 (33326532290), независимо перечитанный, плюс подтверждённое совпадение входов реюз-ключа с текущим SHA.
• Браузерные смоки (demo/smoke_*.mjs) и golden:verify лично не гонял — smoke-select дал НЕОПРЕДЕЛЁННОСТЬ, но src/** не менялся с уже полностью смок-протестированных r3/r4, и все job зелёные в живом CI на 718c20c4; реюз-ключ на 972e708a подтверждает те же входы.
• Performance-профили — не названы в AC, диф не затрагивает чувствительные к перфу пути.
• npm run invariants -- --config <...> отдельной командой — диф геометрических модулей ограничен type hints и B023-биндингом (поведенчески эквивалентен), npm test уже прогоняет инварианты на моделях проекта и прошёл.
• Полный ruff по всему pyproject.toml-include (только CI-скоуп) — см. Low-1.