crank/docs/rust-code-health.md

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 сценарии.

Целевая структура:

apps/admin-api/tests/
crates/crank-registry/tests/
crates/crank-runtime/tests/
crates/crank-community-mcp/tests/

Архитектурные границы

Базовое правило направления зависимостей:

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.