From 5033547534fc84f08d0cf8df4d302c39867feb28 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 27 Sep 2026 10:56:05 +0200 Subject: [PATCH] 0.1.1-alpha.3 --- VERSION | 2 +- deltas/0.1.1/alpha.3.md | 310 ++++++++++++++++++ docs/000-README.md | 3 +- ...007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md | 29 +- docs/rules/530-TYPESCRIPT.md | 37 ++- .../rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md | 26 +- docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md | 118 +++++++ history/0.1.1/alpha.3.md | 130 ++++++++ templates/web-typescript/package.json | 7 + templates/web-typescript/tsconfig.json | 9 + 10 files changed, 650 insertions(+), 21 deletions(-) create mode 100644 deltas/0.1.1/alpha.3.md create mode 100644 docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md create mode 100644 history/0.1.1/alpha.3.md create mode 100644 templates/web-typescript/package.json create mode 100644 templates/web-typescript/tsconfig.json diff --git a/VERSION b/VERSION index d55c7e5..5115655 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.1-alpha.2.fix.1 +0.1.1-alpha.3 diff --git a/deltas/0.1.1/alpha.3.md b/deltas/0.1.1/alpha.3.md new file mode 100644 index 0000000..66eb255 --- /dev/null +++ b/deltas/0.1.1/alpha.3.md @@ -0,0 +1,310 @@ + + + +# Delta 0.1.1-alpha.3 — TypeScript et écosystème de package + +## Baseline et version + +Baseline attendue : commit opérateur de `0.1.1-alpha.2.fix.1`, réalisé après application de `history/0.1.1/alpha.2.fix.1.md` avec statut `PASS`. + +Le hash de ce commit n'est pas anticipé. + +Version avant application : + +```text +0.1.1-alpha.2.fix.1 +``` + +Version après application : + +```text +0.1.1-alpha.3 +``` + +## Objet + +Détailler les owners `530 TypeScript` et `540 JavaScript package ecosystem`, puis fournir une baseline minimale réutilisable pour une application Web TypeScript privée. + +La tranche définit : + +- une baseline TypeScript stricte et indépendante du bundler ; +- le script canonique `typecheck` ; +- la responsabilité de `package.json` et de la sélection explicite du package manager ; +- une politique de lockfile fondée sur le rôle du package et la reproductibilité ; +- une paire minimale `package.json` + `tsconfig.json` sans version TypeScript, package manager, Vite, Sass, framework UI, host ou WASM imposés. + +Vite reste réservé à `alpha.4`. CSS/Sass et la validation frontend réconciliée restent réservés à `alpha.5`. + +## Scope + +REPLACE : + +```text +VERSION +docs/000-README.md +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +docs/rules/530-TYPESCRIPT.md +docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +``` + +ADD : + +```text +deltas/0.1.1/alpha.3.md +docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md +templates/web-typescript/package.json +templates/web-typescript/tsconfig.json +``` + +DELETE : aucun. + +`RULES.md`, `ROADMAP.md`, `CHANGELOG.md`, les profils `550`, `560`, `710`, les skeletons, scripts Python, tests et matrices de validation restent inchangés. + +Aucun `history/0.1.1/alpha.3.md` n'est anticipé. + +## Décisions TypeScript + +La baseline générique contrôlée active : + +```text +strict +noEmit +noUnusedLocals +noUnusedParameters +noFallthroughCasesInSwitch +``` + +Elle n'impose pas : + +```text +target +module +moduleResolution +lib +types +jsx +include/exclude +aliases +Vite +WASM +Tauri +``` + +Ces choix dépendent du runtime, du host, du bundler ou du layout réel. + +Le script `typecheck` SHOULD exposer la vérification TypeScript indépendamment du bundler. Le template utilise : + +```text +tsc --noEmit +``` + +Le package manager reste responsable de l'invocation réelle de ce script. + +## Décisions package manager / manifest + +PGR ne choisit toujours pas npm, pnpm, yarn, Bun ou un autre outil par défaut. + +Le projet MUST rendre son choix de package manager explicite dans un owner local approprié. Le champ `packageManager` de `package.json` MAY être utilisé lorsque la toolchain le permet, mais PGR ne peut pas y inscrire une version fictive dans son template générique. + +Pour une application non publiée, `private: true` SHOULD être utilisé. + +Le template `package.json` n'invente ni version de package, ni dépendance, ni champ de publication. Il fournit seulement un nom d'exemple, `private: true` et le script `typecheck`. + +## Politique de lockfile + +La politique PGR est désormais : + +```text +application privée / déployable + -> lockfile SHOULD être versionné + +bibliothèque publiée + -> lockfile MAY être versionné pour dev/CI + mais le manifest reste le contrat consommateur + +template / fixture sans résolution réelle + -> lockfile MAY être absent +``` + +Un package SHOULD NOT conserver plusieurs lockfiles concurrents sauf migration temporaire explicitement documentée. + +Lorsqu'un lockfile est versionné, CI SHOULD utiliser le mode gelé/immutable/clean-install équivalent du package manager choisi. + +La politique historique Games sans lockfile n'est donc ni réécrite ni qualifiée rétroactivement de défaut. Son adoption `0.1.5` décidera package par package entre `ADOPT` et `OVERRIDE`. + +## Templates + +Les deux fichiers copiables sont : + +```text +templates/web-typescript/package.json +templates/web-typescript/tsconfig.json +``` + +Ils sont volontairement du JSON strict, donc ne portent pas de commentaires internes `file/version`. + +Leur contrat et leurs étapes d'adaptation sont documentés dans : + +```text +docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md +``` + +La paire ne constitue pas encore un skeleton frontend. + +## Validation opérateur + +Après application du history `PASS`, commit/push de `alpha.2.fix.1`, puis application du présent delta : + +```bash +test "$(cat VERSION)" = '0.1.1-alpha.3' +git cat-file -e HEAD:history/0.1.1/alpha.2.fix.1.md +test -f history/0.1.1/alpha.2.fix.1.md +test -f deltas/0.1.1/alpha.3.md +test ! -e history/0.1.1/alpha.3.md + +grep -A2 '^## Statut$' history/0.1.1/alpha.2.fix.1.md | grep -Fx 'PASS' +grep -Fx '' docs/000-README.md +grep -Fx '' docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +grep -Fx '' docs/rules/530-TYPESCRIPT.md +grep -Fx '' docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +grep -Fx '' docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md + +python3 -B - <<'PYGATE' +from pathlib import Path +import json +import re + +history = Path('history/0.1.1/alpha.2.fix.1.md').read_text(encoding='utf-8') +assert re.search(r'## Statut\s+PASS\s', history) + +typescript = Path('docs/rules/530-TYPESCRIPT.md').read_text(encoding='utf-8') +for phrase in ( + 'strict = true', + 'noEmit = true', + 'noUnusedLocals = true', + 'noUnusedParameters = true', + 'noFallthroughCasesInSwitch = true', + 'typecheck', + 'tsc --noEmit', + 'MUST NOT les figer', +): + assert phrase in typescript, phrase + +packages = Path('docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md').read_text(encoding='utf-8') +for phrase in ( + 'private: true', + 'MUST sélectionner explicitement son package manager', + 'typecheck', + 'SHOULD** être versionné', + 'SHOULD NOT** conserver simultanément plusieurs lockfiles', + 'MUST NOT transformer `npm ci` en commande universelle', + '`ADOPT` cette recommandation', + '`OVERRIDE`', +): + assert phrase in packages, phrase + +package = json.loads(Path('templates/web-typescript/package.json').read_text(encoding='utf-8')) +tsconfig = json.loads(Path('templates/web-typescript/tsconfig.json').read_text(encoding='utf-8')) + +assert package == { + 'name': 'project-web', + 'private': True, + 'scripts': {'typecheck': 'tsc --noEmit'}, +} +assert tsconfig == { + 'compilerOptions': { + 'strict': True, + 'noEmit': True, + 'noUnusedLocals': True, + 'noUnusedParameters': True, + 'noFallthroughCasesInSwitch': True, + } +} + +guide = Path('docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md').read_text(encoding='utf-8') +for phrase in ( + 'package manager concret', + 'version TypeScript', + 'target ECMAScript', + 'Vite ou autre bundler', + "n'acceptent pas un header commentaire PGR", + 'npm run typecheck', + 'pnpm typecheck', + 'yarn typecheck', +): + assert phrase in guide, phrase + +plan = Path('docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md').read_text(encoding='utf-8') +for phrase in ( + 'Statut opérateur : **PASS**.', + 'application privée ou déployable `SHOULD` versionner le lockfile', + "`DEFER` jusqu'à l'adoption `0.1.5`", + 'script canonique `typecheck`', + 'Vite reste réservé à `alpha.4`', +): + assert phrase in plan, phrase + +assert Path('docs/rules/550-VITE.md').read_text(encoding='utf-8').splitlines()[1] == '' +assert Path('docs/rules/560-CSS_SASS.md').read_text(encoding='utf-8').splitlines()[1] == '' +assert Path('docs/rules/710-TAURI.md').read_text(encoding='utf-8').splitlines()[1] == '' + +print('0.1.1 alpha.3 TypeScript/package audit: clean (strict typecheck, package-manager neutral, role-based lockfile policy, 2 JSON templates parsed)') +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 docs/000-README.md \ + docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md \ + docs/rules/530-TYPESCRIPT.md docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md \ + docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md \ + templates/web-typescript/package.json templates/web-typescript/tsconfig.json \ + deltas/0.1.1/alpha.3.md + +git diff --cached --check +git status --short +``` + +Le scope indexé attendu avant ajout du history est exactement : + +```text +M VERSION +A deltas/0.1.1/alpha.3.md +M docs/000-README.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/530-TYPESCRIPT.md +M docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +A docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md +A templates/web-typescript/package.json +A templates/web-typescript/tsconfig.json +``` + +## Revue opérateur complémentaire + +Confirmer que : + +- la baseline TypeScript générique ne fige aucun choix propre à Vite, Node, WASM ou Tauri ; +- `typecheck` reste une preuve indépendante et ne devient pas une responsabilité du bundler ; +- PGR ne sélectionne aucun package manager universel ; +- le lockfile est recommandé pour les applications privées/déployables sans imposer la même politique aux bibliothèques publiées ; +- le template `package.json` n'invente aucune version de dépendance ou de package manager ; +- les deux JSON restent des templates minimaux, pas un skeleton frontend ; +- aucun contenu de `alpha.4` ou `alpha.5` n'est absorbé. + +## Transition + +### PASS + +Produire `history/0.1.1/alpha.3.md`, l'appliquer puis committer/pousser la tranche. Préparer ensuite `0.1.1-alpha.4` consacré à Vite, au dev server et aux outputs. + +### FAIL + +Consigner le diagnostic réel dans `history/0.1.1/alpha.3.md` et rester dans `alpha.3.fix.M` sauf REPLAN explicitement justifié. diff --git a/docs/000-README.md b/docs/000-README.md index 52ebc2b..0706f30 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation PGR @@ -24,6 +24,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr - [`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. +- [`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. - [`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/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md b/docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md index 3855170..77e7d76 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 @@ -206,12 +206,17 @@ pnpm-lock.yaml yarn.lock ``` -Aucun lockfile Node n'est versionné dans l'archive. Cette politique est un choix Games actuel, pas une preuve qu'un lockfile frontend doit toujours être ignoré. `0.1.1` doit donc distinguer : +Aucun lockfile Node n'est versionné dans l'archive. Cette politique est un choix Games actuel, pas une preuve qu'un lockfile frontend doit toujours être ignoré. -- le contrat générique d'un manifest/package manager ; -- la sélection explicite du package manager par le projet ; -- la politique du lockfile selon le type de package/application et la reproductibilité recherchée ; -- la politique locale Games, qui restera `KEEP-LOCAL` tant qu'une règle générique différente n'est pas décidée et justifiée. +`alpha.3` retient une politique fondée sur le rôle : + +- une application privée ou déployable `SHOULD` versionner le lockfile produit par son package manager afin de figer l'arbre réellement résolu ; +- une bibliothèque publiée `MAY` versionner un lockfile pour stabiliser l'environnement contributeur/CI, mais le manifest et ses contraintes restent le contrat de résolution des consommateurs ; +- un exemple, template ou fixture sans résolution de dépendances réelle `MAY` ne pas posséder de lockfile ; +- un même package `SHOULD NOT` conserver simultanément plusieurs lockfiles de package managers concurrents, sauf migration explicitement temporaire ; +- lorsqu'un lockfile est versionné, CI `SHOULD` utiliser le mode gelé/immutable/clean-install équivalent du package manager sélectionné plutôt qu'une résolution permissive. + +L'absence actuelle de lockfiles dans Games devient donc une décision à réexaminer pendant l'adoption `0.1.5` : les packages applicatifs pourront `ADOPT` la recommandation en versionnant leur lockfile, ou documenter un `OVERRIDE` s'ils conservent volontairement une autre politique. ### Relation avec WASM et host @@ -266,7 +271,7 @@ Cette granularité conserve l'indépendance d'applicabilité : un projet peut ut | 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 | +| absence/versionnement des lockfiles Games | `DEFER` jusqu'à l'adoption `0.1.5` | choisir alors `ADOPT` ou `OVERRIDE` selon le rôle du package | | 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 | @@ -344,15 +349,17 @@ La gate spécifique n'a toutefois pas pu atteindre son message final : le litté ### alpha.2.fix.1 — correction de la gate d'ownership Web -Corriger uniquement la syntaxe de validation de `alpha.2`, sans modifier les profils `530/540/550/560`, `710-TAURI.md`, les index ou l'architecture déjà livrés. +Statut opérateur : **PASS**. -La gate corrigée doit reconfirmer le `FAIL` historique de `alpha.2`, les quatre owners indépendants, les recommandations `SHOULD`, la classification Games, le maintien du `DEFER` Tauri, puis rejouer les tests et audits documentaires. +Le correctif a conservé le `FAIL` historique de `alpha.2`, reconfirmé les quatre owners `530/540/550/560`, les recommandations `SHOULD`, la classification Games et le `DEFER` Tauri. Les `48/48` tests et les trois audits Markdown sont propres ; le scope du fix est resté limité à `VERSION`, au plan et au delta de correction. ### alpha.3 — TypeScript et écosystème de package -Matérialiser les règles et artefacts réutilisables pour TypeScript, manifest, scripts de package et sélection du package manager. Définir une politique de lockfile fondée sur le rôle de l'artefact et la reproductibilité, pas sur une préférence npm. +Matérialiser les règles et artefacts réutilisables pour TypeScript, manifest, scripts de package et sélection du package manager. -Si un template `package.json` ou `tsconfig.json` est ajouté, il doit rester minimal, parsable et adaptable sans versions arbitrairement figées lorsque PGR ne possède pas cette décision. +La tranche retient un type-check indépendant sous le script canonique `typecheck`, un `tsconfig` strict sans émission comme baseline minimale, un `package.json` privé minimal pour les applications contrôlées et une politique de lockfile fondée sur le rôle de l'artefact et la reproductibilité, jamais sur une préférence npm. + +Les templates `package.json` et `tsconfig.json` restent volontairement minimaux et parsables. Ils n'imposent ni version TypeScript, ni package manager, ni target/module/runtime, ni Vite ; ces décisions sont ajoutées par le projet ou par les owners des tranches suivantes. Vite reste réservé à `alpha.4` et CSS/Sass à `alpha.5`. ### alpha.4 — Vite, dev server et outputs diff --git a/docs/rules/530-TYPESCRIPT.md b/docs/rules/530-TYPESCRIPT.md index f26543e..e24dc4a 100644 --- a/docs/rules/530-TYPESCRIPT.md +++ b/docs/rules/530-TYPESCRIPT.md @@ -1,5 +1,5 @@ - + # Profil TypeScript @@ -31,9 +31,40 @@ Cette recommandation ne transforme pas TS-RS en dépendance générale de TypeSc `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. +Pour un nouveau package TypeScript contrôlé, la baseline PGR `SHOULD` activer au minimum : -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. +```text +strict = true +noEmit = true +``` + +`strict` exprime la volonté d'utiliser le contrôle de types renforcé de TypeScript. `noEmit` sépare le type-check de la production des artefacts JavaScript lorsque cette production appartient à un bundler ou à un autre outil. + +Pour une baseline stricte, PGR `SHOULD` également activer les contrôles simples suivants sauf incompatibilité documentée : + +```text +noUnusedLocals = true +noUnusedParameters = true +noFallthroughCasesInSwitch = true +``` + +Les choix `target`, `module`, `moduleResolution`, `lib`, `types`, `jsx`, chemins/aliases, `include` et `exclude` dépendent du runtime, du bundler, du framework et du layout réel. PGR MUST NOT les figer dans le profil TypeScript générique uniquement parce qu'ils apparaissent dans Games. + +Le package `SHOULD` exposer une validation TypeScript indépendante sous un script canonique : + +```text +typecheck +``` + +Lorsque le compilateur local est installé dans le package, le pattern recommandé est : + +```text +tsc --noEmit +``` + +Un build Vite, Tauri ou autre ne remplace pas automatiquement cette preuve ciblée lorsqu'une propriété de typage doit être validée indépendamment. + +Le modèle minimal [`../../templates/web-typescript/tsconfig.json`](../../templates/web-typescript/tsconfig.json) active uniquement les options génériques ci-dessus. Le guide [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../templates/008-WEB_TYPESCRIPT_PACKAGE.md) liste les décisions à compléter avant adoption réelle. ## Ce que le profil n'impose pas diff --git a/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md b/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md index 1e4c17b..05bdb87 100644 --- a/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +++ b/docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md @@ -1,5 +1,5 @@ - + # Profil écosystème de packages JavaScript @@ -21,8 +21,14 @@ Les commandes opérateur et CI doivent utiliser le package manager réellement s `package.json` appartient à cet owner lorsqu'il décrit le package frontend ou JavaScript/TypeScript concerné. +Pour une application locale/non publiée, `private: true` **SHOULD** être utilisé afin d'exprimer explicitement que le package n'est pas destiné à être publié par erreur. Un package destiné à un registry doit au contraire définir les métadonnées et versions nécessaires à sa publication réelle. + +Le projet MUST sélectionner explicitement son package manager. Cette sélection peut être rendue machine-readable dans le manifest lorsque la toolchain retenue le permet, ou être possédée par la configuration/CI/documentation locale. PGR ne fixe ni le nom ni la version du package manager dans son template générique. + 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. +Pour un package TypeScript, le nom `typecheck` **SHOULD** désigner la vérification TypeScript indépendante. `dev`, `build` et `preview` restent disponibles pour les owners qui possèdent réellement ces comportements ; leur simple présence dans un exemple ne les rend pas obligatoires. + 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 @@ -35,12 +41,22 @@ Un package tiers peut exposer des entrypoints JavaScript, CSS, Sass ou d'autres 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`. +Pour une application privée, un frontend déployable ou un outil livré comme unité exécutable, le lockfile produit par le package manager sélectionné **SHOULD** être versionné afin de conserver l'arbre effectivement résolu entre développeurs, CI et livraisons. -L'absence de lockfile dans Games reste donc une décision locale à classifier, pas une règle PGR générale. +Pour une bibliothèque publiée, un lockfile **MAY** être versionné afin de stabiliser l'environnement de développement et de CI. Il ne remplace toutefois pas les contraintes du manifest qui pilotent la résolution chez les consommateurs. + +Un exemple, un template ou une fixture qui ne résout aucune dépendance réelle **MAY** ne pas embarquer de lockfile. + +Un package **SHOULD NOT** conserver simultanément plusieurs lockfiles concurrents (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` ou équivalent), sauf migration explicitement temporaire entre package managers. + +Lorsqu'un lockfile est versionné, la CI **SHOULD** utiliser le mode de résolution gelé, immutable ou clean-install fourni par le package manager sélectionné. Le nom exact de cette commande reste local à l'outil ; PGR MUST NOT transformer `npm ci` en commande universelle. + +L'absence actuelle de lockfiles dans Games reste historique. Lors de l'adoption `0.1.5`, chaque package concerné devra soit `ADOPT` cette recommandation, soit documenter un `OVERRIDE` si une autre politique reste préférable. ## 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). +Le parsing du manifest, l'installation/résolution de dépendances, le respect du lockfile 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. +Une validation statique PGR peut vérifier qu'un `package.json` template est du JSON valide et que les champs génériques attendus sont présents. Elle ne remplace pas l'installation/résolution réalisée par le package manager sélectionné. + +Le modèle minimal [`../../templates/web-typescript/package.json`](../../templates/web-typescript/package.json) représente une application TypeScript privée sans choisir de package manager ni de versions de dépendances. Son adaptation est documentée par [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../templates/008-WEB_TYPESCRIPT_PACKAGE.md). diff --git a/docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md b/docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md new file mode 100644 index 0000000..b7f1454 --- /dev/null +++ b/docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md @@ -0,0 +1,118 @@ + + + +# Templates de package Web TypeScript + +## Rôle + +Cette spécification accompagne les deux fichiers copiables : + +- [`package.json`](../../templates/web-typescript/package.json) ; +- [`tsconfig.json`](../../templates/web-typescript/tsconfig.json). + +Ils constituent une baseline **minimale** pour une application frontend TypeScript privée. Ils ne constituent ni un projet complet, ni un skeleton Web, ni un choix de Vite, Sass, framework UI ou package manager. + +Les owners normatifs restent [`530-TYPESCRIPT.md`](../rules/530-TYPESCRIPT.md) et [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](../rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md). + +## Pourquoi les templates restent minimaux + +PGR ne possède pas encore, à ce niveau générique, les décisions suivantes : + +```text +package manager concret +version du package manager +version TypeScript +target ECMAScript +module / moduleResolution +lib / types +framework frontend +Vite ou autre bundler +Sass ou CSS direct +layout source final +aliases +WASM +host Tauri ou autre +``` + +Les templates MUST donc rester parsables sans figer arbitrairement ces choix. + +`package.json` et `tsconfig.json` n'acceptent pas un header commentaire PGR sans sortir de leur grammaire standard. Leur chemin et leur rôle sont donc possédés par le présent document plutôt que par des commentaires internes `file/version`. + +## `package.json` + +Le template représente un package privé et contient uniquement : + +```text +name valeur d'exemple à remplacer +private true +scripts typecheck +``` + +Avant utilisation : + +1. remplacer `project-web` par le nom réellement choisi ; +2. sélectionner explicitement le package manager ; +3. ajouter TypeScript comme dépendance de développement avec une version compatible réellement décidée par le projet ; +4. laisser le package manager choisi produire son lockfile si la politique applicable le recommande ; +5. ajouter les dépendances fonctionnelles seulement lorsqu'elles sont réellement nécessaires ; +6. ajouter `dev`, `build`, `preview` ou autres scripts uniquement lorsque leurs owners existent. + +Le template ne contient pas de champ `version` parce qu'une application privée n'a pas besoin d'inventer une version npm distincte. Un projet qui aligne volontairement ce manifest sur sa release globale peut l'ajouter selon sa gouvernance locale. + +## `tsconfig.json` + +Le template active uniquement les contrôles considérés génériques pour une baseline stricte : + +```text +strict +noEmit +noUnusedLocals +noUnusedParameters +noFallthroughCasesInSwitch +``` + +Avant utilisation, le projet doit décider explicitement les options qui dépendent de sa target et de son host : `target`, `module`, `moduleResolution`, `lib`, `types`, `jsx`, `include`, `exclude`, aliases et éventuels chemins générés. + +Le template ne copie donc pas les valeurs Games `ES2022`, `ESNext`, `bundler`, `vite/client`, `node` ou les aliases WASM. Ces valeurs restent des preuves de corpus et pourront être reprises seulement par l'owner qui les justifie. + +## Type-check indépendant + +Après installation locale de TypeScript, le script générique est : + +```text +typecheck -> tsc --noEmit +``` + +Le type-check SHOULD pouvoir être exécuté indépendamment du bundler. Un futur script `build` MAY l'appeler avant le build de production, mais cela ne supprime pas sa responsabilité propre. + +Exemples d'appel selon le package manager sélectionné : + +```text +npm run typecheck +pnpm typecheck +yarn typecheck +``` + +Ces lignes sont des exemples, pas une sélection de package manager par PGR. + +## Lockfile + +Pour une application privée/deployable issue de ce template, le lockfile du package manager sélectionné SHOULD normalement être versionné. + +Si le projet conserve volontairement une autre politique, l'écart doit être traité comme décision locale ou `OVERRIDE` lors d'une adoption PGR, avec justification proportionnée. + +PGR MUST NOT conserver plusieurs lockfiles concurrents uniquement pour rendre le template compatible avec plusieurs package managers. + +## Validation minimale du template dans PGR + +Le dépôt PGR vérifie seulement que les deux fichiers sont du JSON parsable et qu'ils conservent les champs génériques attendus. + +La validation réelle d'un projet destinataire sélectionne ensuite : + +- le package manager choisi ; +- la résolution/install de dépendances si nécessaire ; +- le mode gelé/immutable lorsque le lockfile est versionné ; +- le script `typecheck` ; +- les validations Vite/CSS/Sass/host applicables dans leurs owners respectifs. + +Le futur `alpha.5` de `0.1.1` réconciliera la validation frontend complète sans transformer cette paire de templates en skeleton prématuré. diff --git a/history/0.1.1/alpha.3.md b/history/0.1.1/alpha.3.md new file mode 100644 index 0000000..608c05e --- /dev/null +++ b/history/0.1.1/alpha.3.md @@ -0,0 +1,130 @@ + + + +# History 0.1.1-alpha.3 — TypeScript et écosystème de package + +## Statut + +PASS + +La gate opérateur de `0.1.1-alpha.3` exécutée le `2026-09-27` est propre. + +La tranche matérialise une baseline TypeScript stricte indépendante du bundler, le script canonique `typecheck`, un `package.json` privé minimal, une sélection explicite du package manager et une politique de lockfile fondée sur le rôle de l'artefact. + +Une amélioration de revue a été identifiée après la réussite de la gate : expliciter la découverte et la déclaration des types externes (`@types/*`) nécessaires à l'analyse TypeScript et aux IDE. Cette amélioration appartient exactement au scope `alpha.3`, mais ne remet pas en cause les preuves exécutées. Le delta livré reste immuable ; la précision sera donc portée par `alpha.3.fix.1`. + +## Baseline opérateur + +La tranche `0.1.1-alpha.2.fix.1` et son history `PASS` ont été commités puis poussés avant application de `alpha.3` : + +```text +commit e351f57 +message 0.1.1-alpha.2.fix.1 +push origin/master PASS +``` + +Le history `PASS` du fix est présent dans `HEAD` avant la gate de `alpha.3`. + +## Contrôles d'identité + +Les contrôles opérateur ont confirmé : + +```text +VERSION 0.1.1-alpha.3 +history/0.1.1/alpha.2.fix.1.md présent dans HEAD +deltas/0.1.1/alpha.3.md présent +history/0.1.1/alpha.3.md absent pendant la gate +history alpha.2.fix.1 PASS +docs/000-README.md version 26 +docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md version 4 +docs/rules/530-TYPESCRIPT.md version 2 +docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md version 2 +docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md version 1 +``` + +## Gate spécifique + +La gate TypeScript/package atteint son message final : + +```text +0.1.1 alpha.3 TypeScript/package audit: clean (strict typecheck, package-manager neutral, role-based lockfile policy, 2 JSON templates parsed) +``` + +Elle confirme notamment : + +- `strict`, `noEmit`, `noUnusedLocals`, `noUnusedParameters` et `noFallthroughCasesInSwitch` dans la baseline ; +- le script `typecheck` basé sur `tsc --noEmit` ; +- l'absence de package manager universel imposé ; +- la politique de lockfile fondée sur le rôle ; +- le parsing exact des templates `package.json` et `tsconfig.json` ; +- le maintien de Vite en `alpha.4` et CSS/Sass en `alpha.5`. + +## Tests Python + +La suite complète a affiché : + +```text +Ran 48 tests in 0.718s + +OK +``` + +Soit `48/48` tests `PASS`. + +## Audits Markdown + +Les audits ont affiché : + +```text +Markdown header audit: clean (211 file(s)) +Markdown table audit: clean (9 table(s), 211 file(s)) +Markdown link audit: clean (228 local link(s), 211 file(s)) +``` + +## Hygiène Git et scope + +`git diff --check` et `git diff --cached --check` n'ont produit aucune erreur. + +Le scope indexé observé est exactement : + +```text +M VERSION +A deltas/0.1.1/alpha.3.md +M docs/000-README.md +M docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md +M docs/rules/530-TYPESCRIPT.md +M docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md +A docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md +A templates/web-typescript/package.json +A templates/web-typescript/tsconfig.json +``` + +Aucun contenu Vite de `alpha.4` ni CSS/Sass de `alpha.5` n'a été absorbé. + +## Décision de revue — déclarations de types externes + +La revue opérateur demande de rendre explicite le traitement des packages de déclarations tels que `@types/node` ou `@types/bootstrap`, afin d'améliorer le contrôle TypeScript, l'intégration IDE, les diagnostics et la complétion lorsque la dépendance concernée ne fournit pas déjà des types suffisants. + +La règle à introduire par `alpha.3.fix.1` doit rester conditionnelle : + +1. vérifier d'abord si le package consommé fournit ses propres déclarations TypeScript ; +2. si elles sont absentes ou insuffisantes, rechercher le package `@types/...` correspondant ou une autre déclaration maintenue appropriée ; +3. pour une application/outillage privé, placer normalement ces dépendances de types dans `devDependencies` ; +4. ne pas ajouter `@types/node` à un frontend navigateur qui n'analyse aucun code/config Node ; +5. ne pas ajouter `@types/bootstrap` à un projet qui n'utilise que CSS/Sass et n'importe aucune API JavaScript Bootstrap nécessitant ces déclarations ; +6. pour une bibliothèque publiée, ne pas cacher en `devDependencies` un package de déclarations requis par les `.d.ts` publics des consommateurs ; +7. conserver une compatibilité de version cohérente entre le package runtime, ses déclarations externes et la version TypeScript sélectionnée. + +Le template PGR générique ne doit pas inventer `@types/node`, `@types/bootstrap` ou leurs versions : ces dépendances dépendent des imports et de l'environnement réels du projet. + +## Résultat + +`0.1.1-alpha.3` est validée `PASS`. + +La transition immédiate devient : + +```text +0.1.1-alpha.3.fix.1 +``` + +Le correctif reste local au contrat TypeScript/package et à son guide. Après son `PASS`, la trajectoire reprend avec `0.1.1-alpha.4` consacré à Vite. diff --git a/templates/web-typescript/package.json b/templates/web-typescript/package.json new file mode 100644 index 0000000..f9dad01 --- /dev/null +++ b/templates/web-typescript/package.json @@ -0,0 +1,7 @@ +{ + "name": "project-web", + "private": true, + "scripts": { + "typecheck": "tsc --noEmit" + } +} diff --git a/templates/web-typescript/tsconfig.json b/templates/web-typescript/tsconfig.json new file mode 100644 index 0000000..61ef2e0 --- /dev/null +++ b/templates/web-typescript/tsconfig.json @@ -0,0 +1,9 @@ +{ + "compilerOptions": { + "strict": true, + "noEmit": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true + } +}