"""
Utilities for detecting autodoc-generated content.

Provides a canonical implementation for detecting whether a page was
generated by Bengal's autodoc system. This consolidates duplicate
implementations found in:
- bengal/analysis/knowledge_graph.py (_is_autodoc_page)
- bengal/health/validators/directives.py (_is_autodoc_file)

See RFC: plan/active/rfc-code-quality-improvements.md
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from bengal.protocols import PageLike


def is_autodoc_page(page: PageLike | Any) -> bool:
    """
    Check if a page is autodoc-generated.

    Autodoc pages are identified by multiple signals:

    **Frontmatter Indicators**:
    - Type starting with "python-" (python-module, python-class, etc.)
    - Type "autodoc-cli" or "autodoc-python"
    - Presence of "source_file" field
    - Generator metadata "bengal-autodoc"
    - Presence of "_api_doc" marker

    **Content Indicators**:
    - Content containing "Generated by Bengal autodoc"
    - Content containing "Generated by Bengal"

    **Path Indicators**:
    - Source path contains "/api/"
    - Source path ends with "/api"

    Args:
        page: Page object to check. Can be a Page, PageProxy, or any
              object with metadata/frontmatter and content attributes.

    Returns:
        True if page is autodoc-generated

    Example:
            >>> from bengal.utils.autodoc import is_autodoc_page
            >>> if is_autodoc_page(page):
            ...     # Skip autodoc pages in analysis
            ...     continue

    """
    # Check frontmatter/metadata for autodoc indicators
    # Try both 'metadata' (Page) and 'frontmatter' (some validators use this)
    metadata = getattr(page, "metadata", None) or getattr(page, "frontmatter", {})

    if isinstance(metadata, dict):
        page_type = metadata.get("type", "")

        # Check type-based indicators
        if (
            page_type.startswith(("python-", "cli-", "openapi-"))
            or page_type in ("autodoc-python", "autodoc-cli", "autodoc-rest", "autodoc-hub")
            or "source_file" in metadata
            or metadata.get("generator") == "bengal-autodoc"
            or metadata.get("_api_doc") is not None  # Internal API doc marker
        ):
            return True

    # Check source path for API directory patterns
    source_path = getattr(page, "source_path", None)
    if source_path:
        path_str = str(source_path)
        # Only check for /content/api/ (explicit content/api directory)
        # This avoids matching paths that just happen to contain "api" elsewhere
        if "/content/api/" in path_str:
            return True

    # Check content for autodoc-specific footer
    # NOTE: Only check for "Generated by Bengal autodoc" - NOT the generic
    # "Generated by Bengal" which appears in CLI docs and other generated content.
    content = getattr(page, "content", "")
    return isinstance(content, str) and "Generated by Bengal autodoc" in content
