♻️ Anchor historical sprint window to current calendar year (#75) (#80)

Follow-up to #79. The 3-year window was anchored to the most recent
year present in the webhook data, so it would drift earlier if the
current year's webhooks were incomplete (a known coverage-gap risk).

Anchor the cutoff to the current calendar year instead: keep conference
years >= current_year - HISTORICAL_YEARS. The month no longer matters,
and the window stays stable even when a year's data is missing.

Adds a testable current_year override and covers both the boundary and
the missing-current-year-data case.

Author: jefftriplett

titowebhooks/tests/test_views.py

@@ -10,7 +10,12 @@
 from django.urls import reverse
 
 from titowebhooks.models import TitoWebhookEvent
-from titowebhooks.views import EVENT_SLUG, JOINER_QUESTION_ID, LEADER_QUESTION_ID
+from titowebhooks.views import (
+    EVENT_SLUG,
+    JOINER_QUESTION_ID,
+    LEADER_QUESTION_ID,
+    _extract_historical_sprints,
+)
 
 TEST_PAYLOAD = {
     "_type": "ticket",
@@ -381,8 +386,8 @@ def test_one_row_per_person_per_year_merges_days(self):
         # Both Thursday (leading) and Friday (joining) captured on one row.
         assert merged_2025.count("Yes") >= 2
 
-    def test_limits_to_most_recent_three_years(self):
-        for year in (2022, 2023, 2024, 2025, 2026):
+    def test_window_anchored_to_current_calendar_year(self):
+        for year in (2021, 2022, 2023, 2024, 2025, 2026):
             self._create_event(
                 _historical_payload(
                     email=f"y{year}@example.com",
@@ -392,11 +397,26 @@ def test_limits_to_most_recent_three_years(self):
                 )
             )
 
-        body = self._download()
+        # current_year - years (3) = 2023, so 2023 and newer are kept regardless of
+        # which year happens to be the most recent one present in the data.
+        rows = _extract_historical_sprints(current_year=2026)
+        years = {r["year"] for r in rows}
+        assert years == {2023, 2024, 2025, 2026}
+
+    def test_window_stable_when_current_year_data_missing(self):
+        # No 2026 webhooks captured (e.g. coverage gap); the window must still be
+        # anchored to the current calendar year, not the newest year in the data.
+        for year in (2022, 2023, 2024):
+            self._create_event(
+                _historical_payload(
+                    email=f"y{year}@example.com",
+                    release_title="Sprint (In Person) - Thursday",
+                    created_at=f"{year}-09-01T10:00:00Z",
+                    year=year,
+                )
+            )
 
-        # Most recent year is 2026, so window is 2024-2026.
-        assert "y2026@example.com" in body
-        assert "y2025@example.com" in body
-        assert "y2024@example.com" in body
-        assert "y2023@example.com" not in body
-        assert "y2022@example.com" not in body
+        rows = _extract_historical_sprints(current_year=2026)
+        years = {r["year"] for r in rows}
+        # Anchored to 2026: cutoff 2023, so 2022 drops even though it is recent in the data.
+        assert years == {2023, 2024}

titowebhooks/views.py

@@ -114,13 +114,19 @@ def _event_year(payload: dict) -> int | None:
     return created_at.year if created_at else None
 
 
-def _extract_historical_sprints(include_online: bool = False, years: int | None = HISTORICAL_YEARS):
+def _extract_historical_sprints(
+    include_online: bool = False, years: int | None = HISTORICAL_YEARS, current_year: int | None = None
+):
     """One row per person per conference year, across all events in the webhook log.
 
     Used by the "Download Historical" export so the sprints team can see who has
     attended in-person sprints over the last few years. Online sprints are excluded
-    unless ``include_online`` is set. ``years`` limits the result to the most recent
-    N conference years present in the data (``None`` keeps every year).
+    unless ``include_online`` is set.
+
+    ``years`` limits the result to conference years on or after ``current_year - years``
+    (``None`` keeps every year). The window is anchored to the calendar year, not to the
+    most recent year present in the data, so it stays stable even if a year's webhooks are
+    incomplete. ``current_year`` defaults to today's year and exists mainly for testing.
     """
     events = TitoWebhookEvent.objects.filter(trigger="ticket.completed")
     # Collect per email+year+release, keeping most recent.
@@ -163,10 +169,14 @@ def _extract_historical_sprints(include_online: bool = False, years: int | None
                 "created_at": created_at,
             }
 
-    # Limit to the most recent N conference years present in the data.
-    if years and by_email_year_release:
-        max_year = max(t["year"] for t in by_email_year_release.values())
-        cutoff = max_year - years + 1
+    # Limit to conference years within the last ``years`` calendar years of the current
+    # year (e.g. 2026 with years=3 -> 2023 and newer). Anchoring to the calendar year
+    # rather than the newest year in the data keeps the window stable when a year's
+    # webhook coverage is incomplete.
+    if years:
+        if current_year is None:
+            current_year = datetime.now(timezone.utc).year
+        cutoff = current_year - years
         by_email_year_release = {k: v for k, v in by_email_year_release.items() if v["year"] >= cutoff}
 
     # Consolidate to one row per person per year.