redmine-context 1.0.0

package/dist/extract/ooxml.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Extrator de texto de documentos OOXML — docx/pptx/xlsx (#184, ADR-002/ADR-005).
+ *
+ * 100% LOCAL e SEM BINÁRIO externo (não entra no `doctor`; funciona nos 3 SOs sem
+ * instalar nada): um arquivo Office moderno é um contêiner ZIP com o conteúdo em
+ * XML. Este extrator abre o zip ({@link parseZip}, zero-dep), DESAMBIGUA o formato
+ * pelo conteúdo (não pela extensão nem pelo Content-Type) e puxa o texto das tags
+ * de run de cada dialeto:
+ *
+ *   docx → `word/document.xml`            tags `<w:t>` (parágrafo `</w:p>`, tab `<w:tab/>`)
+ *   pptx → `ppt/slides/slide<N>.xml`      tags `<a:t>` (parágrafo `</a:p>`), na ordem dos slides
+ *   xlsx → `xl/sharedStrings.xml`         tags `<t>`   (uma string por `</si>`)
+ *
+ * É registrado para o MIME `application/zip` (o `magic.ts` reporta OOXML como zip;
+ * a "diferenciação fina" fica aqui, como o próprio `magic.ts` documenta). Um zip
+ * que NÃO é OOXML devolve `unsupported`; zip corrompido/entrada ausente/vazio
+ * devolve `failed` — degradação graciosa, NUNCA crash (ADR-002).
+ *
+ * ROBUSTEZ CONTRA INPUT ADVERSARIAL (anexos são input não confiável de qualquer
+ * usuário do Redmine):
+ *  - a extração de texto é um SCANNER DE UM PASSO (O(n) linear, sem backtracking) —
+ *    NÃO usa `regex.matchAll` sobre o documento inteiro, que degeneraria para O(n²)
+ *    com tags de texto abertas e nunca fechadas (DoS de CPU trivial);
+ *  - orçamento AGREGADO de descompressão no pptx (não só por-entrada) + teto de
+ *    slides, contra zip-bombs de muitas entradas;
+ *  - `unescapeXml` valida o range Unicode antes de `fromCodePoint` (entidade
+ *    numérica fora de range é mantida literal, nunca lança).
+ *
+ * O texto extraído é marcado como não-confiável no bundle pelo mesmo mecanismo do
+ * tesseract/pdf (`<untrusted-content>`), então aqui só devolvemos `{ status:'done', text }`.
+ */
+import type { ExtractorParams } from '../cache/contract.js';
+import type { ExtractorConfig } from '../cache/keys.js';
+import type { ExtractionResult } from '../contract.js';
+import { type ExtractOptions, type Extractor } from './dispatcher.js';
+/** MIME REAL (magic bytes `PK\x03\x04`) que roteia este extrator. */
+export declare const OOXML_MIMES: readonly string[];
+/**
+ * Desescapa entidades XML (nomeadas + numéricas decimais/hex). Sequências
+ * desconhecidas OU com code point fora do range Unicode são mantidas LITERAIS —
+ * `String.fromCodePoint` nunca é chamado com valor inválido (não lança).
+ *
+ * @param s - Texto com entidades XML.
+ * @returns Texto com as entidades resolvidas.
+ * @internal Exportado para teste unitário (range de entidade numérica).
+ */
+export declare function unescapeXml(s: string): string;
+/** Dialeto de um formato: tag de texto + tags que viram quebra de linha/tabulação. */
+interface Dialect {
+    /** Nome da tag de run de texto (ex.: `w:t`, `a:t`, `t`). */
+    readonly textTag: string;
+    /** Tags de FECHAMENTO que marcam fim de parágrafo/registro → `\n` (ex.: `w:p`, `si`). */
+    readonly newlineClose: ReadonlySet<string>;
+    /** Tags de ABERTURA (geralmente self-close) que viram `\n` (ex.: `w:br`, `w:cr`). */
+    readonly newlineOpen: ReadonlySet<string>;
+    /** Tags de ABERTURA que viram tabulação (ex.: `w:tab`). */
+    readonly tabOpen: ReadonlySet<string>;
+}
+/** @internal Exportado para teste unitário (guarda de regressão de ReDoS). */
+export declare const DOCX_DIALECT: Dialect;
+/**
+ * Extrai texto de um XML OOXML com um SCANNER DE UM PASSO (O(n), sem backtracking).
+ * Percorre o buffer uma vez: em cada tag de TEXTO de run do dialeto captura o
+ * conteúdo até o próximo `<` (runs OOXML não têm filhos), e converte as tags
+ * estruturais (parágrafo/break → `\n`, tab → `\t`). Todo o resto — inclusive o
+ * espaço em branco insignificante entre elementos — é ignorado.
+ *
+ * @param xml - Conteúdo XML da parte.
+ * @param d - Dialeto do formato.
+ * @returns Texto concatenado com quebras/tabs nos limites estruturais.
+ */
+export declare function extractTextFromXml(xml: string, d: Dialect): string;
+/**
+ * Extrator OOXML (docx/pptx/xlsx). Implementa {@link Extractor} e expõe
+ * {@link params}/{@link extractorConfig} estáveis para a chave de cache (ADR-004).
+ */
+export declare class OoxmlExtractor implements Extractor {
+    readonly id = "ooxml";
+    readonly version = "ooxml-1";
+    readonly supportedMimes: readonly string[];
+    readonly model = "ooxml";
+    /** Sem parâmetros escalares que alterem a saída (extração determinística). */
+    readonly params: ExtractorParams;
+    /**
+     * Configuração pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig(): ExtractorConfig;
+    /**
+     * Extrai o texto de um arquivo OOXML. Nunca lança: zip inválido/entrada
+     * ausente/vazio → `failed`; zip que não é OOXML → `unsupported`; signal já
+     * abortado → `cancelled`.
+     *
+     * @param filePath - Caminho absoluto do arquivo baixado.
+     * @param options - MIME real + logger + signal — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `unsupported`/`failed`/`cancelled` caso contrário.
+     */
+    extract(filePath: string, options: ExtractOptions): Promise<ExtractionResult>;
+    /**
+     * Concatena o texto de todos os slides do pptx, na ORDEM numérica dos slides,
+     * com orçamento AGREGADO de bytes descomprimidos e teto de nº de slides.
+     *
+     * @param zip - Arquivo OOXML aberto.
+     * @param logger - Logger opcional para avisos (ex.: teto de slides atingido).
+     * @returns Texto concatenado dos slides.
+     * @throws {Error} Se o total descomprimido exceder {@link MAX_TOTAL_BYTES}.
+     */
+    private extractPptx;
+    /**
+     * Monta um resultado terminal simples (`unsupported`/`cancelled`) com metadados.
+     * @param status - Status terminal.
+     * @param mime - MIME real detectado.
+     * @param extra - Metadados adicionais.
+     */
+    private terminal;
+    /**
+     * Monta um `ExtractionResult` `failed` com diagnóstico (sem chaves `undefined`).
+     * @param mime - MIME real detectado.
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (erro/hint/format).
+     */
+    private failed;
+}
+/**
+ * Cria um {@link OoxmlExtractor} pronto para registro. Sem trabalho assíncrono
+ * (não há binário a localizar) — a fábrica existe por simetria com os demais.
+ *
+ * @returns Uma instância do extrator OOXML.
+ */
+export declare function createOoxmlExtractor(): OoxmlExtractor;
+export {};

package/dist/extract/ooxml.js

@@ -0,0 +1,336 @@
+/**
+ * Extrator de texto de documentos OOXML — docx/pptx/xlsx (#184, ADR-002/ADR-005).
+ *
+ * 100% LOCAL e SEM BINÁRIO externo (não entra no `doctor`; funciona nos 3 SOs sem
+ * instalar nada): um arquivo Office moderno é um contêiner ZIP com o conteúdo em
+ * XML. Este extrator abre o zip ({@link parseZip}, zero-dep), DESAMBIGUA o formato
+ * pelo conteúdo (não pela extensão nem pelo Content-Type) e puxa o texto das tags
+ * de run de cada dialeto:
+ *
+ *   docx → `word/document.xml`            tags `<w:t>` (parágrafo `</w:p>`, tab `<w:tab/>`)
+ *   pptx → `ppt/slides/slide<N>.xml`      tags `<a:t>` (parágrafo `</a:p>`), na ordem dos slides
+ *   xlsx → `xl/sharedStrings.xml`         tags `<t>`   (uma string por `</si>`)
+ *
+ * É registrado para o MIME `application/zip` (o `magic.ts` reporta OOXML como zip;
+ * a "diferenciação fina" fica aqui, como o próprio `magic.ts` documenta). Um zip
+ * que NÃO é OOXML devolve `unsupported`; zip corrompido/entrada ausente/vazio
+ * devolve `failed` — degradação graciosa, NUNCA crash (ADR-002).
+ *
+ * ROBUSTEZ CONTRA INPUT ADVERSARIAL (anexos são input não confiável de qualquer
+ * usuário do Redmine):
+ *  - a extração de texto é um SCANNER DE UM PASSO (O(n) linear, sem backtracking) —
+ *    NÃO usa `regex.matchAll` sobre o documento inteiro, que degeneraria para O(n²)
+ *    com tags de texto abertas e nunca fechadas (DoS de CPU trivial);
+ *  - orçamento AGREGADO de descompressão no pptx (não só por-entrada) + teto de
+ *    slides, contra zip-bombs de muitas entradas;
+ *  - `unescapeXml` valida o range Unicode antes de `fromCodePoint` (entidade
+ *    numérica fora de range é mantida literal, nunca lança).
+ *
+ * O texto extraído é marcado como não-confiável no bundle pelo mesmo mecanismo do
+ * tesseract/pdf (`<untrusted-content>`), então aqui só devolvemos `{ status:'done', text }`.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { parseZip } from './zip.js';
+/** Identificador estável do extrator (entra em metadados/cache-key). */
+const EXTRACTOR_ID = 'ooxml';
+/** Modelo lógico para a chave de cache (ADR-004). */
+const EXTRACTOR_MODEL = 'ooxml';
+/** Versão da integração (participa da chave de cache; bump ao mudar a extração). */
+const EXTRACTOR_VERSION = 'ooxml-1';
+/** Teto do arquivo (verificado por `stat` ANTES do `readFile`; download já limita). */
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+/**
+ * Teto AGREGADO de texto descomprimido lido numa única extração de pptx (soma de
+ * todos os slides). Complementa o teto por-entrada de {@link parseZip}: impede que
+ * um `.pptx` pequeno com muitas entradas altamente compressíveis exploda em RAM/CPU.
+ */
+const MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+/** Teto de slides processados num pptx (defesa contra "milhares de slides vazios"). */
+const MAX_SLIDES = 5000;
+/** MIME REAL (magic bytes `PK\x03\x04`) que roteia este extrator. */
+export const OOXML_MIMES = ['application/zip'];
+/** Entradas-âncora que identificam cada formato OOXML dentro do zip. */
+const DOCX_MAIN = 'word/document.xml';
+const PPTX_MAIN = 'ppt/presentation.xml';
+const XLSX_MAIN = 'xl/workbook.xml';
+const XLSX_STRINGS = 'xl/sharedStrings.xml';
+/** Regex de um nome de slide do pptx, capturando o número para ordenação. */
+const SLIDE_RE = /^ppt\/slides\/slide(\d+)\.xml$/;
+/** Entidades XML nomeadas suportadas no desescape. */
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+/** Maior code point Unicode válido (limite de `String.fromCodePoint`). */
+const MAX_CODE_POINT = 0x10ffff;
+/**
+ * Desescapa entidades XML (nomeadas + numéricas decimais/hex). Sequências
+ * desconhecidas OU com code point fora do range Unicode são mantidas LITERAIS —
+ * `String.fromCodePoint` nunca é chamado com valor inválido (não lança).
+ *
+ * @param s - Texto com entidades XML.
+ * @returns Texto com as entidades resolvidas.
+ * @internal Exportado para teste unitário (range de entidade numérica).
+ */
+export function unescapeXml(s) {
+    return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (match, code) => {
+        if (code.startsWith('#')) {
+            const hex = code.startsWith('#x') || code.startsWith('#X');
+            const cp = Number.parseInt(hex ? code.slice(2) : code.slice(1), hex ? 16 : 10);
+            return Number.isInteger(cp) && cp >= 0 && cp <= MAX_CODE_POINT
+                ? String.fromCodePoint(cp)
+                : match;
+        }
+        return NAMED_ENTITIES[code] ?? match;
+    });
+}
+/** Nome + tipo de uma tag a partir do seu interior (entre `<` e `>`). Bounded/linear. */
+const TAG_RE = /^\s*(\/?)\s*([^\s/>]+)/;
+function parseTag(inner) {
+    const selfClose = inner.endsWith('/');
+    const m = TAG_RE.exec(inner);
+    return { name: m?.[2] ?? '', closing: m?.[1] === '/', selfClose };
+}
+/** @internal Exportado para teste unitário (guarda de regressão de ReDoS). */
+export const DOCX_DIALECT = {
+    textTag: 'w:t',
+    newlineClose: new Set(['w:p']),
+    newlineOpen: new Set(['w:br', 'w:cr']),
+    tabOpen: new Set(['w:tab']),
+};
+const PPTX_DIALECT = {
+    textTag: 'a:t',
+    newlineClose: new Set(['a:p']),
+    newlineOpen: new Set(['a:br']),
+    tabOpen: new Set(),
+};
+const XLSX_DIALECT = {
+    textTag: 't',
+    newlineClose: new Set(['si']),
+    newlineOpen: new Set(),
+    tabOpen: new Set(),
+};
+/**
+ * Extrai texto de um XML OOXML com um SCANNER DE UM PASSO (O(n), sem backtracking).
+ * Percorre o buffer uma vez: em cada tag de TEXTO de run do dialeto captura o
+ * conteúdo até o próximo `<` (runs OOXML não têm filhos), e converte as tags
+ * estruturais (parágrafo/break → `\n`, tab → `\t`). Todo o resto — inclusive o
+ * espaço em branco insignificante entre elementos — é ignorado.
+ *
+ * @param xml - Conteúdo XML da parte.
+ * @param d - Dialeto do formato.
+ * @returns Texto concatenado com quebras/tabs nos limites estruturais.
+ */
+export function extractTextFromXml(xml, d) {
+    let out = '';
+    const n = xml.length;
+    let i = 0;
+    while (i < n) {
+        const lt = xml.indexOf('<', i);
+        if (lt < 0)
+            break;
+        const gt = xml.indexOf('>', lt + 1);
+        if (gt < 0)
+            break; // tag não terminada (cauda malformada) — para com segurança
+        const tag = parseTag(xml.slice(lt + 1, gt));
+        i = gt + 1;
+        if (!tag.closing && !tag.selfClose && tag.name === d.textTag) {
+            // Conteúdo do run: do fim desta tag até o próximo `<` (o `</w:t>`). `<` só
+            // aparece escapado como `&lt;` dentro do texto, então isto é seguro.
+            const nextLt = xml.indexOf('<', i);
+            const end = nextLt < 0 ? n : nextLt;
+            out += unescapeXml(xml.slice(i, end));
+            i = end;
+        }
+        else if (tag.closing && d.newlineClose.has(tag.name)) {
+            out += '\n';
+        }
+        else if (!tag.closing && d.newlineOpen.has(tag.name)) {
+            out += '\n';
+        }
+        else if (!tag.closing && d.tabOpen.has(tag.name)) {
+            out += '\t';
+        }
+    }
+    return out;
+}
+/** Normaliza o texto extraído: tira espaço antes de `\n` e colapsa 3+ quebras. */
+function normalize(text) {
+    return text.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * Extrator OOXML (docx/pptx/xlsx). Implementa {@link Extractor} e expõe
+ * {@link params}/{@link extractorConfig} estáveis para a chave de cache (ADR-004).
+ */
+export class OoxmlExtractor {
+    id = EXTRACTOR_ID;
+    version = EXTRACTOR_VERSION;
+    supportedMimes = OOXML_MIMES;
+    model = EXTRACTOR_MODEL;
+    /** Sem parâmetros escalares que alterem a saída (extração determinística). */
+    params = {};
+    /**
+     * Configuração pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig() {
+        return { version: this.version, model: this.model, params: this.params };
+    }
+    /**
+     * Extrai o texto de um arquivo OOXML. Nunca lança: zip inválido/entrada
+     * ausente/vazio → `failed`; zip que não é OOXML → `unsupported`; signal já
+     * abortado → `cancelled`.
+     *
+     * @param filePath - Caminho absoluto do arquivo baixado.
+     * @param options - MIME real + logger + signal — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `unsupported`/`failed`/`cancelled` caso contrário.
+     */
+    async extract(filePath, options) {
+        if (options.signal?.aborted) {
+            return this.terminal('cancelled', options.mime, { reason: 'cancelado' });
+        }
+        // Checa o tamanho ANTES de carregar o arquivo na memória (defesa real caso o
+        // cap de download upstream falhe/seja contornado).
+        let size;
+        try {
+            size = (await stat(filePath)).size;
+        }
+        catch (error) {
+            return this.failed(options.mime, 'erro-leitura', { error: message(error) });
+        }
+        if (size > MAX_FILE_BYTES) {
+            return this.failed(options.mime, 'arquivo-muito-grande', { bytes: size });
+        }
+        let buffer;
+        try {
+            buffer = await readFile(filePath);
+        }
+        catch (error) {
+            return this.failed(options.mime, 'erro-leitura', { error: message(error) });
+        }
+        let zip;
+        try {
+            zip = parseZip(buffer);
+        }
+        catch (error) {
+            return this.failed(options.mime, 'zip-invalido', { error: message(error) });
+        }
+        let format;
+        let text;
+        try {
+            if (zip.has(DOCX_MAIN)) {
+                format = 'docx';
+                text = extractTextFromXml(readText(zip, DOCX_MAIN), DOCX_DIALECT);
+            }
+            else if (zip.has(PPTX_MAIN)) {
+                format = 'pptx';
+                text = this.extractPptx(zip, options.logger);
+            }
+            else if (zip.has(XLSX_MAIN)) {
+                format = 'xlsx';
+                text = zip.has(XLSX_STRINGS)
+                    ? extractTextFromXml(readText(zip, XLSX_STRINGS), XLSX_DIALECT)
+                    : '';
+            }
+            else {
+                return this.terminal('unsupported', options.mime, { reason: 'zip-nao-ooxml' });
+            }
+        }
+        catch (error) {
+            return this.failed(options.mime, 'erro-extracao', { error: message(error) });
+        }
+        const normalized = normalize(text);
+        if (normalized.length === 0) {
+            return this.failed(options.mime, 'ooxml-sem-texto', {
+                format,
+                hint: 'documento OOXML sem texto extraível (ex.: planilha só com números ou slides só com imagens)',
+            });
+        }
+        return {
+            status: 'done',
+            text: normalized,
+            mime: options.mime,
+            metadata: { extractorId: this.id, version: this.version, format },
+        };
+    }
+    /**
+     * Concatena o texto de todos os slides do pptx, na ORDEM numérica dos slides,
+     * com orçamento AGREGADO de bytes descomprimidos e teto de nº de slides.
+     *
+     * @param zip - Arquivo OOXML aberto.
+     * @param logger - Logger opcional para avisos (ex.: teto de slides atingido).
+     * @returns Texto concatenado dos slides.
+     * @throws {Error} Se o total descomprimido exceder {@link MAX_TOTAL_BYTES}.
+     */
+    extractPptx(zip, logger) {
+        const slides = zip
+            .names()
+            .map((name) => {
+            const m = SLIDE_RE.exec(name);
+            return m ? { name, n: Number.parseInt(m[1], 10) } : undefined;
+        })
+            .filter((x) => x !== undefined)
+            .sort((a, b) => a.n - b.n);
+        if (slides.length > MAX_SLIDES) {
+            logger?.warn(`ooxml: pptx com ${slides.length} slides; processando apenas os primeiros ${MAX_SLIDES}`);
+        }
+        const capped = slides.slice(0, MAX_SLIDES);
+        let total = 0;
+        let out = '';
+        for (const slide of capped) {
+            const xml = readText(zip, slide.name);
+            total += Buffer.byteLength(xml, 'utf8');
+            if (total > MAX_TOTAL_BYTES) {
+                throw new Error(`orçamento de descompressão do pptx excedido (${MAX_TOTAL_BYTES} bytes)`);
+            }
+            out += extractTextFromXml(xml, PPTX_DIALECT);
+        }
+        return out;
+    }
+    /**
+     * Monta um resultado terminal simples (`unsupported`/`cancelled`) com metadados.
+     * @param status - Status terminal.
+     * @param mime - MIME real detectado.
+     * @param extra - Metadados adicionais.
+     */
+    terminal(status, mime, extra) {
+        return { status, mime, metadata: { extractorId: this.id, ...extra } };
+    }
+    /**
+     * Monta um `ExtractionResult` `failed` com diagnóstico (sem chaves `undefined`).
+     * @param mime - MIME real detectado.
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (erro/hint/format).
+     */
+    failed(mime, reason, extra) {
+        return {
+            status: 'failed',
+            mime,
+            metadata: { extractorId: this.id, version: this.version, reason, ...extra },
+        };
+    }
+}
+/** Lê uma entrada de texto (UTF-8) do zip; lança se ausente (entrada esperada). */
+function readText(zip, name) {
+    const buf = zip.read(name);
+    if (buf === undefined) {
+        throw new Error(`entrada esperada ausente no OOXML: "${name}"`);
+    }
+    return buf.toString('utf8');
+}
+/** Extrai a mensagem de um erro desconhecido. */
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Cria um {@link OoxmlExtractor} pronto para registro. Sem trabalho assíncrono
+ * (não há binário a localizar) — a fábrica existe por simetria com os demais.
+ *
+ * @returns Uma instância do extrator OOXML.
+ */
+export function createOoxmlExtractor() {
+    return new OoxmlExtractor();
+}

package/dist/extract/pdf.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Extrator de texto de PDF via `pdftotext` (poppler) — M4-extra, #145, ADR-002.
+ *
+ * Roda o binário `pdftotext` sobre um PDF já baixado no cache e devolve a CAMADA
+ * DE TEXTO do documento num {@link ExtractionResult}. ESPELHA ponto-a-ponto o
+ * padrão do {@link TesseractExtractor} (ADR-002), todas as decisões exercitadas
+ * por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: usa `execFile` (nunca `exec`/shell) com lista de
+ *   argumentos explícita (`pdftotext -enc UTF-8 <file> -`, `-` = stdout) — o
+ *   `filePath` NUNCA é interpolado numa string de shell, eliminando injeção por
+ *   nome de arquivo malicioso.
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO e EXPLÍCITO (só `PATH`) —
+ *   segredos do processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o pdftotext.
+ * - TIMEOUT + KILL: um watchdog envia `SIGTERM` no timeout e, após a graça,
+ *   `SIGKILL` — um pdftotext travado (PDF patológico) não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente do PATH/locais convencionais NÃO lança;
+ *   devolve `{ status: 'failed', metadata.reason }` com dica de instalação (o
+ *   `doctor` da #53 orienta o usuário).
+ *
+ * SEMÂNTICA DO PDF SEM CAMADA DE TEXTO (escaneado): quando o `pdftotext` sai com
+ * sucesso mas a saída é VAZIA ou só whitespace (form-feed por página), NÃO
+ * devolvemos `{ status: 'done', text: '' }` — isso MENTIRIA ao consumidor,
+ * afirmando "extração concluída, sem texto" quando na verdade não há camada de
+ * texto extraível (o conteúdo é imagem, exigindo OCR). Devolvemos
+ * `{ status: 'failed', reason: 'pdf-sem-camada-de-texto' }` com um `hint` de que
+ * o OCR por página fica para uma issue futura — falha honesta e diagnosticável.
+ *
+ * A chave de cache do anexo (ADR-004) depende de `version` + `model` + `params`
+ * ({@link buildAttachmentKey}); por isso o extrator expõe {@link PdfExtractor.version}
+ * (derivada do binário real quando detectável, senão a versão da integração) e
+ * {@link PdfExtractor.params} (inclui `enc`/`layout`, estáveis para a chave).
+ */
+import type { ExtractorParams } from '../cache/contract.js';
+import type { ExtractorConfig } from '../cache/keys.js';
+import type { ExtractionResult } from '../contract.js';
+import { type ExtractOptions, type Extractor } from './dispatcher.js';
+/** MIME REAL (magic bytes `%PDF`, ver `./magic.ts`) que o pdftotext aceita. */
+export declare const PDF_MIMES: readonly string[];
+/** Resultado de {@link findPdftotext}: caminho absoluto do binário localizado. */
+export interface PdftotextLocation {
+    /** Caminho absoluto do executável `pdftotext` encontrado. */
+    readonly path: string;
+}
+/**
+ * Localiza o binário `pdftotext` no `PATH` e em locais convencionais por
+ * plataforma (`/opt/homebrew/bin`, `/usr/local/bin`, `C:\\Program Files\\poppler\\bin`).
+ * Função pura e reutilizável pelo `doctor` (#53). Não executa o binário.
+ *
+ * @returns A localização encontrada, ou `undefined` se não instalado.
+ * @example
+ * const found = findPdftotext();
+ * if (found === undefined) logger.warn('pdftotext (poppler) não instalado');
+ */
+export declare function findPdftotext(): PdftotextLocation | undefined;
+/** Opções de construção do {@link PdfExtractor}. */
+export interface PdfExtractorOptions {
+    /**
+     * Caminho absoluto do binário já resolvido. `undefined` = não instalado; nesse
+     * caso {@link PdfExtractor.extract} degrada para `failed` (não lança).
+     */
+    readonly binaryPath?: string | undefined;
+    /** Versão exposta na chave de cache (ver {@link INTEGRATION_VERSION} como fallback). */
+    readonly version: string;
+    /**
+     * Preservar layout físico (`-layout`) em vez da ordem de leitura. Default `false`.
+     * Participa da identidade da extração (chave de cache).
+     */
+    readonly layout?: boolean;
+    /** Timeout antes do `SIGTERM` (ms); default {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Graça `SIGTERM`→`SIGKILL` (ms); default {@link DEFAULT_KILL_GRACE_MS}. */
+    readonly killGraceMs?: number;
+}
+/**
+ * Extrator de texto de PDF baseado no binário `pdftotext` do poppler (ADR-002).
+ * Implementa {@link Extractor} e, além do contrato, expõe {@link params} e
+ * {@link extractorConfig} estáveis para {@link buildAttachmentKey}.
+ */
+export declare class PdfExtractor implements Extractor {
+    readonly id = "pdftotext";
+    readonly version: string;
+    readonly supportedMimes: readonly string[];
+    /** Modelo lógico para a chave de cache (ADR-004). */
+    readonly model = "pdftotext";
+    /** Parâmetros escalares estáveis (`enc`, `layout`) — participam da chave de cache. */
+    readonly params: ExtractorParams;
+    private readonly binaryPath;
+    private readonly layout;
+    private readonly timeoutMs;
+    private readonly killGraceMs;
+    /**
+     * @param options - Ver {@link PdfExtractorOptions}.
+     */
+    constructor(options: PdfExtractorOptions);
+    /**
+     * Configuração do extrator pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig(): ExtractorConfig;
+    /**
+     * Extrai a camada de texto de `filePath`. Nunca lança: falhas (binário ausente,
+     * timeout, erro de execução, PDF sem texto) viram `{ status: 'failed',
+     * metadata.reason }` — degradação graciosa (ADR-002).
+     *
+     * IMPORTANTE (semântica): um PDF ESCANEADO (sem camada de texto) produz saída
+     * vazia/whitespace no `pdftotext`; nesse caso devolvemos `failed` com
+     * `reason: 'pdf-sem-camada-de-texto'` (e um `hint` de OCR), e NÃO
+     * `{ status: 'done', text: '' }` — que afirmaria falsamente sucesso sem texto.
+     *
+     * @param filePath - Caminho absoluto do PDF baixado.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    extract(filePath: string, options: ExtractOptions): Promise<ExtractionResult>;
+    /**
+     * Monta um `ExtractionResult` `failed` com metadados de diagnóstico, sem
+     * injetar chaves `undefined` (respeita `exactOptionalPropertyTypes`).
+     *
+     * @param mime - MIME real detectado (do dispatcher).
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (hint/erro).
+     * @returns Resultado `failed` tipado.
+     */
+    private failed;
+}
+/**
+ * Lê a versão do binário via `pdftotext -v`. O poppler imprime
+ * `pdftotext version X.Y.Z` no STDERR (não stdout) e sai com código 0. Não lança:
+ * retorna `undefined` se o binário falhar ou a saída for inesperada.
+ *
+ * @param bin - Caminho absoluto do binário.
+ * @returns A versão semântica detectada (ex.: `24.02.0`), ou `undefined`.
+ */
+export declare function detectPdftotextVersion(bin: string): Promise<string | undefined>;
+/**
+ * Cria um {@link PdfExtractor} resolvendo binário e versão. Localiza o
+ * `pdftotext` ({@link findPdftotext}); se presente, lê a versão real do binário e
+ * expõe `version = pdftotext-<X.Y.Z>`; se ausente (não instalado) ou versão
+ * ilegível, usa {@link INTEGRATION_VERSION} e o extrator degrada em `extract`.
+ *
+ * @param config - Sobrescreve `layout`/timeouts — ver {@link PdfExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const extractor = await createPdfExtractor({ layout: true });
+ */
+export declare function createPdfExtractor(config?: Omit<PdfExtractorOptions, 'version' | 'binaryPath'>): Promise<PdfExtractor>;