src/format.py

"""Formatting helpers, matching the design's own conventions.

Two rules run through all of this and are worth stating once:

  * A number that does not exist renders as an em dash, never as `0`. The
    Atlas is a tool for judging models, and a fabricated zero is worse than an
    admitted gap.
  * Counts are grouped with commas the way the design writes them
    ("1,842,301"), and abbreviated only where the design abbreviates.
"""

from __future__ import annotations

from datetime import datetime, timezone

DASH = "—"


def num(value) -> str:
    """1842301 -> '1,842,301'. None or unparseable -> em dash."""
    if value is None:
        return DASH
    try:
        return f"{int(value):,}"
    except (TypeError, ValueError):
        return DASH


def compact(value) -> str:
    """731455 -> '731K'. Used in the lineage tree, where space is tight.

    A decimal is kept only below 10, matching how the design writes these:
    "731K", "188K", "1.8M" -- never "731.5K", which is both wider than the
    column and more precision than the number deserves.
    """
    if value is None:
        return DASH
    try:
        n = int(value)
    except (TypeError, ValueError):
        return DASH
    for cutoff, suffix in ((1_000_000_000, "B"), (1_000_000, "M"), (1_000, "K")):
        if abs(n) >= cutoff:
            scaled = n / cutoff
            if abs(scaled) < 10:
                text = f"{scaled:.1f}".rstrip("0").rstrip(".")
            else:
                text = str(round(scaled))
            return f"{text}{suffix}"
    return str(n)


def parse_stamp(value):
    """ISO 8601 -> aware datetime, or None. Never raises."""
    if not value or not isinstance(value, str):
        return None
    try:
        when = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    return when.replace(tzinfo=timezone.utc) if when.tzinfo is None else when


def months_since(value, now=None) -> float | None:
    when = parse_stamp(value)
    if when is None:
        return None
    now = now or datetime.now(timezone.utc)
    return (now - when).days / 30.44


def age_label(value, now=None) -> str:
    """The design's age wording: '3w ago', '9mo ago', '2.6y ago'."""
    months = months_since(value, now)
    if months is None:
        return DASH
    if months < 1:
        days = max(0, int(months * 30.44))
        if days < 7:
            return f"{days}d ago" if days else "today"
        return f"{days // 7}w ago"
    if months < 12:
        return f"{int(months)}mo ago"
    years = f"{months / 12:.1f}".rstrip("0").rstrip(".")
    return f"{years}y ago"


def age_tone(value, now=None) -> tuple:
    """(colour, glyph) for a commit age, on the design's three-band scale."""
    months = months_since(value, now)
    if months is None:
        return "var(--text-tertiary)", "·"
    if months < 3:
        return "var(--fin-up)", "●"
    if months < 12:
        return "var(--accent-amber-strong)", "◐"
    return "var(--fin-down)", "○"


def short_ago(value, now=None) -> str:
    """Compact 'how long since the last crawl', for the header pill."""
    when = parse_stamp(value)
    if when is None:
        return DASH
    now = now or datetime.now(timezone.utc)
    seconds = max(0, (now - when).total_seconds())
    if seconds < 3600:
        return f"{int(seconds // 60)}m"
    if seconds < 86400:
        return f"{int(seconds // 3600)}h"
    return f"{int(seconds // 86400)}d"


def utc_stamp(value) -> str:
    """'2026-08-20 06:14 UTC', the design's header format."""
    when = parse_stamp(value)
    if when is None:
        return DASH
    return when.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")


def iso_date(value) -> str:
    when = parse_stamp(value)
    return when.astimezone(timezone.utc).strftime("%Y-%m-%d") if when else DASH


def percent(part, whole) -> str:
    """'61%'. A zero denominator is an em dash, not a division by zero."""
    try:
        whole = int(whole)
        if whole <= 0:
            return DASH
        return f"{round(int(part) / whole * 100)}%"
    except (TypeError, ValueError, ZeroDivisionError):
        return DASH


def initials(model_id: str) -> str:
    """The two-character author avatar the design puts on every row."""
    author = (model_id or "").split("/")[0]
    if not author:
        return "??"
    return (author[0] + (author[1] if len(author) > 1 else "")).upper()