circulator 2.1.12 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7dbf52b54ebf9536c2d5cac336376e6fa1fadbdd614794bd7322349c714bbc0
-  data.tar.gz: c81382ec182f2d2b2b4f13d73c8228675efed7f5f5ee80886a58d8b77820db76
+  metadata.gz: 9968947252ce58a57128dede22347aba081ed39b515de427868d240e963307f3
+  data.tar.gz: 8b216356c83d0bfc169b94cba44ab23adc153dbc70bef8b4a5dca16e8faf22e0
 SHA512:
-  metadata.gz: c996bdd7a378930fbf14cdfabad9b83b099db386932ea6fab946c38bcd5d649dce25bbc2730b87747b5f46937b55727a06964e8930154b4da23745cf27cdb757
-  data.tar.gz: 24cd2abfe4e710269d4a3a39ed9606bb158b395fa66fa83c5892e9cc060850131c9d9704693a214762eed2efe97ec39a64e4b97378f2e6bda98a1f52ef5adcdf
+  metadata.gz: 706b8085ed7233b1b3f3cf5c1acca0b2f8d1be9c4b61c35188731b22fd5e099bc90efe3bb8fcfa10de4c5ec286410a03efa108c3f6bc2a1609f0d4970dff553a
+  data.tar.gz: 0d35d33444128844ee07ed61acb86ffe94dbf442513af698d600ac566b2ab39de742a05615c69910704faa425e02fdf2993a8b7d4bfbcb47ff1e6639e9a70d92

data/CHANGELOG.md

@@ -5,17 +5,9 @@ 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).
 
-## [2.1.12] - 2026-02-17
-
-### Added
-
-- Named test sampler classes for reuse across test files (b6bcb4e)
-- bang method variants for flow actions (673d8a0)
-- Circulator::InvalidTransition exception class (673d8a0)
-- host-namespaced InvalidTransition subclass per class with flows (673d8a0)
-- flow! instance method and variant: keyword on flow (673d8a0)
-- FLOW_VARIANTS registry that drives method definition (673d8a0)
+## [2.1.14] - 2026-02-24
 
 ### Changed
 
-- Flow attribute writers are private after flow definition Version: minor (35ea18f)
+- Update reissue dependency to 0.4.15 (d11ba8c)
+- Update reissue dependency to 0.4.16 (25c4be7)

data/lib/circulator/flow.rb

@@ -219,6 +219,34 @@ module Circulator
       self
     end
 
+    # Create a deep copy of this flow for a different owning class.
+    # Used when a subclass needs its own copy of a parent's flow
+    # (e.g., when applying extensions to an inherited flow).
+    def dup_for(new_klass)
+      copy = self.class.allocate
+      copy.instance_variable_set(:@klass, new_klass)
+      copy.instance_variable_set(:@attribute_name, @attribute_name)
+      copy.instance_variable_set(:@states, @states.dup)
+      # Procs (@action_missing, @flows_proc, @around) are intentionally shared,
+      # not copied. They are stateless closures that work identically across
+      # parent and child classes.
+      copy.instance_variable_set(:@action_missing, @action_missing)
+      copy.instance_variable_set(:@flows_proc, @flows_proc)
+      copy.instance_variable_set(:@around, @around)
+
+      # Deep copy transition map: action => {from_state => {to:, block:, ...}}
+      new_map = @flows_proc.call
+      @transition_map.each do |action, transitions|
+        new_map[action] = @flows_proc.call
+        transitions.each do |from_state, data|
+          new_map[action][from_state] = data.dup
+        end
+      end
+      copy.instance_variable_set(:@transition_map, new_map)
+
+      copy
+    end
+
     private
 
     def validate_allow_if(allow_if)

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.12"
+  VERSION = "3.0.0"
 end

data/lib/circulator.rb

@@ -79,34 +79,90 @@ module Circulator
 
     private
 
+    # Walk the ancestor chain of +klass+ to find a Flow for +attribute_name+.
+    # Each ancestor is checked under its own model key, since flows are stored
+    # under the declaring class's name.
+    #
+    # Returns the first matching Flow, or nil.
+    def find_inherited_flow(klass, attribute_name)
+      klass.ancestors.drop(1).lazy.filter_map { |a|
+        next unless a.respond_to?(:flows)
+        a_flows = a.instance_variable_get(:@flows)
+        next unless a_flows
+        a_key = Circulator.model_key(a.to_s)
+        a_flows.dig(a_key, attribute_name.to_sym)
+      }.first
+    end
+
+    # Ensure +klass+ has its own local copy of the flow for +attribute_name+.
+    #
+    # If the class already owns a local flow, returns it. Otherwise, looks up
+    # the ancestor chain, deep-copies the inherited flow, stores it on the
+    # child class, and returns the copy.
+    #
+    # Returns the local Flow, or nil if no flow exists anywhere in the chain.
+    def ensure_local_flow(klass, model_key, attribute_name)
+      local_flows = klass.instance_variable_get(:@flows)
+      existing = local_flows&.dig(model_key, attribute_name.to_sym)
+      return existing if existing
+
+      parent_flow = find_inherited_flow(klass, attribute_name)
+      return unless parent_flow
+
+      # Deep-copy parent flow for this subclass
+      copy = parent_flow.dup_for(klass)
+
+      # Store on the child class
+      flows_proc = copy.instance_variable_get(:@flows_proc) || Circulator.default_flow_proc
+      klass.instance_variable_set(:@flows, klass.instance_variable_get(:@flows) || flows_proc.call)
+      klass.instance_variable_get(:@flows)[model_key] ||= flows_proc.call
+      klass.instance_variable_get(:@flows)[model_key][attribute_name.to_sym] = copy
+
+      copy
+    end
+
     def apply_extension_to_existing_flow(class_name, attribute_name, block)
-      # Try to get the class constant
       klass = begin
         Object.const_get(class_name.to_s)
       rescue NameError
-        return # Class doesn't exist yet, extension will be applied when flow is defined
+        return # Class doesn't exist yet
       end
 
-      # Check if the class has flows and the specific attribute flow
-      return unless klass.respond_to?(:flows) && klass.flows
+      return unless klass.respond_to?(:flows)
 
       model_key = Circulator.model_key(klass.to_s)
-      existing_flow = klass.flows.dig(model_key, attribute_name.to_sym)
+      existing_flow = ensure_local_flow(klass, model_key, attribute_name)
       return unless existing_flow
 
-      # Merge the extension into the existing flow
+      # Merge the extension into the (possibly copied) flow
       existing_flow.merge(&block)
 
-      # Re-define flow methods for any new actions/states
+      # Re-define flow methods for new/changed actions
       redefine_flow_methods(klass, attribute_name, existing_flow)
     end
 
+    # Re-define flow action and state methods after an extension is merged.
+    #
+    # Side effect: if the FlowMethods module found in the ancestor chain
+    # belongs to a parent class, this method creates a new FlowMethods
+    # module on +klass+ so that the parent's methods are not mutated.
     def redefine_flow_methods(klass, attribute_name, flow)
+      # Find an existing FlowMethods module in the ancestor chain
       flow_module = klass.ancestors.find { |ancestor|
         ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
       }
       return unless flow_module
 
+      # If the FlowMethods module belongs to a parent class, create a new
+      # one on the child so we don't mutate the parent's methods.
+      if klass.const_defined?(FLOW_MODULE_NAME.to_sym, false)
+        flow_module = klass.const_get(FLOW_MODULE_NAME.to_sym, false)
+      else
+        flow_module = Module.new
+        klass.include flow_module
+        klass.const_set(FLOW_MODULE_NAME.to_sym, flow_module)
+      end
+
       object = nil # Extensions only work on the same class model
 
       # Define or redefine methods for actions (need to redefine if transitions changed)
@@ -131,6 +187,30 @@ module Circulator
         klass.send(:define_state_method, attribute_name:, state:, object:, owner: flow_module)
       end
     end
+
+    # Apply any pending extensions that were registered before the class existed.
+    #
+    # When Circulator.extension is called for a class that doesn't exist yet,
+    # the extension block is stored in the global registry. This method checks
+    # the registry for extensions matching the given class name and applies them.
+    #
+    # Called from the inherited hook when a subclass is defined, and also
+    # lazily from the flows accessor when the class name becomes available
+    # after class creation (e.g., after Object.const_set).
+    def apply_pending_extensions(klass)
+      class_name = klass.name
+      return unless class_name
+
+      Circulator.extensions.each_key do |key|
+        ext_class_name, ext_attribute = key.split(":", 2)
+        next unless ext_class_name == class_name
+
+        attribute_name = ext_attribute.to_sym
+        Circulator.extensions[key].each do |ext_block|
+          apply_extension_to_existing_flow(class_name, attribute_name, ext_block)
+        end
+      end
+    end
   end
 
   FLOW_MODULE_NAME = "FlowMethods"
@@ -275,8 +355,18 @@ module Circulator
   #  # Will log the flow logic according to the with_logging block behavior
   #
   def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
-    @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
+
+    # Check if a parent class already defines this flow
+    parent_flow = Circulator.send(:find_inherited_flow, self, attribute_name)
+
+    if parent_flow
+      raise ArgumentError,
+        "#{self} inherits a :#{attribute_name} flow from a parent class. " \
+        "Use Circulator.extension(#{self}, :#{attribute_name}) to customize it."
+    end
+
+    @flows ||= flows_proc.call
     @flows[model_key] ||= flows_proc.call
     # Pass the flows_proc to Flow so it can create transition_maps of the same type
     @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
@@ -351,10 +441,17 @@ module Circulator
       flow_logic = -> {
         current_value = flow_target.send(attribute_name)
 
+        # Look up transitions dynamically to support inherited+extended flows.
+        # The closure-captured `transitions` may be stale if an extension was
+        # applied after this method was defined (e.g., early extensions on subclasses).
+        # Fall back to the closure-captured transitions if the flow lookup fails.
+        live_flow = flows&.dig(Circulator.model_key(flow_target), attribute_name)
+        current_transitions = live_flow&.transition_map&.[](action) || transitions
+
         transition = if current_value.respond_to?(:to_sym)
-          transitions[current_value.to_sym]
+          current_transitions[current_value.to_sym]
         else
-          transitions[current_value]
+          current_transitions[current_value]
         end
 
         unless transition
@@ -394,7 +491,11 @@ module Circulator
       current_value = flow_target.send(attribute_name)
       current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
 
-      transition = transitions[current_state]
+      # Look up transitions dynamically (same rationale as define_flow_method)
+      live_flow = flows&.dig(Circulator.model_key(flow_target), attribute_name)
+      current_transitions = live_flow&.transition_map&.[](action) || transitions
+
+      transition = current_transitions[current_state]
       unless transition
         raise self.class.const_get(:InvalidTransition),
           "No transition #{action} on #{attribute_name} from #{current_state.inspect}"
@@ -449,7 +550,37 @@ module Circulator
 
   def self.extended(base)
     base.include(InstanceMethods)
-    base.singleton_class.attr_reader :flows
+
+    # Define flows method that walks ancestor chain
+    base.define_singleton_method(:flows) do
+      @flows || ancestors.drop(1).lazy.filter_map { |a|
+        a.instance_variable_get(:@flows) if a.respond_to?(:flows)
+      }.first
+    end
+
+    base.define_singleton_method(:inherited) do |subclass|
+      super(subclass)
+
+      # Track whether pending extensions have been applied for this subclass.
+      # Since inherited fires before the class body block runs (and before
+      # Object.const_set assigns a name), we use lazy application: the first
+      # time flows is accessed on a named subclass, pending extensions are applied.
+      pending_extensions_applied = false
+
+      subclass.define_singleton_method(:flows) do
+        # Lazily apply pending extensions once the class has a name
+        unless pending_extensions_applied
+          if name
+            pending_extensions_applied = true
+            Circulator.send(:apply_pending_extensions, self)
+          end
+        end
+
+        @flows || ancestors.drop(1).lazy.filter_map { |a|
+          a.instance_variable_get(:@flows) if a.respond_to?(:flows)
+        }.first
+      end
+    end
   end
 
   module InstanceMethods
@@ -568,8 +699,31 @@ module Circulator
 
     private
 
+    # Returns the class-level flows hash, aliasing the current instance's
+    # model_key to the parent's flow data when needed.
+    #
+    # Why aliasing is needed: flows are stored under the declaring class's
+    # model_key (e.g. "Parent"), but instance lookups use the instance's own
+    # class key (e.g. "Child"). When a subclass inherits flows without
+    # overriding them, there is no entry for the child's key. We add an alias
+    # entry so that dig(child_key, attribute) resolves correctly.
+    #
+    # The mutation is safe because the alias is idempotent (same value each
+    # time) and just adds a pointer to existing data.
     def flows
-      self.class.flows
+      raw_flows = self.class.flows
+      return nil unless raw_flows
+
+      my_key = Circulator.model_key(self)
+      return raw_flows if raw_flows.key?(my_key)
+
+      # Find the ancestor whose model_key matches a key in the flows hash
+      parent_key = raw_flows.keys.find { |k| raw_flows[k].is_a?(Hash) || raw_flows[k].respond_to?(:dig) }
+      return raw_flows unless parent_key
+
+      # Alias in place — avoids allocating a new Hash on every call.
+      raw_flows[my_key] = raw_flows[parent_key]
+      raw_flows
     end
 
     def check_allow_if(allow_if, *args, **kwargs)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.12
+  version: 3.0.0
 platform: ruby
 authors:
 - Jim Gay