Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.5-alpha.8

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-25 17:41:26 +02:00
parent ecd9de4d4e
commit c331da5114
14 changed files with 1034 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Matrice de validation PGR
@@ -37,9 +37,9 @@ PGR préfère plusieurs audits simples avec une responsabilité identifiable à
## Contrôles Rust réutilisables, hors gate du dépôt PGR
[`002-RUST_STYLE_AUDITS.md`](002-RUST_STYLE_AUDITS.md) décrit deux audits facultatifs : `audit_rust_blank_lines.py` contrôle l'espacement des lignes vides, `audit_rust_const_blocks.py` contrôle l'ordre et l'espacement des blocs de constantes au niveau racine. Ils acceptent des chemins Rust sélectionnés et partagent un petit support lexical ; leur validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_audits.py`.
[`002-RUST_STYLE_AUDITS.md`](002-RUST_STYLE_AUDITS.md) décrit les audits monotâches de structure Rust : lignes vides, blocs `const`, séparation des items, ordre des modules, disposition des imports de traits et blocs de réexports. Ils acceptent des chemins Rust sélectionnés et partagent un petit support lexical ; leur validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_audits.py -v`.
Leur disponibilité ne transforme pas PGR en workspace Rust et ne rend pas automatiquement l'ordre alphabétique applicable à chaque fichier d'un projet. Lors d'une adoption, le projet propriétaire sélectionne ses chemins après `cargo fmt` et applique sa propre gate ; Rustfmt et Clippy conservent les contrôles qu'ils possèdent.
Pour une nouvelle baseline contrôlée, les propriétés sans ordre métier peuvent faire partie du profil strict. L'audit `const_blocks` reste explicitement sélectionné, car une table de protocole, un schéma ou une séquence normative ne doit jamais être réordonné pour satisfaire un tri mécanique. Leur disponibilité ne transforme pas PGR en workspace Rust ; le projet propriétaire exécute ces audits après `cargo fmt`, et Rustfmt/Clippy/rustc conservent les contrôles qu'ils possèdent.
[`003-RUST_EXPORT_COMPLETENESS.md`](003-RUST_EXPORT_COMPLETENESS.md) décrit séparément `audit_rust_export_completeness.py`, audit facultatif de façade crate-root. Sa validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_export_completeness.py -v`. L'audit est destiné aux projets Rust qui choisissent explicitement ce contrat ; PGR n'exécute pas ce script sur son propre dépôt comme gate, car il ne constitue pas lui-même un workspace Rust.

73
docs/validation/002-RUST_STYLE_AUDITS.md
View File

@@ -1,34 +1,79 @@
<!-- file: docs/validation/002-RUST_STYLE_AUDITS.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Audits facultatifs de style Rust
# 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` 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`](../rules/510-RUST_CARGO.md), et la sélection des preuves dans [`400-VALIDATION.md`](../rules/400-VALIDATION.md).
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.
`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.
Le contrat normatif est dans [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). Les scripts disponibles sont read-only et chacun possède une seule famille de preuve :
```text
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`](003-RUST_EXPORT_COMPLETENESS.md), car il possède la façade et les chemins canoniques plutôt que le formatage.
## 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 :
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 :
```bash
cargo fmt --all -- --check
python3 -B scripts/audit_rust_blank_lines.py crates/example/src
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 :
```bash
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.
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.
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.
`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.
## Limites mesurées
`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.
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.
## Mesure croisée KSP / Games
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.
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 :
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.
```text
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`.