sof-cycle 0.1.13 → 0.1.15

data/lib/sof/cycle.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "forwardable"
-require_relative "parser"
+require_relative "cycle/registry"
+require_relative "cycle/parser"
 
 module SOF
   class Cycle
     extend ::Forwardable
+
     class InvalidInput < StandardError; end
 
     class InvalidPeriod < InvalidInput; end
@@ -69,9 +71,7 @@ module SOF
           raise InvalidInput, "'#{notation}' is not a valid input"
         end
 
-        cycle = Cycle.cycle_handlers.find do |klass|
-          parser.parses?(klass.notation_id)
-        end.new(notation, parser:)
+        cycle = registry.for_notation_id(parser.kind).new(notation, parser:)
         return cycle if parser.active?
 
         Cycles::Dormant.new(cycle, parser:)
@@ -83,22 +83,14 @@ module SOF
       # @example
       #   class_for_notation_id('L')
       #
-      def class_for_notation_id(notation_id)
-        Cycle.cycle_handlers.find do |klass|
-          klass.notation_id == notation_id
-        end || raise(InvalidKind, "'#{notation_id}' is not a valid kind of #{name}")
-      end
+      def class_for_notation_id(notation_id) = registry.for_notation_id(notation_id)
 
       # Return the class handling the kind
       #
       # @param sym [Symbol] symbol matching the kind of Cycle class
       # @example
       #   class_for_kind(:lookback)
-      def 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 class_for_kind(sym) = registry.handling(sym)
 
       # Return a legend explaining all notation components
       #
@@ -122,6 +114,8 @@ module SOF
         }
       end
 
+      # Defaults for the base class itself, which handles no kind and so is
+      # never registered.
       @volume_only = false
       @notation_id = nil
       @kind = nil
@@ -149,23 +143,77 @@ module SOF
         kind.to_s == sym.to_s
       end
 
-      def cycle_handlers
-        @cycle_handlers ||= Set.new
+      # Declare what kind of cycle this class handles, and register it.
+      #
+      # Registration is a consequence of declaring, so the two can never
+      # disagree, and subclassing Cycle for any other reason — an abstract
+      # intermediate, a test double — registers nothing.
+      #
+      # An application can declare its own kind this way and the parser will
+      # recognise its notation, because the pattern is built from what is
+      # registered.
+      #
+      # @param kind [Symbol] the kind this class handles, e.g. :lookback
+      # @param notation [String, nil] the notation id opening the cycle, e.g.
+      #   "L". Omit for a cycle with no notation of its own, such as
+      #   volume-only.
+      # @param periods [Array<String>] period keys this kind accepts. Empty
+      #   means the kind takes no period.
+      # @param volume_only [Boolean] whether this kind carries volume alone.
+      #
+      # @example
+      #   class Fortnightly < SOF::Cycle
+      #     handles :fortnightly, notation: "X", periods: %w[D W]
+      #     def self.recurring? = true
+      #   end
+      def handles(kind, notation: nil, periods: [], volume_only: false)
+        @kind = kind
+        @notation_id = notation
+        @valid_periods = periods
+        @volume_only = volume_only
+        register(self)
       end
 
-      def inherited(klass)
-        Cycle.cycle_handlers << klass
-      end
+      # Register a handler that does not inherit from Cycle. Inheriting and
+      # declaring with `handles` is the easier path, because it supplies the
+      # behaviour Cycle.for goes on to use; this is for a class that would
+      # rather implement that itself.
+      #
+      # The class must answer, at the class level:
+      #
+      #   kind             the kind it handles, e.g. :lookback
+      #   notation_id      the notation opening it, e.g. "L", or nil
+      #   valid_periods    period keys it accepts, e.g. %w[D W M Y]
+      #   volume_only?     whether it carries volume alone
+      #   handles?(kind)   whether it answers to a kind
+      #   recurring?       whether the window repeats
+      #   dormant_capable? whether it can be written without a from date
+      #   validate_period(key)
+      #   description, examples   (for the legend)
+      #
+      # and instances are built as `new(notation, parser:)`.
+      #
+      # Registering displaces any handler already answering to the same kind
+      # or notation id, so this replaces a built-in as readily as it adds one.
+      #
+      # @param cycle_class [Class] the handler to register
+      # @return [Class] the class registered
+      def register(cycle_class) = registry.register(cycle_class)
+
+      # Drop a handler, undoing `register` or a `handles` declaration.
+      def unregister(cycle_class) = registry.unregister(cycle_class)
+
+      def registry = Registry.instance
 
       private
 
       def build_kind_legend
         legend = {}
-        Cycle.cycle_handlers.each do |handler|
+        registry.cycle_classes.each do |handler|
           # Skip volume_only since it doesn't have a notation_id
-          next if handler.instance_variable_get(:@volume_only)
+          next if handler.volume_only?
 
-          notation_id = handler.instance_variable_get(:@notation_id)
+          notation_id = handler.notation_id
           next unless notation_id
 
           legend[notation_id] = {
@@ -178,14 +226,10 @@ module SOF
 
       def build_period_legend
         legend = {}
-        # Use known period codes since DatePeriod is private
-        period_mappings = {
-          "D" => "day",
-          "W" => "week",
-          "M" => "month",
-          "Q" => "quarter",
-          "Y" => "year"
-        }
+        # Built from the registered periods, so one an application adds shows
+        # up here too.
+        period_mappings = TimeSpan.period_registry.period_classes
+          .to_h { |klass| [klass.code, klass.period.to_s] }
 
         period_mappings.each do |code, period_name|
           legend[code] = {
@@ -223,7 +267,7 @@ module SOF
     delegate [:kind, :recurring?, :volume_only?, :valid_periods] => "self.class"
     delegate [:period_count, :duration] => :time_span
     delegate [:calendar?, :dormant?, :end_of?, :interval?, :lookback?,
-      :volume_only?, :within?] => :kind_inquiry
+      :lookback_end_of?, :volume_only?, :within?] => :kind_inquiry
 
     def kind_inquiry = ActiveSupport::StringInquirer.new(kind.to_s)
 
@@ -252,6 +296,39 @@ module SOF
 
     def extend_period(_ = nil) = self
 
+    # Whether this kind of cycle can be written without a from date, and so
+    # can be anchored later. Answers on the instance so a dormant cycle can
+    # be asked too — `cycle.class` is Cycles::Dormant there, which knows
+    # nothing of the kind it wraps.
+    def dormant_capable? = self.class.dormant_capable?
+
+    # The cycle restarted from the latest of `dates` past its current anchor.
+    #
+    # A recurring, dormant-capable window (E and I) is reset by the act that
+    # satisfies it — "complete 1 by that date to reset the cycle". Nothing in
+    # the notation does that on its own, so this used to fall to each
+    # consuming app.
+    #
+    # Dates on or before the current anchor are ignored: a back-dated act
+    # must not drag a forward-running window backwards. Every other kind
+    # returns itself — a lookback window already slides, a calendar window is
+    # pinned to the calendar, a one-shot window does not repeat, and an
+    # un-anchored one has no window to move until it is activated.
+    #
+    # @param dates [Array<Date, Time, nil>] the acts that satisfy this cycle
+    # @return [Cycle] the reset cycle, or self when nothing resets it
+    #
+    # @example
+    #   Cycle.for("V1E18MF2026-02-01").reset_by([Date.new(2026, 9, 15)])
+    #   # => Cycle.for("V1E18MF2026-09-15")
+    def reset_by(dates)
+      return self unless recurring? && dormant_capable?
+      return self if from_date.nil?
+
+      reset = reset_date(dates)
+      reset ? Cycle.for(activated_notation(reset)) : self
+    end
+
     # From the supplied anchor date, are there enough in-window completions to
     # satisfy the cycle?
     #
@@ -302,5 +379,13 @@ module SOF
     end
 
     def as_json(...) = notation
+
+    private
+
+    # The latest date that moves this cycle's window forward, or nil.
+    def reset_date(dates)
+      anchored_on = from_date.to_date
+      Array(dates).filter_map { it&.to_date }.select { it > anchored_on }.max
+    end
   end
 end

data/lib/sof/cycles/calendar.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Calendar < Cycle
-      @volume_only = false
-      @notation_id = "C"
-      @kind = :calendar
-      @valid_periods = %w[M Q Y]
+      handles :calendar, notation: "C", periods: %w[M Q Y]
 
       class << self
         def frame_of_reference = "total"

data/lib/sof/cycles/dormant.rb

@@ -22,6 +22,10 @@ module SOF
 
       def covered_dates(...) = []
 
+      # No anchor yet, so nothing to move: a dormant cycle is reset by being
+      # activated, not by the acts that satisfy it.
+      def reset_by(...) = self
+
       def expiration_of(...) = nil
 
       def satisfied_by?(...) = false

data/lib/sof/cycles/end_of.rb

@@ -11,10 +11,7 @@
 module SOF
   module Cycles
     class EndOf < Cycle
-      @volume_only = false
-      @notation_id = "E"
-      @kind = :end_of
-      @valid_periods = %w[W M Q Y]
+      handles :end_of, notation: "E", periods: %w[W M Q Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/interval.rb

@@ -11,10 +11,7 @@
 module SOF
   module Cycles
     class Interval < Cycle
-      @volume_only = false
-      @notation_id = "I"
-      @kind = :interval
-      @valid_periods = %w[D W M Y]
+      handles :interval, notation: "I", periods: %w[D W M Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/lookback.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Lookback < Cycle
-      @volume_only = false
-      @notation_id = "L"
-      @kind = :lookback
-      @valid_periods = %w[D W M Y]
+      handles :lookback, notation: "L", periods: %w[D W M Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/lookback_end_of.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class LookbackEndOf < Cycle
+      handles :lookback_end_of, notation: "LE", periods: %w[D W M Q Y]
+
+      def self.recurring? = true
+
+      def self.description
+        "Lookback End of Period - occurrences within a prior time period, expiring at the end of the calendar period"
+      end
+
+      def self.examples
+        ["V1LE24M - once in the prior 24 months (expires end of month)", "V2LE3W - twice in the prior 3 weeks (expires end of week)"]
+      end
+
+      def to_s = "#{volume}x in the prior #{period_count} #{humanized_period} (end of period)"
+
+      def expiration_of(completion_dates, anchor: Date.current)
+        oldest = completion_dates.max_by(volume) { it }.min
+        return unless satisfied_by?(completion_dates, anchor:)
+
+        final_date(oldest)
+      end
+
+      def final_date(anchor)
+        return if anchor.nil?
+
+        time_span.end_date_of_period(time_span.end_date(anchor.to_date))
+      end
+      alias_method :window_end, :final_date
+
+      def start_date(anchor)
+        time_span.begin_date_of_period(time_span.begin_date(anchor.to_date))
+      end
+      alias_method :window_start, :start_date
+    end
+  end
+end

data/lib/sof/cycles/volume_only.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class VolumeOnly < Cycle
-      @volume_only = true
-      @notation_id = nil
-      @kind = :volume_only
-      @valid_periods = []
+      handles :volume_only, volume_only: true
 
       class << self
         def handles?(sym) = sym.nil? || sym.to_s == "volume_only"

data/lib/sof/cycles/within.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Within < Cycle
-      @volume_only = false
-      @notation_id = "W"
-      @kind = :within
-      @valid_periods = %w[D W M Y]
+      handles :within, notation: "W", periods: %w[D W M Y]
 
       def self.recurring? = false
 
@@ -24,7 +21,7 @@ module SOF
 
       def extend_period(count)
         Cycle.for(
-          Parser.load(
+          Cycle::Parser.load(
             parser.to_h.merge(period_count: period_count + count)
           ).to_s
         )

data/lib/sof-cycle.rb

@@ -14,4 +14,4 @@ require_relative "sof/cycle"
 
 Dir[File.join(__dir__, "sof", "cycles", "*.rb")].each { |file| require file }
 
-require_relative "sof/time_span"
+require_relative "sof/cycle/time_span"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Jim Gay
@@ -43,7 +43,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/settings.local.json"
 - ".rspec"
 - ".simplecov"
 - ".tool-versions"
@@ -56,23 +55,30 @@ files:
 - checksums/sof-cycle-0.1.10.gem.sha512
 - checksums/sof-cycle-0.1.11.gem.sha512
 - checksums/sof-cycle-0.1.12.gem.sha512
+- checksums/sof-cycle-0.1.13.gem.sha512
+- checksums/sof-cycle-0.1.14.gem.sha512
 - checksums/sof-cycle-0.1.2.gem.sha512
+- checksums/sof-cycle-0.1.3.gem.sha512
+- checksums/sof-cycle-0.1.4.gem.sha512
+- checksums/sof-cycle-0.1.5.gem.sha512
 - checksums/sof-cycle-0.1.6.gem.sha512
 - checksums/sof-cycle-0.1.7.gem.sha512
 - checksums/sof-cycle-0.1.8.gem.sha512
 - checksums/sof-cycle-0.1.9.gem.sha512
 - lib/sof-cycle.rb
 - lib/sof/cycle.rb
+- lib/sof/cycle/parser.rb
+- lib/sof/cycle/registry.rb
+- lib/sof/cycle/time_span.rb
 - lib/sof/cycle/version.rb
 - lib/sof/cycles/calendar.rb
 - lib/sof/cycles/dormant.rb
 - lib/sof/cycles/end_of.rb
 - lib/sof/cycles/interval.rb
 - lib/sof/cycles/lookback.rb
+- lib/sof/cycles/lookback_end_of.rb
 - lib/sof/cycles/volume_only.rb
 - lib/sof/cycles/within.rb
-- lib/sof/parser.rb
-- lib/sof/time_span.rb
 homepage: https://github.com/SOFware/sof-cycle
 licenses: []
 metadata:
@@ -92,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Parse and interact with SOF cycle notation.
 test_files: []

data/.claude/settings.local.json

@@ -1,17 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(find:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(touch:*)",
-      "Bash(rm:*)",
-      "Bash(bundle exec rspec:*)",
-      "Bash(bundle exec rake:*)",
-      "Bash(bundle exec standardrb:*)",
-      "Bash(git checkout:*)",
-      "Bash(bundle exec ruby:*)"
-    ],
-    "deny": []
-  }
-}

data/lib/sof/parser.rb

@@ -1,109 +0,0 @@
-# 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 Parser
-    extend Forwardable
-    PARTS_REGEX = /
-      ^(?<vol>V(?<volume>\d*))? # optional volume
-      (?<set>(?<kind>L|C|W|E|I) # 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
-      Cycle.cycle_handlers.select(&:dormant_capable?).map(&:notation_id).compact
-    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(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 ||= 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