tallyd 0.0.0-stage → 0.1.0

package/dist/group/intercompany.js

@@ -0,0 +1,238 @@
+/**
+ * Taking back out what the group owes and sells to itself.
+ *
+ * Aggregation adds every controlled entity in full, so a group that lends
+ * itself a million pounds shows a million of assets and a million of
+ * liabilities that no outsider is party to, and a group that sells to itself
+ * shows revenue it never earned. Neither survives into a set of consolidated
+ * accounts: from outside, the group is one economic entity and it cannot owe
+ * itself anything.
+ *
+ * The model is a declaration rather than an inference. An account is
+ * intercompany because someone said so and because it names which entity it
+ * faces — there is nothing in a balance that reveals whether the person on the
+ * other end of it is inside the group. That forces one account per
+ * counterparty, which is the shape real groups use anyway: "owed by S", "owed
+ * by T", not one "intercompany" account whose balance is a net of three
+ * relationships that each have to be eliminated against a different set of
+ * books.
+ *
+ * The interesting part is that the two sides rarely agree. Money sent on the
+ * 30th and received on the 3rd sits in neither company's cash and in both
+ * companies' intercompany accounts on the wrong side; goods despatched and not
+ * received do the same; and two legs translated at rates that do not
+ * reciprocate disagree by a few pence for no reason anyone can act on. That
+ * residual is the finding. It is booked to a named account, reported with the
+ * pair that produced it, and never plugged into a total — a group whose
+ * intercompany accounts are out by six figures has a problem, and a
+ * consolidation that made the number disappear would be hiding it.
+ */
+import { Money, sumMoney } from "../money/money.js";
+import { JournalEntry } from "../ledger/entry.js";
+import { GROUP_ACCOUNTS } from "./accounts.js";
+import { GroupError } from "./structure.js";
+function key(...parts) {
+    return parts.join(" ");
+}
+function classOf(type) {
+    return type === "income" || type === "expense" ? "profit-and-loss" : "balance-sheet";
+}
+/**
+ * Read the declared balances out of an aggregation.
+ *
+ * The aggregation already holds every entity's translated trial balance, so
+ * nothing is recomputed here and the eliminations are guaranteed to be against
+ * the same figures that were added up.
+ */
+export function intercompanyBalances(group, aggregation, declarations) {
+    const zero = Money.zero(aggregation.presentation);
+    const seen = new Set();
+    const sides = [];
+    for (const declaration of declarations) {
+        const { entity, account, counterparty } = declaration;
+        if (entity === counterparty) {
+            throw new GroupError(`${entity} cannot be its own counterparty (account ${account})`);
+        }
+        if (!group.has(entity)) {
+            throw new GroupError(`Intercompany declaration names ${entity}, which is not in the group`);
+        }
+        if (!group.has(counterparty)) {
+            throw new GroupError(`Intercompany declaration in ${entity} names ${counterparty} as counterparty, ` +
+                `which is not in the group`);
+        }
+        const id = key(entity, account);
+        if (seen.has(id)) {
+            throw new GroupError(`Account ${account} in ${entity} is declared intercompany twice. One account faces ` +
+                `one counterparty; split the balance if it faces more.`);
+        }
+        seen.add(id);
+        const contribution = aggregation.entities.find((c) => c.entity === entity);
+        if (contribution === undefined) {
+            // Declared against an entity that is not being consolidated. Not an
+            // error — an associate's balances stay where they are — but there is
+            // nothing to eliminate, and saying so beats silently dropping it.
+            continue;
+        }
+        const row = contribution.translation.rows.find((r) => r.account === account);
+        sides.push(Object.freeze({
+            entity,
+            account,
+            counterparty,
+            name: row?.name ?? account,
+            type: row?.type ?? null,
+            functional: row?.functional ?? Money.zero(contribution.functional),
+            presentation: row?.presentation ?? zero,
+            link: declaration.link ?? classOf(row?.type ?? null),
+            note: declaration.note ?? "",
+        }));
+    }
+    return Object.freeze(sides);
+}
+function kindOf(a, b) {
+    const left = classOf(a.type);
+    const right = classOf(b.type);
+    return left === right ? left : "mixed";
+}
+/**
+ * Pair the declarations up and produce the entries that remove them.
+ *
+ * Each entry reverses both sides and books whatever is left to the difference
+ * account, so it balances by construction and the combined trial balance
+ * balances after it as it did before.
+ */
+export function eliminateIntercompany(group, aggregation, declarations, options = {}) {
+    const presentation = aggregation.presentation;
+    const zero = Money.zero(presentation);
+    const differenceAccount = options.differenceAccount ?? GROUP_ACCOUNTS.itemsInTransit;
+    const prefix = options.idPrefix ?? "ELIM";
+    const tolerance = options.tolerance ?? zero;
+    const sides = intercompanyBalances(group, aggregation, declarations);
+    // Keyed on the relationship and not just the two entities: a loan account
+    // and a trading account both face the same counterparty, and pairing on the
+    // entities alone would match the loan against the purchases.
+    const byPair = new Map();
+    for (const side of sides) {
+        const id = key(side.entity, side.counterparty, side.link);
+        if (byPair.has(id)) {
+            throw new GroupError(`${side.entity} has two accounts facing ${side.counterparty} on the same "${side.link}" ` +
+                `relationship (${byPair.get(id).account} and ${side.account}). ` +
+                `Name the relationships with "link" so each side knows what it pairs with.`);
+        }
+        byPair.set(id, side);
+    }
+    const pairs = [];
+    const unmatched = [];
+    const handled = new Set();
+    for (const side of sides) {
+        if (handled.has(side))
+            continue;
+        const mirror = byPair.get(key(side.counterparty, side.entity, side.link));
+        if (mirror === undefined || handled.has(mirror)) {
+            unmatched.push(Object.freeze({
+                side,
+                reason: mirror === undefined
+                    ? `${side.counterparty} declares no "${side.link}" account facing ${side.entity}`
+                    : `${side.counterparty}'s "${side.link}" account facing ${side.entity} is already paired`,
+            }));
+            handled.add(side);
+            continue;
+        }
+        handled.add(side);
+        handled.add(mirror);
+        const ordered = side.entity.localeCompare(mirror.entity) <= 0 ? [side, mirror] : [mirror, side];
+        const difference = ordered[0].presentation.plus(ordered[1].presentation);
+        pairs.push(Object.freeze({
+            sides: ordered,
+            kind: kindOf(ordered[0], ordered[1]),
+            difference,
+            agrees: difference.abs().lessThanOrEqual(tolerance) || difference.isZero,
+        }));
+    }
+    pairs.sort((a, b) => {
+        const byEntity = a.sides[0].entity.localeCompare(b.sides[0].entity);
+        if (byEntity !== 0)
+            return byEntity;
+        return a.sides[0].account.localeCompare(b.sides[0].account);
+    });
+    const entries = [];
+    let sequence = 0;
+    for (const pair of pairs) {
+        const [first, second] = pair.sides;
+        if (first.presentation.isZero && second.presentation.isZero)
+            continue;
+        sequence += 1;
+        const postings = [
+            {
+                account: first.account,
+                amount: first.presentation.negated(),
+                memo: `${first.entity} facing ${first.counterparty}`,
+            },
+            {
+                account: second.account,
+                amount: second.presentation.negated(),
+                memo: `${second.entity} facing ${second.counterparty}`,
+            },
+        ];
+        if (!pair.difference.isZero) {
+            postings.push({
+                account: differenceAccount,
+                amount: pair.difference,
+                memo: `${first.entity}/${second.entity} do not agree`,
+            });
+        }
+        entries.push(JournalEntry.create({
+            id: `${prefix}-${String(sequence).padStart(3, "0")}`,
+            date: aggregation.asAt,
+            narration: `Eliminate ${first.entity}/${second.entity} intercompany` +
+                (first.note === "" ? "" : ` — ${first.note}`),
+            postings,
+            tags: ["consolidation", "intercompany"],
+        }, options.chart));
+    }
+    // Measured on the debit side of the pairs actually removed. An unpaired
+    // declaration is not eliminated, so it does not count towards this.
+    const totalEliminated = sumMoney(pairs
+        .flatMap((p) => [...p.sides])
+        .filter((s) => s.presentation.isPositive)
+        .map((s) => s.presentation), presentation);
+    return Object.freeze({
+        presentation,
+        pairs: Object.freeze(pairs),
+        unmatched: Object.freeze(unmatched),
+        disagreements: Object.freeze(pairs.filter((p) => !p.agrees)),
+        entries: Object.freeze(entries),
+        totalDifference: sumMoney(pairs.map((p) => p.difference), presentation),
+        totalEliminated,
+    });
+}
+export function renderEliminations(result) {
+    const lines = [];
+    lines.push(`Intercompany eliminations — ${result.pairs.length} ` +
+        `${result.pairs.length === 1 ? "pair" : "pairs"}, ` +
+        `${result.totalEliminated.toDecimalString()} ${result.presentation.code} removed`);
+    lines.push("-".repeat(96));
+    for (const pair of result.pairs) {
+        const [a, b] = pair.sides;
+        lines.push(`${a.entity} ${a.account} ${a.name}`.padEnd(40) +
+            a.presentation.toDecimalString().padStart(14) +
+            `  ${pair.kind}`);
+        lines.push(`${b.entity} ${b.account} ${b.name}`.padEnd(40) + b.presentation.toDecimalString().padStart(14));
+        if (pair.agrees) {
+            lines.push("  agrees".padEnd(40) + "".padStart(14));
+        }
+        else {
+            const larger = pair.difference.isPositive ? a : b;
+            lines.push(`  out by ${pair.difference.abs().toDecimalString()} — ${larger.entity}'s side is the larger`);
+        }
+    }
+    for (const item of result.unmatched) {
+        lines.push(`UNPAIRED ${item.side.entity} ${item.side.account} ` +
+            `${item.side.presentation.toDecimalString()} — ${item.reason}`);
+    }
+    if (!result.totalDifference.isZero) {
+        lines.push("-".repeat(96));
+        lines.push(`${result.totalDifference.toDecimalString()} ${result.presentation.code} of differences, ` +
+            `carried as items in transit rather than plugged.`);
+    }
+    return lines.join("\n");
+}

package/dist/group/interest.d.ts

@@ -0,0 +1,109 @@
+/**
+ * An ownership interest, exactly.
+ *
+ * This has to be a rational and not a decimal, because the interests that
+ * matter are the ones that come out of a chain. A parent holding two thirds of
+ * a company that holds three quarters of a third owns exactly half of the
+ * third, and there is no decimal expansion of two thirds to write that with.
+ * Rounded to four places and multiplied through, 66.67% of 75% is 50.0025%,
+ * which is then multiplied by a number of pounds and shows up in a balance
+ * sheet as a non-controlling interest that is out by a few pence in a way
+ * nobody can trace.
+ *
+ * So: a numerator and a denominator over bigints, normalised, never converted
+ * to a float except for display, and constrained to [0, 1] because an interest
+ * outside that range is not an interest.
+ */
+import { Money } from "../money/money.js";
+import { type RoundingMode } from "../money/rounding.js";
+export declare class InterestError extends Error {
+    constructor(message: string);
+}
+export declare class Interest {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+    private constructor();
+    /**
+     * A fraction, given as a ratio. Normalised on the way in, so `of(2n, 4n)`
+     * and `of(1n, 2n)` are the same object by `equals` and print the same.
+     */
+    static of(numerator: bigint | number, denominator?: bigint | number): Interest;
+    /**
+     * From a percentage written as a decimal string or a number. The string form
+     * is exact — `ofPercent("33.333")` is 33333/100000 and not the nearest
+     * double — and is what a document loader should use.
+     */
+    static ofPercent(value: string | number): Interest;
+    /** From basis points: 8000 is 80%. */
+    static ofBasisPoints(points: bigint | number): Interest;
+    static readonly whole: Interest;
+    static readonly none: Interest;
+    /**
+     * The interest held through this one. A parent's 80% of a subsidiary that
+     * itself holds 75% of a third company gives the parent 60% of the third.
+     */
+    times(other: Interest): Interest;
+    /** Two holdings in the same company, added. Throws if they exceed the whole. */
+    plus(other: Interest): Interest;
+    minus(other: Interest): Interest;
+    /** What everybody else holds. The non-controlling interest, when this is the group's. */
+    complement(): Interest;
+    get isZero(): boolean;
+    get isWhole(): boolean;
+    /**
+     * More than half. Control is a question about voting rights and in principle
+     * a bare majority is neither necessary nor sufficient for it; this is the
+     * arithmetic part of the test and the group structure treats it as a default
+     * that a definition can override.
+     */
+    get isControlling(): boolean;
+    compare(other: Interest): -1 | 0 | 1;
+    equals(other: Interest): boolean;
+    /**
+     * This share of an amount, rounded to whole minor units.
+     *
+     * Exact until the last step: the multiplication and the division happen in
+     * one bigint operation, so 40% of 3 pence is decided by the rounding mode
+     * rather than by an intermediate float.
+     */
+    share(amount: Money, rounding?: RoundingMode): Money;
+    /**
+     * This share and the rest, summing exactly back to the amount.
+     *
+     * `share` on its own cannot promise that: 50% of an odd number of pence
+     * rounds one way, its complement rounds the same way, and the two halves
+     * come to a penny more or less than the whole. The remainder is given to the
+     * other side, so that a group share and a non-controlling interest always
+     * add up to what was there.
+     */
+    splitOf(amount: Money, rounding?: RoundingMode): {
+        mine: Money;
+        theirs: Money;
+    };
+    toNumber(): number;
+    /**
+     * As a percentage, trailing zeros trimmed. Exact when the interest has a
+     * terminating expansion, and truncated with a trailing marker when it does
+     * not, so a third never reads as if it were 33.33% on the nose.
+     */
+    toPercentString(places?: number): string;
+    toString(): string;
+    /**
+     * A string that `parse` reads back to the same interest.
+     *
+     * Percentages are the readable form and the one a document should normally
+     * carry, but two thirds has no decimal expansion, and writing 66.6667% into
+     * a file that is later read back is a quiet loss of the exactness the whole
+     * type exists for. So a non-terminating interest serialises as its ratio.
+     */
+    toJSON(): string;
+    /** Whether the percentage has a finite decimal expansion. */
+    isTerminating(): boolean;
+    /**
+     * Read either form: `"80%"`, `"80"`, `"0.6"` as a percentage is ambiguous and
+     * is not accepted without the sign, and `"2/3"` for the ones that need it.
+     */
+    static parse(value: string): Interest;
+    /** The ratio itself, for a reader who wants to see where a third came from. */
+    toRatioString(): string;
+}

package/dist/group/interest.js

@@ -0,0 +1,224 @@
+/**
+ * An ownership interest, exactly.
+ *
+ * This has to be a rational and not a decimal, because the interests that
+ * matter are the ones that come out of a chain. A parent holding two thirds of
+ * a company that holds three quarters of a third owns exactly half of the
+ * third, and there is no decimal expansion of two thirds to write that with.
+ * Rounded to four places and multiplied through, 66.67% of 75% is 50.0025%,
+ * which is then multiplied by a number of pounds and shows up in a balance
+ * sheet as a non-controlling interest that is out by a few pence in a way
+ * nobody can trace.
+ *
+ * So: a numerator and a denominator over bigints, normalised, never converted
+ * to a float except for display, and constrained to [0, 1] because an interest
+ * outside that range is not an interest.
+ */
+import { Money } from "../money/money.js";
+import { decimalToRational, divideRound } from "../money/rounding.js";
+export class InterestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InterestError";
+    }
+}
+function gcd(a, b) {
+    let x = a < 0n ? -a : a;
+    let y = b < 0n ? -b : b;
+    while (y !== 0n) {
+        const t = x % y;
+        x = y;
+        y = t;
+    }
+    return x;
+}
+export class Interest {
+    numerator;
+    denominator;
+    constructor(numerator, denominator) {
+        this.numerator = numerator;
+        this.denominator = denominator;
+        Object.freeze(this);
+    }
+    // ---------------------------------------------------------------- factories
+    /**
+     * A fraction, given as a ratio. Normalised on the way in, so `of(2n, 4n)`
+     * and `of(1n, 2n)` are the same object by `equals` and print the same.
+     */
+    static of(numerator, denominator = 1n) {
+        let n = BigInt(numerator);
+        let d = BigInt(denominator);
+        if (d === 0n)
+            throw new InterestError("An interest cannot have a zero denominator");
+        if (d < 0n) {
+            n = -n;
+            d = -d;
+        }
+        if (n < 0n)
+            throw new InterestError(`An interest cannot be negative: ${n}/${d}`);
+        if (n > d) {
+            throw new InterestError(`An interest cannot exceed the whole: ${n}/${d} is more than 100%`);
+        }
+        const g = gcd(n, d);
+        return new Interest(g === 0n ? 0n : n / g, g === 0n ? 1n : d / g);
+    }
+    /**
+     * From a percentage written as a decimal string or a number. The string form
+     * is exact — `ofPercent("33.333")` is 33333/100000 and not the nearest
+     * double — and is what a document loader should use.
+     */
+    static ofPercent(value) {
+        if (typeof value === "number") {
+            if (!Number.isFinite(value))
+                throw new InterestError(`Not a percentage: ${value}`);
+            return Interest.ofPercent(String(value));
+        }
+        const trimmed = value.trim().replace(/%$/, "").trim();
+        if (trimmed === "")
+            throw new InterestError("Not a percentage: an empty string");
+        let rational;
+        try {
+            rational = decimalToRational(trimmed);
+        }
+        catch {
+            throw new InterestError(`Not a percentage: ${JSON.stringify(value)}`);
+        }
+        return Interest.of(rational.numerator, rational.denominator * 100n);
+    }
+    /** From basis points: 8000 is 80%. */
+    static ofBasisPoints(points) {
+        return Interest.of(BigInt(points), 10000n);
+    }
+    static whole = new Interest(1n, 1n);
+    static none = new Interest(0n, 1n);
+    // ------------------------------------------------------------------ algebra
+    /**
+     * The interest held through this one. A parent's 80% of a subsidiary that
+     * itself holds 75% of a third company gives the parent 60% of the third.
+     */
+    times(other) {
+        return Interest.of(this.numerator * other.numerator, this.denominator * other.denominator);
+    }
+    /** Two holdings in the same company, added. Throws if they exceed the whole. */
+    plus(other) {
+        return Interest.of(this.numerator * other.denominator + other.numerator * this.denominator, this.denominator * other.denominator);
+    }
+    minus(other) {
+        return Interest.of(this.numerator * other.denominator - other.numerator * this.denominator, this.denominator * other.denominator);
+    }
+    /** What everybody else holds. The non-controlling interest, when this is the group's. */
+    complement() {
+        return Interest.of(this.denominator - this.numerator, this.denominator);
+    }
+    // ---------------------------------------------------------------- predicates
+    get isZero() {
+        return this.numerator === 0n;
+    }
+    get isWhole() {
+        return this.numerator === this.denominator;
+    }
+    /**
+     * More than half. Control is a question about voting rights and in principle
+     * a bare majority is neither necessary nor sufficient for it; this is the
+     * arithmetic part of the test and the group structure treats it as a default
+     * that a definition can override.
+     */
+    get isControlling() {
+        return this.numerator * 2n > this.denominator;
+    }
+    compare(other) {
+        const left = this.numerator * other.denominator;
+        const right = other.numerator * this.denominator;
+        return left < right ? -1 : left > right ? 1 : 0;
+    }
+    equals(other) {
+        return this.numerator === other.numerator && this.denominator === other.denominator;
+    }
+    // ------------------------------------------------------------------- money
+    /**
+     * This share of an amount, rounded to whole minor units.
+     *
+     * Exact until the last step: the multiplication and the division happen in
+     * one bigint operation, so 40% of 3 pence is decided by the rounding mode
+     * rather than by an intermediate float.
+     */
+    share(amount, rounding = "half-even") {
+        return Money.ofMinor(divideRound(amount.minorUnits * this.numerator, this.denominator, rounding), amount.currency);
+    }
+    /**
+     * This share and the rest, summing exactly back to the amount.
+     *
+     * `share` on its own cannot promise that: 50% of an odd number of pence
+     * rounds one way, its complement rounds the same way, and the two halves
+     * come to a penny more or less than the whole. The remainder is given to the
+     * other side, so that a group share and a non-controlling interest always
+     * add up to what was there.
+     */
+    splitOf(amount, rounding = "half-even") {
+        const mine = this.share(amount, rounding);
+        return { mine, theirs: amount.minus(mine) };
+    }
+    // ------------------------------------------------------------------ display
+    toNumber() {
+        return Number(this.numerator) / Number(this.denominator);
+    }
+    /**
+     * As a percentage, trailing zeros trimmed. Exact when the interest has a
+     * terminating expansion, and truncated with a trailing marker when it does
+     * not, so a third never reads as if it were 33.33% on the nose.
+     */
+    toPercentString(places = 4) {
+        const scale = 10n ** BigInt(places);
+        const scaled = (this.numerator * 100n * scale) / this.denominator;
+        const exact = this.numerator * 100n * scale === scaled * this.denominator;
+        const whole = scaled / scale;
+        const fraction = scaled % scale;
+        let text = whole.toString();
+        if (fraction > 0n) {
+            const digits = fraction.toString().padStart(places, "0").replace(/0+$/, "");
+            text += `.${digits}`;
+        }
+        return `${text}${exact ? "" : "…"}%`;
+    }
+    toString() {
+        return this.toPercentString();
+    }
+    /**
+     * A string that `parse` reads back to the same interest.
+     *
+     * Percentages are the readable form and the one a document should normally
+     * carry, but two thirds has no decimal expansion, and writing 66.6667% into
+     * a file that is later read back is a quiet loss of the exactness the whole
+     * type exists for. So a non-terminating interest serialises as its ratio.
+     */
+    toJSON() {
+        return this.isTerminating() ? this.toPercentString(20) : this.toRatioString();
+    }
+    /** Whether the percentage has a finite decimal expansion. */
+    isTerminating() {
+        // A fraction in lowest terms terminates in base 10 exactly when its
+        // denominator's only prime factors are 2 and 5. The percentage carries a
+        // factor of 100, which supplies two of each.
+        let d = this.denominator;
+        for (const prime of [2n, 5n]) {
+            while (d % prime === 0n)
+                d /= prime;
+        }
+        return d === 1n;
+    }
+    /**
+     * Read either form: `"80%"`, `"80"`, `"0.6"` as a percentage is ambiguous and
+     * is not accepted without the sign, and `"2/3"` for the ones that need it.
+     */
+    static parse(value) {
+        const text = value.trim();
+        const ratio = /^(\d+)\s*\/\s*(\d+)$/.exec(text);
+        if (ratio !== null)
+            return Interest.of(BigInt(ratio[1]), BigInt(ratio[2]));
+        return Interest.ofPercent(text);
+    }
+    /** The ratio itself, for a reader who wants to see where a third came from. */
+    toRatioString() {
+        return `${this.numerator}/${this.denominator}`;
+    }
+}