sof-cycle 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33cc5f466f7776bd9476664153cf9ae0e3f898132b348cffa0117a911ad7dda6
-  data.tar.gz: a30b3ea58dce3a953531deffba10f9199af3b283fdf70f99d7af55988aef428e
+  metadata.gz: bcb187376738c3b567bf2bc9fc68bba6f1cb7e766302a897ab272db848b1b081
+  data.tar.gz: d841689c22f68f7f273d1791feb7753826c3b5c2235deb467fad88ee163ec18f
 SHA512:
-  metadata.gz: ce71b8b026ee7e78c6d6568dea2a88eb2d5faee74cbc4cc4e7c6f78bf7e328b46ba7017e71acf75f7b8613204e6e7a56b9592987d559c5883c1901ead1119718
-  data.tar.gz: 306c295e768f6616c80ebe3ee8adbfb734d64b01b2b4fd5d52a45ac9e913752b660bbc7a77129adfd66fb517adb6c0217ec11f4c62518c32620c788a3803c91b
+  metadata.gz: f193e2a83e149315956c99df5efebabfd05c9ade453bb4e4763db1a39870c62c63bae5e6c82379bddd1f07a85a1a6f898fb90d53a753f0936f146efdf6e5f786
+  data.tar.gz: 7000bd01fd3c3302756b757b406f36ec75db9125a3acf597e5c6fb54ab811356e076b4d45087098db94ffb4d4f0151b33d8bd4ce3c1ebe4e4844ae20029aec66

data/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "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/.simplecov

@@ -1,4 +1,10 @@
 require "simplecov"
+require "simplecov_json_formatter"
+
 SimpleCov.start do
+  formatter SimpleCov::Formatter::MultiFormatter.new([
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::JSONFormatter
+  ])
   add_filter "/spec/"
 end

data/CHANGELOG.md

@@ -5,14 +5,20 @@ 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.6] - 2024-09-04
+## [0.1.8] - 2025-09-04
 
-### Added
+### Changed
+
+- Simplified `handles?` logic to do string comparison instead of symbol comparison.
 
-- `Cycle.extend_period(count)` to get a new cycle with the modified period count
+## [0.1.7] - 2025-06-09
+
+### Added
 
-## [0.1.5] - 2024-09-02
+- `Cycle#considered_dates` to get the subset of `#covered_dates` that are
+  considered for the cycle's calculations.
 
 ### Fixed
 
-- `Cycle#last_completed` works for dormant cycles too
+- `Cycles::Lookback.volume_to_delay_expiration` now computes correctly when the
+  `#considered_dates` is smaller than the `#covered_dates` of the cycle.

data/CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+## Agent OS Documentation
+
+### Product Context
+- **Mission & Vision:** @.agent-os/product/mission.md
+- **Technical Architecture:** @.agent-os/product/tech-stack.md
+- **Development Roadmap:** @.agent-os/product/roadmap.md
+- **Decision History:** @.agent-os/product/decisions.md
+
+### Development Standards
+- **Code Style:** @~/.agent-os/standards/code-style.md
+- **Best Practices:** @~/.agent-os/standards/best-practices.md
+
+### Project Management
+- **Active Specs:** @.agent-os/specs/
+- **Spec Planning:** Use `@~/.agent-os/instructions/create-spec.md`
+- **Tasks Execution:** Use `@~/.agent-os/instructions/execute-tasks.md`
+
+## Workflow Instructions
+
+When asked to work on this codebase:
+
+1. **First**, check @.agent-os/product/roadmap.md for current priorities
+2. **Then**, follow the appropriate instruction file:
+   - For new features: @~/.agent-os/instructions/create-spec.md
+   - For tasks execution: @~/.agent-os/instructions/execute-tasks.md
+3. **Always**, adhere to the standards in the files listed above
+
+## Important Notes
+
+- Product-specific files in `.agent-os/product/` override any global standards
+- User's specific instructions override (or amend) instructions found in `.agent-os/specs/...`
+- Always adhere to established patterns, code style, and best practices documented above.

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

@@ -0,0 +1 @@
+4a0a79b2c4566319f3a28a400b5c5e471a4d3e6acf979f02b38546cfab34c11d4dd1b1b5118eab0b5cbcab77ed54fb896dc81f4fa58afe41ae437ed79f44f235

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

@@ -0,0 +1 @@
+10f35795f9559afbf1b87c26b76c5458fbdca373705539bfb55e3702c372b9198dba2cf1986489c5a95b55359dcdcfe39e27b10564e6570a94552ab95f31de7f

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.6"
+    VERSION = "0.1.8"
   end
 end

data/lib/sof/cycle.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
+require "forwardable"
 require_relative "parser"
 
 module SOF
   class Cycle
-    extend Forwardable
+    extend ::Forwardable
     class InvalidInput < StandardError; end
 
     class InvalidPeriod < InvalidInput; end
@@ -99,12 +100,26 @@ module SOF
         end || raise(InvalidKind, "':#{sym}' is not a valid kind of Cycle")
       end
 
-      def cycle_handlers = @cycle_handlers ||= Set.new
-
-      def inherited(klass) = cycle_handlers << klass
-
-      def handles?(sym)
-        sym && kind == sym.to_sym
+      # Return a legend explaining all notation components
+      #
+      # @return [Hash] hash with notation components organized by category
+      def legend
+        {
+          "quantity" => {
+            "V" => {
+              description: "Volume - the number of times something should occur",
+              examples: ["V1L1D - once in the prior 1 day", "V3L3D - three times in the prior 3 days", "V10L10D - ten times in the prior 10 days"]
+            }
+          },
+          "kind" => build_kind_legend,
+          "period" => build_period_legend,
+          "date" => {
+            "F" => {
+              description: "From - specifies the anchor date for Within cycles",
+              examples: ["F2024-01-01 - from January 1, 2024", "F2024-12-31 - from December 31, 2024"]
+            }
+          }
+        }
       end
 
       @volume_only = false
@@ -127,6 +142,65 @@ module SOF
           #{valid_periods.join(", ")}
         ERR
       end
+
+      def handles?(sym)
+        kind.to_s == sym.to_s
+      end
+
+      def cycle_handlers
+        @cycle_handlers ||= Set.new
+      end
+
+      def inherited(klass)
+        cycle_handlers << klass
+      end
+
+      private
+
+      def build_kind_legend
+        legend = {}
+        cycle_handlers.each do |handler|
+          # Skip volume_only since it doesn't have a notation_id
+          next if handler.instance_variable_get(:@volume_only)
+
+          notation_id = handler.instance_variable_get(:@notation_id)
+          next unless notation_id
+
+          legend[notation_id] = {
+            description: handler.description,
+            examples: handler.examples
+          }
+        end
+        legend
+      end
+
+      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"
+        }
+
+        period_mappings.each do |code, period_name|
+          legend[code] = {
+            description: "#{period_name.capitalize} - period notation",
+            examples: period_examples_for(code, period_name)
+          }
+        end
+        legend
+      end
+
+      def period_examples_for(code, period_name)
+        base_example = (code == "D") ? "3#{code} - 3 #{period_name}s" : "2#{code} - 2 #{period_name}s"
+        lookback_example = "L#{(code == "D") ? "7" : "4"}#{code} - in the prior #{(code == "D") ? "7" : "4"} #{period_name}s"
+        calendar_example = "C1#{code} - this calendar #{period_name}"
+
+        [base_example, lookback_example, calendar_example]
+      end
     end
 
     def initialize(notation, parser: Parser.new(notation))
@@ -175,6 +249,10 @@ module SOF
       covered_dates(completion_dates, anchor:).size >= volume
     end
 
+    def considered_dates(completion_dates, anchor: Date.current)
+      covered_dates(completion_dates, anchor:).max_by(volume) { it }
+    end
+
     def covered_dates(dates, anchor: Date.current)
       dates.select do |date|
         cover?(date, anchor:)

data/lib/sof/cycles/calendar.rb

@@ -10,6 +10,14 @@ module SOF
 
       class << self
         def frame_of_reference = "total"
+
+        def description
+          "Calendar - occurrences within the current calendar period"
+        end
+
+        def examples
+          ["V2C1M - twice this calendar month", "V4C1Y - 4 times this calendar year"]
+        end
       end
 
       def self.recurring? = true
@@ -22,7 +30,7 @@ module SOF
       # @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
+        anchor = completion_dates.max_by(volume) { it }.min
         return unless satisfied_by?(completion_dates, anchor:)
 
         window_end(anchor) + duration

data/lib/sof/cycles/end_of.rb

@@ -18,6 +18,14 @@ module SOF
 
       def self.recurring? = true
 
+      def self.description
+        "End of - occurrences by the end of a time period"
+      end
+
+      def self.examples
+        ["V1E1M - once by the end of next month", "V2E2Q - twice by the end of 2 quarters"]
+      end
+
       def to_s
         return dormant_to_s if dormant?
 

data/lib/sof/cycles/lookback.rb

@@ -10,18 +10,30 @@ module SOF
 
       def self.recurring? = true
 
+      def self.description
+        "Lookback - occurrences within a prior time period counting backwards from today"
+      end
+
+      def self.examples
+        ["V3L3D - 3 times in the prior 3 days", "V1L2W - once in the prior 2 weeks"]
+      end
+
       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
+        relevant_dates = considered_dates(completion_dates, anchor:)
+        return unless satisfied_by?(relevant_dates, anchor:)
+
+        # To move the expiration date, we need to displace each occurance of the
+        # oldest date within #considered_dates.
+        relevant_dates.count(relevant_dates.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
+        anchor = completion_dates.max_by(volume) { it }.min
         return unless satisfied_by?(completion_dates, anchor:)
 
         window_end anchor

data/lib/sof/cycles/volume_only.rb

@@ -9,7 +9,7 @@ module SOF
       @valid_periods = []
 
       class << self
-        def handles?(sym) = sym.nil? || super
+        def handles?(sym) = sym.nil? || sym.to_s == "volume_only"
 
         def validate_period(period)
           raise InvalidPeriod, <<~ERR.squish unless period.nil?

data/lib/sof/cycles/within.rb

@@ -10,6 +10,14 @@ module SOF
 
       def self.recurring? = false
 
+      def self.description
+        "Within - occurrences within a time period from a specific date"
+      end
+
+      def self.examples
+        ["V2W3DF2024-01-01 - twice within 3 days from Jan 1, 2024"]
+      end
+
       def to_s = "#{volume}x within #{date_range}"
 
       def extend_period(count)
@@ -23,7 +31,7 @@ module SOF
       def date_range
         return humanized_span unless active?
 
-        [start_date, final_date].map { _1.to_fs(:american) }.join(" - ")
+        [start_date, final_date].map { it.to_fs(:american) }.join(" - ")
       end
 
       def final_date(_ = nil) = time_span.end_date(start_date)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Jim Gay
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwardable
@@ -38,21 +37,24 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
-description:
 email:
 - jim@saturnflyer.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/settings.local.json"
 - ".rspec"
 - ".simplecov"
 - CHANGELOG.md
+- CLAUDE.md
 - README.md
 - Rakefile
 - checksums/sof-cycle-0.1.0.gem.sha512
 - checksums/sof-cycle-0.1.1.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
 - lib/sof-cycle.rb
 - lib/sof/cycle.rb
 - lib/sof/cycle/version.rb
@@ -69,7 +71,6 @@ 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
@@ -84,8 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Parse and interact with SOF cycle notation.
 test_files: []