agentic-api 2.0.646 → 2.0.885

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

@@ -3,6 +3,9 @@ import { RulesGitConfig, PRMetadata, PRInfo, RuleUser, PRMergeResult, RulePullRe
 /**
  * Synchronise une branche PR avec son mergeBase pour corriger les références orphelines
  *
+ * @deprecated Utiliser le workflow applicatif (RulesWorkflow.syncPullRequest) et
+ * les opérations robustes orientées Git Notes. API conservée pour compatibilité.
+ *
  * FIXME: Cette fonction a un problème de gestion des métadonnées manquantes.
  *
  * PROBLÈME IDENTIFIÉ:
@@ -38,12 +41,14 @@ export declare function gitSyncPR(git: SimpleGit, branch: string, user: RuleUser
  * @param branch Nom de la branche PR
  * @param validationToken Token utilisé pour marquer la fermeture (optionnel, utilise la config par défaut)
  * @returns true si le PR est fermé (dernier commit contient le token de validation)
- * DEPRECATED: use gitIsPRClosedRobust instead
+ * @deprecated Utiliser gitIsPRClosedRobust.
  */
 export declare function gitIsPRClosed(git: SimpleGit, branch: string): Promise<boolean>;
 /**
  * Vérifie si une branche PR est fermée en utilisant Git Notes (avec fallback)
  * Version robuste qui remplace gitIsPRClosed
+ * @deprecated Préférer gitLoadPR() pour récupérer l'état PR complet.
+ *
  * @param git Instance Git
  * @param branch Nom de la branche PR
  * @param validationToken Token utilisé pour marquer la fermeture (optionnel, utilise la config par défaut)
@@ -73,23 +78,18 @@ export declare function gitGetAllPR(git: SimpleGit, options?: {
 }): Promise<PRInfo[]>;
 /**
  * Finds closed PRs by scanning the history of the draft branch for merge commits with PR metadata.
+ * @deprecated Utiliser gitGetAllPR(git, { closed: true }) pour unifier le listing PR.
+ *
  * @param git SimpleGit instance
  * @param gitConfig The git configuration
  * @returns A list of PRInfo objects for closed PRs.
  */
 export declare function gitGetClosedPRs(git: SimpleGit, gitConfig: RulesGitConfig): Promise<PRInfo[]>;
 export declare function gitLoadPR(git: SimpleGit, branch: string): Promise<PRInfo>;
-/**
- * Remplace explicitement un nom de fichier dans les métadonnées d'une PR.
- * Utilisé pour refléter immédiatement les renames sans dépendre de git diff.
- */
-export declare function gitPRReplaceFile(git: SimpleGit, branch: string, options?: {
-    remove?: string;
-    add?: string;
-}, config?: RulesGitConfig): Promise<void>;
 export declare function gitPRUpdateComments(git: SimpleGit, branch: string, details: RulePullRequestDetails, config?: RulesGitConfig): Promise<PRInfo>;
 /**
- * DEPRECATED: use gitClosePRRobust instead
+ * @deprecated Utiliser gitClosePRRobust.
+ *
  * Ferme un PR en ajoutant un commit avec le token de validation
  * @param git Instance Git
  * @param branch Branche PR à fermer
@@ -111,13 +111,6 @@ export declare function gitClosePR(git: SimpleGit, branch: string, author: RuleU
  * @returns Hash du commit de fermeture ou référence de la note
  */
 export declare function gitClosePRRobust(git: SimpleGit, branch: string, closedBy: RuleUser, message?: string, config?: RulesGitConfig): Promise<PRMergeResult>;
-/**
- * Trouve le prochain numéro de PR disponible (protégé contre la concurrence)
- * @param git Instance Git
- * @param validationPrefix Préfixe des branches de validation
- * @returns Prochain numéro de PR
- */
-export declare function gitGetNextPRNumber(git: SimpleGit, validationPrefix: string): Promise<number>;
 /**
  * Crée une nouvelle branche de validation (pour un PR vers rule-editor)
  * à partir d'une branche source (typiquement rule-editor).
@@ -136,7 +129,7 @@ export declare function gitNewValidationRequest(git: SimpleGit, files: string[],
     validationBranchPrefix?: string;
 }): Promise<PRInfo>;
 /**
- * DEPRECATED
+ * @deprecated Utiliser gitNewValidationRequest().
  */
 export declare function gitNewPR(git: SimpleGit, files: string[], description: string, author: RuleUser, options?: {
     content?: string[];

package/dist/src/rules/git/repo.pr.js

@@ -40,20 +40,23 @@ exports.gitGetPRMetadata = gitGetPRMetadata;
 exports.gitGetAllPR = gitGetAllPR;
 exports.gitGetClosedPRs = gitGetClosedPRs;
 exports.gitLoadPR = gitLoadPR;
-exports.gitPRReplaceFile = gitPRReplaceFile;
 exports.gitPRUpdateComments = gitPRUpdateComments;
 exports.gitClosePR = gitClosePR;
 exports.gitClosePRRobust = gitClosePRRobust;
-exports.gitGetNextPRNumber = gitGetNextPRNumber;
 exports.gitNewValidationRequest = gitNewValidationRequest;
 exports.gitNewPR = gitNewPR;
 const errors_1 = require("../errors");
 const path_1 = require("path");
 const fs = __importStar(require("fs/promises"));
 const repo_tools_1 = require("./repo.tools");
+const repo_1 = require("./repo");
+const utils_matter_1 = require("../utils.matter");
 /**
  * Synchronise une branche PR avec son mergeBase pour corriger les références orphelines
  *
+ * @deprecated Utiliser le workflow applicatif (RulesWorkflow.syncPullRequest) et
+ * les opérations robustes orientées Git Notes. API conservée pour compatibilité.
+ *
  * FIXME: Cette fonction a un problème de gestion des métadonnées manquantes.
  *
  * PROBLÈME IDENTIFIÉ:
@@ -152,9 +155,12 @@ async function gitSyncPR(git, branch, user) {
                 throw new errors_1.GitOperationError(`Failed to sync PR ${branch} with merge base ${mergeBase}: ${mergeError}`, 'pr_sync', { branch, mergeBase, mergeError, fallbackError });
             }
         }
-        // Préserver les fichiers originaux de la PR (ne pas recalculer après merge)
-        // Note: Après un merge réussi, gitGetDiffFiles retournera [] car il n'y a plus de différences
-        // Les fichiers de la PR sont une information historique qui doit être préservée
+        // Préserver les fichiers originaux de la PR (ne pas recalculer après merge).
+        // NOTE IMPORTANTE:
+        // - gitSyncPR fait un merge technique pour maintenir la branche de validation à jour.
+        // - Ce merge NE DOIT PAS redéfinir le scope métier de la PR.
+        // - metadata.files reste la source de vérité (pilotée par add/edit/rename/delete).
+        // - Un diff Git post-merge peut être ambigu (base mouvante, merge commit, refs).
         const updatedMetadata = {
             ...pr.metadata,
             files: pr.metadata.files, // Préserver les fichiers originaux
@@ -191,7 +197,7 @@ async function gitSyncPR(git, branch, user) {
  * @param branch Nom de la branche PR
  * @param validationToken Token utilisé pour marquer la fermeture (optionnel, utilise la config par défaut)
  * @returns true si le PR est fermé (dernier commit contient le token de validation)
- * DEPRECATED: use gitIsPRClosedRobust instead
+ * @deprecated Utiliser gitIsPRClosedRobust.
  */
 async function gitIsPRClosed(git, branch) {
     return gitIsPRClosedRobust(git, branch);
@@ -199,6 +205,8 @@ async function gitIsPRClosed(git, branch) {
 /**
  * Vérifie si une branche PR est fermée en utilisant Git Notes (avec fallback)
  * Version robuste qui remplace gitIsPRClosed
+ * @deprecated Préférer gitLoadPR() pour récupérer l'état PR complet.
+ *
  * @param git Instance Git
  * @param branch Nom de la branche PR
  * @param validationToken Token utilisé pour marquer la fermeture (optionnel, utilise la config par défaut)
@@ -232,13 +240,33 @@ async function gitIsPRClosedRobust(git, branch, config) {
 async function gitGetPRMetadata(git, branch, config) {
     const gitConf = (0, repo_tools_1.gitLoad)(config);
     try {
-        // D'abord essayer de chercher sur le commit HEAD de la branche
-        let metadata = await (0, repo_tools_1.gitReadNote)(git, branch, gitConf.gitNotes.namespace, 20);
-        // DEPRECATED: we now we always use the last 20 commits to find the metadata
-        // if (!metadata) {
-        //   metadata = await gitReadNote(git, branch, gitConf.gitNotes.namespace, 20);
-        // }
-        return metadata;
+        const expectedPRId = Number.parseInt(branch.replace(gitConf.validationPrefix, ''), 10);
+        // D'abord essayer de chercher rapidement sur HEAD / historique récent.
+        const metadata = await (0, repo_tools_1.gitReadNote)(git, branch, gitConf.gitNotes.namespace, 20);
+        if (metadata) {
+            // Si ce n'est pas une branche de validation standard, on retourne tel quel.
+            if (Number.isNaN(expectedPRId)) {
+                return metadata;
+            }
+            // Branche de validation: rejeter une note dont l'ID ne correspond pas.
+            if (metadata.id === expectedPRId) {
+                return metadata;
+            }
+            if (gitConf.verbose) {
+                console.warn(`⚠️ gitGetPRMetadata(${branch}): note récente id=${metadata.id}, attendu=${expectedPRId}. Recherche approfondie...`);
+            }
+        }
+        // Fallback robuste: scanner plus large et ne retenir que la note du bon PR.
+        if (!Number.isNaN(expectedPRId)) {
+            const log = await git.log(['-n', '200', branch]);
+            for (const commit of log.all) {
+                const note = await (0, repo_tools_1.gitReadNote)(git, commit.hash, gitConf.gitNotes.namespace, 1);
+                if (note && note.id === expectedPRId) {
+                    return note;
+                }
+            }
+        }
+        return null;
     }
     catch (error) {
         // This typically happens if the branch doesn't exist, which is a valid case.
@@ -287,6 +315,8 @@ async function gitGetAllPR(git, options = {}) {
 }
 /**
  * Finds closed PRs by scanning the history of the draft branch for merge commits with PR metadata.
+ * @deprecated Utiliser gitGetAllPR(git, { closed: true }) pour unifier le listing PR.
+ *
  * @param git SimpleGit instance
  * @param gitConfig The git configuration
  * @returns A list of PRInfo objects for closed PRs.
@@ -317,12 +347,13 @@ async function gitGetClosedPRs(git, gitConfig) {
 }
 async function gitLoadPR(git, branch) {
     try {
+        const gitConf = (0, repo_tools_1.gitLoad)();
         // Load metadata from 
         const metadata = await gitGetPRMetadata(git, branch);
         if (!metadata) {
             throw new errors_1.GitOperationError(`PR not found for branch ${branch}`, 'pr_load', { branch });
         }
-        const files = metadata.files || (await (0, repo_tools_1.gitGetDiffFiles)(git, branch, metadata?.mergeBase, '.md'));
+        const files = metadata.files || (await (0, repo_tools_1.gitGetDiffFiles)(git, branch, metadata?.mergeBase || gitConf.draftBranch, '.md'));
         // Récupérer les infos du dernier commit de la branche
         const log = await git.log({ from: branch, to: branch, maxCount: 1 });
         const lastCommit = log.latest;
@@ -342,49 +373,6 @@ async function gitLoadPR(git, branch) {
         throw new errors_1.GitOperationError(`Failed to retrieve PR: ${error}`, 'pr_load');
     }
 }
-/**
- * Remplace explicitement un nom de fichier dans les métadonnées d'une PR.
- * Utilisé pour refléter immédiatement les renames sans dépendre de git diff.
- */
-async function gitPRReplaceFile(git, branch, options = {}, config) {
-    const { remove, add } = options;
-    if (!remove && !add) {
-        return;
-    }
-    const gitConf = (0, repo_tools_1.gitLoad)(config);
-    const metadata = await gitGetPRMetadata(git, branch, config);
-    if (!metadata) {
-        return;
-    }
-    const currentFiles = Array.isArray(metadata.files) ? metadata.files : [];
-    const seen = new Set();
-    const nextFiles = [];
-    for (const file of currentFiles) {
-        if (!file) {
-            continue;
-        }
-        if (remove && file === remove) {
-            continue;
-        }
-        if (seen.has(file)) {
-            continue;
-        }
-        seen.add(file);
-        nextFiles.push(file);
-    }
-    if (add && !seen.has(add)) {
-        nextFiles.push(add);
-        seen.add(add);
-    }
-    const changed = currentFiles.length !== nextFiles.length ||
-        currentFiles.some((file, idx) => file !== nextFiles[idx]);
-    if (!changed) {
-        return;
-    }
-    metadata.files = nextFiles;
-    const headCommitHash = (await git.revparse([branch])).trim();
-    await (0, repo_tools_1.gitWriteNote)(git, headCommitHash, metadata, gitConf.gitNotes.namespace);
-}
 async function gitPRUpdateComments(git, branch, details, config) {
     const gitConf = (0, repo_tools_1.gitLoad)(config);
     const metadata = await gitGetPRMetadata(git, branch, config);
@@ -405,7 +393,8 @@ async function gitPRUpdateComments(git, branch, details, config) {
     return gitLoadPR(git, branch);
 }
 /**
- * DEPRECATED: use gitClosePRRobust instead
+ * @deprecated Utiliser gitClosePRRobust.
+ *
  * Ferme un PR en ajoutant un commit avec le token de validation
  * @param git Instance Git
  * @param branch Branche PR à fermer
@@ -483,6 +472,7 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
         // Note: "ours" dans ce contexte signifie "garder la version de la branche qu'on merge" (la PR)
         // car nous sommes sur rule-editor et on merge la PR
         let mergeResult;
+        let mergeCommitHash;
         try {
             mergeResult = await git
                 .env({
@@ -498,6 +488,7 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
                 '-m', `Merge branch '${branch}'`,
                 branch
             ]);
+            mergeCommitHash = (await git.revparse(['HEAD'])).trim();
         }
         catch (mergeError) {
             if (gitConf.verbose) {
@@ -537,15 +528,22 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
                     }
                 }
                 // Amend le commit de merge avec les bons contenus
-                await git.commit('--amend', ['--no-edit'], {
+                const amendResult = await git.commit('--amend', ['--no-edit'], {
                     '--author': `${closedBy.name} <${closedBy.email}>`
                 });
+                mergeCommitHash = amendResult.commit || (await git.revparse(['HEAD'])).trim();
                 mergeResult = { summary: { changes: prFiles.length } };
             }
             catch (fallbackError) {
                 throw new errors_1.PRClosureError(`Failed to merge PR ${branch} with all strategies: ${mergeError}\nFallback error: ${fallbackError}`, branch, 'merge_failed');
             }
         }
+        // 6. Attacher aussi la note au commit de merge sur la branche cible.
+        // Cela garantit la traçabilité même si la branche PR est supprimée.
+        if (!mergeCommitHash) {
+            mergeCommitHash = (await git.revparse(['HEAD'])).trim();
+        }
+        await (0, repo_tools_1.gitWriteNote)(git, mergeCommitHash, finalMetadata, gitConf.gitNotes.namespace);
         const result = {
             metadata: finalMetadata,
             failed: false,
@@ -583,37 +581,6 @@ async function gitClosePRRobust(git, branch, closedBy, message, config) {
         (0, repo_tools_1.unlock)('checkout');
     }
 }
-/**
- * Trouve le prochain numéro de PR disponible (protégé contre la concurrence)
- * @param git Instance Git
- * @param validationPrefix Préfixe des branches de validation
- * @returns Prochain numéro de PR
- */
-async function gitGetNextPRNumber(git, validationPrefix) {
-    await (0, repo_tools_1.lock)('pr-number');
-    try {
-        const allBranches = await (0, repo_tools_1.gitGetAllBranches)(git);
-        const prBranches = allBranches.filter((branch) => branch.startsWith(validationPrefix));
-        if (prBranches.length === 0) {
-            return 1;
-        }
-        const numbers = prBranches
-            .map((branch) => {
-            const numberPart = branch.substring(validationPrefix.length);
-            // Gérer les cas où le nom de branche contient plus que le numéro après le préfixe
-            const actualNumber = parseInt(numberPart.split('-')[0], 10);
-            return actualNumber;
-        })
-            .filter((num) => !isNaN(num));
-        return numbers.length > 0 ? Math.max(...numbers) + 1 : 1;
-    }
-    catch (error) {
-        throw new errors_1.GitOperationError(`Failed to get next PR number: ${error}`, 'pr_number', { validationPrefix, originalError: error });
-    }
-    finally {
-        (0, repo_tools_1.unlock)('pr-number');
-    }
-}
 /**
  * Crée une nouvelle branche de validation (pour un PR vers rule-editor)
  * à partir d'une branche source (typiquement rule-editor).
@@ -639,6 +606,20 @@ async function gitNewValidationRequest(git, files, description, author, options
             throw new errors_1.PRCreationError('Author is required', undefined, files);
         }
         try {
+            // Vérification atomique côté API: empêcher plusieurs PR ouvertes sur les mêmes fichiers.
+            const openPRs = await gitGetAllPR(git, {
+                closed: false,
+                validationPrefix: validationBranchPrefix
+            });
+            const conflictingPRs = openPRs.filter((pr) => pr.files.some((prFile) => files.includes(prFile)));
+            if (conflictingPRs.length > 0) {
+                const conflictingFiles = files.filter((file) => conflictingPRs.some((pr) => pr.files.includes(file)));
+                if (gitConfig.verbose) {
+                    console.log('🌶️ DEBUG: gitNewValidationRequest -- conflicting PRs:', conflictingPRs.map((pr) => pr.branch));
+                }
+                const firstConflict = conflictingPRs[0].branch;
+                throw new errors_1.PRCreationError(`Le fichier est déjà dans la validation en cours #${firstConflict.replace(validationBranchPrefix, '')}`, firstConflict, conflictingFiles);
+            }
             // ✅ CLEANUP: Nettoyer tout état de merge corrompu avant de créer la branche
             // Cela évite l'erreur "you need to resolve your current index first"
             try {
@@ -654,7 +635,7 @@ async function gitNewValidationRequest(git, files, description, author, options
                     console.warn('Cleanup before branch creation failed (non-critical):', cleanupError);
                 }
             }
-            const nextID = await gitGetNextPRNumber(git, validationBranchPrefix);
+            const nextID = await (0, repo_1.gitAllocateNextPRNumber)(git, validationBranchPrefix, gitConfig);
             const newBranchName = `${validationBranchPrefix}${nextID}`;
             await git.checkoutBranch(newBranchName, sourceBranch);
             const initialCommitMessage = `#${nextID} ${description}`;
@@ -663,9 +644,16 @@ async function gitNewValidationRequest(git, files, description, author, options
                 if (!content[idx]) {
                     continue;
                 }
-                // console.log('writeFile',files[idx],content[idx]);
+                let fileContent = content[idx];
+                // Assurer l'ID documentaire lors de la création d'une PR avec contenus fournis.
+                if (gitConfig.withID !== false) {
+                    const parsed = (0, utils_matter_1.matterParse)(fileContent);
+                    parsed.matter = (0, repo_1.gitEnsureMatterID)(parsed.matter, gitConfig, newBranchName, files[idx]);
+                    fileContent = (0, utils_matter_1.matterSerialize)(parsed.content, parsed.matter);
+                }
+                // console.log('writeFile',files[idx],fileContent);
                 // This writeFile is in-memory and stages the file.
-                await _writeFileAndCommit(git, files[idx], content[idx], author, gitConfig, initialCommitMessage);
+                await _writeFileAndCommit(git, files[idx], fileContent, author, gitConfig, initialCommitMessage);
             }
             const metadata = {
                 id: nextID,
@@ -710,7 +698,7 @@ async function gitNewValidationRequest(git, files, description, author, options
     }
 }
 /**
- * DEPRECATED
+ * @deprecated Utiliser gitNewValidationRequest().
  */
 async function gitNewPR(git, files, description, author, options = {}) {
     return gitNewValidationRequest(git, files, description, author, options);

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

@@ -123,6 +123,11 @@ export declare function gitGetAllBranches(git: SimpleGit, options?: {
  * @param baseBranch Branche de base (par défaut: main)
  * @param filter Filtre optionnel (ex: '.md')
  * @returns Liste des fichiers modifiés
+ *
+ * NOTE IMPORTANTE:
+ * - Ce résultat est une vue TECHNIQUE du diff Git (commits/références), pas une vérité métier PR.
+ * - Ne pas utiliser seul pour reconstruire metadata.files d'une PR.
+ * - La source de vérité métier reste metadata.files maintenu par add/edit/rename/delete.
  */
 export declare function gitGetDiffFiles(git: SimpleGit, targetBranch: string, baseBranch?: string, filter?: string): Promise<string[]>;
 /**

package/dist/src/rules/git/repo.tools.js

@@ -129,7 +129,7 @@ function gitLoad(defaultConfig) {
     }
     // console.log(`🌶️ gitLoad: First Loading git config`,defaultConfig);
     const verbose = defaultConfig?.verbose || process.env.GIT_VERBOSE === 'true';
-    const remoteUrl = defaultConfig?.remoteUrl || process.env.GIT_REMOTE_URL;
+    const remoteUrl = defaultConfig?.remoteUrl ?? process.env.GIT_REMOTE_URL;
     const repoPath = defaultConfig?.repoPath || process.env.GIT_REPO_PATH;
     const uploadPath = defaultConfig?.uploadPath || process.env.GIT_UPLOAD_PATH;
     const draftBranch = defaultConfig?.draftBranch || process.env.DEFAULT_BRANCH_DRAFT;
@@ -625,6 +625,11 @@ async function gitGetAllBranches(git, options = {}) {
  * @param baseBranch Branche de base (par défaut: main)
  * @param filter Filtre optionnel (ex: '.md')
  * @returns Liste des fichiers modifiés
+ *
+ * NOTE IMPORTANTE:
+ * - Ce résultat est une vue TECHNIQUE du diff Git (commits/références), pas une vérité métier PR.
+ * - Ne pas utiliser seul pour reconstruire metadata.files d'une PR.
+ * - La source de vérité métier reste metadata.files maintenu par add/edit/rename/delete.
  */
 async function gitGetDiffFiles(git, targetBranch, baseBranch, filter) {
     const gitConfig = gitLoad();

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

@@ -122,8 +122,6 @@ export interface FrontMatter {
     id?: number;
     /** Titre descriptif de la règle */
     title: string;
-    /** Ancien nom de fichier (pour renommage) */
-    oldfile?: string;
     /** Auteur original de la règle (format git: "Name <email>") */
     author?: string;
     /** Email du validateur assigné à cette règle */

package/dist/src/rules/utils.matter.js

@@ -121,13 +121,9 @@ function matterParse(markdown) {
  * ✅ NOUVELLE FONCTION pour reconstruire le contenu complet
 */
 function matterSerializeFromRule(rule) {
-    // Créer un objet propre pour le front-matter (exclure oldfile)
-    const matter = { ...rule.matter };
-    delete matter.oldfile;
-    return matterSerialize(rule.content, matter);
+    return matterSerialize(rule.content, rule.matter);
 }
 function matterSerialize(content, matter) {
-    // Créer un objet propre pour le front-matter (exclure oldfile)
     const cleanMatter = { ...matter };
     const result = Object.keys(cleanMatter).reduce((acc, key) => {
         const value = cleanMatter[key];

package/dist/src/scrapper.d.ts

@@ -1,48 +1,161 @@
 import { FrontMatter } from "./rules/types";
-export declare function extractCaptcha(base64Image: string, openai: any): Promise<{
-    number: any;
-    cost: number;
-}>;
+/** Raw image data extracted from a PDF page. */
+export interface PageImage {
+    /** Raw pixel buffer: RGBA, RGB, grayscale bytes, or JPEG-encoded bytes. */
+    data: Buffer;
+    /** Pixel format / encoding of the buffer content. */
+    type: 'jpeg' | 'rgb' | 'rgba' | 'grayscale';
+    width: number;
+    height: number;
+}
+/** Dimensions of a single GFM table detected on a page. */
+export interface PageTable {
+    /** Number of data rows (header and separator lines excluded). */
+    rows: number;
+    /** Number of columns inferred from the header line. */
+    cols: number;
+}
+/** Structured representation of a single PDF page. */
+export interface Page {
+    pageNumber: number;
+    /** Cleaned body text, with reconstructed GFM tables. Running headers/footers removed. */
+    text: string;
+    /**
+     * Running page header detected across ≥ 3 consecutive pages (e.g. chapter title,
+     * magazine section name). Undefined for the poppler engine or single-page PDFs.
+     */
+    header?: string;
+    /**
+     * Running page footer detected across ≥ 3 consecutive pages (e.g. folio number,
+     * document title). Undefined for the poppler engine or single-page PDFs.
+     */
+    footer?: string;
+    /**
+     * Dimensions of each GFM table found in `text`.
+     * Used by `callLLMForParsingPDF` to select an appropriate model:
+     * pages with wide (cols > 3) or long (rows > 10) tables are upgraded
+     * from `LOW-fast` to `MEDIUM-fast` automatically.
+     */
+    tables: PageTable[];
+    /** Images extracted from the page. Always empty for the poppler engine. */
+    images: PageImage[];
+}
+/** Extraction backend selection. */
+export type PdftotextEngine = 'poppler' | 'mupdf';
 /**
- * Calls GPT to parse a PDF file and convert it to markdown format.
+ * Converts extracted PDF content to clean Markdown via LLM.
  *
- * @param {string} inputfile - The name of the PDF file being processed
- * @param {any} pdfData - The extracted content from the PDF file
- * @param {any[]} links - Optional array of links extracted from the PDF to be integrated into the markdown
- * @param {string} model - The model to use for parsing (default: "MEDIUM-fast")
- * @returns {Promise<{markdown: string, cost: number}>} - The parsed markdown content and the cost of the API call
+ * Two paths depending on the `pdfData` type:
+ *
+ * **`Page[]` (mupdf path)** — `MapLLM.reduce`, one page per chunk.
+ * Each page is processed by `mupdfPagePrompt` (heading normalisation, broken-cell
+ * fusion, repeated-header removal). No frontmatter is added here; the caller
+ * (`pdf2markdown`) prepends the single YAML block.
+ *
+ * NOTE: `finalReduce` is intentionally disabled — it is reserved for a future
+ * "N-page light summary" feature where a second LLM pass synthesises the whole
+ * document into a shorter version.
+ *
+ * A raw `string` (e.g. from `html2markdown`) is automatically wrapped into a
+ * single `Page` so both callers share the exact same code path.
+ *
+ * @param inputfile - Original file path (used for logging only).
+ * @param pdfData   - Either a `Page[]` array (mupdf) or a raw string.
+ * @param links     - External links appended as `## Liens` footer (string path).
+ * @param model     - LLM model alias (default: `'MEDIUM-fast'`).
  */
-export declare function callLLMForParsingPDF(inputfile: string, pdfData: any, links?: any[], model?: string): Promise<{
+export declare function callLLMForParsingPDF(inputfile: string, pdfData: Page[] | string, links?: {
+    text: string;
+    href: string;
+}[], model?: string): Promise<{
     markdown: string;
     cost: number;
 }>;
 /**
- * Parses an HTML file and converts it to markdown using GPT.
+ * Parses an HTML file and converts it to markdown using LLM.
  *
  * @param {string} output - The directory path where the output markdown file will be saved.
  * @param {string} file - The path to the HTML file to be parsed.
  * @param {string} service - The service name used as part of the output filename output.
  * @param {string} model - The model to use for parsing (default: "MEDIUM-fast")
- * @returns {Promise<{markdown: string, cost: number}>} - The generated markdown content and the cost of the GPT API call.
+ * @returns {Promise<{markdown: string, cost: number}>} - The generated markdown content and the cost of the API call.
  */
 export declare function html2markdown(output: string, file: string, service: string, model?: string): Promise<{
     markdown: string;
     cost: number;
 }>;
 /**
- * Parse un PDF en effectuant :
- * 1. Le nettoyage du PDF avec Ghostscript.
- * 2. Sa conversion en XML via pdftohtml.
- * 3. (Optionnellement) Le passage du contenu converti au modèle LLM pour analyser la structure.
- *
- * @param {string} outputDir - Dossier de sortie pour le fichier markdown.
- * @param {string} pdf - Chemin vers le fichier PDF à analyser.
- * @param {FrontMatter|null} matter - Métadonnées du document (title, service, author, role). Si null, utilise le nom du PDF pour le titre.
- * @param {string} model - Le modèle à utiliser (défaut: "MEDIUM-fast").
- * @returns {Promise<{markdown: string, cost: number, outputPath: string}>} - Le markdown structuré, le coût et le chemin du fichier de sortie.
+ * Extracts plain text from a PDF using the system `pdftotext` binary (poppler-utils).
+ *
+ * - Pages are delimited by form-feed (\f) characters in the binary's output.
+ * - Excessive blank lines are normalised (3+ → 2).
+ * - Images are NOT extracted (always []).
+ *
+ * NOTE: Better alternative is `pdftotext_pdfjs` which uses Mozilla's PDF engine
+ *   to extract text + images + links in a single Node.js-native pass, with better
+ *   table reconstruction for complex layouts. See `pdftotext_pdfjs` for details.
+ *
+ * @param {string} pdfPath   - Absolute path to the PDF file.
+ * @param {string} outputDir - Directory used for temporary files.
+ * @returns {Promise<Page[]>} One `Page` per PDF page, text-only.
+ */
+export declare function pdftotext_poppler(pdfPath: string, outputDir: string): Promise<Page[]>;
+/**
+ * Extracts text, reconstructed tables, links, and optionally page-raster images
+ * from a PDF using the **mupdf** npm package (WASM build of the MuPDF C library).
+ *
+ * Key advantages over the poppler engine:
+ * - `table-hunt` detects tables geometrically even in **untagged** PDFs.
+ * - `segment` splits the page into logical reading-order blocks.
+ * - Significantly faster than pdfjs for large documents.
+ * - No shell binary dependency (pure WASM, runs anywhere Node.js does).
+ *
+ * Images (opt-in via `withImages: true`): each page is rasterised at 1.5× scale
+ * (≈ 113 DPI). The `imageFormat` option controls encoding:
+ *
+ * | format      | size/page (base64) | notes                          |
+ * |-------------|-------------------|--------------------------------|
+ * | `'rgb'`     | ≈ 4.4 MB          | raw RGB, lossless, large       |
+ * | `'gray'`    | ≈ 1.5 MB          | raw grayscale, 3× smaller      |
+ * | `'jpeg'`    | ≈ 100–200 KB      | JPEG quality 75, 31× smaller   |
+ *
+ * Disabled by default because image data quickly exhausts stdout buffers for
+ * large documents. Use `jpeg` for production with vision models.
+ *
+ * NOTE: `mupdf` is ESM-only. Extraction is delegated to a standalone
+ * `mupdf-extract.mjs` worker spawned via `execAsync`, which avoids any
+ * ESM/CJS interoperability issues in the main process and under ts-jest.
+ *
+ * @param {string}  pdfPath    - Absolute path to the PDF file.
+ * @param {object}  [options]
+ * @param {boolean} [options.withImages=false]     - Rasterise each page.
+ * @param {'rgb'|'gray'|'jpeg'} [options.imageFormat='rgb'] - Pixel encoding.
+ * @returns {Promise<Page[]>} One `Page` per PDF page with text, GFM tables, and optional images.
  */
-export declare function pdf2markdown(outputDir: string, pdf: string, matter: FrontMatter | null, model?: string): Promise<{
+export declare function pdftotext_mupdf(pdfPath: string, options?: {
+    withImages?: boolean;
+    imageFormat?: 'rgb' | 'gray' | 'jpeg';
+}): Promise<Page[]>;
+/**
+ * Converts a PDF to a structured Markdown file.
+ *
+ * Pipeline:
+ * 1. `pdftotext_mupdf` (or poppler) → `Page[]`
+ * 2. `callLLMForParsingPDF` — MapLLM.reduce, one page per chunk
+ * 3. Prepend a **single** YAML frontmatter block and write to `outputDir`.
+ *
+ * Model choice: `LOW-fast` is sufficient — mupdf output is already clean GFM;
+ * the LLM only normalises headings and removes repeated headers/footers.
+ * Use `MEDIUM-fast` for complex layouts that need heavier restructuring.
+ *
+ * @param outputDir - Directory for the output `.md` file.
+ * @param pdf       - Absolute path to the PDF file.
+ * @param matter    - Document metadata; defaults derived from filename.
+ * @param model     - LLM model alias (default: `'LOW-fast'`).
+ * @param engine    - Extraction backend (default: `'mupdf'`).
+ * @returns `{ markdown, outputPath }` — frontmatter-prefixed markdown and output path.
+ */
+export declare function pdf2markdown(outputDir: string, pdf: string, matter: FrontMatter | null, model?: string, engine?: PdftotextEngine): Promise<{
     markdown: string;
-    cost: number;
     outputPath: string;
 }>;