circulator 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0a33536db417f338113b2ef4a5656a38994652f4454f8583ea8e22d626a0e9e
-  data.tar.gz: 394085a68c1a7444192264fa69152be2827663284f4221b844f4fbfcb45cf64b
+  metadata.gz: 42195ffd537b18be888f0bbab239d61d9ff19a2ff91c50adf0d6e51bea4119b0
+  data.tar.gz: ec684979c91e8a5bba4538e6a0c0546d1b23c2746d83b815cc9f43f5cb01fd83
 SHA512:
-  metadata.gz: 4489ca3bf464fe0b37ad3b2e41096fcce05a2d5bcc5348d25e7750f278c666fd10c266e397635846b0093d1ace1064da754d50a0d6973b07f2a4086b5983926d
-  data.tar.gz: 4da4067d6b07dccc9207e17c6095b236dab9f9e7c1d6399f5ff0c475b761b84da34490ec5d8d61ab71678e18fd014b327f6f9358b5aa571b8c70e19306698da6
+  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).
 
-## [2.0.0] - 2025-09-12
+## [2.0.1] - 2025-10-01
 
-### Removed
+### Changed
 
-- The `Circulator::Diverter` module has been and features added to `Circulator` itself.
+- 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

@@ -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/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 = "2.0.0"
+  VERSION = "2.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Jim Gay
@@ -12,15 +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/dot.rb
 - lib/circulator/flow.rb
+- lib/circulator/plantuml.rb
 - lib/circulator/version.rb
 homepage: https://github.com/SOFware/circulator
 licenses: []