Epic: tech-debt paydown sweep (June 2026)

[delabrcd]

Problem

A six-angle tech-debt sweep (scraper/scheduler, pure libs, UI, layout/widget, API/queries, tooling/CI)
found the codebase healthy — disciplined pure/impure split, clean secret handling, strong 5-job CI,
exact-pinned deps, almost no masked checks. The debt is maintainability: a few oversized files,
pervasive small duplication, confirmed-dead code from superseded features, and shallow static analysis.
This epic tracks paying it down in risk-ordered batches (no behavior change unless noted).

Sub-issues (risk-ordered batches)

Batch 1 — quick wins (zero/low risk, no numeric impact):

• Remove confirmed-dead code (discoverInterval, computeFitRowHeight, grain layer, horizonK, …) #146 Remove confirmed-dead code
• Enable tsconfig noUnusedLocals / noUnusedParameters / noImplicitReturns #147 tsconfig unused/returns flags
• Build hygiene: npm ci in Dockerfile + document DATA_DIR in .env.example #148 Build hygiene (npm ci + DATA_DIR)

Batch 2 — tooling hardening (surfaces future debt automatically):

• Add @typescript-eslint rules (no-floating-promises, no-misused-promises) scoped to lib/ #149 @typescript-eslint rules
• CI build caching + coverage report + staged dependency bumps #160 CI caching + coverage report + staged dep bumps

Batch 3 — shared primitives + tests:

• Consolidate duplicated UI primitives (Segmented, chart theme, dismiss-on-outside-click, peak readout, interval fetch scaffold) #150 Consolidate UI primitives
• Extract lib/stats.ts + add missing hand-calc tests (median ×4, ymToLastYmd, parsePdf fallbacks, grain edges) #151 Extract lib/stats.ts + missing hand-calc tests
• Scraper dedup + typed GraphQL (auth login-fill, collect.ts any cluster, shared date/err helpers) #152 Scraper dedup + typed GraphQL

Batch 4 — numeric + efficiency (gated on /api/verify):

• Rename totalDueAmount-named fields that actually carry currentCharges #153 Rename totalDueAmount→currentCharges
• Hot-path query efficiency: /api/settings + getOverview double-fetch #154 Hot-path query efficiency

Batch 5 — large-file decomposition (biggest diffs, laid out last):

• Make 'add a widget' registry-only (defaultVisible field; dedup interval WidgetDefs) #155 Make "add a widget" registry-only
• Decompose IntervalHistory.tsx (1467 LOC) into fetch/overscan/navigation hooks #156 Decompose IntervalHistory.tsx
• Decompose layoutEngine.ts + lift Dashboard/WidgetLayout placement transforms into the pure lib #157 Decompose layoutEngine.ts + lift placement transforms
• Decompose prediction.ts projectSeason (131-line dual-mode function) #158 Decompose prediction.ts projectSeason
• API consistency: uniform error envelope + export routes via withAccount + bills PDF accountId #159 API consistency cleanup

Acceptance criteria

• Each sub-issue lands via its own PR through the 5-job CI gate; numeric changes paste /api/verify.
• No masked checks (standards §9); large refactors are behavior-preserving + visually verified.

Pointers

• docs/standards.md, docs/architecture.md — the rules each change must satisfy.

[delabrcd]

All 13 sub-issues shipped + verified in prod across v0.40.1–v0.40.7. (One mid-sweep prod regression: #150's IntervalHeatmap null-payload crash in v0.40.2 → rolled back → fixed in v0.40.3 #166.) Remaining open: #164 (staged dependency bumps, intentionally deferred to the update-container/staging path). Closing this epic.