Add Rust code health gate

2026-06-20 11:38:10 +00:00
parent 2234529a20
commit 5f8c208409
4 changed files with 174 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Rust Code Health
+
+## Цель
+
+В Community-репозитории нужно удерживать Rust-код в состоянии, где модули можно безопасно менять без разрастания скрытых связей.
+
+Основные риски сейчас:
+
+- крупные production-файлы с тестами внутри;
+- интеграционные сценарии, написанные рядом с кодом;
+- смешение HTTP, registry, runtime и test fixtures в одном модуле;
+- отсутствие автоматического контроля размера файлов.
+
+## Инструменты
+
+В Rust нет одного прямого аналога Python `import-linter`, который закрывает cohesion, coupling и connascence на уровне workspace.
+
+Используемая база:
+
+- `cargo fmt` — единый стиль.
+- `cargo clippy --workspace --all-targets --all-features -- -D warnings` — локальные ошибки, smell-и и часть API-антипаттернов.
+- `cargo test --workspace --all-targets` — unit и integration-style тесты.
+- `scripts/check-rust-code-health.sh` — локальный repo-level gate для размера Rust-файлов.
+
+Что можно добавить позже:
+
+- `cargo-deny` для лицензий, security advisories и duplicate dependencies.
+- `cargo-machete` для поиска неиспользуемых зависимостей.
+- `cargo-udeps` для более строгой проверки зависимостей, если nightly допустим в отдельной job.
+- `cargo-modules` или `cargo-guppy` для анализа графа модулей и зависимостей между crate-ами.
+
+## Правила размера
+
+Новые Rust-файлы не должны быть больше `1000` строк.
+
+Существующие крупные файлы зафиксированы baseline-ом в `scripts/check-rust-code-health.sh`. Они не должны расти дальше. При изменении таких файлов предпочтительно:
+
+- выносить вложенный `mod tests` в `tests/`, если тест проверяет публичное поведение, БД, HTTP или несколько модулей сразу;
+- выделять route/service/runtime helper в отдельный модуль;
+- оставлять рядом с production-кодом только короткие unit-тесты приватной логики.
+
+Текущие крупные файлы:
+
+- `apps/admin-api/src/service.rs`
+- `apps/admin-api/src/app.rs`
+- `apps/mcp-server/src/main.rs`
+- `crates/crank-runtime/src/executor.rs`
+- `crates/crank-registry/src/postgres/mod.rs`
+- `crates/crank-community-mcp/src/app.rs`
+- `crates/crank-registry/src/postgres/operation.rs`
+
+## Правила тестов
+
+Рядом с кодом допустимы:
+
+- маленькие pure unit tests;
+- проверки приватных parser/mapper/helper-функций;
+- тесты без сети, БД и поднятых серверов.
+
+В `tests/` нужно выносить:
+
+- PostgreSQL integration tests;
+- admin-api HTTP сценарии;
+- fake upstream servers;
+- publish/test-run/YAML roundtrip flow;
+- MCP Streamable HTTP сценарии.
+
+Целевая структура:
+
+```text
+apps/admin-api/tests/
+crates/crank-registry/tests/
+crates/crank-runtime/tests/
+crates/crank-community-mcp/tests/
+```
+
+## Архитектурные границы
+
+Базовое правило направления зависимостей:
+
+```text
+apps/* -> crates/*
+crank-community-mcp -> crank-registry + crank-runtime + crank-core
+crank-runtime -> crank-core + crank-mapping + crank-schema + adapters
+crank-registry -> crank-core
+crank-adapter-rest -> crank-core + crank-mapping + crank-schema
+crank-core -> no app crates
+```
+
+Если потребуется строгая автоматическая проверка границ, добавим отдельный script на основе `cargo metadata` или `cargo-guppy`.