From e88c23b8eeee6de829bcdbf7ea76b2ce961fda92 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Wed, 19 Aug 2026 00:11:27 +0000 Subject: [PATCH] docs: review document for #113 Issue: #113 User-Visible: no --- docs/reviews/CODE-REVIEW-113-r3.md | 176 +++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/reviews/CODE-REVIEW-113-r3.md diff --git a/docs/reviews/CODE-REVIEW-113-r3.md b/docs/reviews/CODE-REVIEW-113-r3.md new file mode 100644 index 00000000..2c37ca92 --- /dev/null +++ b/docs/reviews/CODE-REVIEW-113-r3.md @@ -0,0 +1,176 @@ +# CODE-REVIEW-113-r3 — post-merge `docs` gate refresh, no product change + +- **Issue:** https://github.com/Matysh/houseplan-card/issues/113 +- **ТЗ:** `docs/specs/113-optional-space-model.md`, ревью ТЗ — `docs/reviews/SPEC-REVIEW-113-r1.md` + (зелёный, Medium-1 → #184, не блокирует) +- **Предыдущие циклы:** + - `docs/reviews/CODE-REVIEW-113-r1.md` — зелёный, High 0, Medium 0. Автослияние не прошло + (конфликт ветки с `dev`), возврат в `S6-in-progress` за ребейзом, не за переделкой. + - `docs/reviews/CODE-REVIEW-113-r2.md` — зелёный, High 0, Medium 0, после ребейза на + `dev`=`c1676cf`. Пайплайн слил ветку в `dev` и поставил `S8-merged`. + - После слияния параллельный прогон Validate на `dev` показал красный job `docs` + (`node scripts/check-docs.mjs --external`): встроенный в `docs/images/screenshots.json` + `sourceFingerprint` устарел относительно `src/**`, изменённого продуктовым коммитом #113 + (`_spaceModel`/`src/space-model-selection.ts`). Автор исправил это отдельным docs-only + коммитом и вернул issue `S6-in-progress` → `S7-code-review`, чтобы не оставлять `dev` + красным без повторной проверки (комментарий автора от 2026-08-19). +- **Диапазон:** `origin/dev..HEAD` = один коммит `acad3b3` («Refresh documentation source + fingerprint»). `git merge-base origin/dev HEAD` = `origin/dev` (`b443a33`) — линейно, без + дивергенции и без конфликта. +- **Цикл:** r3/4 (счётчик по этапу код-ревью) +- **Роль:** ревьюер кода (Claude), свежая сессия, без контекста реализации и без контекста + собственных прогонов r1/r2. + +## 1. Скоуп цикла r3 + +Единственный коммит диапазона, `acad3b3`: + +``` +docs/images/screenshots.json | 22 +++++++++++----------- +1 file changed, 11 insertions(+), 11 deletions(-) +``` + +Меняются только два повторяющихся поля манифеста — `sourceFingerprint` (один раз, в шапке) и +`sourceSha256` (в каждом из 10 сценариев, то же самое значение). Ни один PNG-файл, ни +`captureScriptSha256`, ни `imageSha256`, ни любой файл класса A/B в диапазоне не меняется — +подтверждено самим `git diff --stat` (единственный изменённый путь) и построчным чтением +diff'а (изменились ровно две пары хеш-строк на сценарий, форма и остальные поля манифеста — +`viewport`/`theme`/`language`/`file`/`imageSha256` — идентичны). + +Класс файла — `docs/**` (класс C, `AGENTS.md`). Продуктовый код (`src/houseplan-card.ts`, +`src/space-model-selection.ts`) в этом коммите не тронут — байт в байт совпадает с тем, что +получило зелёный вердикт в r1/r2 (тот же вывод, что и в r2: `origin/dev` уже содержит +реализацию #113, в этом коммите нет новых продуктовых строк). + +`Issue: #113` / `User-Visible: no` — корректно: манифест скриншотов документации не является +пользовательским интерфейсом, а сами PNG не изменились (см. §2) — то есть это не «видимое +изменение», а служебная синхронизация fingerprint-гейта с уже принятым исходным кодом. + +Это не переход на новую фичу и не расширение скоупа #113: единственная причина коммита — +починка гейта, который стал красным из-за уже принятого продуктового изменения этого же issue, +не из-за постороннего кода. Формально это ближе к «предрелизному гейту» из `PROCESS.md` §11.4 +(гейт называет дефект точно, исправление проверяется тем же гейтом), хотя `docs` — job, +запускаемый на каждый push, а не строго pre-beta; автор осторожно выбрал полный цикл ревью +вместо исключения §11.4, что процессом не запрещено и не требует правки с моей стороны. + +## 2. Как проверялось — таблица гейтов + +| Гейт | Команда | Результат | +|---|---|---| +| Typecheck | `npx tsc --noEmit` | OK, без ошибок | +| Unit | `npm test` | `877/877` OK — идентично r2 (продуктовый код не менялся) | +| Build + 3 копии бандла | `npm run build`, затем `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | OK, обе сверки — байт-в-байт совпадение | +| **Именно упавший гейт** | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links).` — зелёный на итоговом дереве | +| **Пересчёт fingerprint напрямую** | `node -e "import('./scripts/source-fingerprint.mjs').then(({sourceFingerprint}) => console.log(sourceFingerprint(process.cwd())))"` | `b58a522cc70add7b12071bb5340ad3a1ad694c1979a39b46c2cb0b73fd719333` — **совпадает байт-в-байт** с `sourceFingerprint`, записанным в коммите | +| Process gate | `node scripts/process-gate.mjs --issues` | `диапазон origin/dev..HEAD, коммитов 1`, `гейт пройден, предупреждений 0` | + +**Не прогонялось, и почему:** + +- **Браузерные смоки (127+)** — не прогонялись. Диапазон не меняет ни строки `src/**`, ни + `demo/**`-кода, ни фикстур; единственный изменённый файл — JSON-манифест, потребляемый только + `check-docs.mjs`. Ни одна из тронутых поверхностей (документационные скриншоты) не имеет + функционального пути в карточке — прогон смоков не добавил бы информации к тому, что уже + зелено в r1/r2 на идентичном продуктовом коде. +- **`npm run golden:verify`** — не прогонялся. `docs/images/screenshots.json` — отдельный от + golden-эталонов (`demo/golden/baselines/**`) манифест с собственным гейтом (`check-docs.mjs`), + который прогнан и зелёный. Продуктовый рендер не менялся, пиксельного риска golden-эталонов + нет. +- **`python -m pytest tests_backend`** — не тронут ни один файл `custom_components/**/*.py`. +- **Performance-профили** — не названы в AC, ни один hot-path не тронут; диапазон не содержит + кода вообще, только JSON-метаданные. +- Обоснование сознательное, соразмерное объёму диапазона (PROCESS.md §8): один изменённый файл, + один назначенный ему гейт (`check-docs.mjs`), гейт прогнан и зафиксирован именно с помощью + команды и её результата — не «verified» без доказательства. + +## 3. Проверка AC (docs/specs/113-optional-space-model.md §10) + +Продуктовый код, доказывающий AC1–AC10, не менялся в этом цикле (§1) — доказательства r1/r2 +переносятся без изменений. Этот коммит не реализует ни одного AC заново; ниже — что именно +перепроверено на итоговом дереве, а не процитировано. + +| AC | Статус в r3 | +|---|---| +| AC1–AC10 | Код не менялся относительно r2 (единственный файл диапазона — `docs/images/screenshots.json`, не участвующий ни в одном AC из §10 ТЗ). `npx tsc --noEmit` и `npm test` (877/877) перепрогнаны на итоговом дереве и зелёные — подтверждают отсутствие регрессии, не переоткрывая доказательства по существу. | + +Единственное новое утверждение этого цикла — не AC ТЗ #113, а факт того, что манифест +документационных скриншотов синхронизирован с текущим `src/**`. Оно доказано исполнением +(`check-docs.mjs` зелёный + независимый пересчёт fingerprint, см. §2), а не пересказом. + +## 4. Дисциплина «тест умеет падать» — что проверено исполнением + +- **`check-docs.mjs` умеет падать на этом классе дефекта** — до `acad3b3` (на состоянии `dev` + сразу после слияния r2) этот же скрипт краснел в CI ровно с сообщением `screenshot source + fingerprint is stale; run npm run build && node demo/docs/capture.mjs` (см. слово автора и + сам факт, что job `docs` был красным в Validate). Причина понятна и воспроизводима логикой + скрипта (`scripts/check-docs.mjs:118-119`): сравнение `manifest.sourceFingerprint !== + sourceFingerprint(ROOT)`; это прямое сравнение, которое **обязано** покраснеть при любом + расхождении, а не эвристика, которую можно обмануть. +- **Пересчёт fingerprint выполнен независимо от `check-docs.mjs`**, отдельным вызовом + `sourceFingerprint()` через `node -e`, и его значение сверено вручную с байтами, записанными + в коммите — совпадение подтверждает, что коммит не мог быть подделан (вписан руками) и что он + действительно является продуктом `npm run build && node demo/docs/capture.mjs` на этом дереве, + как и заявлено автором. +- **PNG не менялись** — сам `git diff --stat` не содержит ни одного `.png`-пути; отдельно + `check-docs.mjs` сверяет `scenario.imageSha256` с фактическим SHA-256 файла на диске для всех + 10 сценариев и прошёл зелёным — то есть на диске лежат ровно те же байты, что были приняты в + r1/r2, а не новый, неотрецензированный рендер. + +## 5. Находки + +Нет находок High. Нет находок Medium в диапазоне этого коммита. + +**Наблюдение вне скоупа диффа** (не находка кода #113, заведено отдельным issue по правилу +преамбулы `PROCESS.md`: «расхождение процесса с фактической автоматизацией не игнорируется, а +заводится issue с меткой `process`»): канонический список Validate-джобов в `AGENTS.md` («CI is +pinned to an exact SHA... Jobs: `provenance`, `hacs`, `hassfest`, `frontend`, `smoke`, `golden`, +`performance_smoke`, `backend`») не упоминает job `docs`, который и стал причиной этого цикла. +Строка `AGENTS.md` не менялась с `0f8d35f` (2026-08-14), `docs`-job/`check-docs.mjs` появился +позже, `88a647f` (2026-08-16) — это и есть расхождение, а не пересказ известного факта. Заведён +[#191](https://github.com/Matysh/houseplan-card/issues/191) (`process`, `docs`, `P3`), не +блокирует #113 — сам этот коммит корректно работает с фактическим, не с задокументированным, +набором гейтов. + +## 6. Что проверено и корректно + +- Диапазон `origin/dev..HEAD` линеен (`git merge-base origin/dev HEAD == origin/dev`) — ветка не + разошлась, конфликта нет, ребейз не требуется. +- Единственный изменённый файл диапазона — `docs/images/screenshots.json`, класс C; не задевает + ни одного файла класса A/B. Трейлеры коммита (`Issue: #113`, `User-Visible: no`) соответствуют + содержанию (нет пользовательского поведения, только служебные хеши). +- `sourceFingerprint`/`sourceSha256`, записанные в коммите, воспроизведены независимым прогоном + `sourceFingerprint()` на этом дереве и совпали байт-в-байт — коммит не является догадкой или + скопированным чужим значением. +- `captureScriptSha256` и все 10 `imageSha256` в манифесте не изменились и совпадают с файлами на + диске (подтверждено зелёным `check-docs.mjs`) — PNG не перегенерировались заново без рецензии, + ранее принятые скриншоты используются как есть. +- Продуктовый код (`src/houseplan-card.ts`, `src/space-model-selection.ts`) байт-в-байт идентичен + версии, получившей зелёный вердикт в r1 и повторно в r2 — AC1–AC10 не требуют переоткрытия. +- Быстрые гейты (`tsc --noEmit`, `npm test` 877/877, `npm run build` + сверка 3 копий бандла) — + зелёные на итоговом дереве. +- `node scripts/process-gate.mjs --issues` — зелёный, 0 предупреждений, диапазон 1 коммит. +- `docs/CHANGELOG.md`/`docs/CHANGELOG.ru.md` корректно не тронуты — `User-Visible: no`. + +## 7. Чего не проверял + +- Полный набор браузерных смоков и `golden:verify` — обоснование в §2 (диапазон не содержит ни + строки `src/**`/`demo/**`-кода, только JSON-манифест документационных скриншотов). +- `pytest tests_backend` — класс A/B бэкенда не тронут. +- Performance-профили — не названы в AC, не затронуты (диапазон без кода). +- Содержательное AC1–AC10 переисполнение «с нуля» — не требуется: продуктовый код не менялся + байт в байт относительно r1/r2 (подтверждено `git diff --stat`, не предположением). +- Medium-1/#184 (fallback-семантика ТЗ §6, explicit-id команды) — по-прежнему отдельный issue вне + скоупа этого код-ревью. +- Правомерность конкретно выбранного автором пути (полный цикл вместо §11.4-исключения) по + существу не оценивалась дальше констатации, что оба варианта процессом допустимы для этого + случая; выбор автора не создаёт находки. + +## 8. Вердикт + +Единственный коммит цикла — служебная синхронизация fingerprint-манифеста документационных +скриншотов с уже принятым (дважды зелёным) продуктовым кодом #113; PNG не менялись, продуктовый +код не менялся, упавший гейт (`check-docs.mjs`) воспроизведён и подтверждён зелёным, а записанный +в коммите fingerprint независимо пересчитан и совпал байт-в-байт. Все быстрые гейты зелёные. +High: 0. Medium: 0 в диапазоне диффа. Одно наблюдение вне скоупа диффа заведено отдельным issue +(#191, `process`), не блокирует. + +**Вердикт: зелёный · цикл r3/4 · High: 0 · Medium: 0 → #191 (вне скоупа диффа, не блокирует) · Документ: docs/reviews/CODE-REVIEW-113-r3.md**