circulator 2.1.4 → 2.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9126192a7ce18956bc8c27842e52765dac25e9436e322ad259100e5138a5b97f
-  data.tar.gz: f1e15524d5806a3f0b0455bd006e8ba5e3914b13e046ab0d2acd1dbcb897ea27
+  metadata.gz: 128d49edd784a3a0cc8ebc72ee4ca9be581bbea4ab57ff795a7c7435a52e3ddb
+  data.tar.gz: ae4a7ca3dd48197e944c95516f862e9f08cbc082ad098d0ef3d589fe351d59c7
 SHA512:
-  metadata.gz: 03ad68c5d43c45fddf1b7d5c3f84dd845363b2bf8cc1a881463efbd1b1e43d233e196e965dae157726b2ac0b90066d9ec05087f12339667ffd1e9effe0213e54
-  data.tar.gz: 7590c58b27a608f4d49f6041c9fed8a4fd5a05526cd5c36eba40a12346ce5a63cd6f9f0a6253c48ec6aa7405e9e4b5ed8121fae276404a1a32f4587118453c2f
+  metadata.gz: 5792c5c3fc86dc3a7d75fd619229426a3a8ae8198bee46fe28d7ec54f3d78ca374732c71281177fb53a8e54d5f1ed256af8163cd70420739b4450fb0f5b0589d
+  data.tar.gz: f7fc9e7bf3e10331306a3161c7feff64e09b0dd1933f52f054f98076256c2287e40c6ddd7ac7b6c7eee39bb55442ca3f3045179cc889378d87b9c59eb74dc971

data/CHANGELOG.md

@@ -5,24 +5,14 @@ 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.4] - 2025-11-03
-
-### Added
-
-- Symbol-based allow_if support (a96b794)
-- Documentation for symbol-based allow_if (d3befc1)
-- available_flows method with guard and argument support (122e2ab)
-- available_flow? predicate method (122e2ab)
-- Documentation for query methods (a75507e)
+## [2.1.6] - 2025-12-08
 
 ### Changed
 
-- Validate symbol allow_if at definition time (392eac5)
+- Dependabot config to follow a 14 day cooldown. (6aabc0a)
 
-### Removed
-
-- Redundant respond_to? check (40ff669)
-
-### Fixed
+### Added
 
-- DOT syntax error for states ending with ? (65b503e)
+- Documentation for extension system and Circulator.extension API (be7c6fc)
+- --all flag to automatically discover and generate diagrams for all classes with Circulator flows (f4dbbfc)
+- Automatic eager loading of Rails application classes when using --all (f4dbbfc)

data/README.md

@@ -285,10 +285,52 @@ class Payment
 end
 ```
 
+#### Extending Flows
+
+You can extend existing flows using `Circulator.extension`:
+
+```ruby
+class Document
+  extend Circulator
+
+  attr_accessor :status
+
+  flow :status do
+    state :draft do
+      action :submit, to: :review
+    end
+
+    state :review do
+      action :approve, to: :approved
+    end
+
+    state :approved
+  end
+end
+
+# Add additional states and transitions
+Circulator.extension(:Document, :status) do
+  state :review do
+    action :reject, to: :rejected
+  end
+
+  state :rejected do
+    action :revise, to: :draft
+  end
+end
+
+doc = Document.new
+doc.status = :review
+doc.status_reject  # => :rejected (from extension)
+doc.status_revise  # => :draft (from extension)
+```
+
 ### 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.
 
+#### Generate a diagram for a specific model:
+
 ```bash
 bundle exec circulator-diagram MODEL_NAME
 ```
@@ -297,6 +339,30 @@ bundle exec circulator-diagram MODEL_NAME
 bundle exec circulator-diagram MODEL_NAME -f plantuml
 ```
 
+#### Generate diagrams for all models with Circulator flows:
+
+Use the `--all` option to automatically find and generate diagrams for all classes that have Circulator flows defined:
+
+```bash
+bundle exec circulator-diagram --all
+```
+
+```bash
+bundle exec circulator-diagram --all -f plantuml
+```
+
+The `--all` option will:
+- Automatically discover all classes with Circulator flows (including classes that inherit from a parent that extends Circulator)
+- Eager load Rails application classes if running in a Rails environment
+- Generate diagrams for each class found
+- Use the same output directory and format options as single-model generation
+
+#### Other options:
+
+- `-d, --directory DIRECTORY` - Specify output directory (default: `docs`)
+- `-s, --separate` - Generate separate diagram files for each flow attribute
+- `-r, --require FILE` - Require a file before loading models (e.g., `config/environment`)
+
 ## Why Circulator?
 
 Circulator distinguishes itself from other Ruby state machine libraries through its simplicity and flexibility:

data/exe/circulator-diagram

@@ -8,17 +8,21 @@ require_relative "../lib/circulator/dot"
 require_relative "../lib/circulator/plantuml"
 
 # Parse command-line options
-options = {format: "dot", require: nil, directory: "docs", separate: false}
+options = {format: "dot", require: nil, directory: "docs", separate: false, all: false}
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: circulator-diagram MODEL_NAME [options]"
+  opts.banner = "Usage: circulator-diagram [MODEL_NAME | --all] [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 "  MODEL_NAME    Name of the model class with Circulator flows (required unless --all is used)"
   opts.separator ""
   opts.separator "Options:"
 
+  opts.on("-a", "--all", "Generate diagrams for all classes with Circulator in their ancestry") do
+    options[:all] = true
+  end
+
   opts.on("-f", "--format FORMAT", ["dot", "plantuml"], "Output format (dot, plantuml). Default: dot") do |format|
     options[:format] = format
   end
@@ -54,15 +58,15 @@ rescue OptionParser::InvalidOption => e
   exit 1
 end
 
-# Check for required model name argument
-if ARGV.empty?
-  warn "Error: MODEL_NAME is required"
+# Check for required model name argument or --all flag
+if ARGV.empty? && !options[:all]
+  warn "Error: Either MODEL_NAME or --all is required"
   warn ""
   warn parser
   exit 1
 end
 
-model_name = ARGV[0]
+model_name = ARGV[0] unless options[:all]
 
 # Load the application environment
 # Priority: -r option > config/environment.rb > nothing
@@ -79,22 +83,63 @@ elsif File.exist?("config/environment.rb")
   require File.expand_path("config/environment.rb")
 end
 
-# 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
+# Find all classes with Circulator in their ancestry
+def find_circulator_classes
+  classes = []
+
+  # Try to force-load classes that might not be loaded yet
+  # This is especially important for Rails apps with lazy loading
+  if defined?(Rails) && Rails.application
+    begin
+      Rails.application.eager_load!
+    rescue => e
+      warn "Warning: Could not eager load Rails application: #{e.message}"
+    end
+  end
+
+  ObjectSpace.each_object(Class) do |klass|
+    # Skip anonymous classes and classes without names
+    next if klass.name.nil? || klass.name.empty?
+
+    # Check if the class responds to :flows (set up when Circulator is extended)
+    next unless klass.respond_to?(:flows)
+
+    begin
+      flows = klass.flows
+      next if flows.nil? || flows.empty?
+    rescue => e
+      # Skip classes where flows method raises an error
+      warn "Warning: Could not get flows for #{klass.name}: #{e.class} - #{e.message}"
+      next
+    end
+
+    classes << klass
+  rescue => e
+    # Skip any class that causes an error during inspection
+    if ENV["DEBUG"]
+      warn "Warning: Error inspecting class #{begin
+        klass.name
+      rescue
+        "unknown"
+      end}: #{e.class} - #{e.message}"
+    end
+    next
+  end
+
+  classes.sort_by(&:name)
 end
 
-# Generate diagram file(s)
-begin
-  generator = case options[:format]
-  when "plantuml"
-    Circulator::PlantUml.new(model_class)
-  else
-    Circulator::Dot.new(model_class)
+# Generate diagram for a single model class
+def generate_diagram_for_class(model_class, options)
+  begin
+    generator = case options[:format]
+    when "plantuml"
+      Circulator::PlantUml.new(model_class)
+    else
+      Circulator::Dot.new(model_class)
+    end
+  rescue => e
+    raise "Failed to initialize diagram generator for #{model_class.name}: #{e.class} - #{e.message}"
   end
 
   # Determine base output filename and extension
@@ -163,6 +208,59 @@ begin
       puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], base_name)}.png"
     end
   end
+end
+
+# Collect classes to generate diagrams for
+begin
+  if options[:all]
+    # Find all classes with Circulator in their ancestry
+    begin
+      classes_to_process = find_circulator_classes
+    rescue => e
+      warn "Error finding Circulator classes: #{e.class} - #{e.message}"
+      warn e.backtrace.first(10).join("\n")
+      exit 1
+    end
+
+    if classes_to_process.empty?
+      warn "No classes with Circulator flows found"
+      exit 1
+    end
+
+    puts "Found #{classes_to_process.size} class(es) with Circulator flows:"
+    classes_to_process.each do |klass|
+      puts "  - #{klass.name}"
+    end
+    puts ""
+  else
+    # 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
+
+    classes_to_process = [model_class]
+  end
+
+  # Generate diagrams for all classes in the array
+  classes_to_process.each do |model_class|
+    if classes_to_process.size > 1
+      puts "Generating diagram for #{model_class.name}..."
+    end
+
+    begin
+      generate_diagram_for_class(model_class, options)
+    rescue => e
+      warn "Error generating diagram for #{model_class.name}: #{e.class} - #{e.message}"
+      warn e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+      next
+    end
+
+    puts "" if classes_to_process.size > 1
+  end
 
   exit 0
 rescue ArgumentError => e

data/lib/circulator/flow.rb

@@ -2,13 +2,19 @@
 
 module Circulator
   class Flow
-    def initialize(klass, attribute_name, states = Set.new, &block)
+    def initialize(klass, attribute_name, states = Set.new, extension: false, flows_proc: Circulator.default_flow_proc, &block)
       @klass = klass
       @attribute_name = attribute_name
       @states = states
       @no_action = ->(attribute_name, action) { raise "No action found for the current state of #{attribute_name} (#{send(attribute_name)}): #{action}" }
-      @transition_map = {}
-      instance_eval(&block)
+      @flows_proc = flows_proc
+      @transition_map = flows_proc.call
+
+      # Execute the main flow block
+      instance_eval(&block) if block
+
+      # Apply any registered extensions (unless explicitly disabled)
+      apply_extensions unless extension
     end
     attr_reader :transition_map
 
@@ -28,7 +34,7 @@ module Circulator
         validate_allow_if(allow_if)
       end
 
-      @transition_map[name] ||= {}
+      @transition_map[name] ||= @flows_proc.call
       selected_state = (from == :__not_specified__) ? @current_state : from
 
       # Handle nil case specially - convert to [nil] instead of []
@@ -48,8 +54,10 @@ module Circulator
           @states.add(to_state)
         end
 
-        @transition_map[name][from_state] = {to:, block:}
-        @transition_map[name][from_state][:allow_if] = allow_if if allow_if
+        # Build transition data hash with all keys at once
+        transition_data = {to:, block:}
+        transition_data[:allow_if] = allow_if if allow_if
+        @transition_map[name][from_state] = transition_data
       end
     end
 
@@ -132,5 +140,33 @@ module Circulator
         raise ArgumentError, "allow_if references invalid states #{invalid_states.inspect} for :#{attribute_name}. Valid states: #{referenced_states.to_a.inspect}"
       end
     end
+
+    def apply_extensions
+      # Look up extensions for this class and attribute
+      class_name = if @klass.is_a?(Class)
+        @klass.name || @klass.to_s
+      else
+        Circulator.model_key(@klass)
+      end
+      key = "#{class_name}:#{@attribute_name}"
+      extensions = Circulator.extensions[key]
+
+      # Apply each extension by creating a new Flow and merging its transition_map
+      extensions.each do |extension_block|
+        extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &extension_block)
+        extension_flow.transition_map.each do |action, transitions|
+          @transition_map[action] = if @transition_map[action]
+            @transition_map[action].merge(transitions)
+          else
+            transitions
+          end
+        end
+
+        # Merge states from extension
+        extension_flow.instance_variable_get(:@states).each do |state|
+          @states.add(state)
+        end
+      end
+    end
   end
 end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -2,6 +2,32 @@ require "circulator/version"
 require "circulator/flow"
 
 module Circulator
+  # Global registry for extensions
+  @extensions = Hash.new { |h, k| h[k] = [] }
+
+  @default_flow_proc = ::Hash.method(:new)
+  class << self
+    attr_reader :extensions
+    attr_reader :default_flow_proc
+
+    # Register an extension for a specific class and attribute
+    #
+    # Example:
+    #
+    #   Circulator.extension(:Document, :status) do
+    #     state :pending do
+    #       action :send_to_legal, to: :legal_review
+    #     end
+    #   end
+    #
+    # Extensions are automatically applied when the class defines its flow
+    def extension(class_name, attribute_name, &block)
+      raise ArgumentError, "Block required for extension" unless block_given?
+
+      key = "#{class_name}:#{attribute_name}"
+      @extensions[key] << block
+    end
+  end
   # Declare a flow for an attribute.
   #
   # Specify the attribute to be used for states and actions.
@@ -125,11 +151,12 @@ module Circulator
   #  test_object.flow(:unknown, :status, "signal")
   #  # Will raise an UnhandledSignalError
   #
-  def flow(attribute_name, model: to_s, &block)
-    @flows ||= {}
+  def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
+    @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
-    @flows[model_key] ||= {}
-    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, &block)
+    @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)
 
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /FlowMethods/

metadata

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