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

CODE-REVIEW-329-r2

Issue: #329 — экстремально острая вершина комнаты рендерится «трезубцем»; ограничения на стыки стен. Заход: r2. Предыдущий цикл (r1) — вердикт красный, High: 1, Medium: 4, документ docs/reviews/CODE-REVIEW-329-r1.md, получен на SHA e1df015d (коммит «docs: review document for #329», после которого автор добавил четыре коммита закрытия находок).

Скоуп разбора (§2.9)

Дельта r1→r2 — 4 коммита, 12 файлов, +301/-191:

0824e510 test: prove AC10 — Optimize adds no junction violation (#329 M4)
574fea98 docs: one limits section, and Resize does raise a toast (#329 M2, M3)
8f0b6b97 refactor: drop the chamfer helpers the honest apex made dead (#329 M1)
0bb42cae fix: the backend judges both sides after the same migration (#329 H1)

Файлы: custom_components/houseplan/junction_limits.py, src/wall-thickness.ts, test/junction-limits.test.mjs, tests_backend/test_junction_limits.py, scripts/mutation-gate.mjs, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md, docs/specs/329-junction-limits.md, docs/images/screenshots.json, dist/houseplan-card.js, custom_components/houseplan/frontend/houseplan-card.js.

Каждый коммит — прямое закрытие одной находки r1 (H1, M1, M2+M3, M4), rebase на ушедший вперёд dev не производился (дельта считается от r1-документа, ветка не двигалась), новая подсистема не задета, поведенческий контракт не меняется — он чинится до заявленного. Разбор ограничен дельтой плюс всем, до чего она дотягивается (backend-паритет AC9, AC10, §4/AC6 честная вершина — см. ниже). П1–П5 как таковые (AC1–AC5), AC7a/AC7b, AC8 дельтой не задеты — унаследованы.

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

Прогнано (SHA 0824e510):

• npx tsc --noEmit — чисто.
• npm test — 1389 passed, 1 failed, 1 skipped (см. находку r2-H1 ниже). Функциональные тесты этой дельты, включая новые AC10-юниты (ok 493, ok 494) и переписанные бэкенд-паритетные фикстуры, — все зелёные; падает отдельный метатест реестра мутантов.
• npm run build + сверка бандлов: dist/houseplan-card.js == custom_components/houseplan/frontend/houseplan-card.js (байт-в-байт), пересборка с нуля идентична закоммиченному dist (diff пуст).
• node scripts/check-docs.mjs — «Documentation checks passed (7 files, 10 external links)» — отпечаток docs/images/screenshots.json (единственный файл дельты в docs/, пересчитанный после правки src/wall-thickness.ts) валиден.
• python3 -m pytest tests_backend/test_junction_limits.py -q — 8 passed (окружение не несло pytest изначально; установлен локально pip3 install pytest pytest-asyncio, что и позволило прогнать гейт, а не просто прочитать код). Дисциплина «тест умеет падать»: вручную откатил патч мутанта junction-limit-backend-raw-baseline (migrated, _ = commit_wall_segment_model(config) → migrated = config) — 2 из 8 тестов падают (test_legacy_baseline_is_judged_after_the_same_migration, test_a_write_that_adds_a_violation_is_refused_with_a_stable_code), затем восстановил файл — тест 8/8 подтверждён на исходном коде.
• npm run bundle:sync && npm run golden:verify — вся матрица (~80 сцен, включая sharp-apex-legacy-dark и junction-owner-repro-dark) — зелёная, 0 отказов. Нужен был, поскольку M1 правит геометрический файл wall-thickness.ts; удаление мёртвого кода подтверждено эмпирически — ни один кадр не сдвинулся.
• node scripts/mutation-gate.mjs --check — реестр анкеров цел (совпадает с прошедшим юнитом «every mutant patch anchors exactly once», ok 688).
• node scripts/smoke-select.mjs --base e1df015d --head HEAD — «дифф исполняемый, но ни один смок не связан доказуемо»; единственный символ дельты в src/**, которого нет в смоках, — DEGENERATE_APEX_MAX_DEGREES, но дельта его не меняет (значение и семантика те же, переставлен только JSDoc-комментарий при удалении соседних мёртвых функций). Решение: смоки не гоняю — это чистое перемещение комментария, а не новый контракт; поведенческую часть уже покрывает golden:verify (зелёный целиком).

Не прогонялось: полный HA-harness (pytest tests_backend целиком падает при сборе — ModuleNotFoundError: homeassistant, voluptuous; тот же пробел был и в r1, дельта его не устраняет и не обязана). Полная матрица браузерных смоков и мутантов — дельта не даёт для этого повода (см. вывод smoke-select.mjs выше); она предрелизный гейт, не гейт ревью.

Находка r2 (High, в скоупе — блокирует)

r2-H1. Новый мутант ломает npm test, то есть красный CI-гейт validate.yml

scripts/mutation-gate.mjs (коммит 0bb42cae, закрытие H1) добавляет запись junction-limit-backend-raw-baseline с

guard: 'python3 -m pytest tests_backend/test_junction_limits.py -q',

test/mutation-gate.test.mjs:33 («every guard command points at a file that exists») требует, чтобы guard называл .mjs-файл — конвенция, которой следуют ВСЕ остальные бэкенд-мутанты в этом же реестре (node scripts/backend-test-guard.mjs <pattern> [<file>], см. строки 1061, 1073, 1099, 1156, 1223, 1541, 1766, 1777, 1788, 1799, 1810, 1856, 3025, 3037, 3049). Новая запись — сырой python3 -m pytest ... без .mjs, и .split(' ').find(part => part.endsWith('.mjs')) возвращает undefined.

Воспроизведено исполнением: npm test на HEAD (0824e510) — # fail 1, тест 689 падает с junction-limit-backend-raw-baseline: guard не называет исполняемый файл. Проверено дважды (npm test целиком и точечно node --test test/mutation-gate.test.mjs) — не флейк. .github/workflows/validate.yml:282 гоняет именно npm test, значит CI на этой ветке красный по этой же причине.

Функционально мутант работает и семантически осмыслен (я вручную применил его патч и подтвердил, что он ловит регресс H1 — 2/8 тестов падают, откат правки восстанавливает 8/8); дефект чисто в форме guard, не в сути защиты. Это не довод в пользу «оставить как есть»: npm test — обязательный дешёвый гейт этого самого ревью, и он красный на проверяемом SHA.

Нужно: привести guard к конвенции реестра, например node scripts/backend-test-guard.mjs test_legacy_baseline_is_judged_after_the_same_migration tests_backend/test_junction_limits.py (или обеими новыми тестами через -k "test_legacy_baseline_is_judged_after_the_same_migration or test_a_write_that_adds_a_violation_is_refused_with_a_stable_code", если нужно ловить оба). Однострочная правка, но npm test должен быть зелёным на SHA, уходящем в dev.

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

Находка r1	Чем закрыта	Где видно
H1 (High) — бэкенд судит легаси-базу сырой, отклоняет несвязанную правку	0bb42cae: validate_junction_limits гоняет и previous, и candidate через новую _migrated_spaces() → commit_wall_segment_model до подсчёта	junction_limits.py (диф выше); тест test_legacy_baseline_is_judged_after_the_same_migration — 8/8 pytest; мутант junction-limit-backend-raw-baseline вручную подтверждён (2/8 падают без фикса)
M1 — мёртвый код apexCaps/clipPolygonOutsideCap/degenerateApexCaps	8f0b6b97: поле интерфейса и обе функции удалены целиком, JSDoc над wallBodiesGeometry возвращён на место	grep -rn по всему репо (кроме текста самого r1-документа) — не находит; golden:verify вся матрица зелёная — поведение не изменилось
M2 — раздел «Ограничения стыков стен» задвоен в RU-гайде	574fea98	docs/USER-GUIDE.ru.md — ровно один заголовок ### Ограничения стыков стен (строка 420)
M3 — гайд (RU+EN) описывает Resize как «просто останавливается», хотя тост есть	574fea98: текст переписан — «…и один раз за жест поясняет тостом, какое правило дальше нарушится»	docs/USER-GUIDE.md/.ru.md (диф выше); код _rszMove (src/houseplan-card.ts:9183-9191, resize.limit_stopped + _junctionLimitLabel) не менялся — он и раньше показывал тост, теперь описан верно
M4 — AC10 (Optimize не добавляет нарушений) не доказан	0824e510: два юнит-теста в test/junction-limits.test.mjs, считающие нарушения тем же способом, что барьер записи (обе стороны через commitWallSegmentModel/commit_wall_segment_model)	npm test — ok 493, ok 494; первый тест на фикстуре владельца, второй — граничный случай П4 (узлы ровно в 5 см), явно проверяет, что база несёт нарушение (не доказывает пустоту)

Все пять находок r1 закрыты по существу, с наблюдаемым следом в коде/тестах, а не только заявлением автора. Ни одна не переоткрыта.

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

Не тронуто дельтой r1→r2, повторно не проверялось — принято по документу docs/reviews/CODE-REVIEW-329-r1.md, SHA e1df015d:

• AC1–AC5 (П1–П5 как юнит-предикаты с границами) — test/junction-limits.test.mjs до строки 216 дельтой не изменён (только дополнен снизу тестами AC10).
• §4/AC6 (честная вершина легаси-апекса + golden-сцена sharp-apex-legacy-dark) — логика самого предиката (isDegenerateApexCorner) не менялась, только удалён неиспользуемый код вокруг неё; повторно подтверждено попутно этим раундом через golden:verify (зелёный), но отдельного разбора алгоритма не требовалось.
• AC7a/AC7b (Resize/«Толщина»: смок через настоящий pointer-жест, байт- неизменность плана, текст объяснения/тоста) — код и смоки не в дельте; M3 правил только прозу гайда, не контракт и не тест.
• AC8 (скоуп применения — какие поверхности проверяются) — не в дельте.
• Риски, откат, release-артефакты, паритет чисел П1–П4 (кроме самого способа получения базовой линии, который и есть H1) — не в дельте.

Что проверено и корректно (сверх таблицы выше)

• docs/CONFIG-COMPATIBILITY.md — новый абзац про обязательность миграции базовой линии и явное указание обеих реализаций (commitWallSegmentModel / commit_wall_segment_model) фактически точны: обе функции существуют и вызываются ровно там, где написано.
• docs/specs/329-junction-limits.md — ревизия 7 честно фиксирует все пять закрытий и не вводит новых продуктовых решений задним числом.
• Обработка except Exception в _migrated_spaces() (бэкенд): падение миграции не становится вердиктом этого валидатора — по коду до этой точки уже должен был отработать барьер модели стен, так что это защитный, а не рабочий путь; не создаёт регресса H1, так как обе стороны получают одинаковую (либо мигрированную, либо сырую при одинаковом сбое) трактовку независимо друг от друга только в теории — на практике оба документа уже прошли барьер записи раньше в конвейере.
• Трейлеры всех 4 коммитов — Issue: #329, User-Visible: no; корректно: правки чинят баг ещё не выпущенной (Unreleased) фичи этого же issue — запись в docs/CHANGELOG.md/.ru.md уже существует с f514fb27 и описывает финальное, уже исправленное поведение, отдельной строки для самого фикса не требуется.
• «Одно число — один источник»: дельта не вводит и не меняет ни одной новой пользователем видимой величины (правки бэкенда, тестов и прозы документации).

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

• Полный pytest tests_backend (не только test_junction_limits.py) — падает уже на сборе (ModuleNotFoundError: homeassistant, voluptuous), эти пакеты в окружении не установлены; тот же пробел был в r1, дельта его не касается и не обязана устранять.
• Полная матрица demo/smoke_*.mjs и полный прогон реестра мутантов — не запускал: smoke-select.mjs не нашёл ни одной связи для этой дельты (единственный изменённый символ в src/** — переставленный комментарий), а полный прогон реестра — предрелизный гейт (PROCESS.md §8), не гейт ревью такого размера.
• npm run invariants -- --config ... — дельта не меняет геометрический контракт (только удаляет мёртвый код и правит бэкенд/тесты/прозу); поведенческая часть уже закрыта зелёным golden:verify по всей матрице.

Вердикт

Красный. Единственная находка — High, блокирует. Она не переоткрывает ни одну из пяти закрытых находок r1 (все пять закрыты корректно и по существу) и исправляется одной строкой в scripts/mutation-gate.mjs, но npm test сейчас красный на SHA, уходящем в dev, а это один из обязательных дешёвых гейтов этого же процесса.