aws-cron-parser 0.1.0

data/lib/aws_cron_parser/describer/time_composer.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    # Composes time descriptions (second, minute, hour)
+    class TimeComposer
+      include AWSCronParser::Helpers
+
+      attr_reader :second, :minute, :hour, :is_aws
+
+      def initialize(config, is_aws: false)
+        @second = config[:second]
+        @minute = config[:minute]
+        @hour = config[:hour]
+        @is_aws = is_aws
+      end
+
+      def compose
+        return nil if all_wildcards?
+
+        # Try specific patterns first
+        return describe_specific_time if specific_time?
+        return describe_step_pattern if step_pattern?
+        return describe_specific_second if specific_second_pattern?
+
+        # General composition
+        describe_general
+      end
+
+      private
+
+      def all_wildcards?
+        [second, minute, hour].all? { |f| f.nil? || f == '*' || f == '?' }
+      end
+
+      def specific_time?
+        hour =~ DIGIT_ONLY_REGEX && minute =~ DIGIT_ONLY_REGEX
+      end
+
+      def step_pattern?
+        (minute&.include?('/') && hour == '*') ||
+          (hour&.include?('/') && minute == '*') ||
+          (minute&.include?('/') && hour =~ DIGIT_ONLY_REGEX) || # minute step with specific hour
+          (minute&.include?('/') && hour&.include?('-')) # minute step with hour range
+      end
+
+      def specific_second_pattern?
+        second.present? && second =~ DIGIT_ONLY_REGEX && minute == '*' && hour == '*'
+      end
+
+      def describe_specific_time
+        h = hour.to_i
+        m = minute.to_i
+
+        time_str = if second.present? && second =~ DIGIT_ONLY_REGEX
+                     s = second.to_i
+                     format_time_with_seconds(h, m, s)
+                   else
+                     format_time(h, m)
+                   end
+
+        "At #{time_str}"
+      end
+
+      def describe_step_pattern
+        # Hour step: */2 or 0/2 or 1/5 (should be checked first)
+        # Check if minute is 0 (start of the hour) - simplify description
+        if hour&.match?(%r{^(\*|\d+)/(\d+)$}) && (minute == '0')
+          match = hour.match(%r{^(\*|\d+)/(\d+)$})
+          step = match[2].to_i
+          plural = step == 1 ? '' : 's'
+          return step == 1 ? 'Every hour' : "Every #{step} hour#{plural}"
+        end
+
+        # Minute step: */5 or 0/5
+        if minute&.match?(%r{^(\*|\d+)/(\d+)$})
+          match = minute.match(%r{^(\*|\d+)/(\d+)$})
+          step = match[2].to_i
+
+          # Check for hour constraints
+          if hour.present? && hour != '*' && hour != '?'
+            return describe_constrained_minute_step(step)
+          end
+
+          plural = step == 1 ? '' : 's'
+          return step == 1 ? 'Every minute' : "Every #{step} minute#{plural}"
+        end
+
+        nil
+      end
+
+      def describe_constrained_minute_step(step)
+        plural = step == 1 ? '' : 's'
+        base = step == 1 ? 'Every minute' : "Every #{step} minute#{plural}"
+
+        # Hour range: 9-17
+        if hour.include?('-')
+          parts = hour.split('-')
+          start_h = format_hour_12(parts[0].to_i)
+          end_h = format_hour_12(parts[1].to_i)
+          return "#{base} between #{start_h} and #{end_h}"
+        end
+
+        # Hour list: 9,12,15
+        if hour.include?(',')
+          hours = hour.split(',').map { |h| format_hour_12(h.to_i) }
+          hour_part = if hours.length == 2
+                        hours.join(' and ')
+                      else
+                        last = hours.pop
+                        "#{hours.join(', ')}, and #{last}"
+                      end
+          return "#{base} at #{hour_part}"
+        end
+
+        # Single hour: e.g., "1/5 9 * * *" -> "Every 5 minutes from 9:01 AM to 9:56 AM"
+        if /^\d+$/.match?(hour)
+          hour_int = hour.to_i
+          match = minute.match(%r{^(\d+)/(\d+)$})
+          start_min = match ? match[1].to_i : 0
+
+          # Calculate end minute (start + step * floor((59-start)/step))
+          end_min = start_min + (step * ((59 - start_min) / step))
+
+          # Convert to 12-hour format
+          hour_12 = hour_int % 12
+          hour_12 = 12 if hour_12.zero?
+          period = hour_int < 12 ? 'AM' : 'PM'
+
+          return "#{base} from #{hour_12}:#{start_min.to_s.rjust(
+            2, '0'
+          )} #{period} to #{hour_12}:#{end_min.to_s.rjust(
+            2, '0'
+          )} #{period}"
+        end
+
+        base
+      end
+
+      def describe_specific_second
+        s = second.to_i
+        Template.interpolate('composition.every_minute_at_second', second: s)
+      end
+
+      def describe_general
+        # Handle minute-specific with hour=*
+        if hour == '*' && minute.present? && minute != '*' && minute != '?' && !minute.match?(%r{[-,/]})
+          m = minute.to_i
+          return Template.interpolate('composition.every_hour_at_minute', minute: m)
+        end
+
+        # Complex case: describe each component
+        parts = []
+
+        # Add hour if set
+        parts << describe_component(hour, :hour) if hour.present? && hour != '*' && hour != '?'
+
+        # Add minute only if it's not 0 when we have an hour step pattern, hour range, or hour list
+        # Example: "0 */4 * * *" should be "Every 4 hours", not "0 minutes and every 4 hours"
+        # Example: "0 10-15 * * *" should be "Every day from 10 AM to 3 PM", not "0 minutes and from..."
+        # Example: "0 9,12,15 * * *" should be "at 9 AM, 12 PM, and 3 PM", not "0 minutes and at..."
+        should_skip_minute = minute == '0' && (hour&.include?('/') || hour&.include?('-') || hour&.include?(','))
+        if !should_skip_minute && minute.present? && minute != '*' && minute != '?'
+          parts << describe_component(minute, :minute)
+        end
+
+        # Add second if significant
+        if second.present? && second != '*' && second != '?' && second != '0'
+          parts << describe_component(second, :second)
+        end
+
+        return nil if parts.empty?
+
+        # Special case: hour step with specific minute (e.g., "30 */6 * * *")
+        if parts.length == 2 && hour&.include?('/') && minute =~ DIGIT_ONLY_REGEX
+          hour_desc = parts[0]
+          m = minute.to_i
+          return "#{hour_desc} at minute #{m}"
+        end
+
+        # Join parts
+        if parts.length == 1
+          # Single part - return as is if it starts with a capital letter (proper sentence)
+          parts[0]
+        elsif hour&.include?('-') && minute =~ DIGIT_ONLY_REGEX
+          # Multiple parts - join with spaces (descriptions already have proper formatting)
+          # For hour ranges, we want to avoid "30 minutes and from 10 AM to 3 PM"
+          # Instead: "Every day at 10:30 AM to 3:30 PM" or similar
+          # We have a time range - format differently
+          format_time_range
+        else
+          parts.reverse.join(' ')
+        end
+      end
+
+      def format_time_range
+        hour_parts = hour.split('-')
+        start_h = hour_parts[0].to_i
+        end_h = hour_parts[1].to_i
+        m = minute.to_i
+
+        start_time = format_time(start_h, m)
+        end_time = format_time(end_h, m)
+
+        # Return without "Every day" prefix - it will be added by composer if needed
+        "from #{start_time} to #{end_time}"
+      end
+
+      def describe_component(value, type)
+        FieldDescribers::TimeField.new(value, type, is_aws: is_aws).describe
+      end
+
+      def format_time(hour, min)
+        hour_24 = hour.to_i % 24
+        am_pm = hour_24 < 12 ? 'AM' : 'PM'
+        hour_12 = if hour_24.zero?
+                    12
+                  elsif hour_24 > 12
+                    hour_24 - 12
+                  else
+                    hour_24
+                  end
+        time_str = hour_12.to_s
+        time_str += ":#{min.to_s.rjust(2, '0')}" if min != 0 || !is_aws
+        "#{time_str} #{am_pm}"
+      end
+
+      def format_time_with_seconds(hour, min, sec)
+        hour_24 = hour.to_i % 24
+        am_pm = hour_24 < 12 ? 'AM' : 'PM'
+        hour_12 = if hour_24.zero?
+                    12
+                  elsif hour_24 > 12
+                    hour_24 - 12
+                  else
+                    hour_24
+                  end
+        "#{hour_12}:#{min.to_s.rjust(2, '0')}:#{sec.to_s.rjust(2, '0')} #{am_pm}"
+      end
+
+      def format_hour_12(hour_24)
+        hour_24 = hour_24.to_i % 24
+        period = hour_24 < 12 ? 'AM' : 'PM'
+        hour_12 = if hour_24.zero?
+                    12
+                  elsif hour_24 > 12
+                    hour_24 - 12
+                  else
+                    hour_24
+                  end
+        "#{hour_12} #{period}"
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    include AWSCronParser::Helpers
+
+    module_function
+
+    # Main entry point: describe a CRON expression in human-readable form
+    # Returns string like "Every weekday at 9:00 AM"
+    def describe(expression)
+      return nil if expression.nil? || expression.to_s.strip.empty? || !expression.is_a?(String)
+
+      begin
+        AWSCronParser::Validator.validate(expression)
+        config = parse_config(expression)
+        return nil unless config
+
+        case config[:type]
+        when 'rate'
+          describe_rate(config)
+        when 'macro'
+          describe_macro(config)
+        when 'at'
+          describe_at(config)
+        when /^(aws-)?cron/
+          describe_cron(config)
+        end
+      end
+    end
+
+    # Parse parser into config hash for describing
+    def parse_config(expression)
+      trimmed = expression.strip
+
+      # Rate expression: rate(value unit)
+      if (rate_match = trimmed.match(RATE_REGEX))
+        unit = rate_match[:unit].downcase.chomp('s').to_sym
+        return { type: 'rate', value: rate_match[:value].to_i, unit: unit }
+      end
+
+      # Macro expressions: @yearly, @monthly, etc.
+      if (macro_match = trimmed.match(MACRO_REGEX))
+        macro = macro_match[:macro].downcase
+        return { type: 'macro', macro: macro }
+      end
+
+      # At expression: at(iso8601)
+      if (at_match = trimmed.match(AT_REGEX))
+        return { type: 'at', dateTime: at_match[:datetime] }
+      end
+
+      # Detect AWS cron wrapper
+      is_aws = false
+      content = trimmed
+      if (cron_match = content.match(AWS_CRON_REGEX))
+        is_aws = true
+        content = cron_match[:expression].strip
+      end
+
+      fields = content.split(/\s+/)
+      case fields.length
+      when 5
+        # Standard CRON: MINUTE HOUR DAY MONTH DOW
+        # OR AWS (no wrapper): not applicable, AWS needs cron() wrapper
+        { type: is_aws ? 'aws-cron-5' : 'cron-5', second: nil, minute: fields[0], hour: fields[1], day: fields[2],
+          month: fields[3], dow: fields[4], is_aws: is_aws }
+      when 6
+        if is_aws
+          # AWS with wrapper: MINUTE HOUR DAY MONTH DOW YEAR
+          { type: 'aws-cron-6', second: nil, minute: fields[0], hour: fields[1], day: fields[2], month: fields[3],
+            dow: fields[4], year: fields[5], is_aws: is_aws }
+        else
+          # Unix CRON: SECOND MINUTE HOUR DAY MONTH DOW
+          { type: 'cron-6', second: fields[0], minute: fields[1], hour: fields[2], day: fields[3], month: fields[4],
+            dow: fields[5], is_aws: is_aws }
+        end
+      when 7
+        # AWS with seconds: SECOND MINUTE HOUR DAY MONTH DOW YEAR
+        { type: 'aws-cron-7', second: fields[0], minute: fields[1], hour: fields[2], day: fields[3], month: fields[4],
+          dow: fields[5], year: fields[6], is_aws: is_aws }
+      end
+    end
+
+    # Describe rate expression
+    def describe_rate(config)
+      value = config[:value]
+      unit = config[:unit]
+
+      Template.interpolate(value == 1 ? 'rate.singular' : 'rate.plural', value: value, unit: unit)
+    end
+
+    # Describe macro expression
+    def describe_macro(config)
+      macro = config[:macro]
+      Template.interpolate("macro.#{macro}") || "Every #{macro}"
+    end
+
+    # Describe at expression
+    def describe_at(config)
+      date_time = Time.zone.parse(config[:dateTime])
+      "At #{date_time.strftime('%A, %b %d, %Y %I:%M:%S %p')}"
+    rescue StandardError
+      nil
+    end
+
+    # Describe CRON expression using composers
+    def describe_cron(config)
+      CronComposer.new(config).compose
+    end
+
+    # Legacy method - kept for backward compatibility
+    # Delegates to appropriate field describer
+    def describe_field(value, field_type, is_aws: false)
+      return nil if value.blank? || ['*', '?'].include?(value)
+
+      case field_type
+      when 'minute', 'second', 'hour'
+        FieldDescribers::TimeField.new(value, field_type.to_sym, is_aws: is_aws).describe
+      when 'day-of-month'
+        FieldDescribers::DayOfMonth.new(value, is_aws: is_aws).describe
+      when 'day-of-week'
+        FieldDescribers::DayOfWeek.new(value, is_aws: is_aws).describe
+      when 'month'
+        FieldDescribers::Month.new(value, is_aws: is_aws).describe
+      else
+        value
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/fugit_adapter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'fugit'
+
+module AWSCronParser
+  # Adapter to use Fugit gem as replacement for parse-cron
+  # Provides a unified interface for next/last time calculations
+  class FugitAdapter
+    def initialize(source, time_source = Time)
+      @source = source
+      @time_source = time_source
+      @normalized_source = normalize_source(source)
+
+      # Parse with fugit
+      @fugit_cron = Fugit::Cron.parse(@normalized_source)
+
+      raise ArgumentError, "Invalid CRON expression: #{source}" if @fugit_cron.nil?
+    end
+
+    # Get next occurrence of the cron expression
+    def next(now)
+      result = @fugit_cron.next_time(now)
+      normalize_to_time_zone(result)
+    end
+
+    # Get previous occurrence of the cron expression
+    def last(now)
+      result = @fugit_cron.previous_time(now)
+      normalize_to_time_zone(result)
+    end
+
+    # Get the original source expression
+    def original
+      @source
+    end
+
+    private
+
+    # Normalize cron expression for fugit compatibility
+    # Fugit doesn't support ? and L in the same way as Quartz/AWS
+    def normalize_source(source)
+      normalized = source.dup
+
+      # Replace ? with * for compatibility
+      # ? means "no specific value" in Quartz, but fugit uses * for wildcard
+      normalized.tr('?', '*')
+
+      # NOTE: L (last day) is supported by fugit in 5-field format
+      # No need to replace it like parse-cron required
+    end
+
+    # Convert EtOrbi time to Rails Time.zone if available
+    # This ensures consistency with the rest of the application
+    def normalize_to_time_zone(time)
+      return nil unless time
+
+      # If Time.zone is not available, return as-is
+      return time unless Time.respond_to?(:zone) && Time.zone
+
+      # Convert EtOrbi::EoTime to Time.zone
+      Time.zone.at(time.to_i)
+    end
+  end
+end

data/lib/aws_cron_parser/helpers/calendar.rb

@@ -0,0 +1,115 @@
+#  frozen_string_literal: true
+
+module AWSCronParser
+  module Helpers
+    module Calendar
+      AWS_DAY_NAMES = {
+        'SUN' => 1, 'SUNDAY' => 1,
+        'MON' => 2, 'MONDAY' => 2,
+        'TUE' => 3, 'TUESDAY' => 3,
+        'WED' => 4, 'WEDNESDAY' => 4,
+        'THU' => 5, 'THURSDAY' => 5,
+        'FRI' => 6, 'FRIDAY' => 6,
+        'SAT' => 7, 'SATURDAY' => 7
+      }.freeze
+
+      DAY_NAMES = {
+        'SUN' => 0, 'SUNDAY' => 0,
+        'MON' => 1, 'MONDAY' => 1,
+        'TUE' => 2, 'TUESDAY' => 2,
+        'WED' => 3, 'WEDNESDAY' => 3,
+        'THU' => 4, 'THURSDAY' => 4,
+        'FRI' => 5, 'FRIDAY' => 5,
+        'SAT' => 6, 'SATURDAY' => 6
+      }.freeze
+
+      # Weekday names (0-6: SUN-SAT, where 0=Sunday, 6=Saturday)
+      WEEKDAY_NAMES = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+
+      # AWS weekday names (1-7: SUN-SAT, where 1=Sunday, 7=Saturday).
+      # Must stay aligned with AWS_DAY_NAMES above and with the parser, which
+      # matches candidates on Date#wday + 1.
+      AWS_WEEKDAY_NAMES = [nil, 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'].freeze
+
+      # Month names (1-based indexing for CRON)
+      MONTH_NAMES = [nil, 'January', 'February', 'March', 'April', 'May', 'June',
+                     'July', 'August', 'September', 'October', 'November', 'December'].freeze
+
+      # Month abbreviations (for parsing JAN, FEB, etc.)
+      # Using upcase in lookup to avoid case duplication
+      MONTH_ABBREVIATIONS = {
+        'JAN' => 1, 'FEB' => 2, 'MAR' => 3, 'APR' => 4, 'MAY' => 5, 'JUN' => 6,
+        'JUL' => 7, 'AUG' => 8, 'SEP' => 9, 'OCT' => 10, 'NOV' => 11, 'DEC' => 12
+      }.freeze
+
+      # Month full names (for parsing JANUARY, FEBRUARY, etc.)
+      # Using upcase in lookup to avoid case duplication
+      MONTH_FULL_NAMES = {
+        'JANUARY' => 1, 'FEBRUARY' => 2, 'MARCH' => 3, 'APRIL' => 4, 'MAY' => 5, 'JUNE' => 6,
+        'JULY' => 7, 'AUGUST' => 8, 'SEPTEMBER' => 9, 'OCTOBER' => 10, 'NOVEMBER' => 11, 'DECEMBER' => 12
+      }.freeze
+
+      # Convert day name from number or string
+      def day_name(num_or_str, is_aws: false)
+        if num_or_str.is_a?(String) && num_or_str.match?(/[A-Z]/)
+          case num_or_str.upcase
+          when 'MON' then 'Monday'
+          when 'TUE' then 'Tuesday'
+          when 'WED' then 'Wednesday'
+          when 'THU' then 'Thursday'
+          when 'FRI' then 'Friday'
+          when 'SAT' then 'Saturday'
+          when 'SUN' then 'Sunday'
+          else num_or_str
+          end
+        else
+          weekday_names = is_aws ? AWS_WEEKDAY_NAMES : WEEKDAY_NAMES
+          num = num_or_str.to_i
+          # Standard CRON spells Sunday either 0 or 7; AWS only uses 1-7.
+          num = 0 if !is_aws && num == 7
+          weekday_names[num] || "day #{num_or_str}"
+        end
+      end
+
+      # Map month name from number
+      def month_name(num)
+        MONTH_NAMES[num.to_i] || "month #{num}"
+      end
+
+      # Convert month abbreviation to number
+      def month_abbr_to_num(abbr)
+        raise ArgumentError, "Invalid month abbreviation: #{abbr.inspect}" unless abbr.is_a?(String) && !abbr.empty?
+
+        return abbr.to_i if /^\d+$/.match?(abbr)
+
+        upcase_abbr = abbr.upcase
+        MONTH_FULL_NAMES[upcase_abbr] || MONTH_ABBREVIATIONS[upcase_abbr] ||
+          (raise ArgumentError, "Invalid month abbreviation: #{abbr}")
+      end
+
+      # Convert weekday abbreviation to number
+      def weekday_abbr_to_num(abbr, is_aws: false)
+        raise ArgumentError, "Invalid weekday abbreviation: #{abbr.inspect}" unless abbr.is_a?(String) && !abbr.empty?
+
+        return abbr.to_i if /^\d+$/.match?(abbr)
+
+        day_names = is_aws ? AWS_DAY_NAMES : DAY_NAMES
+        day_names[abbr.upcase] || (raise ArgumentError, "Invalid weekday abbreviation: #{abbr}")
+      end
+
+      # Convert weekday name from abbreviation
+      def weekday_name_from_abbr(abbr)
+        case abbr.upcase
+        when 'MON' then 'Monday'
+        when 'TUE' then 'Tuesday'
+        when 'WED' then 'Wednesday'
+        when 'THU' then 'Thursday'
+        when 'FRI' then 'Friday'
+        when 'SAT' then 'Saturday'
+        when 'SUN' then 'Sunday'
+        else abbr
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/helpers/clock.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Helpers
+    # Deliberately not named Time: every class that includes Helpers would then
+    # resolve a bare `Time` to this module instead of ::Time through the
+    # ancestor chain, silently breaking default arguments and Time.zone calls.
+    module Clock
+      # Ensure the given 'now' is a Time object
+      def ensure_time(now, time_source = nil)
+        time_source ||= @time_source || ::Time
+        return now if now.is_a?(::Time)
+
+        # If it's a Date or DateTime, convert preserving timezone info
+        if now.respond_to?(:hour) && now.respond_to?(:min)
+          # It's a DateTime
+          time = time_source.local(now.year, now.month, now.day, now.hour, now.min, 0)
+          now.respond_to?(:utc?) && now.utc? ? time.utc : time
+        else
+          # It's a Date
+          time_source.local(now.year, now.month, now.day, 0, 0, 0)
+        end
+      end
+
+      # Get the start of the next month from a given date
+      def next_month_start(search_date, time_source = nil)
+        time_source ||= @time_source || ::Time
+        next_month = Date.new(search_date.year, search_date.month, 1).next_month
+
+        # Handle both Time.zone (Rails) and ::Time (Ruby)
+        if time_source.respond_to?(:local)
+          time_source.local(next_month.year, next_month.month, 1, 0, 0, 0)
+        else
+          ::Time.zone.local(next_month.year, next_month.month, 1, 0, 0, 0)
+        end
+      end
+
+      # Adjust time to the target second, rolling over minute if needed
+      def adjust_seconds(time, target_second)
+        if time.sec == target_second
+          time
+        elsif time.sec < target_second
+          time.change(sec: target_second)
+        else
+          (time + 60.seconds).change(sec: target_second)
+        end
+      end
+    end
+  end
+end