"""Inline-citation normalization for article HTML.

AI-generated article bodies cite sources with a numbered reference that should
render as a small, clickable superscript number (e.g. a footnote-style ``[1]``)
linking to the source URL, with the full URLs listed only in a trailing
References section.

The model is *instructed* to emit the canonical superscript-anchor form, but it
is not reliable: when it writes the body as HTML, markdown citations like
``[[1]](url)`` land inside raw HTML blocks and never get converted by the
markdown renderer, leaking the literal ``[[1]](url)`` into the published page.

`normalize_citations` runs on the *final* HTML (after markdown rendering) so it
sees a uniform input regardless of whether the body arrived as markdown or HTML.
It converts every inline citation into one canonical form:

    <sup class="tsai-citation"><a href="URL">[N]</a></sup>

It is idempotent: re-running it (or running it on already-correct output) yields
the same result.
"""

from __future__ import annotations

import re

# Canonical inline-citation markup.
_CANONICAL = '<sup class="tsai-citation"><a href="{url}">[{n}]</a></sup>'

# Leaked markdown citation, double bracket: [[1]](url)
_MD_DOUBLE = re.compile(r'\[\[(\d+)\]\]\(([^\s)]+)\)')

# Leaked markdown citation, single bracket: [1](url)
_MD_SINGLE = re.compile(r'\[(\d+)\]\(([^\s)]+)\)')

# An anchor whose visible text is exactly a bracketed number, optionally already
# wrapped in <sup>...</sup>. Matches bare rendered anchors (from a markdown body)
# as well as already-superscripted ones, so both collapse to the canonical form.
# Reference-list entries are unaffected because their link text is the source
# title, not a bracketed number.
_ANCHOR_CITATION = re.compile(
    r'(?:<sup\b[^>]*>\s*)?'                       # optional opening <sup>
    r'<a\b[^>]*?\bhref="([^"]+)"[^>]*>'           # anchor open, capture href
    r'\s*\[(\d+)\]\s*'                            # visible text: [N]
    r'</a>'                                       # anchor close
    r'(?:\s*</sup>)?',                            # optional closing </sup>
)


def normalize_citations(html: str) -> str:
    """Rewrite every inline citation in ``html`` to the canonical superscript form.

    Handles leaked markdown citations (``[[1]](url)`` and ``[1](url)``),
    bare rendered anchors (``<a href="url">[1]</a>``), and already-superscripted
    anchors. Idempotent and safe to run on output that contains no citations.
    """
    if not html:
        return html

    def _md_repl(match: "re.Match[str]") -> str:
        return _CANONICAL.format(url=match.group(2), n=match.group(1))

    def _anchor_repl(match: "re.Match[str]") -> str:
        return _CANONICAL.format(url=match.group(1), n=match.group(2))

    # Order matters: collapse double-bracket markdown before single-bracket so a
    # stray inner match can't fire first.
    html = _MD_DOUBLE.sub(_md_repl, html)
    html = _MD_SINGLE.sub(_md_repl, html)
    html = _ANCHOR_CITATION.sub(_anchor_repl, html)
    return html