# Правила кода Правила проверяются автоматически, а не на честном слове. Главный инструмент — crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `build.rs`, который вызывает его, поэтому **нарушение жёсткого правила ломает любую сборку** (`cargo build`, `check`, `clippy`, `test`). Весь репозиторий проверяется командой `cargo run -p fabrilis-limits`; она же стоит в pre-commit (`.githooks/`). Правила касаются только нашего кода. `docs/`, `*.md` и `ref/` (локальные клоны чужих проектов, см. REFERENCES.md) не проверяются. ## Проверяет `fabrilis-limits` (ошибка сборки) | Правило | Подробности | |---|---| | Размер файла | больше **350** строк — предупреждение, больше **500** — ошибка; на тестовые файлы не распространяется | | Файлов в директории | не больше **4** файлов кода (`.rs`, `.wgsl`, `.rhai`, `.sh`) в одной директории, и так в каждой директории отдельно, на любой глубине; подпапки в счёт не идут, тестовые файлы не считаются | | Комментарии на английском | кириллица в `//`, `///`, `//!`, `/* */` запрещена; строки и литералы не проверяются | | Без маркеров работы | `TODO`, `FIXME`, `HACK`, `XXX` в комментариях запрещены; открытая работа живёт в `TODO.md` | | Тесты отдельно от кода | см. ниже | | Без файлов-свалок | имена `utils`, `util`, `helpers`, `helper`, `common`, `misc`, `stuff`, `shared` для файлов и папок запрещены: файл называется по тому, что в нём лежит | | Слои crate'ов | зависимости идут только вниз; симуляция не зависит от `render`, `ui`, `app`; новый crate нужно внести в таблицу `tools/limits/src/rules/layers.rs`, иначе сборка падает | ### Тесты отдельно от кода В файле с кодом нет ни одного теста: ни `#[test]`, ни `#[cfg(test)] mod x { ... }`, ни `#[cfg(test)]`-хелперов. Допустимо только: - **модульные тесты:** в коде одна строка `#[cfg(test)] mod tests;`, а сами тесты лежат в `tests.rs` той же директории (`foo/mod.rs` → `foo/tests.rs`, `foo/bar.rs` → тоже `foo/tests.rs`); - **интеграционные тесты и бенчи:** папки `tests/` и `benches/` в crate'е; - общие помощники для тестов лежат в `tests/<имя>/mod.rs` (не `common`). Тестовые файлы (`tests.rs`, всё в `tests/` и `benches/`) **не считаются** в лимит четырёх файлов на директорию и **не ограничены** по размеру: один `tests.rs` может быть длинным. Разносить тесты по подпапкам ради лимитов не нужно — весь модуль тестируется одним файлом рядом. ## Проверяют rustfmt и clippy (pre-commit с `-D warnings`) | Правило | Чем задано | |---|---| | Отступы только табами | `rustfmt.toml`: `hard_tabs = true` | | `unsafe` запрещён | `Cargo.toml`: `unsafe_code = "deny"` | | Детерминизм: нет `sin/cos/exp/pow` из `std`, `HashMap/HashSet`, `Instant::now`, `SystemTime::now` | `clippy.toml`: `disallowed-methods`, `disallowed-types`; `platform` и `app` могут разрешить время точечно | | Нет `unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!`, `dbg!` в обычном коде | `Cargo.toml`: lints; в тестах разрешено (`clippy.toml`) | | Индексация только с доказанной границей | см. «Паники и индексация» | | Функция не длиннее 60 строк, не больше 5 аргументов, сложность ≤ 15 | `clippy.toml`: пороги | | Каждое `#[allow]` объясняется: `#[allow(lint, reason = "...")]` | `allow_attributes_without_reason` | Исключения оформляются точечно, с причиной, и не на весь crate без необходимости. ### Паники и индексация `unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!` и `dbg!` в библиотечном коде запрещены, в тестах разрешены. Индексация (`v[i]`) паникует сама, и линтер её не ловит, поэтому: **индексировать можно только там, где граница доказана структурой** — фиксированный массив, срез, полученный в этой же функции с проверкой, индекс из конструктора. Иначе — итераторы, `get`, `chunks`. Паника допустима лишь как утверждение «сюда нельзя попасть» в месте, куда данные из файла или из сети не доходят; в тестах это проверяется отдельным тестом. ### Лимиты и как их держать Списка исключений для файлов кода нет: если файл упирается в лимит, он делится на подмодули по смыслу. Декодер RISC-V, MNA-матрица и FEM собираются из маленьких модулей (по шагам ISA, по типам элементов, по решателям), а не из одного «большого» файла. Если подпапки не помогают, это повод пересмотреть структуру, а не завести исключение. Лимит четырёх файлов действует на каждую директорию независимо: в `src/` может лежать 4 файла и 6 подпапок, и в каждой подпапке снова 4 файла и свои подпапки, без ограничения глубины. Тесты в этот счёт не входят, поэтому `mod.rs`, три модуля и `tests.rs` — это нормальная директория, а не пять файлов. ### Dev-зависимости `proptest` и `criterion` разрешены как dev-зависимости (D26): в продуктовую сборку они не входят. Свои тесты на seeded `core::rng` остаются основой, потому что тот же генератор нужен Monte Carlo. ## Принципы - **KISS**: самое простое решение, которое работает; без заглушек «на будущее». - **DRY**: одно знание — одно место (device tree из карты памяти, единицы в `core`). - **SOLID**: один модуль — одна причина меняться; зависимости через трейты (`PhysicsBackend`, `Cpu`, `Device`); зависимости только вниз по слоям. ## Правила проекта (проверяются ревью) - В движке нет кода под конкретную конструкцию: всё через данные, детали-плагины и сценарии; конструкции лежат в `examples/`. - Crate'ы симуляции не зависят от GPU, окна и Bevy. - Единицы СИ через newtype из `core::units`, без голых `f64` в публичных API физики. - Новая внешняя зависимость обосновывается записью в `DECISIONS.md` (мы пишем своё, где это разумно). - Архитектурное изменение сопровождается записью в `DECISIONS.md`. ## Логирование (обязательно с первого дня) Код пишет диагностику сразу, а не «потом добавим». Единая точка — фасад `fabrilis_core::log` с уровнями; приложение ставит приёмник (stderr, файл, dev-лог). `println!`/`eprintln!` в библиотечном коде запрещены: только `main` для `--help` и ошибок запуска. | Уровень | Когда | Пример | |---|---|---| | `error` | работать дальше нельзя | не создался GPU-девайс, не загрузился проект | | `warn` | работаем, но деградация | шейдер не поддержан, шаг не сошёлся, поле не распознано | | `info` | жизненный цикл, один раз на событие | старт, seed и размер мира, загружено N деталей, режим | | `debug` | сводки и важные изменения | раз в секунду FPS/TPS/RTF, смена камеры, решение сходимости | | `trace` | покадрово/пошагово, только для разбора | входные события, каждый шаг решателя, пики контактов | Правила: - Уровень выбирается по смыслу события, а не по желанию. Горячий цикл логирует только `trace` и только после проверки уровня: строка не должна строиться, если уровень выключен. - Логи не влияют на симуляцию: логгер не меняет порядок, состояние и время. В crate'ах симуляции по-прежнему нет `Instant::now`/`SystemTime::now`; время для логов ставит приёмник в `app`. - Пишем факты в виде `key=value`, а не склейку предложений: `frame=120 frame_ms=18.4 physics_max_ms=0.6 trigger=contact`. - Ошибки и деградации логируются там, где возникли, а не только наверху. - Не логировать секреты и личные пути; большие буферы и меши не дампить. - Сообщения на английском (как комментарии), уровни и поля — стабильные. - Тесты: формат строки, парсеры, поведение выключенного уровня (строка не форматируется), неизменность golden-хеша при включённых логах. `log`/`tracing` сейчас не берём: нужен свой минимальный фасад без зависимостей и с контролем детерминизма (D35). Если понадобится экосистема, заменим фасад, не меняя места вызовов. ## Идеи на потом (пока не включены) Каждый пункт можно включить отдельным шагом, когда проект дорастёт. | Идея | Зачем | |---|---| | `cargo-deny` (лицензии, уязвимости, дубли версий, запрещённые crate'ы) | гигиена зависимостей | | `cargo-machete` | неиспользуемые зависимости | | `missing_docs`, `missing_errors_doc`, `missing_panics_doc` для нижних слоёв | документированный публичный API | | Касты `cast_possible_truncation`, `cast_precision_loss` в crate'ах симуляции | потеря точности между `u64` нс и `f64` | | `float_cmp`: сравнение `f64` через допуск, а не `==` | корректная численная логика | | Фаззинг (`cargo-fuzz`) для импорта мешей, форматов RON, декодера RISC-V | парсеры устойчивы к мусору | | Мутационное тестирование (`cargo-mutants`) и покрытие (`cargo-llvm-cov`) для `core`, `analog`, `cpu` | тесты реально ловят ошибки | | Порог регрессии бенчмарков в автоматическом прогоне (своя утилита замеров) | скорость не падает незаметно | | Conventional Commits и `commit-msg` хук | читаемая история | | Проверка, что каждый crate описан в `ARCHITECTURE.md` | документация не отстаёт | | Лимит на число `unsafe`-блоков и место (только `cpu`, с обоснованием) | контроль рисков |