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

CODE-REVIEW-577-r2

Issue: #577 «Выбор граней окон для солнечных лучей» · заход r2 · блокирующих циклов использовано 1/4 (лимит 4, полный трек; зелёный вердикт бюджет не тратит, §4).

Материал: ветка issue/577-sun-ray-window-corners. Раунд r1 код-ревью прошёл на SHA 6f6a85a11687c4f5cd20e79a2088d05ab6be12df (жёлтый, Medium в скоупе). Материал ревью этого раунда — ровно 59c5f6f6f259bed13ae39df88a7a163be8c4ec83, рабочая копия на этом SHA.

Дельта: что рассматривает этот раунд

Разбор объёма ограничен дельтой git diff 6f6a85a1..HEAD, потому что она локальна по критерию §2.9: не задевает src/**, не меняет ни один продуктовый файл (custom_components/**/*.py, i18n, types.ts) и не меняет контракт поведения — только гейты и артефакты доказательства (класс B/C/D):

git diff --stat 6f6a85a1..HEAD -- . ':!docs/reviews'

• demo/golden/matrix.mjs, demo/golden/harness.mjs — новый сценарий lighting-sun-window-outer-thick-dark (толстая наружная стена 15 см, sun_ray_origin: outer через глобальный settings, не per-space);
• demo/golden/baselines/** + baselines-index.json — новый эталон плюс три пересобранных (safe-resize-handles-clamp-light, settings-help-zoom-200-{en-light,ru-dark} — оба сдвинулись из-за нового select в общих настройках);
• demo/smoke_sun.mjs — новые проверки на реальной сцене: sourceX, количество полигонов, наличие тоннеля/комнатной части, конечность DOM SVG координат;
• demo/smoke_general_settings.mjs — счётчик строк 15 → 16;
• scripts/mutation-registry.mjs — уточнён якорь мутанта sun-golden-north-neutralized (старый anchor стал неоднозначным: новая сцена тоже содержит northDeg: 90,);
• test/golden-matrix.test.mjs — структурные проверки новой сцены (GOLDEN_MATRIX_VERSION 61→62, глобальность поля, cm: 15, capture);
• docs/TESTING.md, docs/images/screenshots.json — обновление ссылки на доказательство и отпечатка исходников (не картинок — см. ниже).
• Класс D (custom_components/houseplan/frontend/**, dist/**) — пересборка вслед за bundle:sync, без изменений источника.

Продуктовый код (src/**, custom_components/houseplan/**/*.py, i18n) в дельте не участвует ни строкой — подтверждено:

git diff --stat 6f6a85a1..HEAD -- src/ custom_components/ 'src/i18n/*.json'

→ пусто помимо сгенерированного custom_components/houseplan/frontend/**.

Следовательно AC1–AC3, AC5, AC6, AC8, AC9, i18n, config-registry, откат — доказательства этого раунда дельта не задевает: наследуются из r1 без повторного прогона (раздел «Унаследовано из r1» ниже). Разбор в этом раунде сфокусирован на AC4 и AC7 — единственном, что дельта меняет.

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

Находка r1	Чем закрыта	Где это видно
Medium (в скоупе): AC4/AC7 объявляют доказательство golden, но demo/golden/matrix.mjs/baselines/** не тронуты вовсе; smoke_sun.mjs проверял только диалог, не реальную геометрию толстой наружной стены в outer.	1) Добавлен golden-сценарий lighting-sun-window-outer-thick-dark (толстая наружная стена 15 см, тема dark, sun_ray_origin: outer через фикстуру harness.mjs, а не per-space override — снимает риск скрытой утечки в space-скоуп). 2) smoke_sun.mjs получил 6 новых проверок на реальной сцене (sourceX > 960, polyCount ≥ 2, тоннель нарисован, комнатная часть нарисована, DOM-полигонов ≥ 2, все SVG-координаты конечны) — именно тот executable oracle, которого не хватало. 3) Эталон принят из Linux CI со свидетельством ревью.	demo/golden/matrix.mjs:856-863 (сценарий), demo/smoke_sun.mjs:258-331 (assertions), demo/golden/harness.mjs:687-694 (глобальное применение sunRayOrigin в фикстуре), коммит cb4a5451 (Baseline-Reviewed: .../runs/34901679608, Release: v1.76.0-beta.3)

Дельта нового расхождения не внесла: git diff 6f6a85a1..HEAD -- docs/SUN.md docs/WALL-THICKNESS.md docs/CONFIG-COMPATIBILITY.md docs/USER-GUIDE.ru.md docs/CHANGELOG.md docs/CHANGELOG.ru.md — пусто, тексты r1 не менялись.

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

Дешёвые гейты подтверждены зелёным Validate на этом SHA (https://github.com/Matysh/houseplan-card/actions/runs/34903422427, conclusion: success, проверено gh run view --json — job'ы typecheck/ unit/build/bundle-sync, Мутанты по диффу 6/6, Смоки в браузере 3/3 green; тяжёлые job'ы golden, backend, performance_smoke, hassfest, hacs, geometry_parity в этом прогоне skipped — это push, не heavy-гейт, см. PROCESS.md, не признак проблемы). Поэтому npx tsc --noEmit, npm test (в части, не относящейся к дельте) и npm run build повторно не гонялись.

То, что Validate не покрывает и что относится к дельте, прогнано здесь:

Гейт	Команда	Результат
Unit — sun (дельта его не трогала, контроль регрессии)	node --test test/sun.test.mjs	40/40 green
Unit — golden-matrix (дельта его меняет)	node --test test/golden-matrix.test.mjs	50/50 green, включая новый тест на lighting-sun-window-outer-thick-dark
Мутант на изменённый якорь	node scripts/mutation-gate.mjs --check --id=sun-golden-north-neutralized	ok — якорь встречается ровно 1 раз (было бы 2 без правки, конфликт со старым анкором доказан отдельно ниже)
Тот же мутант, воспроизведение красного прогона	node scripts/mutation-gate.mjs --id=sun-golden-north-neutralized	«заявленный тест покраснел на мутанте» — поймано 1 из 1
check-docs (дельта трогает demo/golden/*.mjs, входящие в корпус отпечатка)	node scripts/check-docs.mjs --screenshots=strict	green: «Documentation checks passed (7 files, 12 external links)» — отпечаток в docs/images/screenshots.json пересчитан правильно, картинки не изменились (только sourceFingerprint/sourceSha256, imageSha256 те же)
smoke — smoke_sun (дельта его меняет, единственный носитель новых assertions)	npm run build && npm run bundle:sync && node demo/smoke_sun.mjs	green (список чеков включает новые originAvailableWhenRaysOff, originSavedOuter, originRoundTripsToDialog; новые безымянные check() на реальной стене не попали в печатаемый summary, но finish() печатает OK только при пустом списке провалов — подтверждено чтением demo/serve.mjs:68-78)
smoke — smoke_general_settings (дельта его меняет — счётчик строк)	node demo/smoke_general_settings.mjs	green, rows: 16 подтверждён
smoke-select (страховка — не пропущен ли смок, задетый дельтой но не выбранный вручную)	node scripts/smoke-select.mjs --base 6f6a85a1 --head HEAD	«Исполняемого frontend-диффа нет (src/**/*.ts не тронут)» — корректно: дельта не в src/**, смоки на неё не завязаны через прямое совпадение символов
no-new-any (контроль, что дельта действительно пуста в src)	node scripts/no-new-any.mjs --base 6f6a85a1 --head HEAD	«Проверено добавленных строк в src/**/*.ts: 0 в 0 файл(ах)»
golden:verify — полный прогон, все 170 сцен (AC4/AC7 требуют golden явно, а heavy-гейт в push-Validate пропущен)	npm run golden:verify	170/170 passed, 0 failed/missing, в т.ч. lighting-sun-window-outer-thick-dark, lighting-sun-window-state-only-dark, три пересобранных эталона (safe-resize-handles-clamp-light, settings-help-zoom-200-en-light, settings-help-zoom-200-ru-dark)
single-source-numbers (страховка; задача не добавляет новых видимых чисел — только enum)	node --test test/single-source-numbers.test.mjs	3/3 green, не нашёл второго источника — ожидаемо, задача не вводит числовых значений

Разбирался также CI-артефакт кандидата на баланс: run 34901679608 (на SHA 0d1df78f, процитирован в трейлере Baseline-Reviewed коммита cb4a5451) на первый взгляд читается как красный (conclusion: cancelled, Golden-кадры против принятых эталонов: failure, Смоки… шард 1 из 3: failure) — проверено логом: gh run view 34901679608 --log-failed → golden упал единственной строкой missing-baseline lighting-sun-window-outer-thick-dark (ожидаемо: это и есть прогон-кандидат ДО принятия эталона, отсюда взяты кадры для визуальной приёмки), а smoke_general_settings упал на старом rows: 15 — это тот же дефект, который следующий коммит 59c5f6f6 устранил. Расхождение не находка, а подтверждение, что коммит-цепочка честная: кандидат сначала показал недостающий эталон и рассинхронизированный счётчик, затем оба были исправлены отдельными коммитами.

Находки

Нет. High: 0. Medium: 0. Low: 0.

Что проверено и корректно (эта дельта)

• Golden-сценарий lighting-sun-window-outer-thick-dark задаёт sun_ray_origin: 'outer' через fixture.config.settings в harness.mjs:687-694, а не через space.settings — комментарий в коде прямо объясняет, почему это важно (совпадение с реальным путём чтения общих настроек, а не молчаливый fallback на inner); test/golden-matrix.test.mjs дополнительно утверждает outerSpace.settings.sun_ray_origin === undefined — структурная гарантия, что селектор не просочился в per-space скоуп.
• smoke_sun.mjs проверяет именно то, что не хватало по итогам r1: реальная толстая наружная стена, оба полигона (тоннель + комнатная часть) фактически нарисованы в DOM (domPolyCount ≥ 2), координаты не NaN/Infinity.
• Мутант sun-golden-north-neutralized был бы сломан новой сценой (два идентичных фрагмента northDeg: 90, в файле после добавления новой сцены); автор это заметил и уточнил якорь длинным уникальным префиксом — проверено прогоном --check (ровно 1 совпадение) и живым воспроизведением мутации (тест краснеет).
• Изменение отпечатка docs/images/screenshots.json — не регресс документационных скриншотов: sourceFingerprint/sourceSha256 пересчитаны из-за правки demo/golden/*.mjs (файлы входят в корпус отпечатка по scripts/source-fingerprint.mjs), но ни один imageSha256 не изменился — check-docs --screenshots=strict подтверждает это green.
• Трейлеры: все 5 коммитов дельты несут Issue: #577; User-Visible: no корректен — пользовательское поведение не менялось (оно было доставлено и проверено ещё в r1 коммитах db4b397e/6f6a85a1, там же оба changelog). cb4a5451 (единственный, трогающий demo/golden/baselines/**) несёт обязательные Release: v1.76.0-beta.3 и Baseline-Reviewed: — условие AGENTS.md выполнено.
• baselines-index.json: matrixVersion 61→62, platform win32→linux (баланс принят с канонической ОС, не с рабочей машины автора), witnesses.count 101→109 — согласовано с текстом коммита.

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

Без повторной проверки в этом раунде (документ CODE-REVIEW-577-r1.md [закоммичен в 7cc9b4b5], SHA материала 6f6a85a11687c4f5cd20e79a2088d05ab6be12df). Основание: дельта r1→r2 не содержит ни строки в src/**, custom_components/houseplan/**/*.py или src/i18n/*.json (подтверждено git diff --stat выше в этом же документе), поэтому ничто из перечисленного ниже не могло измениться между раундами:

• AC1 (UI/сохранение): select #gs-sun-ray-origin рендерится один раз, всегда доступен, в space-диалоге отсутствует.
• AC2 (совместимость): sunRayOriginOf() fail-closed на inner для всех испорченных значений; backend vol.In(["inner","outer"]); import/export и support package round-trip.
• AC3 (внутренняя грань): формула inner байт-в-байт совпадает с origin/dev; существующие golden для inner не менялись.
• AC5 (инварианты луча): direction/len/fade/rim/препятствия не меняются между inner/outer; нулевая толщина даёт идентичный результат.
• AC6 (кеш): origin — часть ключа _sunRaysCache.
• AC8 (соседние контракты): windowWallInfo, isExteriorWall, per-space sun_rays/north_deg не тронуты диффом ни в r1, ни в дельте r1→r2.
• AC9 (производительность): одна ветка side = ... ? -1 : 1 в уже существующем цикле, без новых таймеров/сетевых вызовов — проверено чтением.
• i18n: en/ru/de/fr, тексты совпадают с телом issue.
• Config registry / schema parity, откат, бюджет бандла, типизация types.ts — как в r1.
• Документация (класс C): docs/SUN.md, docs/WALL-THICKNESS.md §5, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.ru.md, оба docs/CHANGELOG*.md — числятся в скоупе диффа r1 без замечаний; содержимое повторно построчно не сверялось в этом раунде (дельта их не касается).

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

• python -m pytest tests_backend — не прогонялся; backend-файлы не входят в дельту r1→r2, а на r1 SHA backend job Validate был зелёным (унаследовано).
• performance_smoke — heavy-гейт, AC9 называет доказательством «ревью кода»; выполнено чтением в r1, дельта эту ветку не касается.
• Полный smoke-select матч (18 прямых совпадений из r1) — не перегонялся: дельта не в src/**, поэтому набор прямых совпадений не изменился, а smoke_sun/smoke_general_settings (единственные, которые дельта реально меняет) прогнаны явно выше.
• npm run invariants — дельта не в модели геометрии (рёбра комнат, layout, marker.space, записи толщины) и не меняет src/** вовсе; гейт не относится к этому диффу.
• HACS/Hassfest/geometry_parity — не относятся к диффу (нет изменений в манифесте, интеграции или geometry parity harness); в Validate — skipped по тем же причинам (push, не heavy).

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

• Ветка: issue/577-sun-ray-window-corners
• SHA материала: 59c5f6f6f259bed13ae39df88a7a163be8c4ec83
• Предыдущий раунд: CODE-REVIEW-577-r1 (жёлтый, Medium в скоупе), SHA 6f6a85a11687c4f5cd20e79a2088d05ab6be12df

---

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

• Ветка: issue/577-sun-ray-window-corners, коммит 59c5f6f6f259 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: b65cd3cf6d62954b65e9be4f605a767c55b298d0

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

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