diet-guard/diet_guard/_gate.py

"""Decision logic for the diet_guard slot-based log-to-unlock gate.

This module is GUI-free and side-effect-free so the lock/no-lock decision can
be verified headlessly: the fullscreen window in ``_gatelock.py`` is only a
thin shell around :func:`gate_is_due` and :func:`due_slots`.  It composes the
pure slot arithmetic in :mod:`diet_guard._slots` with the logged-slot
state in :mod:`diet_guard._state`; ``now`` is injectable so the
time-of-day rules stay deterministically testable.

The gate fires when any *elapsed* meal slot for today carries no logged meal.
Coming home late therefore surfaces several unlogged slots at once -- a single
lock that backfills the whole day before the PC is usable -- while a normal day
prompts one slot at a time, with no separate weekday code path.
"""

from __future__ import annotations

from datetime import datetime, time, timedelta
from typing import TYPE_CHECKING

import freedays
import sickdays

from diet_guard._hold import hold_covers
from diet_guard._meal_schedule_store import current_schedule
from diet_guard._slots import missing_slots, slot_label
from diet_guard._state import (
    now_local,
)
from diet_guard._state_today import (
    logged_slots_today,
)

if TYPE_CHECKING:
    from datetime import date


def due_slots(now: datetime | None = None) -> tuple[int, ...]:
    """Return today's elapsed-but-unlogged meal slots, ascending.

    Args:
        now: Reference time (defaults to the current local time); injectable.

    Returns:
        The slot minutes that still need a meal logged (empty == nothing due).

    Empty on a shared free day or a sick day that does not keep diet, whatever
    the schedule says: the gate stands down, so no lock opens and nothing
    accrues -- unlogged meals leave no debt, and logging a meal still works as
    on any day. A sick day that keeps diet (``sickdays`` keep set) is a normal
    day here: the slots are due and the lock opens. Each pool is
    read from a single local file and never the network, so this cannot hang
    the systemd-fired gate, and an unreadable pool reads as "not free" / "not
    sick" -- the normal rules apply rather than the gate switching itself off.

    A declared hold (:mod:`diet_guard._hold`) is the same stand-down for a
    window: nothing is due while one is active, and a slot whose time falls
    inside a hold is *excused* -- never owed once the hold ends.
    """
    reference = now if now is not None else now_local()
    day = reference.date()
    # A declared hold (``holds``): the PC stays usable, so nothing is due now.
    if hold_covers(reference):
        return ()
    if freedays.is_free_day(day) or sickdays.stands_down(sickdays.LOCKER_DIET, day):
        return ()
    # One schedule for both halves: snapping the log onto a different schedule
    # than the one deriving the due slots would leave a logged meal covering a
    # checkpoint that is not on the list -- and the real one nagging.
    schedule = current_schedule()
    missing = missing_slots(reference, logged_slots_today(schedule), schedule)
    return tuple(slot for slot in missing if not hold_covers(_slot_time(day, slot)))


def _slot_time(day: date, slot: int) -> datetime:
    """Return the naive wall-clock instant of ``slot`` minutes after midnight."""
    return datetime.combine(day, time()) + timedelta(minutes=slot)


def gate_is_due(now: datetime | None = None) -> bool:
    """Return True if the screen should lock until the missing slots are filled.

    Args:
        now: Reference time (defaults to the current local time); injectable.

    Returns:
        True if at least one elapsed slot today is unlogged, else False.
    """
    return bool(due_slots(now))


def gate_message(now: datetime | None = None) -> str:
    """Return the lock-screen reason line listing the slots to backfill.

    Args:
        now: Reference time (defaults to the current local time); injectable.

    Returns:
        A short human-readable explanation of which meals are missing.
    """
    missing = due_slots(now)
    if not missing:
        return "All meals are logged. You're up to date."
    labels = ", ".join(slot_label(slot) for slot in missing)
    if len(missing) == 1:
        return f"Log your {labels} meal to unlock."
    return f"Log your meals for {labels} to unlock."