v0.2.5-pre.010.fix.002

deltas/0.2.5/pre.010-fix.002.md

@@ -0,0 +1,192 @@
+<!-- file: deltas/0.2.5/pre.010-fix.002.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.5-pre.010-fix.002` — correction normalisation Rust et garde-fous structurels
+
+## 1. Base et version
+
+Base :
+
+```text
+0.2.5-pre.010-fix.001
+workspace.package.version = 0.2.5-pre.10.fix.1
+```
+
+Version technique cible :
+
+```text
+workspace.package.version = 0.2.5-pre.10.fix.2
+```
+
+Identifiant de livraison :
+
+```text
+0.2.5-pre.010-fix.002
+```
+
+Commit attendu après validation :
+
+```text
+v0.2.5-pre.010-fix.002
+```
+
+Aucun tag stable n'est créé par ce fix et `rel.001` reste bloqué jusqu'à validation complète.
+
+## 2. Cause du fix
+
+La validation opérateur de `pre.010-fix.001` a montré que la normalisation automatisée avait introduit plusieurs erreurs de chemin dans `ksp-app-config-desk` :
+
+```text
+helpers privés de module référencés comme faux crate-root items
+fonctions pub(crate) renommées encore appelées sous leur ancien nom local
+réexport crate-root LoggingStartup déclaré mais non consommé explicitement
+```
+
+La revue manuelle a également détecté dans `ksp-core-lib/src/program_ids.rs` une accolade fermante restée à l'ancien emplacement après déplacement de `entries()`. Le code restait syntaxiquement valide parce que `PROGRAM_ID_ENTRIES` devenait un item local situé après un `return`, mais la structure du fichier était incorrecte.
+
+Enfin, le gate du fix précédent ne contrôlait pas assez précisément l'espacement entre items : plusieurs `const fn` et méthodes restaient accolées sans ligne vide.
+
+## 3. Corrections Config Desk
+
+Les tests séparés respectent désormais explicitement la règle de visibilité :
+
+```text
+item strictement privé du module parent -> super::Item
+item pub/pub(crate) partagé            -> crate::Item via crate-root
+```
+
+Corrections principales :
+
+```text
+unit_tests/environment.rs
+  crate::environment_report_from_management
+  -> super::report_from_management
+
+unit_tests/logging_editor.rs
+  crate::logging_document_from_management
+  -> super::document_from_management
+
+unit_tests/profiles.rs
+  crate::profile_inventory_from_management
+  -> super::inventory_from_management
+  crate::profile_detail_from_management
+  -> super::detail_from_management
+
+src/documents.rs
+  detail(...)
+  -> crate::document_detail(...)
+
+src/tw_main.rs
+  require_window(...)
+  -> crate::require_main_window(...)
+```
+
+`LoggingStartup` reste `pub(crate)` parce qu'il traverse la frontière `bootstrap -> app_state`. Les signatures crate-wide utilisent désormais explicitement `crate::LoggingStartup`, ce qui rend le réexport crate-root effectif et supprime le faux `unused import`.
+
+## 4. Correction `program_ids.rs`
+
+L'accolade fermante de :
+
+```rust
+pub const fn entries() -> &'static [crate::ProgramIdEntry]
+```
+
+est replacée immédiatement après :
+
+```rust
+return PROGRAM_ID_ENTRIES;
+```
+
+`PROGRAM_ID_ENTRIES` redevient ainsi un item de module et non un `const` local déclaré après un `return`.
+
+## 5. Espacement Rust normalisé
+
+Le workspace applique maintenant les règles explicites suivantes :
+
+```text
+fonction/méthode/const fn distincte -> exactement 1 ligne vide entre items
+struct/enum/union/trait/impl voisins -> exactement 1 ligne vide
+const de même visibilité dans un même bloc -> 0 ligne vide
+type/static homogènes de même visibilité -> 0 ligne vide
+changement de visibilité/catégorie -> exactement 1 ligne vide
+aucune ligne vide dans le corps d'une fonction/méthode/struct/enum
+```
+
+Le renforcement a détecté puis corrigé 53 séparations manquantes héritées de `fix.001`, notamment dans :
+
+```text
+ksp-app-config-desk
+ksp-config-lib
+ksp-logging-lib
+ksp-onchain-transport-lib
+ksp-wallet-lib
+```
+
+La majorité concernait les méthodes de `rpc_cluster.rs`.
+
+## 6. Audits renforcés
+
+### `audit_rust_general_rules.py`
+
+Ajouts :
+
+```text
+RUST-FMT-110
+  détecte un item déclaré après un return inconditionnel au niveau principal
+  d'une fonction/méthode ; signal d'une accolade ou restructuration incorrecte
+
+RUST-FMT-111
+  impose exactement une ligne vide entre items fonctionnels/type-level voisins
+
+RUST-FMT-112
+  interdit une ligne vide dans un bloc homogène const/static/type de même visibilité
+
+RUST-FMT-113
+  impose exactement une ligne vide entre les blocs pub use et pub(crate) use
+```
+
+### `audit_rust_export_completeness.py`
+
+Ajout d'un contrôle de résolution des chemins simples `crate::Item`. Le nouvel audit vérifie qu'un symbole référencé directement depuis le crate-root est réellement déclaré ou réexporté à cette racine.
+
+Ce contrôle aurait détecté les faux noms `crate::environment_report_from_management`, `crate::logging_document_from_management`, etc. avant la compilation.
+
+Les macros `#[macro_export]`, modules crate-root et bridges `pub extern crate` sont intégrés à l'inventaire afin de ne pas produire de faux positifs.
+
+## 7. Règles normatives
+
+`docs/rules/RULES_RUST.md` précise désormais sans ambiguïté :
+
+- séparation exacte d'une ligne entre fonctions, méthodes et `const fn` ;
+- séparation exacte entre types/blocs `impl` voisins ;
+- absence de ligne vide entre constantes de même visibilité ;
+- séparation d'une ligne entre niveaux de visibilité distincts ;
+- règle analogue pour blocs homogènes `type`/`static` ;
+- interdiction d'un item placé après un `return` inconditionnel au niveau principal d'une fonction.
+
+## 8. Validation exécutée dans l'environnement de préparation
+
+Les contrôles Python ont réellement été exécutés sur l'arbre cible :
+
+```text
+General Rust rule audit: clean
+Rust export completeness audit: 0 candidate(s)
+KSP workspace Rust rule audit: clean
+```
+
+Les scripts modifiés ont aussi été vérifiés par `python3 -m py_compile` pendant la préparation.
+
+Aucun toolchain Cargo/Rust n'est disponible dans l'environnement de préparation ; aucune compilation Rust locale n'est donc revendiquée.
+
+## 9. Validation opérateur requise
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-wallet-lib
+cargo test --workspace
+```
+
+Les arbres de dépendances Dalek/Solana ne nécessitent pas d'être répétés pour ce fix : aucune dépendance n'est modifiée par `fix.002`.