state_machines-mermaid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 387fad10965ac7756257b30ac3a36b20770c2702631796c2727c3b0cb4eeea69
+  data.tar.gz: 26d45114695fab1ed434862f36520c4006f895d5db17903519995366e6045090
+SHA512:
+  metadata.gz: c92e86302c88b96d81dded14771366d26225970a915e9077d0b71311fdd02cdc4e4b2a068311afbc1fca8e951e018d04fb4ed39f5e311c92035316e1acf97bb2
+  data.tar.gz: bb1ce73610a01f2892c2dc1b7737eff292b851e2a988e20a0bf13628a5c28e24a492cc9c6065714adb7278da03b7574354264f96c8a8619d714b143e5df032b3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 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,177 @@
+# StateMachines::Mermaid
+
+[![CI](https://github.com/state-machines/state_machines-mermaid/actions/workflows/ruby.yml/badge.svg)](https://github.com/state-machines/state_machines-mermaid/actions/workflows/ruby.yml)
+[![Gem Version](https://img.shields.io/gem/v/state_machines-mermaid.svg)](https://rubygems.org/gems/state_machines-mermaid)
+[![Supported Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.3.0-orange.svg)](https://www.ruby-lang.org)
+
+Mermaid diagram renderer for [state_machines](https://github.com/state-machines/state_machines). Generate Mermaid state diagrams from your state machines.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'state_machines-mermaid'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install state_machines-mermaid
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'state_machines-mermaid'
+
+class Order
+  state_machine :status, initial: :pending do
+    event :process do
+      transition pending: :processing
+    end
+    
+    event :ship do
+      transition processing: :shipped
+    end
+    
+    event :deliver do
+      transition shipped: :delivered
+    end
+    
+    event :cancel do
+      transition [:pending, :processing] => :cancelled
+    end
+    
+    state :delivered, :cancelled do
+      def final?
+        true
+      end
+    end
+  end
+end
+
+# Generate Mermaid diagram
+puts Order.state_machine(:status).draw
+```
+
+This generates:
+
+```mermaid
+stateDiagram-v2
+  pending : pending
+  processing : processing
+  shipped : shipped
+  delivered : delivered
+  cancelled : cancelled
+  pending --> processing : process
+  processing --> shipped : ship
+  shipped --> delivered : deliver
+  pending --> cancelled : cancel
+  processing --> cancelled : cancel
+```
+
+### With Conditions
+
+```ruby
+class Character
+  state_machine :status, initial: :idle do
+    event :attack do
+      transition idle: :combat, if: :has_weapon?
+    end
+    
+    event :rest do
+      transition combat: :idle, unless: :in_danger?
+    end
+  end
+end
+
+# Generates transitions with conditions
+puts Character.state_machine(:status).draw
+```
+
+Output includes conditions:
+
+```mermaid
+stateDiagram-v2
+  idle : idle
+  combat : combat
+  idle --> combat : attack [if has_weapon?]
+  combat --> idle : rest [unless in_danger?]
+```
+
+### Show Callbacks
+
+```ruby
+# Include callback information in the diagram
+Character.state_machine(:status).draw(show_callbacks: true)
+```
+
+### Output to File
+
+```ruby
+File.open('state_diagram.mmd', 'w') do |file|
+  Order.state_machine(:status).draw(io: file)
+end
+```
+
+### Integration with Mermaid Tools
+
+The generated output is compatible with:
+
+- [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)
+- GitHub Markdown (renders Mermaid diagrams natively)
+- Various documentation tools (GitLab, Notion, etc.)
+- Mermaid CLI for generating PNG/SVG files
+
+### Example: Complex State Machine
+
+```ruby
+class Dragon
+  state_machine :mood, initial: :sleeping do
+    state :sleeping, :hunting, :hoarding, :rampaging
+    
+    event :wake_up do
+      transition sleeping: :hunting, if: :hungry?
+      transition sleeping: :hoarding, if: :treasure_nearby?
+    end
+    
+    event :find_treasure do
+      transition hunting: :hoarding
+      transition hoarding: same  # Keep hoarding
+    end
+    
+    event :enrage do
+      transition any - :rampaging => :rampaging
+    end
+  end
+end
+
+puts Dragon.state_machine(:mood).draw
+```
+
+## Features
+
+- Generates valid Mermaid state diagram syntax
+- Supports initial and final states
+- Shows transition conditions (if/unless)
+- Handles self-transitions (loopbacks)
+- Sanitizes state names for Mermaid compatibility
+- Optional callback visualization
+- Compatible with all state_machines features
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/state-machines/state_machines-mermaid.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/state_machines/mermaid/renderer.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'state_machines-diagram'
+require 'mermaid'
+
+module StateMachines
+  module Mermaid
+    module Renderer
+      extend self
+      
+      # Cache recent metadata so we can enhance the Mermaid output with
+      # condition/callback details when the caller requests it.
+      def reset_metadata!
+        @last_state_metadata = nil
+        @last_transition_metadata = nil
+        @last_transition_metadata_map = nil
+      end
+
+      # The new simplified approach - leverages the diagram gem's semantic structure
+      def draw_machine(machine, io: $stdout, **options)
+        reset_metadata!
+        diagram = build_state_diagram(machine, options)
+        output_diagram(diagram, io, options)
+        diagram
+      end
+      
+      def build_state_diagram(machine, options)
+        builder = StateMachines::Diagram::Builder.new(machine, options)
+        diagram = builder.build
+
+        @last_state_metadata = builder.state_metadata
+        @last_transition_metadata = builder.transition_metadata
+        @last_transition_metadata_map = nil
+
+        diagram
+      end
+      
+      def draw_state(state, graph, options = {}, io = $stdout)
+        reset_metadata!
+        diagram = build_state_diagram(state.machine, options)
+        mermaid_syntax = render_mermaid(diagram, options)
+        # Filter to show only relevant transitions for this state
+        filtered_lines = filter_mermaid_for_state(mermaid_syntax, state.name.to_s)
+        io.puts filtered_lines
+        diagram
+      end
+      
+      def draw_event(event, graph, options = {}, io = $stdout)
+        reset_metadata!
+        diagram = build_state_diagram(event.machine, options)
+        mermaid_syntax = render_mermaid(diagram, options)
+        # Filter to show only transitions triggered by this event
+        filtered_lines = filter_mermaid_for_event(mermaid_syntax, event.name.to_s)
+        io.puts filtered_lines
+        diagram
+      end
+      
+      # The core method - just delegates to the mermaid gem's to_mermaid method
+      def output_diagram(diagram, io, options)
+        mermaid_syntax = render_mermaid(diagram, options)
+        io.puts mermaid_syntax
+        mermaid_syntax
+      end
+
+      private
+
+      def transition_metadata_map
+        @last_transition_metadata_map ||= Array(@last_transition_metadata).each_with_object({}) do |data, memo|
+          transition = data[:transition]
+          memo[transition] = data if transition
+        end
+      end
+
+      def render_mermaid(diagram, options)
+        return diagram.to_mermaid unless @last_transition_metadata
+
+        lines = ["stateDiagram-v2"]
+
+        diagram.states.each do |state|
+          fragment = state.respond_to?(:to_mermaid_fragment) ? state.to_mermaid_fragment : state.id
+          lines << "  #{fragment}" if fragment && !fragment.empty?
+        end
+
+        diagram.transitions.each do |transition|
+          metadata = transition_metadata_map[transition]
+          lines << "  #{render_transition_line(transition, metadata, options)}"
+        end
+
+        lines.join("\n")
+      end
+
+      def render_transition_line(transition, metadata, options)
+        from_node = format_node_id(transition.source_state_id)
+        to_node = format_node_id(transition.target_state_id)
+
+        label_text = ''
+
+        base_label = transition.label
+        label_text = base_label if base_label && !base_label.empty?
+
+        guard_fragment = ''
+        if options[:show_conditions] && metadata
+          condition_tokens = build_condition_tokens(metadata[:conditions])
+          guard_fragment = "[#{condition_tokens.join(' && ')}]" if condition_tokens.any?
+        end
+
+        action_fragment = ''
+        if options[:show_callbacks] && metadata
+          callback_tokens = build_callback_tokens(metadata[:callbacks])
+          action_fragment = "/ #{callback_tokens.join(', ')}" if callback_tokens.any?
+        end
+
+        parts = []
+        parts << label_text unless label_text.empty?
+        parts << guard_fragment unless guard_fragment.empty?
+        parts << action_fragment unless action_fragment.empty?
+        label = parts.join(' ').strip
+
+        if label.empty?
+          "#{from_node} --> #{to_node}"
+        else
+          "#{from_node} --> #{to_node} : #{label}"
+        end
+      end
+
+      def build_condition_tokens(conditions)
+        return [] unless conditions.is_a?(Hash)
+
+        tokens = []
+        Array(conditions[:if]).each do |token|
+          next if token.nil? || token.to_s.empty?
+          tokens << "if #{token}"
+        end
+        Array(conditions[:unless]).each do |token|
+          next if token.nil? || token.to_s.empty?
+          tokens << "unless #{token}"
+        end
+        tokens
+      end
+
+      def build_callback_tokens(callbacks)
+        return [] unless callbacks.is_a?(Hash)
+
+        tokens = []
+        callbacks.each do |type, names|
+          Array(names).each do |name|
+            next if name.nil? || name.to_s.empty?
+            tokens << "#{type} #{format_callback_reference(name)}"
+          end
+        end
+        tokens
+      end
+
+      def format_callback_reference(callback)
+        case callback
+        when Symbol, String
+          callback.to_s
+        when Proc, Method
+          if callback.respond_to?(:source_location) && callback.source_location
+            file, line = callback.source_location
+            filename = File.basename(file) if file
+            "lambda@#{filename}:#{line}"
+          else
+            'lambda'
+          end
+        else
+          callback.to_s
+        end
+      end
+
+      def format_node_id(node_id)
+        node_id == '*' ? '[*]' : node_id
+      end
+
+      def filter_mermaid_for_state(mermaid_syntax, state_name)
+        lines = mermaid_syntax.split("\n")
+        relevant_lines = lines.select do |line|
+          line.include?(state_name) || line.start_with?("stateDiagram")
+        end
+        relevant_lines.join("\n")
+      end
+      
+      def filter_mermaid_for_event(mermaid_syntax, event_name)
+        lines = mermaid_syntax.split("\n")
+        relevant_lines = lines.select do |line|
+          line.include?(event_name) || line.start_with?("stateDiagram")
+        end
+        relevant_lines.join("\n")
+      end
+    end
+  end
+end

data/lib/state_machines/mermaid/version.rb

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

data/lib/state_machines-mermaid.rb

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

data/test/mermaid_renderer_test.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'stringio'
+
+class MermaidRendererTest < Minitest::Test
+  def setup
+    @dragon = Dragon.new
+    @mage = Mage.new
+    @troll = Troll.new
+    @regiment = Regiment.new
+    @battle = Battle.new
+  end
+
+  def test_basic_mermaid_output
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:mood), io: io)
+    
+    output = io.string
+    assert_includes output, "stateDiagram-v2"
+    assert_includes output, "sleeping : sleeping"
+    assert_includes output, "sleeping --> hunting : wake_up"
+  end
+
+  def test_state_labels
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@mage.class.state_machine(:concentration), io: io)
+    
+    output = io.string
+    assert_includes output, "focused : focused"
+    assert_includes output, "deep_meditation : deep_meditation"
+  end
+
+  def test_complex_transitions_with_conditions
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(
+      Character.state_machine(:status), 
+      io: io,
+      show_conditions: true
+    )
+    
+    output = io.string
+    assert_includes output, "idle --> combat : engage"
+    assert_includes output, "[if can_fight?]"
+    assert_includes output, "[unless spell_locked?]"
+  end
+
+  def test_final_states
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(Character.state_machine(:status), io: io)
+    
+    output = io.string
+    # The mermaid gem doesn't add [*] for final states by default
+    assert_includes output, "dead : dead"
+  end
+
+  def test_multiple_from_states
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@troll.class.state_machine(:regeneration), io: io)
+    
+    output = io.string
+    assert_includes output, "normal --> suppressed : take_fire_damage"
+    assert_includes output, "accelerated --> suppressed : take_fire_damage"
+    assert_includes output, "berserk --> suppressed : take_fire_damage"
+  end
+
+  def test_loopback_transitions
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:mood), io: io)
+    
+    output = io.string
+    assert_includes output, "hoarding --> hoarding : find_treasure"
+  end
+
+  def test_callbacks_option
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(
+      Character.state_machine(:status), 
+      io: io, 
+      show_callbacks: true
+    )
+    
+    output = io.string
+    assert_includes output, " / before"
+    assert_includes output, "cast_spell"
+  end
+
+  def test_nested_states_in_spell_school
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@mage.class.state_machine(:spell_school), io: io)
+    
+    output = io.string
+    assert_includes output, "apprentice"
+    assert_includes output, "ember"
+    assert_includes output, "inferno"
+    assert_includes output, "archmage"
+  end
+
+  def test_battle_phase_machine
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@battle.class.state_machine(:phase), io: io)
+    
+    output = io.string
+    assert_includes output, "preparation"
+    assert_includes output, "deployment"
+    assert_includes output, "skirmish"
+    assert_includes output, "main_battle"
+    assert_includes output, "climax"
+    assert_includes output, "aftermath"
+  end
+
+  def test_regiment_formation_states
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@regiment.class.state_machine(:formation), io: io)
+    
+    output = io.string
+    assert_includes output, "column"
+    assert_includes output, "square"
+    assert_includes output, "wedge"
+    assert_includes output, "scattered"
+    assert_includes output, "column --> line : deploy"
+  end
+
+  def test_sanitizes_special_characters_in_ids
+    # Create a class with special characters in state names
+    klass = Class.new do
+      state_machine :status do
+        state :"waiting-for-input"
+        state :"processing/data"
+        state :"error!"
+        
+        event :process do
+          transition :"waiting-for-input" => :"processing/data"
+        end
+        
+        event :fail do
+          transition :"processing/data" => :"error!"
+        end
+      end
+    end
+    
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(klass.state_machine(:status), io: io)
+    
+    output = io.string
+    # The mermaid gem doesn't sanitize IDs by default
+    assert_includes output, "waiting-for-input"
+    assert_includes output, "processing/data"
+    assert_includes output, "error!"
+    assert_includes output, "waiting-for-input --> processing/data"
+  end
+
+  def test_dragon_age_progression
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:age_category), io: io)
+    
+    output = io.string
+    assert_includes output, "wyrmling --> young : age"
+    assert_includes output, "young --> adult : age"
+    assert_includes output, "adult --> ancient : age"
+    assert_includes output, "ancient --> great_wyrm : age"
+  end
+
+  def test_parallel_state_machines_dragon
+    mood_io = StringIO.new
+    flight_io = StringIO.new
+    age_io = StringIO.new
+    
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:mood), io: mood_io)
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:flight), io: flight_io)
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:age_category), io: age_io)
+    
+    # Each should generate valid mermaid syntax
+    [mood_io, flight_io, age_io].each do |io|
+      assert io.string.start_with?("stateDiagram-v2")
+      assert io.string.include?("-->")
+    end
+  end
+
+  def test_complex_conditions_formatting
+    io = StringIO.new
+    StateMachines::Mermaid::Renderer.draw_machine(@dragon.class.state_machine(:mood), io: io)
+    
+    output = io.string
+    # Check that complex conditions are properly formatted
+    lines = output.split("\n")
+    transition_lines = lines.select { |l| l.include?("-->") && l.include?("[") }
+    
+    # Check that at least some transitions exist
+    assert output.include?("-->"), "Should have transitions"
+  end
+
+  def test_all_character_types_render_properly
+    [@dragon, @mage, @troll, @regiment].each do |character|
+      character.class.state_machines.each do |name, machine|
+        io = StringIO.new
+        # Just call the method, any exception will fail the test
+        StateMachines::Mermaid::Renderer.draw_machine(machine, io: io)
+        
+        output = io.string
+        assert output.start_with?("stateDiagram-v2"), 
+          "#{character.class.name}##{name} should generate valid mermaid"
+        assert output.include?("-->"), 
+          "#{character.class.name}##{name} should have transitions"
+      end
+    end
+  end
+end