142 lines
7.7 KiB
Markdown
142 lines
7.7 KiB
Markdown
<!-- file: docs/validation/001-VALIDATION_GATES.md -->
|
||
<!-- version: 11 -->
|
||
|
||
# Gates de validation
|
||
|
||
## Responsabilité
|
||
|
||
Les audits Python peuvent être exécutés pendant la préparation d'un delta. Sauf demande explicite contraire, les commandes Cargo finales sont exécutées par l'utilisateur sur le workspace local.
|
||
|
||
Le générateur ne marque jamais une commande Cargo comme propre s'il ne dispose que du résultat d'un delta antérieur.
|
||
|
||
## Gate normale d’un delta Rust
|
||
|
||
Lorsqu’un delta modifie du code Rust, la validation commence par un formatage mutatif volontaire :
|
||
|
||
```bash
|
||
cargo fmt --all
|
||
cargo fmt --all -- --check
|
||
```
|
||
|
||
Les modifications exclusivement produites par `cargo fmt --all` n’imposent pas d’incrémenter `// version: N`, car elles font partie de la préparation du même état avant commit.
|
||
|
||
Les audits et gates de compilation restent ensuite :
|
||
|
||
```bash
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||
```
|
||
|
||
Les tests sont ciblés par défaut :
|
||
|
||
```bash
|
||
cargo test -p <crate-affectée> --all-targets --all-features
|
||
```
|
||
|
||
Le fichier delta énumère les crates à tester. `cargo test --workspace --all-targets --all-features` n’est demandé systématiquement qu’au démarrage d’une nouvelle version `X.Y.Z`, vers la fin d’une phase/version, après un changement transversal important ou lorsque l’impact réel ne permet pas de sélectionner avec confiance les tests ciblés.
|
||
|
||
## Smokes Desktop
|
||
|
||
Lorsqu'un delta modifie la boucle exécutable, le runtime ou le comportement visible des runners Desktop, exécuter également :
|
||
|
||
```bash
|
||
cargo run -p game-reflex-poc-desktop
|
||
cargo run -p game-snake-poc-desktop
|
||
```
|
||
|
||
Les smokes `cargo run` ne remplacent pas la gate de tests.
|
||
|
||
## Transition vers le delta suivant
|
||
|
||
Si toutes les commandes demandées sont propres, le delta courant est validé et le travail peut passer automatiquement au prochain delta de la roadmap, sauf avis contraire de l'utilisateur.
|
||
|
||
Si une commande échoue, ne pas avancer de prerelease. Produire un correctif du delta courant, par exemple `0.1.0-0-pre.3.fix.1`, puis rejouer la gate demandée.
|
||
|
||
## Android et Web
|
||
|
||
Le build Android SDL3 historique n'est pas encore une gate : le projet Gradle exécutable et l'intégration SDL3/NDK restent planifiés pour une prerelease dédiée. Dès leur introduction, les tâches ciblées par module sont documentées avant d'être rendues obligatoires.
|
||
|
||
Le host Tauri Android Snake possède en revanche une gate réelle à partir de `0.3.1-0-pre.2`. Pour Tauri 2.11.x, les commandes Android utilisent le projet `gen/android` généré par la CLI officielle, sans patch local. La baseline de validation est JDK 17 avec Gradle `8.14.3` et AGP `8.11.0`. Si `gen/android` provient d'une tentative de migration différente, le supprimer puis rejouer `cargo tauri android init` sous JDK 17 avant le smoke `cargo tauri android dev`.
|
||
|
||
Sur AVD, le smoke peut utiliser le forwarding ADB géré automatiquement par Tauri. Sur appareil physique, la gate de référence utilise un tunnel USB explicite sur le port unique `1436` afin d'éviter de dépendre du LAN et de transporter à la fois HTTP et HMR :
|
||
|
||
```bash
|
||
adb -s <serial> reverse --remove-all
|
||
adb -s <serial> reverse tcp:1436 tcp:1436
|
||
(cd crates/apps/game-snake-poc-tauri && cargo tauri android dev --host 127.0.0.1)
|
||
```
|
||
|
||
La validation réelle de `0-pre.4` a confirmé le chemin ARM64 `aarch64-linux-android`. Un premier smoke a observé un abort natif lors du Back/teardown WebView ; après correction du tunnel HMR dans `0-pre.4.fix.1`, un nouveau smoke ARM64 n'a pas reproduit cet abort et est allé jusqu'au détachement de la fenêtre. Le risque reste à revalider sur l'APK autonome beta et ne doit pas être masqué par une modification du scaffold `gen/android`.
|
||
|
||
Le host navigateur direct Snake possède désormais une gate réelle. Lorsqu'il est touché, construire d'abord l'adapter WASM et ses bindings hors dépôt, puis le frontend :
|
||
|
||
```bash
|
||
cargo build -p game-snake-poc-wasm --target wasm32-unknown-unknown
|
||
wasm-bindgen ../builds/sasedev-games/target/wasm32-unknown-unknown/debug/game_snake_poc_wasm.wasm \
|
||
--target web \
|
||
--out-dir ../builds/sasedev-games/game-snake-poc-web/wasm \
|
||
--out-name game_snake_poc_wasm
|
||
cd Web/game-snake-poc
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
Le smoke direct utilise ensuite `npm run dev` et `http://127.0.0.1:1434/main.html`. Pour le POC Snake feature-complete, vérifier aussi : assets `common` + `game` chargés avant le statut `Prêt`, provenance `Web/Wasm/Browser` visible et mise à jour par l'input, pause sans rattrapage lors d'un masquage d'onglet, reprise propre, resize sans tick artificiel, SimpleBar, clavier et contrôles pointer/tactiles.
|
||
|
||
Si une future tranche touche de nouveau la frontière plateforme du bridge WASM, exécuter également `cargo test -p engine-v1-platform-api`, `cargo test -p game-snake-poc-wasm`, puis un smoke `cargo run -p game-snake-poc-desktop` pour confirmer la non-régression SDL3. Les frontends Tauri restent pilotés par leurs hooks Tauri et ne reprennent pas cette gate manuelle.
|
||
|
||
## Gate beta du POC Snake Tauri Android
|
||
|
||
À l'entrée en `0.3.1-2-beta.1`, la gate ajoute la suite Cargo workspace complète et un packaging Android autonome aux audits/check/Clippy habituels :
|
||
|
||
```bash
|
||
cargo test --workspace --all-targets --all-features
|
||
|
||
export JAVA_HOME=/usr/lib/jvm/temurin-17-jdk-amd64
|
||
(cd crates/apps/game-snake-poc-tauri && npm install)
|
||
(cd crates/apps/game-snake-poc-tauri && \
|
||
cargo tauri android build --debug --apk --target aarch64 --target x86_64)
|
||
```
|
||
|
||
Le hook Tauri `beforeBuildCommand` possède le build WASM release, `wasm-bindgen`, TypeScript et Vite ; `npm run build` n'est donc pas une gate manuelle. Le build beta vise un APK Debug contenant `arm64-v8a` et `x86_64`; aucun AAB n'est requis à ce jalon.
|
||
|
||
Après packaging, utiliser le chemin d'APK affiché par Tauri, vérifier son contenu ABI, puis installer le même package sur l'AVD x86_64 et l'appareil ARM64 réel :
|
||
|
||
```bash
|
||
unzip -l <apk> | grep -E 'lib/(arm64-v8a|x86_64)/libgame_snake_poc_tauri_lib\.so'
|
||
adb -s <serial> install -r <apk>
|
||
adb -s <serial> shell am start -n com.sasedev.games.snake.tauri/.MainActivity
|
||
```
|
||
|
||
Le smoke autonome vérifie Canvas, assets, WASM, input, provenance, background/foreground, reprise sans rattrapage, resize/rotation si disponible et plusieurs sorties Back. Il ne doit utiliser ni serveur Vite ni `adb reverse`.
|
||
|
||
## Gate beta du POC Snake Web
|
||
|
||
À l’entrée en `2-beta.1`, le scope `0.3.0` est feature-complete. La gate de frontière de phase ajoute aux audits/check/Clippy la suite Cargo workspace complète :
|
||
|
||
```bash
|
||
cargo test --workspace --all-targets --all-features
|
||
```
|
||
|
||
Le témoin Desktop Snake est construit et fumé en release :
|
||
|
||
```bash
|
||
cargo build -p game-snake-poc-desktop --release
|
||
../builds/sasedev-games/target/release/game-snake-poc-desktop
|
||
```
|
||
|
||
Le host Web beta utilise également un module WASM release avant le build Vite :
|
||
|
||
```bash
|
||
cargo build -p game-snake-poc-wasm --release --target wasm32-unknown-unknown
|
||
wasm-bindgen ../builds/sasedev-games/target/wasm32-unknown-unknown/release/game_snake_poc_wasm.wasm \
|
||
--target web \
|
||
--out-dir ../builds/sasedev-games/game-snake-poc-web/wasm \
|
||
--out-name game_snake_poc_wasm
|
||
(cd Web/game-snake-poc && npm install && npm run build && npm run preview)
|
||
```
|
||
|
||
Le smoke production ouvre `http://127.0.0.1:4174/main.html` et vérifie les mêmes contrats fonctionnels que le smoke `vite dev` : Canvas, inputs, SimpleBar, assets, provenance, lifecycle et resize. Le smoke `vite dev` déjà validé reste utile après un correctif touchant le plugin de dev, mais n’est pas requis à chaque beta si aucun chemin dev n’a changé.
|