jaz-cli 2.6.0 → 2.8.0

package/dist/__tests__/jobs-supplier-recon.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { generateSupplierReconBlueprint } from '../jobs/supplier-recon.js';
+describe('generateSupplierReconBlueprint (basic)', () => {
+    it('produces a valid JobBlueprint with correct jobType', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.jobType).toBe('supplier-recon');
+    });
+    it('has 4 phases and 7 total steps', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.phases).toHaveLength(4);
+        expect(bp.summary.totalSteps).toBe(7);
+    });
+    it('phase names are correct', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.phases.map(p => p.name)).toEqual([
+            'Pull AP Data',
+            'Compare Against Supplier Statement',
+            'Resolve Discrepancies',
+            'Verification',
+        ]);
+    });
+    it('step categories match expectations', () => {
+        const bp = generateSupplierReconBlueprint();
+        const categories = bp.phases.flatMap(p => p.steps.map(s => s.category));
+        expect(categories).toEqual([
+            'report', // 1 — AP aging report
+            'verify', // 2 — list bills for supplier
+            'verify', // 3 — match against statement
+            'review', // 4 — identify mismatches
+            'resolve', // 5 — create missing bills
+            'adjust', // 6 — record adjustments
+            'verify', // 7 — re-check AP aging
+        ]);
+    });
+    it('summary has non-empty apiCalls', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.apiCalls.length).toBeGreaterThan(0);
+    });
+    it('mode is standalone', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.mode).toBe('standalone');
+    });
+});
+describe('generateSupplierReconBlueprint (defaults)', () => {
+    it('default currency is SGD', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.currency).toBe('SGD');
+    });
+    it('default period is current', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.period).toBe('current');
+    });
+});
+describe('generateSupplierReconBlueprint (options)', () => {
+    it('custom currency works', () => {
+        const bp = generateSupplierReconBlueprint({ currency: 'PHP' });
+        expect(bp.currency).toBe('PHP');
+    });
+    it('supplier filter is applied to bills search', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('supplierName', 'Acme Corp');
+    });
+    it('supplier filter absent by default', () => {
+        const bp = generateSupplierReconBlueprint();
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).not.toHaveProperty('supplierName');
+    });
+    it('supplier is reflected in AP aging notes', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const step1 = bp.phases[0].steps[0];
+        expect(step1.notes).toContain('Acme Corp');
+    });
+    it('supplier is reflected in verification notes', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const verifyStep = bp.phases[3].steps[0];
+        expect(verifyStep.notes).toContain('Acme Corp');
+    });
+    it('period filter is applied to bills search with correct end-of-month', () => {
+        const bp = generateSupplierReconBlueprint({ period: '2025-06' });
+        expect(bp.period).toBe('2025-06');
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('dateFrom', '2025-06-01');
+        expect(filters).toHaveProperty('dateTo', '2025-06-30');
+    });
+    it('period filter handles February correctly', () => {
+        const bp = generateSupplierReconBlueprint({ period: '2025-02' });
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('dateTo', '2025-02-28');
+    });
+    it('period filter absent by default', () => {
+        const bp = generateSupplierReconBlueprint();
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).not.toHaveProperty('dateFrom');
+        expect(filters).not.toHaveProperty('dateTo');
+    });
+});
+describe('generateSupplierReconBlueprint (summary)', () => {
+    it('recipeReferences include standard-bill', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.recipeReferences).toContain('standard-bill');
+    });
+    it('apiCalls include key endpoints', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.apiCalls).toContain('POST /generate-reports/ap-aging');
+        expect(bp.summary.apiCalls).toContain('POST /bills/search');
+        expect(bp.summary.apiCalls).toContain('POST /bills');
+        expect(bp.summary.apiCalls).toContain('POST /journals');
+    });
+});

package/dist/__tests__/jobs-validate.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest';
+import { parseMonthPeriod, parseQuarterPeriod, parseYearPeriod, validateDateString, validateOverdueDays, JobValidationError, } from '../jobs/validate.js';
+describe('parseMonthPeriod', () => {
+    it('parses "2025-01" → Jan 2025 with correct dates', () => {
+        const r = parseMonthPeriod('2025-01');
+        expect(r.type).toBe('month');
+        expect(r.year).toBe(2025);
+        expect(r.month).toBe(1);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-01-31');
+        expect(r.label).toBe('Jan 2025');
+    });
+    it('parses "2025-12" → Dec 2025 with correct dates', () => {
+        const r = parseMonthPeriod('2025-12');
+        expect(r.type).toBe('month');
+        expect(r.year).toBe(2025);
+        expect(r.month).toBe(12);
+        expect(r.startDate).toBe('2025-12-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('Dec 2025');
+    });
+    it('handles February in a leap year', () => {
+        const r = parseMonthPeriod('2024-02');
+        expect(r.endDate).toBe('2024-02-29');
+    });
+    it('handles February in a non-leap year', () => {
+        const r = parseMonthPeriod('2025-02');
+        expect(r.endDate).toBe('2025-02-28');
+    });
+    it('rejects month 13 with JobValidationError', () => {
+        expect(() => parseMonthPeriod('2025-13')).toThrow(JobValidationError);
+    });
+    it('rejects non-date string "abc"', () => {
+        expect(() => parseMonthPeriod('abc')).toThrow(JobValidationError);
+    });
+    it('rejects single-digit month "2025-1"', () => {
+        expect(() => parseMonthPeriod('2025-1')).toThrow(JobValidationError);
+    });
+    it('rejects month 00', () => {
+        expect(() => parseMonthPeriod('2025-00')).toThrow(JobValidationError);
+    });
+});
+describe('parseQuarterPeriod', () => {
+    it('parses "2025-Q1" → Jan-Mar 2025', () => {
+        const r = parseQuarterPeriod('2025-Q1');
+        expect(r.type).toBe('quarter');
+        expect(r.year).toBe(2025);
+        expect(r.quarter).toBe(1);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-03-31');
+        expect(r.label).toBe('Q1 2025');
+        expect(r.months).toHaveLength(3);
+        expect(r.months[0].month).toBe(1);
+        expect(r.months[1].month).toBe(2);
+        expect(r.months[2].month).toBe(3);
+    });
+    it('parses "2025-Q4" → Oct-Dec 2025', () => {
+        const r = parseQuarterPeriod('2025-Q4');
+        expect(r.type).toBe('quarter');
+        expect(r.year).toBe(2025);
+        expect(r.quarter).toBe(4);
+        expect(r.startDate).toBe('2025-10-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('Q4 2025');
+        expect(r.months).toHaveLength(3);
+        expect(r.months[0].month).toBe(10);
+        expect(r.months[1].month).toBe(11);
+        expect(r.months[2].month).toBe(12);
+    });
+    it('parses "2025-Q2" → Apr-Jun 2025', () => {
+        const r = parseQuarterPeriod('2025-Q2');
+        expect(r.startDate).toBe('2025-04-01');
+        expect(r.endDate).toBe('2025-06-30');
+    });
+    it('is case-insensitive for the Q prefix', () => {
+        const r = parseQuarterPeriod('2025-q3');
+        expect(r.quarter).toBe(3);
+        expect(r.startDate).toBe('2025-07-01');
+    });
+    it('rejects Q5 with JobValidationError', () => {
+        expect(() => parseQuarterPeriod('2025-Q5')).toThrow(JobValidationError);
+    });
+    it('rejects Q0 with JobValidationError', () => {
+        expect(() => parseQuarterPeriod('2025-q0')).toThrow(JobValidationError);
+    });
+    it('rejects invalid format "2025Q1"', () => {
+        expect(() => parseQuarterPeriod('2025Q1')).toThrow(JobValidationError);
+    });
+    it('each month in the quarter has correct start and end dates', () => {
+        const r = parseQuarterPeriod('2025-Q1');
+        expect(r.months[0].startDate).toBe('2025-01-01');
+        expect(r.months[0].endDate).toBe('2025-01-31');
+        expect(r.months[1].startDate).toBe('2025-02-01');
+        expect(r.months[1].endDate).toBe('2025-02-28');
+        expect(r.months[2].startDate).toBe('2025-03-01');
+        expect(r.months[2].endDate).toBe('2025-03-31');
+    });
+});
+describe('parseYearPeriod', () => {
+    it('parses "2025" → full year Jan-Dec with 4 quarters', () => {
+        const r = parseYearPeriod('2025');
+        expect(r.type).toBe('year');
+        expect(r.year).toBe(2025);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('FY2025');
+        expect(r.quarters).toHaveLength(4);
+    });
+    it('quarters span the correct months', () => {
+        const r = parseYearPeriod('2025');
+        expect(r.quarters[0].startDate).toBe('2025-01-01');
+        expect(r.quarters[0].endDate).toBe('2025-03-31');
+        expect(r.quarters[1].startDate).toBe('2025-04-01');
+        expect(r.quarters[1].endDate).toBe('2025-06-30');
+        expect(r.quarters[2].startDate).toBe('2025-07-01');
+        expect(r.quarters[2].endDate).toBe('2025-09-30');
+        expect(r.quarters[3].startDate).toBe('2025-10-01');
+        expect(r.quarters[3].endDate).toBe('2025-12-31');
+    });
+    it('each quarter has 3 months', () => {
+        const r = parseYearPeriod('2025');
+        for (const q of r.quarters) {
+            expect(q.months).toHaveLength(3);
+        }
+    });
+    it('rejects non-numeric string "abcd"', () => {
+        expect(() => parseYearPeriod('abcd')).toThrow(JobValidationError);
+    });
+    it('rejects partial year "25"', () => {
+        expect(() => parseYearPeriod('25')).toThrow(JobValidationError);
+    });
+    it('rejects YYYY-MM format "2025-01"', () => {
+        expect(() => parseYearPeriod('2025-01')).toThrow(JobValidationError);
+    });
+});
+describe('validateDateString', () => {
+    it('accepts a valid date "2025-06-15"', () => {
+        expect(() => validateDateString('2025-06-15', 'testDate')).not.toThrow();
+    });
+    it('accepts undefined (optional field)', () => {
+        expect(() => validateDateString(undefined, 'testDate')).not.toThrow();
+    });
+    it('rejects "not-a-date"', () => {
+        expect(() => validateDateString('not-a-date', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects invalid month "2025-13-01"', () => {
+        expect(() => validateDateString('2025-13-01', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects impossible calendar date "2025-02-31"', () => {
+        expect(() => validateDateString('2025-02-31', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects impossible calendar date "2025-06-31"', () => {
+        expect(() => validateDateString('2025-06-31', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects wrong format "06/15/2025"', () => {
+        expect(() => validateDateString('06/15/2025', 'testDate')).toThrow(JobValidationError);
+    });
+    it('error message includes the field name', () => {
+        expect(() => validateDateString('bad', 'myField')).toThrow(/myField/);
+    });
+});
+describe('validateOverdueDays', () => {
+    it('accepts a valid positive integer 30', () => {
+        expect(() => validateOverdueDays(30)).not.toThrow();
+    });
+    it('accepts 1 (minimum valid)', () => {
+        expect(() => validateOverdueDays(1)).not.toThrow();
+    });
+    it('rejects 0', () => {
+        expect(() => validateOverdueDays(0)).toThrow(JobValidationError);
+    });
+    it('rejects negative values', () => {
+        expect(() => validateOverdueDays(-1)).toThrow(JobValidationError);
+    });
+    it('rejects non-integer 1.5', () => {
+        expect(() => validateOverdueDays(1.5)).toThrow(JobValidationError);
+    });
+    it('rejects non-integer 0.5', () => {
+        expect(() => validateOverdueDays(0.5)).toThrow(JobValidationError);
+    });
+});

package/dist/__tests__/jobs-year-end.test.js

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { generateYearEndBlueprint } from '../jobs/year-end.js';
+import { JobValidationError } from '../jobs/validate.js';
+describe('generateYearEndBlueprint', () => {
+    // Standalone mode (default)
+    describe('standalone mode', () => {
+        const base = { period: '2025' };
+        it('includes all quarterly phases plus annual extras and verification', () => {
+            const r = generateYearEndBlueprint(base);
+            // 4 quarters x 17 phases each (15 month-end + 2 quarterly) = 68
+            // + Phase 8 (annual extras) + Phase 9 (annual verification) = 70
+            expect(r.phases.length).toBeGreaterThan(0);
+            // Last two phases are annual extras and verification
+            const last = r.phases[r.phases.length - 1];
+            const secondLast = r.phases[r.phases.length - 2];
+            expect(secondLast.name).toBe('Phase 8: Annual Extras');
+            expect(last.name).toBe('Phase 9: Annual Verification');
+        });
+        it('has correct jobType', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.jobType).toBe('year-end-close');
+        });
+        it('mode is standalone', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.mode).toBe('standalone');
+        });
+        it('period label is "FY2025"', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.period).toBe('FY2025');
+        });
+        it('currency defaults to "SGD"', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.currency).toBe('SGD');
+        });
+        it('phase names are prefixed with quarter labels', () => {
+            const r = generateYearEndBlueprint(base);
+            // First batch of phases should contain Q1 prefix
+            expect(r.phases[0].name).toContain('Q1 2025');
+        });
+        it('annual extras has 7 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            expect(extras.name).toBe('Phase 8: Annual Extras');
+            expect(extras.steps).toHaveLength(7);
+        });
+        it('annual verification has 3 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            const verification = r.phases[r.phases.length - 1];
+            expect(verification.name).toBe('Phase 9: Annual Verification');
+            expect(verification.steps).toHaveLength(3);
+        });
+        it('annual extras ordering continues from last quarterly max order', () => {
+            const r = generateYearEndBlueprint(base);
+            // Each quarter ends with quarterly verification at order 26
+            // Annual extras starts at 27
+            const extras = r.phases[r.phases.length - 2];
+            expect(extras.steps[0].order).toBe(27);
+        });
+        it('annual verification follows annual extras ordering', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            const verification = r.phases[r.phases.length - 1];
+            const lastExtraOrder = extras.steps[extras.steps.length - 1].order;
+            expect(verification.steps[0].order).toBe(lastExtraOrder + 1);
+        });
+        it('summary totalSteps matches actual step count', () => {
+            const r = generateYearEndBlueprint(base);
+            const actual = r.phases.reduce((sum, p) => sum + p.steps.length, 0);
+            expect(r.summary.totalSteps).toBe(actual);
+        });
+        it('summary includes recipe references from monthly, quarterly, and annual steps', () => {
+            const r = generateYearEndBlueprint(base);
+            // Monthly recipe
+            expect(r.summary.recipeReferences).toContain('accrued-expenses');
+            // Quarterly recipe
+            expect(r.summary.recipeReferences).toContain('intercompany');
+            // Annual recipe
+            expect(r.summary.recipeReferences).toContain('dividend');
+        });
+        it('summary recipe references are sorted', () => {
+            const r = generateYearEndBlueprint(base);
+            const sorted = [...r.summary.recipeReferences].sort();
+            expect(r.summary.recipeReferences).toEqual(sorted);
+        });
+        it('annual extras API calls use full year dates', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            const gstStep = extras.steps.find(s => s.description.includes('GST'));
+            expect(gstStep).toBeDefined();
+            expect(gstStep.apiBody.startDate).toBe('2025-01-01');
+            expect(gstStep.apiBody.endDate).toBe('2025-12-31');
+        });
+        it('annual verification reports use full year dates', () => {
+            const r = generateYearEndBlueprint(base);
+            const verification = r.phases[r.phases.length - 1];
+            const trialBalance = verification.steps[0];
+            expect(trialBalance.apiBody.startDate).toBe('2025-01-01');
+            expect(trialBalance.apiBody.endDate).toBe('2025-12-31');
+        });
+    });
+    // Incremental mode
+    describe('incremental mode', () => {
+        const base = { period: '2025', incremental: true };
+        it('has only annual extras and verification (no quarter/month phases)', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases).toHaveLength(2);
+            expect(r.phases[0].name).toBe('Phase 8: Annual Extras');
+            expect(r.phases[1].name).toBe('Phase 9: Annual Verification');
+        });
+        it('mode is incremental', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.mode).toBe('incremental');
+        });
+        it('step ordering starts at 1 for extras', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases[0].steps[0].order).toBe(1);
+        });
+        it('step ordering is continuous across extras and verification', () => {
+            const r = generateYearEndBlueprint(base);
+            const allOrders = r.phases.flatMap(p => p.steps.map(s => s.order));
+            for (let i = 0; i < allOrders.length; i++) {
+                expect(allOrders[i]).toBe(i + 1);
+            }
+        });
+        it('total steps = 7 extras + 3 verification = 10', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.summary.totalSteps).toBe(10);
+        });
+        it('annual extras has 7 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases[0].steps).toHaveLength(7);
+        });
+    });
+    // Custom currency
+    it('custom currency "MYR" passes through', () => {
+        const r = generateYearEndBlueprint({ period: '2025', currency: 'MYR' });
+        expect(r.currency).toBe('MYR');
+    });
+    // Validation
+    it('invalid period throws JobValidationError', () => {
+        expect(() => generateYearEndBlueprint({ period: 'bad' })).toThrow(JobValidationError);
+    });
+    it('"2025-Q1" is not a valid year period', () => {
+        expect(() => generateYearEndBlueprint({ period: '2025-Q1' })).toThrow(JobValidationError);
+    });
+    it('"abcd" throws JobValidationError', () => {
+        expect(() => generateYearEndBlueprint({ period: 'abcd' })).toThrow(JobValidationError);
+    });
+});

package/dist/__tests__/lease.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { calculateLease } from '../calc/lease.js';
+import { CalcValidationError } from '../calc/validate.js';
+describe('calculateLease (standard)', () => {
+    const base = { monthlyPayment: 5000, termMonths: 36, annualRate: 5 };
+    it('produces correct schedule length', () => {
+        const r = calculateLease(base);
+        expect(r.schedule).toHaveLength(36);
+    });
+    it('final closing balance is exactly zero', () => {
+        const r = calculateLease(base);
+        expect(r.schedule[r.schedule.length - 1].closingBalance).toBe(0);
+    });
+    it('PV is less than total cash payments', () => {
+        const r = calculateLease(base);
+        expect(r.presentValue).toBeLessThan(r.totalCashPayments);
+    });
+    it('ROU depreciation = PV / term', () => {
+        const r = calculateLease(base);
+        const expected = Math.round(r.presentValue / 36 * 100) / 100;
+        expect(r.monthlyRouDepreciation).toBe(expected);
+    });
+    it('isHirePurchase is false without usefulLifeMonths', () => {
+        const r = calculateLease(base);
+        expect(r.isHirePurchase).toBe(false);
+    });
+    it('opening balance = previous closing balance', () => {
+        const r = calculateLease(base);
+        for (let i = 1; i < r.schedule.length; i++) {
+            expect(r.schedule[i].openingBalance).toBe(r.schedule[i - 1].closingBalance);
+        }
+    });
+    it('every journal entry is balanced', () => {
+        const r = calculateLease(base);
+        for (const row of r.schedule) {
+            const debits = row.journal.lines.reduce((s, l) => s + l.debit, 0);
+            const credits = row.journal.lines.reduce((s, l) => s + l.credit, 0);
+            expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+        }
+    });
+    // Blueprint
+    it('blueprint step 1 = journal (initial recognition)', () => {
+        const r = calculateLease({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps[0].action).toBe('journal');
+    });
+    it('blueprint step 2 = fixed-asset (ROU registration)', () => {
+        const r = calculateLease({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps[1].action).toBe('fixed-asset');
+    });
+    it('blueprint has correct step count (1 recognition + 1 FA + N payments)', () => {
+        const r = calculateLease({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps).toHaveLength(38); // 1 + 1 + 36
+    });
+    it('blueprint null without startDate', () => {
+        const r = calculateLease(base);
+        expect(r.blueprint).toBeNull();
+    });
+    it('capsuleDescription contains IFRS 16', () => {
+        const r = calculateLease({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.capsuleDescription).toContain('IFRS 16');
+    });
+});
+describe('calculateLease (hire purchase)', () => {
+    it('isHirePurchase is true when usefulLifeMonths provided', () => {
+        const r = calculateLease({ monthlyPayment: 5000, termMonths: 36, annualRate: 5, usefulLifeMonths: 60 });
+        expect(r.isHirePurchase).toBe(true);
+    });
+    it('depreciation months = useful life (not term)', () => {
+        const r = calculateLease({ monthlyPayment: 5000, termMonths: 36, annualRate: 5, usefulLifeMonths: 60 });
+        expect(r.depreciationMonths).toBe(60);
+    });
+    it('treats usefulLifeMonths == termMonths as HP', () => {
+        const r = calculateLease({ monthlyPayment: 5000, termMonths: 36, annualRate: 5, usefulLifeMonths: 36 });
+        expect(r.isHirePurchase).toBe(true);
+        expect(r.depreciationMonths).toBe(36);
+    });
+    it('rejects usefulLifeMonths < termMonths', () => {
+        expect(() => calculateLease({
+            monthlyPayment: 5000, termMonths: 36, annualRate: 5, usefulLifeMonths: 24,
+        })).toThrow(CalcValidationError);
+    });
+    it('HP blueprint capsuleType is Hire Purchase', () => {
+        const r = calculateLease({
+            monthlyPayment: 5000, termMonths: 36, annualRate: 5, usefulLifeMonths: 60, startDate: '2025-01-01',
+        });
+        expect(r.blueprint.capsuleType).toBe('Hire Purchase');
+    });
+});
+describe('calculateLease (validation)', () => {
+    it('rejects negative payment', () => {
+        expect(() => calculateLease({ monthlyPayment: -5000, termMonths: 36, annualRate: 5 })).toThrow(CalcValidationError);
+    });
+    it('rejects zero term', () => {
+        expect(() => calculateLease({ monthlyPayment: 5000, termMonths: 0, annualRate: 5 })).toThrow(CalcValidationError);
+    });
+});

package/dist/__tests__/loan.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { calculateLoan } from '../calc/loan.js';
+import { CalcValidationError } from '../calc/validate.js';
+describe('calculateLoan', () => {
+    const base = { principal: 100000, annualRate: 6, termMonths: 12 };
+    it('produces correct schedule length', () => {
+        const r = calculateLoan(base);
+        expect(r.schedule).toHaveLength(12);
+    });
+    it('final closing balance is exactly zero', () => {
+        const r = calculateLoan(base);
+        expect(r.schedule[r.schedule.length - 1].closingBalance).toBe(0);
+    });
+    it('total principal equals loan principal', () => {
+        const r = calculateLoan(base);
+        expect(r.totalPrincipal).toBe(100000);
+    });
+    it('total payments = principal + interest', () => {
+        const r = calculateLoan(base);
+        expect(r.totalPayments).toBe(r.totalPrincipal + r.totalInterest);
+    });
+    it('opening balance = previous closing balance', () => {
+        const r = calculateLoan({ ...base, termMonths: 60 });
+        for (let i = 1; i < r.schedule.length; i++) {
+            expect(r.schedule[i].openingBalance).toBe(r.schedule[i - 1].closingBalance);
+        }
+    });
+    it('every journal entry is balanced (debits = credits)', () => {
+        const r = calculateLoan({ ...base, termMonths: 60 });
+        for (const row of r.schedule) {
+            const debits = row.journal.lines.reduce((s, l) => s + l.debit, 0);
+            const credits = row.journal.lines.reduce((s, l) => s + l.credit, 0);
+            expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+        }
+    });
+    it('all amounts are 2dp (round2 invariant)', () => {
+        const r = calculateLoan(base);
+        const round2 = (n) => Math.round(n * 100) / 100;
+        for (const row of r.schedule) {
+            expect(round2(row.interest)).toBe(row.interest);
+            expect(round2(row.principal)).toBe(row.principal);
+        }
+    });
+    // Blueprint
+    it('blueprint is null when no startDate', () => {
+        const r = calculateLoan(base);
+        expect(r.blueprint).toBeNull();
+    });
+    it('blueprint present when startDate given', () => {
+        const r = calculateLoan({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint).not.toBeNull();
+        expect(r.blueprint.capsuleDescription).toBeTruthy();
+    });
+    it('blueprint step 1 is cash-in (loan disbursement)', () => {
+        const r = calculateLoan({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps[0].action).toBe('cash-in');
+    });
+    it('blueprint has correct step count (1 disbursement + N payments)', () => {
+        const r = calculateLoan({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps).toHaveLength(13); // 1 + 12
+    });
+    it('currency passes through to result', () => {
+        const r = calculateLoan({ ...base, currency: 'SGD' });
+        expect(r.currency).toBe('SGD');
+    });
+    it('currency null when not provided', () => {
+        const r = calculateLoan(base);
+        expect(r.currency).toBeNull();
+    });
+    // Validation
+    it('rejects negative principal', () => {
+        expect(() => calculateLoan({ ...base, principal: -100 })).toThrow(CalcValidationError);
+    });
+    it('rejects zero term', () => {
+        expect(() => calculateLoan({ ...base, termMonths: 0 })).toThrow(CalcValidationError);
+    });
+    it('rejects invalid date format', () => {
+        expect(() => calculateLoan({ ...base, startDate: '01-01-2025' })).toThrow(CalcValidationError);
+    });
+});