"""The fact-check / corrections comment contract.

Fact-check and corrections comments are posted to WordPress as guest comments
whose *author name* encodes which model produced them, e.g.
``Fact-Check (via OpenAI gpt-5.5)``. That name is the only marker identifying
them: corrections look up their parent fact-check by matching the author-name
prefix, and comment scoring excludes them the same way.

The format therefore has to agree in every place that writes or reads it. It
previously lived as separate literals in the article-creation service, the
comment agent, and improve_article.py; this module is the single definition.
"""

from typing import Any, Dict, Iterable, Optional

# Author-name prefixes, lowercased for case-insensitive matching.
FACT_CHECK_AUTHOR_PREFIX = 'fact-check (via '
CORRECTIONS_AUTHOR_PREFIX = 'corrections (via '


def fact_check_author_name(provider_name: str, model_name: str) -> str:
    """The author name to post a fact-check comment under."""
    return f"Fact-Check (via {provider_name} {model_name})"


def corrections_author_name(provider_name: str, model_name: str) -> str:
    """The author name to post a corrections comment under."""
    return f"Corrections (via {provider_name} {model_name})"


def is_fact_check_comment(comment: Dict[str, Any]) -> bool:
    """True when a WordPress comment dict is a fact-check comment."""
    return (comment.get('author_name') or '').lower().startswith(FACT_CHECK_AUTHOR_PREFIX)


def find_fact_check_comment(comments: Optional[Iterable[Dict[str, Any]]]) -> Optional[Dict[str, Any]]:
    """Return the first fact-check comment in a list of WP comments, or None."""
    for comment in comments or []:
        if is_fact_check_comment(comment):
            return comment
    return None