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

0.1.1-alpha.3.fix.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 11:03:58 +02:00
parent 5033547534
commit 889d9cbcbd
7 changed files with 470 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Plan 0.1.1 — fondation frontend Web contrôlée
@@ -218,6 +218,18 @@ Aucun lockfile Node n'est versionné dans l'archive. Cette politique est un choi
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.
Le corpus Games exerce également déjà des dépendances de déclarations TypeScript :
```text
Web/game-snake-poc @types/bootstrap + @types/node
Web/game-realtime-webtransport-browser-smoke @types/node
crates/apps/game-snake-poc-tauri @types/node
```
KSP `0.3.17` corrobore la même pratique sur ses applications Tauri, qui utilisent `@types/bootstrap` et `@types/node` en `devDependencies`. Cette répétition justifie une règle générique de découverte des déclarations nécessaires, mais ne justifie pas d'imposer ces deux packages à tous les frontends.
La règle retenue est donc : vérifier d'abord les types embarqués par le package, puis rechercher un `@types/...` seulement lorsqu'il est réellement nécessaire. Pour une application privée, ces déclarations de développement appartiennent normalement à `devDependencies`; une bibliothèque publiée doit en revanche conserver disponibles aux consommateurs les types requis par ses déclarations publiques.
### Relation avec WASM et host
Deux packages Games chaînent actuellement des commandes WASM avant Vite. Cela prouve une intégration locale, mais ne justifie pas de faire du WASM une responsabilité du futur owner Vite ou TypeScript.
@@ -355,11 +367,19 @@ Le correctif a conservé le `FAIL` historique de `alpha.2`, reconfirmé les quat
### 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.
Statut opérateur : **PASS**.
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.
La tranche a matérialisé 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`.
La gate spécifique atteint son message final, les `48/48` tests et les trois audits Markdown sont propres, et le scope Git correspond exactement au delta. Vite est resté réservé à `alpha.4` et CSS/Sass à `alpha.5`.
La revue opérateur après PASS relève toutefois une précision appartenant exactement au scope de la tranche : le manifest réel doit rechercher et déclarer les types externes nécessaires (`@types/node`, `@types/bootstrap` ou équivalent) lorsque les dépendances utilisées ne fournissent pas déjà leurs propres déclarations. Le delta livré reste immuable ; cette précision est portée par un fix local.
### alpha.3.fix.1 — déclarations de types externes
Préciser la découverte et la classification des packages de déclarations TypeScript sans modifier le template générique avec des dépendances fictives.
Le correctif doit imposer l'ordre de décision `types embarqués → @types si nécessaire`, recommander `devDependencies` pour les déclarations purement de développement d'une application privée, distinguer `@types/node` et `@types/bootstrap` selon leur applicabilité réelle, conserver la nuance des bibliothèques publiées et maintenir Vite/CSS/Sass hors scope.
### alpha.4 — Vite, dev server et outputs

23
docs/rules/530-TYPESCRIPT.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/530-TYPESCRIPT.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Profil TypeScript
@@ -27,6 +27,27 @@ Lorsqu'un projet Rust expose des DTO, structures ou énumérations destinés au
Cette recommandation ne transforme pas TS-RS en dépendance générale de TypeScript. L'owner Rust, le framework ou le sous-système qui possède la frontière décide si cette génération est requise. Le profil Tauri peut notamment renforcer ce contrat dans son propre scope.
## Déclarations de types externes et intégration IDE
Les dépendances TypeScript ne nécessitent pas toutes un package `@types/*` séparé. Avant d'ajouter une déclaration externe, le projet MUST déterminer si le package consommé fournit déjà ses propres fichiers de déclaration TypeScript. Une déclaration déjà fournie par le package ne doit pas être doublée arbitrairement par un package `@types/*`.
Lorsqu'une dépendance utilisée par du code TypeScript ne fournit pas de déclarations suffisantes, le projet **SHOULD** rechercher une source de types maintenue et compatible, typiquement le package `@types/<nom>` publié depuis DefinitelyTyped lorsqu'il existe. Cette dépendance améliore le contrôle statique, la compréhension des API par le language service TypeScript et, par conséquent, les diagnostics, la navigation et la complétion dans les IDE compatibles.
Pour une application privée ou de l'outillage local, les packages de déclarations qui ne sont nécessaires qu'au développement **SHOULD** normalement être placés dans `devDependencies`. Exemples d'applicabilité :
```text
@types/node code, configuration ou outillage TypeScript utilisant réellement des API/globales Node
@types/bootstrap code TypeScript utilisant les API JavaScript Bootstrap lorsque Bootstrap ne fournit pas lui-même les déclarations requises
```
Ces exemples ne sont pas des dépendances PGR universelles. Un frontend navigateur qui n'analyse aucun code Node MUST NOT ajouter `@types/node` uniquement par habitude. Un projet qui ne consomme que le CSS/Sass de Bootstrap n'a pas besoin de `@types/bootstrap` pour cette seule raison.
Lorsqu'un `tsconfig.json` utilise explicitement `compilerOptions.types`, les packages de déclarations globales nécessaires au contexte analysé doivent être sélectionnés de manière cohérente avec cette liste. Les types importés depuis un module restent gouvernés par la résolution de modules applicable.
Pour une bibliothèque publiée, la classification diffère : si les déclarations publiques produites par la bibliothèque référencent un package de types externe requis par les consommateurs, ce package MUST rester disponible à ces consommateurs. Il ne doit donc pas être caché en `devDependencies` par simple convention d'application ; sa classification dans `dependencies`, `peerDependencies` ou une autre relation appropriée doit suivre le contrat de publication réel.
Les versions des déclarations externes SHOULD rester compatibles avec le package runtime concerné et avec la version TypeScript sélectionnée. PGR MUST NOT inventer une version `@types/*` dans un template générique sans dépendance réelle à typer.
## Configuration et validation
`tsconfig.json`, les options de compilation/type-check, les fichiers inclus/exclus et la commande TypeScript canonique appartiennent à ce profil.

18
docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Profil écosystème de packages JavaScript
@@ -37,6 +37,22 @@ Les dépendances téléchargées telles que `node_modules/` sont des artefacts r
Un package tiers peut exposer des entrypoints JavaScript, CSS, Sass ou d'autres assets. Leur utilisation active les owners correspondants selon le besoin réel du projet ; elle ne fait pas du package manager le propriétaire de leur configuration.
## Dépendances de développement et packages de déclarations
Le manifest réel doit distinguer les dépendances runtime des outils et déclarations nécessaires uniquement au développement. Pour une application TypeScript privée, le compilateur TypeScript, les outils de build et les packages de déclarations externes nécessaires au type-check **SHOULD** normalement être déclarés dans `devDependencies`.
Avant d'ajouter un package `@types/*`, le projet MUST vérifier si la dépendance runtime fournit déjà ses propres types. Si les types sont embarqués, un package `@types/*` redondant SHOULD NOT être ajouté. Si les types sont absents, un package `@types/<nom>` maintenu et compatible **SHOULD** être recherché et ajouté lorsqu'il améliore réellement l'analyse du code consommateur.
Des exemples comme `@types/node` et `@types/bootstrap` sont donc conditionnels :
- `@types/node` est pertinent lorsque le package analyse du code/config/outillage TypeScript qui utilise l'environnement Node ;
- `@types/bootstrap` est pertinent lorsque le code TypeScript consomme les API JavaScript Bootstrap et que les déclarations ne sont pas fournies par le package runtime ;
- aucun des deux ne doit être injecté dans tous les frontends par défaut.
Le template PGR générique conserve volontairement un `package.json` sans `devDependencies` préremplies : il ne connaît ni les dépendances runtime du projet, ni la version TypeScript, ni l'environnement Node éventuel. L'instanciation réelle du template doit ajouter TypeScript et les packages de déclarations effectivement requis avec des versions explicitement décidées.
Pour une bibliothèque publiée, une dépendance de déclarations exposée par les `.d.ts` publics peut être nécessaire chez le consommateur. Dans ce cas, la classer uniquement en `devDependencies` est insuffisant ; le manifest publié doit rendre cette dépendance disponible selon son contrat réel.
## Lockfile
La politique du lockfile MUST être explicitement décidée selon le rôle du package, la reproductibilité recherchée, les contraintes de publication et le package manager sélectionné.

44
docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md vendored
View File

@@ -1,5 +1,5 @@
<!-- file: docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Templates de package Web TypeScript
@@ -53,12 +53,48 @@ 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.
4. ajouter les dépendances fonctionnelles seulement lorsqu'elles sont réellement nécessaires ;
5. pour chaque dépendance consommée depuis TypeScript, vérifier si elle fournit déjà ses propres déclarations ;
6. lorsque les déclarations manquent, rechercher le package `@types/...` maintenu correspondant et l'ajouter normalement à `devDependencies` pour une application privée ;
7. ajouter `@types/node` uniquement si du code/config/outillage TypeScript utilise réellement l'environnement Node, et `@types/bootstrap` uniquement si les API JavaScript Bootstrap typées sont consommées ;
8. vérifier la compatibilité de version entre la dépendance runtime, le package de déclarations éventuel et TypeScript ;
9. laisser le package manager choisi produire son lockfile si la politique applicable le recommande ;
10. 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.
## `devDependencies` et déclarations de types
Le fichier copiable n'inclut aucune `devDependencies` concrète, car PGR ne peut pas connaître à l'avance les versions ni les packages réellement utilisés. Un projet instancié doit toutefois compléter le manifest. Un exemple de forme, à adapter sans recopier les versions littéralement, est :
```json
{
"devDependencies": {
"typescript": "<version décidée>",
"@types/node": "<si Node est réellement utilisé>",
"@types/bootstrap": "<si les API JavaScript Bootstrap sont réellement utilisées et nécessitent des types externes>"
}
}
```
L'ordre de décision est important :
```text
package utilisé
↓
fournit-il déjà ses propres types ?
├─ oui → utiliser les types embarqués ; ne pas ajouter un @types redondant
└─ non → rechercher @types/<package> ou une déclaration maintenue équivalente
↓
vérifier compatibilité et besoin réel
↓
ajouter au manifest dans la classe de dépendance appropriée
```
Pour une application privée, un package de déclarations utilisé uniquement par le type-check appartient normalement à `devDependencies`. Pour une bibliothèque publiée, si les `.d.ts` publics produits référencent cette déclaration, le package doit rester disponible aux consommateurs et peut donc devoir appartenir aux dépendances publiées plutôt qu'aux seules `devDependencies`.
Cette étape participe directement à la qualité TypeScript et à l'expérience IDE : les déclarations permettent au language service de mieux comprendre les signatures et objets importés, d'améliorer les diagnostics et de fournir navigation et complétion lorsque l'éditeur les expose.
## `tsconfig.json`
Le template active uniquement les contrôles considérés génériques pour une baseline stricte :