state_machines-diagram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dea8376942dd89e9671884fffabcf95cefb34e39e4c6366a6413deca1f965d0f
+  data.tar.gz: 9dbc0c5784bcf3b68b07f57fcde2681b7623d05ace83582dfe0c7a8c8e3a8c66
+SHA512:
+  metadata.gz: ff56f38bbb64f4d539f5b6418e6ffa8f90627f47c1401b30f63f845815ce666bdc5b0661ffc019383346e0fd99fa896c75e8425d31f894c84c24ccfee9d82cd0
+  data.tar.gz: 1345f579d826b86595a08b7a1a7c82d1521ccd83bb53af1165bc870b91b811af96ab9bc7e267d0ad610d11c2f08b0cea834948c1de3bc624258922de42e08d60

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,349 @@
+# StateMachines::Diagram - Extensible Core for State Machine Visualization
+
+[![CI](https://github.com/state-machines/state_machines-diagram/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/state-machines/state_machines-diagram/actions/workflows/ruby.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby](https://img.shields.io/badge/ruby-3.3%2B-red.svg)](state_machines-diagram.gemspec)
+
+An extensible diagram building foundation for the state_machines ecosystem. This gem provides a structured intermediate representation (IR) and adapter framework that enables consistent visualization across multiple output formats.
+
+## Quick Start
+
+```ruby
+# 1. Define a state machine using any supported library
+require 'state_machines'
+
+class Order
+  state_machine :status, initial: :pending do
+    state :pending, :processing, :shipped, :cancelled
+    
+    event :process do
+      transition pending: :processing, if: :payment_cleared?
+    end
+    
+    event :ship do
+      transition processing: :shipped, action: :send_notification
+    end
+    
+    event :cancel do
+      transition [:pending, :processing] => :cancelled
+    end
+  end
+  
+  def payment_cleared?
+    @payment_cleared ||= false
+  end
+  
+  def send_notification
+    puts "Order shipped!"
+  end
+end
+
+# 2. Generate diagram representation
+require 'state_machines-diagram'
+
+# Text format (default)
+Order.state_machine(:status).draw
+# Output:
+# Status: pending → processing [process] (if: payment_cleared?)
+# Status: processing → shipped [ship] (action: send_notification)
+# Status: pending → cancelled [cancel]
+# Status: processing → cancelled [cancel]
+
+# JSON structure  
+Order.state_machine(:status).draw(format: :json)
+# Output: {"states": [...], "transitions": [...]}
+
+# With specific rendering gem
+require 'state_machines-mermaid'
+Order.state_machine(:status).draw(format: :mermaid)
+# Output:
+# stateDiagram-v2
+#   pending --> processing : process (if: payment_cleared?)
+#   processing --> shipped : ship (action: send_notification)
+#   pending --> cancelled : cancel
+#   processing --> cancelled : cancel
+```
+
+## Architecture
+
+This gem implements a structured data transformation pipeline:
+
+```
+StateMachine → Builder → Diagrams::StateDiagram → Renderer → Output
+```
+
+### Core Components
+
+#### 1. Intermediate Representation (IR)
+
+The `Diagrams::StateDiagram` IR uses immutable `Dry::Struct` objects to represent state machine structure:
+
+```ruby
+# State representation
+Diagrams::Elements::State = Dry::Struct do
+  attribute :id, Types::Strict::String
+  attribute :state_type, Types::StateType  # :initial, :final, :normal
+  attribute :name, Types::Strict::String.optional
+end
+
+# Transition representation with semantic information
+Diagrams::Elements::Transition = Dry::Struct do
+  attribute :source_state_id, Types::Strict::String
+  attribute :target_state_id, Types::Strict::String
+  attribute :label, Types::Strict::String.optional
+  attribute :guard, Types::Strict::String.optional    # if: condition
+  attribute :action, Types::Strict::String.optional   # callback method
+end
+
+# Complete diagram structure
+Diagrams::StateDiagram = Dry::Struct do
+  attribute :states, Types::Array.of(Diagrams::Elements::State)
+  attribute :transitions, Types::Array.of(Diagrams::Elements::Transition)
+  attribute :title, Types::Strict::String.optional
+end
+```
+
+#### 2. Builder Contract
+
+The `StateMachines::Diagram::Builder` extracts semantic information from state machines:
+
+```ruby
+# Core building method
+diagram = StateMachines::Diagram::Builder.build_state_diagram(machine, options)
+
+# Builder handles:
+# - State extraction with type detection
+# - Transition mapping with guard conditions  
+# - Callback extraction (before/after/around)
+# - Event-to-transition resolution
+# - Filtering (state_filter, event_filter)
+```
+
+#### 3. Renderer Interface
+
+Renderers implement a standardized contract:
+
+```ruby
+module StateMachines::Diagram::Renderer
+  # Required method for all renderers
+  def self.draw_machine(machine, io: $stdout, **options)
+    diagram = build_state_diagram(machine, options)
+    output_diagram(diagram, io, options)
+  end
+  
+  private
+  
+  # Override this method for custom output
+  def self.output_diagram(diagram, io, options)
+    # Your rendering logic here
+  end
+end
+```
+
+## Error Handling
+
+The gem provides robust error handling for common edge cases:
+
+```ruby
+begin
+  diagram = StateMachines::Diagram::Builder.build_state_diagram(machine)
+rescue StateMachines::Diagram::InvalidStateError => e
+  puts "Invalid state configuration: #{e.message}"
+rescue StateMachines::Diagram::TransitionError => e
+  puts "Transition error: #{e.message}"
+end
+
+# Validate diagram structure
+if diagram.states.empty?
+  raise StateMachines::Diagram::EmptyDiagramError, "No states found"
+end
+```
+
+## Advanced Usage
+
+### Custom Renderer Example
+
+```ruby
+module MyPlantUMLRenderer
+  extend StateMachines::Diagram::Renderer
+  
+  private
+  
+  def self.output_diagram(diagram, io, options)
+    io.puts "@startuml"
+    io.puts "title #{diagram.title}" if diagram.title
+    
+    diagram.states.each do |state|
+      io.puts "state #{state.id}"
+    end
+    
+    diagram.transitions.each do |transition|
+      line = "#{transition.source_state_id} --> #{transition.target_state_id}"
+      line += " : #{transition.label}" if transition.label
+      
+      annotations = []
+      annotations << "#{transition.guard}" if transition.guard  
+      annotations << "#{transition.action}" if transition.action
+      line += " [#{annotations.join(', ')}]" unless annotations.empty?
+      
+      io.puts line
+    end
+    
+    io.puts "@enduml"
+  end
+end
+
+# Use the custom renderer
+StateMachines::Machine.renderer = MyPlantUMLRenderer
+Order.state_machine(:status).draw
+```
+
+### Complex State Machine Support
+
+```ruby
+class Dragon
+  # Multiple parallel state machines
+  state_machine :mood, initial: :sleeping do
+    state :sleeping, :hunting, :hoarding
+    
+    event :wake_up do
+      transition sleeping: :hunting, if: :hungry?
+      transition sleeping: :hoarding, unless: :hungry?
+    end
+    
+    event :find_treasure do
+      transition hoarding: :hoarding  # Self-transition
+    end
+  end
+  
+  state_machine :flight, initial: :grounded do
+    state :grounded, :airborne
+    
+    event :take_off do
+      transition grounded: :airborne, action: :spread_wings
+    end
+  end
+  
+  def hungry?
+    @hunger_level > 5
+  end
+  
+  def spread_wings
+    puts "Dragon spreads mighty wings!"
+  end
+end
+
+# Generate diagrams for each state machine
+Dragon.state_machine(:mood).draw(show_conditions: true)
+Dragon.state_machine(:flight).draw(show_callbacks: true)
+```
+
+### Filtering and Options
+
+```ruby
+# Focus on specific state
+Order.state_machine(:status).draw(state_filter: :processing)
+
+# Focus on specific event  
+Order.state_machine(:status).draw(event_filter: :ship)
+
+# Show semantic information
+Order.state_machine(:status).draw(show_conditions: true, show_callbacks: true)
+
+# Human-readable names
+Order.state_machine(:status).draw(human_names: true)
+
+# Output to file
+File.open('order_diagram.json', 'w') do |file|
+  Order.state_machine(:status).draw(io: file, format: :json)
+end
+```
+
+## Testing Strategy
+
+The gem includes comprehensive test coverage with robust fixtures:
+
+```bash
+# Run all tests
+rake test
+
+# Test specific components
+ruby -Itest test/unit/builder_test.rb
+ruby -Itest test/unit/renderer_test.rb
+
+# Lint code
+bundle exec rubocop
+```
+
+### Test Coverage
+
+- **Builder Tests**: State extraction, transition mapping, guard condition handling
+- **Renderer Tests**: Output format validation, option handling, error cases
+- **Integration Tests**: End-to-end workflows with complex state machines
+- **Edge Case Tests**: Invalid states, circular transitions, missing callbacks
+
+## Ecosystem Integration
+
+This gem serves as the foundation for rendering-specific gems:
+
+- **`state_machines-diagram`** (this gem): Core diagram building and IR
+- **`state_machines-mermaid`**: Mermaid syntax renderer
+- **`state_machines-graphviz`**: GraphViz DOT format renderer (planned)
+- **Custom renderers**: PlantUML, SVG, ASCII art, etc.
+
+### Supported State Machine Libraries
+
+- `state_machines` (primary)
+- `state_machines-activerecord`
+- `state_machines-activemodel`
+
+### Ruby Version Support
+
+- **Ruby 3.3+**: Required for pattern matching and modern syntax
+- **Rails 7.2+**: Optional, for ActiveRecord/ActiveModel integration
+
+## Performance Considerations
+
+- **Immutable IR**: Uses `Dry::Struct` for thread-safe, immutable diagram objects
+- **Lazy Evaluation**: Diagrams are built only when `draw` is called
+- **Memory Efficient**: No global state or caching by default
+- **Streaming Support**: Large diagrams can be rendered incrementally
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`rake test`)
+5. Ensure code style compliance (`bundle exec rubocop`)
+6. Submit a pull request
+
+### Adding a New State Machine Library
+
+To support a new state machine library, implement the builder pattern:
+
+```ruby
+module StateMachines::Diagram::Adapters
+  class MyLibraryAdapter
+    def initialize(machine)
+      @machine = machine
+    end
+    
+    def build_states
+      # Extract states from @machine
+    end
+    
+    def build_transitions  
+      # Extract transitions from @machine
+    end
+  end
+end
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

data/lib/state_machines/diagram/builder.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'diagram'
+
+module StateMachines
+  module Diagram
+    class Builder
+      attr_reader :machine, :options, :diagram, :state_metadata, :transition_metadata
+
+      def initialize(machine, options = {})
+        @machine = machine
+        @options = options
+        @diagram = create_diagram
+        @state_metadata = {}
+        @transition_metadata = []
+      end
+
+      def build
+        add_states
+        add_transitions
+        diagram
+      end
+
+      private
+
+      def create_diagram
+        ::Diagrams::StateDiagram.new(
+          title: diagram_title
+        )
+      end
+
+      def diagram_id
+        "#{machine.owner_class.name}_#{machine.name}"
+      end
+
+      def diagram_title
+        "#{machine.owner_class.name} #{machine.name} State Machine"
+      end
+
+      def diagram_description
+        "State machine for #{machine.owner_class.name}##{machine.name}"
+      end
+
+      def add_states
+        machine.states.by_priority.each do |state|
+          add_state_node(state)
+        end
+      end
+
+      def add_state_node(state)
+        state_node = ::Diagrams::Elements::State.new(
+          id: state_id(state),
+          label: state_label(state)
+        )
+
+        diagram.add_state(state_node)
+
+        # Store metadata separately for now
+        @state_metadata ||= {}
+        @state_metadata[state_id(state)] = {
+          type: state_type(state),
+          metadata: build_state_metadata(state)
+        }
+      end
+
+      def state_id(state)
+        state.name ? state.name.to_s : 'nil_state'
+      end
+
+      def state_label(state)
+        if options[:human_names]
+          state.human_name(machine.owner_class)
+        else
+          state_id(state)
+        end
+      end
+
+      def state_type(state)
+        if state.initial?
+          'initial'
+        elsif state.final?
+          'final'
+        else
+          'normal'
+        end
+      end
+
+      def build_state_metadata(state)
+        {
+          initial: state.initial?,
+          final: state.final?,
+          value: state.value,
+          methods: state.methods.grep(/^#{state.name}_/).map(&:to_s)
+        }
+      end
+
+      def add_transitions
+        machine.events.each do |event|
+          add_event_transitions(event)
+        end
+      end
+
+      def add_event_transitions(event)
+        event.branches.each do |branch|
+          add_branch_transitions(branch, event)
+        end
+      end
+
+      def add_branch_transitions(branch, event)
+        valid_states = machine.states.by_priority.map(&:name)
+
+        branch.state_requirements.each do |requirement|
+          from_states = requirement[:from].filter(valid_states)
+          to_states = determine_to_states(requirement, from_states)
+
+          create_transitions(from_states, to_states, event, branch)
+        end
+      end
+
+      def determine_to_states(requirement, from_states)
+        if requirement[:to].values.empty?
+          # Loopback transitions
+          from_states
+        else
+          [requirement[:to].values.first]
+        end
+      end
+
+      def create_transitions(from_states, to_states, event, branch)
+        from_states.each do |from|
+          to_states.each do |to|
+            add_transition(from, to, event, branch)
+          end
+        end
+      end
+
+      def add_transition(from, to, event, branch)
+        from_id = from ? from.to_s : 'nil_state'
+        to_id = to ? to.to_s : 'nil_state'
+
+        guard_info = extract_guard_conditions(branch)
+
+        transition = ::Diagrams::Elements::Transition.new(
+          source_state_id: from_id.empty? ? 'nil_state' : from_id,
+          target_state_id: to_id.empty? ? 'nil_state' : to_id,
+          label: transition_label(event),
+          guard: guard_info[:display],
+          action: extract_action_info(branch, event)
+        )
+
+        diagram.add_transition(transition)
+
+        # Store additional metadata separately for advanced analysis
+        @transition_metadata ||= []
+        transition_data = {
+          transition: transition,
+          from: from.to_s,
+          to: to.to_s,
+          event: event.name.to_s,
+          conditions: guard_info[:conditions],
+          callbacks: build_callbacks(branch, event),
+          metadata: build_transition_metadata(event, branch)
+        }
+        @transition_metadata << transition_data
+      end
+
+      def transition_label(event)
+        if options[:human_names]
+          event.human_name(machine.owner_class)
+        else
+          event.name.to_s
+        end
+      end
+
+      def build_callbacks(branch, event)
+        {
+          before: callback_method_names(branch, event, :before),
+          after: callback_method_names(branch, event, :after),
+          around: callback_method_names(branch, event, :around)
+        }
+      end
+
+      def callback_method_names(branch, event, type)
+        machine.callbacks[type == :around ? :before : type].select do |callback|
+          callback.branch.matches?(branch,
+                                   from: branch.state_requirements.map { |req| req[:from] },
+                                   to: branch.state_requirements.map { |req| req[:to] },
+                                   on: event.name)
+        end.flat_map do |callback|
+          callback.instance_variable_get('@methods')
+        end.compact
+      end
+
+      def build_transition_metadata(_event, branch)
+        {
+          requirements: branch.state_requirements.size
+        }
+      end
+
+      def extract_guard_conditions(branch)
+        guard_conditions = {
+          if: [],
+          unless: []
+        }
+        condition_tokens = []
+
+        if branch.if_condition
+          token = guard_condition_token(branch.if_condition)
+          guard_conditions[:if] << token if token
+          condition_tokens << token if token
+        end
+
+        if branch.unless_condition
+          token = guard_condition_token(branch.unless_condition)
+          guard_conditions[:unless] << token if token
+          condition_tokens << "!#{token}" if token
+        end
+
+        {
+          display: condition_tokens.empty? ? nil : condition_tokens.join(' && '),
+          conditions: guard_conditions
+        }
+      end
+
+      def guard_condition_token(condition)
+        return if condition.nil?
+
+        case condition
+        when Symbol
+          method_name = condition.to_s
+          method_name += '?' unless method_name.end_with?('?')
+          method_name
+        when Proc, Method
+          if condition.respond_to?(:source_location) && condition.source_location
+            file, line = condition.source_location
+            filename = File.basename(file) if file
+            "lambda@#{filename}:#{line}"
+          else
+            'lambda'
+          end
+        else
+          condition.to_s
+        end
+      end
+
+      def extract_action_info(branch, event)
+        actions = []
+
+        # Add explicit action if available (store the object, format during rendering)
+        actions << event.action if event.respond_to?(:action) && event.action
+
+        # Add callback methods as actions
+        before_callbacks = callback_method_names(branch, event, :before)
+        after_callbacks = callback_method_names(branch, event, :after)
+
+        actions.concat(before_callbacks) if before_callbacks.any?
+        actions.concat(after_callbacks) if after_callbacks.any?
+
+        return nil if actions.empty?
+
+        # Format all actions appropriately
+        formatted_actions = actions.map { |action| format_action(action) }
+        formatted_actions.join(', ')
+      end
+
+      def format_action(action)
+        case action
+        when Proc, Method
+          # Try to extract source location for better readability
+          if action.respond_to?(:source_location) && action.source_location
+            file, line = action.source_location
+            filename = File.basename(file) if file
+            "lambda@#{filename}:#{line}"
+          else
+            'lambda'
+          end
+        when Symbol
+          action.to_s
+        else
+          action.to_s
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/diagram/renderer.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require_relative 'builder'
+require 'set'
+
+module StateMachines
+  module Diagram
+    module Renderer
+      module_function
+
+      def draw_machine(machine, io: $stdout, **options)
+        diagram, builder = build_state_diagram(machine, options)
+        output_diagram(diagram, io, options, builder)
+        diagram
+      end
+
+      def build_state_diagram(machine, options)
+        builder = Builder.new(machine, options)
+        diagram = builder.build
+        [diagram, builder]
+      end
+
+      def output_diagram(diagram, io, options, builder = nil)
+        case options[:format]
+        when :json
+          io.puts diagram_hash_with_metadata(diagram, builder).to_json
+        when :yaml
+          require 'yaml'
+          io.puts diagram_hash_with_metadata(diagram, builder).to_yaml
+        else
+          # Default text representation
+          io.puts diagram_to_text(diagram, options, builder)
+        end
+      end
+
+      def draw_state(state, _graph, options = {}, io = $stdout)
+        # Build a diagram containing just this state and its transitions
+        machine = state.machine
+
+        # Find all states involved with this state
+        states_involved = Set.new([state.name])
+
+        machine.events.each do |event|
+          event.branches.each do |branch|
+            branch.state_requirements.each do |requirement|
+              valid_states = machine.states.by_priority.map(&:name)
+              from_states = requirement[:from].filter(valid_states)
+              to_states = requirement[:to].values
+
+              if from_states.include?(state.name)
+                states_involved.merge(to_states)
+              elsif to_states.include?(state.name)
+                states_involved.merge(from_states)
+              end
+            end
+          end
+        end
+
+        # Build diagram with all involved states
+        builder = Builder.new(machine, options)
+        builder.instance_variable_set(:@diagram, builder.send(:create_diagram))
+
+        # Add all involved states first
+        machine.states.select { |s| states_involved.include?(s.name) }.each do |s|
+          builder.send(:add_state_node, s)
+        end
+
+        # Then add transitions
+        machine.events.each do |event|
+          event.branches.each do |branch|
+            branch.state_requirements.each do |requirement|
+              valid_states = machine.states.by_priority.map(&:name)
+              from_states = requirement[:from].filter(valid_states)
+              to_states = requirement[:to].values
+
+              # Only add if involves our state
+              if (from_states & states_involved.to_a).any? && (to_states & states_involved.to_a).any?
+                builder.send(:create_transitions, from_states & states_involved.to_a, to_states & states_involved.to_a,
+                             event, branch)
+              end
+            end
+          end
+        end
+
+        output_diagram(builder.diagram, io, options.merge(state_filter: state.name.to_s), builder)
+      end
+
+      def diagram_hash_with_metadata(diagram, builder)
+        base_hash = diagram.to_h
+        return base_hash unless builder
+
+        transition_metadata_index = build_transition_metadata_index(builder)
+        transition_hashes = extract_transition_hashes(base_hash)
+        return base_hash unless transition_hashes
+
+        diagram.transitions.each_with_index do |transition, index|
+          metadata = transition_metadata_index[transition] ||
+                     find_fallback_transition_metadata(transition_metadata_index, transition) ||
+                     {}
+          transition_hash = transition_hashes[index]
+          next unless transition_hash
+
+          guard_terms = guard_terms_for(transition, metadata)
+          action_list = action_list_for(transition, metadata)
+
+          guard_payload = {}
+          guard_payload[:if] = guard_terms[:if] unless guard_terms[:if].empty?
+          guard_payload[:unless] = guard_terms[:unless] unless guard_terms[:unless].empty?
+          transition_hash[:guard] = guard_payload unless guard_payload.empty?
+
+          transition_hash[:action] = action_list unless action_list.empty?
+        end
+
+        base_hash
+      end
+
+      def extract_transition_hashes(base_hash)
+        data = base_hash[:data] || base_hash['data']
+        return unless data
+
+        data[:transitions] || data['transitions']
+      end
+
+      def draw_event(event, _graph, options = {}, io = $stdout)
+        machine = event.machine
+
+        # Add all states involved in this event
+        states_involved = Set.new
+        event.branches.each do |branch|
+          branch.state_requirements.each do |requirement|
+            valid_states = machine.states.by_priority.map(&:name)
+            from_states = requirement[:from].filter(valid_states)
+            to_states = requirement[:to].values
+
+            states_involved.merge(from_states)
+            states_involved.merge(to_states)
+          end
+        end
+
+        # Build a fresh diagram for this event
+        builder = Builder.new(machine, options)
+        builder.instance_variable_set(:@diagram, builder.send(:create_diagram))
+
+        # Add states to diagram first
+        machine.states.select { |s| states_involved.include?(s.name) }.each do |state|
+          builder.send(:add_state_node, state)
+        end
+
+        # Add transitions for this event
+        builder.send(:add_event_transitions, event)
+
+        output_diagram(builder.diagram, io, options.merge(event_filter: event.name.to_s), builder)
+      end
+
+      def draw_branch(branch, _graph, event, valid_states, io = $stdout)
+        machine = event.machine
+
+        # Add states involved in this branch
+        states_involved = Set.new
+        branch.state_requirements.each do |requirement|
+          from_states = requirement[:from].filter(valid_states)
+          to_states = requirement[:to].values
+
+          states_involved.merge(from_states)
+          states_involved.merge(to_states)
+        end
+
+        # Build fresh diagram
+        builder = Builder.new(machine, {})
+        builder.instance_variable_set(:@diagram, builder.send(:create_diagram))
+
+        # Add states first
+        machine.states.select { |s| states_involved.include?(s.name) }.each do |state|
+          builder.send(:add_state_node, state)
+        end
+
+        # Add transitions
+        builder.send(:add_branch_transitions, branch, event)
+
+        output_diagram(builder.diagram, io, {}, builder)
+      end
+
+      def diagram_to_text(diagram, options = {}, builder = nil)
+        # Defensive copy of options to prevent mutation affecting other tests
+        safe_options = options.dup.freeze
+        output = []
+
+        # Add filter headers if specified
+        if safe_options[:state_filter]
+          output << "State: #{safe_options[:state_filter]}"
+          output << ''
+        elsif safe_options[:event_filter]
+          output << "Event: #{safe_options[:event_filter]}"
+          output << ''
+        end
+
+        output << "=== #{diagram.title} ==="
+        output << ''
+
+        # Use provided builder to access metadata (with nil safety)
+        metadata_source = builder&.state_metadata || {}
+
+        # List states
+        output << 'States:'
+        diagram.states.each do |state|
+          metadata = metadata_source[state.id] || {}
+          type_marker = case metadata[:type]
+                        when 'initial' then ' [*]'
+                        when 'final' then ' (O)'
+                        else ''
+                        end
+          label = state.label || state.id
+          output << "  - #{label}#{type_marker}"
+        end
+
+        output << ''
+        output << 'Transitions:'
+
+        # List transitions with semantic information from the transition objects
+        transition_metadata_index = build_transition_metadata_index(builder)
+
+        diagram.transitions.each do |transition|
+          metadata = transition_metadata_index[transition] ||
+                     find_fallback_transition_metadata(transition_metadata_index, transition) ||
+                     {}
+          condition_str = format_guard_condition(transition, metadata)
+          action_str = format_action_callback(transition, metadata)
+
+          label = transition.label || ''
+          output << "  - #{transition.source_state_id} -> #{transition.target_state_id} [#{label}]#{condition_str}#{action_str}"
+        end
+
+        output.join("\n")
+      end
+
+      def build_transition_metadata_index(builder)
+        return {} unless builder&.respond_to?(:transition_metadata)
+
+        Array(builder.transition_metadata).each_with_object({}) do |metadata, index|
+          transition = metadata[:transition]
+          if transition
+            index[transition] = metadata
+          end
+
+          key = [
+            metadata[:from].to_s,
+            metadata[:to].to_s,
+            metadata[:event].to_s
+          ]
+          (index[:by_key] ||= Hash.new { |h, k| h[k] = [] })[key] << metadata
+        end
+      end
+
+      def find_fallback_transition_metadata(index, transition)
+        by_key = index[:by_key]
+        return unless by_key
+
+        key = [
+          transition.source_state_id.to_s,
+          transition.target_state_id.to_s,
+          transition.label.to_s
+        ]
+
+        metadata_list = by_key[key]
+        metadata_list&.first
+      end
+
+      def format_guard_condition(transition, metadata = {})
+        guard_terms = guard_terms_for(transition, metadata)
+
+        return '' if guard_terms[:if].empty? && guard_terms[:unless].empty?
+
+        parts = []
+        guard_terms[:if].each { |condition| parts << "(if: #{condition})" }
+        guard_terms[:unless].each { |condition| parts << "(unless: #{condition})" }
+        " #{parts.join(' ')}"
+      end
+
+      def guard_terms_for(transition, metadata = {})
+        guard_terms = { if: [], unless: [] }
+
+        if transition.respond_to?(:guard) && transition.guard
+          parse_guard_string(transition.guard.to_s, guard_terms)
+        end
+
+        conditions = metadata.fetch(:conditions, {})
+        Array(conditions[:if]).compact.each do |condition|
+          Array(condition).each { |item| guard_terms[:if] << normalize_condition_name(item) }
+        end
+        Array(conditions[:unless]).compact.each do |condition|
+          Array(condition).each { |item| guard_terms[:unless] << normalize_condition_name(item) }
+        end
+
+        guard_terms[:if].uniq!
+        guard_terms[:unless].uniq!
+
+        guard_terms
+      end
+
+      def parse_guard_string(guard_string, guard_terms)
+        guard_string.split(/\s*&&\s*/).each do |segment|
+          next if segment.nil? || segment.empty?
+
+          if segment.start_with?('!')
+            guard_terms[:unless] << normalize_condition_name(segment[1..])
+          else
+            guard_terms[:if] << normalize_condition_name(segment)
+          end
+        end
+      end
+
+      def normalize_condition_name(condition)
+        return '' if condition.nil?
+
+        condition_name = condition.to_s.strip
+        condition_name = condition_name[1..] if condition_name.start_with?(':')
+        condition_name
+      end
+
+      def format_action_callback(transition, metadata = {})
+        actions = action_list_for(transition, metadata)
+        return '' if actions.empty?
+
+        " (action: #{actions.join(', ')})"
+      end
+
+      def action_list_for(transition, metadata = {})
+        actions = []
+
+        if transition.respond_to?(:action) && transition.action
+          actions << normalize_action_name(transition.action)
+        end
+
+        callbacks = metadata.fetch(:callbacks, {})
+        callbacks.values.each do |callback_list|
+          Array(callback_list).each do |callback|
+            actions << normalize_action_name(callback)
+          end
+        end
+
+        actions.compact!
+        actions.uniq!
+        actions
+      end
+
+      def normalize_action_name(action)
+        return if action.nil?
+
+        action.is_a?(Symbol) ? action.to_s : action.to_s
+      end
+    end
+  end
+end

data/lib/state_machines/diagram/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module Diagram
+    VERSION = '0.1.0'
+  end
+end

data/lib/state_machines-diagram.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'state_machines'
+require 'state_machines/diagram/version'
+require 'state_machines/diagram/builder'
+require 'state_machines/diagram/renderer'
+
+# Set the renderer to use diagram
+StateMachines::Machine.renderer = StateMachines::Diagram::Renderer

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: state_machines-diagram
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: diagram
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
+- !ruby/object:Gem::Dependency
+  name: state_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.100'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.100'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.4
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Diagram module for state machines. Builds diagram representations of
+  state machines that can be rendered in various formats
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/state_machines-diagram.rb
+- lib/state_machines/diagram/builder.rb
+- lib/state_machines/diagram/renderer.rb
+- lib/state_machines/diagram/version.rb
+homepage: https://github.com/state-machines/state_machines-diagram
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Diagram building for state machines
+test_files: []