fabrilis/docs/CODE_RULES.md
loki5512344 190ef9cc4b Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:40:39 +01:00

143 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Правила кода
Правила проверяются автоматически, а не на честном слове. Главный инструмент —
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`, с обоснованием) | контроль рисков |