nikola/money
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Pair transfers from rules.toml

Browse Source 
The boolean transfer flag went two commits ago because a one-sided verdict let
half a movement vanish and left the report unbalanced. This is what replaces
it: a [[transfer]] block names both legs, and only a matched pair is dropped
from the report -- both legs together, never one.

Legs pair within five days, nearest date first, and a transaction belongs to at
most one transfer, so the first definition to claim a leg keeps it, exactly as
the first matching rule keeps a tag. The pairing is derived state like the tags:
Engine.Link rewrites the whole transfers table from rules.toml, which is why
retag re-derives both halves of what that file decides, and why it runs over
the whole index rather than a filtered view -- pairing inside one would let a
movement count as a transfer in one report and not in another. An unmatched leg
is not a transfer and keeps counting, surfaced as a warning instead.

Within one currency the amount is the evidence and must be the exact opposite.
Across currencies it is not checked at all: there are no rates here, so the two
numbers are unrelated and the dates carry the pairing alone.

tolerance_pct is the one exception, per definition, for a route where the bank
takes a fee and the two statements genuinely disagree. It defaults to zero and
belongs on the one definition that charges; a global or default tolerance would
loosen every route that does not. The difference it admits is not forgiven --
the pair leaves the report entirely, so a fee hidden inside one would be
spending that appears nowhere. Pair.Fee is what left less what arrived, and
report.Excluded carries it out per currency alongside the legs. It counts only
pairs whose legs are both in view, for the same reason it counts legs and not
transfers: half a pair cannot say what the other half received.

The screens:

- 6 builds a definition against the index as you type, showing the pairs it
  would form and the legs it would catch but leave unpaired. Six fields need
  more room than the rule builder's four, so the form sheds its spacing, then
  its hints, then the borders on unfocused fields.
- 7 lists every definition with what it pairs. Two counts, because they mean
  different things: an unpaired leg is a definition doing something and not
  finishing it, no pairs at all is dead weight. Tol names the tolerance, blank
  where amounts must agree.
- 3 grows a (transfers) row under TOTAL, and a fees row beneath it, or the
  report silently disagrees with the account balances.

Two things that are not part of transfers but are the same day's work:

- ls --uniq lists each account and description once, normalised the way a glob
  sees them, which is the shape of "what still needs a rule?" -- fifty visits
  to one shop are one pattern to write, not fifty rows to read.
- The rule builder's preview now filters to what the glob matches instead of
  marking matches in a full list. The count carries the context the rows no
  longer can: 2 of 7, measured against everything still in view.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
nikola
2026-08-15 19:19:12 +02:00
co-authored by Claude Opus 5
parent ef6a231d98
commit ebf7770569
16 changed files with 3472 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/report/report.go
+95
View File
@@ -25,11 +25,25 @@ func (t TagTotal) Net() int64 { return t.In - t.Out }
const Untagged = "(untagged)"
// ByTag returns totals sorted by currency, then by largest outflow first.
//
// Matched transfer legs are left out entirely. Both legs of a transfer are
// dropped together, so a report over everything is unchanged in total by money
// the user moved between their own accounts; a report scoped to one account or
// one month may see only one leg, and dropping it is still right, since the
// money was not spent. What was left out is available from Excluded.
//
// A pair whose definition sets a tolerance_pct is dropped the same way, fee and
// all — so with such a definition in play the report *is* short by the fee, and
// callers are expected to show Excluded alongside it rather than leave that
// difference unexplained.
func ByTag(txns []model.Transaction) []TagTotal {
type key struct{ currency, tag string }
acc := map[key]*TagTotal{}
for _, t := range txns {
if t.IsTransferLeg() {
continue
}
tag := t.RuleTag
if tag == "" {
tag = Untagged
@@ -96,6 +110,87 @@ func Totals(rows []TagTotal) []CurrencyTotal {
return out
}
// TransferTotal is what ByTag left out for one currency.
//
// It counts legs rather than pairs on purpose: a report scoped to one account
// or month usually holds only one side of a movement, and claiming a whole
// transfer was excluded when only half of it was in view would be a lie. The
// same goes for the two directions, which is why they are separate totals: an
// exchange between currencies has its legs in different columns entirely, so
// one currency can see only what left and the other only what arrived.
type TransferTotal struct {
Currency string
Out int64 // sum of the leaving legs in view, positive
In int64 // sum of the arriving legs in view
Legs int
Digits int
// Fee is what those movements cost: the amount that left less the amount
// that arrived, for pairs whose legs are *both* in view. A definition with a
// tolerance_pct pairs legs that disagree, and since the pair leaves the
// report entirely, this is the only place that difference is still money
// rather than nothing. Zero when no definition allows a mismatch.
Fee int64
// Pairs counts the movements Fee was computed from — complete pairs in this
// currency, not legs. A report scoped to one account or month usually holds
// one side of a movement, and half a pair cannot say what the other half
// received, so it contributes to Legs and Out/In but not here.
Pairs int
}
// Excluded summarises the transfer legs ByTag dropped, so a report can account
// for the difference between its total and the account balances.
func Excluded(txns []model.Transaction) []TransferTotal {
// Both legs of a pair carry the same TransferID, so the ones whose partner
// is also in view can be found without going back to the index.
byID := map[int64][]model.Transaction{}
for _, t := range txns {
if t.IsTransferLeg() {
byID[*t.TransferID] = append(byID[*t.TransferID], t)
}
}
acc := map[string]*TransferTotal{}
row := func(t model.Transaction) *TransferTotal {
r, ok := acc[t.Currency]
if !ok {
r = &TransferTotal{Currency: t.Currency, Digits: t.MinorDigits}
acc[t.Currency] = r
}
return r
}
for _, t := range txns {
if !t.IsTransferLeg() {
continue
}
r := row(t)
r.Legs++
if t.AmountMinor < 0 {
r.Out += -t.AmountMinor
} else {
r.In += t.AmountMinor
}
}
for _, legs := range byID {
// An exchange has its legs in two currencies, and there is no rate here
// to subtract one from the other, so it has no fee to report.
if len(legs) != 2 || legs[0].Currency != legs[1].Currency {
continue
}
r := row(legs[0])
r.Pairs++
r.Fee -= legs[0].AmountMinor + legs[1].AmountMinor
}
out := make([]TransferTotal, 0, len(acc))
for _, r := range acc {
out = append(out, *r)
}
sort.Slice(out, func(i, j int) bool { return out[i].Currency < out[j].Currency })
return out
}
// Months lists the distinct YYYY-MM present in txns, most recent first.
func Months(txns []model.Transaction) []string {
seen := map[string]bool{}
internal/report/report_test.go
+135
View File
@@ -0,0 +1,135 @@
package report
import (
"testing"
"git.petrovv.com/nikola/money/internal/model"
)
func leg(id int64, amount int64, transferID *int64) model.Transaction {
return model.Transaction{
ID: id,
AccountSlug: "nlb",
Currency: "EUR",
MinorDigits: 2,
Date: "2026-03-06",
AmountMinor: amount,
RuleTag: "moving",
TransferID: transferID,
}
}
// A matched transfer is money moved, not money spent, so neither leg reaches
// the report at all.
func TestByTagLeavesTransferLegsOut(t *testing.T) {
id := int64(1)
rows := ByTag([]model.Transaction{
leg(1, -50000, &id),
leg(2, 50000, &id),
{Currency: "EUR", MinorDigits: 2, AmountMinor: -2000, RuleTag: "groceries"},
})
if len(rows) != 1 || rows[0].Tag != "groceries" {
t.Fatalf("rows = %+v, want only the groceries row", rows)
}
if rows[0].Out != 2000 {
t.Errorf("out = %d, want only the shopping", rows[0].Out)
}
}
// An unpaired leg is not a transfer, so it still counts. Money that left an
// account and cannot be shown to have arrived must not quietly vanish from the
// report.
func TestByTagKeepsUnpairedLegs(t *testing.T) {
rows := ByTag([]model.Transaction{leg(1, -50000, nil)})
if len(rows) != 1 || rows[0].Out != 50000 {
t.Fatalf("rows = %+v, want the unpaired leg counted", rows)
}
}
// A report scoped to one account or month usually holds one side of a
// movement, so the summary counts legs rather than claiming whole transfers.
func TestExcludedCountsLegsInView(t *testing.T) {
id := int64(1)
got := Excluded([]model.Transaction{
leg(1, -50000, &id),
{Currency: "EUR", MinorDigits: 2, AmountMinor: -2000, RuleTag: "groceries"},
})
if len(got) != 1 {
t.Fatalf("excluded = %+v, want one currency", got)
}
if got[0].Legs != 1 || got[0].Out != 50000 || got[0].In != 0 || got[0].Currency != "EUR" {
t.Errorf("excluded = %+v, want 1 leg and 50000 out in EUR", got[0])
}
}
// An exchange has its legs in two currencies, so each side reports only what it
// saw. Summing the two would be meaningless: there are no rates here.
func TestExcludedSplitsAnExchangeByCurrency(t *testing.T) {
id := int64(1)
arriving := leg(2, 97790, &id)
arriving.Currency = "BGN"
got := Excluded([]model.Transaction{leg(1, -50000, &id), arriving})
if len(got) != 2 {
t.Fatalf("excluded = %+v, want a row per currency", got)
}
bgn, eur := got[0], got[1]
if bgn.Currency != "BGN" || bgn.In != 97790 || bgn.Out != 0 {
t.Errorf("BGN row = %+v, want only the arriving leg", bgn)
}
if eur.Currency != "EUR" || eur.Out != 50000 || eur.In != 0 {
t.Errorf("EUR row = %+v, want only the leaving leg", eur)
}
}
// A definition with a tolerance pairs legs that disagree, and the pair leaves
// the report with the difference inside it. That difference is real money, so
// the summary has to name it or it is simply lost.
func TestExcludedReportsTheFee(t *testing.T) {
id := int64(1)
got := Excluded([]model.Transaction{leg(1, -50000, &id), leg(2, 49500, &id)})
if len(got) != 1 {
t.Fatalf("excluded = %+v, want one currency", got)
}
if got[0].Fee != 500 || got[0].Pairs != 1 || got[0].Legs != 2 {
t.Errorf("excluded = %+v, want a 5.00 fee over 1 pair and 2 legs", got[0])
}
}
// Half a pair cannot say what the other half received, so a report scoped to
// one account or month reports the leg it saw and claims no fee at all.
func TestExcludedClaimsNoFeeFromHalfAPair(t *testing.T) {
id := int64(1)
got := Excluded([]model.Transaction{leg(1, -50000, &id)})
if len(got) != 1 {
t.Fatalf("excluded = %+v, want one currency", got)
}
if got[0].Fee != 0 || got[0].Pairs != 0 || got[0].Legs != 1 {
t.Errorf("excluded = %+v, want no fee and no complete pair", got[0])
}
}
// Without a tolerance the two legs are exact opposites, so there is nothing to
// report and the line stays as it was.
func TestExcludedReportsNoFeeForAnExactPair(t *testing.T) {
id := int64(1)
got := Excluded([]model.Transaction{leg(1, -50000, &id), leg(2, 50000, &id)})
if len(got) != 1 || got[0].Fee != 0 || got[0].Pairs != 1 {
t.Errorf("excluded = %+v, want one pair and no fee", got)
}
}
// The legs of an exchange are in different units, so subtracting one from the
// other would produce a number meaning nothing.
func TestExcludedClaimsNoFeeAcrossCurrencies(t *testing.T) {
id := int64(1)
arriving := leg(2, 97790, &id)
arriving.Currency = "BGN"
for _, row := range Excluded([]model.Transaction{leg(1, -50000, &id), arriving}) {
if row.Fee != 0 || row.Pairs != 0 {
t.Errorf("%s row = %+v, want no fee across currencies", row.Currency, row)
}
}
}