phase-6: typescript introduction

2026-06-04 22:16:48 -04:00
parent de8427d578
commit 2b785aa861
69 changed files with 2323 additions and 1036 deletions
@@ -1,73 +0,0 @@
-import { YahooClient } from './YahooClient.js';
-import { REGIME } from '../config/constants.js';
-
-const TTL_MS = 60 * 60 * 1000;
-
-const DEFAULTS = {
-  sp500Price: 5000,
-  riskFreeRate: 4.5,
-  vixLevel: 20,
-  rateRegime: REGIME.HIGH,
-  volatilityRegime: REGIME.NORMAL,
-  benchmarks: { marketPE: 22, techPE: 30, reitYield: 3.5, igSpread: 1.0 },
-};
-
-const rateRegime = (rate) => (rate < 2 ? REGIME.LOW : rate <= 5 ? REGIME.NORMAL : REGIME.HIGH);
-const volRegime = (vix) => (vix < 15 ? REGIME.LOW : vix <= 25 ? REGIME.NORMAL : REGIME.HIGH);
-
-const pe = (summary) =>
-  summary.summaryDetail?.trailingPE ?? summary.defaultKeyStatistics?.forwardPE;
-
-export class BenchmarkProvider {
-  // logger: object with .warn() — defaults to console so CLI behaviour is unchanged.
-  constructor({ logger = console } = {}) {
-    this.client = new YahooClient();
-    this.cache = { data: null, expiresAt: 0 };
-    this.logger = logger;
-  }
-
-  async getMarketContext() {
-    if (this.cache.data && Date.now() < this.cache.expiresAt) return this.cache.data;
-
-    try {
-      const [sp500, tn10y, vix, spy, xlk, xlre, lqd] = await Promise.all([
-        this.client.fetchSummary('^GSPC'),
-        this.client.fetchSummary('^TNX'),
-        this.client.fetchSummary('^VIX'),
-        this.client.fetchSummary('SPY'),
-        this.client.fetchSummary('XLK'),
-        this.client.fetchSummary('XLRE'),
-        this.client.fetchSummary('LQD'),
-      ]);
-
-      const riskFreeRate = tn10y.price?.regularMarketPrice ?? 0;
-      const sp500Price = sp500.price?.regularMarketPrice ?? 0;
-      const vixLevel = vix.price?.regularMarketPrice ?? 0;
-
-      if (!sp500Price || !riskFreeRate) throw new Error('Invalid market data (zero values)');
-
-      const lqdYield = (lqd.summaryDetail?.trailingAnnualDividendYield ?? 0) * 100;
-
-      const context = {
-        sp500Price,
-        riskFreeRate,
-        vixLevel,
-        rateRegime: rateRegime(riskFreeRate),
-        volatilityRegime: volRegime(vixLevel),
-        benchmarks: {
-          marketPE: pe(spy) ?? 22,
-          techPE: pe(xlk) ?? 30,
-          reitYield: (xlre.summaryDetail?.trailingAnnualDividendYield ?? 0.035) * 100,
-          igSpread: Math.max(0.1, lqdYield - riskFreeRate),
-        },
-        timestamp: new Date().toISOString(),
-      };
-
-      this.cache = { data: context, expiresAt: Date.now() + TTL_MS };
-      return context;
-    } catch (err) {
-      this.logger.warn('Market data fetch failed, using defaults:', err.message);
-      return this.cache.data ?? DEFAULTS;
-    }
-  }
-}
@@ -0,0 +1,87 @@
+import { YahooClient } from './YahooClient.js';
+import { REGIME } from '../config/constants.js';
+import type { MarketContext, Logger } from '../types.js';
+
+const TTL_MS = 60 * 60 * 1000;
+
+const DEFAULTS: MarketContext = {
+  sp500Price: 5000,
+  riskFreeRate: 4.5,
+  vixLevel: 20,
+  rateRegime: 'HIGH',
+  volatilityRegime: 'NORMAL',
+  benchmarks: { marketPE: 22, techPE: 30, reitYield: 3.5, igSpread: 1.0 },
+};
+
+const rateRegime = (rate: number): MarketContext['rateRegime'] =>
+  rate < 2 ? REGIME.LOW : rate <= 5 ? REGIME.NORMAL : REGIME.HIGH;
+
+const volRegime = (vix: number): MarketContext['volatilityRegime'] =>
+  vix < 15 ? REGIME.LOW : vix <= 25 ? REGIME.NORMAL : REGIME.HIGH;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const pe = (summary: any): number | null =>
+  summary?.summaryDetail?.trailingPE ?? summary?.defaultKeyStatistics?.forwardPE ?? null;
+
+interface BenchmarkProviderOptions {
+  logger?: Logger;
+}
+
+export class BenchmarkProvider {
+  private client: YahooClient;
+  private cache: { data: MarketContext | null; expiresAt: number };
+  private logger: Logger;
+
+  constructor({ logger }: BenchmarkProviderOptions = {}) {
+    this.client = new YahooClient();
+    this.cache = { data: null, expiresAt: 0 };
+    this.logger = logger ?? (console as unknown as Logger);
+  }
+
+  async getMarketContext(): Promise<MarketContext> {
+    if (this.cache.data && Date.now() < this.cache.expiresAt) return this.cache.data;
+
+    try {
+      const [sp500, tn10y, vix, spy, xlk, xlre, lqd] = await Promise.all([
+        this.client.fetchSummary('^GSPC'),
+        this.client.fetchSummary('^TNX'),
+        this.client.fetchSummary('^VIX'),
+        this.client.fetchSummary('SPY'),
+        this.client.fetchSummary('XLK'),
+        this.client.fetchSummary('XLRE'),
+        this.client.fetchSummary('LQD'),
+      ]);
+
+      const riskFreeRate =
+        (sp500 as any)?.price?.regularMarketPrice !== undefined
+          ? ((tn10y as any)?.price?.regularMarketPrice ?? 0)
+          : 0;
+      const sp500Price = (sp500 as any)?.price?.regularMarketPrice ?? 0;
+      const vixLevel = (vix as any)?.price?.regularMarketPrice ?? 0;
+
+      if (!sp500Price || !riskFreeRate) throw new Error('Invalid market data (zero values)');
+
+      const lqdYield = ((lqd as any)?.summaryDetail?.trailingAnnualDividendYield ?? 0) * 100;
+
+      const context: MarketContext = {
+        sp500Price,
+        riskFreeRate,
+        vixLevel,
+        rateRegime: rateRegime(riskFreeRate),
+        volatilityRegime: volRegime(vixLevel),
+        benchmarks: {
+          marketPE: pe(spy) ?? 22,
+          techPE: pe(xlk) ?? 30,
+          reitYield: ((xlre as any)?.summaryDetail?.trailingAnnualDividendYield ?? 0.035) * 100,
+          igSpread: Math.max(0.1, lqdYield - riskFreeRate),
+        },
+      };
+
+      this.cache = { data: context, expiresAt: Date.now() + TTL_MS };
+      return context;
+    } catch (err) {
+      this.logger.warn('Market data fetch failed, using defaults:', (err as Error).message);
+      return this.cache.data ?? DEFAULTS;
+    }
+  }
+}
@@ -1,8 +1,21 @@
 import { SECTOR, ASSET_TYPE, REGIME } from '../config/constants.js';
+import type { MarketContext, AssetType } from '../types.js';
+
+interface InflatedOverrides {
+  gates: Record<string, number>;
+  thresholds: Record<string, number>;
+}

 export class MarketRegime {
-  constructor(marketContext) {
-    const b = marketContext?.benchmarks ?? {};
+  private marketPE: number;
+  private techPE: number;
+  private reitYield: number;
+  private igSpread: number;
+  private rateRegime: string;
+  private volatilityRegime: string;
+
+  constructor(marketContext: Partial<MarketContext>) {
+    const b = marketContext?.benchmarks ?? ({} as MarketContext['benchmarks']);
    this.marketPE = b.marketPE ?? 22;
    this.techPE = b.techPE ?? 30;
    this.reitYield = b.reitYield ?? 3.5;
@@ -11,18 +24,17 @@ export class MarketRegime {
    this.volatilityRegime = marketContext?.volatilityRegime ?? REGIME.NORMAL;
  }

-  getInflatedOverrides(type, sector) {
+  getInflatedOverrides(type: AssetType, sector?: string): InflatedOverrides {
    if (type === ASSET_TYPE.STOCK) return this._stock(sector);
    if (type === ASSET_TYPE.ETF) return this._etf();
    if (type === ASSET_TYPE.BOND) return this._bond();
    return { gates: {}, thresholds: {} };
  }

-  _stock(sector) {
+  private _stock(sector?: string): InflatedOverrides {
    if (sector === SECTOR.REIT) {
      return {
        gates: {},
-        // In HIGH rate environment tighten REIT yield floor — REITs must compete harder with bonds.
        thresholds: {
          minYield: +(this.reitYield * (this.rateRegime === REGIME.HIGH ? 0.95 : 0.85)).toFixed(2),
          maxPFFO: 20,
@@ -38,8 +50,6 @@ export class MarketRegime {
        thresholds: {},
      };
    }
-    // In HIGH rate environment, compress the P/E tolerance — higher rates mean
-    // future earnings are discounted more aggressively (lower DCF valuations).
    const peMultiplier = this.rateRegime === REGIME.HIGH ? 1.2 : 1.5;
    return {
      gates: {
@@ -50,14 +60,15 @@ export class MarketRegime {
    };
  }

-  _etf() {
+  private _etf(): InflatedOverrides {
    return { gates: { maxExpenseRatio: 0.75 }, thresholds: { minYield: 0.5 } };
  }

-  _bond() {
-    // In HIGH rate environment demand a wider spread — the opportunity cost of holding
-    // corporate bonds over Treasuries is higher when risk-free rate is elevated.
+  private _bond(): InflatedOverrides {
    const spreadMultiplier = this.rateRegime === REGIME.HIGH ? 0.9 : 0.8;
-    return { gates: {}, thresholds: { minSpread: +(this.igSpread * spreadMultiplier).toFixed(2) } };
+    return {
+      gates: {},
+      thresholds: { minSpread: +(this.igSpread * spreadMultiplier).toFixed(2) },
+    };
  }
 }
@@ -1,40 +0,0 @@
-import YahooFinance from 'yahoo-finance2';
-
-export class YahooClient {
-  constructor() {
-    // Instantiate the client as required by v3
-    this.yf = new YahooFinance({
-      suppressNotices: ['yahooSurvey'],
-    });
-  }
-
-  async fetchSummary(ticker, retries = 3, backoff = 1000) {
-    for (let i = 0; i < retries; i++) {
-      try {
-        return await this.yf.quoteSummary(ticker, {
-          modules: [
-            'assetProfile',
-            'financialData',
-            'defaultKeyStatistics',
-            'price',
-            'summaryDetail',
-          ],
-        });
-      } catch (error) {
-        if (i === retries - 1) throw error;
-        await new Promise((res) => setTimeout(res, backoff * (i + 1)));
-      }
-    }
-  }
-
-  // Fetches upcoming earnings dates, ex-dividend date, and dividend date for a ticker.
-  // Returns null on failure so callers can skip gracefully.
-  async fetchCalendarEvents(ticker) {
-    try {
-      const r = await this.yf.quoteSummary(ticker, { modules: ['calendarEvents'] });
-      return r.calendarEvents ?? null;
-    } catch {
-      return null;
-    }
-  }
-}
@@ -0,0 +1,42 @@
+import YahooFinance from 'yahoo-finance2';
+
+export class YahooClient {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private yf: any;
+
+  constructor() {
+    this.yf = new (YahooFinance as unknown as new (opts: object) => unknown)({
+      suppressNotices: ['yahooSurvey'],
+    });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async fetchSummary(ticker: string, retries = 3, backoff = 1000): Promise<any> {
+    for (let i = 0; i < retries; i++) {
+      try {
+        return await (this.yf as any).quoteSummary(ticker, {
+          modules: [
+            'assetProfile',
+            'financialData',
+            'defaultKeyStatistics',
+            'price',
+            'summaryDetail',
+          ],
+        });
+      } catch (error) {
+        if (i === retries - 1) throw error;
+        await new Promise<void>((res) => setTimeout(res, backoff * (i + 1)));
+      }
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async fetchCalendarEvents(ticker: string): Promise<any | null> {
+    try {
+      const r = await (this.yf as any).quoteSummary(ticker, { modules: ['calendarEvents'] });
+      return r.calendarEvents ?? null;
+    } catch {
+      return null;
+    }
+  }
+}