diff --git a/custom_components/nestquest/recurrence.py b/custom_components/nestquest/recurrence.py index 5a72293..c114568 100644 --- a/custom_components/nestquest/recurrence.py +++ b/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 " diff --git a/tests/test_recurrence_daily.py b/tests/test_recurrence_daily.py index b61fbba..4505d38 100644 --- a/tests/test_recurrence_daily.py +++ b/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: - """Monthly/yearly land with their own engine tasks; a loud - NotImplementedError beats a silent wrong answer.""" - rule = ScheduleRule( - rule_type=RuleType.YEARLY, month=6, - start_date="2026-09-01", +def test_occurs_on_rejects_unknown_shapes_loudly() -> None: + """All six model shapes are implemented; a shape added to the model + without an engine arm must raise a loud NotImplementedError rather + than a silent wrong answer. Forged via a private enum extension + because ScheduleRule validation rejects unknown names.""" + import enum as enum_module + from custom_components.nestquest import recurrence as mod + + ForgedType = enum_module.Enum( + "ForgedType", {"UNKNOWN_SHAPE": "unknown_shape"} ) - with pytest.raises(NotImplementedError): - occurs_on(rule, _d("2026-09-15")) + 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(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") diff --git a/tests/test_recurrence_model.py b/tests/test_recurrence_model.py index 5d0def5..8e12098 100644 --- a/tests/test_recurrence_model.py +++ b/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: diff --git a/tests/test_recurrence_yearly.py b/tests/test_recurrence_yearly.py new file mode 100644 index 0000000..d544f39 --- /dev/null +++ b/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 \ No newline at end of file