jaz-cli 2.3.0 → 2.6.0

package/dist/calc/lease.js

@@ -0,0 +1,146 @@
+/**
+ * IFRS 16 lease calculator.
+ *
+ * Compliance references:
+ *  - IFRS 16.26: Initial measurement — PV of lease payments
+ *  - IFRS 16.36-37: Subsequent measurement — effective interest method
+ *  - IFRS 16.31-32: ROU depreciation — straight-line over lease term
+ *
+ * Uses `financial` package for PV calculation.
+ * Final period penny adjustment closes lease liability to exactly zero.
+ */
+import { pv } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, fixedAssetStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+export function calculateLease(inputs) {
+    const { monthlyPayment, termMonths, annualRate, usefulLifeMonths, startDate, currency } = inputs;
+    validatePositive(monthlyPayment, 'Monthly payment');
+    validateRate(annualRate, 'Annual rate (IBR)');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    if (usefulLifeMonths !== undefined)
+        validatePositiveInteger(usefulLifeMonths, 'Useful life (months)');
+    validateDateFormat(startDate);
+    const isHirePurchase = usefulLifeMonths !== undefined && usefulLifeMonths > termMonths;
+    const monthlyRate = annualRate / 100 / 12;
+    // PV of an ordinary annuity (payments at end of period)
+    // pv() returns negative, negate for positive value
+    const presentValue = round2(-pv(monthlyRate, termMonths, monthlyPayment));
+    // ROU depreciation: straight-line over lease term (IFRS 16.31-32)
+    // For hire purchase (ownership transfers): depreciate over useful life, not lease term
+    const depreciationMonths = isHirePurchase ? usefulLifeMonths : termMonths;
+    const monthlyRouDepreciation = round2(presentValue / depreciationMonths);
+    const initialJournal = {
+        description: 'Initial recognition — IFRS 16 lease',
+        lines: [
+            { account: 'Right-of-Use Asset', debit: presentValue, credit: 0 },
+            { account: 'Lease Liability', debit: 0, credit: presentValue },
+        ],
+    };
+    // Liability unwinding schedule (effective interest method, IFRS 16.36-37)
+    const schedule = [];
+    let liability = presentValue;
+    let totalInterest = 0;
+    let totalPrincipal = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(liability);
+        const isFinal = i === termMonths;
+        let interest;
+        let principalPortion;
+        let periodPayment;
+        if (isFinal) {
+            // Final period: close liability to exactly zero
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = openingBalance;
+            periodPayment = round2(principalPortion + interest);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = round2(monthlyPayment - interest);
+            periodPayment = monthlyPayment;
+        }
+        liability = round2(openingBalance - principalPortion);
+        totalInterest = round2(totalInterest + interest);
+        totalPrincipal = round2(totalPrincipal + principalPortion);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Lease payment — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Lease Liability', debit: principalPortion, credit: 0 },
+                { account: 'Interest Expense — Leases', debit: interest, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: periodPayment },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: periodPayment,
+            interest,
+            principal: principalPortion,
+            closingBalance: liability,
+            journal,
+        });
+    }
+    // ROU depreciation total (final month absorbs rounding)
+    const totalDepreciation = round2(monthlyRouDepreciation * (termMonths - 1) +
+        (presentValue - monthlyRouDepreciation * (termMonths - 1)));
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const depNote = isHirePurchase
+            ? `Register Right-of-Use Asset in Fixed Asset register: cost ${presentValue}, salvage 0, life ${depreciationMonths} months (straight-line over useful life, not lease term). Jaz will auto-post monthly depreciation of ${monthlyRouDepreciation}.`
+            : `Register Right-of-Use Asset in Fixed Asset register: cost ${presentValue}, salvage 0, life ${termMonths} months (straight-line). Jaz will auto-post monthly depreciation of ${monthlyRouDepreciation}.`;
+        const steps = [
+            journalStep(1, initialJournal.description, startDate, initialJournal.lines),
+            fixedAssetStep(2, depNote, startDate),
+            ...schedule.map((row, idx) => journalStep(idx + 3, row.journal.description, row.date, row.journal.lines)),
+        ];
+        const capsuleType = isHirePurchase ? 'Hire Purchase' : 'Lease Accounting';
+        const capsuleName = isHirePurchase
+            ? `Hire Purchase — ${fmtCapsuleAmount(monthlyPayment, currency)}/month — ${termMonths} months — useful life ${depreciationMonths} months`
+            : `IFRS 16 Lease — ${fmtCapsuleAmount(monthlyPayment, currency)}/month — ${termMonths} months`;
+        const c = currency ?? undefined;
+        const workingsLines = [
+            `${isHirePurchase ? 'Hire Purchase' : 'IFRS 16 Lease'} Workings`,
+            `Monthly payment: ${fmtAmt(monthlyPayment, c)} | IBR: ${annualRate}% p.a. (${round2(monthlyRate * 100)}% monthly)`,
+            `Lease term: ${termMonths} months | PV of payments: ${fmtAmt(presentValue, c)} (IFRS 16.26)`,
+        ];
+        if (isHirePurchase) {
+            workingsLines.push(`Useful life: ${usefulLifeMonths} months | ROU depreciation: ${fmtAmt(monthlyRouDepreciation, c)}/month over ${depreciationMonths} months`);
+        }
+        else {
+            workingsLines.push(`ROU depreciation: ${fmtAmt(monthlyRouDepreciation, c)}/month (SL over ${termMonths} months)`);
+        }
+        workingsLines.push(`Total cash payments: ${fmtAmt(round2(totalInterest + totalPrincipal), c)} | Total interest: ${fmtAmt(totalInterest, c)}`, `Method: Effective interest (IFRS 16.36-37), ROU straight-line (IFRS 16.31-32)`, `Rounding: 2dp per period, final period closes liability to $0.00`);
+        blueprint = {
+            capsuleType,
+            capsuleName,
+            capsuleDescription: workingsLines.join('\n'),
+            tags: [capsuleType],
+            customFields: isHirePurchase ? { 'HP Agreement #': null } : { 'Lease Contract #': null },
+            steps,
+        };
+    }
+    return {
+        type: 'lease',
+        currency: currency ?? null,
+        inputs: {
+            monthlyPayment,
+            termMonths,
+            annualRate,
+            usefulLifeMonths: usefulLifeMonths ?? null,
+            startDate: startDate ?? null,
+        },
+        presentValue,
+        monthlyRouDepreciation,
+        depreciationMonths,
+        isHirePurchase,
+        totalCashPayments: round2(totalInterest + totalPrincipal),
+        totalInterest,
+        totalDepreciation,
+        initialJournal,
+        schedule,
+        blueprint,
+    };
+}

package/dist/calc/loan.js

@@ -0,0 +1,107 @@
+/**
+ * Loan amortization calculator.
+ * Uses the `financial` package for PMT calculation.
+ * IFRS-compliant rounding: 2 decimals per period, final period closes to zero.
+ */
+import { pmt } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, cashInStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+export function calculateLoan(inputs) {
+    const { principal, annualRate, termMonths, startDate, currency } = inputs;
+    validatePositive(principal, 'Principal');
+    validateRate(annualRate, 'Annual rate');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // PMT returns negative (cash outflow convention), negate for positive value
+    const payment = round2(-pmt(monthlyRate, termMonths, principal));
+    const schedule = [];
+    let balance = principal;
+    let totalInterest = 0;
+    let totalPrincipal = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(balance);
+        const isFinal = i === termMonths;
+        let interest;
+        let principalPortion;
+        let periodPayment;
+        if (isFinal) {
+            // Final period: close balance to exactly zero
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = openingBalance;
+            periodPayment = round2(principalPortion + interest);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = round2(payment - interest);
+            periodPayment = payment;
+        }
+        balance = round2(openingBalance - principalPortion);
+        totalInterest = round2(totalInterest + interest);
+        totalPrincipal = round2(totalPrincipal + principalPortion);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Loan payment — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Loan Payable', debit: principalPortion, credit: 0 },
+                { account: 'Interest Expense', debit: interest, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: periodPayment },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: periodPayment,
+            interest,
+            principal: principalPortion,
+            closingBalance: balance,
+            journal,
+        });
+    }
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            cashInStep(1, 'Record loan proceeds received from bank', startDate, [
+                { account: 'Cash / Bank Account', debit: principal, credit: 0 },
+                { account: 'Loan Payable', debit: 0, credit: principal },
+            ]),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+        ];
+        const c = currency ?? undefined;
+        const workings = [
+            `Loan Amortization Workings`,
+            `Principal: ${fmtAmt(principal, c)} | Rate: ${annualRate}% p.a. (${round2(monthlyRate * 100)}% monthly)`,
+            `Term: ${termMonths} months | Monthly payment: ${fmtAmt(payment, c)}`,
+            `Total payments: ${fmtAmt(round2(totalInterest + totalPrincipal), c)} | Total interest: ${fmtAmt(totalInterest, c)}`,
+            `Method: PMT formula, constant payment amortization`,
+            `Rounding: 2dp per period, final period closes balance to $0.00`,
+        ].join('\n');
+        blueprint = {
+            capsuleType: 'Loan Repayment',
+            capsuleName: `Bank Loan — ${fmtCapsuleAmount(principal, currency)} — ${annualRate}% — ${termMonths} months`,
+            capsuleDescription: workings,
+            tags: ['Bank Loan'],
+            customFields: { 'Loan Reference': null },
+            steps,
+        };
+    }
+    return {
+        type: 'loan',
+        currency: currency ?? null,
+        inputs: {
+            principal,
+            annualRate,
+            termMonths,
+            startDate: startDate ?? null,
+        },
+        monthlyPayment: payment,
+        totalPayments: round2(totalInterest + totalPrincipal),
+        totalInterest,
+        totalPrincipal,
+        schedule,
+        blueprint,
+    };
+}

package/dist/calc/provision.js

@@ -0,0 +1,128 @@
+/**
+ * IAS 37 Provision calculator — PV measurement + discount unwinding.
+ *
+ * Calculates the present value of a future obligation and generates
+ * the periodic unwinding schedule (Dr Finance Cost / Cr Provision).
+ *
+ * Compliance references:
+ *  - IAS 37.36: Best estimate of expenditure required to settle
+ *  - IAS 37.45: PV when effect of time value is material
+ *  - IAS 37.60: Unwinding of discount = finance cost
+ *
+ * Uses `financial` package for PV calculation (same as lease calculator).
+ * Final period penny adjustment closes provision to the full nominal amount.
+ *
+ * Use cases:
+ *  - Warranty obligations
+ *  - Legal claims / litigation
+ *  - Decommissioning / restoration
+ *  - Restructuring provisions
+ *  - Onerous contracts
+ */
+import { pv } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, cashOutStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+export function calculateProvision(inputs) {
+    const { amount, annualRate, termMonths, startDate, currency } = inputs;
+    validatePositive(amount, 'Estimated future outflow');
+    validateRate(annualRate, 'Discount rate');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // PV of a single future cash flow (IAS 37.45)
+    // pv(rate, nper, pmt, fv) — pmt=0, fv=amount → returns negative, negate
+    const presentValue = round2(-pv(monthlyRate, termMonths, 0, amount));
+    const totalUnwinding = round2(amount - presentValue);
+    // Initial recognition journal (Dr Expense / Cr Provision at PV)
+    const initialJournal = {
+        description: `Initial provision recognition at PV (IAS 37)`,
+        lines: [
+            { account: 'Provision Expense', debit: presentValue, credit: 0 },
+            { account: 'Provision for Obligations', debit: 0, credit: presentValue },
+        ],
+    };
+    // Unwinding schedule (effective interest method, IAS 37.60)
+    const schedule = [];
+    let provisionBalance = presentValue;
+    let totalInterest = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(provisionBalance);
+        const isFinal = i === termMonths;
+        let interest;
+        if (isFinal) {
+            // Final period: close to nominal amount exactly
+            interest = round2(amount - openingBalance);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+        }
+        provisionBalance = round2(openingBalance + interest);
+        totalInterest = round2(totalInterest + interest);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Provision unwinding — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Finance Cost — Unwinding', debit: interest, credit: 0 },
+                { account: 'Provision for Obligations', debit: 0, credit: interest },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: 0, // no cash movement until settlement
+            interest,
+            principal: 0, // reuse ScheduleRow — principal not applicable
+            closingBalance: provisionBalance,
+            journal,
+        });
+    }
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const settlementDate = addMonths(startDate, termMonths);
+        const steps = [
+            journalStep(1, initialJournal.description, startDate, initialJournal.lines),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+            cashOutStep(termMonths + 2, 'Settlement — pay the obligation', settlementDate, [
+                { account: 'Provision for Obligations', debit: amount, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: amount },
+            ]),
+        ];
+        const c = currency ?? undefined;
+        const workings = [
+            `IAS 37 Provision Workings`,
+            `Nominal obligation: ${fmtAmt(amount, c)} | Discount rate: ${annualRate}% p.a. (${round2(monthlyRate * 100)}% monthly)`,
+            `Term to settlement: ${termMonths} months | PV at recognition: ${fmtAmt(presentValue, c)}`,
+            `Total unwinding (finance cost): ${fmtAmt(totalUnwinding, c)}`,
+            `Method: PV of single future outflow (IAS 37.45), unwinding via effective interest (IAS 37.60)`,
+            `Settlement: ${fmtAmt(amount, c)} cash out on ${settlementDate}`,
+            `Rounding: 2dp per period, final period closes to nominal amount`,
+        ].join('\n');
+        blueprint = {
+            capsuleType: 'Provisions',
+            capsuleName: `Provision — ${fmtCapsuleAmount(amount, currency)} — ${annualRate}% — ${termMonths} months`,
+            capsuleDescription: workings,
+            tags: ['Provision', 'IAS 37'],
+            customFields: { 'Obligation Type': null, 'Expected Settlement Date': null },
+            steps,
+        };
+    }
+    return {
+        type: 'provision',
+        currency: currency ?? null,
+        inputs: {
+            amount,
+            annualRate,
+            termMonths,
+            startDate: startDate ?? null,
+        },
+        presentValue,
+        nominalAmount: amount,
+        totalUnwinding,
+        initialJournal,
+        schedule,
+        blueprint,
+    };
+}

package/dist/calc/types.js

@@ -0,0 +1,21 @@
+/**
+ * Shared types for jaz calc financial calculators.
+ */
+/**
+ * Round to 2 decimal places (cents).
+ *
+ * Uses Math.round() (asymmetric, rounds 0.5 away from zero). This is the
+ * standard JavaScript rounding and works correctly for accounting amounts
+ * up to ~$90 trillion (Number.MAX_SAFE_INTEGER / 100). Final-period
+ * corrections in each calculator absorb any cumulative drift, ensuring
+ * balances always close to exactly $0.00.
+ */
+export function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Advance a date by N months. Returns YYYY-MM-DD string. */
+export function addMonths(dateStr, months) {
+    const d = new Date(dateStr + 'T00:00:00');
+    d.setMonth(d.getMonth() + months);
+    return d.toISOString().slice(0, 10);
+}

package/dist/calc/validate.js

@@ -0,0 +1,48 @@
+/**
+ * Input validation for jaz calc financial calculators.
+ * Throws CalcValidationError with user-friendly messages.
+ */
+export class CalcValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CalcValidationError';
+    }
+}
+export function validatePositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new CalcValidationError(`${name} must be a positive number (got ${value})`);
+    }
+}
+export function validateNonNegative(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new CalcValidationError(`${name} must be zero or positive (got ${value})`);
+    }
+}
+export function validatePositiveInteger(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new CalcValidationError(`${name} must be a positive integer (got ${value})`);
+    }
+}
+export function validateSalvageLessThanCost(salvage, cost) {
+    if (salvage >= cost) {
+        throw new CalcValidationError(`Salvage value (${salvage}) must be less than cost (${cost})`);
+    }
+}
+export function validateDateFormat(date) {
+    if (!date)
+        return;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new CalcValidationError(`Date must be YYYY-MM-DD format (got "${date}")`);
+    }
+    const d = new Date(date + 'T00:00:00');
+    if (isNaN(d.getTime())) {
+        throw new CalcValidationError(`Invalid date: "${date}"`);
+    }
+}
+export function validateRate(rate, name = 'Rate') {
+    validateNonNegative(rate, name);
+    if (rate > 100) {
+        // Warning only — rates >100% are rare but legal (e.g. hyperinflation)
+        process.stderr.write(`Warning: ${name} is ${rate}% — are you sure this isn't a decimal? (e.g. 6 for 6%, not 0.06)\n`);
+    }
+}