houseplan-card/docs/specs/399-backend-gate-honesty.md

# ТЗ #399 — Бэкенд-гейт проверяет ровно то, что обещает

- Issue: https://github.com/Matysh/houseplan-card/issues/399
- Приоритет: P2, infra; полный трек — класс B (конфигурация гейта, workflow,
  тесты), три несвязанные поверхности в одном issue по решению аудита
- Ревизия: 3 (2026-08-31) — по SPEC-REVIEW-399-r2 (Medium: план тестов повторял
  снятую формулировку AC5)

## Сценарий

Разработчик смотрит на зелёный `backend` и делает вывод: «интеграция проверена
против закреплённого Home Assistant, линт прошёл по объявленному скоупу,
версии зафиксированы». Каждое из трёх утверждений сегодня чуть шире правды, и
именно из-за таких зазоров #392 уже случился: харнесс полгода тихо проверял
интеграцию против февральского HA, и ни один гейт об этом не сказал.

## Что человек увидит до и после

Пользователь продукта — ничего. Разработчик перестаёт получать три ложных
обещания: пин фронтенда соответствует закреплённому HA, объявленный скоуп
линта совпадает с проверяемым, а проверка пинов не может выключить сама себя.

## Проблема и контракты по пунктам

### (1) M3 — пин фронтенда не соответствует закреплённому HA

`tests_backend/requirements.txt:29` фиксирует
`home-assistant-frontend==20260826.1`, тогда как рядом (`:32`) закреплён
`homeassistant==2026.8.3`, а его `package_constraints.txt` в теге `2026.8.3`
репозитория `home-assistant/core` требует `home-assistant-frontend==20260729.7`
(проверено загрузкой файла). `pytest-homeassistant-custom-component` фронтенд
в зависимостях не объявляет вовсе, то есть версия выбрана вручную и ничем не
выведена.

Функционального отказа сегодня нет: пакет — статика, тесты его не исполняют.
Но цель #392 формулировалась дословно как «по SHA видно, чем проверяли», а
проверяется набор, которого не существует ни в одном релизе HA.

**Контракт**: версия фронтенда выводится из констрейнтов закреплённого HA, а
не назначается. В комментарии рядом сказано, откуда она берётся, чтобы
следующий подъём HA не превратился в угадывание.

### (2) Low «а» — ruff линтит уже, чем объявляет конфиг

`pyproject.toml:5` включает в `[tool.ruff] include` три дерева:
`custom_components/houseplan/**/*.py`, `scripts/*.py`, `tests_backend/**/*.py`.
Шаг «Линт бэкенда» (`.github/workflows/validate.yml:787-788`) исполняет
`python -m ruff check custom_components/houseplan` — одно дерево из трёх.

Сужение было осознанным решением #42 (щадящий трек, «без массового rewrite»),
и пересматривать само решение эта задача не обязана. Проблема в том, что
конфиг об этом молчит: читающий `pyproject.toml` видит три дерева и делает
неверный вывод. Наблюдаемое следствие — в `tests_backend/test_validation.py`
проехали мёртвые `import sys`/`import types` (F401) и переопределения (F811),
которых на v1.69.0 не было.

**Контракт**: объявленный скоуп и проверяемый совпадают. Допустимы два исхода,
и оба честны — выбрать при реализации, замерив цену:

1. сузить `include` до реально проверяемого дерева, а расширение оставить
   отдельной задачей с разбором долга;
2. расширить CI до полного `include`, разобрав накопленные находки
   (`ruff check custom_components/houseplan scripts tests_backend` — порядка
   полусотни, преимущественно I001/E402/F401 в тестах).

Решение фиксируется в комментарии рядом с `include`, чтобы следующий читатель
не гадал, почему так.

### (3) Low «в» — проверка пинов сама себя отключает

`test/validate-workflow.test.mjs:216`:

```js
if (!/pytest-homeassistant-custom-component|tests_backend\/requirements\.txt/.test(workflow)) continue;
```

Если workflow не содержит ни имени пакета, ни пути к файлу пинов, проверка
пропускает файл молча. То есть возврат к `pip install pytest voluptuous …` без
версий — ровно то, от чего защищались в #392 — гейт не заметит: исчезнут обе
зацепки разом.

Вторая половина той же дыры: проверка перебирает **жёстко заданный массив**
`['validate.yml', 'mutation-gate.yml']`, а не каталог. Новый workflow с
неверсионированной установкой гейт не увидит просто потому, что его нет в
списке — и это ровно тот способ, которым #392 уже случился: корректность
держалась на том, что никто не добавит третий файл.

**Контракт**: проверка перебирает **все** `.github/workflows/*.yml`. Для
каждого файла возможны ровно два исхода: либо он ставит зависимости бэкенда —
и тогда обязан делать это из `tests_backend/requirements.txt`, либо он их не
ставит — и тогда это утверждение проверяется явно (в файле нет установки
python-зависимостей), а не выводится из отсутствия подстроки. Появление нового
workflow, ставящего зависимости мимо файла пинов, краснеет само, без правки
списка.

## Скоуп / не-скоуп

**В скоупе**: `tests_backend/requirements.txt`, `pyproject.toml` (`[tool.ruff]
include`) и/или шаг линта в `.github/workflows/validate.yml`,
`test/validate-workflow.test.mjs`, при выборе исхода (2) — разбор ruff-долга в
`scripts/*.py` и `tests_backend/**/*.py`.

**Не в скоупе**: сам факт сужения линта из #42 как решение (пересматривается
только его видимость в конфиге); версии `homeassistant` и
`pytest-homeassistant-custom-component` (закреплены #392, менять только вместе
с полным прогоном); гейт типизации (#42) и гвард `sys.modules` (#398).

## UX

Не применимо.

## Модель данных и миграция

Не применимо.

## i18n

Новых строк нет.

## Критерии приёмки

- **AC1**. `home-assistant-frontend` в `tests_backend/requirements.txt` равен
  версии из констрейнтов закреплённого `homeassistant`. Доказательство: тест,
  сверяющий пин с зафиксированной в репозитории копией ожидаемой версии (без
  обращения в сеть на прогоне), плюс комментарий в файле с источником.
- **AC2**. Скоуп линта в workflow и `include` в `pyproject.toml` совпадают.
  Доказательство: контрактный тест, читающий оба файла и сравнивающий списки
  деревьев; расхождение краснеет.
- **AC3**. Выбранный исход (1) или (2) записан комментарием рядом с `include`
  с причиной. Доказательство: тест на присутствие обоснования не требуется —
  проверяется ревьюером; но при исходе (2) `ruff check` по полному `include`
  зелёный в CI.
- **AC4**. `test/validate-workflow.test.mjs` отказывает, когда в workflow нет
  ни имени пакета, ни пути к файлу пинов. Доказательство: тест на синтетическом
  workflow без обеих зацепок → красный.
- **AC5**. Проверка перебирает каталог `.github/workflows/*.yml`, а не
  фиксированный список имён. Для файла, который зависимостей бэкенда не
  ставит, это доказывается явно — в нём нет установки python-пакетов, — а не
  выводится из отсутствия подстроки. Доказательство: тест на синтетическом
  каталоге, где третий workflow ставит `pip install pytest` без версий →
  красный, хотя в прежнем списке из двух имён его бы не было. Сегодня в
  репозитории девять workflow, установку python-зависимостей делают два
  (`validate.yml`, `mutation-gate.yml`) — это факт, который проверка обязана
  вывести сама, а не принять на веру.
- **AC6**. Существующие гейты не ослаблены: `npm test`, `ruff` по текущему
  CI-скоупу и `mypy` strict остаются зелёными.

## План автотестов

**Unit** (`test/validate-workflow.test.mjs`, `test/backend-pins.test.mjs`):

1. Пин фронтенда совпадает с ожидаемой версией закреплённого HA (AC1).
2. Списки деревьев в `include` и в шаге линта совпадают (AC2).
3. Синтетический workflow без обеих зацепок → проверка пинов краснеет (AC4).
4. Каталог `.github/workflows/*.yml` перебирается целиком: синтетический
   третий workflow с `pip install pytest` без версий краснеет **без** правки
   каких-либо списков в тесте (AC5). Списка обходимых файлов в тесте нет и
   быть не должно — файл, не ставящий python-зависимостей, распознаётся по
   собственному содержимому.
5. Реальный каталог проверяется тем же кодом: девять workflow, установка
   python-зависимостей найдена ровно в двух — это вывод проверки, а не
   зафиксированное в ней ожидание (AC5).

**Мутанты** (`scripts/mutation-gate.mjs`):

- `backend-pins-check-opts-out`: убрать из workflow путь к файлу пинов →
  `validate-workflow.test.mjs` красный.
- `lint-scope-drifts`: добавить дерево в `include`, не тронув workflow →
  контракт скоупа красный.
- `workflow-scan-hardcodes-the-list`: заменить перебор каталога на
  фиксированный список имён → пункт 4 плана красный (иначе от снятой
  конструкции ничто не удерживает).

## Риски

- **Исход (2) вскроет долг, который придётся чинить в этой же задаче.**
  Смягчение: оценить объём до выбора; при неприемлемом объёме брать исход (1),
  а расширение выносить отдельным issue со своим бюджетом.
- **Сверка версии фронтенда без сети.** Ожидаемая версия должна лежать в
  репозитории, иначе тест станет зависеть от доступности GitHub. Смягчение:
  хранить ожидание рядом с пином (комментарий + константа в тесте), обновлять
  вместе с подъёмом HA — это и есть «видно по SHA».
- **Ложное чувство завершённости.** Задача чинит видимость, а не покрытие:
  после неё линт по-прежнему может проверять одно дерево. Смягчение: явная
  формулировка в комментарии и, при исходе (1), заведённый follow-up.

## Откат

Три независимые правки, каждая — одна строка плюс тест. Продуктовый код не
затронут.

## Release-артефакты

Пользовательских изменений нет: `User-Visible: no`, changelog не трогается.
`docs/ARCHITECTURE.md` — одна строка в разделе про гейты бэкенда, если выбран
исход (2).