market_screener/CLAUDE.md

CLAUDE.md

Guidance for working in this repository.

Overview

market-screener is a Node.js CLI tool that screens stocks, ETFs, and bonds by fetching live data from Yahoo Finance and scoring each asset under two lenses:

• Market-Adjusted — gates derived from live Yahoo benchmarks (SPY P/E, XLK P/E, XLRE yield, LQD spread). Reflects what is acceptable in today's inflated market.
• Fundamental — strict Graham/value-investing style gates from ScoringConfig. Reflects genuine value regardless of market conditions.

The comparison produces a Signal (Strong Buy / Momentum / Speculation / Neutral / Avoid).

ES module project ("type": "module"); use import/export, not require.

Commands

npm install                                   # install dependencies (yahoo-finance2, dotenv, prettier)
npm start                                     # Yahoo news → catalyst tickers → screener-report.html
npm start -- watch                            # default watchlist
npm start -- AAPL MSFT VOO                    # specific tickers
npm run finance                               # portfolio advice + SimpleFIN → finance-report.html
npm run import-portfolio -- holdings.csv      # import Robinhood/Vanguard CSV into portfolio.json
npm test                                      # run all unit tests (node:test, zero deps)
npm run test:watch                            # watch mode during development
npm run format                                # format all src/bin/tests with Prettier
npm run format:check                          # check formatting without writing (CI)

Project Structure

bin/
  screen.js              ← market screener entry point
  finance.js             ← personal finance entry point
  import-portfolio.js    ← broker CSV importer

prompts/
  catalyst-analysis.md   ← daily catalyst analysis playbook (LLM prompt + workflow)

src/
  config/
    ScoringConfig.js     ← CREDIT_RATING_SCALE + ScoringRules (single source of truth)

  market/                ← Yahoo Finance data layer
    YahooClient.js       ← wraps yahoo-finance2 v3, retry + backoff
    BenchmarkProvider.js ← fetches ^GSPC, ^TNX, ^VIX, SPY, XLK, XLRE, LQD → marketContext
    MarketRegime.js      ← derives INFLATED gate overrides from live benchmarks

  screener/              ← core screening domain
    ScreenerEngine.js    ← orchestrates: fetch → score × 2 → HTML report
    DataMapper.js        ← normalises Yahoo payload → flat asset data object
    RuleMerger.js        ← merges base rules + sector overrides + MarketRegime (INFLATED mode)
    Chunker.js           ← splits ticker list into batches
    assets/
      Asset.js           ← abstract base: ticker, currentPrice, type, formatting helpers
      Stock.js           ← metrics: peRatio, pegRatio, priceToBook, ROE, opMargin, etc.
      Etf.js             ← metrics: expenseRatio, yield, totalAssets
      Bond.js            ← metrics: ytm, duration, creditRating, creditRatingNumeric
    scorers/
      StockScorer.js     ← gate checks + weighted registry (ROE, opMargin, margin, peg, rev, fcf)
      EtfScorer.js       ← expense gate + registry (cost, yield, volume)
      BondScorer.js      ← credit gate + spread/duration scoring

  analyst/
    CatalystAnalyst.js   ← fetches Yahoo Finance news, extracts relatedTickers

  finance/
    clients/
      SimpleFINClient.js ← claims setup token → access URL, fetches /accounts
    PersonalFinanceAnalyzer.js ← net worth, cash vs investments, spending by category
    PortfolioAdvisor.js  ← cross-references holdings with screener signals → hold/sell/add advice
    PortfolioImporter.js ← parses Robinhood/Vanguard/Fidelity CSV → merges into portfolio.json

  reporters/
    HtmlReporter.js      ← generates screener-report.html (tabbed inflated/fundamental views)
    FinanceReporter.js   ← generates finance-report.html (net worth, portfolio, spending)

portfolio.json           ← user's holdings: ticker, shares, costBasis, source, type

Data Flow

Yahoo Finance API
  ↓
BenchmarkProvider      — fetches ^GSPC, ^TNX, ^VIX, SPY, XLK, XLRE, LQD
                         builds marketContext { sp500Price, riskFreeRate, vixLevel,
                         rateRegime, volatilityRegime, benchmarks { marketPE, techPE, reitYield, igSpread } }
  ↓
DataMapper             — normalises raw Yahoo payload → flat data object with type (STOCK/ETF/BOND)
                         computes: pFFO proxy, FCF yield, computed PEG, 52-week position
  ↓
Asset subclass         — Stock / Etf / Bond holds metrics, formats display
  ↓
RuleMerger × 2        — FUNDAMENTAL mode: ScoringConfig as-is (Graham-style)
                         INFLATED mode:   sector override + MarketRegime live gate overrides
  ↓
Scorer × 2            — StockScorer / EtfScorer / BondScorer, fully stateless
  ↓
ScreenerEngine         — derives Signal from comparing both verdicts
  ↓
HtmlReporter           — screener-report.html: signal summary + two tabbed tables per asset class

Scoring Modes

Mode	P/E Gate (general)	Source
FUNDAMENTAL	20x	ScoringConfig (Graham)
INFLATED	S&P 500 P/E × 1.5	Live SPY data

Signal	Meaning
✅ Strong Buy	Passes both fundamental AND inflated gates
⚡ Momentum	Passes inflated, holds fundamentally
⚠️ Speculation	Passes inflated, fails fundamental
🔄 Neutral	Hold territory in one or both lenses
❌ Avoid	Fails both

ScoringConfig Structure

src/config/ScoringConfig.js exports two things:

• CREDIT_RATING_SCALE — { AAA: 10, AA: 9, ..., D: 1 }. Used by Bond.js and BondScorer.
• ScoringRules — per-type { gates, weights, thresholds } + SECTOR_OVERRIDE map for STOCK.

Sector overrides are structural (apply in both modes). MarketRegime overrides valuation gates in INFLATED mode only.

Sector Notes

• TECHNOLOGY — maxDebtToEquity: 2.0 (mega-cap tech borrows for buybacks), minQuickRatio: 0.8 (AAPL runs ~0.9). P/E and PEG gates inflated from XLK live data.
• REIT — P/E and PEG disabled (9999). Scored on dividend yield and P/FFO proxy. All base weights (margin, peg, revenue) explicitly zeroed out.
• FINANCIAL — P/E, PEG, D/E disabled. Scored on ROE + Price-to-Book. Quick ratio gate lowered (0.1).

MarketRegime (INFLATED overrides)

src/market/MarketRegime.js derives gate overrides from live benchmarks:

Gate	Formula
Stock maxPERatio	SPY trailing P/E × 1.5
Tech maxPERatio	XLK P/E × 1.3
Tech maxPegGate	XLK P/E ÷ 15
REIT minYield	XLRE dividend yield × 0.85
Bond minSpread	LQD−TNX spread × 0.80
ETF maxExpenseRatio	0.75% (structural loosening)

Missing Data Convention

• Missing metrics use null (not 0) in _sanitize. Gate checks skip null values rather than auto-failing.
• pegRatio falls back to trailingPE / earningsGrowth when Yahoo doesn't provide it.
• quickRatio falls back to currentRatio when missing.

SimpleFIN Auth Flow

1. User gets a Setup Token from https://beta-bridge.simplefin.org
2. SimpleFINClient.init() base64-decodes it → POSTs once to claim URL → receives Access URL
3. Access URL is auto-appended to .env as SIMPLEFIN_ACCESS_URL
4. All subsequent requests use Access URL directly (setup token is one-time use)

portfolio.json Format

{
  "holdings": [
    { "ticker": "AAPL",    "shares": 10,   "costBasis": 150.00, "source": "Robinhood", "type": "stock"  },
    { "ticker": "VOO",     "shares": 8,    "costBasis": 380.00, "source": "Vanguard",  "type": "etf"    },
    { "ticker": "BTC-USD", "shares": 0.25, "costBasis": 45000,  "source": "Coinbase",  "type": "crypto" }
  ]
}

type values: stock, etf, crypto. Crypto is priced via Yahoo (BTC-USD style) but not fundamentally scored.

Tests

Uses Node's built-in test runner (node:test + node:assert/strict) — no test framework to install.

tests/
  ScoringConfig.test.js    ← CREDIT_RATING_SCALE, gate values, sector overrides
  RuleMerger.test.js       ← FUNDAMENTAL vs INFLATED modes, sector merging
  MarketRegime.test.js     ← inflated override formulas per asset type and sector
  StockScorer.test.js      ← gate failures, scoring labels, risk flags
  EtfScorer.test.js        ← expense gate, score tiers
  BondScorer.test.js       ← credit gate, spread/duration scoring, unit handling
  DataMapper.test.js       ← type detection, PEG computation, null convention
  PortfolioAdvisor.test.js ← _position gain/loss calc, _advice signal mapping

Key unit to remember: ytm in Bond.metrics is stored as a percentage (e.g. 6.5 = 6.5%). BondScorer._sanitize divides by 100 before spread calculation. minSpread in ScoringConfig is also in percentage form (e.g. 1.0 = 1%).

Conventions

• Asset type (uppercased) is the routing key across DataMapper, asset classes, SCORERS map in ScreenerEngine, and ScoringRules.
• Prefer adjusting ScoringConfig or MarketRegime over hardcoding numbers in scorers.
• BenchmarkProvider caches for 1 hour — restart the process to force a fresh fetch during development.
• All entry points live in bin/. Do not add logic to entry points — they call into src/.

Planned Enhancements

1. Rate Sensitivity Flag (no new fetches needed)

Flag assets exposed to rate changes using riskFreeRate and rateRegime:

• Long-duration bonds (duration > 7) in HIGH rate regime → warn
• REITs with high D/E in HIGH rate regime → warn
• Growth stocks with negative FCF in HIGH rate regime → warn

2. 52-Week Positioning (data already mapped)

week52High and week52Low are in asset metrics. Add interpretation:

• > 85% position + high P/E = crowded/momentum trade
• < 15% position + passing fundamental gates = potential opportunity

3. Sector Rotation Cues (3–4 new fetches)

Add XLF, XLE, XLV, XLI to BenchmarkProvider. Compare each sector ETF's 1-year return to S&P 500 to identify leading/lagging sectors.

4. Client/Server Architecture

Planned split into:

• Server (Fastify + BullMQ) — API endpoints, webhook-driven news monitoring, WebSocket for live updates
• Client (SvelteKit) — interactive dashboard replacing the HTML reports
• LLM integration (Claude Haiku) wired into the server for deeper catalyst analysis

Adding a New Asset Type

1. Create a subclass of Asset in src/screener/assets/ with a flat metrics object and getDisplayMetrics().
2. Add a per-type entry (gates / weights / thresholds) to ScoringRules in ScoringConfig.js.
3. Add inflated overrides in MarketRegime.getInflatedOverrides().
4. Create a Scorer in src/screener/scorers/ exposing score(metrics, rules, marketContext).
5. Add a mapper in DataMapper.js.
6. Wire into ScreenerEngine: add case in _buildAsset, entry in SCORERS map.