fin-ratios 0.3.0 → 0.4.0

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 = (g3) => {
+  const computeEV = (g4) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g3,
+      growthRate: g4,
       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 mean3 = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean3, 2), 0) / (values.length - ddof);
+  const mean4 = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean4, 2), 0) / (values.length - ddof);
   return Math.sqrt(variance);
 }
 function mean(values) {
@@ -1557,6 +1557,174 @@ function moatScore(annualData, options = {}) {
   };
 }
 
+// src/utils/capital-allocation.ts
+function mean3(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function std2(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean3(xs);
+  return Math.sqrt(xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1));
+}
+function cv2(xs) {
+  const m = mean3(xs);
+  return Math.abs(m) > 1e-9 ? std2(xs) / Math.abs(m) : 1;
+}
+function olsSlope2(ys) {
+  const n = ys.length;
+  if (n < 2) return 0;
+  const xm = (n - 1) / 2;
+  const ym = mean3(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 clamp(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function g3(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function estimateWacc2(series, provided) {
+  if (provided !== void 0) return provided;
+  const d = series[series.length - 1];
+  const equity = g3(d, "totalEquity");
+  const debt = g3(d, "totalDebt");
+  const cash = g3(d, "cash");
+  const totalCap = equity + debt - cash;
+  if (totalCap <= 0) return 0.1;
+  const costEquity = 0.045 + 0.055;
+  const interest = g3(d, "interestExpense");
+  let costDebt = 0.04;
+  if (debt > 0 && interest > 0) {
+    const preTax = clamp(interest / debt, 0.02, 0.15);
+    const ebt = g3(d, "ebt") || g3(d, "ebit") - interest;
+    const tax = g3(d, "incomeTaxExpense");
+    const taxRate = ebt > 0 && tax > 0 ? clamp(tax / ebt, 0, 0.4) : 0.21;
+    costDebt = preTax * (1 - taxRate);
+  }
+  const wE = clamp(equity / totalCap, 0, 1);
+  return clamp(wE * costEquity + (1 - wE) * costDebt, 0.06, 0.2);
+}
+function yearRoic2(d) {
+  const ebit = g3(d, "ebit");
+  const ic = g3(d, "totalEquity") + g3(d, "totalDebt") - g3(d, "cash");
+  if (ic <= 0) return null;
+  const ebt = g3(d, "ebt") || ebit - g3(d, "interestExpense");
+  const tax = g3(d, "incomeTaxExpense");
+  const taxRate = ebt > 0 && tax > 0 ? clamp(tax / ebt, 0, 0.5) : 0.21;
+  return ebit * (1 - taxRate) / ic;
+}
+function scoreValueCreation(series, wacc) {
+  const roicVals = series.map(yearRoic2).filter((r) => r !== null);
+  if (!roicVals.length) return [0.3, ["Value creation: insufficient ROIC data (neutral score)"]];
+  const spreads = roicVals.map((r) => r - wacc);
+  const ms = mean3(spreads);
+  const slope = olsSlope2(spreads);
+  const level = clamp((ms + 0.05) / 0.25, 0, 1);
+  const trendAdj = slope > 0.01 ? 0.1 : slope < -0.01 ? -0.1 : 0;
+  const consistency = Math.max(0, 1 - cv2(spreads) * 0.5);
+  const score = clamp(0.6 * level + 0.4 * consistency + trendAdj, 0, 1);
+  const pos = spreads.filter((s) => s > 0).length;
+  const dir = slope > 0.01 ? "improving" : slope < -0.01 ? "declining" : "stable";
+  return [score, [
+    `Value creation: mean ROIC-WACC spread ${(ms * 100).toFixed(1)}%  (${pos}/${spreads.length} years positive)`,
+    `Spread trend: ${dir}  (OLS ${(slope * 100).toFixed(2)}%/yr)`
+  ]];
+}
+function scoreFcfQuality(series) {
+  const conversions = [];
+  for (const d of series) {
+    const ebit = g3(d, "ebit");
+    if (ebit <= 0) continue;
+    const ebt = g3(d, "ebt") || ebit - g3(d, "interestExpense");
+    const tax = g3(d, "incomeTaxExpense");
+    const taxRate = ebt > 0 && tax > 0 ? clamp(tax / ebt, 0, 0.5) : 0.21;
+    const nopat2 = ebit * (1 - taxRate);
+    if (nopat2 <= 0) continue;
+    const fcf = nopat2 + g3(d, "depreciation") - g3(d, "capex");
+    conversions.push(fcf / nopat2);
+  }
+  if (!conversions.length) return [0.4, ["FCF quality: insufficient data (neutral score)"]];
+  const mc = mean3(conversions);
+  const level = clamp(mc / 1.2, 0, 1);
+  const stability = Math.max(0, 1 - cv2(conversions) * 1.5);
+  const score = clamp(0.65 * level + 0.35 * stability, 0, 1);
+  const quality = mc >= 1 ? "capital-light" : mc < 0.5 ? "capital-heavy" : "moderate";
+  return [score, [`FCF quality: mean NOPAT-to-FCF conversion ${(mc * 100).toFixed(0)}%  (${quality})`]];
+}
+function scoreReinvestmentYield(series) {
+  const yields = [];
+  for (let i = 1; i < series.length; i++) {
+    const prev = series[i - 1];
+    const curr = series[i];
+    const da = g3(curr, "totalAssets") - g3(prev, "totalAssets");
+    const dr = g3(curr, "revenue") - g3(prev, "revenue");
+    if (da > 1e6) yields.push(dr / da);
+  }
+  if (!yields.length) return [0.4, ["Reinvestment yield: insufficient data (neutral score)"]];
+  const my = mean3(yields);
+  const level = clamp((my + 0.2) / 1.7, 0, 1);
+  const consistency = Math.max(0, 1 - cv2(yields) * 0.5);
+  const score = clamp(0.65 * level + 0.35 * consistency, 0, 1);
+  const pos = yields.filter((y) => y > 0).length;
+  return [score, [
+    `Reinvestment yield: mean incremental revenue/asset ${my.toFixed(2)}x  (${pos}/${yields.length} periods productive)`
+  ]];
+}
+function scorePayoutDiscipline(series, wacc) {
+  const coverages = [];
+  for (const d of series) {
+    const ebit = g3(d, "ebit");
+    if (ebit <= 0) continue;
+    const ebt = g3(d, "ebt") || ebit - g3(d, "interestExpense");
+    const tax = g3(d, "incomeTaxExpense");
+    const taxRate = ebt > 0 && tax > 0 ? clamp(tax / ebt, 0, 0.5) : 0.21;
+    const nopat2 = ebit * (1 - taxRate);
+    const fcf = nopat2 + g3(d, "depreciation") - g3(d, "capex");
+    const div = g3(d, "dividendsPaid");
+    if (div > 0) coverages.push(fcf > 0 ? fcf / div : 0);
+  }
+  if (coverages.length) {
+    const mc = mean3(coverages);
+    const score = clamp((mc - 0.5) / 2, 0, 1);
+    const health = mc >= 2 ? "healthy" : mc >= 1 ? "tight" : "stressed";
+    return [score, [`Payout discipline: mean FCF/dividend coverage ${mc.toFixed(1)}x  (${health})`]];
+  }
+  const roicVals = series.map(yearRoic2).filter((r) => r !== null);
+  const mr = mean3(roicVals);
+  if (mr > wacc * 1.2) return [0.7, ["Payout discipline: retaining FCF in above-WACC business (good reinvestment)"]];
+  if (mr <= wacc) return [0.35, ["Payout discipline: retaining FCF despite below-WACC returns (concerning)"]];
+  return [0.5, ["Payout discipline: no dividend data available (neutral score)"]];
+}
+function capitalAllocationScore(annualData, options = {}) {
+  if (annualData.length < 2) {
+    throw new Error("capitalAllocationScore requires at least 2 years of data.");
+  }
+  const wacc = estimateWacc2(annualData, options.wacc);
+  const [vcScore, vcEv] = scoreValueCreation(annualData, wacc);
+  const [fcfScore, fcfEv] = scoreFcfQuality(annualData);
+  const [riScore, riEv] = scoreReinvestmentYield(annualData);
+  const [pdScore, pdEv] = scorePayoutDiscipline(annualData, wacc);
+  const raw = 0.35 * vcScore + 0.25 * fcfScore + 0.25 * riScore + 0.15 * pdScore;
+  const score = Math.round(clamp(raw, 0, 1) * 100);
+  const rating = score >= 75 ? "excellent" : score >= 50 ? "good" : score >= 25 ? "fair" : "poor";
+  return {
+    score,
+    rating,
+    components: {
+      valueCreation: Math.round(vcScore * 1e4) / 1e4,
+      fcfQuality: Math.round(fcfScore * 1e4) / 1e4,
+      reinvestmentYield: Math.round(riScore * 1e4) / 1e4,
+      payoutDiscipline: Math.round(pdScore * 1e4) / 1e4
+    },
+    waccUsed: wacc,
+    yearsAnalyzed: annualData.length,
+    evidence: [...vcEv, ...fcfEv, ...riEv, ...pdEv]
+  };
+}
+
 exports.affo = affo;
 exports.altmanZScore = altmanZScore;
 exports.annualizeReturn = annualizeReturn;
@@ -1574,6 +1742,7 @@ exports.calmarRatio = calmarRatio;
 exports.capRate = capRate;
 exports.capexToDepreciation = capexToDepreciation;
 exports.capexToRevenue = capexToRevenue;
+exports.capitalAllocationScore = capitalAllocationScore;
 exports.capitalTurnover = capitalTurnover;
 exports.cashConversionCycle = cashConversionCycle;
 exports.cashRatio = cashRatio;