khadhroony-solana-project/deltas/0.2.5/pre.010-fix.002.md

<!-- 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`.