0.0.5-alpha.7

This commit is contained in:
2026-09-25 11:45:10 +02:00
parent 4e1c1cd6f0
commit ac03b78708
8 changed files with 398 additions and 28 deletions

View File

@@ -1 +1 @@
0.0.5-alpha.6.fix.3 0.0.5-alpha.7

175
deltas/0.0.5/alpha.7.md Normal file
View File

@@ -0,0 +1,175 @@
<!-- file: deltas/0.0.5/alpha.7.md -->
<!-- version: 1 -->
# Delta 0.0.5-alpha.7 — profil Rust strict, chemins et nomenclature explicite
## Baseline et version
Baseline attendue : commit opérateur complet de `0.0.5-alpha.6.fix.3`, réalisé après application de `history/0.0.5/alpha.6.fix.3.md` avec statut `PASS`.
Version après application :
```text
0.0.5-alpha.7
```
## Motif
La réconciliation Tauri a confirmé qu'un host contrôlé hérite du profil Rust au lieu de redéfinir ses conventions. La relecture des règles autoritaires KSP/Games révèle alors un écart PGR plus ancien : la conception initiale avait retenu un profil de forte explicité, mais `510-RUST_CARGO.md` matérialisé conservait encore une politique permissive sur les `use` non-traits et ne formalisait pas la nomenclature des crates.
KSP `RULES_RUST.md` version `10` fournit la référence stricte : Rust 2024, `use` réservé aux traits, chemins externes publics explicites et courts, réexports internes `self::`, façade crate-root, `crate::Item`, absence d'alias/globs et contrôle de flux explicite. Games `RULES_RUST.md` version `7` confirme le noyau Rust 2024/façade/erreurs mais reste plus léger sur certains imports et règles de forme. `alpha.7` retient donc le profil strict comme défaut des **nouvelles baselines contrôlées** tout en conservant des overrides explicites pour les projets externes ou historiques.
## Scope
REPLACE :
```text
VERSION
docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md
docs/rules/510-RUST_CARGO.md
docs/skeletons/002-RUST_CARGO_WORKSPACE.md
docs/studies/001-KSP_GAMES_RECONCILIATION.md
docs/templates/002-CARGO_MANIFESTS.md
```
ADD :
```text
deltas/0.0.5/alpha.7.md
```
DELETE : aucun.
## Décisions
Pour une nouvelle baseline Rust contrôlée :
- Rust 2024 devient la baseline normative actuelle ; une contrainte externe doit être documentée explicitement ;
- `use` est réservé aux traits qui doivent réellement être mis en scope ; les autres symboles sont appelés par chemins explicites ;
- un symbole externe utilise le chemin public le plus court exposé par sa crate ;
- les réexports internes utilisent `self::`, restent explicites ligne par ligne et ne masquent pas les collisions par alias ;
- les glob imports, regroupements par accolades de façade et imports non-traits de commodité sont interdits ;
- les modules d'implémentation restent privés ; les items partagés passent par la façade crate-root et `crate::Item`, y compris dans leur module propriétaire ;
- `pub(super)`/`pub(in ...)` ne remplacent pas cette façade dans une baseline contrôlée ;
- tout `pub`/`pub(crate)` et tout réexport crate-root porte une rustdoc utile ;
- `unwrap`, `expect` et `?` sont interdits en production dans le profil strict ; la propagation d'erreur et les retours restent explicites.
Le marqueur historique KSP `rust-rules: trait-import` n'est pas généralisé : il appartient à l'enforcement local, pas à la règle sémantique.
Pour la nomenclature des crates d'un nouveau projet contrôlé :
```text
<project>-<responsibility>-<role-or-target>
```
est la forme recommandée. Le préfixe projet/abréviation est obligatoire ; le classificateur (`lib`, `api`, `worker`, `job`, `cli`, `desk`, `desktop`, `tauri`, `wasm`, `server`, etc.) est utilisé lorsqu'il apporte une information réelle. Le vocabulaire exact reste local, aucun suffixe n'est ajouté par symétrie et aucun projet historique n'est renommé rétroactivement uniquement pour adopter cette grammaire.
Le skeleton Rust/Cargo et le guide des manifests adoptent ces choix pour les futures baselines contrôlées. L'audit de façade déjà livré devient une sélection recommandée du skeleton strict ; l'adoption d'un projet existant commence toujours en `--report-only`.
## Hors scope
Cette tranche ne modifie pas les règles de blocs homogènes, ordre alphabétique, espacement, regroupement par visibilité ou organisation structurelle des items : elles restent réservées à `alpha.8` avec leurs audits monotâches.
Elle n'importe pas `audit_rust_general_rules.py` depuis KSP/Games, ne crée aucun parser Rust général et ne modifie pas le skeleton Tauri prévu en `alpha.9`.
## Validation opérateur
Après application du history `PASS` de `alpha.6.fix.3`, commit/push de cette tranche, puis application du présent delta :
```bash
test "$(cat VERSION)" = '0.0.5-alpha.7'
test -f history/0.0.5/alpha.6.fix.3.md
test -f deltas/0.0.5/alpha.7.md
test ! -e history/0.0.5/alpha.7.md
grep -A2 '^## Statut$' history/0.0.5/alpha.6.fix.3.md | grep -Fx 'PASS'
grep -Fx '<!-- version: 5 -->' docs/rules/510-RUST_CARGO.md
grep -Fx '<!-- version: 3 -->' docs/skeletons/002-RUST_CARGO_WORKSPACE.md
grep -Fx '<!-- version: 2 -->' docs/templates/002-CARGO_MANIFESTS.md
grep -Fx '<!-- version: 8 -->' docs/studies/001-KSP_GAMES_RECONCILIATION.md
grep -Fx '<!-- version: 9 -->' docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md
python3 -B -m unittest discover -s tests -v
python3 -B scripts/audit_markdown_headers.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
python3 -B scripts/audit_markdown_tables.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
python3 -B scripts/audit_markdown_links.py \
README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts
python3 -B - <<'PY'
from pathlib import Path
import re
history = Path("history/0.0.5/alpha.6.fix.3.md").read_text(encoding="utf-8")
assert re.search(r"## Statut\s+PASS\s", history)
rules = Path("docs/rules/510-RUST_CARGO.md").read_text(encoding="utf-8")
for phrase in (
"nouveau projet Rust contrôlé MUST utiliser l'édition Rust 2024",
"### Nomenclature des crates dans un projet contrôlé",
"<project>-<responsibility>-<role-or-target>",
"### `use` réservé aux traits",
"le code utilise directement le **chemin public le plus court**",
"Les réexports d'éléments internes commencent par `self::`",
"toute référence dans la même crate MUST utiliser `crate::Item`",
"`unwrap()` et `expect()` MUST NOT être utilisés",
"l'opérateur `?` MUST NOT être utilisé",
):
assert phrase in rules, phrase
for forbidden in (
"PGR ne généralise pas l'interdiction KSP plus stricte de tous les `use` non-traits",
"le profil de façade crate-root est seulement facultatif pour une nouvelle baseline contrôlée",
):
assert forbidden not in rules, forbidden
skeleton = Path("docs/skeletons/002-RUST_CARGO_WORKSPACE.md").read_text(encoding="utf-8")
for phrase in (
"nom court/abréviation canonique du projet",
"édition Rust 2024",
"façade crate-root et les chemins explicites sont sélectionnés par défaut",
"audit_rust_export_completeness.py",
):
assert phrase in skeleton, phrase
study = Path("docs/studies/001-KSP_GAMES_RECONCILIATION.md").read_text(encoding="utf-8")
assert "#### Décision `alpha.7` — profil Rust strict et nomenclature" in study
assert "KSP `RULES_RUST.md` version `10`" in study
assert "Games `RULES_RUST.md` version `7`" in study
assert "Les règles de blocs homogènes" in study
plan = Path("docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md").read_text(encoding="utf-8")
assert "La réconciliation des règles versionnées KSP/Games retient KSP comme référence stricte" in plan
assert "### alpha.8 — formatage Rust structurel et audits monotâches" in plan
assert "### alpha.9 — décision de skeleton Tauri pour projets contrôlés" in plan
print("0.0.5 alpha.7 strict Rust profile audit: clean (explicit paths, crate-root facade, controlled naming, alpha.8 formatting deferred)")
PY
git diff --check
git add VERSION \
docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md \
docs/rules/510-RUST_CARGO.md \
docs/skeletons/002-RUST_CARGO_WORKSPACE.md \
docs/studies/001-KSP_GAMES_RECONCILIATION.md \
docs/templates/002-CARGO_MANIFESTS.md \
deltas/0.0.5/alpha.7.md
git diff --cached --check
git status --short
```
La sortie Git attendue avant ajout du history est exactement :
```text
M VERSION
A deltas/0.0.5/alpha.7.md
M docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md
M docs/rules/510-RUST_CARGO.md
M docs/skeletons/002-RUST_CARGO_WORKSPACE.md
M docs/studies/001-KSP_GAMES_RECONCILIATION.md
M docs/templates/002-CARGO_MANIFESTS.md
```

View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md --> <!-- file: docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md -->
<!-- version: 8 --> <!-- version: 9 -->
# Plan 0.0.5 — réconciliation réelle avec KSP et sasedev-games # Plan 0.0.5 — réconciliation réelle avec KSP et sasedev-games
@@ -110,11 +110,11 @@ Comme `fix.3` atteint le seuil de revue obligatoire des correctifs, le plan est
### alpha.7 — profil Rust strict, chemins et nomenclature explicite ### alpha.7 — profil Rust strict, chemins et nomenclature explicite
Réconcilier les décisions historiques avec les règles effectivement versionnées dans KSP/Games. KSP sert de référence stricte pour les `use` réservés aux traits, chemins externes publics les plus courts, réexports `self::`, alias interdits, façade crate-root et contrôle de flux explicite ; Games confirme le noyau mais montre quelles règles doivent rester sélectionnables ou adaptables. La réconciliation des règles versionnées KSP/Games retient KSP comme référence stricte et Games comme contrôle de généralisation. Pour une nouvelle baseline contrôlée, `510-RUST_CARGO.md` impose désormais Rust 2024, réserve `use` aux traits réellement nécessaires, exige les chemins publics explicites les plus courts pour les autres symboles, les réexports internes `self::`, la façade crate-root et `crate::Item`, et conserve le contrôle de flux explicite sans `unwrap`, `expect` ni `?` en production.
Cette tranche doit également formaliser une convention générique de nomenclature des crates pour les projets contrôlés : préfixe projet/abréviation, responsabilité lisible et suffixe de rôle ou cible (`lib`, `api`, `worker`, `cli`, `desk`, `desktop`, `tauri`, `wasm`, etc.) seulement lorsque ce suffixe apporte une information réelle. Les vocabulaires exacts KSP/Games restent locaux. La nomenclature des crates devient également explicite : préfixe projet/abréviation obligatoire ; responsabilité puis rôle/cible lisibles lorsque ce classificateur apporte une information réelle. La forme recommandée est `<project>-<responsibility>-<role-or-target>` sans figer les vocabulaires KSP/Games ni imposer de renommage rétroactif. Les projets externes ou historiquement contraints peuvent documenter un override borné.
Aucun gros audit composite n'est importé. Les contrôles déjà possédés par Clippy, rustc ou l'audit de façade restent chez leur owner. Le skeleton Rust/Cargo et le guide de manifest reflètent ces choix. Aucun gros audit composite n'est importé ; le marqueur KSP spécifique des trait imports n'est pas généralisé et les contrôles déjà possédés par Clippy, rustc ou l'audit de façade restent chez leur owner.
### alpha.8 — formatage Rust structurel et audits monotâches ### alpha.8 — formatage Rust structurel et audits monotâches

View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/510-RUST_CARGO.md --> <!-- file: docs/rules/510-RUST_CARGO.md -->
<!-- version: 4 --> <!-- version: 5 -->
# Profil Rust / Cargo # Profil Rust / Cargo
@@ -11,9 +11,13 @@ Il spécialise [`500-LANGUAGES.md`](500-LANGUAGES.md) pour les responsabilités
Une règle plus spécifique, par exemple Android, WASM, Tauri ou une frontière FFI, MAY raffiner ce profil dans son scope sans modifier la politique Rust générale. Une règle plus spécifique, par exemple Android, WASM, Tauri ou une frontière FFI, MAY raffiner ce profil dans son scope sans modifier la politique Rust générale.
Pour un **nouveau projet contrôlé** par l'organisation, PGR sélectionne par défaut le profil strict décrit ci-dessous : provenance des symboles visible, façade crate-root explicite, contrôle de flux explicite et noms de crates lisibles. Un projet existant ou imposé par un tiers MAY conserver des contraintes différentes via des règles project-specific ou des exceptions bornées ; cette adaptation ne rend pas le profil strict moins canonique pour les nouvelles baselines contrôlées.
## Toolchain et édition ## Toolchain et édition
Un nouveau projet Rust SHOULD utiliser une toolchain stable récente compatible avec ses dépendances et ses cibles. Une toolchain nightly, beta ou autre prerelease nécessite une justification explicite. Un nouveau projet Rust contrôlé MUST utiliser l'édition Rust 2024 avec une toolchain stable compatible avec ses dépendances et ses cibles, sauf contrainte externe explicitement documentée. Une toolchain nightly, beta ou autre prerelease nécessite une justification explicite.
`2024` est la baseline normative actuelle des projets contrôlés ; PGR ne bascule pas automatiquement vers une future édition au seul motif qu'elle existe. Une évolution de cette baseline demande une décision PGR explicite et une validation de compatibilité.
PGR MUST NOT imposer un pin exact de toolchain uniquement parce qu'un projet source historique utilisait cette version. Un fichier `rust-toolchain.toml` ou équivalent SHOULD être ajouté uniquement lorsqu'un besoin réel de reproductibilité, de composant ou de compatibilité l'exige. PGR MUST NOT imposer un pin exact de toolchain uniquement parce qu'un projet source historique utilisait cette version. Un fichier `rust-toolchain.toml` ou équivalent SHOULD être ajouté uniquement lorsqu'un besoin réel de reproductibilité, de composant ou de compatibilité l'exige.
@@ -34,6 +38,36 @@ Un monorepo contenant plusieurs unités de release indépendantes MUST NOT fabri
Le répertoire `crates/` est le placement PGR recommandé pour les packages Rust d'un workspace structuré, sauf layout imposé par un framework, une plateforme ou un projet existant. Le répertoire `crates/` est le placement PGR recommandé pour les packages Rust d'un workspace structuré, sauf layout imposé par un framework, une plateforme ou un projet existant.
### Nomenclature des crates dans un projet contrôlé
Une crate appartenant à un projet contrôlé MUST commencer par le nom court canonique du projet ou une abréviation documentée et stable. Le reste du nom SHOULD rendre immédiatement lisibles sa responsabilité principale puis, lorsqu'il apporte une information réelle, son rôle ou sa cible.
La forme recommandée est :
```text
<project>-<responsibility>-<role-or-target>
```
Exemples de classificateurs utiles selon le projet :
```text
lib
api
worker
job
cli
desk
desktop
tauri
wasm
server
```
Cette liste n'est ni exhaustive ni un vocabulaire imposé. Un suffixe ou classificateur ne doit pas être ajouté par symétrie : `api` suppose un vrai contrat/extensibility boundary, `worker` un service continu identifiable, `cli` une interface ligne de commande, etc. À l'inverse, un rôle important ne doit pas être masqué dans un nom générique comme `common`, `core` ou `utils` sans responsabilité suffisamment précise.
Un projet historique MAY conserver un ordre local déjà stable, par exemple un rôle placé avant la responsabilité, si sa nomenclature est documentée et cohérente. PGR n'impose aucune campagne de renommage rétroactive uniquement pour adopter la grammaire recommandée.
## Manifests et dépendances Cargo ## Manifests et dépendances Cargo
Dans un workspace, une dépendance tierce réellement partagée par plusieurs crates SHOULD posséder sa contrainte de version canonique sous `[workspace.dependencies]`. Dans un workspace, une dépendance tierce réellement partagée par plusieurs crates SHOULD posséder sa contrainte de version canonique sous `[workspace.dependencies]`.
@@ -84,28 +118,57 @@ Lorsqu'une FFI ou une plateforme impose réellement une opération `unsafe`, l'e
Une exception FFI locale n'autorise donc pas à remplacer globalement `unsafe_code = "forbid"` par une politique permissive pour toutes les crates. Une exception FFI locale n'autorise donc pas à remplacer globalement `unsafe_code = "forbid"` par une politique permissive pour toutes les crates.
## API, visibilité et rustdoc ## API, visibilité, imports et chemins
Tout élément `pub` ou `pub(crate)` SHOULD posséder une rustdoc utile au point de déclaration lorsque son contrat dépasse une implémentation triviale locale. Dans le profil strict d'un projet contrôlé, tout élément `pub` ou `pub(crate)` MUST posséder une rustdoc utile au point de déclaration. Toute réexportation `pub use` ou `pub(crate) use` visible au crate-root MUST également porter une rustdoc adjacente utile. Une rustdoc qui répète seulement le nom du symbole ne satisfait pas ce contrat.
Une crate réutilisable SHOULD exposer son API durable depuis son crate-root par des réexports explicites. Les modules d'implémentation SHOULD rester privés ; `pub mod` ne doit pas être utilisé uniquement pour éviter de concevoir une façade stable. Les modules d'implémentation restent privés. `pub mod` MUST NOT être utilisé pour exposer paresseusement une arborescence interne ; `pub(super)` et `pub(in ...)` MUST NOT remplacer une façade crate-root explicite dans une baseline contrôlée.
Lorsqu'un projet adopte le **contrat strict de façade crate-root**, un élément `pub` d'un module fichier MUST être réexporté explicitement au crate-root. Un élément `pub(crate)` consommé hors de son module MUST de même posséder un réexport `pub(crate)` au crate-root. Un helper réellement local SHOULD rester privé plutôt qu'élargir artificiellement sa visibilité. Un élément `pub` d'un module fichier MUST être réexporté explicitement au crate-root. Un élément `pub(crate)` consommé hors de son module MUST de même posséder un réexport `pub(crate)` au crate-root. Un helper réellement local SHOULD rester privé plutôt qu'élargir artificiellement sa visibilité.
Dès qu'un item possède cette identité crate-root, toute référence dans la même crate MUST utiliser `crate::Item`, y compris depuis son module de déclaration et depuis ses tests unitaires attachés. Les formes `Item`, `self::Item`, `super::Item`, `module::Item` et `crate::module::Item` ne sont pas des chemins de consommation canoniques pour cet item partagé. Un élément strictement privé reste local au module ; un test unitaire attaché peut alors utiliser `super::PrivateItem`. Les réexports d'éléments internes commencent par `self::` :
Les autres crates consomment l'API publique du crate propriétaire via `owner_crate::Item` plutôt que ses chemins internes. Les glob imports SHOULD être évités. Un alias de réexport ne doit pas servir à masquer durablement une collision de noms dans l'API ; lorsqu'un nom fait partie du contrat public, le propriétaire SHOULD choisir un nom canonique non ambigu. ```rust
pub use self::foo::Foo;
pub(crate) use self::bar::InternalBar;
```
PGR ne généralise pas l'interdiction KSP plus stricte de tous les `use` non-traits : cette convention appartient à un profil ou projet plus spécifique tant qu'elle n'est pas nécessaire au contrat Rust général. Un réexport de crate externe utilise son chemin public canonique. Les réexports groupés par accolades, les glob imports et les alias `as` servant à raccourcir ou masquer un nom MUST NOT être utilisés. Une collision durable se résout en donnant au symbole son nom canonique dans son module propriétaire.
### `use` réservé aux traits
Dans le profil strict, `use` MUST NOT importer une constante, fonction, structure, énumération, union, alias de type, module ou macro uniquement pour raccourcir son chemin. Les déclarations `use` sont réservées aux traits lorsqu'une résolution de méthode ou une contrainte du langage exige réellement leur mise en scope.
Un import de trait reste au niveau du module et ne mélange pas de symboles non-traits. Un projet MAY ajouter un marqueur de commentaire spécifique à son audit local, mais PGR n'impose pas un commentaire tel que `rust-rules: trait-import` : ce marqueur est un mécanisme d'enforcement, pas la règle sémantique elle-même.
Pour un élément fourni par une crate externe, le code utilise directement le **chemin public le plus court** exposé par cette crate, par exemple :
```rust
std::path::Path
serde_json::Value
other_crate::Item
```
et non un `use` non-trait destiné à raccourcir ce chemin. Un chemin interne plus long n'est pas préféré lorsque la crate externe expose déjà une façade publique plus courte.
### Façade crate-root et références intra-crate
Dès qu'un item partagé possède une identité crate-root, toute référence dans la même crate MUST utiliser `crate::Item`, y compris depuis son module de déclaration et depuis ses tests unitaires attachés. Les formes `Item`, `self::Item`, `super::Item`, `module::Item` et `crate::module::Item` ne sont pas des chemins de consommation canoniques pour cet item partagé.
Un élément strictement privé reste local au module et n'est pas réexporté. Dans un fichier de tests unitaires rattaché au module parent, un élément privé du parent peut être référencé via `super::PrivateItem`; un élément `pub` ou `pub(crate)` partagé continue d'être référencé via `crate::Item`.
Les autres crates consomment l'API publique du crate propriétaire via `owner_crate::Item`, jamais via ses modules internes. La visibilité d'un item MUST NOT être élargie uniquement pour permettre son test.
Ces conventions sont plus strictes que le Rust idiomatique minimal, mais elles sont retenues pour les projets contrôlés afin de rendre immédiatement visibles l'ownership et la provenance des symboles. Un projet externe contraint peut définir un override explicite ; l'exception ne devient pas la nouvelle règle PGR.
## Contrôle de flux et erreurs ## Contrôle de flux et erreurs
Dans le code de production du profil strict PGR : Dans le code de production du profil strict PGR :
- `unwrap()` et `expect()` MUST NOT servir à traiter un chemin d'erreur récupérable ; - `unwrap()` et `expect()` MUST NOT être utilisés ;
- `panic!` MUST NOT représenter une erreur métier récupérable ; - `panic!` MUST NOT représenter une erreur métier récupérable ;
- les retours explicites sont la convention par défaut ; - les retours explicites sont obligatoires lorsque la fonction possède une valeur de retour ;
- l'opérateur `?` est désactivé par le profil Clippy strict afin de conserver des chemins d'erreur explicites. - l'opérateur `?` MUST NOT être utilisé ; les chemins `Ok`/`Err` et conversions d'erreur restent explicites.
Une règle plus spécifique MAY définir une politique d'erreur différente lorsqu'elle possède une justification architecturale explicite. PGR ne généralise pas l'interdiction d'une bibliothèque d'erreur particulière à partir d'un seul projet source. Une règle plus spécifique MAY définir une politique d'erreur différente lorsqu'elle possède une justification architecturale explicite. PGR ne généralise pas l'interdiction d'une bibliothèque d'erreur particulière à partir d'un seul projet source.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/skeletons/002-RUST_CARGO_WORKSPACE.md --> <!-- file: docs/skeletons/002-RUST_CARGO_WORKSPACE.md -->
<!-- version: 2 --> <!-- version: 3 -->
# Skeleton — Rust/Cargo workspace # Skeleton — Rust/Cargo workspace
@@ -64,15 +64,15 @@ templates/rust-cargo/crates/project-core-lib/Cargo.toml
Avant de considérer la specialization comme instanciée, résoudre explicitement au minimum : Avant de considérer la specialization comme instanciée, résoudre explicitement au minimum :
1. le release unit gouverné et la relation entre son `VERSION` et `[workspace.package].version` ; 1. le release unit gouverné et la relation entre son `VERSION` et `[workspace.package].version` ;
2. la liste réelle des packages membres, leurs noms, leurs rôles et leurs chemins ; 2. le nom court/abréviation canonique du projet, la liste réelle des packages membres, leurs responsabilités, rôles et chemins, puis la conformité de leurs noms au contrat de `510-RUST_CARGO.md` ;
3. l'édition Rust, le resolver Cargo et la toolchain stable compatible ; 3. l'édition Rust 2024, le resolver Cargo et la toolchain stable compatible, ou l'exception externe explicitement documentée ;
4. la politique de publication et les métadonnées réelles communes (`license`, `repository`, `authors`) lorsqu'elles existent ; 4. la politique de publication et les métadonnées réelles communes (`license`, `repository`, `authors`) lorsqu'elles existent ;
5. les dépendances réellement partagées, leurs contraintes de version et les features qui doivent rester locales à chaque membre ; 5. les dépendances réellement partagées, leurs contraintes de version et les features qui doivent rester locales à chaque membre ;
6. la politique de versionnement de `Cargo.lock` adaptée au type de produit ; 6. la politique de versionnement de `Cargo.lock` adaptée au type de produit ;
7. les niveaux de lints hérités, les éventuelles exceptions locales et tout besoin réel d'`unsafe` dans un scope étroit ; 7. les niveaux de lints hérités, les éventuelles exceptions locales et tout besoin réel d'`unsafe` dans un scope étroit ;
8. les paramètres `rustfmt.toml` et `clippy.toml` à conserver ou adapter ; 8. les paramètres `rustfmt.toml` et `clippy.toml` à conserver ou adapter ;
9. l'emplacement des artefacts Cargo et l'identifiant unique utilisé dans `.cargo/config.toml` si cette politique externe au dépôt est retenue ; 9. l'emplacement des artefacts Cargo et l'identifiant unique utilisé dans `.cargo/config.toml` si cette politique externe au dépôt est retenue ;
10. les audits Rust facultatifs réellement adoptés, dont éventuellement le contrat de façade crate-root, et leur scope exact ; 10. les exceptions éventuelles au profil Rust strict ; pour une nouvelle baseline contrôlée, la façade crate-root et les chemins explicites sont sélectionnés par défaut, tandis que les audits de style supplémentaires restent décidés séparément ;
11. les validations Cargo réellement nécessaires au code et aux manifests créés. 11. les validations Cargo réellement nécessaires au code et aux manifests créés.
Les valeurs `0.1.0`, `2024`, `project-name`, `project-core-lib`, les seuils Clippy et les chemins de build présents dans les templates sont des exemples ou baselines à revoir. Ils ne deviennent jamais des valeurs universelles par simple copie. Les valeurs `0.1.0`, `2024`, `project-name`, `project-core-lib`, les seuils Clippy et les chemins de build présents dans les templates sont des exemples ou baselines à revoir. Ils ne deviennent jamais des valeurs universelles par simple copie.
@@ -103,7 +103,7 @@ Le projet ne doit pas remplir les champs manquants avec des identités fictives
Pour chaque crate réellement nécessaire, utiliser `templates/rust-cargo/crates/project-core-lib/Cargo.toml` comme exemple de manifest membre puis adapter son chemin et son nom. Pour chaque crate réellement nécessaire, utiliser `templates/rust-cargo/crates/project-core-lib/Cargo.toml` comme exemple de manifest membre puis adapter son chemin et son nom.
`project-core-lib` n'est pas un nom de crate imposé. Une crate bibliothèque, binaire ou spécialisée doit conserver le layout et les héritages qui correspondent à son rôle réel. `project-core-lib` n'est pas un nom de crate imposé. Dans une nouvelle baseline contrôlée, remplacer `project` par le nom court/abréviation du projet et choisir une responsabilité puis un rôle/cible lisibles conformément à `510-RUST_CARGO.md`. Une crate bibliothèque, binaire ou spécialisée doit conserver le layout et les héritages qui correspondent à son rôle réel ; un suffixe n'est pas ajouté uniquement pour obtenir une symétrie artificielle.
Lorsque le membre hérite de la politique commune, `version.workspace = true`, `edition.workspace = true`, `publish.workspace = true` et `[lints] workspace = true` restent cohérents. Une exception locale, notamment de lint ou de safety, doit suivre le contrat de `510-RUST_CARGO.md` et ne pas affaiblir silencieusement les autres membres. Lorsque le membre hérite de la politique commune, `version.workspace = true`, `edition.workspace = true`, `publish.workspace = true` et `[lints] workspace = true` restent cohérents. Une exception locale, notamment de lint ou de safety, doit suivre le contrat de `510-RUST_CARGO.md` et ne pas affaiblir silencieusement les autres membres.
@@ -131,9 +131,9 @@ Décider explicitement si `Cargo.lock` est versionné selon le type de produit,
Si le projet adopte les conventions documentées dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md), copier les scripts de style concernés et adapter leurs headers à leurs chemins locaux. La sélection des fichiers doit rester explicite. En particulier, l'audit des blocs de constantes ne doit jamais réordonner une table de protocole, une séquence de migrations ou toute autre structure dont l'ordre possède une sémantique propre. Si le projet adopte les conventions documentées dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md), copier les scripts de style concernés et adapter leurs headers à leurs chemins locaux. La sélection des fichiers doit rester explicite. En particulier, l'audit des blocs de constantes ne doit jamais réordonner une table de protocole, une séquence de migrations ou toute autre structure dont l'ordre possède une sémantique propre.
Si le projet adopte le contrat de façade décrit dans [`../validation/003-RUST_EXPORT_COMPLETENESS.md`](../validation/003-RUST_EXPORT_COMPLETENESS.md), copier `audit_rust_export_completeness.py` avec `_rust_audit_common.py`. Une adoption d'un projet existant SHOULD commencer en `--report-only`, résoudre les écarts ou exceptions locales, puis seulement rendre l'audit bloquant. Pour une nouvelle baseline contrôlée, le contrat de façade décrit dans [`../validation/003-RUST_EXPORT_COMPLETENESS.md`](../validation/003-RUST_EXPORT_COMPLETENESS.md) appartient au profil strict ; `audit_rust_export_completeness.py` avec `_rust_audit_common.py` SHOULD être adopté afin de contrôler les propriétés que `rustc` et Clippy ne possèdent pas. Une adoption d'un projet existant SHOULD commencer en `--report-only`, résoudre les écarts ou exceptions locales, puis seulement rendre l'audit bloquant.
Ne pas copier ces scripts uniquement parce qu'ils existent dans PGR. Les audits de style de `002-RUST_STYLE_AUDITS.md` restent séparés et ne sont copiés que lorsque leurs conventions sont retenues. Aucun script n'est copié uniquement parce qu'il existe dans PGR.
## Validation initiale ## Validation initiale
@@ -158,7 +158,9 @@ La validation doit aussi confirmer :
CHECK VERSION et workspace.package.version cohérents pour un train de release unique CHECK VERSION et workspace.package.version cohérents pour un train de release unique
CHECK aucun placeholder project-name/project-core-lib non résolu dans les fichiers adoptés CHECK aucun placeholder project-name/project-core-lib non résolu dans les fichiers adoptés
CHECK édition Rust cohérente entre Cargo.toml et rustfmt.toml CHECK édition Rust cohérente entre Cargo.toml et rustfmt.toml
CHECK membres du workspace existants et correctement nommés CHECK membres du workspace existants, préfixés et nommés selon leur responsabilité/rôle
CHECK édition Rust 2024 ou exception externe explicitement documentée
CHECK profil strict de chemins/façade appliqué ou override borné documenté
CHECK politique Cargo.lock explicitement décidée CHECK politique Cargo.lock explicitement décidée
CHECK artefacts Cargo hors des livraisons source selon la politique locale CHECK artefacts Cargo hors des livraisons source selon la politique locale
REVIEW dépendances/features, lints et métadonnées réellement nécessaires REVIEW dépendances/features, lints et métadonnées réellement nécessaires

View File

@@ -1,5 +1,5 @@
<!-- file: docs/studies/001-KSP_GAMES_RECONCILIATION.md --> <!-- file: docs/studies/001-KSP_GAMES_RECONCILIATION.md -->
<!-- version: 7 --> <!-- version: 8 -->
# Étude de réconciliation PGR / KSP / sasedev-games # Étude de réconciliation PGR / KSP / sasedev-games
@@ -184,6 +184,28 @@ La clarification opérateur de `alpha.6.fix.1` déclenche une seconde lecture de
**Nomenclature des crates** : KSP encode explicitement le rôle (`ksp-<role>-lib`, `ksp-<domain>-api`, `ksp-app-<role>-<interface>`, workers/jobs), tandis que Games conserve lui aussi des noms révélant rôle et cible (`game-logging-lib`, `*-desktop`, `*-tauri`, `*-wasm`, `engine-v1-*`). PGR doit donc étudier une convention générale « préfixe projet + responsabilité + suffixe de rôle/cible » sans figer les vocabulaires propres à KSP ou Games. **Nomenclature des crates** : KSP encode explicitement le rôle (`ksp-<role>-lib`, `ksp-<domain>-api`, `ksp-app-<role>-<interface>`, workers/jobs), tandis que Games conserve lui aussi des noms révélant rôle et cible (`game-logging-lib`, `*-desktop`, `*-tauri`, `*-wasm`, `engine-v1-*`). PGR doit donc étudier une convention générale « préfixe projet + responsabilité + suffixe de rôle/cible » sans figer les vocabulaires propres à KSP ou Games.
#### Décision `alpha.7` — profil Rust strict et nomenclature
La seconde passe sur les règles autoritaires confirme que KSP `RULES_RUST.md` version `10` matérialise le profil d'explicité le plus complet : Rust 2024, `use` réservé aux traits réellement nécessaires, chemins externes publics les plus courts, réexports internes `self::`, absence de glob/groupement/alias, façade crate-root, `crate::Item` intra-crate et contrôle de flux explicite. Games `RULES_RUST.md` version `7` confirme Rust 2024, façade crate-root, `crate::Item`, interdiction des globs, erreurs explicites et lints communs, tout en étant moins strict sur les imports non-traits et certaines formes de visibilité.
La décision PGR est de retenir ce niveau strict comme **défaut des nouvelles baselines Rust contrôlées**. Un projet externe ou historiquement contraint peut conserver une convention différente via un override project-specific borné ; cette exception ne réduit pas le profil canonique des nouveaux projets.
Les règles sémantiques retenues dans `alpha.7` sont :
- édition Rust 2024 comme baseline actuelle des projets contrôlés ;
- `use` réservé aux traits qui doivent réellement être mis en scope ;
- chemins explicites pour les autres symboles, avec le chemin public externe le plus court ;
- réexports internes explicites via `self::`, sans glob, regroupement par accolades ni alias de commodité ;
- façade crate-root pour les items partagés et `crate::Item` dans la crate, y compris dans le module propriétaire ;
- pas de visibilité élargie uniquement pour les tests ;
- `unwrap`, `expect` et `?` interdits en production dans le profil strict, avec retours et propagation d'erreurs explicites.
Le marqueur KSP `rust-rules: trait-import` n'est pas généralisé : il sert l'audit historique KSP et n'est pas la règle sémantique. De même, `alpha.7` n'importe aucun script composite KSP/Games ; l'enforcement complémentaire reste découpé entre les owners PGR existants et la tranche `alpha.8`.
La nomenclature converge sur une propriété utile sans imposer les vocabulaires locaux : KSP préfixe toutes ses crates avec `ksp-` et encode explicitement bibliothèque/API/application/worker/job ; Games emploie également des noms où responsabilité et cible restent visibles (`game-logging-lib`, `*-desktop`, `*-tauri`, `*-wasm`, familles `engine-v1-*`). PGR retient donc pour les nouveaux projets contrôlés un préfixe projet/abréviation obligatoire et recommande la forme `<project>-<responsibility>-<role-or-target>` lorsque le classificateur apporte une information réelle. Les ordres historiques déjà cohérents ne sont pas renommés rétroactivement.
Les règles de blocs homogènes, visibilité, espacement et ordre alphabétique restent volontairement hors de cette décision et appartiennent à `alpha.8`.
#### Politique de version Tauri/frontend réconciliée #### Politique de version Tauri/frontend réconciliée
La baseline KSP `0.3.16` illustre le défaut de l'ancienne convention : les six `tauri.conf.json` n'ont pas de champ `version`, tandis que leurs `package.json` portent des versions historiques différentes (`0.2.6`, `0.2.12-pre.9`, `0.3.7`, `0.3.8` ou `0.3.15`) sans représenter uniformément la release courante. Games `0.3.5` suit la même famille de règles. Cette situation réduit les modifications mécaniques mais affaiblit la lisibilité des manifests. La baseline KSP `0.3.16` illustre le défaut de l'ancienne convention : les six `tauri.conf.json` n'ont pas de champ `version`, tandis que leurs `package.json` portent des versions historiques différentes (`0.2.6`, `0.2.12-pre.9`, `0.3.7`, `0.3.8` ou `0.3.15`) sans représenter uniformément la release courante. Games `0.3.5` suit la même famille de règles. Cette situation réduit les modifications mécaniques mais affaiblit la lisibilité des manifests.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/templates/002-CARGO_MANIFESTS.md --> <!-- file: docs/templates/002-CARGO_MANIFESTS.md -->
<!-- version: 1 --> <!-- version: 2 -->
# Modèles de manifests Cargo workspace et crate membre # Modèles de manifests Cargo workspace et crate membre
@@ -23,7 +23,7 @@ Les trois lints Rust et les `18` niveaux Clippy reprennent la politique partagé
## Adopter le manifest membre ## Adopter le manifest membre
Copier le membre vers `crates/<nom>/Cargo.toml`, adapter `name`, son chemin dans `members` et le header `# file:`. `version.workspace = true`, `edition.workspace = true` et `publish.workspace = true` rendent visibles les héritages choisis ; ajouter séparément `license.workspace = true`, `repository.workspace = true` ou `authors.workspace = true` si les valeurs existent à la racine et concernent cette crate. `[lints] workspace = true` est requis pour reprendre les niveaux du workspace : leur présence à la racine ne suffit pas à les appliquer automatiquement aux membres. Copier le membre vers `crates/<nom>/Cargo.toml`, adapter `name`, son chemin dans `members` et le header `# file:`. Pour un nouveau projet contrôlé, `<nom>` commence par le nom court ou l'abréviation canonique du projet et rend lisibles la responsabilité puis le rôle/cible utiles, conformément à [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). Ne pas conserver `project-core-lib` comme nom réel et ne pas ajouter un suffixe uniquement par symétrie. `version.workspace = true`, `edition.workspace = true` et `publish.workspace = true` rendent visibles les héritages choisis ; ajouter séparément `license.workspace = true`, `repository.workspace = true` ou `authors.workspace = true` si les valeurs existent à la racine et concernent cette crate. `[lints] workspace = true` est requis pour reprendre les niveaux du workspace : leur présence à la racine ne suffit pas à les appliquer automatiquement aux membres.
Le bloc `[dependencies]` vide se remplit selon les besoins de la crate. Pour une dépendance déjà déclarée sous `[workspace.dependencies]`, utiliser localement `nom = { workspace = true }`, avec `features = [...]` au besoin. Pour une dépendance strictement locale, choisir sa contrainte directement dans ce membre ; aucune liste tierce arbitraire n'est copiée par ce modèle. Le bloc `[dependencies]` vide se remplit selon les besoins de la crate. Pour une dépendance déjà déclarée sous `[workspace.dependencies]`, utiliser localement `nom = { workspace = true }`, avec `features = [...]` au besoin. Pour une dépendance strictement locale, choisir sa contrainte directement dans ce membre ; aucune liste tierce arbitraire n'est copiée par ce modèle.

108
history/0.0.5/alpha.7.md Normal file
View File

@@ -0,0 +1,108 @@
<!-- file: history/0.0.5/alpha.7.md -->
<!-- version: 1 -->
# History 0.0.5-alpha.7 — profil Rust strict et nomenclature initiale
## Statut
FAIL
La gate mécanique de `0.0.5-alpha.7` exécutée le `2026-09-25` est propre : tests, audits Markdown, contrôle structurel ciblé et scope Git passent. La revue fonctionnelle opérateur qui suit révèle toutefois que la nomenclature matérialisée reste incomplète : les suffixes de crates ne portent pas encore explicitement leurs contrats architecturaux, la séparation package bibliothèque / package binaire n'est pas cadrée, et l'ownership du logging/tracing n'est pas généralisé alors que KSP et Games fournissent des preuves suffisamment convergentes.
La tranche est donc enregistrée `FAIL` malgré son gate mécanique vert. La correction appartient à `alpha.7.fix.1` ; aucun REPLAN de release n'est nécessaire.
## Baseline et version
La tranche part du commit opérateur de `0.0.5-alpha.6.fix.3` :
```text
4e1c1cd 0.0.5-alpha.6.fix.3
```
Le push vers `origin/master` a réussi avant l'application de `alpha.7`.
La version contrôlée après application est :
```text
0.0.5-alpha.7
```
`history/0.0.5/alpha.6.fix.3.md` est présent avec statut `PASS`, `deltas/0.0.5/alpha.7.md` est présent et `history/0.0.5/alpha.7.md` était absent pendant la gate.
## Validation opérateur observée
L'opérateur a fourni les sorties du `2026-09-25` depuis `~/Projects/pgr`, à `10:47:34`–`11:15:53`.
Les révisions contrôlées sont :
```text
docs/rules/510-RUST_CARGO.md version 5
docs/skeletons/002-RUST_CARGO_WORKSPACE.md version 3
docs/templates/002-CARGO_MANIFESTS.md version 2
docs/studies/001-KSP_GAMES_RECONCILIATION.md version 8
docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md version 9
```
La suite Python globale a exécuté `37` tests, tous réussis :
```text
Ran 37 tests in 0.492s
OK
```
Les audits documentaires sont propres :
```text
Markdown header audit: clean (154 file(s))
Markdown table audit: clean (7 table(s), 154 file(s))
Markdown link audit: clean (150 local link(s), 154 file(s))
```
Le contrôle structurel spécifique affiche :
```text
0.0.5 alpha.7 strict Rust profile audit: clean (explicit paths, crate-root facade, controlled naming, alpha.8 formatting deferred)
```
`git diff --check` et `git diff --cached --check` ne produisent aucun diagnostic.
Le scope Git observé avant ajout du présent history est exactement :
```text
M VERSION
A deltas/0.0.5/alpha.7.md
M docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md
M docs/rules/510-RUST_CARGO.md
M docs/skeletons/002-RUST_CARGO_WORKSPACE.md
M docs/studies/001-KSP_GAMES_RECONCILIATION.md
M docs/templates/002-CARGO_MANIFESTS.md
```
## Écart fonctionnel découvert après gate
La clarification opérateur impose un sens architectural aux noms de crates :
- une crate `-api` doit être un contrat réellement séparé, principalement passif ; elle n'est pas créée si une seule implémentation suffit ;
- une crate `-lib` porte une implémentation/fonctionnalité réutilisable ;
- les exécutables doivent normalement vivre dans des packages séparés et composer les libs au lieu de mélanger binaire et bibliothèque ;
- Tauri constitue l'exception actuelle et doit alors déclarer des targets lib/bin de noms distincts ;
- `tracing` est préféré à `log` pour les diagnostics structurés et un owner transverse de logging doit éviter la duplication de subscriber/sinks/lifecycle dans les workspaces multi-runtime.
La relecture des corpus confirme ce besoin. KSP encode déjà la séparation `-api` / `-lib`, interdit les APIs créées par symétrie et centralise le tracing dans `ksp-logging-lib`. Games sépare ses launchers de ses libs et centralise également la configuration tracing. Une ancienne préférence KSP pour un package worker mixte lib/bin est explicitement rejetée comme règle PGR générale au profit de la clarification actuelle.
## Résultat
`alpha.7` a correctement rétabli le profil Rust strict sur les chemins, imports, façade et contrôle de flux, mais son contrat de nomenclature/packaging reste incomplet. La correction est bornée et n'affecte pas la trajectoire `alpha.8` formatage puis `alpha.9` skeleton Tauri.
## Transition
Appliquer le présent history puis committer et pousser `0.0.5-alpha.7`.
La tranche suivante est :
```text
0.0.5-alpha.7.fix.1
```
Elle complète uniquement les contrats de suffixes, la séparation lib/bin, l'ownership du tracing et l'exception Tauri. Les règles de blocs/espacement/ordre restent hors scope jusqu'à `alpha.8`.