financeops-mcp 0.1.0

package/tests/analysis/anomaly.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from 'vitest';
+import { detectAnomalies } from '../../src/analysis/anomaly.js';
+import type { Transaction } from '../../src/types.js';
+
+function makeTransaction(
+  id: string,
+  date: string,
+  amount: number,
+  description: string,
+  category: string = 'Revenue',
+  type: 'income' | 'expense' | 'transfer' = 'income'
+): Transaction {
+  return {
+    id,
+    date,
+    amount,
+    currency: 'usd',
+    description,
+    category,
+    type,
+    provider: 'stripe',
+  };
+}
+
+describe('detectAnomalies', () => {
+  describe('duplicate detection', () => {
+    it('detects duplicate: same amount, similar description, within 24 hours', () => {
+      const transactions = [
+        makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment from Acme'),
+        makeTransaction('t2', '2026-03-01T14:00:00Z', 5000, 'Invoice payment from Acme'),
+        makeTransaction('t3', '2026-03-05T10:00:00Z', 3000, 'Different transaction'),
+      ];
+
+      const anomalies = detectAnomalies(transactions);
+      const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+      expect(duplicates).toHaveLength(1);
+      expect(duplicates[0].severity).toBe('high');
+    });
+
+    it('does NOT flag as duplicate if descriptions are different', () => {
+      const transactions = [
+        makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme'),
+        makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Hosting fee AWS monthly bill'),
+      ];
+
+      const anomalies = detectAnomalies(transactions);
+      const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+      expect(duplicates).toHaveLength(0);
+    });
+
+    it('does NOT flag as duplicate if more than 24 hours apart', () => {
+      const transactions = [
+        makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+        makeTransaction('t2', '2026-03-03T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+      ];
+
+      const anomalies = detectAnomalies(transactions);
+      const duplicates = anomalies.filter((a) => a.type === 'duplicate');
+
+      expect(duplicates).toHaveLength(0);
+    });
+  });
+
+  describe('large variance detection', () => {
+    it('detects transaction significantly above category average', () => {
+      // Category average ≈ 3000, one transaction at 9000 = 3× average
+      const transactions = [
+        makeTransaction('t1', '2026-03-01', 2000, 'Fee A', 'Fees'),
+        makeTransaction('t2', '2026-03-02', 2500, 'Fee B', 'Fees'),
+        makeTransaction('t3', '2026-03-03', 3000, 'Fee C', 'Fees'),
+        makeTransaction('t4', '2026-03-04', 3000, 'Fee D', 'Fees'),
+        makeTransaction('t5', '2026-03-05', 9000, 'Fee E (spike!)', 'Fees'),
+      ];
+
+      const anomalies = detectAnomalies(transactions, 'medium');  // 2× threshold
+      const variances = anomalies.filter((a) => a.type === 'large_variance');
+
+      expect(variances.length).toBeGreaterThan(0);
+      expect(variances[0].transaction?.id).toBe('t5');
+    });
+
+    it('sensitivity level affects detection threshold', () => {
+      // At 2500 average, 5000 = 2× — detected on 'medium' (2×) but not 'low' (3×)
+      const transactions = [
+        makeTransaction('t1', '2026-03-01', 2000, 'Fee A', 'Fees'),
+        makeTransaction('t2', '2026-03-02', 2500, 'Fee B', 'Fees'),
+        makeTransaction('t3', '2026-03-03', 2500, 'Fee C', 'Fees'),
+        makeTransaction('t4', '2026-03-04', 2500, 'Fee D', 'Fees'),
+        makeTransaction('t5', '2026-03-05', 6000, 'Fee E', 'Fees'),
+      ];
+
+      const anomaliesMedium = detectAnomalies(transactions, 'medium');
+      const anomaliesLow = detectAnomalies(transactions, 'low');
+
+      const variancesMedium = anomaliesMedium.filter((a) => a.type === 'large_variance');
+      const variancesLow = anomaliesLow.filter((a) => a.type === 'large_variance');
+
+      // Medium threshold (2×) should catch more than low threshold (3×)
+      expect(variancesMedium.length).toBeGreaterThanOrEqual(variancesLow.length);
+    });
+
+    it('skips categories with fewer than 3 transactions', () => {
+      const transactions = [
+        makeTransaction('t1', '2026-03-01', 100, 'Item A', 'Rare'),
+        makeTransaction('t2', '2026-03-02', 10000, 'Item B (huge!)', 'Rare'),
+      ];
+
+      const anomalies = detectAnomalies(transactions, 'low');
+      const variances = anomalies.filter((a) => a.type === 'large_variance');
+
+      expect(variances).toHaveLength(0);
+    });
+  });
+
+  it('returns empty array for empty input', () => {
+    const anomalies = detectAnomalies([]);
+    expect(anomalies).toHaveLength(0);
+  });
+
+  it('each anomaly has required fields', () => {
+    const transactions = [
+      makeTransaction('t1', '2026-03-01T10:00:00Z', 5000, 'Invoice payment Acme Corp'),
+      makeTransaction('t2', '2026-03-01T12:00:00Z', 5000, 'Invoice payment Acme Corp'),
+    ];
+
+    const anomalies = detectAnomalies(transactions);
+
+    for (const anomaly of anomalies) {
+      expect(anomaly.id).toBeDefined();
+      expect(anomaly.type).toBeDefined();
+      expect(anomaly.severity).toBeDefined();
+      expect(anomaly.description).toBeDefined();
+    }
+  });
+});

package/tests/analysis/cashflow.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { forecastCashFlow } from '../../src/analysis/cashflow.js';
+import type { Transaction } from '../../src/types.js';
+
+function makeTransaction(
+  id: string,
+  date: string,
+  amount: number,
+  type: 'income' | 'expense' | 'transfer'
+): Transaction {
+  return {
+    id,
+    date,
+    amount,
+    currency: 'usd',
+    description: `${type} ${id}`,
+    type,
+    provider: 'stripe',
+  };
+}
+
+describe('forecastCashFlow', () => {
+  // Build 3 months of deterministic historical data
+  // Jan 2026: income 10000 cents ($100), expense 5000 cents ($50)
+  // Feb 2026: income 12000 cents ($120), expense 6000 cents ($60)
+  // Mar 2026: income 14000 cents ($140), expense 7000 cents ($70)
+  const historicalTransactions: Transaction[] = [
+    makeTransaction('jan-inc', '2026-01-15', 10000, 'income'),
+    makeTransaction('jan-exp', '2026-01-20', 5000, 'expense'),
+    makeTransaction('feb-inc', '2026-02-15', 12000, 'income'),
+    makeTransaction('feb-exp', '2026-02-20', 6000, 'expense'),
+    makeTransaction('mar-inc', '2026-03-15', 14000, 'income'),
+    makeTransaction('mar-exp', '2026-03-20', 7000, 'expense'),
+  ];
+
+  it('returns 3 scenarios: conservative, realistic, optimistic', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    expect(forecast.scenarios.conservative).toBeDefined();
+    expect(forecast.scenarios.realistic).toBeDefined();
+    expect(forecast.scenarios.optimistic).toBeDefined();
+  });
+
+  it('returns the correct number of months in each scenario', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    expect(forecast.scenarios.realistic).toHaveLength(3);
+    expect(forecast.scenarios.conservative).toHaveLength(3);
+    expect(forecast.scenarios.optimistic).toHaveLength(3);
+  });
+
+  it('optimistic income is higher than realistic', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    for (let i = 0; i < 3; i++) {
+      expect(forecast.scenarios.optimistic[i].income).toBeGreaterThan(
+        forecast.scenarios.realistic[i].income
+      );
+    }
+  });
+
+  it('conservative income is lower than realistic', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    for (let i = 0; i < 3; i++) {
+      expect(forecast.scenarios.conservative[i].income).toBeLessThan(
+        forecast.scenarios.realistic[i].income
+      );
+    }
+  });
+
+  it('month labels are in YYYY-MM format starting from next month', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    const months = forecast.scenarios.realistic.map((m) => m.month);
+    expect(months[0]).toBe('2026-04');
+    expect(months[1]).toBe('2026-05');
+    expect(months[2]).toBe('2026-06');
+  });
+
+  it('cumulative_net is running total of net', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+    const realistic = forecast.scenarios.realistic;
+
+    let running = 0;
+    for (const month of realistic) {
+      running += month.net;
+      expect(month.cumulative_net).toBeCloseTo(running, 1);
+    }
+  });
+
+  it('historical averages are in major currency units (not cents)', () => {
+    const forecast = forecastCashFlow(historicalTransactions, 3);
+
+    // Weighted avg income ≈ 120 (weighted towards most recent 140)
+    expect(forecast.historical_monthly_income).toBeGreaterThan(10);
+    expect(forecast.historical_monthly_income).toBeLessThan(200);
+  });
+
+  it('returns empty scenarios with 0 averages when no historical data', () => {
+    const forecast = forecastCashFlow([], 3);
+
+    expect(forecast.historical_monthly_income).toBe(0);
+    expect(forecast.historical_monthly_expenses).toBe(0);
+  });
+
+  it('supports different monthsAhead values', () => {
+    const forecast6 = forecastCashFlow(historicalTransactions, 6);
+    expect(forecast6.scenarios.realistic).toHaveLength(6);
+    expect(forecast6.period_months).toBe(6);
+  });
+});

package/tests/analysis/pnl.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { generatePnL } from '../../src/analysis/pnl.js';
+import { mockTransactions, mockExpenses } from '../helpers/mock-data.js';
+
+describe('generatePnL', () => {
+  // Use a wide date range so all mock transactions are included
+  const dateFrom = '2026-01-01';
+  const dateTo = '2026-12-31';
+
+  it('calculates revenue from income transactions only', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const incomeTransactions = transactions.filter((t) => t.type === 'income');
+    const expectedRevenue = incomeTransactions.reduce((s, t) => s + t.amount, 0) / 100;
+
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    expect(pnl.revenue).toBe(expectedRevenue);
+  });
+
+  it('calculates COGS from expense transactions', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const expenseTransactions = transactions.filter((t) => t.type === 'expense');
+    const expectedCogs = expenseTransactions.reduce((s, t) => s + t.amount, 0) / 100;
+
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    expect(pnl.cogs).toBe(expectedCogs);
+  });
+
+  it('calculates operating expenses from Expense records', () => {
+    const expenses = mockExpenses(4, 'stripe');
+    const expectedOpExp = expenses.reduce((s, e) => s + e.amount, 0) / 100;
+
+    const pnl = generatePnL([], expenses, dateFrom, dateTo);
+
+    expect(pnl.operating_expenses).toBe(expectedOpExp);
+  });
+
+  it('calculates gross profit = revenue - cogs', () => {
+    const transactions = mockTransactions(6, 'stripe');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    expect(pnl.gross_profit).toBeCloseTo(pnl.revenue - pnl.cogs, 5);
+  });
+
+  it('calculates net income = gross profit - operating expenses', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const expenses = mockExpenses(4, 'stripe');
+    const pnl = generatePnL(transactions, expenses, dateFrom, dateTo);
+
+    expect(pnl.net_income).toBeCloseTo(pnl.gross_profit - pnl.operating_expenses, 5);
+  });
+
+  it('calculates gross margin percentage', () => {
+    const transactions = mockTransactions(10, 'stripe');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    const expectedMargin = pnl.revenue > 0 ? (pnl.gross_profit / pnl.revenue) * 100 : 0;
+    expect(pnl.gross_margin_pct).toBeCloseTo(expectedMargin, 1);
+  });
+
+  it('returns currency from transactions (not hardcoded)', () => {
+    const transactions = mockTransactions(5, 'stripe');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+
+    expect(pnl.currency).toBe('usd');
+  });
+
+  it('returns usd as default currency when no transactions', () => {
+    const pnl = generatePnL([], [], dateFrom, dateTo);
+    expect(pnl.currency).toBe('usd');
+  });
+
+  it('groups expenses by category in by_category', () => {
+    const expenses = mockExpenses(4, 'stripe');
+    const pnl = generatePnL([], expenses, dateFrom, dateTo);
+
+    // mockExpenses(4) uses categories at indices 0..3: Processing Fees, Refunds, Office, Software
+    expect(Object.keys(pnl.by_category)).toHaveLength(4);
+    expect(pnl.by_category['Processing Fees']).toBeDefined();
+  });
+
+  it('includes period metadata', () => {
+    const pnl = generatePnL([], [], dateFrom, dateTo);
+    expect(pnl.date_from).toBe(dateFrom);
+    expect(pnl.date_to).toBe(dateTo);
+    expect(pnl.period).toContain(dateFrom);
+  });
+
+  it('revenue is 0 when there are no income transactions', () => {
+    const transactions = mockTransactions(3, 'stripe').filter((t) => t.type !== 'income');
+    const pnl = generatePnL(transactions, [], dateFrom, dateTo);
+    expect(pnl.revenue).toBe(0);
+  });
+});

package/tests/analysis/reconciliation.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { reconcile } from '../../src/analysis/reconciliation.js';
+import type { Transaction } from '../../src/types.js';
+
+function makeTransaction(
+  id: string,
+  date: string,
+  amount: number,
+  description: string,
+  provider: 'stripe' | 'xero'
+): Transaction {
+  return {
+    id,
+    date,
+    amount,
+    currency: 'usd',
+    description,
+    type: 'income',
+    provider,
+  };
+}
+
+describe('reconcile', () => {
+  it('matches transactions with same amount, close date, and similar description', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme Corp', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T14:00:00Z', 5000, 'Payment Acme Corp', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(1);
+    expect(result.matched[0].stripe.id).toBe('s1');
+    expect(result.matched[0].xero.id).toBe('x1');
+    expect(result.unmatched_stripe).toHaveLength(0);
+    expect(result.unmatched_xero).toHaveLength(0);
+  });
+
+  it('HARD GATE: does NOT match transactions with same amount but completely unrelated descriptions', () => {
+    // Critical Fix 4: same amount within 2 days but different descriptions = no match
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'AWS hosting fee', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-02T10:00:00Z', 5000, 'Employee lunch reimbursement', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(1);
+    expect(result.unmatched_xero).toHaveLength(1);
+  });
+
+  it('does NOT match transactions with different amounts', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T10:00:00Z', 5100, 'Payment Acme', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+  });
+
+  it('does NOT match transactions outside 2-day date tolerance', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-05T10:00:00Z', 5000, 'Payment Acme Corp', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(1);
+  });
+
+  it('returns correct summary counts', () => {
+    const stripe = [
+      makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+      makeTransaction('s2', '2026-03-02T10:00:00Z', 9900, 'Subscription renewal', 'stripe'),
+    ];
+    const xero = [
+      makeTransaction('x1', '2026-03-01T14:00:00Z', 5000, 'Payment Acme Corp', 'xero'),
+      makeTransaction('x2', '2026-03-10T10:00:00Z', 9900, 'Completely different thing', 'xero'),
+    ];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.summary.total_stripe).toBe(2);
+    expect(result.summary.total_xero).toBe(2);
+    expect(result.summary.matched_count).toBe(1);
+    expect(result.summary.unmatched_stripe_count).toBe(1);
+    expect(result.summary.unmatched_xero_count).toBe(1);
+  });
+
+  it('confidence score is between 0 and 1', () => {
+    const stripe = [makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme', 'stripe')];
+    const xero = [makeTransaction('x1', '2026-03-01T10:00:00Z', 5000, 'Payment from Acme', 'xero')];
+
+    const result = reconcile(stripe, xero);
+
+    expect(result.matched[0].confidence).toBeGreaterThanOrEqual(0);
+    expect(result.matched[0].confidence).toBeLessThanOrEqual(1);
+  });
+
+  it('handles empty inputs gracefully', () => {
+    const result = reconcile([], []);
+
+    expect(result.matched).toHaveLength(0);
+    expect(result.unmatched_stripe).toHaveLength(0);
+    expect(result.unmatched_xero).toHaveLength(0);
+    expect(result.summary.matched_count).toBe(0);
+  });
+
+  it('does not double-match the same xero transaction', () => {
+    const stripe = [
+      makeTransaction('s1', '2026-03-01T10:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+      makeTransaction('s2', '2026-03-01T11:00:00Z', 5000, 'Payment Acme Corp', 'stripe'),
+    ];
+    const xero = [
+      makeTransaction('x1', '2026-03-01T12:00:00Z', 5000, 'Payment Acme Corp', 'xero'),
+    ];
+
+    const result = reconcile(stripe, xero);
+
+    // Only one match possible (xero transaction used only once)
+    expect(result.matched).toHaveLength(1);
+    expect(result.unmatched_stripe).toHaveLength(1);
+  });
+});

package/tests/analysis/tax.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { calculateTax } from '../../src/analysis/tax.js';
+import type { Transaction } from '../../src/types.js';
+
+function makeIncome(id: string, amount: number, metadata?: Record<string, string>): Transaction {
+  return {
+    id,
+    date: '2026-03-01T00:00:00Z',
+    amount,
+    currency: 'usd',
+    description: `Sale ${id}`,
+    type: 'income',
+    provider: 'stripe',
+    metadata,
+  };
+}
+
+function makeExpense(id: string, amount: number): Transaction {
+  return {
+    id,
+    date: '2026-03-01T00:00:00Z',
+    amount,
+    currency: 'usd',
+    description: `Expense ${id}`,
+    type: 'expense',
+    provider: 'stripe',
+  };
+}
+
+describe('calculateTax — edge cases', () => {
+  it('zero revenue returns all zeros', () => {
+    const result = calculateTax([], 'quarter');
+
+    expect(result.total_taxable_amount).toBe(0);
+    expect(result.total_tax_collected).toBe(0);
+    expect(result.total_tax_owed).toBe(0);
+    expect(result.by_rate).toHaveLength(0);
+  });
+
+  it('only expense transactions return zeros', () => {
+    const transactions = [makeExpense('e1', 50000), makeExpense('e2', 30000)];
+    const result = calculateTax(transactions, 'quarter');
+
+    expect(result.total_taxable_amount).toBe(0);
+    expect(result.total_tax_collected).toBe(0);
+  });
+
+  it('transfer transactions do not count as taxable', () => {
+    const transactions: Transaction[] = [
+      { id: 't1', date: '2026-03-01', amount: 100000, currency: 'usd', description: 'Internal transfer', type: 'transfer', provider: 'stripe' },
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    expect(result.total_taxable_amount).toBe(0);
+  });
+
+  it('multiple jurisdictions: NL, DE, GB produce different tax amounts', () => {
+    const transactions = [makeIncome('t1', 12000)];
+
+    const nlResult = calculateTax(transactions, 'quarter', 'NL');
+    const deResult = calculateTax(transactions, 'quarter', 'DE');
+    const gbResult = calculateTax(transactions, 'quarter', 'GB');
+
+    // All should be different due to different standard rates
+    expect(nlResult.total_tax_collected).not.toEqual(deResult.total_tax_collected);
+    // GB and DEFAULT are both 20%, so they should be equal
+    expect(gbResult.total_tax_collected).toBeCloseTo(20.00, 1);
+  });
+
+  it('US jurisdiction uses 8% standard rate', () => {
+    const transactions = [makeIncome('t1', 10800)];
+    const result = calculateTax(transactions, 'quarter', 'US');
+
+    expect(result.jurisdiction).toBe('US');
+    // 10800 / 1.08 = 10000 taxable, 800 tax = $8
+    expect(result.total_tax_collected).toBeCloseTo(8.00, 1);
+  });
+
+  it('EU jurisdiction uses 21% standard rate', () => {
+    const transactions = [makeIncome('t1', 12100)];
+    const result = calculateTax(transactions, 'quarter', 'EU');
+
+    expect(result.jurisdiction).toBe('EU');
+    expect(result.total_tax_collected).toBeCloseTo(21.00, 1);
+  });
+
+  it('tax calculation is cumulative across multiple transactions', () => {
+    const transactions = [
+      makeIncome('t1', 12000),
+      makeIncome('t2', 12000),
+      makeIncome('t3', 12000),
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    // Each transaction: $120 inclusive at 20% → $100 taxable, $20 tax
+    // Total: 3 × $20 = $60 tax
+    expect(result.total_tax_collected).toBeCloseTo(60.00, 1);
+  });
+
+  it('jurisdiction key is case-insensitive (nl = NL)', () => {
+    const transactions = [makeIncome('t1', 12100)];
+
+    const upperResult = calculateTax(transactions, 'quarter', 'NL');
+    const lowerResult = calculateTax(transactions, 'quarter', 'nl');
+
+    expect(upperResult.jurisdiction).toBe('NL');
+    expect(lowerResult.jurisdiction).toBe('NL');
+    expect(upperResult.total_tax_collected).toBeCloseTo(lowerResult.total_tax_collected, 2);
+  });
+
+  it('mixed income and expense: only income is taxable', () => {
+    const transactions = [
+      makeIncome('t1', 12000),
+      makeExpense('e1', 5000),
+      makeIncome('t2', 12000),
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    // Only 2 income transactions at $120 each → $40 total tax (2 × $20)
+    expect(result.total_tax_collected).toBeCloseTo(40.00, 1);
+  });
+
+  it('tax metadata: custom rate overrides standard rate', () => {
+    const transactions = [
+      makeIncome('t1', 10000, { tax_rate: '0.05' }),  // 5% rate
+    ];
+
+    const result = calculateTax(transactions, 'quarter');
+    const rate5Entry = result.by_rate.find((r) => r.rate === 0.05);
+    expect(rate5Entry).toBeDefined();
+  });
+
+  it('filing_period for quarter matches current year', () => {
+    const result = calculateTax([], 'quarter');
+    const currentYear = new Date().getFullYear().toString();
+    expect(result.filing_period).toContain(currentYear);
+  });
+
+  it('filing_period for year equals current year string', () => {
+    const result = calculateTax([], 'year');
+    const currentYear = new Date().getFullYear().toString();
+    expect(result.filing_period).toBe(currentYear);
+  });
+
+  it('by_rate entries have rate_label: Exempt for rate 0', () => {
+    const transactions = [makeIncome('t1', 10000, { tax_rate: '0' })];
+    const result = calculateTax(transactions, 'quarter');
+
+    const exemptEntry = result.by_rate.find((r) => r.rate === 0);
+    expect(exemptEntry).toBeDefined();
+    expect(exemptEntry!.rate_label).toBe('Exempt');
+  });
+
+  it('by_rate entries have formatted rate_label for non-zero rates', () => {
+    const transactions = [makeIncome('t1', 12000)];
+    const result = calculateTax(transactions, 'quarter');  // Default 20%
+
+    const vatEntry = result.by_rate.find((r) => r.rate === 0.2);
+    expect(vatEntry).toBeDefined();
+    expect(vatEntry!.rate_label).toContain('VAT');
+    expect(vatEntry!.rate_label).toContain('20');
+  });
+});