@linklabjs/core 0.1.0

package/src/core/EventBus.ts

@@ -0,0 +1,187 @@
+/**
+ * EventBus — Bus générique pour hooks, events et errors
+ *
+ * Trois bus distincts, trois contrats clairs :
+ *
+ *   HookBus    — awaitable, peut modifier/annuler le flux
+ *   EventBus   — fire-and-forget, observationnel, ne bloque pas
+ *   ErrorBus   — synchrone, jamais silencieux
+ *
+ * Usage :
+ *   const bus = new EventBus<MyEvents>()
+ *   bus.on('traversal.complete', handler)
+ *   bus.emit('traversal.complete', data)
+ *   bus.off('traversal.complete', handler)
+ */
+
+// ── Types de base ─────────────────────────────────────────────
+
+export type Handler<T = any> = (data: T) => void
+export type AsyncHandler<T = any, R = T | void> = (data: T) => Promise<R> | R
+
+// ── EventBus — fire-and-forget ────────────────────────────────
+
+export class EventBus<TEvents extends Record<string, any> = Record<string, any>> {
+  private handlers = new Map<string, Set<Handler>>()
+
+  on<K extends keyof TEvents & string>(event: K, handler: Handler<TEvents[K]>): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set())
+    }
+    this.handlers.get(event)!.add(handler)
+
+    // Retourne une fonction de désinscription
+    return () => this.off(event, handler)
+  }
+
+  off<K extends keyof TEvents & string>(event: K, handler: Handler<TEvents[K]>): void {
+    this.handlers.get(event)?.delete(handler)
+  }
+
+  emit<K extends keyof TEvents & string>(event: K, data: TEvents[K]): void {
+    const handlers = this.handlers.get(event)
+    if (!handlers?.size) return
+
+    // Fire-and-forget — les erreurs dans les handlers ne propagent pas
+    for (const handler of handlers) {
+      try {
+        handler(data)
+      } catch (err) {
+        console.error(`[EventBus] Handler error on "${event}":`, err)
+      }
+    }
+  }
+
+  clear(event?: string): void {
+    if (event) {
+      this.handlers.delete(event)
+    } else {
+      this.handlers.clear()
+    }
+  }
+
+  listenerCount(event: string): number {
+    return this.handlers.get(event)?.size ?? 0
+  }
+}
+
+// ── HookBus — awaitable, peut modifier ou annuler ────────────
+
+export interface HookResult<T> {
+  value: T
+  cancelled?: boolean
+  reason?: string
+}
+
+export class HookBus<THooks extends Record<string, any> = Record<string, any>> {
+  private handlers = new Map<string, AsyncHandler[]>()
+
+  on<K extends keyof THooks & string>(
+    hook: K,
+    handler: AsyncHandler<THooks[K]>
+  ): () => void {
+    if (!this.handlers.has(hook)) {
+      this.handlers.set(hook, [])
+    }
+    this.handlers.get(hook)!.push(handler)
+
+    return () => this.off(hook, handler)
+  }
+
+  off<K extends keyof THooks & string>(hook: K, handler: AsyncHandler<THooks[K]>): void {
+    const list = this.handlers.get(hook)
+    if (!list) return
+    const idx = list.indexOf(handler)
+    if (idx !== -1) list.splice(idx, 1)
+  }
+
+  /**
+   * Appelle les handlers en séquence.
+   * Chaque handler peut retourner une valeur modifiée — elle est passée au suivant.
+   * Si un handler retourne { cancelled: true }, la chaîne s'arrête.
+   */
+  async call<K extends keyof THooks & string>(
+    hook: K,
+    data: THooks[K]
+  ): Promise<HookResult<THooks[K]>> {
+    const handlers = this.handlers.get(hook)
+    if (!handlers?.length) return { value: data }
+
+    let current = data
+
+    for (const handler of handlers) {
+      const result = await handler(current)
+
+      // Si le handler retourne un objet avec cancelled, on stoppe
+      if (result && typeof result === 'object' && 'cancelled' in result && result.cancelled) {
+        return { value: current, cancelled: true, reason: result.reason }
+      }
+
+      // Si le handler retourne une valeur, elle remplace le contexte courant
+      if (result !== undefined && result !== null) {
+        current = result as THooks[K]
+      }
+    }
+
+    return { value: current }
+  }
+
+  listenerCount(hook: string): number {
+    return this.handlers.get(hook)?.length ?? 0
+  }
+}
+
+// ── ErrorBus — synchrone, jamais silencieux ──────────────────
+
+export class ErrorBus<TErrors extends Record<string, any> = Record<string, any>> {
+  private handlers = new Map<string, Set<Handler>>()
+  private fallback?: (event: string, data: any) => void
+
+  /**
+   * Handler de fallback si aucun handler n'est enregistré pour cette erreur.
+   * Par défaut : console.error.
+   */
+  setFallback(fn: (event: string, data: any) => void): void {
+    this.fallback = fn
+  }
+
+  on<K extends keyof TErrors & string>(event: K, handler: Handler<TErrors[K]>): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set())
+    }
+    this.handlers.get(event)!.add(handler)
+
+    return () => this.off(event, handler)
+  }
+
+  off<K extends keyof TErrors & string>(event: K, handler: Handler<TErrors[K]>): void {
+    this.handlers.get(event)?.delete(handler)
+  }
+
+  emit<K extends keyof TErrors & string>(event: K, data: TErrors[K]): void {
+    const handlers = this.handlers.get(event)
+
+    if (!handlers?.size) {
+      // Jamais silencieux — fallback ou console.error
+      if (this.fallback) {
+        this.fallback(event, data)
+      } else {
+        console.error(`[LinkLab Error] ${event}:`, data)
+      }
+      return
+    }
+
+    for (const handler of handlers) {
+      try {
+        handler(data)
+      } catch (err) {
+        // Les erreurs dans les error handlers ne doivent jamais être avalées
+        console.error(`[ErrorBus] Handler threw on "${event}":`, err)
+      }
+    }
+  }
+
+  listenerCount(event: string): number {
+    return this.handlers.get(event)?.size ?? 0
+  }
+}

package/src/core/GraphEvents.ts

@@ -0,0 +1,153 @@
+/**
+ * GraphEvents — Catalogue des événements LinkLab
+ *
+ * Trois bus, trois contrats :
+ *
+ *   graph.hooks   — awaitable, enrichit ou annule le flux
+ *   graph.events  — fire-and-forget, observation pure
+ *   graph.errors  — synchrone, jamais silencieux
+ *
+ * Conventions de nommage :
+ *   hooks  : <sujet>.<moment>   ex: traversal.before, access.check
+ *   events : <sujet>.<résultat> ex: traversal.complete, cache.miss
+ *   errors : <sujet>.<type>     ex: route.notfound, traversal.failed
+ */
+
+import { HookBus, EventBus, ErrorBus } from './EventBus.js'
+import type { Frame, GraphEdge, NavigationPath, Graph } from '../types/index.js'
+
+// ── Payloads Hooks ────────────────────────────────────────────
+
+export interface TraversalBeforePayload {
+  from: string
+  to: string
+  stack: Frame[]
+  graph: Graph
+}
+
+export interface TraversalStepPayload {
+  node: string
+  edge: GraphEdge
+  stack: Frame[]
+  depth: number
+}
+
+export interface AccessCheckPayload {
+  node: string
+  stack: Frame[]
+  context?: Record<string, any>
+}
+
+export interface StackPushPayload {
+  frame: Frame
+  stack: Frame[]
+}
+
+export interface StackPopPayload {
+  frame: Frame
+  stack: Frame[]
+}
+
+// ── Payloads Events ───────────────────────────────────────────
+
+export interface TraversalCompletePayload {
+  from: string
+  to: string
+  path: NavigationPath
+  durationMs: number
+  stackDepth: number
+  routeUsed: string        // ex: "movies→credits→people"
+  routeWeight: number
+  resultCount?: number
+}
+
+export interface CacheMissPayload {
+  key: string
+  requestedAt: number
+}
+
+export interface CacheHitPayload {
+  key: string
+  accessCount: number
+  cachedAt?: number
+}
+
+export interface WeightUpdatedPayload {
+  edge: string             // "from→to"
+  previousWeight: number
+  newWeight: number
+  reason?: string
+}
+
+export interface StackCompactedPayload {
+  before: Frame[]
+  after: Frame[]
+  removedCount: number
+}
+
+// ── Payloads Errors ───────────────────────────────────────────
+
+export interface RouteNotFoundPayload {
+  from: string
+  to: string
+  stack: Frame[]
+}
+
+export interface TraversalFailedPayload {
+  from: string
+  to: string
+  reason: string
+  error?: Error
+}
+
+export interface HookTimeoutPayload {
+  hook: string
+  timeoutMs: number
+}
+
+export interface AccessDeniedPayload {
+  node: string
+  reason: string
+  stack: Frame[]
+}
+
+// ── Registres typés ───────────────────────────────────────────
+
+export interface GraphHooks {
+  'traversal.before': TraversalBeforePayload
+  'traversal.step':   TraversalStepPayload
+  'access.check':     AccessCheckPayload
+  'stack.push':       StackPushPayload
+  'stack.pop':        StackPopPayload
+}
+
+export interface GraphEventMap {
+  'traversal.complete': TraversalCompletePayload
+  'cache.miss':         CacheMissPayload
+  'cache.hit':          CacheHitPayload
+  'weight.updated':     WeightUpdatedPayload
+  'stack.compacted':    StackCompactedPayload
+}
+
+export interface GraphErrors {
+  'route.notfound':    RouteNotFoundPayload
+  'traversal.failed':  TraversalFailedPayload
+  'hook.timeout':      HookTimeoutPayload
+  'access.denied':     AccessDeniedPayload
+}
+
+// ── Factory — crée les trois bus pour une instance de graphe ──
+
+export interface GraphBuses {
+  hooks:  HookBus<GraphHooks>
+  events: EventBus<GraphEventMap>
+  errors: ErrorBus<GraphErrors>
+}
+
+export function createGraphBuses(): GraphBuses {
+  return {
+    hooks:  new HookBus<GraphHooks>(),
+    events: new EventBus<GraphEventMap>(),
+    errors: new ErrorBus<GraphErrors>(),
+  }
+}

package/src/core/PathFinder.ts

@@ -0,0 +1,283 @@
+/**
+ * PathFinder - Dijkstra + DFS limité
+ *
+ * Deux algorithmes selon l'usage :
+ *
+ *   findShortestPath()  → Dijkstra  (chemin optimal garanti, performant)
+ *   findAllPaths()      → DFS limité (N meilleurs chemins alternatifs)
+ *
+ * Sur un graphe de métro (300+ stations, 900+ arêtes),
+ * le DFS pur explose. Dijkstra est l'algorithme correct.
+ */
+
+import type { Graph, GraphEdge, Path, PathDetails } from '../types/index.js'
+
+export class PathFinder {
+  private adjacencyList: Map<string, Array<{ to: string; edge: GraphEdge }>>
+
+  constructor(private graph: Graph) {
+    this.adjacencyList = this.buildAdjacencyList(graph)
+  }
+
+  // ==================== DIJKSTRA ====================
+
+  /**
+   * Chemin le plus court par poids (Dijkstra).
+   * Garanti optimal. Performant sur grands graphes.
+   */
+  findShortestPath(from: string, to: string): PathDetails | null {
+    const dist = new Map<string, number>()
+    const prev = new Map<string, { node: string; edge: GraphEdge } | null>()
+    const visited = new Set<string>()
+
+    // Initialisation
+    for (const node of this.graph.nodes) {
+      dist.set(node.id, Infinity)
+    }
+    dist.set(from, 0)
+    prev.set(from, null)
+
+    // Priority queue simple (pour notre taille, suffisant)
+    const queue = new Set<string>(this.graph.nodes.map(n => n.id))
+
+    while (queue.size > 0) {
+      // Nœud non visité avec distance minimale
+      let u: string | null = null
+      let minDist = Infinity
+      for (const node of queue) {
+        const d = dist.get(node) ?? Infinity
+        if (d < minDist) {
+          minDist = d
+          u = node
+        }
+      }
+
+      if (u === null || u === to) break
+      if (minDist === Infinity) break // Graphe non connexe
+
+      queue.delete(u)
+      visited.add(u)
+
+      const neighbors = this.adjacencyList.get(u) ?? []
+      for (const { to: v, edge } of neighbors) {
+        if (visited.has(v)) continue
+
+        const alt = (dist.get(u) ?? Infinity) + edge.weight
+        if (alt < (dist.get(v) ?? Infinity)) {
+          dist.set(v, alt)
+          prev.set(v, { node: u, edge })
+        }
+      }
+    }
+
+    if (!prev.has(to) && to !== from) return null
+    if ((dist.get(to) ?? Infinity) === Infinity) return null
+
+    // Reconstruction du chemin
+    const path: string[] = []
+    const edges: GraphEdge[] = []
+    let current: string | null = to
+
+    while (current !== null) {
+      path.unshift(current)
+      const p = prev.get(current)
+      if (p) {
+        edges.unshift(p.edge)
+        current = p.node
+      } else {
+        current = null
+      }
+    }
+
+    return {
+      path,
+      edges,
+      length: path.length,
+      joins: path.length - 1,
+      weight: dist.get(to) ?? 0,
+      indirect: path.length > 2
+    }
+  }
+
+  /**
+   * N meilleurs chemins (Yen's K-shortest paths simplifié).
+   * Trouve le plus court via Dijkstra, puis des alternatives
+   * en pénalisant les arêtes du chemin précédent.
+   */
+  findAllPaths(from: string, to: string, maxPaths = 3, _maxDepth = 50, transferPenalty = 0, allowedVia?: string[], minHops = 0): Path[] {
+    const results: PathDetails[] = []
+    const penalized = new Set<string>() // arêtes temporairement exclues
+
+    for (let k = 0; k < maxPaths; k++) {
+      const result = this.dijkstraWithExclusions(from, to, penalized, transferPenalty, allowedVia, minHops)
+      if (!result) break
+
+      results.push(result)
+
+      // Pénaliser la dernière arête du chemin trouvé pour forcer une alternative
+      if (result.edges.length > 0) {
+        const lastEdge = result.edges[result.edges.length - 1]
+        penalized.add(lastEdge.name ?? `${lastEdge.from}->${lastEdge.to}`)
+      }
+    }
+
+    return results.map(r => r.path)
+  }
+
+  /**
+   * Dijkstra avec exclusion d'arêtes (pour les chemins alternatifs)
+   */
+  private dijkstraWithExclusions(
+    from: string,
+    to: string,
+    excluded: Set<string>,
+    transferPenalty = 0,
+    allowedVia?: string[],
+    minHops = 0
+  ): PathDetails | null {
+    const dist = new Map<string, number>()
+    const prev = new Map<string, { node: string; edge: GraphEdge } | null>()
+    const visited = new Set<string>()
+
+    for (const node of this.graph.nodes) dist.set(node.id, Infinity)
+    dist.set(from, 0)
+    prev.set(from, null)
+
+    const queue = new Set<string>(this.graph.nodes.map(n => n.id))
+
+    while (queue.size > 0) {
+      let u: string | null = null
+      let minDist = Infinity
+      for (const node of queue) {
+        const d = dist.get(node) ?? Infinity
+        if (d < minDist) { minDist = d; u = node }
+      }
+
+      if (u === null || u === to || minDist === Infinity) break
+
+      queue.delete(u)
+      visited.add(u)
+
+      for (const { to: v, edge } of this.adjacencyList.get(u) ?? []) {
+        if (visited.has(v)) continue
+        const edgeKey = edge.name ?? `${edge.from}->${edge.to}`
+        if (excluded.has(edgeKey)) continue
+
+        // Filtre via — si spécifié, ignorer les arêtes dont le type n'est pas dans la liste
+        if (allowedVia && allowedVia.length > 0) {
+          const edgeType = edge.metadata?.type ?? edge.via
+          if (!allowedVia.includes(edgeType)) continue
+        }
+
+        // Pénalité sur changement de ligne — deux cas :
+        // 1. Arête explicitement TRANSFER (self-loop de correspondance)
+        // 2. Changement de ligne implicite (arête DIRECT mais ligne différente de la précédente)
+        let penalty = 0
+        if (transferPenalty > 0) {
+          const isExplicitTransfer = edge.metadata?.type === 'TRANSFER'
+          const prevEdge = prev.get(u)
+          const prevLineId = prevEdge?.edge?.metadata?.lineId
+          const currLineId = edge.metadata?.lineId
+          const isLineChange = prevLineId && currLineId && prevLineId !== currLineId
+            && edge.metadata?.type !== 'TRANSFER'
+          if (isExplicitTransfer || isLineChange) {
+            penalty = transferPenalty
+          }
+        }
+        const alt = (dist.get(u) ?? Infinity) + edge.weight + penalty
+        if (alt < (dist.get(v) ?? Infinity)) {
+          dist.set(v, alt)
+          prev.set(v, { node: u, edge })
+        }
+      }
+    }
+
+    if ((dist.get(to) ?? Infinity) === Infinity) return null
+
+    const path: string[] = []
+    const edges: GraphEdge[] = []
+    let current: string | null = to
+
+    while (current !== null) {
+      path.unshift(current)
+      const p = prev.get(current)
+      if (p) { edges.unshift(p.edge); current = p.node }
+      else current = null
+    }
+
+    // Filtre minHops — rejeter les chemins trop courts
+    if (minHops > 0 && path.length - 1 < minHops) return null
+
+    return {
+      path, edges,
+      length: path.length,
+      joins: path.length - 1,
+      weight: dist.get(to) ?? 0,
+      indirect: path.length > 2
+    }
+  }
+
+  // ==================== HELPERS ====================
+
+  getPathWeight(path: Path): number {
+    let total = 0
+    for (let i = 0; i < path.length - 1; i++) {
+      const edge = this.graph.edges.find(e => e.from === path[i] && e.to === path[i + 1])
+      if (edge) total += edge.weight
+    }
+    return total
+  }
+
+  getPathDetails(path: Path): PathDetails {
+    const edges: GraphEdge[] = []
+    for (let i = 0; i < path.length - 1; i++) {
+      const edge = this.graph.edges.find(e => e.from === path[i] && e.to === path[i + 1])
+      if (edge) edges.push(edge)
+    }
+    return {
+      path, edges,
+      length: path.length,
+      joins: path.length - 1,
+      weight: this.getPathWeight(path),
+      indirect: path.length > 2
+    }
+  }
+
+  hasPath(from: string, to: string): boolean {
+    return this.findShortestPath(from, to) !== null
+  }
+
+  getReachableNodes(from: string, maxDepth = 50): Set<string> {
+    const reachable = new Set<string>()
+    const visited = new Set<string>()
+    const dfs = (node: string, depth: number) => {
+      if (depth > maxDepth || visited.has(node)) return
+      visited.add(node)
+      reachable.add(node)
+      for (const { to } of this.adjacencyList.get(node) ?? []) dfs(to, depth + 1)
+    }
+    dfs(from, 0)
+    reachable.delete(from)
+    return reachable
+  }
+
+  private buildAdjacencyList(graph: Graph): Map<string, Array<{ to: string; edge: GraphEdge }>> {
+    const adj = new Map<string, Array<{ to: string; edge: GraphEdge }>>()
+    for (const edge of graph.edges) {
+      if (!adj.has(edge.from)) adj.set(edge.from, [])
+      adj.get(edge.from)!.push({ to: edge.to, edge })
+      if (!adj.has(edge.to)) adj.set(edge.to, [])
+    }
+    return adj
+  }
+
+  getStats() {
+    const degrees = new Map<string, number>()
+    for (const node of this.graph.nodes) degrees.set(node.id, 0)
+    for (const edge of this.graph.edges) {
+      degrees.set(edge.from, (degrees.get(edge.from) ?? 0) + 1)
+    }
+    const avgDegree = Array.from(degrees.values()).reduce((s, d) => s + d, 0) / degrees.size
+    return { nodes: this.graph.nodes.length, edges: this.graph.edges.length, avgDegree }
+  }
+}

package/src/formatters/BaseFormatter.ts

@@ -0,0 +1,17 @@
+/**
+ * BaseFormatter - Interface pour les formatters de sortie
+ *
+ * Chaque scénario peut avoir son propre formatter.
+ * Le formatter transforme un résultat brut du NavigationEngine
+ * en sortie lisible par un humain.
+ */
+
+import type { NavigationPath, EngineStepResult } from '../types/index.js'
+
+export interface PathFormatter {
+  /** Formate un chemin pour l'affichage humain */
+  format(path: NavigationPath): string
+
+  /** Formate un step complet de résultat */
+  formatResult(result: EngineStepResult): string
+}

package/src/graph/GraphAssembler.ts

@@ -0,0 +1,50 @@
+/**
+ * GraphAssembler — Dictionary → Graph V3
+ *
+ * Transforme le Dictionary produit par GraphBuilder
+ * en Graph V3 (nodes + edges) prêt pour PathFinder.
+ *
+ * Corrige le bug d'itération : dictionary.tables est une Table[]
+ * (liste), pas un Record<string, Table> (dictionnaire).
+ */
+
+import type { Dictionary, Graph, GraphNode, GraphEdge } from '../types/index.js'
+
+export class GraphAssembler {
+
+  assemble(dictionary: Dictionary): Graph {
+    const nodes: GraphNode[] = []
+    const edges: GraphEdge[] = []
+
+    // 1. Tables → Nodes
+    // dictionary.tables est une Table[] — itération sur les éléments, pas les indices
+    for (const table of dictionary.tables) {
+      nodes.push({
+        id: table.name,
+        type: 'table',
+        rowCount: table.rowCount,
+        columns: table.columns.map(c => ({ name: c, type: 'string' }))
+      })
+    }
+
+    // 2. Relations → Edges
+    for (const rel of dictionary.relations) {
+      edges.push({
+        name: rel.label,
+        from: rel.from,
+        to: rel.to,
+        via: rel.via,
+        weight: typeof rel.weight === 'string'
+          ? parseFloat(rel.weight)
+          : (rel.weight ?? 1),
+        metadata: {
+          type: rel.type,
+          condition: rel.condition,
+          metadataField: rel.metadataField
+        }
+      })
+    }
+
+    return { nodes, edges }
+  }
+}