houseplan-card/docs/reviews/CODE-REVIEW-86-r5.md

CODE-REVIEW-86-r5

• Issue: #86 — Тексты подсказок к настройкам: очередь и правила (Party 1)
• Заход: r5 · блокирующих циклов израсходовано 3 из 4
• Материал: git log --oneline origin/dev..HEAD, git diff origin/dev...HEAD
• HEAD: fa146fb1 · origin/dev: 2b0ac0c0 (включает #44, merge-base == origin/dev)
• Спецификация: docs/specs/086-settings-help-content-party1.md (актуализирована 2026-08-30, коммит 20883c31 до ребейза)

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

После зелёного вердикта r4 (на 7408f8af) dev продвинулся на 5 коммитов — слияние #44 «discovery filters become visible, explained and previewable» (d14cf769..2b0ac0c0, включая собственный цикл ревью #44 с фиксами M1‑M2). Ветка issue/86-settings-help-party1 перебазирована на этот новый dev. Все SHA из документов r1–r4 (7408f8af, 96bd3e3e, 18ab3779 и т.д.) более не существуют в истории (git cat-file -t → fatal: Not a valid object name для каждого) — это не косметика, а другое дерево (PROCESS.md §2.10/§7.2). Это ровно случай, для которого прямо предписан полный разбор.

Важное обстоятельство: git merge-base HEAD origin/dev == origin/dev, то есть диапазон origin/dev...HEAD — это весь вклад ветки #86 целиком (в dev уже влит #44, в ветке сверх него — только #86). Это даёт полный и единственный источник правды для разбора, без необходимости реконструировать историю по кускам.

Дополнительная проверка ребейза: #44 и #86 модифицируют одни и те же файлы (src/houseplan-editor-runtime.ts, src/i18n/{en,ru,de,fr}.json, src/styles/dialogs.styles.ts, docs/images/screenshots.json, docs/CHANGELOG*.md). Список конфликтов, зафиксированный в issue перед финальным ребейзом, содержал только сгенерированные бандлы и changelog — никаких конфликтов в src/**/i18n/**. Прочитал итоговый diff этих файлов: изменения #86 (add _help(...) triggers, новые .help/.help.aria ключи) корректно легли поверх кода #44 (_renderDiscoveryFilters, новые i18n-ключи дискавери) без потерь с обеих сторон — рекомбинация чистая.

Что проверялось и как

Гейты, прогнанные лично на fa146fb1

Гейт	Результат
npx tsc --noEmit	зелёный, без ошибок
npm test	1615 тестов, 1614 pass, 0 fail, 1 skip (тот же приватный #281-скип, что и в r1–r4)
npm run build + git status --porcelain после build	0 diff — закоммиченный dist/ побайтово совпадает со свежей сборкой
node scripts/bundle-sync.mjs	0 diff в custom_components/houseplan/frontend и demo/srv/assets — три канонические копии синхронны
node scripts/bundle-budget.mjs	initial View 280 678 B / 300 000 B бюджета, headroom 19 322 B — в норме
node scripts/no-new-any.mjs	«Новых any нет» (119 добавленных строк в 3 файлах)
node scripts/check-docs.mjs --external	«Documentation checks passed (7 files, 10 external links)» — фингерпринт скриншотов не протух, sha256 каждого PNG совпадает с манифестом (тот самый канал, что в r1 поймал H1 — здесь чисто)
node scripts/mutation-gate.mjs --id=settings-help-party1-placement-removed	мутант поймал test/i18n.test.mjs — «покраснел, как обязан»
npm run golden:verify	147/147 passed, 0 different/missing (полный лог сохранён)
13/13 smoke «прямого совпадения» из smoke-select.mjs	все OK, все party1-флаги в smoke_help_affordance.mjs — true

Почему прогнал сам, а не принял «Validate зелёный» на веру: разобрался в устройстве последнего прогона (run 33310161342, headSha=fa146fb1) — job «Классификация изменённых файлов» сравнивал только 04da7eb1..fa146fb1 (3 файла docs/images/**), потому что предыдущий push (04da7eb1, реальный ребилд бандла) получил cancelled прогон (run 33310044199, перекрыт следующим push тремя минутами позже), а не зелёный. В итоге frontend, golden, smoke, backend в финальном прогоне — не «переиспользованы по хешу» (шаг reuse-маркеров явно вернул Cache not found по всем четырём), а skipped классификацией. То есть ни один реальный CI-прогон после финального ребейза не исполнил тяжёлые гейты по-настоящему. Заявление «Validate на fa146fb1 зелёный ⇒ дешёвые гейты подтверждены» из вводных раунда не подтвердилось при проверке — пришлось прогонять самому. Отдельно завёл #387 (infra, P2, вне скоупа #86) с точным описанием механизма и предложением чинки; на вердикт #86 не влияет, так как содержимое проверено мной исполнением напрямую и оказалось корректным.

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

• 18 «слабых связей» смоков (smoke-select.mjs, общий символ _config) — контент партии 1 не менялся с r3, риск для этих смоков уже признавался низким в r2/r3/r4; не нашёл оснований пересматривать.
• python -m pytest tests_backend — diff не касается ни одного .py файла (git diff origin/dev...HEAD --stat не содержит custom_components/**/*.py).
• npm run invariants / модельные инварианты — diff не трогает геометрию, layout, marker.space, open_spans, толщину стен; ТЗ §11 прямо фиксирует «Config, backend, layout и storage не меняются», подтверждено чтением diff (только шаблоны рендера и i18n).
• performance_smoke — ни ТЗ, ни diff не касаются путей, чувствительных к перфу (чисто DOM/CSS-триггеры уже существующего hp-help из #68).
• Полный demo/smoke_*.mjs набор (206 файлов) — не запускал целиком; smoke-select.mjs даёт 13 прямых совпадений (все прогнаны) и не находит оснований для более широкого прогона.

Одно число — один источник

Diff не добавляет и не меняет ни одной пользовательской величины (числа, единицы, отображаемые значения) — только текстовые подсказки и разметку (id=/<label for=>, helpfieldlabel, обёртки). Единственное число, фигурирующее в контенте — «3.6 м» радиуса свечения на golden-скриншотах — это существующее значение конфигурации, отображаемое ровно один раз (в самом поле), подсказка его не дублирует и не пересчитывает. Проверка test/single-source-numbers.test.mjs входит в зелёный npm test.

AC — построчно

1. AC1 (инвентарь 11 placements). Прочитал diff src/houseplan-editor-runtime.ts/houseplan-onboarding-runtime.ts: 10 новых вызовов this._help('*.help') (space.cell_cm, gs.glow_radius, space.fill_mode, marker.controls, gs.north, space.north, gs.bg_mode, space.bg_mode, space.zero_wall_style, device_inbox.show_hidden) + 1 существующий пилот marker.light_role.help (текст обновлён, trigger не дублирован) = 11. Ровно совпадает с таблицей §6 ТЗ. Тест test/i18n.test.mjs («issue 86 Party 1 has the exact help inventory…») проверяет тот же список и assert.equal(..., 11) — зелёный.
2. AC2 (канонический контент). Сверил построчно все 11 RU/EN пар из diff en.json/ru.json с таблицей §6 ТЗ — совпадают дословно. DE/FR передают тот же смысл (проверил выборочно de.json/fr.json diff — присутствуют все те же 11×2 ключа, непустые).
3. AC3 (parity). npm test включает parity-проверку 4 локалей (часть i18n.test.mjs, покрывающего весь словарь, не только Party 1) — зелёная.
4. AC4 (no duplicates). Diff houseplan-editor-runtime.ts показывает явное удаление старых rhint: gs.bg_daynight_hint (заменено на nothing), gs.north_hint (удалён блок), space.zero_wall_help (удалена строка), marker.controls_hint/.rhint (заменены на helpfieldlabel). Тесты test/i18n.test.mjs («issue 86 removes explanatory hints…», «help hosts do not duplicate their explanation in a title attribute») — зелёные, прогнаны в составе npm test.
5. AC5 (все поверхности). Smoke smoke_help_affordance.mjs прогнан лично: флаги party1GeneralInventory, party1SpaceInventory, party1ShowHiddenHelpIsReadOnly, party1GeneralHelpIsReadOnly, party1SpaceHelpIsReadOnly — все true. Marker dialog проверен чтением (marker.controls.help trigger рядом с label, не внутри него) — паттерн идентичен уже проверенным General/Space.
6. AC6 (input/a11y). Тот же smoke: mouseHover, touchClick, keyboardFocus, escapeHelpFirst, disabledExplanation, shadowFocusables, exclusive — все true. Не новый код для #86 (общий механизм #68), но применённый к новым placements — проверено тем же smoke на новых узлах.
7. AC7 (layout, узкий viewport + 200% zoom). Два канала, как требует ТЗ §14: (а) smoke — флаги party1BrowserZoom200Applied/TriggerInside/ TooltipInside/NoHorizontalOverflow/StageStable — все true, прогнано лично; (б) golden — npm run golden:verify лично, сценарии settings-help-zoom-200-en-light/-ru-dark в списке passed; открыл оба PNG глазами — popover gs.bg_mode.help целиком внутри 390×900 viewport на обеих темах, текст совпадает с каноническим §6. Также визуально открыл docs/images/06-device-editor.png (единственный из 10 docs-скриншотов, реально содержащий новые ⓘ-триггеры после этого ребейза — рядом с «Controls other light sources» и «Is this device a light source?») — подсказки на месте, без визуальных дефектов.
8. AC8 (модель/поведение не меняются). Прочитан весь diff src/houseplan-editor-runtime.ts/onboarding-runtime.ts: единственные изменения — разметка (id=, <label for=>, обёртки helpfieldlabel/ device-inbox-filter-help) и вызовы _help(); ни одного изменения в обработчиках @input/@change, ни в save-путях, ни в config schema. npm test включает существующие снапшоты сериализации конфига — зелёные, не менялись.
9. AC9 (партии 2/3 отсутствуют). grep по diff en.json на добавленные строки, не относящиеся к 11 ключам Party 1 — пусто (только заголовок файла). Просмотрел полный список изменённых файлов (git diff origin/dev...HEAD --stat) — нет файлов, относящихся к проёмам, decor, толщине стен вне уже выпущенной zero_wall_style, размерам room labels.

Трейлеры и changelog

16 коммитов ветки; ровно один с User-Visible: yes (30c15a07 — «feat: add critical settings help content»), и он же в том же коммите обновляет docs/CHANGELOG.md и docs/CHANGELOG.ru.md (проверил git show 30c15a07 -- docs/CHANGELOG*.md). Остальные 15 коммитов (fix/test/docs/build, включая оба пост-ребейзных 04da7eb1/fa146fb1) — User-Visible: no, корректно, так как это тестовые/build/docs-инфраструктурные шаги без нового пользовательского поведения. Все коммиты несут Issue: #86.

Закрытие r4

r4 был зелёным вердиктом (High: 0, Medium: 0) — находок не было, закрывать нечего. Единственное событие между r4 и этим заходом — не правка по замечанию ревью, а внешний ребейз на ушедший вперёд dev (#44), что и потребовало полного, а не дельта-разбора (см. раздел выше).

Унаследовано из r1–r4 (контекст, не молчаливое доверие)

Все пункты ниже перепроверены мной заново на актуальном fa146fb1 (см. раздел AC выше и таблицу гейтов) — перечисляю только для прослеживаемости истории задачи, а не как пропущенную проверку:

• ТЗ (docs/specs/086-settings-help-content-party1.md) прошло ревью ТЗ зелёным в SPEC-REVIEW-86-r1 (коммит 20883c31, домержен без изменений смысла в текущий fa146fb1 — сверил текст файла, содержимое идентично).
• H1/H2 из CODE-REVIEW-86-r1 (подделанный фингерпринт скриншотов, красный golden:verify) закрыты внутри r1 и не всплывали в r2–r4; в r5 канал, поймавший H1 (check-docs.mjs), снова прогнан лично и чист.
• M1 из r2/r3 (AC7 browser zoom 200% без golden-канала) закрыт в r3 двумя golden-сценариями; в r5 они снова открыты глазами (см. AC7).

Находки

В скоупе задачи: нет. High: 0, Medium: 0.

Вне скоупа (заведено отдельно): обнаружен процессный пробел в самом Validate-workflow — job классификации файлов сравнивает изменения с головой предыдущего push, и если тот прогон был cancelled (не «force-push», единственный ранее защищённый случай — issue #347), тяжёлые гейты у следующего push тихо помечаются как нерелевантные, хотя фактически не исполнялись ни разу после ребейза. На вердикт #86 это не повлияло — все затронутые гейты прогнаны лично и прошли зелёными без единой находки. Заведено как #387 (infra, P2, S1-new), со ссылкой на #86.

Вердикт

Зелёный. Party 1 (11 подсказок, 4 локали) полностью соответствует docs/specs/086-settings-help-content-party1.md, ребейз на #44 выполнен без потерь с обеих сторон, все 9 AC доказаны исполнением или чтением кода с явной пометкой, changelog и трейлеры в порядке.