aws-cron-parser 0.1.0

data/lib/aws_cron_parser/validators/aws_cron_validator.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    class AWSCronValidator < Base
+      def validate
+        validate_aws_cron
+
+        true
+      end
+
+      private
+
+      # Override method inherited from Helpers::CronExpression
+      def normalize_source(source)
+        normalized = super(source)
+
+        # Handle 6-field standard with seconds by dropping seconds, to make range validation easier
+        tokens = normalized.split(/\s+/)
+        if tokens.length == 6 && tokens.none? { |t| t.include?('?') }
+          normalized = tokens[1..5].join(' ')
+        end
+
+        normalized
+      end
+
+      def validate_aws_cron
+        fields = validate_cron_wrapper_format(source)
+
+        # Pull out fields (with/without seconds)
+        if fields.length == 6
+          minute, hour, dom, month, dow, _year = fields
+        else
+          _second, minute, hour, dom, month, dow, _year = fields
+        end
+
+        # Check for invalid modifiers in day-of-month field
+        if dom&.include?('#')
+          raise ArgumentError, 'day-of-month field cannot contain # (only day-of-week can)'
+        end
+
+        # Validate ranges for minute, hour, month
+        validate_range(minute, 0..59, 'minute')
+        validate_range(hour, 0..23, 'hour')
+        validate_range(normalize_month_field(month), 1..12, 'month')
+
+        # Special patterns: nth weekday (#) and last weekday (L)
+        if dow&.include?('#')
+          validate_special_cron(source, 'nth')
+        elsif dow&.include?('L')
+          validate_special_cron(source, 'last')
+        else
+          # Validate weekday_only/day_only constraints
+          validate_special_cron(source, 'pattern')
+        end
+      end
+
+      def validate_cron_wrapper_format(source)
+        return nil unless (cron_match = source.match(AWS_CRON_REGEX))
+
+        content = cron_match[:expression].strip
+        fields = content.split(/\s+/)
+
+        raise ArgumentError, "cron() requires 6 or 7 fields, got #{fields.length}" unless [6, 7].include?(fields.length)
+
+        # AWS rule: ? cannot be used in both day-of-month and day-of-week
+        # Fields order within cron(): [second] minute hour day-of-month month day-of-week year
+        # For 6 fields: minute hour day-of-month month day-of-week year (no seconds)
+        day_of_month = fields.length == 6 ? fields[2] : fields[3]
+        day_of_week  = fields.length == 6 ? fields[4] : fields[5]
+        if day_of_month == '?' && day_of_week == '?'
+          raise ArgumentError, '? can only be used in one of day-of-month or day-of-week fields'
+        end
+
+        year_field = fields[-1]
+        raise ArgumentError, 'Year cannot have L, #, or W' if /[L#W]/.match?(year_field)
+
+        unless /^\*$|^\d+$|^\d+-\d+$|^\d+,\d+$/.match?(year_field)
+          raise ArgumentError, 'Year must be *, number, range, or list'
+        end
+
+        fields
+      end
+
+      def validate_special_cron(source, type)
+        tokens = normalize_source(source).split(/\s+/)
+        raise ArgumentError, 'Invalid CRON expression' unless (5..6).cover?(tokens.length)
+
+        minute, hour, dom, month, dow = tokens.length == 5 ? tokens[0..4] : tokens[1..5]
+
+        # For non-AWS expressions with special chars, validate ? usage
+        unless source.start_with?('cron(')
+          invalid_q_mark = false
+          [minute, hour, month].each do |field|
+            invalid_q_mark = true if field.include?('?')
+          end
+          if dom.include?('?') && !dow.match?(/[L#]/)
+            invalid_q_mark = true
+          end
+          invalid_q_mark = true if dow.include?('?')
+
+          raise ArgumentError, '? is not valid in standard CRON expressions' if invalid_q_mark
+        end
+
+        if source.start_with?('cron(') && dom == '?' && dow == '?'
+          raise ArgumentError, '? can only be used in one of day-of-month or day-of-week fields'
+        end
+
+        case type
+        when 'nth'
+          raise ArgumentError, 'day-of-month must be ? or *' unless ['?', '*'].include?(dom)
+
+          normalized = normalize_weekday_in_nth_spec(dow, is_aws: true)
+          match = normalized.match(NTH_WEEKDAY_REGEX)
+          raise ArgumentError, "Invalid nth weekday: #{dow}" unless match
+
+          weekday_num = match[:weekday].to_i
+          occurrence_num = match[:occurrence].to_i
+          # Allow 0..7 to be tolerant with sources that use 0 for Sunday; AWS uses 1..7, standard may use 0 or 7.
+          raise ArgumentError, "weekday must be 0-7, got #{weekday_num}" unless (0..7).cover?(weekday_num)
+          raise ArgumentError, "occurrence must be 1-5, got #{occurrence_num}" unless (1..5).cover?(occurrence_num)
+        when 'last'
+          raise ArgumentError, 'day-of-month must be ? or *' unless ['?', '*'].include?(dom)
+
+          normalized = normalize_weekday_in_last_spec(dow)
+          match = normalized.match(LAST_WEEKDAY_REGEX)
+          raise ArgumentError, "Invalid last weekday: #{dow}" unless match
+
+          weekday_num = match[:weekday].to_i
+          raise ArgumentError, "weekday must be 0-7, got #{weekday_num}" unless (0..7).cover?(weekday_num)
+        when 'pattern'
+          raise ArgumentError, 'day-of-month must be ?' if weekday_only?(source) && dom != '?'
+          raise ArgumentError, 'day-of-week must be ?' if day_only?(source) && dow != '?'
+        end
+
+        validate_range(minute, 0..59, 'minute')
+        validate_range(hour, 0..23, 'hour')
+        validate_range(normalize_month_field(month), 1..12, 'month')
+
+        # Validate weekday range based on CRON format (skip validation for special patterns)
+        # Skip if the dow field contains special modifiers (L, #, W) as they're already validated above
+        unless dow.match?(/[L#W]/)
+          weekday_range = source.start_with?('cron(') ? 1..7 : 0..6
+          validate_range(normalize_weekday_field(dow, is_aws: true), weekday_range, 'day-of-week')
+        end
+
+        true
+      end
+
+      def validate_range(field, range, name)
+        return if ['*', '?'].include?(field)
+
+        # Handle step syntax like "*/5" or "0/5"
+        if field.include?('/')
+          start, step = field.split('/', 2)
+          raise ArgumentError, "Invalid step syntax: #{field}" unless start && step
+
+          # Validate start value if it's not '*' or a range
+          unless start == '*' || start.include?('-') || start.include?(',')
+            raise ArgumentError, "Invalid start value in step: #{start}" unless start.match?(/^\d+$/)
+
+            start_val = start.to_i
+            raise ArgumentError, "#{name} start value #{start_val} out of range" unless range.include?(start_val)
+          end
+
+          # Validate step value
+          raise ArgumentError, "Invalid step value: #{step}" unless step.match?(/^\d+$/)
+
+          step_val = step.to_i
+          raise ArgumentError, "Step value must be positive, got #{step_val}" unless step_val.positive?
+
+          return
+        end
+
+        # Handle ranges like "1-5"
+        if field.include?('-')
+          start_str, end_str = field.split('-', 2)
+          raise ArgumentError, "Invalid range syntax: #{field}" unless start_str && end_str
+
+          start_val = start_str.to_i
+          end_val = end_str.to_i
+          raise ArgumentError, "#{name} range start #{start_val} out of range" unless range.include?(start_val)
+          raise ArgumentError, "#{name} range end #{end_val} out of range" unless range.include?(end_val)
+
+          # Allow reverse ranges for permissiveness
+
+          return
+        end
+
+        # Handle lists like "1,3,5"
+        if field.include?(',')
+          values = field.split(',')
+          values.each do |value_str|
+            next if value_str.strip.empty?
+            raise ArgumentError, "Invalid list value: #{value_str}" unless value_str.match?(/^\d+$/)
+
+            value = value_str.to_i
+            raise ArgumentError, "#{name} #{value} out of range" unless range.include?(value)
+          end
+
+          return
+        end
+
+        # Handle simple numeric values
+        return unless field.match?(/^\d+$/)
+
+        value = field.to_i
+        raise ArgumentError, "#{name} #{value} out of range" unless range.include?(value)
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/validators/aws_macro_validator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    class AWSMacroValidator < Base
+      def validate
+        raise ArgumentError, 'Invalid macro expression' unless MACRO_REGEX.match?(source)
+
+        true
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/validators/aws_rate_validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    class AWSRateValidator < Base
+      def validate
+        match = source.match(RATE_REGEX)
+        raise ArgumentError, 'Invalid rate expression' unless match
+
+        value = match[1].to_i
+        raise ArgumentError, 'Rate value must be positive' if value <= 0
+
+        true
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/validators/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    class Base
+      include AWSCronParser::Helpers
+
+      attr_reader :source
+
+      def initialize(source)
+        @source = source
+      end
+
+      def self.validate(source)
+        new(source).validate
+      end
+
+      def validate
+        raise NotImplementedError, 'This method should be implemented in a subclass'
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/validators/quartz_cron_validator.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Validators
+    class QuartzCronValidator < Base
+      def validate
+        parts = @source.split
+
+        # Validate field count (5 or 6 fields)
+        unless (5..6).cover?(parts.length)
+          raise ArgumentError, "Invalid CRON format: expected 5 or 6 fields, got #{parts.length}"
+        end
+
+        # Define field ranges and names
+        field_ranges = if parts.length == 6
+                         [{ min: 0, max: 59, name: 'second' },
+                          { min: 0, max: 59, name: 'minute' },
+                          { min: 0, max: 23, name: 'hour' },
+                          { min: 1, max: 31, name: 'day-of-month' },
+                          { min: 1, max: 12, name: 'month' },
+                          { min: 0, max: 7, name: 'day-of-week' }]
+                       else
+                         [{ min: 0, max: 59, name: 'minute' },
+                          { min: 0, max: 23, name: 'hour' },
+                          { min: 1, max: 31, name: 'day-of-month' },
+                          { min: 1, max: 12, name: 'month' },
+                          { min: 0, max: 7, name: 'day-of-week' }]
+                       end
+
+        # Check for AWS-specific characters and validate ranges
+        aws_chars = %w[L W # ?]
+        parts.each_with_index do |field, index|
+          range_info = field_ranges[index]
+          field_name = range_info[:name]
+
+          # Normalize month and weekday fields before validation
+          normalized_field = if field_name == 'month'
+                               normalize_month_field(field)
+                             elsif field_name == 'day-of-week'
+                               normalize_weekday_field(field, is_aws: false)
+                             else
+                               field
+                             end
+
+          # Check for AWS-specific characters
+          aws_chars.each do |char|
+            next unless field.include?(char)
+
+            msg = "#{field_name} field cannot contain '#{char}'. " \
+                  'Use cron() wrapper for AWS expressions.'
+            raise ArgumentError, msg
+          end
+
+          # Validate numeric values in ranges (simple check for obvious errors)
+          validate_field_values(normalized_field, range_info)
+        end
+
+        # Use FugitAdapter for comprehensive validation
+        AWSCronParser::FugitAdapter.new(@source)
+        true
+      rescue ArgumentError => e
+        raise ArgumentError, e.message
+      end
+
+      private
+
+      # Validate individual numeric values in a field
+      def validate_field_values(field, range_info)
+        return if ['*', '?'].include?(field) # Wildcard/question mark is always valid
+
+        min_val = range_info[:min]
+        max_val = range_info[:max]
+        field_name = range_info[:name]
+
+        # Parse and validate each value (simple approach, let fugit handle complex cases)
+        field.split(',').each do |part|
+          part = part.strip
+          next if part.empty?
+
+          # Check for step of 0 (will cause ZeroDivisionError in fugit)
+          if part.include?('/')
+            step_parts = part.split('/')
+            step_val = step_parts[-1].to_i
+
+            raise ArgumentError, "Step value must be positive, got #{step_val}" if step_val.zero?
+
+            # For ranges like "1-30/0", also check if start is in range
+            if step_parts[0].include?('-')
+              range_start, range_end = step_parts[0].split('-').map(&:to_i)
+              unless (min_val..max_val).cover?(range_start)
+                raise ArgumentError, "#{field_name} #{range_start} out of range"
+              end
+
+              unless (min_val..max_val).cover?(range_end)
+                raise ArgumentError, "#{field_name} #{range_end} out of range"
+              end
+            elsif step_parts[0] != '*' && step_parts[0] != '?'
+              start_val = step_parts[0].to_i
+              unless (min_val..max_val).cover?(start_val)
+                raise ArgumentError, "#{field_name} #{start_val} out of range"
+              end
+            end
+
+            next
+          end
+
+          # Handle ranges like "1-5"
+          if part.include?('-')
+            range_start, range_end = part.split('-').map(&:to_i)
+            unless (min_val..max_val).cover?(range_start)
+              raise ArgumentError, "#{field_name} #{range_start} out of range"
+            end
+
+            unless (min_val..max_val).cover?(range_end)
+              raise ArgumentError, "#{field_name} #{range_end} out of range"
+            end
+
+            next
+          end
+
+          # Single numeric value
+          val = part.to_i
+          next if val.zero? && part != '0' # Not a number, fugit will catch it
+
+          unless (min_val..max_val).cover?(val)
+            raise ArgumentError, "#{field_name} #{val} out of range"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/version.rb

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

data/lib/aws_cron_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'set'
+require 'yaml'
+require 'fugit'
+require 'zeitwerk'
+# The whole core_ext set, not a hand-picked subset: this code was extracted from
+# a Rails app and leans on blank?/present?/exclude?/delegate/durations/Time.zone
+# across paths the suite does not all cover. The AS framework itself stays out.
+require 'active_support'
+require 'active_support/core_ext'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  'aws_cron_parser' => 'AWSCronParser',
+  'aws_at' => 'AWSAt',
+  'aws_cron' => 'AWSCron',
+  'aws_rate' => 'AWSRate',
+  'aws_at_validator' => 'AWSAtValidator',
+  'aws_cron_validator' => 'AWSCronValidator',
+  'aws_macro_validator' => 'AWSMacroValidator',
+  'aws_rate_validator' => 'AWSRateValidator'
+)
+loader.ignore("#{__dir__}/aws_cron_parser/version.rb")
+loader.setup
+
+require_relative 'aws_cron_parser/version'
+
+# ActiveSupport leaves Time.zone nil until a host application sets it, and the
+# parsers build zone-aware times. Default it to UTC so the gem works outside
+# Rails; Rails' own time zone initializer runs later and overrides this.
+Time.zone_default ||= ActiveSupport::TimeZone['UTC']
+
+module AWSCronParser
+  def self.new(expression, time_source = Time)
+    Parser.new(expression, time_source)
+  end
+
+  def self.parse(...)
+    new(...)
+  end
+end
+
+# Exposed so hosts that boot eagerly (or the test suite) can force every
+# constant to resolve instead of discovering a bad autoload path at runtime.
+AWSCronParser::LOADER = loader
+

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: aws-cron-parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Washington Silva
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |-
+  AWSCronParser parses the scheduling expressions accepted by AWS EventBridge and
+  Systems Manager - cron(...) with 6 fields, rate(...), @macros and at(...) - as well
+  as Quartz and standard 5-field CRON. It computes next/previous occurrences, validates
+  expressions with actionable error messages, and renders them as English descriptions
+  such as "Every weekday at 9:00 AM".
+email:
+- washington.silva@skie.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/aws_cron_parser.rb
+- lib/aws_cron_parser/describer.rb
+- lib/aws_cron_parser/describer/cron_composer.rb
+- lib/aws_cron_parser/describer/day_composer.rb
+- lib/aws_cron_parser/describer/field_describers/base.rb
+- lib/aws_cron_parser/describer/field_describers/day_of_month.rb
+- lib/aws_cron_parser/describer/field_describers/day_of_week.rb
+- lib/aws_cron_parser/describer/field_describers/month.rb
+- lib/aws_cron_parser/describer/field_describers/time_field.rb
+- lib/aws_cron_parser/describer/month_composer.rb
+- lib/aws_cron_parser/describer/template.en.yml
+- lib/aws_cron_parser/describer/template.rb
+- lib/aws_cron_parser/describer/time_composer.rb
+- lib/aws_cron_parser/fugit_adapter.rb
+- lib/aws_cron_parser/helpers.rb
+- lib/aws_cron_parser/helpers/calendar.rb
+- lib/aws_cron_parser/helpers/clock.rb
+- lib/aws_cron_parser/helpers/cron_expression.rb
+- lib/aws_cron_parser/helpers/numbers.rb
+- lib/aws_cron_parser/parser.rb
+- lib/aws_cron_parser/parsers/aws_at.rb
+- lib/aws_cron_parser/parsers/aws_cron.rb
+- lib/aws_cron_parser/parsers/aws_rate.rb
+- lib/aws_cron_parser/parsers/base.rb
+- lib/aws_cron_parser/parsers/quartz_cron.rb
+- lib/aws_cron_parser/validator.rb
+- lib/aws_cron_parser/validators/aws_at_validator.rb
+- lib/aws_cron_parser/validators/aws_cron_validator.rb
+- lib/aws_cron_parser/validators/aws_macro_validator.rb
+- lib/aws_cron_parser/validators/aws_rate_validator.rb
+- lib/aws_cron_parser/validators/base.rb
+- lib/aws_cron_parser/validators/quartz_cron_validator.rb
+- lib/aws_cron_parser/version.rb
+homepage: https://github.com/w-osilva/aws-cron-parser
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/w-osilva/aws-cron-parser
+  changelog_uri: https://github.com/w-osilva/aws-cron-parser/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Parser, validator and human-readable describer for AWS, Quartz and standard
+  CRON expressions
+test_files: []