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

CODE-REVIEW-290-r3

• Issue: #290 — «Уступ в один шаг на общей стене создаётся молча и невидим при обычном зуме»
• Этап: код-ревью (PROCESS.md §2.7)
• Заход: r3 · блокирующих циклов израсходовано на входе 1 из 4
• Ветка: issue/290-near-axis-authoring-repair
• HEAD на момент ревью: d33ae88da4049bdbdfd02c57f935199007157cf3
• Диапазон: origin/dev..HEAD (10 коммитов, git diff --stat origin/dev...HEAD: 35 файлов, +2611/-335)

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

Формально предыдущий раунд (r2, комментарий issue #290 от 2026-08-24 13:21) — зелёный, и по правилу §2.10 третий заход мог бы разобрать только дельту после него. Но между r2 и этим заходом ветку перебазировали на ушедший вперёд dev (комментарий владельца 2026-08-24 13:34: домержены #288/#290 changelog, WALL-THICKNESS.md, пересобраны бандлы). Это прямо попадает под исключение §2.10: «ребейз на ушедший вперёд dev — после ребейза это другой код». Сам r2 уже один раз проходил через это же исключение относительно r1 (домёржен #289).

Отдельно: SHA, на котором получен вердикт r2, в самом вердикте не назван (комментарий #8 в issue называет только промежуточные коммиты 615c0744 и 6ded0f01, но не финальный HEAD ветки на момент зелёного вердикта). Это находка процесса, а не кода: проверил — оба этих SHA сейчас нерезолвируемы (git cat-file -t — «Not a valid object name»), что и является следствием силового ребейза, а не пропуском автора. Дальше это не имеет практического значения, потому что рабочий пункт §2.10 всё равно предписывает полный разбор для этого случая, и я его сделал: прочитан и перепроверен весь diff origin/dev...HEAD, а не только «правки со времени r2».

Скоуп

Продукт: единый near-axis classifier (src/near-axis.ts, новый), authoring- привязка при рисовании стен (src/houseplan-card.ts), exact-axis постусловие Safe Resize (src/resize.ts), явный lossy-проход Optimize (src/plan-optimizer.ts) с отчётом/Undo, единый источник допуска 0.25° для renderer (src/wall-thickness.ts), near-axis профиль в CLI инвариантов (scripts/model-invariants.mjs), 6 mutation-gate записей, RU/EN i18n, production-смоки, docs (ARCHITECTURE/CANVAS/RESIZE/WALL-THICKNESS/ CONFIG-COMPATIBILITY/USER-GUIDE×2/TESTING), оба changelog.

Как проверялось — гейты

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	чисто, без ошибок
Unit	npm test	1234 тестов: 1233 passed, 1 skipped, 0 failed
Build + bundle parity	npm run build; diff dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js; git diff --stat -- dist/houseplan-card.js	пересобранный dist идентичен закоммиченному и копии в custom_components — три копии совпадают
Docs fingerprint	node scripts/check-docs.mjs	«Documentation checks passed (7 files, 10 external links)»
Инварианты (геометрия задета)	npm run invariants -- --config test/fixtures/real-plan-first-floor.json; то же для real-plan-second-floor.json	код 0 на обоих; на первом плане 2 наблюдения (не нарушения, записи толщины на exact endpoints)
Near-axis профиль на реальных планах	node scripts/model-invariants.mjs --config <fixture> --near-axis	first-floor: 0 почти-осевых стен; second-floor: 1 (это и есть исходный дефект issue, воспроизводимый и до правки)
Mutation-gate — все 6 обязательных AC9 ID индивидуально	node scripts/mutation-gate.mjs --id=near-axis-* ×6	все шесть: «тест покраснел, как обязан» / «поймано 1 из 1»; после каждого прогона git status --short пуст — патчи откатываются
Smoke — прямое совпадение (smoke-select.mjs --base origin/dev --head HEAD)	node demo/smoke_decor_layer_order.mjs, smoke_room_resize.mjs, smoke_zero_divider_taper.mjs	все три OK
Smoke — зарегистрированная связь	node demo/smoke_near_axis_optimize.mjs	OK, все 12 ключей true
Smoke — файл прямо изменён диффом	node demo/smoke_plan_drawing_repairs.mjs	OK, все 19 ключей true, включая 3 новых near-axis ключа
Golden (полный, т.к. диф трогает Optimize-диалог и authoring-геометрию)	npm run golden:verify	код выхода 0, все 161 сценарий passed, включая optimize-preflight-dialog-{dark-en,light-ru}
Backend pytest	—	не прогонялся: git diff --stat origin/dev...HEAD -- 'custom_components/**/*.py' пуст
Дисциплина «тест умеет падать» — H1 регрессия (r1)	откат src/resize.ts к широкой проверке по всем рёбрам полигона, node --test --test-name-pattern="#290 a remote near-axis" test/resize.test.mjs	тест краснеет (reason: 'invalid-geometry' вместо ожидаемого 'partial-shared'); после отката файла — снова зелёный, git status чист
Дисциплина «тест умеет падать» — AC1 source guard	откат src/wall-thickness.ts:85 к инлайн-литералу = 0.25 вместо импорта, полный npm test + tsc --noEmit	не падает ничего — см. находку M1 ниже

Находки

M1 (Medium, в скоупе задачи)

ТЗ AC1 (docs/specs/290-near-axis-authoring-and-repair.md:173-174) прямо обещает: «Authoring, Optimize и renderer #279 импортируют один threshold source; source guard запрещает отдельные литералы 0.25 в этих classifiers». Такого guard'а в коде нет.

src/wall-thickness.ts:85 действительно ссылается на источник: export const MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES = NEAR_AXIS_MAX_DEGREES; — но единственная проверка этого факта, test/near-axis.test.mjs:23 (assert.equal(MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES, NEAR_AXIS_MAX_DEGREES)), сравнивает числа, а не происхождение значения.

Воспроизведено: заменил в src/wall-thickness.ts:85 импортированную ссылку на инлайн-литерал (export const MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES = 0.25;, удалив зависимость от NEAR_AXIS_MAX_DEGREES) и прогнал npx tsc -p tsconfig.test.json, node scripts/fix-test-build.mjs, node --test test/near-axis.test.mjs test/wall-thickness.test.mjs (115 тестов) и отдельно npx tsc --noEmit — всё зелёное, ни один тест, ни typecheck не заметили расхождения. Значение продублировано, а не переиспользовано, ровно так, как AC1 запрещает, и ни один существующий гейт этого не ловит.

Почему это не придирка, а реальный риск именно для этой задачи: issue #290 существует потому, что renderer (#279) и остальная система однажды разошлись в допуске 0.25°/sin(0.25°). AC1 — это явно сформулированная защита от повторения того же класса дефекта на трёх новых потребителях порога (authoring, Optimize, renderer). Сейчас, если будущий рефакторинг/мёрдж случайно вернёт renderer к собственному литералу (или к чуть другому числу), ни npm test, ни tsc, ни один из зарегистрированных 6 mutation-gate ID для #290 этого не поймают — именно тот тихий дрейф, который эта задача призвана исключить.

Как чинится в скоупе: нужен один из двух вариантов — (а) статический guard по образцу test/single-source-numbers.test.mjs (regex/AST-скан src/**/*.ts на литерал 0.25 вне src/near-axis.ts), либо (б) mutation-gate запись, аналогичная уже существующим шести, которая инлайнит литерал в wall-thickness.ts и требует, чтобы это красило конкретный тест/typecheck. Оба варианта дёшевы и не меняют продуктовое поведение.

Находка в скоупе задачи, High отсутствует → жёлтый вердикт, исправляется в этой же ветке, отдельный issue не заводится (решение владельца 2026-08-19, #202).

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

• AC1 (кроме source guard) — test/near-axis.test.mjs:21-29 покрывает exact axis, 316×1/316×2, зеркальные/обратные концы, ровно 0.25° (NEAR_AXIS_MAX_SLOPE) и чуть выше, 30°-диагональ; boundary включительна (minor / major > NEAR_AXIS_MAX_SLOPE, src/near-axis.ts:28).
• AC2 — demo/smoke_plan_drawing_repairs.mjs: preview (.active-axis) и committed draft персистят 316×0; snapNearAxisEndpoint двигает только свободный конец (src/near-axis.ts:36-44, src/houseplan-card.ts:6917-6931); существующий узел, конфликтующий с near-axis правилом, корректно теряет snap-owner (effectiveCandidate, тест nearAxisRuleDoesNotClaimWrongEndpoint).
• AC3 — src/resize.ts:1015-1021: постусловие проверяет три инцидентных сдвигаемым вершинам ребра (involvedEdges = [prev, edge, edge+1]), не весь полигон. Регрессия r1 (H1: широкая проверка валила несвязанные ручки) закрыта и подтверждена прямым откатом (см. таблицу гейтов); test/resize.test.mjs фиксирует и «south-west,1 → enabled:true», и «north-west,3 → partial-shared по независимой причине #289», не near-axis.
• AC4/AC10 — test/near-axis.test.mjs тест «reduces the tracked real-plan near-axis profile»: на real-plan-second-floor.json до repair — 1 почти- осевая стена (совпадает с --near-axis CLI, см. таблицу гейтов), после Confirm — 0, повторный Optimize — changed:false/wallsStraightened:0.
• AC5 — test/near-axis.test.mjs «repairs a duplicated 316x1» проверяет, что обе room-copies получают идентичные endpoints (north.poly[1] === south.poly[0]), demo/smoke_near_axis_optimize.mjs.applyRekeysWall подтверждает rekey записи толщины стены (wall.key.endsWith('@0.0000')). Repair встроен в существующий pipeline alignAllToGrid → normalizeWallIntervals → degradeWalls (src/plan-optimizer.ts вокруг строки 440), а не специальным обходом, поэтому thickness/open-span rekey получается бесплатно из уже проверенной инфраструктуры.
• AC6 — тест «preserves true diagonals»: 316×2 и партиция diagonal byte-equivalent после repair; отдельный юнит на openings, которые перестали бы помещаться после repair (skips a repair that would no longer fit a hosted opening) — кандидат корректно пропускается, partitions не тронуты.
• AC7 — maxStraightenShiftCm в UI (src/houseplan-card.ts) округляется вверх (Math.ceil(x*10)/10), то есть заведомо не меньше фактического сдвига — соответствует требованию «верхняя граница».
• AC8 — demo/smoke_near_axis_optimize.mjs: preview не пишет (previewDoesNotWrite), Cancel не пишет (cancelDoesNotWrite), Confirm — один атомарный houseplan/plan/optimize (applyUsesOneAtomicWrite), reload — идемпотентно (reloadIsIdempotent), Undo восстанавливает исходную геометрию байт-в-байт и глубина Undo равна одному шагу (undoIsOneDeep). Revision-guard самого транспорта не менялся этим диффом — это существующая инфраструктура Optimize, разбор чтением, не исполнением.
• AC9 — все 6 обязательных mutation ID зарегистрированы (scripts/mutation-gate.mjs:945-1011) и убиты индивидуально (см. таблицу гейтов); это сильнее, чем просто --check реестра.
• Single source of numbers — wallsStraightened/maxStraightenShiftCm считаются один раз в plan-optimizer.ts и не пересчитываются отдельно для превью/после-Confirm/reload; единственное преобразование в UI — округление вверх для отображения, не второй источник величины.
• Changelog/трейлеры — edf8b068 (fix: straighten near-axis wall geometry) несёт Issue: #290, User-Visible: yes и правки в оба docs/CHANGELOG.md/docs/CHANGELOG.ru.md тем же коммитом.
• Bundle parity — пересобранный dist/houseplan-card.js побайтово идентичен закоммиченному и копии в custom_components/houseplan/frontend/.
• Golden — полный прогон (161 сценарий) зелёный, включая два сценария Optimize-диалога, которые непосредственно рендерят новые UI-строки.
• Совместимость — docs/CONFIG-COMPATIBILITY.md описывает repair как подтверждаемый lossy-пас без миграции схемы; PLAN_MODEL_VERSION не поднят (в диффе plan-optimizer.ts версия не менялась) — согласуется с «schema не меняется» из ТЗ §9.
• Производительность (прочитано, не исполнялось) — classifyNearAxisSegment O(1) на сегмент; repairNearAxisRoomWalls линеен по рёбрам/drafts/partitions входного пространства, кандидаты не каскадируют (строятся из immutable входа); добавка в validateSafeResize — фиксированные 3 проверки на вызов. Отдельный performance-прогон не запускал, т.к. не назван в AC и алгоритмическая сложность не изменилась по классу (было O(edges), осталось O(edges)).

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

• Полный набор mutation-gate (все ID, не только 6 near-axis) — не требовался диффом; случайно запустил фоном по невнимательности (--help без распознанного флага не показал справку, а прогнал весь registry), прогон завершился без ошибок, но я не использую его как доказательство — целевые 6 ID проверены индивидуально и осознанно, этого достаточно для AC9.
• Touch-специфичные смоки (pinch/pan/pointercancel) — код диспетчеризации жестов диффом не тронут, near-axis-правило встроено в уже общий для touch/mouse путь _resolvePlanDrawPoint/commit; отдельного риска не вижу, не гонял smoke_editor_gestures/smoke_pan_any_zoom и им подобные (в выдаче smoke-select.mjs они пришли только как «слабая связь» по общему _path).
• python -m pytest tests_backend — не запускал, диф не трогает custom_components/**/*.py (проверено git diff --stat).
• Linux HA harness / полный CI Validate на этом SHA — не мой гейт; автор уже сообщил зелёный Validate 32733382537 на текущем HEAD (комментарий issue от 2026-08-24 13:34); не перепроверял внешний CI прогон напрямую, доверяю ссылке как внешнему источнику, а не самопроверке автора.

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

r2 (комментарий issue от 2026-08-24 13:21:36, зелёный, High:0/Medium:0) сам закрыл H1/M1/M2 из r1 и не оставил открытых находок. Между r2 и этим заходом код не менялся (ребейз перенёс тот же коммит edf8b068/f6cf2c93 на новый dev без изменения содержимого — конфликты владелец разрешил только в changelog/WALL-THICKNESS.md/бандлах, что подтверждено комментарием "Разрешённые конфликты" от 2026-08-24 13:34). Поэтому таблицы «находка → чем закрыта» для r2 не требуется: закрывать нечего, r2 ничего не оставил. Настоящая находка этого раунда (M1, source guard) — новая, не заявлена и не пропущена в r2: r2 прямо пишет «дельта касается только docs/specs/...» на этапе ТЗ (SPEC-REVIEW-290-r2) и не переразбирала AC1 на уровне кода за пределами заявленного автором диффа между r1 и r2, а сам код AC1 (near-axis.ts/wall-thickness.ts) не менялся между r1 и r2 — H1-фикс трогал только resize.ts.

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

Полный разбор в этом раунде проведён самостоятельно и заново по всему диффу origin/dev...HEAD, а не по дельте — так как рёбейз делает предыдущий SHA нерезолвируемым (см. «Почему разбор полный» выше). Поэтому код целиком перепроверен мной лично, а не унаследован. Единственное, что действительно не перепроверялось заново и взято как решённое на уровне продукта, а не кода — продуктовые решения владельца (выравнивать без modifier, lossy-пас Optimize с отчётом и подтверждением, единый допуск 0.25°), зафиксированные и принятые на этапе ТЗ в SPEC-REVIEW-290-r2 (docs/reviews/SPEC-REVIEW-290-r2.md, зелёный, коммит dc9f9a6c по данным того документа) — эти решения не относятся к коду и не могли быть затронуты ребейзом.