@linklabjs/core 0.1.0

package/src/api/Graph.ts

@@ -0,0 +1,271 @@
+/**
+ * api/Graph.ts — Niveau 0 : constructeur et surface unifiée
+ *
+ * Point d'entrée unique de LinkLab.
+ *
+ *   const graph = new Graph(graphJson)
+ *   const graph = new Graph(graphJson, { compiled, dataset })
+ *
+ * Expose :
+ *   Niveau 2 — graph.from(a).to(b).path(strategy)
+ *   Niveau 3 — graph.entities, graph.relations, graph.weights, graph.schema
+ *   Niveau 4 — graph.compile(), graph.snapshot()
+ *
+ * Le niveau 1 (DomainProxy) sera ajouté dans graph.domain() — prochaine étape.
+ */
+
+import { createRequire }    from 'module'
+import fs                   from 'fs'
+import path                 from 'path'
+import type {
+  Graph as GraphData,
+  CompiledGraph,
+  GraphNode,
+  GraphEdge,
+  Provider,
+}                           from '../types/index.js'
+import { GraphCompiler }    from '../graph/GraphCompiler.js'
+import { PathBuilder }      from './PathBuilder.js'
+import { createDomain }     from './DomainNode.js'
+import type { PathBuilderOptions } from './types.js'
+
+export interface GraphOptions {
+  /** CompiledGraph précalculé — active .execute() sur PathBuilder */
+  compiled?:  CompiledGraph
+  /** Dataset en mémoire { tableName: rows[] } — active .execute() */
+  dataset?:   Record<string, any[]>
+  /** Provider externe (PostgreSQL, etc.) — active .execute() via SQL */
+  provider?:  Provider
+  /** Préfixe de chemin pour résoudre les imports relatifs */
+  basePath?:  string
+  /** Dictionnaire résolu — labels humains des routes */
+  dictionary?: Record<string, any> | null
+}
+
+/** Lien navigable depuis un nœud — retourné par linksFrom() */
+export interface NavigationLink {
+  to:       string           // nœud cible
+  label:    string           // nom de la relation ou vue sémantique
+  semantic: boolean          // true = vue filtrée (actor, director...), false = table physique
+  weight?:  number           // poids courant
+}
+
+export class Graph {
+  private _data:       GraphData
+  private _compiled:   CompiledGraph | null
+  private _dataset:    Record<string, any[]> | null
+  private _provider:   Provider | null
+  private _dictionary: Record<string, any> | null
+
+  constructor(source: GraphData | string, options: GraphOptions = {}) {
+    // Accepte un objet GraphData directement ou un chemin vers graph.json
+    if (typeof source === 'string') {
+      const resolved = options.basePath
+        ? path.resolve(options.basePath, source)
+        : path.resolve(source)
+      const req = createRequire(import.meta.url)
+      this._data = req(resolved) as GraphData
+    } else {
+      this._data = source
+    }
+
+    this._compiled   = options.compiled   ?? null
+    this._dataset    = options.dataset    ?? null
+    this._provider   = options.provider   ?? null
+    this._dictionary = options.dictionary ?? null
+  }
+
+  // ── Niveau 1 — Navigation sémantique (domain proxy) ─────────────────────────
+
+  /**
+   * domain() — retourne un Proxy sémantique sur le graphe.
+   * Optionnel — Graph lui-même est utilisable comme domaine directement.
+   *
+   *   const cinema = new Graph(source, opts)
+   *   await cinema.movies                    // via Graph comme domaine
+   *   await cinema.domain().movies           // équivalent explicite
+   *   await cinema.domain('cinema').movies   // avec nom (futur: permissions/projections)
+   */
+  domain(_name?: string) {
+    return createDomain({
+      graphData:  this._data,
+      compiled:   this._compiled,
+      dataset:    this._dataset,
+      provider:   this._provider,
+      dictionary: this._dictionary,
+    }, this)  // ← passe le Graph pour .graph
+  }
+
+  // ── Niveau 2 — Exploration algorithmique ──────────────────────────────────
+
+  /**
+   * from(node) — point de départ d'une traversée.
+   *
+   *   graph.from('Pigalle').to('Alesia').path(Strategy.Comfort())
+   *   graph.from('movies').to('people').execute({ id: 278 })
+   */
+  from(node: string, opts: PathBuilderOptions = {}): PathBuilder {
+    return new PathBuilder(node, this._data, this._compiled, this._dataset ?? null, opts, this._provider)
+  }
+
+  /**
+   * within(node, depth) — exploration radiale depuis un node.
+   * Retourne tous les nodes accessibles en ≤ depth sauts.
+   *
+   *   graph.within('Châtelet', 3).nodes
+   */
+  within(node: string, depth = 2): { nodes: GraphNode[] } {
+    const finder  = new (require('../core/PathFinder.js').PathFinder)(this._data)
+    const reached = finder.getReachableNodes(node, depth)
+    const nodes   = this._data.nodes.filter(n => reached.has(n.id))
+    return { nodes }
+  }
+
+  // ── Niveau 3 — Introspection ───────────────────────────────────────────────
+
+  /** Liste des entités (nodes) du graphe */
+  get entities(): GraphNode[] {
+    return [...this._data.nodes]
+  }
+
+  /** Liste des relations (arêtes) du graphe */
+  get relations(): GraphEdge[] {
+    return [...this._data.edges]
+  }
+
+  /** Poids courants de toutes les arêtes — { edgeName: weight } */
+  get weights(): Record<string, number> {
+    return Object.fromEntries(
+      this._data.edges
+        .filter(e => e.name)
+        .map(e => [e.name!, Number(e.weight) || 1])
+    )
+  }
+
+  /** Schéma résolu — nodes groupés par type */
+  get schema(): Record<string, GraphNode[]> {
+    const result: Record<string, GraphNode[]> = {}
+    for (const node of this._data.nodes) {
+      const type = (node as any).type ?? 'node'
+      if (!result[type]) result[type] = []
+      result[type].push(node)
+    }
+    return result
+  }
+
+  /**
+   * linksFrom(nodeId) — liens navigables depuis un nœud, au niveau sémantique maximal.
+   *
+   * Retourne les routes physiques ET les vues sémantiques du compiledGraph.
+   * Utilisé par : REPL (autocomplétion), TUI, extension VSCode.
+   *
+   *   graph.linksFrom('movies')
+   *   // → [
+   *   //   { to: 'people',   label: 'people',   semantic: false },  ← table physique
+   *   //   { to: 'people',   label: 'actor',    semantic: true  },  ← vue filtrée jobId=1
+   *   //   { to: 'people',   label: 'director', semantic: true  },  ← vue filtrée jobId=2
+   *   // ]
+   */
+  linksFrom(nodeId: string): NavigationLink[] {
+    const links: NavigationLink[] = []
+    const seen = new Set<string>()
+
+    // Routes physiques — priorité : raw-graph edges, fallback : compiled.routes non-sémantiques
+    const rawEdges = this._data.edges.filter(e => e.from === nodeId)
+    if (rawEdges.length > 0) {
+      for (const e of rawEdges) {
+        const label = e.name ?? e.to
+        if (!seen.has(label)) {
+          seen.add(label)
+          links.push({ to: e.to, label, semantic: false, weight: Number(e.weight) || 1 })
+        }
+      }
+    } else if (this._compiled) {
+      // Pas de raw-graph (cas loadGraph({ compiled })) → routes physiques depuis compiled
+      for (const r of (this._compiled as any).routes ?? []) {
+        if (r.from === nodeId && !r.semantic) {
+          const label = r.to
+          if (!seen.has(label)) {
+            seen.add(label)
+            links.push({ to: r.to, label, semantic: false, weight: r.primary?.weight })
+          }
+        }
+      }
+    }
+
+    // Routes sémantiques depuis le compiledGraph
+    if (this._compiled) {
+      for (const r of (this._compiled as any).routes ?? []) {
+        if (r.from === nodeId && r.semantic === true) {
+          const label = r.label ?? r.to
+          if (!seen.has(label)) {
+            seen.add(label)
+            links.push({ to: r.to, label, semantic: true, weight: r.primary?.weight })
+          }
+        }
+      }
+    }
+
+    return links
+  }
+
+  // ── Niveau 4 — Maintenance ─────────────────────────────────────────────────
+
+  /**
+   * compile() — précalcule les routes optimales.
+   * Retourne un nouveau Graph avec le compiledGraph injecté.
+   */
+  compile(config: Parameters<GraphCompiler['compile']>[1] = new Map()): Graph {
+    const compiler  = new GraphCompiler()
+    const compiled  = compiler.compile(this._data, config)
+    return new Graph(this._data, {
+      compiled,
+      dataset: this._dataset ?? undefined,
+    })
+  }
+
+  /**
+   * snapshot() — sérialise l'état courant (graph + compiled si présent).
+   */
+  snapshot(): { graph: GraphData; compiled: CompiledGraph | null } {
+    return {
+      graph:    this._data,
+      compiled: this._compiled,
+    }
+  }
+
+  /**
+   * weight(edgeName).set(value) — ajuste le poids d'une arête.
+   * Retourne un nouveau Graph (immuable).
+   */
+  weight(edgeName: string) {
+    return {
+      set: (value: number): Graph => {
+        const edges = this._data.edges.map(e =>
+          e.name === edgeName ? { ...e, weight: value } : e
+        )
+        return new Graph(
+          { ...this._data, edges },
+          { compiled: this._compiled ?? undefined, dataset: this._dataset ?? undefined }
+        )
+      },
+      update: (fn: (current: number) => number): Graph => {
+        const edges = this._data.edges.map(e => {
+          if (e.name !== edgeName) return e
+          return { ...e, weight: fn(Number(e.weight) || 1) }
+        })
+        return new Graph(
+          { ...this._data, edges },
+          { compiled: this._compiled ?? undefined, dataset: this._dataset ?? undefined }
+        )
+      },
+    }
+  }
+
+  // ── Accès aux données brutes ───────────────────────────────────────────────
+
+  /** GraphData interne — pour les couches qui en ont besoin */
+  get raw(): GraphData {
+    return this._data
+  }
+}

package/src/api/PathBuilder.ts

@@ -0,0 +1,247 @@
+/**
+ * api/PathBuilder.ts — Niveau 2 : exploration algorithmique
+ *
+ * Point d'entrée : graph.from(a).to(b)
+ *
+ * Surface publique :
+ *   .path(strategy?)     → meilleur chemin (PathResult)
+ *   .paths(strategy?)    → tous les chemins ordonnés (PathResult)
+ *   .links               → graphe de relations entre les deux nodes
+ *   .execute(filters)    → traversée avec hydratation de données
+ *
+ * Compile vers PathFinder (Dijkstra) + QueryEngine (données).
+ * Ne connaît pas le domaine — c'est le niveau 1 (DomainProxy) qui traduit
+ * les noms sémantiques en IDs de nodes avant d'appeler PathBuilder.
+ */
+
+import type { Graph, CompiledGraph, GraphEdge, Provider } from '../types/index.js'
+import { PathFinder }                  from '../core/PathFinder.js'
+import { QueryEngine }                 from '../runtime/QueryEngine.js'
+import type {
+  Strategy,
+  PathResult,
+  ResolvedPath,
+  PathStep,
+  QueryResult,
+  PathBuilderOptions,
+} from './types.js'
+import { Strategy as S }               from './types.js'
+
+export class PathBuilder {
+  private _from:    string
+  private _to:      string | null = null
+  private _opts:    PathBuilderOptions
+  private _graph:   Graph
+  private _compiled: CompiledGraph | null
+  private _dataset:  Record<string, any[]> | null
+  private _provider: Provider | null
+
+  constructor(
+    from:     string,
+    graph:    Graph,
+    compiled: CompiledGraph | null = null,
+    dataset:  Record<string, any[]> | null = null,
+    opts:     PathBuilderOptions = {},
+    provider: Provider | null = null
+  ) {
+    this._from     = from
+    this._graph    = graph
+    this._compiled = compiled
+    this._dataset  = dataset
+    this._opts     = opts
+    this._provider = provider
+  }
+
+  // ── Builder ────────────────────────────────────────────────────────────────
+
+  to(node: string): this {
+    this._to = node
+    return this
+  }
+
+  maxPaths(n: number): this {
+    this._opts = { ...this._opts, maxPaths: n }
+    return this
+  }
+
+  via(edgeTypes: string[]): this {
+    this._opts = { ...this._opts, via: edgeTypes }
+    return this
+  }
+
+  minHops(n: number): this {
+    this._opts = { ...this._opts, minHops: n }
+    return this
+  }
+
+  // ── Résultats ──────────────────────────────────────────────────────────────
+
+  /**
+   * path(strategy?) — meilleur chemin selon la stratégie.
+   * Stratégie par défaut : Shortest (poids brut).
+   *
+   * metro:     graph.from('Pigalle').to('Alesia').path(Strategy.Comfort())
+   * musicians: graph.from('Jackson').to('West').path()
+   */
+  path(strategy?: Strategy): PathResult {
+    return this._findPaths(1, strategy)
+  }
+
+  /**
+   * paths(strategy?) — tous les chemins ordonnés par poids.
+   *
+   * metro:     graph.from('Chatelet').to('Nation').paths(Strategy.Shortest())
+   * musicians: graph.from('Pharrell').to('Kanye').paths()
+   */
+  paths(strategy?: Strategy): PathResult {
+    const maxPaths = this._opts.maxPaths ?? 5
+    return this._findPaths(maxPaths, strategy)
+  }
+
+  /**
+   * links — graphe de relations entre from et to.
+   * Retourne toutes les arêtes qui participent aux chemins possibles,
+   * sans les ordonner — vue structurelle, pas navigationnelle.
+   *
+   * musicians: graph.from('Jackson').to('West').links
+   */
+  get links(): PathResult & { edges: GraphEdge[] } {
+    const result = this._findPaths(this._opts.maxPaths ?? 10)
+    // Collecter toutes les arêtes participant aux chemins trouvés
+    const nodeSet = new Set(result.paths.flatMap(p => p.nodes))
+    const edges = this._graph.edges.filter(
+      e => nodeSet.has(e.from) && nodeSet.has(e.to)
+    )
+    return { ...result, edges }
+  }
+
+  /**
+   * execute(filters) — traversée avec hydratation de données.
+   * Uniquement disponible si un dataset ou provider est configuré.
+   *
+   * netflix:    graph.from('movies').to('people').execute({ id: 278 })
+   * dvdrental:  graph.from('customer').to('actor').execute({ id: 1 })
+   */
+  async execute<T = Record<string, any>>(
+    filters: Record<string, any> = {}
+  ): Promise<QueryResult<T>> {
+    if (!this._to) throw new Error(`PathBuilder : .to(node) requis avant execute()`)
+    const to    = this._to
+    const start = Date.now()
+
+    if (!this._compiled || !this._dataset) {
+      throw new Error(
+        `execute() nécessite un compiledGraph et un dataset.\n` +
+        `Utilisez new Graph(graphJson, { compiled, dataset }) pour activer la traversée de données.`
+      )
+    }
+
+    const engine = new QueryEngine(this._compiled)
+    const data   = engine.executeInMemory(
+      { from: this._from, to, filters },
+      this._dataset
+    ) as T[]
+
+    let path: string[] = [this._from, to]
+    try {
+      const route = engine.getRoute(this._from, to)
+      path = route.primary.path
+    } catch { /* route inconnue — chemin direct */ }
+
+    return {
+      from:    this._from,
+      to,
+      filters,
+      data,
+      path,
+      timing:  Date.now() - start,
+    }
+  }
+
+  // ── Interne ────────────────────────────────────────────────────────────────
+
+  private _assertTo(): void {
+    if (!this._to) throw new Error(`PathBuilder : .to(node) requis avant cette opération`)
+  }
+
+  private _findPaths(maxPaths: number, strategy?: Strategy): PathResult {
+    if (!this._to) throw new Error(`PathBuilder : .to(node) requis avant path()/paths()`)
+    const to = this._to
+
+    const penalty  = S.toPenalty(strategy ?? this._opts.strategy ?? S.Shortest())
+    const finder   = new PathFinder(this._graph)
+    const rawPaths = finder.findAllPaths(
+      this._from,
+      to,
+      maxPaths,
+      50,
+      penalty,
+      this._opts.via,
+      this._opts.minHops ?? 0
+    )
+
+    if (rawPaths.length === 0) {
+      return { from: this._from, to, found: false, paths: [] }
+    }
+
+    const paths: ResolvedPath[] = rawPaths.map(nodes => ({
+      nodes,
+      steps:  this._resolveSteps(nodes),
+      weight: this._computeWeight(nodes, penalty),
+      hops:   nodes.length - 1,
+    }))
+
+    return { from: this._from, to, found: true, paths }
+  }
+
+  /**
+   * Enrichit les nodes avec labels et arêtes empruntées.
+   */
+  private _resolveSteps(nodes: string[]): PathStep[] {
+    const nodeMap = new Map(this._graph.nodes.map(n => [n.id, n]))
+
+    return nodes.map((nodeId, i) => {
+      const node  = nodeMap.get(nodeId)
+      const step: PathStep = {
+        node:  nodeId,
+        label: (node as any)?.label ?? (node as any)?.name ?? nodeId,
+      }
+      if (i > 0) {
+        // Arête qui mène à ce node depuis le précédent
+        step.via = this._graph.edges.find(
+          e => e.from === nodes[i - 1] && e.to === nodeId
+        ) ?? this._graph.edges.find(
+          e => e.from === nodeId && e.to === nodes[i - 1]
+        )
+      }
+      return step
+    })
+  }
+
+  /**
+   * Calcule le poids total d'un chemin en tenant compte de la pénalité
+   * de correspondance (changement de ligne/type d'arête).
+   */
+  private _computeWeight(nodes: string[], transferPenalty: number): number {
+    let weight = 0
+    let prevEdgeType: string | undefined
+
+    for (let i = 0; i < nodes.length - 1; i++) {
+      const edge = this._graph.edges.find(
+        e => e.from === nodes[i] && e.to === nodes[i + 1]
+      )
+      const w    = edge ? Number(edge.weight) || 1 : 1
+      const type = edge?.metadata?.type ?? edge?.via
+
+      // Pénalité si changement de type d'arête (correspondance)
+      if (transferPenalty > 0 && prevEdgeType && type !== prevEdgeType) {
+        weight += transferPenalty
+      }
+
+      weight      += w
+      prevEdgeType = type
+    }
+
+    return weight
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,15 @@
+/**
+ * api/index.ts — Re-exports du dossier api/
+ */
+export { Graph }        from './Graph.js'
+export { PathBuilder }  from './PathBuilder.js'
+export {
+  Strategy,
+}                       from './types.js'
+export type {
+  PathResult,
+  ResolvedPath,
+  PathStep,
+  QueryResult,
+  PathBuilderOptions,
+}                       from './types.js'