@linklabjs/core 0.1.0 → 0.1.2

package/dist/api/PathBuilder.js

@@ -0,0 +1,182 @@
+/**
+ * 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 { PathFinder } from '../core/PathFinder.js';
+import { QueryEngine } from '../runtime/QueryEngine.js';
+import { Strategy as S } from './types.js';
+export class PathBuilder {
+    _from;
+    _to = null;
+    _opts;
+    _graph;
+    _compiled;
+    _dataset;
+    _provider;
+    constructor(from, graph, compiled = null, dataset = null, opts = {}, provider = null) {
+        this._from = from;
+        this._graph = graph;
+        this._compiled = compiled;
+        this._dataset = dataset;
+        this._opts = opts;
+        this._provider = provider;
+    }
+    // ── Builder ────────────────────────────────────────────────────────────────
+    to(node) {
+        this._to = node;
+        return this;
+    }
+    maxPaths(n) {
+        this._opts = { ...this._opts, maxPaths: n };
+        return this;
+    }
+    via(edgeTypes) {
+        this._opts = { ...this._opts, via: edgeTypes };
+        return this;
+    }
+    minHops(n) {
+        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) {
+        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) {
+        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() {
+        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(filters = {}) {
+        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);
+        let path = [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 ────────────────────────────────────────────────────────────────
+    _assertTo() {
+        if (!this._to)
+            throw new Error(`PathBuilder : .to(node) requis avant cette opération`);
+    }
+    _findPaths(maxPaths, strategy) {
+        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 = 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.
+     */
+    _resolveSteps(nodes) {
+        const nodeMap = new Map(this._graph.nodes.map(n => [n.id, n]));
+        return nodes.map((nodeId, i) => {
+            const node = nodeMap.get(nodeId);
+            const step = {
+                node: nodeId,
+                label: node?.label ?? node?.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).
+     */
+    _computeWeight(nodes, transferPenalty) {
+        let weight = 0;
+        let prevEdgeType;
+        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;
+    }
+}
+//# sourceMappingURL=PathBuilder.js.map

package/dist/api/PathBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathBuilder.js","sourceRoot":"","sources":["../../src/api/PathBuilder.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAa,YAAY,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAO,kBAAkB,CAAA;AAC/C,OAAO,EACL,QAAQ,GACT,MAA4B,YAAY,CAAA;AACzC,YAAY,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,kBAAkB,GACnB,MAA4B,YAAY,CAAA"}

package/dist/api/index.js

@@ -0,0 +1,7 @@
+/**
+ * api/index.ts — Re-exports du dossier api/
+ */
+export { Graph } from './Graph.js';
+export { PathBuilder } from './PathBuilder.js';
+export { Strategy, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAa,YAAY,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAO,kBAAkB,CAAA;AAC/C,OAAO,EACL,QAAQ,GACT,MAA4B,YAAY,CAAA"}

package/dist/api/loadGraph.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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';
+/** Source du graphe compilé */
+export type GraphSource = string | 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;
+}
+/**
+ * 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 declare function loadGraph(source: GraphSource, options?: LoadGraphOptions): Promise<ReturnType<Graph['domain']>>;
+/** Alias — même API, nom plus court pour les imports fréquents */
+export { loadGraph as graph };
+//# sourceMappingURL=loadGraph.d.ts.map

package/dist/api/loadGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadGraph.d.ts","sourceRoot":"","sources":["../../src/api/loadGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAI1E,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,iBAAiB,CAAA;AAErB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAI,aAAa,CAAA;IACzB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC;IACtE,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAwDD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAG,WAAW,EACpB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAkFtC;AAID,kEAAkE;AAClE,OAAO,EAAE,SAAS,IAAI,KAAK,EAAE,CAAA"}

package/dist/api/loadGraph.js

@@ -0,0 +1,153 @@
+/**
+ * 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';
+// ── Détection environnement ────────────────────────────────────────────────────
+const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
+const IS_BROWSER = typeof globalThis.window !== 'undefined';
+// ── Chargement JSON ────────────────────────────────────────────────────────────
+async function loadJSON(source) {
+    // 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) {
+    // './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, options = {}) {
+    let compiled;
+    let reference = null;
+    let overrides = null;
+    let dictionary = 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 = reference ?? {
+        nodes: compiled.nodes,
+        edges: [],
+    };
+    const { compiled: _c, reference: _r, overrides: _o, dataDir: _d, dataset: _ds, ...graphOptions } = options;
+    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 };
+//# sourceMappingURL=loadGraph.js.map

package/dist/api/loadGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadGraph.js","sourceRoot":"","sources":["../../src/api/loadGraph.ts"],"names":[],"mappings":"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"}

package/dist/api/test-api.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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)
+ */
+export {};
+//# sourceMappingURL=test-api.d.ts.map

package/dist/api/test-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-api.d.ts","sourceRoot":"","sources":["../../src/api/test-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/api/test-api.js

@@ -0,0 +1,133 @@
+/**
+ * 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) => console.log(`  ✅ ${label}`);
+const err = (label, e) => console.log(`  ❌ ${label}: ${e?.message ?? e}`);
+const sep = (title) => 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.map((m) => 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));
+//# sourceMappingURL=test-api.js.map

package/dist/api/test-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-api.js","sourceRoot":"","sources":["../../src/api/test-api.ts"],"names":[],"mappings":"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"}

package/dist/api/test-domain.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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)
+ */
+export {};
+//# sourceMappingURL=test-domain.d.ts.map

package/dist/api/test-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-domain.d.ts","sourceRoot":"","sources":["../../src/api/test-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}