hledger-web-reports/docs/philosophy.md

Development principles

Readable code first

• Make folder, file and function names explain ownership. Keep feature code and its tests together.
• Let operations show meaningful phases. Keep resource lifetimes and cleanup together.
• Improve awkward producer output before adding consumer workarounds. Prefer deletion over speculative abstractions.
• Use comments only for necessary external context, not to narrate code. Keep docs and PR descriptions plain and short.

Financial boundaries

Hledger owns accounting. Preserve exact values, separate commodities and explicit missing or ambiguous states. Category-chart grouping is the only browser arithmetic: exact, within one saved period and commodity, without changing native data.

Browsing reads saved data; financial work requires an explicit request. Preserve private data and completed publications. Unsupported reports require explicit preparation, not automatic migration or deletion.

Tests

Keep tests that protect valuable rules we own: financial fidelity, privacy, access, complete publication and resource ownership. Test at the owning layer with a few representative cases, not repeated matrices. Do not test hledger, Chart.js, framework behavior, UI copy or appearance. Exact financial strings are data, not copy.

Use disposable fictional inputs, never operator journals. Keep a small browser smoke suite for important workflows. Test counts and coverage are not goals.

Review

Prepare one commit's changes unstaged, then stop for owner review. After approval, run code, readability and test reviews, then relevant checks. Stage and commit only with approval and passing checks. Push and open a PR only with approval; the owner merges. PR descriptions briefly explain the change and checks, without a process diary.