oglap-ggp-node 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,386 @@
+# oglap-ggp-node-js
+
+Implémentation Node.js du protocole **OGLAP** (Offline Grid Location Addressing Protocol) — un système d'adressage déterministe basé sur une grille, conçu pour les régions où les adresses postales formelles sont inexistantes ou peu fiables.
+
+OGLAP génère des **codes LAP** compacts et lisibles (ex. `GN-CON-QYTC-B0B1-2282`) qui identifient de façon unique n'importe quelle coordonnée à l'intérieur d'un pays configuré, hors ligne et sans API externe.
+
+---
+
+## Fonctionnalités
+
+- **Coordonnées → code LAP** — encoder toute position GPS en adresse LAP structurée
+- **Code LAP → coordonnées** — décoder un code LAP vers son centre géographique
+- **Geocodage inversé** — trouver la région administrative, zone et lieu contenant une coordonnée
+- **Parsing & validation de code LAP** — analyser des codes partiels ou complets, valider le format et le contenu
+- **Boîte englobante et centroïde** — calculer bbox et centre à partir de géométries GeoJSON
+- **Entièrement hors ligne** — aucune connexion requise une fois les données chargées
+
+---
+
+## Format du code LAP
+
+Un code LAP encode une localisation à quatre niveaux hiérarchiques :
+
+### Grille locale (5 segments)
+```
+GN  - CON  - QYTC - B0B1 - 2282
+│      │      │      │      └─ Microspot  — 4 chiffres, offset métrique (XX = est, YY = nord)
+│      │      │      └─────── Macrobloc   — 4 chars [A-J][0-9][A-J][0-9], blocs ~100 m dans la zone
+│      │      └────────────── Zone        — 4 chars, indiquant la localite administrative immediate de niveau 8 et plus   (example - QYTC pour Yattaya - Fossedè)
+│      └───────────────────── Région      — 3 chars, code de la localite administrative de niveau 4 ou 6 immediate (example - CON pour Conakry)
+└──────────────────────────── Pays        — code ISO alpha-2 du pays (example - gn pour Guinee)
+```
+
+### Grille nationale (4 segments)
+Utilisée quand une coordonnée se situe en dehors des limites administratives de niveau 8 et au-dessus :
+```
+GN  - NZE  - AABCDE - 4250
+│      │      │        └─ Microspot   — 4 chiffres
+│      │      └────────── Macrobloc   — 6 lettres, grille kilométrique nationale
+│      └──────────────── Région       — 3 chars, code de la localite administrative de niveau 4 ou 6 immediate (example - NZE pour Nzérékoré)
+└─────────────────────── Pays         — code ISO alpha-2 du pays (example - gn pour Guinee)
+```
+
+---
+
+## Démarrage
+
+### 1. Ajouter la dépendance
+
+```bash
+npm install oglap-ggp-node-js
+```
+
+### 2. Préparer les données
+
+Le package nécessite trois fichiers JSON :
+
+| Fichier | Description |
+|---|---|
+| `{country_code}_oglap_country_profile.json` | Paramètres de grille, codes admin, règles de nommage |
+| `{country_code}_localities_naming.json` | Géométries GeoJSON des lieux (régions, zones, localités) |
+| `{country_code}_full.json` | Correspondances place-ID → code OGLAP |
+
+### 3. Initialiser avant toute utilisation
+
+Appeler `initOglap` une seule fois au démarrage de l'application, avant toute autre fonction :
+
+**Mode téléchargement (recommandé)** — les données sont téléchargées et mises en cache localement :
+
+```js
+import { initOglap } from 'oglap-ggp-node-js';
+
+const report = await initOglap({
+  version: 'latest',
+  dataDir: 'oglap-data',      // dossier de cache local
+  forceDownload: false,
+  onProgress({ label, status, percent, step, totalSteps }) {
+    if (status === 'downloading') process.stdout.write(`\r↓ [${step}/${totalSteps}] ${label}: ${percent}%`);
+    if (status === 'cached')      console.log(`⚡ [${step}/${totalSteps}] ${label}: depuis le cache`);
+    if (status === 'done')        console.log(`\r✓ [${step}/${totalSteps}] ${label}: terminé`);
+    if (status === 'error')       console.log(`✗ [${step}/${totalSteps}] ${label}: erreur`);
+  }
+});
+
+if (!report.ok) throw new Error(report.error);
+```
+
+---
+
+## Utilisation
+
+### Encoder des coordonnées en code LAP
+
+```js
+import { coordinatesToLap } from 'oglap-ggp-node-js';
+
+const result = coordinatesToLap(9.5370, -13.6773); // lat, lon — Conakry, Guinée
+
+console.log(result.lapCode);        // GN-CON-QYTC-B0B1-2282
+console.log(result.humanAddress);   // B0B1-2282, Yattaya Fossedè, Conakry, Guinée
+console.log(result.admin_level_2);  // CON  (code de région)
+console.log(result.admin_level_3);  // QYTC (code de zone)
+console.log(result.macroblock);     // B0B1
+console.log(result.microspot);      // 2282
+console.log(result.isNationalGrid); // false
+console.log(result.originLat);      // latitude d'origine de la bbox
+console.log(result.originLon);      // longitude d'origine de la bbox
+```
+
+Retourne `null` si les coordonnées sont hors du territoire.
+
+### Décoder un code LAP en coordonnées
+
+```js
+import { lapToCoordinates } from 'oglap-ggp-node-js';
+
+const coords = lapToCoordinates('GN-CON-QYTC-B0B1-2282');
+
+if (coords) {
+  console.log(`lat: ${coords.lat}, lon: ${coords.lon}`);
+  // lat: 9.5370..., lon: -13.6773...
+}
+
+// Le préfixe pays est optionnel
+const coords2 = lapToCoordinates('GN-CON-QYTC-B0B1-2282');
+```
+
+### Parser et valider un code LAP
+
+```js
+import { validateLapCode, parseLapCode } from 'oglap-ggp-node-js';
+
+// Valider — retourne un message d'erreur, ou null si valide
+const error = validateLapCode('GN-CON-QYTC-B0B1-2282');
+if (error) {
+  console.log('Invalide :', error);
+} else {
+  console.log('Code valide');
+}
+
+// Parser en composants
+const parsed = parseLapCode('GN-CON-QYTC-B0B1-2282');
+if (parsed) {
+  console.log(parsed.admin_level_2_Iso);  // code ISO du pays : GN
+  console.log(parsed.admin_level_3_code); // code de la localite administrative de niveau 4 ou 6 immediate : CON
+  console.log(parsed.admin_level_4_code); // code de la localite administrative de niveau 8 et plus : QYTC
+  console.log(parsed.macroblock);         // B0B1 macrobloc ~100m x 100m dans la zone
+  console.log(parsed.microspot);          // 2282 microspot ~1m x 1m dans la zone
+  console.log(parsed.isNationalGrid);     // false
+}
+
+// Les codes partiels sont aussi supportés
+parseLapCode('GN-CON-QYTC'); // région + zone seulement
+parseLapCode('QYTC');         // zone seulement
+```
+
+### Résoudre un code LAP vers un lieu
+
+```js
+import { getPlaceByLapCode } from 'oglap-ggp-node-js';
+
+const resolved = getPlaceByLapCode('GN-CON-QYTC-B0B1-2282');
+
+if (resolved) {
+  console.log(resolved.originLat); // latitude d'origine de la bbox
+  console.log(resolved.originLon); // longitude d'origine de la bbox
+
+  if (resolved.place) {
+    const addr = resolved.place.address;
+    const name = addr?.village ?? addr?.town ?? addr?.city ?? resolved.place.display_name;
+    console.log(name); // nom du lieu lisible
+  }
+
+  // Accéder aux composants parsés
+  console.log(resolved.parsed.macroblock); // B0B1
+  console.log(resolved.parsed.microspot);  // 2282
+}
+```
+
+### Boîte englobante et centroïde
+
+```js
+import { bboxFromGeometry, centroidFromBbox } from 'oglap-ggp-node-js';
+
+const geometry = {
+  type: 'Polygon',
+  coordinates: [[
+    [-13.70, 9.50],
+    [-13.65, 9.50],
+    [-13.65, 9.55],
+    [-13.70, 9.55],
+    [-13.70, 9.50],
+  ]]
+};
+
+const bbox = bboxFromGeometry(geometry);
+// [minLat, maxLat, minLon, maxLon]
+
+if (bbox) {
+  const center = centroidFromBbox(bbox);
+  // [lat, lon] du point central de la bbox
+  console.log(`Centre : ${center[0]}, ${center[1]}`);
+}
+```
+
+### Accéder aux métadonnées du pays
+
+```js
+import { getCountryCode, getCountrySW, getOglapPrefectures } from 'oglap-ggp-node-js';
+
+console.log(getCountryCode()); // "GN"
+console.log(getCountrySW());   // [lat, lon] du coin sud-ouest
+
+const prefectures = getOglapPrefectures();
+// { [isoCode]: prefectureOglapCode, ... }
+```
+
+---
+
+## Modèles de données
+
+### Résultat de `coordinatesToLap`
+
+| Champ | Type | Description |
+|---|---|---|
+| `lapCode` | `string` | Code LAP complet, ex. `GN-CON-QYTC-B0B1-2282` |
+| `country` | `string` | Code pays, ex. `GN` |
+| `admin_level_2` | `string` | Code de région, ex. `CON` |
+| `admin_level_3` | `string\|null` | Code de zone, ex. `QYTC` |
+| `macroblock` | `string` | Composant macrobloc |
+| `microspot` | `string` | Composant microspot |
+| `isNationalGrid` | `boolean` | `true` si grille nationale utilisée |
+| `displayName` | `string` | Nom du lieu issu du geocodage inversé |
+| `humanAddress` | `string` | Adresse complète lisible |
+| `address` | `object` | Composants d'adresse structurés |
+| `originLat` | `number` | Latitude d'origine de la bbox |
+| `originLon` | `number` | Longitude d'origine de la bbox |
+| `pcode` | `string[]` | P-codes UNOCHA pour la localisation |
+
+### Résultat de `parseLapCode`
+
+| Champ | Type | Description |
+|---|---|---|
+| `admin_level_2_Iso` | `string\|undefined` | Code ISO de la région |
+| `admin_level_3_code` | `string\|undefined` | Code de zone |
+| `macroblock` | `string\|undefined` | Composant macrobloc |
+| `microspot` | `string\|undefined` | Composant microspot |
+| `isNationalGrid` | `boolean` | `true` si grille nationale |
+
+### Résultat de `getPlaceByLapCode`
+
+| Champ | Type | Description |
+|---|---|---|
+| `place` | `object\|null` | Données OSM du lieu |
+| `parsed` | `object` | Composants LAP parsés |
+| `originLat` | `number\|undefined` | Latitude d'origine de la bbox |
+| `originLon` | `number\|undefined` | Longitude d'origine de la bbox |
+
+### Rapport de `initOglap`
+
+| Champ | Type | Description |
+|---|---|---|
+| `ok` | `boolean` | Initialisation réussie |
+| `countryCode` | `string\|null` | Ex. `GN` |
+| `countryName` | `string\|null` | Ex. `Guinée` |
+| `bounds` | `number[][]\|null` | `[[swLat, swLon], [neLat, neLon]]` |
+| `checks` | `Array` | Résultats de validation (`pass`, `warn`, `fail`) |
+| `error` | `string\|null` | Message d'erreur si `!ok` |
+| `dataDir` | `string\|undefined` | Dossier de cache local |
+| `dataLoaded` | `object\|undefined` | Résultat du chargement des lieux |
+
+---
+
+## Exemple complet de bout en bout
+
+```js
+import {
+  initOglap,
+  checkOglap,
+  coordinatesToLap,
+  lapToCoordinates,
+  getPlaceByLapCode,
+  validateLapCode,
+  parseLapCode,
+} from 'oglap-ggp-node-js';
+
+class LocationService {
+  static #initialized = false;
+
+  static async init() {
+    if (this.#initialized) return;
+
+    const report = await initOglap({
+      onProgress({ label, status, percent, step, totalSteps }) {
+        if (status === 'downloading') process.stdout.write(`\r↓ [${step}/${totalSteps}] ${label}: ${percent}%`);
+        if (status === 'cached')      console.log(`⚡ [${step}/${totalSteps}] ${label}: depuis le cache`);
+        if (status === 'done')        console.log(`\r✓ [${step}/${totalSteps}] ${label}: terminé`);
+        if (status === 'error')       console.log(`✗ [${step}/${totalSteps}] ${label}: erreur`);
+      }
+    });
+
+    if (!report.ok) throw new Error(`Initialisation OGLAP échouée : ${report.error}`);
+    this.#initialized = true;
+  }
+
+  /** Encoder la position GPS de l'utilisateur */
+  static encodePosition(lat, lon) {
+    const result = coordinatesToLap(lat, lon);
+    return result?.lapCode ?? null;
+  }
+
+  /** Partager une localisation : retourne le code LAP et l'adresse lisible */
+  static shareLocation(lat, lon) {
+    const result = coordinatesToLap(lat, lon);
+    if (!result) return null;
+    return {
+      code:  result.lapCode,
+      label: result.humanAddress,
+    };
+  }
+
+  /** Naviguer vers un code LAP en le convertissant en coordonnées */
+  static decodeToCoords(lapCode) {
+    return lapToCoordinates(lapCode); // { lat, lon } ou null
+  }
+
+  /** Valider la saisie d'un code LAP par l'utilisateur */
+  static validateInput(input) {
+    return validateLapCode(input); // null = valide, string = message d'erreur
+  }
+
+  /** Résoudre un code LAP vers les détails du lieu */
+  static resolvePlace(lapCode) {
+    const resolved = getPlaceByLapCode(lapCode);
+    if (!resolved?.place) return null;
+
+    const addr = resolved.place.address ?? {};
+    return {
+      name:      addr.village ?? addr.town ?? addr.city ?? resolved.place.display_name,
+      adminCode: resolved.parsed.admin_level_3_code,
+      originLat: resolved.originLat,
+      originLon: resolved.originLon,
+    };
+  }
+}
+
+// Utilisation
+await LocationService.init();
+
+// Encoder
+const code = LocationService.encodePosition(9.660147, -13.588009);
+console.log(code); // GN-CON-QYTC-B0B1-2282
+
+// Décoder
+const coords = LocationService.decodeToCoords(code);
+console.log(coords); // { lat: 9.660147, lon: -13.588009 }
+
+// Partager
+const share = LocationService.shareLocation(9.660147, -13.588009);
+console.log(share.label); // B0B1-2282, Yattaya Fossedè, Conakry, Guinée
+
+// Valider la saisie utilisateur
+const err = LocationService.validateInput('GN-CON-QYTC-B0B1-2282');
+console.log(err); // null (valide)
+
+// Résoudre un lieu
+const place = LocationService.resolvePlace('GN-CON-QYTC-B0B1-2282');
+console.log(place.display_name); // Yattaya Fossedè, Ratoma, Conakry, Guinée
+```
+
+---
+
+## Exécuter les tests
+
+```bash
+node test.js
+```
+
+---
+
+## Informations complémentaires
+
+- **Protocole** : OGLAP est conçu pour la Guinée (`GN`) mais configurable pour tout pays via le fichier profil JSON.
+- **Offline-first** : tout l'encodage et décodage est effectué localement avec les données chargées — aucun réseau requis.
+- **Déterministe** : les mêmes coordonnées produisent toujours le même code LAP, à données identiques.
+- **Bugs** : signaler les problèmes dans le dépôt principal Kiraa.

package/package.json

@@ -1,37 +1,43 @@
 {
   "name": "oglap-ggp-node",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Permettre aux développeurs d'installer rapidement le SDK et ses dépendances pour commencer à l'utiliser dans leurs projets.",
+  "type": "module",
+  "main": "oglap.js",
+  "module": "oglap.js",
+  "exports": {
+    ".": {
+      "import": "./oglap.js",
+      "default": "./oglap.js"
+    }
+  },
+  "files": [
+    "oglap.js",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "@turf/boolean-point-in-polygon": "^7.2.0",
+    "@turf/area": "^7.2.0"
+  },
   "keywords": [
     "oglap",
-    "oglap-ggp",
-    "geolocation",
-    "maps",
+    "ggp",
+    "geocoding",
+    "coordinates",
     "guinea",
-    "conakry",
-    "guinee",
-    "addressing",
-    "protocol",
-    "offline",
-    "address",
-    "offline",
-    "maps",
-    "oglap-maps",
-    "kiraa"
+    "geolocation"
   ],
-  "homepage": "https://github.com/Guinee-IO/oglap-ggp-node-js#readme",
-  "bugs": {
-    "url": "https://github.com/Guinee-IO/oglap-ggp-node-js/issues"
-  },
+  "author": "Guinee IO",
+  "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Guinee-IO/oglap-ggp-node-js.git"
   },
-  "license": "ISC",
-  "author": "Guinee IO",
-  "type": "commonjs",
-  "main": "oglap.js",
-  "scripts": {
-    "test": "node test.js"
-  }
+  "bugs": {
+    "url": "https://github.com/Guinee-IO/oglap-ggp-node-js/issues"
+  },
+  "homepage": "https://github.com/Guinee-IO/oglap-ggp-node-js#readme"
 }

package/test.js

@@ -1,349 +0,0 @@
-// test.js — Full OGLAP engine test
-import {
-    // Init & state
-    initOglap,
-    loadOglap,
-    checkOglap,
-    getPackageVersion,
-    getCountryProfile,
-    getCountryCode,
-    getCountrySW,
-    getOglapPrefectures,
-    getOglapPlaces,
-    // Core functions
-    parseLapCode,
-    validateLapCode,
-    getPlaceByLapCode,
-    lapToCoordinates,
-    coordinatesToLap,
-    bboxFromGeometry,
-    centroidFromBbox,
-} from './oglap.js';
-
-// ── Helpers ──
-let passed = 0, failed = 0;
-function section(title) { console.log(`\n${'═'.repeat(60)}\n  ${title}\n${'═'.repeat(60)}`); }
-function log(label, value) { console.log(`  ${label}:`, value); }
-function ok(label, value) { passed++; console.log(`  ✓ ${label}:`, value); }
-function fail(label, value) { failed++; console.error(`  ✗ ${label}:`, value); }
-
-// ══════════════════════════════════════════════════════════════
-//  1. PRE-INIT STATE
-// ══════════════════════════════════════════════════════════════
-section('1. Pre-init state');
-
-log('Package version', getPackageVersion());
-
-const preCheck = checkOglap();
-if (!preCheck.ok) ok('checkOglap() before init', preCheck.error);
-else fail('checkOglap() should not be ok before init', preCheck);
-
-// ══════════════════════════════════════════════════════════════
-//  2. INIT (download mode)
-// ══════════════════════════════════════════════════════════════
-section('2. initOglap() — downloading latest');
-
-const report = await initOglap({
-    onProgress({ label, status, percent, step, totalSteps }) {
-        if (status === 'downloading') {
-            process.stdout.write(`\r  ↓ [${step}/${totalSteps}] ${label}: ${percent}%   `);
-        } else if (status === 'cached') {
-            console.log(`  ⚡ [${step}/${totalSteps}] ${label}: loaded from cache`);
-        } else if (status === 'slow') {
-            console.log(`\n  ⚠ Slow network detected for ${label}`);
-        } else if (status === 'done') {
-            console.log(`\r  ✓ [${step}/${totalSteps}] ${label}: done              `);
-        } else if (status === 'error') {
-            console.log(`\n  ✗ [${step}/${totalSteps}] ${label}: ERROR`);
-        } else if (status === 'validating') {
-            console.log(`  … Validating configuration`);
-        }
-    }
-});
-
-console.log('\n  --- Init report ---');
-log('OK', report.ok);
-log('Country', `${report.countryName} (${report.countryCode})`);
-log('Bounds', report.bounds);
-log('Data dir', report.dataDir);
-if (report.dataLoaded) log('Places loaded', report.dataLoaded.message);
-console.log('  --- Checks ---');
-report.checks.forEach(c => {
-    const icon = c.status === 'pass' ? '✓' : c.status === 'warn' ? '⚠' : '✗';
-    console.log(`    ${icon} [${c.id}] ${c.message}`);
-});
-
-if (!report.ok) {
-    fail('initOglap failed — cannot continue', report.error);
-    process.exit(1);
-}
-ok('initOglap', 'success');
-
-// ══════════════════════════════════════════════════════════════
-//  3. STATE GETTERS
-// ══════════════════════════════════════════════════════════════
-section('3. State getters');
-
-const postCheck = checkOglap();
-postCheck.ok ? ok('checkOglap()', `ok, country=${postCheck.countryCode}`) : fail('checkOglap()', postCheck);
-
-log('getCountryCode()', getCountryCode());
-log('getCountrySW()', getCountrySW());
-
-const profile = getCountryProfile();
-log('getCountryProfile() schema', profile.schema_id);
-
-const prefectures = getOglapPrefectures();
-const prefKeys = Object.keys(prefectures);
-log('getOglapPrefectures()', `${prefKeys.length} entries (first 5: ${prefKeys.slice(0, 5).join(', ')})`);
-
-const places = getOglapPlaces();
-log('getOglapPlaces()', `${places.length} places`);
-
-// ══════════════════════════════════════════════════════════════
-//  4. coordinatesToLap — encode GPS → LAP code
-// ══════════════════════════════════════════════════════════════
-section('4. coordinatesToLap — GPS → LAP');
-
-const testCoords = [
-    { name: 'Conakry center', lat: 9.5370, lon: -13.6785 },
-    { name: 'Nzérékoré', lat: 7.7562, lon: -8.8179 },
-    { name: 'Kankan', lat: 10.3854, lon: -9.3057 },
-    { name: 'Labé', lat: 11.3183, lon: -12.2860 },
-    { name: 'Kindia', lat: 10.0565, lon: -12.8665 },
-];
-
-const generatedLaps = [];
-for (const { name, lat, lon } of testCoords) {
-    try {
-        const result = coordinatesToLap(lat, lon, places);
-        if (result?.lapCode) {
-            ok(`${name} (${lat}, ${lon})`, `${result.lapCode}  →  ${result.humanAddress}`);
-            generatedLaps.push({ name, lat, lon, lap: result.lapCode, result });
-        } else {
-            fail(`${name} (${lat}, ${lon})`, 'returned null/undefined');
-        }
-    } catch (err) {
-        fail(`${name} (${lat}, ${lon})`, err.message);
-    }
-}
-
-// ══════════════════════════════════════════════════════════════
-//  4b. coordinatesToLap — National grid (fallback for admin_level < 9)
-// ══════════════════════════════════════════════════════════════
-section('4b. coordinatesToLap — National grid');
-
-const nationalTestCoords = [
-    { name: 'Rural Siguiri (Kankan)', lat: 11.70, lon: -9.30 },
-    { name: 'Rural Macenta (Nzérékoré)', lat: 8.40, lon: -9.40 },
-    { name: 'Rural Boké (Boké)', lat: 11.20, lon: -14.20 },
-    { name: 'Rural Faranah (Faranah)', lat: 10.10, lon: -10.80 },
-];
-
-const generatedNationalLaps = [];
-for (const { name, lat, lon } of nationalTestCoords) {
-    try {
-        const result = coordinatesToLap(lat, lon, places);
-        if (result?.lapCode) {
-            if (result.isNationalGrid) {
-                ok(`${name} (${lat}, ${lon})`, `${result.lapCode}  →  ${result.humanAddress}  [NATIONAL]`);
-            } else {
-                ok(`${name} (${lat}, ${lon})`, `${result.lapCode}  →  ${result.humanAddress}  [LOCAL — zone found]`);
-            }
-            generatedNationalLaps.push({ name, lat, lon, lap: result.lapCode, result });
-        } else {
-            fail(`${name} (${lat}, ${lon})`, 'returned null/undefined');
-        }
-    } catch (err) {
-        fail(`${name} (${lat}, ${lon})`, err.message);
-    }
-}
-
-// Verify at least one is actually national grid
-const nationalCount = generatedNationalLaps.filter(g => g.result.isNationalGrid).length;
-if (nationalCount > 0) {
-    ok('National grid coverage', `${nationalCount}/${generatedNationalLaps.length} used national grid`);
-} else {
-    fail('National grid coverage', 'None of the test coordinates triggered national grid fallback — adjust coordinates');
-}
-
-// Merge into generatedLaps for sections 5-10
-generatedLaps.push(...generatedNationalLaps);
-
-// ══════════════════════════════════════════════════════════════
-//  4c. coordinatesToLap — Out-of-bounds rejection
-// ══════════════════════════════════════════════════════════════
-section('4c. coordinatesToLap — Out-of-bounds rejection');
-
-const outOfBoundsCoords = [
-    // Far away — caught by bbox
-    { name: 'Dakar, Senegal', lat: 14.6928, lon: -17.4467 },
-    { name: 'Atlantic Ocean', lat: 9.00, lon: -18.00 },
-    // Inside bbox but outside Guinea polygon — caught by country border check
-    { name: 'Bamako, Mali', lat: 12.6392, lon: -8.0029 },
-    { name: 'Freetown, Sierra Leone', lat: 8.4657, lon: -13.2317 },
-    // Tricky: neighboring countries very close to Guinea border
-    { name: 'Bissau, Guinea-Bissau', lat: 11.8617, lon: -15.5977 },
-    { name: 'Monrovia, Liberia', lat: 6.3156, lon: -10.8074 },
-    { name: 'Kédougou, Senegal (near GN border)', lat: 12.5605, lon: -12.1747 },
-];
-
-for (const { name, lat, lon } of outOfBoundsCoords) {
-    try {
-        const result = coordinatesToLap(lat, lon, places);
-        if (result === null) {
-            ok(`${name} (${lat}, ${lon})`, 'correctly rejected — outside country bounds');
-        } else {
-            fail(`${name} (${lat}, ${lon})`, `should be null but got ${result.lapCode}`);
-        }
-    } catch (err) {
-        fail(`${name} (${lat}, ${lon})`, err.message);
-    }
-}
-
-// ══════════════════════════════════════════════════════════════
-//  5. parseLapCode — parse a LAP code into segments
-// ══════════════════════════════════════════════════════════════
-section('5. parseLapCode');
-
-for (const { name, lap } of generatedLaps) {
-    try {
-        const parsed = parseLapCode(lap);
-        parsed ? ok(`parse "${lap}"`, JSON.stringify(parsed)) : fail(`parse "${lap}"`, 'returned null');
-    } catch (err) {
-        fail(`parse "${lap}"`, err.message);
-    }
-}
-
-// ══════════════════════════════════════════════════════════════
-//  6. validateLapCode
-// ══════════════════════════════════════════════════════════════
-section('6. validateLapCode');
-
-for (const { lap } of generatedLaps) {
-    try {
-        const result = validateLapCode(lap);
-        // null = valid (no error), string = error message
-        result === null ? ok(`validate "${lap}"`, 'valid') : fail(`validate "${lap}"`, result);
-    } catch (err) {
-        fail(`validate "${lap}"`, err.message);
-    }
-}
-
-// Test with an invalid code — should return an error string
-try {
-    const bad = validateLapCode('QQ-ZZZ-GARBAGE');
-    bad ? ok('validate invalid "QQ-ZZZ-GARBAGE"', bad) : fail('validate invalid should return error string', 'got null');
-} catch (err) {
-    ok('validate invalid throws', err.message);
-}
-
-// ══════════════════════════════════════════════════════════════
-//  7. lapToCoordinates — decode LAP → GPS
-// ══════════════════════════════════════════════════════════════
-section('7. lapToCoordinates — LAP → GPS');
-
-// lapToCoordinates(lapCode) — just pass the LAP code string
-for (const { name, lat, lon, lap, result: encResult } of generatedLaps) {
-    try {
-        const parsed = parseLapCode(lap);
-        const grid = parsed.isNationalGrid ? 'national' : 'local';
-        const coords = lapToCoordinates(lap);
-        if (coords) {
-            const dist = Math.sqrt((coords.lat - lat) ** 2 + (coords.lon - lon) ** 2);
-            ok(`decode "${lap}" [${grid}]`, `lat=${coords.lat.toFixed(6)}, lon=${coords.lon.toFixed(6)} (Δ≈${(dist * 111320).toFixed(1)}m from original)`);
-        } else {
-            fail(`decode "${lap}" [${grid}]`, 'returned null');
-        }
-    } catch (err) {
-        fail(`decode "${lap}"`, err.message);
-    }
-}
-
-// Test without country prefix (strip "GN-" from a code)
-try {
-    const sampleLap = generatedLaps[0]?.lap;
-    if (sampleLap && sampleLap.startsWith(getCountryCode() + '-')) {
-        const withoutCC = sampleLap.slice(getCountryCode().length + 1);
-        const coords = lapToCoordinates(withoutCC);
-        coords ? ok(`decode without CC "${withoutCC}"`, `lat=${coords.lat.toFixed(6)}, lon=${coords.lon.toFixed(6)}`)
-               : fail(`decode without CC "${withoutCC}"`, 'returned null');
-    }
-} catch (err) {
-    fail('decode without CC', err.message);
-}
-
-// ══════════════════════════════════════════════════════════════
-//  8. getPlaceByLapCode — look up place from LAP code
-// ══════════════════════════════════════════════════════════════
-section('8. getPlaceByLapCode');
-
-for (const { lap } of generatedLaps) {
-    try {
-        // getPlaceByLapCode returns { place, parsed, originLat?, originLon? }
-        const match = getPlaceByLapCode(lap);
-        if (match?.place) {
-            const addr = match.place.address || {};
-            const pName = addr.village || addr.town || addr.city || addr.suburb || '(unnamed)';
-            ok(`lookup "${lap}"`, `place_id=${match.place.place_id}, name="${pName}"`);
-        } else if (match) {
-            ok(`lookup "${lap}"`, `matched (parsed: ${JSON.stringify(match.parsed)}, no place — likely national grid)`);
-        } else {
-            log(`lookup "${lap}"`, 'no match found');
-        }
-    } catch (err) {
-        fail(`lookup "${lap}"`, err.message);
-    }
-}
-
-// ══════════════════════════════════════════════════════════════
-//  9. bboxFromGeometry & centroidFromBbox
-// ══════════════════════════════════════════════════════════════
-section('9. bboxFromGeometry & centroidFromBbox');
-
-const samplePlace = places.find(p => p.geojson?.type === 'Polygon' || p.geojson?.type === 'MultiPolygon');
-if (samplePlace) {
-    try {
-        const bbox = bboxFromGeometry(samplePlace.geojson);
-        ok('bboxFromGeometry', JSON.stringify(bbox));
-
-        const centroid = centroidFromBbox(bbox);
-        ok('centroidFromBbox', JSON.stringify(centroid));
-    } catch (err) {
-        fail('bboxFromGeometry/centroidFromBbox', err.message);
-    }
-} else {
-    log('skip', 'no polygon geometry found in places');
-}
-
-// ══════════════════════════════════════════════════════════════
-//  10. Round-trip: encode → decode → re-encode
-// ══════════════════════════════════════════════════════════════
-section('10. Round-trip consistency');
-
-for (const { name, lat, lon, lap, result: encResult } of generatedLaps) {
-    try {
-        const parsed = parseLapCode(lap);
-        const grid = parsed.isNationalGrid ? 'national' : 'local';
-        const decoded = lapToCoordinates(lap);
-        if (!decoded) { fail(`round-trip ${name} [${grid}]`, 'decode returned null'); continue; }
-        const reResult = coordinatesToLap(decoded.lat, decoded.lon, places);
-        const reEncoded = reResult?.lapCode;
-        if (reEncoded === lap) {
-            ok(`${name} [${grid}]: encode→decode→encode`, `${lap} ✓`);
-        } else {
-            fail(`${name} [${grid}]: encode→decode→encode`, `${lap} → (${decoded.lat},${decoded.lon}) → ${reEncoded}`);
-        }
-    } catch (err) {
-        fail(`round-trip ${name}`, err.message);
-    }
-}
-
-// ══════════════════════════════════════════════════════════════
-//  SUMMARY
-// ══════════════════════════════════════════════════════════════
-section('SUMMARY');
-console.log(`  Passed: ${passed}`);
-console.log(`  Failed: ${failed}`);
-console.log(`  Total:  ${passed + failed}`);
-process.exit(failed > 0 ? 1 : 0);