aws-cron-parser 0.1.0

data/lib/aws_cron_parser/parsers/aws_cron.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module AWSCronParser
+  module Parsers
+    class AWSCron < Base
+      def initialize(source, time_source = Time)
+        super(source, time_source)
+
+        @source = normalize_source(source)
+
+        # Detect special patterns
+        @has_nth_weekday = detect_pattern(@source, '#')
+        @has_last_weekday = detect_pattern(@source, 'L')
+        @has_last_day_of_month = detect_dom_pattern(@source, 'L')
+        @has_weekday_closest = detect_dom_pattern(@source, 'W')
+        @has_complex_step = detect_complex_step(@source)
+        @weekday_only = weekday_only?(@source)
+        @day_only = day_only?(@source)
+      end
+
+      def next(now = @time_source.now)
+        if @has_last_weekday
+          calculate_next_last_weekday(now)
+        elsif @has_nth_weekday
+          calculate_next_nth_weekday(now)
+        elsif @has_last_day_of_month || @has_weekday_closest || @day_only
+          calculate_next_day_only(now)
+        elsif @weekday_only
+          calculate_next_weekday_only(now)
+        elsif @has_complex_step || @source.split(/\s+/).length >= 5
+          calculate_next_standard(now)
+        else
+          raise NotImplementedError, 'Unexpected AWS CRON pattern'
+        end
+      end
+
+      private
+
+      # Override method inherited from Helpers::CronExpression
+      def normalize_source(source)
+        @year_field = nil # Initialize year field
+
+        # Handle macro expressions
+        if (match = source.match(/^@(?<macro>\w+)$/i))
+          return expand_macro(match[:macro].downcase)
+        end
+
+        if source.start_with?('cron(') && source.end_with?(')')
+          inner = source[5...-1].strip
+          fields = inner.split(/\s+/)
+          # Store year field if present and not wildcard
+          @year_field = fields.length > 5 && fields[5] != '*' ? fields[5] : nil
+          # Remove trailing * (year field) if present
+          fields.pop if fields.last == '*'
+          fields.join(' ')
+        else
+          source
+        end
+      end
+
+      # Handles nth weekday specifications like "MON#2"
+      def nth_weekday_spec
+        tokens = @source.split(/\s+/)
+        minute, hour, _dom, month, dow = tokens.length == 5 ? tokens[0..4] : tokens[1..5]
+
+        # Normalize month field to handle abbreviations
+        normalized_month = normalize_month_field(month)
+
+        normalized_dow = normalize_weekday_in_nth_spec(dow, is_aws: true)
+        match = normalized_dow.match(NTH_WEEKDAY_REGEX)
+
+        weekday_num = match[:weekday].to_i
+        is_aws = @original_source.start_with?('cron(')
+
+        # Convert weekday number to Ruby format (0-6, where 0=Sunday)
+        weekday_ruby = if is_aws
+                         # AWS CRON: 1=Sunday, 2=Monday, ..., 7=Saturday
+                         weekday_num - 1
+                       else
+                         # Standard CRON: 0=Sunday, 1=Monday, ..., 6=Saturday, 7=Sunday
+                         weekday_num == 7 ? 0 : weekday_num
+                       end
+
+        {
+          minute: parse_simple_field(minute, 0..59),
+          hour: parse_simple_field(hour, 0..23),
+          month: parse_simple_field(normalized_month, 1..12),
+          weekday: weekday_ruby,
+          occurrence: match[:occurrence].to_i
+        }
+      end
+
+      # Handles last weekday specifications like "FRIL"
+      def last_weekday_spec
+        tokens = @source.split(/\s+/)
+        minute, hour, _dom, month, dow = tokens.length == 5 ? tokens[0..4] : tokens[1..5]
+
+        # Normalize month field to handle abbreviations
+        normalized_month = normalize_month_field(month)
+
+        normalized_dow = normalize_weekday_in_last_spec(dow)
+        match = normalized_dow.match(LAST_WEEKDAY_REGEX)
+
+        weekday_aws = match[:weekday].to_i
+        is_aws = @original_source.start_with?('cron(')
+        weekday_ruby = if is_aws
+                         weekday_aws - 1
+                       else
+                         (weekday_aws == 7 ? 6 : weekday_aws)
+                       end
+
+        {
+          minute: parse_simple_field(minute, 0..59),
+          hour: parse_simple_field(hour, 0..23),
+          month: parse_simple_field(normalized_month, 1..12),
+          weekday: weekday_ruby
+        }
+      end
+
+      # Finds the day of month for the nth occurrence of a weekday in a month
+      def find_nth_weekday_in_month(year, month, target_weekday, occurrence)
+        date = Date.new(year, month, 1)
+        end_of_month = Date.new(year, month, -1)
+        count = 0
+
+        while date <= end_of_month
+          count += 1 if date.wday == target_weekday
+          return date.day if count == occurrence
+
+          date = date.next_day
+        end
+        nil
+      end
+
+      # Finds the weekday closest to a target day in a given month
+      def find_weekday_closest_to(target_day, year, month)
+        target_date = Date.new(year, month, target_day)
+        target_wday = target_date.wday
+
+        if (1..5).cover?(target_wday)
+          return [target_day]
+        end
+
+        closest_day = nil
+        min_distance = Float::INFINITY
+
+        (-3..3).each do |offset|
+          next if offset.zero?
+
+          candidate_day = target_day + offset
+          next if candidate_day < 1 || candidate_day > Date.new(year, month, -1).day
+
+          candidate_date = Date.new(year, month, candidate_day)
+          candidate_wday = candidate_date.wday
+
+          next unless (1..5).cover?(candidate_wday)
+
+          distance = offset.abs
+          if distance < min_distance
+            min_distance = distance
+            closest_day = candidate_day
+          end
+        end
+
+        closest_day ? [closest_day] : [target_day]
+      end
+
+      # Finds the last occurrence of a weekday in a month
+      def find_last_weekday_in_month(year, month, target_weekday)
+        date = Date.new(year, month, -1)
+        while date.day >= 1
+          return date.day if date.wday == target_weekday
+
+          date = date.prev_day
+        end
+        nil
+      end
+
+      # Calculates the next occurrence of the nth weekday
+      def calculate_next_nth_weekday(now)
+        spec = nth_weekday_spec
+        current_time = ensure_time(now)
+        search_date = current_time
+
+        120.times do
+          month = search_date.month
+          year = search_date.year
+
+          if spec[:month].include?(month)
+            nth_day = find_nth_weekday_in_month(year, month, spec[:weekday], spec[:occurrence])
+            if nth_day
+              result = try_times(year, month, nth_day, spec, current_time)
+              return result if result
+            end
+          end
+
+          search_date = next_month_start(search_date)
+        end
+
+        raise 'No occurrence found within 120 months'
+      end
+
+      # Calculates the next occurrence of the last weekday
+      def calculate_next_last_weekday(now)
+        spec = last_weekday_spec
+        current_time = ensure_time(now)
+        search_date = current_time
+
+        120.times do
+          month = search_date.month
+          year = search_date.year
+
+          if spec[:month].include?(month)
+            last_day = find_last_weekday_in_month(year, month, spec[:weekday])
+            if last_day
+              result = try_times(year, month, last_day, spec, current_time)
+              return result if result
+            end
+          end
+
+          search_date = next_month_start(search_date)
+        end
+
+        raise 'No occurrence found within 120 months'
+      end
+
+      # Calculates the next occurrence considering only weekdays
+      def calculate_next_weekday_only(now)
+        tokens = @source.split(/\s+/)
+        minute, hour, _dom, month, dow = tokens.length == 5 ? tokens[0..4] : tokens[1..5]
+
+        minutes = parse_simple_field(minute, 0..59)
+        hours = parse_simple_field(hour, 0..23)
+        months = parse_simple_field(month, 1..12)
+        weekdays = parse_dow_field(dow)
+
+        current_time = ensure_time(now)
+        search_date = current_time
+
+        365.times do
+          month_num = search_date.month
+          year = search_date.year
+
+          if months.include?(month_num)
+            last_day = Date.new(year, month_num, -1).day
+            start_day = search_date.month == month_num && search_date.year == year ? search_date.day : 1
+            (start_day..last_day).each do |day|
+              candidate_date = Date.new(year, month_num, day)
+              aws_wday = candidate_date.wday + 1
+
+              if weekdays.include?(aws_wday)
+                result = try_times(year, month_num, day, { minute: minutes, hour: hours }, current_time)
+                return result if result
+              end
+            end
+          end
+
+          search_date = next_month_start(search_date)
+        end
+
+        raise 'No occurrence found within 365 days'
+      end
+
+      # Calculates the next occurrence of day-only specifications
+      def calculate_next_day_only(now)
+        tokens = @source.split(/\s+/)
+        minute, hour, dom, month, _dow = tokens.length == 5 ? tokens[0..4] : tokens[1..5]
+
+        minutes = parse_simple_field(minute, 0..59)
+        hours = parse_simple_field(hour, 0..23)
+        months = parse_simple_field(month, 1..12)
+
+        current_time = ensure_time(now)
+        search_date = current_time
+
+        365.times do
+          month_num = search_date.month
+          year = search_date.year
+
+          if months.include?(month_num)
+            last_day = Date.new(year, month_num, -1).day
+            days = if dom == 'L'
+                     [last_day]
+                   elsif dom.match?(/\d+W/)
+                     day_num = dom.match(/(\d+)W/)[1].to_i
+                     find_weekday_closest_to(day_num, year, month_num)
+                   else
+                     parse_simple_field(dom, 1..31)
+                   end
+
+            days.each do |day_num|
+              next if day_num > last_day
+
+              result = try_times(year, month_num, day_num, { minute: minutes, hour: hours }, current_time)
+              return result if result
+            end
+          end
+
+          search_date = next_month_start(search_date)
+        end
+
+        raise 'No occurrence found within 365 days'
+      end
+
+      # Calculates the next occurrence using standard CRON parsing
+      def calculate_next_standard(now)
+        tokens = @source.split(/\s+/)
+        if tokens.length == 6
+          second, minute, hour, dom, month, dow = tokens
+          seconds = parse_simple_field(second, 0..59)
+        else
+          minute, hour, dom, month, dow = tokens[0..4]
+          seconds = [0]
+        end
+
+        minutes = parse_simple_field(minute, 0..59)
+        hours = parse_simple_field(hour, 0..23)
+        days = parse_simple_field(dom, 1..31)
+        months = parse_simple_field(month, 1..12)
+        weekdays = parse_dow_field(dow)
+
+        current_time = ensure_time(now)
+        search_date = current_time
+
+        # If year field is specified, start from that year
+        if @year_field
+          target_year = @year_field.to_i
+          if current_time.year < target_year
+            # Jump to the target year start
+            search_date = Date.new(target_year, 1, 1).to_time(current_time.zone)
+          end
+          # For expressions with year, search 10 years ahead
+          search_limit = 3650
+        else
+          search_limit = 365
+        end
+
+        search_limit.times do
+          month_num = search_date.month
+          year = search_date.year
+
+          if months.include?(month_num)
+            last_day = Date.new(year, month_num, -1).day
+            start_day = search_date.month == month_num && search_date.year == year ? search_date.day : 1
+
+            (start_day..last_day).each do |day|
+              candidate_date = Date.new(year, month_num, day)
+
+              next unless days.include?(day)
+
+              if weekdays != (0..6).to_a
+                aws_wday = candidate_date.wday + 1
+                next unless weekdays.include?(aws_wday)
+              end
+
+              result = try_times(year, month_num, day, { second: seconds, minute: minutes, hour: hours }, current_time)
+              return result if result
+            end
+          end
+
+          search_date = next_month_start(search_date)
+        end
+
+        raise 'No occurrence found within search limit'
+      end
+
+      # Tries all time combinations for a given day
+      def try_times(year, month, day, spec, current_time)
+        seconds = spec[:second] ? Array(spec[:second]) : [0]
+        seconds.each do |second|
+          Array(spec[:hour]).each do |hour|
+            Array(spec[:minute]).each do |minute|
+              # Create candidate time, preserving the timezone of current_time
+              candidate = if current_time.utc?
+                            # If current_time is UTC, create UTC time
+                            ::Time.utc(year, month, day, hour, minute, second)
+                          elsif current_time.respond_to?(:zone) && Time.respond_to?(:zone)
+                            ::Time.zone.local(year, month, day, hour, minute, second)
+                          else
+                            @time_source.local(year, month, day, hour, minute, second)
+                          end
+
+              # Compare moments in time using UTC for consistency
+              return candidate if candidate.utc > current_time.utc
+            end
+          end
+        end
+        nil
+      end
+
+      # Expansions use this parser's AWS day-of-week numbering (1=SUN..7=SAT),
+      # not the standard CRON one (0=SUN), so @weekly says SUN rather than 0.
+      def expand_macro(macro)
+        case macro
+        when 'yearly'
+          '0 0 1 1 *'
+        when 'monthly'
+          '0 0 1 * *'
+        when 'weekly'
+          '0 0 * * SUN'
+        when 'daily'
+          '0 0 * * *'
+        when 'hourly'
+          '0 * * * *'
+        else
+          raise ArgumentError, "Unknown macro: @#{macro}"
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/parsers/aws_rate.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Parsers
+    class AWSRate < Base
+      def initialize(source, time_source = Time)
+        super(source, time_source)
+
+        match = source.match(RATE_REGEX)
+        raise ArgumentError, "Invalid rate format: #{source}" unless match
+
+        value = match[1].to_i
+        unit = match[2].downcase
+        unit = unit.chomp('s') if unit.end_with?('s')
+
+        raise ArgumentError, "Rate value must be positive: #{value}" if value <= 0
+
+        @rate = { value: value, unit: unit }
+      end
+
+      def next(now = @time_source.now)
+        current_time = ensure_time(now)
+        seconds_to_add = case @rate[:unit]
+                         when 'minute' then @rate[:value] * 60
+                         when 'hour' then @rate[:value] * 3600
+                         when 'day' then @rate[:value] * 86_400
+                         else raise ArgumentError, "Unknown rate unit: #{@rate[:unit]}"
+                         end
+        current_time + seconds_to_add.seconds
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/parsers/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Parsers
+    class Base
+      include AWSCronParser::Helpers
+
+      attr_reader :original_source, :time_source, :source, :time_zone
+
+      def initialize(source, time_source = Time)
+        @original_source = source
+        @time_source = time_source
+        @time_zone = time_source.respond_to?(:zone) ? time_source.zone : :utc
+        @source = source
+      end
+
+      def next(...) = raise NotImplementedError, 'This method should be implemented in a subclass'
+      def last(...) = raise NotImplementedError, 'This method should be implemented in a subclass'
+    end
+  end
+end

data/lib/aws_cron_parser/parsers/quartz_cron.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Parsers
+    class QuartzCron < Base
+      delegate :next, :last, to: :@fugit_adapter
+
+      def initialize(source, time_source = Time)
+        super(source, time_source)
+
+        # Initialize FugitAdapter for standard CRON parsing
+        # FugitAdapter handles:
+        # - Normalization (? → *, etc.)
+        # - Validation (field count, ranges, special chars)
+        # - Calculation of next/last occurrences
+        # - Timezone handling
+        @fugit_adapter = FugitAdapter.new(@source, time_source)
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  class Validator
+    include AWSCronParser::Helpers
+
+    def self.validate(source)
+      raise ArgumentError, 'CRON expression cannot be blank' if source.nil? || source.strip.empty?
+
+      trimmed = source.strip
+
+      if RATE_REGEX.match?(trimmed)
+        return AWSCronParser::Validators::AWSRateValidator.validate(trimmed)
+      end
+
+      if MACRO_REGEX.match?(trimmed)
+        return AWSCronParser::Validators::AWSMacroValidator.validate(trimmed)
+      end
+
+      if AT_REGEX.match?(trimmed)
+        return AWSCronParser::Validators::AWSAtValidator.validate(trimmed)
+      end
+
+      if trimmed.start_with?('cron(')
+        return AWSCronParser::Validators::AWSCronValidator.validate(trimmed)
+      end
+
+      AWSCronParser::Validators::QuartzCronValidator.validate(trimmed)
+    end
+  end
+end

data/lib/aws_cron_parser/validators/aws_at_validator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    # Validates AWS one-time schedules: at(yyyy-MM-ddThh:mm:ss)
+    class AWSAtValidator < Base
+      DATE_TIME_FORMAT = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\z/
+
+      def validate
+        match = source.match(AT_REGEX)
+        raise ArgumentError, 'Invalid at expression' unless match
+
+        date_time = match[:datetime].strip
+        parts = date_time.match(DATE_TIME_FORMAT)
+        raise ArgumentError, "Invalid at date-time: expected yyyy-MM-ddThh:mm:ss, got #{date_time}" unless parts
+
+        year, month, day, hour, minute, second = parts.captures.map(&:to_i)
+
+        # Date.parse would roll 2025-02-30 forward into March instead of failing.
+        raise ArgumentError, "Invalid at date: #{date_time}" unless Date.valid_date?(year, month, day)
+
+        raise ArgumentError, "Invalid at time: #{date_time}" unless hour <= 23 && minute <= 59 && second <= 59
+
+        true
+      end
+    end
+  end
+end