circulator 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0a33536db417f338113b2ef4a5656a38994652f4454f8583ea8e22d626a0e9e
-  data.tar.gz: 394085a68c1a7444192264fa69152be2827663284f4221b844f4fbfcb45cf64b
+  metadata.gz: 20f38e7ccf237cac5499afb5723d5d8f8f4ffe26b3ecbe7e05ee71ad05366438
+  data.tar.gz: e49a9f22259fea102bc6e99d5545590ae4fa40689cd2679318bababba8a5a075
 SHA512:
-  metadata.gz: 4489ca3bf464fe0b37ad3b2e41096fcce05a2d5bcc5348d25e7750f278c666fd10c266e397635846b0093d1ace1064da754d50a0d6973b07f2a4086b5983926d
-  data.tar.gz: 4da4067d6b07dccc9207e17c6095b236dab9f9e7c1d6399f5ff0c475b761b84da34490ec5d8d61ab71678e18fd014b327f6f9358b5aa571b8c70e19306698da6
+  metadata.gz: 6e59f461501d8bd236755dcc30eaa277372e14aca6a61236545ab5df4334f47668fe4878ee4a418bedc539c16891f1fc6cec3f54d88e19ecd9c766146e4b796e
+  data.tar.gz: 4e98a06987e4d08f44cc3cf81ea5544c219bff24a5f08990bac6b2c5c93193a47ce2d9a20aaecb4cdb28fa24cce06420093966b0be49c60f19fe8302198097ec

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.2] - 2025-10-02
 
-### Removed
+### Added
 
-- The `Circulator::Diverter` module has been and features added to `Circulator` itself.
+- Loading of required files with -r command option for circulator-diagram.
+
+### Changed
+
+- Implement diagrams through a standard base class to coordinate implementation.

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,137 @@
+#!/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", require: nil}
+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("-r", "--require FILE", "Require a file before loading the model (e.g., config/environment)") do |file|
+    options[:require] = file
+  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]
+
+# Load the application environment
+# Priority: -r option > config/environment.rb > nothing
+if options[:require]
+  # User specified a file to require
+  require_file = options[:require]
+  unless File.exist?(require_file)
+    warn "Error: Required file '#{require_file}' not found"
+    exit 1
+  end
+  require require_file
+elsif File.exist?("config/environment.rb")
+  # Rails application detected, load the environment
+  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
+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/diagram.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Circulator
+  class Diagram
+    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 << header
+
+      # 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)
+                states.add(:"?")
+                transitions << dynamic_transition(action, from_state, :"?")
+              else
+                states.add(to_state)
+                transitions << standard_transition(action, from_state, to_state, conditional: transition_info[:allow_if])
+              end
+            end
+          end
+        end
+      end
+
+      # Output state nodes
+      states_output(states, output)
+
+      # Output transition edges
+      transitions_output(transitions, output)
+
+      output << footer
+      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 or model_key differs from class_name (model-based flow),
+      # use model_key, otherwise use class_name
+      if class_name.nil? || (model_key && model_key != class_name)
+        "#{model_key} flows"
+      else
+        "#{class_name} flows"
+      end
+    end
+
+    def header
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+
+    def footer
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+
+    def transitions_output(transitions, output)
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+
+    def states_output(states, output)
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+
+    def standard_transition(action, from_state, to_state, conditional: nil)
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+
+    def dynamic_transition(action, from_state, to_state = nil)
+      raise NotImplementedError, "Subclasses must implement #{__method__}"
+    end
+  end
+end

data/lib/circulator/dot.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "diagram"
+
+module Circulator
+  class Dot < Diagram
+    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 or model_key differs from class_name (model-based flow),
+    #   # use model_key, otherwise use class_name
+    #   if class_name.nil? || (model_key && model_key != class_name)
+    #     "#{model_key} flows"
+    #   else
+    #     "#{class_name} flows"
+    #   end
+    # end
+
+    def states_output(states, output)
+      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
+    end
+
+    def transitions_output(transitions, output)
+      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? ? "nil" : transition[:from].to_s
+        to_label = transition[:to].nil? ? "nil" : transition[:to].to_s
+        output << "  #{from_label} -> #{to_label} [label=\"#{transition[:label]}\"];"
+      end
+    end
+
+    def header
+      <<~DOT
+        digraph "#{graph_name}" {
+          rankdir=LR;
+      DOT
+    end
+
+    def footer
+      "}"
+    end
+
+    def dynamic_transition(action, from_state, to_state = nil)
+      {
+        from: from_state,
+        to: to_state,
+        label: "  #{action} (dynamic)"
+      }
+    end
+
+    def standard_transition(action, from_state, to_state, conditional: nil)
+      label = action.to_s
+      label += " (conditional)" if conditional
+
+      {
+        from: from_state,
+        to: to_state,
+        label: label
+      }
+    end
+  end
+end

data/lib/circulator/plantuml.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "diagram"
+
+module Circulator
+  class PlantUml < Diagram
+    private
+
+    # def graph_name
+    #   @model_class.name || "diagram"
+    # end
+
+    def header
+      <<~PLANTUML
+        @startuml #{graph_name}
+        title #{graph_name}
+      PLANTUML
+    end
+
+    def footer
+      <<~PLANTUML
+
+        @enduml
+      PLANTUML
+    end
+
+    def dynamic_transition(action, from_state, to_state = nil)
+      {
+        from: from_state,
+        to: to_state,
+        label: action.to_s,
+        note: "dynamic target state"
+      }
+    end
+
+    def standard_transition(action, from_state, to_state, conditional: nil)
+      note = if conditional
+        "conditional transition"
+      end
+
+      {
+        from: from_state,
+        to: to_state,
+        label: action.to_s,
+        note:
+      }
+    end
+
+    def states_output(states, output)
+      states.reject(&:nil?).sort_by(&:to_s).each do |state|
+        output << "state #{state}"
+      end
+    end
+
+    def transitions_output(transitions, output)
+      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
+    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.2"
 end

metadata

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