diff --git a/RULES.md b/RULES.md index 40f117d..8d1aa8f 100644 --- a/RULES.md +++ b/RULES.md @@ -1,5 +1,5 @@ - + # Index normatif Project Governance Rules @@ -83,6 +83,10 @@ Familles actuellement actives : - [`docs/rules/500-LANGUAGES.md`](docs/rules/500-LANGUAGES.md) — contrat commun des profils langage, écosystème et spécialisations de build associées. - [`docs/rules/510-RUST_CARGO.md`](docs/rules/510-RUST_CARGO.md) — profil Rust/Cargo : workspace, manifests, dépendances, lints, API, formatage, tests et validation spécialisée. - [`docs/rules/520-JAVA_MAVEN_GRADLE.md`](docs/rules/520-JAVA_MAVEN_GRADLE.md) — profil Java et spécialisations Maven/Gradle : toolchain LTS, structure, dépendances, tests et validation de build. +- [`docs/rules/530-TYPESCRIPT.md`](docs/rules/530-TYPESCRIPT.md) — profil TypeScript : recommandation contrôlée, type-check et frontières typées. +- [`docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md) — manifest `package.json`, sélection du package manager, dépendances et responsabilité du lockfile. +- [`docs/rules/550-VITE.md`](docs/rules/550-VITE.md) — profil Vite : build tool/dev server recommandé, cache, outputs et frontière avec le host. +- [`docs/rules/560-CSS_SASS.md`](docs/rules/560-CSS_SASS.md) — profil CSS/Sass : styles sources, prétraitement optionnel recommandé et dépendances de styles. - [`docs/rules/600-PLATFORMS.md`](docs/rules/600-PLATFORMS.md) — contrat commun des profils plateforme et de leur compatibilité de target/runtime. - [`docs/rules/610-ANDROID.md`](docs/rules/610-ANDROID.md) — profil Android : structure, toolchain/SDK, compatibilité, packaging, configuration locale et validation plateforme. - [`docs/rules/700-FRAMEWORKS.md`](docs/rules/700-FRAMEWORKS.md) — contrat commun des profils framework et de leur orchestration avec langages, plateformes et outils de build. diff --git a/VERSION b/VERSION index faefa00..e374f3c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.1-alpha.1 +0.1.1-alpha.2 diff --git a/deltas/0.1.1/alpha.2.md b/deltas/0.1.1/alpha.2.md new file mode 100644 index 0000000..f92e314 --- /dev/null +++ b/deltas/0.1.1/alpha.2.md @@ -0,0 +1,269 @@ + + + +# Delta 0.1.1-alpha.2 — frontières d'ownership frontend Web + +## Baseline et version + +Baseline attendue : commit opérateur de `0.1.1-alpha.1`, réalisé après application de `history/0.1.1/alpha.1.md` avec statut `PASS`. + +Le hash de ce commit n'est pas anticipé. + +Version avant application : + +```text +0.1.1-alpha.1 +``` + +Version après application : + +```text +0.1.1-alpha.2 +``` + +## Objet + +Matérialiser les frontières d'ownership frontend nécessaires avant d'écrire les configurations détaillées de `alpha.3` à `alpha.5`. + +La tranche crée quatre profils indépendants dans la famille `500` : + +```text +530 TypeScript +540 JavaScript package ecosystem +550 Vite +560 CSS / Sass +``` + +Elle inscrit également les trois préférences validées pendant la revue de `alpha.1` : TypeScript, Vite et Sass sont fortement recommandés dans leurs scopes applicables pour les nouveaux frontends contrôlés, donc exprimés en `SHOULD`, mais aucun n'est une obligation universelle. + +La tranche ne crée encore aucun template `package.json`, `tsconfig.json` ou `vite.config.ts`, aucun skeleton Web, aucun audit frontend et aucune politique finale de lockfile. Ces responsabilités restent prévues dans les tranches suivantes. + +## Scope + +REPLACE : + +```text +VERSION +RULES.md +docs/000-README.md +docs/architecture/003-RULE_PROFILE_MODEL.md +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +docs/rules/000-README.md +docs/rules/710-TAURI.md +``` + +ADD : + +```text +deltas/0.1.1/alpha.2.md +docs/rules/530-TYPESCRIPT.md +docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +docs/rules/550-VITE.md +docs/rules/560-CSS_SASS.md +``` + +DELETE : aucun. + +`ROADMAP.md`, `CHANGELOG.md`, les templates, skeletons, scripts, tests, validations et studies restent inchangés. + +Aucun `history/0.1.1/alpha.2.md` n'est anticipé. + +## Décisions normatives + +### TypeScript + +Pour un frontend contrôlé portant une logique durable non triviale, TypeScript `SHOULD` être préféré au JavaScript non typé. Du JavaScript direct reste valide lorsqu'il est plus proportionné. + +Le type-check TypeScript et la génération éventuelle de bindings depuis une autre source de vérité sont des responsabilités distinctes du bundler. TS-RS reste un outil de frontière Rust/TypeScript lorsqu'un owner plus spécifique l'exige ; il n'est pas une dépendance TypeScript universelle. + +### Écosystème de package + +`package.json`, le package manager concret, les scripts de package, les dépendances téléchargées et la décision de lockfile appartiennent au profil `540`. + +PGR MUST NOT imposer npm par défaut. La politique du lockfile sera définie en `alpha.3` à partir du rôle du package et de la reproductibilité recherchée, pas à partir de l'absence de lockfile observée dans Games. + +### Vite + +Pour un frontend contrôlé compatible avec ses capacités, Vite `SHOULD` être le build tool/dev server privilégié. Une alternative justifiée reste permise. + +Le profil Vite possède sa configuration, son cache et ses outputs ; il ne possède ni TypeScript, ni Sass/CSS, ni le package manager, ni Tauri, ni WASM. + +### CSS / Sass + +CSS direct reste une baseline valide. Sass `SHOULD` être préféré lorsqu'une chaîne de styles non triviale ou une dépendance Sass/SCSS configurable en tire une valeur claire. + +Bootstrap est un exemple réel de bibliothèque pouvant être personnalisée à partir de ses sources Sass et de variables/maps ; il reste un choix de skeleton/projet, pas une dépendance Web universelle. + +Pour du nouveau code Sass, `@use` / `@forward` SHOULD être préférés lorsque compatibles. `@import` MAY rester utilisé pour la compatibilité avec des dépendances existantes qui l'exigent. + +## Classification Games de cadrage + +La classification préparatoire est inscrite dans le plan : + +```text +TypeScript durable ADOPT +Vite ADOPT +package.json ADOPT +npm concret KEEP-LOCAL +lockfiles Games KEEP-LOCAL jusqu'à décision alpha.3 +Sass ADOPT quand applicable +Bootstrap KEEP-LOCAL +frontend/ layout KEEP-LOCAL / candidat skeleton +ports / aliases / plugins KEEP-LOCAL +WASM dans scripts DEFER +``` + +Aucun `OVERRIDE` n'est nécessaire avant l'adoption réelle de Games en `0.1.5`. + +## Validation opérateur + +Après application du history `PASS`, commit/push de `alpha.1`, puis application du présent delta : + +```bash +test "$(cat VERSION)" = '0.1.1-alpha.2' +git cat-file -e HEAD:history/0.1.1/alpha.1.md +test -f history/0.1.1/alpha.1.md +test -f deltas/0.1.1/alpha.2.md +test ! -e history/0.1.1/alpha.2.md + +for path in docs/rules/530-TYPESCRIPT.md docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md docs/rules/550-VITE.md docs/rules/560-CSS_SASS.md; do + test -f "$path" +done + +grep -A2 '^## Statut$' history/0.1.1/alpha.1.md | grep -Fx 'PASS' +grep -Fx '' RULES.md +grep -Fx '' docs/000-README.md +grep -Fx '' docs/architecture/003-RULE_PROFILE_MODEL.md +grep -Fx '' docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +grep -Fx '' docs/rules/000-README.md +grep -Fx '' docs/rules/710-TAURI.md + +python3 -B -m unittest discover -s tests -v + +python3 -B scripts/audit_markdown_headers.py README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_links.py README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts + +python3 -B - <<'PYGATE' +from pathlib import Path +import re + +history = Path('history/0.1.1/alpha.1.md').read_text(encoding='utf-8') +assert re.search(r'## Statut\s+PASS\s', history) + +expected = { + '530-TYPESCRIPT.md': ( + 'TypeScript **SHOULD** être préféré', + 'TS-RS', + 'ni Vite', + ), + '540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md': ( + 'MUST NOT imposer npm', + 'Lockfile', + 'alpha.3', + ), + '550-VITE.md': ( + 'Vite **SHOULD** être le build tool/dev server privilégié', + 'Le profil s'applique uniquement lorsqu'un projet utilise réellement Vite.', + 'alpha.4', + ), + '560-CSS_SASS.md': ( + 'Sass **SHOULD** être préféré', + 'Bootstrap constitue un exemple concret', + '`@use` / `@forward`', + '`@import` Sass est déprécié', + 'alpha.5', + ), +} +for name, phrases in expected.items(): + text = Path('docs/rules', name).read_text(encoding='utf-8') + for phrase in phrases: + assert phrase in text, (name, phrase) + +rules = Path('RULES.md').read_text(encoding='utf-8') +rules_index = Path('docs/rules/000-README.md').read_text(encoding='utf-8') +architecture = Path('docs/architecture/003-RULE_PROFILE_MODEL.md').read_text(encoding='utf-8') +tauri = Path('docs/rules/710-TAURI.md').read_text(encoding='utf-8') +plan = Path('docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md').read_text(encoding='utf-8') +roadmap = Path('ROADMAP.md').read_text(encoding='utf-8') + +for owner in ('530-TYPESCRIPT.md', '540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md', '550-VITE.md', '560-CSS_SASS.md'): + assert owner in rules + assert owner in rules_index + +for phrase in ( + '530 — TypeScript', + '540 — JavaScript package ecosystem', + '550 — Vite', + '560 — CSS / Sass', + 'Un frontend minimal peut n'en sélectionner qu'une partie.', +): + assert phrase in architecture, phrase + +for phrase in ( + 'TypeScript et Vite sont fortement recommandés mais restent des `SHOULD`', + 'Sass est également fortement recommandé', + 'profils `530`, `550` et `560`', +): + assert phrase in tauri, phrase + +for phrase in ( + 'Décisions de revue après `alpha.1`', + '**TypeScript** : fortement recommandé', + '**Vite** : fortement recommandé', + '**Sass** : fortement recommandé', + '`@use` / `@forward`', + '| TypeScript pour les frontends durables | `ADOPT` |', + '| npm comme package manager concret | `KEEP-LOCAL` |', + '| commandes/génération WASM dans les scripts | `DEFER` |', +): + assert phrase in plan, phrase + +assert '0.1.8' not in roadmap +assert 'skeleton Tauri avant owners Web suffisants' in roadmap + +print('0.1.1 alpha.2 ownership audit: clean (530/540/550/560 independent, SHOULD recommendations explicit, Games classified)') +PYGATE + +git diff --check +git add VERSION RULES.md docs/000-README.md docs/architecture/003-RULE_PROFILE_MODEL.md docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md docs/rules/000-README.md docs/rules/710-TAURI.md docs/rules/530-TYPESCRIPT.md docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md docs/rules/550-VITE.md docs/rules/560-CSS_SASS.md deltas/0.1.1/alpha.2.md +git diff --cached --check +git status --short +``` + +Le scope indexé attendu avant ajout du history est : + +```text +M RULES.md +M VERSION +A deltas/0.1.1/alpha.2.md +M docs/000-README.md +M docs/architecture/003-RULE_PROFILE_MODEL.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/000-README.md +A docs/rules/530-TYPESCRIPT.md +A docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +A docs/rules/550-VITE.md +A docs/rules/560-CSS_SASS.md +M docs/rules/710-TAURI.md +``` + +La revue qualitative doit confirmer que : + +- `SHOULD` représente bien « fortement recommandé » et qu'aucun des profils `530`, `550`, `560` n'est activé universellement ; +- TypeScript n'est pas rendu dépendant de Rust ou TS-RS ; +- Vite est recommandé sans interdire un autre build tool ; +- Sass est recommandé conditionnellement et CSS direct reste valide ; +- Bootstrap reste un exemple/choix de skeleton, pas une dépendance universelle ; +- npm et la politique Games des lockfiles restent non généralisés ; +- WASM, serveur Rust et skeleton Tauri restent hors scope de la tranche. + +## Transition + +### PASS + +Produire `history/0.1.1/alpha.2.md`, puis préparer `0.1.1-alpha.3` consacré aux règles et artefacts TypeScript + écosystème de package : `tsconfig`, manifest, scripts utiles, sélection du package manager et politique du lockfile. + +### FAIL + +Consigner le diagnostic réel dans `history/0.1.1/alpha.2.md` et rester dans `alpha.2.fix.N` sauf REPLAN justifié. Le fix MUST rester borné au défaut d'ownership ou de formulation observé. diff --git a/docs/000-README.md b/docs/000-README.md index 2e66034..52ebc2b 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation PGR @@ -23,6 +23,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr ## Points d'entrée de 0.1.1 - [`plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md`](plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md) — plan actif de la fondation frontend Web contrôlée, de l'audit des corpus à la séparation TypeScript/Vite/styles/package/validation. +- [`rules/530-TYPESCRIPT.md`](rules/530-TYPESCRIPT.md), [`rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md), [`rules/550-VITE.md`](rules/550-VITE.md) et [`rules/560-CSS_SASS.md`](rules/560-CSS_SASS.md) — owners frontend matérialisés par `0.1.1-alpha.2`, séparant langage typé, écosystème de package, build tool et styles. - [`studies/002-TAURI_SKELETON_DECISION.md`](studies/002-TAURI_SKELETON_DECISION.md) — décision `DEFER` dont `0.1.1` doit satisfaire les prérequis Web sans créer ni autoriser automatiquement le skeleton Tauri. - [`studies/003-V0_1_0_HORIZON_REVIEW.md`](studies/003-V0_1_0_HORIZON_REVIEW.md) — revue ayant engagé `0.1.1` à `0.1.7` et maintenu WASM, serveur Rust et deployment sans réservation prématurée. - [`../prompts/007-V0_1_1_START_PROMPT.md`](../prompts/007-V0_1_1_START_PROMPT.md) — contrat de reprise autoritaire de la release `0.1.1`. diff --git a/docs/architecture/003-RULE_PROFILE_MODEL.md b/docs/architecture/003-RULE_PROFILE_MODEL.md index 17132a4..7b5a3f8 100644 --- a/docs/architecture/003-RULE_PROFILE_MODEL.md +++ b/docs/architecture/003-RULE_PROFILE_MODEL.md @@ -1,5 +1,5 @@ - + # Modèle de profils de règles PGR @@ -214,6 +214,38 @@ La famille `800 — architecture` reste réservée : aucune règle nouvelle n'en La réconciliation a également confirmé qu'une règle générale ne doit pas être recopiée comme si le profil spécifique en devenait propriétaire. Un profil peut rappeler une conséquence spécifique au contexte, mais doit référencer l'owner général lorsque le contrat lui-même n'est pas spécialisé. +## Owners frontend matérialisés en `0.1.1` + +L'audit Games/KSP et la revue opérateur de `0.1.1-alpha.1` justifient quatre owners distincts dans la famille `500` : + +```text +530 — TypeScript +540 — JavaScript package ecosystem +550 — Vite +560 — CSS / Sass +``` + +Cette séparation évite un profil monolithique « Web moderne » : TypeScript, Vite et Sass sont des recommandations fortes pour les nouveaux frontends contrôlés lorsqu'ils apportent une valeur proportionnée, mais chacun reste sélectionnable indépendamment. Le package manager est également indépendant et PGR n'impose pas npm. + +Une composition complète peut par exemple être : + +```text +GENERAL ++ 500 ++ 530 TypeScript ++ 540 JavaScript package ecosystem ++ 550 Vite ++ 560 CSS / Sass +``` + +Un frontend minimal peut n'en sélectionner qu'une partie. Un host Tauri qui utilise cette stack ajoute ensuite `700 + 710` sans transférer à Tauri l'ownership des règles frontend : + +```text +GENERAL + 500 + 510 + 530 + 540 + 550 + 560 + 700 + 710 +``` + +WASM et serveur Web Rust restent des responsabilités séparées et ne sont pas activés par cette composition. + ## Instanciation par skeleton Les skeleton specifications sélectionnent les profils applicables et identifient les règles à reprendre ou adapter dans la baseline locale du projet créé. Leur contrat transversal de composition appartient à [`../rules/220-SKELETONS.md`](../rules/220-SKELETONS.md) ; le présent document reste propriétaire de la hiérarchie et de la résolution des profils eux-mêmes. diff --git a/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md b/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md index 1d7a37e..2dc4ea8 100644 --- a/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +++ b/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan 0.1.1 — fondation frontend Web contrôlée @@ -235,6 +235,46 @@ Cette répétition confirme que les owners TypeScript/Vite/Sass/CSS sont bien tr Aucune autre règle KSP n'est importée dans `0.1.1-alpha.1`. +## Décisions de revue après `alpha.1` + +La gate opérateur de `alpha.1` est `PASS` : `48/48` tests, audits Markdown propres et scope Git conforme. Aucun fix de cadrage n'est nécessaire. + +La revue ajoute trois préférences explicites à traduire avec la force normative `SHOULD` : + +- **TypeScript** : fortement recommandé pour les frontends contrôlés, mais non obligatoire. Sa valeur attendue est le type-check statique avant exécution/génération du JavaScript et la possibilité de partager des contrats typés avec d'autres écosystèmes ; lorsqu'une frontière Rust existe, des générateurs comme TS-RS peuvent éviter la duplication manuelle des DTO. +- **Vite** : fortement recommandé comme build tool/dev server des frontends contrôlés lorsque ses capacités correspondent au besoin, mais non obligatoire. Une alternative justifiée reste valide. +- **Sass** : fortement recommandé pour les chaînes de styles non triviales, en particulier lorsqu'une dépendance installée via l'écosystème de packages expose un entrypoint Sass/SCSS, des variables, maps, mixins ou autres points de configuration permettant d'adapter la bibliothèque sans modifier ses sources. Sass reste optionnel pour un frontend simple. + +Bootstrap constitue un exemple réel de dépendance offrant une chaîne Sass personnalisable ; il ne devient pas pour autant une dépendance PGR universelle. Pour du nouveau code Sass, `@use` / `@forward` est préféré lorsque compatible ; `@import` reste toléré pour les bibliothèques existantes qui l'exigent encore. + +`alpha.2` matérialise donc quatre owners séparés dans la famille `500` : + +```text +530 TypeScript +540 JavaScript package ecosystem +550 Vite +560 CSS / Sass +``` + +Cette granularité conserve l'indépendance d'applicabilité : un projet peut utiliser TypeScript sans Vite, Vite avec JavaScript, CSS sans Sass, ou un package manager sans aucune des trois autres briques. + +### Classification initiale des choix Games + +| Choix Games | Classification pour l'adoption future | Motif | +|--------------------------------------------|-------------------------------------------------|----------------------------------------------------------------| +| TypeScript pour les frontends durables | `ADOPT` | déjà exercé et conforme à la préférence PGR `SHOULD` | +| Vite comme build tool/dev server | `ADOPT` | déjà exercé ; reste remplaçable par une alternative justifiée | +| `package.json` comme manifest frontend | `ADOPT` | owner générique nécessaire | +| npm comme package manager concret | `KEEP-LOCAL` | PGR ne rend pas npm universel | +| absence/versionnement des lockfiles Games | `KEEP-LOCAL` en attente de `alpha.3` | ne pas généraliser le corpus historique | +| Sass dans `game-snake-poc` | `ADOPT` lorsque la chaîne de styles le justifie | capacité recommandée, applicabilité conditionnelle | +| Bootstrap | `KEEP-LOCAL` | choix de présentation/skeleton, pas règle Web universelle | +| `frontend/` comme layout | `KEEP-LOCAL` / candidat skeleton | ne pas transformer un layout observé en règle de langage/build | +| ports, aliases et plugins Vite | `KEEP-LOCAL` | valeurs propres au host/projet | +| commandes/génération WASM dans les scripts | `DEFER` | futur owner WASM séparé | + +Aucun `OVERRIDE` n'est nécessaire à ce stade : Games n'est pas encore gouverné par ces nouveaux profils et sera réellement mappé pendant `0.1.5`. + ## Mission de `0.1.1` `0.1.1` doit produire la première fondation frontend Web contrôlée de PGR à partir des responsabilités réellement exercées, sans créer un catalogue théorique de technologies Web. @@ -296,9 +336,9 @@ Auditer `v0.1.0`, `publish.001`, Games `0.3.6`, les décisions Tauri/horizon, pu ### alpha.2 — frontières d'ownership Web -Décider la composition minimale des owners nécessaires à TypeScript, package manager/manifest, Vite et styles. Matérialiser uniquement les familles/profils dont l'ownership est suffisamment prouvé. +Décider et matérialiser la composition minimale des owners nécessaires à TypeScript, package manager/manifest, Vite et styles. La décision retenue est `530 / 540 / 550 / 560`, quatre profils indépendants de la famille `500`. -Cette tranche doit aussi classifier explicitement les choix Games selon `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` sans migrer Games. +La tranche inscrit les recommandations `SHOULD` TypeScript/Vite/Sass sans les transformer en `MUST`, puis classifie explicitement les choix Games selon `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` sans migrer Games. Les détails de configuration restent dans les tranches spécialisées suivantes. ### alpha.3 — TypeScript et écosystème de package diff --git a/docs/rules/000-README.md b/docs/rules/000-README.md index 621cc0e..40e669a 100644 --- a/docs/rules/000-README.md +++ b/docs/rules/000-README.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/rules/530-TYPESCRIPT.md b/docs/rules/530-TYPESCRIPT.md new file mode 100644 index 0000000..f26543e --- /dev/null +++ b/docs/rules/530-TYPESCRIPT.md @@ -0,0 +1,50 @@ + + + +# 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. diff --git a/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md b/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md new file mode 100644 index 0000000..1e4c17b --- /dev/null +++ b/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md @@ -0,0 +1,46 @@ + + + +# 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. diff --git a/docs/rules/550-VITE.md b/docs/rules/550-VITE.md new file mode 100644 index 0000000..a1e8f40 --- /dev/null +++ b/docs/rules/550-VITE.md @@ -0,0 +1,54 @@ + + + +# 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. diff --git a/docs/rules/560-CSS_SASS.md b/docs/rules/560-CSS_SASS.md new file mode 100644 index 0000000..d40c3a8 --- /dev/null +++ b/docs/rules/560-CSS_SASS.md @@ -0,0 +1,44 @@ + + + +# 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. diff --git a/docs/rules/710-TAURI.md b/docs/rules/710-TAURI.md index 761711e..95293d3 100644 --- a/docs/rules/710-TAURI.md +++ b/docs/rules/710-TAURI.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/history/0.1.1/alpha.2.md b/history/0.1.1/alpha.2.md new file mode 100644 index 0000000..f9460e7 --- /dev/null +++ b/history/0.1.1/alpha.2.md @@ -0,0 +1,134 @@ + + + +# History 0.1.1-alpha.2 — frontières d'ownership Web + +## Statut + +FAIL + +La gate opérateur de `0.1.1-alpha.2` exécutée le `2026-09-27` n'a pas atteint un PASS complet. + +Le contenu attendu de la tranche a été appliqué, la tranche précédente `alpha.1` est bien enregistrée `PASS`, les `48` tests Python ont réussi et les trois audits Markdown sont propres. Le contrôle spécifique d'ownership Web n'a toutefois pas pu s'exécuter : un littéral Python entouré de quotes simples contient l'apostrophe de `s'applique`, ce qui provoque un `SyntaxError`. + +Aucun défaut normatif des profils Web livrés par `alpha.2` n'est établi par les preuves disponibles. Le défaut appartient à la gate de validation elle-même. + +## Baseline opérateur + +`0.1.1-alpha.1` a été clôturée avec son history `PASS`, puis committée et poussée avant application de `alpha.2` : + +```text +commit 7b7565d +message 0.1.1-alpha.1 +push origin/master PASS +``` + +Après application de `alpha.2`, les contrôles initiaux ont confirmé : + +```text +VERSION 0.1.1-alpha.2 +history/0.1.1/alpha.1.md présent dans HEAD +deltas/0.1.1/alpha.2.md présent +history/0.1.1/alpha.2.md absent pendant la gate +docs/rules/530-TYPESCRIPT.md présent +docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md présent +docs/rules/550-VITE.md présent +docs/rules/560-CSS_SASS.md présent +RULES.md version 13 +docs/000-README.md version 25 +docs/architecture/003-RULE_PROFILE_MODEL.md version 6 +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md version 2 +docs/rules/000-README.md version 15 +docs/rules/710-TAURI.md version 6 +``` + +## Défaut exact de la gate + +Le delta contenait dans son bloc Python : + +```python +'Le profil s'applique uniquement lorsqu'un projet utilise réellement Vite.' +``` + +La chaîne étant entourée de quotes simples, l'apostrophe de `s'applique` termine le littéral prématurément. Python a donc arrêté le contrôle avec : + +```text +File "", line 20 + 'Le profil s'applique uniquement lorsqu'un projet utilise réellement Vite.', + ^^^^^^^^^^^^^^^^^^^^^ +SyntaxError: invalid syntax. Perhaps you forgot a comma? +``` + +Le message final attendu : + +```text +0.1.1 alpha.2 ownership audit: clean (...) +``` + +n'a donc pas été produit. + +## Preuves réussies malgré le défaut + +La suite Python globale a exécuté `48` tests et tous ont réussi : + +```text +Ran 48 tests in 0.738s + +OK +``` + +Les audits Markdown ont affiché : + +```text +Markdown header audit: clean (206 file(s)) +Markdown table audit: clean (9 table(s), 206 file(s)) +Markdown link audit: clean (219 local link(s), 206 file(s)) +``` + +Le scope Git observé avant ajout du présent history est exactement : + +```text +M RULES.md +M VERSION +A deltas/0.1.1/alpha.2.md +M docs/000-README.md +M docs/architecture/003-RULE_PROFILE_MODEL.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/000-README.md +A docs/rules/530-TYPESCRIPT.md +A docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +A docs/rules/550-VITE.md +A docs/rules/560-CSS_SASS.md +M docs/rules/710-TAURI.md +``` + +Ce scope correspond aux fichiers annoncés par `alpha.2`. + +## Décision + +Aucun REPLAN n'est requis. La tranche reste conceptuellement bornée aux frontières d'ownership Web et aux préférences `SHOULD` déjà livrées. + +La correction autorisée est : + +```text +0.1.1-alpha.2.fix.1 +``` + +Le fix doit : + +- conserver intégralement `deltas/0.1.1/alpha.2.md` comme snapshot historique ; +- conserver `RULES.md`, `docs/000-README.md`, `docs/architecture/003-RULE_PROFILE_MODEL.md`, `docs/rules/000-README.md`, `docs/rules/710-TAURI.md` et les profils `530/540/550/560` inchangés ; +- remplacer uniquement les littéraux Python fragiles dans la nouvelle gate par une forme syntaxiquement sûre ; +- reconfirmer le `FAIL` historique de `alpha.2` et le contenu déjà livré ; +- exécuter à nouveau les `48` tests et les trois audits Markdown ; +- vérifier que le scope du fix reste limité à `VERSION`, au plan actif et au nouveau delta de correction. + +## Résultat + +`0.1.1-alpha.2` est enregistré `FAIL` pour défaut de syntaxe dans sa gate opérateur, sans défaut normatif établi sur les nouveaux owners Web. + +La seule transition autorisée est : + +```text +0.1.1-alpha.2.fix.1 +```