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
README.md
+277 -34
View File
@@ -10,7 +10,7 @@ tagged by glob rules you write.
```
~/money/ # the data root (see "Where the data root lives")
rules.toml # tag rules, in order
rules.toml # tag rules and transfer definitions, in order
index.db # SQLite index (rebuildable; safe to delete*)
checking/
account.toml # currency + which parser reads this bank's exports
@@ -62,8 +62,9 @@ compiles only the files listed, which breaks the moment the package has two.
money # open the TUI (default)
money import # extract new transactions from every statement
money import --force # re-parse statements even if unchanged
money retag # re-apply rules.toml to everything already imported
money ls --untagged # what no rule has claimed yet
money retag # re-apply rules.toml: retag, and re-pair transfers
money ls --untagged # what neither a rule nor a transfer has claimed
money ls --untagged --uniq # the same, one row per distinct description
money ls --wide # also show type and reported balance
money ls --account checking --month 2026-01
money report --month 2026-01 # spending by tag
@@ -76,14 +77,36 @@ An account folder appears in the app only once its statements have been
imported — creating an `account.toml` is not enough on its own. Run
`money import` (or press `i` in the TUI) after adding one.
`--uniq` turns `ls` into a list of patterns still to write rather than a list of
rows to read: one line per distinct account and description, since fifty visits
to the same shop are one glob, not fifty lines. Descriptions print exactly as a
glob sees them — upper-cased with whitespace collapsed — so two statements that
worded the same payee differently collapse into the one row they deserve, and a
pattern written from the list matches what the list showed you.
```
$ money ls --untagged --uniq
ACCOUNT DESCRIPTION
checking KAUFLAND 4412 SOFIA
checking LIDL SOFIA 4412
savings INTEREST PAID
3 distinct descriptions
```
It composes with the other filters (`--account`, `--month`, `--search`), and
`--limit` caps the rows printed, saying how many it held back. It cannot be
combined with `--wide`: a reported balance belongs to one transaction, and
there is nothing sensible to print for a whole group of them.
### TUI keys
| Key | Action |
| --- | --- |
| `1` `2` `3` `4` `5` / `tab` | accounts · transactions · report · rule builder · rules |
| `1` `2` `3` `4` `5` `6` `7` / `tab` | accounts · transactions · report · rule builder · rules · transfer builder · transfers |
| `enter` | open the selected account (accounts view) |
| `/` | filter by description |
| `u` | show only untagged transactions |
| `u` | show only untagged transactions (matched transfer legs are not among them) |
| `a` | clear the account filter |
| `i` | import · `r` re-apply rules · `q` quit |
@@ -94,18 +117,25 @@ nowhere else, so tagging what you are looking at means writing a rule for it on
### Rule builder (`4`)
Writing rules by hand means guessing what a glob will catch. This screen shows
the answer as you type: the form is on the left, and on the right is every
still-untagged description in the data, sorted alphabetically and grouped, with
a `▸` against each one the glob currently matches and a running
"*n* of *m* descriptions match" count.
the answer as you type: the form is on the left, and on the right the
still-untagged descriptions the glob currently matches, marked `▸`, grouped and
sorted alphabetically, under a running "*n* of *m* descriptions match" count.
The list narrows as you type, so what is on screen is what the rule would
claim — nothing else is left there to read past. The count keeps the context
the rows no longer can: *m* is everything still in view, so `2 of 7` says the
glob picked two descriptions out of seven, and `0 of 7` says the glob is wrong.
With the glob still empty there is nothing to filter by, and the list is every
untagged description in the data — which is the other question this screen
answers, and where you go looking for the next thing to write a rule for.
```
glob Untagged description N
╭────────────────────────────╮ ACME PAYROLL JAN 1
│ *LIDL* │ BOLT RIDE 1
╰────────────────────────────╯ ▸ LIDL SOFIA 4412 2
vs. the description ▸ LIDL VARNA 9911 1
ZARA MLADOST 1
╭────────────────────────────╮ ▸ LIDL SOFIA 4412 2
│ *LIDL* │ ▸ LIDL VARNA 9911 1
╰────────────────────────────╯
vs. the description
account
╭────────────────────────────╮
│ blank = every account │
@@ -147,7 +177,9 @@ which is what stops `groceries` acquiring a `grocery` twin.
Leaving the account blank applies the rule everywhere; filling it in also
narrows the preview to that account. Rules are appended, so anything already in
`rules.toml` keeps precedence — the preview accounts for that automatically,
since it only ever lists transactions no existing rule has already tagged.
since it only ever lists transactions no existing rule has already tagged. Legs
of a matched transfer are left out too: they are already accounted for by the
definition that paired them, and the report leaves them out anyway.
### Rules (`5`)
@@ -180,6 +212,104 @@ comments, ordering and formatting survive; a comment sitting directly above a
deleted rule goes with it, while one separated by a blank line is treated as a
section heading and left alone.
### Transfer builder (`6`)
Same idea as the rule builder, for money moved between your own accounts. Both
sides are named, and the preview on the right shows what the pair would be:
`▸` for a movement it matches end to end, `⚠` for a leg it catches on one side
and cannot pair with anything on the other.
```
from account Date Amount Movement Description
╭────────────────────────────╮ ⚠ 2026-04-01 500.00 checking → ? TRANSFER TO SAVINGS
│ checking │ ▸ 2026-03-01 500.00 checking → savings TRANSFER TO SAVINGS
╰────────────────────────────╯
money leaves here
▸ from desc
╭────────────────────────────╮
│ *TO SAVINGS* │
╰────────────────────────────╯
glob vs. the leaving leg
to account
╭────────────────────────────╮
│ savings │
╰────────────────────────────╯
money arrives here
to desc
╭────────────────────────────╮
│ *FROM CHECKING* │
╰────────────────────────────╯
glob vs. the arriving leg
tolerance %
╭────────────────────────────╮
│ 0 │
╰────────────────────────────╯
0 = amounts must match exactly
note
╭────────────────────────────╮
│ optional │
╰────────────────────────────╯
why this transfer exists
1 pairs · 1 unpaired
```
The account fields complete exactly as the rule builder's do. `tab` / `↑↓` move
between fields, `pgup` / `pgdn` scroll the list, `enter` appends the definition
to `rules.toml` and re-pairs immediately, and `esc` goes back. Saving keeps both
account names in place and clears the two globs, since the next transfer you
write is usually the same route in the other direction. The tolerance is cleared
with them: carried over silently it would loosen a route that never asked for
one. Six fields need more room than the rule builder's four, so on a short
window this form gives up its spacing, then its hints, then the borders on the
fields you are not editing — every field stays on screen.
`tolerance %` is the one field worth previewing before you save. Type a
percentage and the pairs it buys appear immediately, showing both amounts —
`500.00 → 495.00` — with what they cost summarised beside the counts:
```
1 pairs · 0 unpaired · 5.00 in fees
```
A half-written definition previews too: fill in one side and its legs show up as
unpaired, which is the quickest way to see that a glob is wrong before you have
written the other half.
### Transfers (`7`)
Every definition in file order, with what it currently pairs.
```
money · transfers · 4 definitions · 1 leg(s) unpaired
# From To Pairs Unpaired Tol Note
1 ⚠ checking *TO SAVINGS* savings *FROM CHECKING* 11 1 monthly saving
2 checking *TO BROKER* traderepublic *FROM NLB* 4 0
3 checking *WIRE TO SAVINGS* savings *WIRE FROM CHECK* 2 0 1.5% the bank keeps a fee
4 ✗ checking *TO OLD BANK* savings *FROM OLD BANK* 0 0 closed in 2025
```
The two counts mean different things, which is the point of the screen. `⚠` is a
definition catching legs it cannot complete: a wrong glob on the other side, a
statement not imported yet, or a movement that genuinely went missing. `✗` is a
definition matching nothing at all, which is just dead weight.
`Tol` is the definition's `tolerance_pct`, and it qualifies the counts beside
it: row 3's two pairs were matched on slack rather than on the amount agreeing.
It is blank for every definition that requires the exact amount — which is the
default, so an empty column means nothing here is pairing on a mismatch.
`d` deletes the selected definition and `p` deletes every `✗` one at once, both
after a `y`. Definitions marked `⚠` are never pruned — they are doing something,
just not finishing it, and deleting one would hide the problem rather than fix
it. `r` re-pairs against what is currently in the index.
## rules.toml
Rules are evaluated in file order and the **first match wins**, so put specific
@@ -205,24 +335,6 @@ tag = "salary"
match = "*ACME PAYROLL*"
note = "paid on the 4th; the December one lands early"
# Money moved between your own accounts is tagged like anything else. Both
# legs need a rule, and both count in the report -- one as an outflow, the
# other as an inflow.
[[rule]]
match = "*TO SAVINGS*"
tag = "transfer"
[[rule]]
match = "*FROM CHECKING*"
tag = "transfer"
# Such movements are often only identifiable by the other side's account
# number, whatever the rest of the description happens to say. Every bank
# parser keeps that number in the description, so an ordinary glob finds it.
[[rule]]
match = "*SI56*"
tag = "transfer"
# A rule can be limited to one account, and can require several patterns.
[[rule]]
account = "checking"
@@ -239,7 +351,138 @@ Every tag comes from this file, so a tag is never something you have to keep
safe: `money retag` recomputes all of them from the current rules and is safe
to run whenever you change it. A transaction no rule matches simply stays
untagged, and shows up under `money ls --untagged`, the `u` view, and
`(untagged)` in the report.
`(untagged)` in the report — unless it is one leg of a matched transfer, which
is already spoken for and is left out of all three.
### Transfers
Money moved between your own accounts is one movement the statements show
twice: an outflow leaving one account and an inflow arriving in another. A
`[[transfer]]` block names both legs, in the same file and with the same globs
as everything else.
```toml
[[transfer]]
from_account = "checking"
from_desc = "*TO SAVINGS*"
to_account = "savings"
to_desc = "*FROM CHECKING*"
note = "monthly saving, usually lands the next working day"
# Such movements are often only identifiable by the other side's account
# number, whatever the rest of the description happens to say. Every bank
# parser keeps that number in the description, so an ordinary glob finds it.
[[transfer]]
from_account = "checking"
from_desc = "*SI56*"
to_account = "traderepublic"
to_desc = "*FROM NLB*"
```
All four `_account` / `_desc` keys are required; `note` and `tolerance_pct` are
optional, and `note`, as on a rule, never takes part in matching. `from_desc` is
matched against outflows on `from_account` and `to_desc` against inflows on
`to_account`, so a definition written backwards pairs nothing.
Two legs are the same movement when they match one definition and are dated no
more than **5 days** apart. Within one currency they must also be the exact
opposite amount, because a movement that arrives short is not obviously the same
movement leaving.
#### When the bank takes a fee
Some routes charge, and then the two statements really do disagree: 500.00
leaves and 495.00 arrives. `tolerance_pct` says how far short (or over) the
arriving leg may be, as a percentage of the leg that left:
```toml
[[transfer]]
from_account = "checking"
from_desc = "*WIRE TO SAVINGS*"
to_account = "savings"
to_desc = "*WIRE FROM CHECKING*"
tolerance_pct = 1.5
note = "the bank keeps a wire fee"
```
It belongs to that one definition and loosens nothing else — every other route
still needs the exact amount. It defaults to 0, which is what every definition
written without the key means, and it must stay under 100: at 100% any amount
would pair with any other and the dates would be deciding alone. Keep it as
tight as the fee actually requires. Every percent of slack is also a percent
more chance of pairing two unrelated movements that happen to fall in the same
five days, and where two candidates are the same number of days away the nearer
amount wins.
**The difference is not forgiven, it is reported.** A pair leaves the report
entirely, so a fee hidden inside one would be spending that appears nowhere at
all. `money report` names it on the excluded line and the TUI's report gives it
its own row (see below). Across currencies there is no fee to compute — the two
numbers are in different units — so a tolerance there means nothing and is
ignored.
**Across currencies the amount is not checked at all.** An exchange between two
of your own accounts — the same money in EUR and in BGN — has two unrelated
numbers, and the tool holds no exchange rates, so the dates carry the pairing on
their own and the nearest one wins. That is a weaker rule than the
same-currency one, deliberately: use the same route twice inside one window and
it will pair the wrong two legs. The transfer builder shows both amounts for
such a pair (`500.00 → 977.90`), which is the only place the rate the bank
actually used appears.
Definitions are evaluated in file order and each transaction belongs to at most
one transfer, so — exactly as with rules — the first definition to claim a leg
keeps it.
**A matched pair leaves the report entirely.** Both legs go together, so a
report over everything is unchanged in total by money you shuffled between your
own accounts, and `money report` says what it held out, per currency and per
direction — an exchange puts its two legs in different currencies, so each side
reports only the leg it saw:
```
transfers excluded: 4 legs in EUR, 2000.00 out, 1500.00 in
transfers excluded: 1 legs in BGN, 0.00 out, 977.90 in
```
Where a `tolerance_pct` definition let a fee through, the line says so too, and
that is the number your spending is short by:
```
transfers excluded: 2 legs in EUR, 500.00 out, 495.00 in, 5.00 in fees
```
The report screen (`3`) shows the same thing under its `TOTAL`, the fee on its
own row:
```
TAG CUR OUT IN NET N
groceries EUR 20.00 0.00 -20.00 1
TOTAL EUR 20.00 0.00 -20.00
(transfers) EUR 500.00 495.00 -5.00 2
⤷ fees EUR 5.00 -5.00 1
```
The fee is counted only for pairs whose legs are *both* in the report you are
looking at, for the same reason the line counts legs and not transfers: filter
to one account or one month and you usually have one side of a movement, and
half a pair cannot say what the other half received.
A paired leg shows as `(transfer)` in the tag column of the transaction list
and of `money ls`, so it reads as accounted for rather than as a blank waiting
for a rule. That label is display only — nothing writes it to the index, and it
is never offered as a tag to complete against. A rule tag wins where there is
one, since that is your own word for it.
An *unpaired* leg is not a transfer and still counts, tagged like anything
else. That is deliberate: money that left an account and cannot be shown to
have arrived is exactly what you want to see, not something to quietly drop.
`money import` and `money retag` report unpaired legs on stderr, and the
transfers screen (`7`) shows which definition they belong to.
The pairing is derived state, like the tags: it lives in the index, is
recomputed wholesale by `money retag` and after every import, and disappears
with the definition that made it.
## account.toml