sof-cycle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 416c2fd3c9e369ece57bafe7cbf5a58f07b9e30177c04b7253059cb87d6e32dc
+  data.tar.gz: 00fd30f51d4efb2eeabbe7eef1b8fdd58a6290a08579ae661984b2de359585e4
+SHA512:
+  metadata.gz: 582f1597715e073ea8d517b8236ad3daf81fcdf9ce023c860a77ed2ddb4847e4df027b606764915d816d7d5ddd06ec383bcae58fb0174e8e1e6f02d97265ed71
+  data.tar.gz: 8d9e747a1ac2d0a649f911f6c7de8e81dc7a8139294c41c37eb20b8d9cc67e52e5242f61df1315b74aab24127f5c0c7ea7738a9d9fc7e1130ddc94dec9de6445

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--order random

data/.simplecov

@@ -0,0 +1,4 @@
+require "simplecov"
+SimpleCov.start do
+  add_filter "/spec/"
+end

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-07-09
+
+### Added
+
+- Initial extraction

data/README.md

@@ -0,0 +1,27 @@
+# SOF::Cycle
+
+Parse and interact with SOF cycle notation.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add sof-cycle
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install sof-cycle
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/sof-cycle.

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+task default: :spec
+
+require "reissue/gem"
+
+Reissue::Task.create do |task|
+  task.version_file = "lib/sof/cycle/version.rb"
+end

data/lib/sof/cycle/parser.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../cycle"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/inclusion"
+require "active_support/core_ext/hash/reverse_merge"
+require "active_support/isolated_execution_state"
+
+module SOF
+  # This class is not intended to be referenced directly.
+  # This is an internal implementation of Cycle behavior.
+  class Cycle::Parser
+    extend Forwardable
+    PARTS_REGEX = /
+      ^(?<vol>V(?<volume>\d*))? # optional volume
+      (?<set>(?<kind>L|C|W) # kind
+      (?<period_count>\d+) # period count
+      (?<period_key>D|W|M|Q|Y)?)? # period_key
+      (?<from>F(?<from_date>\d{4}-\d{2}-\d{2}))?$ # optional from
+    /ix
+
+    def self.dormant_capable_kinds = %w[W]
+
+    def self.for(str_or_notation)
+      return str_or_notation if str_or_notation.is_a? self
+
+      new(str_or_notation)
+    end
+
+    def self.load(hash)
+      hash.symbolize_keys!
+      hash.reverse_merge!(volume: 1)
+      keys = %i[volume kind period_count period_key]
+      str = "V#{hash.values_at(*keys).join}"
+      return new(str) unless hash[:from_date]
+
+      new([str, "F#{hash[:from_date]}"].join)
+    end
+
+    def initialize(notation)
+      @notation = notation&.upcase
+      @match = @notation&.match(PARTS_REGEX)
+    end
+
+    attr_reader :match, :notation
+
+    delegate [:dormant_capable_kinds] => "self.class"
+    delegate [:period, :humanized_period] => :time_span
+
+    # Return a TimeSpan object for the period and period_count
+    def time_span
+      @time_span ||= Cycle::TimeSpan.for(period_count, period_key)
+    end
+
+    def valid? = match.present?
+
+    def inspect = notation
+    alias_method :to_s, :inspect
+
+    def activated_notation(date)
+      return notation unless dormant_capable?
+
+      self.class.load(to_h.merge(from_date: date.to_date)).notation
+    end
+
+    def ==(other) = other.to_h == to_h
+
+    def to_h
+      {
+        volume:,
+        kind:,
+        period_count:,
+        period_key:,
+        from_date:
+      }
+    end
+
+    def parses?(notation_id) = kind == notation_id
+
+    def active? = !dormant?
+
+    def dormant? = dormant_capable? && from_date.nil?
+
+    def dormant_capable? = kind.in?(dormant_capable_kinds)
+
+    def period_count = match[:period_count]
+
+    def period_key = match[:period_key]
+
+    def vol = match[:vol] || "V1"
+
+    def volume = (match[:volume] || 1).to_i
+
+    def from_data
+      return {} unless from
+
+      {from: from}
+    end
+
+    def from_date = match[:from_date]
+
+    def from = match[:from]
+
+    def kind = match[:kind]
+  end
+end

data/lib/sof/cycle/time_span.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "../cycle"
+require "active_support/deprecator"
+require "active_support/deprecation"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/integer/time"
+require "active_support/core_ext/string/conversions"
+module SOF
+  # This class is not intended to be referenced directly.
+  # This is an internal implementation of Cycle behavior.
+  class Cycle::TimeSpan
+    extend Forwardable
+    # TimeSpan objects map Cycle notations to behaviors for their periods
+    #
+    # For example:
+    #   'M' => TimeSpan::DatePeriod::Month
+    #   'Y' => TimeSpan::DatePeriod::Year
+    # Read each DatePeriod subclass for more information.
+    #
+    class InvalidPeriod < StandardError; end
+
+    class << self
+      # Return a time_span for the given count and period
+      def for(count, period)
+        case count.to_i
+        when 0
+          TimeSpanNothing
+        when 1
+          TimeSpanOne
+        else
+          self
+        end.new(count, period)
+      end
+
+      # Return a notation string from a hash
+      def notation(hash)
+        return unless hash.key?(:period)
+
+        [
+          hash.fetch(:period_count) { 1 },
+          notation_id_from_name(hash[:period])
+        ].compact.join
+      end
+
+      # Return the notation character for the given period name
+      def notation_id_from_name(name)
+        type = DatePeriod.types.find do |klass|
+          klass.period.to_s == name.to_s
+        end
+
+        raise InvalidPeriod, "'#{name}' is not a valid period" unless type
+
+        type.code
+      end
+    end
+
+    # Class used to calculate the windows of time so that
+    # a TimeSpan object will know the correct end of year,
+    # quarter, etc.
+    class DatePeriod
+      extend Forwardable
+      class << self
+        def for(count, period_notation)
+          @cached_periods ||= {}
+          @cached_periods[period_notation] ||= {}
+          @cached_periods[period_notation][count] ||= (for_notation(period_notation) || self).new(count)
+          @cached_periods[period_notation][count]
+        end
+
+        def for_notation(notation)
+          types.find do |klass|
+            klass.code == notation.to_s.upcase
+          end
+        end
+
+        def types = @types ||= Set.new
+
+        def inherited(klass)
+          DatePeriod.types << klass
+        end
+
+        @period = nil
+        @code = nil
+        @interval = nil
+        attr_reader :period, :code, :interval
+      end
+
+      delegate [:period, :code, :interval] => "self.class"
+
+      def initialize(count)
+        @count = count
+      end
+      attr_reader :count
+
+      def end_date(date)
+        @end_date ||= {}
+        @end_date[date] ||= date + duration
+      end
+
+      def begin_date(date)
+        @begin_date ||= {}
+        @begin_date[date] ||= date - duration
+      end
+
+      def duration = count.send(period)
+
+      def end_of_period(_) = nil
+
+      def humanized_period
+        return period if count == 1
+
+        "#{period}s"
+      end
+
+      class Year < self
+        @period = :year
+        @code = "Y"
+        @interval = "years"
+
+        def end_of_period(date)
+          date.end_of_year
+        end
+
+        def beginning_of_period(date)
+          date.beginning_of_year
+        end
+      end
+
+      class Quarter < self
+        @period = :quarter
+        @code = "Q"
+        @interval = "quarters"
+
+        def duration
+          (count * 3).months
+        end
+
+        def end_of_period(date)
+          date.end_of_quarter
+        end
+
+        def beginning_of_period(date)
+          date.beginning_of_quarter
+        end
+      end
+
+      class Month < self
+        @period = :month
+        @code = "M"
+        @interval = "months"
+
+        def end_of_period(date)
+          date.end_of_month
+        end
+
+        def beginning_of_period(date)
+          date.beginning_of_month
+        end
+      end
+
+      class Week < self
+        @period = :week
+        @code = "W"
+        @interval = "weeks"
+
+        def end_of_period(date)
+          date.end_of_week
+        end
+
+        def beginning_of_period(date)
+          date.beginning_of_week
+        end
+      end
+
+      class Day < self
+        @period = :day
+        @code = "D"
+        @interval = "days"
+
+        def end_of_period(date)
+          date
+        end
+
+        def beginning_of_period(date)
+          date
+        end
+      end
+    end
+    private_constant :DatePeriod
+
+    def initialize(count, period_id)
+      @count = Integer(count, exception: false)
+      @window = DatePeriod.for(period_count, period_id)
+    end
+    attr_reader :window
+
+    delegate [:end_date, :begin_date] => :window
+
+    def end_date_of_period(date)
+      window.end_of_period(date)
+    end
+
+    def begin_date_of_period(date)
+      window.beginning_of_period(date)
+    end
+
+    # Integer value for the period count or nil
+    def period_count
+      @count
+    end
+
+    delegate [:period, :duration, :interval, :humanized_period] => :window
+
+    # Return a date according to the rules of the time_span
+    def final_date(date)
+      return unless period
+
+      window.end_date(date.to_date)
+    end
+
+    def to_h
+      {
+        period:,
+        period_count:
+      }
+    end
+
+    class TimeSpanNothing < self
+    end
+
+    class TimeSpanOne < self
+      def interval = humanized_period
+    end
+  end
+end

data/lib/sof/cycle/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SOF
+  class Cycle
+    VERSION = "0.1.0"
+  end
+end

data/lib/sof/cycle.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require_relative "cycle/version"
+require "forwardable"
+require_relative "cycle/parser"
+require_relative "cycle/time_span"
+require "active_support/core_ext/date/conversions"
+require "active_support/core_ext/string/filters"
+
+module SOF
+  class Cycle
+    extend Forwardable
+    class InvalidInput < StandardError; end
+
+    class InvalidPeriod < InvalidInput; end
+
+    class InvalidKind < InvalidInput; end
+
+    def initialize(notation, parser: Parser.new(notation))
+      @notation = notation
+      @parser = parser
+      validate_period
+
+      return if @parser.valid?
+
+      raise InvalidInput, "'#{notation}' is not a valid input"
+    end
+
+    attr_reader :parser
+
+    delegate [:activated_notation, :volume, :from, :from_date, :time_span, :period,
+      :humanized_period, :period_key, :active?] => :@parser
+    delegate [:kind, :volume_only?, :valid_periods] => "self.class"
+    delegate [:period_count, :duration] => :time_span
+
+    # Turn a cycle or notation string into a hash
+    def self.dump(cycle_or_string)
+      if cycle_or_string.is_a? Cycle
+        cycle_or_string
+      else
+        Cycle.for(cycle_or_string)
+      end.to_h
+    end
+
+    # Return a Cycle object from a hash
+    def self.load(hash)
+      symbolized_hash = hash.symbolize_keys
+      cycle_class = class_for_kind(symbolized_hash[:kind])
+
+      unless cycle_class.valid_periods.empty?
+        cycle_class.validate_period(
+          TimeSpan.notation_id_from_name(symbolized_hash[:period])
+        )
+      end
+
+      Cycle.for notation(symbolized_hash)
+    rescue TimeSpan::InvalidPeriod => exc
+      raise InvalidPeriod, exc.message
+    end
+
+    # Retun a notation string from a hash
+    #
+    # @param hash [Hash] hash of data for a valid Cycle
+    # @return [String] string representation of a Cycle
+    def self.notation(hash)
+      volume_notation = "V#{hash.fetch(:volume) { 1 }}"
+      return volume_notation if hash[:kind].nil? || hash[:kind].to_sym == :volume_only
+
+      cycle_class = class_for_kind(hash[:kind].to_sym)
+      [
+        volume_notation,
+        cycle_class.notation_id,
+        TimeSpan.notation(hash.slice(:period, :period_count)),
+        hash.fetch(:from, nil)
+      ].compact.join
+    end
+
+    # Return a Cycle object from a notation string
+    #
+    # @param notation [String] a string notation representing a Cycle
+    # @example
+    #   Cycle.for('V2C1Y)
+    # @return [Cycle] a Cycle object representing the provide string notation
+    def self.for(notation)
+      return notation if notation.is_a? Cycle
+      return notation if notation.is_a? Cycle::Dormant
+      parser = Parser.new(notation)
+      unless parser.valid?
+        raise InvalidInput, "'#{notation}' is not a valid input"
+      end
+
+      cycle = cycle_handlers.find do |klass|
+        parser.parses?(klass.notation_id)
+      end.new(notation, parser:)
+      return cycle if parser.active?
+
+      Cycle::Dormant.new(cycle, parser:)
+    end
+
+    # Return the appropriate class for the give notation id
+    #
+    # @param notation [String] notation id matching the kind of Cycle class
+    # @example
+    #   class_for_notation_id('L')
+    #
+    def self.class_for_notation_id(notation_id)
+      cycle_handlers.find do |klass|
+        klass.notation_id == notation_id
+      end || raise(InvalidKind, "'#{notation_id}' is not a valid kind of #{name}")
+    end
+
+    # Return the class handling the kind
+    #
+    # @param sym [Symbol] symbol matching the kind of Cycle class
+    # @example
+    #   class_for_kind(:lookback)
+    def self.class_for_kind(sym)
+      Cycle.cycle_handlers.find do |klass|
+        klass.handles?(sym)
+      end || raise(InvalidKind, "':#{sym}' is not a valid kind of Cycle")
+    end
+
+    def self.cycle_handlers = @cycle_handlers ||= Set.new
+
+    def self.inherited(klass) = cycle_handlers << klass
+
+    def self.handles?(sym)
+      sym && kind == sym.to_sym
+    end
+
+    @volume_only = false
+    @notation_id = nil
+    @kind = nil
+    @valid_periods = []
+
+    def self.volume_only? = @volume_only
+
+    class << self
+      attr_reader :notation_id, :kind, :valid_periods
+    end
+
+    # Raises an error if the given period isn't in the list of valid periods.
+    #
+    # @param period [String] period matching the class valid periods
+    # @raise [InvalidPeriod]
+    def self.validate_period(period)
+      raise InvalidPeriod, <<~ERR.squish unless valid_periods.include?(period)
+        Invalid period value of '#{period}' provided. Valid periods are:
+        #{valid_periods.join(", ")}
+      ERR
+    end
+
+    def validate_period
+      return if valid_periods.empty?
+
+      self.class.validate_period(period_key)
+    end
+
+    # Return the cycle representation as a notation string
+    def notation = self.class.notation(to_h)
+
+    # Cycles are considered equal if their hash representations are equal
+    def ==(other) = to_h == other.to_h
+
+    # From the supplied anchor date, are there enough in-window completions to
+    # satisfy the cycle?
+    #
+    # @return [Boolean] true if the cycle is satisfied, false otherwise
+    def satisfied_by?(completion_dates, anchor: Date.current)
+      covered_dates(completion_dates, anchor:).size >= volume
+    end
+
+    def covered_dates(dates, anchor: Date.current)
+      dates.select do |date|
+        cover?(date, anchor:)
+      end
+    end
+
+    def cover?(date, anchor: Date.current)
+      range(anchor).cover?(date)
+    end
+
+    def range(anchor) = start_date(anchor)..final_date(anchor)
+
+    def humanized_span = [period_count, humanized_period].join(" ")
+
+    # Return the final date of the cycle
+    def final_date(_anchor) = nil
+
+    def expiration_of(_completion_dates, anchor: Date.current) = nil
+
+    def volume_to_delay_expiration(_completion_dates, anchor:) = 0
+
+    def to_h
+      {
+        kind:,
+        volume:,
+        period:,
+        period_count:,
+        **from_data
+      }
+    end
+
+    def from_data
+      return {} unless from
+
+      {from: from}
+    end
+
+    def as_json(...) = notation
+
+    class Dormant
+      def initialize(cycle, parser:)
+        @cycle = cycle
+        @parser = parser
+      end
+
+      attr_reader :cycle, :parser
+
+      def to_s
+        cycle.to_s + " (dormant)"
+      end
+
+      def covered_dates(...) = []
+
+      def expiration_of(...) = nil
+
+      def satisfied_by?(...) = false
+
+      def cover?(...) = false
+
+      def method_missing(method, ...) = cycle.send(method, ...)
+
+      def respond_to_missing?(method, include_private = false)
+        cycle.respond_to?(method, include_private)
+      end
+    end
+
+    class Within < self
+      @volume_only = false
+      @notation_id = "W"
+      @kind = :within
+      @valid_periods = %w[D W M Y]
+
+      def to_s = "#{volume}x within #{date_range}"
+
+      def date_range
+        return humanized_span unless active?
+
+        [start_date, final_date].map { _1.to_fs(:american) }.join(" - ")
+      end
+
+      def final_date(_ = nil) = time_span.end_date(start_date)
+
+      def start_date(_ = nil) = from_date.to_date
+    end
+
+    class VolumeOnly < self
+      @volume_only = true
+      @notation_id = nil
+      @kind = :volume_only
+      @valid_periods = []
+
+      class << self
+        def handles?(sym) = sym.nil? || super
+
+        def validate_period(period)
+          raise InvalidPeriod, <<~ERR.squish unless period.nil?
+            Invalid period value of '#{period}' provided. Valid periods are:
+            #{valid_periods.join(", ")}
+          ERR
+        end
+      end
+
+      def to_s = "#{volume}x total"
+
+      def covered_dates(dates, ...) = dates
+
+      def cover?(...) = true
+    end
+
+    class Lookback < self
+      @volume_only = false
+      @notation_id = "L"
+      @kind = :lookback
+      @valid_periods = %w[D W M Y]
+
+      def to_s = "#{volume}x in the prior #{period_count} #{humanized_period}"
+
+      def volume_to_delay_expiration(completion_dates, anchor:)
+        oldest_relevant_completion = completion_dates.min
+        [completion_dates.count(oldest_relevant_completion), volume].min
+      end
+
+      # "Absent further completions, you go red on this date"
+      # @return [Date, nil] the date on which the cycle will expire given the
+      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
+      def expiration_of(completion_dates)
+        anchor = completion_dates.max_by(volume) { _1 }.min
+        return unless satisfied_by?(completion_dates, anchor:)
+
+        window_end anchor
+      end
+
+      def final_date(anchor)
+        return if anchor.nil?
+
+        time_span.end_date(anchor.to_date)
+      end
+      alias_method :window_end, :final_date
+
+      def start_date(anchor)
+        time_span.begin_date(anchor.to_date)
+      end
+      alias_method :window_start, :start_date
+    end
+
+    class Calendar < self
+      @volume_only = false
+      @notation_id = "C"
+      @kind = :calendar
+      @valid_periods = %w[M Q Y]
+
+      class << self
+        def frame_of_reference = "total"
+      end
+
+      def to_s
+        "#{volume}x every #{period_count} calendar #{humanized_period}"
+      end
+
+      # "Absent further completions, you go red on this date"
+      # @return [Date, nil] the date on which the cycle will expire given the
+      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
+      def expiration_of(completion_dates)
+        anchor = completion_dates.max_by(volume) { _1 }.min
+        return unless satisfied_by?(completion_dates, anchor:)
+
+        window_end(anchor) + duration
+      end
+
+      def final_date(anchor)
+        return if anchor.nil?
+        time_span.end_date_of_period(anchor.to_date)
+      end
+      alias_method :window_end, :final_date
+
+      def start_date(anchor)
+        time_span.begin_date_of_period(anchor.to_date)
+      end
+    end
+  end
+end

data/lib/sof-cycle.rb

@@ -0,0 +1 @@
+require_relative "sof/cycle"

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: sof-cycle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jim Gay
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: forwardable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description:
+email:
+- jim@saturnflyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".simplecov"
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/sof-cycle.rb
+- lib/sof/cycle.rb
+- lib/sof/cycle/parser.rb
+- lib/sof/cycle/time_span.rb
+- lib/sof/cycle/version.rb
+homepage: https://github.com/SOFware/sof-cycle
+licenses: []
+metadata:
+  homepage_uri: https://github.com/SOFware/sof-cycle
+  changelog_uri: https://github.com/SOFware/sof-cycle/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Parse and interact with SOF cycle notation.
+test_files: []