4.7 KiB
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 :
-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
La séquence normale d'un changement Rust pertinent inclut :
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.