agentic-api 2.0.31 → 2.0.314

package/dist/src/rag/types.d.ts

@@ -44,16 +44,6 @@ export interface RAGMetadata {
     config: RAGConfig;
     /** Mapping ID → référence document/section */
     documents: Record<string, DocumentReference>;
-    /**
-     * Dernier identifiant documentaire attribué.
-     * Utilisé pour générer un ID documentaire stable (matter.id) indépendant du nom de fichier.
-     */
-    docLastID?: number;
-    /** Checkpoint avec le hash du dernier commit de la branche */
-    checkpoint: {
-        branch: string;
-        hash: string;
-    };
     /** Statistiques de l'index */
     stats: {
         totalDocuments: number;
@@ -98,13 +88,25 @@ export interface DocumentSection {
 export interface ParsedDocument {
     /** Nom du fichier source dans GIT*/
     filename: string;
-    /** Métadonnées du front-matter */
-    matter: Record<string, any>;
+    /** Métadonnées du front-matter (id et title obligatoires) */
+    matter: RAGMatter;
     /** Contenu sans le front-matter */
     content: string;
     /** Sections du document */
     sections: DocumentSection[];
 }
+/**
+ * Métadonnées du front-matter d'un document RAG
+ * IMPORTANT: id et title sont obligatoires
+ */
+export interface RAGMatter {
+    /** Identifiant documentaire stable (entier positif, max 2^32-1 pour hnswlib) */
+    id: number;
+    /** Titre descriptif du document */
+    title: string;
+    /** Propriétés optionnelles supplémentaires */
+    [key: string]: string | Date | number | boolean;
+}
 export interface RAGRef {
     /** ID du document */
     id: number;
@@ -158,6 +160,32 @@ export interface DocumentQueries {
     queries: UserQuery[];
     /** Coût de l'extraction */
     cost: number;
+    /** fingerprint content hash (SHA-256 du contenu source) - Optionnel pour rétrocompatibilité */
+    fingerprint?: string;
+}
+/**
+ * Résultat de la construction d'un index vectoriel
+ *
+ * Retourné par Embeddings.indexFromDocuments() pour que RAGManager
+ * puisse créer les métadonnées complètes du RAG.
+ *
+ * Cette interface sépare clairement les responsabilités :
+ * - Embeddings : Construction de l'index vectoriel
+ * - RAGManager : Gestion des métadonnées et du cycle de vie
+ */
+export interface IndexBuildResult {
+    /** Nombre total de vecteurs indexés */
+    totalVectors: number;
+    /** Dimensions des vecteurs */
+    vectorDimensions: number;
+    /** Références des documents avec leurs métadonnées */
+    documents: Record<string, DocumentReference>;
+    /** Mapping ID -> ref des sections */
+    mapping: Record<string, string>;
+    /** Tag de version généré */
+    tag: string;
+    /** Version du format */
+    version: string;
 }
 /** Interface pour le fichier de mapping des IDs */
 export interface RAGMapping {
@@ -176,3 +204,91 @@ export interface RAGMapping {
  * Génère un tag de version au format vYYYYMMDD
  */
 export declare function generateVersionTag(): string;
+/**
+ * Contraintes pour les IDs hnswlib-node
+ * Les labels dans hnswlib sont des entiers non-signés 32 bits
+ */
+export declare const HNSW_ID_CONSTRAINTS: {
+    readonly MIN: 0;
+    readonly MAX: 4294967295;
+    readonly RESERVED_START: 0;
+    readonly RESERVED_END: 999;
+};
+/**
+ * Vérifie si un ID est valide pour hnswlib-node
+ *
+ * Les contraintes sont :
+ * - Doit être un entier
+ * - Doit être >= 0
+ * - Doit être <= 2^32-1 (4294967295)
+ * - Doit être > 999 (pour éviter les IDs réservés)
+ *
+ * @param id L'ID à vérifier
+ * @returns true si l'ID est valide, false sinon
+ *
+ * @example
+ * ```typescript
+ * isValidHNSWID(1000) // true
+ * isValidHNSWID(999) // false (réservé)
+ * isValidHNSWID(-1) // false (négatif)
+ * isValidHNSWID(1.5) // false (pas un entier)
+ * ```
+ */
+export declare function isValidHNSWID(id: number): boolean;
+/**
+ * Vérifie si les métadonnées RAGMatter sont valides
+ *
+ * Les contraintes sont :
+ * - id et title doivent être définis
+ * - id doit être un entier valide pour hnswlib (> 999, < 2^32)
+ * - title doit être une chaîne non vide
+ *
+ * @param matter Les métadonnées à vérifier
+ * @returns true si les métadonnées sont valides, false sinon
+ * @throws Error avec un message descriptif si les métadonnées sont invalides
+ *
+ * @example
+ * ```typescript
+ * isValidRAGMatter({ id: 1000, title: 'Mon document' }) // true
+ * isValidRAGMatter({ id: 999, title: 'Test' }) // throws (ID réservé)
+ * isValidRAGMatter({ id: 1000, title: '' }) // throws (titre vide)
+ * ```
+ */
+export declare function isValidRAGMatter(matter: any): matter is RAGMatter;
+/** Interface pour une entrée du registre RAG */
+export interface RAGRegistryEntry {
+    /** Identifiant unique (slug) */
+    name: string;
+    /** Chemin vers le dossier du RAGConfig (tempPath si building, destDir si active) */
+    configPath: string;
+    /** Chemin de destination finale (utilisé pour remplacer configPath après build) */
+    destDir?: string;
+    /** Statut du RAG */
+    status: 'active' | 'building' | 'archived' | 'error' | 'paused';
+    /** Description optionnelle du RAG */
+    description?: string;
+    /** Hash du dernier commit Git (checkpoint pour builds incrémentaux) */
+    checkpoint?: string;
+}
+/** Interface pour le registre des RAG */
+export interface RAGRegistry {
+    /** Version du registre */
+    version: string;
+    /** Liste des RAG disponibles */
+    registries: Record<string, RAGRegistryEntry>;
+    /** RAG par défaut (par défaut: 'RAGRegistry') */
+    defaultName?: string;
+}
+/** Configuration du gestionnaire RAG */
+export interface RAGManagerConfig {
+    /** Répertoire de base du registre */
+    baseDir: string;
+    /** Répertoire temporaire pour les constructions */
+    tempDir?: string;
+    /** Répertoire d'archives */
+    archiveDir?: string;
+    /** Nombre maximum d'archives par RAG */
+    maxArchives?: number;
+    /** Mode verbose */
+    verbose?: boolean;
+}

package/dist/src/rag/types.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RAG_FILES = void 0;
+exports.HNSW_ID_CONSTRAINTS = exports.RAG_FILES = void 0;
 exports.generateVersionTag = generateVersionTag;
+exports.isValidHNSWID = isValidHNSWID;
+exports.isValidRAGMatter = isValidRAGMatter;
 // Constantes pour les noms de fichiers RAG
 exports.RAG_FILES = {
     VECTORS: 'rag-hnsw.dat',
@@ -19,3 +21,100 @@ function generateVersionTag() {
     const day = String(today.getDate()).padStart(2, '0');
     return `v${year}${month}${day}`;
 }
+/**
+ * Contraintes pour les IDs hnswlib-node
+ * Les labels dans hnswlib sont des entiers non-signés 32 bits
+ */
+exports.HNSW_ID_CONSTRAINTS = {
+    MIN: 0,
+    MAX: 4294967295, // 2^32 - 1
+    RESERVED_START: 0,
+    RESERVED_END: 999 // IDs réservés pour usage interne
+};
+/**
+ * Vérifie si un ID est valide pour hnswlib-node
+ *
+ * Les contraintes sont :
+ * - Doit être un entier
+ * - Doit être >= 0
+ * - Doit être <= 2^32-1 (4294967295)
+ * - Doit être > 999 (pour éviter les IDs réservés)
+ *
+ * @param id L'ID à vérifier
+ * @returns true si l'ID est valide, false sinon
+ *
+ * @example
+ * ```typescript
+ * isValidHNSWID(1000) // true
+ * isValidHNSWID(999) // false (réservé)
+ * isValidHNSWID(-1) // false (négatif)
+ * isValidHNSWID(1.5) // false (pas un entier)
+ * ```
+ */
+function isValidHNSWID(id) {
+    return (Number.isInteger(id) &&
+        id >= exports.HNSW_ID_CONSTRAINTS.MIN &&
+        id <= exports.HNSW_ID_CONSTRAINTS.MAX &&
+        id > exports.HNSW_ID_CONSTRAINTS.RESERVED_END);
+}
+/**
+ * Vérifie si les métadonnées RAGMatter sont valides
+ *
+ * Les contraintes sont :
+ * - id et title doivent être définis
+ * - id doit être un entier valide pour hnswlib (> 999, < 2^32)
+ * - title doit être une chaîne non vide
+ *
+ * @param matter Les métadonnées à vérifier
+ * @returns true si les métadonnées sont valides, false sinon
+ * @throws Error avec un message descriptif si les métadonnées sont invalides
+ *
+ * @example
+ * ```typescript
+ * isValidRAGMatter({ id: 1000, title: 'Mon document' }) // true
+ * isValidRAGMatter({ id: 999, title: 'Test' }) // throws (ID réservé)
+ * isValidRAGMatter({ id: 1000, title: '' }) // throws (titre vide)
+ * ```
+ */
+function isValidRAGMatter(matter) {
+    // Vérifier que matter existe
+    if (!matter || typeof matter !== 'object' || Array.isArray(matter)) {
+        throw new Error('RAGMatter: matter est requis et doit être un objet');
+    }
+    // Vérifier que id existe et est un nombre
+    if (matter.id === undefined || matter.id === null) {
+        // Message plus explicite si le matter est complètement vide
+        const matterKeys = Object.keys(matter);
+        if (matterKeys.length === 0) {
+            throw new Error('RAGMatter: le front-matter est vide. Le contenu fourni ne contient probablement pas de front-matter YAML. Utilisez matterSerialize() pour ajouter le front-matter avant d\'appeler getSections().');
+        }
+        throw new Error(`RAGMatter: le champ "id" est obligatoire (matter reçu: ${JSON.stringify(matter)})`);
+    }
+    if (typeof matter.id !== 'number') {
+        throw new Error(`RAGMatter: le champ "id" doit être un nombre (reçu: ${typeof matter.id})`);
+    }
+    // Vérifier que l'ID est valide pour hnswlib
+    if (!isValidHNSWID(matter.id)) {
+        if (!Number.isInteger(matter.id)) {
+            throw new Error(`RAGMatter: l'ID ${matter.id} doit être un entier`);
+        }
+        if (matter.id <= exports.HNSW_ID_CONSTRAINTS.RESERVED_END) {
+            throw new Error(`RAGMatter: l'ID ${matter.id} est réservé (doit être > ${exports.HNSW_ID_CONSTRAINTS.RESERVED_END})`);
+        }
+        if (matter.id > exports.HNSW_ID_CONSTRAINTS.MAX) {
+            throw new Error(`RAGMatter: l'ID ${matter.id} dépasse la limite maximale (${exports.HNSW_ID_CONSTRAINTS.MAX})`);
+        }
+        throw new Error(`RAGMatter: l'ID ${matter.id} n'est pas valide`);
+    }
+    // Vérifier que title existe et est une chaîne non vide
+    if (matter.title === undefined || matter.title === null) {
+        throw new Error('RAGMatter: le champ "title" est obligatoire');
+    }
+    if (typeof matter.title !== 'string') {
+        throw new Error(`RAGMatter: le champ "title" doit être une chaîne (reçu: ${typeof matter.title})`);
+    }
+    if (matter.title.trim().length === 0) {
+        throw new Error('RAGMatter: le champ "title" ne peut pas être vide');
+    }
+    return true;
+}

package/dist/src/rag/usecase.d.ts

@@ -1,4 +1,12 @@
 import { DocumentQueries, UserQuery, RAGConfig, ParsedDocument } from './types';
+/**
+ * Calcule le fingerprint SHA-256 d'un contenu
+ * Utilisé pour détecter si un document a changé et nécessite une re-extraction
+ *
+ * @param content Contenu du document
+ * @returns Hash SHA-256 en hexadécimal
+ */
+export declare function calculateFingerprint(content: string): string;
 /**
  * Extrait tous les use cases d'un document parsé
  */
@@ -14,3 +22,32 @@ export declare function saveUseCases(queries: DocumentQueries, config: RAGConfig
  * Charge les use cases depuis un fichier JSON
  */
 export declare function loadUseCases(file: string, config: RAGConfig): DocumentQueries;
+/**
+ * Extrait et sauvegarde les use cases d'un document
+ * Fonction standalone indépendante de la classe Embeddings
+ *
+ * Optimisation: Utilise un fingerprint (SHA-256) pour détecter si le document a changé.
+ * Si le fingerprint est identique, retourne les use cases existants sans re-extraction.
+ *
+ * @param document Document parsé
+ * @param baseDir Dossier où sauvegarder le fichier .query.json
+ * @param version Version du RAG (optionnel)
+ * @param tag Tag de version (optionnel)
+ * @param options Options d'extraction
+ * @param options.force Forcer la re-extraction même si le fingerprint est identique
+ * @param options.verbose Afficher les logs détaillés
+ * @returns Les queries extraites avec leur coût
+ *
+ * @example
+ * ```typescript
+ * // Extraction avec cache (skip si fingerprint identique)
+ * const queries = await extractAndSaveDocumentUseCases(doc, './rag');
+ *
+ * // Forcer la re-extraction
+ * const queries = await extractAndSaveDocumentUseCases(doc, './rag', '1.0', 'v1', { force: true });
+ * ```
+ */
+export declare function extractAndSaveDocumentUseCases(document: ParsedDocument, baseDir: string, version?: string, tag?: string, options?: {
+    force?: boolean;
+    verbose?: boolean;
+}): Promise<DocumentQueries>;

package/dist/src/rag/usecase.js

@@ -3,12 +3,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFingerprint = calculateFingerprint;
 exports.extractDocumentUseCases = extractDocumentUseCases;
 exports.saveUseCases = saveUseCases;
 exports.loadUseCases = loadUseCases;
+exports.extractAndSaveDocumentUseCases = extractAndSaveDocumentUseCases;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const types_1 = require("./types");
 const usecase_1 = require("../usecase");
+/**
+ * Calcule le fingerprint SHA-256 d'un contenu
+ * Utilisé pour détecter si un document a changé et nécessite une re-extraction
+ *
+ * @param content Contenu du document
+ * @returns Hash SHA-256 en hexadécimal
+ */
+function calculateFingerprint(content) {
+    return (0, crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');
+}
 /**
  * Extrait tous les use cases d'un document parsé
  */
@@ -26,22 +40,22 @@ async function extractDocumentUseCases(parsedDocument) {
             continue;
         }
         try {
-            const { json, cost } = await (0, usecase_1.callGPTToExtractUserQueries)(section.content, filename);
-            const result = JSON.parse(json);
+            const { json, cost } = await (0, usecase_1.llmExtractUserQueries)(section.content, filename);
+            const result = json ? JSON.parse(json) : { queries: [] };
             if (result.queries && Array.isArray(result.queries)) {
                 // Enrichir chaque query avec les informations de section
                 const enrichedQueries = result.queries.map((query) => ({
                     ...query,
                     filename: path_1.default.basename(filename, path_1.default.extname(filename)),
-                    sectionIndex: index,
-                    ref: `${path_1.default.basename(filename, path_1.default.extname(filename))}#section-${index}`
+                    sectionIndex: section.index,
+                    ref: `${path_1.default.basename(filename, path_1.default.extname(filename))}#section-${section.index}`
                 }));
                 allQueries.push(...enrichedQueries);
             }
             totalCost += cost;
         }
         catch (error) {
-            console.error(`Erreur lors de l'extraction des use cases pour ${filename}, section ${index}:`, error);
+            console.error(`Erreur lors de l'extraction des use cases pour ${filename}, section ${index}:`, error.message);
         }
     }
     return { queries: allQueries, cost: totalCost };
@@ -52,8 +66,12 @@ async function extractDocumentUseCases(parsedDocument) {
 function saveUseCases(queries, config) {
     try {
         const file = path_1.default.join(config.baseDir, queries.file);
+        // Créer le répertoire s'il n'existe pas
+        const dir = path_1.default.dirname(file);
+        if (!(0, fs_1.existsSync)(dir)) {
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        }
         (0, fs_1.writeFileSync)(file, JSON.stringify(queries, null, 2), 'utf8');
-        console.log(`🔔 Use cases sauvegardés: ${file}`);
     }
     catch (error) {
         console.error('Erreur lors de la sauvegarde des use cases:', error);
@@ -73,7 +91,78 @@ function loadUseCases(file, config) {
         return JSON.parse((0, fs_1.readFileSync)(queriesFile, 'utf8'));
     }
     catch (error) {
-        console.error('🔔 Erreur lors du chargement des use cases:', error);
+        console.error('🔔 Erreur lors du chargement des use cases:', error.message);
         throw new Error(`Erreur lors du chargement des use cases: ${queriesFile} ${error.message}`);
     }
 }
+/**
+ * Extrait et sauvegarde les use cases d'un document
+ * Fonction standalone indépendante de la classe Embeddings
+ *
+ * Optimisation: Utilise un fingerprint (SHA-256) pour détecter si le document a changé.
+ * Si le fingerprint est identique, retourne les use cases existants sans re-extraction.
+ *
+ * @param document Document parsé
+ * @param baseDir Dossier où sauvegarder le fichier .query.json
+ * @param version Version du RAG (optionnel)
+ * @param tag Tag de version (optionnel)
+ * @param options Options d'extraction
+ * @param options.force Forcer la re-extraction même si le fingerprint est identique
+ * @param options.verbose Afficher les logs détaillés
+ * @returns Les queries extraites avec leur coût
+ *
+ * @example
+ * ```typescript
+ * // Extraction avec cache (skip si fingerprint identique)
+ * const queries = await extractAndSaveDocumentUseCases(doc, './rag');
+ *
+ * // Forcer la re-extraction
+ * const queries = await extractAndSaveDocumentUseCases(doc, './rag', '1.0', 'v1', { force: true });
+ * ```
+ */
+async function extractAndSaveDocumentUseCases(document, baseDir, version, tag, options = {}) {
+    const { force = false, verbose = false } = options;
+    const filename = path_1.default.basename(document.filename, path_1.default.extname(document.filename));
+    const queryFile = path_1.default.join(baseDir, filename + '.query.json');
+    // Calculer le fingerprint du contenu source
+    const fingerprint = calculateFingerprint(document.content || '');
+    // Vérifier si le fichier existe déjà et si le fingerprint est identique
+    if (!force && (0, fs_1.existsSync)(queryFile)) {
+        try {
+            const existingQueries = JSON.parse((0, fs_1.readFileSync)(queryFile, 'utf8'));
+            // Comparer le fingerprint
+            if (existingQueries.fingerprint === fingerprint) {
+                if (verbose) {
+                    console.log(`⏭️ Use cases à jour (fingerprint identique): ${document.filename}`);
+                }
+                return existingQueries;
+            }
+            else if (verbose) {
+                console.log(`🔄 Contenu modifié (fingerprint différent): ${document.filename}`);
+            }
+        }
+        catch (error) {
+            // Si erreur de lecture, on continue avec l'extraction
+            if (verbose) {
+                console.warn(`⚠️ Erreur lecture use cases existants: ${error}`);
+            }
+        }
+    }
+    // Extraction nécessaire (fichier inexistant, fingerprint différent, ou force=true)
+    if (verbose && force) {
+        console.log(`🔄 Re-extraction forcée: ${document.filename}`);
+    }
+    const { queries, cost } = await extractDocumentUseCases(document);
+    const docQueries = {
+        type: 'use-cases',
+        version: version || '1.0',
+        tag: tag || (0, types_1.generateVersionTag)(),
+        source: document.filename,
+        file: filename + '.query.json',
+        cost,
+        queries,
+        fingerprint // ✅ Ajouter le fingerprint
+    };
+    saveUseCases(docQueries, { baseDir });
+    return docQueries;
+}

package/dist/src/rules/git/git.e2e.helper.js

@@ -404,6 +404,7 @@ class GitE2EFactory {
             gitConfig,
             autoCleanup: options?.autoCleanup ?? true
         };
+        testConfig.gitConfig.verbose = options?.customConfig?.verbose ?? false;
         const helper = new GitE2EHelper(testConfig);
         // Set test environment
         process.env.NODE_ENV = 'test';

package/dist/src/rules/git/git.health.d.ts

@@ -1,4 +1,16 @@
 import { RulesGitConfig, GitHealthStatus } from '../types';
+/**
+ * Rapport d'analyse des IDs
+ */
+export interface SafeIDsReport {
+    scanned: number;
+    valid: number;
+    missingID: string[];
+    missingTitle: string[];
+    invalidID: string[];
+    duplicateID: string[];
+    errors: string[];
+}
 /**
  * Git Repository Health Manager
  *
@@ -63,4 +75,49 @@ export declare class GitHealthManager {
      * - Erreurs de traitement par branche → continue avec les autres
      */
     migrateNotes(): Promise<void>;
+    /**
+     * Analyse les IDs des documents Markdown dans une branche
+     *
+     * @param branch Branche à analyser (par défaut: toutes les branches)
+     * @returns Rapport d'analyse avec les fichiers problématiques
+     */
+    analyseSafeIDs(branch?: string): Promise<SafeIDsReport>;
+    /**
+     * Répare les IDs problématiques identifiés dans un rapport d'analyse
+     *
+     * @param report Rapport d'analyse généré par analyseSafeIDs
+     * @param options Options de réparation
+     * @param options.dryRun Mode simulation (affiche les réparations sans modifier)
+     * @returns Rapport mis à jour avec les fichiers réparés
+     */
+    repairSafeIDs(report: SafeIDsReport, options?: {
+        dryRun?: boolean;
+    }): Promise<SafeIDsReport>;
+    /**
+     * Vérifie et répare les IDs manquants dans tous les documents Markdown du repository
+     *
+     * Cette méthode orchestre l'analyse et la réparation :
+     * 1. Analyse les documents avec analyseSafeIDs()
+     * 2. Si autoFix est activé, répare avec repairSafeIDs()
+     *
+     * @param options Options de scan et réparation
+     * @param options.branch Branche spécifique à scanner (par défaut: toutes les branches)
+     * @param options.autoFix Active la réparation automatique (par défaut: false)
+     * @param options.dryRun Mode simulation (affiche les problèmes sans modifier)
+     * @returns Résumé des documents scannés et réparés
+     */
+    ensureSafeIDS(options?: {
+        branch?: string;
+        autoFix?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        scanned: number;
+        valid: number;
+        missingID: number;
+        missingTitle: number;
+        invalidID: number;
+        duplicateID: number;
+        fixed: number;
+        errors: string[];
+    }>;
 }