diff --git a/README.md b/README.md index d42248e..40662fb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # zfin -A financial data library, CLI, and terminal UI written in Zig. Tracks portfolios, analyzes trailing returns, displays options chains, earnings history, and more -- all from the terminal. +A financial data library, CLI, and terminal UI written in Zig. Tracks portfolios, analyzes trailing returns, displays options chains and earnings history, and renders price and projection charts (inline Kitty graphics or PNG export) -- all from the terminal. ## Quick start @@ -102,60 +102,124 @@ caching/TTL model, and the complete environment-variable list, see ``` src/ - root.zig Library root, exports all public types - format.zig Shared formatters, braille engine, ANSI helpers - config.zig Configuration from env vars / .env files - service.zig DataService: cache-check -> fetch -> cache -> return + main.zig CLI dispatch + TUI entry point + root.zig Library root, exports all public types + Config.zig Configuration from env vars / .env files + service.zig DataService: cache-check -> fetch -> cache -> return + Date.zig Date type (i32 days since epoch); arithmetic, formatting + Money.zig Money formatting ($1,234.56; whole/trim/signed variants) + format.zig Shared formatters, braille engine, ANSI helpers + padded.zig Generic width/alignment wrapper for any formattable type + PortfolioData.zig Per-portfolio parse, price fetch, summary, background workers + portfolio_loader.zig Loads + union-merges portfolio_*.srf for CLI and TUI + compare.zig Composes two points in time (snapshot vs live) for `compare` + history.zig Reads history/-portfolio.srf snapshots; aggregation + market.zig Market calendar; close-anchored cache freshness + git.zig Thin git subprocess wrappers (diff/walk tracked portfolios) + atomic.zig Crash-safe atomic file writes (tmp + fsync + rename) + stderr.zig Best-effort (non-throwing) stderr hint/progress writers + term_graphics.zig Kitty graphics emission for plain (non-TUI) CLI charts + term_query.zig Terminal capability probing for inline CLI graphics + chart_export.zig Chart-to-PNG export (`--export-chart `) + comptime_validator.zig Shared comptime contract-validation helpers models/ - candle.zig OHLCV price bars - date.zig Date type with arithmetic, snapping, formatting - dividend.zig Dividend records with type classification - split.zig Stock splits - option.zig Option contracts and chains - earnings.zig Earnings events with surprise calculation - etf_profile.zig ETF profiles with holdings and sectors - portfolio.zig Lots, positions, and portfolio aggregation - classification.zig Classification metadata parser - quote.zig Real-time quote data + candle.zig OHLCV price bars + quote.zig Real-time quote data + dividend.zig Dividend records with type classification + split.zig Stock splits + option.zig Option contracts and chains + earnings.zig Earnings events with surprise calculation + etf_profile.zig ETF profiles with holdings and sectors + portfolio.zig Lots, positions, and portfolio aggregation + classification.zig Classification metadata parser + snapshot.zig Snapshot record types (history/*-portfolio.srf wire format) + transaction_log.zig transaction_log.srf wire format (transfer:: records) + shiller_year.zig One year of Shiller returns (S&P / bond / CPI) providers/ - tiingo.zig Tiingo: daily candles (primary), supplementary div/split merge - twelvedata.zig TwelveData: quote fallback - polygon.zig Polygon: dividends, splits (primary, with forward-looking entries) - fmp.zig FMP: earnings (actuals + estimates) - cboe.zig CBOE: options chains (no API key) - Edgar.zig SEC EDGAR: ETF profiles (NPORT-P), mutual-fund ticker map, XBRL company facts - Wikidata.zig Wikidata SPARQL: classification metadata for `enrich` - yahoo.zig Yahoo Finance: quotes (primary), candles (Tiingo fallback) - openfigi.zig OpenFIGI: CUSIP to ticker lookup - xml.zig Vendored XML parser used by Edgar.zig (see "Vendored code") + tiingo.zig Tiingo: daily candles (primary) + yahoo.zig Yahoo Finance: quotes (primary), candle fallback + twelvedata.zig TwelveData: quote fallback + polygon.zig Polygon: dividends, splits (with forward-looking entries) + fmp.zig FMP: earnings (actuals + estimates) + cboe.zig CBOE: options chains (no API key) + Edgar.zig SEC EDGAR: ETF profiles (NPORT-P), ticker map, XBRL facts + Wikidata.zig Wikidata SPARQL: classification metadata for `enrich` + openfigi.zig OpenFIGI: CUSIP to ticker lookup + json_utils.zig Shared JSON parsing helpers + xml.zig Vendored XML parser used by Edgar.zig (see "Vendored code") analytics/ - indicators.zig SMA, Bollinger Bands, RSI - performance.zig Trailing returns (as-of-date + month-end) - risk.zig Volatility, Sharpe, drawdown - valuation.zig Portfolio summary, allocations, covered call adjustments - analysis.zig Portfolio analysis engine (breakdowns by class/sector/geo/account/tax) + indicators.zig SMA, Bollinger Bands, RSI + performance.zig Trailing returns (as-of-date + month-end) + risk.zig Per-symbol volatility, Sharpe, drawdown + portfolio_risk.zig Correlation-aware portfolio-level risk + valuation.zig Portfolio summary, allocations, covered-call adjustments + analysis.zig Breakdowns by class/sector/geo/account/tax + benchmark.zig Per-position benchmark returns + exposure.zig Look-through exposure (direct + ETF holdings) + milestones.zig Retirement-attainment grid + projections.zig Monte Carlo + percentile bands + forecast_evaluation.zig Forecast-vs-actual (convergence + return back-test) + observations.zig Portfolio sanity checks for the review surface + timeline.zig History-tab tier rollup + data/ + ie_data.csv Raw Shiller S&P 500 + CPI dataset (CSV) + shiller.zig Shiller series, comptime-generated from ie_data.csv + imported_values.zig Back-history portfolio values (imported from spreadsheet) + staleness.zig Account-cadence staleness checks + Journal.zig acknowledgments.srf journal (acknowledged findings) + brokerage/ + types.zig Normalized BrokeragePosition record + dollar parser + fidelity.zig Fidelity "Download Positions" CSV parser + schwab.zig Schwab export parser + wells_fargo.zig Wells Fargo export parser + views/ + portfolio_sections.zig Portfolio view model (renderer-agnostic StyleIntent) + compare.zig Compare view model + history.zig History view model + projections.zig Projections view model + review.zig Per-holding performance + risk dashboard view model + observations_view.zig Findings list (engine output + acknowledgments) cache/ - store.zig SRF file cache with TTL freshness checks - net/ - http.zig HTTP client with retries and server error retry - rate_limiter.zig Token-bucket rate limiter + store.zig SRF file cache with TTL freshness checks + net/ + http.zig HTTP client with retries and server-error retry + RateLimiter.zig Token-bucket rate limiter commands/ - common.zig Shared CLI helpers (progress, formatting) - perf.zig Trailing returns command - quote.zig Quote command - ... (14 command files) - tui.zig Interactive TUI application + common.zig Shared CLI helpers (progress, formatting, color) + framework.zig CLI command framework + portfolio pattern resolution + TimeRange.zig Shared --range / time-window parsing + audit/ Brokerage reconciliation helpers for `audit` + (one .zig per CLI command: perf, quote, portfolio, analysis, history, ...) + charts/ + chart.zig Price + Bollinger + volume + RSI renderer (z2d) + projection_chart.zig Percentile-band + median projection renderer + forecast_chart.zig Convergence / back-test line renderer + line_chart.zig Single-series value-over-time line renderer + axis.zig Shared axis-label helpers + draw.zig Shared z2d drawing primitives + text.zig 5x7 bitmap font for axis labels + tui.zig Interactive TUI App orchestrator tui/ - chart.zig z2d pixel chart renderer (Kitty graphics) - keybinds.zig Configurable keybinding system - theme.zig Configurable color theme + tab_framework.zig Tab contract + comptime validator + keybinds.zig Configurable keybinding system + theme.zig Configurable color theme + input_buffer.zig Modal text-input state machine + (nine *_tab.zig tabs: portfolio, analysis, review, projections, + history, quote, performance, earnings, options) + version.zig Build version string ``` -Data files (user-managed, in project root): +Data files (user-managed, auto-detected in cwd or `$ZFIN_HOME`): ``` -portfolio.srf Portfolio lots -metadata.srf Classification metadata for analysis -accounts.srf Account to tax type mapping for analysis +portfolio.srf Portfolio lots (positions and cost basis) +accounts.srf Account -> tax-type mapping for analysis +metadata.srf Per-symbol classification (class/sector/geo) for analysis +watchlist.srf Symbols to track in the TUI watchlist +transaction_log.srf Declared transfers so contributions math skips internal moves +projections.srf Retirement / Monte Carlo projection assumptions +theme.srf TUI color theme overrides +keys.srf TUI keybinding overrides +acknowledgments.srf Acknowledged review-tab findings (app-maintained) ``` ### Dependencies @@ -165,6 +229,7 @@ accounts.srf Account to tax type mapping for analysis | [SRF](https://git.lerch.org/lobo/srf) | Git | Cache file format and portfolio/watchlist parsing | | [libvaxis](https://github.com/rockorager/libvaxis) | Git (v0.6.0) | Terminal UI rendering | | [z2d](https://github.com/vancluever/z2d) | Git (v0.11.0) | Pixel chart rendering (Kitty graphics protocol) | +| [zeit](https://github.com/rockorager/zeit) | Git (v0.9.0) | Calendar arithmetic + timezone conversion (ET) | ## Building