fin-ratios 0.2.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 = (g2) => {
+  const computeEV = (g4) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g2,
+      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 mean2 = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean2, 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) {
@@ -1331,6 +1331,400 @@ function _evict() {
   }
 }
 
+// src/utils/moat-score.ts
+function mean2(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function std(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean2(xs);
+  return Math.sqrt(xs.reduce((s, x) => s + (x - m) ** 2, 0) / (xs.length - 1));
+}
+function cv(xs) {
+  const m = mean2(xs);
+  return Math.abs(m) > 1e-9 ? std(xs) / Math.abs(m) : 1;
+}
+function olsSlope(ys) {
+  const n = ys.length;
+  if (n < 2) return 0;
+  const xm = (n - 1) / 2;
+  const ym = mean2(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 g2(d, key) {
+  const v = d[key];
+  return typeof v === "number" && !isNaN(v) ? v : 0;
+}
+function yearRoic(d) {
+  const ebit = g2(d, "ebit");
+  const equity = g2(d, "totalEquity");
+  const debt = g2(d, "totalDebt");
+  const cash = g2(d, "cash");
+  const ic = equity + debt - cash;
+  if (ic <= 0 || ebit <= 0) return null;
+  const ebt = g2(d, "ebt") || ebit - g2(d, "interestExpense");
+  const tax = g2(d, "incomeTaxExpense");
+  const taxRate = ebt > 0 && tax > 0 ? Math.min(Math.max(tax / ebt, 0), 0.5) : 0.21;
+  return ebit * (1 - taxRate) / ic;
+}
+function estimateWacc(series, override) {
+  if (override !== void 0) return override;
+  const d = series[series.length - 1];
+  const equity = g2(d, "totalEquity");
+  const debt = g2(d, "totalDebt");
+  const totalCap = equity + debt;
+  if (totalCap <= 0) return 0.09;
+  const we = equity / totalCap;
+  const wd = debt / totalCap;
+  const costEquity = 0.045 + 1 * 0.055;
+  const interest = g2(d, "interestExpense");
+  const preCostDebt = debt > 0 && interest > 0 ? Math.min(interest / debt, 0.15) : 0.05;
+  const ebt = g2(d, "ebt") || g2(d, "ebit") - interest;
+  const tax = g2(d, "incomeTaxExpense");
+  const taxRate = ebt > 0 && tax > 0 ? Math.min(Math.max(tax / ebt, 0), 0.4) : 0.21;
+  const costDebt = preCostDebt * (1 - taxRate);
+  return Math.max(Math.min(we * costEquity + wd * costDebt, 0.2), 0.06);
+}
+function scoreRoicPersistence(roicSeries, wacc) {
+  if (!roicSeries.length) return [0, ["Insufficient ROIC data"]];
+  const above = roicSeries.filter((r) => r > wacc).length;
+  const pctAbove = above / roicSeries.length;
+  const roicCv = cv(roicSeries);
+  const meanRoic = mean2(roicSeries);
+  const spread = meanRoic - wacc;
+  const stability = Math.max(0, 1 - roicCv * 0.4);
+  const score = Math.min(Math.max(pctAbove * stability, 0), 1);
+  return [score, [
+    `ROIC exceeded WACC in ${above}/${roicSeries.length} years (${(pctAbove * 100).toFixed(0)}%)`,
+    `Mean ROIC ${(meanRoic * 100).toFixed(1)}%  vs  WACC ${(wacc * 100).toFixed(1)}%  (spread ${spread >= 0 ? "+" : ""}${(spread * 100).toFixed(1)}%)`,
+    `ROIC volatility (CV): ${roicCv.toFixed(2)} \u2014 ${roicCv < 0.15 ? "highly stable" : roicCv < 0.3 ? "stable" : "volatile"}`
+  ]];
+}
+function scorePricingPower(gmSeries) {
+  if (!gmSeries.length) return [0.5, ["Gross margin unavailable \u2014 pricing power assumed neutral"]];
+  const meanGm = mean2(gmSeries);
+  const gmCv = cv(gmSeries);
+  const slope = olsSlope(gmSeries);
+  const level = Math.min(Math.max((meanGm - 0.2) / 0.4, 0), 1);
+  const stability = Math.max(0, 1 - gmCv * 2.5);
+  const trendAdj = Math.max(Math.min(slope * 10, 0.1), -0.1);
+  const score = Math.min(Math.max(0.6 * level + 0.4 * stability + trendAdj, 0), 1);
+  const trendLbl = slope > 5e-3 ? "improving" : slope < -5e-3 ? "declining" : "stable";
+  return [score, [
+    `Mean gross margin ${(meanGm * 100).toFixed(1)}% over ${gmSeries.length} years`,
+    `Gross margin CV ${gmCv.toFixed(3)} \u2014 ${gmCv < 0.05 ? "excellent stability" : gmCv < 0.15 ? "moderate" : "high variability"}`,
+    `Gross margin trend: ${trendLbl}`
+  ]];
+}
+function scoreReinvestmentQuality(series) {
+  if (series.length < 2) return [0.5, ["Insufficient data for reinvestment quality \u2014 assumed neutral"]];
+  const roiicVals = [];
+  let negativeCount = 0;
+  for (let i = 1; i < series.length; i++) {
+    const prev = series[i - 1];
+    const curr = series[i];
+    const deltaEbit = g2(curr, "ebit") - g2(prev, "ebit");
+    const netReinvest = g2(curr, "capex") - g2(curr, "depreciation") + (g2(curr, "currentAssets") - g2(curr, "currentLiabilities")) - (g2(prev, "currentAssets") - g2(prev, "currentLiabilities"));
+    if (netReinvest > 1e6) {
+      roiicVals.push(Math.max(Math.min(deltaEbit / netReinvest, 5), -1));
+    } else {
+      negativeCount++;
+    }
+  }
+  const totalPeriods = series.length - 1;
+  const capitalLight = !roiicVals.length || negativeCount / totalPeriods > 0.5;
+  if (capitalLight) {
+    const ebitGrowth = [];
+    for (let i = 1; i < series.length; i++) {
+      const prevEbit = g2(series[i - 1], "ebit");
+      if (prevEbit > 0) ebitGrowth.push(g2(series[i], "ebit") / prevEbit - 1);
+    }
+    if (ebitGrowth.length && mean2(ebitGrowth) > 0.05) {
+      return [0.82, [
+        "Capital-light model: EBIT growing with minimal net reinvestment",
+        "Low reinvestment requirement is a strong moat signal"
+      ]];
+    }
+    return [0.5, ["Reinvestment quality indeterminate (limited reinvestment data)"]];
+  }
+  const meanRoiic = mean2(roiicVals);
+  const score = Math.min(Math.max(0.3 + meanRoiic * 0.7, 0), 1);
+  return [score, [
+    `Mean incremental ROIC (ROIIC): ${(meanRoiic * 100).toFixed(1)}%`,
+    `Based on ${roiicVals.length} reinvestment period(s)`,
+    meanRoiic > 0.5 ? "Excellent capital reinvestment efficiency" : meanRoiic > 0.15 ? "Adequate reinvestment returns" : "Low incremental returns on reinvestment"
+  ]];
+}
+function scoreOperatingLeverage(series) {
+  if (series.length < 2) return [0.5, ["Insufficient data for operating leverage"]];
+  const dolVals = [];
+  for (let i = 1; i < series.length; i++) {
+    const prev = series[i - 1];
+    const curr = series[i];
+    if (g2(prev, "revenue") <= 0 || Math.abs(g2(prev, "ebit")) < 1e5) continue;
+    const pctRev = (g2(curr, "revenue") - g2(prev, "revenue")) / g2(prev, "revenue");
+    const pctEbit = (g2(curr, "ebit") - g2(prev, "ebit")) / Math.abs(g2(prev, "ebit"));
+    if (Math.abs(pctRev) > 5e-3) {
+      const dol = pctEbit / pctRev;
+      if (dol > 0 && dol < 25) dolVals.push(dol);
+    }
+  }
+  if (!dolVals.length) return [0.4, ["Operating leverage indeterminate (insufficient revenue variance)"]];
+  const meanDol = mean2(dolVals);
+  const cvDol = cv(dolVals);
+  const level = Math.min(Math.max((meanDol - 1) / 5, 0), 1);
+  const consistency = Math.max(0, 1 - cvDol * 0.5);
+  const score = Math.min(Math.max(0.65 * level + 0.35 * consistency, 0), 1);
+  const quality = meanDol > 3 ? "High fixed-cost structure \u2014 strong scale advantages" : meanDol > 1.5 ? "Moderate operating leverage" : "Variable cost structure \u2014 limited scale advantage";
+  return [score, [
+    `Mean degree of operating leverage (DOL): ${meanDol.toFixed(2)}\xD7`,
+    `DOL consistency: ${(consistency * 100).toFixed(0)}%`,
+    quality
+  ]];
+}
+function scoreCap(roicSeries, wacc) {
+  if (!roicSeries.length) return [0.3, 5, ["Insufficient data for CAP estimate"]];
+  const meanRoic = mean2(roicSeries);
+  const spread = meanRoic - wacc;
+  if (spread <= 0) {
+    return [0, 0, [`ROIC ${(meanRoic * 100).toFixed(1)}% \u2264 WACC ${(wacc * 100).toFixed(1)}%: no competitive advantage detected`]];
+  }
+  const slope = olsSlope(roicSeries);
+  let capYears;
+  let direction;
+  if (slope < -5e-3) {
+    capYears = Math.min(Math.max(spread / Math.abs(slope), 0), 30);
+    direction = "declining";
+  } else if (slope > 5e-3) {
+    capYears = Math.min(spread * 80 + 5, 30);
+    direction = "improving";
+  } else {
+    const roicCv = cv(roicSeries);
+    capYears = Math.min(Math.max(spread * 60 / Math.max(roicCv, 0.1), 3), 25);
+    direction = "stable";
+  }
+  const capScore = Math.min(capYears / 20, 1);
+  return [capScore, capYears, [
+    `Estimated competitive advantage period: ${capYears.toFixed(1)} years`,
+    `ROIC trend: ${direction} (slope ${slope >= 0 ? "+" : ""}${slope.toFixed(3)}/yr)`,
+    `ROIC spread above WACC: ${spread >= 0 ? "+" : ""}${(spread * 100).toFixed(1)}%`
+  ]];
+}
+var W = {
+  roicPersistence: 0.3,
+  pricingPower: 0.25,
+  reinvestmentQuality: 0.2,
+  operatingLeverage: 0.15,
+  cap: 0.1
+};
+function moatScore(annualData, options = {}) {
+  if (annualData.length < 2) {
+    throw new Error("moatScore requires at least 2 years of data (3\u201310 recommended).");
+  }
+  const estWacc = estimateWacc(annualData, options.wacc);
+  const roicSeries = annualData.map(yearRoic).filter((r) => r !== null);
+  const gmSeries = annualData.filter((d) => g2(d, "revenue") > 0).map((d) => safeDivide(g2(d, "grossProfit"), g2(d, "revenue")) ?? 0);
+  const [sRp, evRp] = scoreRoicPersistence(roicSeries, estWacc);
+  const [sPp, evPp] = scorePricingPower(gmSeries);
+  const [sRq, evRq] = scoreReinvestmentQuality(annualData);
+  const [sOl, evOl] = scoreOperatingLeverage(annualData);
+  const [sCp, capYears, evCp] = scoreCap(roicSeries, estWacc);
+  const raw = W.roicPersistence * sRp + W.pricingPower * sPp + W.reinvestmentQuality * sRq + W.operatingLeverage * sOl + W.cap * sCp;
+  const score = Math.round(Math.min(Math.max(raw * 100, 0), 100));
+  const width = score >= 70 ? "wide" : score >= 40 ? "narrow" : "none";
+  const desc = {
+    wide: "Durable competitive advantage likely to persist for 10+ years",
+    narrow: "Real but limited or potentially fading competitive advantage",
+    none: "No detectable financial signature of a durable economic moat"
+  };
+  return {
+    score,
+    width,
+    components: {
+      roicPersistence: parseFloat(sRp.toFixed(4)),
+      pricingPower: parseFloat(sPp.toFixed(4)),
+      reinvestmentQuality: parseFloat(sRq.toFixed(4)),
+      operatingLeverage: parseFloat(sOl.toFixed(4)),
+      capScore: parseFloat(sCp.toFixed(4))
+    },
+    capEstimateYears: parseFloat(capYears.toFixed(1)),
+    waccUsed: parseFloat(estWacc.toFixed(4)),
+    yearsAnalyzed: annualData.length,
+    evidence: [...evRp, ...evPp, ...evRq, ...evOl, ...evCp],
+    interpretation: `Score ${score}/100: ${desc[width]}`
+  };
+}
+
+// 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;
@@ -1348,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;
@@ -1416,6 +1811,7 @@ exports.magicNumber = magicNumber;
 exports.maxDrawdown = maxDrawdown;
 exports.maximumDrawdown = maximumDrawdown;
 exports.mean = mean;
+exports.moatScore = moatScore;
 exports.montierCScore = montierCScore;
 exports.netDebtToEbitda = netDebtToEbitda;
 exports.netDebtToEquity = netDebtToEquity;