739 lines
41 KiB
Markdown
739 lines
41 KiB
Markdown
# AGENTS.md
|
|
|
|
## ⛔ ABSOLUTE PROHIBITIONS — READ FIRST ⛔
|
|
|
|
### Zig 0.16.0 reference — read the release notes
|
|
|
|
This codebase is on Zig 0.16.0. The 0.16 release was a major
|
|
I/O-as-an-interface refactor that reshaped the standard library.
|
|
Before making non-trivial changes (especially anything touching
|
|
`std.Io`, `std.fs`, `std.process`, `std.http`, `std.Thread`,
|
|
allocators, or `std.time`), **read the release notes** at:
|
|
|
|
https://ziglang.org/download/0.16.0/release-notes.html
|
|
|
|
Key migrations that bit us repeatedly during the 0.16 upgrade and
|
|
will bite future work too:
|
|
|
|
- `std.io` → `std.Io` (namespace rename, no deprecation alias).
|
|
- `std.fs.cwd()` → `std.Io.Dir.cwd()`. All file ops take `io`.
|
|
- `std.process.Child.init(argv, alloc)` → `std.process.spawn(io, .{...})`
|
|
or `std.process.run(gpa, io, .{...})`.
|
|
- `std.time.timestamp()` → `std.Io.Timestamp.now(io, .real).toSeconds()`.
|
|
- `std.Thread.sleep(ns)` → `std.Io.sleep(io, duration, clock)`.
|
|
- `pub fn main` gains a `std.process.Init` parameter ("Juicy Main");
|
|
provides pre-built `gpa`, `io`, `arena`, `environ_map`.
|
|
- `std.heap.GeneralPurposeAllocator` → `std.heap.DebugAllocator`.
|
|
- `std.heap.ThreadSafeAllocator` removed; `ArenaAllocator` is now
|
|
lock-free thread-safe, `DebugAllocator` is thread-safe by default.
|
|
- `std.mem.trimRight`/`trimLeft` → `trimEnd`/`trimStart`.
|
|
- `std.mem.indexOf*` → `find*` (deprecation aliases still present,
|
|
so old names work but warn).
|
|
- `std.testing.refAllDeclsRecursive` removed. Only `refAllDecls`
|
|
remains. We use the bare `std.testing.refAllDecls(@This())` in
|
|
`src/main.zig`'s test block — it sema-touches every top-level decl,
|
|
which transitively pulls in every imported file's `test` blocks.
|
|
No local reimplementation is needed. See "Test discovery" below.
|
|
- `std.fs.File.readToEndAlloc(alloc, N)` → two-step:
|
|
`file.reader(io, &.{})` then `.interface.allocRemaining(alloc, .limited(N))`.
|
|
|
|
For anything not on this list, **read the release notes first.**
|
|
The notes are long but they're organized by section; searching for
|
|
the specific symbol you're migrating is fast.
|
|
|
|
### `io` vs `today` / `now_s` — design rule
|
|
|
|
The 0.16 upgrade made a deliberate choice about which Zig-0.16 `Io`
|
|
calls to thread through and which to sidestep. **This rule is
|
|
load-bearing**; please read before adding new code that needs the
|
|
current time.
|
|
|
|
- **`io: std.Io` is threaded through anything that actually does
|
|
I/O** — file reads/writes, stderr, HTTP, process spawn, terminal
|
|
detection. A function taking `io` is announcing that it touches
|
|
the outside world. The "code smell" is a feature.
|
|
- **`today: Date` is passed as a value** for functions that need
|
|
"what day is it" but don't otherwise do I/O. Captured once at
|
|
the top of the unit of work (`runCli` for CLI, `App.init` for
|
|
TUI) and threaded through. Render output stays deterministic
|
|
within a frame even if the clock ticks over mid-render.
|
|
|
|
- **Use the name `today` only when the parameter genuinely
|
|
means "the current calendar day."** That's the App-level
|
|
`app.today` field and the per-command `today` arg threaded
|
|
from `runCli`. The caller can't reasonably pass anything
|
|
other than the actual current day to these.
|
|
- **Use `as_of: Date` when the parameter is the reference
|
|
date for a computation, and the caller might legitimately
|
|
pass any value.** Examples: rolling-windows blocks (the
|
|
`--as-of` flag back-dates the view), CAGR / annualization
|
|
helpers, snapshot-resolution helpers. The function should
|
|
work correctly whether the caller passes today's date,
|
|
last week's date, or 2014. Calling such a parameter
|
|
`today` invites bugs because future maintainers will
|
|
assume the function uses it as "now" rather than "the
|
|
reference date you asked about."
|
|
- When in doubt: if the function's behavior would be
|
|
nonsensical with a date that isn't today, use `today`.
|
|
Otherwise use `as_of`. Most analytics functions are
|
|
`as_of`.
|
|
|
|
- **`now_s: i64` (or similar `before_s`/`after_s` pairs) is passed
|
|
as a value** for sub-second-precision metadata fields like
|
|
snapshot `captured_at`, rollup `#!created=`, audit cadence
|
|
staleness math. Same single-capture-and-thread pattern as
|
|
`today`.
|
|
|
|
When adding a new function that needs the current time, do NOT
|
|
reach for `std.Io.Timestamp.now(io, .real)` inside the function.
|
|
Take `today: Date` or `now_s: i64` instead. Only take `io` if the
|
|
function genuinely needs to do I/O for other reasons.
|
|
|
|
**Legitimate `Timestamp.now` callers** (each must have a
|
|
`// wall-clock required: <why>` comment justifying the read):
|
|
- `cache/store.zig` — cache entry timestamps and TTL math
|
|
- `service.zig` — per-fetch `FetchResult.timestamp`
|
|
- `net/RateLimiter.zig` — token-bucket refill
|
|
- `commands/audit.zig`, `commands/cache.zig`, `commands/history.zig`
|
|
— per-invocation `now_s` captures for staleness math, "X ago"
|
|
age displays, and rollup `#!created=` directives. Each call
|
|
site has a justifying comment.
|
|
- TUI per-frame "now" captures for relative-time display
|
|
(e.g. earnings, options, quote tabs)
|
|
- `tui.zig` `shouldDebounceWheel` — uses `.awake` (monotonic
|
|
clock) for sub-millisecond input-event debounce; resists
|
|
system clock jumps that `.real` would expose
|
|
- The single `Timestamp.now` capture in `main.zig`'s dispatch
|
|
entry that produces `today` and `now_s` for the rest of the
|
|
invocation
|
|
- The `format.todayDate(io)` helper itself (the one legitimate
|
|
capture function for unit-of-work entry points)
|
|
|
|
If you find yourself writing `Timestamp.now(io, ...)` somewhere
|
|
not on that list, either add a justifying comment or refactor
|
|
the function to take a value parameter.
|
|
|
|
### Time and money helpers — CHECK FIRST before adding any new function
|
|
|
|
This project is, at its core, thousands of lines of code about
|
|
time and money. Almost any helper you think you need to add for
|
|
date arithmetic, age calculation, dollar formatting, percentage
|
|
formatting, currency rounding, or trailing-zero handling **already
|
|
exists** under some name. Adding a near-duplicate is a recurring,
|
|
easy-to-make mistake that silently bloats the codebase with three
|
|
slightly-different ways to do the same thing.
|
|
|
|
**Before writing any new helper that touches time or money, you
|
|
MUST search for existing implementations.** Not "search if it
|
|
seems familiar" — search every time. Examples of helpers that
|
|
already exist and have caught me out:
|
|
|
|
- `Date.addYears` / `Date.subtractYears` — calendar-year math
|
|
with Feb 29 → Feb 28 clamping.
|
|
- `Date.yearsBetween` — 365.25-day approximation, returns f64.
|
|
- `Date.wholeYearsBetween` — floored, returns u16.
|
|
- `Date.ageOn` — calendar-precise age (handles "birthday hasn't
|
|
occurred this year yet"). Distinct from `wholeYearsBetween`.
|
|
- `Date.format` — Zig 0.15+ writer-style format method. Use `{f}`
|
|
to render "YYYY-MM-DD" directly into a writer.
|
|
- `Date.padRight(N)` / `Date.padLeft(N)` — column-aligned wrappers
|
|
for `{f}` rendering. Use these instead of `{s:>N}` when you
|
|
previously would have called a buffer-into-slice formatter and
|
|
passed the slice to a width-spec.
|
|
- For cases that need a `[]const u8` (URL params, struct fields),
|
|
call `std.fmt.bufPrint(&buf, "{f}", .{my_date})` into a `[10]u8`.
|
|
- `Money.from(amount)` with `{f}` — "$1,234.56" with commas,
|
|
always 2 dp. Standard format method (Zig 0.15+ format-method
|
|
protocol) — no buffer ceremony.
|
|
- `Money.from(amount).whole()` — "$1,234" rounded to whole
|
|
dollars. Returns a wrapper struct; render with `{f}`.
|
|
- `Money.from(amount).trim()` — like default but elides `.00`.
|
|
- `Money.from(amount).signed()` — "+$1,234.56" / "-$1,234.56".
|
|
- `Money.from(amount).padRight(N)` / `padLeft(N)` — column-aligned
|
|
output. Composes with `.whole()`/`.trim()`/`.signed()` (each
|
|
variant exposes its own `padRight`/`padLeft`). Generic over the
|
|
inner type via `Padded(T)` so the same wrapper works for any
|
|
`format`-bearing type.
|
|
- `format.fmtIntCommas` — "1,234,567" without `$`.
|
|
- `analytics/performance.formatReturn` — signed percent for
|
|
trailing-returns and gain/loss displays. (Lives in
|
|
`analytics/performance.zig` because returns are a
|
|
performance-domain concept; reusing it from elsewhere is fine.)
|
|
|
|
**Search recipes that catch the most cases:**
|
|
|
|
```
|
|
# Money — Money.zig should be your first stop. Search for callers:
|
|
grep -rn "Money.from\|fmt.fmtMoney" src/
|
|
|
|
# Bare-money formatter footguns (these existed pre-Money.zig and
|
|
# should be migrated to Money if found):
|
|
grep -rn "@round.*amount\|@intFromFloat(@round" src/
|
|
grep -rn "endsWith.*\\\".00\\\"\|lastIndexOfScalar.*'\\\\.'" src/
|
|
|
|
# Date / age helpers
|
|
grep -rn "fn age\|ageOn\|addYears\|subtractYears\|yearsBetween" src/
|
|
grep -rn "month() <\|day() <\|on\\.year() -" src/ # ad-hoc age math
|
|
|
|
# Time / now
|
|
grep -rn "Timestamp.now\|fromEpoch\|toEpoch" src/
|
|
```
|
|
|
|
If the search turns up an existing helper that does what you need,
|
|
**use it**. If it turns up something close-but-not-quite, prefer
|
|
extending the existing helper (new variant, optional parameter,
|
|
generalized signature) over adding a parallel one. Three closely
|
|
related functions in the same module is a smell; the user will
|
|
ask you to consolidate them and you'll have wasted both your time
|
|
and theirs.
|
|
|
|
If the search confirms nothing exists, add the new helper to the
|
|
right module:
|
|
|
|
- Date / calendar math → `src/Date.zig`, as a `Date` method
|
|
when the receiver is natural.
|
|
- Money formatting → `src/Money.zig`. New variants are wrapper
|
|
structs returned from `Money` methods; each implements
|
|
`format(self, *Writer) !void` so it works with `{f}`.
|
|
- Other number formatting (non-money) → `src/format.zig`.
|
|
- Per-domain formatting that wraps the above → keep in the
|
|
domain's view module.
|
|
|
|
Add tests in the same file. Money helpers belong next to
|
|
the other tests in `Money.zig`; date helpers belong next to
|
|
`yearsBetween`'s tests.
|
|
|
|
### NEVER invoke ripgrep. EVER.
|
|
|
|
**Do not run `rg` in the Bash tool.** Not for open-ended search, not for
|
|
counting matches, not for "just this one quick check", not ever. Running
|
|
ripgrep on this machine hammers the filesystem badly enough to degrade the
|
|
whole system — this is a recurring, reproducible problem, not a hunch.
|
|
|
|
**Use instead:**
|
|
|
|
- **Grep tool** (built-in) for content search. It handles regex, file
|
|
globs, and output shaping without spawning `rg`.
|
|
- **Glob tool** (built-in) for finding files by name pattern.
|
|
- **Read tool** for reading files (with `offset`/`limit` for large ones).
|
|
- Plain `grep` via the Bash tool is acceptable when the built-in Grep
|
|
tool can't express what you need — but prefer the built-in first.
|
|
|
|
**If you catch yourself typing `rg` in a Bash command:** stop, delete it,
|
|
use the Grep tool instead. The fact that `rg` is faster in the abstract
|
|
does NOT matter here. This machine's filesystem + ripgrep's parallelism
|
|
is a bad combination, full stop.
|
|
|
|
**This applies to every variant:** `rg`, `ripgrep`, piping through
|
|
`rg`, backgrounded `rg`, `rg --files`, etc. All banned.
|
|
|
|
### NEVER delete or modify build caches. EVER.
|
|
|
|
**This means:**
|
|
|
|
- **NEVER** run `rm -rf .zig-cache` or `rm -rf .zig-cache/*` or any variant.
|
|
- **NEVER** run `rm -rf ~/.cache/zig` or touch anything under `~/.cache/zig/`.
|
|
- **NEVER** touch `~/.cache/zls/` or any other tool cache.
|
|
- **NEVER** suggest deleting the cache as a "fix" — it is not a fix, it is
|
|
damage. Deleting `.zig-cache` while ZLS or another `zig build` is running
|
|
creates a corrupt state where the build runner's expected cache entry
|
|
(`.zig-cache/o/<hash>/build`) references a path that no longer exists,
|
|
producing the error `failed to spawn build runner .zig-cache/o/<hash>/build:
|
|
FileNotFound`. Recovering from this on the affected machine requires
|
|
killing every concurrent `zig` process (including ZLS) and waiting for
|
|
filesystem state to re-stabilize — it is NOT a simple retry.
|
|
- **NEVER** touch the cache "just to force a rebuild". Zig's cache is
|
|
content-addressed. It does not get stale in a way that deletion fixes.
|
|
If a build result looks wrong, the bug is in the source, not the cache.
|
|
Use `touch src/somefile.zig` if you truly need to invalidate one file's
|
|
cache line. Do not nuke the whole directory.
|
|
- **NEVER** suggest a "different cache directory" as a workaround without
|
|
an explicit, specific reason and explicit user approval. `--cache-dir`
|
|
and `--global-cache-dir` flags exist; they are not toys.
|
|
|
|
**If a test result seems wrong or cached incorrectly:** the answer is
|
|
ALWAYS to investigate the source code or build graph, not to delete
|
|
cache. See "Test discovery" below — 99% of the time the "cached wrong
|
|
result" is actually a test discovery problem, not a cache problem.
|
|
|
|
**If you find yourself typing `rm -rf` anywhere near a cache path: STOP.
|
|
Ask the user instead.**
|
|
|
|
### NEVER run destructive git operations without explicit permission.
|
|
|
|
- No `git reset --hard`, `git clean -fdx`, `git push --force`, `git checkout .`
|
|
on files with uncommitted work, unless the user asks for that specific
|
|
operation by name.
|
|
|
|
### NEVER run `git stash`. EVER.
|
|
|
|
- **`git stash` is banned outright.** Not `git stash push`, not `git stash --keep-index`,
|
|
not `git stash pop`, not `git stash apply`, not even read-only `git stash list`.
|
|
No variant. No "just to test something." No "I'll pop it right back."
|
|
- The reason: `git stash pop` can conflict on overlapping lines and leave
|
|
unresolved conflict markers in the working tree. The recovery requires
|
|
hand-resolving the markers, which trashes whatever curated index state
|
|
the user had in flight. This has bitten the user before and it's bitten
|
|
them again because of me. The rule is absolute now.
|
|
- If you think you need `git stash` to verify something (e.g. "does the
|
|
staged-only state build cleanly in isolation?"), the answer is: **don't
|
|
verify it that way.** Either:
|
|
- Read `git diff --cached` and reason about whether the staged hunks
|
|
are coherent on their own, OR
|
|
- Ask the user to verify after they commit, OR
|
|
- If verification is critical, ask the user to do the stash themselves
|
|
with their tools — but recommend against it because of this rule.
|
|
- **There is no exception clause for `git stash`.** Not even "the user
|
|
said it's OK this once" — the previous "one-time exception" for git
|
|
staging operations is what led to the stash incident. Direct exceptions
|
|
for `git add -p` / `git restore --staged` for staging-management remain
|
|
permitted with explicit user approval, but `git stash` is permanently
|
|
off-limits regardless of consent.
|
|
|
|
### NEVER run `git add`, `git commit`, or `git push`. EVER.
|
|
|
|
- **The user commits. You do not.** Do not stage files. Do not create commits.
|
|
Do not amend commits. Do not push. Do not suggest running these commands
|
|
yourself "to save a step". This includes `git add -p`, `git add .`,
|
|
`git add <file>`, `git commit -m ...`, `git commit --amend`, `git push`,
|
|
and any `gh pr create` that would auto-stage or auto-commit.
|
|
- If you are tempted to run any of these because "the work is done and it
|
|
seems logical to commit" — STOP. The user has a review-and-commit workflow.
|
|
Your job ends at a clean working tree with the changes ready to review.
|
|
- The ONLY exception is when the user says, verbatim in the current turn,
|
|
"commit this" / "make a commit" / "push it" / similar direct imperative.
|
|
Do not extrapolate from earlier intent, a plan that mentioned milestones,
|
|
or any indirect signal. If in doubt, ask — don't commit.
|
|
- When a milestone plan says "STOP POINT — user reviews and commits": you
|
|
stop. You do not commit. You do not prepare a commit. You hand off the
|
|
working tree and wait.
|
|
|
|
### Documentation-file conventions
|
|
|
|
- **`TODO.md` holds only what's still open.** Git already tracks what was
|
|
done and when. Do NOT add "DONE" markers, completion status, strikethrough,
|
|
or "shipped in …" blurbs to TODO entries — just delete the section when
|
|
the work is finished. If follow-up work came out of the finished task,
|
|
add it as a new top-level section; don't leave the parent entry around
|
|
as a historical wrapper.
|
|
- **`REPORT.md` is untracked on purpose.** It's a personal workflow doc
|
|
living in the repo root only until it moves to `~/finance`. Edit it
|
|
freely when asked; don't treat it as part of the repo surface. Don't
|
|
mention it in commit messages for unrelated work.
|
|
|
|
### Em-dash usage — ASK FIRST
|
|
|
|
If you're about to write an em-dash (`—`) anywhere (code, tests, doc
|
|
comments, commit messages, AGENTS.md prose), **stop and check whether a
|
|
regular ASCII hyphen (`-`) would do.** Most of the time it would. Em-dashes
|
|
look nice in prose but they create real problems:
|
|
|
|
- **In tabular output / TUI cells**, `—` is 3 bytes / 1 display column.
|
|
Zig's `{s:>N}` formatter pads by byte count, so any column containing
|
|
em-dashes will be 2 visual columns short per em-dash. We've fixed this
|
|
bug at least twice; don't reintroduce it. If you genuinely need a
|
|
multibyte sentinel for "no data", use `fmt.padRightToCols` /
|
|
`fmt.centerDash` (display-column-aware) — or just hard-code the cell
|
|
as a literal const string when the cell width is fixed and the dash
|
|
position is static (no point computing what you already know). Add
|
|
an alignment test that compares the multibyte row's `displayCols`
|
|
against an ASCII row.
|
|
- **In code identifiers and string literals**, em-dashes look fine in your
|
|
editor and break grep on the user's machine when they're searching with
|
|
ASCII `-`. If a future grep for "expected-return" or "as-of" silently
|
|
misses your "expected—return" string, that's a bug surface.
|
|
- **In commit messages and prose docs**, em-dashes are an AI tell. The
|
|
user reads commit messages and won't appreciate the codebase looking
|
|
like it was written by ChatGPT.
|
|
|
|
**Rule of thumb:**
|
|
|
|
- Use `-` (ASCII hyphen) for: ranges (`1-5y`), compound modifiers
|
|
(`forecast-vs-actual`), CLI flag names (`--return-backtest`), code
|
|
identifiers, and string concatenation in tables.
|
|
- Use `—` (em-dash) only when you're displaying it to the user as a
|
|
meaningful sentinel (e.g. "no data" cell in a table), AND you've handled
|
|
the display-column padding correctly.
|
|
- If you find yourself reaching for `—` in prose for a parenthetical
|
|
aside, **switch to a regular dash, comma, or parens.** Em-dashes have
|
|
become a stylistic AI tic and the user has explicitly asked to keep
|
|
them out unless they earn their place.
|
|
|
|
When in doubt, **ask**. A one-line "I'm about to use `—` here for X, OK?"
|
|
is much cheaper than reverting after the user notices.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
zig build # build the zfin binary (output: zig-out/bin/zfin)
|
|
zig build test # run all tests (single binary, discovers all tests via refAllDecls + the import graph)
|
|
zig build run -- <args> # build and run CLI
|
|
zig build docs # generate library documentation
|
|
zig build coverage # run tests with kcov coverage (Linux only). See "Coverage" section.
|
|
zig build coverage -Dcoverage-threshold=65 # fail build if coverage < N% (pre-commit uses 65)
|
|
```
|
|
|
|
**Tooling** (managed via `.mise.toml`):
|
|
- Zig 0.16.0 (minimum)
|
|
- ZLS 0.16.0
|
|
- zlint 0.7.9
|
|
|
|
**Linting**: `zlint --deny-warnings --fix` (runs via pre-commit on staged `.zig` files).
|
|
|
|
**Formatting**: `zig fmt` (enforced by pre-commit). Always run before committing.
|
|
|
|
**Pre-commit hooks** run in order: trailing-whitespace, end-of-file-fixer, zig-fmt, zlint, zig-build, then tests with coverage.
|
|
|
|
## Architecture
|
|
|
|
Single binary (CLI + TUI) built from `src/main.zig`. No separate library binary for internal use — the library module (`src/root.zig`) exists only for downstream consumers and documentation generation.
|
|
|
|
### Data flow
|
|
|
|
```
|
|
User input → main.zig (CLI dispatch) or tui.zig (TUI event loop)
|
|
→ commands/*.zig (CLI) or tui/*.zig (TUI tab renderers)
|
|
→ DataService (service.zig) — sole data access layer
|
|
→ Cache check (cache/store.zig, SRF files in ~/.cache/zfin/{SYMBOL}/)
|
|
→ Server sync (optional ZFIN_SERVER, parallel HTTP)
|
|
→ Provider fetch (providers/*.zig, rate-limited HTTP)
|
|
→ Cache write
|
|
→ analytics/*.zig (performance, risk, valuation calculations)
|
|
→ format.zig (shared formatters, braille charts)
|
|
→ views/*.zig (view models — renderer-agnostic display data)
|
|
→ stdout (CLI via buffered Writer) or vaxis (TUI terminal rendering)
|
|
```
|
|
|
|
### Key design decisions
|
|
|
|
- **Internal imports use file paths, not module names.** Only external dependencies (`srf`, `vaxis`, `z2d`) use `@import("name")`. Internal code uses relative paths like `@import("Date.zig")` or `@import("models/portfolio.zig")`. This is intentional — it lets `refAllDecls` in the test binary discover all tests across the entire source tree.
|
|
|
|
- **DataService is the sole data source.** Both CLI and TUI go through `DataService` for all fetched data. Never call provider APIs directly from commands or TUI tabs.
|
|
|
|
- **Providers are lazily initialized.** `DataService` fields like `td`, `pg`, `fh` start as `null` and are created on first use via `getProvider()`. The provider field name is derived from the type name at comptime.
|
|
|
|
- **Cache uses SRF format.** [SRF](https://git.lerch.org/lobo/srf) (Simple Record Format) is a line-oriented key-value format. Cache layout: `{cache_dir}/{SYMBOL}/{data_type}.srf`. Freshness is determined by file mtime vs TTL.
|
|
|
|
- **Candles use incremental updates.** On cache miss, only candles newer than the last cached date are fetched (not the full 10-year history). The `candles_meta.srf` file tracks the last date and provider without deserializing the full candle file.
|
|
|
|
- **View models separate data from rendering.** `views/portfolio_sections.zig` produces renderer-agnostic structs with `StyleIntent` enums. CLI and TUI renderers are thin adapters that map `StyleIntent` to ANSI colors or vaxis styles.
|
|
|
|
- **Negative cache entries.** When a provider fetch fails permanently (not rate-limited), a negative cache entry is written to prevent repeated retries for nonexistent symbols.
|
|
|
|
- **TUI tab framework.** The TUI is a registry-driven framework with eight tabs sharing infrastructure. The single source of truth is `tab_modules` in `src/tui.zig` (an anonymous struct literal mapping tag → module). Everything else — the `Tab` enum, tab-bar labels, the `TabStates` aggregator, key/mouse dispatch, help overlay rows, status-line hints, draw routing — is derived from `tab_modules` at comptime. Each tab module conforms to a contract documented in `src/tui/tab_framework.zig`: declare an `Action` enum, a `State` struct, a `tab` namespace with required hooks, and exactly one of `buildStyledLines` or `drawContent`. A comptime validator (`tab_framework.validateTabModule`) checks every registered module at build time, including hook signatures and a "tabs cannot bind globally-bound keys" rule. See "Adding a new TUI tab" below for the workflow.
|
|
|
|
### Module map
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `src/models/` | Data types: `Candle`, `Dividend`, `Split`, `Lot`, `Portfolio`, `OptionContract`, `EarningsEvent`, `EtfProfile`, `Quote`. (`Date` and `Money` are top-level types in `src/Date.zig` and `src/Money.zig`.) |
|
|
| `src/providers/` | API clients: each provider has its own struct with `init(allocator, api_key)` + fetch methods. `json_utils.zig` has shared JSON parsing helpers. |
|
|
| `src/analytics/` | Pure computation: `performance.zig` (Morningstar-style trailing returns), `risk.zig` (Sharpe, drawdown), `valuation.zig` (portfolio summary), `analysis.zig` (breakdowns by class/sector/geo), `benchmark.zig` (per-position benchmark returns), `indicators.zig` (SMA/Bollinger/RSI), `milestones.zig` (retirement-attainment grid), `projections.zig` (Monte Carlo + percentile bands), `timeline.zig` (history-tab tier rollup). |
|
|
| `src/data/` | Static / semi-static datasets: `imported_values.zig` (back-history values), `shiller.zig` (S&P + CPI series, Shiller's data set), `staleness.zig` (account-cadence checks). `ie_data.csv` is the raw Shiller dataset. |
|
|
| `src/views/` | View models producing renderer-agnostic display data with `StyleIntent`: `compare.zig`, `history.zig`, `portfolio_sections.zig`, `projections.zig`. |
|
|
| `src/commands/` | CLI command handlers: each has a `pub fn run(...)` entry point. Signatures vary by command's needs (some take `as_of`, `now_s`, `args`, etc.); `common.zig` has shared CLI helpers and color constants. See "Adding a new CLI command" below. |
|
|
| `src/tui/` | Eight-tab interactive TUI. Each tab is a separate file conforming to the framework contract documented in `tab_framework.zig`: `portfolio_tab.zig`, `quote_tab.zig`, `performance_tab.zig`, `options_tab.zig`, `earnings_tab.zig`, `analysis_tab.zig`, `history_tab.zig`, `projections_tab.zig`. Plus `keybinds.zig` (configurable input + scoped bindings), `theme.zig` (configurable colors), `chart.zig` (Kitty graphics chart renderer), `projection_chart.zig` (percentile-band overlay), `input_buffer.zig` (modal text-input state machine). The `App` orchestrator lives in the parent `src/tui.zig`. |
|
|
| `src/cache/` | `store.zig`: SRF cache read/write with TTL freshness checks. |
|
|
| `src/net/` | `http.zig`: HTTP client with retry and error classification. `RateLimiter.zig`: token-bucket rate limiter. |
|
|
| `build/` | Build-time support: `Coverage.zig` (kcov integration), `download_kcov.zig` (kcov binary fetcher), `gen_shiller.zig` (CSV → comptime data converter), `bcov.css` (kcov report styling). |
|
|
|
|
## Code patterns and conventions
|
|
|
|
### Error handling
|
|
|
|
- Provider HTTP errors are classified in `net/http.zig`: `RequestFailed`, `RateLimited`, `Unauthorized`, `NotFound`, `ServerError`, `InvalidResponse`.
|
|
- `DataService` wraps these into `DataError`: `NoApiKey`, `FetchFailed`, `TransientError`, `AuthError`, etc.
|
|
- Transient errors (server 5xx, connection failures) cause the refresh to stop. Non-transient errors (NotFound, ParseError) cause fallback to the next provider.
|
|
- Rate limit hits trigger a single retry after `rateLimitBackoff()`.
|
|
|
|
### The `Date` type
|
|
|
|
`Date` is an `i32` of days since Unix epoch. It is used everywhere instead of timestamps. Construction: `Date.fromYmd(2024, 1, 15)` or `Date.parse("2024-01-15")`. Formatting: `try writer.print("{f}", .{date})` writes `YYYY-MM-DD` directly to a writer (Zig 0.15+ format method). For column-aligned output, use `date.padLeft(12)` / `date.padRight(12)` with `{f}`. For cases that need a `[]const u8` (URL params, struct fields), call `std.fmt.bufPrint(&buf, "{f}", .{date})` into a `[10]u8` buffer. The type has SRF serialization hooks (`srfParse`, `srfFormat`).
|
|
|
|
### Formatting pattern
|
|
|
|
Functions in `format.zig` write into caller-provided buffers and return slices. They never allocate. Example: `fmtIntCommas(&buf, value)` returns `[]const u8`. Money formatting now lives in `src/Money.zig` and uses the `{f}` format-method protocol — see the "Time and money helpers" prohibition section above.
|
|
|
|
### Provider pattern
|
|
|
|
Each provider in `src/providers/` follows the same structure:
|
|
1. Struct with `client: http.Client`, `allocator`, `api_key`
|
|
2. `init(allocator, api_key)` / `deinit()`
|
|
3. `fetch*(allocator, symbol, ...)` methods that build a URL, call `self.client.get(url)`, and parse the JSON response
|
|
4. Private `parse*` functions that handle the provider-specific JSON format
|
|
5. Shared JSON helpers from `json_utils.zig` (`parseJsonFloat`, `optFloat`, `optUint`, `jsonStr`)
|
|
|
|
### Test pattern
|
|
|
|
All tests are inline (in `test` blocks within source files). There is a single test binary rooted at `src/main.zig` which uses `std.testing.refAllDecls(@This())` to sema-touch every top-level decl in main.zig. Each decl that's a `@import(...)` of a source file pulls that file into compilation, which causes its `test` blocks to be collected by the test runner. The `tests/` directory exists but fixtures are empty — all test data is defined inline.
|
|
|
|
Tests use `std.testing.allocator` (which detects leaks) and are structured as unit tests that verify individual functions. Network-dependent code is not tested (no mocking infrastructure).
|
|
|
|
### Test discovery
|
|
|
|
`zig build test` runs every `test` block in every file reachable from
|
|
`src/main.zig` via the import graph, courtesy of
|
|
`std.testing.refAllDecls(@This())` in main.zig's bottom `test {}` block.
|
|
"Reachable" means: somewhere in the chain there's a
|
|
`const foo = @import("foo.zig");` (or any other binding to the imported
|
|
file struct, including `pub const`, struct field, etc).
|
|
|
|
**The verification workflow is dead simple:**
|
|
|
|
```bash
|
|
zig build test --summary all 2>&1 | grep "tests passed"
|
|
```
|
|
|
|
Run it before and after a change. If the count moved the way you expected,
|
|
you're done. If it didn't, fix it. There is no further analysis required —
|
|
no manual graph walking, no canary tests, no dependency archaeology.
|
|
|
|
**The one gotcha:** if you import a file purely as a type extraction —
|
|
`const T = @import("foo.zig").T;` — the test blocks in `foo.zig` are NOT
|
|
collected. The fix is to bind the file struct itself somewhere:
|
|
`const foo = @import("foo.zig");`. You'll know this happened because the
|
|
test count won't go up after adding tests to a new file. The `_ = @import(...)`
|
|
escape hatch in main.zig's test block is also fine if reshaping imports is
|
|
inconvenient — `refAllDecls` will sema-touch it.
|
|
|
|
**Do NOT clear the cache "to be sure."** Cache is content-addressed; it
|
|
isn't the problem. See the prohibitions at the top of this file.
|
|
|
|
### Coverage
|
|
|
|
Test coverage is measured by `zig build coverage`, which runs the
|
|
test binary under [kcov](https://simonkagstrom.github.io/kcov/) and
|
|
emits an HTML report under `coverage/` plus a one-line summary on
|
|
stdout:
|
|
|
|
```
|
|
Total test coverage: 65.15% (15399/23638)
|
|
```
|
|
|
|
**The pre-commit hook enforces a coverage floor.** The current
|
|
floor is **65%** (set in `.pre-commit-config.yaml`). The hook runs
|
|
`zig build coverage -Dcoverage-threshold=65` and fails the commit
|
|
if coverage drops below that threshold. Bumping the floor over time
|
|
is encouraged — every time we push the actual coverage materially
|
|
higher, raise the floor in the pre-commit config in the same commit
|
|
so the gain is locked in.
|
|
|
|
**Coverage expectations for new work:**
|
|
|
|
1. **For most features, coverage should go UP, or you should be
|
|
able to explain why not.** New analytics modules, parsers,
|
|
loaders, formatters, and pure-domain transforms are easy to
|
|
cover and should be — they're the load-bearing logic. New
|
|
tests on existing files also nudge the percentage up by
|
|
exercising more lines of the same code.
|
|
|
|
2. **It's fine for some additions to push coverage flat or
|
|
slightly down.** Examples:
|
|
- **New TUI rendering paths.** TUI code that needs an
|
|
interactive vaxis context (event handlers, draw callbacks,
|
|
mouse handling) is hard to test without a vaxis-aware test
|
|
harness, which we don't have. Adding a new tab will add
|
|
uncovered lines unless you can extract a pure render
|
|
function and test it in isolation.
|
|
- **New provider HTTP code.** We don't mock providers; live
|
|
network calls aren't run in tests. Provider request/response
|
|
parsers ARE testable (and SHOULD be tested) — extract them
|
|
from the HTTP-bound code so they can be exercised with
|
|
fixture bytes.
|
|
- **CLI command dispatch glue in `src/main.zig`.** The command
|
|
match chain itself doesn't need tests; the command's
|
|
`run()` function and helpers should.
|
|
|
|
3. **If coverage drops, document why in the commit message.** A
|
|
single sentence — "Adds TUI tab; pure render fn covered;
|
|
event handlers and mouse handlers uncovered, no test
|
|
harness" — is enough. Future-you will thank present-you.
|
|
|
|
**How to investigate uncovered lines:**
|
|
|
|
```bash
|
|
zig build coverage
|
|
# Open coverage/index.html in a browser, or:
|
|
ls coverage/ # per-file HTML reports
|
|
```
|
|
|
|
Each file's report shows red lines (uncovered) and green lines
|
|
(covered). For a quick numeric breakdown by file, the kcov JSON
|
|
output under `coverage/kcov-merged/coverage.json` is greppable.
|
|
|
|
**Common reasons coverage looks lower than expected:**
|
|
|
|
- A new `.zig` file's tests aren't being discovered. Check the
|
|
Test discovery section above. The tests pass-or-fail report
|
|
will say "0 tests" for that module if it's orphaned.
|
|
- A function has many branches but the tests only exercise the
|
|
happy path. Add error-path tests with `expectError`.
|
|
- A switch over many enum variants only tests one. Loop the test
|
|
over all variants.
|
|
- Code is dead. Either start using it or delete it.
|
|
|
|
**Don't game the metric.** If you find yourself adding tests that
|
|
don't actually verify behavior just to pump the percentage —
|
|
`try expect(true)` calls, tests that only construct types and
|
|
check field defaults, etc. — stop. The gate exists to catch real
|
|
regressions in test discipline; gaming it produces tests that
|
|
will fail to catch real bugs later.
|
|
|
|
### Adding a new CLI command
|
|
|
|
1. Create `src/commands/newcmd.zig` with a `pub fn run(allocator, *DataService, symbol, color, *Writer) !void`
|
|
2. Add the import to the `commands` struct in `src/main.zig`
|
|
3. Add the dispatch branch in `main.zig`'s command matching chain
|
|
4. Update the `usage` string in `main.zig`
|
|
|
|
### Adding a new provider
|
|
|
|
1. Create `src/providers/newprovider.zig` following the existing struct pattern
|
|
2. Add a field to `DataService` (e.g., `np: ?NewProvider = null`)
|
|
3. Add the API key to `Config` (e.g., `newprovider_key: ?[]const u8 = null`) — the field name must be the lowercased type name + `_key` for the comptime `getProvider` lookup to work
|
|
4. Wire `resolve("NEWPROVIDER_API_KEY")` in `Config.fromEnv`
|
|
|
|
### Adding a new TUI tab
|
|
|
|
The TUI uses a comptime-derived tab registry (`tab_modules` in
|
|
`src/tui.zig`). Adding a new tab is one append to the registry
|
|
plus a tab module that conforms to the framework contract. The
|
|
`Tab` enum, tab-bar label, `TabStates` aggregator, key/mouse
|
|
dispatch, help overlay, status hint, and draw routing all flow
|
|
from the registry at comptime — App needs no hand-edits.
|
|
|
|
1. **Create `src/tui/newtab_tab.zig`** with:
|
|
- `pub const Action = enum { ... };` — tab-local keybind
|
|
actions (or empty).
|
|
- `pub const State = struct { ... };` — tab-private state
|
|
(cursor, expansion flags, cached load state, etc).
|
|
- `pub const tab = struct { ... };` — the framework
|
|
contract: `label`, `default_bindings`, `action_labels`,
|
|
`status_hints`, lifecycle hooks (`init`, `deinit`,
|
|
`activate`, `deactivate`, `reload`, `tick`),
|
|
`handleAction`, optional event hooks (`handleKey`,
|
|
`handleMouse`, `handlePaste`, `statusOverride`,
|
|
`onSymbolChange`, `onScroll`, `onCursorMove`,
|
|
`isDisabled`).
|
|
- **Exactly one** of `pub fn buildStyledLines(state, app, arena)`
|
|
(line-list rendering) or `pub fn drawContent(state, app,
|
|
arena, buf, width, height)` (direct cell-buffer rendering,
|
|
for charts). The framework validator enforces this.
|
|
2. **Append to `tab_modules`** at the top of `src/tui.zig`:
|
|
`.newtab = @import("tui/newtab_tab.zig"),`
|
|
3. Done. The compiler's framework validator (in
|
|
`tab_framework.validateTabModule`) will reject the build
|
|
with a precise message if any required hook is missing or
|
|
has the wrong signature. There's also a comptime check that
|
|
the tab's keybindings don't conflict with the global keymap.
|
|
|
|
For the contract details, read the doc-block at the top of
|
|
`src/tui/tab_framework.zig` — it shows the full required
|
|
shape with example signatures.
|
|
|
|
### `anytype` is almost never the right answer — pause and ask first
|
|
|
|
Empirically, every time `anytype` looked necessary in this codebase
|
|
it turned out not to be. Concrete-typed parameters always worked
|
|
once we actually tried them. **Before adding any new `anytype`
|
|
parameter, stop and reconsider.** The discussion that surfaces "no,
|
|
this can be `*App` after all" is short and worth having every time.
|
|
|
|
Common reasons people reach for `anytype` and what to do instead:
|
|
|
|
- **"I want to avoid a circular import."** Test the assumption.
|
|
Zig resolves `a.zig ↔ b.zig` cycles fine in most cases — file
|
|
structs are evaluated lazily, and the cycle only fails if
|
|
evaluation actually loops. Just write the concrete type and run
|
|
`zig build`. If it fails, the answer is usually to extract the
|
|
shared type to a third file, not to weaken the contract with
|
|
`anytype`. (See: the `tab_framework.zig` ↔ `tui.zig` cycle —
|
|
caught me once; turned out Zig handled it cleanly.)
|
|
- **"This function is genuinely polymorphic over many types."**
|
|
In Zig, the right shape for runtime polymorphism is usually
|
|
`*anyopaque` + an explicit cast at the boundary, paired with
|
|
a vtable struct of fn pointers. That's harder to abuse than
|
|
`anytype` and the cast site documents the type contract
|
|
unambiguously. Compile-time polymorphism over a known set of
|
|
types is better expressed with `comptime T: type` parameters.
|
|
- **"It's an event union and I don't want to pattern-match in
|
|
every caller."** Split the contract by event class
|
|
(`handleKey`, `handleMouse`, `handlePaste`) and let the
|
|
dispatcher do the discrimination once. Each method gets a
|
|
concrete type; tabs that don't care about a class simply omit
|
|
the method.
|
|
- **"It's a test helper that takes any struct."** This is the
|
|
one case where `anytype` is sometimes OK — generic test
|
|
utilities like `std.testing.expectEqual`. But check whether
|
|
a concrete type would do.
|
|
|
|
The real cost of `anytype` is that it punches a hole in the type
|
|
contract: the compiler can't catch wrong-shape arguments at the
|
|
boundary, signatures stop being self-documenting, and each
|
|
callsite gets monomorphized into its own instantiation that may
|
|
or may not behave the same as the others. The framework's whole
|
|
point is "let the compiler enforce the shape." `anytype` defeats
|
|
that.
|
|
|
|
If you've considered the alternatives above and still believe
|
|
`anytype` is correct, **flag it in your message to the user
|
|
before writing the code.** Phrase it as "I think this needs
|
|
`anytype` because X — does that match your intuition?" so the
|
|
default is discussion, not silently-typed-loose code.
|
|
|
|
### Command `run()` signatures — allocator as code smell
|
|
|
|
A CLI command's `run()` function that takes `*DataService` and `*std.Io.Writer`
|
|
usually doesn't also need an `std.mem.Allocator` parameter. `FetchResult(T)`
|
|
carries its own allocator and self-deinits (see `src/service.zig`), so callers
|
|
never need to wire up matching allocators for payload cleanup. The writer
|
|
owns its own buffer.
|
|
|
|
If a new `run()` signature still wants an allocator, ask whether the work
|
|
it's funding is:
|
|
|
|
- **Legitimate**: file I/O for a secondary config (portfolio load,
|
|
metadata), non-trivial intermediate computation, or an arena wrapping
|
|
view-layer allocations. Keep it.
|
|
- **Suspicious**: freeing `FetchResult.data` manually instead of calling
|
|
`result.deinit()`, or duplicating strings that could be borrowed.
|
|
Drop the allocator and fix the leak-shaped helper.
|
|
|
|
Not a hard rule — just a signal worth questioning when reviewing a new
|
|
command.
|
|
|
|
## Gotchas
|
|
|
|
- **Provider field naming is comptime-derived.** `DataService.getProvider(T)` finds the `?T` field by iterating struct fields at comptime, and the config key is derived by lowercasing the type name and appending `_key`. If you rename a provider struct, you must also rename the config field or the comptime logic breaks.
|
|
|
|
- **Candle data has two cache files.** `candles_daily.srf` holds the actual OHLCV data; `candles_meta.srf` holds metadata (last_date, provider, fail_count). When invalidating candles, both must be cleared (this is handled by `DataService.invalidate`).
|
|
|
|
- **TwelveData candles are force-refetched.** Cached candles from the TwelveData provider are treated as stale regardless of TTL because TwelveData's `adj_close` values were found to be unreliable. The code in `getCandles` explicitly checks `m.provider == .twelvedata` and falls through.
|
|
|
|
- **Mutual fund detection is heuristic.** `isMutualFund` checks if the symbol is exactly 5 chars ending in 'X'. This skips earnings fetching for mutual funds. It's imperfect but covers the common case.
|
|
|
|
- **SRF string lifetimes.** When reading SRF records, string fields point into the iterator's internal buffer. If you need strings to outlive the iterator, use a `postProcess` callback to `allocator.dupe()` them (see `dividendPostProcess` in `service.zig`).
|
|
|
|
- **Buffered stdout.** CLI output uses a single `std.Io.Writer` with a 4096-byte stack buffer, flushed once at the end of `main()`. Don't write to stdout through other means.
|
|
|
|
- **The `color` parameter flows through everything.** CLI commands accept a `color: bool` parameter. Don't use ANSI escapes unconditionally — always gate on the `color` flag.
|
|
|
|
- **Portfolio auto-detection.** Both CLI and TUI auto-load `portfolio.srf` from cwd if no explicit path is given. If not found in cwd, falls back to `$ZFIN_HOME/portfolio.srf`. `watchlist.srf` and `.env` follow the same cascade. `metadata.srf` and `accounts.srf` are loaded from the same directory as the resolved portfolio file.
|
|
|
|
- **`transaction_log.srf` is a sibling file.** Optional. Lives next to `portfolio.srf` / `accounts.srf`. Holds user-declared `transfer::` records so the contributions pipeline can tell internal account-to-account movement apart from real external contributions. Only `type::cash` is wired in v1 — `type::in_kind` parses but is rejected downstream. Missing file → matcher is a no-op. See `REPORT.md` §5 "Transfer log" for the user-facing guide.
|
|
|
|
- **Server sync is optional.** The `ZFIN_SERVER` env var enables parallel cache syncing from a remote zfin-server instance. All server sync code silently no-ops when the URL is null.
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Purpose |
|
|
|------------|---------|
|
|
| [SRF](https://git.lerch.org/lobo/srf) | Cache file format, portfolio/watchlist parsing, serialization |
|
|
| [libvaxis](https://github.com/rockorager/libvaxis) (v0.6.0) | Terminal UI rendering |
|
|
| [z2d](https://github.com/vancluever/z2d) (v0.11.0) | Pixel chart rendering (Kitty graphics protocol) |
|
|
|
|
## Build system rules
|
|
|
|
- **Never use `addAnonymousImport`** in `build.zig`. Always use `b.addModule()` + `addImport()`. Anonymous imports cause "file belongs to multiple modules" errors and make dependency wiring opaque.
|