diff --git a/docs/reviews/CODE-REVIEW-323-r1.md b/docs/reviews/CODE-REVIEW-323-r1.md new file mode 100644 index 00000000..248c59bc --- /dev/null +++ b/docs/reviews/CODE-REVIEW-323-r1.md @@ -0,0 +1,176 @@ +# CODE-REVIEW — issue #323, заход r1 + +**SHA материала:** `69facb991882b336a8e4122abf7733faec56d5ba` (после ребейза +конвейером: `fec74ff3` → `69facb99`, поверх легло 1 коммит `dev`; предыдущего +верхнего коммита в родословной ветки нет — это исходный ребейз перед первым +циклом ревью, разбор полный). + +**Трек:** `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-ресурс сохраняются. + +**Класс изменения:** C (документация), без кода — `src/**`, +`custom_components/**/*.py` не тронуты. + +## Скоуп диффа + +``` +README.md | 11 ++++++----- +README.ru.md | 12 +++++++----- +docs/STATUS.md | 2 +- +docs/TESTING.md | 2 +- +4 files changed, 15 insertions(+), 12 deletions(-) +``` + +Два коммита, оба с трейлерами `Issue: #323` / `User-Visible: no`: +- `343af61a` — README.md + README.ru.md: бейдж и секция установки; +- `69facb99` — попутно найденные устаревшие места: строка HACS в + `docs/STATUS.md` (описывала очередь из 835 PR) и пункт установки в + `docs/TESTING.md` (начинался с custom repository). + +## Как проверялось + +### AC — по коду (docs), проверено чтением + +- **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, поведения карточки + правка не касается). + +`hacs.json.name` = `"House Plan (card + storage)"` — поиск по подстроке +«House Plan» в HACS находит запись; формулировка в README не вводит +пользователя в заблуждение. + +### Гейты — прогнаны + +| Гейт | Команда | Результат | +|---|---|---| +| Typecheck | `npx tsc --noEmit` | зелёный, без вывода | +| 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`, не унаследован. + +### Гейты — не прогонялись, и почему + +- `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-пути не задеты. + +## Находки + +### Medium — В СКОУПЕ задачи + +**M1. `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` не обновлены и +противоречат исправленному README.** + +Обе версии полного руководства (на которое README ссылается как на «Full +user guide» / «Полное руководство», и куда RU-README прямо отправляет за +«пошаговыми сценариями») в разделе «HACS» / «Установка через HACS» +по‑прежнему учат добавлять репозиторий вручную: + +``` +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` и взял в работу), не предмет + код-ревью и не блокирует; не выношу отдельной находкой. + +## Вердикт + +High: 0. Medium: 1, в скоупе задачи (M1) — чинится в этом же issue. +Полный набор AC доказан, но задача не закрывает сценарий целиком, пока +второй документ с теми же инструкциями противоречит первому — поэтому +вердикт жёлтый, а не зелёный, несмотря на 0 High.