v0.1.0-pre.061

olddocs/RUST_WORKSPACE_RULE_AUDIT.md

@@ -0,0 +1,85 @@
+<!-- file: docs/RUST_WORKSPACE_RULE_AUDIT.md -->
+<!-- version: 3 -->
+
+# Audit des règles Rust du workspace
+
+L’entrée unique est :
+
+```bash
+python3 scripts/audit_rust_workspace_rules.py
+```
+
+Elle exécute trois contrôles obligatoires :
+
+1. `audit_rust_general_rules.py` pour les règles Rust réutilisables ;
+2. `audit_rust_export_completeness.py` pour la fermeture des façades ;
+3. `audit_khadhroony_workspace_rules.py` pour les contrats propres au projet.
+
+## Façades et réexports
+
+Tous les modules sont privés avec `mod`. Une API de crate est formée uniquement par des
+réexports explicites depuis `lib.rs` ou `main.rs`.
+
+Les réexports d’un module interne utilisent `self::`, ne sont jamais groupés, ne changent
+jamais le nom du symbole avec `as` et possèdent une rustdoc adjacente. Un bloc homogène de
+`pub use` ou `pub(crate) use` ne contient aucune ligne vide.
+
+L’audit de complétude suit les réexports transitifs à travers les façades privées. Il vérifie
+donc qu’un type déclaré dans un sous-module atteint réellement la racine de sa crate sans
+exiger un faux accès public au module qui le contient. Les constantes de suivi des scaffolds
+de migration restent internes à leur inventaire et ne font pas partie de l’API publique.
+
+## Nomenclature de `kb-lib`
+
+| Famille       | Constante | Type ou trait | Fonction libre  |
+|---------------|-----------|---------------|-----------------|
+| Décodeur      | `DC_`     | `Dc`          | `decoder_`      |
+| Matérialiseur | `MT_`     | `Mt`          | `materializer_` |
+| Exécuteur     | `EX_`     | `Ex`          | `executor_`     |
+| Modèle        | `MD_`     | `Md`          | `model_`        |
+
+Les méthodes inhérentes et les helpers strictement privés ne sont pas soumis à un préfixe
+global. Les symboles `pub` et `pub(crate)` le sont, car ils peuvent entrer en collision après
+la fusion des anciennes crates dans `kb-lib`.
+
+Les 98 frontières de décodeurs encore en attente utilisent des constantes uniques
+`DC_<FAMILLE>_<SURFACE>_LEGACY_CRATE` et
+`DC_<FAMILLE>_<SURFACE>_MIGRATION_STATUS`. Elles sont référencées par un inventaire interne
+pour que `cargo check` ne produise pas d’avertissements de code mort.
+
+## Tracing
+
+Une crate opérationnelle autonome garde un unique `TRACING_TARGET` dans `constants.rs` et le
+réexporte avec :
+
+```rust
+pub(crate) use self::constants::TRACING_TARGET;
+```
+
+Un composant opérationnel de `kb-lib` utilise un nom préfixé, par exemple
+`TRACING_TARGET_DECODER_SPL_TOKEN_2022` ou `TRACING_TARGET_MATERIALIZER_TOKEN_ACCOUNTS`, réexporté
+transitivement jusqu’à `kb-lib/src/lib.rs`. Sa valeur suit exactement le chemin hiérarchique
+du composant, par exemple `kb-lib.decoder.spl.token_2022`.
+
+## Validation
+
+L’audit strict exige le `Cargo.lock` versionné de l’application et vérifie exclusivement :
+
+```text
+wincode 0.5.5
+solana-wincode-varint 1.0.0
+```
+
+Une livraison sans `Cargo.lock` peut contrôler le reste avec `--report-only`, mais elle ne
+doit pas annoncer l’audit strict comme propre tant que le lock réel n’a pas été utilisé.
+
+La fermeture d’une tranche demande ensuite :
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets
+```
+