fin-ratios 0.7.3 → 1.0.2

package/dist/index.d.cts

@@ -1333,4 +1333,292 @@ interface PortfolioOptions {
  */
 declare function portfolioQuality(holdings: HoldingInput[], options?: PortfolioOptions): PortfolioQualityResult;
 
-export { AnnualQualityData, type CacheOptions, type DuPont3Factor, type FairValueOptions, type FairValueRange, type HoldingInput, type HoldingResult, type PortfolioOptions, type PortfolioQualityResult, QualityFactorResult, type RatioFn, affo, annualizeReturn, arrPerFte, assetTurnover, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicNumber, maxDrawdown, maximumDrawdown, mean, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, workingCapitalTurnover };
+/**
+ * Valuation Attractiveness Score.
+ *
+ * Provides a point-in-time assessment of how attractively a security is priced
+ * relative to its earnings power, free cash flow generation, asset value, and
+ * intrinsic value estimate. Higher scores indicate greater margin of safety.
+ *
+ * Signals
+ * -------
+ * 1. Earnings Yield Spread  (25%) — excess earnings yield over risk-free rate
+ * 2. FCF Yield              (25%) — free cash flow yield on market price
+ * 3. EV/EBITDA              (20%) — enterprise multiple vs historical norms
+ * 4. P/B Ratio              (15%) — price-to-book premium or discount
+ * 5. DCF Upside             (15%) — percentage gap to intrinsic value estimate
+ *
+ * Score:  0–100
+ * Rating: 'attractive' (≥65), 'fair' (40–64), 'expensive' (20–39), 'overvalued' (<20)
+ */
+interface ValuationComponents {
+    earningsYield: number;
+    fcfYield: number;
+    evEbitda: number;
+    pbRatio: number;
+    dcfUpside: number;
+}
+interface ValuationScore {
+    score: number;
+    rating: 'attractive' | 'fair' | 'expensive' | 'overvalued';
+    components: ValuationComponents;
+    riskFreeRate: number;
+    evidence: string[];
+    interpretation: string;
+}
+interface ValuationParams {
+    peRatio?: number;
+    evEbitda?: number;
+    pFcf?: number;
+    pbRatio?: number;
+    fcfYieldPct?: number;
+    earningsYieldPct?: number;
+    dcfUpsidePct?: number;
+    riskFreeRate?: number;
+}
+/**
+ * Compute a point-in-time Valuation Attractiveness Score.
+ *
+ * @param params - Valuation multiples and optional risk-free rate override.
+ *                 At least one input is required; missing signals default to 0.5.
+ * @returns ValuationScore with score (0–100), rating, components, and evidence.
+ *
+ * @example
+ *   const result = valuationAttractivenessScore({
+ *     peRatio: 18,
+ *     evEbitda: 11,
+ *     pFcf: 22,
+ *     pbRatio: 3.2,
+ *     dcfUpsidePct: 25,
+ *   })
+ *   console.log(result.score)   // e.g. 62
+ *   console.log(result.rating)  // 'fair'
+ */
+declare function valuationAttractivenessScore(params: ValuationParams): ValuationScore;
+
+/**
+ * Management Quality Score.
+ *
+ * Evaluates management's operational effectiveness using multi-year financial
+ * series. A high-scoring management team consistently earns strong returns on
+ * invested capital, expands or defends operating margins, treats shareholders
+ * with respect by avoiding dilution, and delivers reliable revenue growth.
+ *
+ * Signals
+ * -------
+ * 1. ROIC Excellence        (35%) — level, trend, and consistency of ROIC
+ * 2. Margin Stability       (25%) — operating margin level, trend, and stability
+ * 3. Shareholder Orientation(25%) — share count trajectory (buybacks vs dilution)
+ * 4. Revenue Execution      (15%) — revenue growth rate level and consistency
+ *
+ * Score:  0–100
+ * Rating: 'excellent' (≥75), 'good' (50–74), 'fair' (25–49), 'poor' (<25)
+ *
+ * Minimum 3 years of data required.
+ */
+/** One year of financial data for management quality analysis. */
+interface AnnualManagementData {
+    revenue?: number;
+    ebit?: number;
+    totalAssets?: number;
+    totalEquity?: number;
+    totalDebt?: number;
+    cash?: number;
+    sharesOutstanding?: number;
+    incomeTaxExpense?: number;
+    ebt?: number;
+    interestExpense?: number;
+    year?: number | string;
+}
+interface ManagementComponents {
+    roicExcellence: number;
+    marginStability: number;
+    shareholderOrientation: number;
+    revenueExecution: number;
+}
+interface ManagementScore {
+    score: number;
+    rating: 'excellent' | 'good' | 'fair' | 'poor';
+    components: ManagementComponents;
+    hurdleRateUsed: number;
+    yearsAnalyzed: number;
+    evidence: string[];
+    interpretation: string;
+}
+/**
+ * Compute Management Quality Score from a sequence of annual financial records.
+ *
+ * @param annualData  Array in chronological order (oldest first). Minimum 3 years.
+ * @param hurdleRate  Optional WACC override (e.g. 0.09 for 9%).
+ * @returns ManagementScore with score (0–100), rating, components, evidence.
+ *
+ * @example
+ *   const result = managementQualityScoreFromSeries([
+ *     { year: 2020, revenue: 100e9, ebit: 22e9, totalEquity: 40e9, totalDebt: 10e9,
+ *       cash: 5e9, sharesOutstanding: 5e9 },
+ *     { year: 2021, revenue: 115e9, ebit: 26e9, totalEquity: 44e9, totalDebt: 10e9,
+ *       cash: 7e9, sharesOutstanding: 4.9e9 },
+ *     { year: 2022, revenue: 130e9, ebit: 30e9, totalEquity: 48e9, totalDebt: 9e9,
+ *       cash: 9e9, sharesOutstanding: 4.75e9 },
+ *   ])
+ *   console.log(result.score)    // e.g. 78
+ *   console.log(result.rating)   // 'excellent'
+ */
+declare function managementQualityScoreFromSeries(annualData: AnnualManagementData[], hurdleRate?: number): ManagementScore;
+
+/**
+ * Dividend Safety Score.
+ *
+ * Assesses the probability that a company can maintain and grow its dividend
+ * using multi-year financial data. The analysis covers free cash flow coverage,
+ * earnings coverage, balance sheet capacity, and dividend growth track record.
+ *
+ * Non-payers receive a special rating rather than a scored assessment.
+ *
+ * Signals (dividend-payers only)
+ * -------
+ * 1. FCF Payout Ratio       (35%) — dividends as fraction of free cash flow
+ * 2. Earnings Payout Ratio  (25%) — dividends as fraction of net income
+ * 3. Balance Sheet Strength (25%) — net debt / EBITDA capacity headroom
+ * 4. Dividend Growth Track  (15%) — consecutive years of non-declining dividends
+ *
+ * Score:  0–100
+ * Rating: 'safe' (≥70), 'adequate' (45–69), 'risky' (20–44), 'danger' (<20), 'non-payer'
+ */
+interface DividendComponents {
+    fcfPayoutRatio: number;
+    earningsPayoutRatio: number;
+    balanceSheetStrength: number;
+    dividendGrowthTrack: number;
+}
+interface DividendSafetyScore {
+    score: number;
+    rating: 'safe' | 'adequate' | 'risky' | 'danger' | 'non-payer';
+    components: DividendComponents;
+    isDividendPayer: boolean;
+    yearsAnalyzed: number;
+    evidence: string[];
+    interpretation: string;
+}
+/** One year of financial data for dividend safety analysis. */
+type AnnualDividendData = {
+    dividendsPaid?: number;
+    operatingCashFlow?: number;
+    capex?: number;
+    netIncome?: number;
+    totalDebt?: number;
+    cash?: number;
+    ebit?: number;
+    depreciation?: number;
+    year?: number | string;
+};
+/**
+ * Compute Dividend Safety Score from a sequence of annual financial records.
+ *
+ * @param annualData - Array in chronological order (oldest first). Min 2 years recommended.
+ * @returns DividendSafetyScore with score (0–100), rating, components, and evidence.
+ *
+ * @example
+ *   const result = dividendSafetyScoreFromSeries([
+ *     { year: 2020, dividendsPaid: 1.2e9, operatingCashFlow: 8e9, capex: 2e9,
+ *       netIncome: 5e9, totalDebt: 10e9, cash: 3e9, ebit: 7e9, depreciation: 1e9 },
+ *     { year: 2021, dividendsPaid: 1.3e9, operatingCashFlow: 9e9, capex: 2.2e9,
+ *       netIncome: 5.5e9, totalDebt: 9e9, cash: 3.5e9, ebit: 7.8e9, depreciation: 1.1e9 },
+ *   ])
+ *   console.log(result.score)   // e.g. 74
+ *   console.log(result.rating)  // 'safe'
+ */
+declare function dividendSafetyScoreFromSeries(annualData: AnnualDividendData[]): DividendSafetyScore;
+
+/**
+ * Investment Score — Grand Synthesis.
+ *
+ * Combines five complementary dimensions into a single conviction-weighted
+ * investment score. The score is designed to surface the highest-quality,
+ * best-priced businesses — the intersection of durable moat, disciplined
+ * capital allocation, reliable earnings, strong management, and attractive
+ * valuation.
+ *
+ * Weights (all five present):
+ *   Moat                25% — durability of competitive advantage
+ *   Capital Allocation  20% — effectiveness of management's capital use
+ *   Earnings Quality    20% — reliability and sustainability of reported earnings
+ *   Management          15% — operational execution and shareholder orientation
+ *   Valuation           20% — price attractiveness vs intrinsic value
+ *
+ * If valuation is omitted, its 20% weight is redistributed proportionally
+ * across the remaining four factors.
+ *
+ * Score:  0–100
+ * Grade:  'A+' (≥90), 'A' (80–89), 'B+' (70–79), 'B' (60–69),
+ *         'C' (45–59), 'D' (25–44), 'F' (<25)
+ * Conviction: 'strongBuy' | 'buy' | 'hold' | 'sell' | 'strongSell'
+ */
+
+interface InvestmentComponents {
+    moat: number | null;
+    capitalAllocation: number | null;
+    earningsQuality: number | null;
+    management: number | null;
+    valuation: number | null;
+}
+interface InvestmentScore {
+    score: number;
+    grade: 'A+' | 'A' | 'B+' | 'B' | 'C' | 'D' | 'F';
+    conviction: 'strongBuy' | 'buy' | 'hold' | 'sell' | 'strongSell';
+    components: InvestmentComponents;
+    evidence: string[];
+    interpretation: string;
+}
+interface InvestmentScoreInputs {
+    moatScore: number;
+    capitalAllocationScore: number;
+    earningsQualityScore: number;
+    managementScore: number;
+    valuationScore?: number;
+}
+/**
+ * Combine pre-computed sub-scores into an Investment Score.
+ *
+ * @param inputs - Individual sub-scores (0–100 each). `valuationScore` is optional.
+ * @returns InvestmentScore with grade, conviction, components, and evidence.
+ *
+ * @example
+ *   const result = investmentScoreFromScores({
+ *     moatScore:             78,
+ *     capitalAllocationScore: 65,
+ *     earningsQualityScore:  71,
+ *     managementScore:       80,
+ *     valuationScore:        62,
+ *   })
+ *   console.log(result.grade)      // 'B+'
+ *   console.log(result.conviction) // 'buy'
+ */
+declare function investmentScoreFromScores(inputs: InvestmentScoreInputs): InvestmentScore;
+/**
+ * Compute all sub-scores from annual financial data, then combine into an
+ * Investment Score. The management sub-score requires at least 3 years;
+ * all other sub-scores require at least 2 years.
+ *
+ * @param annualData      - Array in chronological order (oldest first). Min 3 years.
+ * @param valuationParams - Optional point-in-time valuation multiples.
+ * @param wacc            - Optional WACC override applied to moat and capital allocation.
+ * @returns InvestmentScore with grade, conviction, components, and evidence.
+ *
+ * @example
+ *   const result = investmentScoreFromSeries(
+ *     [
+ *       { year: 2020, revenue: 100e9, grossProfit: 60e9, ebit: 25e9,
+ *         netIncome: 20e9, operatingCashFlow: 24e9, totalAssets: 80e9,
+ *         totalEquity: 40e9, totalDebt: 12e9, cash: 6e9,
+ *         capex: 3e9, depreciation: 4e9, sharesOutstanding: 5e9 },
+ *       // ... more years
+ *     ],
+ *     { peRatio: 18, evEbitda: 11, pbRatio: 3.1, dcfUpsidePct: 22 },
+ *   )
+ *   console.log(result.grade)      // e.g. 'B+'
+ *   console.log(result.conviction) // 'buy'
+ */
+declare function investmentScoreFromSeries(annualData: AnnualQualityData[], valuationParams?: ValuationParams, wacc?: number): InvestmentScore;
+
+export { type AnnualDividendData, type AnnualManagementData, AnnualQualityData, type CacheOptions, type DividendComponents, type DividendSafetyScore, type DuPont3Factor, type FairValueOptions, type FairValueRange, type HoldingInput, type HoldingResult, type InvestmentComponents, type InvestmentScore, type InvestmentScoreInputs, type ManagementComponents, type ManagementScore, type PortfolioOptions, type PortfolioQualityResult, QualityFactorResult, type RatioFn, type ValuationComponents, type ValuationParams, type ValuationScore, affo, annualizeReturn, arrPerFte, assetTurnover, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, dividendSafetyScoreFromSeries, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, investmentScoreFromScores, investmentScoreFromSeries, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicNumber, managementQualityScoreFromSeries, maxDrawdown, maximumDrawdown, mean, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, valuationAttractivenessScore, workingCapitalTurnover };

package/dist/index.d.ts

@@ -1333,4 +1333,292 @@ interface PortfolioOptions {
  */
 declare function portfolioQuality(holdings: HoldingInput[], options?: PortfolioOptions): PortfolioQualityResult;
 
-export { AnnualQualityData, type CacheOptions, type DuPont3Factor, type FairValueOptions, type FairValueRange, type HoldingInput, type HoldingResult, type PortfolioOptions, type PortfolioQualityResult, QualityFactorResult, type RatioFn, affo, annualizeReturn, arrPerFte, assetTurnover, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicNumber, maxDrawdown, maximumDrawdown, mean, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, workingCapitalTurnover };
+/**
+ * Valuation Attractiveness Score.
+ *
+ * Provides a point-in-time assessment of how attractively a security is priced
+ * relative to its earnings power, free cash flow generation, asset value, and
+ * intrinsic value estimate. Higher scores indicate greater margin of safety.
+ *
+ * Signals
+ * -------
+ * 1. Earnings Yield Spread  (25%) — excess earnings yield over risk-free rate
+ * 2. FCF Yield              (25%) — free cash flow yield on market price
+ * 3. EV/EBITDA              (20%) — enterprise multiple vs historical norms
+ * 4. P/B Ratio              (15%) — price-to-book premium or discount
+ * 5. DCF Upside             (15%) — percentage gap to intrinsic value estimate
+ *
+ * Score:  0–100
+ * Rating: 'attractive' (≥65), 'fair' (40–64), 'expensive' (20–39), 'overvalued' (<20)
+ */
+interface ValuationComponents {
+    earningsYield: number;
+    fcfYield: number;
+    evEbitda: number;
+    pbRatio: number;
+    dcfUpside: number;
+}
+interface ValuationScore {
+    score: number;
+    rating: 'attractive' | 'fair' | 'expensive' | 'overvalued';
+    components: ValuationComponents;
+    riskFreeRate: number;
+    evidence: string[];
+    interpretation: string;
+}
+interface ValuationParams {
+    peRatio?: number;
+    evEbitda?: number;
+    pFcf?: number;
+    pbRatio?: number;
+    fcfYieldPct?: number;
+    earningsYieldPct?: number;
+    dcfUpsidePct?: number;
+    riskFreeRate?: number;
+}
+/**
+ * Compute a point-in-time Valuation Attractiveness Score.
+ *
+ * @param params - Valuation multiples and optional risk-free rate override.
+ *                 At least one input is required; missing signals default to 0.5.
+ * @returns ValuationScore with score (0–100), rating, components, and evidence.
+ *
+ * @example
+ *   const result = valuationAttractivenessScore({
+ *     peRatio: 18,
+ *     evEbitda: 11,
+ *     pFcf: 22,
+ *     pbRatio: 3.2,
+ *     dcfUpsidePct: 25,
+ *   })
+ *   console.log(result.score)   // e.g. 62
+ *   console.log(result.rating)  // 'fair'
+ */
+declare function valuationAttractivenessScore(params: ValuationParams): ValuationScore;
+
+/**
+ * Management Quality Score.
+ *
+ * Evaluates management's operational effectiveness using multi-year financial
+ * series. A high-scoring management team consistently earns strong returns on
+ * invested capital, expands or defends operating margins, treats shareholders
+ * with respect by avoiding dilution, and delivers reliable revenue growth.
+ *
+ * Signals
+ * -------
+ * 1. ROIC Excellence        (35%) — level, trend, and consistency of ROIC
+ * 2. Margin Stability       (25%) — operating margin level, trend, and stability
+ * 3. Shareholder Orientation(25%) — share count trajectory (buybacks vs dilution)
+ * 4. Revenue Execution      (15%) — revenue growth rate level and consistency
+ *
+ * Score:  0–100
+ * Rating: 'excellent' (≥75), 'good' (50–74), 'fair' (25–49), 'poor' (<25)
+ *
+ * Minimum 3 years of data required.
+ */
+/** One year of financial data for management quality analysis. */
+interface AnnualManagementData {
+    revenue?: number;
+    ebit?: number;
+    totalAssets?: number;
+    totalEquity?: number;
+    totalDebt?: number;
+    cash?: number;
+    sharesOutstanding?: number;
+    incomeTaxExpense?: number;
+    ebt?: number;
+    interestExpense?: number;
+    year?: number | string;
+}
+interface ManagementComponents {
+    roicExcellence: number;
+    marginStability: number;
+    shareholderOrientation: number;
+    revenueExecution: number;
+}
+interface ManagementScore {
+    score: number;
+    rating: 'excellent' | 'good' | 'fair' | 'poor';
+    components: ManagementComponents;
+    hurdleRateUsed: number;
+    yearsAnalyzed: number;
+    evidence: string[];
+    interpretation: string;
+}
+/**
+ * Compute Management Quality Score from a sequence of annual financial records.
+ *
+ * @param annualData  Array in chronological order (oldest first). Minimum 3 years.
+ * @param hurdleRate  Optional WACC override (e.g. 0.09 for 9%).
+ * @returns ManagementScore with score (0–100), rating, components, evidence.
+ *
+ * @example
+ *   const result = managementQualityScoreFromSeries([
+ *     { year: 2020, revenue: 100e9, ebit: 22e9, totalEquity: 40e9, totalDebt: 10e9,
+ *       cash: 5e9, sharesOutstanding: 5e9 },
+ *     { year: 2021, revenue: 115e9, ebit: 26e9, totalEquity: 44e9, totalDebt: 10e9,
+ *       cash: 7e9, sharesOutstanding: 4.9e9 },
+ *     { year: 2022, revenue: 130e9, ebit: 30e9, totalEquity: 48e9, totalDebt: 9e9,
+ *       cash: 9e9, sharesOutstanding: 4.75e9 },
+ *   ])
+ *   console.log(result.score)    // e.g. 78
+ *   console.log(result.rating)   // 'excellent'
+ */
+declare function managementQualityScoreFromSeries(annualData: AnnualManagementData[], hurdleRate?: number): ManagementScore;
+
+/**
+ * Dividend Safety Score.
+ *
+ * Assesses the probability that a company can maintain and grow its dividend
+ * using multi-year financial data. The analysis covers free cash flow coverage,
+ * earnings coverage, balance sheet capacity, and dividend growth track record.
+ *
+ * Non-payers receive a special rating rather than a scored assessment.
+ *
+ * Signals (dividend-payers only)
+ * -------
+ * 1. FCF Payout Ratio       (35%) — dividends as fraction of free cash flow
+ * 2. Earnings Payout Ratio  (25%) — dividends as fraction of net income
+ * 3. Balance Sheet Strength (25%) — net debt / EBITDA capacity headroom
+ * 4. Dividend Growth Track  (15%) — consecutive years of non-declining dividends
+ *
+ * Score:  0–100
+ * Rating: 'safe' (≥70), 'adequate' (45–69), 'risky' (20–44), 'danger' (<20), 'non-payer'
+ */
+interface DividendComponents {
+    fcfPayoutRatio: number;
+    earningsPayoutRatio: number;
+    balanceSheetStrength: number;
+    dividendGrowthTrack: number;
+}
+interface DividendSafetyScore {
+    score: number;
+    rating: 'safe' | 'adequate' | 'risky' | 'danger' | 'non-payer';
+    components: DividendComponents;
+    isDividendPayer: boolean;
+    yearsAnalyzed: number;
+    evidence: string[];
+    interpretation: string;
+}
+/** One year of financial data for dividend safety analysis. */
+type AnnualDividendData = {
+    dividendsPaid?: number;
+    operatingCashFlow?: number;
+    capex?: number;
+    netIncome?: number;
+    totalDebt?: number;
+    cash?: number;
+    ebit?: number;
+    depreciation?: number;
+    year?: number | string;
+};
+/**
+ * Compute Dividend Safety Score from a sequence of annual financial records.
+ *
+ * @param annualData - Array in chronological order (oldest first). Min 2 years recommended.
+ * @returns DividendSafetyScore with score (0–100), rating, components, and evidence.
+ *
+ * @example
+ *   const result = dividendSafetyScoreFromSeries([
+ *     { year: 2020, dividendsPaid: 1.2e9, operatingCashFlow: 8e9, capex: 2e9,
+ *       netIncome: 5e9, totalDebt: 10e9, cash: 3e9, ebit: 7e9, depreciation: 1e9 },
+ *     { year: 2021, dividendsPaid: 1.3e9, operatingCashFlow: 9e9, capex: 2.2e9,
+ *       netIncome: 5.5e9, totalDebt: 9e9, cash: 3.5e9, ebit: 7.8e9, depreciation: 1.1e9 },
+ *   ])
+ *   console.log(result.score)   // e.g. 74
+ *   console.log(result.rating)  // 'safe'
+ */
+declare function dividendSafetyScoreFromSeries(annualData: AnnualDividendData[]): DividendSafetyScore;
+
+/**
+ * Investment Score — Grand Synthesis.
+ *
+ * Combines five complementary dimensions into a single conviction-weighted
+ * investment score. The score is designed to surface the highest-quality,
+ * best-priced businesses — the intersection of durable moat, disciplined
+ * capital allocation, reliable earnings, strong management, and attractive
+ * valuation.
+ *
+ * Weights (all five present):
+ *   Moat                25% — durability of competitive advantage
+ *   Capital Allocation  20% — effectiveness of management's capital use
+ *   Earnings Quality    20% — reliability and sustainability of reported earnings
+ *   Management          15% — operational execution and shareholder orientation
+ *   Valuation           20% — price attractiveness vs intrinsic value
+ *
+ * If valuation is omitted, its 20% weight is redistributed proportionally
+ * across the remaining four factors.
+ *
+ * Score:  0–100
+ * Grade:  'A+' (≥90), 'A' (80–89), 'B+' (70–79), 'B' (60–69),
+ *         'C' (45–59), 'D' (25–44), 'F' (<25)
+ * Conviction: 'strongBuy' | 'buy' | 'hold' | 'sell' | 'strongSell'
+ */
+
+interface InvestmentComponents {
+    moat: number | null;
+    capitalAllocation: number | null;
+    earningsQuality: number | null;
+    management: number | null;
+    valuation: number | null;
+}
+interface InvestmentScore {
+    score: number;
+    grade: 'A+' | 'A' | 'B+' | 'B' | 'C' | 'D' | 'F';
+    conviction: 'strongBuy' | 'buy' | 'hold' | 'sell' | 'strongSell';
+    components: InvestmentComponents;
+    evidence: string[];
+    interpretation: string;
+}
+interface InvestmentScoreInputs {
+    moatScore: number;
+    capitalAllocationScore: number;
+    earningsQualityScore: number;
+    managementScore: number;
+    valuationScore?: number;
+}
+/**
+ * Combine pre-computed sub-scores into an Investment Score.
+ *
+ * @param inputs - Individual sub-scores (0–100 each). `valuationScore` is optional.
+ * @returns InvestmentScore with grade, conviction, components, and evidence.
+ *
+ * @example
+ *   const result = investmentScoreFromScores({
+ *     moatScore:             78,
+ *     capitalAllocationScore: 65,
+ *     earningsQualityScore:  71,
+ *     managementScore:       80,
+ *     valuationScore:        62,
+ *   })
+ *   console.log(result.grade)      // 'B+'
+ *   console.log(result.conviction) // 'buy'
+ */
+declare function investmentScoreFromScores(inputs: InvestmentScoreInputs): InvestmentScore;
+/**
+ * Compute all sub-scores from annual financial data, then combine into an
+ * Investment Score. The management sub-score requires at least 3 years;
+ * all other sub-scores require at least 2 years.
+ *
+ * @param annualData      - Array in chronological order (oldest first). Min 3 years.
+ * @param valuationParams - Optional point-in-time valuation multiples.
+ * @param wacc            - Optional WACC override applied to moat and capital allocation.
+ * @returns InvestmentScore with grade, conviction, components, and evidence.
+ *
+ * @example
+ *   const result = investmentScoreFromSeries(
+ *     [
+ *       { year: 2020, revenue: 100e9, grossProfit: 60e9, ebit: 25e9,
+ *         netIncome: 20e9, operatingCashFlow: 24e9, totalAssets: 80e9,
+ *         totalEquity: 40e9, totalDebt: 12e9, cash: 6e9,
+ *         capex: 3e9, depreciation: 4e9, sharesOutstanding: 5e9 },
+ *       // ... more years
+ *     ],
+ *     { peRatio: 18, evEbitda: 11, pbRatio: 3.1, dcfUpsidePct: 22 },
+ *   )
+ *   console.log(result.grade)      // e.g. 'B+'
+ *   console.log(result.conviction) // 'buy'
+ */
+declare function investmentScoreFromSeries(annualData: AnnualQualityData[], valuationParams?: ValuationParams, wacc?: number): InvestmentScore;
+
+export { type AnnualDividendData, type AnnualManagementData, AnnualQualityData, type CacheOptions, type DividendComponents, type DividendSafetyScore, type DuPont3Factor, type FairValueOptions, type FairValueRange, type HoldingInput, type HoldingResult, type InvestmentComponents, type InvestmentScore, type InvestmentScoreInputs, type ManagementComponents, type ManagementScore, type PortfolioOptions, type PortfolioQualityResult, QualityFactorResult, type RatioFn, type ValuationComponents, type ValuationParams, type ValuationScore, affo, annualizeReturn, arrPerFte, assetTurnover, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, dividendSafetyScoreFromSeries, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, investmentScoreFromScores, investmentScoreFromSeries, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicNumber, managementQualityScoreFromSeries, maxDrawdown, maximumDrawdown, mean, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, valuationAttractivenessScore, workingCapitalTurnover };