3.7 KiB
Audits facultatifs de style Rust
Responsabilité et provenance
Les sources KSP 0.3.16 et Games 0.3.5 possèdent chacune un audit_rust_general_rules.py qui mêle plusieurs règles. Le découpage PGR fournit deux contrôles ciblés sans copier l'orchestrateur ni les règles propres aux deux projets. Le contrat de style facultatif est dans 510-RUST_CARGO.md, et la sélection des preuves dans 400-VALIDATION.md.
scripts/audit_rust_blank_lines.py contrôle les lignes vides consécutives et les lignes vides dans un corps de fonction/méthode, struct ou enum. scripts/audit_rust_const_blocks.py contrôle l'ordre pub, pub(crate), privé, le tri naturel des noms dans chaque visibilité et l'espacement entre constantes consécutives au niveau racine du fichier. scripts/_rust_audit_common.py partage la sélection des chemins et le masquage des commentaires/littéraux : il ne définit aucune nouvelle politique.
Adoption et commandes
Dans un projet Rust qui choisit ces conventions, copier les trois fichiers scripts/*.py concernés en gardant le helper à côté des deux audits. Adapter les headers file au chemin du projet et maintenir une révision de fichier propre à cette copie.
Choisir explicitement les fichiers concernés par chaque contrat. Après formatage :
cargo fmt --all -- --check
python3 -B scripts/audit_rust_blank_lines.py crates/example/src
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 fichiers inspectés ni l'arborescence de build. Les sorties utilisent le chemin et la ligne ; le code de sortie est 0 si propre, 1 pour violation, 2 pour sélection/lecture impossible.
Ne sélectionner pour l'audit des constantes que les fichiers dont les blocs racine sans sémantique d'ordre doivent effectivement suivre ce contrat. Un tri de table de protocole, des migrations, des champs de wire format ou de toute séquence métier peut casser le programme : sa revue appartient au projet. Ne pas utiliser la sortie du script comme justification pour les réordonner.
Limites mesurées
La prévalidation des sources réels a porté sur 300 fichiers KSP et 59 Games sous crates/**/src/. L'audit des lignes vides n'y détecte aucun écart. L'audit de constantes détecte 17 signaux KSP et aucun Games lorsque tous ces fichiers lui sont soumis ; des fichiers KSP contiennent des séquences ordonnées selon le protocole ou le schéma, ce qui rend une gate globale du tri inappropriée. Ces observations ne sont pas une gate de validation opérateur PGR.
L'analyse lexicale masque littéraux et commentaires courants, y compris commentaires imbriqués et chaînes Rust brutes. Elle n'est pas un parseur Rust : les macros élaborées, syntaxe nouvelle, attributs complexes, items associés dans impl et constantes dans modules inline n'entrent pas dans le contrat garanti de l'audit des blocs racine. Les lignes vides à l'intérieur d'un littéral multilignes sont exclues. Les cas qui demandent une interprétation sémantique nécessitent la revue humaine ou les outils Rust du projet.
Rustfmt reste propriétaire de l'ordre qu'il réécrit déjà dans les groupes de use/mod. Clippy et le compilateur restent responsables de leurs diagnostics. La suite tests/test_rust_audits.py vérifie les propriétés ciblées avec des cas propres, des violations et des littéraux/commentaires qui contiennent des accolades.