feat: add yearly recurrence with leap-day clamp policy (#30)

custom_components/nestquest/recurrence.py

@@ -270,10 +270,9 @@ class ScheduleRule:
                                 "nth_weekday_weekday", "month")
         elif shape is RuleType.MONTHLY_WEEKDAY:
             forbidden_fields = ("weekday_set", "day_of_month", "month")
-        else:  # YEARLY
+        elif shape is RuleType.YEARLY:
             forbidden_fields = (
                 "weekday_set",
-                "day_of_month",
                 "nth_weekday",
                 "nth_weekday_weekday",
             )
@@ -316,6 +315,14 @@ class ScheduleRule:
                 raise RuleValidationError(
                     f"month must be 1..12, got {self.month!r}"
                 )
+            if self.day_of_month is not None and not (
+                _is_plain_int(self.day_of_month)
+                and 1 <= self.day_of_month <= 31
+            ):
+                raise RuleValidationError(
+                    f"day_of_month must be 1..31 for yearly rules, got "
+                    f"{self.day_of_month!r}"
+                )
 
     def to_dict(self) -> dict:
         """Return the lossless dict form (model-side storage shape).
@@ -504,6 +511,31 @@ def _occurs_monthly_weekday(
     return nth_day is not None and target.day == nth_day
 
 
+def _occurs_yearly(rule: ScheduleRule, target: datetime.date) -> bool:
+    """YEARLY evaluation with the documented leap-day clamp policy.
+
+    Policy: in each interval-eligible year, the rule fires on
+    ``day_of_month`` of ``month`` when that day exists.  A YEARLY rule
+    for February 29th fires on FEBRUARY 28TH in a non-leap year (the
+    same clamp-as-month-end policy as MONTHLY_DAY: the annual chore
+    still happens every year, pinned to February's end when its
+    nominal date is absent) rather than silently vanishing.  A YEARLY
+    rule with NO day_of_month fires on the first day of ``month``.
+    The interval anchors on years elapsed from start_date's year.
+    """
+    anchor = _parse_date(rule.start_date)
+    years_elapsed = target.year - anchor.year
+    if years_elapsed % rule.interval != 0:
+        return False
+    if target.month != rule.month:
+        return False
+    if rule.day_of_month is None:
+        # Day-less yearly rules fire on the first of the month.
+        return target.day == 1
+    month_end = _month_end(target.year, target.month)
+    return target.day == min(rule.day_of_month, month_end)
+
+
 def occurs_on(rule: ScheduleRule, target: datetime.date) -> bool:
     """Return True when ``rule`` fires on ``target``.
 
@@ -516,7 +548,7 @@ def occurs_on(rule: ScheduleRule, target: datetime.date) -> bool:
     shape = rule.rule_type
     if shape not in (
         RuleType.DAILY, RuleType.WEEKLY, RuleType.CUSTOM_DAYS,
-        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY,
+        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY, RuleType.YEARLY,
     ):
         raise NotImplementedError(
             f"occurs_on for {shape} lands with its own engine task "
@@ -531,6 +563,8 @@ def occurs_on(rule: ScheduleRule, target: datetime.date) -> bool:
         return _occurs_monthly_day(rule, target)
     if shape is RuleType.MONTHLY_WEEKDAY:
         return _occurs_monthly_weekday(rule, target)
+    if shape is RuleType.YEARLY:
+        return _occurs_yearly(rule, target)
     # WEEKLY / CUSTOM_DAYS: whole-week anchoring from start_date, never
     # ISO week numbers (Feature 04/05 guardrail: 53-week years flip ISO
     # parity on January 1st; anchor arithmetic does not).
@@ -556,7 +590,7 @@ def occurrences_between(
     """
     if rule.rule_type not in (
         RuleType.DAILY, RuleType.WEEKLY, RuleType.CUSTOM_DAYS,
-        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY,
+        RuleType.MONTHLY_DAY, RuleType.MONTHLY_WEEKDAY, RuleType.YEARLY,
     ):
         raise NotImplementedError(
             f"occurrences_between for {rule.rule_type} lands with its own "

tests/test_recurrence_daily.py

@@ -213,15 +213,32 @@ def test_occurrences_between_year_boundary() -> None:
 # ---------------------------------------------------------------------------
 
 
-def test_occurs_on_rejects_unimplemented_shapes_loudly() -> None:
+def test_occurs_on_rejects_unknown_shapes_loudly() -> None:
-    """Monthly/yearly land with their own engine tasks; a loud
+    """All six model shapes are implemented; a shape added to the model
-    NotImplementedError beats a silent wrong answer."""
+    without an engine arm must raise a loud NotImplementedError rather
-    rule = ScheduleRule(
+    than a silent wrong answer.  Forged via a private enum extension
-        rule_type=RuleType.YEARLY, month=6,
+    because ScheduleRule validation rejects unknown names."""
-        start_date="2026-09-01",
+    import enum as enum_module
+    from custom_components.nestquest import recurrence as mod
+
+    ForgedType = enum_module.Enum(
+        "ForgedType", {"UNKNOWN_SHAPE": "unknown_shape"}
     )
+    forged_rule = ScheduleRule.__new__(ScheduleRule)
+    object.__setattr__(forged_rule, "rule_type", ForgedType.UNKNOWN_SHAPE)
+    object.__setattr__(forged_rule, "interval", 1)
+    object.__setattr__(forged_rule, "weekday_set", None)
+    object.__setattr__(forged_rule, "day_of_month", None)
+    object.__setattr__(forged_rule, "nth_weekday", None)
+    object.__setattr__(forged_rule, "nth_weekday_weekday", None)
+    object.__setattr__(forged_rule, "month", None)
+    object.__setattr__(forged_rule, "start_date", "2026-09-01")
+    object.__setattr__(forged_rule, "end_date", None)
+    for day in ("2026-08-31", "2026-09-15", "2026-12-31"):
         with pytest.raises(NotImplementedError):
-        occurs_on(rule, _d("2026-09-15"))
+            occurs_on(forged_rule, _d(day))
+        with pytest.raises(NotImplementedError):
+            occurrences_between(forged_rule, "2026-08-01", "2026-12-31")
 
 def test_interval_7_preserves_weekday_alignment_across_months() -> None:
     """Weekly-by-interval semantics: every firing lands on the SAME
@@ -269,27 +286,4 @@ def test_occurrences_between_year_boundary_interval_2() -> None:
     assert result == ["2026-12-30", "2027-01-01", "2027-01-03"]
 
 
-def test_occurs_on_unimplemented_shape_raises_even_outside_window() -> None:
-    """An unimplemented shape must raise whether the date is inside or
-    outside the window — silent False would hide a missing engine."""
-    rule = ScheduleRule(
-        rule_type=RuleType.YEARLY, month=6,
-        start_date="2026-09-01", end_date="2026-09-10",
-    )
-    # Before start, inside window, after end: all must raise.
-    for day in ("2026-08-31", "2026-09-07", "2026-09-20"):
-        with pytest.raises(NotImplementedError):
-            occurs_on(rule, _d(day))
 
-
-def test_occurrences_between_unimplemented_shape_raises_even_disjoint(
-    tmp_path,
-) -> None:
-    rule = ScheduleRule(
-        rule_type=RuleType.YEARLY, month=6,
-        start_date="2026-09-01"
-    )
-    # A range entirely before the rule's start still raises: the shape
-    # is unimplemented, and silence would hide it.
-    with pytest.raises(NotImplementedError):
-        occurrences_between(rule, "2026-08-01", "2026-08-10")

tests/test_recurrence_model.py

@@ -393,16 +393,21 @@ def test_monthly_day_rejects_month() -> None:
 
 
 def test_yearly_rejects_day_and_nth_fields() -> None:
-    with pytest.raises(RuleValidationError, match="must not set"):
-        ScheduleRule(
-            rule_type=RuleType.YEARLY, month=6, day_of_month=15,
-            start_date="2026-09-01",
-        )
     with pytest.raises(RuleValidationError, match="must not set"):
         ScheduleRule(
             rule_type=RuleType.YEARLY, month=6, nth_weekday=1,
             nth_weekday_weekday=0, start_date="2026-09-01",
         )
+    # YEARLY MAY carry an optional day_of_month (Feb 29 rules need it):
+    rule = ScheduleRule(rule_type=RuleType.YEARLY, month=2,
+                        day_of_month=29, start_date="2026-09-01")
+    assert rule.day_of_month == 29
+    # ...but it is still validated when present.
+    with pytest.raises(RuleValidationError, match="day_of_month"):
+        ScheduleRule(
+            rule_type=RuleType.YEARLY, month=6, day_of_month=32,
+            start_date="2026-09-01",
+        )
 
 
 def test_storage_value_mapping() -> None:

tests/test_recurrence_yearly.py

@@ -0,0 +1,233 @@
+"""Tests for YEARLY recurrence with the leap-day clamp policy."""
+from __future__ import annotations
+
+import datetime
+
+import pytest
+
+from custom_components.nestquest.recurrence import (
+    RuleType,
+    RuleValidationError,
+    ScheduleRule,
+    occurs_on,
+    occurrences_between,
+)
+
+
+def _d(date: str) -> datetime.date:
+    return datetime.date.fromisoformat(date)
+
+
+# ---------------------------------------------------------------------------
+# Nominal-day firings across four consecutive years (incl. leap 2028)
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_june_15_four_consecutive_years() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=15,
+        start_date="2026-06-15",
+    )
+    for year in (2026, 2027, 2028, 2029):
+        assert occurs_on(rule, datetime.date(year, 6, 15)) is True, year
+    assert occurs_on(rule, datetime.date(2026, 6, 14)) is False
+    assert occurs_on(rule, datetime.date(2026, 6, 16)) is False
+    assert occurs_on(rule, datetime.date(2026, 5, 15)) is False
+    assert occurs_on(rule, datetime.date(2026, 7, 15)) is False
+
+
+def test_yearly_feb_15_across_four_years() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=15,
+        start_date="2026-02-15",
+    )
+    # Feb 15 exists every year; the leap day is irrelevant.
+    for year in (2026, 2027, 2028, 2029):
+        assert occurs_on(rule, datetime.date(year, 2, 15)) is True, year
+
+
+def test_yearly_never_fires_before_start() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=15,
+        start_date="2027-06-15",
+    )
+    assert occurs_on(rule, datetime.date(2026, 6, 15)) is False
+    assert occurs_on(rule, datetime.date(2027, 6, 15)) is True
+
+
+def test_yearly_respects_end_date() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=15,
+        start_date="2026-06-15", end_date="2028-06-15",
+    )
+    assert occurs_on(rule, datetime.date(2028, 6, 15)) is True
+    assert occurs_on(rule, datetime.date(2029, 6, 15)) is False
+
+
+# ---------------------------------------------------------------------------
+# Leap-day policy: Feb 29 rule fires Feb 28 in non-leap years
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_feb_29_clamps_to_feb_28_non_leap() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+        start_date="2026-02-28",
+    )
+    # 2026 non-leap: no Feb 29 — the clamp fires Feb 28.
+    assert occurs_on(rule, datetime.date(2026, 2, 28)) is True
+    assert occurs_on(rule, datetime.date(2026, 2, 27)) is False
+    # 2027 non-leap: same clamp.
+    assert occurs_on(rule, datetime.date(2027, 2, 28)) is True
+
+
+def test_yearly_feb_29_fires_feb_29_in_leap_years() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+        start_date="2026-02-28",
+    )
+    # 2028 leap: Feb 29 exists — nominal day.
+    assert occurs_on(rule, datetime.date(2028, 2, 29)) is True
+    assert occurs_on(rule, datetime.date(2028, 2, 28)) is False
+
+
+def test_yearly_feb_29_four_consecutive_years() -> None:
+    """The done-condition's four-year sweep: 2026 (clamp 28), 2027
+    (clamp 28), 2028 (leap: nominal 29), 2029 (clamp 28)."""
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+        start_date="2026-02-28",
+    )
+    assert occurs_on(rule, datetime.date(2026, 2, 28)) is True
+    assert occurs_on(rule, datetime.date(2027, 2, 28)) is True
+    assert occurs_on(rule, datetime.date(2028, 2, 29)) is True
+    assert occurs_on(rule, datetime.date(2029, 2, 28)) is True
+    # No other day in those Februaries fires.
+    for year, non_firing in (
+        (2026, (27,)), (2027, (26, 27)), (2028, (27,)),
+        (2029, (26, 27)),
+    ):
+        for day in non_firing:
+            assert occurs_on(rule, datetime.date(year, 2, day)) is False
+
+
+def test_yearly_feb_30_is_impossible_by_model() -> None:
+    """The model rejects day_of_month 30+ for February? No — 30/31 are
+    accepted (1..31) and clamp to the month end like MONTHLY_DAY."""
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=30,
+        start_date="2027-02-28",
+    )
+    # Non-leap 2027: Feb 28 is the month end — the clamp fires it.
+    assert occurs_on(rule, datetime.date(2027, 2, 28)) is True
+    # Leap 2028: Feb 29 is the month end — clamps there.
+    assert occurs_on(rule, datetime.date(2028, 2, 29)) is True
+    assert occurs_on(rule, datetime.date(2028, 2, 28)) is False
+
+
+# ---------------------------------------------------------------------------
+# Day-less YEARLY rules fire on the first of the month
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_without_day_fires_on_first_of_month() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, start_date="2026-01-01",
+    )
+    assert occurs_on(rule, datetime.date(2026, 6, 1)) is True
+    assert occurs_on(rule, datetime.date(2026, 6, 2)) is False
+    assert occurs_on(rule, datetime.date(2026, 5, 1)) is False
+    assert occurs_on(rule, datetime.date(2027, 6, 1)) is True
+
+
+# ---------------------------------------------------------------------------
+# Interval: every N years
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_interval_2_every_second_year() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=15, interval=2,
+        start_date="2026-06-15",
+    )
+    assert occurs_on(rule, datetime.date(2026, 6, 15)) is True   # y0
+    assert occurs_on(rule, datetime.date(2027, 6, 15)) is False  # y1
+    assert occurs_on(rule, datetime.date(2028, 6, 15)) is True   # y2
+    assert occurs_on(rule, datetime.date(2029, 6, 15)) is False  # y3
+    assert occurs_on(rule, datetime.date(2030, 6, 15)) is True   # y4
+
+
+def test_yearly_interval_2_leap_day_every_second_year() -> None:
+    """A Feb 29 rule at interval 2 anchored 2026 fires in even years:
+    2026 clamps (Feb 28), 2027 skips, 2028 hits the nominal Feb 29."""
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29, interval=2,
+        start_date="2026-02-28",
+    )
+    assert occurs_on(rule, datetime.date(2026, 2, 28)) is True   # y0 clamp
+    assert occurs_on(rule, datetime.date(2027, 2, 28)) is False  # y1
+    assert occurs_on(rule, datetime.date(2028, 2, 29)) is True   # y2 nominal
+    assert occurs_on(rule, datetime.date(2029, 2, 28)) is False  # y3
+    assert occurs_on(rule, datetime.date(2030, 2, 28)) is True   # y4 clamp
+
+
+def test_yearly_interval_3_across_start_year() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=3, day_of_month=10, interval=3,
+        start_date="2026-03-10",
+    )
+    assert occurs_on(rule, datetime.date(2026, 3, 10)) is True
+    assert occurs_on(rule, datetime.date(2027, 3, 10)) is False
+    assert occurs_on(rule, datetime.date(2028, 3, 10)) is False
+    assert occurs_on(rule, datetime.date(2029, 3, 10)) is True
+
+
+# ---------------------------------------------------------------------------
+# occurrences_between
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_occurrences_between_span() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+        start_date="2026-02-28",
+    )
+    result = occurrences_between(rule, "2026-01-01", "2029-12-31")
+    assert result == [
+        "2026-02-28", "2027-02-28", "2028-02-29", "2029-02-28",
+    ]
+
+
+def test_yearly_occurrences_between_disjoint_range() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=15,
+        start_date="2026-06-15",
+    )
+    # The rule only ever fires in June: other months are empty.
+    assert occurrences_between(rule, "2027-01-01", "2027-05-31") == []
+    assert occurrences_between(rule, "2027-07-01", "2027-12-31") == []
+
+
+def test_yearly_occurrences_between_rejects_inverted() -> None:
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=2, day_of_month=29,
+        start_date="2026-02-28",
+    )
+    with pytest.raises(RuleValidationError, match="on or after"):
+        occurrences_between(rule, "2029-01-01", "2026-01-01")
+
+
+# ---------------------------------------------------------------------------
+# Day of month 31 in a 30-day month: clamp consistency with MONTHLY_DAY
+# ---------------------------------------------------------------------------
+
+
+def test_yearly_june_31_clamps_to_june_30() -> None:
+    """June has 30 days: a June 31st yearly rule clamps to June 30."""
+    rule = ScheduleRule(
+        rule_type=RuleType.YEARLY, month=6, day_of_month=31,
+        start_date="2026-06-30",
+    )
+    assert occurs_on(rule, datetime.date(2026, 6, 30)) is True
+    assert occurs_on(rule, datetime.date(2027, 6, 30)) is True
+    assert occurs_on(rule, datetime.date(2026, 6, 29)) is False