ROIC Calculation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

/** Deterministic TypeScript reference calculations for D18-F01. */

type Inputs = Record<string, unknown>;
type Output = Record<string, unknown>;

function numberValue(name: string, value: unknown): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new RangeError(`${name} must be a finite number`);
  return value;
}

function positive(name: string, value: unknown): number {
  const parsed = numberValue(name, value);
  if (parsed <= 0) throw new RangeError(`${name} must be positive`);
  return parsed;
}

function booleanValue(name: string, value: unknown): boolean {
  if (typeof value !== "boolean") throw new RangeError(`${name} must be boolean`);
  return value;
}

const average = (beginning: number, ending: number): number => (beginning + ending) / 2;
const clean = (value: number): number => {
  const rounded = Math.round((value + Number.EPSILON) * 1e12) / 1e12;
  return Object.is(rounded, -0) ? 0 : rounded;
};

export function dupontDecomposition(input: Inputs): Output {
  const income = numberValue("net_income", input.net_income);
  const revenue = numberValue("revenue", input.revenue);
  const averageAssets = average(numberValue("beginning_assets", input.beginning_assets), numberValue("ending_assets", input.ending_assets));
  const averageEquity = average(numberValue("beginning_equity", input.beginning_equity), numberValue("ending_equity", input.ending_equity));
  if (revenue === 0 || averageAssets <= 0 || averageEquity <= 0) {
    const reasons: string[] = [];
    if (revenue === 0) reasons.push("zero-revenue");
    if (averageAssets <= 0) reasons.push("nonpositive-average-assets");
    if (averageEquity <= 0) reasons.push("nonpositive-average-equity");
    return { net_profit_margin: null, asset_turnover: null, equity_multiplier: null, dupont_roe: null, direct_roe: null, identity_gap: null,
      average_assets: clean(averageAssets), average_equity: clean(averageEquity), state: "not-meaningful", reason: reasons.join("+") };
  }
  const margin = income / revenue;
  const turnover = revenue / averageAssets;
  const multiplier = averageAssets / averageEquity;
  const dupontRoe = margin * turnover * multiplier;
  const directRoe = income / averageEquity;
  return { net_profit_margin: clean(margin), asset_turnover: clean(turnover), equity_multiplier: clean(multiplier), dupont_roe: clean(dupontRoe),
    direct_roe: clean(directRoe), identity_gap: clean(dupontRoe - directRoe), average_assets: clean(averageAssets), average_equity: clean(averageEquity),
    state: income < 0 ? "loss" : "calculated", reason: "three-factor-identity-reconciles" };
}

export function roicCalculation(input: Inputs): Output {
  const profit = numberValue("operating_profit", input.operating_profit);
  const taxRate = numberValue("normalized_tax_rate", input.normalized_tax_rate);
  if (taxRate < 0 || taxRate > 1) throw new RangeError("normalized_tax_rate must be between 0 and 1");
  const capitalBegin = numberValue("beginning_operating_assets", input.beginning_operating_assets) - numberValue("beginning_operating_liabilities", input.beginning_operating_liabilities);
  const capitalEnd = numberValue("ending_operating_assets", input.ending_operating_assets) - numberValue("ending_operating_liabilities", input.ending_operating_liabilities);
  const averageCapital = average(capitalBegin, capitalEnd);
  const nopat = profit * (1 - taxRate);
  if (averageCapital <= 0) return { nopat: clean(nopat), beginning_invested_capital: clean(capitalBegin), ending_invested_capital: clean(capitalEnd),
    average_invested_capital: clean(averageCapital), roic: null, state: "not-meaningful", reason: "nonpositive-average-invested-capital" };
  return { nopat: clean(nopat), beginning_invested_capital: clean(capitalBegin), ending_invested_capital: clean(capitalEnd),
    average_invested_capital: clean(averageCapital), roic: clean(nopat / averageCapital), state: nopat < 0 ? "loss" : "calculated",
    reason: "package-operating-capital-definition" };
}

export function cashConversionCycle(input: Inputs): Output {
  const revenue = numberValue("revenue", input.revenue);
  const cogs = numberValue("cost_of_goods_sold", input.cost_of_goods_sold);
  const days = positive("day_count", input.day_count);
  const receivablesBegin = numberValue("beginning_receivables", input.beginning_receivables);
  const receivablesEnd = numberValue("ending_receivables", input.ending_receivables);
  const inventoryBegin = numberValue("beginning_inventory", input.beginning_inventory);
  const inventoryEnd = numberValue("ending_inventory", input.ending_inventory);
  const payablesBegin = numberValue("beginning_trade_payables", input.beginning_trade_payables);
  const payablesEnd = numberValue("ending_trade_payables", input.ending_trade_payables);
  if (Math.min(receivablesBegin, receivablesEnd, inventoryBegin, inventoryEnd, payablesBegin, payablesEnd) < 0) throw new RangeError("working-capital balances must be nonnegative");
  const receivables = average(receivablesBegin, receivablesEnd);
  const inventory = average(inventoryBegin, inventoryEnd);
  const payables = average(payablesBegin, payablesEnd);
  if (revenue <= 0 || cogs <= 0) return { average_receivables: clean(receivables), average_inventory: clean(inventory), average_trade_payables: clean(payables),
    days_sales_outstanding: null, days_inventory_outstanding: null, days_payables_outstanding: null, cash_conversion_cycle_days: null,
    state: "not-meaningful", reason: revenue <= 0 ? "nonpositive-revenue" : "nonpositive-cogs" };
  const dso = receivables / revenue * days;
  const dio = inventory / cogs * days;
  const dpo = payables / cogs * days;
  const ccc = dio + dso - dpo;
  return { average_receivables: clean(receivables), average_inventory: clean(inventory), average_trade_payables: clean(payables),
    days_sales_outstanding: clean(dso), days_inventory_outstanding: clean(dio), days_payables_outstanding: clean(dpo),
    cash_conversion_cycle_days: clean(ccc), state: ccc < 0 ? "negative-cycle" : "calculated", reason: "dio-plus-dso-minus-dpo" };
}

export function interestCoverageRatio(input: Inputs): Output {
  const ebit = numberValue("ebit", input.ebit);
  const interest = numberValue("gross_interest_expense", input.gross_interest_expense);
  if (interest <= 0) return { ebit: clean(ebit), gross_interest_expense: clean(interest), interest_coverage_ratio: null,
    coverage_shortfall: null, state: "not-meaningful", reason: "nonpositive-gross-interest-expense" };
  const ratio = ebit / interest;
  return { ebit: clean(ebit), gross_interest_expense: clean(interest), interest_coverage_ratio: clean(ratio),
    coverage_shortfall: clean(Math.max(0, interest - ebit)), state: ratio >= 1 ? "covered" : "not-covered",
    reason: "ebit-divided-by-gross-interest-expense" };
}

export function netDebtToEbitda(input: Inputs): Output {
  const income = numberValue("net_income", input.net_income);
  const interest = numberValue("interest_expense", input.interest_expense);
  const tax = numberValue("income_tax_expense", input.income_tax_expense);
  const da = numberValue("depreciation_and_amortization", input.depreciation_and_amortization);
  const currentDebt = numberValue("current_borrowings", input.current_borrowings);
  const noncurrentDebt = numberValue("noncurrent_borrowings", input.noncurrent_borrowings);
  const leases = numberValue("lease_liabilities", input.lease_liabilities);
  const cash = numberValue("cash_and_cash_equivalents", input.cash_and_cash_equivalents);
  const includeLeases = booleanValue("include_lease_liabilities", input.include_lease_liabilities);
  if (Math.min(interest, da, currentDebt, noncurrentDebt, leases, cash) < 0) throw new RangeError("debt, cash, interest, and D&A inputs must be nonnegative");
  const ebitda = income + interest + tax + da;
  const grossDebt = currentDebt + noncurrentDebt + (includeLeases ? leases : 0);
  const netDebt = grossDebt - cash;
  if (ebitda <= 0) return { ebitda: clean(ebitda), gross_debt: clean(grossDebt), net_debt: clean(netDebt), net_debt_to_ebitda: null,
    lease_policy: includeLeases ? "included" : "excluded", state: "not-meaningful", reason: "nonpositive-ebitda" };
  return { ebitda: clean(ebitda), gross_debt: clean(grossDebt), net_debt: clean(netDebt), net_debt_to_ebitda: clean(netDebt / ebitda),
    lease_policy: includeLeases ? "included" : "excluded", state: netDebt < 0 ? "net-cash" : "net-debt", reason: "net-debt-divided-by-ebitda" };
}

interface Item { label: string; value: number }
interface Period { period: string; items: Item[] }

export function commonSizeStatements(input: Inputs): Output {
  const statementType = input.statement_type;
  if (statementType !== "income" && statementType !== "balance") throw new RangeError("statement_type must be 'income' or 'balance'");
  const baseLabel = input.base_label;
  const focusLabel = input.focus_label;
  if (typeof baseLabel !== "string" || !baseLabel.trim()) throw new RangeError("base_label must be a nonempty string");
  if (typeof focusLabel !== "string" || !focusLabel.trim()) throw new RangeError("focus_label must be a nonempty string");
  if (!Array.isArray(input.periods) || input.periods.length < 2) throw new RangeError("periods must contain at least two period objects");
  let expectedLabels: string[] | null = null;
  let previousFocus: number | null = null;
  const normalizedPeriods = (input.periods as unknown[]).map((rawPeriod, periodIndex) => {
    if (!rawPeriod || typeof rawPeriod !== "object") throw new RangeError(`periods[${periodIndex}] must be an object`);
    const period = rawPeriod as Record<string, unknown>;
    if (typeof period.period !== "string" || !period.period.trim()) throw new RangeError(`periods[${periodIndex}].period must be a nonempty string`);
    if (!Array.isArray(period.items) || period.items.length < 4) throw new RangeError(`periods[${periodIndex}].items must contain at least four rows`);
    const seen = new Set<string>();
    const parsed = (period.items as unknown[]).map((rawItem, itemIndex): Item => {
      if (!rawItem || typeof rawItem !== "object") throw new RangeError(`periods[${periodIndex}].items[${itemIndex}] must be an object`);
      const item = rawItem as Record<string, unknown>;
      if (typeof item.label !== "string" || !item.label.trim() || seen.has(item.label)) throw new RangeError("statement item labels must be nonempty and unique within a period");
      seen.add(item.label);
      return { label: item.label, value: numberValue(`${period.period}.${item.label}`, item.value) };
    });
    const labels = parsed.map((item) => item.label);
    if (expectedLabels === null) expectedLabels = labels;
    else if (labels.join("\u0000") !== expectedLabels.join("\u0000")) throw new RangeError("every period must use the same ordered line-item labels");
    const values = Object.fromEntries(parsed.map((item) => [item.label, item.value]));
    if (!(baseLabel in values) || !(focusLabel in values)) throw new RangeError("base_label and focus_label must exist in every period");
    const base = values[baseLabel];
    if (base === 0 || (statementType === "balance" && base < 0)) throw new RangeError("the common-size base must be nonzero and positive for balance sheets");
    const focusPercentage = values[focusLabel] / base * 100;
    const result = { period: (period.period as string).trim(), base_value: clean(base), focus_percentage: clean(focusPercentage),
      focus_change_pp: previousFocus === null ? null : clean(focusPercentage - previousFocus),
      items: parsed.map((item) => ({ label: item.label, value: clean(item.value), common_size_pct: clean(item.value / base * 100) })) };
    previousFocus = focusPercentage;
    return result;
  });
  const latest = normalizedPeriods[normalizedPeriods.length - 1];
  return { statement_type: statementType, base_label: baseLabel, focus_label: focusLabel, period_count: normalizedPeriods.length,
    line_item_count: normalizedPeriods[0].items.length, focus_percentage: latest.focus_percentage, focus_change_pp: latest.focus_change_pp,
    periods: normalizedPeriods, state: "calculated", reason: "signed-line-items-divided-by-period-base" };
}

export function calculate(topicId: string, input: Inputs): Output {
  if (!input || typeof input !== "object" || Array.isArray(input)) throw new RangeError("inputs must be an object");
  switch (topicId) {
    case "D18-F01-A01": return dupontDecomposition(input);
    case "D18-F01-A02": return roicCalculation(input);
    case "D18-F01-A03": return cashConversionCycle(input);
    case "D18-F01-A04": return interestCoverageRatio(input);
    case "D18-F01-A05": return netDebtToEbitda(input);
    case "D18-F01-A06": return commonSizeStatements(input);
    default: throw new RangeError(`unsupported topic_id: ${topicId}`);
  }
}