passerelle-geo-components 0.2.0-alpha.1

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "passerelle-geo-components",
+  "version": "0.2.0-alpha.1",
+  "description": "Web Components pour cartes MapLibre + composants controllers pilotes - brique commune multi-projet avec contract SceneManifest V0.3.1. Zero dependance runtime, ES module, encapsulation Shadow DOM.",
+  "type": "module",
+  "main": "geo-components.js",
+  "module": "geo-components.js",
+  "exports": {
+    ".": "./geo-components.js",
+    "./schemas/scene-manifest": "./schemas/scene_manifest.schema.json",
+    "./schemas/scene-manifest-zod": "./schemas/scene_manifest.zod.ts"
+  },
+  "files": [
+    "geo-components.js",
+    "README.md",
+    "schemas/scene_manifest.schema.json",
+    "schemas/scene_manifest.zod.ts",
+    "schemas/scene_manifest.pydantic.py",
+    "examples/*.json"
+  ],
+  "scripts": {
+    "test": "node _selftest.mjs",
+    "test:schemas": "node scripts/test-schemas.mjs",
+    "build:zod": "json-schema-to-zod -i schemas/scene_manifest.schema.json -o schemas/scene_manifest.zod.ts --name SceneManifestSchema",
+    "build:pydantic": "datamodel-codegen --input schemas/scene_manifest.schema.json --input-file-type jsonschema --output schemas/scene_manifest.pydantic.py --output-model-type pydantic_v2.BaseModel --field-constraints --use-double-quotes --strict-nullable",
+    "build:schemas": "npm run build:zod && npm run build:pydantic",
+    "validate:examples": "for f in examples/*.json; do ajv validate -s schemas/scene_manifest.schema.json -d \"$f\" --spec=draft2020 || exit 1; done",
+    "sync-schema": "node scripts/sync-schema-from-qgis-sspcloud.mjs",
+    "prepack": "node -e \"const fs=require('fs');fs.copyFileSync('README.md','.README.repo.md.bak');fs.copyFileSync('NPM-README.md','README.md');\"",
+    "postpack": "node -e \"const fs=require('fs');if(fs.existsSync('.README.repo.md.bak')){fs.copyFileSync('.README.repo.md.bak','README.md');fs.unlinkSync('.README.repo.md.bak');}\""
+  },
+  "devDependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "ajv-cli": "^5.0.0",
+    "json-schema-to-zod": "^2.4.0",
+    "@apidevtools/json-schema-ref-parser": "^11.0.0"
+  },
+  "keywords": [
+    "geospatial",
+    "maplibre",
+    "web-components",
+    "custom-elements",
+    "cartography",
+    "scene-manifest",
+    "storymap",
+    "three-js",
+    "grist-widget",
+    "qgis"
+  ],
+  "author": "Nicolas LAVAL <laval.nicolas13@gmail.com>",
+  "license": "EUPL-1.2",
+  "peerDependencies": {
+    "maplibre-gl": "^5.6.1",
+    "geoai-kit": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": false
+    },
+    "geoai-kit": {
+      "optional": true
+    }
+  },
+  "sideEffects": [
+    "geo-components.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nic01asFr/Passerelle.git",
+    "directory": "sdk/js/geo-components"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "dev"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,125 @@
+# Schemas — 3 dialectes du contract SceneManifest V0.3.1
+
+Ce dossier contient les **3 dialectes** du contract `SceneManifest V0.3.1` :
+
+- **`scene_manifest.schema.json`** — JSON Schema 2020-12 **canonique** (source de vérité)
+- **`scene_manifest.zod.ts`** — Zod TypeScript (généré depuis JSON Schema)
+- **`scene_manifest.pydantic.py`** — Pydantic Python (généré depuis JSON Schema)
+
+Voir [`../CONTRACT-V0.3.1.md`](../CONTRACT-V0.3.1.md) pour la spec humaine complète.
+
+## Source de vérité
+
+**Seul `scene_manifest.schema.json` est édité manuellement.** Les deux autres dialectes sont **générés automatiquement** via la CI.
+
+Rationale : garantir round-trip Zod ⇔ Pydantic ⇔ JSON Schema sans divergence (P0-G de la revue adversariale 2026-07-10).
+
+## Pipeline de génération
+
+```
+scene_manifest.schema.json  (édité manuellement)
+        │
+        ├──▶ datamodel-code-generator ──▶ scene_manifest.pydantic.py
+        │
+        └──▶ json-schema-to-zod ────────▶ scene_manifest.zod.ts
+```
+
+### Prérequis
+
+Dependencies déjà déclarées dans `../package.json` (à ajouter en Chantier 1c) :
+
+```json
+{
+  "devDependencies": {
+    "json-schema-to-zod": "^2.4.0",
+    "@apidevtools/json-schema-ref-parser": "^11.0.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1"
+  }
+}
+```
+
+Python (via pip pour la CI ou local venv) :
+
+```
+datamodel-code-generator[http]==0.30.0
+pydantic==2.9.2
+```
+
+### Commandes de génération
+
+Depuis le dossier `sdk/js/geo-components/` :
+
+```bash
+# 1. Valider le JSON Schema (draft 2020-12)
+pnpm exec ajv validate -s schemas/scene_manifest.schema.json -d examples/minimal.json --spec=draft2020
+
+# 2. Générer Zod TypeScript
+pnpm exec json-schema-to-zod \
+  -i schemas/scene_manifest.schema.json \
+  -o schemas/scene_manifest.zod.ts \
+  --name SceneManifestSchema
+
+# 3. Générer Pydantic Python
+datamodel-codegen \
+  --input schemas/scene_manifest.schema.json \
+  --input-file-type jsonschema \
+  --output schemas/scene_manifest.pydantic.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --field-constraints \
+  --use-double-quotes \
+  --use-title-as-name \
+  --strict-nullable
+```
+
+### Tests de round-trip
+
+```bash
+# Valide les 8 exemples canoniques contre les 3 dialectes
+pnpm run test:schemas
+```
+
+Détail des vérifications :
+1. Chaque `examples/*.json` valide contre `scene_manifest.schema.json` via AJV
+2. Chaque `examples/*.json` parse successfully en Zod via `SceneManifestSchema.parse(json)`
+3. Chaque `examples/*.json` valide en Pydantic via `SceneManifest.model_validate(json)`
+4. Round-trip `dict → Pydantic → dict` identique
+5. Round-trip `json → Zod → json` identique
+
+## État actuel (2026-07-10)
+
+- ✅ `scene_manifest.schema.json` (canonique) — 905 lignes, JSON valide
+- ⏳ `scene_manifest.zod.ts` — à générer (Chantier 1c continuation)
+- ⏳ `scene_manifest.pydantic.py` — à générer (Chantier 1c continuation)
+- ⏳ 8 exemples canoniques — à rédiger (Chantier 1d)
+- ⏳ CI workflow `.github/workflows/geo-components-ci.yml` — à créer (Chantier 5)
+
+## Convention de versioning
+
+- Le fichier `scene_manifest.schema.json` porte le champ `$id` avec version :
+  `https://nic01asfr.github.io/Passerelle/schemas/scene_manifest/0.3.1.json`
+- Toute modification du JSON Schema **DOIT** :
+  - Bumper le patch (`0.3.1 → 0.3.2`) si extension non-breaking
+  - Bumper le minor (`0.3.x → 0.4.0`) si breaking-safe (nouveaux champs ajoutés à des unions ouvertes)
+  - Bumper le major (`0.x.y → 1.0.0`) si breaking-hard (renommages, suppressions)
+- Compatibilité descendante 2 versions mineures : `0.3.x` accepte tout `0.3.y` avec `y ≤ x`
+- Une PR modifiant le JSON Schema **DOIT** re-générer les 2 autres dialectes dans le même commit (via CI hook pré-merge)
+
+## Hébergement public du schema
+
+Le fichier `scene_manifest.schema.json` sera publié sur GitHub Pages via `https://nic01asfr.github.io/Passerelle/schemas/scene_manifest/0.3.1.json` pour que :
+
+- L'attribut `$schema` des manifests V0.3.1 pointe vers une URL résolvable
+- Les éditeurs JSON (VS Code, IntelliJ) autocomplètent depuis le schema publié
+- Les consommateurs externes (partenaires, agents LLM tiers) peuvent le référencer sans dépendre du repo Passerelle
+
+Pipeline GitHub Pages : à mettre en place au commit npm publish 0.2.0 (Chantier 6).
+
+## Références
+
+- [CONTRACT-V0.3.1.md](../CONTRACT-V0.3.1.md) — spec humaine complète
+- [SPRINT-V0.2-STATUS.md](../SPRINT-V0.2-STATUS.md) — tracker Sprint V0.2 convergence
+- [MIGRATION.md](../MIGRATION.md) — état d'adoption cross-projet
+- JSON Schema 2020-12 spec : https://json-schema.org/draft/2020-12/schema
+- datamodel-code-generator : https://github.com/koxudaxi/datamodel-code-generator
+- json-schema-to-zod : https://github.com/StefanTerdell/json-schema-to-zod