khadhroony-bot3/docs/RUST_WORKSPACE_RULE_AUDIT.md

Audit des règles Rust du workspace

L’entrée unique est :

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 :

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_TOKEN2022 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.token2022.

Validation

L’audit strict exige le Cargo.lock versionné de l’application et vérifie exclusivement :

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 :

cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets