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

CODE-REVIEW-580-r2

Issue: #580 · Этап: code · Заход: r2 · Материал: c044e9ea3861b777c04233073a02a0a3e2da354a (рабочая копия проверена на этом SHA, git fetch/checkout не выполнялись)

Почему это r2, а не продолжение r1

Первый код-ревью (CODE-REVIEW-580-r1.md) вынес зелёный вердикт на материале 4cb6827c3d1ea0e8307ff7f406b425262c25649a. Пока ревью шло, origin/dev продвинулся на один коммит, автоматическое слияние отказало (§7.2 — «это другой код»), и автор перебазировал ветку на новый origin/dev скриптом scripts/rebase-on-dev.mjs (комментарий issue от 2026-09-15T06:07:14Z). Новая вершина — c044e9ea — и это материал текущего раунда. Старые SHA r1 (4cb6827c, 23e66392, c22eaf7d) после ребейза не существуют в истории (git cat-file -t — Not a valid object name), поэтому дельта «дословно» через git diff <старый SHA>..HEAD невозможна.

Это ребейз на ушедший вперёд dev — по правилам раунда такой случай не сокращается до дельты и требует полного разбора. Ниже — полный разбор, но методом, который эксплуатирует то, что можно проверить дёшево: побайтовое сравнение каждого изменённого файла в git diff origin/dev...HEAD с тем, что цитировал и проверял r1, плюс независимая проверка, что тяжёлые CI-гейты на новом SHA подтверждены не «переиспользованием ради переиспользования», а совпадением хеша содержимого с ранее проверенным деревом.

Скоуп

git log --oneline origin/dev..HEAD — шесть коммитов, из них три содержательных (остальные три — docs: review document for #580, коммиты документов SPEC-REVIEW r1/r2 и этого самого CODE-REVIEW r1, наследие этапа spec и предыдущего раунда, не трогаются):

• d2c7e6f7 (fix, User-Visible: yes) — окклюзия комнатной части внешнего луча внутренними откосами толстой стены.
• a32b280b (fix, User-Visible: no) — типизация того же кода (Geom вместо as any).
• 8b8260b2 (test, User-Visible: no, несёт Release: v1.76.0-beta.4 и Baseline-Reviewed:) — принятие двух golden-эталонов (DPR1/DPR2).

git diff origin/dev...HEAD --stat: 57 файлов, из них по существу — src/sun.ts, test/sun.test.mjs, test/golden-matrix.test.mjs, demo/smoke_sun.mjs, demo/golden/matrix.mjs, scripts/mutation-registry.mjs, docs/SUN.md, оба CHANGELOG; плюс два новых PNG-эталона, demo/golden/baselines/baselines-index.json и весь бандл (dist/**, custom_components/houseplan/frontend/**) — бандл пересобран с новыми хешами файлов из-за нового dev в основании, это ожидаемо и не несёт логики. custom_components/**/*.py в диффе отсутствует — AC7 по touch/i18n/схеме не задет.

Трейлеры: d2c7e6f7 — User-Visible: yes, оба changelog в этом же коммите (проверено git show --stat). 8b8260b2 — Release:/Baseline-Reviewed: со ссылкой на реальный run.

Проверка того, что ребейз не изменил код по существу

Построчно сравнил git diff origin/dev...HEAD для каждого содержательного файла с текстом, который CODE-REVIEW-580-r1.md цитировал и разбирал:

• src/sun.ts — diff идентичен описанному в r1 (тот же intersectRings, та же сигнатура rayRimEdges/rimSources, те же номера механик — intersectRings(quad, rayQuad(innerA, innerB, away, len), clipPoly) и дедупликация источников по eps=1e-4).
• test/sun.test.mjs — оба новых теста (#580: an oblique outer ray..., #580: normal incidence...) побайтово совпадают с тем, что цитировал r1, включая константу 328.4529946162075.
• demo/smoke_sun.mjs — тот же pointInRing, тот же innerFaceX через отражение экрана, те же четыре новых check(...).
• demo/golden/matrix.mjs, test/golden-matrix.test.mjs — та же пара сценариев dpr{1,2}, версия матрицы 62→63.
• scripts/mutation-registry.mjs — те же два новых мутанта (sun-ray-outer-jamb-occlusion-ignored, sun-ray-outer-occluded-rim-source-ignored), find-паттерны совпадают со строками текущего src/sun.ts.
• docs/SUN.md, оба CHANGELOG — тот же текст.

Вывод: продуктовая дельта #580 после ребейза не изменилась ни на строку — изменился только бандл (новые хеши ассетов) и добавились три коммита документов ревью. Это подтверждает и сам автор в комментарии («продуктовая дельта #580 не менялась»), но здесь это установлено чтением диффа, а не принято на слово.

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

Гейты

Валидация на точном материале c044e9ea — зелёная, дважды: run 34935586944 (упомянут во вводном сообщении) и более ранний 34935525859 того же SHA — оба conclusion: success.

Не поверил заявлению «зелёный» буквально: посмотрел job-логи run 34935586944 и обнаружил, что тяжёлые джобы (browser-смоки, golden, perf-смок, geometry-parity, backend) в нём skipped через Переиспользование: это дерево уже проверено. Чтобы отличить легитимный реюз от «зелёного, потому что не запускалось», прочитал лог этого job'а: ключи реюза считает scripts/gate-reuse.mjs --job=<job> по содержимому, не по SHA коммита и не по полному git-дереву (иначе ребилд бандла сломал бы совпадение):

job	результат
smoke	Cache hit for: reuse-smoke-bb7d10d9…
golden	Cache hit for: reuse-golden-ac206839…
performance_smoke	Cache hit for: reuse-performance_smoke-c2e55df8…-glow
geometry_parity	Cache not found (ожидаемо — diff не трогает модель геометрии)
backend	Cache not found (ожидаемо — custom_components/**/*.py не тронут)

Кэш-хиты для smoke/golden/performance_smoke означают, что релевантное содержимое (то, что реально проверяют эти гейты) на c044e9ea побайтово совпало с деревом, на котором r1 уже нашёл реально выполненный (не переиспользованный) прогон — 34933022019, зафиксированный в r1 как run с 3/3 browser-смоками, golden и 6/6 mutation-шардами зелёными. Это закрывает AC4/AC5 без повторного локального прогона: реюз здесь не «дыра», а детерминированная функция от неизменного содержимого, что я проверил, а не предположил.

Мутационные джобы (Мутанты по диффу 1–6/6) на c044e9ea — не переиспользованы, выполнены заново и зелёные: npx tsc --noEmit/typecheck и юнит-тесты прошли свежо на этом самом SHA.

Не гонял локально: npx tsc --noEmit, npm test, npm run build, node scripts/check-docs.mjs, npm run golden:verify — покрыты зелёным Validate на точном SHA (см. выше), плюс отдельно проверенным содержательным реюзом. npm run invariants, python -m pytest tests_backend — diff не касается персистентной модели геометрии (рёбра/толщина/layout/marker.space/open_spans) и не трогает custom_components/**/*.py; толщина стены здесь только читается (wallDepthByOpening), не записывается.

Разбор кода

Продуктовый код (src/sun.ts) не изменился относительно того, что r1 уже разобрал построчно (независимый вывод формулы окклюзии в базисе {нормаль, тангенциальная ось окна}, ручной пересчёт константы 328.4529946162075 с совпадением до 13 знаков, проверка что мутанты бьют именно по изменённым строкам, проверка что demo/smoke_sun.mjs — независимая, не скопированная из продукта реализация геометрии). Побайтовое совпадение диффа (раздел выше) означает, что этот разбор остаётся в силе без повторного вывода — не потому что я поверил документу r1, а потому что сверил текст, который он проверял, с текстом, который лежит в origin/dev...HEAD сейчас.

Дополнительно к r1 проверил:

• что три «продуктовых» коммита (d2c7e6f7, a32b280b, 8b8260b2) после ребейза не имеют собственных CI-прогонов (gh run list --commit <sha> → [] для каждого) — Validate гонялся только на итоговом SHA ветки, что ожидаемо для push после ребейза без промежуточных пушей;
• что коммиты d37b2c9f (Prepare v1.76.0-beta.4) и e54ff33c (новый tip origin/dev, docs-ревью #581), которые вошли в основание после ребейза, не трогают src/sun.ts и вообще не пересекаются с темой солнечных лучей — подтверждено git diff d37b2c9f..e54ff33c -- src/sun.ts (пусто) и git show --stat обоих коммитов;
• что коммиты #577 (внешний луч, та же тема) целиком лежат в основании до ребейза (были в dev ещё когда открывалась ветка #580) — новых пересечений с #577 не возникло, src/sun.ts в диапазоне d37b2c9f..e54ff33c не менялся.

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

находка r1	статус
Блокирующих находок не было	—
Не-Medium наблюдение (неточность формулировки ТЗ «одно дополнительное пересечение»)	не относится к коду; сам код и диагноз не изменились ребейзом — наблюдение остаётся зафиксированным для памяти, не требует действия

Раздел «находка → чем закрыта» здесь вырожден: r1 был зелёным без замечаний в скоупе задачи, поэтому r2 не закрывает правки — он подтверждает, что зелёный вердикт остаётся верным на новом материале после механического (не содержательного) ребейза.

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

Из docs/reviews/CODE-REVIEW-580-r1.md (материал 4cb6827c3d1ea0e8307ff7f406b425262c25649a, дерево eb607a98d8c5a3f34ff9545a589358b50988c20f) принято без повторного самостоятельного вывода, поскольку побайтовое сравнение диффов (раздел выше) подтвердило отсутствие изменений в этих файлах:

• независимый математический вывод формулы окклюзии и ручной пересчёт константы 328.4529946162075 — сверено, что тест и код не изменились;
• анализ rayRimEdges/uniqueSources/отката на [ray.a, ray.b] при rimSources === undefined (AC3, режим inner/d<=0) — код не изменился;
• проверка независимости demo/smoke_sun.mjs (pointInRing, innerFaceX через отражение) от продуктовой формулы — файл не изменился;
• проверка demo/golden/matrix.mjs/хешей PNG на не-пустой принятый эталон и на корректный DPR при рендере — сценарии не изменились, только версия матрицы;
• вывод «единственный источник числа» (обрезанная ширина луча входит в тот же SunRay.polys, второго независимого вычисления в продукте нет) — код не изменился.

Найдено

Блокирующих находок нет.

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

• AC1–AC3 — код идентичен r1-проверенному, юнит-тесты не изменились.
• AC4 (browser smoke), AC5 (golden DPR1/DPR2) — реюз-кэш на точном SHA c044e9ea подтверждён как совпадение по содержимому с деревом, где эти джобы реально выполнялись (см. таблицу gate-reuse выше), а не как слепое доверие статусу Validate.
• AC6 — Validate зелёный на точном материале раунда, двумя независимыми run.
• AC7 — diff по-прежнему ограничен солнечной геометрией/тестами/документацией и пересборкой бандла; custom_components/**/*.py, UI, i18n, touch-контракт и схема конфигурации не тронуты.
• Трейлеры и оба changelog — в правильном коммите (не изменилось).
• Ребейз на новый dev — чисто механический: без конфликтов исходников, продуктовая дельта #580 не изменилась ни на строку, новое основание (d37b2c9f, e54ff33c) не пересекается с темой солнечных лучей.

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

• Не запускал npx tsc --noEmit, npm test, npm run build, node scripts/check-docs.mjs, npm run golden:verify локально — переиспользовал зелёный Validate на этом самом SHA, дополнительно проверив легитимность реюза тяжёлых джобов по ключам содержимого (см. выше), а не только по статусу.
• Не запускал npm run invariants — diff не касается персистентной модели геометрии (рёбра/толщина/layout/marker.space/open_spans).
• Не запускал python -m pytest tests_backend — custom_components/**/*.py не тронут.
• Не перевыводил независимо математику окклюзии и не пересчитывал константу 328.4529946162075 — унаследовано из r1, поскольку строки src/sun.ts и test/sun.test.mjs не изменились (подтверждено побайтовым сравнением диффа).

---

---

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

• Ветка: issue/580-outer-sun-wall-occlusion, коммит c044e9ea3861 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 723c351607934580f0bfbbc19bef5b182273f939

  git log --all --format='%H %T' | grep 723c35160793
  

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