circulator 2.0.2 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f38e7ccf237cac5499afb5723d5d8f8f4ffe26b3ecbe7e05ee71ad05366438
-  data.tar.gz: e49a9f22259fea102bc6e99d5545590ae4fa40689cd2679318bababba8a5a075
+  metadata.gz: 31b604ea699b2cbe133905f3078e81aa7860bc4e70e52cfd928611b92140b3f8
+  data.tar.gz: e264bd9c50f93fb1ab9f606a0d6b670ce4708304ccdf4a04a67a3a2e588b5bf5
 SHA512:
-  metadata.gz: 6e59f461501d8bd236755dcc30eaa277372e14aca6a61236545ab5df4334f47668fe4878ee4a418bedc539c16891f1fc6cec3f54d88e19ecd9c766146e4b796e
-  data.tar.gz: 4e98a06987e4d08f44cc3cf81ea5544c219bff24a5f08990bac6b2c5c93193a47ce2d9a20aaecb4cdb28fa24cce06420093966b0be49c60f19fe8302198097ec
+  metadata.gz: 80262bad01b9861f1f20459a67c80fbbd77c1f4cf4bc661d5b5918bd727582e8e099871cfd63b29a973fc5998a0c942a0f63aa2ced5894d41de91b5722517b19
+  data.tar.gz: fcbd512e14e020ee4ede8cb34b0432b46c38fbfee246c43a14906f0711302825e633376e8bb1b98c00eee55a24396c5e5814e1fd394dbc8f5a106737a615cb39

data/CHANGELOG.md

@@ -5,12 +5,9 @@ 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.2] - 2025-10-02
+## [2.1.1] - 2025-10-06
 
 ### Added
 
-- Loading of required files with -r command option for circulator-diagram.
-
-### Changed
-
-- Implement diagrams through a standard base class to coordinate implementation.
+- Visual organization for separate flows in generated diagrams
+- Ability to generate separate diagrams for each flow in a class.

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", require: nil}
+options = {format: "dot", require: nil, directory: "docs", separate: false}
 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("-s", "--separate", "Generate separate diagram files for each flow attribute") do
+    options[:separate] = true
+  end
+
   opts.on("-r", "--require FILE", "Require a file before loading the model (e.g., config/environment)") do |file|
     options[:require] = file
   end
@@ -80,7 +88,7 @@ rescue NameError
   exit 1
 end
 
-# Generate diagram file
+# Generate diagram file(s)
 begin
   generator = case options[:format]
   when "plantuml"
@@ -89,9 +97,7 @@ begin
     Circulator::Dot.new(model_class)
   end
 
-  content = generator.generate
-
-  # Determine output filename and extension
+  # Determine base output filename and extension
   # Convert namespaced class names to directory paths
   # Something::Other becomes something/other
   class_name = model_class.name || "diagram"
@@ -100,30 +106,62 @@ begin
   }
   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}"
+  if options[:separate]
+    # Generate separate diagram file for each flow attribute
+    diagrams = generator.generate_separate
+    extension = (options[:format] == "plantuml") ? ".puml" : ".dot"
+
+    diagrams.each do |attribute_name, content|
+      # Create filename with attribute name
+      output_file = File.join(options[:directory], "#{base_name}_#{attribute_name}#{extension}")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      FileUtils.mkdir_p(dir) unless File.exist?(dir)
+
+      File.write(output_file, content)
+      puts "Generated #{options[:format]} file: #{output_file}"
+    end
+
+    puts ""
+    puts "To create images, run:"
+    if options[:format] == "plantuml"
+      puts "  plantuml #{File.join(options[:directory], "#{base_name}_*#{extension}")}"
+    else
+      diagrams.keys.each do |attribute_name|
+        output_file = File.join(options[:directory], "#{base_name}_#{attribute_name}#{extension}")
+        puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], "#{base_name}_#{attribute_name}")}.png"
+      end
+    end
   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"
+    # Generate single combined diagram file
+    content = generator.generate
+
+    if options[:format] == "plantuml"
+      # Use model class name for PlantUML files
+      output_file = File.join(options[:directory], "#{base_name}.puml")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      FileUtils.mkdir_p(dir) unless 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 = File.join(options[:directory], "#{base_name}.dot")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      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 #{File.join(options[:directory], base_name)}.png"
+    end
   end
 
   exit 0

data/lib/circulator/diagram.rb

@@ -20,12 +20,14 @@ module Circulator
       output = []
       output << header
 
-      # Collect all states and transitions
-      states = Set.new
-      transitions = []
+      # Collect states and transitions grouped by attribute
+      flows_data = []
 
       @flows.each do |model_key, attribute_flows|
         attribute_flows.each do |attribute_name, flow|
+          states = Set.new
+          transitions = []
+
           # Extract states and transitions from the flow
           flow.transition_map.each do |action, state_transitions|
             state_transitions.each do |from_state, transition_info|
@@ -41,19 +43,68 @@ module Circulator
               end
             end
           end
+
+          flows_data << {
+            attribute_name: attribute_name,
+            states: states,
+            transitions: transitions
+          }
         end
       end
 
-      # Output state nodes
-      states_output(states, output)
-
-      # Output transition edges
-      transitions_output(transitions, output)
+      # Output flows (grouped or combined based on subclass implementation)
+      flows_output(flows_data, output)
 
       output << footer
       output.join("\n") + "\n"
     end
 
+    # Generate separate diagrams for each flow attribute
+    # Returns a hash mapping attribute_name => diagram_content
+    def generate_separate
+      result = {}
+
+      @flows.each do |model_key, attribute_flows|
+        attribute_flows.each do |attribute_name, flow|
+          states = Set.new
+          transitions = []
+
+          # 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
+
+          # Generate diagram for this flow only
+          output = []
+          output << header_for_attribute(attribute_name)
+
+          flows_data = [{
+            attribute_name: attribute_name,
+            states: states,
+            transitions: transitions
+          }]
+
+          flows_output(flows_data, output)
+          output << footer
+
+          result[attribute_name] = output.join("\n") + "\n"
+        end
+      end
+
+      result
+    end
+
     private
 
     def graph_name
@@ -74,15 +125,15 @@ module Circulator
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def footer
+    def header_for_attribute(attribute_name)
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def transitions_output(transitions, output)
+    def footer
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def states_output(states, output)
+    def flows_output(flows_data, output)
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 

data/lib/circulator/dot.rb

@@ -6,6 +6,49 @@ module Circulator
   class Dot < Diagram
     private
 
+    def flows_output(flows_data, output)
+      if flows_data.size == 1
+        # Single flow: no grouping needed
+        flow = flows_data.first
+        states_output(flow[:states], output)
+        transitions_output(flow[:transitions], output)
+      else
+        # Multiple flows: use subgraph clusters
+        flows_data.each_with_index do |flow, index|
+          output << ""
+          output << "  subgraph cluster_#{index} {"
+          output << "    label=\":#{flow[:attribute_name]}\";"
+          output << "    style=dashed;"
+          output << "    color=blue;"
+          output << ""
+
+          # Output states within this cluster
+          flow[:states].sort_by(&:to_s).each do |state|
+            state_label = state.nil? ? "nil" : state.to_s
+            # Prefix state names with attribute to avoid conflicts
+            prefixed_name = "#{flow[:attribute_name]}_#{state_label}"
+            output << "    #{prefixed_name} [label=\"#{state_label}\", shape=circle];"
+          end
+
+          output << "  }"
+        end
+
+        # Output all transitions after clusters
+        output << ""
+        output << "  // Transitions"
+        flows_data.each do |flow|
+          flow[: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
+            # Use prefixed names
+            prefixed_from = "#{flow[:attribute_name]}_#{from_label}"
+            prefixed_to = "#{flow[:attribute_name]}_#{to_label}"
+            output << "  #{prefixed_from} -> #{prefixed_to} [label=\"#{transition[:label]}\"];"
+          end
+        end
+      end
+    end
+
     # def graph_name
     #   # Use the model class name if available, otherwise use the model key
     #   class_name = @model_class.name
@@ -45,6 +88,14 @@ module Circulator
       DOT
     end
 
+    def header_for_attribute(attribute_name)
+      class_name = @model_class.name || "diagram"
+      <<~DOT
+        digraph "#{class_name} :#{attribute_name} flow" {
+          rankdir=LR;
+      DOT
+    end
+
     def footer
       "}"
     end

data/lib/circulator/plantuml.rb

@@ -6,9 +6,53 @@ module Circulator
   class PlantUml < Diagram
     private
 
-    # def graph_name
-    #   @model_class.name || "diagram"
-    # end
+    def flows_output(flows_data, output)
+      if flows_data.size == 1
+        # Single flow: no grouping needed
+        flow = flows_data.first
+        states_output(flow[:states], output)
+        transitions_output(flow[:transitions], output)
+      else
+        # Multiple flows: use composite states (state containers) with visible labels
+        flows_data.each do |flow|
+          output << ""
+          output << "state \":#{flow[:attribute_name]}\" as #{flow[:attribute_name]}_group {"
+
+          # Output states for this flow
+          flow[:states].reject(&:nil?).sort_by(&:to_s).each do |state|
+            # Replace characters that PlantUML doesn't like in identifiers
+            safe_state = state.to_s.gsub("?", "unknown")
+            prefixed_name = "#{flow[:attribute_name]}_#{safe_state}"
+            output << "  state \"#{state}\" as #{prefixed_name}"
+          end
+
+          output << "}"
+        end
+
+        # Output all transitions after composite states
+        output << ""
+        flows_data.each do |flow|
+          flow[: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
+            # Use prefixed names for non-nil states
+            # Replace characters that PlantUML doesn't like in identifiers
+            safe_from = from_label.gsub("?", "unknown")
+            safe_to = to_label.gsub("?", "unknown")
+            prefixed_from = transition[:from].nil? ? "[*]" : "#{flow[:attribute_name]}_#{safe_from}"
+            prefixed_to = transition[:to].nil? ? "[*]" : "#{flow[:attribute_name]}_#{safe_to}"
+            output << "#{prefixed_from} --> #{prefixed_to} : #{transition[:label]}"
+
+            # Add note if present
+            if transition[:note]
+              output << "note on link"
+              output << "  #{transition[:note]}"
+              output << "end note"
+            end
+          end
+        end
+      end
+    end
 
     def header
       <<~PLANTUML
@@ -17,6 +61,14 @@ module Circulator
       PLANTUML
     end
 
+    def header_for_attribute(attribute_name)
+      class_name = @model_class.name || "diagram"
+      <<~PLANTUML
+        @startuml #{class_name}_#{attribute_name}
+        title #{class_name} :#{attribute_name} flow
+      PLANTUML
+    end
+
     def footer
       <<~PLANTUML
 
@@ -48,7 +100,13 @@ module Circulator
 
     def states_output(states, output)
       states.reject(&:nil?).sort_by(&:to_s).each do |state|
-        output << "state #{state}"
+        # Replace characters that PlantUML doesn't like in identifiers
+        safe_state = state.to_s.gsub("?", "unknown")
+        output << if safe_state != state.to_s
+          "state \"#{state}\" as #{safe_state}"
+        else
+          "state #{state}"
+        end
       end
     end
 
@@ -56,7 +114,10 @@ module Circulator
       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]}"
+        # Replace characters that PlantUML doesn't like in identifiers
+        safe_from = (from_label == "[*]") ? from_label : from_label.gsub("?", "unknown")
+        safe_to = (to_label == "[*]") ? to_label : to_label.gsub("?", "unknown")
+        output << "#{safe_from} --> #{safe_to} : #{transition[:label]}"
 
         # Add note if present
         if transition[:note]

data/lib/circulator/version.rb

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

metadata

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