from dataclasses import dataclass
from typing import List
import pandas as pd


@dataclass
class GovernanceFinding:
    severity: str
    message: str


def data_quality_report(df: pd.DataFrame) -> List[GovernanceFinding]:
    findings: List[GovernanceFinding] = []

    if df.empty:
        return [GovernanceFinding("HIGH", "Dataset is empty. Analytics cannot proceed.")]

    missing_ratio = df.isna().mean()
    high_missing = missing_ratio[missing_ratio >= 0.30]

    if not high_missing.empty:
        findings.append(
            GovernanceFinding(
                "MEDIUM",
                "High missingness detected in: " + ", ".join(high_missing.index.tolist()),
            )
        )

    if "esg_score" in df.columns:
        values = pd.to_numeric(df["esg_score"], errors="coerce").dropna()
        if not values.empty and ((values < 0).any() or (values > 100).any()):
            findings.append(
                GovernanceFinding("HIGH", "esg_score contains values outside 0..100.")
            )

    return findings


def representation_proxy_check(df: pd.DataFrame, group_col: str = "country") -> List[GovernanceFinding]:
    findings: List[GovernanceFinding] = []

    if group_col not in df.columns:
        return findings

    shares = df[group_col].fillna("UNKNOWN").value_counts(normalize=True)
    if not shares.empty and shares.iloc[0] > 0.75:
        findings.append(
            GovernanceFinding(
                "MEDIUM",
                f"Representation imbalance detected: '{shares.index[0]}' accounts for {shares.iloc[0]*100:.1f}% of records.",
            )
        )

    return findings
