# ruff: noqa: E501

"""

# -----------

VENDORED https://github.com/mkdocstrings/autorefs/blob/e19b9fa47dac136a529c2be0d7969106ca5d5106/src/mkdocs_autorefs/

Waiting for the following PR to be merged: https://github.com/mkdocstrings/autorefs/pull/25

# -----------

This module contains the "mkdocs-autorefs" plugin.

After each page is processed by the Markdown converter, this plugin stores absolute URLs of every HTML anchors

it finds to later be able to fix unresolved references.

It stores them during the [`on_page_content` event hook](https://www.mkdocs.org/user-guide/plugins/#on_page_content).

Just before writing the final HTML to the disc, during the

[`on_post_page` event hook](https://www.mkdocs.org/user-guide/plugins/#on_post_page),

this plugin searches for references of the form `[identifier][]` or `[title][identifier]` that were not resolved,

and fixes them using the previously stored identifier-URL mapping.

"""

import contextlib

import functools

import logging

import os

import re

from html import escape, unescape

from typing import Any, Callable, Dict, List, Match, Optional, Sequence, Tuple, Union

from urllib.parse import urlsplit

from xml.etree.ElementTree import Element

from markdown import Markdown

from markdown.extensions import Extension

from markdown.inlinepatterns import REFERENCE_RE, ReferenceInlineProcessor

from markdown.util import INLINE_PLACEHOLDER_RE

from mkdocs.config import Config

from mkdocs.config import config_options as c

from mkdocs.plugins import BasePlugin

from mkdocs.structure.pages import Page

from mkdocs.structure.toc import AnchorLink

from mkdocs.utils import warning_filter

AUTO_REF_RE = re.compile(

    r"<span data-(?P<kind>autorefs-identifier|autorefs-optional|autorefs-optional-hover)="

    r'("?)(?P<identifier>[^"<>]*)\2>(?P<title>.*?)</span>'

)

"""A regular expression to match mkdocs-autorefs' special reference markers

in the [`on_post_page` hook][mkdocs_autorefs.plugin.AutorefsPlugin.on_post_page].

"""

EvalIDType = Tuple[Any, Any, Any]

class AutoRefInlineProcessor(ReferenceInlineProcessor):

    """A Markdown extension."""

    def __init__(self, *args, **kwargs):  # noqa: D107

        super().__init__(REFERENCE_RE, *args, **kwargs)

    # Code based on

    # https://github.com/Python-Markdown/markdown/blob/8e7528fa5c98bf4652deb13206d6e6241d61630b/markdown/inlinepatterns.py#L780

    def handleMatch(self, m, data) -> Union[Element, EvalIDType]:  # type: ignore[override]  # noqa: N802,WPS111

        """Handle an element that matched.

        Arguments:

            m: The match object.

            data: The matched data.

        Returns:

            A new element or a tuple.

        """

        text, index, handled = self.getText(data, m.end(0))

        if not handled:

            return None, None, None

        identifier, end, handled = self.evalId(data, index, text)

        if not handled:

            return None, None, None

        if re.search(r"[/ \x00-\x1f]", identifier):

            # Do nothing if the matched reference contains:

            # - a space, slash or control character (considered unintended);

            # - specifically \x01 is used by Python-Markdown HTML stash when there's inline formatting,

            #   but references with Markdown formatting are not possible anyway.

            return None, m.start(0), end

        return self.makeTag(identifier, text), m.start(0), end

    def evalId(

        self, data: str, index: int, text: str

    ) -> EvalIDType:  # noqa: N802 (parent's casing)

        """Evaluate the id portion of `[ref][id]`.

        If `[ref][]` use `[ref]`.

        Arguments:

            data: The data to evaluate.

            index: The starting position.

            text: The text to use when no identifier.

        Returns:

            A tuple containing the identifier, its end position, and whether it matched.

        """

        m = self.RE_LINK.match(data, pos=index)  # noqa: WPS111

        if not m:

            return None, index, False

        identifier = m.group(1)

        if not identifier:

            identifier = text

            # Allow the entire content to be one placeholder, with the intent of catching things like [`Foo`][].

            # It doesn't catch [*Foo*][] though, just due to the priority order.

            # https://github.com/Python-Markdown/markdown/blob/1858c1b601ead62ed49646ae0d99298f41b1a271/markdown/inlinepatterns.py#L78

            if INLINE_PLACEHOLDER_RE.fullmatch(identifier):

                identifier = self.unescape(identifier)

        end = m.end(0)

        return identifier, end, True

    def makeTag(self, identifier: str, text: str) -> Element:  # type: ignore[override]  # noqa: N802,W0221

        """Create a tag that can be matched by `AUTO_REF_RE`.

        Arguments:

            identifier: The identifier to use in the HTML property.

            text: The text to use in the HTML tag.

        Returns:

            A new element.

        """

        el = Element("span")

        el.set("data-autorefs-identifier", identifier)

        el.text = text

        return el

def relative_url(url_a: str, url_b: str) -> str:

    """Compute the relative path from URL A to URL B.

    Arguments:

        url_a: URL A.

        url_b: URL B.

    Returns:

        The relative URL to go from A to B.

    """

    parts_a = url_a.split("/")

    url_b, anchor = url_b.split("#", 1)

    parts_b = url_b.split("/")

    # remove common left parts

    while parts_a and parts_b and parts_a[0] == parts_b[0]:

        parts_a.pop(0)

        parts_b.pop(0)

    # go up as many times as remaining a parts' depth

    levels = len(parts_a) - 1

    parts_relative = [".."] * levels + parts_b  # noqa: WPS435

    relative = "/".join(parts_relative)

    return f"{relative}#{anchor}"

def fix_ref(

    url_mapper: Callable[[str], str], unmapped: List[str]

) -> Callable:  # noqa: WPS212,WPS231

    """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).

    In our context, we match Markdown references and replace them with HTML links.

    When the matched reference's identifier was not mapped to an URL, we append the identifier to the outer

    `unmapped` list. It generally means the user is trying to cross-reference an object that was not collected

    and rendered, making it impossible to link to it. We catch this exception in the caller to issue a warning.

    Arguments:

        url_mapper: A callable that gets an object's site URL by its identifier,

            such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].

        unmapped: A list to store unmapped identifiers.

    Returns:

        The actual function accepting a [`Match` object](https://docs.python.org/3/library/re.html#match-objects)

        and returning the replacement strings.

    """

    def inner(match: Match):  # noqa: WPS212,WPS430

        identifier = match["identifier"]

        title = match["title"]

        kind = match["kind"]

        try:

            url = url_mapper(unescape(identifier))

        except KeyError:

            if kind == "autorefs-optional":

                return title

            elif kind == "autorefs-optional-hover":

                return f'<span title="{identifier}">{title}</span>'

            unmapped.append(identifier)

            if title == identifier:

                return f"[{identifier}][]"

            return f"[{title}][{identifier}]"

        parsed = urlsplit(url)

        external = parsed.scheme or parsed.netloc

        classes = ["autorefs", "autorefs-external" if external else "autorefs-internal"]

        class_attr = " ".join(classes)

        if kind == "autorefs-optional-hover":

            return f'<a class="{class_attr}" title="{identifier}" href="{escape(url)}">{title}</a>'

        return f'<a class="{class_attr}" href="{escape(url)}">{title}</a>'

    return inner

def fix_refs(html: str, url_mapper: Callable[[str], str]) -> Tuple[str, List[str]]:

    """Fix all references in the given HTML text.

    Arguments:

        html: The text to fix.

        url_mapper: A callable that gets an object's site URL by its identifier,

            such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].

    Returns:

        The fixed HTML.

    """

    unmapped = []  # type: ignore

    html = AUTO_REF_RE.sub(fix_ref(url_mapper, unmapped), html)

    return html, unmapped

class AutorefsExtension(Extension):

    """Extension that inserts auto-references in Markdown."""

    def extendMarkdown(

        self, md: Markdown

    ) -> None:  # noqa: N802 (casing: parent method's name)

        """Register the extension.

        Add an instance of our [`AutoRefInlineProcessor`][mkdocs_autorefs.references.AutoRefInlineProcessor] to the Markdown parser.

        Arguments:

            md: A `markdown.Markdown` instance.

        """

        md.inlinePatterns.register(

            AutoRefInlineProcessor(md),

            "mkdocs-autorefs",

            priority=168,  # noqa: WPS432  # Right after markdown.inlinepatterns.ReferenceInlineProcessor

        )

log = logging.getLogger(f"mkdocs.plugins.{__name__}")

log.addFilter(warning_filter)

class AutorefsPlugin(BasePlugin):

    """An `mkdocs` plugin.

    This plugin defines the following event hooks:

    - `on_config`

    - `on_page_content`

    - `on_post_page`

    Check the [Developing Plugins](https://www.mkdocs.org/user-guide/plugins/#developing-plugins) page of `mkdocs`

    for more information about its plugin system.

    """

    scan_toc: bool = True

    current_page: Optional[str] = None

    config_scheme = (("priority", c.ListOfItems(c.Type(str), default=[])),)

    def __init__(self) -> None:

        """Initialize the object."""

        super().__init__()

        self._url_map: Dict[str, str] = {}

        self._abs_url_map: Dict[str, str] = {}

        self.get_fallback_anchor: Optional[

            Callable[[str], Optional[str]]

        ] = None  # noqa: WPS234

        self._priority_patterns = None

    @property

    def priority_patterns(self):

        if self._priority_patterns is None:

            self._priority_patterns = [

                os.path.join("/", pat) for pat in self.config.get("priority")

            ]

        return self._priority_patterns

    def register_anchor(self, url: str, identifier: str):

        """Register that an anchor corresponding to an identifier was encountered when rendering the page.

        Arguments:

            url: The relative URL of the current page. Examples: `'foo/bar/'`, `'foo/index.html'`

            identifier: The HTML anchor (without '#') as a string.

        """

        new_url = os.path.join("/", f"{url}#{identifier}")

        old_url = os.path.join("/", self._url_map.get(identifier, "")).split("#")[0]

        if identifier in self._url_map and not old_url == new_url:

            rev_patterns = list(enumerate(self.priority_patterns))[::-1]

            old_priority_idx = next(

                (i for i, pat in rev_patterns if re.match(pat, old_url)),

                len(rev_patterns),

            )

            new_priority_idx = next(

                (i for i, pat in rev_patterns if re.match(pat, new_url)),

                len(rev_patterns),

            )

            if new_priority_idx >= old_priority_idx:

                return

            if "reference" not in new_url:

                raise Exception("URL WTF", new_url)

        self._url_map[identifier] = new_url

    def register_url(self, identifier: str, url: str):

        """Register that the identifier should be turned into a link to this URL.

        Arguments:

            identifier: The new identifier.

            url: The absolute URL (including anchor, if needed) where this item can be found.

        """

        self._abs_url_map[identifier] = url

    def _get_item_url(  # noqa: WPS234

        self,

        identifier: str,

        fallback: Optional[Callable[[str], Sequence[str]]] = None,

    ) -> str:

        try:

            return self._url_map[identifier]

        except KeyError:

            if identifier in self._abs_url_map:

                return self._abs_url_map[identifier]

            if fallback:

                new_identifiers = fallback(identifier)

                for new_identifier in new_identifiers:

                    with contextlib.suppress(KeyError):

                        url = self._get_item_url(new_identifier)

                        self._url_map[identifier] = url

                        return url

            raise

    def get_item_url(  # noqa: WPS234

        self,

        identifier: str,

        from_url: Optional[str] = None,

        fallback: Optional[Callable[[str], Sequence[str]]] = None,

    ) -> str:

        """Return a site-relative URL with anchor to the identifier, if it's present anywhere.

        Arguments:

            identifier: The anchor (without '#').

            from_url: The URL of the base page, from which we link towards the targeted pages.

            fallback: An optional function to suggest alternative anchors to try on failure.

        Returns:

            A site-relative URL.

        """

        return self._get_item_url(identifier, fallback)

    def on_config(

        self, config: Config, **kwargs

    ) -> Config:  # noqa: W0613,R0201 (unused arguments, cannot be static)

        """Instantiate our Markdown extension.

        Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).

        In this hook, we instantiate our [`AutorefsExtension`][mkdocs_autorefs.references.AutorefsExtension]

        and add it to the list of Markdown extensions used by `mkdocs`.

        Arguments:

            config: The MkDocs config object.

            kwargs: Additional arguments passed by MkDocs.

        Returns:

            The modified config.

        """

        log.debug(f"{__name__}: Adding AutorefsExtension to the list")

        config["markdown_extensions"].append(AutorefsExtension())

        return config

    def on_page_markdown(

        self, markdown: str, page: Page, **kwargs

    ) -> str:  # noqa: W0613 (unused arguments)

        """Remember which page is the current one.

        Arguments:

            markdown: Input Markdown.

            page: The related MkDocs page instance.

            kwargs: Additional arguments passed by MkDocs.

        Returns:

            The same Markdown. We only use this hook to map anchors to URLs.

        """

        self.current_page = page.url  # noqa: WPS601

        return markdown

    def on_page_content(

        self, html: str, page: Page, **kwargs

    ) -> str:  # noqa: W0613 (unused arguments)

        """Map anchors to URLs.

        Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).

        In this hook, we map the IDs of every anchor found in the table of contents to the anchors absolute URLs.

        This mapping will be used later to fix unresolved reference of the form `[title][identifier]` or

        `[identifier][]`.

        Arguments:

            html: HTML converted from Markdown.

            page: The related MkDocs page instance.

            kwargs: Additional arguments passed by MkDocs.

        Returns:

            The same HTML. We only use this hook to map anchors to URLs.

        """

        if self.scan_toc:

            log.debug(

                f"{__name__}: Mapping identifiers to URLs for page {page.file.src_path}"

            )

            for item in page.toc.items:

                self.map_urls(page, item)

        return html

    def map_urls(self, page: Page, anchor: AnchorLink) -> None:

        """Recurse on every anchor to map its ID to its absolute URL.

        This method populates `self.url_map` by side-effect.

        Arguments:

            base_url: The base URL to use as a prefix for each anchor's relative URL.

            anchor: The anchor to process and to recurse on.

        """

        abs_url = os.path.join("/", page.file.url)

        self.register_anchor(abs_url, anchor.id)

        for child in anchor.children:

            self.map_urls(page, child)

    def on_post_page(

        self, output: str, page: Page, **kwargs

    ) -> str:  # noqa: W0613 (unused arguments)

        """Fix cross-references.

        Hook for the [`on_post_page` event](https://www.mkdocs.org/user-guide/plugins/#on_post_page).

        In this hook, we try to fix unresolved references of the form `[title][identifier]` or `[identifier][]`.

        Doing that allows the user of `autorefs` to cross-reference objects in their documentation strings.

        It uses the native Markdown syntax so it's easy to remember and use.

        We log a warning for each reference that we couldn't map to an URL, but try to be smart and ignore identifiers

        that do not look legitimate (sometimes documentation can contain strings matching

        our [`AUTO_REF_RE`][mkdocs_autorefs.references.AUTO_REF_RE] regular expression that did not intend to reference anything).

        We currently ignore references when their identifier contains a space or a slash.

        Arguments:

            output: HTML converted from Markdown.

            page: The related MkDocs page instance.

            kwargs: Additional arguments passed by MkDocs.

        Returns:

            Modified HTML.

        """

        log.debug(f"{__name__}: Fixing references in page {page.file.src_path}")

        url_mapper = functools.partial(

            self.get_item_url, from_url=page.url, fallback=self.get_fallback_anchor

        )

        fixed_output, unmapped = fix_refs(output, url_mapper)

        if unmapped and log.isEnabledFor(logging.WARNING):

            for ref in unmapped:

                log.warning(

                    f"{__name__}: {page.file.src_path}: Could not find cross-reference target '[{ref}]'",

                )

        return fixed_output