fin-ratios 0.2.0 → 0.3.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 = (g3) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g2,
+      growthRate: g3,
       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 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);
   return Math.sqrt(variance);
 }
 function mean(values) {
@@ -1331,6 +1331,232 @@ 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]}`
+  };
+}
+
 exports.affo = affo;
 exports.altmanZScore = altmanZScore;
 exports.annualizeReturn = annualizeReturn;
@@ -1416,6 +1642,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;