circulator 2.1.5 → 2.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c511772e424334259794bfff3d3507e5740fc98f0a130c66bf1d77a41862f6a
-  data.tar.gz: 7ee239ac23cbd6998a6d1689f8d6729983b42a6d6081e092465483ee19013107
+  metadata.gz: 128d49edd784a3a0cc8ebc72ee4ca9be581bbea4ab57ff795a7c7435a52e3ddb
+  data.tar.gz: ae4a7ca3dd48197e944c95516f862e9f08cbc082ad098d0ef3d589fe351d59c7
 SHA512:
-  metadata.gz: 63e6165e93a276d89ac6c469c3e8b5db41e6b184cde3290a9ff1332992e7f27a06cf1cd8f8b93c32100986c27be3761d0cfbc9ef7c69414b0cd379f32813c018
-  data.tar.gz: 586cdd39db8b98b10465e84c02de948a44f39c556ae270ea6a68ea8f90ca8c0b61af37917419dfe599e39e882584101169f932671996edbeeb97d6e9debe806d
+  metadata.gz: 5792c5c3fc86dc3a7d75fd619229426a3a8ae8198bee46fe28d7ec54f3d78ca374732c71281177fb53a8e54d5f1ed256af8163cd70420739b4450fb0f5b0589d
+  data.tar.gz: f7fc9e7bf3e10331306a3161c7feff64e09b0dd1933f52f054f98076256c2287e40c6ddd7ac7b6c7eee39bb55442ca3f3045179cc889378d87b9c59eb74dc971

data/CHANGELOG.md

@@ -5,10 +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.5] - 2025-11-15
+## [2.1.6] - 2025-12-08
+
+### Changed
+
+- Dependabot config to follow a 14 day cooldown. (6aabc0a)
 
 ### Added
 
-- Circulator.extension to define changes to existing state machines. (0f0a50f)
-- Circulator.default_flow_proc to allow for custom storage objects. (7ddc442)
-- Test support for custom flows storage with libraries like Contours::BlendedHash. (c7f1f26)
+- 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/version.rb

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

metadata

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