From 674607694fb2f7cfef3c2e11772885d4f351aeb3 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:12:03 +0000 Subject: [PATCH] docs: review document for #323 Issue: #323 User-Visible: no --- docs/reviews/CODE-REVIEW-323-r1.md | 275 ++++++++++++++--------------- 1 file changed, 128 insertions(+), 147 deletions(-) diff --git a/docs/reviews/CODE-REVIEW-323-r1.md b/docs/reviews/CODE-REVIEW-323-r1.md index 248c59bc..9039dd16 100644 --- a/docs/reviews/CODE-REVIEW-323-r1.md +++ b/docs/reviews/CODE-REVIEW-323-r1.md @@ -1,176 +1,157 @@ -# CODE-REVIEW — issue #323, заход r1 +# CODE-REVIEW — issue #323, заход r2 -**SHA материала:** `69facb991882b336a8e4122abf7733faec56d5ba` (после ребейза -конвейером: `fec74ff3` → `69facb99`, поверх легло 1 коммит `dev`; предыдущего -верхнего коммита в родословной ветки нет — это исходный ребейз перед первым -циклом ревью, разбор полный). +**Примечание о нумерации.** Заголовок задачи, переданный конвейером, указывал +«заход r1 · блокирующих циклов 0 из 2». Это не соответствует фактическому +состоянию: в дереве уже лежит закоммиченный `docs/reviews/CODE-REVIEW-323-r1.md` +(коммит `3b915bd0`, класс C, трейлеры корректны), а в комментариях issue есть +жёлтый вердикт `заход r1 · блокирующих циклов 1/2`, полученный на SHA `69facb99`, +и последующий комментарий владельца «r1 → r2: M1 закрыта» на HEAD `fb8fdf47`. +Текущий разбор — фактически **r2**, бюджет циклов до этого раунда равен **1/2** +(лимит короткого трека — 2, §5.1). Документ ниже назван и оформлен как r2; +если шаг публикации всё же соберёт имя `CODE-REVIEW-323-r1.md` из переданного +заголовка, он затрёт настоящий r1 — заголовок задачи нужно поправить на стороне +конвейера. -**Трек:** `trivial` (§5.1). AC зафиксированы автором в теле issue при переводе -в `S5-ready`: -1. бейдж `HACS-Custom` → `HACS-Default` (README.md, README.ru.md); -2. секция установки — вместо «⋮ → Custom repositories» обычный поиск «House - Plan» в HACS; my-кнопка, перезапуск, добавление интеграции и заметка про - Lovelace-ресурс сохраняются. +**SHA материала:** `fb8fdf479c503992667c45294b28aede2d5056c3` (`git rev-parse HEAD` +непосредственно перед подведением итогов). -**Класс изменения:** C (документация), без кода — `src/**`, -`custom_components/**/*.py` не тронуты. +**Трек:** `trivial` (§5.1), лимит код-ревью — 2 цикла. -## Скоуп диффа +**Класс изменения:** C (документация). `src/**`, `custom_components/**/*.py` не +тронуты ни в этом раунде, ни в r1. + +## Скоуп раунда — дельта r1 → r2 + +Предыдущий вердикт (r1, SHA `69facb99`) — жёлтый, High: 0, Medium: 1 (M1, +в скоупе). Дельта объявлена по `git diff 69facb99..fb8fdf47`: ``` -README.md | 11 ++++++----- -README.ru.md | 12 +++++++----- -docs/STATUS.md | 2 +- -docs/TESTING.md | 2 +- -4 files changed, 15 insertions(+), 12 deletions(-) +docs/USER-GUIDE.md | 6 +++--- +docs/USER-GUIDE.ru.md | 4 ++-- +docs/reviews/CODE-REVIEW-323-r1.md | 176 ++++++++++++++++++++++ (публикация r1 конвейером) +3 files changed ``` -Два коммита, оба с трейлерами `Issue: #323` / `User-Visible: no`: -- `343af61a` — README.md + README.ru.md: бейдж и секция установки; -- `69facb99` — попутно найденные устаревшие места: строка HACS в - `docs/STATUS.md` (описывала очередь из 835 PR) и пункт установки в - `docs/TESTING.md` (начинался с custom repository). +Один продуктивный коммит: `fb8fdf47` — «docs: both user guides install from +the HACS default catalog too», трейлеры `Issue: #323` / `User-Visible: no`, +сообщение коммита прямо ссылается на `CODE-REVIEW-323-r1 M1`. Второй файл в +дельте (`docs/reviews/CODE-REVIEW-323-r1.md`) — собственный doc-коммит +публикации `3b915bd0`, ожидаемый и не являющийся предметом ревью. -## Как проверялось +Дельта локальна: правка ограничена ровно теми двумя файлами, что назвала +находка M1, ничего за пределами её формулировки не задето. Ребейза на ушедший +вперёд `dev` не было (родословная `fb8fdf47` — прямое продолжение `69facb99`), +контракт поведения не менялся, новая подсистема не задета, объём дельты +(10 строк в двух markdown-файлах) многократно меньше исходной задачи. Полный +разбор не требуется — работает сокращение по §2.10. -### AC — по коду (docs), проверено чтением +## Закрытие раунда r1 -- **AC1 (бейдж).** `README.md:3` и `README.ru.md:3` — `HACS-Custom` → - `HACS-Default`, URL и alt-текст остались консистентны с прежним статичным - shields.io-бейджем (не live-бейдж, разница только в тексте/подписи). - Выполнено. -- **AC2 (секция установки).** `README.md:88-95`, `README.ru.md:91-99` — - шаги «⋮ → Custom repositories» / «добавьте URL» убраны, заменены на - «найдите House Plan в поиске HACS и установите»; my-кнопка - (`my.home-assistant.io/.../hacs_repository`), шаг перезапуска, шаг «Add - integration → House Plan» и абзац про ручную регистрацию Lovelace-ресурса - (`resources: /houseplan_files/houseplan-card.js`) сохранены дословно. - Выполнено. Проверено чтением, не исполнением (docs-only, поведения карточки - правка не касается). +| Находка r1 | Чем закрыта | Где видно | +|---|---|---| +| **M1** — `docs/USER-GUIDE.md` (82-83) и `docs/USER-GUIDE.ru.md` (82) учили добавлять custom-репозиторий вручную, противореча исправленному README | Шаг 1 в обоих файлах переписан: поиск «House Plan» в HACS, явная фраза «no custom repository needed» / «пользовательский репозиторий добавлять не нужно» — по образцу формулировки README | `docs/USER-GUIDE.md:82-83` (diff `69facb99..fb8fdf47`, коммит `fb8fdf47`); `docs/USER-GUIDE.ru.md:82` (тот же коммит). Проверено чтением: `sed -n '75,90p' docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` после правки, сверено построчно с формулировкой `README.md:88-91` / `README.ru.md:91-95` — смысл идентичен (входит в default-каталог, custom repository не нужен), терминология «основной каталог HACS» совпадает между RU-README и RU-USER-GUIDE | -`hacs.json.name` = `"House Plan (card + storage)"` — поиск по подстроке -«House Plan» в HACS находит запись; формулировка в README не вводит -пользователя в заблуждение. +Дополнительно перепроверено grep'ом по всему трекаемому дереву (не только +`.md`, без исключений кроме CHANGELOG/reviews/specs, чтобы не полагаться +на грепы r1 без проверки): `git grep -rniE "custom.{0,25}repositor|HACS-Custom|пользовательск\S*\s+репозитор|custom.{0,15}Integration.{0,15}repositor"` +находит только четыре ожидаемых строки — по одной новой формулировке в каждом +из четырёх файлов (README.md, README.ru.md, USER-GUIDE.md, USER-GUIDE.ru.md). +Ни устаревших упоминаний, ни расхождений в `custom_components/**`, `src/**` +или где-либо ещё не осталось. M1 закрыта полностью, новых мест с тем же +дефектом дельта не оставила. -### Гейты — прогнаны +## Унаследовано из r1 + +Без повторной проверки в этом раунде, ссылка — `docs/reviews/CODE-REVIEW-323-r1.md` +на SHA `69facb99`: + +- **AC1** (бейдж `HACS-Custom` → `HACS-Default` в README.md/README.ru.md) — + дельта r1→r2 не трогает README, доказательство r1 не устарело. +- **AC2** (секция установки README — поиск вместо custom repository, my-кнопка/ + restart/add integration/YAML-ресурс сохранены) — та же причина, README не в + дельте. +- Правки `docs/STATUS.md` и `docs/TESTING.md` (коммит `69facb99`) — вне дельты + этого раунда, признаны корректными в r1. +- Трейлеры `Issue: #323` / `User-Visible: no` на коммитах r1 (`343af61a`, + `69facb99`) — проверены в r1, не переоценивались повторно. +- Обоснование непрогона `check-docs.mjs`, инвариантов геометрии, смоков, + `golden:verify`, backend-тестов и perf-профилей для диффа README/STATUS/TESTING + (docs-only, `src/**` и геометрия не задеты) — рассуждение переносится и на + делту r2, поскольку она тоже чисто текстовая и тоже не касается `src/**`. +- Пункт «чего не проверял» из r1 (живой поиск в HACS UI, докс-скриншоты, + отсутствие типа `bug` на трек `trivial`) — сохраняет силу, дельта этого + раунда на эти пункты не влияет. + +## Гейты этого раунда + +Дешёвые гейты прогнаны заново на `fb8fdf47`, как требует §2.10 (код/дерево +изменились с r1, а стоят гейты минуты): | Гейт | Команда | Результат | |---|---|---| -| Typecheck | `npx tsc --noEmit` | зелёный, без вывода | +| Typecheck | `npx tsc --noEmit` | зелёный, без вывода, exit 0 | +| Build | `npm run build` | зелёный, `dist/houseplan-card.js` собран за 11.9s | +| Синхронность копий бандла | `git status --short dist/ custom_components/houseplan/frontend/ demo/srv/assets/` + `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | пусто / идентичны — класс D не менялся | | Unit-тесты | `npm test` | зелёный: 1358 объявлено, 1357 pass, 1 skipped, 0 fail | -| Build | `npm run build` | зелёный, `dist/houseplan-card.js` собран за 9.3s | -| Синхронность трёх копий бандла | `git status --short` после build | пусто — `dist/`, `custom_components/houseplan/frontend/`, `demo/srv/assets/` не тронуты и не разошлись (класс D не менялся, дифф его и не затрагивал) | -Три гейта прогнаны, потому что они всегда дешёвые и прогоняются в каждом -раунде независимо от объёма диффа — их результат актуален именно для -`69facb99`, не унаследован. +Не прогонялись, причина не изменилась относительно r1 (дельта тоже docs-only, +не касается `src/**`, геометрии, рендера, backend): -### Гейты — не прогонялись, и почему +- `node scripts/check-docs.mjs` — дельта не трогает `src/**`, отпечаток + скриншотов не мог устареть от правки в двух markdown-файлах руководства. +- `npm run invariants -- --config …` — geometry/`layout`/толщина стен/ + `marker.space`/`open_spans` не задеты ни разу за оба раунда. +- Браузерные смоки (`demo/smoke_*.mjs`) — изменённые символы это markdown-текст + `docs/USER-GUIDE*.md`, не код/тест; `smoke-select.mjs` не запускал по той же + причине, что и в r1 (инструмент ищет связи по изменённым символам кода/тестов, + а не по тексту руководств вне `demo/`). +- `npm run golden:verify` — рендер, геометрия, стили не менялись. +- `python -m pytest tests_backend -q` — `custom_components/**/*.py` не тронут. +- Perf-профили — не названы в AC, не задеты. -- `node scripts/check-docs.mjs` — не нужен: диплом не трогает `src/**`, - отпечаток скриншотов не может устареть от правки в README/STATUS/TESTING. -- `npm run invariants -- --config …` — геометрия, `layout`, толщина стен, - `marker.space`, `open_spans` диффом не затронуты. -- Браузерные смоки (`demo/smoke_*.mjs`) — диплом не меняет ни одной - видимой в карточке строки или поведения; `node scripts/smoke-select.mjs` - не запускал, т.к. измененные символы — это markdown-текст README/STATUS/ - TESTING, а не код/тесты, по которым инструмент ищет связи. Смоки - рендерят `demo/srv/demo.html`, README/STATUS/TESTING в это дерево не - попадают. -- `npm run golden:verify` — рендер, геометрия и стили не менялись. -- `python -m pytest tests_backend -q` — `custom_components/**/*.py` не - тронут. -- Perf-профили — не названы в AC, geometry/perf-пути не задеты. +«Одно число — один источник»: дельта не вводит и не меняет пользовательских +числовых величин; текстовая формулировка «в основном каталоге HACS, custom +repository не нужен» теперь идентична между README и USER-GUIDE на обоих +языках (см. таблицу закрытия M1 выше) — именно то расхождение, которое r1 +поймал как Medium, теперь устранено единообразно. -## Находки +## Находки этого раунда -### Medium — В СКОУПЕ задачи +Нет. High: 0, Medium: 0, Low: 0. Дельта — точечный фикс, ничего нового не +внесла и не задела соседнее поведение. -**M1. `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` не обновлены и -противоречат исправленному README.** +## Проверено и корректно -Обе версии полного руководства (на которое README ссылается как на «Full -user guide» / «Полное руководство», и куда RU-README прямо отправляет за -«пошаговыми сценариями») в разделе «HACS» / «Установка через HACS» -по‑прежнему учат добавлять репозиторий вручную: +- M1 закрыта: оба полных руководства (EN/RU) больше не учат ручному добавлению + custom-репозитория и текстуально согласованы с README. +- Расширенный grep (не только `.md`, без предположения, что r1 нашёл всё) + подтверждает отсутствие других мест с тем же устаревшим паттерном. +- Коммит `fb8fdf47` несёт корректные трейлеры (`Issue: #323`, + `User-Visible: no`); `User-Visible: no` обоснован — поведение карточки/ + интеграции не меняется, только текст документации, changelog-файлы не + тронуты (согласуется). +- Класс D (`dist/**`, `custom_components/houseplan/frontend/**`, + `demo/golden/baselines/**`) не менялся ни в дельте, ни ранее. +- Doc-коммит публикации r1 (`3b915bd0`) корректно трейлерован и не является + предметом ревью — ожидаемый служебный коммит конвейера. -``` -docs/USER-GUIDE.md:82-83 -1. Add `https://github.com/Matysh/houseplan-card` to HACS as a custom - **Integration** repository. +## Чего не проверял -docs/USER-GUIDE.ru.md:82 -1. В HACS добавьте `https://github.com/Matysh/houseplan-card` как - пользовательский репозиторий категории **Integration**. -``` - -**Воспроизведение:** пользователь читает README → видит «House Plan is in -the HACS default catalog — no custom repository needed», переходит по -ссылке «Full user guide» за подробностями → получает противоположную и -устаревшую инструкцию (добавить custom repository вручную) в том же самом -разделе «HACS». Это ровно та проблема, которую issue #323 ставит целью -убрать («лишние шаги, которых больше не требуется»), просто в соседнем -файле того же класса C. - -Автор этой же ветки уже расширял скоуп за пределы «только README»: коммит -`69facb99` правит `docs/STATUS.md` и `docs/TESTING.md` как «попутно -найденные устаревшие места» — тот же тип дефекта (стале-упоминание -custom-repository потока), тот же класс C. USER-GUIDE — тот же случай, -не пойманный при том же самом sweep (вероятная причина: непрямое -совпадение по тексту — «custom **Integration** repository» с жирным между -словами в EN и строчная «пользовательский» без грепаемого «HACS-Custom» в -RU, — оба ускользают от точного grep по фразе «custom repository»). - -Без этой правки задача не решает заявленный сценарий полностью: у -пользователя остаётся действующий (и более заметный, т.к. это «полное -руководство») путь к устаревшей инструкции. - -**Что делать:** привести шаг 1 в обоих `docs/USER-GUIDE*.md` к тому же -виду, что и в README (поиск в HACS вместо добавления custom-repository), в -рамках этого же issue — Medium в скоупе, отдельный issue не заводится -(#202). - -Других мест с той же формулировкой не нашлось (проверено -`grep -rniE "custom.{0,20}repositor|HACS-Custom|пользовательск\S*\s+репозитор" ---include="*.md" .`, исключая CHANGELOG и `node_modules`; `docs/DEVELOPMENT.md`, -`CONTRIBUTING.md` чисты). - -### Проверено и корректно - -- Бейдж и секция установки в обоих README согласованы между собой (EN/RU), - порядок шагов и сохранённые фрагменты (my-кнопка, restart, add - integration, YAML-ресурс) идентичны прежним, кроме заменённого шага. -- `docs/STATUS.md` HACS-строка и `docs/TESTING.md` install-чеклист приведены - в соответствие факту (`hacs/default#9004` merged 2026-08-25) без потери - информации (post-merge checklist сохранён). -- Трейлеры `Issue: #323` / `User-Visible: no` на обоих коммитах корректны: - продукт (карточка/интеграция) не меняется, значит changelog не требуется. -- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md` не тронуты — согласуется с - `User-Visible: no`. -- Диплом не трогает `dist/**`, `custom_components/houseplan/frontend/**`, - `demo/golden/baselines/**` (класс D) — верно для чисто текстовой правки. -- «Одно число — один источник»: числовых пользовательских величин дифф не - вводит и не меняет, правило не применимо к этому диффу за вычетом M1, - которое устройство ровно того же типа дефекта, но текстовое, а не - числовое. - -### Чего не проверял (и осознанно) - -- Живой поиск «House Plan» в HACS UI — недоступен в окружении ревьюера (нет - запущенного HA/HACS-инстанса); утверждение принято по ссылке на - `hacs/default#9004` (merged, зафиксировано владельцем в чате 2026-08-27, - процитировано в теле issue) и по `hacs.json.name`. -- Скриншоты/докс-фингерпринт — не проверялись, т.к. `src/**` не тронут и - `check-docs.mjs` не применим (см. таблицу гейтов выше). -- Отсутствие меты типа (`bug`/`feature`/`tech-debt`) на issue #323 при - наличии `trivial` — замечено (§5.1 требует тип `bug` в списке критериев - короткого трека), но это принятое владельцем в `S2-analysis` решение - (владелец лично перевёл в `S5-ready` и взял в работу), не предмет - код-ревью и не блокирует; не выношу отдельной находкой. +- Живой поиск «House Plan» в интерфейсе HACS — недоступен в окружении + ревьюера; унаследовано из r1 без повторной попытки. +- Докс-скриншоты/фингерпринт — не проверялись, `src/**` не тронут, `check-docs.mjs` + не применим ни в r1, ни в r2. +- Отсутствие меты типа (`bug`/`feature`/`tech-debt`) на issue при наличии + `trivial` — уже отмечено и принято в r1 как решение владельца, не предмет + этого раунда. ## Вердикт -High: 0. Medium: 1, в скоупе задачи (M1) — чинится в этом же issue. -Полный набор AC доказан, но задача не закрывает сценарий целиком, пока -второй документ с теми же инструкциями противоречит первому — поэтому -вердикт жёлтый, а не зелёный, несмотря на 0 High. +High: 0. Medium: 0. M1 из r1 закрыта полностью и без побочных находок. Все +AC (унаследованные из r1, дельта их не задевает) доказаны; дополнительная +находка r1, из-за которой стоял жёлтый, устранена — задача теперь решает +заявленный сценарий целиком: и README, и полное руководство на обоих языках +согласованно говорят «House Plan уже в default-каталоге HACS, custom +repository не нужен». + +Вердикт: зелёный.