circulator 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42195ffd537b18be888f0bbab239d61d9ff19a2ff91c50adf0d6e51bea4119b0
-  data.tar.gz: ec684979c91e8a5bba4538e6a0c0546d1b23c2746d83b815cc9f43f5cb01fd83
+  metadata.gz: a33499a72d0661bf32e27e39213e4b0193f292eef8537c1946f0eb139e751a91
+  data.tar.gz: 6c3fa67b66bef192886a17cc9d756cb491bce6509127b43b87e7f5ca74347ef4
 SHA512:
-  metadata.gz: eb5064f15bb2d4756139ae66b8a229d35afd9e3df5dd09ae0f8875c522661ffa82c7d0773d6dd088becca25c42f17da350fee347723357d21bd6b67037aa256d
-  data.tar.gz: 1d800dc29d73a0e5f8e88821abba4ec9b3e4d48e109362b5bbd15550a0af4a7e40e2c7a00346c64ac8eebe6d8caf327c57129ea1ae3d09de2129922c235adc0a
+  metadata.gz: 3755e25bcb3a1b34ba3768e8e3b501489dd7827ad9c1695b7365c2ffee9cbf9160181e2bd7226ba49e5c76d1763811e425beef4a0250a28811f22e57f970df98
+  data.tar.gz: 0c970bbeca86d6835911ae4ec7369585a14a9815ff6fc4fcdf28886ae556f0fc3b3d1be97fc301a45799bb5cc3b702681b3160f0072489a5eb96cfdb222fd225

data/CHANGELOG.md

@@ -5,12 +5,8 @@ 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.1] - 2025-10-01
-
-### Changed
-
-- Switched to a rake test task to set the test order
+## [2.1.0] - 2025-10-02
 
 ### Added
 
-- Ability to generate diagrams from declared flows in Dot or PlantUML
+- Configure directory for generating diagrams, defaulting to "docs"

data/exe/circulator-diagram

@@ -8,7 +8,7 @@ require_relative "../lib/circulator/dot"
 require_relative "../lib/circulator/plantuml"
 
 # Parse command-line options
-options = {format: "dot"}
+options = {format: "dot", require: nil, directory: "docs"}
 parser = OptionParser.new do |opts|
   opts.banner = "Usage: circulator-diagram MODEL_NAME [options]"
   opts.separator ""
@@ -23,6 +23,14 @@ parser = OptionParser.new do |opts|
     options[:format] = format
   end
 
+  opts.on("-d", "--directory DIRECTORY", "Output directory. Default: docs") do |directory|
+    options[:directory] = directory
+  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
@@ -52,6 +60,21 @@ 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)
@@ -83,11 +106,11 @@ begin
 
   if options[:format] == "plantuml"
     # Use model class name for PlantUML files
-    output_file = "#{base_name}.puml"
+    output_file = File.join(options[:directory], "#{base_name}.puml")
 
     # Create directory if needed
     dir = File.dirname(output_file)
-    FileUtils.mkdir_p(dir) unless dir == "." || File.exist?(dir)
+    FileUtils.mkdir_p(dir) unless File.exist?(dir)
 
     File.write(output_file, content)
     puts "Generated PlantUML file: #{output_file}"
@@ -95,16 +118,16 @@ begin
     puts "  plantuml #{output_file}"
   else
     # Use model class name for DOT files
-    output_file = "#{base_name}.dot"
+    output_file = File.join(options[:directory], "#{base_name}.dot")
 
     # Create directory if needed
     dir = File.dirname(output_file)
-    FileUtils.mkdir_p(dir) unless dir == "." || File.exist?(dir)
+    FileUtils.mkdir_p(dir) unless 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"
+    puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], base_name)}.png"
   end
 
   exit 0

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

@@ -1,92 +1,71 @@
 # 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
+require_relative "diagram"
 
-    def generate
-      output = []
-      output << "digraph #{graph_name} {"
-      output << "  rankdir=LR;"
-      output << ""
+module Circulator
+  class Dot < Diagram
+    private
 
-      # Collect all states and transitions
-      states = Set.new
-      transitions = []
+    # 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
 
-      @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)
+    #   # 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
 
-              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
+    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"
-
-      # 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
+    end
 
-      output << "}"
-      output.join("\n") + "\n"
+    def header
+      <<~DOT
+        digraph "#{graph_name}" {
+          rankdir=LR;
+      DOT
     end
 
-    private
+    def footer
+      "}"
+    end
+
+    def dynamic_transition(action, from_state, to_state = nil)
+      {
+        from: from_state,
+        to: to_state,
+        label: "  #{action} (dynamic)"
+      }
+    end
 
-    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
+    def standard_transition(action, from_state, to_state, conditional: nil)
+      label = action.to_s
+      label += " (conditional)" if conditional
 
-      # 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
+      {
+        from: from_state,
+        to: to_state,
+        label: label
+      }
     end
   end
 end

data/lib/circulator/plantuml.rb

@@ -1,72 +1,58 @@
 # frozen_string_literal: true
 
+require_relative "diagram"
+
 module Circulator
-  class PlantUml
-    def initialize(model_class)
-      unless model_class.respond_to?(:flows)
-        raise ArgumentError, "Model class must extend Circulator"
-      end
+  class PlantUml < Diagram
+    private
 
-      flows = model_class.flows
-      if flows.nil? || flows.empty?
-        raise ArgumentError, "Model class has no flows defined"
-      end
+    # def graph_name
+    #   @model_class.name || "diagram"
+    # end
 
-      @model_class = model_class
-      @flows = flows
+    def header
+      <<~PLANTUML
+        @startuml #{graph_name}
+        title #{graph_name}
+      PLANTUML
     end
 
-    def generate
-      output = []
-      output << "@startuml"
-      output << ""
+    def footer
+      <<~PLANTUML
 
-      # Collect all states and transitions
-      states = Set.new
-      transitions = []
+        @enduml
+      PLANTUML
+    end
 
-      @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)
+    def dynamic_transition(action, from_state, to_state = nil)
+      {
+        from: from_state,
+        to: to_state,
+        label: action.to_s,
+        note: "dynamic target state"
+      }
+    end
 
-              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
+    def standard_transition(action, from_state, to_state, conditional: nil)
+      note = if conditional
+        "conditional transition"
       end
 
-      # Output state declarations (except nil which is represented as [*])
+      {
+        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
 
-      output << ""
-
-      # Output transitions
+    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
@@ -79,10 +65,6 @@ module Circulator
           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.1"
+  VERSION = "2.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Jim Gay
@@ -22,6 +22,7 @@ files:
 - Rakefile
 - exe/circulator-diagram
 - lib/circulator.rb
+- lib/circulator/diagram.rb
 - lib/circulator/dot.rb
 - lib/circulator/flow.rb
 - lib/circulator/plantuml.rb