From f86bc34dd565053ab5e922ae3e100ab5376161cf Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:11:01 +0000 Subject: [PATCH] docs: review document for #628 Issue: #628 User-Visible: no --- docs/reviews/CODE-REVIEW-628-r1.md | 172 +++++++++++++++++++++++++++++ docs/reviews/INDEX.md | 1 + 2 files changed, 173 insertions(+) create mode 100644 docs/reviews/CODE-REVIEW-628-r1.md diff --git a/docs/reviews/CODE-REVIEW-628-r1.md b/docs/reviews/CODE-REVIEW-628-r1.md new file mode 100644 index 00000000..ddfe2b27 --- /dev/null +++ b/docs/reviews/CODE-REVIEW-628-r1.md @@ -0,0 +1,172 @@ +# CODE-REVIEW-628-r1 + +Issue: #628 · Материал раунда: `66b2b576aee86e905a620722d7dd7acf3a71ee57` (HEAD, +рабочая копия на нём) · диапазон `origin/dev..HEAD`. + +## Скоуп + +Инфраструктурная задача без ТЗ (трек «infrastructure-only», AGENTS.md): +владелец выбрал вариант 1 из четырёх, предложенных в теле issue — разовый +`git gc --prune=now` клона на Windows-машине владельца, замер до/после, +фиксация решения в `docs/DEVELOPMENT.md`. LFS, единая копия бандла в git и +перезапись истории явно отклонены владельцем (комментарии от 2026-09-24 и +2026-09-25). + +AC из тела issue: +- **AC1** — решение владельца зафиксировано в `docs/DEVELOPMENT.md`. +- **AC2** — прирост пака за следующий месяц ≤ 20 MiB, тот же `count-objects`. + +Диапазон `origin/dev..HEAD` — ровно один коммит: + +``` +66b2b576 docs: record repository GC baseline +``` + +Диф — ровно один файл, `docs/DEVELOPMENT.md`, +27/-0. Не класс A: код +(`src/**`, `custom_components/**/*.py`, манифесты, i18n) не тронут — задача +законно вошла в конвейер напрямую на `S7-code-review`, минуя `S1`…`S6`. +Трейлеры коммита: `Issue: #628`, `User-Visible: no` — верно для документации, +не меняющей продукт; правка обоих CHANGELOG не требуется и не сделана. + +## Как проверялось + +- Прочитаны тело issue #628 и все 4 комментария (вопросы владельца с + умолчаниями от 2026-09-24, ответ «вариант 1» от 2026-09-25, взятие в работу, + итоговый отчёт с фактическими командами и числами). +- `git log --oneline origin/dev..HEAD` и `git diff origin/dev...HEAD` — + материал раунда подтверждён, дифф прочитан целиком (27 строк, приведён + выше). +- Арифметика внесённых чисел пересчитана вручную: + - до GC: 749.84 (loose) + 334.55 (packs) = **1084.39 MiB** — совпадает с + текстом «fell from 1,084.39 MiB»; + - после GC: 0 (loose) + 467.63 (packs) = **467.63 MiB** — совпадает; + - разница: 1084.39 − 467.63 = **616.76 MiB** — совпадает с текстом; + - принятая верхняя граница AC2: 467.63 + 20 (порог AC2) = **487.63 MiB** — + совпадает с текстом. + Все четыре числа в документе внутренне согласованы, источник порога — AC2 + из тела issue, дублирования с конфликтующим значением нигде не найдено + (`grep -rn "size-pack|count-objects|git gc" docs/` — единственное упоминание + во всём `docs/**`, само `docs/DEVELOPMENT.md`). +- `node scripts/check-docs.mjs --screenshots=warn` — прогнал сам (диф не + трогает `src/**`, гейт не обязателен, но дешёвый): `Documentation checks + passed (7 files, 12 external links)`, есть неотносящееся к диффу + предупреждение про устаревший fingerprint скриншотов на `dev` — то же самое, + что автор указал в issue-комментарии. +- Проверена структура заголовков всего файла (`grep -n '^#' docs/DEVELOPMENT.md`) + и прочитан контекст вставки (строки ~93–236) целиком, чтобы понять, в какую + секцию попал новый раздел и что было до/после него. + +## Находки + +### Medium (в скоупе задачи, чинится в этом же раунде) + +**Новый раздел разрывает существующую секцию «Local Windows workstation» и +меняет владельца подсекции «File-sync pitfalls».** + +- Файл: `docs/DEVELOPMENT.md` +- Строки диффа: вставка после строки 167 (`git config core.untrackedCache + true` + закрывающий ``` ```), перед исходной строкой 168 + (`### ⚠️ File-sync pitfalls (critical)`). +- Воспроизведение: до диффа секция `## Local Windows workstation` (начинается + на исходной строке 93) заканчивалась абзацем про `git config + core.fsmonitor/core.untrackedCache` и затем без разрыва переходила в свою + подсекцию `### ⚠️ File-sync pitfalls (critical)` — про ненадёжность + сетевого mount при редактировании и сборке на Windows, тема, не связанная + ни с #628, ни с `git gc`. Новый уровень-2 заголовок `## Local repository + maintenance (#628)` вставлен ровно между ними. Формально уровни заголовков + не нарушены (`##` на своём месте), но логически подсекция `### + File-sync pitfalls` теперь читается как часть раздела о разовом `git gc`, а + не как часть раздела про настройку Windows-рабочей станции, которому она + принадлежит по смыслу и куда попала бы любая навигация по дереву + заголовков (TOC-скрипты, IDE outline, `grep -n '^#'`). Читатель, ищущий + «почему нельзя редактировать файлы через сетевой mount», найдёт этот пункт + под заголовком про garbage collection репозитория — вводит в заблуждение + ровно там, где документ единственная страховка (эта же папка отмечена как + «⚠️ critical»). +- Почему это не Low: единственная продукция этой задачи — текст документа; + структурная ошибка в нём — дефект в самой поставке, а не косметика. Задача + дешёво чинится перестановкой блока (переместить новый `##`-раздел после + `### File-sync pitfalls` и перед `## Tests`, либо перед `## Local Windows + workstation`), без изменения содержания. +- Чем доказано: проверено чтением (`git diff`, `grep -n '^#'`, + прочитан весь диапазон строк 93–236 до и после точки вставки) — не + исполнением, для документации исполнения не требуется. + +Других находок нет. + +## Что проверено и корректно + +- **AC1** — решение владельца зафиксировано текстом, который совпадает с + тем, что владелец выбрал в комментариях (вариант 1 из «Варианты» issue-тела; + явные исключения LFS/удаление `dist/**`/перезапись истории воспроизводят + умолчания-отказы владельца по вопросам 2–4 из первого комментария). + Проверено чтением issue + диффа. +- **AC2** — документ не может «закрыть» этот AC сейчас (проверка назначена на + 2026-10-25 и позже), но правильно фиксирует измеримый критерий: базовая + величина 467.63 MiB, порог ≤20 MiB из AC2, принятая верхняя граница 487.63 + MiB, и явная команда для будущего замера (`git gc --prune=now`, `git + count-objects -vH`, сравнение `size-pack`). Это ровно то, что можно + зафиксировать в рамках этой задачи; сам будущий замер — не предмет этого + ревью. +- Арифметика всех четырёх чисел в новом разделе пересчитана и подтверждена + (см. «Как проверялось»). +- Трейлеры коммита корректны: `Issue: #628`, `User-Visible: no`; ни один + changelog не тронут — и не должен быть, изменение не видно пользователю + продукта. +- Дифф не касается `src/**`, `custom_components/**/*.py`, манифестов, i18n, + `test/**`, `scripts/**`, геометрии — ни один защитный AC, ни один + автотестируемый контракт этой задачей не затронут; таблица «AC · чем + доказан · чем краснеет» не требуется, потому что в задаче нет защитного AC + (валидации/гарда/лимита/отказа/инварианта) — оба AC описательные + (зафиксировать решение / измерить рост). +- Однократность действия (не повторяющийся `git gc` в CI, не CRON) — + подтверждена и текстом раздела, и тем, что диф не трогает + `.github/workflows/**` и `scripts/**`. +- Единственность источника чисел: `size-pack`/`count-objects`/`git gc` + встречаются в `docs/**` только в этом новом разделе — нет второго места, где + та же величина продублирована с другим значением. + +## Чего не проверял и почему + +- **`npx tsc --noEmit`, `npm test`, `npm run build` (сверка бандла)** — не + перегонял: диф не содержит кода, только `docs/DEVELOPMENT.md`; кроме того + Validate на этом же SHA `66b2b576` уже зелёный + (https://github.com/Matysh/houseplan-card/actions/runs/36121805309), + что покрывает эти дешёвые гейты. +- **Смоки, golden, `pytest tests_backend`, инварианты модели, + performance-профили** — не прогонял: диф не касается рендера, геометрии, + Python-кода интеграции или производительности; ни один из них не назван в + AC1/AC2. `node scripts/smoke-select.mjs` не запускал по той же причине — + диф не в `src/**`/`demo/**`, смок-выбор не применим к markdown-only диффу. +- **Сам замер AC2 (`git gc` + `count-objects` на 2026-10-25 или позже)** — не + мой предмет: это будущая проверка, которую документ только готовит; в этом + раунде оценивается полнота и корректность подготовки, не результат. +- **Повторный запуск владельческого `git gc --prune=now` на Windows-клоне** — + не выполнял и не мог: у ревьюера нет доступа к машине владельца, а числа до/ + после в issue-комментарии — отчёт владельца о собственном действии, не + проверяемый из песочницы; я перепроверил только внутреннюю арифметику + перенесённых в документ чисел (см. выше), не первичный факт их измерения. +- **Разбор навигации doc-tooling (TOC-генераторы, `scripts/check-docs.mjs` + на предмет заголовков)** — `check-docs.mjs` прогнан и зелёный, но он не + проверяет семантическую принадлежность подсекций — эта проверка сделана + мной вручную построением дерева заголовков, а не инструментом. + +## Вердикт + +Жёлтый: единственная Medium-находка — в скоупе задачи (тот же файл, та же +правка) и без High-находок, поэтому по правилам возвращается автору в этом же +issue, без отдельного issue. + +--- + + + +## Материал раунда + +- Ветка: `issue/628-repository-gc`, коммит `66b2b576aee8` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `4aabbb2ce19d8605d15a9a6d17dc999366f3bf9b` + ``` + git log --all --format='%H %T' | grep 4aabbb2ce19d + ``` +- Тело issue: `9b54257641bbb6e8f0276842401740d958c3593af319626ccc1c8a88e0e6c671` +- Вердикт конвейера: `yellow` · High 0 diff --git a/docs/reviews/INDEX.md b/docs/reviews/INDEX.md index d824d57a..a37c98ff 100644 --- a/docs/reviews/INDEX.md +++ b/docs/reviews/INDEX.md @@ -41,6 +41,7 @@ | #629 | [SPEC-REVIEW-629-r1.md](SPEC-REVIEW-629-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | — | — | | #629 | [CODE-REVIEW-629-r1.md](CODE-REVIEW-629-r1.md) | code · r1 | 🟢 зелёный | 0 | 0 | — | — | | #629 | [CODE-REVIEW-629-r2.md](CODE-REVIEW-629-r2.md) | code · r2 | 🟢 зелёный | 0 | 0 | — | — | +| #628 | [CODE-REVIEW-628-r1.md](CODE-REVIEW-628-r1.md) | code · r1 | 🟡 жёлтый | 0 | 1 | Новый раздел разрывает существующую секцию «Local Windows workstation» и меняет владель… | `docs/DEVELOPMENT.md` | | #627 | [SPEC-REVIEW-627-r1.md](SPEC-REVIEW-627-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | избыточное (не противоречивое) условие в AC2; влияние на touch не названо явным пунктом | `docs/TOUCH-SUPPORT.md` | | #627 | [CODE-REVIEW-627-r1.md](CODE-REVIEW-627-r1.md) | code · r1 | 🟡 жёлтый | 0 | 1 | demo/smoke_danger_confirmation.mjs не переведён на ожидание составного гейта; диалог оп… | `demo/smoke_danger_confirmation.mjs` `src/houseplan-card.ts` `de.ts` `smoke_danger_confirm_branches.mjs` | | #627 | [CODE-REVIEW-627-r2.md](CODE-REVIEW-627-r2.md) | code · r2 | 🟢 зелёный | 0 | 0 | — | — |