0.0.3-alpha.4

docs/plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Plan 0.0.3 — templates initiaux et audits réutilisables
 
@@ -15,7 +15,7 @@ La source autoritaire est l'archive Gitea fournie `pgr-v0.0.2.zip`, issue selon
 
 Le rapport séparé `pgr-0.0.2-publish.001-report.md` indique `PASS` et donne le même hash. Il atteste la publication post-tag sans appartenir au tag. L'archive sans `.git` ne peut prouver indépendamment le commit ni l'identité du tag ; ces éléments sont les déclarations et preuves de publication de l'opérateur.
 
-Le contrat de démarrage est `prompts/003-V0_0_3_START_PROMPT.md`. Les règles applicables partent de `RULES.md`, puis des familles `200`, `210`, `300`, `400`, du modèle de profils `003` et des profils `500`/`510`, `520`, `600`/`610` selon leur scope. PGR reste un dépôt documentaire avec deux utilitaires Python ; les toolchains Rust, Java et Android ne deviennent pas des prérequis du dépôt.
+Le contrat de démarrage est `prompts/003-V0_0_3_START_PROMPT.md`. Les règles applicables partent de `RULES.md`, puis des familles `200`, `210`, `300`, `400`, du modèle de profils `003` et des profils `500`/`510`, `520`, `600`/`610` selon leur scope. PGR reste un dépôt documentaire doté d'outils Python ; les toolchains Rust, Java et Android ne deviennent pas des prérequis du dépôt.
 
 Deux corpus de comparaison supplémentaires, fournis après le gate initial de `alpha.1`, ont été inspectés pour ce fix documentaire :
 
@@ -60,7 +60,7 @@ Les deux `rustfmt.toml` ont un contenu technique identique et seulement un numé
 
 ### Retenu : famille Rust/Cargo minimale
 
-Le besoin concret n'est pas limité à `rustfmt.toml`. La première famille doit couvrir quatre responsabilités distinctes :
+Le besoin concret n'est pas limité à `rustfmt.toml`. La première famille doit couvrir cinq responsabilités distinctes :
 
 1. `rustfmt.toml` : options communes dont la valeur est justifiée ; alignement de `edition` avec le projet destinataire ; ne pas reprendre mécaniquement chaque préférence des deux sources ;
 2. configuration Clippy : niveaux de lint Rust/Clippy dans les sections Cargo `[workspace.lints.rust]` et `[workspace.lints.clippy]`, plus `clippy.toml` pour les seuils et réglages conservés dans le profil de départ éprouvé ; chaque projet peut adapter ces choix ;

docs/templates/001-RUST_CARGO_TOOLING.md

@@ -1,5 +1,5 @@
 <!-- file: docs/templates/001-RUST_CARGO_TOOLING.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Templates d'outillage Rust/Cargo
 
@@ -11,7 +11,7 @@ Ces trois fichiers fournissent une baseline de configuration issue des conventio
 - [`clippy.toml`](../../templates/rust-cargo/clippy.toml) — paramètres de lints (seuils, exceptions de tests, identifiants courts) issus du noyau partagé des deux projets ;
 - [`.cargo/config.toml`](../../templates/rust-cargo/.cargo/config.toml) — emplacements des artefacts Cargo hors de la racine source.
 
-Les niveaux `deny`, `allow`, `warn` et `forbid` des lints Rust/Clippy appartiennent au `Cargo.toml` du workspace, selon [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). `clippy.toml` règle des paramètres de lints, pas leur niveau. Les modèles de manifests racine et membre, ainsi que l'héritage `[lints] workspace = true`, sont prévus en `alpha.4` après l'extraction des audits de style de `alpha.3`.
+Les niveaux `deny`, `allow`, `warn` et `forbid` des lints Rust/Clippy appartiennent au `Cargo.toml` du workspace, selon [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). `clippy.toml` règle des paramètres de lints, pas leur niveau. Les deux modèles Cargo et l'héritage `[lints] workspace = true` sont documentés dans [`002-CARGO_MANIFESTS.md`](002-CARGO_MANIFESTS.md).
 
 ## Copier et adapter
 

docs/templates/002-CARGO_MANIFESTS.md

@@ -0,0 +1,47 @@
+<!-- file: docs/templates/002-CARGO_MANIFESTS.md -->
+<!-- version: 1 -->
+
+# Modèles de manifests Cargo workspace et crate membre
+
+## Rôle des deux fichiers
+
+Le [manifest racine](../../templates/rust-cargo/Cargo.toml) est celui d'un workspace virtuel à une unité de release ; le [manifest membre](../../templates/rust-cargo/crates/project-core-lib/Cargo.toml) montre une crate bibliothèque ordinaire. Les deux fichiers forment un exemple TOML syntaxiquement valide. Après copie dans un nouveau projet, il faut aussi fournir le code source de la crate avant de demander à Cargo de la compiler. Le dépôt PGR ne devient pas lui-même un workspace Cargo.
+
+Ces modèles prolongent les trois configurations de [`001-RUST_CARGO_TOOLING.md`](001-RUST_CARGO_TOOLING.md). Le propriétaire des choix normatifs reste [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). Les chemins `project-core-lib`, le nom du package et la version `0.1.0` sont des **valeurs d'exemple à remplacer** : cette version ne reflète pas `VERSION` de PGR et ne définit pas la version d'un autre projet.
+
+## Adopter le manifest racine
+
+Copier `templates/rust-cargo/Cargo.toml` vers `Cargo.toml` du projet, corriger son header `# file:` et commencer sa propre révision de fichier à `1`. Adapter `members` aux répertoires qui existent effectivement, puis choisir la version canonique de l'unité de release. Lorsque toutes les crates partagent une seule release, aligner `[workspace.package].version` sur le `VERSION` de ce projet ; plusieurs unités de release indépendantes ne doivent pas hériter d'une version fictive commune.
+
+L'édition `2024` et `resolver = "3"` sont cohérents avec l'exemple [`rustfmt.toml`](../../templates/rust-cargo/rustfmt.toml). Pour un workspace virtuel, fixer explicitement le resolver souhaité ; adapter ensemble l'édition, Rustfmt et la toolchain compatible si le projet prend d'autres valeurs. `publish = false` est un défaut prudent pour cet exemple ; définir la politique de publication réelle avant de publier une crate.
+
+`license`, `repository` et `authors` ne sont volontairement pas renseignés avec des identités fictives. Si ces métadonnées ont une valeur vraie et commune, les déclarer dans `[workspace.package]` et les hériter explicitement dans chaque crate concernée, par exemple `license.workspace = true` seulement après avoir déclaré `license` à la racine. Ne pas imposer un auteur, une licence ou une URL propres à KSP/Games.
+
+Le bloc `[workspace.dependencies]` est vide tant qu'aucune dépendance concrète ne sert plusieurs crates. Déclarer à la racine seulement les contraintes et features réellement communes ; les features propres à un membre sont activées sur sa dépendance locale. Cargo ajoute les features demandées au membre à celles déjà sélectionnées au workspace ; éviter d'activer globalement une feature de test ou de plateforme par facilité. Les dépendances de test appartiennent à `[dev-dependencies]` du membre qui les utilise.
+
+Les trois lints Rust et les `18` niveaux Clippy reprennent la politique partagée observée dans KSP et Games. Les `allow` retiennent leurs choix de style explicite, notamment `needless_return` malgré `implicit_return = "deny"`, et évitent qu'un lint de suggestion réécrive systématiquement ce style. Réviser leur pertinence pour le projet avant adoption. Les seuils et réglages supplémentaires appartiennent au [`clippy.toml`](../../templates/rust-cargo/clippy.toml) distinct : ce fichier ne définit aucun niveau de lint.
+
+## 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.
+
+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.
+
+Une application binaire peut reprendre les mêmes héritages après adaptation du nom, du layout et de sa cible `src/main.rs` ; ne pas fabriquer un deuxième manifest quasi identique. Une crate à version ou politique de publication réellement indépendante doit déclarer ses valeurs locales et ne plus hériter ces champs par automatisme.
+
+## Exception locale de lints
+
+Une frontière FFI peut avoir besoin de `unsafe_code = "allow"` dans une crate particulière, comme l'entrée Android observée dans Games. Cette exception demande justification, portée étroite et validation du code `unsafe` concerné. Cargo ne permet pas de combiner `workspace = true` avec des définitions de lints locaux dans le même manifest membre : retirer l'héritage `[lints]` pour cette crate et déclarer localement `[lints.rust]` ainsi que `[lints.clippy]`, en recopiant les niveaux partagés réellement conservés puis en ajustant seulement l'exception motivée. Les autres membres continuent d'hériter des lints racine.
+
+## Vérification dans le projet destinataire
+
+Après avoir ajouté le code source nécessaire, vérifier d'abord la résolution des manifests et les héritages, puis les contrôles réellement applicables :
+
+```bash
+cargo metadata --format-version 1 --no-deps
+cargo fmt --all -- --check
+cargo check --workspace
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Vérifier séparément le cas d'une crate à lints locaux lorsque le projet comporte réellement une exception. `Cargo.lock` et les artefacts créés par ces commandes suivent la politique du projet et la configuration Cargo de [`001-RUST_CARGO_TOOLING.md`](001-RUST_CARGO_TOOLING.md).