fabrilis/docs/CODE_RULES.md
loki5512344 79928b645b
Initial commit: Fabrilis docs, rules and deterministic core
Docs (architecture, decisions, coupling, determinism, UI, references), code rules enforced by tools/limits, deterministic core with units, time, math, sched, snapshot, vec and rng, plus smoke tests. ref/ stays out of git.
2026-11-16 23:06:29 +01:00

108 lines
10 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/`) и в CI.
Правила касаются только нашего кода. `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 и CI с `-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`.
## Идеи на потом (пока не включены)
Каждый пункт можно включить отдельным шагом, когда проект дорастёт.
| Идея | Зачем |
|---|---|
| `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` | тесты реально ловят ошибки |
| Порог регрессии бенчмарков в CI (своя утилита замеров) | скорость не падает незаметно |
| Conventional Commits и `commit-msg` хук | читаемая история |
| Проверка, что каждый crate описан в `ARCHITECTURE.md` | документация не отстаёт |
| Лимит на число `unsafe`-блоков и место (только `cpu`, с обоснованием) | контроль рисков |