fasti 1.0.0

data/lib/fasti/calendar.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "date"
+require "holidays"
+
+module Fasti
+  # Represents a calendar for a specific month and year with configurable start of week.
+  #
+  # This class provides calendar structure functionality including calendar grid generation,
+  # day calculations, and formatting support. It handles different week start preferences
+  # (Sunday vs Monday) and integrates with country-specific holiday detection via the holidays gem.
+  #
+  # @example Creating a calendar for January 2024
+  #   calendar = Calendar.new(2024, 1, country: :jp, start_of_week: :sunday)
+  #   calendar.days_in_month  #=> 31
+  #   calendar.month_year_header  #=> "January 2024"
+  #
+  # @example Getting calendar grid for display
+  #   grid = calendar.calendar_grid
+  #   # Returns: [[nil, 1, 2, 3, 4, 5, 6], [7, 8, 9, ...], ...]
+  #
+  # @example Working with different week starts
+  #   sunday_calendar = Calendar.new(2024, 1, country: :us, start_of_week: :sunday)
+  #   monday_calendar = Calendar.new(2024, 1, country: :jp, start_of_week: :monday)
+  class Calendar
+    # @return [Integer] The year of the calendar
+    # @return [Integer] The month of the calendar (1-12)
+    # @return [Symbol] The start of week preference (:sunday, :monday, :tuesday, etc.)
+    # @return [Symbol] The country code for holiday context
+    attr_reader :year, :month, :start_of_week, :country
+
+    # Full weekday names for internal reference (as symbols)
+    WEEK_DAYS = %i[sunday monday tuesday wednesday thursday friday saturday].freeze
+    private_constant :WEEK_DAYS
+
+    # Abbreviated day names for calendar headers
+    DAY_ABBREVS = %w[Su Mo Tu We Th Fr Sa].freeze
+    private_constant :DAY_ABBREVS
+
+    # Creates a new calendar instance.
+    #
+    # @param year [Integer] The year (must be positive)
+    # @param month [Integer] The month (1-12)
+    # @param country [Symbol] Country code for holiday context (e.g., :jp, :us)
+    # @param start_of_week [Symbol] Week start preference (:sunday, :monday, :tuesday, etc.)
+    # @raise [ArgumentError] If parameters are invalid
+    #
+    # @example Standard calendar
+    #   Calendar.new(2024, 6, country: :jp)
+    #
+    # @example Monday-start calendar
+    #   Calendar.new(2024, 6, country: :us, start_of_week: :monday)
+    def initialize(year, month, country:, start_of_week: :sunday)
+      @year = year
+      @month = month
+      @start_of_week = start_of_week.to_sym
+      @country = country
+      @holidays_for_month = nil
+      @calendar_transition = CalendarTransition.new(@country)
+
+      validate_inputs
+    end
+
+    # Returns the number of days in the calendar month.
+    #
+    # @return [Integer] Number of days in the month (28-31)
+    #
+    # @example
+    #   Calendar.new(2024, 2, country: :jp).days_in_month  #=> 29 (leap year)
+    #   Calendar.new(2023, 2, country: :jp).days_in_month  #=> 28
+    def days_in_month
+      Date.new(year, month, -1).day
+    end
+
+    # Returns the first day of the calendar month.
+    #
+    # @return [Date] The first day of the month
+    #
+    # @example
+    #   Calendar.new(2024, 6, country: :jp).first_day_of_month
+    #   #=> #<Date: 2024-06-01>
+    def first_day_of_month
+      @calendar_transition.create_date(year, month, 1)
+    rescue ArgumentError
+      # If day 1 is in a gap (very rare), try day 2, then 3, etc.
+      (2..31).each do |day|
+        return @calendar_transition.create_date(year, month, day)
+      rescue ArgumentError
+        next
+      end
+      # Fallback to standard Date if all fails
+      Date.new(year, month, 1)
+    end
+
+    # Returns the last day of the calendar month.
+    #
+    # @return [Date] The last day of the month
+    #
+    # @example
+    #   Calendar.new(2024, 6, country: :jp).last_day_of_month
+    #   #=> #<Date: 2024-06-30>
+    def last_day_of_month
+      # Start from the theoretical last day and work backwards
+      max_days = Date.new(year, month, -1).day
+      max_days.downto(1).each do |day|
+        return @calendar_transition.create_date(year, month, day)
+      rescue ArgumentError
+        next
+      end
+      # Fallback to standard Date if all fails
+      Date.new(year, month, -1)
+    end
+
+    # Returns the day of the week for the first day of the month.
+    #
+    # @return [Integer] Day of week (0=Sunday, 1=Monday, ..., 6=Saturday)
+    #
+    # @example
+    #   calendar = Calendar.new(2024, 6, country: :jp)
+    #   calendar.first_day_wday  #=> 6 (if June 1st, 2024 is Saturday)
+    def first_day_wday
+      first_day_of_month.wday
+    end
+
+    # Generates a 2D grid representing the calendar layout.
+    #
+    # The grid is an array of weeks (rows), where each week is an array of 7 days.
+    # Days are represented as integers (1-31) or nil for empty cells.
+    # The grid respects the start_of_week preference.
+    #
+    # @return [Array<Array<Integer, nil>>] 2D array of calendar days
+    #
+    # @example Sunday-start June 2024
+    #   calendar = Calendar.new(2024, 6, country: :jp, start_of_week: :sunday)
+    #   grid = calendar.calendar_grid
+    #   # Returns: [[nil, nil, nil, nil, nil, nil, 1],
+    #   #           [2, 3, 4, 5, 6, 7, 8], ...]
+    def calendar_grid
+      grid = []
+      current_row = []
+
+      # Add leading empty cells for days before month starts
+      leading_empty_days.times do
+        current_row << nil
+      end
+
+      # Add only existing days (skip gap days) for continuous display
+      (1..days_in_month).each do |day|
+        # Only add days that actually exist (not in transition gaps)
+        next unless to_date(day)
+
+        current_row << day
+
+        # Start new row on end of week
+        if current_row.length == 7
+          grid << current_row
+          current_row = []
+        end
+        # Skip gap days completely - they don't take up space in the grid
+      end
+
+      # Add trailing empty cells and final row if needed
+      if current_row.any?
+        current_row << nil while current_row.length < 7
+        grid << current_row
+      end
+
+      grid
+    end
+
+    # Calculates the number of empty cells needed before the first day.
+    #
+    # This accounts for the start_of_week preference to properly align
+    # the first day of the month in the calendar grid.
+    #
+    # @return [Integer] Number of empty cells (0-6)
+    #
+    # @example
+    #   # If June 1st, 2024 falls on Saturday and we start weeks on Sunday:
+    #   calendar = Calendar.new(2024, 6, country: :jp, start_of_week: :sunday)
+    #   calendar.leading_empty_days  #=> 6
+    def leading_empty_days
+      # Calculate offset based on start of week preference
+      start_wday = WEEK_DAYS.index(start_of_week) || 0
+
+      (first_day_wday - start_wday) % 7
+    end
+
+    # Returns day abbreviations arranged according to start_of_week preference.
+    #
+    # @return [Array<String>] Array of day abbreviations (Su, Mo, Tu, etc.)
+    #
+    # @example Sunday start
+    #   Calendar.new(2024, 6, country: :jp, start_of_week: :sunday).day_headers
+    #   #=> ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]
+    #
+    # @example Monday start
+    #   Calendar.new(2024, 6, country: :jp, start_of_week: :monday).day_headers
+    #   #=> ["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"]
+    #
+    # @example Wednesday start
+    #   Calendar.new(2024, 6, country: :jp, start_of_week: :wednesday).day_headers
+    #   #=> ["We", "Th", "Fr", "Sa", "Su", "Mo", "Tu"]
+    def day_headers
+      # Rotate headers based on start of week
+      start_wday = WEEK_DAYS.index(start_of_week) || 0
+
+      DAY_ABBREVS.rotate(start_wday)
+    end
+
+    # Returns a formatted month and year header string.
+    #
+    # @return [String] Formatted month and year (e.g., "June 2024")
+    #
+    # @example
+    #   Calendar.new(2024, 6, country: :jp).month_year_header  #=> "June 2024"
+    #   Calendar.new(2024, 12, country: :jp).month_year_header #=> "December 2024"
+    def month_year_header
+      date = first_day_of_month
+      date.strftime("%B %Y")
+    end
+
+    # Converts a day number to a Date object for this calendar's month/year.
+    #
+    # @param day [Integer, nil] Day of the month (1-31) or nil
+    # @return [Date, nil] Date object for the specified day, or nil if day is nil
+    #
+    # @example
+    #   calendar = Calendar.new(2024, 6, country: :jp)
+    #   calendar.to_date(15)  #=> #<Date: 2024-06-15>
+    #   calendar.to_date(nil) #=> nil
+    def to_date(day)
+      return nil unless day
+      return nil unless (1..days_in_month).cover?(day)
+
+      begin
+        @calendar_transition.create_date(year, month, day)
+      rescue ArgumentError
+        # Date falls in calendar transition gap (non-existent)
+        nil
+      end
+    end
+
+    # Checks if a specific day in this calendar month is a holiday.
+    #
+    # @param day [Integer, nil] Day of the month (1-31) or nil
+    # @return [Boolean] true if the day is a holiday, false otherwise
+    #
+    # @example
+    #   calendar = Calendar.new(2024, 1, country: :jp)
+    #   calendar.holiday?(1)   #=> true (New Year's Day in Japan)
+    #   calendar.holiday?(15)  #=> false (regular day)
+    #   calendar.holiday?(nil) #=> false
+    def holiday?(day)
+      date = to_date(day)
+      return false unless date
+
+      holidays_for_month.key?(date)
+    end
+
+    # Returns a hash of holidays for the current month, keyed by date
+    #
+    # @return [Hash<Date, Hash>] Hash mapping holiday dates to holiday information
+    private def holidays_for_month
+      @holidays_for_month ||= begin
+        # Use standard Date creation for holidays lookup to avoid recursion
+        start_date = Date.new(year, month, 1)
+        end_date = Date.new(year, month, -1)
+
+        begin
+          holidays = Holidays.between(start_date, end_date, country)
+          holidays.each_with_object({}) {|holiday, hash| hash[holiday[:date]] = holiday }
+        rescue Holidays::InvalidRegion
+          warn "Warning: Unknown country code '#{country}' for holiday detection"
+          {}
+        rescue => e
+          warn "Warning: Holiday detection failed: #{e.message}"
+          {}
+        end
+      end
+    end
+
+    private def validate_inputs
+      raise ArgumentError, "Invalid year: #{year}" unless year.is_a?(Integer) && year.positive?
+      raise ArgumentError, "Invalid month: #{month}" unless (1..12).cover?(month)
+
+      return if WEEK_DAYS.include?(start_of_week)
+
+      raise ArgumentError, "Invalid start_of_week: #{start_of_week}. Must be one of: #{WEEK_DAYS.join(", ")}"
+    end
+  end
+end

data/lib/fasti/calendar_transition.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Fasti
+  # Manages Julian to Gregorian calendar transitions for a specific country.
+  #
+  # This class provides country-specific calendar transition data and validation
+  # methods to handle historical calendar reforms. It uses Julian Day Numbers (JDN)
+  # for precise date calculations and gap management during transition periods.
+  #
+  # @example Basic usage
+  #   transition = CalendarTransition.new(:gb)
+  #   transition.gregorian_start_jdn  #=> 2361222
+  #   transition.valid_date?(Date.new(1752, 9, 10))  #=> false (in gap)
+  #
+  # @example Date creation with country-specific transitions
+  #   gb = CalendarTransition.new(:gb)
+  #   gb.create_date(1752, 9, 2)   #=> Date object with British transition
+  #   it = CalendarTransition.new(:it)
+  #   it.create_date(1582, 10, 4)  #=> Date object with Italian transition
+  class CalendarTransition
+    # Calendar transition data mapping countries to their Gregorian adoption dates.
+    #
+    # Each entry contains the Julian Day Number when the country switched to
+    # the Gregorian calendar. This corresponds to Ruby's Date class constants.
+    #
+    # Key transitions:
+    # - Italy (1582): October 4 (Julian) → October 15 (Gregorian) - 10 day gap
+    # - Great Britain (1752): September 2 (Julian) → September 14 (Gregorian) - 11 day gap
+    # - Russia (1918): January 31 (Julian) → February 14 (Gregorian) - 13 day gap
+    # - Greece (1923): February 15 (Julian) → March 1 (Gregorian) - 13 day gap
+    TRANSITIONS = {
+      # Italy - October 15, 1582 (Gregorian start)
+      it: Date::ITALY, # 2299161
+
+      # Great Britain - September 14, 1752 (Gregorian start)
+      gb: Date::ENGLAND, # 2361222
+
+      # Common countries using Italian transition (Catholic countries)
+      es: Date::ITALY,     # Spain - same as Italy (1582-10-15)
+      fr: 2_299_227,       # France - 1582-12-20
+      pt: Date::ITALY,     # Portugal - same as Italy (1582-10-15)
+      pl: Date::ITALY,     # Poland - same as Italy (1582-10-15)
+      at: Date::ITALY,     # Austria - same as Italy (1582-10-15)
+
+      # Countries using British transition (British influence)
+      us: Date::ENGLAND,   # United States - followed British calendar
+      ca: Date::ENGLAND,   # Canada - followed British calendar
+      au: Date::ENGLAND,   # Australia - followed British calendar
+      nz: Date::ENGLAND,   # New Zealand - followed British calendar
+      in: Date::ENGLAND,   # India - under British rule
+
+      # Germany (complex - varied by region, using common date)
+      de: Date::ITALY, # Most German states adopted in 1582-1584
+
+      # Nordic countries (varied transitions)
+      se: 2_361_391,         # Sweden - March 1, 1753 (complex gradual transition)
+      dk: 2_342_032,         # Denmark - March 1, 1700
+      no: 2_342_032,         # Norway - same as Denmark (March 1, 1700)
+
+      # Eastern European countries (much later adoption)
+      ru: 2_421_639,         # Russia - February 14, 1918
+      gr: 2_423_410,         # Greece - March 1, 1923
+
+      # Netherlands (complex regional adoption - using latest Protestant adoption)
+      nl: 2_342_164, # Netherlands - July 12, 1700 (Gelderland, last province)
+
+      # Additional European countries from historical table
+      be: 2_299_245,         # Belgium (Spanish Netherlands) - January 6, 1583
+      ch: 2_342_150,         # Switzerland (Protestant cantons) - January 23, 1700
+      bg: 2_421_344,         # Bulgaria - April 14, 1916
+      ro: 2_421_972,         # Romania - April 14, 1919
+      rs: 2_421_972,         # Serbia (Yugoslavia) - April 14, 1919
+      hr: 2_421_972,         # Croatia (Yugoslavia) - April 14, 1919
+      si: 2_421_972,         # Slovenia (Yugoslavia) - April 14, 1919
+      tr: 2_424_858,         # Turkey (civil calendar) - January 1, 1927
+
+      # The following countries never used Julian calendar before Gregorian adoption
+      # Use proleptic Gregorian calendar (Date::GREGORIAN) for computational consistency
+
+      # Recent adopters from lunar calendars
+      sa: Date::GREGORIAN, # Saudi Arabia - adopted 2016-10-01 (from Islamic/Hijri calendar)
+
+      # Asian countries: transitioned from lunisolar calendars
+      jp: Date::GREGORIAN,  # Japan adopted Gregorian calendar on 1873-01-01 (Meiji 6)
+      cn: Date::GREGORIAN,  # China adopted Gregorian calendar on 1912-01-01 (Republic of China establishment)
+      tw: Date::GREGORIAN,  # Taiwan (same historical root as mainland China)
+      kr: Date::GREGORIAN,  # Korea adopted Gregorian calendar on 1896-01-01 (Korean Empire, Geonyang 1)
+      vn: Date::GREGORIAN,  # Vietnam adopted Gregorian calendar in 1967
+      th: Date::GREGORIAN   # Thailand adopted Gregorian calendar on 1888-01-01 (Rattanakosin 107)
+    }.freeze
+    private_constant :TRANSITIONS
+
+    # Default transition for countries not explicitly listed
+    DEFAULT_TRANSITION = Date::ITALY
+    private_constant :DEFAULT_TRANSITION
+
+    # Returns list of supported countries with transition dates.
+    #
+    # @return [Array<Symbol>] List of supported country codes
+    def self.supported_countries
+      TRANSITIONS.keys.sort
+    end
+
+    # Creates a new CalendarTransition instance for the specified country.
+    #
+    # @param country [Symbol] Country code (e.g., :gb, :us, :it)
+    def initialize(country)
+      @country = country
+      @transition_jdn = TRANSITIONS[@country] || DEFAULT_TRANSITION
+    end
+
+    # Returns the country code for this transition.
+    #
+    # @return [Symbol] Country code
+    attr_reader :country
+
+    # Returns the Julian Day Number when this country adopted the Gregorian calendar.
+    #
+    # @return [Integer] Julian Day Number of Gregorian calendar adoption
+    #
+    # @example
+    #   gb = CalendarTransition.new(:gb)
+    #   gb.gregorian_start_jdn  #=> 2361222
+    #
+    #   it = CalendarTransition.new(:it)
+    #   it.gregorian_start_jdn  #=> 2299161
+    #
+    #   unknown = CalendarTransition.new(:unknown)
+    #   unknown.gregorian_start_jdn  #=> 2299161 (default)
+    def gregorian_start_jdn
+      @transition_jdn
+    end
+
+    # Creates a Date object using the appropriate calendar system for this country.
+    #
+    # This method automatically selects Julian or Gregorian calendar based on
+    # the date and country's transition point, ensuring appropriate calendar
+    # date representation.
+    #
+    # @param year [Integer] Year
+    # @param month [Integer] Month (1-12)
+    # @param day [Integer] Day of month
+    # @return [Date] Date object with appropriate calendar system
+    # @raise [ArgumentError] If the date falls in the transition gap (non-existent)
+    #
+    # @example
+    #   gb = CalendarTransition.new(:gb)
+    #   # Before British transition - uses Julian
+    #   gb.create_date(1752, 9, 2)
+    #
+    #   # After British transition - uses Gregorian
+    #   gb.create_date(1752, 9, 14)
+    #
+    #   # In gap - raises ArgumentError
+    #   gb.create_date(1752, 9, 10)  # => ArgumentError
+    def create_date(year, month, day)
+      # Try creating the date with Gregorian first (most common case)
+      gregorian_date = Date.new(year, month, day, Date::GREGORIAN)
+
+      if gregorian_date.jd >= @transition_jdn
+        # Date is on or after transition - use Gregorian
+        gregorian_date
+      else
+        # Date is before transition - use Julian
+        julian_date = Date.new(year, month, day, Date::JULIAN)
+
+        # Check if this date would fall in the gap
+        if julian_date.jd >= @transition_jdn
+          raise ArgumentError,
+            "Date #{year}-#{month.to_s.rjust(2, "0")}-#{day.to_s.rjust(2, "0")} " \
+            "does not exist in #{@country.upcase} due to calendar transition"
+        end
+
+        julian_date
+      end
+    end
+
+    # Checks if a date exists in this country's calendar system.
+    #
+    # During calendar transitions, certain dates were skipped and never existed.
+    # This method validates whether a specific date is valid for this country.
+    #
+    # @param date [Date] Date to validate
+    # @return [Boolean] true if date exists, false if it falls in transition gap
+    #
+    # @example
+    #   gb = CalendarTransition.new(:gb)
+    #   date1 = Date.new(1752, 9, 10)  # In British gap
+    #   gb.valid_date?(date1)  #=> false
+    #
+    #   date2 = Date.new(1752, 9, 2)   # Before British gap
+    #   gb.valid_date?(date2)  #=> true
+    def valid_date?(date)
+      # If we're dealing with the default transition (Italy), Ruby handles it correctly
+      return true if @transition_jdn == DEFAULT_TRANSITION && date.jd != @transition_jdn - 1
+
+      # For other countries, check if the date falls in a gap
+      # We need to check both Julian and Gregorian representations
+      begin
+        julian_version = Date.new(date.year, date.month, date.day, Date::JULIAN)
+        gregorian_version = Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+
+        # If both versions have the same JDN, there's no ambiguity
+        return true if julian_version.jd == gregorian_version.jd
+
+        # Check if either version is valid for this country
+        julian_valid = julian_version.jd < @transition_jdn
+        gregorian_valid = gregorian_version.jd >= @transition_jdn
+
+        julian_valid || gregorian_valid
+      rescue ArgumentError
+        # Invalid date in both calendar systems
+        false
+      end
+    end
+
+    # Returns information about this country's calendar transition.
+    #
+    # @return [Hash] Transition information including JDN and gap details
+    #
+    # @example
+    #   gb = CalendarTransition.new(:gb)
+    #   gb.transition_info
+    #   #=> {
+    #   #     country: :gb,
+    #   #     gregorian_start_jdn: 2361222,
+    #   #     gregorian_start_date: #<Date: 1752-09-14>,
+    #   #     julian_end_date: #<Date: 1752-09-02>,
+    #   #     gap_days: 11
+    #   #   }
+    def transition_info
+      # Use explicit calendar system to avoid implicit Italian transition
+      gregorian_start = Date.jd(@transition_jdn, Date::GREGORIAN)
+      julian_end = Date.jd(@transition_jdn - 1, Date::JULIAN)
+
+      # Calculate actual gap in calendar dates, not just JDN difference
+      # For example: Oct 4 (Julian) -> Oct 15 (Gregorian) has 10 gap days (5-14)
+      if @transition_jdn == DEFAULT_TRANSITION
+        # For Italy, Ruby's Date class already handles the gap
+        gap_days = 10 # Known historical gap for Italy
+      else
+        # For other countries, calculate based on calendar date differences
+        # The gap is the difference between the date numbers minus 1
+        gap_days = gregorian_start.day - julian_end.day - 1
+
+        # Handle cross-month transitions (like Denmark Dec 21 -> Jan 1)
+        if gap_days < 0
+          # When crossing months, need to account for days in the previous month
+          # This is a simplified calculation - may need refinement for complex cases
+          prev_month_days = Date.new(julian_end.year, julian_end.month, -1, Date::JULIAN).day
+          gap_days = (prev_month_days - julian_end.day) + gregorian_start.day - 1
+        end
+      end
+
+      {
+        country: @country,
+        gregorian_start_jdn: @transition_jdn,
+        gregorian_start_date: gregorian_start,
+        julian_end_date: julian_end,
+        gap_days:
+      }
+    end
+  end
+end