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