state_machines-yard 0.1.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ci.yml +12 -4
  3. data/.github/workflows/release.yml +8 -6
  4. data/.release-please-manifest.json +3 -0
  5. data/.rubocop.yml +38 -0
  6. data/CHANGELOG.md +54 -0
  7. data/Gemfile +12 -1
  8. data/README.md +45 -0
  9. data/Rakefile +21 -3
  10. data/lib/state_machines/yard/description.rb +77 -0
  11. data/lib/state_machines/yard/handlers/actions.rb +113 -0
  12. data/lib/state_machines/yard/handlers/base.rb +145 -20
  13. data/lib/state_machines/yard/handlers/callback.rb +56 -0
  14. data/lib/state_machines/yard/handlers/event.rb +16 -12
  15. data/lib/state_machines/yard/handlers/machine.rb +258 -253
  16. data/lib/state_machines/yard/handlers/requirements.rb +92 -0
  17. data/lib/state_machines/yard/handlers/state.rb +16 -12
  18. data/lib/state_machines/yard/handlers/transition.rb +59 -30
  19. data/lib/state_machines/yard/handlers.rb +3 -1
  20. data/lib/state_machines/yard/renderer.rb +62 -0
  21. data/lib/state_machines/yard/templates/default/class/html/setup.rb +14 -7
  22. data/lib/state_machines/yard/templates/default/class/html/state_machines.erb +33 -0
  23. data/lib/state_machines/yard/templates.rb +2 -0
  24. data/lib/state_machines/yard/version.rb +3 -1
  25. data/lib/state_machines/yard.rb +7 -0
  26. data/release-please-config.json +11 -0
  27. data/state_machines-yard.gemspec +16 -8
  28. data/test/description_test.rb +138 -0
  29. data/test/handlers/base_test.rb +43 -18
  30. data/test/handlers/callback_test.rb +168 -0
  31. data/test/handlers/event_test.rb +32 -19
  32. data/test/handlers/guards_test.rb +180 -0
  33. data/test/handlers/machine_test.rb +100 -16
  34. data/test/handlers/review_test.rb +192 -0
  35. data/test/handlers/state_test.rb +20 -13
  36. data/test/handlers/transition_test.rb +154 -19
  37. data/test/integration_test.rb +47 -36
  38. data/test/templates_test.rb +39 -16
  39. data/test/test_helper.rb +24 -10
  40. metadata +103 -20
@@ -0,0 +1,92 @@
1
+ # frozen_string_literal: true
2
+
3
+ module StateMachines
4
+ module Yard
5
+ module Handlers
6
+ # Reads the requirements and guards a transition or callback declares,
7
+ # as the core reads them, for handlers built on Base
8
+ module Requirements
9
+ # Conditions on the object
10
+ CONDITIONS = %i[if unless].freeze
11
+ # Conditions on the states of other machines, each a group of
12
+ # machine => state requirements
13
+ STATE_GUARDS = %i[if_state unless_state if_all_states unless_all_states if_any_state
14
+ unless_any_state].freeze
15
+ # The matchers the DSL names
16
+ MATCHERS = { all: AllMatcher, any: AllMatcher, same: LoopbackMatcher }.freeze
17
+
18
+ private
19
+
20
+ def option_value(name, node)
21
+ if CONDITIONS.include?(name) then condition(node)
22
+ elsif STATE_GUARDS.include?(name) then state_guard(node)
23
+ else requirement(node)
24
+ end
25
+ end
26
+
27
+ # A state or event requirement: a name, an Array of names, or a
28
+ # matcher (all, any, same, all - names)
29
+ def requirement(node)
30
+ case node
31
+ when Prism::CallNode then matcher(node)
32
+ when Prism::ArrayNode then node.elements.map { name_literal(it, nil_allowed: true) }
33
+ else name_literal(node, nil_allowed: true)
34
+ end
35
+ end
36
+
37
+ def matcher(node)
38
+ return MATCHERS.fetch(node.name).instance if bare_call?(node) && MATCHERS.key?(node.name)
39
+ return AllMatcher.instance - names_in(node.arguments.arguments.first, nil_allowed: true) if exclusion?(node)
40
+
41
+ unreadable(node)
42
+ end
43
+
44
+ # all - names, any - names
45
+ def exclusion?(node)
46
+ node.name == :- && all_matcher?(node.receiver) && node.arguments&.arguments&.one?
47
+ end
48
+
49
+ def all_matcher?(node)
50
+ node.is_a?(Prism::CallNode) && bare_call?(node) && MATCHERS[node.name] == AllMatcher
51
+ end
52
+
53
+ def bare_call?(node)
54
+ node.receiver.nil? && node.arguments.nil? && node.block.nil?
55
+ end
56
+
57
+ # An if:/unless: condition as the core reads it: nil and false are no
58
+ # condition, an Array is several, a Symbol names a method, a String is
59
+ # code. Anything else is code (a lambda, a method call) only known
60
+ # when it runs, so its source is documented as the condition
61
+ # (#condition_term).
62
+ def condition(node)
63
+ case node
64
+ when Prism::NilNode then nil
65
+ when Prism::FalseNode then false
66
+ when Prism::ArrayNode then node.elements.map { condition_term(it) }
67
+ else condition_term(node)
68
+ end
69
+ end
70
+
71
+ # A Symbol or String condition as written. Code (a lambda, a method
72
+ # call) is kept as a Symbol of its source: diagrams show it as
73
+ # written, and it is never taken for a String condition, which the
74
+ # core (and diagram introspection) validates and evaluates as code.
75
+ def condition_term(node)
76
+ case node
77
+ when Prism::SymbolNode, Prism::StringNode then literal(node)
78
+ else node.slice.to_sym
79
+ end
80
+ end
81
+
82
+ # A state guard: a Hash of machine => state, kept as one group
83
+ def state_guard(node)
84
+ guard = literal(node)
85
+ unreadable(node) unless guard.is_a?(Hash)
86
+
87
+ guard
88
+ end
89
+ end
90
+ end
91
+ end
92
+ end
@@ -1,28 +1,32 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module StateMachines
2
4
  module Yard
3
5
  module Handlers
4
6
  # Handles and processes #state
5
7
  class State < Base
6
8
  handles method_call(:state)
7
-
9
+
8
10
  # Store the handled method name for testing
9
11
  @handles_method = :state
10
12
 
11
13
  def process
12
- if owner.is_a?(StateMachines::Machine)
13
- handler = self
14
- statement = self.statement
15
- names = extract_node_names(statement.parameters(false))
14
+ return unless owner.is_a?(StateMachines::Machine)
15
+
16
+ handler = self
17
+ block = statement.block
18
+ names = positional_arguments.flat_map { names_in(it, nil_allowed: true) }
19
+ options = literal_options(%i[value human_name], code: %i[value human_name])
16
20
 
17
- names.each do |name|
18
- owner.state(name) do
19
- # Parse the block only if it exists
20
- if statement.block
21
- handler.parse_block(statement.block.last, owner: self)
22
- end
23
- end
21
+ names.each do |name|
22
+ owner.state(name, **options) do
23
+ handler.parse_block(block.last, owner: self) if block
24
24
  end
25
25
  end
26
+ rescue Unreadable, ArgumentError => e
27
+ # One the core refuses (a name of another type than the others) is
28
+ # not documented as something else
29
+ skip('state', e)
26
30
  end
27
31
  end
28
32
  end
@@ -1,49 +1,78 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module StateMachines
2
4
  module Yard
3
5
  module Handlers
4
- # Handles and processes #transition
6
+ # Handles and processes #transition. The documented machine gets the
7
+ # transition with the guards the core runs: if:/unless: conditions
8
+ # (each one of an Array, a String as the code it is, any other code
9
+ # by its source) and state guards with the requirements of each group,
10
+ # and its own before:/around:/after: callbacks, each method read as a
11
+ # transition callback's (Actions): a lambda or other code is a method
12
+ # the transition runs, not a state.
5
13
  class Transition < Base
6
14
  handles method_call(:transition)
7
-
15
+
8
16
  # Store the handled method name for testing
9
17
  @handles_method = :transition
10
18
 
11
- def process
12
- if [StateMachines::Machine, StateMachines::Event, StateMachines::State].include?(owner.class)
13
- options = {}
19
+ include Requirements
20
+ include Actions
14
21
 
15
- # Extract requirements
16
- ast = statement.parameters.first
17
- ast.children.each do |assoc|
18
- # Skip conditionals
19
- next if %w(if :if unless :unless).include?(assoc[0].jump(:ident).source)
22
+ # What a transition is declared on: a machine, an event, or a state's
23
+ # block (state :parked do ... end), whose owner is its StateContext
24
+ OWNERS = [StateMachines::Machine, StateMachines::Event, StateMachines::StateContext].freeze
25
+ # The options that hold the transition's own callbacks
26
+ CALLBACKS = %i[before around after].freeze
27
+ # Literals whose value is never a method name (Symbol, String), Proc
28
+ # or Method, which is all the core takes as a transition's callback
29
+ NOT_METHODS = [
30
+ *KEYWORDS.keys, *NUMBERS, Prism::RationalNode, Prism::ImaginaryNode, Prism::RegularExpressionNode,
31
+ Prism::InterpolatedRegularExpressionNode, Prism::HashNode, Prism::RangeNode, Prism::SourceLineNode,
32
+ Prism::SourceEncodingNode
33
+ ].freeze
20
34
 
21
- options[extract_requirement(assoc[0])] = extract_requirement(assoc[1])
22
- end
35
+ def process
36
+ return unless OWNERS.include?(owner.class)
23
37
 
24
- owner.transition(options)
25
- end
38
+ owner.transition(requirements)
39
+ rescue Unreadable, ArgumentError => e
40
+ # A transition that cannot be read, or that the core refuses, would
41
+ # be documented with other requirements or guards than it has
42
+ skip('transition', e)
26
43
  end
27
44
 
28
45
  private
29
- # Extracts the statement requirement from the given node
30
- def extract_requirement(ast)
31
- case ast.type
32
- when :symbol_literal, :string_literal, :array
33
- extract_node_names(ast, false)
34
- when :binary
35
- AllMatcher.instance - extract_node_names(ast.children.last)
36
- when :var_ref, :vcall
37
- case ast.source
38
- when 'nil'
39
- nil
40
- when 'same'
41
- LoopbackMatcher.instance
42
- else
43
- AllMatcher.instance
44
- end
46
+
47
+ def requirements
48
+ pairs = option_pairs
49
+ unreadable(call_node) if pairs.empty?
50
+
51
+ pairs.to_h do |key, value|
52
+ name = requirement(key)
53
+ [name, CALLBACKS.include?(name) ? own_callbacks(value) : option_value(name, value)]
45
54
  end
46
55
  end
56
+
57
+ # The methods of a before:/around:/after: option: one, or an Array of
58
+ # them, each read through any parentheses around it. A literal that
59
+ # is no method (nil, true, a number, a Regexp, a Hash, a Range, an
60
+ # Array inside the list) is kept as code the core refuses, as it
61
+ # refuses that literal when the class loads.
62
+ def own_callbacks(node)
63
+ node = unwrap(node)
64
+ return node.elements.map { own_callback(it) } if node.is_a?(Prism::ArrayNode)
65
+
66
+ own_callback(node)
67
+ end
68
+
69
+ def own_callback(node)
70
+ node = unwrap(node)
71
+ return Code.new(node.slice) if node.is_a?(Prism::ArrayNode) || nil_literal?(node) ||
72
+ NOT_METHODS.any? { node.is_a?(it) }
73
+
74
+ action(node)
75
+ end
47
76
  end
48
77
  end
49
78
  end
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module StateMachines
2
4
  module Yard
3
5
  # YARD custom handlers for integrating the state_machine DSL with the
@@ -5,4 +7,4 @@ module StateMachines
5
7
  module Handlers
6
8
  end
7
9
  end
8
- end
10
+ end
@@ -0,0 +1,62 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'stringio'
4
+ require 'tmpdir'
5
+
6
+ module StateMachines
7
+ module Yard
8
+ # Draws a documented machine with the renderer STATE_MACHINES_RENDERER
9
+ # names (graphviz, mermaid or none), guards included
10
+ module Renderer
11
+ module_function
12
+
13
+ def selection
14
+ env = ENV.fetch('STATE_MACHINES_RENDERER', nil)
15
+ return env.to_sym if %w[graphviz mermaid none].include?(env)
16
+
17
+ :none
18
+ end
19
+
20
+ # The diagram, or nil. A renderer that fails on a machine leaves its
21
+ # diagram out with a warning; the rest of its documentation stands.
22
+ def render(machine)
23
+ case selection
24
+ when :graphviz then render_graphviz(machine)
25
+ when :mermaid then render_mermaid(machine)
26
+ end
27
+ rescue StandardError, SecurityError => e
28
+ log.warn "state_machines-yard: no #{selection} diagram for #{machine.owner_class} #{machine.name}: " \
29
+ "#{e.class}: #{e.message}"
30
+ nil
31
+ end
32
+
33
+ # The machine as a PNG. Drawn with the GraphViz renderer itself:
34
+ # Machine#draw goes through whichever renderer is global.
35
+ def render_graphviz(machine)
36
+ require 'state_machines/graphviz'
37
+
38
+ Dir.mktmpdir('state_machines-yard') do |dir|
39
+ graph = StateMachines::Graphviz::Renderer.draw_machine(
40
+ machine, name: 'state_machine', path: dir, format: 'png', orientation: 'landscape'
41
+ )
42
+ { image: File.binread(graph.file_path) }
43
+ end
44
+ rescue LoadError
45
+ nil
46
+ end
47
+
48
+ def render_mermaid(machine)
49
+ require 'state_machines-mermaid'
50
+
51
+ io = StringIO.new
52
+ StateMachines::Mermaid::Renderer.draw_machine(machine, io: io, show_conditions: true, show_callbacks: true)
53
+ mermaid = io.string
54
+ return nil if mermaid.strip.empty?
55
+
56
+ { mermaid: mermaid }
57
+ rescue LoadError
58
+ nil
59
+ end
60
+ end
61
+ end
62
+ end
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  # Define where state machine descriptions will be rendered
2
4
  def init
3
5
  super
@@ -11,13 +13,18 @@ end
11
13
 
12
14
  # Gets a list of state machines for this class
13
15
  def state_machines
14
- @state_machines ||= begin
15
- if state_machines = object['state_machines']
16
- state_machines.each do |_name, machine|
17
- serializer.serialize(state_machine_image_path(machine), machine[:image]) if machine[:image]
18
- end
19
- end
20
- end
16
+ @state_machines ||= if (state_machines = object['state_machines'])
17
+ @has_mermaid = state_machines.any? { |_name, machine| machine[:mermaid] }
18
+ state_machines.each_value do |machine|
19
+ serializer.serialize(state_machine_image_path(machine), machine[:image]) if machine[:image]
20
+ end
21
+ state_machines
22
+ end
23
+ end
24
+
25
+ def mermaid?
26
+ state_machines
27
+ @has_mermaid
21
28
  end
22
29
 
23
30
  # Generates the image path for the given machine's visualization
@@ -2,11 +2,44 @@
2
2
 
3
3
  This class contains <%= state_machines.count %> state machine(s).
4
4
 
5
+ <% if mermaid? %>
6
+ <script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js"></script>
7
+ <script>mermaid.initialize({ startOnLoad: true });</script>
8
+ <% end %>
9
+
5
10
  <% state_machines.each do |name, machine| %>
6
11
  <h3><%= h(machine[:name]) %></h3>
7
12
  <p><%= h(machine[:description]) %></p>
8
13
 
14
+ <% if machine[:events]&.any? %>
15
+ <h4>Events</h4>
16
+ <dl class="state_machine_events">
17
+ <% machine[:events].each do |event| %>
18
+ <dt><tt><%= h(event[:name]) %></tt></dt>
19
+ <dd>
20
+ <% if event[:error] %>
21
+ <p>Its transitions cannot be described: <%= h(event[:error]) %></p>
22
+ <% elsif event[:transitions].empty? %>
23
+ <p>No transitions: it never fires.</p>
24
+ <% else %>
25
+ <p>Transitions (from each state the first that matches is taken):</p>
26
+ <ul>
27
+ <% event[:transitions].each do |transition| %>
28
+ <li><tt><%= h(transition) %></tt></li>
29
+ <% end %>
30
+ </ul>
31
+ <% end %>
32
+ <% if event[:failure].any? %>
33
+ <p>On failure: <tt><%= h(event[:failure].join(', ')) %></tt></p>
34
+ <% end %>
35
+ </dd>
36
+ <% end %>
37
+ </dl>
38
+ <% end %>
39
+
9
40
  <% if machine[:image] %>
10
41
  <img alt="State machine diagram for <%= h(machine[:name]) %>" src="<%= url_for(state_machine_image_path(machine)) %>"/>
42
+ <% elsif machine[:mermaid] %>
43
+ <pre class="mermaid"><%= h(machine[:mermaid]) %></pre>
11
44
  <% end %>
12
45
  <% end %>
@@ -1 +1,3 @@
1
+ # frozen_string_literal: true
2
+
1
3
  YARD::Templates::Engine.register_template_path File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
@@ -1,5 +1,7 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module StateMachines
2
4
  module Yard
3
- VERSION = '0.1.0'
5
+ VERSION = '0.4.0'
4
6
  end
5
7
  end
@@ -1,4 +1,7 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'yard'
4
+ require 'state_machines'
2
5
  require_relative 'yard/version'
3
6
  module StateMachines
4
7
  # YARD plugin for automated documentation
@@ -6,8 +9,12 @@ module StateMachines
6
9
  end
7
10
  end
8
11
 
12
+ require_relative 'yard/description'
9
13
  require_relative 'yard/handlers'
10
14
  require_relative 'yard/handlers/base'
15
+ require_relative 'yard/handlers/requirements'
16
+ require_relative 'yard/handlers/actions'
17
+ require_relative 'yard/handlers/callback'
11
18
  require_relative 'yard/handlers/event'
12
19
  require_relative 'yard/handlers/machine'
13
20
  require_relative 'yard/handlers/state'
@@ -0,0 +1,11 @@
1
+ {
2
+ "packages": {
3
+ ".": {
4
+ "release-type": "ruby",
5
+ "package-name": "state_machines-yard",
6
+ "version-file": "lib/state_machines/yard/version.rb",
7
+ "bump-minor-pre-major": true,
8
+ "include-component-in-tag": false
9
+ }
10
+ }
11
+ }
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require_relative 'lib/state_machines/yard/version'
2
4
 
3
5
  Gem::Specification.new do |spec|
@@ -5,21 +7,27 @@ Gem::Specification.new do |spec|
5
7
  spec.version = StateMachines::Yard::VERSION
6
8
  spec.authors = ['Abdelkader Boudih', 'Aaron Pfeifer']
7
9
  spec.email = ['terminale@gmail.com']
8
- spec.summary = %q(State machines YARD plugin)
9
- spec.description = %q(State machines YARD plugin for automated documentation)
10
+ spec.summary = 'State machines YARD plugin'
11
+ spec.description = 'State machines YARD plugin for automated documentation'
10
12
  spec.homepage = 'https://github.com/state-machines/state_machines-yard'
11
13
  spec.license = 'MIT'
12
14
 
13
- spec.required_ruby_version = '>= 3.0'
15
+ spec.required_ruby_version = '>= 4.0'
14
16
 
15
17
  spec.files = `git ls-files -z`.split("\x0")
16
18
  spec.require_paths = ['lib']
17
19
 
18
- spec.add_dependency 'yard'
19
- spec.add_dependency 'state_machines-graphviz'
20
20
  spec.add_dependency 'rdoc'
21
- spec.add_development_dependency 'bundler', '~> 2.0'
22
- spec.add_development_dependency 'rake', '~> 13.0'
23
- spec.add_development_dependency 'minitest', '~> 5.0'
21
+ spec.add_dependency 'state_machines', '>= 0.304.0'
22
+ spec.add_dependency 'state_machines-diagram', '>= 0.4.0'
23
+ spec.add_dependency 'yard'
24
+ spec.add_development_dependency 'bundler', '>= 4.0'
25
+ spec.add_development_dependency 'minitest', '~> 6.0'
24
26
  spec.add_development_dependency 'nokogiri'
27
+ spec.add_development_dependency 'rake', '~> 13.0'
28
+ spec.add_development_dependency 'rubocop', '~> 1.59'
29
+ spec.add_development_dependency 'rubocop-minitest', '~> 0.34'
30
+ spec.add_development_dependency 'rubocop-performance', '~> 1.20'
31
+ spec.add_development_dependency 'rubocop-rake', '~> 0.6'
32
+ spec.metadata['rubygems_mfa_required'] = 'true'
25
33
  end
@@ -0,0 +1,138 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'test_helper'
4
+ require 'state_machines/yard/renderer'
5
+
6
+ # The generated documentation lists each event's transitions, guards and
7
+ # callbacks as text whichever renderer draws the diagram, or none
8
+ class DescriptionTest < Minitest::Test
9
+ include TestHelpers
10
+
11
+ CODE = <<~RUBY
12
+ class Vehicle
13
+ state_machine :status, initial: :parked do
14
+ before_transition from: :parked, do: :check_mirrors
15
+ after_transition to: :idling, do: :log_start, if: :logging?
16
+ after_failure on: :ignite, do: :alert
17
+
18
+ event :ignite do
19
+ transition parked: :idling, if: :engine_ok?, if_any_state: { gate: :open, alarm: :off }
20
+ transition parked: :stalled
21
+ transition parked: :never
22
+ end
23
+
24
+ event :noop
25
+ end
26
+ end
27
+ RUBY
28
+
29
+ IGNITE = [
30
+ 'parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, ' \
31
+ 'after log_start (if logging?)',
32
+ 'parked -> stalled / before check_mirrors'
33
+ ].freeze
34
+
35
+ DIAGRAMS = { 'none' => [], 'graphviz' => ['img'], 'mermaid' => ['pre.mermaid'] }.freeze
36
+
37
+ def setup
38
+ setup_yard
39
+ @previous_renderer = ENV.fetch('STATE_MACHINES_RENDERER', nil)
40
+ end
41
+
42
+ def teardown
43
+ ENV['STATE_MACHINES_RENDERER'] = @previous_renderer
44
+ cleanup_yard
45
+ end
46
+
47
+ def document(renderer)
48
+ ENV['STATE_MACHINES_RENDERER'] = renderer
49
+ YARD::Registry.clear
50
+ parse_code(CODE)
51
+ YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
52
+ Nokogiri::HTML(File.read(File.join(@yard_dir, 'Vehicle.html')))
53
+ end
54
+
55
+ def test_each_renderer_mode_documents_the_events_as_text
56
+ DIAGRAMS.each do |renderer, diagram|
57
+ html = document(renderer)
58
+ events = html.css('dl.state_machine_events')
59
+
60
+ assert_equal(%w[ignite noop], events.css('dt').map { it.text.strip }, renderer)
61
+ assert_equal(IGNITE, events.css('dd').first.css('li').map { it.text.strip }, renderer)
62
+ assert_includes(events.css('dd').first.text, 'On failure: alert', renderer)
63
+ assert_includes(events.css('dd').last.text, 'No transitions: it never fires.', renderer)
64
+ assert_equal(diagram.size, diagram.sum { html.css(it).size }, renderer)
65
+ end
66
+ end
67
+
68
+ def test_callbacks_read_in_the_order_the_core_runs_them
69
+ machine = parse_machines(<<~RUBY)['Lamp'][:state]
70
+ class Lamp
71
+ state_machine initial: :off do
72
+ around_transition on: :switch, do: :hold
73
+ before_transition from: :off, do: :check
74
+ after_transition do: :log
75
+ around_transition on: :switch, do: :time
76
+ event(:switch) { transition off: :on }
77
+ end
78
+ end
79
+ RUBY
80
+
81
+ assert_equal(['off -> on / around hold, before check, around time, after log'],
82
+ StateMachines::Yard::Description.events(machine).first[:transitions])
83
+ end
84
+
85
+ LAMP = <<~RUBY
86
+ class Lamp
87
+ state_machine initial: :off do
88
+ before_transition do: :check
89
+ around_transition do: :hold
90
+ before_transition on: :switch, do: :warm, if: :cold?
91
+ after_transition do: :log
92
+ state :dim
93
+ event :switch do
94
+ transition off: :lit, if: :bulb?, before: :prime, around: :fade, after: [:glow, -> { hum }]
95
+ transition off: :dim, after: :flicker
96
+ transition lit: same, around: :pulse
97
+ end
98
+ state :lit do
99
+ transition to: :off, on: :cut, around: :fade, before: :cool
100
+ end
101
+ end
102
+ end
103
+ RUBY
104
+
105
+ def test_a_transitions_own_callbacks_read_where_the_core_runs_them
106
+ switch, cut = StateMachines::Yard::Description.events(parse_machines(LAMP)['Lamp'][:state])
107
+
108
+ assert_equal(['off -> lit [if bulb?] / before check, around hold, before warm (if cold?), before prime, ' \
109
+ 'around fade, after glow, after lambda@(stdin):9, after log',
110
+ 'off -> dim / before check, around hold, before warm (if cold?), after flicker, after log',
111
+ 'lit -> lit / before check, around hold, before warm (if cold?), around pulse, after log'],
112
+ switch[:transitions])
113
+ # a state context transition, its around: written before its before:
114
+ assert_equal(['lit -> off / before check, around hold, around fade, before cool, after log'], cut[:transitions])
115
+ end
116
+
117
+ def test_the_mermaid_diagram_shows_a_transitions_own_callbacks
118
+ mermaid = StateMachines::Yard::Renderer.render_mermaid(parse_machines(LAMP)['Lamp'][:state])[:mermaid]
119
+
120
+ assert_includes(mermaid, 'lit --> off : cut / before check, around hold, around fade, before cool, after log')
121
+ end
122
+
123
+ def test_each_renderer_mode_documents_the_event_methods
124
+ DIAGRAMS.each_key do |renderer|
125
+ document(renderer)
126
+ ignite = YARD::Registry.at('Vehicle#ignite').docstring
127
+ ignite_bang = YARD::Registry.at('Vehicle#ignite!').docstring
128
+
129
+ [ignite, ignite_bang].each do |docstring|
130
+ IGNITE.each { assert_includes(docstring, "* #{it}", renderer) }
131
+
132
+ assert_includes(docstring, 'On failure: alert', renderer)
133
+ end
134
+ assert_includes(YARD::Registry.at('Vehicle#noop').docstring, 'No transitions: it never fires.', renderer)
135
+ assert_equal(['@param', '@return'], YARD::Registry.at('Vehicle#ignite').tags.map { "@#{it.tag_name}" })
136
+ end
137
+ end
138
+ end