"""Expected Return (spec §29 / VALUATION.md §6)."""
from __future__ import annotations

from dataclasses import dataclass
from typing import Optional


@dataclass(frozen=True)
class ExpectedReturnComponents:
    fundamental_growth_rate: Optional[float]   # EPS or FCF CAGR used as the growth driver
    shareholder_yield: Optional[float]         # dividends + net buybacks, annualized
    current_multiple: Optional[float]
    reference_multiple: Optional[float]        # multiple the price is assumed to converge toward
    years: int


@dataclass(frozen=True)
class ExpectedReturnResult:
    cagr: Optional[float]
    components: ExpectedReturnComponents


def compute_expected_return(c: ExpectedReturnComponents) -> ExpectedReturnResult:
    if c.fundamental_growth_rate is None or c.years <= 0:
        return ExpectedReturnResult(None, c)

    growth_factor = (1 + c.fundamental_growth_rate) ** c.years
    yield_factor = (1 + (c.shareholder_yield or 0.0)) ** c.years

    if c.current_multiple and c.reference_multiple and c.current_multiple > 0:
        multiple_factor = (c.reference_multiple / c.current_multiple)
    else:
        multiple_factor = 1.0  # no multiple re-rating assumed if either multiple is unavailable/non-positive

    total_factor = growth_factor * yield_factor * multiple_factor
    if total_factor <= 0:
        return ExpectedReturnResult(None, c)
    cagr = total_factor ** (1 / c.years) - 1
    return ExpectedReturnResult(cagr, c)