aws-cron-parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0284e39612c4ce6c3f6a32d9f0c296d95db41827b0f9cb61a1e384c6bd81480d'
+  data.tar.gz: 4f769078b37d559c1db706aeb1b02e99c9f88d879bb2ebe93cec135f4c381170
+SHA512:
+  metadata.gz: 1f86462e91dfff10b4a9b18376572361e523a5d981ca11bd898e65a4cc4d1d2e3e4126e379114142ec9f721456b3fa98d42080bd8f19760bf33c20b76f2ca91b
+  data.tar.gz: 98ef95a962a5b3bcbcd4cc90ef20c6541b3185659d2f215991d4d75b9ac4f721616cd33508997dceba5aa4537606af519cc556b6324b798ca9eb135e0d2e46d1

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0]
+
+Extracted from an internal Rails application into a standalone gem. Autoloading
+runs through the gem's own Zeitwerk loader and Rails is no longer required.
+
+Fixed while extracting, all of which the inherited suite passed straight through:
+
+- AWS weekday numbers were described one day off. The parser matches on
+  `1=SUN..7=SAT` but the describer named `1` Monday, so `cron(0 9 ? * 2 *)` ran on
+  Monday while reporting Tuesday.
+- `Helpers::Time` shadowed `::Time` for every class including `Helpers`, since a
+  bare `Time` resolves through the ancestor chain. `Parser.new(expr).next` raised
+  `NoMethodError`, and `Describer` silently returned nil for `at(...)`. The module
+  is now `Helpers::Clock`.
+- `@daily` and the other macros validated and described correctly but raised
+  `NotImplementedError` on `next`: the expansion was computed and discarded, and
+  `@weekly` expanded to standard CRON's `0=SUN` which this parser never matches.
+- A day-of-week given as a bare name described as "day 0" — `FRI` was run through
+  `to_i`. Ranges and lists were unaffected.
+- Month names described as "month January", from a double-applied formatter.
+- `*/N` was rejected in the month and day-of-week fields, the two that also
+  resolve names: the `*` was passed to the abbreviation lookup. Past that, the
+  AWS day-of-week field had no step expansion, so `cron(0 9 ? * */2 *)` searched
+  a year of candidates and failed with a bare `RuntimeError`.
+- Standard CRON spells Sunday 0 or 7; `0 9 * * 7` described as "day 7".
+- `at(...)` was unreachable: the expression had a describer branch and a regex but
+  no validator or parser, so it was rejected before reaching them. It is now
+  supported end to end, including a `next` that stops once the instant passes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Washington Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated software documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# aws-cron-parser
+
+[![CI](https://github.com/w-osilva/aws-cron-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/w-osilva/aws-cron-parser/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/aws-cron-parser.svg)](https://rubygems.org/gems/aws-cron-parser)
+
+Parse, validate and describe the scheduling expressions accepted by AWS EventBridge and
+Systems Manager, plus Quartz and standard 5-field CRON.
+
+- **AWS cron** — `cron(0 9 ? * MON-FRI *)`, 6 fields, `?` / `L` / `W` / `#`, weekdays `1=SUN..7=SAT`
+- **AWS rate** — `rate(5 minutes)`, `rate(1 day)`
+- **AWS at** — `at(2025-06-15T10:30:00)`, a one-time schedule
+- **Standard / Quartz cron** — `0 9 * * 1-5`, `*/10 * * * *`, 6-field with seconds
+- **Macros** — `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`
+
+No Rails required. The gem autoloads through its own Zeitwerk loader.
+
+## Installation
+
+```ruby
+gem 'aws-cron-parser'
+```
+
+```ruby
+require 'aws_cron_parser'
+```
+
+## Usage
+
+```ruby
+parser = AWSCronParser.parse('cron(0 9 ? * MON-FRI *)')
+
+parser.describe    # => "Every Monday through Friday at 9 AM"
+parser.expression  # => "cron(0 9 ? * MON-FRI *)"
+parser.source      # => "0 9 ? * MON-FRI"
+```
+
+### Next and previous occurrences
+
+```ruby
+now = Time.utc(2025, 1, 15, 10, 30)
+parser = AWSCronParser.parse('0 9 * * 1-5')
+
+parser.next(now)          # => 2025-01-16 09:00:00 UTC
+parser.last(now)          # => 2025-01-15 09:00:00 UTC
+parser.next_runs(3, now)  # => [2025-01-16 09:00, 2025-01-17 09:00, 2025-01-20 09:00]
+```
+
+`next_unique_dates(count, from)` and `next_unique_hours(count, from)` collapse repeated
+executions down to one entry per day or per hour — useful when rendering a schedule preview.
+
+`last` is only available for standard/Quartz expressions; AWS `cron(...)`, `rate(...)`
+and `at(...)` raise `ArgumentError`, since they are anchored forwards in time.
+
+### One-time schedules
+
+`at(...)` fires exactly once. `next` returns the instant while it is still ahead and
+`nil` once it has passed, so `next_runs` yields at most one entry:
+
+```ruby
+parser = AWSCronParser.parse('at(2025-06-15T10:30:00)')
+
+parser.next(Time.utc(2025, 1, 1))   # => 2025-06-15 10:30:00 UTC
+parser.next(Time.utc(2026, 1, 1))   # => nil
+parser.next_runs(5, Time.utc(2025, 1, 1)).size  # => 1
+```
+
+### Weekday numbering
+
+Inside `cron(...)` weekdays follow AWS: **1 = Sunday** through 7 = Saturday. Bare
+5-field expressions follow standard CRON, where 0 and 7 are Sunday and 1 is Monday.
+`cron(0 9 ? * 1 *)` and `0 9 * * 1` are therefore different schedules.
+
+### Validation
+
+```ruby
+AWSCronParser::Validator.validate('0 9 * * 1-5')  # => true
+AWSCronParser.parse('cron(99 9 ? * MON *)')       # raises ArgumentError: minute 99 out of range
+
+parser = AWSCronParser.parse('0 9 * * 1-5')
+parser.valid?   # => true
+parser.errors   # => []
+```
+
+`AWSCronParser.parse` validates eagerly and raises `ArgumentError` with a field-level
+message. Use `valid?` / `errors` when you want to report the problem instead of raising.
+
+### Descriptions
+
+```ruby
+AWSCronParser::Describer.describe('cron(0/15 * * * ? *)')  # => "Every 15 minutes"
+AWSCronParser::Describer.describe('cron(0 0 L * ? *)')     # => "On the last day of the month at 12 AM"
+AWSCronParser::Describer.describe('cron(0 12 ? * 6#3 *)')  # => "On the third Saturday at 12 PM"
+AWSCronParser::Describer.describe('rate(5 minutes)')       # => "Every 5 minutes"
+```
+
+Wording lives in `lib/aws_cron_parser/describer/template.en.yml`.
+
+### Time zones
+
+The parsers build zone-aware times through ActiveSupport's `Time.zone`. Outside Rails the
+gem defaults it to UTC if the host has not set one; inside Rails your `config.time_zone`
+wins. You can also pass an explicit time source:
+
+```ruby
+AWSCronParser.parse('0 9 * * 1-5', Time.find_zone('America/Sao_Paulo'))
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/aws_cron_parser/describer/cron_composer.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    # Composes complete CRON descriptions from field descriptions
+    class CronComposer
+      include AWSCronParser::Helpers
+
+      attr_reader :config, :is_aws
+
+      def initialize(config)
+        @config = config
+        @is_aws = config[:type]&.start_with?('aws-cron')
+      end
+
+      def compose
+        # Handle simple patterns first
+        return quick_patterns if quick_patterns
+
+        # Build component descriptions
+        time_desc = TimeComposer.new(config, is_aws: is_aws).compose
+        day_desc = DayComposer.new(config, is_aws: is_aws).compose
+        month_desc = MonthComposer.new(config, is_aws: is_aws).compose
+
+        # Compose final description based on what's set
+        compose_description(time_desc, day_desc, month_desc)
+      end
+
+      private
+
+      def quick_patterns
+        s = config[:second]
+        m = config[:minute]
+        h = config[:hour]
+        day = config[:day]
+        dow = config[:dow]
+        month = config[:month]
+
+        # Quick patterns for common cases
+        # Standard CRON (5 fields, no seconds)
+        if s.nil? && all_wildcards?(m, h, day, dow, month)
+          return 'Every minute'
+        end
+
+        # Unix CRON with seconds (6 fields) or AWS CRON with seconds (7 fields)
+        if s.present? && all_wildcards?(s, m, h, day, dow, month)
+          return 'Every second'
+        end
+
+        # Only seconds field is set (rest are wildcards)
+        if s.present? && s != '*' && all_wildcards?(m, h, day, dow, month)
+          return nil # Let time composer handle it
+        end
+
+        # Every minute (when second is 0 or wildcard, minute is wildcard)
+        if (s.nil? || s == '*' || s == '0') && all_wildcards?(m, h, day, dow, month)
+          return 'Every minute'
+        end
+
+        # NOTE: "0 * * * *" should be "Every hour at minute 0", not just "Every hour"
+        # Let TimeComposer handle this case
+
+        nil
+      end
+
+      def all_wildcards?(*fields)
+        fields.all? { |f| wildcards?(f) }
+      end
+
+      def wildcards?(*fields)
+        fields.all? { |f| f.nil? || f == '*' || f == '?' }
+      end
+
+      def compose_description(time_desc, day_desc, month_desc)
+        # Determine which components are present
+        has_time = time_desc.present?
+        has_day = day_desc.present?
+        has_month = month_desc.present?
+
+        case [has_time, has_day, has_month]
+        when [true, false, false]
+          # Time only (day/dow/month are wildcards) = "Every day at..."
+          add_every_day(time_desc)
+        when [false, false, true]
+          month_desc
+        when [false, true, false]
+          day_desc
+        when [true, false, true]
+          compose_time_month(time_desc, month_desc)
+        when [true, true, false]
+          compose_time_day(time_desc, day_desc)
+        when [false, true, true]
+          compose_day_month(day_desc, month_desc)
+        when [true, true, true]
+          compose_all(time_desc, day_desc, month_desc)
+        else
+          'Every minute'
+        end
+      end
+
+      def add_every_day(time_desc)
+        # If time is simple "At X:XX AM/PM", "at X AM...", or "from X to Y", add "Every day" prefix
+        if time_desc.match?(/^At \d+/)
+          "Every day #{time_desc.sub(/^At /, 'at ')}"
+        elsif time_desc.match?(/^(at|from) \d+/)
+          "Every day #{time_desc}"
+        else
+          time_desc
+        end
+      end
+
+      def compose_time_month(time_desc, month_desc)
+        # Time + Month (no day): "At 12:00 AM in July"
+        "#{time_desc} #{month_desc}"
+      end
+
+      def compose_time_day(time_desc, day_desc)
+        # Day + Time (no month): "On the 1st at 6:00 PM"
+        # Capitalize day description and add "of every month" if applicable
+        day_desc = capitalize_first(day_desc)
+        day_desc = add_month_context(day_desc) if needs_month_context?(day_desc)
+
+        # Handle duplicate "Every" when both time and day start with "Every"
+        if time_desc.start_with?('Every') && day_desc.start_with?('Every')
+          # Remove "Every" from time description and make it lowercase
+          time_clean = time_desc.sub(/^Every /, 'every ')
+          "#{day_desc}, #{time_clean}"
+        elsif time_desc.start_with?('Every day') && day_desc.start_with?('Every')
+          # Remove "Every day" from time, keep time portion only
+          time_clean = time_desc.sub(/^Every day (from|at) /, '')
+          "#{day_desc} from #{time_clean}"
+        elsif time_desc.start_with?('at ')
+          # Time starts with lowercase "at" - if we have DOW, just append; otherwise add "Every day"
+          if day_desc.start_with?('Every')
+            "#{day_desc} #{time_desc}"
+          else
+            # No day context, add "Every day"
+            "Every day #{time_desc}"
+          end
+        elsif time_desc.start_with?('At ')
+          time_lower = time_desc.sub(/^At /, 'at ')
+          "#{day_desc} #{time_lower}"
+        else
+          "#{day_desc} #{time_desc}"
+        end
+      end
+
+      def compose_day_month(day_desc, month_desc)
+        # Day + Month (no specific time): "On the 1st in July"
+        "#{day_desc} #{month_desc}"
+      end
+
+      def compose_all(time_desc, day_desc, month_desc)
+        # All three: Time + Day + Month
+        # Patterns:
+        # - Special case: "On January 1st at 1:00 AM" (day 1 of month 1)
+        # - General case: "Every October on the 10th at 10:10 AM"
+
+        # Convert month from "in October" to clean form
+        month_clean = month_desc.sub(/^in /, '')
+
+        # Convert day from "on the 1st" to "1st" (remove both "on the")
+        day_clean = day_desc.sub(/^on the /, '')
+
+        # Convert time from "At 10:10 AM" or "Every day at X" to clean form
+        time_clean = time_desc.sub(/^At /, '').sub(/^Every day at /, '')
+
+        # Check if this is a special date: January 1st
+        is_january_first = month_clean == 'January' && day_clean == '1st'
+
+        if is_january_first
+          "On #{month_clean} #{day_clean} at #{time_clean}"
+        elsif month_desc.start_with?('Every')
+          # Month has step pattern like "Every 2 months starting in January"
+          "#{month_desc} on the #{day_clean} at #{time_clean}"
+        else
+          "Every #{month_clean} on the #{day_clean} at #{time_clean}"
+        end
+      end
+
+      def capitalize_first(text)
+        return text if text.blank?
+
+        text[0].upcase + text[1..]
+      end
+
+      def needs_month_context?(day_desc)
+        # Add "of every month" when describing days but month is wildcard
+        month_wildcard = wildcards?(config[:month])
+        month_wildcard && day_desc.match?(/^(on|On) the \d/)
+      end
+
+      def add_month_context(day_desc)
+        "#{day_desc} of every month"
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/day_composer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    # Composes day descriptions (day-of-month and day-of-week)
+    class DayComposer
+      include AWSCronParser::Helpers
+
+      attr_reader :day, :dow, :is_aws
+
+      def initialize(config, is_aws: false)
+        @day = config[:day]
+        @dow = config[:dow]
+        @is_aws = is_aws
+      end
+
+      def compose
+        day_wildcard = wildcards?(day)
+        dow_wildcard = wildcards?(dow)
+
+        # Both wildcards - no day description
+        return nil if day_wildcard && dow_wildcard
+
+        # Only day-of-week
+        return describe_dow if day_wildcard && !dow_wildcard
+
+        # Only day-of-month
+        return describe_day if !day_wildcard && dow_wildcard
+
+        # Both specified (AWS allows this for OR logic)
+        describe_both
+      end
+
+      private
+
+      def wildcards?(*fields)
+        fields.all? { |f| f.nil? || f == '*' || f == '?' }
+      end
+
+      def describe_day
+        FieldDescribers::DayOfMonth.new(day, is_aws: is_aws).describe
+      end
+
+      def describe_dow
+        result = FieldDescribers::DayOfWeek.new(dow, is_aws: is_aws).describe
+        return result if result.nil?
+
+        # Add "Every" prefix for day ranges and simple day names
+        # "on the" prefix means it's already formatted (like "on the 2nd Monday")
+        return result if result.start_with?('on the', 'On the', 'Every')
+
+        # For "on Monday" or "Monday through Friday" patterns, add "Every"
+        if result.start_with?('on ')
+          "Every #{result.sub('on ', '')}"
+        else
+          # For ranges like "Monday through Friday", add "Every" prefix
+          "Every #{result}"
+        end
+      end
+
+      def describe_both
+        day_desc = describe_day
+        dow_desc = FieldDescribers::DayOfWeek.new(dow, is_aws: is_aws).describe
+
+        # For AWS, both fields can be set for OR logic
+        # Example: day=1-7 dow=MON means "1st-7th when those days are Monday"
+        return nil if day_desc.nil? || dow_desc.nil?
+
+        # Simplify the composition
+        day_desc
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/field_describers/base.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    module FieldDescribers
+      # Base class for field describers - provides common pattern matching
+      class Base
+        include AWSCronParser::Helpers
+
+        STEP_PATTERN = %r{^(?:(?<base>[\d*]+)|(?<start>\d+)-(?<end>\d+))?/(?<step>\d+)$}
+        RANGE_PATTERN = /^(?<start>\d+)-(?<end>\d+)$/
+        LIST_PATTERN = /^[\d,]+$/
+
+        attr_reader :value, :is_aws
+
+        def initialize(value, is_aws: false)
+          @value = value
+          @is_aws = is_aws
+        end
+
+        def describe
+          return nil if wildcard?
+
+          # Try patterns in order of specificity
+          describe_step || describe_list || describe_range || describe_single
+        end
+
+        private
+
+        def wildcard?
+          ['*', '?', ''].include?(value)
+        end
+
+        def describe_step
+          return nil unless value.include?('/')
+
+          match = value.match(STEP_PATTERN)
+          return nil unless match
+
+          step = match[:step].to_i
+          start_val = match[:start] || match[:base]
+          end_val = match[:end]
+
+          if start_val.nil? || start_val == '*'
+            step_wildcard(step)
+          elsif end_val
+            # Range with step: 8-18/2
+            step_range(start_val.to_i, end_val.to_i, step)
+          else
+            step_from(start_val.to_i, step)
+          end
+        end
+
+        def describe_list
+          return nil unless value.include?(',') && value.match?(LIST_PATTERN)
+
+          items = value.split(',').map(&:strip).sort_by(&:to_i)
+          formatted = items.map { |v| format_value(v.to_i) }
+          list_template(formatted)
+        end
+
+        def describe_range
+          return nil unless value.match?(RANGE_PATTERN)
+
+          match = value.match(RANGE_PATTERN)
+          start_val = match[:start].to_i
+          end_val = match[:end].to_i
+
+          range_template(format_value(start_val), format_value(end_val))
+        end
+
+        def describe_single
+          single_template(format_value(value.to_i))
+        end
+
+        # Template methods - to be overridden by subclasses
+        def step_wildcard(_step)
+          raise NotImplementedError
+        end
+
+        def step_from(_start, _step)
+          raise NotImplementedError
+        end
+
+        def step_range(start_val, _end_val, step)
+          # Default: fall back to step_from if not overridden
+          step_from(start_val, step)
+        end
+
+        def list_template(_items)
+          raise NotImplementedError
+        end
+
+        def range_template(_start, _end)
+          raise NotImplementedError
+        end
+
+        def single_template(_value)
+          raise NotImplementedError
+        end
+
+        def format_value(val)
+          val
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/field_describers/day_of_month.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module AWSCronParser
+  module Describer
+    module FieldDescribers
+      # Describes day-of-month field
+      class DayOfMonth < Base
+        NTH_PATTERN = /^(\d+)#(\d+)$/
+        LAST_PATTERN = /^(\d+)?L$/
+        WEEKDAY_PATTERN = /^(\d+)W$/
+
+        def describe
+          return nil if wildcard?
+
+          # AWS-specific patterns
+          if is_aws
+            return describe_nth if value.match?(NTH_PATTERN)
+            return describe_last if value.match?(LAST_PATTERN)
+            return describe_closest_weekday if value.match?(WEEKDAY_PATTERN)
+          end
+
+          super # Use base class patterns
+        end
+
+        private
+
+        def describe_nth
+          # Not typically used for day-of-month, but handle if present
+          nil
+        end
+
+        def describe_last
+          return Template.interpolate('day_of_month.last_day') if value == 'L'
+
+          nil
+        end
+
+        def describe_closest_weekday
+          match = value.match(WEEKDAY_PATTERN)
+          day = match[1].to_i
+          Template.interpolate('day_of_month.closest_weekday', ordinal: ordinal(day))
+        end
+
+        def step_wildcard(step)
+          Template.interpolate('day_of_month.step', step: step, step_plural: Template.plural_for(step))
+        end
+
+        def step_from(start_val, step)
+          Template.interpolate('day_of_month.step_range',
+                               step: step,
+                               step_plural: Template.plural_for(step),
+                               start_ordinal: ordinal(start_val))
+        end
+
+        def list_template(items)
+          Template.interpolate('day_of_month.list', items: format_list(items))
+        end
+
+        def range_template(start_val, end_val)
+          Template.interpolate('day_of_month.range',
+                               start_ordinal: ordinal(start_val),
+                               end_ordinal: ordinal(end_val))
+        end
+
+        def single_template(val)
+          Template.interpolate('day_of_month.single', ordinal: ordinal(val))
+        end
+
+        def format_value(val)
+          ordinal(val.to_i)
+        end
+
+        def format_list(items)
+          return items.first if items.length == 1
+
+          if items.length == 2
+            items.join(' and ')
+          else
+            last = items.pop
+            "#{items.join(', ')}, and #{last}"
+          end
+        end
+      end
+    end
+  end
+end