sof-cycle 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3012f6707b4790074bd8d39619c93abbca8ffd333c4942365c1b995c321040a
-  data.tar.gz: a9b8032594afa34f6aada7bbd8709cf05898dfb68bdd4f45f3a7e64270853054
+  metadata.gz: bcb187376738c3b567bf2bc9fc68bba6f1cb7e766302a897ab272db848b1b081
+  data.tar.gz: d841689c22f68f7f273d1791feb7753826c3b5c2235deb467fad88ee163ec18f
 SHA512:
-  metadata.gz: 97f6a123c55cc133347ee5cad99639f7105a19397b7a8bfeaad0f72ac9ef0da0748a51bc40a3976816f347e4075463bc18ee9184bfe6837308d2dcc438bd72dc
-  data.tar.gz: 6fa462d207af7d7fc7e659a5e586ad19d5cec3a6042814ba89254974b566054f27ee6dd2efbb661c2804deef174a99c6f3ae5e26e273d57edf7a0f0f0e8a2d4e
+  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,6 +5,12 @@ 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.8] - 2025-09-04
+
+### Changed
+
+- Simplified `handles?` logic to do string comparison instead of symbol comparison.
+
 ## [0.1.7] - 2025-06-09
 
 ### Added
@@ -16,9 +22,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `Cycles::Lookback.volume_to_delay_expiration` now computes correctly when the
   `#considered_dates` is smaller than the `#covered_dates` of the cycle.
-
-## [0.1.6] - 2024-09-04
-
-### Added
-
-- `Cycle.extend_period(count)` to get a new cycle with the modified period count

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.7.gem.sha512

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

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.7"
+    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))
@@ -176,7 +250,7 @@ module SOF
     end
 
     def considered_dates(completion_dates, anchor: Date.current)
-      covered_dates(completion_dates, anchor:).max_by(volume) { _1 }
+      covered_dates(completion_dates, anchor:).max_by(volume) { it }
     end
 
     def covered_dates(dates, anchor: Date.current)

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,6 +10,14 @@ 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:)
@@ -25,7 +33,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

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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Jim Gay
@@ -43,15 +43,18 @@ 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