0.1.1-alpha.5
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: README.md -->
|
||||
<!-- version: 17 -->
|
||||
<!-- version: 18 -->
|
||||
|
||||
# Project Governance Rules
|
||||
|
||||
@@ -35,6 +35,7 @@ La version courante est définie par [`VERSION`](VERSION). La release `0.0.1` é
|
||||
- [`docs/skeletons/000-README.md`](docs/skeletons/000-README.md) — index des skeleton specifications et de leur contrat de composition ;
|
||||
- [`docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md`](docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md) — fondation composable de gouvernance locale pour un projet adoptant PGR ;
|
||||
- [`docs/skeletons/002-RUST_CARGO_WORKSPACE.md`](docs/skeletons/002-RUST_CARGO_WORKSPACE.md) — specialization composable pour un workspace Rust/Cargo gouverné ;
|
||||
- [`docs/skeletons/003-WEB_FRONTEND.md`](docs/skeletons/003-WEB_FRONTEND.md) — specialization composable pour un frontend Web contrôlé, avec TypeScript/Vite recommandés, Sass optionnel et validation indépendante du host ;
|
||||
- [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation.
|
||||
|
||||
## Langue et nomenclature
|
||||
|
||||
325
deltas/0.1.1/alpha.5.md
Normal file
325
deltas/0.1.1/alpha.5.md
Normal file
@@ -0,0 +1,325 @@
|
||||
<!-- file: deltas/0.1.1/alpha.5.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.1-alpha.5 — CSS/Sass, validation frontend et skeleton Web
|
||||
|
||||
## Baseline et version
|
||||
|
||||
Baseline attendue : commit opérateur de `0.1.1-alpha.4`, réalisé après application de `history/0.1.1/alpha.4.md` avec statut `PASS`.
|
||||
|
||||
Le hash de ce commit n'est pas anticipé.
|
||||
|
||||
Version avant application :
|
||||
|
||||
```text
|
||||
0.1.1-alpha.4
|
||||
```
|
||||
|
||||
Version après application :
|
||||
|
||||
```text
|
||||
0.1.1-alpha.5
|
||||
```
|
||||
|
||||
## Objet
|
||||
|
||||
Compléter l'owner `560-CSS_SASS.md`, définir une validation frontend réutilisable indépendante du host et matérialiser un skeleton Web uniquement parce que les owners `530/540/550/560` sont désormais suffisamment séparés et actionnables.
|
||||
|
||||
La tranche conserve les décisions suivantes :
|
||||
|
||||
- CSS reste valide sans Sass ;
|
||||
- Sass reste optionnel mais recommandé (`SHOULD`) lorsqu'il apporte une valeur réelle ;
|
||||
- `@use` / `@forward` sont préférés pour le nouveau Sass contrôlé ;
|
||||
- `@import` reste une compatibilité possible pour les dépendances qui l'exigent encore ;
|
||||
- les sources CSS/Sass et leurs outputs générés sont distingués sans ambiguïté ;
|
||||
- un package de styles est consommé via son entrypoint public/documenté plutôt que par un chemin interne arbitraire ;
|
||||
- Bootstrap/Tailwind CSS/alternative restent des choix de projet ou skeleton, pas des obligations de `560` ;
|
||||
- la validation frontend est séparée de la validation du host ;
|
||||
- le skeleton Web compose des owners existants et ne devient pas leur propriétaire.
|
||||
|
||||
Le `DEFER` Tauri n'est pas levé par cette tranche.
|
||||
|
||||
## Validation frontend indépendante du host
|
||||
|
||||
[`docs/validation/005-WEB_FRONTEND_VALIDATION.md`](../../docs/validation/005-WEB_FRONTEND_VALIDATION.md) définit les couches de preuve réutilisables :
|
||||
|
||||
```text
|
||||
restore reproductible
|
||||
TypeScript typecheck
|
||||
styles si preuve distincte
|
||||
build frontend de production
|
||||
browser smoke si nécessaire
|
||||
host integration séparée
|
||||
```
|
||||
|
||||
La matrice évite les doublons : si Sass est déjà compilé par le build Vite et qu'aucun contrat Sass autonome n'existe, une seconde compilation identique n'est pas requise.
|
||||
|
||||
Un `PASS` frontend ne vaut jamais automatiquement `PASS` du host.
|
||||
|
||||
## Skeleton Web
|
||||
|
||||
[`docs/skeletons/003-WEB_FRONTEND.md`](../../docs/skeletons/003-WEB_FRONTEND.md) devient la première specialization Web PGR.
|
||||
|
||||
Il peut composer :
|
||||
|
||||
```text
|
||||
GENERAL + 500 + 530 + 540 + 550 + 560
|
||||
```
|
||||
|
||||
mais chaque profil reste sélectionné selon les faits du projet. TypeScript et Vite restent des recommandations `SHOULD`; Sass reste conditionnel.
|
||||
|
||||
Le skeleton MUST NOT imposer :
|
||||
|
||||
```text
|
||||
npm
|
||||
Bootstrap
|
||||
Tailwind CSS
|
||||
frontend/
|
||||
vite.config.ts générique
|
||||
main.scss générique
|
||||
port fixe
|
||||
base fixe
|
||||
WASM
|
||||
Tauri
|
||||
backend
|
||||
deployment
|
||||
```
|
||||
|
||||
## Pas de faux templates techniques
|
||||
|
||||
La tranche ajoute un guide CSS/Sass :
|
||||
|
||||
```text
|
||||
docs/templates/010-WEB_CSS_SASS.md
|
||||
```
|
||||
|
||||
mais aucun `templates/web-css/main.scss` ni autre source de style factice.
|
||||
|
||||
Le skeleton réutilise les templates TypeScript/package existants et les guides Vite/CSS-Sass. Les valeurs réellement dépendantes du projet restent à décider pendant l'instanciation.
|
||||
|
||||
## Scope
|
||||
|
||||
REPLACE :
|
||||
|
||||
```text
|
||||
VERSION
|
||||
README.md
|
||||
docs/000-README.md
|
||||
docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
|
||||
docs/rules/560-CSS_SASS.md
|
||||
docs/skeletons/000-README.md
|
||||
docs/validation/001-VALIDATION_MATRIX.md
|
||||
```
|
||||
|
||||
ADD :
|
||||
|
||||
```text
|
||||
docs/skeletons/003-WEB_FRONTEND.md
|
||||
docs/templates/010-WEB_CSS_SASS.md
|
||||
docs/validation/005-WEB_FRONTEND_VALIDATION.md
|
||||
deltas/0.1.1/alpha.5.md
|
||||
```
|
||||
|
||||
DELETE : aucun.
|
||||
|
||||
## Validation opérateur
|
||||
|
||||
Après application du history `PASS`, commit/push de `alpha.4`, puis application du présent delta :
|
||||
|
||||
```bash
|
||||
test "$(cat VERSION)" = '0.1.1-alpha.5'
|
||||
git cat-file -e HEAD:history/0.1.1/alpha.4.md
|
||||
test -f history/0.1.1/alpha.4.md
|
||||
test -f deltas/0.1.1/alpha.5.md
|
||||
test ! -e history/0.1.1/alpha.5.md
|
||||
|
||||
grep -A2 '^## Statut$' history/0.1.1/alpha.4.md | grep -Fx 'PASS'
|
||||
grep -Fx '<!-- version: 18 -->' README.md
|
||||
grep -Fx '<!-- version: 28 -->' docs/000-README.md
|
||||
grep -Fx '<!-- version: 8 -->' docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
|
||||
grep -Fx '<!-- version: 2 -->' docs/rules/560-CSS_SASS.md
|
||||
grep -Fx '<!-- version: 6 -->' docs/skeletons/000-README.md
|
||||
grep -Fx '<!-- version: 1 -->' docs/skeletons/003-WEB_FRONTEND.md
|
||||
grep -Fx '<!-- version: 1 -->' docs/templates/010-WEB_CSS_SASS.md
|
||||
grep -Fx '<!-- version: 14 -->' docs/validation/001-VALIDATION_MATRIX.md
|
||||
grep -Fx '<!-- version: 1 -->' docs/validation/005-WEB_FRONTEND_VALIDATION.md
|
||||
|
||||
python3 -B - <<'PYGATE'
|
||||
from pathlib import Path
|
||||
import re
|
||||
|
||||
history = Path("history/0.1.1/alpha.4.md").read_text(encoding="utf-8")
|
||||
assert re.search(r"## Statut\s+PASS\s", history)
|
||||
|
||||
styles = Path("docs/rules/560-CSS_SASS.md").read_text(encoding="utf-8")
|
||||
for phrase in (
|
||||
"Sass **SHOULD** être préféré",
|
||||
"Sass n'est donc jamais requis",
|
||||
"MUST NOT être modifié manuellement",
|
||||
"`@use` / `@forward`",
|
||||
"L'ancien `@import` Sass est déprécié",
|
||||
"entrypoint Sass public",
|
||||
"`sass-embedded` **SHOULD** être préféré",
|
||||
"Un package npm apportant uniquement des styles n'impose pas l'ajout de déclarations `@types/*`",
|
||||
"un build Vite réussi peut constituer la preuve de compilation des styles",
|
||||
"005-WEB_FRONTEND_VALIDATION.md",
|
||||
):
|
||||
assert phrase in styles, phrase
|
||||
|
||||
guide = Path("docs/templates/010-WEB_CSS_SASS.md").read_text(encoding="utf-8")
|
||||
for phrase in (
|
||||
"ne fournit volontairement pas de `main.scss`",
|
||||
"CSS seul reste valide",
|
||||
"sass-embedded",
|
||||
"@use",
|
||||
"@forward",
|
||||
"Les dépendances `@types/*` ne concernent que les API JavaScript/TypeScript",
|
||||
"PGR ne fixe ni Bootstrap, ni Bootswatch",
|
||||
"host gate séparée",
|
||||
):
|
||||
assert phrase in guide, phrase
|
||||
|
||||
validation = Path("docs/validation/005-WEB_FRONTEND_VALIDATION.md").read_text(encoding="utf-8")
|
||||
for phrase in (
|
||||
"Le frontend **SHOULD** être validable indépendamment du host",
|
||||
"Un résultat frontend `PASS`",
|
||||
"restauration reproductible des dépendances",
|
||||
"type-check TypeScript",
|
||||
"build frontend de production",
|
||||
"preview / smoke navigateur",
|
||||
"PGR MUST NOT imposer `npm ci`",
|
||||
"PGR SHOULD NOT lancer deux compilations équivalentes",
|
||||
"Un host tel que Tauri",
|
||||
"Il ne vaut pas `PASS` Tauri",
|
||||
):
|
||||
assert phrase in validation, phrase
|
||||
|
||||
skeleton = Path("docs/skeletons/003-WEB_FRONTEND.md").read_text(encoding="utf-8")
|
||||
for phrase in (
|
||||
"GENERAL",
|
||||
"+ 530 TypeScript",
|
||||
"+ 540 JavaScript package ecosystem",
|
||||
"+ 550 Vite",
|
||||
"+ 560 CSS / Sass",
|
||||
"Le skeleton ne transforme pas une recommandation `SHOULD` en `MUST`",
|
||||
"PGR ne fournit pas de `vite.config.ts` universel",
|
||||
"PGR ne fournit pas non plus de `main.scss`",
|
||||
"Le nom `frontend/` est une convention possible",
|
||||
"le package manager réel",
|
||||
"Bootstrap, Tailwind CSS ou autre",
|
||||
"Le skeleton Tauri reste `DEFER` pendant `0.1.1`",
|
||||
):
|
||||
assert phrase in skeleton, phrase
|
||||
|
||||
matrix = Path("docs/validation/001-VALIDATION_MATRIX.md").read_text(encoding="utf-8")
|
||||
assert "005-WEB_FRONTEND_VALIDATION.md" in matrix
|
||||
|
||||
index = Path("docs/000-README.md").read_text(encoding="utf-8")
|
||||
for target in (
|
||||
"templates/010-WEB_CSS_SASS.md",
|
||||
"validation/005-WEB_FRONTEND_VALIDATION.md",
|
||||
"skeletons/003-WEB_FRONTEND.md",
|
||||
):
|
||||
assert target in index, target
|
||||
|
||||
skeleton_index = Path("docs/skeletons/000-README.md").read_text(encoding="utf-8")
|
||||
assert "003-WEB_FRONTEND.md" in skeleton_index
|
||||
assert "La création du skeleton Web ne lève pas automatiquement ce `DEFER`." in skeleton_index
|
||||
|
||||
plan = Path("docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md").read_text(encoding="utf-8")
|
||||
for phrase in (
|
||||
"### alpha.4 — Vite, dev server et outputs",
|
||||
"Statut opérateur : **PASS**.",
|
||||
"### alpha.5 — CSS/Sass et validation frontend",
|
||||
"Les owners `530/540/550/560` sont désormais assez complets",
|
||||
"Le skeleton ne lève pas le `DEFER` Tauri",
|
||||
):
|
||||
assert phrase in plan, phrase
|
||||
|
||||
study = Path("docs/studies/002-TAURI_SKELETON_DECISION.md").read_text(encoding="utf-8")
|
||||
assert "DEFER" in study
|
||||
for phrase in (
|
||||
"TypeScript et conventions Web contrôlées",
|
||||
"Vite et ownership des commandes/dev server/build outputs",
|
||||
"Sass/CSS et statut des artefacts générés",
|
||||
"validation frontend indépendante de la validation Tauri",
|
||||
"choix Bootstrap ou alternative clairement classifié",
|
||||
):
|
||||
assert phrase in study, phrase
|
||||
|
||||
assert not Path("templates/web-vite/vite.config.ts").exists()
|
||||
assert not Path("templates/web-css/main.scss").exists()
|
||||
assert Path("docs/rules/530-TYPESCRIPT.md").read_text(encoding="utf-8").splitlines()[1] == "<!-- version: 3 -->"
|
||||
assert Path("docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md").read_text(encoding="utf-8").splitlines()[1] == "<!-- version: 3 -->"
|
||||
assert Path("docs/rules/550-VITE.md").read_text(encoding="utf-8").splitlines()[1] == "<!-- version: 2 -->"
|
||||
assert Path("docs/rules/710-TAURI.md").read_text(encoding="utf-8").splitlines()[1] == "<!-- version: 6 -->"
|
||||
assert "0.1.8" not in Path("ROADMAP.md").read_text(encoding="utf-8")
|
||||
|
||||
print("0.1.1 alpha.5 Web frontend audit: clean (CSS/Sass bounded, host-independent validation explicit, Web skeleton composable, Tauri DEFER preserved)")
|
||||
PYGATE
|
||||
|
||||
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
|
||||
|
||||
git diff --check
|
||||
|
||||
git add VERSION README.md docs/000-README.md \
|
||||
docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md \
|
||||
docs/rules/560-CSS_SASS.md \
|
||||
docs/skeletons/000-README.md docs/skeletons/003-WEB_FRONTEND.md \
|
||||
docs/templates/010-WEB_CSS_SASS.md \
|
||||
docs/validation/001-VALIDATION_MATRIX.md docs/validation/005-WEB_FRONTEND_VALIDATION.md \
|
||||
deltas/0.1.1/alpha.5.md
|
||||
|
||||
git diff --cached --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
Le scope indexé attendu avant ajout du history de `alpha.5` est exactement :
|
||||
|
||||
```text
|
||||
M README.md
|
||||
M VERSION
|
||||
A deltas/0.1.1/alpha.5.md
|
||||
M docs/000-README.md
|
||||
M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
|
||||
M docs/rules/560-CSS_SASS.md
|
||||
M docs/skeletons/000-README.md
|
||||
A docs/skeletons/003-WEB_FRONTEND.md
|
||||
A docs/templates/010-WEB_CSS_SASS.md
|
||||
M docs/validation/001-VALIDATION_MATRIX.md
|
||||
A docs/validation/005-WEB_FRONTEND_VALIDATION.md
|
||||
```
|
||||
|
||||
## Revue opérateur complémentaire
|
||||
|
||||
Confirmer que :
|
||||
|
||||
- Sass reste `SHOULD` et conditionnel ;
|
||||
- CSS seul reste une baseline valide ;
|
||||
- `@use` / `@forward` sont préférés sans casser les dépendances encore basées sur `@import` ;
|
||||
- aucun CSS compilé n'est présenté comme source à modifier ;
|
||||
- aucune dépendance Sass/Vite/Bootstrap n'est injectée dans le template `package.json` générique ;
|
||||
- aucun `main.scss` ou `vite.config.ts` artificiel n'est ajouté ;
|
||||
- le skeleton `003-WEB_FRONTEND.md` compose les owners au lieu de recopier leurs règles ;
|
||||
- npm, Bootstrap, Tailwind CSS, `frontend/`, ports et `base` restent des décisions locales ;
|
||||
- la validation frontend peut être exécutée séparément du host autant que le graphe réel le permet ;
|
||||
- un `PASS` frontend n'est pas présenté comme un `PASS` Tauri ;
|
||||
- le `DEFER` du skeleton Tauri reste intact ;
|
||||
- WASM, backend et deployment restent hors scope.
|
||||
|
||||
## Transition
|
||||
|
||||
### PASS
|
||||
|
||||
Produire `history/0.1.1/alpha.5.md`, l'appliquer puis committer/pousser `alpha.5`. Continuer avec `0.1.1-beta.1` pour la réconciliation large, le dry-run proportionné du skeleton Web et la preuve factuelle de préparation du futur réexamen Tauri.
|
||||
|
||||
### FAIL
|
||||
|
||||
Consigner le diagnostic réel dans `history/0.1.1/alpha.5.md`, puis produire `alpha.5.fix.N` ou effectuer un REPLAN si le défaut révèle une frontière d'ownership incorrecte. Ne pas absorber `beta.1` dans un correctif CSS/Sass.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/000-README.md -->
|
||||
<!-- version: 27 -->
|
||||
<!-- version: 28 -->
|
||||
|
||||
# Documentation PGR
|
||||
|
||||
@@ -26,6 +26,9 @@ Les templates techniques copiables sous `templates/` restent séparés des instr
|
||||
- [`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.
|
||||
- [`templates/008-WEB_TYPESCRIPT_PACKAGE.md`](templates/008-WEB_TYPESCRIPT_PACKAGE.md) — adaptation de la baseline minimale `package.json` + `tsconfig.json` de `alpha.3`, sans package manager, versions ou bundler imposés.
|
||||
- [`templates/009-WEB_VITE.md`](templates/009-WEB_VITE.md) — guide d'adaptation Vite de `alpha.4` : root, dev server, cache, outputs, assets et scripts sans imposer de layout ni de port universels.
|
||||
- [`templates/010-WEB_CSS_SASS.md`](templates/010-WEB_CSS_SASS.md) — guide CSS/Sass de `alpha.5` : sources, modules Sass, packages de styles et artefacts générés sans imposer de framework CSS.
|
||||
- [`validation/005-WEB_FRONTEND_VALIDATION.md`](validation/005-WEB_FRONTEND_VALIDATION.md) — validation frontend réutilisable et indépendante du host : restore, type-check, build/styles et smoke proportionné.
|
||||
- [`skeletons/003-WEB_FRONTEND.md`](skeletons/003-WEB_FRONTEND.md) — specialization Web composable fondée sur les owners `530/540/550/560`, sans imposer Vite, Sass, npm, Bootstrap ou un layout unique.
|
||||
- [`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`.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Plan 0.1.1 — fondation frontend Web contrôlée
|
||||
|
||||
@@ -393,27 +393,31 @@ Aucune règle TypeScript/package ni aucun template n'a été modifié par le fix
|
||||
|
||||
### alpha.4 — Vite, dev server et outputs
|
||||
|
||||
Matérialiser le contrat Vite sans créer un `vite.config.ts` universel artificiel : les chemins `root`, `cacheDir`, `build.outDir`, la valeur `base`, les ports, aliases, plugins et intégrations de host dépendent du layout réel du projet.
|
||||
Statut opérateur : **PASS**.
|
||||
|
||||
Le profil doit en revanche fixer les responsabilités génériques suivantes :
|
||||
La tranche a matérialisé le contrat Vite sans créer de `vite.config.ts` universel artificiel. Les sources, cache, outputs et assets ont des statuts explicites ; le dev server reste borné ; les paramètres `root`, `base`, ports, aliases et plugins restent des décisions locales.
|
||||
|
||||
- distinguer sources versionnées, cache reproductible et outputs de build générés ;
|
||||
- garder cache et outputs hors Git, en les externalisant hors de l'arborescence source lorsque cela reste raisonnable ;
|
||||
- considérer `publicDir` comme une source statique optionnelle et les copies présentes dans `outDir` comme générées ;
|
||||
- n'utiliser `build.emptyOutDir = true` que lorsque `outDir` est un répertoire dédié et possédé sans ambiguïté par le build ;
|
||||
- garder le dev server local/loopback par défaut et n'élargir l'écoute réseau que pour un besoin explicite ;
|
||||
- rendre port + `strictPort` déterministes lorsqu'un host ou un smoke dépend d'une URL fixe ;
|
||||
- éviter les ouvertures globales de `allowedHosts` ou CORS sans justification ;
|
||||
- réserver `vite preview` à la prévisualisation locale d'un build et non à un serveur de production ;
|
||||
- ajouter Vite au manifest réel comme outil de développement et exposer `dev` / `build` / `preview` seulement lorsqu'ils correspondent au workflow réel.
|
||||
|
||||
Les paramètres de port, host, `base`, aliases, plugins, découpage d'assets et intégrations particulières restent locaux sauf preuve générique contraire. TypeScript reste validé séparément ; CSS/Sass reste réservé à `alpha.5`.
|
||||
La gate spécifique a atteint son message final, les `48/48` tests et les trois audits Markdown sont propres, et le scope Git correspond exactement aux six chemins annoncés. TypeScript/package n'a pas été rouvert et CSS/Sass est resté réservé à `alpha.5`.
|
||||
|
||||
### alpha.5 — CSS/Sass et validation frontend
|
||||
|
||||
Matérialiser la frontière CSS/Sass, puis rendre explicite la validation frontend indépendante du host. Sass reste une capacité optionnelle. Bootstrap ou toute alternative reste un choix de skeleton/projet sauf règle générique distinctement démontrée.
|
||||
Matérialiser la frontière CSS/Sass et la validation frontend indépendante du host.
|
||||
|
||||
Cette tranche peut créer un skeleton frontend uniquement si les owners précédents rendent sa composition suffisamment stable ; sinon le skeleton reste différé sans bloquer la release.
|
||||
La tranche retient les décisions suivantes :
|
||||
|
||||
- CSS reste une baseline valide sans préprocesseur ;
|
||||
- Sass reste optionnel mais **SHOULD** être préféré lorsque la chaîne de styles est non triviale ou lorsqu'un package expose une API Sass utile ;
|
||||
- le nouveau code Sass contrôlé privilégie `@use` / `@forward`, tandis que `@import` reste uniquement une voie de compatibilité pour les dépendances qui l'exigent encore ;
|
||||
- les sources `.css` / `.scss` / `.sass` intentionnelles sont versionnées, mais les CSS compilées, minifiées, sourcemaps et copies présentes dans un output de build sont générées et ne doivent pas devenir un second source ;
|
||||
- un package de styles doit être consommé via son entrypoint public/documenté plutôt que par des chemins internes arbitraires ;
|
||||
- Bootstrap, Tailwind CSS ou une autre bibliothèque restent des choix de projet/skeleton, jamais une obligation de `560` ;
|
||||
- lorsqu'un frontend utilise Vite + Sass, `sass-embedded` est un choix de développement recommandé lorsque compatible, mais le profil Sass ne dépend pas de Vite ;
|
||||
- la validation frontend distingue restore reproductible, type-check, build/compilation des styles et smoke navigateur seulement lorsque celui-ci apporte une preuve supplémentaire ;
|
||||
- un PASS frontend ne vaut pas PASS du host, et un host Tauri ne doit pas posséder les validations TypeScript/Vite/Sass génériques.
|
||||
|
||||
Les owners `530/540/550/560` sont désormais assez complets pour composer un skeleton Web sans ownership caché. La tranche crée donc `003-WEB_FRONTEND.md` comme specialization contrôlée : TypeScript et Vite y restent des `SHOULD`, Sass reste conditionnel, le package manager et le framework CSS restent des décisions explicites, et aucun layout `frontend/`, `vite.config.ts`, `main.scss`, port ou package concret n'est imposé.
|
||||
|
||||
Le skeleton ne lève pas le `DEFER` Tauri. `beta.1` devra encore réconcilier les cinq conditions de sortie de l'étude `002` et conclure factuellement si `0.1.4` peut réexaminer le candidat Tauri.
|
||||
|
||||
### beta.1 — réconciliation et preuve de préparation Tauri
|
||||
|
||||
|
||||
@@ -1,19 +1,25 @@
|
||||
<!-- file: docs/rules/560-CSS_SASS.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# 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.
|
||||
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, points d'entrée publics et classification des artefacts générés.
|
||||
|
||||
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.
|
||||
Il complète [`500-LANGUAGES.md`](500-LANGUAGES.md). Il ne rend aucun framework CSS particulier obligatoire et ne possède ni TypeScript, ni Vite, ni le package manager, ni le host.
|
||||
|
||||
Le profil s'applique à un projet qui possède réellement des sources CSS/Sass ou une chaîne de styles correspondante. La présence d'un frontend sans styles n'oblige pas à créer des fichiers CSS/Sass artificiels.
|
||||
|
||||
## 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.
|
||||
Un frontend Web peut utiliser directement CSS sans préprocesseur. Sass n'est donc jamais requis 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.
|
||||
Les styles sources intentionnels **SHOULD** être versionnés. Les CSS produits uniquement par compilation à partir de sources Sass, les variantes minifiées, les sourcemaps et les copies placées dans un output de build sont des artefacts générés et **SHOULD** rester hors du source control, sauf besoin explicite de distribution ou publication gouverné comme tel.
|
||||
|
||||
Un artefact généré MUST NOT être modifié manuellement comme s'il constituait un second source. La correction appartient au source ou à la configuration qui le produit.
|
||||
|
||||
PGR MUST NOT imposer un nom de répertoire universel tel que `css/`, `styles/` ou `sass/`. Le layout appartient au projet ou au skeleton qui le compose.
|
||||
|
||||
## Recommandation Sass pour les projets contrôlés
|
||||
|
||||
@@ -21,24 +27,44 @@ Pour un frontend contrôlé dont la chaîne de styles est non triviale, Sass **S
|
||||
|
||||
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.
|
||||
Bootstrap constitue un exemple concret de cette catégorie : ses sources Sass permettent de sélectionner des parties de la bibliothèque et de configurer 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.
|
||||
|
||||
## Implémentation Sass et intégration au build
|
||||
|
||||
Le profil Sass ne dépend d'aucun bundler particulier.
|
||||
|
||||
Lorsqu'un projet utilise Vite et sélectionne Sass, il MAY utiliser `sass` ou `sass-embedded` selon la compatibilité de sa toolchain. Pour une nouvelle baseline contrôlée compatible, `sass-embedded` **SHOULD** être préféré lorsque son intégration est supportée et apporte un gain proportionné ; ce choix reste une `devDependency` du projet réel et n'est pas prérempli dans un template PGR générique.
|
||||
|
||||
Un autre bundler ou une compilation Sass autonome MAY utiliser l'implémentation officielle adaptée à son environnement. PGR MUST NOT installer un plugin Vite spécifique uniquement pour activer Sass lorsque Vite prend déjà en charge le préprocesseur sélectionné.
|
||||
|
||||
## 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.
|
||||
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
|
||||
Lorsqu'une bibliothèque expose une API Sass publique et configurable, le projet **SHOULD** suivre cette API documentée. Avec le système de modules, une configuration par `@use ... with (...)` ou un entrypoint réexporté via `@forward` est préférable lorsqu'elle est réellement supportée.
|
||||
|
||||
PGR **SHOULD NOT** dépendre de chemins internes non documentés sous `node_modules` ou d'une arborescence privée d'un package si celui-ci expose un entrypoint Sass public. Une compatibilité historique MAY justifier temporairement un chemin interne, mais cette dépendance doit rester explicite et révisable.
|
||||
|
||||
## Frameworks CSS et packages de styles
|
||||
|
||||
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
|
||||
Un package npm apportant uniquement des styles n'impose pas l'ajout de déclarations `@types/*`. Les déclarations TypeScript sont requises seulement lorsque des API JavaScript/TypeScript réellement consommées en ont besoin, conformément à [`530-TYPESCRIPT.md`](530-TYPESCRIPT.md) et [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md).
|
||||
|
||||
La compilation Sass et la validation du CSS produit sont distinctes du type-check TypeScript, du build Vite et du smoke navigateur.
|
||||
## Validation des styles
|
||||
|
||||
`0.1.1-alpha.5` précisera les gates de styles et leur intégration à la validation frontend indépendante du host.
|
||||
La validation doit prouver la chaîne réellement utilisée sans dupliquer artificiellement la même propriété.
|
||||
|
||||
Lorsque Sass est compilé à l'intérieur du build Vite et qu'aucune compilation Sass indépendante n'existe, un build Vite réussi peut constituer la preuve de compilation des styles. PGR SHOULD NOT imposer en plus une seconde compilation Sass identique uniquement pour ajouter une commande à la gate.
|
||||
|
||||
Lorsqu'une compilation Sass autonome, un linter CSS/Sass ou une autre transformation possède un contrat distinct, sa commande officielle MAY être ajoutée comme preuve séparée.
|
||||
|
||||
Une validation de styles ne remplace ni le type-check TypeScript, ni le build frontend complet, ni un smoke navigateur nécessaire à un comportement observable, ni la validation du host.
|
||||
|
||||
Le contrat de validation frontend indépendant du host est décrit dans [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md). Le guide [`../templates/010-WEB_CSS_SASS.md`](../templates/010-WEB_CSS_SASS.md) décrit l'adaptation pratique sans imposer de layout ou framework CSS universel.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/skeletons/000-README.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Index des skeleton specifications PGR
|
||||
|
||||
@@ -19,13 +19,16 @@ Une specification peut se composer avec une fondation plus générale, mais la c
|
||||
|
||||
- [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md) — fondation composable pour établir la gouvernance locale, la version, la documentation minimale, le workflow retenu et sa validation initiale sans imposer d'architecture applicative.
|
||||
- [`002-RUST_CARGO_WORKSPACE.md`](002-RUST_CARGO_WORKSPACE.md) — specialization composable d'un workspace Rust/Cargo fondée sur `001`, les profils `500 + 510`, les cinq templates Rust/Cargo et une validation réelle de la toolchain.
|
||||
- [`003-WEB_FRONTEND.md`](003-WEB_FRONTEND.md) — specialization composable d'un frontend Web contrôlé fondée sur les owners `530/540/550/560`, avec TypeScript/Vite recommandés, Sass conditionnel et validation indépendante du host.
|
||||
|
||||
Pour un projet existant, ces specifications servent de références de comparaison et non de recettes à recopier aveuglément. Le chemin canonique passe alors par [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md) et son mapping `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`.
|
||||
|
||||
Les familles Java/Android, Web, JNI et autres domaines sans pièces suffisantes restent différées tant que leurs owners normatifs et artefacts d'instanciation ne permettent pas une baseline réellement actionnable.
|
||||
Les familles Java/Android, JNI et autres domaines sans pièces suffisantes restent différées tant que leurs owners normatifs et artefacts d'instanciation ne permettent pas une baseline réellement actionnable.
|
||||
|
||||
Le skeleton Tauri a fait l'objet d'une décision explicite en `0.0.5-alpha.9` : le host Rust/Tauri est suffisamment cadré par `510` et `710`, mais PGR ne possède pas encore les owners Web/Vite/TypeScript/Sass nécessaires pour matérialiser proprement la stack frontend candidate des projets contrôlés. Aucun `003-TAURI...` n'est donc créé dans `0.0.5`. La décision et ses conditions de sortie sont enregistrées dans [`../studies/002-TAURI_SKELETON_DECISION.md`](../studies/002-TAURI_SKELETON_DECISION.md).
|
||||
Le skeleton Web `003` est matérialisé en `0.1.1-alpha.5` parce que les owners `530/540/550/560`, les guides d'adaptation et la validation frontend indépendante du host permettent désormais une composition sans ownership caché. Il ne fixe ni npm, ni Vite/Sass comme obligations, ni Bootstrap, ni un layout `frontend/` universel.
|
||||
|
||||
Un futur skeleton Tauri devra composer les owners existants avec les profils Web réellement matérialisés ; il ne devra pas faire du skeleton lui-même le propriétaire des règles Vite, TypeScript, Sass, Bootstrap ou du package manager.
|
||||
Le skeleton Tauri a fait l'objet d'une décision explicite en `0.0.5-alpha.9` : son host Rust/Tauri est cadré par `510` et `710`, mais sa promotion avait été différée tant que les owners Web nécessaires n'existaient pas. La décision `DEFER` et ses conditions de sortie restent enregistrées dans [`../studies/002-TAURI_SKELETON_DECISION.md`](../studies/002-TAURI_SKELETON_DECISION.md).
|
||||
|
||||
La création du skeleton Web ne lève pas automatiquement ce `DEFER`. `0.1.1-beta.1` doit encore réconcilier objectivement les conditions de sortie avant que `0.1.4` ne réexamine un éventuel skeleton Tauri, qui devra composer les owners Web au lieu de posséder leurs règles.
|
||||
|
||||
Aucun fichier placeholder ne doit être ajouté pour réserver un skeleton futur.
|
||||
|
||||
143
docs/skeletons/003-WEB_FRONTEND.md
Normal file
143
docs/skeletons/003-WEB_FRONTEND.md
Normal file
@@ -0,0 +1,143 @@
|
||||
<!-- file: docs/skeletons/003-WEB_FRONTEND.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Skeleton — Web frontend
|
||||
|
||||
## Objectif
|
||||
|
||||
Cette specification décrit une specialization composable pour créer une baseline frontend Web contrôlée sans confondre langage, package ecosystem, build tool, styles et host.
|
||||
|
||||
Elle se compose avec [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md), sélectionne les owners Web réellement applicables de la famille `500` et utilise les templates/guides `008`, `009` et `010` lorsqu'ils correspondent aux choix du projet.
|
||||
|
||||
Le contrat transversal des skeletons reste possédé par [`../rules/220-SKELETONS.md`](../rules/220-SKELETONS.md).
|
||||
|
||||
## Applicabilité
|
||||
|
||||
Appliquer cette specialization lorsqu'un projet ou sous-projet possède un frontend Web autonome ou embarqué dont la baseline frontend est contrôlée par le projet.
|
||||
|
||||
Elle peut servir de fondation frontend à un host plus spécifique, par exemple Tauri, sans rendre ce host applicable par elle-même.
|
||||
|
||||
Pour un projet existant, cette specification sert de référence de comparaison : l'adoption suit [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md) et classe les choix existants `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` plutôt que de réécrire son layout.
|
||||
|
||||
Ne pas appliquer ce skeleton à un backend sans frontend, à une page statique qui n'a besoin d'aucune de ces responsabilités, ni uniquement parce que Vite/TypeScript sont recommandés ailleurs.
|
||||
|
||||
## Owners sélectionnables
|
||||
|
||||
La composition de référence d'un frontend moderne contrôlé est :
|
||||
|
||||
```text
|
||||
GENERAL
|
||||
+ 500 language / ecosystem family
|
||||
+ 530 TypeScript
|
||||
+ 540 JavaScript package ecosystem
|
||||
+ 550 Vite
|
||||
+ 560 CSS / Sass
|
||||
```
|
||||
|
||||
La sélection reste factuelle :
|
||||
|
||||
- `530` est sélectionné lorsque TypeScript est utilisé ; TypeScript **SHOULD** être préféré pour une baseline durable lorsqu'il est compatible avec le besoin ;
|
||||
- `540` est sélectionné lorsqu'un `package.json`, un package manager ou des dépendances JavaScript sont réellement utilisés ;
|
||||
- `550` est sélectionné uniquement si Vite est choisi ; Vite **SHOULD** être préféré pour les frontends compatibles, sans être obligatoire ;
|
||||
- `560` est sélectionné si le frontend possède une chaîne CSS/Sass ; CSS seul reste valide et Sass reste optionnel, bien que recommandé pour une chaîne non triviale ou un package exposant une API Sass utile.
|
||||
|
||||
Le skeleton ne transforme pas une recommandation `SHOULD` en `MUST`.
|
||||
|
||||
## Fondation et fichiers de départ
|
||||
|
||||
Lorsque TypeScript + package ecosystem sont sélectionnés, le projet MAY partir des templates :
|
||||
|
||||
```text
|
||||
templates/web-typescript/package.json
|
||||
templates/web-typescript/tsconfig.json
|
||||
```
|
||||
|
||||
Le guide [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../templates/008-WEB_TYPESCRIPT_PACKAGE.md) possède leur adaptation.
|
||||
|
||||
PGR ne fournit pas de `vite.config.ts` universel. Si Vite est sélectionné, créer ou adapter la configuration réelle à partir des décisions décrites dans [`../templates/009-WEB_VITE.md`](../templates/009-WEB_VITE.md).
|
||||
|
||||
PGR ne fournit pas non plus de `main.scss` ou de thème universel. Si CSS/Sass est sélectionné, organiser les sources selon les besoins réels et suivre [`../templates/010-WEB_CSS_SASS.md`](../templates/010-WEB_CSS_SASS.md).
|
||||
|
||||
Le nom `frontend/` est une convention possible, pas un chemin imposé par ce skeleton.
|
||||
|
||||
## Décisions destinataire avant matérialisation
|
||||
|
||||
Résoudre explicitement au minimum :
|
||||
|
||||
1. la racine et le scope exacts du frontend ;
|
||||
2. TypeScript ou JavaScript, avec justification si une nouvelle baseline durable n'adopte pas la recommandation TypeScript ;
|
||||
3. le package manager réel et la politique de lockfile adaptée au rôle du package ;
|
||||
4. les versions réelles de TypeScript et des dépendances, ainsi que les déclarations `@types/*` réellement nécessaires ;
|
||||
5. Vite ou un build tool alternatif, avec ses chemins `root`, cache, outputs, `base`, ports, plugins et assets lorsqu'ils s'appliquent ;
|
||||
6. CSS seul ou Sass, puis l'implémentation Sass réelle si sélectionnée ;
|
||||
7. le framework CSS éventuel : aucun, Bootstrap, Tailwind CSS ou autre ; ce choix reste local au projet ;
|
||||
8. les entrypoints de styles publics des dépendances et les overrides réellement nécessaires ;
|
||||
9. les scripts de package réellement utiles (`typecheck`, `dev`, `build`, `preview` ou équivalents) ;
|
||||
10. la gate frontend indépendante du host et les éventuels smokes navigateur utiles ;
|
||||
11. les prérequis produits par d'autres owners, s'il en existe, sans les faire absorber par le frontend.
|
||||
|
||||
Aucune décision ouverte ne doit être remplacée silencieusement par une valeur observée dans Games ou KSP.
|
||||
|
||||
## Dépendances et manifest
|
||||
|
||||
Le package réel **SHOULD** rester privé lorsqu'il représente une application non publiée, conformément à `540`.
|
||||
|
||||
Les dépendances de développement telles que TypeScript, Vite, Sass ou packages de déclarations sont ajoutées uniquement si les choix du projet les rendent nécessaires. Le skeleton MUST NOT préremplir `@types/node`, `@types/bootstrap`, `sass-embedded`, Vite ou Bootstrap sans besoin réel ni version décidée.
|
||||
|
||||
Lorsqu'une dépendance fournit déjà ses propres types, ne pas ajouter un package `@types/*` redondant.
|
||||
|
||||
## Styles
|
||||
|
||||
CSS source et Sass source sont des entrées versionnées. Les CSS compilées/minifiées, sourcemaps et copies dans l'output sont générées sauf contrat de distribution explicite.
|
||||
|
||||
Pour du nouveau Sass contrôlé, `@use` / `@forward` sont préférés lorsque les dépendances le permettent. Une compatibilité `@import` peut être conservée pour un package existant qui l'exige encore.
|
||||
|
||||
Le choix d'un framework CSS ne rend ni Bootstrap, ni Tailwind CSS, ni un thème spécifique normatif pour les autres projets.
|
||||
|
||||
## Build et outputs
|
||||
|
||||
Lorsque Vite est sélectionné, le cache et `build.outDir` restent générés et hors Git. Les chemins exacts restent locaux.
|
||||
|
||||
`build.emptyOutDir = true` n'est utilisé que sur un output dédié. `vite preview` reste un smoke/prévisualisation locale et ne devient pas un serveur de production.
|
||||
|
||||
Un autre build tool possède ses propres décisions project-specific tant qu'aucun owner PGR dédié n'existe.
|
||||
|
||||
## Validation initiale
|
||||
|
||||
La validation suit [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md).
|
||||
|
||||
Selon les profils sélectionnés, elle doit pouvoir prouver indépendamment du host, autant que possible :
|
||||
|
||||
```text
|
||||
restore reproductible
|
||||
TypeScript typecheck
|
||||
compilation/transformation des styles
|
||||
build frontend de production
|
||||
smoke navigateur seulement si nécessaire
|
||||
```
|
||||
|
||||
La commande concrète appartient au package manager et aux outils réellement sélectionnés.
|
||||
|
||||
Le host reçoit ensuite sa propre gate d'intégration. Un PASS frontend ne constitue pas un PASS Tauri ou plateforme.
|
||||
|
||||
Une instanciation temporaire MAY être utilisée pour un dry-run de cette specialization. Elle doit employer les toolchains officielles réelles plutôt qu'un audit Python simulant TypeScript/Vite/Sass.
|
||||
|
||||
## Composition avec un host
|
||||
|
||||
Un host peut composer ce skeleton comme fondation frontend, puis ajouter son propre profil/skeleton.
|
||||
|
||||
Cette composition ne transfère jamais au host l'ownership de TypeScript, du package manager, de Vite ou de Sass/CSS.
|
||||
|
||||
Le skeleton Tauri reste `DEFER` pendant `0.1.1`. La présence du présent skeleton Web satisfait une pièce de préparation mais ne décide pas à elle seule la promotion du candidat Tauri.
|
||||
|
||||
## Hors scope
|
||||
|
||||
Cette specification ne possède pas :
|
||||
|
||||
- Tauri ou un autre host natif ;
|
||||
- WASM ou ses bindings/générations ;
|
||||
- backend/serveur Web ;
|
||||
- deployment/operations ;
|
||||
- choix de framework UI/CSS universel ;
|
||||
- configuration de sécurité propre à un host ;
|
||||
- service worker/PWA tant qu'un owner distinct n'est pas justifié.
|
||||
111
docs/templates/010-WEB_CSS_SASS.md
vendored
Normal file
111
docs/templates/010-WEB_CSS_SASS.md
vendored
Normal file
@@ -0,0 +1,111 @@
|
||||
<!-- file: docs/templates/010-WEB_CSS_SASS.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Guide d'adaptation CSS / Sass
|
||||
|
||||
## Objet
|
||||
|
||||
Ce guide accompagne le profil [`../rules/560-CSS_SASS.md`](../rules/560-CSS_SASS.md). Il aide un projet à décider sa chaîne de styles sans transformer Sass, Bootstrap, Vite ou un layout particulier en obligation universelle.
|
||||
|
||||
PGR ne fournit volontairement pas de `main.scss`, de thème Bootstrap ou de structure `styles/` copiable par défaut : ces fichiers ne deviennent utiles qu'après choix du framework, des entrypoints, du layout et du niveau de personnalisation réel.
|
||||
|
||||
## Décider d'abord si Sass apporte une valeur
|
||||
|
||||
CSS seul reste valide lorsque les besoins sont simples ou que les capacités CSS modernes suffisent.
|
||||
|
||||
Sass est particulièrement pertinent lorsque le projet a besoin de :
|
||||
|
||||
- variables et configuration de compilation ;
|
||||
- mixins, fonctions ou composition de modules ;
|
||||
- factorisation d'une chaîne de styles non triviale ;
|
||||
- personnalisation d'un package qui expose officiellement des sources Sass/SCSS ;
|
||||
- construction sélective d'un framework ou thème sans modifier les sources tierces.
|
||||
|
||||
La décision doit rester liée au besoin réel. Un smoke ou un petit frontend n'a pas à recevoir Sass uniquement pour ressembler à un autre projet.
|
||||
|
||||
## Choisir l'implémentation
|
||||
|
||||
Dans un projet Vite compatible, les sources `.scss` / `.sass` peuvent être prises en charge par Vite lorsque le préprocesseur correspondant est installé. Pour une nouvelle baseline contrôlée, `sass-embedded` est un bon choix de `devDependency` lorsqu'il est supporté ; `sass` reste une alternative légitime.
|
||||
|
||||
Le package manager, la version et la commande d'installation sont décidés par le projet. Le guide ne transforme donc pas un exemple `npm add -D ...` en commande normative.
|
||||
|
||||
Hors Vite, utiliser l'intégration officielle du bundler ou du compilateur Sass sélectionné.
|
||||
|
||||
## Organiser les sources
|
||||
|
||||
Le projet décide ses noms de répertoires et entrypoints. Une organisation possible peut séparer :
|
||||
|
||||
```text
|
||||
variables / configuration
|
||||
modules internes
|
||||
adaptations de packages tiers
|
||||
styles applicatifs
|
||||
entrypoint principal
|
||||
```
|
||||
|
||||
Cette organisation n'est qu'un pattern. PGR n'impose ni `frontend/sass/`, ni `_variables.scss`, ni `main.scss`.
|
||||
|
||||
Les fichiers sources intentionnels sont versionnés. Les CSS compilées, fichiers minifiés, sourcemaps et copies du build restent générés sauf artefact de distribution explicitement gouverné.
|
||||
|
||||
## Préférer les modules Sass modernes
|
||||
|
||||
Pour le nouveau code :
|
||||
|
||||
```text
|
||||
@use
|
||||
@forward
|
||||
```
|
||||
|
||||
sont préférés lorsque les dépendances les supportent.
|
||||
|
||||
`@import` Sass peut rester nécessaire pour une dépendance historique ou une API tierce qui le documente encore. Cette compatibilité doit rester locale ; elle ne doit pas conduire à écrire de nouveau code PGR autour de `@import` lorsque le système de modules fonctionne.
|
||||
|
||||
Lorsqu'un module accepte une configuration, utiliser son API publique et ses variables configurables plutôt que copier/modifier ses sources dans le projet.
|
||||
|
||||
## Packages npm et entrypoints de styles
|
||||
|
||||
Pour une dépendance de styles :
|
||||
|
||||
1. vérifier l'entrypoint CSS/Sass public documenté par le package ;
|
||||
2. vérifier s'il expose une configuration Sass supportée ;
|
||||
3. utiliser cet entrypoint public avant d'envisager un chemin interne sous `node_modules` ;
|
||||
4. conserver tout override dans un source possédé par le projet ;
|
||||
5. ne jamais modifier directement le package installé.
|
||||
|
||||
Un package peut exposer CSS, Sass, JavaScript ou plusieurs de ces surfaces. Les dépendances `@types/*` ne concernent que les API JavaScript/TypeScript qui en ont réellement besoin ; importer uniquement le Sass/CSS d'un package ne suffit pas à justifier un package de déclarations.
|
||||
|
||||
## Exemple Bootstrap
|
||||
|
||||
Bootstrap illustre un package pouvant être utilisé de plusieurs façons : CSS précompilé, API JavaScript et sources Sass configurables.
|
||||
|
||||
Si le projet choisit Bootstrap avec Sass, il doit suivre l'API Sass de la version réellement sélectionnée, placer ses variables/overrides avant les étapes requises par cette API et conserver les adaptations dans ses propres sources.
|
||||
|
||||
PGR ne fixe ni Bootstrap, ni Bootswatch, ni un thème, ni un ordre d'import particulier comme baseline universelle. Un projet existant utilisant encore `@import` pour compatibilité MAY le conserver jusqu'à une migration sûre.
|
||||
|
||||
## Relation avec Vite
|
||||
|
||||
Lorsque Vite est sélectionné :
|
||||
|
||||
- l'import d'un entrypoint `.scss` depuis le graphe frontend peut suffire à déclencher la compilation ;
|
||||
- `css.preprocessorOptions` MAY adapter le compilateur lorsque le projet en a réellement besoin ;
|
||||
- une configuration globale injectée dans chaque fichier doit rester limitée aux symboles nécessaires ; injecter des styles complets partout peut dupliquer le CSS ;
|
||||
- les CSS présentes dans `build.outDir` sont des outputs Vite générés, pas de nouveaux sources.
|
||||
|
||||
Le profil Vite reste propriétaire de `vite.config.ts`, du cache et de l'output ; le profil CSS/Sass reste propriétaire de la chaîne de styles elle-même.
|
||||
|
||||
## Validation
|
||||
|
||||
Pour un frontend où Sass est intégré au build Vite :
|
||||
|
||||
```text
|
||||
typecheck preuve TypeScript séparée si applicable
|
||||
build preuve Vite + compilation/transformation des styles
|
||||
browser smoke seulement si une propriété observable le nécessite
|
||||
host gate séparée
|
||||
```
|
||||
|
||||
Ne pas ajouter une commande Sass autonome si elle ne prouve rien de plus que le build déjà exécuté.
|
||||
|
||||
Si le projet possède au contraire une compilation Sass autonome, un linter ou un package de styles publié séparément, ajouter la preuve officielle correspondante.
|
||||
|
||||
Le contrat complet est décrit dans [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md).
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Matrice de validation PGR
|
||||
|
||||
@@ -45,6 +45,12 @@ Pour une nouvelle baseline contrôlée, les propriétés sans ordre métier peuv
|
||||
|
||||
[`004-RUST_CARGO_BASELINE_DRY_RUN.md`](004-RUST_CARGO_BASELINE_DRY_RUN.md) décrit une preuve temporaire de réutilisabilité des skeletons/templates Rust/Cargo. Le mode « nouveau projet » utilise la toolchain officielle dans un répertoire temporaire ; le mode « projet existant » vérifie qu’un mapping d’adoption n’écrase pas les décisions locales classées `KEEP-LOCAL` ou `DEFER`. Cette preuve est sélectionnée lorsque les artefacts Rust/Cargo eux-mêmes changent ou lorsqu’une phase de release doit reconfirmer leur composabilité ; elle n’est pas une cérémonie de chaque delta documentaire.
|
||||
|
||||
## Validation frontend Web réutilisable, hors gate du dépôt PGR
|
||||
|
||||
[`005-WEB_FRONTEND_VALIDATION.md`](005-WEB_FRONTEND_VALIDATION.md) décrit la validation indépendante du host pour un frontend réel : restauration reproductible selon le package manager choisi, type-check TypeScript, styles, build de production et smoke navigateur seulement lorsqu'il apporte une preuve supplémentaire.
|
||||
|
||||
Cette validation appartient aux projets qui possèdent réellement un frontend ou aux dry-runs de skeletons correspondants. Le dépôt PGR n'installe pas TypeScript, Vite ou Sass uniquement pour simuler une gate qu'il ne possède pas. Les outils officiels restent propriétaires de leurs preuves ; un audit Python PGR ne les réimplémente pas.
|
||||
|
||||
## Politique Eclipse actuelle
|
||||
|
||||
Les métadonnées Eclipse spécifiques à une machine restent ignorées, notamment `.project`, `.classpath` et les préférences non partagées.
|
||||
|
||||
128
docs/validation/005-WEB_FRONTEND_VALIDATION.md
Normal file
128
docs/validation/005-WEB_FRONTEND_VALIDATION.md
Normal 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.
|
||||
100
history/0.1.1/alpha.5.md
Normal file
100
history/0.1.1/alpha.5.md
Normal file
@@ -0,0 +1,100 @@
|
||||
<!-- file: history/0.1.1/alpha.5.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# History 0.1.1-alpha.5 — CSS/Sass, validation frontend et skeleton Web
|
||||
|
||||
## Statut
|
||||
|
||||
PASS
|
||||
|
||||
La gate opérateur de `0.1.1-alpha.5` exécutée le `2026-09-27` est `PASS`.
|
||||
|
||||
La tranche précédente `0.1.1-alpha.4` avait été clôturée, committée sous `89b8ea8` puis poussée sur `origin/master` avant application du delta `alpha.5`.
|
||||
|
||||
## Contrôles structurels
|
||||
|
||||
Les préconditions et versions documentaires attendues ont été confirmées :
|
||||
|
||||
```text
|
||||
VERSION 0.1.1-alpha.5
|
||||
history/0.1.1/alpha.4.md présent dans HEAD et PASS
|
||||
deltas/0.1.1/alpha.5.md présent
|
||||
history/0.1.1/alpha.5.md absent pendant la gate
|
||||
README.md version 18
|
||||
docs/000-README.md version 28
|
||||
docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md version 8
|
||||
docs/rules/560-CSS_SASS.md version 2
|
||||
docs/skeletons/000-README.md version 6
|
||||
docs/skeletons/003-WEB_FRONTEND.md version 1
|
||||
docs/templates/010-WEB_CSS_SASS.md version 1
|
||||
docs/validation/001-VALIDATION_MATRIX.md version 14
|
||||
docs/validation/005-WEB_FRONTEND_VALIDATION.md version 1
|
||||
```
|
||||
|
||||
La gate spécifique Web frontend a atteint son message final :
|
||||
|
||||
```text
|
||||
0.1.1 alpha.5 Web frontend audit: clean (CSS/Sass bounded, host-independent validation explicit, Web skeleton composable, Tauri DEFER preserved)
|
||||
```
|
||||
|
||||
Elle a notamment reconfirmé :
|
||||
|
||||
- CSS comme baseline valide sans Sass ;
|
||||
- Sass comme recommandation conditionnelle `SHOULD`, jamais obligation universelle ;
|
||||
- `@use` / `@forward` pour le nouveau Sass contrôlé, avec `@import` réservé à la compatibilité ;
|
||||
- la séparation entre sources CSS/Sass et artefacts générés ;
|
||||
- les entrypoints publics/documentés pour les packages de styles ;
|
||||
- `sass-embedded` comme choix recommandé lorsque Vite + Sass le justifient ;
|
||||
- l'absence de lien artificiel entre styles seuls et packages `@types/*` ;
|
||||
- la validation frontend indépendante du host ;
|
||||
- le skeleton `003-WEB_FRONTEND.md` comme composition des owners `530/540/550/560` ;
|
||||
- l'absence volontaire de `vite.config.ts`, `main.scss`, npm, Bootstrap, Tailwind CSS, port ou `base` universels ;
|
||||
- le maintien du skeleton Tauri en `DEFER`.
|
||||
|
||||
## Tests et audits
|
||||
|
||||
La suite Python globale a exécuté `48` tests :
|
||||
|
||||
```text
|
||||
Ran 48 tests in 0.737s
|
||||
|
||||
OK
|
||||
```
|
||||
|
||||
Les audits Markdown ont affiché :
|
||||
|
||||
```text
|
||||
Markdown header audit: clean (223 file(s))
|
||||
Markdown table audit: clean (9 table(s), 223 file(s))
|
||||
Markdown link audit: clean (256 local link(s), 223 file(s))
|
||||
```
|
||||
|
||||
`git diff --check` et `git diff --cached --check` n'ont produit aucune erreur.
|
||||
|
||||
## Scope observé
|
||||
|
||||
Le scope indexé final était exactement :
|
||||
|
||||
```text
|
||||
M README.md
|
||||
M VERSION
|
||||
A deltas/0.1.1/alpha.5.md
|
||||
M docs/000-README.md
|
||||
M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
|
||||
M docs/rules/560-CSS_SASS.md
|
||||
M docs/skeletons/000-README.md
|
||||
A docs/skeletons/003-WEB_FRONTEND.md
|
||||
A docs/templates/010-WEB_CSS_SASS.md
|
||||
M docs/validation/001-VALIDATION_MATRIX.md
|
||||
A docs/validation/005-WEB_FRONTEND_VALIDATION.md
|
||||
```
|
||||
|
||||
Aucun profil Tauri, owner WASM, backend ou domaine deployment n'a été absorbé dans la tranche.
|
||||
|
||||
## Conclusion
|
||||
|
||||
`0.1.1-alpha.5` est validée `PASS`.
|
||||
|
||||
La transition autorisée est `0.1.1-beta.1` pour réconcilier la fondation Web complète, vérifier structurellement la composabilité du skeleton `003-WEB_FRONTEND.md` et comparer factuellement les owners désormais disponibles aux cinq conditions de sortie du `DEFER` enregistré dans `002-TAURI_SKELETON_DECISION.md`.
|
||||
|
||||
`beta.1` ne doit ni lever ce `DEFER`, ni créer un skeleton Tauri.
|
||||
Reference in New Issue
Block a user