From b8ad25e9abc2c995e13ece9091d1ba37c573eb9b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 03:52:56 +0000 Subject: [PATCH] Remove bank names from the app; neutral account codes with a data migration (v1.12.0) - UI text, default account names, samples and current docs say "bank" / "credit card" - Kinds and schema ids: bank_checking, bank_savings, credit_card; card accounts: card_ - js/migrate.js rewrites data saved by older versions (State, IndexedDB, localStorage, finlens-state.json, JSON exports), including transaction ids, so edits and re-import dedup carry over - AI Eval: renamed samples; published results still load and re-score unchanged - History (earlier CHANGELOG entries, published eval results, docs/archive) unchanged --- CHANGELOG.md | 28 ++ CLAUDE.md | 118 ++++-- README.md | 43 +- index.html | 3 +- js/core.js | 70 ++-- js/db.js | 2 +- js/init.js | 8 + js/migrate.js | 375 ++++++++++++++++++ js/ui.js | 5 +- js/views-ai.js | 4 +- js/views-data.js | 28 +- js/views-db.js | 2 +- js/views-eval.js | 24 +- js/views-forecast.js | 6 +- js/views-invest.js | 4 +- js/views-main.js | 40 +- js/views-plan.js | 6 +- js/views-settings.js | 2 +- samples/README.md | 6 +- ...hecking_sample.csv => checking_sample.csv} | 12 +- ...card_sample.csv => credit_card_sample.csv} | 0 ..._savings_sample.csv => savings_sample.csv} | 0 22 files changed, 629 insertions(+), 157 deletions(-) create mode 100644 js/migrate.js rename samples/{ally_checking_sample.csv => checking_sample.csv} (92%) rename samples/{chase_card_sample.csv => credit_card_sample.csv} (100%) rename samples/{ally_savings_sample.csv => savings_sample.csv} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index fcdb32c..5954dce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,34 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). --- +## [1.12.0] — 2026-11-01 + +### All views +- **No bank names in the app.** Labels, hints, default account names and footnotes say "bank" or "credit card" instead, e.g. **Bank Checking**, **Bank Savings**, **Bank Credit Card (file name)**, "Credit card balances", "Load the CSV exports from your bank". +- **Settings → Import:** the account-type choices are Bank Checking, Bank Savings and Bank Credit Card. A file is guessed as a card from `card` or `credit` in its name. Otherwise its `Transaction Date` + `Post Date` headers identify it, as before. + +### Technical +- **Neutral account codes.** Kinds and `BANK_SCHEMAS` ids are now `bank_checking`, `bank_savings` and `credit_card`. Account ids are `bank_checking`, `bank_savings` and `card_`. Every view's kind checks, `ui.js` colors and the AI summary's cash/debt totals use them. +- **`js/migrate.js` (new) rewrites data saved by older versions** (`IdMigration`, CLAUDE.md §22): + - **What it rewrites:** account ids, kinds and old default names; transaction ids and the edits, balances, limits, labels, account order and file assignments keyed by them; the import log. + - **Where:** State, IndexedDB and localStorage at boot; `finlens-state.json` when it's loaded (then saved back); JSON exports on import. + - **Transaction ids.** They hash the account id, so they change too. The stored rows lack the bank time and post date, so `_rekey()` uses the hash's linearity to swap the account part of each id. The new ids are exactly what a fresh import gives, so re-importing the same CSVs still adds nothing. + - **Edits saved under an old id** that couldn't be moved at boot (for example, kept while transactions were cleared) move on the next CSV import (`adoptOverrides()`). + - **Names you typed are kept.** Only the old default names change. +- **Samples renamed:** `checking_sample.csv`, `savings_sample.csv`, `credit_card_sample.csv`. The card autopay line in the checking sample is now `CREDIT CARD AUTOPAY`. + +### AI Eval +- **`AIEval.SAMPLES` uses the new files.** The checking sample's earlier hash is kept in `earlier`, and results files are now matched by hash instead of file name. Published results still load: re-scoring the v1.10.0, v1.10.1 and v1.10.2 runs gives the same numbers as before. The next run's summary will use the new account names. +- **`buildDataset()`** mirrors the new account ids and names. **The generated EVAL.md** describes the data as synthetic bank checking, savings and credit card CSVs. +- **Matcher:** the bank-name synonym entry is removed. It changed no figure in any published run. + +### Docs +- **README** — supported files described by their columns, not by bank; account kinds, samples and project structure updated. +- **CLAUDE.md** — §3 `migrate.js` and load order; §4, §5, §10, §18 neutral codes, plus a rule against naming banks; §21 sample `earlier` hashes; **§22 Migrations** added. +- **History is unchanged:** earlier CHANGELOG entries, published eval results (`docs/EVAL.md`, `docs/eval-runs/`), `docs/archive/` and the changelog text embedded in `views-db.js`. + +--- + ## [1.10.2] — 2026-10-25 ### AI Analysis diff --git a/CLAUDE.md b/CLAUDE.md index cf7d24a..1d09fa8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ Nothing reaches `master` except through a reviewed pull request. This is the own - **Minor changes may be grouped** into a single branch and PR — typos, doc wording, small refactors, version or changelog housekeeping. - **Revisions requested in review go on that PR's own branch** (new commits), not into a new PR. - **Never commit directly to `master`.** Never force-push a branch that has an open PR. -- **Branch names:** short, kebab-case, describing the change, e.g. `fix-chase-reimport-duplicates`, `data-cleanup-and-reset`, `docs-branch-pr-workflow`. +- **Branch names:** short, kebab-case, describing the change, e.g. `fix-card-reimport-duplicates`, `data-cleanup-and-reset`, `docs-branch-pr-workflow`. ### What every PR includes @@ -59,9 +59,9 @@ Until then, this section is the rule. FinLens is a **single-origin, zero-build, vanilla JavaScript personal finance dashboard** that runs entirely in the browser. There is no server, no npm, no bundler, no framework, and no TypeScript. The entry point is `index.html`; everything else is a plain `.js` file in the `js/` folder. -**Current version:** v1.10.2 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release). +**Current version:** v1.12.0 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release). -**What it does:** Imports CSV exports from Ally Bank (Checking + Savings) and Chase credit cards, parses and normalizes them into a unified transaction model, and renders a multi-tab financial dashboard with budgeting, debt tracking, savings forecasting, investment planning, and Claude-powered AI analysis. +**What it does:** Imports CSV exports from a bank (checking + savings) and credit cards, parses and normalizes them into a unified transaction model, and renders a multi-tab financial dashboard with budgeting, debt tracking, savings forecasting, investment planning, and Claude-powered AI analysis. --- @@ -94,13 +94,13 @@ FinLens/ ├── CLAUDE.md ← This file ├── CHANGELOG.md ← Version history (update on every release) ├── data/ ← CSV exports (not committed to git) -│ ├── ally_checking_transactions.csv -│ ├── ally_savings_transactions.csv -│ └── chase_transactions.csv +│ ├── checking_transactions.csv +│ ├── savings_transactions.csv +│ └── credit_card_transactions.csv ├── samples/ ← Synthetic CSVs (fake data) for demos, manual testing and the AI eval — committed -│ ├── ally_checking_sample.csv -│ ├── ally_savings_sample.csv -│ └── chase_card_sample.csv +│ ├── checking_sample.csv +│ ├── savings_sample.csv +│ └── credit_card_sample.csv ├── docs/ │ ├── EVAL.md ← AI Analysis grounding eval: method + results (exported by the AI Eval view) + hand-written Runs table │ ├── eval-results.json ← Raw answers + per-figure classifications for that run @@ -112,6 +112,7 @@ FinLens/ ├── core.js ← State, helpers, CSV parsing, date range, account filter ├── aggregation.js ← Pure data aggregation: sums, groupings, recurring detection ├── db.js ← IndexedDB layer (finlens_db) + ├── migrate.js ← Rewrites data saved by older versions: account codes (§22) ├── ui.js ← View registry, drawer, theme, chart helpers, CRUD helpers ├── views-main.js ← Overview, Transactions, Income, Bills, Spending, Transfers ├── views-plan.js ← Budgeting, Savings Buckets, Debt Tracker, Trends @@ -130,7 +131,7 @@ FinLens/ ### Script load order (matters — no bundler enforces it) ``` -core.js → aggregation.js → db.js → ui.js → views-main.js → views-plan.js → views-invest.js +core.js → aggregation.js → db.js → migrate.js → ui.js → views-main.js → views-plan.js → views-invest.js → views-forecast.js → views-ai.js → views-data.js → views-settings.js → views-cleanup.js → views-db.js → views-eval.js → init.js ``` @@ -188,13 +189,13 @@ Transactions are created by `mkTx()` in `core.js` and never mutated directly — amount: number, // Positive = income/credit, Negative = expense/debit categories: string[], // Array; first element accessed via get category() get category(), // Accessor: returns categories[0] || 'Other' - account: string, // accountId (e.g. 'ally_checking', 'ally_savings', 'chase_...') + account: string, // accountId (e.g. 'bank_checking', 'bank_savings', 'card_...') type: 'debit' | 'credit' | 'transfer' | 'payment', isRecurring: boolean, isBill: boolean, isSubscription: boolean, notes: string, - balance: null, // Always null — Ally does NOT export running balance; balance is + balance: null, // Always null — checking/savings exports have no running balance; balance is // computed from manually entered starting balance + transactions _originalDesc: string, // Immutable original CSV description } @@ -204,9 +205,9 @@ Transactions are created by `mkTx()` in `core.js` and never mutated directly — ```js { - id: string, // e.g. 'ally_checking', 'ally_savings', 'chase_my_card_csv' + id: string, // e.g. 'bank_checking', 'bank_savings', 'card_my_card_csv' name: string, // Display name (user-editable via Data tab) - kind: 'ally_checking' | 'ally_savings' | 'chase' | 'unknown', + kind: 'bank_checking' | 'bank_savings' | 'credit_card' | 'unknown', balance: null, // Not used directly — use currentBalances() or periodEndBalance() limit: null, // Not used directly — use State.manualBalances[id+'_limit'] sourceFile: string, @@ -288,7 +289,7 @@ loadStateFromFile() → found? | CSS classes | `kebab-case` | `.card`, `.amt-pos`, `.chart-wrap`, `.acct-group` | | State keys | `camelCase` | `State.txOverrides`, `State.manualBalances` | | localStorage keys | `camelCase` without prefix | `'budgets'`, `'txOverrides'`, `'apiKey'` | -| Account IDs | `snake_case` | `'ally_checking'`, `'ally_savings'`, `'chase_card_name'` | +| Account IDs | `snake_case` | `'bank_checking'`, `'bank_savings'`, `'card_file_name'` | | View IDs | `kebab-case` | `'overview'`, `'forecast-invest'`, `'bills'` | | File names | `kebab-case` with module prefix | `views-plan.js`, `views-settings.js` | @@ -474,13 +475,15 @@ clearAllData() // = DataCleanup.startOver('archive') — f | Account | Kind | Detection | |---|---|---| -| Ally Checking | `ally_checking` | Filename contains `check` OR has `Type`+`Amount` columns | -| Ally Savings | `ally_savings` | Filename contains `saving` | -| Chase Credit Card | `chase` | Filename contains `chase`/`card`/`credit` OR has `Transaction Date` column | +| Bank Checking | `bank_checking` | Filename contains `check` OR has `Time`+`Type`+`Amount` columns | +| Bank Savings | `bank_savings` | Filename contains `saving` | +| Bank Credit Card | `credit_card` | Filename contains `card`/`credit` OR has `Transaction Date`+`Post Date` columns | + +FinLens names no bank in the UI, the code, sample data or current docs. Describe a format by its columns, not by who exports it. History stays as written: earlier CHANGELOG entries, published eval results and `docs/archive/`. Data saved before v1.12.0 used bank-named codes; only `migrate.js` lists them (§22). ### Actual CSV column structure -**Ally Checking & Savings** — columns: `Date`, `Time`, `Amount`, `Type`, `Description` +**Bank Checking & Savings** — columns: `Date`, `Time`, `Amount`, `Type`, `Description` | Column | Format | Notes | |---|---|---| @@ -490,26 +493,26 @@ clearAllData() // = DataCleanup.startOver('archive') — f | `Type` | string | `Withdrawal` or `Deposit` | | `Description` | string | Payee / memo text | -**Chase Credit Card** — columns: `Transaction Date`, `Post Date`, `Description`, `Category`, `Type`, `Amount`, `Memo` +**Bank Credit Card** — columns: `Transaction Date`, `Post Date`, `Description`, `Category`, `Type`, `Amount`, `Memo` | Column | Format | Notes | |---|---|---| | `Transaction Date` | YYYY-MM-DD | Date charge occurred — no time component | | `Post Date` | MM/DD/YYYY | Date charge settled — may differ by 1–3 days; **different format from Transaction Date in the same file** | | `Description` | string | Merchant name | -| `Category` | string | Chase-assigned category — used for initial auto-categorization | +| `Category` | string | Bank-assigned category — used for initial auto-categorization | | `Type` | string | `Sale`, `Payment`, or `Return` | | `Amount` | number | Negative = charge, Positive = payment/refund | | `Memo` | string | Always empty in practice — **ignored entirely** | -### Critical: Ally CSV headers have leading spaces +### Critical: checking/savings CSV headers have leading spaces -Ally exports headers like `" Date", " Time", " Amount", " Type", " Description"` — each header has a leading space. PapaParse is configured with `transformHeader: h => h.trim()`. **Do not remove this.** +The checking/savings export has headers like `" Date", " Time", " Amount", " Type", " Description"` — each header has a leading space. PapaParse is configured with `transformHeader: h => h.trim()`. **Do not remove this.** ### Amount sign convention -- **Negative** = money leaving the account (withdrawal for Ally; charge for Chase) -- **Positive** = money entering the account (deposit for Ally; payment/refund for Chase) +- **Negative** = money leaving the account (withdrawal from checking/savings; charge on a card) +- **Positive** = money entering the account (deposit to checking/savings; payment/refund on a card) This is consistent across all account types. @@ -519,14 +522,16 @@ The deterministic `id` for each transaction is computed per source to survive re | Source | Hash inputs | Tiebreaker rationale | |---|---|---| -| Ally Checking | `date \| time \| description \| amount \| accountId` | `Time` is bank-assigned (HH:MM:SS), always meaningful — collision risk is near zero | -| Ally Savings | `date \| time \| description \| amount \| accountId` | Same as checking | -| Chase | `transactionDate \| postDate \| description \| amount \| accountId` | No timestamp; post date disambiguates most cases | +| Bank Checking | `date \| time \| description \| amount \| accountId` | `Time` is bank-assigned (HH:MM:SS), always meaningful — collision risk is near zero | +| Bank Savings | `date \| time \| description \| amount \| accountId` | Same as checking | +| Credit Card | `transactionDate \| postDate \| description \| amount \| accountId` | No timestamp; post date disambiguates most cases | + +The account id comes last on purpose: `migrate.js` relies on it to rename account ids without the original rows (§22). -**Identical rows (occurrence suffix):** Truly identical Chase rows (same transaction date, post date, description, and amount) do occur in practice — e.g. multiple TAXMANIA charges on the same day for the same amount. `parseCsvFile()` counts them **within the file**: the first keeps the base hash, the 2nd gets `_2`, the 3rd `_3` (via the `occurrence` argument of `normalizeRow()` → `mkTx()`). The suffix is part of the ID everywhere — memory, IndexedDB and `txOverrides`. Because identical rows are interchangeable, file order is enough to make the suffix stable across re-uploads. +**Identical rows (occurrence suffix):** Truly identical credit card rows (same transaction date, post date, description, and amount) do occur in practice — e.g. multiple TAXMANIA charges on the same day for the same amount. `parseCsvFile()` counts them **within the file**: the first keeps the base hash, the 2nd gets `_2`, the 3rd `_3` (via the `occurrence` argument of `normalizeRow()` → `mkTx()`). The suffix is part of the ID everywhere — memory, IndexedDB and `txOverrides`. Because identical rows are interchangeable, file order is enough to make the suffix stable across re-uploads. -- Suffixes are allowed when `schema.allowOccurrenceSuffix` is true, or when it's unset and the schema has no `time` column (custom schemas). Ally sets it to `false`: with a bank-assigned `Time`, an identical row is a true duplicate and only the first copy is kept. -- **Never assign suffixes on a database collision.** Up to v1.8.0, `DB.importTransactions()` did, which re-inserted every row of a re-uploaded Chase file as an `_2` copy. +- Suffixes are allowed when `schema.allowOccurrenceSuffix` is true, or when it's unset and the schema has no `time` column (custom schemas). The checking and savings schemas set it to `false`: with a bank-assigned `Time`, an identical row is a true duplicate and only the first copy is kept. +- **Never assign suffixes on a database collision.** Up to v1.8.0, `DB.importTransactions()` did, which re-inserted every row of a re-uploaded credit card file as an `_2` copy. **Re-upload safety:** IDs are final when they reach `DB.importTransactions()`, which reads the stored keys once and skips any ID it already holds. Re-uploading a file — or a newer export with rows appended — inserts only genuinely new rows. On each import it also deletes leftover copies from the old bug: a suffixed row whose base transaction is in the file but whose exact ID is not. Same-day identical rows always appear together in a bank export, so the file is authoritative for how many copies exist. The import results card reports these as "leftover duplicate copies removed". @@ -547,7 +552,7 @@ The deterministic `id` for each transaction is computed per source to survive re ## 11.1 Payment Type -`type='payment'` is set in `normalizeRow()` when `rawType` equals `"Payment"` (case-insensitive). This occurs on Chase credit card uploads where a payment toward the card balance is recorded as a positive-amount transaction with Chase `Type = "Payment"`. Payment transactions are **excluded from income sums** (`sumIncome()` filters them out) to avoid double-counting. They are distinct from `'credit'` (which represents purchase refunds/credits) and `'transfer'` (which represents inter-account moves). +`type='payment'` is set in `normalizeRow()` when `rawType` equals `"Payment"` (case-insensitive). This occurs on credit card uploads where a payment toward the card balance is recorded as a positive-amount transaction with `Type = "Payment"`. Payment transactions are **excluded from income sums** (`sumIncome()` filters them out) to avoid double-counting. They are distinct from `'credit'` (which represents purchase refunds/credits) and `'transfer'` (which represents inter-account moves). --- @@ -788,16 +793,16 @@ Also update **Current version** in §1 of this file. Never close out a change wi | Kind | Description | Balance source | |---|---|---| -| `ally_checking` | Ally Bank Checking | Computed from transactions + manually entered starting balance (Ally does not export running balance) | -| `ally_savings` | Ally Bank Savings | Computed from transactions + manually entered starting balance (Ally does not export running balance) | -| `chase` | Chase credit card(s) | Manual override in Data tab | +| `bank_checking` | Bank Checking | Computed from transactions + manually entered starting balance (the export has no running balance) | +| `bank_savings` | Bank Savings | Computed from transactions + manually entered starting balance (the export has no running balance) | +| `credit_card` | Bank Credit Card(s) | Manual override in Data tab | | `unknown` | Any other CSV | Computed from transactions + initial balance | -Multiple Chase card files can be loaded simultaneously. Each gets a unique `accountId` derived from the filename: `chase_` + sanitized filename. +Multiple credit card files can be loaded simultaneously. Each gets a unique `accountId` derived from the filename: `card_` + sanitized filename, and a default name `Bank Credit Card ()`. --- -*Last updated: v1.10.2 — 2026-10-25 (§13 summary states its dates; §21 per-month derivations; v1.10.1: §13 `AI_MAX_TOKENS`, thinking and cut-off answers; v1.10.0: §21 AI Eval added; §13 `callClaude()` raw mode; v1.9.6: §14 folder access lasts until the last tab closes, not one page load; v1.9.5: §7 chart guard; v1.9.4: views-db.js changelog reads CRLF checkouts; v1.9.3: §14 folder permission: re-request on click, Reconnect banner, browser copy wins; v1.9.2: §0 branch, PR and approval workflow added; v1.9.1: §4.5 rehydrate transactions loaded from JSON; v1.9.0: §20 Data & Reset added; v1.8.1: §10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)* +*Last updated: v1.12.0 — 2026-11-01 (bank-neutral account codes, names, samples and docs; §22 `migrate.js` added; §3, §4, §5, §10, §18, §21 updated; v1.10.2: §13 summary states its dates; §21 per-month derivations; v1.10.1: §13 `AI_MAX_TOKENS`, thinking and cut-off answers; v1.10.0: §21 AI Eval added; §13 `callClaude()` raw mode; v1.9.6: §14 folder access lasts until the last tab closes, not one page load; v1.9.5: §7 chart guard; v1.9.4: views-db.js changelog reads CRLF checkouts; v1.9.3: §14 folder permission: re-request on click, Reconnect banner, browser copy wins; v1.9.2: §0 branch, PR and approval workflow added; v1.9.1: §4.5 rehydrate transactions loaded from JSON; v1.9.0: §20 Data & Reset added; v1.8.1: §10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)* --- @@ -815,7 +820,7 @@ The full IndexedDB implementation is live. See **`docs/archive/INDEXEDDB_PLAN.md - **Transfer Keywords** — `State.transferKeywords` is user-editable from Settings. `detectTransfers()` builds its regex from this list. ### Adding a new bank -Add a new object to `BANK_SCHEMAS` in `core.js`. No other code changes needed if the bank follows standard column conventions (`date`, `amount`, `description`). For non-standard conventions use: `amountSign: 'inverted'`, custom `columns` map, `dateFormat` (`'YYYY-MM-DD'` | `'MM/DD/YYYY'` | `'DD/MM/YYYY'`), and `postDateFormat` if the post-date column uses a different format than the primary date column (see Chase schema). +Add a new object to `BANK_SCHEMAS` in `core.js`. No other code changes needed if the bank follows standard column conventions (`date`, `amount`, `description`). For non-standard conventions use: `amountSign: 'inverted'`, custom `columns` map, `dateFormat` (`'YYYY-MM-DD'` | `'MM/DD/YYYY'` | `'DD/MM/YYYY'`), and `postDateFormat` if the post-date column uses a different format than the primary date column (see the `credit_card` schema). ### Deferred - Column Mapping UI for truly unknown CSV formats (show a modal when `detectSchema()` returns null). @@ -869,7 +874,7 @@ A developer-only view (`showView('ai-eval')`) that measures how well AI Analysis ### Rules -- **Samples only, never real data.** The eval reads only the three files in `samples/`, and only if their SHA-256 (after normalizing line endings) matches `AIEval.SAMPLES`. If you change a sample file on purpose, update its hash there (the error message shows the new one) and re-run the eval. +- **Samples only, never real data.** The eval reads only the three files in `samples/`, and only if their SHA-256 (after normalizing line endings) matches `AIEval.SAMPLES`. If you change a sample file on purpose, update its hash there (the error message shows the new one), add the old hash to that sample's `earlier` list so published results still load (results files are matched by hash, not file name), and re-run the eval. - **Sandbox, synchronously.** `_withSampleState(fn)` swaps a fresh, sample-only set of `State` keys in, runs `fn`, and restores every key in `finally`. `fn` must be synchronous — no `await` — so no render, `lsSet()` or debounced save can run while sample data is in `State`. If `buildFinancialSummary()`, `normalizeRow()`, `mkTx()` or `detectTransfers()` start reading a new `State` key, add it to the sandbox or the user's value will leak into the eval. - **Same parsing as an import.** `buildDataset()` mirrors `parseCsvFile()` (schema detection, account ids, occurrence suffixes) without touching IndexedDB. If `parseCsvFile()` changes, mirror it here; the sandbox summary must equal what a normal import of `samples/` produces. - **Same request as the AI tab** — `callClaude()` raw mode (§13). Never build a second request path. @@ -880,3 +885,38 @@ A developer-only view (`showView('ai-eval')`) that measures how well AI Analysis - **Publishing a new run:** move the current `docs/EVAL.md` and `docs/eval-results.json` to `docs/eval-runs/v/` unchanged except for a one-line "Archived" banner, its JSON link label, and relative links the move would break (`eval-runs/vX/…` becomes `../vX/…`). Put the new results JSON in `docs/`, generate EVAL.md by loading it in the view (**Load results JSON** → **Download EVAL.md**), then add the hand-written sections before *Method*: the **Runs** table (one column per run: `max_tokens`, cut-off answers, tokens, figures, grounded, derived, traceable, unsupported), what changed between runs, and *Changes made after the run*. Keep README's Evaluation numbers in step. - **Changing the matcher after a run:** fix only bugs against the method EVAL.md states. Record each fix in EVAL.md's "Changes made after the run" with before and after numbers. Never add a rule just because it raises the score on answers you've already seen. - **Classification** (`classifyText()`): grounded → explicit equation (a wrong one is a math error) → standard derivations (`_candidates()`, each with context keys) → restatements, correct equations and same-line arithmetic on anchored figures → forecast (the 12-month prediction prompt only) or unsupported. When adding a derivation, give it context keys; check the chance-match rate in the report doesn't rise noticeably — it is the matcher's false-positive rate and is published alongside the headline. + +--- + +## 22. Migrations (migrate.js) + +Data saved by older versions is rewritten when it's loaded. Everything lives on the `IdMigration` namespace object, loaded after `db.js`. + +### v1.12.0: account codes + +Up to v1.10.x the account kinds, `BANK_SCHEMAS` ids, account ids and default account names were named after banks. Now they are: + +| What | New | +|---|---| +| Kinds and schema ids | `bank_checking`, `bank_savings`, `credit_card` | +| Account ids | `bank_checking`, `bank_savings`, `card_` | +| Default names | `Bank Checking`, `Bank Savings`, `Bank Credit Card ()` | + +The old codes and names are listed in `migrate.js` and nowhere else in the code or current docs. They stay there so browser storage, `finlens-state.json`, its backups and JSON exports from older versions still load. + +**Where it runs** +- **Boot** (`init.js`): `IdMigration.atBoot()`, after State is loaded. It rewrites State, then IndexedDB (`transactions`, `tx_overrides`, `accounts`, `import_log`, `app_state`, all in one transaction) and localStorage. It only reads the `transactions` store when the `accounts` store still has an old id. +- **The state file** (`loadStateFromFile()`): it rewrites the loaded copy and schedules a save, so the file on disk gets the new codes once write access allows. +- **JSON import** (`importJsonFile()`): it rewrites the export, and its edits move to the current ids. +- **CSV import** (`loadFiles()`): `adoptOverrides()` moves edits still saved under an old id (for example, kept while transactions were cleared) to the new id. + +Each step is idempotent: on new data nothing matches and nothing is written. + +**Transaction ids.** The id hashes the account id (§10), so renaming an account changes its transactions' ids. Stored transactions lack the bank time and post date, so the id can't be recomputed from them. `hash()` is linear instead (h = 31·h + c mod 2³²), so `_rekey()` takes the prefix hash out of the old id and extends it with the new account id. The id keeps only |h|, so there are two candidates. `_fits()` keeps the one that matches the transaction's date, description and amount, with a time or post date found by search. If neither or both match, the transaction keeps its old id, and the count is logged. That didn't happen in testing (20,000 random ids, plus the samples). + +**Rules** +- **Changing `hash()` or the hash-key layout in `mkTx()`** changes every transaction id. It breaks re-import dedup and every edit. Don't, unless you add a migration for it here. +- **Renaming a code again** needs a new mapping here. Old data must still load. +- **Names the user typed are never changed.** Only the old default names are renamed. +- **File names are user data.** An account id derived from a file name keeps whatever that name contains. To hide a name, relabel the account; renaming the CSV file creates a new account on the next import. +- **No new storage.** It only rewrites places listed in §20. diff --git a/README.md b/README.md index b81e018..e75f663 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ > A zero-install, browser-native finance dashboard. Drop in your bank CSVs, get instant clarity on your money. -**Version:** v1.10.2  ·  **Stack:** Vanilla JS, HTML, CSS  ·  **Install:** None +**Version:** v1.12.0  ·  **Stack:** Vanilla JS, HTML, CSS  ·  **Install:** None --- ## What It Does -FinLens turns raw CSV exports from Ally Bank and Chase into a fully interactive personal finance dashboard — no account linking, no cloud sync, no subscriptions. Your data never leaves your machine. +FinLens turns raw CSV exports from your bank into a fully interactive personal finance dashboard — no account linking, no cloud sync, no subscriptions. Your data never leaves your machine. Load your CSV files once, and FinLens gives you: @@ -38,15 +38,15 @@ No server. No install. No `npm install`. Just open the file. **2. Load your data** -Go to **Settings → Import** and click **Pick a Folder**. Point it at a folder containing your CSV exports: +Go to **Settings → Import** and click **Pick a Folder**. Point it at a folder containing your bank's CSV exports (usually under the account's transactions or activity page → Download / Export → CSV): -| Bank | How to export | +| Account | Columns in the CSV | |---|---| -| Ally Bank Checking | Account → Transactions → Export → CSV | -| Ally Bank Savings | Account → Transactions → Export → CSV | -| Chase Credit Card | Account → Download → CSV (Activity) | +| Bank checking | `Date`, `Time`, `Amount`, `Type`, `Description` | +| Bank savings | Same as checking | +| Bank credit card | `Transaction Date`, `Post Date`, `Description`, `Category`, `Type`, `Amount` | -FinLens auto-detects which file is which based on filename and column headers. You can also assign them manually if the auto-detection misses. +FinLens auto-detects which file is which based on filename and column headers. Checking and savings exports have the same columns, so keep `checking` or `savings` in their file names (or assign them manually on import). **No bank exports handy?** Pick the [`samples/`](samples/) folder instead — three synthetic CSVs (fake data) covering May–Oct 2026. Set the date range to **All Time** to see everything. @@ -56,13 +56,13 @@ Use the sidebar to navigate between views. The date range picker in the top bar --- -## Supported Banks +## Supported Accounts | Account Type | Kind | Notes | |---|---|---| -| Ally Checking | `ally_checking` | Balance computed from transactions + manually entered starting balance | -| Ally Savings | `ally_savings` | Balance computed from transactions + manually entered starting balance | -| Chase Credit Card | `chase` | Multiple card files supported simultaneously | +| Bank Checking | `bank_checking` | Balance computed from transactions + manually entered starting balance | +| Bank Savings | `bank_savings` | Balance computed from transactions + manually entered starting balance | +| Bank Credit Card | `credit_card` | Multiple card files supported simultaneously | | Other CSV | `unknown` | Any CSV with Date, Description, Amount columns — set initial balance manually in Data tab | --- @@ -103,7 +103,7 @@ FinLens stores all your data — budgets, bills, transaction edits, settings, AI ## Features In Depth ### Overview -Net worth snapshot, per-account balance cards with sparklines, cash flow chart, upcoming bills list, and top Chase transactions for the selected period. +Net worth snapshot, per-account balance cards with sparklines, cash flow chart, upcoming bills list, and top credit card transactions for the selected period. ### Transactions Full transaction table with search, category filter, type filter (Income / Expense / Transfer), sortable columns, and pagination (50 per page). Click any row to open an edit drawer — update description, categories, type, notes, and flags (Bill, Recurring, Subscription). Transaction Rules let you auto-flag transactions by keyword (e.g. "Netflix → Subscription"). @@ -200,13 +200,13 @@ FinLens/ ├── CHANGELOG.md ← Full version history ├── CLAUDE.md ← Developer/AI context for this codebase ├── data/ ← Drop your CSV files here (not committed to git) -│ ├── ally_checking_transactions.csv -│ ├── ally_savings_transactions.csv -│ └── chase_transactions.csv +│ ├── checking_transactions.csv +│ ├── savings_transactions.csv +│ └── credit_card_transactions.csv ├── samples/ ← Synthetic CSVs (fake data) for trying the app and the AI eval -│ ├── ally_checking_sample.csv -│ ├── ally_savings_sample.csv -│ └── chase_card_sample.csv +│ ├── checking_sample.csv +│ ├── savings_sample.csv +│ └── credit_card_sample.csv ├── docs/ │ ├── EVAL.md ← AI Analysis grounding eval: method, results, and a table comparing runs │ ├── eval-results.json ← Raw answers and per-figure classifications from that run @@ -215,6 +215,7 @@ FinLens/ ├── core.js ← State, helpers, CSV parsing, bank schema registry ├── aggregation.js ← Pure data aggregation: sums, groupings, recurring detection ├── db.js ← IndexedDB layer (finlens_db) + ├── migrate.js ← Rewrites data saved by older versions (account codes, v1.12.0) ├── ui.js ← View engine, drawer, chart helpers, CRUD ├── views-main.js ← Overview, Transactions, Income, Bills, Spending, Transfers ├── views-plan.js ← Budgeting, Savings Buckets, Debt Tracker, Trends @@ -239,7 +240,7 @@ FinLens/ **Category rules** — go to **Spending → Category Rules** to teach FinLens your merchants. Rules apply across all future imports. Your category list is managed under **Database → Categories**. -**Multiple Chase cards** — load as many Chase CSV files as you want. Each gets its own account card and can be filtered independently. +**Multiple credit cards** — load as many credit card CSV files as you want. Each gets its own account card and can be filtered independently. **Cleaning up or starting over** — **Settings → 🧹 Data & Reset** shows what FinLens has stored and lets you: - **Clean up imported data:** clear imported transactions, the import log or your transaction edits. @@ -260,4 +261,4 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history. --- -*FinLens v1.10.2 — Built for one person's finances, designed to be useful for anyone's.* +*FinLens v1.12.0 — Built for one person's finances, designed to be useful for anyone's.* diff --git a/index.html b/index.html index 94b63f6..135b2b4 100644 --- a/index.html +++ b/index.html @@ -326,7 +326,7 @@
⚙️ Settings
@@ -391,6 +391,7 @@

Transaction Detail

+ diff --git a/js/core.js b/js/core.js index 6cdc5f2..01d8c51 100644 --- a/js/core.js +++ b/js/core.js @@ -139,6 +139,9 @@ async function loadStateFromFile() { .filter(t => !isNaN(t.date)) .sort((a, b) => b.date - a.date); } + // A file written before v1.12.0 (or an old backup) uses the old account codes: + // rewrite them (migrate.js) and save the file again once it's loaded. + if (IdMigration.migrateState(loaded).changed.length) _saveStateDebounced(State); console.log('[FinLens] State loaded from finlens-state.json'); return loaded; } catch(e) { @@ -382,8 +385,8 @@ const DEFAULT_TRANSFER_KEYWORDS = ['transfer','zelle','ach','venmo','paypal','co // Data-driven normalizer config. Adding a new bank = adding a new object here (or via custom schema UI). const BANK_SCHEMAS = [ { - id: 'ally_checking', - name: 'Ally Bank Checking', + id: 'bank_checking', + name: 'Bank Checking', kind: 'checking', detect: (headers) => headers.includes('Time') && @@ -404,15 +407,15 @@ const BANK_SCHEMAS = [ dateFormat: 'YYYY-MM-DD', }, { - id: 'ally_savings', - name: 'Ally Bank Savings', + id: 'bank_savings', + name: 'Bank Savings', kind: 'savings', detect: (headers) => headers.includes('Time') && headers.includes('Type') && headers.includes('Amount') && !headers.includes('Transaction Date'), - // Note: ally_checking and ally_savings share the same CSV format. + // Note: bank_checking and bank_savings share the same CSV format. // Filename check ('saving' in name) runs first in detectSchema(). columns: { date: 'Date', @@ -428,8 +431,8 @@ const BANK_SCHEMAS = [ dateFormat: 'YYYY-MM-DD', }, { - id: 'chase', - name: 'Chase Credit Card', + id: 'credit_card', + name: 'Bank Credit Card', kind: 'credit', detect: (headers) => headers.includes('Transaction Date') && @@ -439,7 +442,7 @@ const BANK_SCHEMAS = [ postDate: 'Post Date', // Used in hash description: 'Description', amount: 'Amount', - category: 'Category', // Chase-assigned; used for initial auto-categorization + category: 'Category', // Bank-assigned; used for initial auto-categorization type: 'Type', // 'Sale' | 'Payment' | 'Return' }, amountSign: 'standard', @@ -454,12 +457,12 @@ const BANK_SCHEMAS = [ // Returns the best-matching schema for a given set of (already-trimmed) headers + filename. function detectSchema(headers, filename) { const fn = (filename || '').toLowerCase(); - // Filename-based disambiguation for Ally (checking vs savings share identical column structure) - if (fn.includes('saving')) return BANK_SCHEMAS.find(s => s.id === 'ally_savings') || null; - if (fn.includes('check') && !fn.includes('checkout')) return BANK_SCHEMAS.find(s => s.id === 'ally_checking') || null; - // Chase by filename - if (fn.includes('chase') || fn.includes('card') || fn.includes('credit')) { - const s = BANK_SCHEMAS.find(s => s.id === 'chase'); + // Filename-based disambiguation for bank checking vs savings (identical column structure) + if (fn.includes('saving')) return BANK_SCHEMAS.find(s => s.id === 'bank_savings') || null; + if (fn.includes('check') && !fn.includes('checkout')) return BANK_SCHEMAS.find(s => s.id === 'bank_checking') || null; + // Credit card by filename (otherwise its Transaction Date + Post Date headers identify it below) + if (fn.includes('card') || fn.includes('credit')) { + const s = BANK_SCHEMAS.find(s => s.id === 'credit_card'); if (s) return s; } // Header-based detection for all schemas (built-in + custom) @@ -471,7 +474,7 @@ function detectSchema(headers, filename) { } /* ---------- GENERIC ROW NORMALIZER ---------- */ -// Replaces normalizeAllyRow() and normalizeChaseRow(). +// Replaces the per-bank row normalizers of earlier versions. // `occurrence` (1-based) distinguishes truly identical rows within one file — see parseCsvFile(). function normalizeRow(row, schema, accountId, occurrence = 1) { const get = (col) => col && row[col] !== undefined ? row[col].toString().trim() : ''; @@ -560,8 +563,9 @@ function applyTxRulesToAll() { function mkTx(o) { const dateStr = o.date.toISOString().slice(0,10); // Per-source hash strategy (see CLAUDE.md §10): - // Ally: date|time|desc|amount|account — Time is bank-assigned (HH:MM:SS), eliminates collision risk - // Chase: txDate|postDate|desc|amount|account — post date disambiguates same-day identical charges + // Bank checking/savings: date|time|desc|amount|account — Time is bank-assigned (HH:MM:SS), eliminates collision risk + // Credit card: txDate|postDate|desc|amount|account — post date disambiguates same-day identical charges + // migrate.js relies on this layout (the account id last) to rename account ids. let hashKey; if (o.time) { hashKey = dateStr+'|'+o.time+'|'+o.description+'|'+o.amount+'|'+o.account; @@ -599,7 +603,7 @@ function parseCsvFile(file, forcedKind) { Papa.parse(file, { header: true, skipEmptyLines: true, - transformHeader: h => h.trim(), // KEY: trim whitespace from Ally CSV headers (they have leading spaces) + transformHeader: h => h.trim(), // KEY: trim whitespace from bank CSV headers (checking/savings exports have leading spaces) complete: async (res) => { const rows = res.data || []; const headers = rows.length ? Object.keys(rows[0]) : []; @@ -616,9 +620,9 @@ function parseCsvFile(file, forcedKind) { // Final fallback: header content matching const lk = headers.map(h => h.toLowerCase()); if (lk.includes('transaction date') || lk.includes('post date')) - schema = BANK_SCHEMAS.find(s => s.id === 'chase'); + schema = BANK_SCHEMAS.find(s => s.id === 'credit_card'); else if (lk.includes('time') && lk.includes('type') && lk.includes('amount')) - schema = BANK_SCHEMAS.find(s => s.id === 'ally_checking'); + schema = BANK_SCHEMAS.find(s => s.id === 'bank_checking'); } // Unknown schema — skip with warning (Column Mapping UI is a future enhancement) if (!schema) { @@ -629,15 +633,15 @@ function parseCsvFile(file, forcedKind) { const kind = schema.id; - // Build accountId and display name + // Build accountId and display name (migrate.js maps the ids older versions used) let accountId, accountName; - if (kind === 'chase') { - accountId = 'chase_' + file.name.replace(/\.csv$/i,'').toLowerCase().replace(/[^a-z0-9]+/g,'_'); - accountName = 'Chase (' + file.name.replace(/\.csv$/i,'') + ')'; - } else if (kind === 'ally_savings') { - accountId = 'ally_savings'; accountName = 'Ally Savings'; - } else if (kind === 'ally_checking') { - accountId = 'ally_checking'; accountName = 'Ally Checking'; + if (kind === 'credit_card') { + accountId = 'card_' + file.name.replace(/\.csv$/i,'').toLowerCase().replace(/[^a-z0-9]+/g,'_'); + accountName = 'Bank Credit Card (' + file.name.replace(/\.csv$/i,'') + ')'; + } else if (kind === 'bank_savings') { + accountId = 'bank_savings'; accountName = 'Bank Savings'; + } else if (kind === 'bank_checking') { + accountId = 'bank_checking'; accountName = 'Bank Checking'; } else { accountId = 'acct_' + file.name.replace(/\.csv$/i,'').replace(/[^a-z0-9]+/g,'_'); accountName = file.name; @@ -657,7 +661,7 @@ function parseCsvFile(file, forcedKind) { // this file: the 2nd copy gets an _2 suffix, the 3rd _3, and so on. Counting per // file (never against the database) keeps IDs identical across re-uploads, so // DB.importTransactions() can simply skip IDs it already holds. Schemas with a - // bank-assigned Time column (Ally) opt out: an identical row there is a true + // bank-assigned Time column (checking/savings) opt out: an identical row there is a true // duplicate, so only the first copy is kept. const allowSuffix = schema.allowOccurrenceSuffix ?? !schema.columns.time; const txs = []; @@ -731,6 +735,14 @@ async function loadFiles(fileList, assignments) { const txs = await parseCsvFile(f, kind); State.transactions.push(...txs); } + // Edits still saved under a transaction's id from before v1.12.0 (e.g. kept while the + // transactions were cleared) move to its current id (migrate.js). + const adopted = IdMigration.adoptOverrides(State.transactions); + if (adopted.size) { + State.transactions = State.transactions.map(t => adopted.has(t.id) + ? reconstituteTx({ ...t, description: t._originalDesc }, State.txOverrides[t.id]) : t); + lsSet('txOverrides', State.txOverrides); + } State.transactions.sort((a,b)=>b.date-a.date); detectTransfers(); // Keep accountOrder in sync: preserve existing order, append any newly loaded accounts diff --git a/js/db.js b/js/db.js index 71d1fa8..f5c7b15 100644 --- a/js/db.js +++ b/js/db.js @@ -153,7 +153,7 @@ const DB = { * _2, _3 … suffixes for truly identical rows, counted within the file — so any ID * already in the store is a re-imported row and is skipped. Never assign suffixes * here: doing so on collision (≤v1.8.0) re-inserted every row of a re-uploaded - * Chase file as an "_2" copy. + * credit card file as an "_2" copy. * * Also removes leftover copies from that bug: a suffixed row whose base transaction * is in this file but whose exact ID is not (e.g. base_2 when the file has only one diff --git a/js/init.js b/js/init.js index bec5be1..3ba9a28 100644 --- a/js/init.js +++ b/js/init.js @@ -105,6 +105,14 @@ } } + /* ---- Rename old account codes (v1.12.0) in State and browser storage ---- */ + // Runs every boot; once nothing old is left it changes nothing (migrate.js). + try { + await IdMigration.atBoot(); + } catch(e) { + console.warn('[FinLens] Boot: account code migration failed:', e.message); + } + /* ---- Auto-reload CSV data from previously selected folder ---- */ // Only needed if IndexedDB has no transactions (fresh install or DB cleared). // If DB already has transactions, we skip the CSV reload — data is already loaded. diff --git a/js/migrate.js b/js/migrate.js new file mode 100644 index 0000000..f1685b9 --- /dev/null +++ b/js/migrate.js @@ -0,0 +1,375 @@ +/* ================================================================ + FINLENS — migrate.js + Rewrites data saved by older versions. Loaded after db.js. +================================================================ */ + +/* ---------- v1.12.0: neutral account codes ---------- */ +// Up to v1.10.x the account kinds, schema ids and account ids were named after two +// banks. They are now bank_checking, bank_savings and credit_card (card_ for card +// accounts). Data saved by those versions (browser storage, finlens-state.json, its +// backups and JSON exports) still carries the old codes, so this file is the one place +// that lists them (CLAUDE.md §22). +// +// Transaction ids are hashes that include the account id (mkTx() in core.js), so they +// change too. The stored transaction lacks two of the hash inputs (the bank's time or +// the post date), but the hash is linear enough to swap the account part of an existing +// id without them: see _rekey(). +const IdMigration = { + // Account kinds and BANK_SCHEMAS ids + KINDS: { ally_checking: 'bank_checking', ally_savings: 'bank_savings', chase: 'credit_card' }, + // Account ids: fixed ones, and the prefix of card accounts () + ACCOUNT_IDS: { ally_checking: 'bank_checking', ally_savings: 'bank_savings' }, + OLD_CARD_PREFIX: 'chase_', + NEW_CARD_PREFIX: 'card_', + // Default names older versions gave imported accounts → the names given now. Names the + // user typed are left alone. + NAMES: [ + [/^Ally (?:Bank )?Checking$/, () => 'Bank Checking'], + [/^Ally (?:Bank )?Savings$/, () => 'Bank Savings'], + [/^Chase Credit Card$/, () => 'Bank Credit Card'], + [/^Chase \((.*)\)$/, (m) => `Bank Credit Card (${m[1]})`], + ], + // Persisted State keys that hold account ids, kinds or transaction ids. + KEYS: ['txOverrides', 'manualBalances', 'accountLabels', 'accountOrder', 'fileAssignments'], + + /* ---------- codes and names ---------- */ + kind(k) { return this.KINDS[k] || k; }, + + accountId(id) { + if (typeof id !== 'string') return id; + if (this.ACCOUNT_IDS[id]) return this.ACCOUNT_IDS[id]; + if (id.startsWith(this.OLD_CARD_PREFIX)) return this.NEW_CARD_PREFIX + id.slice(this.OLD_CARD_PREFIX.length); + return id; + }, + + isOld(id) { return this.accountId(id) !== id; }, + + // The id an older version gave this account, or null if it never had another. + oldAccountId(id) { + if (typeof id !== 'string') return null; + for (const [o, n] of Object.entries(this.ACCOUNT_IDS)) if (n === id) return o; + if (id.startsWith(this.NEW_CARD_PREFIX)) return this.OLD_CARD_PREFIX + id.slice(this.NEW_CARD_PREFIX.length); + return null; + }, + + accountName(name) { + if (typeof name !== 'string') return name; + for (const [re, to] of this.NAMES) { const m = re.exec(name); if (m) return to(m); } + return name; + }, + + // manualBalances keys: , _limit, _initial + balanceKey(k) { + for (const [o, n] of Object.entries(this.ACCOUNT_IDS)) { + if (k === o || k === o + '_limit' || k === o + '_initial') return n + k.slice(o.length); + } + return k.startsWith(this.OLD_CARD_PREFIX) ? this.NEW_CARD_PREFIX + k.slice(this.OLD_CARD_PREFIX.length) : k; + }, + + /* ---------- transaction ids ---------- */ + // hash() in core.js is h = 31·h + charCode (mod 2^32) over "|