ADR-003: Date Range Architecture for AWS Cost Explorer Integration¶

TimePeriod = {
    'Start': '2025-12-01',  # INCLUSIVE
    'End': '2026-01-01'      # EXCLUSIVE (queries Dec 1-31)
}

# Lines 595-603
if month:
    year, mon = map(int, month.split("-"))
    start_date = date(year, mon, 1)
    # AWS Cost Explorer end date is EXCLUSIVE - use first day of next month
    if mon == 12:
        end_date = date(year + 1, 1, 1)  # Jan 1 (exclusive) = Dec 31 (inclusive)
    else:
        end_date = date(year, mon + 1, 1)  # Next month's first day (exclusive)

# Lines 375-383
if month:
    year, mon = map(int, month.split("-"))
    start_date = date(year, mon, 1)
    # Calculate last day of month (end_date is inclusive, +1 added later for API)
    if mon == 12:
        end_date = date(year + 1, 1, 1) - timedelta(days=1)  # Dec 31 (INCLUSIVE)
    else:
        end_date = date(year, mon + 1, 1) - timedelta(days=1)  # Last day (INCLUSIVE)

# Lines 422-423
end_str = (end_date + timedelta(days=1)).isoformat()  # CE end date is exclusive

# src/runbooks/finops/date_utils.py
from datetime import date, datetime, timezone, timedelta
from typing import Tuple, NamedTuple

class DateRange(NamedTuple):
    """Immutable date range for AWS Cost Explorer API."""
    start: date  # Inclusive
    end: date    # EXCLUSIVE (AWS API semantics)
    days: int    # Number of days in range

class DateRangeCalculator:
    """
    Centralized date range calculation for AWS Cost Explorer integration.

    Design Principles:
    1. UTC-first: All calculations use UTC timezone
    2. Exclusive end dates: Match AWS API semantics
    3. Immutable: Returns NamedTuple (no state mutation)
    4. Test coverage: 100% for all edge cases
    """

    @staticmethod
    def utc_today() -> date:
        """Get current date in UTC (avoids timezone off-by-one errors)."""
        return datetime.now(timezone.utc).date()

    @staticmethod
    def month_range(month: str) -> DateRange:
        """
        Calculate date range for specific month (YYYY-MM format).

        Args:
            month: Month in YYYY-MM format (e.g., "2025-12")

        Returns:
            DateRange with exclusive end date

        Examples:
            >>> DateRangeCalculator.month_range("2025-12")
            DateRange(start=date(2025, 12, 1), end=date(2026, 1, 1), days=31)

            >>> DateRangeCalculator.month_range("2024-02")  # Leap year
            DateRange(start=date(2024, 2, 1), end=date(2024, 3, 1), days=29)
        """
        year, mon = map(int, month.split("-"))
        start_date = date(year, mon, 1)

        # Calculate exclusive end date (first day of next month)
        if mon == 12:
            end_date = date(year + 1, 1, 1)
        else:
            end_date = date(year, mon + 1, 1)

        days = (end_date - start_date).days
        return DateRange(start=start_date, end=end_date, days=days)

    @staticmethod
    def previous_month_range(current_range: DateRange) -> DateRange:
        """
        Calculate previous month range for MoM comparison.

        Args:
            current_range: Current month's DateRange

        Returns:
            Previous month's DateRange with same day-of-month logic

        Examples:
            >>> current = DateRangeCalculator.month_range("2026-01")
            >>> DateRangeCalculator.previous_month_range(current)
            DateRange(start=date(2025, 12, 1), end=date(2026, 1, 1), days=31)
        """
        start = current_range.start

        # Handle January → December transition
        if start.month == 1:
            prev_start = date(start.year - 1, 12, 1)
            prev_end = date(start.year, 1, 1)
        else:
            prev_start = date(start.year, start.month - 1, 1)
            prev_end = start

        days = (prev_end - prev_start).days
        return DateRange(start=prev_start, end=prev_end, days=days)

    @staticmethod
    def format_for_cost_explorer(range: DateRange) -> Tuple[str, str]:
        """
        Format DateRange for AWS Cost Explorer API.

        Args:
            range: DateRange with exclusive end date

        Returns:
            Tuple of (start_str, end_str) in ISO format

        Examples:
            >>> range = DateRangeCalculator.month_range("2025-12")
            >>> DateRangeCalculator.format_for_cost_explorer(range)
            ('2025-12-01', '2026-01-01')
        """
        return (range.start.isoformat(), range.end.isoformat())

# tests/finops/test_date_range_calculator.py
import pytest
from datetime import date, timezone
from runbooks.finops.date_utils import DateRangeCalculator, DateRange

class TestMonthRangeCalculation:
    """Test month_range() for all edge cases."""

    @pytest.mark.parametrize("month,expected_start,expected_end,expected_days", [
        # Regular months
        ("2025-01", date(2025, 1, 1), date(2025, 2, 1), 31),
        ("2025-04", date(2025, 4, 1), date(2025, 5, 1), 30),
        ("2025-12", date(2025, 12, 1), date(2026, 1, 1), 31),  # Year boundary

        # February (leap year vs non-leap)
        ("2024-02", date(2024, 2, 1), date(2024, 3, 1), 29),  # Leap year
        ("2025-02", date(2025, 2, 1), date(2025, 3, 1), 28),  # Non-leap

        # Edge cases
        ("2000-02", date(2000, 2, 1), date(2000, 3, 1), 29),  # Century leap year
        ("1900-02", date(1900, 2, 1), date(1900, 3, 1), 28),  # Century non-leap
    ])
    def test_month_range_all_months(self, month, expected_start, expected_end, expected_days):
        """Test: month_range() returns correct exclusive end dates."""
        result = DateRangeCalculator.month_range(month)

        assert result.start == expected_start
        assert result.end == expected_end
        assert result.days == expected_days

        # Validate AWS API semantics (end is exclusive)
        assert (result.end - result.start).days == expected_days

    def test_invalid_month_format(self):
        """Test: month_range() raises ValueError for invalid format."""
        with pytest.raises(ValueError):
            DateRangeCalculator.month_range("2025/12")  # Wrong separator

        with pytest.raises(ValueError):
            DateRangeCalculator.month_range("2025-13")  # Invalid month

    def test_previous_month_january_to_december(self):
        """Test: previous_month_range() handles year boundary."""
        current = DateRangeCalculator.month_range("2026-01")
        previous = DateRangeCalculator.previous_month_range(current)

        assert previous.start == date(2025, 12, 1)
        assert previous.end == date(2026, 1, 1)
        assert previous.days == 31

    def test_utc_today_timezone_independence(self):
        """Test: utc_today() returns UTC date regardless of local timezone."""
        # This test will pass in all timezones
        utc_date = DateRangeCalculator.utc_today()

        # Validate it's a date object (not datetime)
        assert isinstance(utc_date, date)

        # Validate it matches UTC timezone
        from datetime import datetime, timezone
        expected = datetime.now(timezone.utc).date()
        assert utc_date == expected

    def test_format_for_cost_explorer(self):
        """Test: format_for_cost_explorer() returns ISO format strings."""
        range = DateRangeCalculator.month_range("2025-12")
        start_str, end_str = DateRangeCalculator.format_for_cost_explorer(range)

        assert start_str == "2025-12-01"
        assert end_str == "2026-01-01"

        # Validate ISO format (YYYY-MM-DD)
        assert len(start_str) == 10
        assert start_str.count("-") == 2

class TestTimezoneEdgeCases:
    """Test timezone-related edge cases."""

    def test_utc_vs_local_timezone_boundary(self):
        """Test: UTC date calculation at timezone boundaries."""
        import os

        # Simulate different timezones (requires TZ environment variable)
        timezones = [
            ("UTC", "Etc/UTC"),
            ("Sydney", "Australia/Sydney"),  # UTC+11
            ("Los Angeles", "America/Los_Angeles"),  # UTC-8
        ]

        for name, tz in timezones:
            # Set timezone
            os.environ['TZ'] = tz

            # Get UTC date
            utc_date = DateRangeCalculator.utc_today()

            # Validate it's consistent across timezones
            from datetime import datetime, timezone as tz_module
            expected = datetime.now(tz_module.utc).date()
            assert utc_date == expected, f"Failed for timezone: {name}"