@linklabjs/core 0.1.0

package/src/http/plugin.ts

@@ -0,0 +1,360 @@
+/**
+ * LinkLab Fastify Plugin
+ *
+ * Transforme automatiquement chaque requête HTTP en Trail,
+ * résout la navigation via le graphe, et retourne une réponse
+ * HATEOAS Level 3 — liens générés automatiquement depuis le graphe.
+ *
+ * Usage minimal :
+ * ```typescript
+ * import Fastify from 'fastify'
+ * import { linklabPlugin } from '@linklab/http'
+ *
+ * const fastify = Fastify()
+ * await fastify.register(linklabPlugin, {
+ *   graph:  compiledGraph,
+ *   prefix: '/api'
+ * })
+ * await fastify.listen({ port: 3000 })
+ * ```
+ *
+ * Toutes ces routes fonctionnent sans configuration supplémentaire :
+ *   GET /api/people
+ *   GET /api/people/Nolan
+ *   GET /api/people/Nolan/movies
+ *   GET /api/people/Nolan/movies/1/actors
+ *
+ * Hooks disponibles sur chaque requête :
+ * ```typescript
+ * fastify.register(linklabPlugin, {
+ *   graph,
+ *   onEngine: (engine, req) => {
+ *     engine.hooks.on('access.check', async (ctx) => {
+ *       if (!ctx.trail.user.userId) {
+ *         return { cancelled: true, reason: 'unauthenticated' }
+ *       }
+ *     })
+ *   }
+ * })
+ * ```
+ */
+
+import type {
+  FastifyPluginAsync,
+  FastifyRequest,
+  FastifyReply,
+} from 'fastify'
+import fp from 'fastify-plugin'
+
+import type { Graph, CompiledGraph } from '../types/index.js'
+import { Trail }                  from '../navigation/Trail.js'
+import { TrailParser }            from '../navigation/TrailParser.js'
+import { NavigationEngine }       from '../navigation/NavigationEngine.js'
+import { LinkBuilder }            from './LinkBuilder.js'
+import { DataLoader, type DataLoaderOptions } from '../runtime/DataLoader.js'
+import {
+  defaultUserExtractor,
+  type UserContextExtractor,
+} from './TrailRequest.js'
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface LinklabPluginOptions {
+  /** Le graphe sémantique — navigation, LinkBuilder, Resolver */
+  graph: Graph
+
+  /** Le graphe compilé — routes SQL optimales pour DataLoader/QueryEngine */
+  compiledGraph?: CompiledGraph
+
+  /** Préfixe URL — ex: '/api' ou '/api/v1' */
+  prefix?: string
+
+  /** Contexte global injecté dans chaque Trail */
+  global?: Record<string, any>
+
+  /**
+   * Extracteur de contexte utilisateur.
+   * Par défaut : lit req.user ou req.session.user
+   */
+  extractUser?: UserContextExtractor
+
+  /**
+   * Hook appelé après création du moteur, avant résolution.
+   * C'est ici que Netflix branche sa logique métier.
+   *
+   * @example
+   * ```typescript
+   * onEngine: (engine, req) => {
+   *   engine.hooks.on('access.check', async (ctx) => {
+   *     if (!ctx.trail.user.subscription) {
+   *       return { cancelled: true, reason: 'subscription_required' }
+   *     }
+   *   })
+   * }
+   * ```
+   */
+  onEngine?: (engine: NavigationEngine, req: FastifyRequest) => void | Promise<void>
+
+  /**
+   * Options du DataLoader — source de données réelles.
+   *
+   * @example
+   * ```typescript
+   * // Mode JSON (Netflix mock / tests)
+   * dataLoader: { dataset: { movies, people, credits } }
+   *
+   * // Mode SQL (PostgreSQL)
+   * dataLoader: { provider: postgresProvider }
+   * ```
+   */
+  dataLoader?: DataLoaderOptions
+
+  /**
+   * Transforme les données avant envoi.
+   * Utile pour la pagination, la sérialisation custom, etc.
+   */
+  transformData?: (data: any, trail: Trail) => any
+}
+
+// ── Format de réponse ─────────────────────────────────────────
+
+export interface TrailResponse {
+  data:    any
+  _links:  Record<string, any>
+  _trail:  string
+  _meta:   ResponseMeta
+}
+
+export interface ResponseMeta {
+  entity:   string
+  depth:    number
+  resolved: number
+  timing:   number
+  count?:   number
+}
+
+// ── Helper — vérifie qu'un node est exposé ───────────────────
+// Un node sans flag exposed (graphe ancien) est considéré exposé
+// pour assurer la rétrocompatibilité.
+// Un node avec exposed: false est bloqué.
+
+function isExposed(graph: Graph, entity: string): boolean {
+  const node = graph.nodes.find(n => n.id === entity)
+  if (!node) return false
+  // Rétrocompatibilité : si exposed n'est pas défini, on expose
+  if (node.exposed === undefined) return true
+  return node.exposed === true
+}
+
+// ── Plugin ────────────────────────────────────────────────────
+
+const linklabPluginImpl: FastifyPluginAsync<LinklabPluginOptions> = async (
+  fastify,
+  options
+) => {
+  const {
+    graph,
+    prefix        = '',
+    global        = {},
+    extractUser   = defaultUserExtractor,
+    onEngine,
+    dataLoader,
+    transformData,
+  } = options
+
+  const linkBuilder = new LinkBuilder(graph, { prefix })
+
+  // compiledGraph peut être passé séparément (semantic graph + compiled graph distincts)
+  // ou graph peut lui-même être un CompiledGraph (avec .routes)
+  const effectiveCompiled: CompiledGraph | null =
+    options.compiledGraph
+      ?? ('routes' in graph && Array.isArray((graph as any).routes) ? graph as any : null)
+
+  const loader = (dataLoader && effectiveCompiled)
+    ? new DataLoader(effectiveCompiled, dataLoader)
+    : null
+
+  if (dataLoader && !effectiveCompiled) {
+    fastify.log.warn('[LinkLab] dataLoader ignoré : graph doit être un CompiledGraph (avec .routes)')
+  }
+
+  // ── Décorer chaque request avec trail + linkBuilder ─────────
+  fastify.decorateRequest('trail',       null as any)
+  fastify.decorateRequest('linkBuilder', null as any)
+
+  // ── Hook preHandler — parse le Trail avant chaque requête ───
+  fastify.addHook('preHandler', async (req: FastifyRequest) => {
+    const userCtx = await extractUser(req)
+
+    const rawPath = req.url.split('?')[0]
+    const path    = prefix ? rawPath.replace(new RegExp(`^${prefix}`), '') : rawPath
+
+    const trail = TrailParser.fromPath(path, {
+      global: { ...global },
+      user:   userCtx,
+    })
+
+    ;(req as any).trail       = trail
+    ;(req as any).linkBuilder = linkBuilder
+  })
+
+  // ── Routes génériques — capture tous les paths ─────────────
+  const routePath  = prefix ? `${prefix}/*` : '/*'
+  const rootPath   = prefix || '/'
+
+  // Route pour le prefix exact ex: GET /api
+  fastify.get(rootPath, async (
+    req:   FastifyRequest,
+    reply: FastifyReply
+  ) => {
+    const links = buildRootLinks(graph, prefix)
+    return { data: null, _links: links, _trail: '', _meta: { entity: 'root', depth: 0, resolved: 0, timing: 0 } }
+  })
+
+  fastify.get(routePath, async (
+    req:   FastifyRequest,
+    reply: FastifyReply
+  ): Promise<TrailResponse> => {
+    const trail   = (req as any).trail as Trail
+    const start   = Date.now()
+
+    // Trail vide = index — retourner les nœuds racines du graphe
+    if (trail.depth === 0) {
+      const rootLinks = buildRootLinks(graph, prefix)
+      return {
+        data:   null,
+        _links: rootLinks,
+        _trail: '',
+        _meta:  { entity: 'root', depth: 0, resolved: 0, timing: Date.now() - start },
+      }
+    }
+
+    // ── Vérifier que toutes les frames du Trail pointent vers des nodes exposés
+    // On vérifie chaque entité du Trail — si l'une est non exposée → 404.
+    // Cela couvre aussi les vues sémantiques : leur entité cible résolue
+    // est vérifiée au moment de la résolution du Trail.
+    for (const frame of trail.frames) {
+      if (!isExposed(graph, frame.entity)) {
+        reply.code(404)
+        return reply.send({
+          error:  'NOT_FOUND',
+          reason: `Entity '${frame.entity}' is not exposed`,
+          _trail: TrailParser.toFluent(trail),
+        }) as any
+      }
+    }
+
+    // ── Créer le moteur de navigation ─────────────────────────
+    const engine = NavigationEngine.forNavigation(graph, { trail })
+
+    // Laisser Netflix (ou tout autre app) brancher ses hooks
+    if (onEngine) {
+      await onEngine(engine, req)
+    }
+
+    // ── Résoudre le Trail ─────────────────────────────────────
+    const results = await engine.run(trail.depth + 1)
+    const lastResult = results[results.length - 1]
+
+    // ── Gérer les erreurs de navigation ───────────────────────
+    if (lastResult?.result?.type === 'FAIL') {
+      const reason = lastResult.result.reason ?? 'Navigation failed'
+
+      if (reason.includes('notfound') || reason.includes('Aucun chemin')) {
+        reply.code(404)
+        return reply.send({
+          error:  'NOT_FOUND',
+          reason,
+          _trail: TrailParser.toFluent(trail),
+        }) as any
+      }
+
+      if (reason.includes('forbidden') || reason.includes('denied') || reason.includes('unauthenticated')) {
+        reply.code(403)
+        return reply.send({
+          error:  'FORBIDDEN',
+          reason,
+          _trail: TrailParser.toFluent(trail),
+        }) as any
+      }
+
+      reply.code(400)
+      return reply.send({
+        error:  'BAD_REQUEST',
+        reason,
+        _trail: TrailParser.toFluent(trail),
+      }) as any
+    }
+
+    // ── Charger les données via DataLoader ───────────────────
+    if (loader) {
+      await loader.load(engine.trail)
+    }
+
+    // ── Récupérer les données de la frame courante ────────────
+    const current  = engine.trail.current
+    const rawData  = current?.data ?? null
+    const data     = transformData ? transformData(rawData, engine.trail) : rawData
+
+    // ── Générer les liens HATEOAS ─────────────────────────────
+    const links = linkBuilder.from(engine.trail)
+
+    // Si data est une liste, enrichir chaque item avec ses liens
+    const isCollection = Array.isArray(data)
+    let responseData   = data
+
+    if (isCollection && data.length > 0) {
+      const itemLinks = linkBuilder.forItems(engine.trail, data)
+      responseData    = data.map((item: any, i: number) => ({
+        ...item,
+        _links: itemLinks[i],
+      }))
+    }
+
+    // ── Construire la réponse ─────────────────────────────────
+    const resolved = engine.trail.frames.filter(f => f.state === 'RESOLVED').length
+
+    return {
+      data:   responseData,
+      _links: links,
+      _trail: TrailParser.toFluent(engine.trail),
+      _meta:  {
+        entity:   current?.entity ?? '',
+        depth:    engine.trail.depth,
+        resolved,
+        timing:   Date.now() - start,
+        count:    isCollection ? data.length : undefined,
+      },
+    }
+  })
+}
+
+// ── Helper — liens racines ────────────────────────────────────
+// Filtre les nodes non exposés des liens racines.
+
+function buildRootLinks(graph: Graph, prefix: string): Record<string, any> {
+  const hasIncoming = new Set(graph.edges.map(e => e.to))
+  const roots       = graph.nodes.filter(n =>
+    !hasIncoming.has(n.id) && isExposed(graph, n.id)
+  )
+
+  const links: Record<string, any> = {
+    self: { href: prefix || '/', method: 'GET' }
+  }
+
+  for (const node of roots) {
+    links[node.id] = {
+      href:   `${prefix}/${node.id}`,
+      method: 'GET',
+      rel:    node.id,
+    }
+  }
+
+  return links
+}
+
+// ── Export avec fastify-plugin (preserve encapsulation) ───────
+export const linklabPlugin = fp(linklabPluginImpl, {
+  fastify: '4.x || 5.x',
+  name:    'linklab',
+})

package/src/index.ts

@@ -0,0 +1,121 @@
+/**
+ * @linklab/core — Point d'entrée public
+ *
+ * Trois zones d'export, du plus utilisé au plus technique :
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  API  — ce que 80% des utilisateurs importent           │
+ *   │  BUILD — pipeline schema → graph (setup, CI)            │
+ *   │  HTTP  — plugin Fastify HATEOAS (optionnel)             │
+ *   │  ADVANCED — internals pour extensions et tests          │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * Usage typique :
+ *
+ *   import { Graph, Strategy } from '@linklab/core'
+ *
+ *   const cinema = new Graph(graphJson, { compiled, dataset }).domain()
+ *   const cast   = await cinema.movies(278).people
+ *   const route  = cinema.from('Pigalle').to('Alesia').path(Strategy.Comfort())
+ */
+
+// ══════════════════════════════════════════════════════════════
+//  API — Surface publique principale
+//  import { Graph, Strategy } from '@linklab/core'
+// ══════════════════════════════════════════════════════════════
+
+export { Graph } from './api/Graph.js'
+export { Strategy } from './api/types.js'
+export type {
+  PathResult,
+  ResolvedPath,
+  PathStep,
+  QueryResult,
+  PathBuilderOptions
+} from './api/types.js'
+
+// PathBuilder est retourné par graph.from() — exposé pour le typage
+export { PathBuilder } from './api/PathBuilder.js'
+
+// ══════════════════════════════════════════════════════════════
+//  BUILD — Pipeline schema → graph
+//  Usage : scripts de génération, CI, pipeline.ts
+//  import { SchemaExtractor, GraphCompiler } from '@linklab/core/build'
+// ══════════════════════════════════════════════════════════════
+
+export { SchemaExtractor } from './schema/SchemaExtractor.js'
+export { JsonSchemaExtractor } from './schema/JsonSchemaExtractor.js'
+export { SchemaAnalyzer } from './schema/SchemaAnalyzer.js'
+export { GraphBuilder } from './schema/GraphBuilder.js'
+export { GraphAssembler } from './graph/GraphAssembler.js'
+export { GraphCompiler } from './graph/GraphCompiler.js'
+export { GraphTrainer } from './graph/GraphTrainer.js'
+export { GraphOptimizer } from './graph/GraphOptimizer.js'
+export { GraphExtractor } from './graph/GraphExtractor.js'
+
+// ══════════════════════════════════════════════════════════════
+//  HTTP — Plugin Fastify HATEOAS
+//  Usage : apps serveur
+//  import { linklabPlugin } from '@linklab/core'
+// ══════════════════════════════════════════════════════════════
+
+export { linklabPlugin } from './http/plugin.js'
+export { LinkBuilder } from './http/LinkBuilder.js'
+export type { LinklabPluginOptions } from './http/plugin.js'
+
+// ══════════════════════════════════════════════════════════════
+//  ADVANCED — Internals pour extensions, providers, tests
+//  Stable mais sans garantie de compatibilité entre versions
+// ══════════════════════════════════════════════════════════════
+
+// Moteur de navigation bas niveau
+export { NavigationEngine } from './navigation/NavigationEngine.js'
+export { Resolver } from './navigation/Resolver.js'
+export { Scheduler } from './navigation/Scheduler.js'
+export { Trail } from './navigation/Trail.js'
+export { TrailParser } from './navigation/TrailParser.js'
+
+// Runtime
+export { QueryEngine } from './runtime/QueryEngine.js'
+export { Engine } from './runtime/Engine.js'
+export { DataLoader } from './runtime/DataLoader.js'
+
+// Providers
+export { PostgresProvider } from './providers/PostgresProvider.js'
+export { MockProvider } from './providers/MockProvider.js'
+
+// Formatters
+export type { PathFormatter } from './formatters/BaseFormatter.js'
+
+// PathFinder — algorithme Dijkstra brut
+export { PathFinder } from './core/PathFinder.js'
+
+// ══════════════════════════════════════════════════════════════
+//  TYPES — tous les types internes
+//  Pour les utilisateurs qui construisent sur les internals
+// ══════════════════════════════════════════════════════════════
+
+export type {
+  Graph as GraphData, // renommé pour éviter le conflit avec la classe Graph
+  GraphNode,
+  GraphEdge,
+  CompiledGraph,
+  RouteInfo,
+  Dictionary,
+  Frame,
+  Path,
+  PathQuery
+} from './types/index.js'
+
+export type { MetricsMap, TrainingMetrics, UseCase } from './types/index.js'
+
+// ── Instrumentation — opt-in telemetry bridge ─────────────────────────────
+export {
+  injectTelemetry,
+  resetTelemetry,
+  preloadTelemetry,
+  shim
+} from './instrumentation/TelemetryShim.js'
+export type { TelemetryModule } from './instrumentation/TelemetryShim.js'
+
+export type { ExposeConfig } from './types/index.js'

package/src/instrumentation/TelemetryShim.ts

@@ -0,0 +1,172 @@
+/**
+ * TelemetryShim.ts — Pont opt-in entre @linklab/core et @linklab/telemetry
+ *
+ * @linklab/core ne dépend PAS de @linklab/telemetry.
+ *
+ * Deux modes d'activation :
+ *
+ * 1. INJECTION (recommandé, toujours fiable) :
+ *    L'appelant qui connaît les deux packages injecte les modules directement.
+ *    Utilisé dans les tests (@linklab/telemetry) et en production (Netflix-backend).
+ *
+ *      import { injectTelemetry } from '@linklab/core'
+ *      import { SpanBuilder, traceBus } from '@linklab/telemetry'
+ *      injectTelemetry({ SpanBuilder, traceBus })
+ *
+ * 2. PRELOAD (production uniquement) :
+ *    Import dynamique — fonctionne si @linklab/telemetry est installé ET
+ *    accessible depuis le même module resolver que @linklab/core.
+ *    Ne pas utiliser dans les tests (résolution cross-package impossible sous Vitest).
+ *
+ *      import { preloadTelemetry } from '@linklab/core'
+ *      await preloadTelemetry()
+ *
+ * Sans activation → toutes les opérations sont des no-ops silencieux.
+ */
+
+// ── Types minimaux inlinés — pas d'import depuis @linklab/telemetry ───────────
+
+interface MinimalSpanBuilder {
+  stepStart(step: string): this
+  stepEnd(step: string): this
+  addCacheEvent(event: {
+    level: 'L1' | 'L2' | 'MISS'
+    hit: boolean
+    entity?: string
+    promoted: boolean
+    yoyo?: boolean
+  }): this
+  end(opts: { rowCount: number }): MinimalSpan
+  endWithError(err: Error, state: MinimalEngineState): MinimalSpan
+  withPath?(path: string[]): this
+  withFilters?(filters: Record<string, any>): this
+  readonly routeKey: string
+}
+
+interface MinimalSpan {
+  spanId: string
+  traceId: string
+  timestamp: number
+  trail: string
+  from: string
+  to: string
+  path: string[]
+  filters: Record<string, any>
+  timings: any[]
+  totalMs: number
+  cacheEvents: any[]
+  rowCount: number
+  error?: any
+  metrics?: any
+}
+
+interface MinimalEngineState {
+  compiledGraphHash: string
+  weights: Record<string, number>
+  cacheState: {
+    l1HitRate: number
+    l2HitRate: number
+    globalHitRate: number
+    yoyoEvents: number
+  }
+}
+
+export interface TelemetryModule {
+  SpanBuilder: {
+    start(opts: { trail: string; from: string; to: string; traceId?: string }): MinimalSpanBuilder
+  }
+  traceBus: {
+    emit(event: 'span:end' | 'span:error', span: MinimalSpan): void
+  }
+}
+
+// ── Registre interne ──────────────────────────────────────────────────────────
+
+let _module: TelemetryModule | null = null
+let _attempted = false
+
+// ── API d'injection ───────────────────────────────────────────────────────────
+
+/**
+ * Injecte les composants de @linklab/telemetry dans le shim.
+ * Méthode universelle — fonctionne dans tous les contextes (tests, prod).
+ * Prend effet immédiatement et de manière synchrone.
+ */
+export function injectTelemetry(module: TelemetryModule): void {
+  _module = module
+  _attempted = true // bloquer tout preloadTelemetry() ultérieur
+}
+
+/**
+ * Réinitialise le shim — utile pour les tests d'isolation.
+ */
+export function resetTelemetry(): void {
+  _module = null
+  _attempted = false
+}
+
+/**
+ * Précharge le module telemetry via import dynamique.
+ * Uniquement pour la production (Netflix-backend) où les deux packages
+ * partagent le même module resolver Node.js.
+ * Ne pas utiliser dans les tests — préférer injectTelemetry().
+ */
+export async function preloadTelemetry(): Promise<void> {
+  if (_attempted) return
+  _attempted = true
+  try {
+    const specifier = '@linklab/telemetry'
+    const mod = await new Function('s', 'return import(s)')(specifier)
+    _module = mod as TelemetryModule
+  } catch {
+    _module = null
+  }
+}
+
+// ── API du shim ───────────────────────────────────────────────────────────────
+
+export const shim = {
+  startSpan(opts: {
+    trail: string
+    from: string
+    to: string
+    traceId?: string
+    path?: string[]
+    filters?: Record<string, any>
+  }): MinimalSpanBuilder | null {
+    if (!_module) return null
+    try {
+      const builder = _module.SpanBuilder.start({
+        trail: opts.trail,
+        from: opts.from,
+        to: opts.to,
+        traceId: opts.traceId
+      })
+      if (opts.path) builder.withPath?.(opts.path)
+      if (opts.filters) builder.withFilters?.(opts.filters)
+      return builder
+    } catch {
+      return null
+    }
+  },
+
+  emitEnd(span: MinimalSpan): void {
+    if (!_module) return
+    try {
+      _module.traceBus.emit('span:end', span)
+    } catch {}
+  },
+
+  emitError(span: MinimalSpan): void {
+    if (!_module) return
+    try {
+      _module.traceBus.emit('span:error', span)
+    } catch {}
+  },
+
+  get active(): boolean {
+    return _module !== null
+  }
+}
+
+export type { MinimalSpanBuilder, MinimalSpan, MinimalEngineState }