sof-cycle 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eb9458907426d68d8fc05c159a9bb782819b2ec821baf2ec24109b45c6794ff
-  data.tar.gz: e4c0b55074d59aad3f4e562e579759d8d85413b1fd93c93c873b79bdbff1c629
+  metadata.gz: ace7e7bdb57808f1c633cf78aaab4fc7949e6820e86089c283926e0c22558bbd
+  data.tar.gz: 5c12b7d8d840f2afe367d13cc7e5864fd835d62e2f0b9bc480d17873e706182c
 SHA512:
-  metadata.gz: c799aed72bf8973a8b6438cab7d2635f2563575fcf3d16eac4b4bf38df409953000d78afc8b691ed4b5e4eb40b39a7969858e79d9ee844697ce113e1f0170ae5
-  data.tar.gz: c99b76559985729d0ea59ee3ff5be523500965578c450c85a90c24fd2d958ebd6eb4ff4ad550d101e8178423f2f39d02ffe79a47a28f716e34865c4028ce83a5
+  metadata.gz: d1c8dda915931d2a5cd860ebf1ad79d2c6cc353d8794a159cc52720bde02f2e3e3aa7001fbb7af240dbf16c1b212f44ce28eacb7ec10fa1868dd47c7860406ae
+  data.tar.gz: ea2ca6604e38d85894d0df757010449f839040b28c01de608270cdffc536ed5f8e62125ecea7ec59f9100106eae6a3ab2a3243b68b4218a7269b671f483e9bad

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.3
+ruby 4.0.2

data/CHANGELOG.md

@@ -5,22 +5,6 @@ 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.13] - 2026-03-20
+## [0.1.15] - 2026-07-27
 
-### Added
-
-- Interval cycle kind (`I` notation) — repeating windows anchored to a from_date that re-anchor from completion date (e.g., `V1I24MF2026-03-31`)
-
-### Changed
-
-- Dormant capability is now declared on each cycle class (`def self.dormant_capable? = true`) instead of only in `Parser.dormant_capable_kinds`
-
-### Fixed
-
-- EndOf cycle `final_date` was off by one period — `V1E12M` now correctly expires at the end of the 12th month, not the 11th
-
-## [0.1.12] - 2025-09-05
-
-### Added
-
-- Missing code coverage and updated EndOf to properly handle dormant cycles.
+## [0.1.14] - 2026-04-27

data/checksums/sof-cycle-0.1.13.gem.sha512

@@ -0,0 +1 @@
+bb21b935b95e99c2616c397155c6354976d343e669c34a7c36a319c495bdfda5b3a24c5d6042d891672215f90e405703a3ee24f79623e129c17bdd9967190a29

data/checksums/sof-cycle-0.1.14.gem.sha512

@@ -0,0 +1 @@
+33dfd415ab31a635f8af0e515187f22f958227d26cf9c27f087dccc03c4c8ff4b7c38f9f303f5f134597b652aafe8363d8683d82ccb93492e3bb4310f218f50d

data/checksums/sof-cycle-0.1.3.gem.sha512

@@ -0,0 +1 @@
+0c1dbd71ae4ba8c8dd68e6285acd567ebe5f715c88a6a25c16e9abc1baa48a02618e006a5b1234b0d2c97bacdef53d1a0deb0691a8659474eeb9304c95764289

data/checksums/sof-cycle-0.1.4.gem.sha512

@@ -0,0 +1 @@
+8692e06774fdb76269fa438824887f87991703885a2cf2cb7dc5bd77ba44b2e0ddce1a78c40e5411da8be2b88dfb0c875900b42f8a784a4060db7d4f4c4d4f1b

data/checksums/sof-cycle-0.1.5.gem.sha512

@@ -0,0 +1 @@
+7c06ae8b1c4eaafac55f16143c7f60b4ce3c613a83d75859e2f798e850a90190d1f26109057e349c42f03fcce8c0f81a85904bab3ca96877b60c27ad52ee1517

data/lib/sof/cycle/parser.rb

@@ -0,0 +1,127 @@
+# 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
+  class Cycle
+    # This class is not intended to be referenced directly.
+    # This is an internal implementation of Cycle behavior.
+    class Parser
+      extend Forwardable
+
+      # Built from the registry rather than written out, so an application
+      # that declares its own kind has its notation recognised too. Rebuilt
+      # whenever a class registers; cached in between, since parsing is hot.
+      def self.parts_regex
+        pattern = [Cycle.registry.notation_pattern, Cycle::TimeSpan.period_registry.code_pattern]
+        return @parts_regex if @parts_regex && @parts_regex_pattern == pattern
+
+        @parts_regex_pattern = pattern
+        kinds, periods = pattern
+        @parts_regex = /
+          ^(?<vol>V(?<volume>\d*))? # optional volume
+          (?<set>(?<kind>#{kinds}) # kind
+          (?<period_count>\d+) # period count
+          (?<period_key>#{periods})?)? # period_key
+          (?<from>F(?<from_date>\d{4}-\d{2}-\d{2}))?$ # optional from
+        /ix
+      end
+
+      # Deliberately a method, not a constant: handlers register as each file
+      # in sof/cycles loads, which happens after this file. A constant would
+      # capture the empty set and leave every dormant-capable kind
+      # unrecognized.
+      def self.dormant_capable_kinds
+        Cycle.registry.cycle_classes.select(&:dormant_capable?).map(&:notation_id).compact.freeze
+      end
+
+      def self.for(notation_or_parser)
+        return notation_or_parser if notation_or_parser.is_a? self
+
+        new(notation_or_parser)
+      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(self.class.parts_regex)
+        @time_span = nil
+      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 ||= 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
+end

data/lib/sof/cycle/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SOF
+  class Cycle
+    # The set of classes that handle cycle kinds.
+    #
+    # Registration is explicit — a class joins by declaring what it handles
+    # (see Cycle.handles), not by subclassing. Inheriting from Cycle for any
+    # other reason, such as a test double or an abstract intermediate, then
+    # carries no hidden side effect.
+    #
+    # The registry is also what the parser reads to recognise notations, so an
+    # application can add a kind of its own and have its notation parse without
+    # reopening this gem.
+    class Registry
+      def self.instance = @instance ||= new
+
+      def initialize
+        @cycle_classes = []
+        @notation_pattern = nil
+      end
+
+      # Add a handler, displacing any already handling the same kind or
+      # notation id. That is what lets an application override a built-in
+      # kind — declare a class handling :lookback and it takes over "L" —
+      # as well as add one of its own. Re-registering the same class is a
+      # no-op, so a reloaded file accumulates no duplicates.
+      #
+      # Returns the class, so a declaration can use the result.
+      def register(cycle_class)
+        displaced = @cycle_classes.reject { |klass| klass.equal?(cycle_class) }
+          .select { |klass| conflicts?(klass, cycle_class) }
+        @cycle_classes -= displaced
+        @cycle_classes << cycle_class unless @cycle_classes.include?(cycle_class)
+        @notation_pattern = nil
+        cycle_class
+      end
+
+      # Drop a handler. Mainly for an application undoing an override, and for
+      # tests that register a throwaway kind.
+      def unregister(cycle_class)
+        @cycle_classes.delete(cycle_class)
+        @notation_pattern = nil
+        cycle_class
+      end
+
+      def cycle_classes = @cycle_classes.dup
+
+      # The class declaring `kind`.
+      def handling(kind)
+        @cycle_classes.find { |klass| klass.handles?(kind) } ||
+          raise(InvalidKind, "':#{kind}' is not a valid kind of Cycle")
+      end
+
+      # The class declaring `notation_id` — the letter(s) that open a cycle's
+      # notation, such as "L" or "LE".
+      def for_notation_id(notation_id)
+        @cycle_classes.find { |klass| klass.notation_id == notation_id } ||
+          raise(InvalidKind, "'#{notation_id}' is not a valid kind of Cycle")
+      end
+
+      # Registered notation ids, longest first. A volume-only cycle has none,
+      # so it contributes nothing to parse.
+      def notation_ids
+        @cycle_classes.filter_map(&:notation_id).uniq.sort_by { |id| [-id.length, id] }
+      end
+
+      # The alternation the parser splices into its pattern. Rebuilt whenever a
+      # class registers, so a kind added at runtime is recognised from then on.
+      def notation_pattern
+        @notation_pattern ||= notation_ids.map { Regexp.escape(it) }.join("|")
+      end
+
+      private
+
+      # Two handlers conflict when they answer to the same kind, or claim the
+      # same notation id. A nil notation id claims nothing.
+      def conflicts?(existing, incoming)
+        return true if existing.kind == incoming.kind
+        return false if incoming.notation_id.nil?
+
+        existing.notation_id == incoming.notation_id
+      end
+    end
+  end
+end

data/lib/sof/cycle/time_span.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+module SOF
+  class Cycle
+    # This class is not intended to be referenced directly.
+    # This is an internal implementation of Cycle behavior.
+    class 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
+
+      # The set of classes measuring a period of time. Registration is
+      # explicit — a class joins by declaring what it measures, not by
+      # subclassing — which is what removes the inherited hook and lets the
+      # parser build its period alternation from what is registered.
+      #
+      # Internal, like DatePeriod itself: periods are not an extension point.
+      # Reach it through TimeSpan.period_registry.
+      class PeriodRegistry
+        def self.instance = @instance ||= new
+
+        def initialize
+          @period_classes = []
+          @code_pattern = nil
+        end
+
+        # Add a period class, displacing any already measuring the same period
+        # or claiming the same code, so an application can replace a built-in as
+        # well as add to it. Returns the class.
+        def register(period_class)
+          displaced = @period_classes.reject { |klass| klass.equal?(period_class) }
+            .select { |klass| conflicts?(klass, period_class) }
+          @period_classes -= displaced
+          @period_classes << period_class unless @period_classes.include?(period_class)
+          @code_pattern = nil
+          period_class
+        end
+
+        def unregister(period_class)
+          @period_classes.delete(period_class)
+          @code_pattern = nil
+          period_class
+        end
+
+        def period_classes = @period_classes.dup
+
+        # The class whose notation code this is, e.g. "M". Case-insensitive,
+        # since a notation may be written either way. Nil when unrecognised —
+        # DatePeriod.for falls back to its own default.
+        def for_code(code)
+          return if code.nil?
+
+          normalized = code.to_s.upcase
+          @period_classes.find { |klass| klass.code == normalized }
+        end
+
+        # The class measuring this period, e.g. :month. Nil when unrecognised.
+        def for_period(period)
+          @period_classes.find { |klass| klass.period.to_s == period.to_s }
+        end
+
+        # Registered codes, longest first so a longer code is never shadowed by
+        # its own prefix.
+        def codes
+          @period_classes.filter_map(&:code).uniq.sort_by { |code| [-code.length, code] }
+        end
+
+        # The alternation the parser splices in for the period key. Rebuilt
+        # whenever a class registers.
+        def code_pattern
+          @code_pattern ||= codes.map { Regexp.escape(it) }.join("|")
+        end
+
+        private
+
+        def conflicts?(existing, incoming)
+          return true if existing.period == incoming.period
+          return false if incoming.code.nil?
+
+          existing.code == incoming.code
+        end
+      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[:period].present?
+
+          [
+            hash.fetch(:period_count) { 1 },
+            notation_id_from_name(hash[:period])
+          ].compact.join
+        end
+
+        # The registry of period classes, owned by DatePeriod. Exposed here
+        # because DatePeriod is a private constant, so callers outside cannot
+        # name it — the parser needs the code alternation to build its pattern.
+        def period_registry = PeriodRegistry.instance
+
+        # Return the notation character for the given period name
+        def notation_id_from_name(name)
+          period_registry.for_period(name)&.code ||
+            raise(InvalidPeriod, "'#{name}' is not a valid period")
+        end
+      end
+
+      def notation
+        [period_count, code].join
+      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) = registry.for_code(notation)
+
+          def types = registry.period_classes
+
+          def registry = TimeSpan.period_registry
+
+          # Declare the period this class measures, and register it.
+          #
+          # As with Cycle.handles, registration follows from declaring, so
+          # subclassing DatePeriod on its own registers nothing, and an
+          # application can add a period of its own — its code is recognised
+          # because the parser builds that alternation from the registry.
+          #
+          # @param period [Symbol] the period measured, e.g. :month
+          # @param code [String] the notation character, e.g. "M"
+          # @param interval [String] the plural name used in descriptions
+          #
+          # @example
+          #   class Fortnight < DatePeriod
+          #     measures :fortnight, code: "N", interval: "fortnights"
+          #     def duration = (count * 2).weeks
+          #   end
+          def measures(period, code:, interval:)
+            @period = period
+            @code = code
+            @interval = interval
+            registry.register(self)
+          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_date = {}
+          @begin_date = {}
+        end
+        attr_reader :count
+
+        def end_date(date)
+          @end_date[date] ||= date + duration
+        end
+
+        def begin_date(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
+          measures :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
+          measures :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
+          measures :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
+          measures :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
+          measures :day, code: "D", interval: "days"
+
+          def end_of_period(date)
+            date
+          end
+
+          def beginning_of_period(date)
+            date
+          end
+        end
+      end
+      private_constant :DatePeriod, :PeriodRegistry
+
+      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, :code] => :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
+end

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.13"
+    VERSION = "0.1.15"
   end
 end