"""
Basic helper functions for working with href attributes in HTML files.

These utilities classify different types of links so that the cleaner
can make informed decisions about whether a link should be preserved,
verified, or disabled. Each helper focuses on a specific category of
href values commonly found in Dartdoc-generated HTML.
"""

from __future__ import annotations


def is_anchor(href: str) -> bool:
    """
    Return True if the href represents a pure anchor link.

    Anchor links begin with a single '#' and refer to a specific
    section within the same HTML document. Because they do not
    point to external files, they are never treated as dead links
    by the cleaner.
    """
    return href.startswith("#")


def is_external_or_js(href: str) -> bool:
    """
    Return True if the href points to an external resource or a
    JavaScript pseudo-URL.

    External URLs (http://, https://):
        These are not validated for existence, because external pages
        are outside the scope of the documentation and should not be
        disabled based on local checks.

    JavaScript URLs (javascript:...):
        These do not represent real navigation targets and are considered
        non-functional or potentially unsafe. They are treated as invalid
        when encountered by the cleaner.
    """
    return href.startswith(("http://", "https://", "javascript:"))


def is_trivially_bad_href(href: str) -> bool:
    """
    Return True for href values that are always considered invalid.

    This includes:
        - empty strings or whitespace-only values,
        - JavaScript pseudo-URLs (javascript:...),
        - localhost or 127.0.0.1 URLs, which have no meaning inside
          a static documentation set and typically indicate template
          leftovers or unintended development links.

    These hrefs are disabled without performing any other checks.
    """
    if not href or href.strip() == "":
        return True

    low = href.lower()

    if low.startswith("javascript:"):
        return True

    if low.startswith("http://localhost") or low.startswith("http://127.0.0.1"):
        return True

    return False
