docs: review document for #225

Issue: #225
User-Visible: no

docs/reviews/CODE-REVIEW-225-r2.md

@@ -0,0 +1,149 @@
+# Code review #225 — r2
+
+- **Issue:** https://github.com/Matysh/houseplan-card/issues/225
+- **Spec:** тело issue (лёгкий трек `small`), зелёное `SPEC-REVIEW-225-r2.md`
+- **Reviewed branch:** `issue/225-import-attachment-url-query`
+- **r1 code review:** жёлтый · SHA `e59962f` · документ `docs/reviews/CODE-REVIEW-225-r1.md`
+- **Дельта этого раунда:** `git diff e59962f..HEAD` = коммит `04945e1`
+  («fix: reject absolute urls in the content resolver, register the mutants»)
+- **Base:** `origin/dev` at `5f000cb` (ветка — линейное продолжение `5f000cb`,
+  не ребейз: `git merge-base HEAD origin/dev` = `5f000cb`, `origin/dev` ушёл
+  вперёд по несвязанному issue #226 своей веткой)
+- **Reviewer:** Claude, независимая сессия без контекста реализации
+
+## Вердикт
+
+**Зелёный · цикл r2/2 · High: 0 · Medium: 0.**
+
+Разбор — по дельте (§2.10 PROCESS.md, issue #214): r1 закончился жёлтым с
+двумя находками в скоупе (M1 — резолвер доверял `path` даже при `scheme`/
+`netloc`; M2 — заявленные мутанты не осели в реестре). Дельта `e59962f..HEAD`
+— один коммит, касающийся только того же файла/теста/гейта, которые уже были
+в скоупе задачи; не ребейз, контракт поведения не менялся, новая подсистема не
+затронута — сокращённый разбор оправдан.
+
+Обе находки закрыты правильно и это подтверждено не заявлением автора, а
+независимой проверкой: извлёк литеральную логику `_internal_path` (плюс
+`sanitize_marker_id`/`sanitize_filename`, `_looks_internal`) вне HA-харнеса и
+прогнал её на всех AC-кейсах и на всех трёх мутантах из реестра — старая
+(до фикса) версия резолвит `https://evil.example/houseplan_files/files/m1/doc.pdf`
+как внутренний файл, новая — корректно возвращает `None`; каждый из трёх
+зарегистрированных мутантов при применении к текущему коду переворачивает
+хотя бы один из своих AC-кейсов (детали — «Закрытие раунда r1» ниже). CI
+`Validate` зелёный на точном SHA `04945e1`, job `backend` — 339 passed (было
+335 на `e59962f`, +4 — ровно новый параметризованный тест на 4 варианта
+абсолютного/protocol-relative URL). Дешёвые гейты (`tsc`, `npm test`
+962/962, `build` + сверка трёх копий бандла, `mutation-gate --check` по
+всему реестру, включая три новых id) прогнаны локально и зелёные.
+
+Новых находок в этом раунде нет.
+
+## Скоуп дельты
+
+Один продуктовый коммит `04945e1` (`Issue: #225`, `User-Visible: no` —
+верно: это закрытие M1/M2, а не пользовательское поведение; пользовательский
+эффект уже описан в changelog коммитом `e59962f`, changelog в `04945e1` не
+трогается и не должен был):
+
+- `custom_components/houseplan/import_export.py` (+10/−1) — в `_internal_path`
+  перед тем как доверять `parsed.path`, добавлена проверка
+  `if parsed.scheme or parsed.netloc: return None`; комментарий указывает на
+  ревью r1/M1. Остальная функция (префиксы, `sanitize_marker_id`/
+  `sanitize_filename`, посегментное сравнение) не тронута — совпадает с
+  диффом `e59962f..HEAD` построчно;
+- `tests_backend/test_ha_import_export.py` (+20, 1 тест, 4 кейса) —
+  `test_issue_225_absolute_url_never_resolves_onto_a_local_file`: https+FILES_URL,
+  https+CONTENT_URL с query, protocol-relative `//`, https+PLANS_URL;
+- `scripts/mutation-gate.mjs` (+41, 3 записи) — `internal-path-ignores-query`,
+  `internal-path-trusts-foreign-host`, `internal-path-allows-traversal`, все
+  с `guard: node scripts/backend-test-guard.mjs issue_225`;
+- никаких изменений в `docs/CHANGELOG*`, `src/**`, i18n, конфиге
+  совместимости — соответствует `User-Visible: no` и тому, что коммит чинит
+  находки код-ревью, а не меняет заявленное поведение.
+
+## Как проверялось
+
+| Гейт | Результат |
+|---|---|
+| `npx tsc --noEmit` | pass |
+| `npm test` | **962/962 pass** (включает дешёвую половину мутационного гейта — `test/mutation-gate.test.mjs`: уникальность якорей и существование guard-файлов для всех мутантов, включая три новых) |
+| `npm run build` + сверка трёх копий бандла | pass, `dist`/`custom_components/houseplan/frontend`/`demo/srv/assets` побайтово совпадают, `git status` после сборки чист |
+| `node scripts/mutation-gate.mjs --check` (весь реестр, не только новые id) | **ok** на всех записях — новые три не столкнулись якорями со старыми 20+ |
+| CI `Validate` на точном SHA `04945e1` (`gh api .../commits/04945e1/check-runs`, job `backend` id `96542792712`) | `completed success`; лог: «Backend unit tests (pure + HA harness) — **339 passed** in 5.26s» (было 335 на `e59962f`, делта +4 совпадает с числом новых параметризованных кейсов) |
+| Независимая проверка «мутант умеет ловиться» — вынес `_internal_path`/`_looks_internal`/`sanitize_marker_id`/`sanitize_filename` в автономный скрипт (без HA) и прогнал: (а) новую версию на AC1/AC1-plan/AC4/AC4a/AC5-M1; (б) буквальные патчи всех трёх мутантов реестра против неё | новая версия проходит все кейсы; **все три мутанта переворачивают** результат хотя бы одного своего AC-кейса — не эквивалентные патчи, не «зелёный тест ничего не проверяет» (детали ниже) |
+| `python -m pytest tests_backend -q` локально | не прогонял — окружение ревью на py3.12 без `homeassistant`; `test_ha_*.py` тем же механизмом молча пропускается, что и у автора и у меня же в r1 (см. `AGENTS.md`, «Backend»). Заменено CI-прогоном на точном SHA плюс независимым исполнением чистой логики вне HA — то же покрытие, что использовалось в r1 |
+| browser `demo/smoke_*.mjs` (127 шт.), `npm run golden:verify`, performance-профили | не прогонял — дельта не касается `src/**`/визуала/производительности, ни один AC их не называет; то же основание, что в r1 |
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+|---|---|---|
+| **M1** — `urlsplit(url).path` доверяет пути даже при `scheme`/`netloc`; `https://evil.example/houseplan_files/files/m1/doc.pdf` резолвится как локальный файл, хотя `_looks_internal` говорит «внешний» | Добавлена проверка `if parsed.scheme or parsed.netloc: return None` перед использованием `parsed.path` | `custom_components/houseplan/import_export.py:364-366`; тест `test_issue_225_absolute_url_never_resolves_onto_a_local_file` (4 кейса: https+FILES_URL, https+CONTENT_URL+query, `//`+FILES_URL, https+PLANS_URL) — все требуют `_internal_path(...) is None` и `_looks_internal(...) is False`. Независимо прогнал ту же логику вне HA: без проверки все 4 URL резолвятся в валидный локальный путь, с проверкой — все 4 дают `None` |
+| **M2** — три мутанта из ТЗ (`internal-path-ignores-query`, `internal-path-allows-traversal`, плюс подразумеваемый мутант на M1) не зарегистрированы в `scripts/mutation-gate.mjs`, разовый ручной прогон не оставляет постоянной защиты | Три записи добавлены в `MUTANTS` (`scripts/mutation-gate.mjs:676-716`): `internal-path-ignores-query`, `internal-path-trusts-foreign-host` (регрессия M1), `internal-path-allows-traversal`, все с `guard: node scripts/backend-test-guard.mjs issue_225` | `node scripts/mutation-gate.mjs --check` — все три анкера уникальны в текущем коде; `test/mutation-gate.test.mjs` (часть `npm test`, 962/962) проверяет то же плюс существование guard-файла. Прогнал патчи буквально: `internal-path-ignores-query` переворачивает 2/6 кейсов AC1 (варианты с `#fragment`) и оба кейса AC4a; `internal-path-trusts-foreign-host` переворачивает все 4 кейса нового теста M1; `internal-path-allows-traversal` переворачивает кейс `plans/_/../x.svg?v=1` из AC4 (для `files`-ветки этот же мутант оказывается эквивалентным — `sanitize_marker_id("..") == "misc"` ловит traversal независимо от структурной проверки, поэтому реестр справедливо не утверждает, что он ловит все AC4-кейсы, только тот один, который у файловой ветки не защищён вторым эшелоном) |
+
+## Унаследовано из r1
+
+Без повторной проверки в этом раунде — дельта их не касается — приняты выводы
+из `docs/reviews/CODE-REVIEW-225-r1.md` (SHA `e59962f`):
+
+- диагноз бага и контракт исправления (`urlsplit`, query/fragment вне
+  определения файла) совпадают с кодом;
+- данные пользователя не переписываются (`item["url"]` не трогается);
+- `identity()` (`:1034-1039`) не включает `storage` в ключ сравнения —
+  смена классификации `external → internal` для канонических cache-busted
+  ссылок не ломает сопоставление manifest-строк (AC6);
+- traversal-защита для случаев без `scheme`/`netloc` (три из четырёх кейсов
+  AC4) не ослаблена дропом query — сегментные проверки работают над тем же
+  материалом, что и раньше;
+- AC6/AC7 (regression, plan-only idempotency) — diff `e59962f` только
+  добавляет тесты в конец файла, plan-only диапазон (`:489-736`) вне диффа;
+- trailers, ветка, оба changelog в коммите `e59962f` — по правилам.
+
+Дельта r1→r2 не касается этих участков кода (только резолвер и мутационный
+реестр), поэтому пересчёт не требовался — см. «Скоуп дельты» выше, где
+подтверждено, что diff `e59962f..HEAD` ограничен ровно тем, что было
+находками r1.
+
+## Что проверено и корректно (в этом раунде)
+
+- M1-фикс не задевает уже покрытые ветки: прогнал старую/новую версию
+  резолвера на AC1 (5+3 кейса), AC4 (4 кейса), AC4a (2 кейса) — результат
+  идентичен до и после добавления проверки `scheme`/`netloc`, потому что ни
+  один из этих URL её не содержит.
+- `_looks_internal` не менялась (проверено `git diff` — файл затронут только
+  в `_internal_path`), поэтому согласованность двух функций, из-за
+  расхождения которых родился исходный баг #225, теперь восстановлена в обе
+  стороны: внутренний путь ⇒ обе функции согласны; внешний хост ⇒ обе
+  согласны «внешний».
+- Мутант `internal-path-allows-traversal` умышленно снимает два патча сразу;
+  комментарий `because` в реестре объясняет, что снятие одного из них
+  (`len(tail) != 2`) для файловой ветки было бы эквивалентным мутантом —
+  проверил это утверждение напрямую (см. таблицу выше), оно верно.
+- Trailers коммита `04945e1` (`Issue: #225`, `User-Visible: no`) корректны:
+  фикс не меняет наблюдаемое пользователем поведение (только закрывает
+  внутреннюю рассогласованность двух приватных функций), поэтому отсутствие
+  правки changelog — не пропуск.
+- `process-gate`/pre-push пройден (CI job `process-gate`: success на
+  `04945e1`).
+
+## Чего не проверял
+
+- `python -m pytest tests_backend -q` в собственном окружении — та же
+  причина, что в r1 (py3.12, без `homeassistant`, `test_ha_*.py` молча
+  пропускается `conftest.py`). Компенсировано CI-прогоном на точном SHA
+  (339 passed) и независимым исполнением чистой логики резолвера вне HA.
+- Полный (дорогой) прогон `node scripts/mutation-gate.mjs` с пересборкой
+  бандла в worktree для каждого из 20+ мутантов реестра — не требовался:
+  задача не трогает остальные мутанты, а три новых проверены анкерным
+  `--check` и независимым буквальным прогоном патчей против чистой логики
+  (эквивалент того, что делает дорогой прогон, без пересборки бандла на
+  каждый). Дорогой прогон — предрелизный гейт (`.github/workflows/
+  mutation-gate.yml`), не гейт ревью (PROCESS.md §8 vs §2.7).
+- Browser-смоки (127 шт.), `npm run golden:verify`, performance-профили —
+  дельта не касается `src/**`, визуала или производительности; то же
+  основание, что в r1.
+
+## Лимит циклов
+
+Код-ревью лёгкого трека — 2 цикла (§4). Это второй и последний цикл; вердикт
+зелёный, лимит не понадобился.