"""Docstring content quality tests.

Validates that generated convenience docstrings:
- Show spec defaults for all types (not just booleans)
- Use endpoint-specific pagination descriptions from convenience.json
- Have rich descriptions for convenience params (via request_model enrichment)
"""

from __future__ import annotations

import pytest


def _get_docstring(cls_path: str, method: str) -> str:
    module_path, cls_name = cls_path.rsplit(".", 1)
    mod = __import__(module_path, fromlist=[cls_name])
    cls = getattr(mod, cls_name)
    return getattr(cls, method).__doc__ or ""


# ---------------------------------------------------------------------------
# Spec defaults in docstrings
# ---------------------------------------------------------------------------

class TestDocstringSpecDefaults:
    """Docstrings must show spec defaults for all types, not just booleans.

    Signatures use = None for non-booleans (let server decide), but docstrings
    show the actual default so users can discover server behavior.
    See resolve_doc_default() in param_merge.py.
    """

    def test_sort_order_server_default_shown(self):
        doc = _get_docstring("goodmem.api.spaces.SpacesAPI", "list")
        assert "server default='DESCENDING'" in doc, (
            "spaces.list() docstring must show server default='DESCENDING' for sort_order"
        )

    def test_sort_by_server_default_shown(self):
        doc = _get_docstring("goodmem.api.spaces.SpacesAPI", "list")
        assert "server default='created_time'" in doc, (
            "spaces.list() docstring must show server default='created_time' for sort_by"
        )

    def test_boolean_server_default_shown(self):
        """Booleans use server default=, not SDK default= (same as all other types)."""
        doc = _get_docstring("goodmem.api.memories.MemoriesAPI", "get")
        assert "server default=False" in doc, (
            "memories.get() docstring must show server default=False for include_content"
        )


# ---------------------------------------------------------------------------
# Pagination descriptions from convenience.json
# ---------------------------------------------------------------------------

class TestPaginationDescriptions:
    """Pagination param descriptions must come from convenience.json, not the IR."""

    def test_memories_page_size_has_endpoint_specific_clamping(self):
        doc = _get_docstring("goodmem.api.memories.MemoriesAPI", "list")
        assert "[1, 500]" in doc, (
            "memories.list() page_size must mention [1, 500] clamping"
        )

    def test_spaces_page_size_has_endpoint_specific_clamping(self):
        doc = _get_docstring("goodmem.api.spaces.SpacesAPI", "list")
        assert "[1, 1000]" in doc, (
            "spaces.list() page_size must mention [1, 1000] clamping"
        )

    def test_no_alias_hint_in_page_size(self):
        """page_size description must not contain server-side alias hints."""
        for cls_path in ["goodmem.api.memories.MemoriesAPI", "goodmem.api.spaces.SpacesAPI"]:
            doc = _get_docstring(cls_path, "list")
            for line in doc.splitlines():
                if "page_size" in line:
                    assert "snake_case alias" not in line, (
                        f"{cls_path}.list() page_size must not contain alias hint"
                    )

    def test_max_items_has_cross_page_description(self):
        doc = _get_docstring("goodmem.api.memories.MemoriesAPI", "list")
        assert "total" in doc.lower() or "across all pages" in doc.lower(), (
            "memories.list() max_items must explain cross-page behavior"
        )


# ---------------------------------------------------------------------------
# Convenience docstring enrichment via request_model
# ---------------------------------------------------------------------------

class TestConvenienceDocstringEnrichment:
    """Convenience params must have rich descriptions from request_model enrichment."""

    def test_api_key_param_describes_credential_conversion(self):
        doc = _get_docstring("goodmem.api.llms.LlmsAPI", "create")
        assert "EndpointAuthentication" in doc or "credential" in doc.lower(), (
            "llms.create() api_key should describe credential conversion"
        )

    def test_model_identifier_mentions_registry(self):
        doc = _get_docstring("goodmem.api.llms.LlmsAPI", "create")
        assert "auto-fill" in doc.lower() or "registered" in doc.lower() or "infer" in doc.lower(), (
            "llms.create() model_identifier should mention registry auto-inference"
        )

    def test_endpoint_url_mentions_auto_inference(self):
        doc = _get_docstring("goodmem.api.rerankers.RerankersAPI", "create")
        assert "infer" in doc.lower() or "auto" in doc.lower(), (
            "rerankers.create() endpoint_url should mention auto-inference"
        )
