# Правила репозитория ICE-NET · обязательные ## Структура и ограничения 1. **Не более 250 физических строк на любой авторский текстовый файл**, включая MD, Rust, Slint, TOML, Python, YAML. 2. **Не более 4 авторских файлов непосредственно в одном каталоге** (подкаталоги отдельно). Сгенерированный `Cargo.lock`, `.gitignore` и системный `.DS_Store` не учитываются при подсчёте; на исходники и `.slint` это исключение не действует. 3. Если модуль вырос — делить по ответственности, **не** сжимать код в одну строку. 4. Не размещать тесты в `src/` через `#[cfg(test)]`: unit-like и integration tests — отдельные `tests/*.rs`. 5. Не создавать crate ради каждого типа; новая граница crate требует независимой ответственности и односторонних зависимостей. 6. `workspace/tools/check_layout.py` проверяет лимиты для `.rs`, `.slint`, `.md` и конфигурации. Не обходить скрипт переименованием файла. 7. Исключение: дословные тексты лицензий (`LICENSE`, `LICENSES/`) — не авторские файлы; не править и не сокращать. ## Documentation & comments (English) - Public crates: `//! Module or crate description.` - Public types, traits, methods: `/// Summary.` — **rustdoc** (Rust-аналог JavaDoc). - Для нетривиальных API применять секции `# Arguments`, `# Returns`, `# Errors`, `# Panics`, `# Examples`, `# Safety` где уместно. - Комментарии внутри исходников — **English**, поясняют *почему*, а не буквально *что* делает строка. - Текст документации в `docs/` и issue допускается на русском. ```rust /// Finds a route that satisfies the traffic class policy. /// /// # Arguments /// - `class`: The traffic class to schedule. /// /// # Returns /// A route, or `None` when no eligible path exists. /// /// # Errors /// This operation currently does not return I/O errors. pub fn find_route(class: TrafficClass) -> Option { /* example */ None } ``` ## Архитектурные принципы - **KISS:** сначала простейшая проверяемая реализация; избегать преждевременного async/actor/DI-фреймворка. - **DRY:** общая логика живёт в одном crate; не превращать каждый похожий `match` в абстракцию. - **SOLID:** маленькие интерфейсы (`Transport`, `RoutePlanner`), разделение политик и механики, инверсия зависимостей на границе с железом. - **Hexagonal architecture:** UI и сеть — адаптеры; алгоритмы **не** импортируют GUI и операционную систему. - Детерминированность симулятора: фиксированные seed, стабильный порядок событий, симулированное время. - Одна ответственность на модуль; публичный API минимальный; ошибки типизированные, не `panic` на входных пакетах. ## Код, качество, безопасность - Rust Edition 2024, `resolver = "3"`; версия инструмента согласуется с версиями GUI. - Не применять `unsafe` без ADR + ревью; `unwrap()` в обработке входных данных запрещён. - Запретить секреты, токены, приватные ключи и реальные данные пользователей в git/фикстурах. - Test Pyramid: проверка инвариантов → integration → сценарии города → hardware-in-the-loop. - Криптографическая «угроза» от ICE: только **локально разрешить/отказать/ограничить/залогировать**; никаких ответных атак. - Code review по контрактам, тестам, потреблению RAM/airtime, privacy и зависимости. ## Definition of Done для PR - [ ] Лимиты 250/4, rustdoc на новых публичных API, тесты в `tests/`. - [ ] `cargo fmt`, `cargo clippy`, `cargo test` без ошибок. - [ ] Указано, какие сценарии покрыты, какие риски и какие измерения получены. - [ ] Не заявлена совместимость/безопасность без тестов, лицензия зависимостей проверена. ## Внешние зависимости (MVP) - Библиотечные крейты по умолчанию работают **без crates.io-зависимостей**. - Каждая новая зависимость требует краткого обоснования: функция, лицензия, MSRV, транситивные зависимости, поддержка, альтернатива на std. - GUI-зависимости только в `apps/icenet-city`, никогда в `icenet-core`/`icenet-sim`. - Для Slint выключены defaults: без Qt, Skia, WGPU, webview, tokio или serde. - `slint-build` нужен только для компиляции `.slint` в `build.rs`. - В версии 0.3 GUI: Slint 1.18.1, software renderer и Winit (desktop Linux). - Поставляемые программы требуют проверки лицензий, особенно Slint. - Лицензия собственного кода: **LGPL-3.0-or-later** (`license` в `workspace/Cargo.toml`; каждый crate наследует её). Код других проектов с несовместимой лицензией не копировать. - После обновления GUI **перегенерировать и закоммитить новый `Cargo.lock`**.