@linklabjs/core 0.1.0

package/src/api/loadGraph.ts

@@ -0,0 +1,207 @@
+/**
+ * loadGraph.ts — Factory universelle pour charger un graphe LinkLab
+ *
+ * Point d'entrée recommandé pour 80% des cas.
+ * Déduit le mode de chargement depuis le paramètre source et l'environnement.
+ *
+ * Usage :
+ *   // Node — fichier local
+ *   const cinema = await loadGraph('./cinema.json', { provider })
+ *
+ *   // Browser ou Node — URL HTTP
+ *   const cinema = await loadGraph('https://cdn.example.com/cinema.json', { provider })
+ *
+ *   // Données déjà en mémoire (tests, browser, injection)
+ *   const cinema = await loadGraph({ compiled }, { provider })
+ *
+ * Convention fichiers (Node) :
+ *   cinema.json            ← graphe compilé  (requis)
+ *   cinema.reference.json  ← graphe brut     (optionnel — chargé automatiquement)
+ *   cinema.override.json   ← surcharges dev  (optionnel — chargé automatiquement)
+ *
+ * new Graph() reste disponible pour les niveaux 2/3 et les tests unitaires.
+ */
+
+import { Graph } from './Graph.js'
+import type { GraphOptions } from './Graph.js'
+import type { Graph as GraphData, CompiledGraph } from '../types/index.js'
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Source du graphe compilé */
+export type GraphSource =
+  | string          // chemin fichier (Node) ou URL http(s) (browser/Node)
+  | GraphSourceObject
+
+export interface GraphSourceObject {
+  compiled:   CompiledGraph
+  reference?: GraphData
+  overrides?: Record<string, any>
+}
+
+/** Options de loadGraph — étend GraphOptions */
+export interface LoadGraphOptions extends Omit<GraphOptions, 'compiled'> {
+  /** Surcharge le chemin du graphe de référence (optionnel) */
+  reference?: string
+  /** Surcharge le chemin des overrides (optionnel) */
+  overrides?: string
+  /** Dossier contenant les fichiers JSON de données {entity}.json (mode local) */
+  dataDir?: string
+}
+
+// ── Détection environnement ────────────────────────────────────────────────────
+
+const IS_NODE    = typeof process !== 'undefined' && !!process.versions?.node
+const IS_BROWSER = typeof (globalThis as any).window !== 'undefined'
+
+// ── Chargement JSON ────────────────────────────────────────────────────────────
+
+async function loadJSON(source: string): Promise<any> {
+  // URL HTTP/HTTPS → fetch (universel)
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const res = await fetch(source)
+    if (!res.ok) throw new Error(`loadGraph: HTTP ${res.status} — ${source}`)
+    return res.json()
+  }
+
+  // Chemin fichier → Node uniquement
+  if (IS_NODE) {
+    const { createRequire } = await import('module')
+    const { fileURLToPath } = await import('url')
+    const pathModule        = await import('path')
+    const fsModule          = await import('fs')
+
+    // Résoudre le chemin depuis cwd
+    const resolved = pathModule.default.resolve(source)
+    if (!fsModule.default.existsSync(resolved)) return null
+
+    // createRequire depuis cwd pour les JSON
+    const req = createRequire(pathModule.default.join(process.cwd(), 'noop.js'))
+    return req(resolved)
+  }
+
+  throw new Error(`loadGraph: chemin fichier non supporté dans ce contexte — utiliser une URL HTTP`)
+}
+
+/** Derive les chemins convention depuis un chemin de base */
+function deriveConventionPaths(basePath: string): {
+  compiled:   string
+  reference:  string
+  overrides:  string
+  dictionary: string
+} {
+  // './cinema.json' → base = './cinema'
+  // './cinema'      → base = './cinema'
+  const base = basePath.replace(/\.json$/i, '')
+  return {
+    compiled:   `${base}.json`,
+    reference:  `${base}.reference.gen.json`,
+    overrides:  `${base}.override.json`,
+    dictionary: `${base}.dictionary.gen.json`,
+  }
+}
+
+// ── Factory principale ────────────────────────────────────────────────────────
+
+/**
+ * loadGraph — charge un graphe LinkLab depuis n'importe quelle source.
+ *
+ * Retourne directement le proxy sémantique (niveau 1) — prêt à naviguer.
+ * Pour accéder au Graph sous-jacent (niveaux 2/3/4) : domain.graph
+ *
+ * @example
+ *   const cinema = await loadGraph('./cinema.json', { provider })
+ *   await cinema.directors('Nolan').movies
+ *   cinema.graph.from('movies').to('people').path()  // niveau 2
+ */
+export async function loadGraph(
+  source:  GraphSource,
+  options: LoadGraphOptions = {}
+): Promise<ReturnType<Graph['domain']>> {
+
+  let compiled:   CompiledGraph
+  let reference:  GraphData | null = null
+  let overrides:  Record<string, any> | null = null
+  let dictionary: Record<string, any> | null = null
+
+  // ── Source objet en mémoire ────────────────────────────────────────────────
+  if (typeof source === 'object') {
+    compiled  = source.compiled
+    reference = source.reference  ?? null
+    overrides = source.overrides  ?? null
+  }
+
+  // ── Source string (chemin ou URL) ─────────────────────────────────────────
+  else {
+    const isURL = source.startsWith('http://') || source.startsWith('https://')
+
+    if (isURL) {
+      // URL directe — pas de convention (on ne peut pas deviner les URLs sœurs)
+      compiled = await loadJSON(source)
+      if (!compiled) throw new Error(`loadGraph: impossible de charger ${source}`)
+    } else {
+      // Chemin fichier — convention {name}.json + {name}.reference.json + {name}.override.json
+      const paths = deriveConventionPaths(source)
+
+      compiled = await loadJSON(options.reference ? source : paths.compiled)
+      if (!compiled) throw new Error(`loadGraph: graphe introuvable — ${paths.compiled}`)
+
+      // Référence (optionnel — chargé silencieusement)
+      const refPath = options.reference ?? paths.reference
+      reference = await loadJSON(refPath)   // null si absent
+
+      // Overrides (optionnel — chargé silencieusement)
+      const ovPath  = options.overrides ?? paths.overrides
+      overrides = await loadJSON(ovPath)    // null si absent
+
+      // Dictionnaire résolu (optionnel — labels humains des routes)
+      dictionary = await loadJSON(paths.dictionary)  // null si absent
+    }
+  }
+
+  // ── Charger dataset depuis dataDir ────────────────────────────────────────
+  let dataset = options.dataset ?? null
+
+  if (!dataset && options.dataDir && IS_NODE) {
+    const pathModule = await import('path')
+    const fsModule   = await import('fs')
+    const { createRequire } = await import('module')
+    const req        = createRequire(pathModule.default.join(process.cwd(), 'noop.js'))
+    const dataDirAbs = pathModule.default.resolve(options.dataDir)
+    dataset = {}
+    for (const node of compiled.nodes) {
+      const file = pathModule.default.join(dataDirAbs, `${node.id}.json`)
+      if (fsModule.default.existsSync(file)) dataset[node.id] = req(file)
+    }
+  }
+
+  // ── Appliquer les overrides sur le compilé ─────────────────────────────────
+  // TODO : deepMerge(compiled, overrides) quand ADR-0008 sera implémenté
+  if (overrides && IS_NODE && process.env.LINKLAB_DEBUG) {
+    console.warn('[loadGraph] overrides chargés mais pas encore appliqués (ADR-0008 pending)')
+  }
+
+  // ── Construire le Graph (niveau bas) ──────────────────────────────────────
+  const rawGraph: GraphData = reference ?? {
+    nodes: compiled.nodes,
+    edges: [],
+  }
+
+  const { compiled: _c, reference: _r, overrides: _o, dataDir: _d, dataset: _ds, ...graphOptions } = options as any
+  const graph = new Graph(rawGraph, {
+    ...graphOptions,
+    compiled,
+    ...(dataset    ? { dataset }    : {}),
+    ...(dictionary ? { dictionary } : {}),
+  })
+
+  // ── Retourner le domain directement ───────────────────────────────────────
+  // loadGraph() retourne le proxy sémantique (niveau 1) — pas le Graph brut.
+  // Accès au Graph sous-jacent via : const g = domain.graph
+  return graph.domain()
+}
+
+// ── Export de commodité ────────────────────────────────────────────────────────
+
+/** Alias — même API, nom plus court pour les imports fréquents */
+export { loadGraph as graph }

package/src/api/test-api.ts

@@ -0,0 +1,153 @@
+/**
+ * test-api.ts — Validation niveau 2 sur les 3 exemples
+ *
+ * Couvre les deux familles :
+ *   A) Pathfinding pur   — metro, musicians (pas de données)
+ *   B) Navigation data   — netflix (compiled + dataset)
+ */
+
+import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
+import path              from 'path'
+import { Graph, Strategy } from './index.js'
+
+const require   = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const root      = path.join(__dirname, '..')
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const ok  = (label: string) => console.log(`  ✅ ${label}`)
+const err = (label: string, e: any) => console.log(`  ❌ ${label}: ${e?.message ?? e}`)
+const sep = (title: string) => console.log(`\n${'─'.repeat(50)}\n${title}`)
+
+// ── Famille A : Pathfinding pur ───────────────────────────────────────────────
+
+sep('METRO — Pathfinding pur')
+try {
+  const metro = new Graph(require(`${root}/examples/metro/graph.json`))
+
+  // Chemin optimal (Shortest)
+  const r1 = metro.from('Station-chatelet').to('Station-opera').path()
+  r1.found && r1.paths[0].hops > 0
+    ? ok(`Châtelet→Opéra : ${r1.paths[0].hops} saut(s), poids=${r1.paths[0].weight}`)
+    : err('Châtelet→Opéra', 'chemin non trouvé')
+
+  // Mode confort — pénalise les correspondances
+  const r2 = metro.from('Station-republique').to('Station-bastille')
+               .paths(Strategy.Comfort())
+  r2.found
+    ? ok(`République→Bastille Comfort : ${r2.paths.length} chemins`)
+    : err('République→Bastille', 'non trouvé')
+
+  // Mode LeastHops
+  const r3 = metro.from('Station-gare-du-nord').to('Station-montparnasse-bienvenue')
+               .path(Strategy.LeastHops())
+  r3.found
+    ? ok(`GdN→Montparnasse LeastHops : ${r3.paths[0].hops} sauts`)
+    : err('GdN→Montparnasse', 'non trouvé')
+
+  // Introspection
+  console.log(`\n  graph.entities  : ${metro.entities.length} nodes`)
+  console.log(`  graph.relations : ${metro.relations.length} arêtes`)
+  const types = Object.keys(metro.schema)
+  console.log(`  graph.schema    : types = [${types.join(', ')}]`)
+
+} catch(e) { err('Metro init', e) }
+
+sep('MUSICIANS — Pathfinding avec via + minHops')
+try {
+  const music = new Graph(require(`${root}/examples/musicians/graph.json`))
+
+  // Chaîne sampling Will Smith → Manu Dibango
+  const r1 = music.from('artist-will-smith').to('artist-manu-dibango')
+               .paths()
+  r1.found
+    ? ok(`Will Smith→Manu Dibango : ${r1.paths.length} chemin(s), meilleur=${r1.paths[0].hops} sauts`)
+    : err('Will Smith→Manu Dibango', 'non trouvé')
+
+  // Chemin d'influence James Brown → Kanye avec minHops
+  const builder = music.from('artist-james-brown', { minHops: 1 })
+                       .to('artist-kanye-west')
+  const r2 = builder.paths()
+  r2.found
+    ? ok(`James Brown→Kanye (minHops=1) : ${r2.paths.length} chemin(s)`)
+    : err('James Brown→Kanye', 'non trouvé')
+
+  // .links — vue structurelle
+  const l = music.from('artist-daft-punk').to('artist-kanye-west').links
+  l.found
+    ? ok(`.links Daft Punk↔Kanye : ${l.edges.length} arêtes dans le sous-graphe`)
+    : err('.links', 'non trouvé')
+
+  // Steps enrichis — labels lisibles
+  if (r1.found && r1.paths[0].steps.length > 0) {
+    const labels = r1.paths[0].steps.map(s => s.label ?? s.node).join(' → ')
+    ok(`Steps : ${labels}`)
+  }
+
+} catch(e) { err('Musicians init', e) }
+
+sep('NETFLIX — Navigation avec données')
+try {
+  const compiled = require(`${root}/examples/netflix/compiled-graph.json`)
+  const movies   = require(`${root}/scenarios/test-netflix/data/movies.json`)
+  const credits  = require(`${root}/scenarios/test-netflix/data/credits.json`)
+  const people   = require(`${root}/scenarios/test-netflix/data/people.json`)
+
+  const netflix = new Graph(
+    require(`${root}/scenarios/test-netflix/graph.json`),
+    { compiled, dataset: { movies, credits, people } }
+  )
+
+  // Traversée movies → people via execute()
+  const r1 = await netflix.from('movies').to('people').execute({ id: 278 })
+  r1.data.length > 0
+    ? ok(`movies(278)→people : ${r1.data.length} personnes en ${r1.timing}ms, path=${r1.path.join('→')}`)
+    : err('movies→people', 'data vide')
+
+  // Traversée people → movies
+  const r2 = await netflix.from('people').to('movies').execute({ id: 4027 })
+  r2.data.length > 0
+    ? ok(`people(4027)→movies : ${r2.data.length} films (${(r2.data as any[]).map((m:any)=>m.title).join(', ')})`)
+    : err('people→movies', 'data vide')
+
+  // path() fonctionne aussi (sans données)
+  const r3 = netflix.from('movies').to('people').path()
+  r3.found
+    ? ok(`path() movies→people : ${r3.paths[0].nodes.join('→')}`)
+    : err('path() movies→people', 'non trouvé')
+
+  // Introspection
+  console.log(`\n  graph.entities  : ${netflix.entities.length} nodes`)
+  console.log(`  graph.weights   : ${Object.keys(netflix.weights).length} arêtes pondérées`)
+
+} catch(e) { err('Netflix init', e) }
+
+sep('NIVEAU 4 — Maintenance')
+try {
+  const music = new Graph(require(`${root}/examples/musicians/graph.json`))
+
+  // weight().set()
+  const edge   = music.relations.find(e => e.name)!
+  const g2     = music.weight(edge.name!).set(99)
+  const before = music.weights[edge.name!]
+  const after  = g2.weights[edge.name!]
+  before !== after && after === 99
+    ? ok(`weight('${edge.name}').set(99) : ${before} → ${after}`)
+    : err('weight.set', `${before} → ${after}`)
+
+  // Immuabilité — le graph original n'est pas modifié
+  music.weights[edge.name!] === before
+    ? ok(`Immuabilité préservée : original = ${before}`)
+    : err('Immuabilité', 'graph original modifié')
+
+  // snapshot()
+  const snap = music.snapshot()
+  snap.graph && !snap.compiled
+    ? ok(`snapshot() : graph OK, compiled=null (pas de compile())`)
+    : err('snapshot', JSON.stringify(snap))
+
+} catch(e) { err('Niveau 4', e) }
+
+console.log('\n' + '─'.repeat(50))

package/src/api/test-domain.ts

@@ -0,0 +1,119 @@
+/**
+ * test-domain.ts — Validation niveau 1 : DomainProxy
+ *
+ * Couvre :
+ *   - Accès propriété simple       cinema.movies
+ *   - Filtre par ID (number)       cinema.people(278)
+ *   - Filtre par objet             cinema.people({ id: 278 })
+ *   - Traversée thenable           await cinema.people(278).movies
+ *   - Fetch direct                 await cinema.movies
+ *   - Chaînage profond             await cinema.people(278).movies (depth 2)
+ */
+
+import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
+import path              from 'path'
+import { Graph }         from './index.js'
+
+const require   = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const root      = path.join(__dirname, '..')
+
+const ok  = (label: string) => console.log(`  ✅ ${label}`)
+const err = (label: string, detail: any) => console.log(`  ❌ ${label}: ${detail?.message ?? JSON.stringify(detail)}`)
+const sep = (t: string) => console.log(`\n${'─'.repeat(50)}\n${t}`)
+
+// ── Setup Netflix ─────────────────────────────────────────────────────────────
+
+const compiled = require(`${root}/examples/netflix/compiled-graph.json`)
+const movies   = require(`${root}/scenarios/test-netflix/data/movies.json`)
+const credits  = require(`${root}/scenarios/test-netflix/data/credits.json`)
+const people   = require(`${root}/scenarios/test-netflix/data/people.json`)
+
+const cinema = new Graph(
+  require(`${root}/scenarios/test-netflix/graph.json`),
+  { compiled, dataset: { movies, credits, people } }
+).domain()
+
+sep('NIVEAU 1 — Fetch direct (depth 1)')
+try {
+  // await cinema.movies → tous les films
+  const r1 = await (cinema as any).movies
+  r1.data.length > 0
+    ? ok(`await cinema.movies → ${r1.data.length} films`)
+    : err('cinema.movies', 'vide')
+
+  // await cinema.people → toutes les personnes
+  const r2 = await (cinema as any).people
+  r2.data.length > 0
+    ? ok(`await cinema.people → ${r2.data.length} personnes`)
+    : err('cinema.people', 'vide')
+
+  // await cinema.movies(278) → un seul film
+  const r3 = await (cinema as any).movies(278)
+  r3.data.length === 1 && r3.data[0].title === 'Les Évadés'
+    ? ok(`await cinema.movies(278) → "${r3.data[0].title}"`)
+    : err('cinema.movies(278)', r3.data)
+
+  // await cinema.people(4027) → Frank Darabont
+  const r4 = await (cinema as any).people(4027)
+  r4.data.length === 1 && r4.data[0].name === 'Frank Darabont'
+    ? ok(`await cinema.people(4027) → "${r4.data[0].name}"`)
+    : err('cinema.people(4027)', r4.data)
+
+  // Filtre par objet
+  const r5 = await (cinema as any).people({ id: 4027 })
+  r5.data.length === 1
+    ? ok(`await cinema.people({ id: 4027 }) → "${r5.data[0].name}"`)
+    : err('cinema.people({id:4027})', r5.data)
+
+} catch(e) { err('Depth 1', e) }
+
+sep('NIVEAU 1 — Traversée (depth 2)')
+try {
+  // await cinema.people(4027).movies → filmographie Darabont
+  const r1 = await (cinema as any).people(4027).movies
+  r1.data.length >= 2
+    ? ok(`await cinema.people(4027).movies → ${r1.data.length} films : ${r1.data.map((m:any)=>m.title).join(', ')}`)
+    : err('cinema.people(4027).movies', `${r1.data.length} films`)
+
+  // await cinema.movies(278).people → cast des Évadés
+  const r2 = await (cinema as any).movies(278).people
+  r2.data.length >= 10
+    ? ok(`await cinema.movies(278).people → ${r2.data.length} personnes`)
+    : err('cinema.movies(278).people', `${r2.data.length}`)
+
+  // Trail path
+  r1.path.length > 1
+    ? ok(`path: ${r1.path.join('→')}`)
+    : err('path', r1.path)
+
+} catch(e) { err('Depth 2', e) }
+
+sep('NIVEAU 1 — Clé sémantique (string filter)')
+try {
+  // await cinema.movies('Les Évadés') → via title
+  // Le semantic_key pour movies devrait être 'title'
+  const r1 = await (cinema as any).movies({ title: 'Les Évadés' })
+  r1.data.length === 1
+    ? ok(`await cinema.movies({ title: 'Les Évadés' }) → id=${r1.data[0].id}`)
+    : err('cinema.movies({title})', `${r1.data.length} résultats`)
+
+} catch(e) { err('Semantic key', e) }
+
+sep('NIVEAU 1 — Musicians (nodes par type)')
+try {
+  const music = new Graph(
+    require(`${root}/examples/musicians/graph.json`)
+  ).domain()
+
+  // Les musicians ont type='artist' — pas de données, juste des nodes
+  // cinema.artists → devrait résoudre le type 'artist'
+  const node = (music as any).artists
+  node !== undefined
+    ? ok(`cinema.artists → DomainNode résolu (entity=${node.entity})`)
+    : err('cinema.artists', 'undefined')
+
+} catch(e) { err('Musicians domain', e) }
+
+console.log('\n' + '─'.repeat(50))

package/src/api/types.ts

@@ -0,0 +1,88 @@
+/**
+ * api/types.ts — Types publics de l'API LinkLab niveau 2+
+ *
+ * Ces types sont la surface visible pour les utilisateurs du moteur.
+ * Les types internes (CompiledGraph, RouteInfo, etc.) restent dans types/index.ts.
+ */
+
+import type { GraphEdge } from '../types/index.js'
+
+// ── Stratégies de pathfinding ────────────────────────────────────────────────
+
+/**
+ * Strategy — comment Dijkstra pondère les chemins.
+ *
+ * Shortest      : poids brut des arêtes — temps pur, distance minimale
+ * Comfort       : pénalité par correspondance (+8 unités) — moins de changements
+ * LeastHops     : favorise les chemins avec peu d'étapes
+ * Custom(n)     : pénalité explicite par correspondance
+ */
+export type Strategy =
+  | { type: 'Shortest' }
+  | { type: 'Comfort' }
+  | { type: 'LeastHops' }
+  | { type: 'Custom'; transferPenalty: number }
+
+// Factories — évitent les objets littéraux à l'usage
+export const Strategy = {
+  Shortest:  (): Strategy => ({ type: 'Shortest' }),
+  Comfort:   (): Strategy => ({ type: 'Comfort' }),
+  LeastHops: (): Strategy => ({ type: 'LeastHops' }),
+  Custom:    (transferPenalty: number): Strategy => ({ type: 'Custom', transferPenalty }),
+
+  toPenalty(s: Strategy): number {
+    switch (s.type) {
+      case 'Shortest':  return 0
+      case 'Comfort':   return 8
+      case 'LeastHops': return 50
+      case 'Custom':    return s.transferPenalty
+    }
+  }
+} as const
+
+// ── Résultats de pathfinding ─────────────────────────────────────────────────
+
+export interface PathStep {
+  node:   string       // ID du node
+  label?: string       // label lisible si présent dans le graph
+  via?:   GraphEdge    // arête empruntée pour arriver ici (absente pour le premier node)
+}
+
+export interface ResolvedPath {
+  nodes:  string[]     // séquence d'IDs : ['Pigalle', 'Liège', 'Europe', ...]
+  steps:  PathStep[]   // version enrichie avec labels et arêtes
+  weight: number       // poids total selon la stratégie appliquée
+  hops:   number       // nombre d'arêtes traversées
+}
+
+export interface PathResult {
+  from:  string
+  to:    string
+  found: boolean
+  paths: ResolvedPath[]
+}
+
+// ── Résultats de navigation avec données ─────────────────────────────────────
+
+/**
+ * QueryResult — retourné par PathBuilder.execute()
+ * Uniquement en mode données (netflix, dvdrental) — pas pour metro/musicians.
+ */
+export interface QueryResult<T = Record<string, any>> {
+  from:    string
+  to:      string
+  filters: Record<string, any>
+  data:    T[]
+  path:    string[]
+  timing:  number
+}
+
+// ── Options du PathBuilder ───────────────────────────────────────────────────
+
+export interface PathBuilderOptions {
+  maxPaths?:  number
+  minHops?:   number
+  maxHops?:   number
+  via?:       string[]
+  strategy?:  Strategy
+}

package/src/config/synonyms.json

@@ -0,0 +1,28 @@
+{
+  "_comment": "Singular → plural irregular mappings for FK resolution. Used by JsonSchemaExtractor to resolve *Id columns to their target table. Add project-specific synonyms in examples/<project>/synonyms.json.",
+
+  "person":     "people",
+  "man":        "men",
+  "woman":      "women",
+  "child":      "children",
+
+  "company":    "companies",
+  "category":   "categories",
+  "country":    "countries",
+  "city":       "cities",
+  "currency":   "currencies",
+  "industry":   "industries",
+  "activity":   "activities",
+  "facility":   "facilities",
+  "capability": "capabilities",
+  "authority":  "authorities",
+  "community":  "communities",
+
+  "datum":      "data",
+  "medium":     "media",
+  "criterion":  "criteria",
+  "phenomenon": "phenomena",
+  "analysis":   "analyses",
+  "basis":      "bases",
+  "thesis":     "theses"
+}