jw_calendar 0.1.0

data/lib/jw_calendar/boundary/report.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Boundary
+    # Immutable collection of machine-readable boundary events.
+    class Report
+      include Enumerable
+      attr_reader :events
+
+      def initialize(events)
+        @events = events.map(&:freeze).freeze
+        freeze
+      end
+
+      def each(&)
+        events.each(&)
+      end
+
+      def to_a
+        events
+      end
+
+      def to_h
+        { events: }
+      end
+    end
+  end
+end

data/lib/jw_calendar/calendars/gregorian.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Calendars
+    # Proleptic Gregorian arithmetic using an integer Julian Day Number (JDN).
+    # The supported civil year domain begins at 1 CE.
+    module Gregorian
+      module_function
+
+      MONTH_LENGTHS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+
+      # Whether the Gregorian year has 366 days.
+      def leap_year?(year)
+        valid_year!(year)
+        (year % 4).zero? && (!(year % 100).zero? || (year % 400).zero?)
+      end
+
+      # Number of days in the requested Gregorian month.
+      def days_in_month(year, month)
+        valid_year!(year)
+        valid_month!(month)
+        return 29 if month == 2 && leap_year?(year)
+
+        MONTH_LENGTHS.fetch(month - 1)
+      end
+
+      # Number of days in a validated positive Gregorian year.
+      def days_in_year(year)
+        leap_year?(year) ? 366 : 365
+      end
+
+      # Whether the components form a valid Gregorian date.
+      def valid_date?(year, month, day)
+        return false unless year.is_a?(Integer) && year.positive?
+        return false unless month.is_a?(Integer) && month.between?(1, 12)
+        return false unless day.is_a?(Integer) && day.positive?
+
+        day <= days_in_month(year, month)
+      rescue ArgumentError
+        false
+      end
+
+      # Raise {InvalidDateError} unless the components form a valid date.
+      def validate_date!(year, month, day)
+        return true if valid_date?(year, month, day)
+
+        raise InvalidDateError, "invalid Gregorian date: #{format_components(year, month, day)}"
+      end
+
+      # Convert a Gregorian date to its integer JDN at astronomical noon.
+      # Convert Gregorian components to an integer JDN.
+      def to_jdn(year, month, day)
+        validate_date!(year, month, day)
+        a = Arithmetic::FloorDivision.div(14 - month, 12)
+        y = year + 4_800 - a
+        m = month + (12 * a) - 3
+        day + Arithmetic::FloorDivision.div((153 * m) + 2, 5) + (365 * y) +
+          Arithmetic::FloorDivision.div(y, 4) - Arithmetic::FloorDivision.div(y, 100) +
+          Arithmetic::FloorDivision.div(y, 400) - 32_045
+      end
+
+      # Convert an integer JDN to `[year, month, day]` Gregorian components.
+      def from_jdn(jdn)
+        integer_jdn!(jdn)
+        a = jdn + 32_044
+        b = Arithmetic::FloorDivision.div((4 * a) + 3, 146_097)
+        c = a - Arithmetic::FloorDivision.div(146_097 * b, 4)
+        d = Arithmetic::FloorDivision.div((4 * c) + 3, 1_461)
+        e = c - Arithmetic::FloorDivision.div(1_461 * d, 4)
+        m = Arithmetic::FloorDivision.div((5 * e) + 2, 153)
+        day = e - Arithmetic::FloorDivision.div((153 * m) + 2, 5) + 1
+        month = m + 3 - (12 * Arithmetic::FloorDivision.div(m, 10))
+        year = (100 * b) + d - 4_800 + Arithmetic::FloorDivision.div(m, 10)
+        raise InvalidDateError, "JDN is earlier than the supported Gregorian domain" unless year.positive?
+
+        [year, month, day]
+      end
+
+      # Return the one-based ordinal day for a valid Gregorian date.
+      def day_of_year(year, month, day)
+        validate_date!(year, month, day)
+        prior_month_days = (1...month).inject(0) { |total, m| total + days_in_month(year, m) }
+        prior_month_days + day
+      end
+
+      def valid_year!(year)
+        return if year.is_a?(Integer) && year.positive?
+
+        raise ArgumentError,
+              "year must be a positive Integer (1 CE or later)"
+      end
+      private_class_method :valid_year!
+
+      def valid_month!(month)
+        return if month.is_a?(Integer) && month.between?(1, 12)
+
+        raise ArgumentError, "month must be an Integer in 1..12"
+      end
+      private_class_method :valid_month!
+
+      def integer_jdn!(jdn)
+        return if jdn.is_a?(Integer)
+
+        raise ArgumentError, "JDN must be an Integer"
+      end
+      private_class_method :integer_jdn!
+
+      def format_components(year, month, day)
+        [year, month, day].map(&:to_s).join("-")
+      end
+      private_class_method :format_components
+    end
+  end
+end

data/lib/jw_calendar/calendars/julian.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Calendars
+    # Julian civil-calendar arithmetic. This is distinct from a Julian Day Number.
+    module Julian
+      module_function
+
+      MONTH_LENGTHS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+
+      # Julian leap years occur every four years.
+      def leap_year?(year)
+        valid_year!(year)
+        (year % 4).zero?
+      end
+
+      # Number of days in the requested Julian month.
+      def days_in_month(year, month)
+        valid_year!(year)
+        valid_month!(month)
+        return 29 if month == 2 && leap_year?(year)
+
+        MONTH_LENGTHS.fetch(month - 1)
+      end
+
+      def days_in_year(year)
+        leap_year?(year) ? 366 : 365
+      end
+
+      # Whether the components form a valid Julian date.
+      def valid_date?(year, month, day)
+        return false unless year.is_a?(Integer) && year.positive?
+        return false unless month.is_a?(Integer) && month.between?(1, 12)
+        return false unless day.is_a?(Integer) && day.positive?
+
+        day <= days_in_month(year, month)
+      rescue ArgumentError
+        false
+      end
+
+      # Raise {InvalidDateError} unless the components form a valid date.
+      def validate_date!(year, month, day)
+        return true if valid_date?(year, month, day)
+
+        raise InvalidDateError, "invalid Julian calendar date: #{[year, month, day].join('-')}"
+      end
+
+      # Convert Julian components to an integer JDN.
+      def to_jdn(year, month, day)
+        validate_date!(year, month, day)
+        a = Arithmetic::FloorDivision.div(14 - month, 12)
+        y = year + 4_800 - a
+        m = month + (12 * a) - 3
+        day + Arithmetic::FloorDivision.div((153 * m) + 2, 5) + (365 * y) +
+          Arithmetic::FloorDivision.div(y, 4) - 32_083
+      end
+
+      # Convert an integer JDN to `[year, month, day]` Julian components.
+      def from_jdn(jdn)
+        raise ArgumentError, "JDN must be an Integer" unless jdn.is_a?(Integer)
+
+        c = jdn + 32_082
+        d = Arithmetic::FloorDivision.div((4 * c) + 3, 1_461)
+        e = c - Arithmetic::FloorDivision.div(1_461 * d, 4)
+        m = Arithmetic::FloorDivision.div((5 * e) + 2, 153)
+        day = e - Arithmetic::FloorDivision.div((153 * m) + 2, 5) + 1
+        month = m + 3 - (12 * Arithmetic::FloorDivision.div(m, 10))
+        year = d - 4_800 + Arithmetic::FloorDivision.div(m, 10)
+        raise InvalidDateError, "JDN is earlier than the supported Julian domain" unless year.positive?
+
+        [year, month, day]
+      end
+
+      def valid_year!(year)
+        return if year.is_a?(Integer) && year.positive?
+
+        raise ArgumentError,
+              "year must be a positive Integer (1 CE or later)"
+      end
+      private_class_method :valid_year!
+
+      def valid_month!(month)
+        return if month.is_a?(Integer) && month.between?(1, 12)
+
+        raise ArgumentError, "month must be an Integer in 1..12"
+      end
+      private_class_method :valid_month!
+    end
+  end
+end

data/lib/jw_calendar/calendars/reform_calendar.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Calendars
+    # A local civil calendar switching from Julian to Gregorian labels on a
+    # caller-supplied pair of consecutive absolute days.
+    class ReformCalendar
+      attr_reader :last_julian_date, :first_gregorian_date
+
+      def self.papal
+        new(last_julian_date: CivilDate.julian(1582, 10, 4),
+            first_gregorian_date: CivilDate.gregorian(1582, 10, 15))
+      end
+
+      def self.british_empire
+        new(last_julian_date: CivilDate.julian(1752, 9, 2),
+            first_gregorian_date: CivilDate.gregorian(1752, 9, 14))
+      end
+
+      def initialize(last_julian_date:, first_gregorian_date:)
+        @last_julian_date = coerce_date(last_julian_date, :julian)
+        @first_gregorian_date = coerce_date(first_gregorian_date, :gregorian)
+        unless (label(@last_julian_date) <=> label(@first_gregorian_date)) == -1
+          raise ArgumentError, "last Julian label must precede first Gregorian label"
+        end
+        unless @first_gregorian_date.to_jdn == @last_julian_date.to_jdn + 1
+          raise ArgumentError, "cutover dates must be consecutive absolute days"
+        end
+
+        freeze
+      end
+
+      def valid_date?(year, month, day)
+        return false unless [year, month, day].all? { |part| part.is_a?(Integer) }
+
+        calendar_for_label(year, month, day)
+        true
+      rescue InvalidDateError, ReformGapError, ArgumentError
+        false
+      end
+
+      def date(year, month, day)
+        calendar = calendar_for_label(year, month, day)
+        CivilDate.new(year, month, day, calendar:)
+      end
+
+      def to_jdn(year, month, day)
+        date(year, month, day).to_jdn
+      end
+
+      def from_jdn(jdn)
+        raise ArgumentError, "JDN must be an Integer" unless jdn.is_a?(Integer)
+
+        return CivilDate.from_jdn(jdn, calendar: :julian) if jdn <= last_julian_date.to_jdn
+
+        CivilDate.from_jdn(jdn, calendar: :gregorian)
+      end
+
+      def skipped_labels
+        start_label = last_julian_date
+        end_label = first_gregorian_date
+        labels = []
+        cursor = start_label
+        loop do
+          cursor = cursor.next_day
+          break if (label(cursor) <=> label(end_label)) >= 0
+
+          labels << cursor.to_s
+        end
+        labels.freeze
+      end
+
+      private
+
+      def coerce_date(value, calendar)
+        return value if value.is_a?(CivilDate) && value.calendar == calendar
+        return CivilDate.new(*value, calendar:) if value.is_a?(Array) && value.length == 3
+
+        raise ArgumentError, "cutover date must be a #{calendar} CivilDate or [year, month, day]"
+      end
+
+      def calendar_for_label(year, month, day)
+        unless [year, month, day].all? { |part| part.is_a?(Integer) }
+          raise InvalidDateError, "year, month, and day must be integers"
+        end
+
+        tuple = [year, month, day]
+        if (tuple <=> label(last_julian_date)) <= 0
+          Julian.validate_date!(year, month, day)
+          :julian
+        elsif (tuple <=> label(first_gregorian_date)) >= 0
+          Gregorian.validate_date!(year, month, day)
+          :gregorian
+        else
+          raise ReformGapError, "#{year}-#{month}-#{day} was skipped by this calendar reform"
+        end
+      end
+
+      def label(date)
+        [date.year, date.month, date.day]
+      end
+    end
+  end
+end

data/lib/jw_calendar/civil_date.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  # Immutable civil date. It is a calendar label, not an instant or a UTC midnight.
+  # Years start at 1 CE; supported calendars are proleptic Gregorian and Julian.
+  class CivilDate
+    include Comparable
+
+    CALENDARS = %i[gregorian julian].freeze
+    attr_reader :year, :month, :day, :calendar
+
+    # Build a validated date label.
+    # @param year [Integer] positive civil year
+    # @param month [Integer] month from 1 to 12
+    # @param day [Integer] valid day in the selected month
+    # @param calendar [Symbol] `:gregorian` or `:julian`
+    def initialize(year, month, day, calendar: :gregorian)
+      raise InvalidCalendarError, "calendar must be :gregorian or :julian" unless CALENDARS.include?(calendar)
+
+      validator = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+      validator.validate_date!(year, month, day)
+      @year = year
+      @month = month
+      @day = day
+      @calendar = calendar
+      freeze
+    end
+
+    # Create a proleptic Gregorian date.
+    def self.gregorian(year, month, day)
+      new(year, month, day, calendar: :gregorian)
+    end
+
+    # Create a proleptic Julian date.
+    def self.julian(year, month, day)
+      new(year, month, day, calendar: :julian)
+    end
+
+    # Parse an extended `YYYY-MM-DD` civil date.
+    def self.parse(value, calendar: :gregorian)
+      match = /\A(\d{4,})-(\d{2})-(\d{2})\z/.match(value.to_s)
+      raise InvalidDateError, "expected YYYY-MM-DD, got #{value.inspect}" unless match
+
+      new(match[1].to_i, match[2].to_i, match[3].to_i, calendar:)
+    end
+
+    # Compare by absolute day, independent of the calendar label.
+    def <=>(other)
+      return nil unless other.is_a?(CivilDate)
+
+      to_jdn <=> other.to_jdn
+    end
+
+    # Equality includes the year, month, day, and calendar system.
+    def ==(other)
+      other.is_a?(CivilDate) && [year, month, day, calendar] == [other.year, other.month, other.day, other.calendar]
+    end
+    alias eql? ==
+
+    def hash
+      [year, month, day, calendar].hash
+    end
+
+    # Return this date's integer Julian Day Number.
+    def to_jdn
+      converter = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+      converter.to_jdn(year, month, day)
+    end
+
+    # Return ISO weekday number, Monday=1 through Sunday=7.
+    def weekday
+      (to_jdn % 7) + 1 # ISO weekday: Monday=1 … Sunday=7.
+    end
+
+    def weekday_name
+      ISO::WeekDate::WEEKDAY_NAMES.fetch(weekday - 1)
+    end
+
+    # Return the one-based day of year in this date's calendar.
+    def ordinal_day
+      first_day = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+      to_jdn - first_day.to_jdn(year, 1, 1) + 1
+    end
+
+    # Return a new date a fixed number of civil days from this date.
+    def add_days(amount)
+      raise ArgumentError, "amount must be an Integer" unless amount.is_a?(Integer)
+
+      self.class.from_jdn(to_jdn + amount, calendar:)
+    end
+
+    def subtract_days(amount)
+      add_days(-amount)
+    end
+
+    def next_day
+      add_days(1)
+    end
+
+    def previous_day
+      add_days(-1)
+    end
+
+    def days_until(other)
+      raise ArgumentError, "other must be a CivilDate" unless other.is_a?(CivilDate)
+
+      other.to_jdn - to_jdn
+    end
+
+    # Return the ISO week date for this absolute day.
+    def iso_week
+      ISO::WeekDate.for(self)
+    end
+
+    def to_s
+      format("%<year>04d-%<month>02d-%<day>02d", year:, month:, day:)
+    end
+
+    def to_iso8601
+      to_s
+    end
+
+    def inspect
+      "#<#{self.class} #{self} calendar=#{calendar}>"
+    end
+
+    # Convert an integer JDN to a date label in the selected calendar.
+    def self.from_jdn(jdn, calendar: :gregorian)
+      raise InvalidCalendarError, "calendar must be :gregorian or :julian" unless CALENDARS.include?(calendar)
+
+      converter = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+      new(*converter.from_jdn(jdn), calendar:)
+    end
+  end
+end

data/lib/jw_calendar/cli/runner.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module JWCalendar
+  module CLI
+    # Standard-library command-line interface used by the jwcalendar executable.
+    class Runner
+      def initialize(stdout: $stdout, stderr: $stderr)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run(argv)
+        args = argv.dup
+        command = args.shift
+        return help if command.nil? || %w[-h --help help].include?(command)
+        return version if %w[-v --version version].include?(command)
+
+        case command
+        when "inspect" then inspect_date(args)
+        when "iso-week" then iso_week(args)
+        when "jdn" then jdn(args)
+        when "convert" then convert(args)
+        when "grid" then grid(args)
+        when "boundary" then boundary(args)
+        else
+          raise ArgumentError, "unknown command #{command.inspect}; run jwcalendar --help"
+        end
+      rescue OptionParser::ParseError, ArgumentError, Error => e
+        @stderr.puts("jwcalendar: #{e.message}")
+        2
+      end
+
+      private
+
+      def inspect_date(args)
+        options = { json: false, calendar: :gregorian }
+        parser = OptionParser.new do |opts|
+          opts.on("--json") { options[:json] = true }
+          opts.on("--calendar NAME", %w[gregorian julian]) { |value| options[:calendar] = value.to_sym }
+        end
+        parser.parse!(args)
+        date = parse_single_date(args, options[:calendar])
+        iso = date.iso_week
+        output = {
+          date: date.to_s, calendar: date.calendar, weekday: date.weekday_name,
+          weekday_number: date.weekday, ordinal_day: date.ordinal_day,
+          jdn: date.to_jdn, iso_week_year: iso.week_year,
+          iso_week: iso.week, iso_weekday: iso.weekday
+        }
+        if options[:json]
+          @stdout.puts(JSON.pretty_generate(output))
+        else
+          output.each { |key, value| @stdout.puts("#{key.to_s.tr('_', ' ')}: #{value}") }
+        end
+        0
+      end
+
+      def iso_week(args)
+        json = false
+        calendar = :gregorian
+        parser = OptionParser.new do |opts|
+          opts.on("--json") { json = true }
+          opts.on("--calendar NAME", %w[gregorian julian]) { |value| calendar = value.to_sym }
+        end
+        parser.parse!(args)
+        date = parse_single_date(args, calendar)
+        week = date.iso_week
+        output = { date: date.to_s, week_year: week.week_year, week: week.week,
+                   weekday: week.weekday, weekday_name: week.weekday_name,
+                   iso_date: week.to_s }
+        @stdout.puts(json ? JSON.pretty_generate(output) : "#{week} (#{week.weekday_name})")
+        0
+      end
+
+      def jdn(args)
+        json = false
+        calendar = :gregorian
+        parser = OptionParser.new do |opts|
+          opts.on("--json") { json = true }
+          opts.on("--calendar NAME", %w[gregorian julian]) { |value| calendar = value.to_sym }
+        end
+        parser.parse!(args)
+        date = parse_single_date(args, calendar)
+        result = { date: date.to_s, calendar:, jdn: date.to_jdn,
+                   jd_at_midnight: Conversion::JulianDayNumber.jd(date).to_s,
+                   mjd_at_midnight: Conversion::JulianDayNumber.mjd(date).to_s }
+        @stdout.puts(json ? JSON.pretty_generate(result) : result.map { |key, value| "#{key}: #{value}" }.join("\n"))
+        0
+      end
+
+      def convert(args)
+        options = { from: :gregorian, to: :julian, json: false }
+        parser = OptionParser.new do |opts|
+          opts.on("--from NAME", %w[gregorian julian]) { |value| options[:from] = value.to_sym }
+          opts.on("--to NAME", %w[gregorian julian]) { |value| options[:to] = value.to_sym }
+          opts.on("--json") { options[:json] = true }
+        end
+        parser.parse!(args)
+        date = parse_single_date(args, options[:from])
+        converted = Conversion::CalendarConverter.convert(date, to: options[:to])
+        result = { input: date.to_s, from: options[:from], result: converted.to_s, to: options[:to], jdn: date.to_jdn }
+        human_result = "#{date} (#{options[:from]}) = #{converted} (#{options[:to]})"
+        @stdout.puts(options[:json] ? JSON.pretty_generate(result) : human_result)
+        0
+      end
+
+      def grid(args)
+        options = { week_start: :monday, fixed_weeks: nil, json: false, adjacent: true }
+        parser = OptionParser.new do |opts|
+          opts.on("--week-start DAY", %w[monday sunday]) { |value| options[:week_start] = value.to_sym }
+          opts.on("--fixed-weeks N", Integer) { |value| options[:fixed_weeks] = value }
+          opts.on("--no-adjacent") { options[:adjacent] = false }
+          opts.on("--json") { options[:json] = true }
+        end
+        parser.parse!(args)
+        unless args.length == 1 && (match = /\A(\d{4,})-(\d{2})\z/.match(args.first))
+          raise ArgumentError,
+                "expected one YYYY-MM month"
+        end
+
+        layout = Grid::MonthGrid.new(year: match[1].to_i, month: match[2].to_i,
+                                     week_start: options[:week_start], fixed_weeks: options[:fixed_weeks],
+                                     include_adjacent: options[:adjacent])
+        @stdout.puts(options[:json] ? JSON.pretty_generate(layout.to_h) : render_grid(layout))
+        0
+      end
+
+      def boundary(args)
+        json = false
+        parser = OptionParser.new { |opts| opts.on("--json") { json = true } }
+        parser.parse!(args)
+        raise ArgumentError, "expected one year" unless args.length == 1 && /\A\d+\z/.match?(args.first)
+
+        report = Boundary::Analyzer.year(args.first.to_i)
+        @stdout.puts(json ? JSON.pretty_generate(report.to_h) : report.map do |event|
+                                                                  "#{event[:date]} #{event[:type]}"
+                                                                end.join("\n"))
+        0
+      end
+
+      def render_grid(layout)
+        title = format("%<year>04d-%<month>02d", year: layout.year, month: layout.month)
+        lines = ["#{title}  (week starts #{ISO::WeekDate::WEEKDAY_NAMES[layout.week_start - 1]})",
+                 layout.day_names.map { |name| name[0, 3].rjust(4) }.join]
+        layout.rows.each do |row|
+          lines << row.map do |cell|
+            if cell.date.nil?
+              "    "
+            elsif cell.in_current_month?
+              cell.date.day.to_s.rjust(4)
+            else
+              "(#{cell.date.day})".rjust(4)
+            end
+          end.join
+        end
+        lines.join("\n")
+      end
+
+      def parse_single_date(args, calendar)
+        raise ArgumentError, "expected one YYYY-MM-DD date" unless args.length == 1
+
+        CivilDate.parse(args.first, calendar:)
+      end
+
+      def version
+        @stdout.puts("jwcalendar #{VERSION}")
+        0
+      end
+
+      def help
+        @stdout.puts <<~TEXT
+          JW Calendar #{VERSION} — deterministic civil-date computation
+
+          Usage: jwcalendar COMMAND [OPTIONS]
+
+          Commands:
+            inspect DATE           Show date, weekday, ordinal day and ISO week
+            iso-week DATE          Show the ISO week date
+            jdn DATE               Show JDN, exact JD and MJD at midnight
+            convert DATE           Convert between Gregorian and Julian labels
+            grid YYYY-MM           Print a structured month grid
+            boundary YEAR          List calendar boundary cases
+
+          Common options:
+            --json                 Emit machine-readable JSON where supported
+            --calendar NAME        Select gregorian or julian for date commands
+            --help, --version      Show help or version
+        TEXT
+        0
+      end
+    end
+  end
+end

data/lib/jw_calendar/conversion/calendar_converter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Conversion
+    # Converts labels between the proleptic Gregorian and Julian calendars.
+    module CalendarConverter
+      module_function
+
+      # Convert a date label while preserving its absolute JDN.
+      def convert(date, to:)
+        raise ArgumentError, "date must be a CivilDate" unless date.is_a?(CivilDate)
+
+        unless CivilDate::CALENDARS.include?(to)
+          raise InvalidCalendarError,
+                "target calendar must be :gregorian or :julian"
+        end
+
+        CivilDate.from_jdn(date.to_jdn, calendar: to)
+      end
+    end
+  end
+end