diet-guard/diet_guard/_budget.py

"""Freely-editable daily calorie budget for diet_guard.

The budget is computed once from biometrics at ``init`` time (via the same
Mifflin-St Jeor formula as before) and written to a plain JSON file in the
XDG data dir, but it is no longer sealed: it can be changed at any time, on
this machine or the phone app, with no special ritual. It syncs like the
food log (see :mod:`diet_guard._sync`), so the same current value is
available on both devices, last-edit-wins.

This is a deliberate design change from the file's previous ``chattr +i``
seal, which existed specifically to make impulsive "make room" edits
require a deliberate root step. That friction is gone by design; nothing in
this module tries to reintroduce it.
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timezone
import json
import logging

from diet_guard._constants import BUDGET_FILE

_logger = logging.getLogger(__name__)

# Schema version stored in the file, so a future format change can be
# detected rather than silently misread. v2 adds the optional body weight
# (``w``) used to derive a protein target; v1 files (budget only) still
# read correctly.
_FILE_VERSION = 2


def _now_local() -> datetime:
    """Return the current time as a timezone-aware local datetime.

    Duplicated from :func:`diet_guard._state.now_local` rather than
    imported: ``_state`` imports :func:`daily_budget` from this module, so
    importing back from ``_state`` here would be circular.
    """
    return datetime.now(tz=timezone.utc).astimezone()


# A medically sane lower bound.  Even an aggressive deficit must not compute
# a starvation-level target, so the value is floored here.
_MIN_SANE_BUDGET = 1200

# Daily protein target for an active adult holding muscle on a deficit, in
# grams per kg of body weight.  Used only to show a target in the dashboard;
# it has no part in the calorie budget maths.
PROTEIN_G_PER_KG = 1.8


class BudgetError(Exception):
    """Base class for all budget-access failures."""


class BudgetNotInitializedError(BudgetError):
    """Raised when no budget has been set yet (``init`` never run)."""

    def __init__(self) -> None:
        """Initialize with a fixed, side-effect-free message."""
        super().__init__("daily budget has not been initialized")


class BudgetFileCorruptError(BudgetError):
    """Raised when the budget file exists but cannot be read or parsed."""

    def __init__(self) -> None:
        """Initialize with a fixed, side-effect-free message."""
        super().__init__("daily budget file is corrupt")


@dataclass(frozen=True)
class Biometrics:
    """Body metrics that feed the Mifflin-St Jeor budget formula.

    Grouped into one value object so the budget calculation stays under the
    repo's five-argument lint ceiling and so the inputs travel together.

    Attributes:
        weight_kg: Body mass in kilograms.
        height_cm: Height in centimetres.
        age_years: Age in years.
        is_male: True for the male BMR constant (+5), False for female (-161).
    """

    weight_kg: float
    height_cm: float
    age_years: float
    is_male: bool


def mifflin_st_jeor_bmr(bio: Biometrics) -> float:
    """Return resting metabolic rate via the Mifflin-St Jeor equation.

    Args:
        bio: The person's body metrics.

    Returns:
        Basal metabolic rate in kcal/day.
    """
    base = 10.0 * bio.weight_kg + 6.25 * bio.height_cm - 5.0 * bio.age_years
    return base + 5.0 if bio.is_male else base - 161.0


def compute_target_budget(
    bio: Biometrics,
    *,
    activity_factor: float,
    deficit_kcal: float,
) -> int:
    """Return the daily kcal target: TDEE minus a deficit, floored for safety.

    TDEE (total daily energy expenditure) is the BMR scaled by an activity
    factor; subtracting a deficit yields a target that drives gradual loss.

    Args:
        bio: The person's body metrics.
        activity_factor: Multiplier for daily activity (e.g. 1.2 sedentary,
            1.375 light, 1.55 moderate, 1.725 very active).
        deficit_kcal: Calories subtracted from TDEE for weight loss.

    Returns:
        The target budget in kcal, never below ``_MIN_SANE_BUDGET``.
    """
    bmr = mifflin_st_jeor_bmr(bio)
    tdee = bmr * activity_factor
    target = round(tdee - deficit_kcal)
    return max(target, _MIN_SANE_BUDGET)


def is_initialized() -> bool:
    """Return True if a budget file exists on disk."""
    return BUDGET_FILE.exists()


def write_budget(value: int, *, weight_kg: float | None = None) -> None:
    """Write ``value`` as the daily kcal budget, plainly (no seal, no signing).

    Stamps a ``t`` edit timestamp on every write (unlike a food-log entry,
    the budget can be edited repeatedly, so :mod:`diet_guard._sync` needs to
    know *when* this write happened to resolve a last-edit-wins merge
    against another device's write).

    Args:
        value: The daily budget in kcal.
        weight_kg: Body weight in kg to store alongside the budget, so a
            protein target can later be derived. Optional; omitting it
            writes a budget-only record that reads back with no protein
            target.
    """
    record: dict[str, object] = {
        "v": _FILE_VERSION,
        "b": int(value),
        "t": _now_local().isoformat(timespec="seconds"),
    }
    if weight_kg is not None:
        record["w"] = round(float(weight_kg), 1)
    write_raw_record(record)


def _read_record() -> dict[str, object]:
    """Read and parse the budget file.

    Returns:
        The parsed record dict (carrying ``b`` and, optionally, ``w``).

    Raises:
        BudgetNotInitializedError: If no budget has been set yet.
        BudgetFileCorruptError: If the file exists but cannot be parsed.
    """
    if not BUDGET_FILE.exists():
        raise BudgetNotInitializedError
    try:
        with BUDGET_FILE.open() as handle:
            record = json.load(handle)
    except (OSError, json.JSONDecodeError) as exc:
        raise BudgetFileCorruptError from exc
    if not isinstance(record, dict):
        raise BudgetFileCorruptError
    return record


def daily_budget() -> int:
    """Return the current daily kcal budget.

    Returns:
        The daily kcal budget.

    Raises:
        BudgetNotInitializedError: If no budget has been set yet.
        BudgetFileCorruptError: If the file exists but cannot be parsed.
    """
    record = _read_record()
    value = record.get("b")
    if isinstance(value, bool) or not isinstance(value, int):
        raise BudgetFileCorruptError
    return value


def budget_weight() -> float | None:
    """Return the body weight stored with the budget, or None if unavailable.

    Returns:
        The stored weight in kg, or None for a pre-v2 (budget-only) record.

    Raises:
        BudgetNotInitializedError: If no budget has been set yet.
        BudgetFileCorruptError: If the file exists but cannot be parsed.
    """
    record = _read_record()
    value = record.get("w")
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        return None
    return float(value)


def protein_target_g() -> float | None:
    """Return the daily protein target in grams, or None if it cannot be derived.

    Derived from the stored body weight at :data:`PROTEIN_G_PER_KG`.  Returns
    None -- rather than raising -- whenever the target is simply unavailable
    (no budget set, a pre-v2 record without weight, or a corrupt file), so
    the dashboard can show calories and quietly omit the protein line.

    Returns:
        The protein target in grams, or None when weight is unknown.
    """
    try:
        weight = budget_weight()
    except BudgetError:
        return None
    if weight is None:
        return None
    return round(weight * PROTEIN_G_PER_KG, 1)


def read_raw_record() -> dict[str, object] | None:
    """Return the on-disk budget record verbatim, or None if unset/corrupt.

    Public, sync-only counterpart to :func:`_read_record`:
    :mod:`diet_guard._sync` must treat "not yet set" and "unreadable" alike
    as "nothing of this device's to contribute to the merge" rather than an
    error, so unlike :func:`daily_budget` this never raises.
    """
    if not BUDGET_FILE.exists():
        return None
    try:
        with BUDGET_FILE.open() as handle:
            record = json.load(handle)
    except (OSError, json.JSONDecodeError):
        return None
    if not isinstance(record, dict):
        return None
    return record


def write_raw_record(record: dict[str, object]) -> None:
    """Persist ``record`` verbatim, overwriting the file on disk.

    Public counterpart to :func:`read_raw_record`, used by both
    :func:`write_budget` and :mod:`diet_guard._sync` (to write back a
    merged record, carrying the winning side's ``t`` edit timestamp).
    """
    BUDGET_FILE.parent.mkdir(parents=True, exist_ok=True)
    with BUDGET_FILE.open("w") as handle:
        json.dump(record, handle)