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

0.1.1-alpha.5

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 11:43:09 +02:00
parent 89b8ea88c1
commit 55c6f7b05d
12 changed files with 885 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/validation/005-WEB_FRONTEND_VALIDATION.md Normal file
View File

@@ -0,0 +1,128 @@
<!-- file: docs/validation/005-WEB_FRONTEND_VALIDATION.md -->
<!-- version: 1 -->
# Validation frontend Web indépendante du host
## Objet
Ce document décrit une validation réutilisable pour un frontend Web composé à partir des owners TypeScript/package/Vite/CSS-Sass de PGR.
Il complète [`../rules/400-VALIDATION.md`](../rules/400-VALIDATION.md). Il n'ajoute aucune gate au dépôt PGR lui-même, qui ne contient pas de frontend exécutable. Il sert aux projets destinataires et aux dry-runs de skeletons lorsqu'un frontend réel est présent.
## Principe d'indépendance
Le frontend **SHOULD** être validable indépendamment du host autant que son graphe réel le permet.
Un résultat frontend `PASS` prouve uniquement les propriétés frontend sélectionnées. Il ne vaut pas `PASS` Tauri, Android, WASM, backend ou deployment.
Inversement, un échec du host ne doit pas être requalifié en échec TypeScript/Vite/Sass lorsque la gate frontend indépendante est déjà propre et que le défaut appartient clairement à l'intégration du host.
Une dépendance d'entrée réellement générée par un autre owner reste un prérequis explicite. PGR ne doit pas prétendre à une indépendance complète lorsque le build frontend consomme effectivement un artefact externe absent.
## Couches de preuve
Une gate frontend sélectionne uniquement les couches applicables :
```text
1. restauration reproductible des dépendances
2. type-check TypeScript
3. compilation/transformation des styles si distincte
4. build frontend de production
5. inspection ciblée des outputs si nécessaire
6. preview / smoke navigateur si une propriété runtime le justifie
7. validation du host séparée
```
Ces étapes décrivent des responsabilités, pas une liste obligatoire de commandes.
## Restauration des dépendances
Si le package possède un lockfile versionné, CI et les gates reproductibles **SHOULD** utiliser le mode frozen/immutable/clean-install équivalent du package manager sélectionné.
PGR MUST NOT imposer `npm ci` à un projet pnpm, Yarn ou autre. La commande appartient au package manager réel.
Une tranche purement documentaire ou une preuve qui n'a pas besoin de résoudre les dépendances MAY réutiliser une installation déjà autorisée si les règles locales de reproductibilité le permettent.
## Type-check
Lorsqu'un frontend sélectionne le profil TypeScript `530`, le script canonique `typecheck` **SHOULD** rester directement exécutable.
La preuve conceptuelle est :
```text
<package-manager> run typecheck
```
La syntaxe exacte dépend de l'outil sélectionné.
Si le script `build` exécute déjà exactement le même type-check, la matrice locale MAY éviter une exécution redondante lorsque cette composition est stable et visible. Pour une séparation de diagnostic plus claire, exécuter `typecheck` puis `build` reste préférable lorsque le coût est faible.
## Styles
Si Sass/CSS est transformé à l'intérieur du build frontend, le build réussi MAY constituer la preuve de compilation des styles.
Une compilation Sass autonome, un linter CSS/Sass ou une publication de package de styles reçoit une gate séparée uniquement si elle possède un contrat distinct.
PGR SHOULD NOT lancer deux compilations équivalentes uniquement pour augmenter le nombre de checks.
## Build de production
Lorsqu'un bundler tel que Vite est sélectionné, un changement qui touche ses entrées, sa configuration ou ses outputs **SHOULD** exécuter le build de production réel :
```text
<package-manager> run build
```
La réussite du build prouve la capacité du frontend à produire ses outputs avec le graphe courant. Elle ne prouve pas automatiquement le comportement dans un navigateur ni le fonctionnement du host.
Un contrôle ciblé MAY vérifier l'existence ou l'emplacement d'un output critique lorsque cette propriété n'est pas déjà garantie de façon suffisante par le build.
## Preview et smoke navigateur
Un smoke navigateur n'est requis que lorsqu'une propriété importante ne peut pas être prouvée utilement par type-check/build seuls, par exemple :
- chargement réel de l'entrypoint ;
- résolution d'assets ou de `base` ;
- comportement runtime critique ;
- connexion à un service local de test ;
- intégration navigateur spécifique.
Avec Vite, `preview` MAY servir à exposer localement le build pour ce smoke. `preview` n'est pas un serveur de production.
Un smoke **SHOULD** rester court, déterministe autant que possible et centré sur la propriété qui justifie son existence.
## Host séparé
Un host tel que Tauri peut déclencher le dev/build frontend via ses hooks, mais ce couplage ne transfère pas l'ownership de la validation frontend au host.
La matrice locale **SHOULD** conserver au minimum une voie permettant d'exécuter les preuves frontend pertinentes sans lancer l'ensemble du host, lorsque la topologie réelle du projet le permet.
Ensuite seulement, une gate d'intégration du host vérifie la composition : hooks, chemins, artefacts attendus, capacités natives, packaging ou comportement end-to-end selon le framework.
## Matrice minimale adaptable
Exemple de classification, à adapter au projet :
```text
restore reproductible | lockfile versionné | package manager | mode frozen/immutable/clean-install
type-check | TypeScript sélectionné | TypeScript | script typecheck
styles | compilation distincte du build | Sass/CSS toolchain | commande officielle ciblée
build | bundler sélectionné | Vite ou alternative | script build
browser smoke | comportement runtime à prouver | navigateur / harness | smoke court
host integration | host présent | Tauri ou autre host | gate du host
```
Le projet peut fusionner deux lignes uniquement lorsque la même commande prouve réellement les deux contrats et que cette composition reste explicite.
## Validation d'un skeleton Web
Une instanciation temporaire du skeleton Web MAY être utilisée pour vérifier :
- que les fichiers copiés/adaptés sont parsables ;
- que le package manager et les versions sélectionnés résolvent réellement ;
- que `typecheck` passe ;
- que le build sélectionné produit les outputs attendus ;
- que les styles choisis compilent ;
- qu'aucune validation du host n'est nécessaire pour ces preuves frontend.
Cette preuve de toolchain doit utiliser les outils officiels réels. Un audit Python statique ne remplace pas TypeScript, Vite ou Sass pour les propriétés qu'ils possèdent.