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

CODE-REVIEW-521-r2

Issue: #521 «fix: alignment guides follow the live gesture again» Материал ревью: 9a3af808d95684b32df8f102da4211f3f800703c (ветка issue/521-align-guides-live). Диапазон делты этого раунда — 0715321fdc69a2955d7850f3f384c1a0fdc25311..9a3af808 (материал r1 → материал r2): один коммит deebcfb0 (публикация CODE-REVIEW-521-r1.md конвейером, 0 изменений кода) и один продуктовый/тестовый коммит 9a3af808 «fix: hide the settled guides copy for the whole gesture, and prove it». Заход: r2 · блокирующих циклов израсходовано 1 из 4 (r1 — жёлтый).

Скоуп

Единственная находка r1 (Medium, в скоупе) — AC5 заявлял доказательство («снятие подавления осевой копии слоя даёт 2 группы .alignguides — смок красный»), которого прежний свидетель не давал: осевая копия .hp-editor-only-layer в сценарии смока всегда была пуста, потому что смок ни разу не форсировал осевую отрисовку посреди самого жеста. Дельта r1→r2 — исправление ровно этого: переписанный сценарий devices в demo/smoke_align_guides.mjs форсирует настоящую осевую отрисовку (c._hdrH += 0.01) в середине перетаскивания, проверяет, что она действительно произошла, что владение слоем перешло к осевшей сцене с правильной (живой) точкой, что видимая группа ровно одна на каждом шаге передачи, и что следующее движение возвращает владение живому художнику; плюс новый мутант live-editor-keeps-the-settled-guides-visible в scripts/mutation-gate.mjs, откатывающий подавление обратно в ветку plan (как было до задачи).

Продуктовый код (src/live-editor.ts) в этой дельте не изменился по существу: единственная правка — комментарий, объясняющий измеренный механизм передачи слоя (было общее «плановый режим уже это делал», стало «владение чередуется само, _commitLiveEditor() … измерено: две .alignline …»). Логика makeTransparent(...) вне ветки plan осталась той же, что была принята и проверена в r1 — сама защита не менялась, менялось только доказательство её работы.

Дельта локальна по критериям §2.10: не ребейз (единственный промежуточный коммит — публикация документа предыдущего раунда), не смена контракта поведения (контракт п.3/AC5 переформулированы под тот же механизм, а не заменены другим), не новая подсистема, объём (17 строк комментариев в live-editor.ts, 16 строк нового мутанта, ~90 строк в свидетеле) далеко не сопоставим с исходной задачей. Полный повторный разбор всей задачи не требуется — по AC1–AC4, AC6–AC9 переверяю только то, что могла задеть дельта (сам свидетель), остальное наследую из r1.

Отдельная находка: тело issue правилось после зелёного ревью ТЗ (#517)

Хеш нормализованного тела issue на момент зелёного SPEC-REVIEW-521-r3.md («Материал раунда», конец документа) — 1e7f8d192f340e80e878aec0d6de383c982263254b408f8fc928f383130f5684. Текущий хеш (пересчитан дважды независимо: gh issue view --json body и gh api repos/.../issues/521 -q .body, оба дают одинаковый нормализованный текст) — d117679d25abeab7ebfad3ed7902a8222625fc2ad43d0396b56d6fdacc12b5d3. Хеши расходятся — тело менялось после зелёного ревью ТЗ. Дельту GitHub не хранит, поэтому проверяю не разницу, а текущий текст целиком (см. «Что проверено» ниже).

Что именно изменилось, восстанавливается по признанию автора в комментарии «Исправление по код-ревью r1 → заход r2»: «ТЗ: пункт контракта 3 и AC5 переписаны под измеренный механизм». Прочитал текущий пункт 3 «Контракта» и строку AC5 в теле issue — они дословно описывают именно тот механизм (чередование владения через _commitLiveEditor(), измеренные «две .alignline, осевая отстаёт на шаг»), который выяснился при разборе r1 и теперь доказан переписанным свидетелем. Текст не расходится с кодом и тестами этого раунда — я сверил это построчно (см. «Что проверено»), а не принял на слово автора.

Оценка: это находка процесса — правка раздела ## ТЗ, уже прошедшего зелёное ревью, должна по идее возвращаться на новый цикл S4-spec-review, а не вноситься по ходу код-ревью. Но по существу правка не меняет ни персону, ни сценарий, ни объём видимого изменения, ни один AC-номер — она уточняет формулировку контракта и доказательства AC5 под механизм, который сам же код-ревью r1 и вскрыл, и делает это прозрачно (объяснено в комментарии, а не тихой правкой). Отдельного цикла ревью ТЗ эта поправка не заслуживает: именно для такого случая существует делегирование «технический спор решает ревью кода» (PROCESS.md §7.1) — здесь спора и нет, есть согласие с находкой r1, выраженное в тексте. Классифицирую как Low, снимаю решением ревьюера: текст ТЗ проверен целиком и корректен, действие не требуется.

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

Валидация на материале раунда (9a3af808) зелёная (https://github.com/Matysh/houseplan-card/actions/runs/34526718586), включая шесть параллельных джобов «Мутанты по диффу» — я прочитал логи всех шести шардов напрямую (gh run view --job <id> --log), а не поверил статусу «success» на слово:

Гейт	Прогнал	Результат
Validate на 9a3af808 (tsc, test, build+bundle-sync, no-new-any)	нет, зачтено по зелёному прогону CI (см. ссылку)	success
Логи 6 шардов «Мутанты по диффу» в этом прогоне	да, прочитаны построчно	все 5 мутантов задачи пойманы: live-editor-devices-drops-align-guides (шард 5/6), live-editor-decor-drops-align-guides (4/6), live-editor-plan-drops-align-guides (1/6), align-point-reads-frozen-snapshot (2/6), live-editor-keeps-the-settled-guides-visible (6/6) — новый мутант этого раунда, «тест покраснел, как обязан»
npm run bundle:sync (пересборка + сверка dist/custom_components/.../frontend/demo/srv/assets)	да, локально (нужно было поднять demo/srv/assets, он не коммитится)	чисто, git status не показал diff после сборки — включает tsc --noEmit
node demo/smoke_align_guides.mjs (полный сценарий, все 34 поля)	да	все true, OK
node scripts/mutation-gate.mjs --id=live-editor-keeps-the-settled-guides-visible	да, независимо от CI, в рабочем дереве материала	«поймано 1 из 1»
Ещё 4 мутанта задачи по одному (--id=…)	да, все 4	все «поймано 1 из 1»
node --test test/smoke-harness-contract.test.mjs (AC8)	да	7/7
node scripts/check-docs.mjs	да	зелёный, 7 файлов, 12 внешних ссылок
node scripts/smoke-select.mjs --base 0715321f --head HEAD (выборка по дельте раунда, не по всей задаче)	да	1 прямое совпадение — demo/smoke_align_guides.mjs (символ _alignPoint); других смоков дельта не касается
node demo/smoke_isometric_live_touch.mjs, node demo/smoke_touch_tips.mjs	да (продуктовый код не менялся между r1/r2, но риск ТЗ по touch не был явно закрыт в r1 — закрываю здесь)	оба зелёные, все поля true
cmp dist/houseplan-card.js custom_components/.../houseplan-card.js, то же для houseplan-panel.js и houseplan-assets.json	да	побайтово идентичны
git show -s --format=full 9a3af808 (трейлеры)	да	Issue: #521, User-Visible: no — верно: дельта не меняет видимого поведения (сама правка уже была User-Visible: yes в 53585b45, эта дельта — доказательство и комментарий)
Хеш тела issue (issueBodyDigest из scripts/review-doc-guard.mjs, два независимых способа получения текста)	да	не совпадает с зафиксированным в зелёном SPEC-REVIEW-521-r3.md — находка выше

Не прогонял: golden:verify (дельта раунда не меняет визуал — только комментарий, тестовый файл и конфиг мутанта; видимый рендер не тронут), pytest tests_backend (Python не тронут), полный набор из 239 смоков (не обосновано ни диффом, ни smoke-select), performance-профили (см. ниже), WSL/HA-харнесс.

Перф (AC9). Не перезамерял. Диф src/live-editor.ts между материалом r1 и материалом r2 — только комментарии (проверил построчно: if/makeTransparent вызовы в paintHouseplanEditor и editorTemplate идентичны байт в байт по существу, разница — только текст комментариев). Комментарии не выполняются, поэтому число операций в кадре жеста не изменилось ни на одну со времён r1, где я независимо (не на слово автора) прогнал benchmark:large-house-interaction

• benchmark:compare с собственной базой на fa7ac02c и получил зелёный отчёт без регрессии (см. docs/reviews/CODE-REVIEW-521-r1.md, таблица гейтов). Этот вывод наследуется без повторного прогона.

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

Находка r1	Чем закрыта	Где это видно
Medium: AC5 заявлял «снятие подавления даёт 2 группы .alignguides — смок красный», но смок никогда не форсировал осевую отрисовку посреди жеста, поэтому осевая копия всегда была пуста и мутация не проверялась	Сценарий devices смока форсирует настоящую осевую отрисовку через c._hdrH += 0.01 (свойство вне liveProperties/hoverProperties/gestureProperties — проверил по src/live-editor.ts:80-86, оно не маршрутизируется в живой путь ни при каком состоянии жеста), проверяет, что рендер действительно случился (handoverHappened, счётчик willUpdate), что слой перешёл сцене с правильной живой точкой (handoverGivesTheLayerBackToTheSettledScene, handoverGuideStaysOnTheLivePoint), что видимая группа ровно одна (handoverKeepsExactlyOneGuide), и что следующее движение возвращает владение живому художнику (nextMoveTakesTheLayerBack). Новый мутант live-editor-keeps-the-settled-guides-visible откатывает makeTransparent(...) обратно в ветку plan — смок красный именно на nextMoveTakesTheLayerBack	demo/smoke_align_guides.mjs:162-197; собственный прогон смока — все поля true; собственный прогон mutation-gate.mjs --id=live-editor-keeps-the-settled-guides-visible — «поймано 1 из 1»; то же самое независимо подтверждено логом шарда 6/6 в Validate на 9a3af808
(побочно устранённая слабость свидетеля, не отдельная находка r1) счёт направляющих по числу узлов в DOM вместо видимых — гашение делает копию прозрачной, а не удаляет	visible(selector) фильтрует по layer.style.opacity !== '0' вместо сырого querySelectorAll; проверил, что makeTransparent (src/live-editor.ts:157-163) действительно ставит element.style.opacity = '0' строкой, а restore() снимает через removeProperty('opacity')	demo/smoke_align_guides.mjs:27-36, src/live-editor.ts:157-163, :213-220

Находка закрыта по существу: не «сделали AC5 неопровержимым переписыванием слов», а заставили смок действительно воспроизвести сценарий (внешний осевой рендер посреди активного жеста), который единственный делает защиту наблюдаемой, и подтвердили мутацией, что без защиты сценарий ловится.

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

Без повторной проверки в этом раунде приняты выводы docs/reviews/CODE-REVIEW-521-r1.md (материал: 0715321fdc69a2955d7850f3f384c1a0fdc25311), поскольку дельта r1→r2 их не задевает:

• диагноз и причинность регресса (c0d61ca3/#451, оба слома — слой и замороженная точка) — не менялись, дельта их не касается;
• AC1 (направляющая в трёх живых жестах), AC2 (живая точка), AC3, AC4 — свидетель для decor/plan-сценариев не менялся вовсе в этой дельте (правки смока — только в сценарии devices, между строками 162 и 197); мутанты live-editor-devices-drops-align-guides, live-editor-decor-drops-align-guides, live-editor-plan-drops-align-guides, align-point-reads-frozen-snapshot перепрогнаны мной заново тем не менее (дёшево, один и тот же смок теперь длиннее) — все 4 по-прежнему «поймано 1 из 1»;
• AC6 (один расчёт кандидатов на кадр) — код и проверка не менялись в этой дельте, наследуется техническое заключение r1 («проверено чтением», без отдельного мутанта — осталось так же, это не регрессия дельты);
• AC7 (старые гарантии, #400) — не менялся код и не менялся тот участок смока;
• AC8 (свидетель не фабрикует состояние) — тест-линт test/smoke-harness-contract.test.mjs не менялся; перепрогнал (7/7) на новом более длинном смоке — линт по-прежнему проверяет отсутствие _deviceDrag =/_decorDraft =, новые строки (c._hdrH = …, c._layout = … уже был в старой версии) под запрет не подпадают;
• AC9 (перф) — см. «Как проверялось» выше, база fa7ac02c и зелёный отчёт r1 наследуются без повторного прогона, так как дельта не трогает исполняемый код;
• бюджет core-file-budget и мягкость _renderAlignGuides на карточке (this._editorRuntime?._renderAlignGuides() ?? nothing) — не менялись, проверено в r1 чтением;
• трейлеры и changelog коммита 53585b45 — не менялись, User-Visible: yes подтверждён в r1.

Технический раздел «Чего не проверял» из r1 (golden, pytest, полная матрица смоков, WSL/HA-харнесс) остаётся в силе тем же образом — дельта раунда их не задевает и не расширяет их необходимость.

Находки

Low-1 (снимается, см. выше) — тело issue правилось после зелёного ревью ТЗ без нового цикла S4-spec-review

См. раздел «Отдельная находка» в «Скоупе». Текст пункта 3 «Контракта» и AC5 переписан автором вместе с исправлением по код-ревью r1, без возврата в S3-spec/S4-spec-review. Проверено: новая формулировка точно описывает реализованный и теперь доказанный механизм, персона/сценарий/объём/номера AC не изменились, изменение раскрыто в комментарии автора. Действия не требую; записываю, чтобы хеш в следующем зелёном документе (материал раунда ниже) зафиксировал новое значение и цепочка не молчала.

Других находок нет.

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

• Механизм передачи владения слоем воспроизведён чтением независимо от комментария автора. updated() (houseplan-card.ts:4157) на каждом осевом рендере зовёт _commitLiveEditor() → commitHouseplanEditor (live-editor.ts:439-454): отменяет незавершённый raf, вызывает restore(state) (снимает opacity/visibility, выставленные makeTransparent/dim/hide) и очищает живой корень (render(nothing, target)). Значит после любого settled-рендера слой физически переходит к осевшей сцене чистым, без «памяти» о прежнем подавлении.
• _hdrH гарантированно не маршрутизируется в живой путь. Прочитал liveProperties/hoverProperties/gestureProperties (live-editor.ts:80-86) и routeHouseplanEditorUpdate (live-editor.ts:120-145) — _hdrH не входит ни в один набор, значит namedLive ложно и осевой рендер происходит независимо от активного жеста. Форсирование смоком (c._hdrH += 0.01) действительно моделирует внешний settled-рендер (приход hass, ресайз), а не подглядывает во внутреннее состояние жеста.
• _alignPoint — геттер, а не хранимое состояние (houseplan-card.ts:12879), поэтому и живой, и осевой путь при вызове _renderAlignGuides() во время самого settled-рендера читают одну и ту же живую точку — вот почему «отставание на шаг» проявляется только НА СЛЕДУЮЩЕМ живом кадре после хендовера, а не в момент самого хендовера; смок проверяет обе фазы раздельно (handoverGuideStaysOnTheLivePoint, затем nextMoveTakesTheLayerBack), и это совпадает с объяснением автора.
• Мутант live-editor-keeps-the-settled-guides-visible патчит именно тот код, который сейчас в файле — сверил find-строку патча (scripts/mutation-gate.mjs) с текущим paintHouseplanEditor (live-editor.ts:357-360) посимвольно, совпадает; применимость и результат подтверждены собственным прогоном и логом CI.
• AC8 не сломан новыми строками смока. c._hdrH = …, c._layout = … (уже было раньше), c.requestUpdate() не запрещены тест-линтом — запрещены только присваивания _deviceDrag =/_decorDraft =; перепрогнал линт, 7/7.
• Touch-контракт не задет (риск ТЗ явно требовал: «существующие touch-смоки обязаны остаться зелёными») — smoke_isometric_live_touch.mjs и smoke_touch_tips.mjs зелёные на материале раунда; в r1 эти два смока не были явно названы прогнанными, закрываю пробел здесь, а не переношу его дальше.
• «Одно число — один источник» не применимо. Направляющая — линия и точка, не число; пользователю в этом диффе не показывается ни одна величина дважды.
• Бандл и трейлеры. bundle:sync пересобрал дерево с нуля, dist/ custom_components/.../frontend/demo/srv/assets побайтово совпали с закоммиченными файлами; git show -s --format=full 9a3af808 — трейлеры Issue: #521/User-Visible: no корректны, changelog не тронут и не должен быть (дельта раунда не меняет видимое поведение сверх уже опубликованного в 53585b45).

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

• npm run golden:verify — дельта раунда не меняет визуал (комментарий + тестовый файл + конфиг мутанта), в r1 видимый рендер тоже не менялся кроме уже принятого identical-скриншота.
• python -m pytest tests_backend — Python не тронут ни в одном коммите задачи.
• Полная матрица из 239 смоков — не обоснована ни диффом раунда, ни smoke-select.mjs (одно прямое совпадение); полный набор — предрелизный гейт.
• Не перезамерял benchmark:large-house-interaction — обосновано выше (дельта раунда не исполняемый код).
• Не запрашивал у владельца дополнительного цикла S4-spec-review по поводу правки ТЗ после зелёного вердикта r3 — see Low-1: решил вопрос по существу сам, поскольку это чисто техническая правка формулировки под уже найденный в код-ревью механизм, а не продуктовый вопрос из числа тех, что задаются владельцу (§7.1).

Вердикт

Единственная находка предыдущего раунда закрыта по существу и подтверждена воспроизведением (собственный прогон смока и мутанта плюс независимое чтение логов CI). Новых блокирующих находок нет; единственная новая находка — процедурная (Low), снята решением ревьюера с записью выше. High: 0. Задача готова к очереди на пре-релиз.

Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0 → в задаче

Документ: docs/reviews/CODE-REVIEW-521-r2.md

---

Материал раунда

• Ветка: issue/521-align-guides-live, коммит 9a3af808d956 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 20fbfc5c7f020a361c04f252900511c2e383ceba

  git log --all --format='%H %T' | grep 20fbfc5c7f02
  

• Тело issue: d117679d25abeab7ebfad3ed7902a8222625fc2ad43d0396b56d6fdacc12b5d3
• Вердикт конвейера: green · High 0