Срезать проверки стенда: под нож всё, что не служит менти #56

New Issue

2026-08-06T12:21:40+03:00

ddmitry commented

2026-08-06 12:21:40 +03:00

Цель

Проверок в репозитории больше, чем продукта. Замер 6 августа 2026 года:
1583 строки проверок стенда и 447 строк пробников против 2787 строк генератора
и 405 строк SQL с конфигами. Это на первом этапе из девяти.

Выросло не по замыслу. Каждая проверка появлялась как критерий приёмки этапа,
критерии писались из спеки, а спека писалась до того, как стенд впервые
собрали. Тот же механизм разобран в ADR 0004 на примере порога памяти: число
из оценки стало законом, которого никто не выбирал.

Критерий отбора здесь один: проверка остаётся, если она очевидно полезна
менти. Читатель — не побочный потребитель, а тот, ради кого стенд существует
(AGENTS.md, «Кому что поручать»). Код, который менти не прочтёт и из которого
ничему не научится, учебной ценности не несёт, а сопровождать его приходится:
при каждой правке проверок сторожа переписываются заново.

Тесты генератора (generator/tests, 2113 строк) под нож не идут: для
библиотеки в 2787 строк это нормальное соотношение, а схема события объявлена
контрактом.

Что войдёт

Что	Строк	Почему под нож
`tests/dag-probes-unit.py`	307	Заглушки `StubMessage`, `StubTopicPartition`, `RecordingClient` проверяют вспомогательные функции пробника в отрыве от стенда. Пробник затем и существует, чтобы гоняться на живом стенде; если он сломан, это видно из его прогона
`tests/stand-smoke-guards.sh`	193	Учит `setsid`, гонке за окном между фоновым прогоном и пробником, убийству групп процессов и разбору журналов DAG внутри контейнера. Про дата-платформу здесь ничего
`tests/stand-smoke-static.sh`	49	Тест теста: не виснет ли смоук при сломанном docker
`tests/smoke-guards.sh` целиком, вместе с целью `make smoke-guards`	139	Все три её проверки платят убийством ноды или той же машинерией с `setsid` и гонкой за окном: `check_failure_guards` убивает `clickhouse-02` посреди прогона и меряет уборку, вторая его половина шлёт SIGINT по группе процессов, `check_preflight_hint` тоже убивает ноду и чинит стенд через `make up`
`check_env_consistency` в `scripts/stand-smoke.sh`	~100	Разбор `${VAR:-default}` из compose и сверка с `.env.example` — парсер на bash, который менти не прочтёт
Обвязка пробников	~200	По шесть-семь функций `_assert_*` на пробник. Они оборонительные, а не учебные

Что остаётся и почему.

Пробники — ядро, их не трогаем по существу. dags/test_clickhouse.py и
dags/test_kafka.py — единственное место, где видно, как Airflow ходит в
ClickHouse и Kafka; по ним менти напишет свои DAG-и. Утверждения остаются
дословно: запись через ноду 1 и чтение через Distributed на ноде 2;
запись в Kafka и чтение своего маркера. Режется только обвязка: функции
_assert_* сворачиваются в тело задач. Комментарии про разницу
DELIVERY / SOCKET / FLUSH и про одноразовую группу консьюмера сохранить
дословно — это готовый учебный текст, а не служебная заметка.
Поведения, которые сторожил smoke-guards.sh, остаются на месте.
Подсказка «выполните make up» на неподнятом стенде и уборка временных таблиц
по Ctrl-C живут в scripts/clickhouse-smoke.sh, а его мы не трогаем.
Удаляется только их сторож. Менти встретит оба естественным путём: поднимет
не весь стенд — увидит подсказку, нажмёт Ctrl-C — увидит, что мусора не
осталось. Отдельный прогон с убийством ноды и двумя make up ради этого не
нужен.
check_keeper_runtime переезжает в scripts/stand-smoke.sh. Это не
сторож: keeper работает от пользователя clickhouse, nofile не меньше
262144, каталог данных свой. Это проверка устройства стенда, и грабли тут
настоящие. В scripts/clickhouse-smoke.sh её не селим — он занят веткой #43.
Из-за этого переезда счёт проверок в смоуке не падает: минус
check_env_consistency, плюс check_keeper_runtime — снова 25. Падают
строки, а не счёт; так и назвать в PR.
Отложенные импорты в пробниках остаются, а комментарий к ним
переписывается. dags/test_clickhouse.py объясняет, почему
import clickhouse_connect спрятан внутрь задачи, ссылкой на малые
проверки — после их удаления это станет неправдой. Но у отложенного импорта
есть вторая причина, и она лучше первой: обработчик разбирает DAG-файл снова
и снова, и тяжёлый импорт наверху оплачивался бы каждым разбором. Это прямая
рекомендация Airflow (best-practices.rst, сверено через Context7 на 3.1.6:
в примере доки названы pandas, torch, tensorflow — наши клиенты того же
рода). Импорт остаётся на месте, комментарий пишется про настоящую причину.
Для менти это выигрыш: живое правило Airflow вместо детали нашего
config-test. В dags/test_kafka.py такого комментария нет вовсе —
поставить один раз для confluent_kafka.
scripts/config-test.sh худеет вместе с dag-probes-unit.py. Он не
только запускает юнит-тесты пробников, но и грепает их вывод по образцу
^(Ran [0-9]+ tests|OK|FAILED) — проверяет, что unittest действительно
что-то прогнал. Это сторож сторожа, и уходит он вместе с тем, что сторожил.
Остальное в config-test.sh (bash -n, compileall по dags, разбор
compose) остаётся: дёшево и ловит настоящие опечатки.
Мысль, ради которой писался мутационный сторож, — проверка, которая не
умеет краснеть, бесполезна — не пропадает, а записывается абзацем в README
(в #54 переедет в docs/architecture/testing.md). Абзац текста вместо
193 строк гонок.
Одиннадцать проверок здоровья контейнеров остаются, хотя сразу после
make up --wait они повторяют то, чего compose уже дождался: у всех
долгоживущих служб есть healthcheck. Менти первым делом хочет знать, что всё
живо, и стоят они меньше секунды. В документации это назвать честно.

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

tests/dag-probes-unit.py удалён; scripts/config-test.sh на него
больше не ссылается, греп по его выводу убран вместе с вызовом.
tests/stand-smoke-guards.sh удалён; мысль «проверка, которая не умеет
краснеть, бесполезна» записана абзацем в README.
tests/stand-smoke-static.sh удалён; make config-test зелёный без него.
tests/smoke-guards.sh удалён, цель make smoke-guards из Makefile
убрана, упоминания в README сняты.
check_keeper_runtime работает в составе make smoke.
check_env_consistency удалён из scripts/stand-smoke.sh. Роль
.env.example объяснена в README словами.
Пробники ужаты: _assert_* свёрнуты, учебные комментарии сохранены
дословно — кроме комментария про отложенный импорт, он переписан на
причину из документации Airflow. Оба пробника по-прежнему делают ровно
то, что делали: test_clickhouse пишет через ноду 1 и читает через
Distributed на ноде 2, test_kafka пишет в Kafka и читает свой маркер.
Счёт проверок в make smoke назван в теле PR вместе с числом строк:
счёт остаётся 25, режутся строки.
make config-test, make up, make smoke, make smoke-cluster
зелёные.
Документация правится тем же PR: README (роль .env.example, состав
проверок, абзац про красноту), при необходимости — спека.

Границы

Тесты генератора не трогать (generator/tests).
scripts/clickhouse-smoke.sh не трогать: в него встраивается
contract-тест из #43.
Пробники не переписывать по существу. Что они утверждают — остаётся
дословно; режется обвязка вокруг.
Деление смоука на цели, переименование целей и карта проверок — это #54, не
здесь. Этот тикет идёт первым: он убирает код, который #54 иначе стал бы
делить и переименовывать.
Новых проверок не заводить. Задача только про удаление и ужатие.

Сначала прочитать

tests/dag-probes-unit.py, tests/stand-smoke-guards.sh,
tests/stand-smoke-static.sh, tests/smoke-guards.sh — всё, что режется.
scripts/stand-smoke.sh — check_env_consistency в начале файла.
dags/test_clickhouse.py, dags/test_kafka.py — что сохранить дословно.
scripts/config-test.sh — запуск юнит-тестов пробников и греп по их выводу.
Makefile — цель config-test меняет состав, цель smoke-guards уходит.
AGENTS.md — про учебную ценность и про то, кому что поручать.
docs/adr/0004-resource-limits.md — как из оценки получается закон.

Проверка

make config-test
make up
make smoke
make smoke-cluster

## Цель Проверок в репозитории больше, чем продукта. Замер 6 августа 2026 года: 1583 строки проверок стенда и 447 строк пробников против 2787 строк генератора и 405 строк SQL с конфигами. Это на первом этапе из девяти. Выросло не по замыслу. Каждая проверка появлялась как критерий приёмки этапа, критерии писались из спеки, а спека писалась до того, как стенд впервые собрали. Тот же механизм разобран в ADR 0004 на примере порога памяти: число из оценки стало законом, которого никто не выбирал. Критерий отбора здесь один: **проверка остаётся, если она очевидно полезна менти.** Читатель — не побочный потребитель, а тот, ради кого стенд существует (AGENTS.md, «Кому что поручать»). Код, который менти не прочтёт и из которого ничему не научится, учебной ценности не несёт, а сопровождать его приходится: при каждой правке проверок сторожа переписываются заново. Тесты генератора (`generator/tests`, 2113 строк) под нож **не идут**: для библиотеки в 2787 строк это нормальное соотношение, а схема события объявлена контрактом. ## Что войдёт | Что | Строк | Почему под нож | |---|---|---| | `tests/dag-probes-unit.py` | 307 | Заглушки `StubMessage`, `StubTopicPartition`, `RecordingClient` проверяют вспомогательные функции пробника в отрыве от стенда. Пробник затем и существует, чтобы гоняться на живом стенде; если он сломан, это видно из его прогона | | `tests/stand-smoke-guards.sh` | 193 | Учит `setsid`, гонке за окном между фоновым прогоном и пробником, убийству групп процессов и разбору журналов DAG внутри контейнера. Про дата-платформу здесь ничего | | `tests/stand-smoke-static.sh` | 49 | Тест теста: не виснет ли смоук при сломанном docker | | `tests/smoke-guards.sh` целиком, вместе с целью `make smoke-guards` | 139 | Все три её проверки платят убийством ноды или той же машинерией с `setsid` и гонкой за окном: `check_failure_guards` убивает `clickhouse-02` посреди прогона и меряет уборку, вторая его половина шлёт SIGINT по группе процессов, `check_preflight_hint` тоже убивает ноду и чинит стенд через `make up` | | `check_env_consistency` в `scripts/stand-smoke.sh` | ~100 | Разбор `${VAR:-default}` из compose и сверка с `.env.example` — парсер на bash, который менти не прочтёт | | Обвязка пробников | ~200 | По шесть-семь функций `_assert_*` на пробник. Они оборонительные, а не учебные | **Что остаётся и почему.** - **Пробники — ядро, их не трогаем по существу.** `dags/test_clickhouse.py` и `dags/test_kafka.py` — единственное место, где видно, как Airflow ходит в ClickHouse и Kafka; по ним менти напишет свои DAG-и. Утверждения остаются дословно: запись через ноду 1 и чтение через `Distributed` на ноде 2; запись в Kafka и чтение своего маркера. Режется только обвязка: функции `_assert_*` сворачиваются в тело задач. Комментарии про разницу DELIVERY / SOCKET / FLUSH и про одноразовую группу консьюмера **сохранить дословно** — это готовый учебный текст, а не служебная заметка. - **Поведения, которые сторожил `smoke-guards.sh`, остаются на месте.** Подсказка «выполните make up» на неподнятом стенде и уборка временных таблиц по Ctrl-C живут в `scripts/clickhouse-smoke.sh`, а его мы не трогаем. Удаляется только их сторож. Менти встретит оба естественным путём: поднимет не весь стенд — увидит подсказку, нажмёт Ctrl-C — увидит, что мусора не осталось. Отдельный прогон с убийством ноды и двумя `make up` ради этого не нужен. - **`check_keeper_runtime` переезжает в `scripts/stand-smoke.sh`.** Это не сторож: keeper работает от пользователя `clickhouse`, `nofile` не меньше 262144, каталог данных свой. Это проверка устройства стенда, и грабли тут настоящие. В `scripts/clickhouse-smoke.sh` её не селим — он занят веткой #43. Из-за этого переезда счёт проверок в смоуке не падает: минус `check_env_consistency`, плюс `check_keeper_runtime` — снова 25. Падают строки, а не счёт; так и назвать в PR. - **Отложенные импорты в пробниках остаются, а комментарий к ним переписывается.** `dags/test_clickhouse.py` объясняет, почему `import clickhouse_connect` спрятан внутрь задачи, ссылкой на малые проверки — после их удаления это станет неправдой. Но у отложенного импорта есть вторая причина, и она лучше первой: обработчик разбирает DAG-файл снова и снова, и тяжёлый импорт наверху оплачивался бы каждым разбором. Это прямая рекомендация Airflow (`best-practices.rst`, сверено через Context7 на 3.1.6: в примере доки названы `pandas`, `torch`, `tensorflow` — наши клиенты того же рода). Импорт остаётся на месте, комментарий пишется про настоящую причину. Для менти это выигрыш: живое правило Airflow вместо детали нашего `config-test`. В `dags/test_kafka.py` такого комментария нет вовсе — поставить один раз для `confluent_kafka`. - **`scripts/config-test.sh` худеет вместе с `dag-probes-unit.py`.** Он не только запускает юнит-тесты пробников, но и грепает их вывод по образцу `^(Ran [0-9]+ tests|OK|FAILED)` — проверяет, что unittest действительно что-то прогнал. Это сторож сторожа, и уходит он вместе с тем, что сторожил. Остальное в `config-test.sh` (`bash -n`, `compileall` по `dags`, разбор compose) остаётся: дёшево и ловит настоящие опечатки. - **Мысль, ради которой писался мутационный сторож,** — проверка, которая не умеет краснеть, бесполезна — не пропадает, а записывается абзацем в README (в #54 переедет в `docs/architecture/testing.md`). Абзац текста вместо 193 строк гонок. - **Одиннадцать проверок здоровья контейнеров остаются,** хотя сразу после `make up --wait` они повторяют то, чего compose уже дождался: у всех долгоживущих служб есть healthcheck. Менти первым делом хочет знать, что всё живо, и стоят они меньше секунды. В документации это назвать честно. ## Критерии приёмки - [ ] `tests/dag-probes-unit.py` удалён; `scripts/config-test.sh` на него больше не ссылается, греп по его выводу убран вместе с вызовом. - [ ] `tests/stand-smoke-guards.sh` удалён; мысль «проверка, которая не умеет краснеть, бесполезна» записана абзацем в README. - [ ] `tests/stand-smoke-static.sh` удалён; `make config-test` зелёный без него. - [ ] `tests/smoke-guards.sh` удалён, цель `make smoke-guards` из `Makefile` убрана, упоминания в README сняты. - [ ] `check_keeper_runtime` работает в составе `make smoke`. - [ ] `check_env_consistency` удалён из `scripts/stand-smoke.sh`. Роль `.env.example` объяснена в README словами. - [ ] Пробники ужаты: `_assert_*` свёрнуты, учебные комментарии сохранены дословно — кроме комментария про отложенный импорт, он переписан на причину из документации Airflow. Оба пробника по-прежнему делают ровно то, что делали: `test_clickhouse` пишет через ноду 1 и читает через `Distributed` на ноде 2, `test_kafka` пишет в Kafka и читает свой маркер. - [ ] Счёт проверок в `make smoke` назван в теле PR вместе с числом строк: счёт остаётся 25, режутся строки. - [ ] `make config-test`, `make up`, `make smoke`, `make smoke-cluster` зелёные. - [ ] Документация правится тем же PR: README (роль `.env.example`, состав проверок, абзац про красноту), при необходимости — спека. ## Границы - **Тесты генератора не трогать** (`generator/tests`). - **`scripts/clickhouse-smoke.sh` не трогать:** в него встраивается contract-тест из #43. - Пробники не переписывать по существу. Что они утверждают — остаётся дословно; режется обвязка вокруг. - Деление смоука на цели, переименование целей и карта проверок — это #54, не здесь. Этот тикет идёт **первым**: он убирает код, который #54 иначе стал бы делить и переименовывать. - Новых проверок не заводить. Задача только про удаление и ужатие. ## Сначала прочитать - `tests/dag-probes-unit.py`, `tests/stand-smoke-guards.sh`, `tests/stand-smoke-static.sh`, `tests/smoke-guards.sh` — всё, что режется. - `scripts/stand-smoke.sh` — `check_env_consistency` в начале файла. - `dags/test_clickhouse.py`, `dags/test_kafka.py` — что сохранить дословно. - `scripts/config-test.sh` — запуск юнит-тестов пробников и греп по их выводу. - `Makefile` — цель `config-test` меняет состав, цель `smoke-guards` уходит. - `AGENTS.md` — про учебную ценность и про то, кому что поручать. - `docs/adr/0004-resource-limits.md` — как из оценки получается закон. ## Проверка ``` make config-test make up make smoke make smoke-cluster ```

ddmitry added the ready-for-agent label 2026-08-06 12:21:40 +03:00

ddmitry referenced this issue

2026-08-06 12:23:49 +03:00

Проверки по назначению: честные имена целей, карта и быстрый смоук #54

ddmitry added a new dependency 2026-08-06 12:23:55 +03:00

#54 Проверки по назначению: честные имена целей, карта и быстрый смоук

ddmitry referenced this issue from a commit

2026-08-06 13:07:07 +03:00

refactor(smoke): срезаны проверки стенда, не служащие менти

ddmitry referenced this issue

2026-08-06 13:07:30 +03:00

refactor(smoke): срезаны проверки стенда, не служащие менти #57