@crewhaus/tool-money 0.7.0 → 0.8.1

package/dist/lib/statement.js

@@ -16,6 +16,7 @@
  * Only what the file says is reported. No categorization, no counterparty
  * enrichment, no guessing at what a memo line means.
  */
+import { InexactAmountError } from "./exact";
 export const DATE_ORDERS = ["iso", "dmy", "mdy"];
 export const STATEMENT_FORMATS = ["csv", "ofx"];
 /** RFC 4180 fields: quotes, doubled quotes inside them, embedded newlines. */
@@ -60,7 +61,16 @@ export function parseCsvRows(text) {
     }
     return rows.filter((r) => r.some((f) => f.trim() !== ""));
 }
-/** Parse a money string to minor units, exactly, without floating point. */
+/** The most digits a safe integer has: 2^53 − 1 is 9,007,199,254,740,991. */
+const SAFE_DIGITS = 16;
+/**
+ * Parse a money string to minor units, exactly, without floating point.
+ *
+ * Returns null for text that is not an amount. An amount past 2^53 − 1 minor
+ * units is refused with an {@link InexactAmountError}: a JSON number past
+ * that has already been rounded, and 90,071,992,547,409.93 read as
+ * 9007199254740992 cents is a figure one cent out that nothing flags.
+ */
 export function parseMoneyMinor(raw, decimals, decimalComma) {
     let text = raw.trim();
     if (text === "")
@@ -96,7 +106,15 @@ export function parseMoneyMinor(raw, decimals, decimalComma) {
         return null;
     // Pad or truncate to the currency's exponent rather than rounding a float.
     const scaled = `${whole}${fraction.padEnd(decimals, "0").slice(0, decimals)}`;
-    const value = Number.parseInt(scaled === "" ? "0" : scaled, 10);
+    const digits = scaled.replace(/^0+/, "");
+    // Counted before it is converted: past sixteen digits it cannot fit, and a
+    // megabyte of digits is not worth a bigint to find that out.
+    if (digits.length > SAFE_DIGITS ||
+        (digits.length === SAFE_DIGITS && BigInt(digits) > BigInt(Number.MAX_SAFE_INTEGER))) {
+        const shown = raw.trim().length > 40 ? `${raw.trim().slice(0, 40)}…` : raw.trim();
+        throw new InexactAmountError(`"${shown}" is more than 2^53 − 1 (9007199254740991) minor units, the largest amount this reads exactly, so it is left out rather than rounded`);
+    }
+    const value = digits === "" ? 0 : Number(digits);
     return negative ? -value : value;
 }
 /**
@@ -164,133 +182,214 @@ function findColumn(headers, role, override) {
     const aliases = COLUMN_ALIASES[role] ?? [];
     return headers.findIndex((h) => aliases.includes(h.trim().toLowerCase()));
 }
+/**
+ * The `<STMTTRN>` blocks of an OFX file, in one forward pass over its tags.
+ *
+ * OFX 1.x is SGML, where an end tag may be left out, so a block that is
+ * never closed ends where the next one starts, at the transaction list's
+ * own tags, or at the end of the file — and is read like any other rather
+ * than dropped. (A lazy `<STMTTRN>…</STMTTRN>` match instead rescanned to
+ * the end of the file from every unclosed tag, which was quadratic, and
+ * swallowed the next transaction into an unclosed one.) A stray end tag is
+ * ignored.
+ */
+export function* ofxTransactionBlocks(text) {
+    const tag = /<(\/?)(STMTTRN|BANKTRANLIST)>/gi;
+    let open = -1;
+    for (let m = tag.exec(text); m !== null; m = tag.exec(text)) {
+        const closing = m[1] === "/";
+        const isTransaction = m[2].toUpperCase() === "STMTTRN";
+        // Its own end tag closes a block; any other boundary ends it unclosed.
+        if (open !== -1)
+            yield text.slice(open, m.index);
+        open = -1;
+        if (!closing && isTransaction)
+            open = m.index;
+    }
+    if (open !== -1)
+        yield text.slice(open);
+}
+/** One OFX element's value, e.g. `<TRNAMT>-12.50`. Built once per tag, not once per block. */
+const OFX_FIELDS = Object.fromEntries(["DTPOSTED", "TRNAMT", "NAME", "MEMO", "FITID", "CHECKNUM", "REFNUM"].map((tag) => [
+    tag,
+    new RegExp(`<${tag}>([^<\\r\\n]*)`, "i"),
+]));
+/**
+ * Where a parse keeps what it has read: the lists up to what the caller will
+ * show, the counts and the exact totals for every row.
+ */
+class StatementTally {
+    keepTransactions;
+    keepRejected;
+    transactions = [];
+    rejected = [];
+    count = 0;
+    rejectedCount = 0;
+    total = 0n;
+    debit = 0n;
+    credit = 0n;
+    constructor(keepTransactions, keepRejected) {
+        this.keepTransactions = keepTransactions;
+        this.keepRejected = keepRejected;
+    }
+    add(transaction) {
+        this.count++;
+        const amount = BigInt(transaction.amountMinor);
+        this.total += amount;
+        if (transaction.direction === "debit")
+            this.debit += amount;
+        else
+            this.credit += amount;
+        if (this.transactions.length < this.keepTransactions)
+            this.transactions.push(transaction);
+    }
+    reject(row, reason) {
+        this.rejectedCount++;
+        if (this.rejected.length < this.keepRejected)
+            this.rejected.push({ row, reason });
+    }
+    result(format, dateOrder) {
+        const limit = BigInt(Number.MAX_SAFE_INTEGER);
+        const sums = [
+            ["total", this.total],
+            ["debit total", this.debit],
+            ["credit total", this.credit],
+        ];
+        // Each total is reported when it fits, and left out, by name, when not.
+        const over = sums.filter(([, v]) => v > limit || v < -limit);
+        const fit = (v) => (v > limit || v < -limit ? null : Number(v));
+        return {
+            format,
+            transactions: this.transactions,
+            count: this.count,
+            totalMinor: fit(this.total),
+            debitMinor: fit(this.debit),
+            creditMinor: fit(this.credit),
+            totalsUnavailable: over.length === 0
+                ? null
+                : `the statement's ${over.map(([name, v]) => `${name} comes to ${v}`).join(" and its ")} minor units, past ±2^53 − 1 (9007199254740991), so ${over.length === 1 ? "it is" : "they are"} left out rather than rounded; every transaction's own amount is exact`,
+            dateOrder,
+            rejected: this.rejected,
+            rejectedCount: this.rejectedCount,
+        };
+    }
+}
+/** A money column read for one row: the amount, or why the row is refused. */
+function readMoney(raw, column, decimals, decimalComma) {
+    try {
+        return { value: parseMoneyMinor(raw, decimals, decimalComma) };
+    }
+    catch (err) {
+        if (err instanceof InexactAmountError)
+            return { refused: `the ${column} ${err.message}` };
+        throw err;
+    }
+}
 export function parseStatement(text, options = {}) {
     const format = options.format ?? (/<OFX>|<STMTTRN>/i.test(text) ? "ofx" : "csv");
     const decimals = options.decimals ?? 2;
     const decimalComma = options.decimalComma === true;
-    const rejected = [];
-    const transactions = [];
+    const tally = new StatementTally(options.keep?.transactions ?? Number.POSITIVE_INFINITY, options.keep?.rejected ?? Number.POSITIVE_INFINITY);
     if (format === "ofx") {
         // OFX is SGML with optional closing tags; the transaction blocks are all
         // that matters here and they are regular enough to read directly.
-        const blocks = text.match(/<STMTTRN>[\s\S]*?<\/STMTTRN>/gi) ?? [];
-        const field = (block, tag) => {
-            const m = new RegExp(`<${tag}>([^<\\r\\n]*)`, "i").exec(block);
-            return (m?.[1] ?? "").trim();
-        };
-        for (const [i, block] of blocks.entries()) {
+        const field = (block, tag) => (OFX_FIELDS[tag].exec(block)?.[1] ?? "").trim();
+        let i = -1;
+        for (const block of ofxTransactionBlocks(text)) {
+            i++;
             const date = parseDate(field(block, "DTPOSTED"), "iso");
-            const amount = parseMoneyMinor(field(block, "TRNAMT"), decimals, false);
-            if (date === null || amount === null) {
-                rejected.push({ row: i + 1, reason: "the transaction has no readable date or amount" });
+            const amount = readMoney(field(block, "TRNAMT"), "amount", decimals, false);
+            if ("refused" in amount) {
+                tally.reject(i + 1, amount.refused);
                 continue;
             }
+            if (date === null || amount.value === null) {
+                tally.reject(i + 1, "the transaction has no readable date or amount");
+                continue;
+            }
+            const amountMinor = amount.value;
             const name = field(block, "NAME") || field(block, "MEMO");
-            transactions.push({
+            tally.add({
                 id: field(block, "FITID") || `ofx-${i + 1}`,
                 date,
                 description: name,
-                amountMinor: amount,
-                direction: amount < 0 ? "debit" : "credit",
+                amountMinor,
+                direction: amountMinor < 0 ? "debit" : "credit",
                 reference: field(block, "CHECKNUM") || field(block, "REFNUM"),
                 balanceMinor: null,
             });
         }
+        return tally.result(format, "iso");
+    }
+    const rows = parseCsvRows(text);
+    if (rows.length < 2) {
+        throw new Error("the CSV has no data rows under its header");
+    }
+    const headers = rows[0].map((h) => h.trim());
+    const at = {
+        date: findColumn(headers, "date", options.columns?.date),
+        description: findColumn(headers, "description", options.columns?.description),
+        amount: findColumn(headers, "amount", options.columns?.amount),
+        debit: findColumn(headers, "debit", options.columns?.debit),
+        credit: findColumn(headers, "credit", options.columns?.credit),
+        balance: findColumn(headers, "balance", options.columns?.balance),
+        reference: findColumn(headers, "reference", options.columns?.reference),
+    };
+    if (at.date === -1) {
+        throw new Error(`no date column found; the header is: ${headers.join(", ")}`);
     }
-    else {
-        const rows = parseCsvRows(text);
-        if (rows.length < 2) {
-            throw new Error("the CSV has no data rows under its header");
+    if (at.amount === -1 && at.debit === -1 && at.credit === -1) {
+        throw new Error(`no amount, debit or credit column found; the header is: ${headers.join(", ")}`);
+    }
+    const body = rows.slice(1);
+    const rawDates = body.map((r) => r[at.date] ?? "");
+    let order = options.dateOrder;
+    if (order === undefined) {
+        if (!datesAreUnambiguous(rawDates)) {
+            throw new Error("the dates in this file could be day-first or month-first and the file does not say which; pass dateOrder explicitly rather than have the months guessed at");
         }
-        const headers = rows[0].map((h) => h.trim());
-        const at = {
-            date: findColumn(headers, "date", options.columns?.date),
-            description: findColumn(headers, "description", options.columns?.description),
-            amount: findColumn(headers, "amount", options.columns?.amount),
-            debit: findColumn(headers, "debit", options.columns?.debit),
-            credit: findColumn(headers, "credit", options.columns?.credit),
-            balance: findColumn(headers, "balance", options.columns?.balance),
-            reference: findColumn(headers, "reference", options.columns?.reference),
-        };
-        if (at.date === -1) {
-            throw new Error(`no date column found; the header is: ${headers.join(", ")}`);
+        order = rawDates.some((d) => /^\d{1,2}[/.-]/.test(d.trim())) ? "dmy" : "iso";
+    }
+    const money = (row, column, name) => column === -1 ? { value: null } : readMoney(row[column] ?? "", name, decimals, decimalComma);
+    for (const [i, row] of body.entries()) {
+        const date = parseDate(row[at.date] ?? "", order);
+        if (date === null) {
+            tally.reject(i + 2, `"${row[at.date] ?? ""}" is not a date this can read`);
+            continue;
         }
-        if (at.amount === -1 && at.debit === -1 && at.credit === -1) {
-            throw new Error(`no amount, debit or credit column found; the header is: ${headers.join(", ")}`);
+        const amount = money(row, at.amount, "amount");
+        const debit = money(row, at.debit, "debit");
+        const credit = money(row, at.credit, "credit");
+        const balance = money(row, at.balance, "balance");
+        const refusal = [amount, debit, credit, balance].find((m) => "refused" in m);
+        if (refusal !== undefined && "refused" in refusal) {
+            tally.reject(i + 2, refusal.refused);
+            continue;
         }
-        const body = rows.slice(1);
-        const rawDates = body.map((r) => r[at.date] ?? "");
-        let order = options.dateOrder;
-        if (order === undefined) {
-            if (!datesAreUnambiguous(rawDates)) {
-                throw new Error("the dates in this file could be day-first or month-first and the file does not say which; pass dateOrder explicitly rather than have the months guessed at");
-            }
-            order = rawDates.some((d) => /^\d{1,2}[/.-]/.test(d.trim())) ? "dmy" : "iso";
+        let amountMinor = "value" in amount ? amount.value : null;
+        if (amountMinor === null) {
+            const out = "value" in debit ? debit.value : null;
+            const into = "value" in credit ? credit.value : null;
+            // A debit column holds a positive number meaning money out, so the
+            // sign has to be applied rather than read.
+            if (out !== null && out !== 0)
+                amountMinor = -Math.abs(out);
+            else if (into !== null && into !== 0)
+                amountMinor = Math.abs(into);
         }
-        for (const [i, row] of body.entries()) {
-            const date = parseDate(row[at.date] ?? "", order);
-            if (date === null) {
-                rejected.push({
-                    row: i + 2,
-                    reason: `"${row[at.date] ?? ""}" is not a date this can read`,
-                });
-                continue;
-            }
-            let amountMinor = null;
-            if (at.amount !== -1) {
-                amountMinor = parseMoneyMinor(row[at.amount] ?? "", decimals, decimalComma);
-            }
-            if (amountMinor === null && (at.debit !== -1 || at.credit !== -1)) {
-                const debit = at.debit === -1 ? null : parseMoneyMinor(row[at.debit] ?? "", decimals, decimalComma);
-                const credit = at.credit === -1 ? null : parseMoneyMinor(row[at.credit] ?? "", decimals, decimalComma);
-                // A debit column holds a positive number meaning money out, so the
-                // sign has to be applied rather than read.
-                if (debit !== null && debit !== 0)
-                    amountMinor = -Math.abs(debit);
-                else if (credit !== null && credit !== 0)
-                    amountMinor = Math.abs(credit);
-            }
-            if (amountMinor === null) {
-                rejected.push({ row: i + 2, reason: "no readable amount in this row" });
-                continue;
-            }
-            transactions.push({
-                id: (at.reference !== -1 ? row[at.reference] : "") || `row-${i + 2}`,
-                date,
-                description: (at.description === -1 ? "" : (row[at.description] ?? "")).trim(),
-                amountMinor,
-                direction: amountMinor < 0 ? "debit" : "credit",
-                reference: at.reference === -1 ? "" : (row[at.reference] ?? "").trim(),
-                balanceMinor: at.balance === -1 ? null : parseMoneyMinor(row[at.balance] ?? "", decimals, decimalComma),
-            });
+        if (amountMinor === null) {
+            tally.reject(i + 2, "no readable amount in this row");
+            continue;
         }
-        return {
-            format,
-            transactions,
-            count: transactions.length,
-            totalMinor: transactions.reduce((s, t) => s + t.amountMinor, 0),
-            debitMinor: transactions
-                .filter((t) => t.direction === "debit")
-                .reduce((s, t) => s + t.amountMinor, 0),
-            creditMinor: transactions
-                .filter((t) => t.direction === "credit")
-                .reduce((s, t) => s + t.amountMinor, 0),
-            dateOrder: order,
-            rejected,
-        };
+        tally.add({
+            id: (at.reference !== -1 ? row[at.reference] : "") || `row-${i + 2}`,
+            date,
+            description: (at.description === -1 ? "" : (row[at.description] ?? "")).trim(),
+            amountMinor,
+            direction: amountMinor < 0 ? "debit" : "credit",
+            reference: at.reference === -1 ? "" : (row[at.reference] ?? "").trim(),
+            balanceMinor: "value" in balance ? balance.value : null,
+        });
     }
-    return {
-        format,
-        transactions,
-        count: transactions.length,
-        totalMinor: transactions.reduce((s, t) => s + t.amountMinor, 0),
-        debitMinor: transactions
-            .filter((t) => t.direction === "debit")
-            .reduce((s, t) => s + t.amountMinor, 0),
-        creditMinor: transactions
-            .filter((t) => t.direction === "credit")
-            .reduce((s, t) => s + t.amountMinor, 0),
-        dateOrder: "iso",
-        rejected,
-    };
+    return tally.result(format, order);
 }

package/dist/lib/tax.d.ts

@@ -74,6 +74,12 @@ export type TaxResult = {
     readonly rounding: RoundingMode;
     readonly scope: RoundingScope;
 };
-/** Round a rational to an integer, by the caller's rule. */
+/**
+ * Round a rational to an integer, by the caller's rule, exactly: the
+ * numerator is an amount times a rate in basis points, which passes 2^53 long
+ * before the amount or the answer does.
+ */
+export declare function roundMinorExact(numerator: bigint, denominator: bigint, mode: RoundingMode): bigint;
+/** {@link roundMinorExact} over integer numbers, for callers holding numbers. */
 export declare function roundMinor(numerator: number, denominator: number, mode: RoundingMode): number;
 export declare function calculateTax(lines: ReadonlyArray<TaxLine>, rates: ReadonlyArray<TaxRate>, options?: TaxOptions): TaxResult;

package/dist/lib/tax.js

@@ -11,16 +11,21 @@
  * happens per line or once per invoice. Jurisdictions differ, the totals
  * differ, and a tool that picked one silently would be wrong half the time.
  */
+import { big, mathRound, toNumber } from "./exact";
 export const ROUNDING_MODES = ["half-up", "half-even", "down", "up"];
 export const ROUNDING_SCOPES = ["line", "invoice"];
-/** Round a rational to an integer, by the caller's rule. */
-export function roundMinor(numerator, denominator, mode) {
-    if (denominator === 0)
+/**
+ * Round a rational to an integer, by the caller's rule, exactly: the
+ * numerator is an amount times a rate in basis points, which passes 2^53 long
+ * before the amount or the answer does.
+ */
+export function roundMinorExact(numerator, denominator, mode) {
+    if (denominator === 0n)
         throw new Error("denominator must not be zero");
-    const negative = numerator < 0 !== denominator < 0;
-    const n = Math.abs(numerator);
-    const d = Math.abs(denominator);
-    const whole = Math.floor(n / d);
+    const negative = numerator < 0n !== denominator < 0n;
+    const n = numerator < 0n ? -numerator : numerator;
+    const d = denominator < 0n ? -denominator : denominator;
+    const whole = n / d;
     const remainder = n - whole * d;
     let result;
     switch (mode) {
@@ -28,26 +33,30 @@ export function roundMinor(numerator, denominator, mode) {
             result = whole;
             break;
         case "up":
-            result = remainder > 0 ? whole + 1 : whole;
+            result = remainder > 0n ? whole + 1n : whole;
             break;
         case "half-even": {
-            const twice = remainder * 2;
+            const twice = remainder * 2n;
             if (twice > d)
-                result = whole + 1;
+                result = whole + 1n;
             else if (twice < d)
                 result = whole;
             // Exactly half: go to the even neighbour. Over many lines this is what
             // keeps a total from drifting upward the way half-up does.
             else
-                result = whole % 2 === 0 ? whole : whole + 1;
+                result = whole % 2n === 0n ? whole : whole + 1n;
             break;
         }
         default:
-            result = remainder * 2 >= d ? whole + 1 : whole;
+            result = remainder * 2n >= d ? whole + 1n : whole;
     }
     return negative ? -result : result;
 }
-const BPS_DENOMINATOR = 10_000;
+/** {@link roundMinorExact} over integer numbers, for callers holding numbers. */
+export function roundMinor(numerator, denominator, mode) {
+    return toNumber(roundMinorExact(big(numerator, "numerator"), big(denominator, "denominator"), mode), "the rounded amount");
+}
+const BPS_DENOMINATOR = 10000n;
 export function calculateTax(lines, rates, options = {}) {
     const mode = options.rounding ?? "half-up";
     const scope = options.scope ?? "line";
@@ -59,60 +68,66 @@ export function calculateTax(lines, rates, options = {}) {
             }
         }
     }
-    if (!Number.isInteger(lines.reduce((s, l) => s + l.amountMinor, 0))) {
-        throw new Error("amounts must be integer minor units");
-    }
+    // Exact throughout: every amount and rate as a bigint, and a figure goes
+    // back to a number only when it fits. See ./exact.
     const tally = new Map();
     const results = [];
     // Exact totals kept as numerator over BPS_DENOMINATOR, so invoice-scope
     // rounding rounds the true sum rather than a sum of rounded pieces.
-    let exactTaxNumerator = 0;
+    let exactTaxNumerator = 0n;
+    let netTotal = 0n;
+    let summedTax = 0n;
     for (const line of lines) {
-        if (!Number.isInteger(line.amountMinor)) {
-            throw new Error(`line "${line.id}" has a non-integer amount; use minor units`);
-        }
+        const amount = big(line.amountMinor, `line "${line.id}" amountMinor`);
         const applied = line.exempt || options.reverseCharge ? [] : line.taxCodes;
         const rateList = applied.map((code) => byCodeIndex.get(code));
         // Net is the base everything is charged on. When listed prices already
         // include tax it has to be recovered first: gross / (1 + total rate).
-        let netMinor;
+        let net;
         if (options.pricesIncludeTax && rateList.length > 0) {
             let multiplier = BPS_DENOMINATOR;
             for (const rate of rateList) {
+                const bps = big(rate.bps, `rate "${rate.code}" bps`);
                 multiplier = rate.compound
-                    ? Math.round((multiplier * (BPS_DENOMINATOR + rate.bps)) / BPS_DENOMINATOR)
-                    : multiplier + rate.bps;
+                    ? mathRound(multiplier * (BPS_DENOMINATOR + bps), BPS_DENOMINATOR)
+                    : multiplier + bps;
             }
-            netMinor = roundMinor(line.amountMinor * BPS_DENOMINATOR, multiplier, mode);
+            net = roundMinorExact(amount * BPS_DENOMINATOR, multiplier, mode);
         }
         else {
-            netMinor = line.amountMinor;
+            net = amount;
         }
         const breakdown = [];
-        let lineTax = 0;
+        let lineTax = 0n;
         for (const rate of rateList) {
             // `compound` describes the base THIS rate is charged on — net plus the
             // taxes already applied — not an effect on the rates after it. Adding
             // to the base afterwards instead left the compound rate itself charged
             // on the bare net, which is the whole thing the flag exists to change.
-            const base = rate.compound ? netMinor + lineTax : netMinor;
-            const numerator = base * rate.bps;
-            const taxMinor = roundMinor(numerator, BPS_DENOMINATOR, mode);
+            const base = rate.compound ? net + lineTax : net;
+            const numerator = base * big(rate.bps, `rate "${rate.code}" bps`);
+            const taxMinor = roundMinorExact(numerator, BPS_DENOMINATOR, mode);
             exactTaxNumerator += numerator;
-            breakdown.push({ code: rate.code, bps: rate.bps, taxMinor });
+            breakdown.push({
+                code: rate.code,
+                bps: rate.bps,
+                taxMinor: toNumber(taxMinor, `line "${line.id}" ${rate.code} tax`),
+            });
             lineTax += taxMinor;
-            const seen = tally.get(rate.code) ?? { bps: rate.bps, taxMinor: 0, netMinor: 0 };
+            const seen = tally.get(rate.code) ?? { bps: rate.bps, taxMinor: 0n, netMinor: 0n };
             tally.set(rate.code, {
                 bps: rate.bps,
                 taxMinor: seen.taxMinor + taxMinor,
-                netMinor: seen.netMinor + netMinor,
+                netMinor: seen.netMinor + net,
             });
         }
+        netTotal += net;
+        summedTax += lineTax;
         results.push({
             id: line.id,
-            netMinor,
-            taxMinor: lineTax,
-            grossMinor: netMinor + lineTax,
+            netMinor: toNumber(net, `line "${line.id}" net`),
+            taxMinor: toNumber(lineTax, `line "${line.id}" tax`),
+            grossMinor: toNumber(net + lineTax, `line "${line.id}" gross`),
             breakdown,
             note: options.reverseCharge
                 ? "reverse charge: the customer accounts for the tax"
@@ -121,16 +136,19 @@ export function calculateTax(lines, rates, options = {}) {
                     : "",
         });
     }
-    const netMinor = results.reduce((s, r) => s + r.netMinor, 0);
-    const summedTax = results.reduce((s, r) => s + r.taxMinor, 0);
-    const taxMinor = scope === "invoice" ? roundMinor(exactTaxNumerator, BPS_DENOMINATOR, mode) : summedTax;
+    const taxTotal = scope === "invoice" ? roundMinorExact(exactTaxNumerator, BPS_DENOMINATOR, mode) : summedTax;
     return {
         lines: results,
-        netMinor,
-        taxMinor,
-        grossMinor: netMinor + taxMinor,
+        netMinor: toNumber(netTotal, "the invoice's net"),
+        taxMinor: toNumber(taxTotal, "the invoice's tax"),
+        grossMinor: toNumber(netTotal + taxTotal, "the invoice's gross"),
         byCode: [...tally.entries()]
-            .map(([code, v]) => ({ code, ...v }))
+            .map(([code, v]) => ({
+            code,
+            bps: v.bps,
+            taxMinor: toNumber(v.taxMinor, `the ${code} tax`),
+            netMinor: toNumber(v.netMinor, `the net taxed at ${code}`),
+        }))
             .sort((a, b) => (a.code < b.code ? -1 : 1)),
         reverseCharge: options.reverseCharge === true,
         rounding: mode,

package/dist/paths.d.ts

@@ -1,10 +1,29 @@
 import { CrewhausError } from "@crewhaus/errors";
-/** Raised when a caller-supplied path resolves outside the workspace root. */
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export declare const MAX_PATH_CHARS: number;
+/**
+ * Raised when a caller-supplied path resolves outside the workspace root, or
+ * is longer than any path can be.
+ */
 export declare class ToolPermissionError extends CrewhausError {
     readonly name = "ToolPermissionError";
     readonly toolName: string;
     readonly path: string;
-    constructor(toolName: string, attemptedPath: string);
+    /**
+     * Why, when it is not that the location escapes the workspace root: a path
+     * longer than any path can be. A caller that rewords the refusal says this.
+     */
+    readonly reason: string | undefined;
+    constructor(toolName: string, attemptedPath: string, reason?: string);
 }
 /**
  * A validated path, in both forms the tools need.