Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_<file>`. 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.5] — 2026-11-02

### Fixed
Expand Down
118 changes: 79 additions & 39 deletions CLAUDE.md

Large diffs are not rendered by default.

43 changes: 22 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.5 &nbsp;·&nbsp; **Stack:** Vanilla JS, HTML, CSS &nbsp;·&nbsp; **Install:** None
**Version:** v1.12.0 &nbsp;·&nbsp; **Stack:** Vanilla JS, HTML, CSS &nbsp;·&nbsp; **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:

Expand Down Expand Up @@ -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.

Expand All @@ -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 |

---
Expand Down Expand Up @@ -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").
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -260,4 +261,4 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history.

---

*FinLens v1.10.5 — 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.*
3 changes: 2 additions & 1 deletion index.html
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@
<div style="margin-top:auto">
<a class="nav" data-view="settings">⚙️ Settings</a>
<div class="footer">
<div style="color:var(--text-3);font-size:11px">v1.10.5 · FinLens</div>
<div style="color:var(--text-3);font-size:11px">v1.12.0 · FinLens</div>
</div>
</div>
</aside>
Expand Down Expand Up @@ -391,6 +391,7 @@ <h3>Transaction Detail</h3>
<script src="js/core.js"></script>
<script src="js/aggregation.js"></script>
<script src="js/db.js"></script>
<script src="js/migrate.js"></script>
<script src="js/ui.js"></script>
<script src="js/views-main.js"></script>
<script src="js/views-plan.js"></script>
Expand Down
70 changes: 41 additions & 29 deletions js/core.js
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,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) {
Expand Down Expand Up @@ -390,8 +393,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') &&
Expand All @@ -412,15 +415,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',
Expand All @@ -436,8 +439,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') &&
Expand All @@ -447,7 +450,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',
Expand All @@ -462,12 +465,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)
Expand All @@ -479,7 +482,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() : '';
Expand Down Expand Up @@ -568,8 +571,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;
Expand Down Expand Up @@ -607,7 +611,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]) : [];
Expand All @@ -624,9 +628,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) {
Expand All @@ -637,15 +641,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;
Expand All @@ -665,7 +669,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 = [];
Expand Down Expand Up @@ -739,6 +743,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
Expand Down
2 changes: 1 addition & 1 deletion js/db.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading