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.
13 KiB
Правила кода
Правила проверяются автоматически, а не на честном слове. Главный инструмент —
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.
Логирование (обязательно с первого дня)
Код пишет диагностику сразу, а не «потом добавим». Единая точка — фасад
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 |
тесты реально ловят ошибки |
| Порог регрессии бенчмарков в CI (своя утилита замеров) | скорость не падает незаметно |
Conventional Commits и commit-msg хук |
читаемая история |
Проверка, что каждый crate описан в ARCHITECTURE.md |
документация не отстаёт |
Лимит на число unsafe-блоков и место (только cpu, с обоснованием) |
контроль рисков |