@linklabjs/core 0.1.0

package/src/scenarios/test-netflix/queries.ts

@@ -0,0 +1,159 @@
+/**
+ * queries.ts — Requêtes scénario Netflix
+ *
+ * Démontre la navigation dans un graphe généré automatiquement par le pipeline.
+ * Le graphe contient 7 nœuds et 66 arêtes dont 56 vues sémantiques issues de
+ * credits.jobId → jobs (actor, director, writer, screenplay...).
+ *
+ * Usage :
+ *   tsx cli/run-scenario.ts scenarios/test-netflix --query directors-of-movie
+ *   tsx cli/run-scenario.ts scenarios/test-netflix --query all
+ *
+ * Graphe disponible :
+ *   Nœuds  : movies, people, credits, jobs, departments, categories, users
+ *   Arêtes physiques    : credits→movies, credits→people, credits→jobs, jobs→departments
+ *   Arêtes sémantiques  : movies↔people via [actor | director | writer | screenplay ...]
+ *   Arêtes virtuelles   : movies↔categories (array inline)
+ */
+
+import type { PathQuery } from '../../types/index.js'
+
+export interface NamedQuery {
+  name: string
+  description: string
+  query: PathQuery
+}
+
+export const netflixQueries: NamedQuery[] = [
+
+  // ============================================================
+  // NAVIGATION SÉMANTIQUE — Vues générées depuis credits.jobId
+  // ============================================================
+
+  {
+    name: 'directors-of-movie',
+    description: 'movies → people via vue sémantique "director"',
+    query: {
+      from: 'movies',
+      to: 'people',
+      via: ['director'],
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'actors-of-movie',
+    description: 'movies → people via vue sémantique "actor"',
+    query: {
+      from: 'movies',
+      to: 'people',
+      via: ['actor'],
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'movies-of-director',
+    description: 'people → movies via vue sémantique "director_in"',
+    query: {
+      from: 'people',
+      to: 'movies',
+      via: ['director_in'],
+      maxPaths: 3
+    }
+  },
+
+  {
+    name: 'movies-of-actor',
+    description: 'people → movies via vue sémantique "actor_in"',
+    query: {
+      from: 'people',
+      to: 'movies',
+      via: ['actor_in'],
+      maxPaths: 3
+    }
+  },
+
+  // ============================================================
+  // NAVIGATION PHYSIQUE — Relations FK déclarées
+  // ============================================================
+
+  {
+    name: 'credits-to-jobs',
+    description: 'credits → jobs (FK physique credits.jobId → jobs.id)',
+    query: {
+      from: 'credits',
+      to: 'jobs',
+      maxPaths: 2
+    }
+  },
+
+  {
+    name: 'jobs-to-departments',
+    description: 'jobs → departments (FK physique jobs.departmentId → departments.id)',
+    query: {
+      from: 'jobs',
+      to: 'departments',
+      maxPaths: 2
+    }
+  },
+
+  // ============================================================
+  // NAVIGATION VIRTUELLE — Array inline movies.categories
+  // ============================================================
+
+  {
+    name: 'movies-to-categories',
+    description: 'movies → categories (relation virtuelle depuis array inline)',
+    query: {
+      from: 'movies',
+      to: 'categories',
+      maxPaths: 2
+    }
+  },
+
+  // ============================================================
+  // CHEMINS LONGS — Traversées multi-sauts
+  // ============================================================
+
+  {
+    name: 'movies-to-departments',
+    description: 'movies → departments (2 sauts : movies→credits→jobs→departments)',
+    query: {
+      from: 'movies',
+      to: 'departments',
+      maxPaths: 2
+    }
+  },
+
+  {
+    name: 'people-to-departments',
+    description: 'people → departments (via credits → jobs → departments)',
+    query: {
+      from: 'people',
+      to: 'departments',
+      maxPaths: 3
+    }
+  },
+
+  // ============================================================
+  // CHEMIN MINIMAL — minHops
+  // ============================================================
+
+  {
+    name: 'people-to-movies-minhops',
+    description: 'people → movies chemin le plus court (minHops)',
+    query: {
+      from: 'people',
+      to: 'movies',
+      minHops: 1,
+      maxPaths: 5
+    }
+  }
+
+]
+
+/**
+ * Requête par défaut (utilisée sans --query)
+ */
+export const defaultQuery = netflixQueries.find(q => q.name === 'directors-of-movie')!

package/src/scenarios/test-netflix/stack.json

@@ -0,0 +1,14 @@
+[
+  {
+    "entity": "Directors",
+    "id": 2,
+    "state": "RESOLVED",
+    "purpose": "explore"
+  },
+  {
+    "entity": "Movies",
+    "id": null,
+    "state": "UNRESOLVED",
+    "purpose": "list"
+  }
+]

package/src/schema/GraphBuilder.ts

@@ -0,0 +1,106 @@
+import fs from 'fs'
+import path from 'path'
+import type { AnalyzedSchema, Dictionary, Relation } from '../types/index.js'
+
+export class GraphBuilder {
+  /**
+   * Construit le dictionnaire final à partir du schéma analysé
+   */
+  build(analyzed: AnalyzedSchema, dataPath: string): Dictionary {
+    const dictionary: Dictionary = {
+      tables: [],
+      relations: []
+    }
+
+    // 1. Déclarer les tables
+    for (const ent of analyzed.entities) {
+      dictionary.tables.push({
+        name: ent.name,
+        columns: ent.properties.map(p => p.name),
+        rowCount: ent.rowCount
+      })
+
+      // 2. Transformer les PK/FK physiques en relations de base
+      for (const prop of ent.properties) {
+        if (prop.isFK && prop.references) {
+          dictionary.relations.push({
+            from: ent.name,
+            to: prop.references.table,
+            via: prop.name,
+            type: 'physical',
+            weight: analyzed.weights[`${ent.name}.${prop.name}`] || 1,
+            label: `FK_${prop.name}`
+          })
+
+          // Relation inverse (One-to-Many implicite)
+          dictionary.relations.push({
+            from: prop.references.table,
+            to: ent.name,
+            via: prop.name,
+            type: 'physical_reverse',
+            weight: (analyzed.weights[`${ent.name}.${prop.name}`] || 1) * 1.1, // Légèrement plus lourd de remonter
+            label: `LIST_OF_${ent.name.toUpperCase()}`
+          })
+        }
+      }
+    }
+
+    // 3. Génération des Vues Sémantiques (L'intelligence métier)
+    this.injectVirtualViews(analyzed, dictionary, dataPath)
+
+    return dictionary
+  }
+
+  private injectVirtualViews(analyzed: AnalyzedSchema, dict: Dictionary, dataPath: string) {
+    // On cherche le conseil de pivot que l'Analyzer a posé
+    const pivotAdvices = analyzed.advices.filter(a => a.action === 'SUGGEST_VIRTUAL_VIEWS')
+
+    for (const advice of pivotAdvices) {
+      const pivotTable = advice.target // ex: 'credits'
+
+      // On cherche quelle table sert de "Type" pour segmenter (ex: jobs)
+      const entity = analyzed.entities.find(e => e.name === pivotTable)
+      const typeFK = entity?.properties.find(p =>
+        /type|job|category|role/i.test(p.references?.table || '')
+      )
+
+      if (typeFK && typeFK.references) {
+        const typeTableName = typeFK.references.table
+        const typeDataPath = path.join(dataPath, `${typeTableName}.json`)
+
+        if (fs.existsSync(typeDataPath)) {
+          const types = JSON.parse(fs.readFileSync(typeDataPath, 'utf-8'))
+
+          types.forEach((typeObj: any) => {
+            const roleName = typeObj.name.toLowerCase()
+
+            // Ignorer les rôles sans nom significatif
+            if (!roleName || /^unknow|^unknown|^n\/a/i.test(roleName)) return
+
+            // On crée l'arête sémantique : movies -> people (via credits filtré)
+            dict.relations.push({
+              from: 'movies',
+              to: 'people',
+              via: pivotTable,
+              type: 'semantic_view',
+              label: roleName,
+              condition: { [typeFK.name]: typeObj.id },
+              weight: 0.8 // Très léger car c'est une intention directe de l'utilisateur
+            })
+
+            // Et l'inverse : people -> movies (via credits filtré)
+            dict.relations.push({
+              from: 'people',
+              to: 'movies',
+              via: pivotTable,
+              type: 'semantic_view',
+              label: `${roleName}_in`,
+              condition: { [typeFK.name]: typeObj.id },
+              weight: 0.8
+            })
+          })
+        }
+      }
+    }
+  }
+}

package/src/schema/JsonSchemaExtractor.ts

@@ -0,0 +1,107 @@
+/**
+ * JsonSchemaExtractor — Extraction de schéma depuis des fichiers JSON
+ *
+ * Inférence automatique :
+ *   - Types de colonnes depuis le premier enregistrement
+ *   - FK par convention de nommage (*Id → table cible) via SynonymResolver
+ *   - Détection des arrays inline (ex: movies.categories)
+ *
+ * Synonymes :
+ *   Délégués à SynonymResolver — config/synonyms.json + <dataPath>/synonyms.json
+ */
+
+import fs from 'fs'
+import path from 'path'
+import type { TechnicalSchema, TechEntity, TechProperty } from '../types/index.js'
+import { SynonymResolver } from './SynonymResolver.js'
+
+export class JsonSchemaExtractor {
+
+  private resolver: SynonymResolver
+
+  constructor(
+    private dataPath: string,
+    configPath: string = path.join(process.cwd(), 'config')
+  ) {
+    // Passe le dataPath comme projectPath — synonyms.json projet y est optionnel
+    this.resolver = new SynonymResolver(configPath, dataPath)
+  }
+
+  async extract(): Promise<TechnicalSchema> {
+    console.log(`📂 JsonSchemaExtractor — scanning : ${this.dataPath}`)
+
+    const files = fs.readdirSync(this.dataPath)
+      .filter(f => f.endsWith('.json') && f !== 'synonyms.json')
+
+    const entities: TechEntity[] = []
+
+    // Passe 1 — inférer entités et propriétés
+    for (const file of files) {
+      const tableName = path.basename(file, '.json')
+      const content   = JSON.parse(fs.readFileSync(path.join(this.dataPath, file), 'utf-8'))
+
+      if (!Array.isArray(content) || content.length === 0) {
+        console.log(`   ⏭️  ${file} — vide ou non-liste, ignoré`)
+        continue
+      }
+
+      const properties = this.inferProperties(content[0])
+      const arrayCols  = properties.filter(p => p.type === 'array').map(p => p.name)
+
+      entities.push({ name: tableName, properties, rowCount: content.length })
+
+      console.log(
+        `   ✅ ${tableName} (${content.length} entrées` +
+        (arrayCols.length ? `, arrays: ${arrayCols.join(', ')}` : '') + ')'
+      )
+    }
+
+    // Passe 2 — résoudre les FK via SynonymResolver
+    this.resolveForeignKeys(entities)
+
+    return {
+      source: {
+        type: 'json_files',
+        name: path.basename(this.dataPath),
+        generatedAt: new Date().toISOString()
+      },
+      entities
+    }
+  }
+
+  private inferProperties(sample: Record<string, any>): TechProperty[] {
+    return Object.entries(sample).map(([key, value]) => ({
+      name:      key,
+      type:      Array.isArray(value)      ? 'array'
+               : value === null            ? 'null'
+               : typeof value === 'object' ? 'object'
+               : typeof value,
+      isPK:      key === 'id',
+      isFK:      false,
+      isIndexed: true,
+      nullable:  value === null
+    }))
+  }
+
+  private resolveForeignKeys(entities: TechEntity[]): void {
+    const tableNames = entities.map(e => e.name)
+
+    for (const entity of entities) {
+      for (const prop of entity.properties) {
+        if (prop.isPK) continue
+        if (!prop.name.endsWith('Id') && !prop.name.endsWith('_id')) continue
+
+        const target = this.resolver.resolveColumn(prop.name, tableNames)
+
+        if (target) {
+          prop.isFK       = true
+          prop.references = { table: target, column: 'id' }
+          console.log(`   🔗 ${entity.name}.${prop.name} → ${target}.id`)
+        } else {
+          const prefix = this.resolver.extractPrefix(prop.name)
+          console.log(`   ❓ ${entity.name}.${prop.name} — "${prefix}" introuvable`)
+        }
+      }
+    }
+  }
+}

package/src/schema/SchemaAnalyzer.ts

@@ -0,0 +1,175 @@
+/**
+ * SchemaAnalyzer — Analyse sémantique d'un schéma technique
+ *
+ * Produit :
+ *   - Poids par colonne (basés sur volumétrie et indexation)
+ *   - Advices de performance (FK non indexées)
+ *   - Détection de pivots sémantiques (tables de liaison)
+ *   - Détection de FK implicites via SynonymResolver
+ *     (colonnes *_id sans FK déclarée qui correspondent à une table existante)
+ *
+ * Compatible PostgreSQL et JSON — même logique quelque soit la source.
+ */
+
+import fs from 'fs'
+import type { TechnicalSchema, TechEntity, AnalysisAdvice, AnalyzedSchema } from '../types/index.js'
+import { SynonymResolver } from './SynonymResolver.js'
+
+export class SchemaAnalyzer {
+
+  private advices: AnalysisAdvice[] = []
+  private weights: Record<string, number> = {}
+  private resolver: SynonymResolver
+
+  constructor(
+    configPath: string = process.cwd() + '/config',
+    projectPath?: string
+  ) {
+    this.resolver = new SynonymResolver(configPath, projectPath)
+  }
+
+  analyze(schema: TechnicalSchema): AnalyzedSchema {
+    this.advices = []
+    this.weights = {}
+
+    for (const entity of schema.entities) {
+      this.analyzeEntity(entity)
+    }
+
+    this.detectSemanticPivots(schema)
+    this.detectImplicitFKs(schema)
+
+    return {
+      ...schema,
+      advices:           this.advices,
+      weights:           this.weights,
+      implicitRelations: this.collectImplicitRelations(schema)
+    }
+  }
+
+  // ─── Analyse par entité ────────────────────────────────────────────────────
+
+  private analyzeEntity(entity: TechEntity): void {
+    for (const prop of entity.properties) {
+      const key = `${entity.name}.${prop.name}`
+      let weight = 1
+
+      // FK non indexée — coût de traversée élevé
+      if (prop.isFK && !prop.isIndexed) {
+        weight = 10
+        this.advices.push({
+          type:    'PERFORMANCE',
+          level:   'WARNING',
+          target:  key,
+          message: `FK '${prop.name}' non indexée dans '${entity.name}'.`,
+          action:  `CREATE INDEX idx_${entity.name}_${prop.name} ON ${entity.name}(${prop.name});`
+        })
+      }
+
+      // Volumétrie — tables larges coûtent plus cher à traverser
+      if (entity.rowCount > 1000) {
+        weight += parseFloat(Math.log10(entity.rowCount / 100).toFixed(2))
+      }
+
+      this.weights[key] = weight
+    }
+  }
+
+  // ─── Pivots sémantiques ────────────────────────────────────────────────────
+
+  /**
+   * Détecte les tables de liaison (credits, film_category...)
+   * Pattern : table avec 2+ FK dont une vers une table de "types"
+   */
+  private detectSemanticPivots(schema: TechnicalSchema): void {
+    for (const entity of schema.entities) {
+      const fks = entity.properties.filter(p => p.isFK)
+      if (fks.length < 2) continue
+
+      const typeFK = fks.find(fk =>
+        /type|job|category|dept|role|department/i.test(fk.references?.table ?? '')
+      )
+
+      if (typeFK) {
+        this.advices.push({
+          type:    'STRUCTURE',
+          level:   'INFO',
+          target:  entity.name,
+          message: `Pivot sémantique — segmentation possible par '${typeFK.references!.table}'.`,
+          action:  'SUGGEST_VIRTUAL_VIEWS'
+        })
+      }
+    }
+  }
+
+  // ─── FK implicites ─────────────────────────────────────────────────────────
+
+  /**
+   * Détecte les colonnes *_id sans FK déclarée qui correspondent
+   * à une table existante via SynonymResolver.
+   *
+   * Utile pour :
+   *   - PostgreSQL : FK non déclarées (store.store_id non contrainte)
+   *   - JSON       : colonnes oubliées dans la passe 2 de JsonSchemaExtractor
+   */
+  private detectImplicitFKs(schema: TechnicalSchema): void {
+    const tableNames = schema.entities.map(e => e.name)
+
+    for (const entity of schema.entities) {
+      for (const prop of entity.properties) {
+        // Ignorer PK et FK déjà déclarées
+        if (prop.isPK || prop.isFK) continue
+        if (!prop.name.endsWith('_id') && !prop.name.endsWith('Id')) continue
+
+        const target = this.resolver.resolveColumn(prop.name, tableNames)
+        if (!target) continue
+
+        // FK implicite trouvée
+        this.advices.push({
+          type:    'STRUCTURE',
+          level:   'INFO',
+          target:  `${entity.name}.${prop.name}`,
+          message: `FK implicite détectée : '${entity.name}.${prop.name}' → '${target}'.`,
+          action:  'ADD_IMPLICIT_FK'
+        })
+      }
+    }
+  }
+
+  /**
+   * Collecte les FK implicites comme relations exploitables par GraphBuilder.
+   */
+  private collectImplicitRelations(schema: TechnicalSchema): Array<{
+    fromTable: string
+    column:    string
+    guessedTable: string
+  }> {
+    const tableNames = schema.entities.map(e => e.name)
+    const result: Array<{ fromTable: string; column: string; guessedTable: string }> = []
+
+    for (const entity of schema.entities) {
+      for (const prop of entity.properties) {
+        if (prop.isPK || prop.isFK) continue
+        if (!prop.name.endsWith('_id') && !prop.name.endsWith('Id')) continue
+
+        const target = this.resolver.resolveColumn(prop.name, tableNames)
+        if (target) {
+          result.push({
+            fromTable:    entity.name,
+            column:       prop.name,
+            guessedTable: target
+          })
+        }
+      }
+    }
+
+    return result
+  }
+
+  // ─── Persistence ───────────────────────────────────────────────────────────
+
+  saveAnalysis(analyzed: AnalyzedSchema, outputPath: string): void {
+    fs.writeFileSync(outputPath, JSON.stringify(analyzed, null, 2))
+    console.log(`💾 Analyse sauvegardée : ${outputPath}`)
+  }
+}

package/src/schema/SchemaExtractor.ts

@@ -0,0 +1,102 @@
+import fs from 'fs'
+import type { Provider, TechnicalSchema, TechEntity, TechProperty } from '../types/index.js'
+
+export class SchemaExtractor {
+  constructor(private provider: Provider) {}
+
+  async extract(databaseName: string): Promise<TechnicalSchema> {
+    console.log(`🔍 Extraction du schéma technique pour : ${databaseName}`)
+
+    const tables = await this.getTables()
+    const entities: TechEntity[] = []
+
+    for (const tableName of tables) {
+      const properties = await this.getProperties(tableName)
+      const rowCount = await this.getRowCount(tableName)
+
+      entities.push({
+        name: tableName,
+        properties,
+        rowCount
+      })
+    }
+
+    const schema: TechnicalSchema = {
+      source: {
+        type: 'postgresql',
+        name: databaseName,
+        generatedAt: new Date().toISOString()
+      },
+      entities
+    }
+
+    fs.writeFileSync('./schema.json', JSON.stringify(schema, null, 2))
+    return schema
+  }
+
+  private async getTables(): Promise<string[]> {
+    const query = `
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+    `
+    const rows = await this.provider.query<{ table_name: string }>(query)
+    return rows.map(r => r.table_name)
+  }
+
+  private async getProperties(tableName: string): Promise<TechProperty[]> {
+    const query = `
+      SELECT
+        cols.column_name as name,
+        cols.data_type as type,
+        -- Détection Primary Key
+        EXISTS (
+          SELECT 1 FROM information_schema.table_constraints tc
+          JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name
+          WHERE tc.table_name = cols.table_name AND kcu.column_name = cols.column_name
+          AND tc.constraint_type = 'PRIMARY KEY'
+        ) as is_pk,
+        -- Détection Foreign Key Target
+        ccu.table_name as fk_target_table,
+        ccu.column_name as fk_target_column,
+        -- Détection Index
+        EXISTS (
+          SELECT 1 FROM pg_index i
+          JOIN pg_class c ON c.oid = i.indrelid
+          JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(i.indkey)
+          WHERE c.relname = cols.table_name AND a.attname = cols.column_name
+        ) as is_indexed
+      FROM information_schema.columns cols
+      LEFT JOIN information_schema.key_column_usage kcu
+        ON cols.table_name = kcu.table_name AND cols.column_name = kcu.column_name
+      LEFT JOIN information_schema.referential_constraints rc
+        ON kcu.constraint_name = rc.constraint_name
+      LEFT JOIN information_schema.constraint_column_usage ccu
+        ON rc.unique_constraint_name = ccu.constraint_name
+      WHERE cols.table_name = $1
+    `
+
+    const rows = await this.provider.query<any>(query, [tableName])
+
+    return rows.map(r => ({
+      name: r.name,
+      type: r.type,
+      isPK: r.is_pk,
+      isFK: !!r.fk_target_table,
+      references: r.fk_target_table
+        ? {
+            table: r.fk_target_table,
+            column: r.fk_target_column
+          }
+        : undefined,
+      isIndexed: r.is_indexed
+    }))
+  }
+
+  private async getRowCount(tableName: string): Promise<number> {
+    const res = await this.provider.query<{ count: string }>(
+      `SELECT reltuples::bigint as count FROM pg_class WHERE relname = $1`,
+      [tableName]
+    )
+    return parseInt(res[0]?.count || '0', 10)
+  }
+}