signal-bot/signal_bot/analytics/render.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""What !analityka says in the group.

Twelve lines is a cap, not a quota: a line with nothing to say is dropped
rather than printed empty, the same way the nightly report drops its
highlights. No ``ljust`` anywhere -- Signal renders a proportional font, so
padding lines up in a terminal and on nobody's phone.

Two rules about people, both inherited from ``DOCS-statistics.md``.

Only somebody whose display name has actually been seen may be named; the
group listing knows everyone else as a raw uuid or a phone number, and
printing either into a chat is a leak. And a per-person breakdown of
everybody's habits stays on the management page: the group gets a top three
and the asker's own favourite, which is what was decided when this was
specified.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING, Final

from signal_bot.analytics import trend as trends
from signal_bot.stats import text
from signal_bot.stats.periods import pl_day_month

if TYPE_CHECKING:
    from collections.abc import Mapping, Sequence

    from signal_bot.analytics.demand import Demand
    from signal_bot.analytics.hours import Peak
    from signal_bot.analytics.scope import Window
    from signal_bot.analytics.usage import CommandUse, PersonUse

MAX_LINES: Final = 12
TOP_COMMANDS: Final = 3
TOP_PEOPLE: Final = 3

HEADING: Final = "Analityka komend"
NOTHING_YET: Final = "Nikt jeszcze nie użył żadnej komendy."

DIRECTIONS: Final = {
    trends.RISING: "użycie rośnie",
    trends.FALLING: "użycie spada",
    trends.FLAT: "użycie się trzyma",
}


def days_phrase(count: int) -> str:
    """A day count with its noun agreeing: 3 dni."""
    return f"{count} {text.plural(count, 'dzień', 'dni', 'dni')}"


def times_phrase(count: int) -> str:
    """A count with its noun agreeing: 5 razy."""
    return f"{count} {text.plural(count, 'raz', 'razy', 'razy')}"


def window_line(measured: Window) -> str:
    """What the numbers actually cover. Always printed, always first.

    The bot is days old, not months. A reader who cannot see that is reading
    a month panel drawn from three days as though it were a month.
    """
    span = days_phrase(measured.days)
    if measured.first_day == measured.last_day:
        return f"Okno: {span} ({pl_day_month(measured.first_day)}), {times_phrase(measured.events)}"
    return (
        f"Okno: {span} ({pl_day_month(measured.first_day)}"
        f" — {pl_day_month(measured.last_day)}), {times_phrase(measured.events)}"
    )


def top_line(uses: Sequence[CommandUse]) -> str:
    """The three most used commands, with their counts."""
    best = ", ".join(f"!{use.command} {use.uses}" for use in uses[:TOP_COMMANDS])
    return f"Najczęściej: {best}"


def rarest_line(uses: Sequence[CommandUse]) -> str:
    """The least used command that anybody has used at all."""
    quietest = uses[-1]
    return f"Najrzadziej: !{quietest.command} — {times_phrase(quietest.uses)}"


def hours_line(peak: Peak) -> str:
    """When the group actually reaches for the bot."""
    return f"Najgłośniejsza godzina: {peak.busiest:02d}:00 ({times_phrase(peak.busiest_uses)})"


def trend_line(direction: str) -> str:
    """The verdict, or nothing at all when it is too early to have one.

    Returning "" rather than "za mało danych" is deliberate: the window line
    above already says how many days there are, and repeating it as an
    apology wastes one of twelve lines.
    """
    return DIRECTIONS.get(direction, "")


def health_line(uses: Sequence[CommandUse]) -> str:
    """The command most in need of attention, if any is.

    Refusals count as much as errors here. A command refused half the time
    is not popular, it is mis-tuned, and from the group's side both read as
    "it does not work".
    """
    troubled = [use for use in uses if use.errors or use.refused]
    if not troubled:
        return ""
    worst = max(troubled, key=lambda use: (use.errors + use.refused, use.command))
    # "błędów: 3" rather than "3 błędy": a label and a number needs no
    # agreement at all, and Polish agreement after a numeral has three forms
    # whose rule reads the last two digits. Sidestepping it here is free.
    parts = []
    if worst.errors:
        parts.append(f"błędów: {worst.errors}")
    if worst.refused:
        parts.append(f"odmów: {worst.refused}")
    return f"Do poprawki: !{worst.command} ({', '.join(parts)})"


def demand_line(demand: Demand) -> str:
    """The trigger people keep almost typing, which wants another alias."""
    if not demand.near_misses:
        return ""
    miss = demand.near_misses[0]
    return f"Blisko trafień: {miss.target} — {times_phrase(miss.hits)}"


def people_line(people: Sequence[PersonUse], names: Mapping[str, str]) -> str:
    """The top three, and only those whose name the bot has actually seen."""
    named = [(names[person.uuid], person.uses) for person in people if person.uuid in names]
    if not named:
        return ""
    best = ", ".join(f"{name} {uses}" for name, uses in named[:TOP_PEOPLE])
    return f"Kto najwięcej: {best}"


def mine_line(people: Sequence[PersonUse], uuid: str) -> str:
    """The asker's own favourite. Self-scope, so it names nobody else."""
    for person in people:
        if person.uuid == uuid and person.favourite:
            return f"Twoja ulubiona: !{person.favourite} ({times_phrase(person.uses)})"
    return ""


def share_line(commands: int, messages: int) -> str:
    """How much of the group's talking is talking to the bot."""
    if not messages:
        return ""
    percent = round(100 * commands / messages)
    return f"Komendy to {percent}% wiadomości w tej grupie"


@dataclass(frozen=True, slots=True)
class Summary:
    """Everything the reply needs, gathered before any of it is worded.

    One object rather than ten arguments, because these always travel
    together: the command builds it from the query layer and the renderer
    turns it into Polish, and neither half needs to know the other.
    """

    measured: Window
    uses: Sequence[CommandUse]
    people: Sequence[PersonUse]
    names: Mapping[str, str]
    peak: Peak
    direction: str
    demand: Demand
    asker: str
    commands: int
    messages: int


def render(summary: Summary) -> str:
    """Build the reply, capped at twelve lines and never padded."""
    if not summary.uses:
        return NOTHING_YET
    lines = [
        HEADING,
        window_line(summary.measured),
        top_line(summary.uses),
        rarest_line(summary.uses),
        hours_line(summary.peak),
        trend_line(summary.direction),
        share_line(summary.commands, summary.messages),
        health_line(summary.uses),
        demand_line(summary.demand),
        people_line(summary.people, summary.names),
        mine_line(summary.people, summary.asker),
    ]
    # Dropped, then capped. A line with nothing to say is not printed empty,
    # so the cap bites on content rather than on blanks -- and the cap is
    # what keeps a reply readable on a phone.
    kept = [line for line in lines if line][:MAX_LINES]
    return "\n".join(kept)