jw_calendar 0.1.0

data/lib/jw_calendar/conversion/julian_day_number.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Conversion
+    # Integer JDN and exact JD/MJD conversions. A civil date starts at midnight;
+    # its JDN is the integer labelled at the following astronomical noon.
+    module JulianDayNumber
+      module_function
+
+      HALF = Rational(1, 2)
+      MJD_OFFSET = Rational(2_400_001, 1)
+
+      # Return the date's integer JDN.
+      def for(date)
+        date.to_jdn
+      end
+
+      # Convert an integer JDN into a civil date.
+      def to_date(jdn, calendar: :gregorian)
+        CivilDate.from_jdn(jdn, calendar:)
+      end
+
+      # Return exact Julian Date for an explicitly supplied fraction of a day.
+      # Return JD at midnight plus an optional exact fraction of a day.
+      def jd(date, fraction: 0)
+        fraction = rational_fraction!(fraction)
+        raise ArgumentError, "fraction must be in 0...1" unless fraction >= 0 && fraction < 1
+
+        Rational(date.to_jdn, 1) - HALF + fraction
+      end
+
+      # Convert exact JD to [civil_date, fraction_of_day] at midnight boundaries.
+      # Split a JD into a civil date and exact fraction since midnight.
+      def from_jd(value, calendar: :gregorian)
+        jd_value = rational_number!(value)
+        shifted = jd_value + HALF
+        jdn = shifted.floor
+        [to_date(jdn, calendar:), shifted - jdn]
+      end
+
+      # Return MJD at midnight plus an optional exact fraction of a day.
+      def mjd(date, fraction: 0)
+        fraction = rational_fraction!(fraction)
+        raise ArgumentError, "fraction must be in 0...1" unless fraction >= 0 && fraction < 1
+
+        Rational(date.to_jdn, 1) - MJD_OFFSET + fraction
+      end
+
+      # Split an MJD into a civil date and exact fraction since midnight.
+      def from_mjd(value, calendar: :gregorian)
+        mjd_value = rational_number!(value)
+        day_offset = mjd_value.floor
+        fraction = mjd_value - day_offset
+        # MJD 0 is Gregorian 1858-11-17 at midnight (JDN 2,400,001).
+        [to_date(day_offset + 2_400_001, calendar:), fraction]
+      end
+
+      def rational_fraction!(value)
+        raise ArgumentError, "fraction must be Numeric" unless value.is_a?(Numeric)
+
+        value.to_r
+      end
+      private_class_method :rational_fraction!
+
+      def rational_number!(value)
+        raise ArgumentError, "Julian date value must be Numeric" unless value.is_a?(Numeric)
+
+        value.to_r
+      rescue RangeError
+        raise ArgumentError, "Julian date value must be finite"
+      end
+      private_class_method :rational_number!
+    end
+  end
+end

data/lib/jw_calendar/conversion/ordinal_date.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Conversion
+    # Immutable year/day-of-year value, using the selected civil calendar.
+    class OrdinalDate
+      attr_reader :year, :day, :calendar
+
+      # Create a validated year and ordinal day.
+      def initialize(year, day, calendar: :gregorian)
+        unless CivilDate::CALENDARS.include?(calendar)
+          raise InvalidCalendarError, "calendar must be :gregorian or :julian"
+        end
+
+        engine = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+        engine.days_in_year(year)
+        unless day.is_a?(Integer) && day.between?(1, engine.days_in_year(year))
+          raise InvalidDateError, "ordinal day must be in 1..#{engine.days_in_year(year)} for #{year}"
+        end
+
+        @year = year
+        @day = day
+        @calendar = calendar
+        freeze
+      end
+
+      # Convert a CivilDate to its ordinal form.
+      def self.for(date)
+        new(date.year, date.ordinal_day, calendar: date.calendar)
+      end
+
+      # Convert the ordinal value to its calendar date.
+      def to_date
+        jan1 = CivilDate.new(year, 1, 1, calendar:)
+        jan1.add_days(day - 1)
+      end
+
+      def to_s
+        format("%<year>04d-%<day>03d", year:, day:)
+      end
+
+      def ==(other)
+        other.is_a?(OrdinalDate) && [year, day, calendar] == [other.year, other.day, other.calendar]
+      end
+      alias eql? ==
+
+      def hash
+        [year, day, calendar].hash
+      end
+    end
+  end
+end

data/lib/jw_calendar/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  class Error < StandardError; end
+  class InvalidDateError < Error; end
+  class InvalidCalendarError < Error; end
+  class InvalidISOWeekError < Error; end
+  class ReformGapError < Error; end
+end

data/lib/jw_calendar/formatting/iso8601.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Formatting
+    # Strict parsing/formatting helpers for supported extended ISO civil dates.
+    module ISO8601
+      module_function
+
+      def parse_date(value, calendar: :gregorian)
+        CivilDate.parse(value, calendar:)
+      end
+
+      def format_date(date)
+        raise ArgumentError, "date must be a CivilDate" unless date.is_a?(CivilDate)
+
+        date.to_s
+      end
+    end
+  end
+end

data/lib/jw_calendar/grid/cell.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Grid
+    # Immutable cell in a month grid. A nil date represents a blank spillover.
+    class Cell
+      attr_reader :date, :week_index, :column_index
+
+      def initialize(date:, in_current_month:, week_index:, column_index:)
+        @date = date
+        @in_current_month = in_current_month
+        @week_index = week_index
+        @column_index = column_index
+        freeze
+      end
+
+      def in_current_month?
+        @in_current_month
+      end
+
+      def weekday
+        date&.weekday
+      end
+    end
+  end
+end

data/lib/jw_calendar/grid/month_grid.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Grid
+    # Deterministic structured month layout. Weeks may be natural length (4–6)
+    # or fixed to six rows for print and stable UI layouts.
+    class MonthGrid
+      WEEKDAY_STARTS = { monday: 1, sunday: 7 }.freeze
+      attr_reader :year, :month, :week_start, :fixed_weeks, :calendar
+
+      # Build a month grid without producing any HTML or locale-dependent output.
+      def initialize(year:, month:, week_start: :monday, fixed_weeks: nil,
+                     include_adjacent: true, calendar: :gregorian)
+        engine = calendar_engine(calendar)
+        engine.days_in_month(year, month)
+        week_start = normalize_week_start(week_start)
+        validate_fixed_weeks!(fixed_weeks)
+
+        @year = year
+        @month = month
+        @week_start = week_start
+        @fixed_weeks = fixed_weeks
+        @calendar = calendar
+        @include_adjacent = include_adjacent
+        first = CivilDate.new(year, month, 1, calendar:)
+        leading, weeks = layout_dimensions(first, engine, week_start, fixed_weeks)
+        @rows = build_rows(first, leading, weeks)
+        freeze
+      end
+
+      # Return seven-cell rows.
+      attr_reader :rows
+
+      def weeks
+        rows.length
+      end
+
+      def cells
+        rows.flatten.freeze
+      end
+
+      # Return column headings in display order.
+      def day_names
+        names = ISO::WeekDate::WEEKDAY_NAMES
+        Array.new(7) { |index| names[(week_start - 1 + index) % 7] }.freeze
+      end
+
+      def to_a
+        rows.map { |row| row.map { |cell| cell.date&.day } }.freeze
+      end
+
+      # Return a JSON-friendly hash of grid semantics.
+      def to_h
+        {
+          year:, month:, calendar:, week_start:,
+          fixed_weeks:, weekdays: day_names,
+          rows: rows.map do |row|
+            row.map do |cell|
+              { date: cell.date&.to_s, day: cell.date&.day,
+                in_current_month: cell.in_current_month?, weekday: cell.weekday,
+                week_index: cell.week_index, column_index: cell.column_index }
+            end
+          end
+        }
+      end
+
+      private
+
+      def calendar_engine(calendar)
+        return Calendars::Gregorian if calendar == :gregorian
+        return Calendars::Julian if calendar == :julian
+
+        raise InvalidCalendarError, "calendar must be :gregorian or :julian"
+      end
+
+      def normalize_week_start(week_start)
+        return week_start if week_start.is_a?(Integer) && week_start.between?(1, 7)
+
+        normalized = WEEKDAY_STARTS[week_start]
+        raise ArgumentError, "week_start must be :monday, :sunday, or ISO weekday 1..7" unless normalized
+
+        normalized
+      end
+
+      def validate_fixed_weeks!(fixed_weeks)
+        return if fixed_weeks.nil? || [4, 5, 6].include?(fixed_weeks)
+
+        raise ArgumentError, "fixed_weeks must be nil, 4, 5, or 6"
+      end
+
+      def layout_dimensions(first, engine, week_start, fixed_weeks)
+        leading = (first.weekday - week_start) % 7
+        natural_weeks = (leading + engine.days_in_month(year, month) + 6) / 7
+        weeks = fixed_weeks || natural_weeks
+        if weeks < natural_weeks
+          raise ArgumentError, "#{weeks} rows cannot contain all dates for #{year}-#{format('%02d', month)}"
+        end
+
+        [leading, weeks]
+      end
+
+      def build_rows(first, leading, weeks)
+        Array.new(weeks) do |row|
+          Array.new(7) do |column|
+            actual = first.add_days((row * 7) + column - leading)
+            in_month = actual.year == year && actual.month == month && actual.calendar == calendar
+            date = in_month || @include_adjacent ? actual : nil
+            Cell.new(date:, in_current_month: in_month, week_index: row, column_index: column)
+          end.freeze
+        end.freeze
+      end
+    end
+  end
+end

data/lib/jw_calendar/iso/week_date.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module ISO
+    # ISO week date value with Monday=1 through Sunday=7.
+    class WeekDate
+      WEEKDAY_NAMES = %w[Monday Tuesday Wednesday Thursday Friday Saturday Sunday].freeze
+      attr_reader :week_year, :week, :weekday
+
+      # Create a valid ISO week-year, week, and weekday tuple.
+      def initialize(week_year, week, weekday)
+        unless week_year.is_a?(Integer) && week_year.positive?
+          raise InvalidISOWeekError, "ISO week-year must be a positive Integer"
+        end
+        raise InvalidISOWeekError, "ISO weekday must be in 1..7" unless weekday.is_a?(Integer) && weekday.between?(1, 7)
+
+        weeks = self.class.weeks_in_year(week_year)
+        unless week.is_a?(Integer) && week.between?(1, weeks)
+          raise InvalidISOWeekError, "ISO week must be in 1..#{weeks} for #{week_year}"
+        end
+
+        @week_year = week_year
+        @week = week
+        @weekday = weekday
+        freeze
+      end
+
+      # Compute the ISO week date for an absolute civil date.
+      def self.for(date)
+        raise ArgumentError, "date must be a CivilDate" unless date.is_a?(CivilDate)
+
+        weekday = date.weekday
+        # The Thursday determines the ISO week-year, even for Julian labels.
+        thursday = CivilDate.from_jdn(date.to_jdn + 4 - weekday)
+        week_year = thursday.year
+        jan4 = Calendars::Gregorian.to_jdn(week_year, 1, 4)
+        week1_monday = jan4 - (jan4 % 7)
+        week = Arithmetic::FloorDivision.div(date.to_jdn - week1_monday, 7) + 1
+        new(week_year, week, weekday)
+      end
+
+      # Return 52 or 53 according to the ISO week-year rule.
+      def self.weeks_in_year(year)
+        unless year.is_a?(Integer) && year.positive?
+          raise InvalidISOWeekError,
+                "ISO week-year must be a positive Integer"
+        end
+
+        jan1_weekday = (Calendars::Gregorian.to_jdn(year, 1, 1) % 7) + 1
+        return 53 if jan1_weekday == 4 || (jan1_weekday == 3 && Calendars::Gregorian.leap_year?(year))
+
+        52
+      end
+
+      # Convert the ISO tuple to a proleptic Gregorian CivilDate.
+      def to_date
+        jan4 = Calendars::Gregorian.to_jdn(week_year, 1, 4)
+        week1_monday = jan4 - (jan4 % 7)
+        CivilDate.from_jdn(week1_monday + ((week - 1) * 7) + weekday - 1)
+      end
+
+      def to_s
+        format("%<week_year>04d-W%<week>02d-%<weekday>d", week_year:, week:, weekday:)
+      end
+
+      def weekday_name
+        WEEKDAY_NAMES.fetch(weekday - 1)
+      end
+
+      def ==(other)
+        other.is_a?(WeekDate) && [week_year, week, weekday] == [other.week_year, other.week, other.weekday]
+      end
+      alias eql? ==
+
+      def hash
+        [week_year, week, weekday].hash
+      end
+    end
+  end
+end

data/lib/jw_calendar/range/date_range.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  # Lazy inclusive range of dates from one calendar system.
+  class DateRange
+    include Enumerable
+
+    attr_reader :start_date, :end_date
+
+    # Create an inclusive range with matching calendar systems.
+    def initialize(start_date, end_date)
+      unless start_date.is_a?(CivilDate) && end_date.is_a?(CivilDate)
+        raise ArgumentError, "range endpoints must be CivilDate objects"
+      end
+      unless start_date.calendar == end_date.calendar
+        raise InvalidCalendarError, "range endpoints must use the same calendar"
+      end
+      raise ArgumentError, "start_date must not follow end_date" if start_date > end_date
+
+      @start_date = start_date
+      @end_date = end_date
+      freeze
+    end
+
+    # Yield each date without first materializing the range.
+    def each
+      return enum_for(:each) unless block_given?
+
+      offset = 0
+      while offset <= count - 1
+        yield start_date.add_days(offset)
+        offset += 1
+      end
+      self
+    end
+
+    # Number of dates in the inclusive interval.
+    def count
+      start_date.days_until(end_date) + 1
+    end
+    alias size count
+
+    def include?(date)
+      date.is_a?(CivilDate) && date.calendar == start_date.calendar &&
+        date.to_jdn >= start_date.to_jdn && date.to_jdn <= end_date.to_jdn
+    end
+
+    def first(number = nil)
+      return start_date if number.nil?
+      raise ArgumentError, "number must be a non-negative Integer" unless number.is_a?(Integer) && number >= 0
+
+      take(number)
+    end
+
+    def last(number = nil)
+      return end_date if number.nil?
+      raise ArgumentError, "number must be a non-negative Integer" unless number.is_a?(Integer) && number >= 0
+      return [] if number.zero?
+
+      first_index = [count - number, 0].max
+      (first_index...count).map { |offset| start_date.add_days(offset) }
+    end
+
+    def step(days = 1)
+      raise ArgumentError, "step must be a positive Integer" unless days.is_a?(Integer) && days.positive?
+      return enum_for(:step, days) unless block_given?
+
+      offset = 0
+      while offset < count
+        yield start_date.add_days(offset)
+        offset += days
+      end
+      self
+    end
+
+    def weekdays
+      return enum_for(:weekdays) unless block_given?
+
+      each { |date| yield date unless [6, 7].include?(date.weekday) }
+      self
+    end
+  end
+end

data/lib/jw_calendar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  VERSION = "0.1.0"
+end

data/lib/jw_calendar.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "jw_calendar/version"
+require "jw_calendar/errors"
+require "jw_calendar/arithmetic/floor_division"
+require "jw_calendar/calendars/gregorian"
+require "jw_calendar/calendars/julian"
+require "jw_calendar/civil_date"
+require "jw_calendar/conversion/julian_day_number"
+require "jw_calendar/conversion/calendar_converter"
+require "jw_calendar/conversion/ordinal_date"
+require "jw_calendar/iso/week_date"
+require "jw_calendar/calendars/reform_calendar"
+require "jw_calendar/grid/cell"
+require "jw_calendar/grid/month_grid"
+require "jw_calendar/range/date_range"
+require "jw_calendar/boundary/report"
+require "jw_calendar/boundary/analyzer"
+require "jw_calendar/formatting/iso8601"
+
+# Deterministic civil-date arithmetic for Gregorian, Julian, and reform calendars.
+module JWCalendar
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: jw_calendar
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JW Calendar
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A dependency-free civil-calendar engine for Ruby with proleptic Gregorian and Julian arithmetic,
+  Julian Day Number conversions, ISO week and ordinal dates, month grids, reform cutovers, and
+  boundary analysis. Civil dates are kept separate from instants and time zones.
+email: []
+executables:
+- jwcalendar
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- SECURITY.md
+- docs/architecture.md
+- docs/civil-dates.md
+- docs/cli.md
+- docs/correctness.md
+- docs/gregorian.md
+- docs/iso-week.md
+- docs/julian-day-number.md
+- docs/julian.md
+- docs/month-grid.md
+- docs/reform-calendars.md
+- exe/jwcalendar
+- lib/jw_calendar.rb
+- lib/jw_calendar/arithmetic/floor_division.rb
+- lib/jw_calendar/boundary/analyzer.rb
+- lib/jw_calendar/boundary/report.rb
+- lib/jw_calendar/calendars/gregorian.rb
+- lib/jw_calendar/calendars/julian.rb
+- lib/jw_calendar/calendars/reform_calendar.rb
+- lib/jw_calendar/civil_date.rb
+- lib/jw_calendar/cli/runner.rb
+- lib/jw_calendar/conversion/calendar_converter.rb
+- lib/jw_calendar/conversion/julian_day_number.rb
+- lib/jw_calendar/conversion/ordinal_date.rb
+- lib/jw_calendar/errors.rb
+- lib/jw_calendar/formatting/iso8601.rb
+- lib/jw_calendar/grid/cell.rb
+- lib/jw_calendar/grid/month_grid.rb
+- lib/jw_calendar/iso/week_date.rb
+- lib/jw_calendar/range/date_range.rb
+- lib/jw_calendar/version.rb
+homepage: https://jwcalendar.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://jwcalendar.com/
+  source_code_uri: https://github.com/karencohenjw/jw_calendar
+  documentation_uri: https://github.com/karencohenjw/jw_calendar/tree/main/docs
+  changelog_uri: https://github.com/karencohenjw/jw_calendar/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/karencohenjw/jw_calendar/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Deterministic Gregorian, Julian, ISO week-date and calendar-grid utilities
+  for Ruby.
+test_files: []