5.2 KiB
Audits monotâches de structure Rust
Responsabilité et provenance
Les sources KSP 0.3.16 et Games 0.3.5 possèdent chacune un audit_rust_general_rules.py composite. 0.0.3 avait déjà extrait deux propriétés ciblées ; 0.0.5-alpha.8 termine la réconciliation des propriétés de forme communes sans importer cet orchestrateur monolithique ni ses règles locales.
Le contrat normatif est dans 510-RUST_CARGO.md. Les scripts disponibles sont read-only et chacun possède une seule famille de preuve :
audit_rust_blank_lines.py
lignes vides consécutives et lignes vides dans fn/méthode/struct/enum
audit_rust_const_blocks.py
ordre visibilité/nom et espacement des blocs const explicitement sélectionnés
audit_rust_item_spacing.py
exactement une ligne vide entre items Rust distincts voisins d'un même scope
audit_rust_module_order.py
modules de production avant tests, ordre alphabétique de chaque groupe
audit_rust_trait_import_blocks.py
bloc de use non exportés au module, avant les déclarations et sans ligne vide interne
audit_rust_reexport_blocks.py
bloc pub use avant pub(crate) use, espacement exact entre/à l'intérieur des blocs
scripts/_rust_audit_common.py partage seulement la sélection de fichiers et le masquage lexical des commentaires/littéraux. Il ne définit aucune politique. audit_rust_export_completeness.py reste séparé dans 003-RUST_EXPORT_COMPLETENESS.md, car il possède la façade et les chemins canoniques plutôt que le formatage.
Adoption et commandes
Pour une nouvelle baseline Rust contrôlée qui sélectionne le profil strict, les audits sans interprétation métier peuvent être exécutés sur les sources concernées après Rustfmt :
cargo fmt --all -- --check
python3 -B scripts/audit_rust_blank_lines.py crates
python3 -B scripts/audit_rust_item_spacing.py crates
python3 -B scripts/audit_rust_module_order.py crates
python3 -B scripts/audit_rust_trait_import_blocks.py crates
python3 -B scripts/audit_rust_reexport_blocks.py crates
L'audit des constantes reste différent : sélectionner seulement les fichiers dont les blocs const doivent réellement suivre l'ordre mécanique PGR. Exemple :
python3 -B scripts/audit_rust_const_blocks.py crates/example/src/constants.rs
Une invocation sans chemin est une erreur, de même qu'un chemin absent ou aucun fichier Rust sélectionné. Un répertoire sélectionne récursivement les fichiers .rs hors répertoires générés habituels. Les audits ne modifient ni les sources ni l'arborescence de build. Le code de sortie est 0 si propre, 1 pour violation et 2 pour sélection/lecture impossible.
audit_rust_trait_import_blocks.py ne prouve pas qu'un use importe réellement un trait ; cette sémantique appartient au profil et à la revue/compilation. audit_rust_reexport_blocks.py ne trie pas les symboles exportés. Dans les deux cas, Rustfmt reste l'owner de l'ordre intra-bloc lorsque les lignes sont contiguës.
audit_rust_item_spacing.py ne possède pas l'espacement des blocs compacts homogènes const/static/type : il les délègue afin de ne pas transformer une séparation sémantique entre deux grandes tables en faux positif. L'audit spécialisé const_blocks reste opt-in sur des fichiers explicitement choisis.
Mesure croisée KSP / Games
La prévalidation alpha.8 a exécuté les quatre nouveaux audits sur l'ensemble des fichiers Rust sous crates/ des archives fournies : 603 fichiers KSP 0.3.16 et 87 fichiers Games 0.3.5. Les quatre contrôles sont propres sur les deux corpus :
KSP 0.3.16 Games 0.3.5
item spacing clean / 603 clean / 87
module order clean / 603 clean / 87
trait import blocks clean / 603 clean / 87
re-export blocks clean / 603 clean / 87
L'audit des lignes vides est également propre sur les 603 et 87 fichiers. En revanche, l'audit const_blocks appliqué aveuglément à tout le corpus produit 18 signaux KSP et 0 Games. Certains signaux KSP concernent des tables/schémas dont l'ordre est intentionnel, ce qui confirme qu'il ne doit pas devenir une gate globale par défaut. Ces mesures sont des preuves de réconciliation PGR, pas une validation opérateur de KSP/Games.
Limites et owners
Les analyses masquent les commentaires et littéraux courants, y compris chaînes brutes et commentaires imbriqués, mais ne constituent pas un parseur Rust. Elles n'essaient pas de comprendre les expansions de macros, l'ordre métier, les protocoles ou les dépendances sémantiques entre items.
PGR ne crée pas d'audit automatique pour imposer un ordre global des catégories enum, struct, impl, fonctions ou helpers privés. Le rapprochement struct puis impl, et la préférence des éléments visibles avant les helpers privés, restent des conventions de lisibilité soumises à la sémantique locale.
Rustfmt possède le formatage et les tris qu'il sait réellement réécrire ; rustc et Clippy conservent leurs diagnostics. Les tests PGR de ces scripts vivent dans tests/test_rust_audits.py.