docs: review document for #225

Issue: #225
User-Visible: no

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

@@ -0,0 +1,218 @@
+# Code review #225 — r1
+
+- **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`
+- **Reviewed range:** `origin/dev..HEAD` = `e59962f` (единственный продуктовый коммит)
+- **Base:** `origin/dev` at `5f000cb`
+- **Reviewer:** Claude, независимая сессия без контекста реализации
+
+## Вердикт
+
+**Жёлтый · цикл r1/2 · High: 0 · Medium: 2 → в задаче.**
+
+Диагноз и контракт («парсить URL как URL», `urlsplit(url).path`, query/fragment
+не участвуют в определении файла) реализованы и покрыты честными тестами:
+семь параметризованных тестов на `_internal_path`/`_content_state` плюс
+полный roundtrip-тест, все зелёные в CI на точном SHA (см. «Как проверялось»).
+Я независимо воспроизвёл логику `_internal_path` вне HA-харнеса и подтвердил,
+что каждый из новых тестов **умеет падать** на добеговом резолвере.
+
+Но контракт реализован не полностью: `urlsplit(url).path` доверяет пути даже
+тогда, когда у URL есть `scheme`/`netloc` — то есть строка вида
+`https://evil.example/houseplan_files/files/m1/doc.pdf` после фикса резолвится
+как **внутренний** файл, хотя `_looks_internal` (строковая проверка префикса,
+не изменена) по‑прежнему говорит «не внутренний». Это то самое расхождение,
+от которого защищает `_content_state` (docstring прямо называет угрозу:
+«a crafted file could ... bypass the mandatory detach decision»), только в
+обратную сторону от исходного бага. Ни один AC (в частности AC5) эту форму
+входа не проверяет (M1).
+
+Отдельно: ТЗ само выписало три записи мутационного гейта с готовыми
+find/replace-патчами в формате `scripts/mutation-gate.mjs` — ровно так, как
+это уже делалось для прежних бэкенд-фиксов в этом же файле (#167:
+`plan-only-*`, тем же коммитом). В этой задаче патчи не легли в реестр —
+проверка осталась разовой, только в тексте хендоффа (M2).
+
+Оба High отсутствуют, обе находки в скоупе issue (правка того же файла и
+того же гейта, который эта задача уже трогает) — по §2.7/§7.2 PROCESS.md
+это жёлтый вердикт с возвратом автору, а не отдельный issue.
+
+## Скоуп
+
+Единственный продуктовый коммит `e59962f` (`Issue: #225`, `User-Visible: yes`,
+трейлеры на месте):
+
+- `custom_components/houseplan/import_export.py` (+10) — `_internal_path`
+  теперь режет `urlsplit(url).path` до сравнения сегментов; остальная логика
+  (префиксы `plans/_/`/`FILES_URL`, `sanitize_marker_id`/`sanitize_filename`,
+  требование ровно двух сегментов, посегментное сравнение) не тронута;
+- `tests_backend/test_ha_import_export.py` (+128, 7 тестов) — AC1/AC1-plan,
+  AC4, AC4a, AC5, AC2 (обе ветки `same_source`), AC3 (полный roundtrip);
+- `docs/CHANGELOG.md` + `docs/CHANGELOG.ru.md` (+6/+6) — пользовательская
+  формулировка совпадает с USER-GUIDE-стилем сообщения об ошибке, ссылка на
+  #225 есть в обоих.
+
+Никаких изменений в `src/**`, i18n, миграции, конфиге совместимости — как и
+заявлено в ТЗ. Ветка `issue/225-import-attachment-url-query` соответствует
+правилу именования.
+
+## Как проверялось
+
+| Гейт | Результат |
+|---|---|
+| `npx tsc --noEmit` | pass |
+| `npm test` | **962/962 pass** |
+| `npm run build` + сверка трёх копий бандла | pass, `dist`/`custom_components/houseplan/frontend`/`demo/srv/assets` побайтово совпадают, `git status` после сборки чист |
+| CI `Validate` на точном SHA `e59962f` (`gh run view 32403605914`) | `completed success`; job `backend` — `completed success`, лог: «Backend unit tests (pure + HA harness) — 335 passed in 3.78s» (полный HA-харнес, включая `test_ha_*.py`, не только «чистое» подмножество) |
+| Независимая проверка «тест умеет падать» — извлёк `_internal_path` (плюс `sanitize_marker_id`/`sanitize_filename`, у функции нет собственной HA-зависимости, она приходит из модуля целиком) и прогнал старую/новую версию на всех кейсах AC1/AC1-plan/AC4/AC4a/AC5 вне HA-харнеса | новая версия проходит все кейсы AC1/AC1-plan/AC4/AC4a/AC5; **старая версия (`origin/dev`) красная** на 4/5 кейсов AC1, обоих кейсах AC1-plan-с-query и обоих кейсах AC4a — регрессия доказуема, а не заявлена на слово |
+| `python -m pytest tests_backend -q` локально | не прогонял — окружение ревью на py3.12 без `homeassistant`, `test_ha_*.py` тем же механизмом молча пропускается (см. `AGENTS.md`); заменено CI-прогоном выше и независимой проверкой резолвера |
+| browser `demo/smoke_*.mjs` (127 шт.) | не прогонял — задача не касается `src/**`, ни один AC их не называет |
+| `npm run golden:verify` | не прогонял — визуала нет, бэкенд-only фикс |
+| performance-профили | не прогонял — не названы в AC, путь не производительный |
+
+## Проверка AC1–AC7
+
+| AC | Метод по ТЗ | Статус | Как закрыт |
+|---|---|---|---|
+| AC1 | backend unit | ✅ | `test_issue_225_attachment_url_resolves_regardless_of_query` (5 кейсов) + `..._plan_url_resolves_regardless_of_query` (3 кейса); я пересчитал `urlsplit(url).path` для каждого кейса вручную и вне HA — совпадает |
+| AC2 | backend unit/`_content_state` | ✅ | `test_issue_225_content_state_accepts_a_cache_busted_attachment`, обе ветки `same_source`; зелёный в CI на точном SHA (см. выше) |
+| AC3 | backend HA-харнес, roundtrip | ✅ | `test_issue_225_backup_with_an_attachment_survives_a_full_round_trip`; зелёный в CI |
+| AC4 | backend unit, traversal | ✅ | `test_issue_225_traversal_stays_closed_with_a_query` (4 кейса); подтверждено чтением — `sanitize_marker_id`/`sanitize_filename` и посегментное сравнение работают над `urlsplit(url).path`, то есть после отделения query, ровно как и до фикса |
+| AC4a | backend unit | ✅ | `test_issue_225_hostile_looking_query_does_not_reject_a_valid_path` (2 кейса); я подтвердил разбором, что мусор в query/fragment действительно не участвует в резолвинге |
+| AC5 | backend unit | ⚠️ формально ✅, но неполно | `test_issue_225_external_url_is_still_external` зелёный для `https://example.invalid/floor.svg?v=1` — путь этого URL (`/floor.svg`) не совпадает с внутренним префиксом. AC **не покрывает** случай, когда путь абсолютного/protocol‑relative внешнего URL *совпадает* с внутренним префиксом — см. M1: в этом случае `_internal_path` **резолвит его как внутренний**, хотя `_looks_internal` говорит «нет» |
+| AC6 | regression, существующие тесты без правок | ✅ | diff — только добавления в конец файла (проверено `git show`), ни одна существующая строка теста не изменена; CI backend green |
+| AC7 | plan-only idempotency (`:704`) | ✅ (чтением) | тесты `test_plan_only_export_projects_geometry_and_round_trips_room_labels` и соседние в диапазоне 489–736 не задеты диффом; `_internal_path` используется в plan-only пути так же, как раньше, отличие только в разборе query/fragment |
+
+## Находки
+
+### M1 (Medium, в скоупе) — `_internal_path` доверяет `path` даже при непустых `scheme`/`netloc`
+
+`urlsplit(url).path` отбрасывает не только query/fragment, но и `scheme` с
+`netloc`. Для строки с полной схемой или protocol‑relative префиксом это
+означает, что путь резолвится как внутренний, даже когда URL целиком указывает
+на другой хост.
+
+Воспроизведено извлечением и прогоном литеральной логики `_internal_path` вне
+HA (сравнение с `_looks_internal`, определённой в том же файле построчно):
+
+```
+url = "https://evil.example/houseplan_files/files/m1/doc.pdf"
+_looks_internal(url)               -> False   (не меняется фиксом)
+_internal_path(root, url)  (НОВЫЙ)  -> ('attachment', <root>/files/m1/doc.pdf)
+_internal_path(root, url)  (СТАРЫЙ, origin/dev) -> None
+```
+
+То же самое для protocol-relative `//evil.example/houseplan_files/files/m1/doc.pdf`
+и для варианта с `?v=1`. `urlsplit` реально разбирает такие строки так, что
+`netloc="evil.example"`, `path="/houseplan_files/files/m1/doc.pdf"` — я
+проверил это отдельно интерпретатором, это не домысел.
+
+Практический эффект ограничен (traversal по‑прежнему закрыт AC4 —
+посегментные проверки не меняются): `_looks_internal` в `_content_state` не
+кидает `ImportFailure`, потому что она сама смотрит на исходную строку и
+по‑прежнему говорит «внешний». Но `internal is not None` (новое поведение)
+уводит такую запись в ветку `available`/`detach_required` вместо `external`:
+`content_manifest` на экспорте и `_content_state` на импорте начинают
+описывать заведомо внешнюю ссылку так, будто она указывает на настоящий
+локальный файл, включая проверку `is_file()` по пути, который в
+действительности к этому URL не относится. Это ровно тот класс
+несогласованности, который докстринг `_content_state` называет угрозой
+(«a crafted file could ... bypass the mandatory detach decision»), только не
+исходный баг issue, а новый, привнесённый самим фиксом.
+
+Ни один AC (в частности AC5, единственный про «внешний» URL) не проверяет
+такую форму — тест `https://example.invalid/floor.svg?v=1` не совпадает по
+path с внутренним префиксом и потому не может поймать эту ветку.
+
+**Фикс:** перед тем как доверять `parsed.path`, требовать
+`not parsed.scheme and not parsed.netloc`, иначе — как и сегодня для любой
+внешней ссылки — возвращать `None`. Пара строк плюс тест-кейс(ы) с `https://`
+и `//`-префиксом на пути, совпадающем с внутренним namespace.
+
+**Вердикт:** в скоупе issue (тот же файл, тот же контракт «разобрать URL как
+URL»), чинится в этом же цикле.
+
+### M2 (Medium, в скоупе) — заявленный мутационный гейт не зарегистрирован
+
+ТЗ issue содержит раздел «Мутационный гейт» с тремя id и готовыми
+find/replace-патчами (`internal-path-ignores-query`,
+`internal-path-allows-traversal`, `roundtrip-import-with-attachment`) —
+буквально в формате записей `scripts/mutation-gate.mjs`. Это не абстрактная
+формулировка риска: патчи прямо адресуют строки `import_export.py`.
+
+Прецедент в этом же файле — issue #167 (`feat: add plan-only space export`,
+коммит `7f397a6`): пять аналогичных backend-мутантов
+(`plan-only-room-area-restored` и соседние, гвард
+`node scripts/backend-test-guard.mjs <pattern>`) были добавлены в реестр
+**тем же коммитом**, что и сама правка. `scripts/backend-test-guard.mjs`
+уже поддерживает произвольный `-k`-паттерн по `test_ha_import_export.py`, то
+есть механизм для #225 был готов без доработок — `node
+scripts/backend-test-guard.mjs issue_225_attachment_url_resolves` и подобные
+сразу работали бы как guard.
+
+В `e59962f` `scripts/mutation-gate.mjs` не менялся (проверено `git show
+e59962f --stat` и `git log --follow -- scripts/mutation-gate.mjs`). Хендофф
+описывает, что автор вручную прогонял мутации через отдельные патч-версии
+файла и даже сделал полезное наблюдение (первая редакция
+`internal-path-allows-traversal` оказалась «эквивалентной» — traversal
+защищён двумя независимыми проверками одновременно) — но эта работа нигде не
+осела постоянной проверкой. Без записи в реестре периодический
+предрелизный `mutation-gate` (`.github/workflows/mutation-gate.yml`) никогда
+не перепроверит, что будущий рефакторинг `_internal_path` не вернёт баг
+#225 бесшумно — то есть именно тот сценарий, ради которого механизм
+существует (см. комментарий в начале `scripts/mutation-gate.mjs`: «зелёный
+тест в этом проекте несколько раз означал ничего не проверено»).
+
+**Вердикт:** в скоупе issue (`scripts/mutation-gate.mjs` — класс B, «может
+использовать issue того изменения, которое покрывает»), чинится добавлением
+двух работающих записей в этом же цикле (третью, `internal-path-allows-
+traversal`, — с патчем, который автор уже подобрал как небезрезультатный,
+согласно находке из хендоффа).
+
+## Что проверено и корректно
+
+- Диагноз бага (несовпадение `_looks_internal`/`_internal_path` из-за
+  `sanitize_filename` над сырым хвостом с `?v=...`) и контракт исправления
+  (`urlsplit`, query/fragment не участвуют в определении файла) — совпадают
+  с фактическим кодом `_internal_path` до и после правки.
+- Данные пользователя не переписываются: URL в конфиге сохраняется как есть
+  (проверено чтением — фикс меняет только внутреннюю логику резолвинга,
+  возвращаемое значение из `create_export`/`_content_state` не трогает
+  `item["url"]`; тест `test_issue_225_content_state_accepts_a_cache_busted_attachment`
+  отдельно утверждает `rows[0]["url"] == url`).
+- `identity()` (`:1034-1039`) не включает `storage`/`state` в ключ сравнения
+  — смена классификации `external → internal` для канонических cache-busted
+  ссылок (сама цель фикса) не ломает сопоставление manifest-строк; тем же
+  свойством объясняется, почему M1 не валит существующие проверки
+  идентичности, только их семантику для одной специфичной формы входа.
+- Traversal-защита (AC4) не ослаблена: `sanitize_marker_id`/
+  `sanitize_filename` и требование `len(tail) == 2` работают над результатом
+  `urlsplit(url).path`, то есть над тем же материалом, что и раньше для
+  URL без scheme/netloc — я прогнал старую и новую версию резолвера на всех
+  четырёх кейсах AC4 и получил идентичный `None` в обеих.
+- AC6/AC7 не нарушены: diff — чистое добавление в конец файла тестов, ни
+  одна существующая строка не тронута; plan-only regression-диапазон вне
+  диффа.
+- Trailers `Issue: #225`/`User-Visible: yes`, оба changelog в одном коммите,
+  ветка `issue/225-import-attachment-url-query` — по правилам.
+- Три копии бандла побайтово совпадают после локальной пересборки — класс D
+  не разошёлся, хотя эта задача его не трогает (бэкенд-only).
+
+## Чего не проверял
+
+- `python -m pytest tests_backend -q` в собственном окружении — ревью
+  выполняется на py3.12 без установленного `homeassistant`; `conftest.py`
+  тем же механизмом, что и у автора, молча пропустил бы `test_ha_*.py`, то
+  есть локальный зелёный прогон здесь ничего не доказывает (см. `AGENTS.md`,
+  раздел «Backend»). Использован CI `Validate` на точном SHA (`backend`:
+  335 passed, полный HA-харнес) плюс независимое исполнение чистой логики
+  `_internal_path` вне HA — сильнее, чем «поверил хендоффу».
+- Полный набор из 127 browser-smoke и `performance_smoke` — задача не
+  касается `src/**`, ни один AC их не называет, поверхность чисто бэкендовая.
+- `npm run golden:verify` — визуальных изменений нет.
+- Мутационный гейт (`node scripts/mutation-gate.mjs`, дорогой прогон с
+  пересборкой бандла в отдельном worktree) целиком не запускал — сам факт
+  отсутствия трёх заявленных записей в реестре зафиксирован находкой M2 без
+  необходимости гонять существующие 40+ мутантов, которых этот диф не
+  касается.