diff --git a/docs/reviews/SPEC-REVIEW-398-r3.md b/docs/reviews/SPEC-REVIEW-398-r3.md new file mode 100644 index 00000000..35c98910 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-398-r3.md @@ -0,0 +1,167 @@ +# SPEC-REVIEW-398-r3 + +- Issue: https://github.com/Matysh/houseplan-card/issues/398 +- Этап: ТЗ на ревью (PROCESS.md §2.4) +- Материал: `docs/specs/398-sysmodules-guard-scope.md`, коммит `9fde407e` + («#398 spec revision 3 per SPEC-REVIEW-398-r2») +- Заход: r3 · блокирующих циклов израсходовано до этого вердикта: 2 из 4 +- Предыдущий вердикт: `docs/reviews/SPEC-REVIEW-398-r2.md`, жёлтый, на коммите + `480d202f` (ревизия 2 ТЗ). SHA назван в самом документе r2 явно + («Материал: …, коммит `480d202f`»), детективная работа не требуется. + +## Разбор по дельте (PROCESS.md §2.9, #214) + +Дельта — `git diff 480d202f..9fde407e -- docs/specs/398-sysmodules-guard-scope.md` +(27 добавленных / 7 удалённых строк, один файл). Правка не ребейзится на ушедший +вперёд `dev`, не меняет продуктовый контракт (`User-Visible: no`, класс B +сохранён), не задевает новую подсистему и по объёму меньше исходной задачи — +полный повторный разбор не требуется. Дельта касается четырёх мест: (1) шапка +«Ревизия», (2) новый абзац после раздела «Что делать с `load_pure`», (3) AC3 + +новый AC8, (4) план автотестов (пп. 3–4 unit, мутанты). Разделы, которых дельта +не коснулась (Сценарий, «Что человек увидит», Скоуп/не-скоуп, UX, модель данных, +i18n, AC1/AC2/AC5/AC6, Риски, Откат, Release-артефакты), унаследованы из r2 — +см. раздел ниже. Отдельно проверено, не задевает ли дельта совместность с AC, +которые сама не редактировала (AC1/AC2 vs новый AC3/AC8) — это и есть предмет +находки r2, разбор ниже. + +## Закрытие раунда r2 + +| Находка r2 | Чем закрыта | Где это видно | +|---|---|---| +| Medium: устранение «пути 2» в ревизии 2 сделало AC1/AC2 (fail-closed отказ на `sys.modules[<переменная>] = …`) несовместимыми с AC3 (единственное исключение — только `conftest.py`) для `tests_backend/pure_imports.py:31`, оставленного в скоупе и обязанного по AC5 продолжать резолвить относительные импорты | Статический список исключений расширен до двух поимённых файлов; ключевое отличие от снятого «пути 2» — обязанность самоочистки (AC4) сохранена и продублирована отдельным AC8 с собственным мутантом, то есть исключение из AC1-проверки и обязанность очистки по AC4 разведены как два независимых требования, а не связаны в одно (именно эта связка и была ошибкой пути 2) | `docs/specs/398-sysmodules-guard-scope.md:88-100` (новый абзац «Исключений в статическом гварде два, и это не возврат снятого пути») дословно повторяет вариант, предложенный ревьюером в r2 («Как править», см. `docs/reviews/SPEC-REVIEW-398-r2.md`), включая обоснование «там файл исключался ВМЕСТО очистки, здесь — при обязательной очистке»; AC3 (строки 133-135) теперь называет оба файла поимённо; новый AC8 (строки 136-139) требует восстановления в `finally` с отдельным мутантом `pure-imports-stops-cleaning` | + +Закрытие текстуально точное и логически корректное: авторская правка не просто +переименовала проблему, а разнесла два ранее слитых требования (статический +список «кому разрешено писать» и исполняемая проверка «осталось ли что-то +после») по разным AC, что и было сутью замечания r2. + +**Каскадная правка, которую отдельно стоит отметить.** Автор также обновил +мутант `sysmodules-guard-blind-to-variable`: в ревизии 2 он ещё был +сформулирован как «вернуть запись через переменную в `pure_imports.py` → +гвард красный» — формулировка, оставшаяся неизменной с ревизии 1 и после +правки r2 переставшая быть верной (раз `pure_imports.py` теперь легален по +AC3, мутация на нём самом не могла бы покраснеть). В ревизии 3 текст исправлен +на «добавить запись через переменную в файл ВНЕ списка исключений → гвард +красный». Это не было прямо указано ревьюером, но вытекает из его находки — +хороший признак того, что правка не точечная, а проверена на согласованность +со смежными местами документа. + +## Новые находки (в этом раунде) + +Blocking (High/Medium в скоупе) не найдено. Два наблюдения ниже — Low, +не блокируют. + +### Low — план автотестов не называет явно позитивный контракт-тест для `pure_imports.py` как второго исключения + +`docs/specs/398-sysmodules-guard-scope.md:154-157`, пункты плана автотестов: + +``` +3. `conftest.py` со своей условной подменой → зелено (AC3). +4. Попытка добавить третий файл в список исключений → красный (AC3). +``` + +AC3 вводит **два** поимённых исключения, но явный позитивный тест-пример +назван только для одного (`conftest.py`); для `tests_backend/pure_imports.py` — +файла, ради которого вся ревизия 3 и написана, — отдельного пункта «его +собственная запись `sys.modules[name] = module` → зелено (AC3)» в плане нет. +Это не логическое противоречие (как было в r1/r2): без него набор AC остаётся +формально выполнимым, поскольку `test/backend-test-hygiene.test.mjs` +сканирует реальные файлы `tests_backend/*.py`, включая сам `pure_imports.py`, +и при каждом прогоне `npm test` наличие исключения будет неявно упражнено +(если реализация ошибочно не распознает второе исключение, `npm test` +покраснеет на реальном файле, а не только на синтетическом). Поэтому не +поднимаю до Medium. Но именно эта строка кода — центр всей ревизии 3, и явный +пункт плана снял бы зависимость от «неявного» покрытия реальным файлом. + +### Low — нумерация критериев приёмки нарушена: AC8 вставлен между AC3 и AC4, AC7 не существует + +`docs/specs/398-sysmodules-guard-scope.md:133-142`: порядок в тексте — +AC1, AC2, AC3, **AC8**, AC4, AC5, AC6. Ни в одной прежней ревизии (проверено: +`git show 69dd09a7:...`, `git show 480d202f:...`) критерия AC7 не было — не +удалён, а просто пропущен номер. Сути не меняет (каждый AC однозначен и +пронумерован уникально, дублей нет), но для читателя, ищущего «AC7», это +выглядит как потерянный критерий, а не как намеренный пропуск. Дешевле всего +исправить переносом нового критерия в конец списка под следующим свободным +номером (AC7) при следующей правке текста; заводить отдельный цикл ради этого +нет оснований. + +## Унаследовано из r2 + +Без повторной проверки в этом раунде — дельта r2→r3 не касалась этих участков +и они не входят в цепочку доказательства новых находок или закрытия r2: + +- Обязательные продуктовые разделы («Сценарий», «Что человек увидит до и + после») и корректность персоны (разработчик, не пользователь продукта) — + `docs/reviews/SPEC-REVIEW-398-r2.md`, раздел «Унаследовано из r1», на SHA + `69dd09a7`. Текст этих разделов не изменился ни в 480d202f, ни в 9fde407e + (сверено: ни один hunk `git diff 69dd09a7..9fde407e` их не касается). +- Полнота обязательных разделов §7.1 (проблема, скоуп/не-скоуп, UX Н/П, + модель данных и миграция Н/П, i18n Н/П, план автотестов, откат, + release-артефакты) — там же. Структура документа не менялась в r3, только + содержимое трёх блоков (проблема/контракт, AC3+AC8, план автотестов), + разобранных выше. +- Соответствие `docs/SCOPE.md`: задача чисто инфраструктурная, не претендует + на строку Core user jobs — `docs/reviews/SPEC-REVIEW-398-r2.md`, «Что + проверено и корректно». Дельта r3 не меняет ни продуктовую рамку, ни + `User-Visible`. +- Скоуп/не-скоуп (`tests_backend/conftest.py` вне скоупа, правило #393 вне + скоупа) — не тронут дельтой r3, наследуется из r1/r2. +- AC1, AC2, AC5, AC6 — однозначны и проверяемы по отдельности — + `docs/reviews/SPEC-REVIEW-398-r1.md`, «Что проверено и корректно», п.4, + переподтверждено в r2. Текст этих критериев дельтой r3 не тронут (см. диф + выше — правки только в AC3, новый AC8, план автотестов). +- Риски «разбор Python из Node», «снятие регистрации ломает относительные + импорты», «соседи, подтянутые относительными импортами» — не изменены в + r3 (диф `480d202f..9fde407e` не затрагивает раздел «Риски»), проверены по + существу в r1/r2. +- Откат и release-артефакты — не изменены дельтой r3, наследуются из r1/r2. +- Наблюдения r1 (напряжение формулировок «контракт vs риски» про способ + разбора; маршрутизация issue мимо инфраструктурного пути) — не блокировали + тогда, не затронуты дельтой r3, остаются наблюдениями. + +## Что проверено и корректно (в этом раунде) + +- Закрытие находки r2 логически полное: две ранее слитые обязанности + (статическое разрешение писать / исполняемая проверка отсутствия мусора) + теперь заданы независимыми AC (AC3 и AC4/AC8), что и требовалось — сверено + построчно по диффу. +- Каскадное обновление мутанта `sysmodules-guard-blind-to-variable` (описано + выше) — проверено сопоставлением текста ревизии 2 и ревизии 3; без этой + правки план автотестов противоречил бы новому AC3. +- Новый AC8 имеет самостоятельное, отличное от AC3 доказательство (мутант + `pure-imports-stops-cleaning`, отдельно перечисленный в разделе «Мутант») — + не голая декларация без способа проверки. +- Сверено с реальным кодом: `tests_backend/pure_imports.py` на текущий момент + не содержит `finally`-восстановления и `sys.modules[name] = module` пишет + безусловно (строки 27-29 файла) — ожидаемо, реализация ещё не начата, текст + ТЗ описывает будущее состояние, а не выдаёт его за существующее. +- `docs/SCOPE.md` по-прежнему не нарушается — дельта r3 не расширяет + заявленную поверхность. + +## Чего не проверял + +- Не гонял `npx tsc --noEmit` / `npm test` / `npm run build` — на этапе + ревью ТЗ нет продуктового или тестового кода помимо самого `docs/specs/*.md`; + `finally`-очистка и AST-гвард ещё не реализованы, гейты неприменимы (то же + основание, что в r1/r2). +- Не проверял выполнимость «разбор синтаксиса Python из Node» экспериментом — + наблюдение 1 из r1 остаётся открытым, не переоценивалось в r3 (дельта его + не касалась). +- Не проверял `tests_backend/test_validation.py` повторно — его `_load_pure` + использует префикс `hp_pure.*`, не пересекающийся с `custom_components*`, + подтверждено в r1 и не релевантно дельте r3. +- Не проверял, что произойдёт при переименовании одного из двух исключённых + файлов (например, `pure_imports.py` → `pure_imports_v2.py`) — это вопрос + реализации статического списка (по имени файла vs по содержимому), ТЗ его + не обязано покрывать явно, а два Low-наблюдения выше достаточны для + следующей правки текста, если автор сочтёт нужным. + +## Вердикт + +Зелёный. Находка r2 закрыта корректно и по существу (не переименование +проблемы, а разведение двух ранее слитых требований по разным AC), новых +блокирующих несовместимостей правка не внесла. Два Low-наблюдения (нумерация +AC8 вне последовательности; план автотестов не называет явный позитивный +тест-пример для `pure_imports.py` как исключения) не блокируют и не образуют +цикл — оставляю их автору на усмотрение при следующей правке текста, если +таковая понадобится по другому поводу.