# src/dartdoc_advanced/cleaner/stubs.py

"""
Logic for detecting "stub" HTML files - very small, low-value pages that can
be safely removed from generated documentation.

The goal is to reduce noise in the final docs by deleting pages that contain
almost no meaningful content, while carefully preserving structural and
navigation-critical files such as class sidebars.
"""

from __future__ import annotations

from pathlib import Path

from bs4 import BeautifulSoup

# Suffixes for class / enum / mixin / extension / typedef / top-level sidebars.
# These sidebars are never deleted even if they appear short, because they
# usually contain important navigation for symbols within the library.
CLASS_SIDEBAR_SUFFIXES = tuple(
    f"-{k}-sidebar.html"
    for k in ("class", "enum", "mixin", "extension", "typedef", "top-level")
)


def is_deletable_stub(html_path: Path, min_chars: int, tiny_chars: int) -> bool:
    """
    Decide whether a given HTML file should be treated as a "stub" and removed.

    Rules:
        - Always delete files ending with "*-library-sidebar.html":
          these sidebars add little value and often duplicate content.

        - Never delete class/enum/mixin/extension/typedef/top-level sidebars:
          even short sidebars for these entity types still provide navigation,
          so they are considered essential.

        - For files ending with "*-sidebar.html" or "*-library.html":
          interpret them as navigation or library-level pages and compare
          their text length against `min_chars`.

        - For all other HTML files:
          compare their text length against `tiny_chars`.

    The thresholds `min_chars` and `tiny_chars` are supplied by the caller
    and allow tuning the aggressiveness of stub detection.

    Parameters:
        html_path: Path to the HTML file being evaluated.
        min_chars: Minimum text length for sidebar/library pages to be kept.
        tiny_chars: Minimum text length for all other HTML pages to be kept.

    Returns:
        True  if the file should be treated as a stub and can be deleted.
        False if the file should be preserved.
    """
    name = html_path.name

    # Always drop library sidebars: they contribute very little on their own.
    if name.endswith("-library-sidebar.html"):
        return True

    # Explicitly keep class/enum/mixin/etc. sidebars even if short.
    if name.endswith(CLASS_SIDEBAR_SUFFIXES):
        return False

    # Compute the length of the textual content in the file.
    try:
        txt_len = len(
            BeautifulSoup(
                html_path.read_text(encoding="utf-8", errors="ignore"), "lxml"
            ).get_text(strip=True)
        )
    except Exception:
        # If anything goes wrong while reading/parsing, treat the file as empty.
        txt_len = 0

    # Sidebar and library pages use the more conservative `min_chars` threshold.
    if name.endswith(("-sidebar.html", "-library.html")):
        return txt_len < min_chars

    # All other pages use the more aggressive `tiny_chars` threshold.
    return txt_len < tiny_chars
