@arela/uploader 1.1.4 → 1.2.0

package/.claude/worktrees/agent-multi-profile/src/scoring/db-matcher-adapter.js

@@ -0,0 +1,98 @@
+/**
+ * Adapt DB matchers (from arela-api `GET /document-matcher/resolved`) into the
+ * shape the scoring engine consumes — the HYBRID model:
+ *
+ *   - SELECTION comes from the DB matcher's clues / qualify (per-RFC + globals).
+ *   - EXTRACTION uses the rich JS extractors keyed by `documentType` when one
+ *     exists (resolveType, multi-pattern field extractors, pedimento composition);
+ *     otherwise it falls back to building simple regex extractors from the DB
+ *     matcher's `fieldExtractors`.
+ *
+ * This keeps per-client matching configurable from the UI while preserving the
+ * robust field extraction that already ships in the uploader.
+ */
+// IMPORTANT: load document-type-shared FIRST so it becomes the root of the
+// shared<->definitions import cycle and fully evaluates before the individual
+// definitions are referenced (otherwise: "Cannot access X before initialization").
+import { FieldResult } from '../document-type-shared.js';
+import { dodaPdfDefinition } from '../document-types/doda-pdf.js';
+import { dodaXmlDefinition } from '../document-types/doda-xml.js';
+import { facturaInterAgenciaDefinition } from '../document-types/factura-inter-agencia.js';
+import { facturasComerciales } from '../document-types/facturas-comerciales.js';
+import { pedimentoCompletoXmlDefinition } from '../document-types/pedimento-completo-xml.js';
+import { pedimentoCompletoDefinition } from '../document-types/pedimento-completo.js';
+import { pedimentoSimplificadoDefinition } from '../document-types/pedimento-simplificado.js';
+import { supportDocumentDefinition } from '../document-types/support-document.js';
+
+// documentType -> rich extraction half of the JS definition.
+function extractionOf(def) {
+  return {
+    extractors: def.extractors,
+    resolveType: def.resolveType,
+    extractNumPedimento: def.extractNumPedimento,
+    extractPedimentoYear: def.extractPedimentoYear,
+  };
+}
+
+const EXTRACTION_REGISTRY = {
+  pedimento_simplificado: extractionOf(pedimentoSimplificadoDefinition),
+  pedimento_completo: extractionOf(pedimentoCompletoDefinition),
+  pedimento_completo_xml: extractionOf(pedimentoCompletoXmlDefinition),
+  doda_pdf: extractionOf(dodaPdfDefinition),
+  doda_xml: extractionOf(dodaXmlDefinition),
+  factura_inter_agencia: extractionOf(facturaInterAgenciaDefinition),
+  factura_comercial: extractionOf(facturasComerciales),
+  support_document: extractionOf(supportDocumentDefinition),
+};
+
+// Build a scoring-engine extractor from a DB fieldExtractor (regex + capture).
+function regexExtractor(fe) {
+  return {
+    field: fe.field,
+    extract: (source) => {
+      try {
+        const m = source.match(new RegExp(fe.extractor, fe.flags || ''));
+        return new FieldResult(fe.field, !!m, m ? (m[1] ?? m[0]) : null);
+      } catch {
+        return new FieldResult(fe.field, false, null);
+      }
+    },
+  };
+}
+
+/**
+ * Convert resolved DB matchers into scoring-engine matchers.
+ * @param {Array} dbMatchers - matchers from the API (with clues + fieldExtractors)
+ * @returns {Array} scoring matchers
+ */
+export function adaptDbMatchers(dbMatchers) {
+  return (dbMatchers || []).map((m) => {
+    const rich = EXTRACTION_REGISTRY[m.documentType];
+    const extraction = rich
+      ? rich
+      : { extractors: (m.fieldExtractors || []).map(regexExtractor) };
+
+    return {
+      documentType: m.documentType,
+      extensions: Array.isArray(m.extensions)
+        ? m.extensions
+        : String(m.extensions || '')
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+      minScore: m.minScore ?? undefined,
+      priority: m.priority ?? 0,
+      qualify: m.qualify ?? undefined,
+      clues: (m.clues || []).map((c) => ({
+        kind: c.kind,
+        pattern: c.pattern,
+        flags: c.flags || undefined,
+        weight: c.weight ?? 1,
+        group: c.group || undefined,
+        required: !!c.required,
+        negative: !!c.negative,
+      })),
+      ...extraction,
+    };
+  });
+}

package/.claude/worktrees/agent-multi-profile/src/scoring/matchers-seed.js

@@ -0,0 +1,386 @@
+/**
+ * Seed matchers for the scoring engine (PROTOTYPE).
+ *
+ * Each entry re-expresses the boolean `match()` of an existing
+ * `src/document-types/*.js` definition as a set of weighted **clues**, while
+ * REUSING that definition's `extractors` / `resolveType` /
+ * `extractNumPedimento` / `extractPedimentoYear` verbatim. Only the SELECTION
+ * logic is new — field extraction is unchanged, so a comparison against
+ * `extractDocumentFields` isolates the first-match-wins → best-match change.
+ *
+ * Clue → flag mapping used throughout:
+ *   - strong positive signal   → high `weight`
+ *   - hard exclusion (return false in the original) → `negative: true`
+ *   - mandatory signature       → `required: true`
+ *   - `minScore` is tuned so the weighted sum reproduces the original boolean
+ *     on the existing test fixtures.
+ *
+ * NOTE: a few original conditions are compound (e.g. simplificado's
+ * "COVE: present AND PAGO absent", or inter-agencia's "≥2 distinct RFCs from a
+ * set"). Where a single clue cannot express the exact boolean, the closest
+ * faithful approximation is used and flagged inline — the comparison harness
+ * (`scripts/scoring-compare.js`) surfaces any divergence on a real corpus.
+ */
+import { dodaPdfDefinition } from '../document-types/doda-pdf.js';
+import { dodaXmlDefinition } from '../document-types/doda-xml.js';
+import {
+  INTER_AGENCIA_RFCS,
+  facturaInterAgenciaDefinition,
+} from '../document-types/factura-inter-agencia.js';
+import { facturasComerciales } from '../document-types/facturas-comerciales.js';
+import { pedimentoCompletoXmlDefinition } from '../document-types/pedimento-completo-xml.js';
+import { pedimentoCompletoDefinition } from '../document-types/pedimento-completo.js';
+import { pedimentoSimplificadoDefinition } from '../document-types/pedimento-simplificado.js';
+import { supportDocumentDefinition } from '../document-types/support-document.js';
+
+// Pull the extraction half of a definition (reused unchanged).
+function reuse(def) {
+  return {
+    extractors: def.extractors,
+    resolveType: def.resolveType,
+    extractNumPedimento: def.extractNumPedimento,
+    extractPedimentoYear: def.extractPedimentoYear,
+  };
+}
+
+const PEDIMENTO_NUM = /\d{2}\s?\d{2}\s?\d{4}\s?\d{7}/;
+
+// --- pedimento_simplificado --------------------------------------------------
+// Original: AVISO/COVE excluded; title "FORMA SIMPLIFICADA DE[L] PEDIMENTO"
+// short-circuits to true; otherwise the header trio (all three) qualifies.
+// Copy markers are NOT made negative here — they let `pedimento_completo`
+// outscore on completo layouts, which reproduces the title short-circuit.
+const simplificado = {
+  documentType: 'pedimento_simplificado',
+  extensions: ['pdf'],
+  minScore: 3, // title(5) OR full header trio(1+1+1)
+  priority: 1,
+  ...reuse(pedimentoSimplificadoDefinition),
+  clues: [
+    { kind: 'CONTENT_REGEX', pattern: /AVISO\s+CONSOLIDADO/i, negative: true },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /COMPROBANTE\s+DE\s+VALOR\s+ELECTR[ÓO]NICO/i,
+      negative: true,
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /FORMA\s+SIMPLIFICADA\s+DEL?\s+PEDIMENTO/i,
+      weight: 5,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /NUM\.?\s*PEDIMENTO:/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /CVE\.?\s*PEDIMENTO:/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /T\.?\s*OPER:?/i, weight: 1 },
+  ],
+};
+
+// --- pedimento_completo ------------------------------------------------------
+// Original: exclude FORMA SIMPLIFICADA & AVISO; (header trio AND ≥1 copy marker)
+// OR clue-count heuristic (>25% of ~18 clues ≈ ≥5).
+const completo = {
+  documentType: 'pedimento_completo',
+  extensions: ['pdf'],
+  minScore: 5, // header trio(3) + 1 copy marker(2), or ≥5 fallback clues
+  priority: 1,
+  ...reuse(pedimentoCompletoDefinition),
+  clues: [
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /FORMA\s+SIMPLIFICADA\s+DEL?\s+PEDIMENTO/i,
+      negative: true,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /AVISO\s+CONSOLIDADO/i, negative: true },
+    // header trio
+    { kind: 'CONTENT_REGEX', pattern: /NUM\.?\s*PEDIMENTO:/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /CVE\.?\s*PEDIMENTO:/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /T\.?\s*OPER:?/i, weight: 1 },
+    // copy markers (long-form pedimento signatures)
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /ORIGINAL:\s*ADMINISTRACION GENERAL DE ADUANAS/i,
+      weight: 2,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /SEGUNDA\s+COPIA/i, weight: 2 },
+    { kind: 'CONTENT_REGEX', pattern: /TERCERA\s+COPIA/i, weight: 2 },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /COPIA\s+(SIMPLIFICAD[AO])?\s*TRANSPORTISTA/i,
+      weight: 2,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /DEFINITIVO/i, weight: 2 },
+    { kind: 'CONTENT_REGEX', pattern: /ANEXO\s+DEL\s+PEDIMENTO/i, weight: 2 },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /\*+FIN\s+DE\s+PEDIMENTO\s*\*+/i,
+      weight: 2,
+    },
+    // exotic-layout fallback clues (weight 1 each)
+    { kind: 'CONTENT_REGEX', pattern: /CERTIFICACIONES/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /CUADRO\s+DE\s+LIQUIDACION/i, weight: 1 },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /\*\*\*\s+PAGO\s+ELECTRONICO\s+\*\*\*/i,
+      weight: 1,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /MEDIOS\s+DE\s+TRANSPORTE/i, weight: 1 },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /DATOS\s+DEL\s+IMPORTADOR\/EXPORTADOR/i,
+      weight: 1,
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /DATOS\s+DEL\s+PROVEEDOR\s+O\s+COMPRADOR/i,
+      weight: 1,
+    },
+    { kind: 'CONTENT_REGEX', pattern: /LINEA\s+DE\s+CAPTURA:/i, weight: 1 },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /DECLARO\s+BAJO\s+PROTESTA\s+DE\s+DECIR\s+VERDAD/i,
+      weight: 1,
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /PEDIMENTO\s+ELABORADO\s+DE\s+CONFORMIDAD/i,
+      weight: 1,
+    },
+  ],
+};
+
+// --- pedimento_completo_xml --------------------------------------------------
+// Original: single condition — the VUCEM response root tag.
+const completoXml = {
+  documentType: 'pedimento_completo_xml',
+  extensions: ['xml'],
+  minScore: 1,
+  priority: 2, // authoritative signal — must dominate doda_xml/support on XML
+  ...reuse(pedimentoCompletoXmlDefinition),
+  clues: [
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /consultarPedimentoCompletoRespuesta/i,
+      weight: 10,
+      required: true,
+    },
+  ],
+};
+
+// --- doda_pdf ----------------------------------------------------------------
+// Original: primary marker → true; OR (≥2 secondary + pedimento#);
+// OR (doda-context + pedimento# + ≥1 secondary).
+const dodaPdf = {
+  documentType: 'doda_pdf',
+  extensions: ['pdf'],
+  priority: 1,
+  qualify: [
+    { primary: 1 },
+    { secondary: 2, pedimento: 1 },
+    { context: 1, pedimento: 1, secondary: 1 },
+  ],
+  ...reuse(dodaPdfDefinition),
+  clues: [
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /DOCUMENTO DE OPERACI[OÓ]N PARA DESPACHO ADUANERO/i,
+      weight: 5,
+      group: 'primary',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /DODA/i, weight: 1, group: 'secondary' },
+    { kind: 'CONTENT_REGEX', pattern: /VUCEM/i, weight: 1, group: 'secondary' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: PEDIMENTO_NUM,
+      weight: 1,
+      group: 'pedimento',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /despacho aduanero|operaci[oó]n aduanera|validaci[oó]n/i,
+      weight: 1,
+      group: 'context',
+    },
+  ],
+};
+
+// --- doda_xml ----------------------------------------------------------------
+// Original: ≥1 doda marker → true; OR (≥3 pedimento markers AND <?xml).
+const dodaXml = {
+  documentType: 'doda_xml',
+  extensions: ['xml'],
+  priority: 1,
+  qualify: [{ doda: 1 }, { pedimento: 3, xml: 1 }],
+  ...reuse(dodaXmlDefinition),
+  clues: [
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /documentoOperacion/i,
+      weight: 3,
+      group: 'doda',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /despachoAduanero/i,
+      weight: 3,
+      group: 'doda',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /<doda\b/i, weight: 3, group: 'doda' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /xmlns[^"]*doda/i,
+      weight: 3,
+      group: 'doda',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /VUCEM/i, weight: 3, group: 'doda' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /numPedimento/i,
+      weight: 1,
+      group: 'pedimento',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /patenteAduanal/i,
+      weight: 1,
+      group: 'pedimento',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /aduanaDespacho/i,
+      weight: 1,
+      group: 'pedimento',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /tipoOperacion/i,
+      weight: 1,
+      group: 'pedimento',
+    },
+    // structural gate for the pedimento-markers path (weight 0 = gate only)
+    { kind: 'CONTENT_REGEX', pattern: /<\?xml/i, weight: 0, group: 'xml' },
+  ],
+};
+
+// --- factura_inter_agencia ---------------------------------------------------
+// Original: isCfdiContent AND ≥2 distinct configured RFCs AND broker clave.
+// The pair of agency RFCs and the broker-service clave are modelled as REQUIRED
+// clues, which is what lets this win over `factura_comercial` purely by score —
+// no registration-order dependency. (Scope-limited to the configured pair, same
+// as the original; widening means making RFC presence a counting rule.)
+const interAgencia = {
+  documentType: 'factura_inter_agencia',
+  extensions: ['xml', 'pdf'],
+  minScore: 25, // both required RFCs (10+10) + required clave (5)
+  priority: 3,
+  ...reuse(facturaInterAgenciaDefinition),
+  clues: [
+    ...INTER_AGENCIA_RFCS.map((rfc) => ({
+      kind: 'CONTENT_REGEX',
+      pattern: new RegExp(`\\b${rfc}\\b`, 'i'),
+      weight: 10,
+      required: true,
+    })),
+    // BROKER_SERVICE_CLAVE_PROD_SERV (78141502 = servicios de agentes aduaneros)
+    { kind: 'CONTENT_REGEX', pattern: /78141502/, weight: 5, required: true },
+    // CFDI content markers (informational positive signal)
+    { kind: 'CONTENT_REGEX', pattern: /cfdi:Comprobante/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /xmlns:cfdi/i, weight: 1 },
+    { kind: 'CONTENT_REGEX', pattern: /TipoDeComprobante/i, weight: 1 },
+  ],
+};
+
+// --- factura_comercial -------------------------------------------------------
+// Original: cfdiMatches≥2 OR (invoiceMatches≥1 AND customsMatches≥1).
+// Faithfully expressed with clue groups + qualify (OR-of-ANDs) — a flat
+// minScore could not enforce the "invoice AND customs" pairing and produced
+// false positives on COVE acuses (customs keywords alone reaching the threshold).
+const facturaComercial = {
+  documentType: 'factura_comercial',
+  extensions: ['pdf', 'xml'],
+  priority: 0,
+  qualify: [{ cfdi: 2 }, { invoice: 1, customs: 1 }],
+  ...reuse(facturasComerciales),
+  clues: [
+    { kind: 'CONTENT_REGEX', pattern: /cfdi:Comprobante/i, group: 'cfdi' },
+    { kind: 'CONTENT_REGEX', pattern: /xmlns:cfdi/i, group: 'cfdi' },
+    { kind: 'CONTENT_REGEX', pattern: /TipoDeComprobante/i, group: 'cfdi' },
+    { kind: 'CONTENT_REGEX', pattern: /timbreFiscalDigital/i, group: 'cfdi' },
+    { kind: 'CONTENT_REGEX', pattern: /SelloSAT/i, group: 'cfdi' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /factura\s*(comercial|de\s*venta|de\s*exportaci[oó]n)?/i,
+      group: 'invoice',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /commercial\s*invoice/i,
+      group: 'invoice',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /invoice\s*number/i, group: 'invoice' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /n[uú]mero\s*de\s*factura/i,
+      group: 'invoice',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /pedimento/i, group: 'customs' },
+    { kind: 'CONTENT_REGEX', pattern: /aduana/i, group: 'customs' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /importaci[oó]n|exportaci[oó]n/i,
+      group: 'customs',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /despacho\s*aduanero/i,
+      group: 'customs',
+    },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /fracci[oó]n\s*arancelaria/i,
+      group: 'customs',
+    },
+  ],
+};
+
+// --- support_document --------------------------------------------------------
+// Original: soapFound≥2 OR customsFound≥2. Broad fallback → lowest priority so
+// it only wins when no specific matcher qualifies.
+const supportDocument = {
+  documentType: 'support_document',
+  extensions: ['xml', 'txt', 'json'],
+  priority: -1,
+  qualify: [{ soap: 2 }, { customs: 2 }],
+  ...reuse(supportDocumentDefinition),
+  clues: [
+    { kind: 'CONTENT_REGEX', pattern: /soapenv:Envelope/i, group: 'soap' },
+    { kind: 'CONTENT_REGEX', pattern: /xmlns:soapenv=/i, group: 'soap' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /solicitarRecibirCoveServicio/i,
+      group: 'soap',
+    },
+    { kind: 'CONTENT_REGEX', pattern: /tipoOperacion/i, group: 'soap' },
+    { kind: 'CONTENT_REGEX', pattern: /patenteAduanal/i, group: 'soap' },
+    // customs metadata fallback — original requires BOTH patterns present
+    { kind: 'CONTENT_REGEX', pattern: /rfc/i, group: 'customs' },
+    {
+      kind: 'CONTENT_REGEX',
+      pattern: /patente|aduana|customs|pedimento/i,
+      group: 'customs',
+    },
+  ],
+};
+
+/**
+ * Default/global seed set. Order is irrelevant — best-match selects the winner.
+ * (This becomes the seed for DEFAULT matchers when the model moves to the DB.)
+ */
+export const scoringMatchers = [
+  simplificado,
+  completo,
+  completoXml,
+  dodaPdf,
+  dodaXml,
+  interAgencia,
+  facturaComercial,
+  supportDocument,
+];