# quality-checks Specification

## Purpose
Единый набор проверок качества для сервисных репозиториев АРМ КА, выполняемый локально одной командой перед каждым PR:
какие проверки обязательны, в каком порядке и с какими внешними ресурсами. Конфигураций CI в репозиториях нет — в Gitea
CI не используется, пайплайн платформы банка вне зоны проекта.

## Requirements

### Requirement: `make check` — быстрые проверки без Docker
Каждый сервисный репозиторий SHALL предоставлять цель `make check`, выполняющую из `api/`: `ruff check .`,
`ruff format --check .`, `mypy src` (в сервисе с копией общего кода `arm_statements` — `mypy src arm_statements`, в
`arm-core` — ещё `scripts`), `pytest -m "not integration"` (включая тесты копии `arm_statements/tests/`), тест
идентичности вендоренного контракта с `../docs/contracts` (схема копии — с `<имя>.v<M>.schema.json` своего `MAJOR`,
если такой файл есть в docs, иначе с основным; примеры — с `examples/v<M>/`, если там есть одноимённый файл, иначе с
`examples/`; правило — спека `recognition-contract`, требование «Копия контракта в сервисе идентична источнику»). Цель SHALL завершаться ненулевым кодом при первой упавшей проверке и MUST NOT требовать
запущенного Docker, PostgreSQL или NATS. Свежесть копии `arm_statements` относительно репозитория `arm-statements` в
`make check` MUST NOT проверяться (соседний репозиторий в `make check` не читается).

#### Scenario: Файл не отформатирован
- **WHEN** в репозитории есть файл, не отформатированный `ruff format`
- **THEN** `make check` завершается с кодом 1 на шаге `ruff format --check`, следующие шаги не выполняются

#### Scenario: Чистый репозиторий
- **WHEN** все проверки проходят
- **THEN** `make check` завершается с кодом 0 за время, не превышающее нескольких минут, без обращения к сети

#### Scenario: Тесты копии общего кода
- **WHEN** в `tabular-parser` лежит копия `api/arm_statements/` с тестами пакета
- **THEN** `make check` гоняет их вместе с тестами сервиса, `mypy` проверяет и копию

### Requirement: `make check-full` — полная проверка против compose
Каждый сервисный репозиторий SHALL предоставлять цель `make check-full`: `make check` плюс `pytest -m integration` против
инфраструктуры `docs/dev/docker-compose.yml` (PostgreSQL 16, NATS, MinIO, для `scan-gateway` — эмулятор). Для `arm-core`
цель SHALL дополнительно выполнять «`alembic upgrade head` → `alembic downgrade base` → `alembic upgrade head`» на чистой
БД и `python scripts/check_dbml_vs_orm.py` против текущей версии модели (`../docs/model/data-model-v<текущая>.dbml`, путь — переменная `DBML` Makefile). В сервисе с копией общего
кода `arm_statements` цель SHALL выполнять `statements-check` — `../docs/scripts/sync-statements.sh --check` по этому
хосту (спека `statement-normalization`, требование «`sync-statements` — копии пакета в потребителях»): коды `0` и `10`
— шаг зелёный (`10` — с предупреждением «копия отстала»), `20` и `2` — красный. `make check-full` SHALL быть
выполнен перед созданием PR, его итог (и предупреждение `statements-check`, если было) вписывается в описание PR.

#### Scenario: Расхождение ORM и DBML
- **WHEN** в ORM добавлена колонка, которой нет в DBML
- **THEN** шаг `check_dbml_vs_orm` падает с перечнем расхождений, `make check-full` завершается с кодом 1

#### Scenario: Миграция без отката
- **WHEN** `downgrade` ревизии не удаляет созданный ею объект
- **THEN** шаг «upgrade → downgrade → upgrade» падает

#### Scenario: Прямая правка копии общего кода
- **WHEN** в `scan-gateway` поправлен файл `api/arm_statements/steps/…`, а в `arm-statements` такого изменения нет
- **THEN** `statements-check` завершается с кодом 20 и называет файл, `make check-full` красный

### Requirement: Фикстуры и соседние репозитории — опциональны с предупреждением
Проверки SHALL брать `docs` и `fixtures` из соседних каталогов workspace (`../docs`, `../fixtures`) или из переменных
`ARM_KA_DOCS`, `ARM_KA_FIXTURES`. При отсутствии фикстур тесты с маркером `fixtures` SHALL пропускаться с явной причиной;
при отсутствии docs тест идентичности контракта SHALL пропускаться с предупреждением. Отсутствие соседей MUST NOT делать
`make check` красным.

#### Scenario: Нет фикстур
- **WHEN** `../fixtures` отсутствует и `ARM_KA_FIXTURES` не задан
- **THEN** тесты с маркером `fixtures` помечены skipped с причиной «ARM_KA_FIXTURES недоступен», остальные выполняются

### Requirement: Одинаковый набор целей во всех репозиториях
`Makefile` каждого сервисного репозитория SHALL содержать цели `up`, `test`, `test-integration`, `lint`, `check`,
`check-full` с одинаковой семантикой (описана в `docs/dev/checks.md`); репозиторий MAY добавлять свои цели (`migrate`,
`seed`, `emulator`), но MUST NOT менять смысл общих.

#### Scenario: Сверка с описанием
- **WHEN** ревьюер сравнивает список общих целей `Makefile` сервиса с `docs/dev/checks.md`
- **THEN** все общие цели присутствуют и запускают описанные команды