signal-bot/signal_bot/reporting.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Composing the evening report: what it says, but never the sending of it.

Split out of bot.py at the 250-line cap, and the seam is worth having on its
own terms -- everything here is pure, so "what would the group be told?" is a
question that can be answered without a transport, a group, or a send.

One run can have several things to say: a day the bot was down for, the day
it is on now, and the week or month that ended inside them. They are blocks
in one message rather than a post each, because four notifications in one
evening is how a daily tally becomes something people mute.
"""

from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Final

from signal_bot.stats import curiosities, periods
from signal_bot.stats.backfill import backfilled_day
from signal_bot.stats.facts import gather
from signal_bot.stats.highlights import SLOTS, select
from signal_bot.stats.nightly import closing_periods
from signal_bot.stats.queries_day import day_rows, day_totals, with_silent
from signal_bot.stats.queries_period import Trend, period_rows, total_for
from signal_bot.stats.render_day import DayView, render_day
from signal_bot.stats.render_period import render_period

if TYPE_CHECKING:
    from collections.abc import Sequence

    from signal_bot.discovery import GroupDirectory
    from signal_bot.store import Store

logger = logging.getLogger(__name__)

# What separates the day, the week and any caught-up day inside one report.
# A blank line and a rule, because Signal renders no markdown and two blocks
# run straight into each other without one.
BLOCK_SEPARATOR: Final = "\n\n———\n\n"


def compose(
    store: Store,
    directory: GroupDirectory,
    group_id: str,
    days: Sequence[str],
    today: str,
    closed_at: str | None,
) -> str:
    """The whole message for one group, or "" when there is nothing to say.

    Args:
        store: The open database.
        directory: Used for the member roster, so people who said nothing are
            still named.
        group_id: The group being reported on.
        days: Days to cover, oldest first.
        today: The day that is still running, from the caller's clock. Passed
            rather than read here: one injected clock decides what "today"
            means for the whole bot, and a second reading of the real one
            could disagree with it across midnight.
        closed_at: "HH:MM" that still-running day was counted up to.
    """
    blocks: list[str] = []
    for day in days:
        block = day_block(store, directory, group_id, day, closed_at if day == today else None)
        if block:
            blocks.append(block)
        blocks.extend(closing_blocks(store, group_id, day))
    return BLOCK_SEPARATOR.join(blocks)


def day_block(
    store: Store,
    directory: GroupDirectory,
    group_id: str,
    day: str,
    closed_at: str | None,
) -> str | None:
    """One day as the group reads it, or None if nobody spoke that day."""
    rows = day_rows(store.events, group_id, day)
    if not rows:
        # The bot is in every group it was ever added to, so "nobody spoke"
        # would be a nightly ping into every quiet group, forever.
        logger.info("no messages in %s on %s; not reporting on it", group_id, day)
        return None
    named = store.events.roster(group_id, directory.member_identities(group_id))
    with_zeros = with_silent(rows, [(person.uuid, person.display_name) for person in named])
    backfilled = backfilled_day(store, group_id)
    facts = gather(store.events, group_id, day, with_zeros, exclude=backfilled)
    picks = select(curiosities.for_day(facts), SLOTS)
    return render_day(
        day,
        with_zeros,
        day_totals(with_zeros),
        DayView(
            since=store.events.first_day(group_id),
            approximate=backfilled == day,
            highlights=tuple(pick.text for pick in picks),
            # Only for a day that is still running: telling the group a
            # finished day's count "stopped at 21:37" would be a lie.
            closed_at=closed_at,
        ),
    )


def closing_blocks(store: Store, group_id: str, day: str) -> list[str]:
    """The week, month or year that ended with this day, if any.

    Rendered rather than posted: they join the day in one message, so a
    Sunday evening is one notification and not two.
    """
    blocks: list[str] = []
    for period in closing_periods(day):
        rows = period_rows(store.events, group_id, period)
        if not rows:
            continue
        before = periods.previous(period)
        trend = Trend(
            now=total_for(store.events, group_id, period.start, period.end),
            before=total_for(store.events, group_id, before.start, before.end),
        )
        blocks.append(
            render_period(
                period,
                rows,
                trend,
                since=store.events.first_day(group_id),
                podium=period.kind != "week",
            )
        )
    return blocks