"""Content definitions for the AskMyDocs enterprise documentation corpus.

Documents are defined as markdown strings generated by builder functions
that accept a :class:`~scripts.corpus_shims.CorpusContext`, which keeps
cross-references (document ids, usernames, feature flags) consistent.

Sections / topics covered:

docs 001-004  Authentication & security (auth, tokens, mfa, security)
docs 005-009  OAuth / SSO / federation
docs 010-014  API usage / references / errors
docs 015-018  Configuration / feature flags
docs 019-021  Deployment / environments
docs 022-024  Monitoring / observability
docs 025-027  User management / roles
docs 028-031  Database behavior / troubleshooting / rate limits / webhooks
"""

from __future__ import annotations

from collections.abc import Callable

from corpus_shims import front_matter, h2

# ---------------------------------------------------------------------------
# Reusable factual "facts" that the golden dataset references.
# These constants make the golden dataset verifiable against the corpus.
# ---------------------------------------------------------------------------

FACTS = {
    "api_key_prefix": "amsk_",
    "api_key_lifetime": "90 days",
    "oauth_provider": "OAuth 2.0",
    "token_expiry": "60 minutes",
    "refresh_token_expiry": "30 days",
    "rate_limit_default": "100 requests per minute",
    "rate_limit_burst": "300 requests per minute",
    "webhook_delivery": "HMAC-SHA256 signature",
    "webhook_retry": "5 retries, exponential backoff, max 10 minutes",
    "database_engine": "PostgreSQL 16",
    "db_connection_max": "100",
    "backup_retention": "30 days",
    "apitoken_claim": "permissions claim",
    "rbac_default_role": "viewer",
    "sso_saml": "SAML 2.0",
    "sso_oidc": "OpenID Connect",
    "sla_uptime": "99.95%",
    "pii_encryption": "AES-256 at rest",
}

# ---------------------------------------------------------------------------
# Helper: section renderer
# ---------------------------------------------------------------------------


def doc(
    doc_id: str,
    title: str,
    version: str,
    module: str,
    *sections: Callable[[], str],
) -> str:
    """Compose a document from front matter + sections."""
    parts: list[str] = [front_matter(doc_id=doc_id, title=title, version=version, module=module)]
    parts.extend(s() for s in sections)
    return "\n".join(parts)


def numbered_section(num: int, title: str, body: str) -> str:
    return h2(f"{num}. {title}") + body


def create_auth_context() -> dict[str, str]:
    """Context fields shared across auth-related documents."""
    return {
        "api_key_prefix": FACTS["api_key_prefix"],
        "token_expiry": FACTS["token_expiry"],
        "refresh_token_expiry": FACTS["refresh_token_expiry"],
    }