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

0.1.1-alpha.2

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 10:18:43 +02:00
parent 7b7565d5d4
commit dc63b543ac
13 changed files with 691 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/rules/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/000-README.md -->
<!-- version: 14 -->
<!-- version: 15 -->
# Index des règles PGR
@@ -20,6 +20,10 @@ Les règles générales actuellement nécessaires restent dans `RULES.md`. La fa
- [`500-LANGUAGES.md`](500-LANGUAGES.md) — contrat commun des profils langage/écosystème et de leurs spécialisations de build.
- [`510-RUST_CARGO.md`](510-RUST_CARGO.md) — profil Rust/Cargo et règles réutilisables propres à cet écosystème.
- [`520-JAVA_MAVEN_GRADLE.md`](520-JAVA_MAVEN_GRADLE.md) — profil Java et spécialisations de build Maven/Gradle.
- [`530-TYPESCRIPT.md`](530-TYPESCRIPT.md) — profil TypeScript, recommandation pour les frontends contrôlés, type-check et frontières typées.
- [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md) — package manager, `package.json`, dépendances, scripts et responsabilité du lockfile.
- [`550-VITE.md`](550-VITE.md) — profil Vite, build tool/dev server recommandé et ownership de son cache et de ses outputs.
- [`560-CSS_SASS.md`](560-CSS_SASS.md) — profil CSS/Sass, styles sources, prétraitement conditionnel et intégration de dépendances de styles.
- [`600-PLATFORMS.md`](600-PLATFORMS.md) — contrat commun des profils plateforme.
- [`610-ANDROID.md`](610-ANDROID.md) — profil plateforme Android et règles réutilisables de compatibilité, packaging et validation.
- [`700-FRAMEWORKS.md`](700-FRAMEWORKS.md) — contrat commun des profils framework et de leur composition avec les owners déjà applicables.

50
docs/rules/530-TYPESCRIPT.md Normal file
View File

@@ -0,0 +1,50 @@
<!-- file: docs/rules/530-TYPESCRIPT.md -->
<!-- version: 1 -->
# Profil TypeScript
## Rôle et applicabilité
Ce profil possède les règles réutilisables propres à TypeScript lorsqu'un projet sélectionne TypeScript pour du code frontend ou un autre package JavaScript typé.
Il complète [`500-LANGUAGES.md`](500-LANGUAGES.md). Il ne possède ni le package manager, ni `package.json`, ni le bundler/dev server, ni la chaîne CSS/Sass, ni le host natif ou navigateur.
Le profil s'applique lorsqu'une partie du source contrôlé est écrite en TypeScript ou lorsque la validation du projet inclut explicitement la toolchain TypeScript.
## Recommandation pour les projets contrôlés
Pour un frontend que l'organisation contrôle, TypeScript **SHOULD** être préféré à du JavaScript non typé dès que le frontend porte une logique durable non triviale.
Cette préférence n'est pas une obligation universelle. Du JavaScript direct MAY rester approprié pour un artefact très petit, un script isolé, une contrainte externe ou un environnement où l'introduction de TypeScript n'apporte pas une valeur proportionnée.
La justification de la recommandation est fonctionnelle : TypeScript ajoute une vérification statique avant exécution et permet de détecter une partie des incohérences de types pendant la validation plutôt qu'au runtime.
## Frontières typées avec d'autres écosystèmes
TypeScript facilite également les frontières où des types doivent être partagés avec un autre langage ou runtime.
Lorsqu'un projet Rust expose des DTO, structures ou énumérations destinés au frontend et qu'un générateur de bindings tel que TS-RS est applicable, la génération de déclarations TypeScript depuis la source de vérité Rust SHOULD être préférée à la duplication manuelle des mêmes contrats.
Cette recommandation ne transforme pas TS-RS en dépendance générale de TypeScript. L'owner Rust, le framework ou le sous-système qui possède la frontière décide si cette génération est requise. Le profil Tauri peut notamment renforcer ce contrat dans son propre scope.
## Configuration et validation
`tsconfig.json`, les options de compilation/type-check, les fichiers inclus/exclus et la commande TypeScript canonique appartiennent à ce profil.
`0.1.1-alpha.2` fixe uniquement cette frontière d'ownership. Les defaults réutilisables, templates éventuels et gates TypeScript détaillés sont traités par `alpha.3` après validation du présent découpage.
Un build Vite, Tauri ou autre ne remplace pas automatiquement une preuve TypeScript ciblée lorsqu'une propriété de typage doit être validée indépendamment.
## Ce que le profil n'impose pas
Ce profil ne rend obligatoire :
- ni Vite ;
- ni npm ou un autre package manager particulier ;
- ni Sass ou un framework CSS ;
- ni TS-RS pour un projet qui ne partage aucun contrat avec Rust ;
- ni un framework frontend particulier ;
- ni WASM ;
- ni Tauri.
Les choix correspondants restent possédés par leurs owners applicables.

46
docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md Normal file
View File

@@ -0,0 +1,46 @@
<!-- file: docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md -->
<!-- version: 1 -->
# Profil écosystème de packages JavaScript
## Rôle et applicabilité
Ce profil possède le contrat réutilisable d'un package JavaScript/TypeScript utilisant un manifest `package.json` et un package manager compatible avec cet écosystème.
Il complète [`500-LANGUAGES.md`](500-LANGUAGES.md) et reste indépendant du choix entre JavaScript et TypeScript, du bundler, du framework frontend, de Sass et du host.
## Package manager
PGR MUST NOT imposer npm uniquement parce qu'il est utilisé par un corpus source.
Le projet MUST sélectionner explicitement le package manager qu'il utilise lorsque plusieurs outils sont possibles. npm, pnpm, yarn, Bun ou une autre solution compatible MAY être retenus si le besoin et la toolchain du projet le justifient.
Les commandes opérateur et CI doivent utiliser le package manager réellement sélectionné par le projet ; un exemple PGR ne doit pas transformer sa propre syntaxe en obligation universelle.
## Manifest et scripts
`package.json` appartient à cet owner lorsqu'il décrit le package frontend ou JavaScript/TypeScript concerné.
Les scripts du manifest doivent représenter des responsabilités utiles du package. Un script MAY orchestrer plusieurs outils, mais sa présence ne transfère pas l'ownership de TypeScript, Vite, Sass, WASM ou Tauri vers le package manager.
Les champs de version restent classifiés selon la gouvernance PGR et le rôle du package ; un package privé appartenant au même release train et un package publié indépendamment n'ont pas nécessairement la même politique.
## Dépendances et sorties téléchargées
Les dépendances téléchargées telles que `node_modules/` sont des artefacts reproductibles et SHOULD rester hors du source control.
Un package tiers peut exposer des entrypoints JavaScript, CSS, Sass ou d'autres assets. Leur utilisation active les owners correspondants selon le besoin réel du projet ; elle ne fait pas du package manager le propriétaire de leur configuration.
## Lockfile
La politique du lockfile MUST être explicitement décidée selon le rôle du package, la reproductibilité recherchée, les contraintes de publication et le package manager sélectionné.
`0.1.1-alpha.2` fixe cette responsabilité mais ne choisit pas encore une règle universelle de versionnement/ignorance. La politique détaillée est traitée par `alpha.3`.
L'absence de lockfile dans Games reste donc une décision locale à classifier, pas une règle PGR générale.
## Validation
Le parsing du manifest, l'installation/résolution de dépendances et les scripts du package manager sont des preuves distinctes. Leur sélection reste proportionnée au scope conformément à [`400-VALIDATION.md`](400-VALIDATION.md).
`alpha.3` précisera les artefacts/templates et la gate générique sans imposer un package manager particulier.

54
docs/rules/550-VITE.md Normal file
View File

@@ -0,0 +1,54 @@
<!-- file: docs/rules/550-VITE.md -->
<!-- version: 1 -->
# Profil Vite
## Rôle et applicabilité
Ce profil possède les règles réutilisables propres à Vite lorsqu'il est sélectionné comme build tool et dev server d'un frontend.
Vite est traité comme une spécialisation de build de l'écosystème frontend au sein de la famille [`500-LANGUAGES.md`](500-LANGUAGES.md), pas comme le propriétaire de TypeScript, Sass/CSS, du package manager, du framework UI ou du host Tauri.
Le profil s'applique uniquement lorsqu'un projet utilise réellement Vite.
## Recommandation pour les projets contrôlés
Pour un frontend moderne que l'organisation contrôle et dont les besoins sont compatibles, Vite **SHOULD** être le build tool/dev server privilégié.
Cette recommandation n'est pas une obligation. Un autre bundler, dev server ou build tool MAY être choisi lorsque ses capacités, les contraintes d'un framework, l'environnement cible ou le coût de migration le justifient mieux.
Le simple fait qu'un projet Web existe ne rend donc pas ce profil applicable automatiquement.
## Ownership
Lorsque Vite est sélectionné, cet owner possède notamment :
- `vite.config.ts` ou une configuration Vite équivalente ;
- la racine frontend présentée à Vite ;
- le dev server et son contrat de lancement ;
- le cache Vite ;
- les outputs du build Vite ;
- la copie/transformation d'assets configurée par Vite ou ses plugins ;
- les paramètres Vite nécessaires à l'intégration avec un host, sans posséder le host lui-même.
Les ports, hosts réseau, aliases, plugins et conventions de nommage d'assets restent des décisions locales tant qu'aucune règle plus générale n'est démontrée.
## Sources, cache et outputs
Les sources frontend versionnées, le cache de développement et les outputs de production sont des catégories différentes.
Le cache et les sorties de build reproductibles SHOULD rester hors Git. Pour les projets contrôlés, ils SHOULD être placés hors de l'arborescence source lorsque cela reste simple, reproductible et compatible avec la toolchain ; sinon ils doivent au minimum être ignorés explicitement.
Le détail du contrat `root`, `cacheDir`, `outDir`, assets et dev server est réservé à `0.1.1-alpha.4`.
## Validation
Une validation Vite ciblée prouve le contrat de build/dev tool de Vite ; elle ne remplace pas automatiquement :
- le type-check TypeScript ;
- une compilation Sass spécifique lorsqu'elle est indépendante ;
- le smoke navigateur requis par un comportement observable ;
- la validation du host Tauri ;
- une génération WASM possédée par un autre owner.
`alpha.4` précisera les commandes et artefacts génériques applicables.

44
docs/rules/560-CSS_SASS.md Normal file
View File

@@ -0,0 +1,44 @@
<!-- file: docs/rules/560-CSS_SASS.md -->
<!-- version: 1 -->
# Profil CSS et Sass
## Rôle et applicabilité
Ce profil possède les règles réutilisables de la chaîne de styles frontend : sources CSS, prétraitement Sass lorsqu'il est sélectionné, dépendances de styles et classification des CSS générées.
Il complète [`500-LANGUAGES.md`](500-LANGUAGES.md). Il ne rend aucun framework CSS particulier obligatoire et ne possède ni Vite, ni le package manager, ni le host.
## CSS comme baseline
Un frontend Web peut utiliser directement CSS sans préprocesseur. Sass n'est donc jamais activé par la simple présence de fichiers CSS.
Les styles sources intentionnels sont versionnés ; les CSS produits uniquement par compilation à partir de sources Sass sont des artefacts générés et SHOULD rester hors du source control sauf besoin explicite de distribution ou de publication.
## Recommandation Sass pour les projets contrôlés
Pour un frontend contrôlé dont la chaîne de styles est non triviale, Sass **SHOULD** être préféré lorsqu'il apporte une valeur claire de composition, factorisation ou configuration.
Cette recommandation est particulièrement forte lorsqu'une dépendance installée par le package manager expose un entrypoint Sass/SCSS, des variables configurables, maps, mixins, fonctions ou modules permettant de personnaliser la bibliothèque à la compilation sans modifier ses sources.
Bootstrap constitue un exemple concret de cette catégorie : ses sources Sass permettent de sélectionner des parties de la bibliothèque et de surcharger des variables. Cette observation n'en fait pas une dépendance PGR universelle.
Un frontend petit, un smoke minimal ou un projet dont les besoins sont couverts proprement par CSS MAY rester sans Sass.
## Modules Sass et compatibilité
Pour du nouveau code contrôlé, le système de modules Sass moderne (`@use` / `@forward`) SHOULD être préféré lorsque les dépendances et la toolchain le permettent.
L'ancien `@import` Sass est déprécié dans Dart Sass. Il MAY toutefois rester nécessaire à titre de compatibilité lorsqu'une bibliothèque tierce, une version existante ou sa documentation l'impose encore. PGR ne doit pas forcer une migration syntaxique qui casse une dépendance supportée.
## Frameworks CSS
Bootstrap, Tailwind CSS ou une autre bibliothèque de présentation restent des décisions de skeleton/projet ou d'un futur owner spécifique si un contrat réutilisable distinct apparaît.
Le profil CSS/Sass possède uniquement la façon de traiter leurs sources/styles lorsqu'elles passent par CSS ou Sass ; il ne choisit pas la bibliothèque à la place du projet.
## Validation
La compilation Sass et la validation du CSS produit sont distinctes du type-check TypeScript, du build Vite et du smoke navigateur.
`0.1.1-alpha.5` précisera les gates de styles et leur intégration à la validation frontend indépendante du host.

8
docs/rules/710-TAURI.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/710-TAURI.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Profil Tauri 2
@@ -29,7 +29,9 @@ PGR MUST NOT imposer universellement Vite, TypeScript, Sass, Bootstrap, Tailwind
Le frontend possède ses propres règles et peut être sélectionné par une skeleton specification ou par la baseline locale du projet. Le profil Tauri possède seulement le contrat d'intégration entre ce frontend et le host natif.
Pour les projets que l'organisation contrôle entièrement, une skeleton MAY choisir une stack frontend par défaut et un layout stable. Cette décision appartient au skeleton et aux futurs profils Web applicables, pas au présent owner Tauri.
Les owners frontend matérialisés par `0.1.1` sont [`530-TYPESCRIPT.md`](530-TYPESCRIPT.md), [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md), [`550-VITE.md`](550-VITE.md) et [`560-CSS_SASS.md`](560-CSS_SASS.md). Ils s'appliquent uniquement lorsque les technologies correspondantes sont réellement sélectionnées.
Pour les projets que l'organisation contrôle entièrement, une skeleton MAY choisir une stack frontend par défaut et un layout stable. Cette décision appartient au skeleton et aux profils Web applicables, pas au présent owner Tauri.
## WASM
@@ -86,7 +88,7 @@ Lorsque le workspace possède une crate de logging/tracing commune, le host Taur
Lorsque le frontend sélectionné est TypeScript, les structures, énumérations et DTO Rust **possédés par le host** et partagés avec le frontend MUST utiliser TS-RS comme source de génération dans le profil strict, sauf incompatibilité technique explicitement documentée. Le contrat Rust reste la source de vérité ; les bindings générés ne sont pas modifiés manuellement et SHOULD rester hors Git lorsqu'ils sont entièrement reproductibles. Le skeleton MAY normaliser leur sortie sous `frontend/ts/bindings/`.
Pour les projets contrôlés, `frontend/` est le répertoire recommandé pour les sources Web versionnées. Vite + TypeScript + Sass constitue la stack candidate par défaut et Bootstrap est la baseline de présentation privilégiée lorsque le projet a besoin d'un framework CSS généraliste. Tailwind CSS n'est pas interdit par le profil Tauri, mais il n'est pas le choix PGR par défaut et son adoption demande une décision explicite du projet. Ces choix restent possédés par le futur skeleton et les profils Web correspondants.
Pour les projets contrôlés, `frontend/` est le répertoire recommandé pour les sources Web versionnées. TypeScript et Vite sont fortement recommandés mais restent des `SHOULD`, jamais des obligations universelles. Sass est également fortement recommandé lorsque la chaîne de styles est non triviale ou qu'une dépendance expose des sources Sass/SCSS configurables ; il reste optionnel pour un frontend qui n'en tire pas de valeur. Bootstrap est la baseline de présentation privilégiée lorsque le futur skeleton choisit un framework CSS généraliste, mais il ne devient pas une dépendance Tauri ou Web universelle. Tailwind CSS n'est pas interdit ; son adoption reste une décision explicite du projet. Les règles correspondantes appartiennent aux profils `530`, `550` et `560`, puis au futur skeleton lorsqu'il choisira effectivement cette composition.
L'intégration d'un plugin SHOULD préférer les étapes explicites décrites par sa documentation — dépendance Cargo, initialisation Rust, package frontend et capabilities nécessaires — afin que chaque modification reste visible et revue. `cargo tauri add` MAY être utilisé lorsque ce raccourci apporte une vraie valeur, mais il n'est pas la voie canonique imposée aux projets contrôlés.