0.1.1-alpha.3.fix.1
This commit is contained in:
242
deltas/0.1.1/alpha.3.fix.1.md
Normal file
242
deltas/0.1.1/alpha.3.fix.1.md
Normal file
@@ -0,0 +1,242 @@
|
||||
<!-- file: deltas/0.1.1/alpha.3.fix.1.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.1-alpha.3.fix.1 — déclarations de types externes
|
||||
|
||||
## Baseline et version
|
||||
|
||||
Baseline attendue : commit opérateur de `0.1.1-alpha.3`, réalisé après application de `history/0.1.1/alpha.3.md` avec statut `PASS`.
|
||||
|
||||
Le hash de ce commit n'est pas anticipé.
|
||||
|
||||
Version avant application :
|
||||
|
||||
```text
|
||||
0.1.1-alpha.3
|
||||
```
|
||||
|
||||
Version après application :
|
||||
|
||||
```text
|
||||
0.1.1-alpha.3.fix.1
|
||||
```
|
||||
|
||||
## Objet
|
||||
|
||||
Compléter le contrat TypeScript/package de `alpha.3` avec la gestion explicite des déclarations de types externes nécessaires au type-check et à l'intégration IDE.
|
||||
|
||||
Le correctif formalise l'ordre de décision suivant :
|
||||
|
||||
```text
|
||||
package consommé
|
||||
↓
|
||||
types TypeScript embarqués ?
|
||||
├─ oui → les utiliser, sans @types redondant
|
||||
└─ non → rechercher @types/<package> ou une déclaration maintenue équivalente
|
||||
↓
|
||||
vérifier besoin et compatibilité
|
||||
↓
|
||||
classer correctement dans package.json
|
||||
```
|
||||
|
||||
Pour une application privée, les packages de déclarations nécessaires seulement au développement `SHOULD` normalement appartenir à `devDependencies`. `@types/node` et `@types/bootstrap` sont des exemples conditionnels, pas des dépendances PGR universelles.
|
||||
|
||||
Le template `package.json` minimal reste volontairement inchangé : PGR ne connaît ni les dépendances réelles, ni leurs versions, ni la version TypeScript au niveau générique.
|
||||
|
||||
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/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
|
||||
```
|
||||
|
||||
ADD :
|
||||
|
||||
```text
|
||||
deltas/0.1.1/alpha.3.fix.1.md
|
||||
```
|
||||
|
||||
DELETE : aucun.
|
||||
|
||||
`templates/web-typescript/package.json`, `templates/web-typescript/tsconfig.json`, `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.fix.1.md` n'est anticipé.
|
||||
|
||||
## Règles ajoutées
|
||||
|
||||
Le correctif précise que :
|
||||
|
||||
- un package qui fournit déjà ses propres déclarations TypeScript ne doit pas recevoir arbitrairement un `@types/*` redondant ;
|
||||
- lorsqu'une dépendance utilisée depuis TypeScript ne fournit pas de déclarations suffisantes, le projet `SHOULD` rechercher un package `@types/<nom>` maintenu ou une autre déclaration appropriée ;
|
||||
- pour une application privée, les déclarations utilisées seulement au développement `SHOULD` normalement être dans `devDependencies` ;
|
||||
- `@types/node` est applicable lorsque du code, de la configuration ou de l'outillage TypeScript utilise réellement l'environnement Node ;
|
||||
- `@types/bootstrap` est applicable lorsque les API JavaScript Bootstrap sont consommées depuis TypeScript et nécessitent des déclarations externes ;
|
||||
- un usage CSS/Sass seul de Bootstrap ne justifie pas `@types/bootstrap` ;
|
||||
- si `compilerOptions.types` est utilisé, les packages de déclarations globales nécessaires doivent être sélectionnés explicitement de manière cohérente ;
|
||||
- pour une bibliothèque publiée, une déclaration externe requise par les `.d.ts` publics doit rester disponible aux consommateurs et ne peut pas être cachée arbitrairement dans les seules `devDependencies` ;
|
||||
- les versions runtime, `@types/*` et TypeScript doivent rester compatibles.
|
||||
|
||||
## Preuve corpus
|
||||
|
||||
Games `0.3.6` exerce déjà :
|
||||
|
||||
```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 pratique sur ses applications Tauri avec `@types/bootstrap` et `@types/node` en `devDependencies`.
|
||||
|
||||
Cette répétition justifie la règle de découverte/classification, pas l'installation universelle de ces packages.
|
||||
|
||||
## Validation opérateur
|
||||
|
||||
Après application du history `PASS`, commit/push de `alpha.3`, puis application du présent delta :
|
||||
|
||||
```bash
|
||||
test "$(cat VERSION)" = '0.1.1-alpha.3.fix.1'
|
||||
git cat-file -e HEAD:history/0.1.1/alpha.3.md
|
||||
test -f history/0.1.1/alpha.3.md
|
||||
test -f deltas/0.1.1/alpha.3.md
|
||||
test -f deltas/0.1.1/alpha.3.fix.1.md
|
||||
test ! -e history/0.1.1/alpha.3.fix.1.md
|
||||
|
||||
grep -A2 '^## Statut$' history/0.1.1/alpha.3.md | grep -Fx 'PASS'
|
||||
grep -Fx '<!-- version: 5 -->' docs/plans/007-V0_1_1_WEB_FRONTEND_FOUNDATION_PLAN.md
|
||||
grep -Fx '<!-- version: 3 -->' docs/rules/530-TYPESCRIPT.md
|
||||
grep -Fx '<!-- version: 3 -->' docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md
|
||||
grep -Fx '<!-- version: 2 -->' 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.3.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 (
|
||||
'Déclarations de types externes et intégration IDE',
|
||||
'fournit déjà ses propres fichiers de déclaration TypeScript',
|
||||
'@types/<nom>',
|
||||
'`devDependencies`',
|
||||
'`@types/node`',
|
||||
'`@types/bootstrap`',
|
||||
'Un projet qui ne consomme que le CSS/Sass de Bootstrap',
|
||||
'`compilerOptions.types`',
|
||||
'bibliothèque publiée',
|
||||
):
|
||||
assert phrase in typescript, phrase
|
||||
|
||||
packages = Path('docs/rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md').read_text(encoding='utf-8')
|
||||
for phrase in (
|
||||
'Dépendances de développement et packages de déclarations',
|
||||
'la dépendance runtime fournit déjà ses propres types',
|
||||
'@types/<nom>',
|
||||
'`@types/node` est pertinent',
|
||||
'`@types/bootstrap` est pertinent',
|
||||
'Le template PGR générique conserve volontairement un `package.json` sans `devDependencies` préremplies',
|
||||
'Pour une bibliothèque publiée',
|
||||
):
|
||||
assert phrase in packages, phrase
|
||||
|
||||
guide = Path('docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md').read_text(encoding='utf-8')
|
||||
for phrase in (
|
||||
'`devDependencies` et déclarations de types',
|
||||
'fournit-il déjà ses propres types ?',
|
||||
'ne pas ajouter un @types redondant',
|
||||
'"@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>"',
|
||||
'qualité TypeScript et à l'expérience IDE',
|
||||
):
|
||||
assert phrase in guide, phrase
|
||||
|
||||
package = json.loads(Path('templates/web-typescript/package.json').read_text(encoding='utf-8'))
|
||||
assert package == {
|
||||
'name': 'project-web',
|
||||
'private': True,
|
||||
'scripts': {'typecheck': 'tsc --noEmit'},
|
||||
}
|
||||
|
||||
tsconfig = json.loads(Path('templates/web-typescript/tsconfig.json').read_text(encoding='utf-8'))
|
||||
assert tsconfig == {
|
||||
'compilerOptions': {
|
||||
'strict': True,
|
||||
'noEmit': True,
|
||||
'noUnusedLocals': True,
|
||||
'noUnusedParameters': True,
|
||||
'noFallthroughCasesInSwitch': True,
|
||||
}
|
||||
}
|
||||
|
||||
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**.',
|
||||
'### alpha.3.fix.1 — déclarations de types externes',
|
||||
'@types/bootstrap + @types/node',
|
||||
'types embarqués → @types si nécessaire',
|
||||
'Vite/CSS/Sass hors scope',
|
||||
):
|
||||
assert phrase in plan, phrase
|
||||
|
||||
assert Path('docs/rules/550-VITE.md').read_text(encoding='utf-8').splitlines()[1] == '<!-- version: 1 -->'
|
||||
assert Path('docs/rules/560-CSS_SASS.md').read_text(encoding='utf-8').splitlines()[1] == '<!-- version: 1 -->'
|
||||
assert Path('docs/rules/710-TAURI.md').read_text(encoding='utf-8').splitlines()[1] == '<!-- version: 6 -->'
|
||||
|
||||
print('0.1.1 alpha.3.fix.1 type declarations audit: clean (bundled types first, conditional @types, app/library dependency roles 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 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 deltas/0.1.1/alpha.3.fix.1.md
|
||||
|
||||
git diff --cached --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
Le scope indexé attendu avant ajout du history du fix est exactement :
|
||||
|
||||
```text
|
||||
M VERSION
|
||||
A deltas/0.1.1/alpha.3.fix.1.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
|
||||
M docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md
|
||||
```
|
||||
|
||||
## Revue opérateur complémentaire
|
||||
|
||||
Confirmer que :
|
||||
|
||||
- `alpha.3` reste historisé `PASS` et son delta n'est pas réécrit ;
|
||||
- le fix n'ajoute aucune dépendance fictive au template générique `package.json` ;
|
||||
- les `@types/*` ne sont recherchés qu'après vérification des types embarqués ;
|
||||
- `@types/node` et `@types/bootstrap` restent des exemples conditionnels ;
|
||||
- les applications privées et les bibliothèques publiées conservent des règles de classification distinctes ;
|
||||
- Vite, CSS/Sass, WASM et Tauri restent hors scope du correctif.
|
||||
|
||||
## Transition
|
||||
|
||||
### PASS
|
||||
|
||||
Produire `history/0.1.1/alpha.3.fix.1.md`, l'appliquer puis committer/pousser le fix. Reprendre ensuite la trajectoire normale avec `0.1.1-alpha.4`, consacré à Vite, au dev server, aux caches et aux outputs de production.
|
||||
|
||||
### FAIL
|
||||
|
||||
Consigner le diagnostic réel dans `history/0.1.1/alpha.3.fix.1.md` et rester dans `alpha.3.fix.M`. Le scope MUST rester limité au contrat TypeScript/package tant qu'aucun défaut plus large ne justifie un REPLAN.
|
||||
Reference in New Issue
Block a user