sof-cycle 0.1.12 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24c5b52ab1efb27e840af6448d16f2d74074310909a00d6d8a9bd10d42466b83
-  data.tar.gz: a7507d727a8c7d87b34a6cabeccd49abaabb9ae29374bed6c9eff70a800d9c9b
+  metadata.gz: 4bf300b22d76c7736f524022360c052b1546fa573ca39e851d4ce2a2ec2de4b7
+  data.tar.gz: 30f5a7972655d52acd3a547f59482c32d6c8fbdf22711f9f23eca27e695053cf
 SHA512:
-  metadata.gz: deb2c0b296fef6fdc65fb0db0e7d92934de2c8a402f96757ac357446e87c2dc4d5cd880e6a8a210aed4bc794ff1977bba1397fb2de96aadd909879566851e783
-  data.tar.gz: e238e4937718f34f644acf024ea4aae39742eee04a9b6d0b75a10df2306219ab8c3ac13abf6d7760e401d9554882f467518348ba0744e1eb51cf0fd2741452b9
+  metadata.gz: 63208d5574eaf86293c0a39214155f7a645b74d51b2dd23bfd03ae83b9dcbd032d145ffd909a8b3a675caef7485f6abe14d5b4bbfcbaafac3c383e29193fa8a7
+  data.tar.gz: e4caecf602ea58c7b0cec5a27b1efe36e23b65d0cf191b9c71eb7415e75a01c05079d4783c75d69e02d1ed31da76ef2765a15bc93ee84d43b39c8f03d615a17d

data/.tool-versions

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

data/CHANGELOG.md

@@ -5,14 +5,18 @@ 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.12] - 2025-09-05
+## [0.1.14] - 2026-04-27
 
-### Added
+## [0.1.13] - 2026-03-20
 
-- Missing code coverage and updated EndOf to properly handle dormant cycles.
+### Added
 
-## [0.1.11] - 2025-09-05
+- Interval cycle kind (`I` notation) — repeating windows anchored to a from_date that re-anchor from completion date (e.g., `V1I24MF2026-03-31`)
 
 ### Changed
 
-- Use `time_span.notation` instead of `TimeSpan.notation` in `Cycle#notation`.
+- 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

data/README.md

@@ -25,7 +25,9 @@ cycle.to_s # => "3x in the prior 3 days"
 
 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).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+This project is managed with [Reissue](https://github.com/SOFware/reissue). Releases are automated via the [shared release workflow](https://github.com/SOFware/reissue/blob/main/.github/workflows/SHARED_WORKFLOW_README.md). Trigger a release by running the "Release gem to RubyGems.org" workflow from the Actions tab.
 
 ## Contributing
 

data/Rakefile

@@ -14,4 +14,5 @@ require "reissue/gem"
 
 Reissue::Task.create do |task|
   task.version_file = "lib/sof/cycle/version.rb"
+  task.push_finalize = :branch
 end

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

@@ -0,0 +1 @@
+e7091d8a602dd216e947b2c0207ad66383b0322646c1b3ab4eacd670cd885035d3bf6e1e5ba3c848466aa9989f298ef8993fd1a260559953bb47a866cc613a52

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.12"
+    VERSION = "0.1.14"
   end
 end

data/lib/sof/cycle.rb

@@ -6,6 +6,7 @@ require_relative "parser"
 module SOF
   class Cycle
     extend ::Forwardable
+
     class InvalidInput < StandardError; end
 
     class InvalidPeriod < InvalidInput; end
@@ -130,6 +131,8 @@ module SOF
       attr_reader :notation_id, :kind, :valid_periods
       def volume_only? = @volume_only
 
+      def dormant_capable? = false
+
       def recurring? = raise "#{name} must implement #{__method__}"
 
       # Raises an error if the given period isn't in the list of valid periods.
@@ -215,12 +218,13 @@ module SOF
 
     attr_reader :parser
 
-    delegate [:activated_notation, :volume, :from, :from_date, :time_span, :period,
+    delegate [:activated_notation, :volume, :from,
+      :from_date, :time_span, :period,
       :humanized_period, :period_key, :active?] => :@parser
     delegate [:kind, :recurring?, :volume_only?, :valid_periods] => "self.class"
     delegate [:period_count, :duration] => :time_span
-    delegate [:calendar?, :dormant?, :end_of?, :lookback?, :volume_only?,
-      :within?] => :kind_inquiry
+    delegate [:calendar?, :dormant?, :end_of?, :interval?, :lookback?,
+      :lookback_end_of?, :volume_only?, :within?] => :kind_inquiry
 
     def kind_inquiry = ActiveSupport::StringInquirer.new(kind.to_s)
 

data/lib/sof/cycles/end_of.rb

@@ -2,7 +2,7 @@
 
 # Captures the logic for enforcing the EndOf cycle variant
 #   E.g. "V1E18MF2020-01-05" means:
-#     You're good until the end of the 17th subsequent month from 2020-01-05.
+#     You're good until the end of the 18th month from 2020-01-05.
 #     Complete 1 by that date to reset the cycle.
 #
 # Some of the calculations are quite different from other cycles.
@@ -18,6 +18,8 @@ module SOF
 
       def self.recurring? = true
 
+      def self.dormant_capable? = true
+
       def self.description
         "End of - occurrences by the end of a time period"
       end
@@ -62,15 +64,15 @@ module SOF
       #
       # @param [nil] _ Unused parameter, maintained for compatibility
       # @return [Date] The final date of the cycle calculated as the end of the
-      #   nth subsequent period after the FROM date, where n = (period count - 1)
+      #   nth period after the FROM date
       #
       # @example
       #   Cycle.for("V1E18MF2020-01-09").final_date
-      #   # => #<Date: 2021-06-30>
+      #   # => #<Date: 2021-07-31>
       def final_date(_ = nil)
         return nil if parser.dormant? || from_date.nil?
         time_span
-          .end_date(start_date - 1.send(period))
+          .end_date(start_date)
           .end_of_month
       end
 
@@ -79,14 +81,11 @@ module SOF
       private
 
       def dormant_to_s
-        <<~DESC.squish
-          #{volume}x by the last day of the #{subsequent_ordinal}
-          subsequent #{period}
-        DESC
+        "#{volume}x by the last day of the #{ordinalized_period_count} #{period}"
       end
 
-      def subsequent_ordinal
-        ActiveSupport::Inflector.ordinalize(period_count - 1)
+      def ordinalized_period_count
+        ActiveSupport::Inflector.ordinalize(period_count)
       end
     end
   end

data/lib/sof/cycles/interval.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Captures the logic for enforcing the Interval cycle variant
+#   E.g. "V1I24MF2026-03-31" means:
+#     Complete 1 every 24 months, current window from 2026-03-31.
+#     After completion, the consuming app re-anchors from the completion date.
+#
+# Unlike EndOf, there is no end-of-month rounding.
+# Unlike Lookback, the window is anchored to a from_date, not sliding from today.
+# Unlike Within, the window is repeating — it re-anchors from the completion date.
+module SOF
+  module Cycles
+    class Interval < Cycle
+      @volume_only = false
+      @notation_id = "I"
+      @kind = :interval
+      @valid_periods = %w[D W M Y]
+
+      def self.recurring? = true
+
+      def self.dormant_capable? = true
+
+      def self.description
+        "Interval - occurrences within a repeating window that re-anchors from completion date"
+      end
+
+      def self.examples
+        ["V1I24MF2026-03-31 - once every 24 months from March 31, 2026 (re-anchors after completion)"]
+      end
+
+      def to_s
+        return dormant_to_s unless active?
+
+        "#{volume}x every #{humanized_span} from #{start_date.to_fs(:american)}"
+      end
+
+      # Returns the expiration date for the current window
+      #
+      # @return [Date, nil] The final date of the current window
+      def expiration_of(_ = nil, anchor: nil)
+        final_date
+      end
+
+      # Is the supplied anchor date within the current window?
+      #
+      # @return [Boolean] true if the anchor is before or on the final date
+      def satisfied_by?(_ = nil, anchor: Date.current)
+        anchor <= final_date
+      end
+
+      # Returns the from_date as the last completed date
+      def last_completed(_ = nil) = from_date&.to_date
+
+      # Calculates the final date of the current window
+      #
+      # @return [Date] from_date + period (no end-of-month rounding)
+      #
+      # @example
+      #   Cycle.for("V1I24MF2026-03-31").final_date
+      #   # => #<Date: 2028-03-31>
+      def final_date(_ = nil)
+        return nil if start_date.nil?
+        time_span.end_date(start_date)
+      end
+
+      def start_date(_ = nil) = from_date&.to_date
+
+      private
+
+      def dormant_to_s
+        "#{volume}x every #{humanized_span}"
+      end
+    end
+  end
+end

data/lib/sof/cycles/lookback_end_of.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class LookbackEndOf < Cycle
+      @volume_only = false
+      @notation_id = "LE"
+      @kind = :lookback_end_of
+      @valid_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/within.rb

@@ -10,6 +10,8 @@ module SOF
 
       def self.recurring? = false
 
+      def self.dormant_capable? = true
+
       def self.description
         "Within - occurrences within a time period from a specific date"
       end

data/lib/sof/parser.rb

@@ -12,15 +12,18 @@ module SOF
   # 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) # kind
+      (?<set>(?<kind>LE|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 = %w[E W]
+    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

data/lib/sof/time_span.rb

@@ -5,6 +5,7 @@ module SOF
   # This is an internal implementation of Cycle behavior.
   class TimeSpan
     extend Forwardable
+
     # TimeSpan objects map Cycle notations to behaviors for their periods
     #
     # For example:
@@ -58,6 +59,7 @@ module SOF
     # quarter, etc.
     class DatePeriod
       extend Forwardable
+
       class << self
         def for(count, period_notation)
           @cached_periods ||= {}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.1.14
 platform: ruby
 authors:
 - Jim Gay
@@ -43,7 +43,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/settings.local.json"
 - ".rspec"
 - ".simplecov"
 - ".tool-versions"
@@ -55,6 +54,7 @@ files:
 - checksums/sof-cycle-0.1.1.gem.sha512
 - 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.2.gem.sha512
 - checksums/sof-cycle-0.1.6.gem.sha512
 - checksums/sof-cycle-0.1.7.gem.sha512
@@ -66,7 +66,9 @@ files:
 - 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
@@ -90,7 +92,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": []
-  }
-}