Skip to content

v1.16.7: Fix transaction links to budgets, buckets and debts pointing at the wrong item after a delete - #30

Open
gitluis wants to merge 3 commits into
fix-json-export-fieldsfrom
fix-plan-link-ids
Open

gitluis wants to merge 3 commits into
fix-json-export-fieldsfrom
fix-plan-link-ids

Conversation

@gitluis

@gitluis gitluis commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #29 (fix-json-export-fields), in a chain of fixes on top of the Clarity redesign (#16 → #17 → #19 → #20 → #21). Merge in order: #16, #17, #19, #20, #21, then the fixes #24–#38 and #39–#50 in order, then #10, then #23. #18 is a separate patch on master (already merged).
This fix doesn't use any earlier fix's code; it is stacked only so versions and the CHANGELOG merge cleanly.

Summary

You can link a transaction to a budget, bucket or debt in its edit drawer ("Link to a budget, bucket or debt"). The link stored the item's position in its list. Deleting an item moved every item after it up one place, so their links then pointed at the wrong item. Links now point at a stable id instead. Deleting an item, or clearing its list in Data & reset, removes the links to it. Data saved by older versions is migrated when it loads.

Cause

  • The link was a position. showTxDrawer() saved txOverrides[txId].link = { type, idx }, where idx was the item's index in State.budgets, State.buckets or State.debts.
  • Deletes shifted the list. deleteBudget(), deleteBucket() and deleteDebt() spliced the array and left links alone.
  • What you saw: with three budgets, delete the first. The transaction linked to the second now showed the third. The one linked to the third pointed past the end of the list, so the drawer fell back to its first option (now the second). The bucket drawer's "Linked transactions" matched on l.idx === i, so it was wrong in the same way.
  • Who reads links on this stack: only the transaction drawer and the bucket drawer. No budget, debt or Overview footnote reads them, and neither does buildFinancialSummary().

What changed

  • Ids. Every budget, bucket and debt has an id: bud_, bkt_ or dbt_ plus 10 random base-36 characters (newPlanId() and PLAN_LINK_TYPES in core.js).
    • Given on create: saveBudget(), seedBudgets() (Use starter budget), addBucket() (+ New bucket), saveBucket() and saveDebt(), including a debt started from a card.
    • Kept on edit: the save functions keep prev.id. setBudgetLimit() and setCardDetail() change fields in place.
  • Links. A link is now { type, id }.
    • The drawer (showTxDrawer()) lists items by id and saves { type, id }. A link to an item that no longer exists shows as None, and saving drops it. ensurePlanIds() first gives an id to any item that has none (an item added by hand, or by an older version in another tab).
    • New helpers in ui.js: planItem(), linkedTransactions() (the bucket drawer uses it), unlinkPlanItems() and ensurePlanIds().
  • Deletes. deleteBudget(), deleteBucket() and deleteDebt() remove the links to the deleted item, saved as txOverrides. Links to other items stay. A transaction's other edits stay; an edit left with nothing in it is removed.
  • Data & reset. Clear budgets, Clear buckets and Clear debts also remove that type's links (clearPlan() in views-cleanup.js). The button text is unchanged.
  • Migration (IdMigration.migratePlanLinks() in migrate.js).
    • Ids: an item with no id gets <prefix>_m<n>, where n is its position when the migration runs. If that id is already taken, it gets _2, _3 and so on. A duplicate id is replaced the same way. The ids depend only on position, so the same old data gets the same ids wherever it's migrated.
    • Links: each { type, idx } becomes { type, id } of the item it already pointed at, so no link changes target. A link past the end of its list, or with an idx that isn't a whole number, is dropped.
    • Left alone: a link whose list isn't in the object being migrated (an export without that list) waits for the next boot. Links of an unknown type, and links that already have an id, aren't touched.
    • Where it runs: inside migrateState(), so in the same three places as the v1.12.0 account-code migration:
      • Boot (atBoot()). Afterwards, storePlanLinks() writes State's budgets, buckets, debts and txOverrides through lsSet(): localStorage, IndexedDB app_state, and the normal debounced save of finlens-state.json. It writes when the migration changed State, or when a browser copy still has old data because State came from the state file. The four keys are written together, so a copy's links always match its lists.
      • The state file (loadStateFromFile()). This also covers _restoreStateIfBrowserEmpty(). The loaded copy is migrated and a save is scheduled.
      • JSON import. importJsonFile() already calls migrateState(); neither it nor exportAllData() was edited.
    • Running it again changes nothing. A single console line ([FinLens] Plan links: …, in browser storage or … in finlens-state.json) reports what changed. migrateState() also returns codes (the account-code changes), so the old "Renamed old account codes" line still appears only for account codes.
  • AI summary. buildFinancialSummary() doesn't read links or ids, and it is byte-identical to v1.16.0's (see testing). docs/EVAL.md stays valid, and the eval doesn't need a re-run.
  • Docs and version. CLAUDE.md §1, §3, §4.1 (the id fields, the TxOverride shape and link), §8, §9, §20, §22 and the "Last updated" line. A CHANGELOG entry. v1.16.7 in the index.html footer, README.md (twice) and Settings → General. views-db.js: the schema note now says {type,id}.

Not verified

  • Other browsers: nothing was run outside headless Chromium (no desktop Chrome, Edge, Safari or Firefox).
  • A real folder: the state-file path ran against a fake directory handle, through the real loadStateFromFile() and saveStateToFile(). Permission prompts and the Reconnect flow weren't exercised.
  • Two tabs, one on an older version: the older tab can still write { type, idx } links and items without ids. The next boot migrates them by position at that moment. This wasn't tested.
  • The tx_overrides IndexedDB store isn't migrated. No current code writes that store, and links are only read from State.txOverrides. Any old link there stays as it is and is never read.
  • An export with old links but without the matching list: those links are left for the next boot, which resolves them against the lists in State. Only the unit-level check covers this; it wasn't tested end to end.
  • The AI eval wasn't re-run against the API. The summary it sends is byte-identical, so §13 doesn't call for a re-run.
  • The embedded changelog in views-db.js (CHANGELOG_MD) still ends at v1.4.1. No release since has updated it, and this one doesn't either. (v1.16.15: Cleanup — remove unused views-database.js, fix the in-app changelog, update stale wording #38, further up the stack, replaces it with a read of CHANGELOG.md.)
Automated checks: earlier run, not re-run · 19b6c32

Moved unchanged from this PR's "Test results" comment on 2026-11-04; not re-run, so not in the new table format. Originally a description section titled "How it was tested".

Headless Chromium (Playwright) at 1280×900 against samples/ (257 transactions), with the pinned CDN libraries served from npm, on this branch's final commit 19b6c32, chained on #29. Each script ran as NODE_PATH=$(npm root -g) node <script> <repo> <outdir>, from one harness shared by every branch in the stack: the base suites, plus every test added by this PR or by a PR below it (cumulative regression).

Script Result on 19b6c32
test-clarity.js 55/55
test-insights.js 137/137
test-finances.js 126/126
test-plan.js 127/127
boot.js 257 transactions, 24 views, 0 errors
race.js 8 errors, all renderImportLog (the race #18 fixes on master; not in this stack)
test-clear-edits.js (from #24) 47/47
test-rebuild-folder.js (from #25) 57/57
test-partial-import.js (from #26) 47/47
test-json-import.js (from #27) 28/28
test-new-browser-copy.js (from #28) 10/10
test-json-export.js (from #29) 31/31
test-plan-links.js (new in this PR) 60/60

Measured before the chain

By the agent that wrote the fix, on ae9b0a0 (built on ddc8a5f, v1.16.0; then numbered v1.16.4). The AI summary baseline it compares with was captured on ddc8a5f, and the same comparison passes on this branch's commit (test-plan-links.js above).

Headless Chromium (Playwright) against samples/, on commit ae9b0a0. The harness serves the pinned CDN libraries from npm. Every suite passed with the same counts on the base commit ddc8a5f before the change.

Script Result
test-clarity.js 55/55
test-finances.js 126/126
test-plan.js 127/127 (one check edited, below)
test-insights.js 137/137 (one check edited, below)
test-plan-links.js (new) 60/60
boot.js 0 errors
race.js 7 errors, and 8 in another run, all renderImportLog / importLogsBody (fixed by #18). The base commit gave 7. None come from this change.

Existing checks edited, and why:

  • test-plan.js "Budget: Save adds it" compared the whole new budget as JSON. The record now also has an id. The check now compares the record without id (the same string as before) and requires the id to match ^bud_[0-9a-z]{10}$.
  • test-insights.js "General: version line" expected FinLens v1.16.0. It now expects v1.16.7.

test-plan-links.js covers:

  • Create: three budgets, buckets and debts made through the screens (drawers, + New bucket, a debt started from a card). Each gets a unique id in the right format. Edits keep it: the drawer, the inline budget amount, and Settings → Credit cards APR.
  • Link, delete the first item: transactions linked to the 2nd and 3rd of each through the drawer. After the 1st is deleted, the drawer, the stored links and the bucket drawer's list all still show the right items.
  • Delete a linked item: its links are removed, and the transaction's notes stay. Other links are untouched. Deleting an item that has no id removes nothing else. Choosing None in the drawer removes a link.
  • Clear actions: Clear budgets, buckets and debts each remove only their own type's links, in State, localStorage and app_state. Other edits stay.
  • Reloads: links survive a reload after each step, and cleared links don't come back.
  • Old data at boot: browser storage holding { type, idx } data is migrated on reload. Ids become bud_m0…, links point at the items their idx meant, and two past-the-end links are dropped (one emptied edit is removed). localStorage and app_state are rewritten to match, and one log line appears.
  • Old data in finlens-state.json: a fake folder handle, injected before init.js, makes boot go through the real loadStateFromFile(). State is migrated, an older, different browser copy is replaced by State's, and the normal save rewrites the file. Reloading from the rewritten file keeps the links and changes nothing.
  • JSON import: an old-style export imported through Settings → Data & reset gets ids, correct links and a dropped past-the-end link, all saved. A reload changes nothing.
  • Twice: migrateState() on migrated State, on the rewritten file and on the export changes nothing, and a second boot logs nothing.
  • Edge cases: id collisions, duplicate ids, non-object items, a string idx, missing lists, unknown types, and 2,000 newPlanId() ids with no repeats.
  • AI summary: compared with output captured on ddc8a5f (capture-links-base.js, run on an export of that commit). buildFinancialSummary() is byte-identical for All time, This month and Last 3 months, both with no plan items and with three of each plus links. The AI request body for the debt-payoff prompt is byte-identical, and so is the AI Eval's sample summary (AIEval.loadSamples()).

Control: control-delete.js runs the bug's steps through the UI. On ddc8a5f, after deleting B1, the transaction linked to B2 shows B3 and the one linked to B3 shows B2. On this branch they show B2 and B3.

How to reproduce the bug

Run this on the base branch, fix-json-export-fields.

  1. Do the Setup from the testing steps below, but check out fix-json-export-fields instead of fix-plan-link-ids. Use the scratch folder with the three sample CSVs, never your real folder.
  2. Go to Plan → Budget. Click + Add category, name it B1, tick one category, and click Save budget. Repeat for B2 and B3, each with a different category.
  3. Go to Transactions. Open any transaction (T2). Under Link to a budget, bucket or debt, choose Budget → B2. Click Save changes.
  4. Open a different transaction (T3), link it to Budget → B3, and click Save changes.
  5. Go to Plan → Budget. Click the name B1, then Delete → Click again to delete.
  6. Go back to Transactions and open T2, then T3.

What goes wrong:

  • T2 shows B3, not B2.
  • T3 shows B2, not B3: its link points past the end of the list, so the drawer falls back to the first option.
Manual QA steps

Setup

  1. Copy checking_sample.csv, credit_card_sample.csv and savings_sample.csv from samples/ into a new scratch folder (for example FinLens-test-30). Do not use your real folder: this PR rewrites saved state.
  2. git checkout fix-plan-link-ids, then open index.html in Edge.
  3. If FinLens already has data in this browser, go to Settings → Data & reset, type RESET in Type RESET to confirm and click Erase and start over, so you start clean.
  4. On the welcome screen click Pick your CSV folder and choose the scratch folder. Allow read and write access.
  5. Open the date range button (calendar icon, top bar) and choose All time.
  6. Press F12 and keep the Console tab open throughout.

1. Deleting the first budget keeps the other links (the main fix)

  1. Go to Plan → Budget.
  2. Click + Add category. Name it B1, tick one category (any), click Save budget.
  3. Repeat for B2 and B3, each with a different category.
  4. Go to Transactions. Click the description of any transaction (call it T2).
  5. Under Link to a budget, bucket or debt, choose Budget, then B2 in the second list. Click Save changes.
  6. Open a different transaction (T3), link it to Budget → B3, click Save changes.
  7. Go to Plan → Budget. Click the name B1. Click Delete, then Click again to delete.
  8. Go back to Transactions and open T2, then T3.

Expected:

  • T2 shows Budget / B2.
  • T3 shows Budget / B3.

Before this fix: T2 showed B3, and T3 showed B2 (its link pointed past the end of the list, so the drawer fell back to the first option).

2. Deleting a linked item removes only its links

  1. Open T2 again. Type keep me in Notes, leave the link on B2, click Save changes.
  2. Go to Plan → Budget, click B2, then Delete → Click again to delete.
  3. Go to Transactions and open T2.
  4. Open T3.

Expected:

  • T2's link shows None (the second list is hidden). Its note keep me is still there, and the note line still shows under its description in the table.
  • T3 still shows Budget / B3.

3. Buckets: delete the first, check the bucket drawer's list

  1. Go to Plan → Buckets. Click + New bucket, name it K1, click Create bucket.
  2. Do the same for K2 and K3.
  3. In Transactions, link one transaction to Bucket → K2 and another to Bucket → K3 (click Save changes each time). Note their descriptions.
  4. In Plan → Buckets, click the pencil (Edit) on K1, then Delete → Click again to delete.
  5. Click the pencil on K2. Look at Linked transactions. Click Cancel.
  6. Click the pencil on K3 and look at Linked transactions.

Expected:

  • K2's drawer shows Linked transactions · 1 with the transaction you linked to K2.
  • K3's drawer shows Linked transactions · 1 with the one you linked to K3.

Before this fix: after deleting K1, each bucket's list showed the other bucket's transaction (K2 showed nothing or K3's).

4. Debts, including one started from a card

  1. Go to Plan → Debt. If no debts exist, click Add + the card's name (the button under "No debts yet"), then Save debt. Otherwise click + Add debt.
  2. Click + Add debt twice more, giving names D2 and D3, a balance (e.g. 500) and Save debt each time.
  3. Link one transaction to Debt → D2 and one to Debt → D3.
  4. In Plan → Debt, click the pencil on the first debt, then Delete → Click again to delete.
  5. Open the two linked transactions.

Expected:

  • They still show D2 and D3 respectively.

5. Editing an item keeps its links

  1. In Plan → Budget, click the pencil (Edit amount) on B3, change the amount, and click the check to finish.
  2. Click the name B3, rename it to B3 renamed, click Save budget.
  3. Open T3 in Transactions.

Expected:

  • T3 shows Budget / B3 renamed.

6. Data & reset → Clear budgets removes only budget links

  1. Make sure T3 is linked to B3 renamed and has a note and a changed category. Click Save changes.
  2. Make sure at least one transaction is still linked to a bucket (from test 3).
  3. Go to Settings → Data & reset. In Clean up, find Clear budgets and click Clear, then Click again to confirm.
  4. Go to Transactions and open T3.
  5. Open the bucket-linked transaction.

Expected:

  • T3's link shows None, and Budget is no longer in the first list (no budgets exist). Its note and category are kept.
  • The bucket-linked transaction still shows Bucket and the right bucket.

7. Links survive a reload

  1. Press F5.
  2. Open the bucket-linked and debt-linked transactions from tests 3 and 4.
  3. Add a new budget, link a transaction to it, then press F5 again and reopen that transaction.

Expected:

  • All links show the same items as before the reload.
  • Cleared budget links (test 6) did not come back.
  • F12 → Application → Local storage → the file:// entry → finlens_txOverrides: each link reads {"type":"…","id":"bud_…"} (or bkt_ / dbt_), never idx.

8. Old data is migrated on first load

  1. In Settings → Data & reset → Start over, choose Delete finlens-state.json, type RESET and click Erase and start over.
  2. git checkout fix-json-export-fields (the base branch) and reload index.html.
  3. Pick the scratch folder again and set All time.
  4. Add three budgets B1, B2, B3. Link one transaction to B2 and one to B3. Wait about 5 seconds so the state file is saved.
  5. git checkout fix-plan-link-ids and press F5.
  6. Look at the Console.
  7. Open the two linked transactions.
  8. Delete B1 in Plan → Budget and open them again.

Expected:

  • The console shows at least one line starting [FinLens] Plan links: 3 budget, bucket or debt ids added, 2 links rewritten, 0 dropped, ending in browser storage or in finlens-state.json.
  • The two transactions show B2 and B3, before and after B1 is deleted.
  • After about 5 seconds, finlens-state.json in the folder contains "id":"bud_m0", bud_m1, bud_m2.
  • Press F5 again: no Plan links line appears the second time.

9. Old-style JSON backup import

  1. On the base branch (fix-json-export-fields), with budgets and links set up as in test 8, go to Settings → Data & reset and click Export JSON. Save the file.
  2. git checkout fix-plan-link-ids, F5. In Settings → Data & reset → Start over, choose Delete finlens-state.json, type RESET, click Erase and start over. Pick the scratch folder again and set All time.
  3. In Settings → Data & reset, click Import JSON… and choose the exported file.
  4. Open the linked transactions.

Expected:

  • The links show the same budgets as in the export.
  • After F5 they still do.

Please check before merging

https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft


Generated by Claude Code

A transaction's link to a budget, bucket or debt stored the item's list
position ({ type, idx }). Deleting an item moved the ones after it up a
place, so their links pointed at the wrong item.

- Budgets, buckets and debts get a stable id when they're created
  (newPlanId() in core.js) and keep it when edited. Links are { type, id }.
- Deleting an item, or clearing its list in Data & reset, removes the
  links to it (unlinkPlanItems() in ui.js).
- migrate.js: migratePlanLinks() gives older items <prefix>_m<n> ids and
  rewrites each { type, idx } link to the item it pointed at; links past
  the end of the list are dropped. It runs inside migrateState(): at boot
  (with a write-back to localStorage and IndexedDB app_state), when
  finlens-state.json loads, and on JSON import.
- buildFinancialSummary() output is unchanged.
- CLAUDE.md §1, §3, §4.1, §8, §9, §20, §22; CHANGELOG; version 1.16.7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
gitluis pushed a commit that referenced this pull request Nov 2, 2026
…e-tab

Merges cleanup-stale-docs-and-dead-code (#38), the top of the fix chain
stacked on #21, so #10 can merge last. No rebase.

Conflicts:
- Versions: 1.17.0 kept in the footer, README, Settings -> General and
  CLAUDE.md §1. CHANGELOG: 1.17.0, then 1.16.15 ... 1.16.1, then 1.16.0.
- CLAUDE.md: "Last updated" is #10's note followed by the chain's
  history; §3's views-db.js line names both the Database tab and the
  Changelog view that reads CHANGELOG.md.
- views-db.js: #10's rebuilt DB Schema code, with #30's plan link note
  ({type,id}); the Changelog banner keeps "4. CHANGELOG" with #38's
  text and code (loadChangelog(), no embedded copy).
- views-settings.js: #10's tab-bar comment and version line.
- #10's wording about the embedded changelog, which #38 removed, is
  updated in CLAUDE.md §19 and the 1.17.0 entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
…nk-ids

Carries master's v1.10.3-v1.10.5 up the stack: declined answers (#14),
literal single "~" (#15) and the Import Logs race fix (#18), with
clarity-insights' port of #14 to the rebuilt AI tab.

One conflict: CLAUDE.md's "Last updated" line. Kept this branch's
line and added the v1.10.3-v1.10.5 history. The CHANGELOG merged cleanly.
Versions stay 1.16.7. renderImportLog() keeps #18's guards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
@gitluis gitluis added bug Something isn't working data loss Fixes a bug that loses or corrupts saved data labels Nov 3, 2026 — with Claude
@gitluis gitluis added this to the Clarity stack (v1.12.0 → v1.18.1) milestone Nov 3, 2026 — with Claude
…ix-plan-link-ids

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBUZo6LRYpLthSp2PRi

# Conflicts:
#	js/views-settings.js
@gitluis gitluis changed the title v1.16.7: fix transaction links to budgets, buckets and debts pointing at the wrong item after a delete v1.16.7: Fix transaction links to budgets, buckets and debts pointing at the wrong item after a delete Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working data loss Fixes a bug that loses or corrupts saved data

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants