101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
<!-- file: docs/validation/004-RUST_CARGO_BASELINE_DRY_RUN.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Dry-run de baseline Rust/Cargo
|
||
|
||
## Rôle
|
||
|
||
Ce contrat vérifie que la fondation PGR, le skeleton Rust/Cargo et les cinq templates techniques peuvent être utilisés sans dépendre de KSP ou Games.
|
||
|
||
Il possède deux modes distincts :
|
||
|
||
```text
|
||
NEW nouveau projet : instanciation temporaire réelle des templates
|
||
ADOPTION projet existant : comparaison et mapping non destructifs
|
||
```
|
||
|
||
Le dry-run n’est ni un générateur de projet permanent ni une nouvelle architecture applicative. Les répertoires temporaires sont supprimés après la preuve.
|
||
|
||
## Owners exercés
|
||
|
||
Le chemin `NEW` compose :
|
||
|
||
```text
|
||
001-PROJECT_GOVERNANCE_FOUNDATION
|
||
002-RUST_CARGO_WORKSPACE
|
||
500-LANGUAGES
|
||
510-RUST_CARGO
|
||
001-RUST_CARGO_TOOLING
|
||
002-CARGO_MANIFESTS
|
||
```
|
||
|
||
Le chemin `ADOPTION` ajoute [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md) et traite `001` / `002` comme checklists de comparaison plutôt que comme recettes de remplacement.
|
||
|
||
## Mode NEW — nouveau workspace
|
||
|
||
La preuve temporaire SHOULD :
|
||
|
||
1. copier les cinq artefacts de `templates/rust-cargo/` dans un répertoire temporaire ;
|
||
2. remplacer `project-name`, `project-core-lib`, le membre workspace et la version d’exemple par des valeurs propres au dry-run ;
|
||
3. créer uniquement le `src/lib.rs` minimal nécessaire à Cargo ;
|
||
4. vérifier qu’aucun placeholder PGR ne reste dans les fichiers adoptés ;
|
||
5. parser les manifests/configurations TOML avec un parseur fiable ;
|
||
6. lorsque Cargo est disponible, exécuter au minimum :
|
||
|
||
```bash
|
||
cargo metadata --format-version 1 --no-deps
|
||
cargo fmt --all -- --check
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||
```
|
||
|
||
Le code source temporaire ne devient pas un template PGR. Son seul rôle est de permettre à la toolchain officielle de vérifier les manifests et l’outillage copiés.
|
||
|
||
## Mode ADOPTION — workspace existant
|
||
|
||
La preuve d’adoption MUST partir d’un état local qui ne correspond pas byte-for-byte aux templates PGR. Elle doit démontrer au minimum un mapping contenant plusieurs décisions, par exemple :
|
||
|
||
```text
|
||
510-RUST_CARGO ADOPT
|
||
rustfmt.max_width local KEEP-LOCAL
|
||
configuration d’artefacts PGR DEFER
|
||
audit de façade strict DEFER
|
||
```
|
||
|
||
Le dry-run MUST vérifier que les fichiers classés `KEEP-LOCAL` ou `DEFER` restent inchangés. Une adoption n’est pas prouvée en recopiant les templates puis en déclarant que le projet existant était compatible.
|
||
|
||
Lorsque la toolchain est disponible, le workspace existant synthétique ou réel SHOULD rester valide avant et après le mapping : `cargo metadata`, `cargo fmt -- --check`, `cargo check` et, lorsque pertinent, `cargo clippy` restent les preuves autoritaires des contrats Cargo/Rust.
|
||
|
||
## Prévalidation sans Cargo
|
||
|
||
Un environnement disposant de Python mais pas de Cargo MAY prévalider :
|
||
|
||
- syntaxe TOML avec `tomllib` ou un parseur équivalent ;
|
||
- résolution des placeholders attendus ;
|
||
- cohérence des liens entre skeletons, templates et owners ;
|
||
- caractère non destructif du mapping d’adoption ;
|
||
- absence de dépendance à KSP/Games dans les artefacts copiables.
|
||
|
||
Cette prévalidation ne constitue pas un `PASS` de la toolchain. Lorsqu’une tranche exige le mode `NEW` complet, l’absence de Cargo conduit à `BLOCKED` ou à une preuve explicitement incomplète, jamais à un faux succès.
|
||
|
||
## Critères de sortie
|
||
|
||
Le dry-run est réussi lorsque :
|
||
|
||
```text
|
||
NEW
|
||
- templates adaptés sans placeholder résiduel ;
|
||
- TOML valide ;
|
||
- toolchain Rust/Cargo sélectionnée réussie ;
|
||
- aucun artefact temporaire n’entre dans le dépôt PGR.
|
||
|
||
ADOPTION
|
||
- baseline locale explicitement distincte ;
|
||
- mapping ADOPT / KEEP-LOCAL / OVERRIDE / DEFER valide ;
|
||
- fichiers KEEP-LOCAL / DEFER préservés ;
|
||
- toolchain locale toujours valide lorsque cette preuve est applicable ;
|
||
- aucun historique n’est réécrit.
|
||
```
|
||
|
||
Le résultat de release reste possédé par le history de la tranche qui exécute cette preuve.
|