aws-cron-parser 0.1.0

data/lib/aws_cron_parser/helpers/cron_expression.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Helpers
+    module CronExpression
+      include AWSCronParser::Helpers::Calendar
+
+      # Expression type patterns
+      AWS_CRON_REGEX = /^cron\((?<expression>.+)\)$/i
+      RATE_REGEX = /^rate\((?<value>\d+)\s+(?<unit>minute|minutes|hour|hours|day|days)\)$/i
+      MACRO_REGEX = /^@(?<macro>yearly|monthly|weekly|daily|hourly)$/i
+      AT_REGEX = /^at\((?<datetime>.+)\)$/i
+
+      # Consolidated CRON field patterns
+      CRON_PATTERNS = {
+        digit_only: /^\d+$/,
+        step: %r{^\*/(\d+)$|^0/(\d+)$},
+        range: /^(\d+)-(\d+)$/,
+        step_range: %r{(\d+)/(\d+)},
+        nth_weekday_numeric: /^\d+#\d+$/,
+        last_weekday_numeric: /^\d+L$/,
+        nth_weekday: /^(?<weekday>\d)#(?<occurrence>\d)$/,
+        nth_weekday_name: /^(?<name>[A-Z]{3}|[A-Z]+)#(?<occurrence>\d+)$/i,
+        last_weekday: /^(?<weekday>\d)L$/,
+        last_weekday_name: /^(?<name>[A-Z]{3}|[A-Z]+)L$/i
+      }.freeze
+
+      # Backward compatibility - individual constants for existing code
+      DIGIT_ONLY_REGEX = CRON_PATTERNS[:digit_only]
+      RANGE_REGEX = CRON_PATTERNS[:range]
+      STEP_RANGE_REGEX = CRON_PATTERNS[:step_range]
+      NTH_WEEKDAY_REGEX = CRON_PATTERNS[:nth_weekday]
+      LAST_WEEKDAY_REGEX = CRON_PATTERNS[:last_weekday]
+
+      # Normalize expression by stripping cron() wrapper if present
+      def normalize_source(source)
+        return source if source.blank?
+
+        normalized = source.strip
+        if (match = normalized.match(AWS_CRON_REGEX))
+          content = match[:expression].strip
+          parts = content.split(/\s+/)
+          normalized = if parts.length == 7
+                         parts[0..5].join(' ')
+                       elsif parts.length == 6
+                         parts[0..4].join(' ')
+                       else
+                         parts.join(' ')
+                       end
+        end
+
+        normalized
+      end
+
+      # Detect if a specific pattern character exists in the day-of-week field
+      def detect_pattern(source, pattern_char)
+        tokens = source.split(/\s+/)
+        return false if tokens.length < 5
+
+        dow_field = tokens.length == 5 ? tokens[4] : tokens[5]
+        dow_field.include?(pattern_char)
+      end
+
+      # Detect if a specific pattern character exists in the day-of-month field
+      def detect_dom_pattern(source, pattern_char)
+        tokens = source.split(/\s+/)
+        return false if tokens.length < 5
+
+        dom_field = tokens.length == 5 ? tokens[2] : tokens[3]
+        dom_field.include?(pattern_char)
+      end
+
+      # Detect if the CRON expression uses complex step patterns (with ranges or lists)
+      def detect_complex_step(source)
+        tokens = source.split(/\s+/)
+        return false if tokens.length < 5
+
+        tokens.each do |field|
+          return true if field.include?('/') && field.exclude?('#') && field.exclude?('L')
+        end
+        false
+      end
+
+      # Check if month field matches actual month
+      def month_only?(source)
+        tokens = source.split(/\s+/)
+        return false if tokens.length < 5
+
+        dom_idx = tokens.length == 5 ? 2 : 3
+        dow_idx = tokens.length == 5 ? 4 : 5
+
+        dom = tokens[dom_idx]
+        dow = tokens[dow_idx]
+
+        ['*', '?'].include?(dom) && dow != '*' && dow != '?' && dow.exclude?('#') && dow.exclude?('L')
+      end
+
+      # Check if day-of-month field is specified and day-of-week is '?'
+      def day_only?(source)
+        tokens = source.split(/\s+/)
+        return false if tokens.length < 5
+
+        dom_idx = tokens.length == 5 ? 2 : 3
+        dow_idx = tokens.length == 5 ? 4 : 5
+
+        dom = tokens[dom_idx]
+        dow = tokens[dow_idx]
+
+        dom != '?' && dow == '?'
+      end
+
+      # Parse a simple cron field (minute, hour, day, month, or weekday)
+      def parse_simple_field(field, range)
+        return range.to_a if ['*', '?'].include?(field)
+        return [field.to_i] if field.match?(/^\d+$/)
+
+        if field.include?('-')
+          start_num, end_num = field.split('-').map(&:to_i)
+          (start_num..end_num).to_a
+        elsif field.include?(',')
+          field.split(',').map(&:to_i)
+        elsif field.include?('/')
+          start_str, step_str = field.split('/')
+          start = start_str == '*' ? range.first : start_str.to_i
+          step = step_str.to_i
+          result = []
+          current = start
+          while current <= range.last
+            result << current
+            current += step
+          end
+          result
+        else
+          [field.to_i]
+        end
+      end
+
+      # Parse the day-of-week field (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+      def parse_dow_field(field)
+        return (0..6).to_a if ['*', '?'].include?(field)
+
+        result = []
+        field.split(',').each do |part|
+          part = part.strip
+          if part.include?('/')
+            result.concat(expand_dow_step(part))
+          elsif part.include?('-')
+            start_num, end_num = part.split('-')
+            start_num = AWS_DAY_NAMES[start_num.upcase] || start_num.to_i
+            end_num = AWS_DAY_NAMES[end_num.upcase] || end_num.to_i
+            (start_num..end_num).each { |n| result << n }
+          elsif part.match?(/^\d+$/)
+            result << part.to_i
+          elsif AWS_DAY_NAMES[part.upcase]
+            result << AWS_DAY_NAMES[part.upcase]
+          end
+        end
+        result.sort.uniq
+      end
+
+      # Expands */2, MON/2 or 2-6/2 over the AWS weekday range (1=SUN..7=SAT).
+      # Without this the field yields no days at all and the caller searches a
+      # whole year before giving up.
+      def expand_dow_step(part)
+        base, step = part.split('/')
+        step = step.to_i
+        return [] if step <= 0
+
+        if base.include?('-')
+          start_num, end_num = base.split('-').map { |v| AWS_DAY_NAMES[v.upcase] || v.to_i }
+        elsif ['*', '?'].include?(base)
+          start_num = 1
+          end_num = 7
+        else
+          start_num = AWS_DAY_NAMES[base.upcase] || base.to_i
+          end_num = 7
+        end
+
+        (start_num..end_num).step(step).to_a
+      end
+
+      # Normalize weekday in nth spec (e.g., "MON#2" to "1#2")
+      def normalize_weekday_in_nth_spec(dow_spec, is_aws: false)
+        return dow_spec if dow_spec.match?(CRON_PATTERNS[:nth_weekday_numeric])
+
+        match = dow_spec.match(CRON_PATTERNS[:nth_weekday_name])
+        return dow_spec unless match
+
+        day_names = is_aws ? AWS_DAY_NAMES : DAY_NAMES
+        day_num = day_names[match[:name].upcase] || match[:name]
+        "#{day_num}##{match[:occurrence]}"
+      end
+
+      # Normalize weekday field (e.g., "mon", "tue-wed", "fri/2")
+      def normalize_weekday_field(weekday, is_aws: false)
+        return weekday if ['*', '?'].include?(weekday) || weekday =~ /^\d/
+
+        # Handle ranges like "mon-wed"
+        if weekday.include?('-')
+          parts = weekday.split('-')
+          start_num = weekday_abbr_to_num(parts[0], is_aws: is_aws)
+          end_num = weekday_abbr_to_num(parts[1], is_aws: is_aws)
+          return "#{start_num}-#{end_num}"
+        end
+
+        # Handle lists like "mon,wed,fri"
+        if weekday.include?(',')
+          parts = weekday.split(',').map { |w| weekday_abbr_to_num(w, is_aws: is_aws) }
+          return parts.join(',')
+        end
+
+        # Handle steps like "mon/2" and "*/2" - the wildcard base is not a name
+        if weekday.include?('/')
+          parts = weekday.split('/')
+          start = ['*', '?'].include?(parts[0]) ? parts[0] : weekday_abbr_to_num(parts[0], is_aws: is_aws)
+          return "#{start}/#{parts[1]}"
+        end
+
+        # Single weekday abbreviation
+        weekday_abbr_to_num(weekday, is_aws: is_aws).to_s
+      end
+
+      # Normalize weekday in last spec (e.g., "MONL" to "1L")
+      def normalize_weekday_in_last_spec(dow_spec)
+        return dow_spec if dow_spec.match?(CRON_PATTERNS[:last_weekday_numeric])
+
+        match = dow_spec.match(CRON_PATTERNS[:last_weekday_name])
+        return dow_spec unless match
+
+        day_num = AWS_DAY_NAMES[match[:name].upcase] || match[:name]
+        "#{day_num}L"
+      end
+
+      # Normalize month field (e.g., "jan", "feb-mar", "apr/2")
+      def normalize_month_field(month)
+        return month if ['*', '?'].include?(month) || month =~ /^\d/
+
+        # Handle ranges like "jan-mar"
+        if month.include?('-')
+          parts = month.split('-')
+          start_num = month_abbr_to_num(parts[0])
+          end_num = month_abbr_to_num(parts[1])
+          return "#{start_num}-#{end_num}"
+        end
+
+        # Handle lists like "jan,mar,jun"
+        if month.include?(',')
+          parts = month.split(',').map { |m| month_abbr_to_num(m) }
+          return parts.join(',')
+        end
+
+        # Handle steps like "jan/2" and "*/2" - the wildcard base is not a name
+        if month.include?('/')
+          parts = month.split('/')
+          start = ['*', '?'].include?(parts[0]) ? parts[0] : month_abbr_to_num(parts[0])
+          return "#{start}/#{parts[1]}"
+        end
+
+        # Single month abbreviation
+        month_abbr_to_num(month).to_s
+      end
+
+      def weekday_only?(source)
+        tokens = normalize_source(source).split(/\s+/)
+        return false if tokens.length < 5
+
+        dom_idx = tokens.length == 5 ? 2 : 3
+        dow_idx = tokens.length == 5 ? 4 : 5
+
+        dom = tokens[dom_idx]
+        dow = tokens[dow_idx]
+
+        dom == '?' && dow != '?' && dow.exclude?('#') && dow.exclude?('L')
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/helpers/numbers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Helpers
+    module Numbers
+      # Convert number to ordinal string (1 => "1st", 2 => "2nd", etc.)
+      def ordinal(num)
+        num = num.to_i
+        case num % 100
+        when 11, 12, 13
+          "#{num}th"
+        else
+          case num % 10
+          when 1 then "#{num}st"
+          when 2 then "#{num}nd"
+          when 3 then "#{num}rd"
+          else "#{num}th"
+          end
+        end
+      end
+
+      # Convert number to ordinal word (1 => "first", 2 => "second", etc.)
+      def ordinal_word(num)
+        num = num.to_i
+        words = %w[zeroth first second third fourth fifth sixth seventh eighth ninth tenth
+                   eleventh twelfth thirteenth fourteenth fifteenth sixteenth seventeenth
+                   eighteenth nineteenth twentieth]
+        words[num] || ordinal(num).to_s
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/helpers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Helpers
+    def self.included(base)
+      [
+        AWSCronParser::Helpers::Calendar,
+        AWSCronParser::Helpers::Clock,
+        AWSCronParser::Helpers::CronExpression,
+        AWSCronParser::Helpers::Numbers
+      ].each do |m|
+        base.include(m)
+        base.extend(m)
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/parser.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+
+module AWSCronParser
+  class Parser
+    include AWSCronParser::Helpers
+
+    def initialize(source, time_source = Time)
+      @original_source = source
+      @time_source = time_source
+
+      validate!
+
+      # Route to appropriate parser
+      @parser = if RATE_REGEX.match?(@original_source)
+                  AWSCronParser::Parsers::AWSRate.new(@original_source, @time_source)
+                elsif AT_REGEX.match?(@original_source)
+                  AWSCronParser::Parsers::AWSAt.new(@original_source, @time_source)
+                elsif AWS_CRON_REGEX.match?(@original_source) || @original_source.start_with?('@')
+                  AWSCronParser::Parsers::AWSCron.new(@original_source, @time_source)
+                else
+                  AWSCronParser::Parsers::QuartzCron.new(@original_source, @time_source)
+                end
+    end
+
+    def next(now = @time_source.now)
+      @parser.next(now)
+    rescue ZeroDivisionError => e
+      # Normalize low-level arithmetic errors from underlying parser into
+      # a user-facing ArgumentError so callers (and controllers) can
+      # return a proper 4xx validation response instead of crashing.
+      raise ArgumentError, "Invalid CRON expression: #{e.message}"
+    end
+
+    def last(now = @time_source.now)
+      if @parser.is_a?(AWSCronParser::Parsers::AWSCron) ||
+         @parser.is_a?(AWSCronParser::Parsers::AWSRate) ||
+         @parser.is_a?(AWSCronParser::Parsers::AWSAt)
+        raise ArgumentError, 'last() not supported for special patterns'
+      end
+
+      @parser.last(now)
+    end
+
+    # Get multiple next runs (shows unique occurrences for UI when appropriate)
+    # @param count [Integer] Number of next runs to calculate
+    # @param from [Time] Starting time (defaults to now)
+    # @return [Array<Time>] Array of next execution times
+    def next_runs(count = 5, from = @time_source.now)
+      # Always show all executions - the UI can handle pagination/filtering if needed
+      next_runs_all(count, from)
+    end
+
+    # Get ALL next runs (raw behavior - every single execution)
+    # @param count [Integer] Number of next runs to calculate
+    # @param from [Time] Starting time (defaults to now)
+    # @return [Array<Time>] Array of next execution times
+    def next_runs_all(count = 5, from = @time_source.now)
+      raise ArgumentError, 'count must be positive' if count <= 0
+
+      results = []
+      current = from
+
+      count.times do
+        current = @parser.next(current)
+        # A one-time at() schedule stops yielding once its instant has passed.
+        break if current.nil?
+
+        results << current
+      end
+
+      results
+    end
+
+    # Get unique dates (remove time component)
+    def next_unique_dates(count, from = @time_source.now)
+      seen_dates = Set.new
+      results = []
+      current = from
+
+      while results.length < count && results.length < 1000 # Safety limit
+        current = self.next(current)
+        break if current.nil?
+
+        date_key = current.to_date
+
+        next if seen_dates.include?(date_key)
+
+        seen_dates.add(date_key)
+        # Set to start of day for cleaner display
+        results << current.beginning_of_day
+      end
+
+      results
+    end
+
+    # Get unique hours (remove minute component)
+    def next_unique_hours(count, from = @time_source.now)
+      seen_hours = Set.new
+      results = []
+      current = from
+
+      while results.length < count && results.length < 1000 # Safety limit
+        current = self.next(current)
+        break if current.nil?
+
+        hour_key = [current.to_date, current.hour]
+
+        next if seen_hours.include?(hour_key)
+
+        seen_hours.add(hour_key)
+        # Set to start of hour for cleaner display
+        results << current.beginning_of_hour
+      end
+
+      results
+    end
+
+    def source
+      @parser.source
+    end
+
+    def expression
+      @original_source
+    end
+
+    def describe
+      Describer.describe(@original_source)
+    end
+
+    def validate!
+      Validator.validate(@original_source)
+    end
+
+    def validate
+      @errors = nil
+      Validator.validate(@original_source)
+    rescue ArgumentError => e
+      @errors = [e.message]
+    end
+
+    def valid?
+      validate
+      errors.empty?
+    end
+
+    def errors
+      @errors || []
+    end
+  end
+end

data/lib/aws_cron_parser/parsers/aws_at.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Parsers
+    # AWS one-time schedule: at(yyyy-MM-ddThh:mm:ss). Fires exactly once.
+    class AWSAt < Base
+      attr_reader :at
+
+      def initialize(source, time_source = Time)
+        super
+
+        match = source.strip.match(AT_REGEX)
+        raise ArgumentError, "Invalid at format: #{source}" unless match
+
+        @at = zone.parse(match[:datetime].strip)
+      end
+
+      # nil once the instant has passed: a one-time schedule has no further runs.
+      def next(now = @time_source.now)
+        @at > ensure_time(now) ? @at : nil
+      end
+
+      private
+
+      # AWS at() carries no offset, so it is read in the caller's zone when one
+      # was given, and otherwise in Time.zone (UTC unless the host set it).
+      def zone
+        @time_source.is_a?(ActiveSupport::TimeZone) ? @time_source : ::Time.zone
+      end
+    end
+  end
+end