#!/usr/bin/env python3
"""Verify the two invariants a treemap can silently break.

A treemap's whole claim is that **area is the encoding**. Both ways of breaking
that claim render perfectly - nothing errors, nothing disappears, and neither
`lint-skin.py` (colors, fonts, a11y) nor `verify-geometry.py` (label masks vs
later-painted nodes) reads a cell against the number printed inside it.

1. AREA FIDELITY - a cell's share of the drawn area must match the share its
   own label claims. This is checked as **relative** error, not percentage
   points: a 0.13pp slip is noise on a 59% cell and a quarter of a 0.5% cell,
   so an absolute threshold passes exactly the cell most likely to be wrong.
   The failure is real - the smallest cell absorbs the whole 4px-grid residue,
   because 4px is a third of a sliver and a rounding error on a giant.

2. LABEL AND MARKER FIT - a label or information marker must stay inside the
   cell it names. Cells have no clip path, so overflow bleeds into a neighbour
   or off the viewBox and reads as belonging to the wrong thing. A cell too
   small for its annotation is not a nudge-the-coordinates problem: drop the
   annotation (the cell keeps its honest area) or merge the tail into a named
   "Other".

Text extent is estimated from font metrics rather than measured in a browser,
deliberately: every other gate here is pure Python and runs in CI with no
browser. The Latin advances below are calibrated against Chromium renderings of
the shipped Geist / Geist Mono faces and rounded UP. Unicode wide/full-width
characters use a conservative 1em advance, so both estimates report overflow
slightly before real overflow, never after.

Usage:
    python3 scripts/verify-treemap.py --all
    python3 scripts/verify-treemap.py skills/diagram-design/assets/example-treemap.html

Exit: 0 clean, 1 findings, 2 usage.
"""

from __future__ import annotations

import argparse
import html
import re
import sys
import unicodedata
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
ASSET_DIR = ROOT / "skills/diagram-design/assets"

CELL_RE = re.compile(
    r"<rect\b[^>]*?"
    r'\bx="(?P<x>-?[\d.]+)"\s+y="(?P<y>-?[\d.]+)"\s+'
    r'width="(?P<w>[\d.]+)"\s+height="(?P<h>[\d.]+)"[^>]*?'
    r'rx="2"',
    re.IGNORECASE,
)
TEXT_RE = re.compile(r"<text\b(?P<attrs>[^>]*)>(?P<body>.*?)</text>", re.IGNORECASE | re.DOTALL)
CIRCLE_RE = re.compile(r"<circle\b(?P<attrs>[^>]*)/?>", re.IGNORECASE)
ATTR_RE = re.compile(r'(?P<name>[\w:-]+)="(?P<value>[^"]*)"')
ROTATE_RE = re.compile(r"rotate\(\s*(?P<deg>-?[\d.]+)")
TAG_RE = re.compile(r"<[^>]+>")
# A cell states its size one of two ways, and the two must not be confused: a
# magnitude ("4.78B") is a value to be normalised against the other cells, while
# a percentage ("59%", "0.6%") is already the claimed share. Reading "0.6%" as
# the number 0.6 against cells measured in billions produces nonsense, so the
# percentage pattern is tried first and anchored on the sign.
PCT_RE = re.compile(r"(?P<num>\d[\d,]*(?:\.\d+)?)\s*%")
VALUE_RE = re.compile(r"(?P<num>\d[\d,]*(?:\.\d+)?)\s*(?P<unit>[BMK])\b")

MONO_ADVANCE = 0.62
SANS_ADVANCE = 0.60
WIDE_ADVANCE = 1.00
ASCENT = 0.74
UNITS = {None: 1.0, "K": 1e3, "M": 1e6, "B": 1e9}

# A treemap cell is large enough to hold a label and small enough not to be a
# page background or diagram container.
CELL_MIN_AREA = 400.0
CELL_MAX_W = 900.0
CELL_MAX_H = 460.0
EPSILON = 1.0
# Relative area tolerance. Grid snapping on a 1000x500 viewBox cannot do better
# than a couple of percent on a sub-1% cell; 8% is loose enough never to fire on
# honest rounding and tight enough to have caught the 30%-undersized sliver this
# check exists for.
AREA_TOLERANCE = 8.0
MARKER_EPSILON = 0.01


class Box:
    __slots__ = ("x", "y", "w", "h", "offset")

    def __init__(self, x: float, y: float, w: float, h: float, offset: int = 0) -> None:
        self.x, self.y, self.w, self.h, self.offset = x, y, w, h, offset

    @property
    def right(self) -> float:
        return self.x + self.w

    @property
    def bottom(self) -> float:
        return self.y + self.h

    @property
    def area(self) -> float:
        return self.w * self.h

    def contains_point(self, x: float, y: float) -> bool:
        return (
            self.x - EPSILON <= x <= self.right + EPSILON
            and self.y - EPSILON <= y <= self.bottom + EPSILON
        )


def line_of(source: str, offset: int) -> int:
    return source.count("\n", 0, offset) + 1


def plain(body: str) -> str:
    return html.unescape(TAG_RE.sub("", body)).strip()


def estimated_advance(text: str, mono: bool) -> float:
    """Conservative text advance in em, preserving the calibrated Latin baseline."""
    narrow_advance = MONO_ADVANCE if mono else SANS_ADVANCE
    advance = 0.0
    for char in text:
        # Nonspacing and enclosing marks modify the preceding glyph; counting
        # them as another glyph rejects labels that do fit. Spacing combining
        # marks (Mc) retain the narrow estimate because they can advance.
        if unicodedata.category(char) in {"Mn", "Me"}:
            continue
        if unicodedata.east_asian_width(char) in {"W", "F"}:
            advance += WIDE_ADVANCE
        else:
            advance += narrow_advance
    return advance


def parse_cells(source: str) -> list[Box]:
    """Deduped cell rects. Each cell is painted twice: paper mask, then body."""
    seen: list[Box] = []
    for m in CELL_RE.finditer(source):
        box = Box(
            float(m.group("x")),
            float(m.group("y")),
            float(m.group("w")),
            float(m.group("h")),
            m.start(),
        )
        if box.area < CELL_MIN_AREA or box.w > CELL_MAX_W or box.h > CELL_MAX_H:
            continue
        if any(
            abs(s.x - box.x) < 0.01
            and abs(s.y - box.y) < 0.01
            and abs(s.w - box.w) < 0.01
            and abs(s.h - box.h) < 0.01
            for s in seen
        ):
            continue
        seen.append(box)
    return seen


def label_box(attrs: dict[str, str], body: str) -> Box | None:
    """Estimated rendered box of a <text>, in root user space."""
    try:
        x = float(attrs["x"])
        y = float(attrs["y"])
        size = float(attrs.get("font-size", "12"))
    except (KeyError, ValueError):
        return None
    text = plain(body)
    if not text:
        return None
    mono = "mono" in attrs.get("font-family", "").lower()
    width = size * estimated_advance(text, mono)
    anchor = attrs.get("text-anchor", "start")

    transform = attrs.get("transform", "")
    if transform:
        m = ROTATE_RE.search(transform)
        # Only the quarter-turn cases are modelled; anything else is skipped
        # rather than guessed at.
        if m is None or abs(abs(float(m.group("deg"))) - 90.0) > 0.01:
            return None
        if anchor == "middle":
            top = y - width / 2
        elif anchor == "end":
            top = y
        else:
            top = y - width
        return Box(x - size * ASCENT, top, size, width)

    if anchor == "middle":
        left = x - width / 2
    elif anchor == "end":
        left = x - width
    else:
        left = x
    return Box(left, y - size * ASCENT, width, size)


def _number(match: re.Match[str] | None) -> float | None:
    if match is None:
        return None
    try:
        return float(match.group("num").replace(",", ""))
    except ValueError:
        return None


def parse_claim(text: str) -> tuple[float | None, float | None]:
    """(percentage, value) claimed by a label. Either may be absent."""
    percentage = _number(PCT_RE.search(text))
    value_match = VALUE_RE.search(text)
    value = _number(value_match)
    if value is not None and value_match is not None:
        value *= UNITS[value_match.group("unit")]
    return percentage, value


def check(path: Path) -> list[str]:
    source = path.read_text(encoding="utf-8")
    cells = parse_cells(source)
    if len(cells) < 3:
        return []

    findings: list[str] = []
    labels: dict[int, list[str]] = {index: [] for index in range(len(cells))}

    for m in TEXT_RE.finditer(source):
        attrs = {a.group("name"): a.group("value") for a in ATTR_RE.finditer(m.group("attrs"))}
        box = label_box(attrs, m.group("body"))
        if box is None:
            continue
        # Host is resolved from the text's ANCHOR, not its box corner. An
        # end- or middle-anchored label extends left of its anchor, so a box
        # corner can land outside the very cell the label belongs to - which
        # would silently attribute it to a neighbour, or to nothing at all.
        anchor_x, anchor_y = float(attrs["x"]), float(attrs["y"])
        host_index = None
        for index, cell in enumerate(cells):
            if not cell.contains_point(anchor_x, anchor_y):
                continue
            if host_index is None or cell.area < cells[host_index].area:
                host_index = index
        if host_index is None:
            continue
        host = cells[host_index]
        labels[host_index].append(plain(m.group("body")))

        # All four edges. Checking only right and bottom passes an end-anchored
        # label hanging off the left, or a label whose ascent clears the top -
        # both of which read as belonging to the neighbouring cell.
        overflow = {
            "left": host.x - box.x,
            "top": host.y - box.y,
            "right": box.right - host.right,
            "bottom": box.bottom - host.bottom,
        }
        breached = {side: over for side, over in overflow.items() if over > EPSILON}
        if breached:
            detail = " / ".join(f"{over:.1f} {side}" for side, over in breached.items())
            findings.append(
                f"{path.name}:{line_of(source, m.start())}: label "
                f"{plain(m.group('body'))[:38]!r} overflows its {host.w:g}x{host.h:g} cell "
                f"by {detail} — drop the label or merge the cell into a named Other"
            )

    # Information marks are 8–12px discs placed inside sliver cells. Their
    # one-letter text can fit while the surrounding disc still crosses a cell
    # boundary, so circles need their own containment check.
    for m in CIRCLE_RE.finditer(source):
        attrs = {a.group("name"): a.group("value") for a in ATTR_RE.finditer(m.group("attrs"))}
        try:
            cx = float(attrs["cx"])
            cy = float(attrs["cy"])
            radius = float(attrs["r"])
        except (KeyError, ValueError):
            continue
        if not 4.0 <= radius <= 6.0:
            continue
        host_index = None
        for index, cell in enumerate(cells):
            if not cell.contains_point(cx, cy):
                continue
            if host_index is None or cell.area < cells[host_index].area:
                host_index = index
        if host_index is None:
            continue
        host = cells[host_index]
        overflow = {
            "left": host.x - (cx - radius),
            "top": host.y - (cy - radius),
            "right": (cx + radius) - host.right,
            "bottom": (cy + radius) - host.bottom,
        }
        breached = {
            side: over for side, over in overflow.items() if over > MARKER_EPSILON
        }
        if breached:
            detail = " / ".join(f"{over:.1f} {side}" for side, over in breached.items())
            findings.append(
                f"{path.name}:{line_of(source, m.start())}: information marker "
                f"overflows its {host.w:g}x{host.h:g} cell by {detail} — "
                "drop the marker and identify the sliver in the legend"
            )

    claims = {index: parse_claim(" ".join(texts)) for index, texts in labels.items()}
    # Only compare on a basis every cell states, so the shares share a
    # denominator. Percentages win when present: they are the claim itself.
    percentages = {i: p for i, (p, _) in claims.items() if p}
    magnitudes = {i: v for i, (_, v) in claims.items() if v}
    known = percentages if len(percentages) >= len(magnitudes) else magnitudes

    # Normalise both sides over the labelled cells only. A sliver too small to
    # label is legal - it keeps its honest area and is named in the source line
    # - and it must not switch this check off for the cells that do carry a
    # claim, which is what comparing against the full drawn area would do.
    if len(known) >= 3:
        drawn_total = sum(cells[index].area for index in known)
        value_total = sum(known.values())
        for index, value in sorted(known.items()):
            cell = cells[index]
            area_share = cell.area / drawn_total * 100
            value_share = value / value_total * 100
            relative = (area_share - value_share) / value_share * 100
            if abs(relative) > AREA_TOLERANCE:
                findings.append(
                    f"{path.name}:{line_of(source, cell.offset)}: cell "
                    f"{cell.w:g}x{cell.h:g} labelled {' '.join(labels[index])[:30]!r} draws "
                    f"{area_share:.2f}% of the area for a {value_share:.2f}% value — "
                    f"{relative:+.1f}% relative. Area is the only encoding; resize the cell"
                )
    return findings


def targets(args: argparse.Namespace) -> list[Path]:
    if args.all:
        return sorted(ASSET_DIR.glob("example-treemap*.html"))
    return [Path(p) for p in args.paths]


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Verify treemap area fidelity and label/marker fit."
    )
    parser.add_argument("paths", nargs="*", help="HTML files to check")
    parser.add_argument("--all", action="store_true", help="check every shipped treemap example")
    args = parser.parse_args()
    if not args.all and not args.paths:
        parser.print_help()
        return 2

    findings: list[str] = []
    checked = 0
    for path in targets(args):
        if not path.exists():
            print(f"error: {path} does not exist", file=sys.stderr)
            return 2
        findings.extend(check(path))
        checked += 1

    for finding in findings:
        print(finding)
    if findings:
        print(f"\n{len(findings)} treemap finding(s) across {checked} file(s).")
        return 1
    print(
        f"OK treemap: {checked} file(s), area matches labels and every label/marker fits its cell"
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())