@linklabjs/core 0.1.0

package/src/scenarios/test-metro-paris/queries.ts

@@ -0,0 +1,152 @@
+/**
+ * queries.ts — Requêtes métro Paris
+ *
+ * Remplace les config*.json éparpillés.
+ * Chaque requête a un nom, une description, et des paramètres typés.
+ *
+ * Usage :
+ *   tsx cli/run-scenario.ts scenarios/test-metro-paris --query chatelet-opera
+ *   tsx cli/run-scenario.ts scenarios/test-metro-paris --query all
+ */
+
+import type { PathQuery } from '../../types/index.js'
+
+export interface NamedQuery {
+  name: string
+  description: string
+  query: PathQuery
+}
+
+export const metroQueries: NamedQuery[] = [
+
+  // ============================================================
+  // TRAJETS SIMPLES — Une seule ligne, pas de correspondance
+  // ============================================================
+
+  {
+    name: 'chatelet-opera',
+    description: 'Châtelet → Opéra (Ligne 7, 2 stations, ~3 min)',
+    query: {
+      from: 'Station-chatelet',
+      to: 'Station-opera',
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'ligne1-terminus',
+    description: 'La Défense → Château de Vincennes (Ligne 1 complète, ~45 min)',
+    query: {
+      from: 'Station-la-defense-grande-arche',
+      to: 'Station-chateau-de-vincennes',
+      maxPaths: 1
+    }
+  },
+
+  {
+    name: 'ligne4-nord-sud',
+    description: 'Porte de Clignancourt → Mairie de Montrouge (Ligne 4 complète)',
+    query: {
+      from: 'Station-porte-de-clignancourt',
+      to: 'Station-mairie-de-montrouge',
+      maxPaths: 1
+    }
+  },
+
+  // ============================================================
+  // TRAJETS AVEC CORRESPONDANCES — Teste le pathfinder
+  // ============================================================
+
+  {
+    name: 'republique-bastille',
+    description: 'République → Bastille (plusieurs chemins via L5, L8, L9)',
+    query: {
+      from: 'Station-republique',
+      to: 'Station-bastille',
+      maxPaths: 5
+    }
+  },
+
+  {
+    name: 'gare-du-nord-montparnasse',
+    description: 'Gare du Nord → Montparnasse (correspondance obligatoire)',
+    query: {
+      from: 'Station-gare-du-nord',
+      to: 'Station-montparnasse-bienvenue',
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'defense-nation',
+    description: 'La Défense → Nation (traversée Est-Ouest, Ligne 1)',
+    query: {
+      from: 'Station-la-defense-grande-arche',
+      to: 'Station-nation',
+      maxPaths: 3
+    }
+  },
+
+  // ============================================================
+  // TRAJETS COMPLEXES — Hubs majeurs, longue distance
+  // ============================================================
+
+  {
+    name: 'saint-denis-chatillon',
+    description: 'Saint-Denis Université → Châtillon-Montrouge (Ligne 13 complète)',
+    query: {
+      from: 'Station-saint-denis-universite',
+      to: 'Station-chatillon-montrouge',
+      maxPaths: 2
+    }
+  },
+
+  {
+    name: 'vincennes-defense',
+    description: 'Château de Vincennes → La Défense (traversée complète Ligne 1)',
+    query: {
+      from: 'Station-chateau-de-vincennes',
+      to: 'Station-la-defense-grande-arche',
+      maxPaths: 1
+    }
+  },
+
+  {
+    name: 'clignancourt-vincennes',
+    description: 'Porte de Clignancourt → Château de Vincennes (diagonale NW→SE)',
+    query: {
+      from: 'Station-porte-de-clignancourt',
+      to: 'Station-chateau-de-vincennes',
+      maxPaths: 5
+    }
+  },
+
+  // ============================================================
+  // TOURISME — Stations emblématiques
+  // ============================================================
+
+  {
+    name: 'louvre-tour-eiffel',
+    description: 'Louvre-Rivoli → Trocadéro (musées)',
+    query: {
+      from: 'Station-louvre-rivoli',
+      to: 'Station-trocadero',
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'notre-dame-sacre-coeur',
+    description: 'Cité → Abbesses (Notre-Dame → Sacré-Cœur)',
+    query: {
+      from: 'Station-cite',
+      to: 'Station-abbesses',
+      maxPaths: 3
+    }
+  }
+]
+
+/**
+ * Requête par défaut (utilisée sans --query)
+ */
+export const defaultQuery = metroQueries.find(q => q.name === 'chatelet-opera')!

package/src/scenarios/test-metro-paris/stack.json

@@ -0,0 +1 @@
+[]

package/src/scenarios/test-musicians/config.json

@@ -0,0 +1,10 @@
+{
+  "mode": "PATHFIND",
+  "description": "Trouver la chaîne de sampling entre deux artistes",
+  "pathQuery": {
+    "from": "Artist-Will-Smith",
+    "to": "Artist-Manu-Dibango",
+    "maxPaths": 3,
+    "maxHops": 8
+  }
+}

package/src/scenarios/test-musicians/graph.json

@@ -0,0 +1,20 @@
+{
+  "nodes": [
+    { "id": "Artist-Manu-Dibango", "type": "entity" },
+    { "id": "Artist-Michael-Jackson", "type": "entity" },
+    { "id": "Artist-Will-Smith", "type": "entity" },
+    { "id": "Track-Soul-Makossa", "type": "entity" },
+    { "id": "Track-Wanna-Be-Startin", "type": "entity" },
+    { "id": "Track-Gettin-Jiggy", "type": "entity" }
+  ],
+  "edges": [
+    { "name": "created", "from": "Artist-Manu-Dibango", "to": "Track-Soul-Makossa", "via": "artist_tracks", "weight": 1 },
+    { "name": "created", "from": "Artist-Michael-Jackson", "to": "Track-Wanna-Be-Startin", "via": "artist_tracks", "weight": 1 },
+    { "name": "created", "from": "Artist-Will-Smith", "to": "Track-Gettin-Jiggy", "via": "artist_tracks", "weight": 1 },
+    { "name": "samples", "from": "Track-Wanna-Be-Startin", "to": "Track-Soul-Makossa", "via": "track_samples", "weight": 3 },
+    { "name": "samples", "from": "Track-Gettin-Jiggy", "to": "Track-Wanna-Be-Startin", "via": "track_samples", "weight": 3 },
+    { "name": "credited_on", "from": "Track-Soul-Makossa", "to": "Artist-Manu-Dibango", "via": "artist_tracks", "weight": 1 },
+    { "name": "credited_on", "from": "Track-Wanna-Be-Startin", "to": "Artist-Michael-Jackson", "via": "artist_tracks", "weight": 1 },
+    { "name": "credited_on", "from": "Track-Gettin-Jiggy", "to": "Artist-Will-Smith", "via": "artist_tracks", "weight": 1 }
+  ]
+}

package/src/scenarios/test-musicians/stack.json

@@ -0,0 +1 @@
+[]

package/src/scenarios/test-netflix/MIGRATION.md

@@ -0,0 +1,23 @@
+# Migration depuis l'ancien scénario Netflix
+
+## Fichiers supprimés
+
+| Fichier | Raison |
+|---------|--------|
+| `actions.ts` | Mode SCHEDULE mis de côté — remplacé par `queries.ts` |
+| `stack.json` | Pile pré-chargée pour SCHEDULE — plus pertinente |
+
+## Fichiers remplacés
+
+| Ancien | Nouveau | Changement |
+|--------|---------|------------|
+| `config.json` mode `SCHEDULE` | `config.json` mode `NAVIGATE` | Abandon de SCHEDULE |
+| `graph.json` conceptuel (Directors/Actors/Genres) | `graph.json` généré par pipeline | Remplacement complet |
+
+## Fichiers ajoutés
+
+| Fichier | Description |
+|---------|-------------|
+| `data/` | 8 fichiers JSON + synonyms.json |
+| `queries.ts` | 10 requêtes NAVIGATE/PATHFIND |
+| `README.md` | Documentation complète |

package/src/scenarios/test-netflix/README.md

@@ -0,0 +1,138 @@
+# Scénario Netflix
+
+Démonstration du **pipeline amont** de LinkLab sur des données JSON réelles.
+
+Ce scénario est le seul qui illustre les deux côtés de LinkLab :
+
+```
+Pipeline amont   JsonSchemaExtractor → SchemaAnalyzer → GraphBuilder
+                 → GraphAssembler → GraphOptimizer → graph.json
+
+Pipeline aval    PathFinder → NavigationEngine → résultats
+```
+
+Le `graph.json` de ce scénario **n'est pas écrit à la main** — il est généré
+automatiquement depuis les 8 fichiers JSON dans `data/`.
+
+---
+
+## Structure des données
+
+```
+data/
+  categories.json    18 entrées   id, name
+  companies.json     vide
+  credits.json       2 957 entrées  id, movieId, personId, jobId
+  departments.json   4 entrées    id, name
+  jobs.json          28 entrées   id, name, departmentId
+  movies.json        200 entrées  id, title, categories[], releaseYear, ...
+  people.json        2 363 entrées  id, gender, name
+  users.json         5 entrées    id, name, isAdmin, preferences{}
+  synonyms.json      synonymes projet (person→people, movie→movies, ...)
+```
+
+### Relations FK détectées automatiquement
+
+| Colonne | Résolution | Stratégie |
+|---------|------------|-----------|
+| `credits.movieId` | → `movies.id` | pluriel régulier +s |
+| `credits.personId` | → `people.id` | synonyme universel (person→people) |
+| `credits.jobId` | → `jobs.id` | synonyme projet (job→jobs) |
+| `jobs.departmentId` | → `departments.id` | correspondance directe |
+
+---
+
+## Graphe généré
+
+```
+7 nœuds   movies, people, credits, jobs, departments, categories, users
+66 arêtes
+  physical         × 4   FK déclarées
+  physical_reverse × 4   inverses automatiques
+  semantic_view    × 56  movies ↔ people pour chacun des 28 jobs
+  virtual          × 2   movies ↔ categories (array inline)
+```
+
+### Pourquoi 56 vues sémantiques ?
+
+`credits` est un pivot entre `movies` et `people` avec un discriminant `jobId → jobs`.
+Le `GraphBuilder` lit la table `jobs` (28 entrées) et génère automatiquement une
+paire d'arêtes sémantiques par job :
+
+```
+movies → people  [actor]          condition: { jobId: 1 }
+people → movies  [actor_in]       condition: { jobId: 1 }
+movies → people  [director]       condition: { jobId: 2 }
+people → movies  [director_in]    condition: { jobId: 2 }
+movies → people  [writer]         condition: { jobId: 3 }
+...
+```
+
+Sans le pipeline, ces 56 relations devraient être écrites à la main.
+
+---
+
+## Lancer le scénario
+
+```bash
+# Requête par défaut (directors-of-movie)
+tsx cli/run-scenario.ts scenarios/test-netflix
+
+# Requêtes disponibles
+tsx cli/run-scenario.ts scenarios/test-netflix --query actors-of-movie
+tsx cli/run-scenario.ts scenarios/test-netflix --query movies-of-director
+tsx cli/run-scenario.ts scenarios/test-netflix --query movies-to-departments
+tsx cli/run-scenario.ts scenarios/test-netflix --query people-to-movies-minhops
+tsx cli/run-scenario.ts scenarios/test-netflix --query all
+```
+
+### Requêtes disponibles
+
+| Nom | Description |
+|-----|-------------|
+| `directors-of-movie` | movies → people via vue `director` |
+| `actors-of-movie` | movies → people via vue `actor` |
+| `movies-of-director` | people → movies via vue `director_in` |
+| `movies-of-actor` | people → movies via vue `actor_in` |
+| `credits-to-jobs` | navigation physique credits → jobs |
+| `jobs-to-departments` | navigation physique jobs → departments |
+| `movies-to-categories` | relation virtuelle (array inline) |
+| `movies-to-departments` | 2 sauts : movies → credits → jobs → departments |
+| `people-to-departments` | 3 sauts via credits → jobs → departments |
+| `people-to-movies-minhops` | chemin le plus court avec `minHops` |
+
+---
+
+## Régénérer le graphe
+
+Si tu modifies les données, relance le pipeline pour régénérer `graph.json` :
+
+```bash
+tsx cli/run-pipeline.ts scenarios/test-netflix/data --out scenarios/test-netflix/graph.json
+```
+
+Le pipeline utilise `data/synonyms.json` pour résoudre les FK irrégulières
+(`personId → people`, `jobId → jobs`) en complément de `config/synonyms.json`
+(synonymes universels).
+
+---
+
+## Ce que ce scénario ne couvre pas
+
+| Donnée | Raison |
+|--------|--------|
+| `movies.categories` (array inline) | Relation virtuelle générée, mais sans garantie de correspondance exacte des ids |
+| `users.preferences` (objet imbriqué) | Pas de FK — structure non relationnelle |
+| `people/` et `movies/` (sous-dossiers détail) | Fichiers enrichis pour l'application — hors scope du pipeline |
+| `companies.json` (vide) | Ignoré automatiquement |
+
+---
+
+## Comparaison avec les autres scénarios
+
+| Scénario | Source | Ce qu'il démontre |
+|----------|--------|-------------------|
+| **Netflix** | JSON → pipeline | pipeline amont + vues sémantiques auto-générées |
+| Musiciens | graph manuel | PATHFIND, `via`, `minHops`, cycles |
+| Métro Paris | graph manuel | Dijkstra, poids, transferPenalty |
+| DVDRental | PostgreSQL → pipeline | FK implicites, SchemaExtractor SQL |

package/src/scenarios/test-netflix/actions.ts

@@ -0,0 +1,92 @@
+/**
+ * Actions du scénario Netflix
+ *
+ * Simule le parcours d'un utilisateur qui :
+ *   1. Voit la liste des films d'un réalisateur (déjà en contexte)
+ *   2. Sélectionne un film
+ *   3. Navigue vers les acteurs
+ *   4. Sélectionne un acteur
+ *   5. Explore les options à partir de cet acteur
+ */
+
+import type { ScheduleAction, Frame } from '../../types/index.js'
+
+const actions: ScheduleAction[] = [
+  {
+    name: 'selectMovie',
+    weight: 10,
+    // Movies est résolu (liste chargée) mais pas encore d'ID choisi
+    when: (stack: Frame[]) => {
+      const movies = stack.find(f => f.entity === 'Movies')
+      return movies?.state === 'RESOLVED' && movies.id == null
+    },
+    execute: async (stack: Frame[]) => {
+      console.log('  🎬 [selectMovie] L\'utilisateur choisit un film dans la liste...')
+      const movies = stack.find(f => f.entity === 'Movies')
+      if (movies) {
+        movies.id = 10
+        console.log('  ✓ Film #10 sélectionné')
+      }
+      return stack
+    },
+    cooldown: 0
+  },
+
+  {
+    name: 'navigateToActors',
+    weight: 8,
+    // Un film est sélectionné, mais pas encore de frame Actors
+    when: (stack: Frame[]) => {
+      const movies = stack.find(f => f.entity === 'Movies')
+      const actors = stack.find(f => f.entity === 'Actors')
+      return !!movies && movies.id != null && !actors
+    },
+    execute: async (stack: Frame[]) => {
+      console.log('  🎭 [navigateToActors] L\'utilisateur clique sur "Voir les acteurs"...')
+      stack.push({ entity: 'Actors', state: 'UNRESOLVED' })
+      console.log('  ✓ Frame Actors ajoutée à la stack')
+      return stack
+    },
+    cooldown: 0
+  },
+
+  {
+    name: 'selectActor',
+    weight: 5,
+    // Actors existe, est résolu, mais pas encore d'ID choisi
+    when: (stack: Frame[]) => {
+      const actors = stack.find(f => f.entity === 'Actors')
+      return !!actors && actors.state === 'RESOLVED' && actors.id == null
+    },
+    execute: async (stack: Frame[]) => {
+      console.log('  ⭐ [selectActor] L\'utilisateur sélectionne un acteur...')
+      const actors = stack.find(f => f.entity === 'Actors')
+      if (actors) {
+        actors.id = 3
+        console.log('  ✓ Acteur #3 sélectionné')
+      }
+      return stack
+    },
+    cooldown: 0
+  },
+
+  {
+    name: 'exploreFromActor',
+    weight: 3,
+    terminal: true, // S'exécute une seule fois
+    when: (stack: Frame[]) => {
+      const actors = stack.find(f => f.entity === 'Actors')
+      return !!actors && actors.id != null
+    },
+    execute: async (stack: Frame[]) => {
+      console.log('  🔍 [exploreFromActor] Affichage des options d\'exploration :')
+      console.log('      - Filmographie complète')
+      console.log('      - Autres réalisateurs')
+      console.log('      - Co-stars')
+      return stack
+    },
+    cooldown: 0
+  }
+]
+
+export default actions

package/src/scenarios/test-netflix/config.json

@@ -0,0 +1,6 @@
+{
+  "mode": "NAVIGATE",
+  "description": "Scénario Netflix — navigation dans un graphe généré automatiquement par le pipeline. Démontre les vues sémantiques (actor, director, writer...) issues de credits.jobId → jobs.",
+  "dataPath": "./data",
+  "graphGeneratedBy": "JsonSchemaExtractor → SchemaAnalyzer → GraphBuilder → GraphAssembler → GraphOptimizer"
+}

package/src/scenarios/test-netflix/data/categories.json

@@ -0,0 +1 @@
+[{"id":18,"name":"Drame"},{"id":80,"name":"Crime"},{"id":36,"name":"Histoire"},{"id":10752,"name":"Guerre"},{"id":35,"name":"Comédie"},{"id":10749,"name":"Romance"},{"id":16,"name":"Animation"},{"id":10751,"name":"Familial"},{"id":14,"name":"Fantastique"},{"id":28,"name":"Action"},{"id":53,"name":"Thriller"},{"id":12,"name":"Aventure"},{"id":37,"name":"Western"},{"id":10402,"name":"Musique"},{"id":27,"name":"Horreur"},{"id":9648,"name":"Mystère"},{"id":878,"name":"Science-Fiction"},{"id":10770,"name":"Téléfilm"}]

package/src/scenarios/test-netflix/data/companies.json

@@ -0,0 +1 @@
+[]