"""FAQ hints for the interactive formation flow.

Maps formation field keywords to relevant legal FAQ snippets shown during
the ``corpo form`` interactive flow.
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class FAQHint:
    question: str
    short_answer: str
    statutory_reference: str
    category: str


# Each entry maps a set of field keywords to an FAQ hint.
_HINTS: list[tuple[list[str], FAQHint]] = [
    (
        ["name", "entity name", "llc name", "lao", "dao"],
        FAQHint(
            question="Why 'LAO' instead of 'DAO'?",
            short_answer=(
                "Corpo uses LAO (Limited Autonomous Organization) exclusively. "
                "It signals legal compliance + limited liability protection and "
                "distinguishes from informal/unregistered DAOs. Names ending in "
                "'DAO', 'DAO LLC', 'LLC', or 'L.L.C.' are rejected."
            ),
            statutory_reference="W.S. 17-31-104(d)",
            category="entity_naming",
        ),
    ),
    (
        ["tax", "taxation", "c-corp", "k-1", "irs"],
        FAQHint(
            question="Why C-corp taxation?",
            short_answer=(
                "Corpo elects C-corp taxation (IRS Form 8832) so the entity "
                "pays 21% federal corporate tax. Token holders have no "
                "individual tax obligations — no K-1 headaches."
            ),
            statutory_reference="IRS Form 8832",
            category="taxation",
        ),
    ),
    (
        ["vote", "voting", "quorum", "governance", "token"],
        FAQHint(
            question="Why one-token-one-vote?",
            short_answer=(
                "Wyoming defaults to contribution-based voting. Corpo overrides "
                "this: 1 governance token = 1 vote, regardless of contribution "
                "amount. Quorum = >50% of deposited tokens."
            ),
            statutory_reference="W.S. 17-31-111(a)(i)",
            category="voting_governance",
        ),
    ),
    (
        ["member", "members", "membership", "withdraw"],
        FAQHint(
            question="How does token supply map to membership?",
            short_answer=(
                "Anyone holding governance tokens deposited into Realms becomes "
                "a member. Withdrawn members forfeit all membership interests."
            ),
            statutory_reference="W.S. 17-31-113(d)(i)",
            category="voting_governance",
        ),
    ),
    (
        ["smart contract", "realms", "solana", "program"],
        FAQHint(
            question="What's the smart contract requirement?",
            short_answer=(
                "Articles must include the Solana Realms governance program "
                "address. Corpo includes it automatically — no 30-day filing "
                "risk."
            ),
            statutory_reference="W.S. 17-31-106(b)",
            category="formation_compliance",
        ),
    ),
    (
        ["cost", "price", "fee", "filing"],
        FAQHint(
            question="What does it cost?",
            short_answer=(
                "Formation: $260 (SOS $100 + registered agent $100 + annual "
                "report $60). Ongoing: $160/year. Does not include Corpo "
                "platform fees or Solana tx costs."
            ),
            statutory_reference="",
            category="practical",
        ),
    ),
    (
        ["registered agent", "agent", "wyoming agents"],
        FAQHint(
            question="What's the registered agent?",
            short_answer=(
                "Corpo uses Wyoming Agents (wyomingagents.com). Wyoming "
                "requires every LLC to maintain a registered agent in-state."
            ),
            statutory_reference="W.S. 17-31-105(b)",
            category="practical",
        ),
    ),
    (
        ["fiduciary", "duty", "liability", "good faith"],
        FAQHint(
            question="What about fiduciary duties?",
            short_answer=(
                "DAO LLC members have NO fiduciary duty except the implied "
                "covenant of good faith and fair dealing — a much lower bar "
                "than traditional LLCs."
            ),
            statutory_reference="W.S. 17-31-110",
            category="liability_duties",
        ),
    ),
    (
        ["dissolve", "dissolution", "inactivity", "inactive"],
        FAQHint(
            question="What about the 1-year inactivity dissolution risk?",
            short_answer=(
                "A DAO LLC is dissolved if no proposals or actions for 1 year. "
                "Keep governance active! Even a simple admin proposal counts."
            ),
            statutory_reference="W.S. 17-31-114(a)(iv)",
            category="formation_compliance",
        ),
    ),
    (
        ["state", "wyoming", "foreign", "jurisdiction"],
        FAQHint(
            question="Can a foreign DAO register in Wyoming?",
            short_answer=(
                "No. W.S. 17-31-116 prohibits it. You must form natively in "
                "Wyoming to get DAO LLC protections."
            ),
            statutory_reference="W.S. 17-31-116",
            category="practical",
        ),
    ),
]


def lookup_hints(field_name: str, *, max_results: int = 2) -> list[FAQHint]:
    """Return FAQ hints relevant to *field_name* (case-insensitive keyword match)."""
    field_lower = field_name.lower()
    results: list[FAQHint] = []
    for keywords, hint in _HINTS:
        for kw in keywords:
            if kw in field_lower or field_lower in kw:
                results.append(hint)
                break
        if len(results) >= max_results:
            break
    return results


def format_hint(hint: FAQHint) -> str:
    """Format a single FAQ hint for terminal display."""
    ref = f" [{hint.statutory_reference}]" if hint.statutory_reference else ""
    return f"  💡 {hint.question}{ref}\n     {hint.short_answer}"


def format_hints_for_field(field_name: str) -> str | None:
    """Return formatted FAQ hints for a field, or None if no matches."""
    hints = lookup_hints(field_name)
    if not hints:
        return None
    lines = [format_hint(h) for h in hints]
    return "\n".join(lines)
