circulator 1.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34d38ad852dfc0dea3071103c368fa9d77224c7a390b7fc10c6a39fde2e2b507
-  data.tar.gz: c67068423ece22963cdf64391f0424251a8c23caebf08280a6bb977b1a18bd4b
+  metadata.gz: 42195ffd537b18be888f0bbab239d61d9ff19a2ff91c50adf0d6e51bea4119b0
+  data.tar.gz: ec684979c91e8a5bba4538e6a0c0546d1b23c2746d83b815cc9f43f5cb01fd83
 SHA512:
-  metadata.gz: dc4264165cdb3fdf72ec246dcabc02c0bacff9d20f24a167984e6521517550cc131fd0711f289892c8263fea6ac6c07dcc1d39c0ed77165dbf74d2a3d044f331
-  data.tar.gz: d85440b2e40cc2aa2ff1f7848f5b4dc63b94c2217ebdd7918488967489badb439edcb1c5f39c0b762634f1739ce38405ad19e841a7f4b84c2bb8671262418ec3
+  metadata.gz: eb5064f15bb2d4756139ae66b8a229d35afd9e3df5dd09ae0f8875c522661ffa82c7d0773d6dd088becca25c42f17da350fee347723357d21bd6b67037aa256d
+  data.tar.gz: 1d800dc29d73a0e5f8e88821abba4ec9b3e4d48e109362b5bbd15550a0af4a7e40e2c7a00346c64ac8eebe6d8caf327c57129ea1ae3d09de2129922c235adc0a

data/CHANGELOG.md

@@ -5,8 +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).
 
-## [1.0.0] - 2025-09-11
+## [2.0.1] - 2025-10-01
 
-### 
+### Changed
 
-- Initial release.
+- Switched to a rake test task to set the test order
+
+### Added
+
+- Ability to generate diagrams from declared flows in Dot or PlantUML

data/README.md

@@ -39,7 +39,7 @@ gem install circulator
 
 ```ruby
 class Order
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :status
 
@@ -77,7 +77,7 @@ order.status_deliver  # => :delivered
 
 ```ruby
 class Document
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :state, :reviewed_by
 
@@ -97,7 +97,7 @@ end
 
 ```ruby
 class Task
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :priority, :urgency_level
 
@@ -114,7 +114,7 @@ end
 
 ```ruby
 class Server
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :power_state, :network_state
 
@@ -147,7 +147,7 @@ end
 
 ```ruby
 class Payment
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :status, :processed_at
 
@@ -168,6 +168,18 @@ class Payment
 end
 ```
 
+### Generating Diagrams
+
+You can generate diagrams for your Circulator models using the `circulator-diagram` executable. By default, it will generate a DOT file. You can also generate a PlantUML file by passing the `-f plantuml` option.
+
+```bash
+bundle exec circulator-diagram MODEL_NAME
+```
+
+```bash
+bundle exec circulator-diagram MODEL_NAME -f plantuml
+```
+
 ## Why Circulator?
 
 Circulator distinguishes itself from other Ruby state machine libraries through its simplicity and flexibility:

data/Rakefile

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
+require "rake/testtask"
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+  t.warning = true
+end
 
 require "standard/rake"
 
@@ -15,4 +21,5 @@ Reissue::Task.create :reissue do |task|
   task.version_file = "lib/circulator/version.rb"
   task.changelog_file = "CHANGELOG.md"
   task.version_limit = 1
+  task.fragment = :git
 end

data/exe/circulator-diagram

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+require_relative "../lib/circulator"
+require_relative "../lib/circulator/dot"
+require_relative "../lib/circulator/plantuml"
+
+# Parse command-line options
+options = {format: "dot"}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: circulator-diagram MODEL_NAME [options]"
+  opts.separator ""
+  opts.separator "Generate diagram files for Circulator state machine flows"
+  opts.separator ""
+  opts.separator "Arguments:"
+  opts.separator "  MODEL_NAME    Name of the model class with Circulator flows"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-f", "--format FORMAT", ["dot", "plantuml"], "Output format (dot, plantuml). Default: dot") do |format|
+    options[:format] = format
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit 0
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "circulator-diagram #{Circulator::VERSION}"
+    exit 0
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption => e
+  warn "Error: #{e.message}"
+  warn parser
+  exit 1
+end
+
+# Check for required model name argument
+if ARGV.empty?
+  warn "Error: MODEL_NAME is required"
+  warn ""
+  warn parser
+  exit 1
+end
+
+model_name = ARGV[0]
+
+# Try to constantize the model name
+begin
+  model_class = Object.const_get(model_name)
+rescue NameError
+  warn "Error: Model '#{model_name}' not found"
+  warn "Make sure the model is loaded in your environment"
+  exit 1
+end
+
+# Generate diagram file
+begin
+  generator = case options[:format]
+  when "plantuml"
+    Circulator::PlantUml.new(model_class)
+  else
+    Circulator::Dot.new(model_class)
+  end
+
+  content = generator.generate
+
+  # Determine output filename and extension
+  # Convert namespaced class names to directory paths
+  # Something::Other becomes something/other
+  class_name = model_class.name || "diagram"
+  path_parts = class_name.split("::").map { |part|
+    part.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+  }
+  base_name = path_parts.join("/")
+
+  if options[:format] == "plantuml"
+    # Use model class name for PlantUML files
+    output_file = "#{base_name}.puml"
+
+    # Create directory if needed
+    dir = File.dirname(output_file)
+    FileUtils.mkdir_p(dir) unless dir == "." || File.exist?(dir)
+
+    File.write(output_file, content)
+    puts "Generated PlantUML file: #{output_file}"
+    puts "To create an image, run:"
+    puts "  plantuml #{output_file}"
+  else
+    # Use model class name for DOT files
+    output_file = "#{base_name}.dot"
+
+    # Create directory if needed
+    dir = File.dirname(output_file)
+    FileUtils.mkdir_p(dir) unless dir == "." || File.exist?(dir)
+
+    File.write(output_file, content)
+    puts "Generated DOT file: #{output_file}"
+    puts "To create an image, run:"
+    puts "  dot -Tpng #{output_file} -o #{base_name}.png"
+  end
+
+  exit 0
+rescue ArgumentError => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue => e
+  warn "Error: #{e.class} - #{e.message}"
+  warn e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+  exit 1
+end

data/lib/circulator/dot.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Circulator
+  class Dot
+    def initialize(model_class)
+      unless model_class.respond_to?(:flows)
+        raise ArgumentError, "Model class must extend Circulator"
+      end
+
+      flows = model_class.flows
+      if flows.nil? || flows.empty?
+        raise ArgumentError, "Model class has no flows defined"
+      end
+
+      @model_class = model_class
+      @flows = flows
+    end
+
+    def generate
+      output = []
+      output << "digraph #{graph_name} {"
+      output << "  rankdir=LR;"
+      output << ""
+
+      # Collect all states and transitions
+      states = Set.new
+      transitions = []
+
+      @flows.each do |model_key, attribute_flows|
+        attribute_flows.each do |attribute_name, flow|
+          # Extract states and transitions from the flow
+          flow.transition_map.each do |action, state_transitions|
+            state_transitions.each do |from_state, transition_info|
+              states.add(from_state)
+
+              to_state = transition_info[:to]
+              if to_state.respond_to?(:call)
+                # Dynamic state - use ? as placeholder
+                states.add(:"?")
+                label = "#{action} (dynamic)"
+                transitions << {from: from_state, to: :"?", label: label}
+              else
+                states.add(to_state)
+                label = action.to_s
+                label += " (conditional)" if transition_info[:allow_if]
+                transitions << {from: from_state, to: to_state, label: label}
+              end
+            end
+          end
+        end
+      end
+
+      # Output state nodes
+      output << "  // States"
+      states.sort_by { |s| s.to_s }.each do |state|
+        state_label = state.nil? ? "nil" : state.to_s
+        output << "  #{state_label} [shape=circle];"
+      end
+
+      output << ""
+      output << "  // Transitions"
+
+      # Output transition edges
+      transitions.sort_by { |t| [t[:from].to_s, t[:to].to_s, t[:label]] }.each do |transition|
+        from_label = transition[:from].nil? ? "nil" : transition[:from].to_s
+        to_label = transition[:to].nil? ? "nil" : transition[:to].to_s
+        output << "  #{from_label} -> #{to_label} [label=\"#{transition[:label]}\"];"
+      end
+
+      output << "}"
+      output.join("\n") + "\n"
+    end
+
+    private
+
+    def graph_name
+      # Use the model class name if available, otherwise use the model key
+      class_name = @model_class.name
+      model_key = @flows.keys.first
+
+      # If class has no name, use the model_key which will be like "anonymous_XXX"
+      # If model_key differs from class_name, it's a model-based flow, use model_key
+      if class_name.nil?
+        "#{model_key}_flows"
+      elsif model_key && model_key != class_name
+        "#{model_key}_flows"
+      else
+        "#{class_name}_flows"
+      end
+    end
+  end
+end

data/lib/circulator/flow.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "diverter"
-
 module Circulator
   class Flow
     def initialize(klass, attribute_name, states = Set.new, &block)
@@ -70,4 +68,4 @@ module Circulator
       end
     end
   end
-end
+end

data/lib/circulator/plantuml.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Circulator
+  class PlantUml
+    def initialize(model_class)
+      unless model_class.respond_to?(:flows)
+        raise ArgumentError, "Model class must extend Circulator"
+      end
+
+      flows = model_class.flows
+      if flows.nil? || flows.empty?
+        raise ArgumentError, "Model class has no flows defined"
+      end
+
+      @model_class = model_class
+      @flows = flows
+    end
+
+    def generate
+      output = []
+      output << "@startuml"
+      output << ""
+
+      # Collect all states and transitions
+      states = Set.new
+      transitions = []
+
+      @flows.each do |model_key, attribute_flows|
+        attribute_flows.each do |attribute_name, flow|
+          # Extract states and transitions from the flow
+          flow.transition_map.each do |action, state_transitions|
+            state_transitions.each do |from_state, transition_info|
+              states.add(from_state)
+
+              to_state = transition_info[:to]
+              if to_state.respond_to?(:call)
+                # Dynamic state - use [*] as placeholder (end state)
+                label = action.to_s
+                transitions << {
+                  from: from_state,
+                  to: nil,
+                  label: label,
+                  note: "dynamic target state"
+                }
+              else
+                states.add(to_state)
+                label = action.to_s
+                note = nil
+                note = "conditional transition" if transition_info[:allow_if]
+                transitions << {
+                  from: from_state,
+                  to: to_state,
+                  label: label,
+                  note: note
+                }
+              end
+            end
+          end
+        end
+      end
+
+      # Output state declarations (except nil which is represented as [*])
+      states.reject(&:nil?).sort_by(&:to_s).each do |state|
+        output << "state #{state}"
+      end
+
+      output << ""
+
+      # Output transitions
+      transitions.sort_by { |t| [t[:from].to_s, t[:to].to_s, t[:label]] }.each do |transition|
+        from_label = transition[:from].nil? ? "[*]" : transition[:from].to_s
+        to_label = transition[:to].nil? ? "[*]" : transition[:to].to_s
+        output << "#{from_label} --> #{to_label} : #{transition[:label]}"
+
+        # Add note if present
+        if transition[:note]
+          output << "note on link"
+          output << "  #{transition[:note]}"
+          output << "end note"
+        end
+      end
+
+      output << ""
+      output << "@enduml"
+      output.join("\n") + "\n"
+    end
+  end
+end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -1,3 +1,241 @@
 require "circulator/version"
-require "circulator/diverter"
 require "circulator/flow"
+
+module Circulator
+  # Declare a flow for an attribute.
+  #
+  # Specify the attribute to be used for states and actions.
+  #
+  # Example:
+  #
+  #   flow(:status) do
+  #     state :pending do
+  #       action :approve, to: :approved
+  #     end
+  #   end
+  #
+  # The above declares a flow for the `status` attribute. When in the `pending`
+  # state, the `approve` action will transition the `status` to `approved`.
+  #
+  # This creates a `status_approve` method which will change the state in memory.
+  #
+  # You will also have a instance method `flow` which will allow you to specify
+  # the action to take on the attribute.
+  #
+  # Example:
+  #
+  #   test_object.status_approve
+  #   # OR
+  #   test_object.flow(:approve, :status)
+  #
+  # You can also provide a block to receive arguments
+  #
+  # Example:
+  #
+  #   flow(:status) do
+  #     state :pending do
+  #       action :approve, to: :approved do |*args, **kwargs|
+  #         @args_received = {args: args, kwargs: kwargs}
+  #       end
+  #       action_allowed(:approve) { true } # Optional. Check some value on self
+  #     end
+  #   end
+  #
+  # The block will be evalutaed on the instance of the class declaring the flow.
+  # So `self` inside that action block will be the instance of the class.
+  #
+  # Example:
+  #
+  #   test_object.status_approve("arg1", "arg2", key: "value")
+  #   # @args_received will be {args: ["arg1", "arg2"], kwargs: {key: "value"}}
+  #
+  # If the action is not allowed, the transition will not be executed.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    state :pending do
+  #      action :approve, to: :approved do
+  #        @args_received = {args: args, kwargs: kwargs}
+  #      end
+  #      action_allowed(:approve) { false }
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will not transition because the action is not allowed
+  #
+  # You may also specify the `allow_if` option to check a condition before
+  # the action is allowed. The callable will be evaluated on the instance of
+  # the class declaring the flow. So `self` inside that block will be the
+  # instance of the class.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    state :pending do
+  #      action :approve, to: :approved, allow_if: -> { true }
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will transition to :approved if the condition is true
+  #
+  # If you declare states separately, for example in an enum, you can use the
+  # `action` method to declare the action on the attribute.
+  #
+  # Example:
+  #
+  #  enum :status, {pending: 0, approved: 1, rejected: 2}
+  #  flow(:status) do
+  #    action :approve, to: :approved, from: :pending
+  #    action :reject, to: :rejected, from: :approved do |rejected_at|
+  #      self.rejected_at = rejected_at
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will transition to :approved
+  #  test_object.status_reject
+  #  # Will transition to :rejected and set the rejected_at attribute
+  #
+  # By default, if there is no transition for the current state, the flow will
+  # raise an error. You can specify a no_action block to handle this case.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    no_action { |attribute_name, action| raise "Nope!" }
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will raise an error
+  #
+  # You can also provide a custom action for other behavior for a set of states and
+  # use the `to` option as a callable to set the attribute.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    action :unknown, to: -> { status }, from: [:enforcing, :monitoring, :ignoring] do |signal|
+  #      raise UnhandledSignalError, signal
+  #    end
+  #  end
+  #
+  #  test_object.flow(:unknown, :status, "signal")
+  #  # Will raise an UnhandledSignalError
+  #
+  def flow(attribute_name, model: to_s, &block)
+    @flows ||= {}
+    model_key = Circulator.model_key(model)
+    @flows[model_key] ||= {}
+    @flows[model_key][attribute_name] = Flow.new(model, attribute_name, &block)
+
+    flow_module = ancestors.find { |ancestor|
+      ancestor.name.to_s =~ /FlowMethods/
+    } || Module.new.tap do |mod|
+      include mod
+
+      const_set(:FlowMethods, mod)
+    end
+
+    object = if model == to_s
+      nil
+    else
+      Circulator.methodize_name(model)
+    end
+
+    @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
+      define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
+    end
+  end
+  alias_method :circulator, :flow
+
+  def define_flow_method(attribute_name:, action:, transitions:, object:, owner:)
+    object_attribute_method = [object, attribute_name, action].compact.join("_")
+    raise ArgumentError, "Method already defined: #{object_attribute_method}" if owner.method_defined?(object_attribute_method)
+
+    owner.define_method(object_attribute_method) do |*args, flow_target: self, **kwargs, &block|
+      current_value = flow_target.send(attribute_name)
+
+      transition = if current_value.respond_to?(:to_sym)
+        transitions[current_value.to_sym]
+      else
+        transitions[current_value]
+      end
+
+      unless transition
+        flow_target.instance_exec(attribute_name, action, &flows.dig(Circulator.model_key(flow_target), attribute_name).no_action)
+        return
+      end
+
+      if transition[:allow_if]
+        return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+      end
+
+      if transition[:block]
+        flow_target.instance_exec(*args, **kwargs, &transition[:block])
+      end
+
+      if transition[:to].respond_to?(:call)
+        flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
+      else
+        flow_target.send("#{attribute_name}=", transition[:to])
+      end.tap do
+        if block
+          flow_target.instance_exec(*args, **kwargs, &block)
+        end
+      end
+    end
+  end
+
+  module_function def model_key(object)
+    if object.is_a?(String)
+      if object.start_with?("#<Class:")
+        "anonymous_#{object.split("0x")[1]}".sub(">", "")
+      else
+        object
+      end
+    else
+      model_key(object.class.name || object.class.to_s)
+    end
+  end
+
+  module_function def methodize_name(name)
+    name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2') }.join("_").downcase
+  end
+
+  def self.extended(base)
+    base.include(InstanceMethods)
+    base.singleton_class.attr_reader :flows
+  end
+
+  module InstanceMethods
+    # Use this method to call an action on the attribute.
+    #
+    # Example:
+    #
+    #   test_object.flow(:approve, :status)
+    #   test_object.flow(:approve, :status, "arg1", "arg2", key: "value")
+    def flow(action, attribute, *args, flow_target: self, **kwargs, &block)
+      target_name = if flow_target != self
+        Circulator.methodize_name(Circulator.model_key(flow_target))
+      end
+      external_attribute_name = [target_name, attribute].compact.join("_")
+      method_name = "#{external_attribute_name}_#{action}"
+      if respond_to?(method_name)
+        send(method_name, *args, flow_target:, **kwargs, &block)
+      elsif flow_target.respond_to?(method_name)
+        flow_target.send(method_name, *args, **kwargs, &block)
+      else
+        raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
+      end
+    end
+
+    private
+
+    def flows
+      self.class.flows
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Jim Gay
@@ -12,16 +12,19 @@ dependencies: []
 description: Simple declarative state machine
 email:
 - jim@saturnflyer.com
-executables: []
+executables:
+- circulator-diagram
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - README.md
 - Rakefile
+- exe/circulator-diagram
 - lib/circulator.rb
-- lib/circulator/diverter.rb
+- lib/circulator/dot.rb
 - lib/circulator/flow.rb
+- lib/circulator/plantuml.rb
 - lib/circulator/version.rb
 homepage: https://github.com/SOFware/circulator
 licenses: []

data/lib/circulator/diverter.rb

@@ -1,242 +0,0 @@
-# frozen_string_literal: true
-
-module Circulator
-  module Diverter
-    # Declare a flow for an attribute.
-    #
-    # Specify the attribute to be used for states and actions.
-    #
-    # Example:
-    #
-    #   flow(:status) do
-    #     state :pending do
-    #       action :approve, to: :approved
-    #     end
-    #   end
-    #
-    # The above declares a flow for the `status` attribute. When in the `pending`
-    # state, the `approve` action will transition the `status` to `approved`.
-    #
-    # This creates a `status_approve` method which will change the state in memory.
-    #
-    # You will also have a instance method `flow` which will allow you to specify
-    # the action to take on the attribute.
-    #
-    # Example:
-    #
-    #   test_object.status_approve
-    #   # OR
-    #   test_object.flow(:approve, :status)
-    #
-    # You can also provide a block to receive arguments
-    #
-    # Example:
-    #
-    #   flow(:status) do
-    #     state :pending do
-    #       action :approve, to: :approved do |*args, **kwargs|
-    #         @args_received = {args: args, kwargs: kwargs}
-    #       end
-    #       action_allowed(:approve) { true } # Optional. Check some value on self
-    #     end
-    #   end
-    #
-    # The block will be evalutaed on the instance of the class declaring the flow.
-    # So `self` inside that action block will be the instance of the class.
-    #
-    # Example:
-    #
-    #   test_object.status_approve("arg1", "arg2", key: "value")
-    #   # @args_received will be {args: ["arg1", "arg2"], kwargs: {key: "value"}}
-    #
-    # If the action is not allowed, the transition will not be executed.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    state :pending do
-    #      action :approve, to: :approved do
-    #        @args_received = {args: args, kwargs: kwargs}
-    #      end
-    #      action_allowed(:approve) { false }
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will not transition because the action is not allowed
-    #
-    # You may also specify the `allow_if` option to check a condition before
-    # the action is allowed. The callable will be evaluated on the instance of
-    # the class declaring the flow. So `self` inside that block will be the
-    # instance of the class.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    state :pending do
-    #      action :approve, to: :approved, allow_if: -> { true }
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will transition to :approved if the condition is true
-    #
-    # If you declare states separately, for example in an enum, you can use the
-    # `action` method to declare the action on the attribute.
-    #
-    # Example:
-    #
-    #  enum :status, {pending: 0, approved: 1, rejected: 2}
-    #  flow(:status) do
-    #    action :approve, to: :approved, from: :pending
-    #    action :reject, to: :rejected, from: :approved do |rejected_at|
-    #      self.rejected_at = rejected_at
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will transition to :approved
-    #  test_object.status_reject
-    #  # Will transition to :rejected and set the rejected_at attribute
-    #
-    # By default, if there is no transition for the current state, the flow will
-    # raise an error. You can specify a no_action block to handle this case.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    no_action { |attribute_name, action| raise "Nope!" }
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will raise an error
-    #
-    # You can also provide a custom action for other behavior for a set of states and
-    # use the `to` option as a callable to set the attribute.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    action :unknown, to: -> { status }, from: [:enforcing, :monitoring, :ignoring] do |signal|
-    #      raise UnhandledSignalError, signal
-    #    end
-    #  end
-    #
-    #  test_object.flow(:unknown, :status, "signal")
-    #  # Will raise an UnhandledSignalError
-    #
-    def flow(attribute_name, model: to_s, &block)
-      @flows ||= {}
-      model_key = Circulator::Diverter.model_key(model)
-      @flows[model_key] ||= {}
-      @flows[model_key][attribute_name] = Circulator::Flow.new(model, attribute_name, &block)
-
-      flow_module = ancestors.find { |ancestor|
-        ancestor.name.to_s =~ /FlowMethods/
-      } || Module.new.tap do |mod|
-        include mod
-
-        const_set(:FlowMethods, mod)
-      end
-
-      object = if model == to_s
-        nil
-      else
-        Circulator::Diverter.methodize_name(model)
-      end
-
-      @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
-        define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
-      end
-    end
-    alias_method :circulator, :flow
-
-    def define_flow_method(attribute_name:, action:, transitions:, object:, owner:)
-      object_attribute_method = [object, attribute_name, action].compact.join("_")
-      raise ArgumentError, "Method already defined: #{object_attribute_method}" if owner.method_defined?(object_attribute_method)
-
-      owner.define_method(object_attribute_method) do |*args, flow_target: self, **kwargs, &block|
-        current_value = flow_target.send(attribute_name)
-
-        transition = if current_value.respond_to?(:to_sym)
-          transitions[current_value.to_sym]
-        else
-          transitions[current_value]
-        end
-
-        unless transition
-          flow_target.instance_exec(attribute_name, action, &flows.dig(Circulator::Diverter.model_key(flow_target), attribute_name).no_action)
-          return
-        end
-
-        if transition[:allow_if]
-          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
-        end
-
-        if transition[:block]
-          flow_target.instance_exec(*args, **kwargs, &transition[:block])
-        end
-
-        if transition[:to].respond_to?(:call)
-          flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
-        else
-          flow_target.send("#{attribute_name}=", transition[:to])
-        end.tap do
-          if block
-            flow_target.instance_exec(*args, **kwargs, &block)
-          end
-        end
-      end
-    end
-
-    module_function def model_key(object)
-      if object.is_a?(String)
-        if object.start_with?("#<Class:")
-          "anonymous_#{object.split("0x")[1]}".sub(">", "")
-        else
-          object
-        end
-      else
-        model_key(object.class.name || object.class.to_s)
-      end
-    end
-
-    module_function def methodize_name(name)
-      name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2') }.join("_").downcase
-    end
-
-    def self.extended(base)
-      base.include(InstanceMethods)
-      base.singleton_class.attr_reader :flows
-    end
-
-    module InstanceMethods
-      # Use this method to call an action on the attribute.
-      #
-      # Example:
-      #
-      #   test_object.flow(:approve, :status)
-      #   test_object.flow(:approve, :status, "arg1", "arg2", key: "value")
-      def flow(action, attribute, *args, flow_target: self, **kwargs, &block)
-        target_name = if flow_target != self
-          Circulator::Diverter.methodize_name(Circulator::Diverter.model_key(flow_target))
-        end
-        external_attribute_name = [target_name, attribute].compact.join("_")
-        method_name = "#{external_attribute_name}_#{action}"
-        if respond_to?(method_name)
-          send(method_name, *args, flow_target:, **kwargs, &block)
-        elsif flow_target.respond_to?(method_name)
-          flow_target.send(method_name, *args, **kwargs, &block)
-        else
-          raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
-        end
-      end
-
-      private
-
-      def flows
-        self.class.flows
-      end
-    end
-  end
-end