82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
<!-- file: docs/rules/510-RUST_CARGO.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Rust / Cargo local Knowledge
|
|
|
|
## Toolchain et workspace
|
|
|
|
Knowledge utilise Rust stable, édition 2024 et un workspace Cargo à train de release unique. `[workspace.package].version` suit `VERSION` et les crates membres héritent de la version commune.
|
|
|
|
Aucun `rust-toolchain.toml` n'est ajouté sans besoin réel de reproductibilité ou de compatibilité. Les artefacts Cargo sont dirigés hors de l'arborescence source par la configuration locale lorsque possible.
|
|
|
|
`Cargo.lock` est généré localement, ignoré et non versionné pour ce workspace. Cette politique ne s'applique pas au lockfile npm.
|
|
|
|
## Nomenclature et responsabilités
|
|
|
|
Les crates utilisent le préfixe `knowledge-`. Les suffixes portent un contrat :
|
|
|
|
```text
|
|
-api frontière passive de contrats réutilisables/remplaçables
|
|
-lib implémentation ou fonctionnalité réutilisable
|
|
-server launcher/processus mince
|
|
```
|
|
|
|
Une crate n'est pas créée par symétrie. Une `-api` ne contient ni runtime, ni logging imposé, ni implémentation de provider. Un launcher ne duplique pas une logique qui possède un owner bibliothèque commun.
|
|
|
|
## Façade crate-root
|
|
|
|
Pour toute crate bibliothèque Knowledge, `src/lib.rs` est une façade de crate. Il contient la documentation de crate, les déclarations de modules, les réexports publics/internes nécessaires et, lorsque pertinent, le rattachement conditionnel des tests.
|
|
|
|
Les `struct`, `enum`, `trait`, fonctions, implémentations et autres définitions de comportement appartiennent à des modules nommés selon leur responsabilité. Une petite crate n'est pas artificiellement éclatée en nombreux fichiers : un seul module de responsabilité peut suffire, mais les définitions ne s'accumulent pas dans `lib.rs`.
|
|
|
|
Les crates `-api` nomment leurs modules par le contrat réel (`reference`, `revision`, `snapshot`, `repository`, `signal`, etc.) plutôt que par un générique `api.rs` sans ownership.
|
|
|
|
Les consommateurs externes utilisent la façade `owner_crate::Item`. Les références intra-crate vers des items partagés passent par `crate::Item` afin de garder une identité stable indépendante du module propriétaire.
|
|
|
|
`scripts/audit_rust_crate_root_facades.py` contrôle que les crate-roots de bibliothèque restent des façades sans définitions top-level de production.
|
|
|
|
## Safety, erreurs et contrôle de flux
|
|
|
|
`unsafe` est interdit par défaut. Les lints workspace stricts restent autoritaires.
|
|
|
|
Le code de production ne doit pas utiliser `unwrap`, `expect`, `panic!` ou l'opérateur `?` lorsque les lints locaux les interdisent. Les erreurs récupérables sont propagées explicitement avec le type d'erreur possédé par la couche concernée.
|
|
|
|
Les retours explicites exigés par la politique Clippy locale sont conservés, y compris dans les closures lorsque le lint `implicit_return` s'applique.
|
|
|
|
## Imports, modules et réexports
|
|
|
|
Les `use` non exportés sont réservés aux imports réellement nécessaires, notamment les traits. Les modules de production précèdent les modules de tests conditionnels et suivent un ordre déterministe lorsqu'aucune sémantique ne l'interdit.
|
|
|
|
Les réexports crate-root restent groupés par visibilité. La façade publique doit être complète pour les items partagés et les modules propriétaires restent privés sauf besoin architectural explicite.
|
|
|
|
## Tests
|
|
|
|
Les tests unitaires résident sous `unit_tests/` à la racine de chaque crate et sont rattachés depuis le module source correspondant. Les tests d'intégration Cargo résident sous `tests/` et consomment l'API publique.
|
|
|
|
Les tests ne rendent pas l'API produit plus visible uniquement pour accéder à des détails internes.
|
|
|
|
## Formatage et audits
|
|
|
|
Le formatter est appliqué, pas seulement interrogé : `cargo fmt --all` précède obligatoirement les audits du code Rust, puis `cargo fmt --all -- --check` vérifie immédiatement le résultat.
|
|
|
|
La séquence normale d'un changement Rust pertinent inclut :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo fmt --all -- --check
|
|
python3 -B scripts/audit_rust_test_layout.py crates
|
|
python3 -B scripts/audit_rust_blank_lines.py crates
|
|
python3 -B scripts/audit_rust_item_spacing.py crates
|
|
python3 -B scripts/audit_rust_module_order.py crates
|
|
python3 -B scripts/audit_rust_trait_import_blocks.py crates
|
|
python3 -B scripts/audit_rust_reexport_blocks.py crates
|
|
python3 -B scripts/audit_rust_crate_root_facades.py crates
|
|
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
Les tests ciblés sont sélectionnés selon le scope. `cargo test --workspace --all-targets --all-features` est utilisé pour les changements transverses et les phases de consolidation.
|
|
|
|
L'audit mécanique des blocs `const` n'est pas sélectionné globalement par Knowledge : l'ordre de constantes peut être sémantique. Il ne sera ajouté localement que si un besoin réel et un corpus approprié le justifient.
|