# 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`.