Feature/money mirror issue 012 production (#20)

shadowdevcode · web-flow · commit c2ad3c5201be · 2026-04-09T01:37:48.000+05:30
* feat(money-mirror): prepare issue-012 production release candidate

Bundle the latest local Money Mirror enhancements and pipeline artifacts into a single branch for production validation, including dashboard clarity UX, frequency insights, guided review flows, proactive touchpoints, and release gating documentation.

Made-with: Cursor

* ci: retry assign-reviewers on transient provider overloads

Add bounded retries with backoff for the Claude /assign-reviewers step so temporary 529 overloaded errors do not fail PR checks.

Made-with: Cursor

* fix(money-mirror): harden production pdf parsing
diff --git a/apps/money-mirror/__tests__/api/parse.test.ts b/apps/money-mirror/__tests__/api/parse.test.ts
@@ -7,22 +7,29 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { NextRequest } from 'next/server';
 
+const mockExtractPdfText = vi.fn().mockResolvedValue({
+  text: '01/03/2026 SWIGGY 450.00 Dr\n02/03/2026 SALARY 50000.00 Cr',
+  pageCount: 1,
+});
+
+class MockPdfExtractionError extends Error {
+  code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
 vi.mock('@/lib/pdf-parser', () => ({
-  extractPdfText: vi.fn().mockResolvedValue({
-    text: '01/03/2026 SWIGGY 450.00 Dr\n02/03/2026 SALARY 50000.00 Cr',
-    pageCount: 1,
-  }),
-  PdfExtractionError: class PdfExtractionError extends Error {
-    code: string;
-    constructor(message: string, code: string) {
-      super(message);
-      this.code = code;
-    }
-  },
+  extractPdfText: mockExtractPdfText,
+  PdfExtractionError: MockPdfExtractionError,
 }));
 
+const mockCaptureServerEvent = vi.fn().mockResolvedValue(undefined);
+
 vi.mock('@/lib/posthog', () => ({
-  captureServerEvent: vi.fn().mockResolvedValue(undefined),
+  captureServerEvent: mockCaptureServerEvent,
 }));
 
 const mockGetSessionUser = vi.fn();
@@ -90,6 +97,10 @@ describe('POST /api/statement/parse', () => {
   beforeEach(() => {
     vi.clearAllMocks();
 
+    mockExtractPdfText.mockResolvedValue({
+      text: '01/03/2026 SWIGGY 450.00 Dr\n02/03/2026 SALARY 50000.00 Cr',
+      pageCount: 1,
+    });
     mockGetSessionUser.mockResolvedValue({
       id: 'user-123',
       email: 'vijay@example.com',
@@ -245,4 +256,34 @@ describe('POST /api/statement/parse', () => {
       credit_limit_paisa: 15000000,
     });
   });
+
+  it('returns 422 for parser failures and emits parser diagnostics', async () => {
+    mockExtractPdfText.mockRejectedValueOnce(
+      new MockPdfExtractionError(
+        'Failed to parse PDF: DOMMatrix is not defined in server runtime',
+        'PARSE_FAILED'
+      )
+    );
+
+    const POST = await getRoute();
+    const res = await POST(makeRequest(makePdfFile('statement.pdf', 1024)));
+    const body = await res.json();
+
+    expect(res.status).toBe(422);
+    expect(body).toMatchObject({
+      error: 'Failed to read the PDF. Please ensure it is a valid bank statement.',
+    });
+    expect(mockCaptureServerEvent).toHaveBeenCalledWith(
+      'user-123',
+      'statement_parse_failed',
+      expect.objectContaining({
+        error_type: 'PARSE_FAILED',
+        file_name: expect.any(String),
+        statement_type: 'bank_account',
+        parser_stage: 'pdf_text_extraction',
+        parser_detail: 'Failed to parse PDF: DOMMatrix is not defined in server runtime',
+      })
+    );
+    expect(mockGenerateContent).not.toHaveBeenCalled();
+  });
 });
diff --git a/apps/money-mirror/__tests__/lib/pdf-parser.test.ts b/apps/money-mirror/__tests__/lib/pdf-parser.test.ts
@@ -6,38 +6,49 @@
  */
 
 // @vitest-environment node
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// ─── Hoisted mock fns ─────────────────────────────────────────
-const { mockGetText, mockDestroy, MockPDFParse } = vi.hoisted(() => {
-  const mockGetText = vi.fn();
-  const mockDestroy = vi.fn().mockResolvedValue(undefined);
-  function MockPDFParse(opts: unknown) {
-    void opts;
-    return { getText: mockGetText, destroy: mockDestroy };
-  }
-  return { mockGetText, mockDestroy, MockPDFParse };
-});
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+type PdfParserModule = typeof import('@/lib/pdf-parser');
 
-vi.mock('pdf-parse', () => ({
-  PDFParse: MockPDFParse,
-}));
+const mockGetText = vi.fn();
+const mockDestroy = vi.fn();
+const mockPdfParseConstructor = vi.fn(function MockPDFParse(opts: unknown) {
+  void opts;
+  return { getText: mockGetText, destroy: mockDestroy };
+});
+const mockPdfParseFactory = vi.fn(async () => {
+  return {
+    PDFParse: mockPdfParseConstructor,
+  };
+});
 
-import { extractPdfText, PdfExtractionError } from '@/lib/pdf-parser';
+async function loadPdfParserModule(): Promise<PdfParserModule> {
+  vi.resetModules();
+  vi.doMock('pdf-parse', mockPdfParseFactory);
+  return import('@/lib/pdf-parser');
+}
 
 describe('extractPdfText', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockDestroy.mockResolvedValue(undefined);
+    delete (globalThis as Record<string, unknown>).DOMMatrix;
+    delete (globalThis as Record<string, unknown>).ImageData;
+    delete (globalThis as Record<string, unknown>).Path2D;
   });
 
   it('throws EMPTY_FILE when buffer is empty', async () => {
+    const { extractPdfText } = await loadPdfParserModule();
+
     await expect(extractPdfText(Buffer.alloc(0))).rejects.toMatchObject({
       code: 'EMPTY_FILE',
     });
+    expect(mockPdfParseFactory).not.toHaveBeenCalled();
   });
 
   it('throws PARSE_FAILED when getText throws', async () => {
+    const { extractPdfText } = await loadPdfParserModule();
+
     mockGetText.mockRejectedValue(new Error('Invalid PDF structure'));
     const garbage = Buffer.from('not a pdf', 'utf-8');
     await expect(extractPdfText(garbage)).rejects.toMatchObject({
@@ -46,6 +57,8 @@ describe('extractPdfText', () => {
   });
 
   it('throws EMPTY_TEXT when PDF yields blank text', async () => {
+    const { extractPdfText } = await loadPdfParserModule();
+
     mockGetText.mockResolvedValue({ text: '   ', total: 1 });
     const fakeBuffer = Buffer.from('fake pdf content');
     await expect(extractPdfText(fakeBuffer)).rejects.toMatchObject({
@@ -54,6 +67,8 @@ describe('extractPdfText', () => {
   });
 
   it('returns text and pageCount on success', async () => {
+    const { extractPdfText } = await loadPdfParserModule();
+
     const fakeText = '01/03/26  SWIGGY  500.00  49500.00\n';
     mockGetText.mockResolvedValue({ text: fakeText, total: 3 });
     const fakeBuffer = Buffer.from('fake pdf content');
@@ -65,10 +80,47 @@ describe('extractPdfText', () => {
   });
 
   it('returns a PdfExtractionError instance on failure', async () => {
+    const { extractPdfText, PdfExtractionError } = await loadPdfParserModule();
+
     try {
       await extractPdfText(Buffer.alloc(0));
     } catch (e) {
       expect(e).toBeInstanceOf(PdfExtractionError);
     }
   });
+
+  it('lazy-loads pdf-parse only after server polyfills are installed', async () => {
+    mockPdfParseFactory.mockImplementationOnce(async () => {
+      expect(globalThis.DOMMatrix).toBeTypeOf('function');
+      expect(globalThis.ImageData).toBeTypeOf('function');
+      expect(globalThis.Path2D).toBeTypeOf('function');
+
+      return {
+        PDFParse: function MockPDFParse() {
+          return { getText: mockGetText, destroy: mockDestroy };
+        },
+      };
+    });
+
+    const { extractPdfText } = await loadPdfParserModule();
+    mockGetText.mockResolvedValue({ text: 'statement text', total: 2 });
+
+    await expect(extractPdfText(Buffer.from('fake pdf content'))).resolves.toMatchObject({
+      text: 'statement text',
+      pageCount: 2,
+    });
+  });
+
+  it('maps parser initialization failures to PARSE_FAILED', async () => {
+    mockPdfParseConstructor.mockImplementation(function MockPDFParseFailure() {
+      throw new Error('DOMMatrix is not defined');
+    });
+
+    const { extractPdfText } = await loadPdfParserModule();
+
+    await expect(extractPdfText(Buffer.from('fake pdf content'))).rejects.toMatchObject({
+      code: 'PARSE_FAILED',
+      message: 'Failed to parse PDF: DOMMatrix is not defined',
+    });
+  });
 });
diff --git a/apps/money-mirror/src/app/api/statement/parse/route.ts b/apps/money-mirror/src/app/api/statement/parse/route.ts
@@ -125,9 +125,14 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     fileBuffer = null;
 
     const code = err instanceof PdfExtractionError ? err.code : 'PARSE_FAILED';
+    const parserDetail =
+      err instanceof Error ? err.message.slice(0, 200) : String(err).slice(0, 200);
     captureServerEvent(userId, 'statement_parse_failed', {
       error_type: code,
       file_name: fileName,
+      statement_type: statementType,
+      parser_stage: 'pdf_text_extraction',
+      parser_detail: parserDetail,
     }).catch(() => {});
     const errorMessage =
       code === 'EMPTY_TEXT'
diff --git a/apps/money-mirror/src/lib/pdf-parser.ts b/apps/money-mirror/src/lib/pdf-parser.ts
@@ -9,8 +9,6 @@
  * eligible for GC. See /api/statement/parse/route.ts.
  */
 
-import { PDFParse } from 'pdf-parse';
-
 export interface PdfExtractionResult {
   text: string;
   pageCount: number;
@@ -26,6 +24,105 @@ export class PdfExtractionError extends Error {
   }
 }
 
+interface PdfParseModule {
+  PDFParse: new (opts: { data: Uint8Array; verbosity: number }) => {
+    getText: () => Promise<{ text?: string; total?: number }>;
+    destroy: () => Promise<void>;
+  };
+}
+
+interface DomMatrixLike {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}
+
+class MinimalDOMMatrix implements DomMatrixLike {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+
+  constructor(init?: Iterable<number> | ArrayLike<number>) {
+    const values = init ? Array.from(init).slice(0, 6) : [];
+    this.a = values[0] ?? 1;
+    this.b = values[1] ?? 0;
+    this.c = values[2] ?? 0;
+    this.d = values[3] ?? 1;
+    this.e = values[4] ?? 0;
+    this.f = values[5] ?? 0;
+  }
+
+  multiplySelf(): MinimalDOMMatrix {
+    return this;
+  }
+
+  preMultiplySelf(): MinimalDOMMatrix {
+    return this;
+  }
+
+  translate(tx?: number, ty?: number): MinimalDOMMatrix {
+    this.e += tx ?? 0;
+    this.f += ty ?? 0;
+    return this;
+  }
+
+  scale(scaleX?: number, scaleY?: number): MinimalDOMMatrix {
+    this.a *= scaleX ?? 1;
+    this.d *= scaleY ?? scaleX ?? 1;
+    return this;
+  }
+
+  invertSelf(): MinimalDOMMatrix {
+    return this;
+  }
+}
+
+class MinimalImageData {
+  data: Uint8ClampedArray;
+  width: number;
+  height: number;
+
+  constructor(data: Uint8ClampedArray, width: number, height: number) {
+    this.data = data;
+    this.width = width;
+    this.height = height;
+  }
+}
+
+class MinimalPath2D {
+  addPath(): void {}
+}
+
+let pdfParseModulePromise: Promise<PdfParseModule> | null = null;
+
+function ensurePdfJsServerPolyfills(): void {
+  const globalRecord = globalThis as Record<string, unknown>;
+
+  if (!globalRecord.DOMMatrix) {
+    globalRecord.DOMMatrix = MinimalDOMMatrix;
+  }
+  if (!globalRecord.ImageData) {
+    globalRecord.ImageData = MinimalImageData;
+  }
+  if (!globalRecord.Path2D) {
+    globalRecord.Path2D = MinimalPath2D;
+  }
+}
+
+async function loadPdfParseModule(): Promise<PdfParseModule> {
+  if (!pdfParseModulePromise) {
+    ensurePdfJsServerPolyfills();
+    pdfParseModulePromise = import('pdf-parse') as Promise<PdfParseModule>;
+  }
+  return pdfParseModulePromise;
+}
+
 /**
  * Extract plain text from a PDF buffer.
  *
@@ -42,6 +139,7 @@ export async function extractPdfText(buffer: Buffer): Promise<PdfExtractionResul
   let pageCount: number;
 
   try {
+    const { PDFParse } = await loadPdfParseModule();
     const parser = new PDFParse({ data: buffer, verbosity: 0 });
     const result = await parser.getText();
     text = result.text ?? '';
