agentic-api 2.0.491 → 2.0.592

package/dist/src/rag/embeddings.js

@@ -10,6 +10,8 @@ const path_1 = __importDefault(require("path"));
 const types_1 = require("./types");
 const parser_1 = require("./parser");
 const utils_1 = require("../utils");
+const llm_1 = require("../llm");
+const modelconfig_1 = require("../execute/modelconfig");
 const usecase_1 = require("./usecase");
 class Embeddings {
     constructor(config) {
@@ -22,6 +24,7 @@ class Embeddings {
         this.distance = config.distance || 'cosine';
         this.inmemory = config.inmemory || false;
         this.debug = false;
+        this.provider = config.provider || 'openai';
         // Charger l'index existant si disponible et pas en mode inmemory
         if (!this.inmemory && (0, fs_1.existsSync)(this.vectorsFile)) {
             this.loadIndex();
@@ -127,14 +130,19 @@ class Embeddings {
         };
     }
     /**
-     * Recherche sémantique avec OpenAI
+     * Recherche sémantique avec le provider de l'embedding
+     * @param question La question à rechercher
+     * @param options Options de recherche
+     * @returns Les résultats de la recherche
      */
     async semanticSearch(question, options = {}) {
         const startTime = Date.now();
-        const openai = (0, utils_1.openaiInstance)();
+        const provider = this.provider;
+        const openai = (0, llm_1.llmInstance)({ provider });
+        const embeddingConfig = (0, modelconfig_1.modelConfig)("EMBEDDING-small", { provider });
         // Créer l'embedding de la question
         const embedding = await openai.embeddings.create({
-            model: 'text-embedding-3-small',
+            model: embeddingConfig.model,
             input: question,
             dimensions: this.space,
             encoding_format: 'float',
@@ -263,7 +271,9 @@ class Embeddings {
         const m = options?.m || this.config.hnswConfig?.m || 32;
         const isUpdate = options?.update || false;
         const prepare = options?.prepare || ((input) => input);
-        const openai = (0, utils_1.openaiInstance)();
+        const provider = this.provider;
+        const openai = (0, llm_1.llmInstance)({ provider });
+        const embeddingConfig = (0, modelconfig_1.modelConfig)("EMBEDDING-small", { provider });
         const vectors = {};
         const documentRefs = {};
         const documentReferences = {};
@@ -304,7 +314,7 @@ class Embeddings {
                 }
                 // Créer l'embedding de la section
                 const embedding = await openai.embeddings.create({
-                    model: "text-embedding-3-small",
+                    model: embeddingConfig.model,
                     input: prepare(section.content),
                     dimensions: this.space,
                     encoding_format: "float",

package/dist/src/rag/parser.js

@@ -34,7 +34,7 @@ function getSections(content, filename) {
     content = contentWithoutMatter || content;
     //
     // le contenu est toujours sans le front-matter!
-    const rawSections = content.split('---').map(section => section.trim());
+    const rawSections = content.split('\n---\n').map(section => section.trim());
     if (!rawSections.length) {
         return {
             filename,

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

@@ -47,6 +47,9 @@ export declare class RAGManager {
     /**
      * Notifie les embeddings chargés de se mettre à jour
      *
+     * Cette méthode est publique pour permettre aux applications de notifier
+     * les utilisateurs actifs du RAG (tools, search) qu'il a été mis à jour.
+     *
      * @param name Nom du RAG à mettre à jour
      * @param opts Options de mise à jour (action: 'rename' pour renommer un document)
      *
@@ -59,18 +62,22 @@ export declare class RAGManager {
      *
      * @example
      * ```typescript
-     * // Après un build
-     * this.notifyUpdate('procedures-stable');
+     * // Après un build externe
+     * ragManager.notifyUpdate('procedures-stable');
      *
      * // Après un rename de document
-     * this.notifyUpdate('procedures-stable', {
+     * ragManager.notifyUpdate('procedures-stable', {
      *   action: 'rename',
      *   oldFile: 'old.md',
      *   newFile: 'new.md'
      * });
      * ```
      */
-    private notifyUpdate;
+    notifyUpdate(name: string, opts?: {
+        action?: 'rename';
+        oldFile?: string;
+        newFile?: string;
+    }): void;
     /**
      * Génère un nom d'archive avec timestamp YYYMMDD
      */
@@ -161,6 +168,15 @@ export declare class RAGManager {
      * ```
      */
     addDocument(name: string, filename: string, content: string): void;
+    /**
+     * Marque un document comme entièrement traité (enhanced + query.json générés)
+     * Le .sha est écrit APRÈS le traitement complet pour garantir la cohérence
+     *
+     * @param name Nom du RAG
+     * @param filename Nom du fichier (ex: 'procedure.md')
+     * @param content Contenu du document traité
+     */
+    markDocumentProcessed(name: string, filename: string, content: string): void;
     /**
      * Prépare un RAG enfant en copiant les documents d'un RAG parent
      *
@@ -242,6 +258,26 @@ export declare class RAGManager {
      * ```
      */
     loadUseCases(name: string, filename: string): DocumentQueries;
+    /**
+     * Charge tous les use cases de tous les documents d'un RAG
+     *
+     * Utilise le fichier rag-metadata.json pour obtenir la liste des documents valides
+     * puis charge chaque fichier .query.json correspondant
+     *
+     * @param name Nom du RAG
+     * @returns Objet contenant tous les use cases par document
+     *
+     * @example
+     * ```typescript
+     * const allQueries = ragManager.loadAllUseCases('my-rag');
+     * console.log(`${Object.keys(allQueries.documents).length} documents avec use cases`);
+     * console.log(`${allQueries.totalQueries} questions au total`);
+     * ```
+     */
+    loadAllUseCases(name: string): {
+        documents: Record<string, DocumentQueries>;
+        totalQueries: number;
+    };
     /**
      * Construit un RAG de manière atomique
      *
@@ -274,7 +310,7 @@ export declare class RAGManager {
     /**
      * Supprime un RAG du registre
      */
-    delete(name: string, archiveFlag?: boolean): Promise<void>;
+    delete(name: string, archiveFlag?: boolean): Promise<void | Error>;
     /**
      * Renomme un document dans un RAG existant
      *
@@ -306,7 +342,8 @@ export declare class RAGManager {
      */
     private updateJSONReferences;
     /**
-     * Renomme un RAG existant
+     * Renomme un RAG existant (nom dans le registre uniquement)
+     * Le dossier physique n'est PAS modifié, seul le nom dans la config change.
      *
      * @param from Nom actuel du RAG
      * @param to Nouveau nom du RAG
@@ -316,6 +353,7 @@ export declare class RAGManager {
      * @example
      * ```typescript
      * await ragManager.rename('old-name', 'new-name', 'Description mise à jour');
+     * // Le dossier reste /path/to/old-name mais le RAG s'appelle 'new-name'
      * ```
      */
     rename(from: string, to: string, description?: string): Promise<void>;

package/dist/src/rag/rag.manager.js

@@ -53,12 +53,19 @@ class RAGManager {
         DEFAULT_RAG_INSTANCE[defaultName] = this;
     }
     static get(config) {
-        // Vérifier si une instance existe déjà pour ce baseDir
-        if (DEFAULT_RAG_INSTANCE[config.baseDir]) {
-            return DEFAULT_RAG_INSTANCE[config.baseDir];
-        }
-        // Créer une nouvelle instance
-        return new RAGManager(config);
+        // Normaliser le baseDir pour éviter les doublons dus aux trailing slashes
+        // ou aux variations de paths (relatif/absolu, symlinks, etc.)
+        const normalizedBaseDir = path_1.default.resolve(config.baseDir).replace(/\/+$/, '');
+        // Vérifier si une instance existe déjà pour ce baseDir normalisé
+        if (DEFAULT_RAG_INSTANCE[normalizedBaseDir]) {
+            return DEFAULT_RAG_INSTANCE[normalizedBaseDir];
+        }
+        // Créer une nouvelle instance avec le baseDir normalisé
+        const normalizedConfig = {
+            ...config,
+            baseDir: normalizedBaseDir
+        };
+        return new RAGManager(normalizedConfig);
     }
     /**
      * Nettoie le cache des instances (utile pour les tests)
@@ -206,6 +213,9 @@ class RAGManager {
     /**
      * Notifie les embeddings chargés de se mettre à jour
      *
+     * Cette méthode est publique pour permettre aux applications de notifier
+     * les utilisateurs actifs du RAG (tools, search) qu'il a été mis à jour.
+     *
      * @param name Nom du RAG à mettre à jour
      * @param opts Options de mise à jour (action: 'rename' pour renommer un document)
      *
@@ -218,11 +228,11 @@ class RAGManager {
      *
      * @example
      * ```typescript
-     * // Après un build
-     * this.notifyUpdate('procedures-stable');
+     * // Après un build externe
+     * ragManager.notifyUpdate('procedures-stable');
      *
      * // Après un rename de document
-     * this.notifyUpdate('procedures-stable', {
+     * ragManager.notifyUpdate('procedures-stable', {
      *   action: 'rename',
      *   oldFile: 'old.md',
      *   newFile: 'new.md'
@@ -495,18 +505,31 @@ class RAGManager {
         if (!entry) {
             throw new Error(`RAG '${name}' n'existe pas`);
         }
-        // if (status.status !== 'building') {
-        //   throw new Error(`RAG '${name}' n'est pas en construction (status: ${status.status})`);
-        // }
         const buildPath = entry.configPath;
         if (!(0, fs_1.existsSync)(buildPath)) {
             throw new Error(`Le dossier de construction n'existe pas: ${buildPath}`);
         }
         const filePath = path_1.default.join(buildPath, filename);
-        const shaPath = path_1.default.join(buildPath, filename + '.sha');
-        // ✅ Sauvegarder le fichier
+        // ✅ Sauvegarder le fichier source uniquement
+        // Le .sha est écrit par markDocumentProcessed() APRÈS génération de .enhanced.md et .query.json
         (0, fs_1.writeFileSync)(filePath, content, 'utf8');
-        // ✅ Sauvegarder le fingerprint
+    }
+    /**
+     * Marque un document comme entièrement traité (enhanced + query.json générés)
+     * Le .sha est écrit APRÈS le traitement complet pour garantir la cohérence
+     *
+     * @param name Nom du RAG
+     * @param filename Nom du fichier (ex: 'procedure.md')
+     * @param content Contenu du document traité
+     */
+    markDocumentProcessed(name, filename, content) {
+        const entry = this.getEntry(name);
+        if (!entry) {
+            throw new Error(`RAG '${name}' n'existe pas`);
+        }
+        const buildPath = entry.configPath;
+        const shaPath = path_1.default.join(buildPath, filename + '.sha');
+        // ✅ Sauvegarder le fingerprint pour marquer le document comme traité
         const sha = (0, usecase_1.calculateFingerprint)(content);
         (0, fs_1.writeFileSync)(shaPath, sha, 'utf8');
     }
@@ -686,6 +709,72 @@ class RAGManager {
         const queryFile = baseName + '.query.json';
         return (0, usecase_1.loadUseCases)(queryFile, { baseDir: configPath });
     }
+    /**
+     * Charge tous les use cases de tous les documents d'un RAG
+     *
+     * Utilise le fichier rag-metadata.json pour obtenir la liste des documents valides
+     * puis charge chaque fichier .query.json correspondant
+     *
+     * @param name Nom du RAG
+     * @returns Objet contenant tous les use cases par document
+     *
+     * @example
+     * ```typescript
+     * const allQueries = ragManager.loadAllUseCases('my-rag');
+     * console.log(`${Object.keys(allQueries.documents).length} documents avec use cases`);
+     * console.log(`${allQueries.totalQueries} questions au total`);
+     * ```
+     */
+    loadAllUseCases(name) {
+        const entry = this.getEntry(name);
+        if (!entry) {
+            throw new Error(`RAG '${name}' n'existe pas`);
+        }
+        //
+        // Charger le metadata pour obtenir la liste des documents
+        const metadataFile = path_1.default.join(entry.configPath, types_1.RAG_FILES.METADATA);
+        if (!(0, fs_1.existsSync)(metadataFile)) {
+            throw new Error(`Fichier metadata manquant: ${metadataFile}`);
+        }
+        let metadata;
+        try {
+            metadata = JSON.parse((0, fs_1.readFileSync)(metadataFile, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`Erreur lors du chargement du metadata: ${error}`);
+        }
+        //
+        // Extraire les filenames uniques depuis metadata.documents
+        const uniqueFilenames = new Set();
+        for (const docRef of Object.values(metadata.documents)) {
+            if (docRef.filename) {
+                uniqueFilenames.add(docRef.filename);
+            }
+        }
+        //
+        // Charger les use cases pour chaque document
+        const documents = {};
+        let totalQueries = 0;
+        const filenames = [];
+        for (const filename of uniqueFilenames) {
+            const baseName = filename.replace(/\.md$/, '');
+            const queryFile = path_1.default.join(entry.configPath, baseName + '.query.json');
+            if ((0, fs_1.existsSync)(queryFile)) {
+                try {
+                    const queries = JSON.parse((0, fs_1.readFileSync)(queryFile, 'utf8'));
+                    documents[filename] = queries;
+                    totalQueries += queries.queries?.length || 0;
+                    filenames.push(filename);
+                }
+                catch (error) {
+                    //
+                    // Log l'erreur mais continue avec les autres documents
+                    console.warn(`⚠️ Erreur chargement use cases pour ${filename}:`, error.message);
+                }
+            }
+        }
+        return { documents, totalQueries };
+    }
     /**
      * Construit un RAG de manière atomique
      *
@@ -881,28 +970,34 @@ class RAGManager {
      */
     async delete(name, archiveFlag = true) {
         if (!this.exists(name)) {
-            throw new Error(`RAG '${name}' n'existe pas`);
+            console.warn(`⚠️ RAG '${name}' n'existe pas, skip delete`);
+            return new Error(`RAG '${name}' n'existe pas`);
         }
-        const entry = this.getEntry(name);
-        const registry = this.getRegistry();
-        // Archiver si demandé
-        if (archiveFlag) {
-            await this.archive(name);
-        }
-        else if ((0, fs_1.existsSync)(entry.configPath)) {
-            (0, fs_1.rmSync)(entry.configPath, { recursive: true, force: true });
-        }
-        // Supprimer du registre
-        delete registry.registries[name];
-        // Supprimer de la map des embeddings chargés
-        this.loadedEmbeddings.delete(name);
-        // Changer le défaut si nécessaire
-        if (registry.defaultName === name) {
-            const remainingRAGs = Object.keys(registry.registries);
-            registry.defaultName = remainingRAGs.length > 0 ? remainingRAGs[0] : 'RAGRegistry';
+        try {
+            const entry = this.getEntry(name);
+            const registry = this.getRegistry();
+            // Archiver si demandé
+            if (archiveFlag) {
+                await this.archive(name);
+            }
+            else if ((0, fs_1.existsSync)(entry.configPath)) {
+                (0, fs_1.rmSync)(entry.configPath, { recursive: true, force: true });
+            }
+            // Supprimer du registre
+            delete registry.registries[name];
+            // Supprimer de la map des embeddings chargés
+            this.loadedEmbeddings.delete(name);
+            // Changer le défaut si nécessaire
+            if (registry.defaultName === name) {
+                const remainingRAGs = Object.keys(registry.registries);
+                registry.defaultName = remainingRAGs.length > 0 ? remainingRAGs[0] : 'RAGRegistry';
+            }
+            this.saveRegistry(registry);
+            console.log(`✅ RAG supprimé: ${name}`);
+        }
+        catch (error) {
+            return error;
         }
-        this.saveRegistry(registry);
-        console.log(`✅ RAG supprimé: ${name}`);
     }
     /**
      * Renomme un document dans un RAG existant
@@ -1041,7 +1136,8 @@ class RAGManager {
         }
     }
     /**
-     * Renomme un RAG existant
+     * Renomme un RAG existant (nom dans le registre uniquement)
+     * Le dossier physique n'est PAS modifié, seul le nom dans la config change.
      *
      * @param from Nom actuel du RAG
      * @param to Nouveau nom du RAG
@@ -1051,6 +1147,7 @@ class RAGManager {
      * @example
      * ```typescript
      * await ragManager.rename('old-name', 'new-name', 'Description mise à jour');
+     * // Le dossier reste /path/to/old-name mais le RAG s'appelle 'new-name'
      * ```
      */
     async rename(from, to, description) {
@@ -1073,20 +1170,14 @@ class RAGManager {
             throw new Error(`Le nom '${to}' est réservé et ne peut pas être utilisé`);
         }
         const sourceEntry = this.getEntry(from);
-        const sourcePath = sourceEntry.configPath;
-        const destPath = path_1.default.join(this.config.baseDir, to);
         try {
-            // Renommer le dossier physique
-            if ((0, fs_1.existsSync)(sourcePath)) {
-                (0, fs_1.renameSync)(sourcePath, destPath);
-                if (this.config.verbose)
-                    console.log(`📁 Dossier renommé: ${sourcePath} → ${destPath}`);
-            }
-            // Mettre à jour le registre
+            //
+            // Ne PAS renommer le dossier physique - juste le nom dans le registre
+            // Le configPath reste inchangé (pointe vers le même dossier)
             const registry = this.getRegistry();
             registry.registries[to] = {
                 name: to,
-                configPath: destPath,
+                configPath: sourceEntry.configPath, // ✅ Garde le même chemin
                 status: sourceEntry.status,
                 description: description || sourceEntry.description
             };
@@ -1100,12 +1191,10 @@ class RAGManager {
             if (embeddingData) {
                 this.loadedEmbeddings.set(to, embeddingData);
                 this.loadedEmbeddings.delete(from);
-                // Notifier l'embedding de se mettre à jour avec le nouveau chemin
-                this.notifyUpdate(to);
             }
             // Mettre à jour le cache
             this.saveRegistry(registry);
-            console.log(`✅ RAG renommé: ${from} → ${to}`);
+            console.log(`✅ RAG renommé: ${from} → ${to} (dossier inchangé: ${sourceEntry.configPath})`);
         }
         catch (error) {
             console.error(`❌ Erreur lors du renommage de '${from}' en '${to}':`, error);

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

@@ -5,6 +5,8 @@ export declare const RAG_FILES: {
     readonly QUERIES: "rag-queries.json";
 };
 export interface RAGConfig {
+    /** Provider de l'embedding (default openai) */
+    provider?: string;
     /** Répertoire de base pour les documents et index */
     baseDir: string;
     /** Nom du fichier de vecteurs (sans extension) */

package/dist/src/rag/usecase.js

@@ -132,25 +132,22 @@ async function extractAndSaveDocumentUseCases(document, baseDir, version, tag, o
             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}`);
-                }
+                console.log(`⏭️ Skip queries: ${document.filename}`);
                 return existingQueries;
             }
-            else if (verbose) {
-                console.log(`🔄 Contenu modifié (fingerprint différent): ${document.filename}`);
-            }
+            console.log(`🔄 Source modifiée queries: ${document.filename}`);
         }
         catch (error) {
             // Si erreur de lecture, on continue avec l'extraction
-            if (verbose) {
-                console.warn(`⚠️ Erreur lecture use cases existants: ${error}`);
-            }
+            console.warn(`⚠️ Erreur lecture use cases: ${error}`);
         }
     }
     // Extraction nécessaire (fichier inexistant, fingerprint différent, ou force=true)
-    if (verbose && force) {
-        console.log(`🔄 Re-extraction forcée: ${document.filename}`);
+    if (force) {
+        console.log(`🔄 Force queries: ${document.filename}`);
+    }
+    else {
+        console.log(`✨ Nouveau queries: ${document.filename}`);
     }
     const { queries, cost } = await extractDocumentUseCases(document);
     const docQueries = {

package/dist/src/rules/git/git.health.js

@@ -551,6 +551,44 @@ class GitHealthManager {
         ];
         let fixed = 0;
         const fixedFiles = new Set();
+        // ✅ ÉTAPE CRITIQUE: Charger le cache pour toutes les branches avant la réparation
+        // Cela permet à getFileID() de trouver l'ID existant du fichier
+        if (!dryRun && filesToFix.length > 0) {
+            console.log(`   🔍 Chargement du cache pour toutes les branches...`);
+            const allBranches = await (0, git_1.gitGetAllBranches)(this.git);
+            const uniqueFiles = new Set();
+            for (const fileRef of filesToFix) {
+                const [, ...fileParts] = fileRef.split(':');
+                const file = fileParts.join(':');
+                uniqueFiles.add(file);
+            }
+            // Mettre en cache la liste des fichiers par branche pour éviter les appels répétés
+            const branchFilesCache = new Map();
+            for (const branch of allBranches) {
+                try {
+                    const filesInBranch = await (0, git_1.gitListFilesInBranch)(this.git, branch);
+                    branchFilesCache.set(branch, filesInBranch);
+                }
+                catch (e) {
+                    // Ignorer silencieusement les erreurs (branche peut être inaccessible)
+                    branchFilesCache.set(branch, []);
+                }
+            }
+            // Charger le cache pour chaque fichier dans les branches où il existe
+            for (const file of uniqueFiles) {
+                for (const branch of allBranches) {
+                    try {
+                        const filesInBranch = branchFilesCache.get(branch) || [];
+                        if (filesInBranch.includes(file)) {
+                            await (0, git_1.gitFileStrictMatter)(this.git, file, branch, this.config);
+                        }
+                    }
+                    catch (e) {
+                        // Ignorer silencieusement les erreurs (fichier peut ne pas exister)
+                    }
+                }
+            }
+        }
         for (const fileRef of filesToFix) {
             // Éviter de réparer deux fois le même fichier
             if (fixedFiles.has(fileRef)) {
@@ -570,11 +608,19 @@ class GitHealthManager {
                     // Parser le matter complet
                     const parsed = (0, utils_matter_1.matterParse)(fileData.content);
                     const { matter: fullMatter, content } = parsed;
-                    // Générer un nouvel ID si manquant
-                    if (!fullMatter.id || typeof fullMatter.id !== 'number' || fullMatter.id <= 999) {
-                        fullMatter.id = (0, git_1.gitGenerateNextID)(this.config);
-                        console.log(`   🔧 ${file}: Génération d'un nouvel ID: ${fullMatter.id}`);
+                    // ✅ CORRECTION: Utiliser gitEnsureMatterID() pour réutiliser l'ID existant du fichier
+                    // Si le fichier existe déjà dans une autre branche, son ID sera réutilisé
+                    // Sinon, un nouvel ID sera généré automatiquement
+                    const matterWithID = (0, git_1.gitEnsureMatterID)(fullMatter, this.config, branchName, file);
+                    if (matterWithID.id !== fullMatter.id) {
+                        if (fullMatter.id && fullMatter.id > 999) {
+                            console.log(`   🔧 ${file}: ID ${fullMatter.id} remplacé par ID existant ${matterWithID.id}`);
+                        }
+                        else {
+                            console.log(`   🔧 ${file}: Nouvel ID assigné: ${matterWithID.id}`);
+                        }
                     }
+                    fullMatter.id = matterWithID.id;
                     // Générer un titre si manquant (basé sur le nom du fichier ou le premier titre de section)
                     if (!fullMatter.title || fullMatter.title.trim() === '') {
                         // Essayer d'extraire le premier titre de section (# Title)
@@ -591,6 +637,15 @@ class GitHealthManager {
                     }
                     // Re-sérialiser et sauvegarder
                     const updatedContent = (0, utils_matter_1.matterSerialize)(content, fullMatter);
+                    // ✅ CRITIQUE: Vérifier si le contenu a réellement changé avant de créer un commit
+                    // Si le contenu n'a pas changé, ne pas créer de commit pour éviter de déplacer les notes Git
+                    if (updatedContent === fileData.content) {
+                        // Le contenu n'a pas changé, juste mettre à jour le cache sans créer de commit
+                        console.log(`   ℹ️  ${file}: Aucun changement nécessaire (ID ${fullMatter.id} déjà correct)`);
+                        fixed++;
+                        fixedFiles.add(fileRef);
+                        continue;
+                    }
                     // ✅ IMPORTANT: Désactiver withID car l'ID est déjà généré et enregistré
                     // Évite la double validation qui cause "ID déjà utilisé"
                     await (0, repo_1.gitCreateOrEditFile)(this.git, file, branchName, updatedContent, { name: 'GitHealthManager', email: 'health@system' }, { ...this.config, canForce: true, withID: false });

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

@@ -195,13 +195,20 @@ export declare function gitShowConfiguration(git: SimpleGit): Promise<any>;
  */
 export declare function gitCheckConfiguration(git?: SimpleGit): Promise<any>;
 /**
- * Crée un fichier dans la branche draft (opération bas niveau)
- * @param git Instance Git
+ * Crée ou modifie un fichier dans une branche Git et fait un commit automatique
+ *
+ * @param git Instance SimpleGit
  * @param filePath Chemin du fichier
  * @param PR Nom de la branche de Pull Request
  * @param content Contenu du fichier
- * @param user Utilisateur qui effectue l'opération
- * @param config Configuration Git (optionnel, utilise la config globale)
+ * @param user Utilisateur qui fait le commit
+ * @param config Configuration Git optionnelle
+ * @returns Historique du commit créé
+ *
+ * @fixme Ajouter un paramètre optionnel `commitMessage?: string` pour permettre de personnaliser
+ *        le message de commit au lieu d'utiliser toujours `commit: ${filePath}` par défaut.
+ *        Cela permettrait aux callers de spécifier des messages plus descriptifs.
+ *
  * @throws GitOperationError si la création échoue
  */
 export declare function gitCreateOrEditFile(git: SimpleGit, filePath: string, PR: string, content: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;