86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
<!-- file: docs/RUST_WORKSPACE_RULE_AUDIT.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# 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_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 :
|
||
|
||
```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
|
||
```
|
||
|