fin-ratios 0.7.3 → 1.0.2

package/dist/index.cjs

@@ -119,10 +119,10 @@ gordonGrowthModel.formula = "D1 / (r - g)";
 gordonGrowthModel.description = "DDM for stable dividend-paying stocks. Only valid when r > g.";
 function reverseDcf(input) {
   const target = input.marketCap + (input.netDebt ?? 0);
-  const computeEV = (g5) => {
+  const computeEV = (g7) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g5,
+      growthRate: g7,
       years: input.years,
       terminalGrowthRate: input.terminalGrowthRate,
       wacc: input.wacc
@@ -452,8 +452,8 @@ function annualizeReturn(returnValue, periodsPerYear) {
 }
 function stdDev(values, ddof = 1) {
   if (values.length < 2) return null;
-  const mean5 = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean5, 2), 0) / (values.length - ddof);
+  const mean7 = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean7, 2), 0) / (values.length - ddof);
   return Math.sqrt(variance);
 }
 function mean(values) {
@@ -1947,8 +1947,8 @@ function fairValueRange(options) {
     if (fy && fy > 0) estimates[`FCF Yield (${(targetYield * 100).toFixed(0)}%)`] = fy;
   }
   if (eps && bvps) {
-    const g5 = grahamValue(eps, bvps);
-    if (g5 && g5 > 0) estimates["Graham Number"] = g5;
+    const g7 = grahamValue(eps, bvps);
+    if (g7 && g7 > 0) estimates["Graham Number"] = g7;
   }
   if (ebitda && ebitda > 0 && shares && shares > 0) {
     const v = evEbitdaValue(ebitda, totalDebt, cash, shares, evEbitdaMultiple);
@@ -2059,6 +2059,552 @@ function portfolioQuality(holdings, options = {}) {
   };
 }
 
+// src/utils/valuation-score.ts
+function _clamp(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function _lerp(x, x0, x1, y0, y1) {
+  if (x1 === x0) return y0;
+  const t = (x - x0) / (x1 - x0);
+  return y0 + _clamp(t, 0, 1) * (y1 - y0);
+}
+function scoreEarningsYield(params, rf) {
+  let ey = null;
+  if (params.earningsYieldPct !== void 0) {
+    ey = params.earningsYieldPct / 100;
+  } else if (params.peRatio !== void 0 && params.peRatio > 0) {
+    ey = 1 / params.peRatio;
+  }
+  if (ey === null) {
+    return [0.5, ["Earnings yield: no P/E or earnings yield data (neutral score)"]];
+  }
+  const excess = ey - rf;
+  const score = _lerp(excess, -0.04, 0.04, 0, 1);
+  const label = excess >= 0.02 ? "attractive" : excess >= 0 ? "slight premium" : "below risk-free";
+  return [score, [
+    `Earnings yield: ${(ey * 100).toFixed(2)}%  vs  risk-free ${(rf * 100).toFixed(2)}%  (spread ${excess >= 0 ? "+" : ""}${(excess * 100).toFixed(2)}%)`,
+    `Earnings yield spread: ${label}`
+  ]];
+}
+function scoreFcfYield(params) {
+  let fy = null;
+  if (params.fcfYieldPct !== void 0) {
+    fy = params.fcfYieldPct / 100;
+  } else if (params.pFcf !== void 0 && params.pFcf > 0) {
+    fy = 1 / params.pFcf;
+  }
+  if (fy === null) {
+    return [0.5, ["FCF yield: no P/FCF or FCF yield data (neutral score)"]];
+  }
+  let score;
+  if (fy < 0.02) {
+    score = _lerp(fy, -0.02, 0.02, 0, 0.3);
+  } else if (fy < 0.05) {
+    score = _lerp(fy, 0.02, 0.05, 0.3, 0.7);
+  } else {
+    score = _lerp(fy, 0.05, 0.08, 0.7, 1);
+  }
+  const label = fy >= 0.06 ? "excellent" : fy >= 0.04 ? "good" : fy >= 0.02 ? "modest" : "thin";
+  return [score, [
+    `FCF yield: ${(fy * 100).toFixed(2)}%  (${label})`
+  ]];
+}
+function scoreEvEbitda(params) {
+  if (params.evEbitda === void 0) {
+    return [0.5, ["EV/EBITDA: not provided (neutral score)"]];
+  }
+  const ev = params.evEbitda;
+  if (ev <= 0) {
+    return [0.2, ["EV/EBITDA: negative or zero (uninvestable or distressed)"]];
+  }
+  let score;
+  if (ev < 12) {
+    score = _lerp(ev, 5, 12, 1, 0.6);
+  } else if (ev < 20) {
+    score = _lerp(ev, 12, 20, 0.6, 0.2);
+  } else {
+    score = _lerp(ev, 20, 30, 0.2, 0.05);
+  }
+  const label = ev < 10 ? "deep value" : ev < 14 ? "reasonable" : ev < 20 ? "full valued" : "expensive";
+  return [score, [
+    `EV/EBITDA: ${ev.toFixed(1)}\xD7  (${label})`
+  ]];
+}
+function scorePbRatio(params) {
+  if (params.pbRatio === void 0) {
+    return [0.5, ["P/B ratio: not provided (neutral score)"]];
+  }
+  const pb2 = params.pbRatio;
+  if (pb2 <= 0) {
+    return [0.15, ["P/B ratio: negative book value \u2014 balance sheet impaired"]];
+  }
+  let score;
+  if (pb2 < 2) {
+    score = _lerp(pb2, 0.5, 2, 1, 0.65);
+  } else if (pb2 < 4) {
+    score = _lerp(pb2, 2, 4, 0.65, 0.3);
+  } else {
+    score = _lerp(pb2, 4, 8, 0.3, 0.05);
+  }
+  const label = pb2 < 1.5 ? "near book value" : pb2 < 3 ? "moderate premium" : pb2 < 5 ? "high premium" : "very high premium";
+  return [score, [
+    `P/B ratio: ${pb2.toFixed(2)}\xD7  (${label})`
+  ]];
+}
+function scoreDcfUpside(params) {
+  if (params.dcfUpsidePct === void 0) {
+    return [0.5, ["DCF upside: not provided (neutral score)"]];
+  }
+  const u = params.dcfUpsidePct / 100;
+  let score;
+  if (u < 0) {
+    score = _lerp(u, -0.5, 0, 0, 0.3);
+  } else if (u < 0.3) {
+    score = _lerp(u, 0, 0.3, 0.3, 0.75);
+  } else {
+    score = _lerp(u, 0.3, 0.6, 0.75, 1);
+  }
+  const label = u >= 0.3 ? "significant margin of safety" : u >= 0.1 ? "modest upside" : u >= 0 ? "fairly valued" : "trading above intrinsic value";
+  return [score, [
+    `DCF upside: ${(u * 100).toFixed(1)}%  (${label})`
+  ]];
+}
+function valuationAttractivenessScore(params) {
+  const rf = params.riskFreeRate ?? 0.045;
+  const [eyScore, eyEv] = scoreEarningsYield(params, rf);
+  const [fyScore, fyEv] = scoreFcfYield(params);
+  const [evScore, evEv] = scoreEvEbitda(params);
+  const [pbScore, pbEv] = scorePbRatio(params);
+  const [dcfScore, dcfEv] = scoreDcfUpside(params);
+  const raw = 0.25 * eyScore + 0.25 * fyScore + 0.2 * evScore + 0.15 * pbScore + 0.15 * dcfScore;
+  const score = Math.round(_clamp(raw, 0, 1) * 100);
+  const rating = score >= 65 ? "attractive" : score >= 40 ? "fair" : score >= 20 ? "expensive" : "overvalued";
+  const desc = {
+    attractive: "Multiple signals indicate price is below intrinsic value \u2014 margin of safety present",
+    fair: "Price appears broadly in line with fundamental value",
+    expensive: "Price embeds optimistic assumptions \u2014 limited margin of safety",
+    overvalued: "Price materially exceeds indicated intrinsic value across multiple metrics"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      earningsYield: Math.round(eyScore * 1e4) / 1e4,
+      fcfYield: Math.round(fyScore * 1e4) / 1e4,
+      evEbitda: Math.round(evScore * 1e4) / 1e4,
+      pbRatio: Math.round(pbScore * 1e4) / 1e4,
+      dcfUpside: Math.round(dcfScore * 1e4) / 1e4
+    },
+    riskFreeRate: rf,
+    evidence: [...eyEv, ...fyEv, ...evEv, ...pbEv, ...dcfEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/management-score.ts
+function mean5(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function std4(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean5(xs);
+  return Math.sqrt(xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1));
+}
+function cv4(xs) {
+  const m = mean5(xs);
+  return Math.abs(m) > 1e-9 ? std4(xs) / Math.abs(m) : 1;
+}
+function olsSlope4(ys) {
+  const n = ys.length;
+  if (n < 2) return 0;
+  const xm = (n - 1) / 2;
+  const ym = mean5(ys);
+  const ssXX = Array.from({ length: n }, (_, i) => (i - xm) ** 2).reduce((a, b) => a + b, 0);
+  const ssXY = Array.from({ length: n }, (_, i) => (i - xm) * ((ys[i] ?? 0) - ym)).reduce((a, b) => a + b, 0);
+  return ssXX ? ssXY / ssXX : 0;
+}
+function clamp3(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function lerp(x, x0, x1, y0, y1) {
+  if (x1 === x0) return y0;
+  return y0 + clamp3((x - x0) / (x1 - x0), 0, 1) * (y1 - y0);
+}
+function g5(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function yearRoic3(d) {
+  const ebit = g5(d, "ebit");
+  const ic = g5(d, "totalEquity") + g5(d, "totalDebt") - g5(d, "cash");
+  if (ic <= 0) return null;
+  const ebt = g5(d, "ebt") || ebit - g5(d, "interestExpense");
+  const tax = g5(d, "incomeTaxExpense");
+  const taxRate = ebt > 0 && tax > 0 ? clamp3(tax / ebt, 0, 0.5) : 0.21;
+  return ebit * (1 - taxRate) / ic;
+}
+function estimateHurdleRate(series, provided) {
+  if (provided !== void 0) return provided;
+  const d = series[series.length - 1];
+  const equity = g5(d, "totalEquity");
+  const debt = g5(d, "totalDebt");
+  const cash = g5(d, "cash");
+  const totalCap = equity + debt - cash;
+  if (totalCap <= 0) return 0.1;
+  const costEquity = 0.045 + 0.055;
+  const interest = g5(d, "interestExpense");
+  let costDebt = 0.04;
+  if (debt > 0 && interest > 0) {
+    const preTax = clamp3(interest / debt, 0.02, 0.15);
+    const ebt = g5(d, "ebt") || g5(d, "ebit") - interest;
+    const tax = g5(d, "incomeTaxExpense");
+    const taxRate = ebt > 0 && tax > 0 ? clamp3(tax / ebt, 0, 0.4) : 0.21;
+    costDebt = preTax * (1 - taxRate);
+  }
+  const wE = clamp3(equity / totalCap, 0, 1);
+  return clamp3(wE * costEquity + (1 - wE) * costDebt, 0.06, 0.2);
+}
+function scoreRoicExcellence(series, hurdle) {
+  const roicVals = series.map(yearRoic3).filter((r) => r !== null);
+  if (!roicVals.length) return [0.35, ["ROIC excellence: insufficient data (neutral score)"]];
+  const meanRoic = mean5(roicVals);
+  const slope = olsSlope4(roicVals);
+  const consistency = clamp3(1 - cv4(roicVals) * 0.5, 0, 1);
+  const level = lerp(meanRoic, 0.05, 0.3, 0, 1);
+  const trendAdj = slope > 0.01 ? 0.08 : slope < -0.01 ? -0.08 : 0;
+  const score = clamp3(0.55 * level + 0.35 * consistency + trendAdj, 0, 1);
+  const aboveHurdle = roicVals.filter((r) => r > hurdle).length;
+  const dir = slope > 0.01 ? "improving" : slope < -0.01 ? "declining" : "stable";
+  return [score, [
+    `ROIC excellence: mean ${(meanRoic * 100).toFixed(1)}%  (hurdle ${(hurdle * 100).toFixed(1)}%,  ${aboveHurdle}/${roicVals.length} years above)`,
+    `ROIC trend: ${dir}  (OLS ${(slope * 100).toFixed(2)}%/yr)`
+  ]];
+}
+function scoreMarginStability(series) {
+  const margins = series.filter((d) => g5(d, "revenue") > 0 && g5(d, "ebit") !== 0).map((d) => g5(d, "ebit") / g5(d, "revenue"));
+  if (margins.length < 2) return [0.4, ["Margin stability: insufficient revenue/EBIT data (neutral score)"]];
+  const meanMargin = mean5(margins);
+  const slope = olsSlope4(margins);
+  const consistency = clamp3(1 - cv4(margins) * 1, 0, 1);
+  const level = lerp(meanMargin, 0, 0.3, 0, 1);
+  const trendAdj = slope > 5e-3 ? 0.08 : slope < -5e-3 ? -0.08 : 0;
+  const score = clamp3(0.5 * level + 0.4 * consistency + trendAdj, 0, 1);
+  const dir = slope > 5e-3 ? "expanding" : slope < -5e-3 ? "contracting" : "stable";
+  const quality = meanMargin >= 0.2 ? "high" : meanMargin >= 0.1 ? "moderate" : "thin";
+  return [score, [
+    `Operating margin: mean ${(meanMargin * 100).toFixed(1)}%  (${quality} quality,  CV ${cv4(margins).toFixed(3)})`,
+    `Margin trend: ${dir}  (OLS ${(slope * 100).toFixed(3)}%/yr)`
+  ]];
+}
+function scoreShareholderOrientation(series) {
+  const shares = series.map((d) => g5(d, "sharesOutstanding")).filter((s) => s > 0);
+  if (shares.length < 2) return [0.5, ["Shareholder orientation: share count data unavailable (neutral score)"]];
+  const meanShares = mean5(shares);
+  const slope = olsSlope4(shares);
+  const slopePct = meanShares > 0 ? slope / meanShares : 0;
+  const score = clamp3(0.5 - slopePct * 5, 0, 1);
+  const pctChange = (shares[shares.length - 1] - shares[0]) / shares[0];
+  const dir = slopePct < -0.01 ? "declining (buybacks)" : slopePct > 0.01 ? "growing (dilution)" : "roughly flat";
+  return [score, [
+    `Share count: ${dir}  (${pctChange >= 0 ? "+" : ""}${(pctChange * 100).toFixed(1)}% over period)`,
+    slopePct < -5e-3 ? "Management is reducing share count \u2014 shareholder friendly" : slopePct > 0.02 ? "Material share dilution detected \u2014 value transfer risk" : "Share count broadly stable"
+  ]];
+}
+function scoreRevenueExecution(series) {
+  const growthRates = [];
+  for (let i = 1; i < series.length; i++) {
+    const prevRev = g5(series[i - 1], "revenue");
+    const currRev = g5(series[i], "revenue");
+    if (prevRev > 0) growthRates.push((currRev - prevRev) / prevRev);
+  }
+  if (!growthRates.length) return [0.4, ["Revenue execution: insufficient revenue data (neutral score)"]];
+  const meanGrowth = mean5(growthRates);
+  const level = lerp(meanGrowth, -0.05, 0.2, 0, 1);
+  const consistency = clamp3(1 - cv4(growthRates) * 0.4, 0, 1);
+  const score = clamp3(0.65 * level + 0.35 * consistency, 0, 1);
+  const posYears = growthRates.filter((r) => r > 0).length;
+  const quality = meanGrowth >= 0.1 ? "strong" : meanGrowth >= 0.04 ? "adequate" : meanGrowth >= 0 ? "sluggish" : "declining";
+  return [score, [
+    `Revenue growth: mean ${(meanGrowth * 100).toFixed(1)}%/yr  (${quality},  ${posYears}/${growthRates.length} years positive)`
+  ]];
+}
+function managementQualityScoreFromSeries(annualData, hurdleRate) {
+  if (annualData.length < 3) {
+    throw new Error("managementQualityScoreFromSeries requires at least 3 years of data.");
+  }
+  const hurdle = estimateHurdleRate(annualData, hurdleRate);
+  const [roicScore, roicEv] = scoreRoicExcellence(annualData, hurdle);
+  const [marginScore, marginEv] = scoreMarginStability(annualData);
+  const [soScore, soEv] = scoreShareholderOrientation(annualData);
+  const [revScore, revEv] = scoreRevenueExecution(annualData);
+  const raw = 0.35 * roicScore + 0.25 * marginScore + 0.25 * soScore + 0.15 * revScore;
+  const score = Math.round(clamp3(raw, 0, 1) * 100);
+  const rating = score >= 75 ? "excellent" : score >= 50 ? "good" : score >= 25 ? "fair" : "poor";
+  const desc = {
+    excellent: "Management consistently earns high ROIC, protects margins, and treats shareholders well",
+    good: "Solid operational track record with most quality signals positive",
+    fair: "Mixed signals \u2014 some areas of strength but meaningful shortfalls elsewhere",
+    poor: "Weak returns, margin deterioration, or material shareholder dilution detected"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      roicExcellence: Math.round(roicScore * 1e4) / 1e4,
+      marginStability: Math.round(marginScore * 1e4) / 1e4,
+      shareholderOrientation: Math.round(soScore * 1e4) / 1e4,
+      revenueExecution: Math.round(revScore * 1e4) / 1e4
+    },
+    hurdleRateUsed: hurdle,
+    yearsAnalyzed: annualData.length,
+    evidence: [...roicEv, ...marginEv, ...soEv, ...revEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/dividend-score.ts
+function mean6(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function clamp4(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function g6(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function isDividendPayer(series) {
+  return series.some((d) => {
+    const div = d.dividendsPaid;
+    return typeof div === "number" && isFinite(div) && div > 0;
+  });
+}
+function scoreFcfPayout(series) {
+  const ratios = [];
+  for (const d of series) {
+    const div = g6(d, "dividendsPaid");
+    if (div <= 0) continue;
+    const cfo = g6(d, "operatingCashFlow");
+    const capex = g6(d, "capex");
+    const fcf = cfo - capex;
+    if (fcf !== 0) ratios.push(div / fcf);
+  }
+  if (!ratios.length) return [0.5, ["FCF payout ratio: no dividend/FCF overlap (neutral score)"]];
+  const avg = mean6(ratios);
+  let score;
+  if (avg < 0.4) score = 1;
+  else if (avg < 0.6) score = 0.75;
+  else if (avg < 0.8) score = 0.45;
+  else if (avg <= 1) score = 0.15;
+  else score = 0;
+  const quality = avg < 0.4 ? "very well covered" : avg < 0.6 ? "adequately covered" : avg < 0.8 ? "tight" : avg <= 1 ? "stressed" : "uncovered by FCF";
+  return [score, [
+    `FCF payout ratio: mean ${(avg * 100).toFixed(0)}%  (${quality})`
+  ]];
+}
+function scoreEarningsPayout(series) {
+  const ratios = [];
+  for (const d of series) {
+    const div = g6(d, "dividendsPaid");
+    const ni = g6(d, "netIncome");
+    if (div > 0 && ni > 0) ratios.push(div / ni);
+  }
+  if (!ratios.length) return [0.5, ["Earnings payout ratio: no dividend/earnings overlap (neutral score)"]];
+  const avg = mean6(ratios);
+  let score;
+  if (avg < 0.35) score = 1;
+  else if (avg < 0.55) score = 0.75;
+  else if (avg < 0.75) score = 0.45;
+  else if (avg <= 1) score = 0.2;
+  else score = 0;
+  const quality = avg < 0.35 ? "conservative" : avg < 0.55 ? "moderate" : avg < 0.75 ? "elevated" : avg <= 1 ? "high" : "exceeds earnings";
+  return [score, [
+    `Earnings payout ratio: mean ${(avg * 100).toFixed(0)}%  (${quality})`
+  ]];
+}
+function scoreBalanceSheet(series) {
+  const d = series[series.length - 1];
+  const totalDebt = g6(d, "totalDebt");
+  const cash = g6(d, "cash");
+  const netDebt = totalDebt - cash;
+  const ebit = g6(d, "ebit");
+  const dep = g6(d, "depreciation");
+  const ebitda = ebit + dep;
+  if (ebitda <= 0) {
+    return [0.3, ["Balance sheet strength: EBITDA unavailable or negative (below-neutral score)"]];
+  }
+  const ratio = netDebt / ebitda;
+  let score;
+  if (ratio < 0) score = 1;
+  else if (ratio < 1) score = 0.85;
+  else if (ratio < 2) score = 0.65;
+  else if (ratio < 3) score = 0.4;
+  else if (ratio < 4) score = 0.2;
+  else score = 0.05;
+  const quality = ratio < 0 ? "net cash position" : ratio < 1 ? "very low leverage" : ratio < 2 ? "modest leverage" : ratio < 3 ? "moderate leverage" : ratio < 4 ? "elevated leverage" : "highly levered";
+  return [score, [
+    `Net debt / EBITDA: ${ratio.toFixed(2)}\xD7  (${quality})`
+  ]];
+}
+function scoreDividendGrowthTrack(series) {
+  const divs = series.map((d) => g6(d, "dividendsPaid")).filter((d) => d > 0);
+  if (divs.length < 2) {
+    return [0.15, ["Dividend growth track: insufficient history (below-neutral score)"]];
+  }
+  let consecutive = 0;
+  for (let i = 1; i < divs.length; i++) {
+    if ((divs[i] ?? 0) >= (divs[i - 1] ?? 0)) {
+      consecutive++;
+    } else {
+      consecutive = 0;
+    }
+  }
+  let score;
+  if (consecutive >= 10) score = 1;
+  else if (consecutive >= 7) score = 0.75;
+  else if (consecutive >= 4) score = 0.55;
+  else if (consecutive >= 2) score = 0.35;
+  else score = 0.15;
+  const label = consecutive >= 10 ? "dividend aristocrat-level streak" : consecutive >= 7 ? "strong track record" : consecutive >= 4 ? "solid track record" : consecutive >= 2 ? "limited track record" : "recent cut or minimal history";
+  return [score, [
+    `Dividend growth track: ${consecutive} consecutive non-declining year(s)  (${label})`
+  ]];
+}
+function dividendSafetyScoreFromSeries(annualData) {
+  const payer = isDividendPayer(annualData);
+  if (!payer) {
+    return {
+      score: 50,
+      rating: "non-payer",
+      isDividendPayer: false,
+      yearsAnalyzed: annualData.length,
+      components: {
+        fcfPayoutRatio: 0.5,
+        earningsPayoutRatio: 0.5,
+        balanceSheetStrength: 0.5,
+        dividendGrowthTrack: 0.5
+      },
+      evidence: ["No dividends detected across the provided data series"],
+      interpretation: "Score 50/100: Company does not pay a dividend \u2014 score is not meaningful"
+    };
+  }
+  const [fcfScore, fcfEv] = scoreFcfPayout(annualData);
+  const [epScore, epEv] = scoreEarningsPayout(annualData);
+  const [bsScore, bsEv] = scoreBalanceSheet(annualData);
+  const [dgtScore, dgtEv] = scoreDividendGrowthTrack(annualData);
+  const raw = 0.35 * fcfScore + 0.25 * epScore + 0.25 * bsScore + 0.15 * dgtScore;
+  const score = Math.round(clamp4(raw, 0, 1) * 100);
+  const rating = score >= 70 ? "safe" : score >= 45 ? "adequate" : score >= 20 ? "risky" : "danger";
+  const desc = {
+    safe: "Dividend well-covered by cash flows with a strong balance sheet",
+    adequate: "Dividend appears sustainable but headroom is limited in some areas",
+    risky: "Coverage is strained \u2014 dividend could be at risk in a downturn",
+    danger: "Dividend likely unsustainable; cut probability is high"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      fcfPayoutRatio: Math.round(fcfScore * 1e4) / 1e4,
+      earningsPayoutRatio: Math.round(epScore * 1e4) / 1e4,
+      balanceSheetStrength: Math.round(bsScore * 1e4) / 1e4,
+      dividendGrowthTrack: Math.round(dgtScore * 1e4) / 1e4
+    },
+    isDividendPayer: true,
+    yearsAnalyzed: annualData.length,
+    evidence: [...fcfEv, ...epEv, ...bsEv, ...dgtEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/investment-score.ts
+function clamp5(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function gradeFromScore(score) {
+  if (score >= 90) return "A+";
+  if (score >= 80) return "A";
+  if (score >= 70) return "B+";
+  if (score >= 60) return "B";
+  if (score >= 45) return "C";
+  if (score >= 25) return "D";
+  return "F";
+}
+function convictionFromScore(score) {
+  if (score >= 80) return "strongBuy";
+  if (score >= 65) return "buy";
+  if (score >= 45) return "hold";
+  if (score >= 30) return "sell";
+  return "strongSell";
+}
+function computeWeightedScore(inputs) {
+  const hasValuation = inputs.valuationScore !== void 0;
+  if (hasValuation) {
+    return 0.25 * inputs.moatScore + 0.2 * inputs.capitalAllocationScore + 0.2 * inputs.earningsQualityScore + 0.15 * inputs.managementScore + 0.2 * inputs.valuationScore;
+  }
+  return 0.3125 * inputs.moatScore + 0.25 * inputs.capitalAllocationScore + 0.25 * inputs.earningsQualityScore + 0.1875 * inputs.managementScore;
+}
+function investmentScoreFromScores(inputs) {
+  const rawScore = computeWeightedScore(inputs);
+  const score = Math.round(clamp5(rawScore, 0, 100));
+  const grade = gradeFromScore(score);
+  const conviction = convictionFromScore(score);
+  const hasVal = inputs.valuationScore !== void 0;
+  const evidence = [
+    `Economic Moat:         ${inputs.moatScore}/100  (weight ${hasVal ? "25" : "31"}%)`,
+    `Capital Allocation:    ${inputs.capitalAllocationScore}/100  (weight ${hasVal ? "20" : "25"}%)`,
+    `Earnings Quality:      ${inputs.earningsQualityScore}/100  (weight ${hasVal ? "20" : "25"}%)`,
+    `Management Quality:    ${inputs.managementScore}/100  (weight ${hasVal ? "15" : "19"}%)`
+  ];
+  if (hasVal) {
+    evidence.push(`Valuation:             ${inputs.valuationScore}/100  (weight 20%)`);
+  } else {
+    evidence.push("Valuation:             not provided (weight redistributed)");
+  }
+  const convictionLabel = {
+    strongBuy: "Strong Buy \u2014 exceptional quality at an attractive price",
+    buy: "Buy \u2014 above-average quality with reasonable valuation",
+    hold: "Hold \u2014 average quality or price adequately reflects value",
+    sell: "Sell \u2014 below-average quality or price significantly exceeds value",
+    strongSell: "Strong Sell \u2014 poor quality and/or materially overpriced"
+  };
+  return {
+    score,
+    grade,
+    conviction,
+    components: {
+      moat: inputs.moatScore,
+      capitalAllocation: inputs.capitalAllocationScore,
+      earningsQuality: inputs.earningsQualityScore,
+      management: inputs.managementScore,
+      valuation: inputs.valuationScore ?? null
+    },
+    evidence,
+    interpretation: `Grade ${grade}  |  Score ${score}/100  |  ${convictionLabel[conviction]}`
+  };
+}
+function investmentScoreFromSeries(annualData, valuationParams, wacc) {
+  if (annualData.length < 3) {
+    throw new Error("investmentScoreFromSeries requires at least 3 years of data.");
+  }
+  const waccOpt = wacc !== void 0 ? { wacc } : {};
+  const moatResult = moatScore(annualData, waccOpt);
+  const caResult = capitalAllocationScore(annualData, waccOpt);
+  const eqResult = earningsQualityScore(annualData);
+  const mgmtResult = managementQualityScoreFromSeries(annualData, wacc);
+  const inputs = {
+    moatScore: moatResult.score,
+    capitalAllocationScore: caResult.score,
+    earningsQualityScore: eqResult.score,
+    managementScore: mgmtResult.score
+  };
+  if (valuationParams !== void 0) {
+    const valResult = valuationAttractivenessScore(valuationParams);
+    inputs.valuationScore = valResult.score;
+  }
+  return investmentScoreFromScores(inputs);
+}
+
 exports.affo = affo;
 exports.altmanZScore = altmanZScore;
 exports.annualizeReturn = annualizeReturn;
@@ -2097,6 +2643,7 @@ exports.debtToEquity = debtToEquity;
 exports.defensiveIntervalRatio = defensiveIntervalRatio;
 exports.dio = dio;
 exports.dividendGrowthRate = dividendGrowthRate;
+exports.dividendSafetyScoreFromSeries = dividendSafetyScoreFromSeries;
 exports.downsideCaptureRatio = downsideCaptureRatio;
 exports.dpo = dpo;
 exports.dso = dso;
@@ -2137,6 +2684,8 @@ exports.interestCoverageRatio = interestCoverageRatio;
 exports.invalidateCache = invalidate;
 exports.inventoryTurnover = inventoryTurnover;
 exports.investedCapital = investedCapital;
+exports.investmentScoreFromScores = investmentScoreFromScores;
+exports.investmentScoreFromSeries = investmentScoreFromSeries;
 exports.jensensAlpha = jensensAlpha;
 exports.leveredFcf = leveredFcf;
 exports.loanToDepositRatio = loanToDepositRatio;
@@ -2144,6 +2693,7 @@ exports.lossRatio = lossRatio;
 exports.ltvCacRatio = ltvCacRatio;
 exports.magicFormula = magicFormula;
 exports.magicNumber = magicNumber;
+exports.managementQualityScoreFromSeries = managementQualityScoreFromSeries;
 exports.maxDrawdown = maxDrawdown;
 exports.maximumDrawdown = maximumDrawdown;
 exports.mean = mean;
@@ -2211,6 +2761,5 @@ exports.ulcerIndex = ulcerIndex;
 exports.underwritingProfitMargin = underwritingProfitMargin;
 exports.unleveredFcf = unleveredFcf;
 exports.upsideCaptureRatio = upsideCaptureRatio;
+exports.valuationAttractivenessScore = valuationAttractivenessScore;
 exports.workingCapitalTurnover = workingCapitalTurnover;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map