phase-7: code restructure

server/config/ScoringConfig.ts

@@ -1,4 +1,4 @@
-import type { Sector } from './constants.js';
+import type { ScoringRulesShape } from '../types';
 
 // ── Credit rating scale (S&P convention) ─────────────────────────────────
 // Bond.ts converts letter ratings to these numbers; BondScorer uses them for gate checks.
@@ -17,26 +17,8 @@ export const CREDIT_RATING_SCALE: Record<string, number> = {
 };
 
 // ── Scoring rule shape ────────────────────────────────────────────────────
-
-interface GateSet extends Record<string, number> {}
-interface WeightSet extends Record<string, number> {}
-interface ThresholdSet extends Record<string, number> {}
-
-interface RuleBlock {
-  gates: GateSet;
-  weights: WeightSet;
-  thresholds: ThresholdSet;
-}
-
-interface StockRules extends RuleBlock {
-  SECTOR_OVERRIDE: Partial<Record<Sector, Partial<RuleBlock>>>;
-}
-
-interface ScoringRulesShape {
-  STOCK: StockRules;
-  ETF: RuleBlock;
-  BOND: RuleBlock;
-}
+// Structural shapes (GateSet/WeightSet/ThresholdSet/RuleBlock/StockRules/
+// ScoringRulesShape) live in server/types/asset.model.ts.
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Fundamental baseline — Graham / value-investing style.
@@ -58,6 +40,8 @@ export const ScoringRules: ScoringRulesShape = {
       peg: 2, // valuation relative to growth
       revenue: 2, // revenue growth
       fcf: 3, // FCF is the most manipulation-resistant quality signal
+      analyst: 2, // Wall Street consensus (1=Strong Buy … 5=Strong Sell, inverted in scorer)
+      dcf: 2, // DCF margin of safety: positive = undervalued vs intrinsic value
     },
     thresholds: {
       marginHigh: 15, // 15% net margin is genuinely excellent across most sectors
@@ -72,6 +56,12 @@ export const ScoringRules: ScoringRulesShape = {
       revMed: 5,
       fcfHigh: 5,
       fcfMed: 2,
+      // Analyst consensus thresholds (Yahoo recommendationMean scale: 1=Strong Buy, 5=Strong Sell)
+      analystBuy: 2.0, // ≤ 2.0 → consensus is Buy or better
+      analystHold: 3.0, // ≤ 3.0 → consensus is Hold or better
+      // DCF margin-of-safety thresholds (% undervaluation vs intrinsic value)
+      dcfUndervalued: 20, // ≥ 20% margin of safety → undervalued
+      dcfFairValue: 0, // 0–20% → fairly valued; negative → overvalued
     },
 
     SECTOR_OVERRIDE: {

server/config/constants.ts

@@ -1,4 +1,4 @@
-import type { Signal, AssetType, RateRegime } from '../types.js';
+import type { Signal, AssetType, RateRegime } from '../types';
 
 export const SIGNAL = {
   STRONG_BUY: '✅ Strong Buy' as Signal,
@@ -6,14 +6,28 @@ export const SIGNAL = {
   SPECULATION: '⚠️  Speculation' as Signal,
   NEUTRAL: '🔄 Neutral' as Signal,
   AVOID: '❌ Avoid' as Signal,
-} as const;
+};
 
 export const ASSET_TYPE = {
   STOCK: 'STOCK' as AssetType,
   ETF: 'ETF' as AssetType,
   BOND: 'BOND' as AssetType,
   CRYPTO: 'crypto',
-} as const;
+};
+
+// ── Why some constants use `as const` and others don't ────────────────────
+//
+// SIGNAL / ASSET_TYPE / REGIME — each member is individually cast to its
+// named type (e.g. `'✅ Strong Buy' as Signal`).  TypeScript already knows
+// the exact literal type of each value, so `as const` on the object would
+// be redundant.
+//
+// SECTOR / SCORE_MODE / CAP_CATEGORY / GROWTH_CATEGORY — these use
+// `as const` because their public type aliases are *derived* from the
+// object itself via `(typeof X)[keyof typeof X]`.  Without `as const`,
+// TypeScript widens every value to `string`, and the derived union
+// collapses to `string` instead of `'TECHNOLOGY' | 'REIT' | ...`.
+// ──────────────────────────────────────────────────────────────────────────
 
 export const SECTOR = {
   TECHNOLOGY: 'TECHNOLOGY',
@@ -38,7 +52,7 @@ export const REGIME = {
   LOW: 'LOW' as RateRegime,
   NORMAL: 'NORMAL' as RateRegime,
   HIGH: 'HIGH' as RateRegime,
-} as const;
+};
 
 export const YAHOO_MODULES: string[] = [
   'assetProfile',
@@ -55,3 +69,29 @@ export const SIGNAL_ORDER: Record<string, number> = {
   [SIGNAL.SPECULATION]: 3,
   [SIGNAL.AVOID]: 4,
 };
+
+// ── Market capitalisation tiers ───────────────────────────────────────────
+// Thresholds follow institutional convention (MSCI/Russell definitions).
+export const CAP_CATEGORY = {
+  MEGA: 'Mega Cap', // > $200B
+  LARGE: 'Large Cap', // $10B – $200B
+  MID: 'Mid Cap', // $2B – $10B
+  SMALL: 'Small Cap', // $300M – $2B
+  MICRO: 'Micro Cap', // < $300M
+} as const;
+
+export type CapCategory = (typeof CAP_CATEGORY)[keyof typeof CAP_CATEGORY];
+
+// ── Growth / style classification ─────────────────────────────────────────
+// Derived from revenue growth, earnings growth, and dividend yield.
+// Used for display and to contextualise signals within each cap tier.
+export const GROWTH_CATEGORY = {
+  HIGH_GROWTH: 'High Growth', // rev >15% or earnings >20%
+  MODERATE_GROWTH: 'Growth', // rev 5–15%
+  STABLE: 'Stable', // low growth, modest or no dividend
+  VALUE: 'Value', // low growth + dividend yield ≥ 3%
+  TURNAROUND: 'Turnaround', // negative earnings, positive revenue
+  DECLINING: 'Declining', // negative revenue growth
+} as const;
+
+export type GrowthCategory = (typeof GROWTH_CATEGORY)[keyof typeof GROWTH_CATEGORY];