@arela/uploader 1.0.22 → 1.0.24

package/tests/unit/scoring-engine.test.js

@@ -0,0 +1,221 @@
+/**
+ * Tests for the best-match scoring engine (PROTOTYPE).
+ *
+ * Two layers:
+ *  1. Engine mechanics (pure): extension filter, required/negative
+ *     disqualification, weighted scoring, threshold, tie-breaking.
+ *  2. Faithfulness on representative documents: the seed matchers select the
+ *     same document type best-match would, including the key
+ *     `factura_inter_agencia` vs `factura_comercial` case resolved by SCORE
+ *     (not registration order).
+ */
+import { describe, it, expect } from '@jest/globals';
+
+import {
+  classifyDocument,
+  scoreMatcher,
+  selectBestMatch,
+} from '../../src/scoring/scoring-engine.js';
+import { scoringMatchers } from '../../src/scoring/matchers-seed.js';
+
+// ----------------------------- engine mechanics -----------------------------
+describe('scoreMatcher (mechanics)', () => {
+  const base = {
+    documentType: 't',
+    extensions: ['pdf'],
+    minScore: 2,
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+      { kind: 'CONTENT_REGEX', pattern: /beta/i, weight: 1 },
+    ],
+  };
+
+  it('returns null when the extension does not apply', () => {
+    expect(scoreMatcher(base, { source: 'alpha', extension: 'xml' })).toBeNull();
+  });
+
+  it('sums the weights of matched clues', () => {
+    const r = scoreMatcher(base, { source: 'alpha beta', extension: 'pdf' });
+    expect(r.score).toBe(3);
+    expect(r.totalWeight).toBe(3);
+    expect(r.fraction).toBeCloseTo(1);
+    expect(r.passed).toBe(true);
+  });
+
+  it('does not pass below minScore', () => {
+    const r = scoreMatcher(base, { source: 'beta', extension: 'pdf' });
+    expect(r.score).toBe(1);
+    expect(r.passed).toBe(false);
+  });
+
+  it('disqualifies on a negative clue hit', () => {
+    const m = {
+      ...base,
+      clues: [
+        { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+        { kind: 'CONTENT_REGEX', pattern: /excluded/i, negative: true },
+      ],
+    };
+    const r = scoreMatcher(m, { source: 'alpha excluded', extension: 'pdf' });
+    expect(r.disqualified).toBe(true);
+  });
+
+  it('disqualifies when a required clue is missing', () => {
+    const m = {
+      ...base,
+      clues: [
+        { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 },
+        { kind: 'CONTENT_REGEX', pattern: /mandatory/i, required: true, weight: 1 },
+      ],
+    };
+    const r = scoreMatcher(m, { source: 'alpha', extension: 'pdf' });
+    expect(r.disqualified).toBe(true);
+  });
+});
+
+describe('selectBestMatch (ordering)', () => {
+  const ctx = { source: 'alpha beta gamma', extension: 'pdf' };
+  const low = {
+    documentType: 'low',
+    extensions: ['pdf'],
+    minScore: 1,
+    clues: [{ kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 1 }],
+  };
+  const high = {
+    documentType: 'high',
+    extensions: ['pdf'],
+    minScore: 1,
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 1 },
+      { kind: 'CONTENT_REGEX', pattern: /beta/i, weight: 1 },
+      { kind: 'CONTENT_REGEX', pattern: /gamma/i, weight: 1 },
+    ],
+  };
+
+  it('picks the highest score regardless of array order', () => {
+    expect(selectBestMatch([low, high], ctx).documentType).toBe('high');
+    expect(selectBestMatch([high, low], ctx).documentType).toBe('high');
+  });
+
+  it('breaks score ties by priority', () => {
+    const a = {
+      documentType: 'a',
+      extensions: ['pdf'],
+      minScore: 1,
+      priority: 0,
+      clues: [{ kind: 'CONTENT_REGEX', pattern: /alpha/i, weight: 2 }],
+    };
+    const b = { ...a, documentType: 'b', priority: 5 };
+    expect(selectBestMatch([a, b], ctx).documentType).toBe('b');
+  });
+});
+
+describe('qualify rules (group gate, OR-of-ANDs)', () => {
+  // mirrors factura_comercial: (cfdi>=2) OR (invoice>=1 AND customs>=1)
+  const m = {
+    documentType: 'q',
+    extensions: ['xml'],
+    qualify: [{ cfdi: 2 }, { invoice: 1, customs: 1 }],
+    clues: [
+      { kind: 'CONTENT_REGEX', pattern: /cfdiA/i, group: 'cfdi' },
+      { kind: 'CONTENT_REGEX', pattern: /cfdiB/i, group: 'cfdi' },
+      { kind: 'CONTENT_REGEX', pattern: /factura/i, group: 'invoice' },
+      { kind: 'CONTENT_REGEX', pattern: /aduana/i, group: 'customs' },
+    ],
+  };
+
+  it('qualifies when a single rule is fully satisfied (cfdi>=2)', () => {
+    expect(scoreMatcher(m, { source: 'cfdiA cfdiB', extension: 'xml' }).passed).toBe(true);
+  });
+
+  it('qualifies on the AND rule (invoice AND customs)', () => {
+    expect(scoreMatcher(m, { source: 'factura aduana', extension: 'xml' }).passed).toBe(true);
+  });
+
+  it('does NOT qualify on a partial AND rule (customs alone)', () => {
+    // This is the COVE-acuse false-positive case the flat model produced.
+    const r = scoreMatcher(m, { source: 'aduana pedimento aduana', extension: 'xml' });
+    expect(r.passed).toBe(false);
+  });
+
+  it('does NOT qualify with only one cfdi marker', () => {
+    expect(scoreMatcher(m, { source: 'cfdiA', extension: 'xml' }).passed).toBe(false);
+  });
+});
+
+// --------------------------- faithfulness on docs ---------------------------
+const DOCS = {
+  simplificadoPaid: {
+    extension: 'pdf',
+    source: `FORMA SIMPLIFICADA DEL PEDIMENTO
+NUM. PEDIMENTO: 26 07 3429 6000079
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+RFC: CSM9204097Q1
+FECHA DE PAGO: 04/03/2026`,
+  },
+  simplificadoUnpaid: {
+    extension: 'pdf',
+    source: `FORMA SIMPLIFICADA DE PEDIMENTO
+NUM. PEDIMENTO: 26 07 3429 6000080
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+RFC: CSM9204097Q1
+*** NO PAGADO ***`,
+  },
+  completo: {
+    extension: 'pdf',
+    source: `NUM. PEDIMENTO: 26 07 3429 2002089
+CVE. PEDIMENTO: A1
+T. OPER: IMP
+SEGUNDA COPIA TRANSPORTISTA
+CUADRO DE LIQUIDACION
+*** PAGO ELECTRONICO ***
+FECHA DE PAGO: 02/03/2026`,
+  },
+  interAgencia: {
+    extension: 'xml',
+    source: `<cfdi:Comprobante xmlns:cfdi="..." TipoDeComprobante="I">
+  <cfdi:Emisor Rfc="NAA120215F20"/>
+  <cfdi:Receptor Rfc="PCC1008161WA"/>
+  <cfdi:Concepto ClaveProdServ="78141502"/>
+</cfdi:Comprobante>`,
+  },
+};
+
+describe('seed matchers select the correct document type', () => {
+  it('classifies a paid simplificado', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.simplificadoPaid);
+    expect(r.detectedType).toBe('pedimento_simplificado');
+  });
+
+  it('resolves an unpaid simplificado to proforma (resolveType reused)', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.simplificadoUnpaid);
+    expect(r.detectedType).toBe('proforma');
+  });
+
+  it('separates completo from simplificado without registration order', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.completo);
+    expect(r.detectedType).toBe('pedimento_completo');
+  });
+});
+
+describe('inter-agencia precedence is by score, not order', () => {
+  it('wins over factura_comercial with the default seed', () => {
+    const r = classifyDocument(scoringMatchers, DOCS.interAgencia);
+    expect(r.detectedType).toBe('factura_inter_agencia');
+    // factura_comercial also qualifies but scores far lower
+    const comercial = r.candidates.find(
+      (c) => c.documentType === 'factura_comercial',
+    );
+    const winner = r.candidates[0];
+    expect(winner.documentType).toBe('factura_inter_agencia');
+    if (comercial) expect(winner.score).toBeGreaterThan(comercial.score);
+  });
+
+  it('still wins when the matcher array is reversed (order-independent)', () => {
+    const reversed = [...scoringMatchers].reverse();
+    const r = classifyDocument(reversed, DOCS.interAgencia);
+    expect(r.detectedType).toBe('factura_inter_agencia');
+  });
+});