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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f44c4181dbd4a72f83b7a3c39b41c12a70decb9cc9479f942322eead08cab927
4
- data.tar.gz: 6c992389d5a3ab8cda9e879871ceccc9fd071283278b292e69e8bd54b0e80f00
3
+ metadata.gz: 90c9f031f3007e509582714835aa6c1b3607b50d44871ba5b73ccb85aad301b7
4
+ data.tar.gz: 2b7a97545ca16cac0e2f47b425024aa0d1a318acf091c600fd59897d9d75fa14
5
5
  SHA512:
6
- metadata.gz: 31dbd1176ec57de4d9fb5221008d7bc651f7508a47fe407b401f536ac738f7788b2b5555bfbf4c1d0913838bb5f3ca5b7762ef022b4ed40b3955bc9c567692b4
7
- data.tar.gz: 1a298b682b5ff8a3c1074e49f54bdf41b8b06e5f2122825fcc4465d052e1efed9455228b95162ca53dad431cdc13ecad8c3691056bd3257c25982802c14d2193
6
+ metadata.gz: 65193fd5562621438bf8235416eef4e2f23abfee6bb39d1f5c44132960dac60d2b4e0ba9285cb53042d8108423967fcf07106c33feafdadebf3d088a7847d736
7
+ data.tar.gz: bc1fe94bd090ff2f1425c79002a38bd64da4af0301cc607e8f76a6f6839436b68ae710c68052d6e3e45bed58742dbf23fe22f030514da606011ada52defe5075
@@ -10,15 +10,23 @@ jobs:
10
10
  build:
11
11
 
12
12
  runs-on: ubuntu-latest
13
+ strategy:
14
+ fail-fast: false
15
+ matrix:
16
+ ruby-version: ['4.0']
17
+ renderer: ['none', 'graphviz', 'mermaid']
13
18
 
14
19
  steps:
15
- - uses: actions/checkout@v4
20
+ - uses: actions/checkout@v7
16
21
  - name: Set up Ruby
17
22
  uses: ruby/setup-ruby@v1
18
23
  with:
19
- ruby-version: '3.0'
24
+ ruby-version: ${{ matrix.ruby-version }}
20
25
  bundler-cache: true
21
- - name: Install graphviz
26
+ # Every job draws a GraphViz diagram in the renderer tests
27
+ - name: Install graphviz
22
28
  run: sudo apt-get update && sudo apt-get install -y graphviz
23
29
  - name: Run tests
24
- run: bundle exec rake
30
+ env:
31
+ STATE_MACHINES_RENDERER: ${{ matrix.renderer }}
32
+ run: bundle exec rake
@@ -1,16 +1,18 @@
1
- name: Release Please
1
+ name: release-please
2
2
 
3
3
  on:
4
4
  push:
5
5
  branches:
6
6
  - master
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: write
11
+ pull-requests: write
12
+ issues: write
7
13
 
8
14
  jobs:
9
15
  release-please:
10
16
  runs-on: ubuntu-latest
11
17
  steps:
12
- - uses: actions/checkout@v4
13
- - uses: googleapis/release-please-action@v3
14
- with:
15
- release-type: ruby
16
- package-name: state_machines-yard
18
+ - uses: googleapis/release-please-action@v5
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.4.0"
3
+ }
data/.rubocop.yml ADDED
@@ -0,0 +1,38 @@
1
+ plugins:
2
+ - rubocop-minitest
3
+ - rubocop-rake
4
+ - rubocop-performance
5
+ AllCops:
6
+ TargetRubyVersion: 4.0
7
+ NewCops: enable
8
+ Exclude:
9
+ - 'pkg/**/*'
10
+ - 'tmp/**/*'
11
+ - 'vendor/**/*'
12
+
13
+ Style/Documentation:
14
+ Enabled: false
15
+
16
+ Metrics/MethodLength:
17
+ Max: 20
18
+ Exclude:
19
+ - 'test/**/*' # Tests hold their fixture source
20
+
21
+ Metrics/AbcSize:
22
+ Max: 40
23
+
24
+ Minitest/MultipleAssertions:
25
+ Enabled: false
26
+
27
+ Gemspec/DevelopmentDependencies:
28
+ Enabled: false
29
+
30
+ Metrics/ClassLength:
31
+ Exclude:
32
+ - 'test/**/*' # Allow longer test classes
33
+ - 'lib/state_machines/yard/handlers/machine.rb' # The generated methods' documentation
34
+
35
+ # Test classes are long blocks by nature.
36
+ Metrics/BlockLength:
37
+ Exclude:
38
+ - 'test/**/*'
data/CHANGELOG.md CHANGED
@@ -1,5 +1,59 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.0](https://github.com/state-machines/state_machines-yard/compare/v0.3.0...v0.4.0) (2026-11-17)
4
+
5
+
6
+ ### Features
7
+
8
+ * list a transition's own callbacks where the core runs them ([f63e27b](https://github.com/state-machines/state_machines-yard/commit/f63e27b6fcae11bac31356971addb65453cc147a))
9
+ * require state_machines-diagram 0.4.0 for transition callbacks ([0d72dc4](https://github.com/state-machines/state_machines-yard/commit/0d72dc40ea5a7d46a02bc428e4360ca1f66877f0))
10
+
11
+
12
+ ### Bug Fixes
13
+
14
+ * document no callback method for do: nil or &nil ([b1d4e32](https://github.com/state-machines/state_machines-yard/commit/b1d4e3228145172268eaeb0083e53ec9909053f0))
15
+ * document transitions declared in a state's block ([71951c6](https://github.com/state-machines/state_machines-yard/commit/71951c67654d6720818e05b00df55a78812fd582))
16
+ * leave out a callback whose block argument has no to_proc ([e1b5d12](https://github.com/state-machines/state_machines-yard/commit/e1b5d12c05c78546ab8f0892db0cb700f71128f0))
17
+ * read a call whole when YARD's parser cuts its last argument ([a8ee0ed](https://github.com/state-machines/state_machines-yard/commit/a8ee0edd69878e6406bdecb02da322b023f243ae))
18
+ * read a callback method through parentheses and refuse every non-method ([0d5f024](https://github.com/state-machines/state_machines-yard/commit/0d5f024f11c0db7cd7db24264b9453d5448213a6))
19
+ * read a transition's before:/around:/after: as the methods they are ([482a37f](https://github.com/state-machines/state_machines-yard/commit/482a37fe78677afbede4189c3736211fb2a1f7ab))
20
+
21
+ ## [0.3.0](https://github.com/state-machines/state_machines-yard/compare/v0.2.0...v0.3.0) (2026-11-17)
22
+
23
+
24
+ ### Features
25
+
26
+ * document each event's transitions, guards and callbacks as text ([d79a9a1](https://github.com/state-machines/state_machines-yard/commit/d79a9a117b380183301659221bcc8664c451c021))
27
+ * document the guards and options the DSL declares ([75c2603](https://github.com/state-machines/state_machines-yard/commit/75c26039e59d00b61cfa12bf7524acdabfab3481))
28
+ * document transition callbacks ([3bb2645](https://github.com/state-machines/state_machines-yard/commit/3bb264539d585a49fadeaab663ba18b62bb06a04))
29
+
30
+
31
+ ### Bug Fixes
32
+
33
+ * a code condition is never evaluated as a String condition ([47d25d6](https://github.com/state-machines/state_machines-yard/commit/47d25d688bdf80a6a61409a2d7eb1af84aa2d828))
34
+ * a documented machine is owned by a class named as the documented one ([82e8e5c](https://github.com/state-machines/state_machines-yard/commit/82e8e5ca9a6695adaf33a0dbb34e1e49b0ec881a))
35
+ * a reopened machine never publishes its earlier diagram ([1edc9b8](https://github.com/state-machines/state_machines-yard/commit/1edc9b87980d1202c72671deeb7c4494761bc557))
36
+ * code-valued state options and numeric names are documented as written ([d7a2c4b](https://github.com/state-machines/state_machines-yard/commit/d7a2c4b976b3cf5fd46258e9602660402e1a25f2))
37
+ * key documented machines by their fully qualified namespace ([5bf46b0](https://github.com/state-machines/state_machines-yard/commit/5bf46b095a91e9293cbdec8ae269bf8e16096aba))
38
+ * read callbacks through Callback#callables; require state_machines 0.303.0 ([8bd5e0d](https://github.com/state-machines/state_machines-yard/commit/8bd5e0db24a92e056fd53bf915c2d41dbb12f158))
39
+ * release-please bumps the gem version ([1115494](https://github.com/state-machines/state_machines-yard/commit/1115494011bf37913c7d5ff123a70b6e4f657dc6))
40
+ * reopened and inherited machines are documented as the core builds them ([84ac0ee](https://github.com/state-machines/state_machines-yard/commit/84ac0ee8d60e21cea536121af353a0b84a05ab2a))
41
+ * run RuboCop in the default task ([f5827cf](https://github.com/state-machines/state_machines-yard/commit/f5827cfb471d8ff14848fc562c3b94780226bf06))
42
+ * the Events text lists callbacks in the order the core runs them ([e568c5f](https://github.com/state-machines/state_machines-yard/commit/e568c5f9a0c665eba8b86d72fdaff423bc0a0496))
43
+
44
+ ## [0.2.0](https://github.com/state-machines/state_machines-yard/compare/v0.1.0...v0.2.0) (2026-10-18)
45
+
46
+
47
+ ### Features
48
+
49
+ * configurable renderer for yard diagrams ([3268679](https://github.com/state-machines/state_machines-yard/commit/326867993c1982bfc9fe2ccf406d6f3669f4608e))
50
+ * run tests with padded_cell on CRuby ([#13](https://github.com/state-machines/state_machines-yard/issues/13)) ([1b9201c](https://github.com/state-machines/state_machines-yard/commit/1b9201c114a1f8d28988430069527f1f7d1236dd))
51
+
52
+
53
+ ### Bug Fixes
54
+
55
+ * require state_machines-mermaid ([eea3f26](https://github.com/state-machines/state_machines-yard/commit/eea3f26d8a53689ad184cfc4fe201fa6406c9c05))
56
+
3
57
  ## 0.1.0 (2025-03-18)
4
58
 
5
59
 
data/Gemfile CHANGED
@@ -1,4 +1,15 @@
1
+ # frozen_string_literal: true
2
+
1
3
  source 'https://rubygems.org'
2
4
  gemspec
3
5
 
4
- gem 'ruby-graphviz', github: 'seuros/ruby-graphviz'
6
+ platforms :mri do
7
+ gem 'padded_cell', '~> 0.2'
8
+ end
9
+
10
+ gem 'ruby-graphviz'
11
+
12
+ group :test do
13
+ gem 'state_machines-graphviz', '>= 0.2.0'
14
+ gem 'state_machines-mermaid', '>= 0.3.0'
15
+ end
data/README.md CHANGED
@@ -16,6 +16,51 @@ Or install it yourself as:
16
16
 
17
17
  $ gem install state_machines-yard
18
18
 
19
+ ## Events
20
+
21
+ Whatever the renderer, each class's documentation lists its machines' events, and
22
+ each event's method (`ignite`, `ignite!`) describes the transitions it performs: from
23
+ each state the first branch that matches, its guards and the callbacks that run on it in
24
+ the order the core runs them (an around where it enters; a transition's own
25
+ `before:`/`around:`/`after:` closest to the state change, after the machine's befores and
26
+ before its afters), and the `after_failure` callbacks:
27
+
28
+ * parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, after log_start (if logging?)
29
+ * parked -> stalled / before check_mirrors
30
+
31
+ On failure: alert
32
+
33
+ The text is read through [state_machines-diagram](https://github.com/state-machines/state_machines-diagram),
34
+ so it labels guards and callbacks exactly as the diagrams do.
35
+
36
+ ## Diagrams
37
+
38
+ Diagrams are an optional extra. Set `STATE_MACHINES_RENDERER` to draw each documented machine:
39
+
40
+ * `graphviz` embeds a PNG drawn by [state_machines-graphviz](https://github.com/state-machines/state_machines-graphviz)
41
+ (needs the `dot` binary)
42
+ * `mermaid` embeds a Mermaid diagram drawn by [state_machines-mermaid](https://github.com/state-machines/state_machines-mermaid)
43
+ * `none` (the default) draws nothing
44
+
45
+ The plugin reads the state machine DSL without running it. Transitions carry the
46
+ guards the core runs: `if:`/`unless:` conditions (each one of an Array, a String
47
+ as the code it is, a lambda or other code by its source) and state guards
48
+ (`if_state`, `if_all_states`, `if_any_state`, `unless_state`, `unless_all_states`,
49
+ `unless_any_state`), each group with its requirements. A requirement or state guard
50
+ only known when the code runs (a constant, a method call) cannot be documented
51
+ faithfully, so that transition is left out with a warning; an initial state
52
+ written as code documents no state as initial.
53
+
54
+ Transition callbacks (`before_transition`, `after_transition`, `around_transition`,
55
+ `after_failure`) are read the same way: their methods (positional, `do:`, a block),
56
+ the transitions they run on (`from`/`to`/`on`, their `except_` forms, `a => b`
57
+ pairs) and their own conditions. A transition's own callbacks
58
+ (`transition parked: :idling, before: :prime, after: -> { log }`) are read as methods the
59
+ same way, in an event or a state's block. Diagrams show them as the renderers label them:
60
+ a Symbol by name, String code as written, a block or lambda as `lambda@file:line`,
61
+ a conditional callback with its conditions. A diagram a renderer fails to draw is
62
+ left out with a warning; the rest of the class's documentation stands.
63
+
19
64
  ## Testing
20
65
 
21
66
  A comprehensive test suite is included for the gem. To run all tests:
data/Rakefile CHANGED
@@ -1,12 +1,30 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'bundler/gem_tasks'
2
4
  require 'rake/testtask'
5
+ require 'shellwords'
3
6
 
4
- Rake::TestTask.new do |t|
7
+ Rake::TestTask.new(:minitest) do |t|
5
8
  t.libs << 'test'
6
9
  t.pattern = 'test/**/*_test.rb'
7
10
  t.verbose = true
8
11
  t.warning = false
9
12
  end
10
13
 
11
- desc 'Run tests'
12
- task default: :test
14
+ # Both branches define :test, once per engine.
15
+ # rubocop:disable Rake/DuplicateTask
16
+ desc 'Run the test suite (padded_cell on CRuby, plain Minitest elsewhere)'
17
+ if RUBY_ENGINE == 'ruby'
18
+ task :test do
19
+ sh 'padded_cell', *Shellwords.split(ENV.fetch('TESTOPTS', ''))
20
+ end
21
+ else
22
+ task test: :minitest
23
+ end
24
+ # rubocop:enable Rake/DuplicateTask
25
+
26
+ require 'rubocop/rake_task'
27
+
28
+ RuboCop::RakeTask.new
29
+
30
+ task default: %i[test rubocop]
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'state_machines/diagram/introspection'
4
+
5
+ module StateMachines
6
+ module Yard
7
+ # A machine's events as text: the transitions each performs, as the core
8
+ # resolves them (from one source the first matching branch), with their
9
+ # guards and callbacks, labelled as the diagram renderers label them. The
10
+ # documentation carries this whatever renderer draws, or none.
11
+ module Description
12
+ Introspection = StateMachines::Diagram::Introspection
13
+ Labels = StateMachines::Diagram::Labels
14
+
15
+ module_function
16
+
17
+ # Each event as { name:, transitions: [line], failure: [callback] }, or
18
+ # { name:, error: } when the core refuses one of its conditions (a
19
+ # String it will not evaluate): it raises the same when it fires
20
+ def events(machine)
21
+ machine.events.map do |event|
22
+ { name: event.name.to_s,
23
+ transitions: Introspection.event_transitions(machine, event).map { transition(machine, event, *it) },
24
+ failure: failure_callbacks(machine, event) }
25
+ rescue SecurityError, ArgumentError => e
26
+ { name: event.name.to_s, error: e.message, transitions: [], failure: [] }
27
+ end
28
+ end
29
+
30
+ # "parked -> idling [if a && if_state gate=open] / before check, after log"
31
+ def transition(machine, event, from, to, branch)
32
+ guards = Labels.condition_phrases(Introspection.guard_conditions(branch))
33
+ callbacks = callback_steps(machine, from, to, event.name, branch)
34
+ ["#{Labels.state_text(from)} -> #{Labels.state_text(to)}",
35
+ ("[#{guards.join(' && ')}]" if guards.any?),
36
+ ("/ #{callbacks.join(', ')}" if callbacks.any?)].compact.join(' ')
37
+ end
38
+
39
+ # The callbacks in the order the core runs them, each with its kind: an
40
+ # around where it enters (as Labels.action_list lists it), the afters
41
+ # after the state change: "around time, before check, after log". The
42
+ # transition's own (transition ..., before:/around:/after:) run
43
+ # closest to the change: its befores and arounds after the machine's,
44
+ # its afters before them.
45
+ def callback_steps(machine, from, to, event_name, branch)
46
+ Introspection.callback_sequence(machine, from, to, event_name, branch: branch)
47
+ .reject { it[:phase] == :exit }
48
+ .map { "#{it[:kind]} #{Labels.callback_text(it)}" }
49
+ end
50
+
51
+ # The after_failure callbacks that run when the event fails
52
+ def failure_callbacks(machine, event)
53
+ machine.callbacks[:failure].select { it.branch.matches?(nil, on: event.name, guard: false) }
54
+ .flat_map do |callback|
55
+ conditions = Introspection.guard_conditions(callback.branch)
56
+ callback.callables.map do |method|
57
+ Labels.callback_text(label: Labels.action_label(method), conditions: conditions)
58
+ end
59
+ end
60
+ end
61
+
62
+ # The event's description lines for its methods' docstrings
63
+ def docstring_lines(event)
64
+ lines = if event[:error]
65
+ ['', "Its transitions cannot be described: #{event[:error]}"]
66
+ elsif event[:transitions].empty?
67
+ ['', 'No transitions: it never fires.']
68
+ else
69
+ ['', 'Transitions (from each state the first that matches is taken):', '',
70
+ *event[:transitions].map { "* #{it}" }]
71
+ end
72
+ lines += ['', "On failure: #{event[:failure].join(', ')}"] if event[:failure].any?
73
+ lines + ['']
74
+ end
75
+ end
76
+ end
77
+ end
@@ -0,0 +1,113 @@
1
+ # frozen_string_literal: true
2
+
3
+ module StateMachines
4
+ module Yard
5
+ module Handlers
6
+ # Reads the methods a callback runs as the core reads them, for
7
+ # handlers built on Base: a transition callback's (do:, positional, a
8
+ # block) and a transition's own (before:, around:, after:)
9
+ module Actions
10
+ # Literals without to_proc: & raises TypeError on them, so the
11
+ # declaration never runs. A Symbol and a Hash have one.
12
+ NO_TO_PROC = [
13
+ Prism::TrueNode, Prism::FalseNode, Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode,
14
+ Prism::ImaginaryNode, Prism::StringNode, Prism::InterpolatedStringNode, Prism::XStringNode,
15
+ Prism::InterpolatedXStringNode, Prism::SourceFileNode, Prism::SourceLineNode, Prism::SourceEncodingNode,
16
+ Prism::ArrayNode, Prism::RangeNode, Prism::RegularExpressionNode, Prism::InterpolatedRegularExpressionNode
17
+ ].freeze
18
+
19
+ private
20
+
21
+ # A do: option's methods: one, or an Array of them. The core reads
22
+ # it with Array(), so nil (do: nil) is no method.
23
+ def action_list(node)
24
+ return [] if nil_literal?(node)
25
+
26
+ node = unwrap(node)
27
+ node.is_a?(Prism::ArrayNode) ? node.elements.map { action(it) } : [action(node)]
28
+ end
29
+
30
+ # A method the callback runs, as the core reads it: a Symbol names a
31
+ # method, a String is code. A lambda or proc is shown as diagrams show
32
+ # a Proc, by where it is defined; any other code by its source.
33
+ def action(node)
34
+ node = unwrap(node)
35
+ case node
36
+ when Prism::SymbolNode, Prism::StringNode then literal(node)
37
+ else proc_literal?(node) ? lambda_label(node.location.start_line) : node.slice
38
+ end
39
+ end
40
+
41
+ # The expression a group gives: (x), ((x)) and begin x end are x. An
42
+ # empty group, or one of several expressions or with rescue / else /
43
+ # ensure, stays itself (see #nil_literal?).
44
+ def unwrap(node)
45
+ single = single_statement(group_body(node)) if group?(node)
46
+ single ? unwrap(single) : node
47
+ end
48
+
49
+ # nil, written as such or as an empty group: () or begin end
50
+ def nil_literal?(node)
51
+ node = unwrap(node)
52
+ node.is_a?(Prism::NilNode) || (group?(node) && group_body(node).nil?)
53
+ end
54
+
55
+ def group?(node)
56
+ node.is_a?(Prism::ParenthesesNode) ||
57
+ (node.is_a?(Prism::BeginNode) && !node.rescue_clause && !node.else_clause && !node.ensure_clause)
58
+ end
59
+
60
+ def group_body(node) = node.is_a?(Prism::BeginNode) ? node.statements : node.body
61
+
62
+ def single_statement(body)
63
+ return body unless body.is_a?(Prism::StatementsNode)
64
+
65
+ body.body.first if body.body.one?
66
+ end
67
+
68
+ # ->, lambda {}, proc {} or Proc.new {}
69
+ def proc_literal?(node)
70
+ return true if node.is_a?(Prism::LambdaNode)
71
+ return false unless node.is_a?(Prism::CallNode) && node.block
72
+
73
+ node.receiver.nil? ? %i[lambda proc].include?(node.name) : proc_new?(node)
74
+ end
75
+
76
+ def proc_new?(node)
77
+ node.name == :new && node.receiver.slice == 'Proc'
78
+ end
79
+
80
+ # The callback's own block, or a block argument: &:name as diagrams
81
+ # show a Symbol's proc, a Hash's proc as diagrams show a Proc without
82
+ # a source (lambda), anything else as an action. &nil passes no
83
+ # block, so it is no method; a literal without to_proc raises
84
+ # TypeError, so the declaration is refused as it never registers.
85
+ def block_actions(node)
86
+ return [lambda_label(node.location.start_line)] if node.is_a?(Prism::BlockNode)
87
+
88
+ expression = unwrap(node.expression)
89
+ return [] if nil_literal?(expression)
90
+ if NO_TO_PROC.any? { expression.is_a?(it) }
91
+ raise ArgumentError, "`#{node.slice}` is no block: Ruby raises TypeError, so the core never registers it"
92
+ end
93
+
94
+ [block_label(expression)]
95
+ end
96
+
97
+ def block_label(expression)
98
+ case expression
99
+ when Prism::SymbolNode then "&#{expression.slice}"
100
+ when Prism::HashNode then 'lambda'
101
+ else action(expression)
102
+ end
103
+ end
104
+
105
+ # "lambda@file:line", the label diagrams give a Proc; +line+ counts
106
+ # from the start of the statement
107
+ def lambda_label(line)
108
+ "lambda@#{File.basename(parser.file.to_s)}:#{statement.line + line - 1}"
109
+ end
110
+ end
111
+ end
112
+ end
113
+ end
@@ -1,35 +1,160 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'prism'
4
+
1
5
  module StateMachines
2
6
  module Yard
3
7
  module Handlers
4
- # Handles and processes nodes
8
+ # Handles and processes nodes. A handler reads its call's arguments
9
+ # from the source with Prism and takes only what is written as a
10
+ # literal: nothing in the documented code is run.
5
11
  class Base < YARD::Handlers::Ruby::Base
12
+ # An argument that is not a literal, so its value is only known when
13
+ # the code runs
14
+ class Unreadable < StandardError; end
15
+
16
+ # Code the documented source holds where the core takes a value (a
17
+ # state's value: or human_name:), shown as it is written
18
+ Code = Data.define(:source) do
19
+ def to_s = source
20
+ def inspect = source
21
+ end
22
+
23
+ # The literals Ruby spells as keywords
24
+ KEYWORDS = { Prism::NilNode => nil, Prism::TrueNode => true, Prism::FalseNode => false }.freeze
25
+ NUMBERS = [Prism::IntegerNode, Prism::FloatNode].freeze
26
+ # The literals a name can be
27
+ NAMES = [Symbol, String, Integer, Float, TrueClass, FalseClass].freeze
28
+ # Text literals, and how each turns its text into its value
29
+ TEXTS = { Prism::SymbolNode => :to_sym, Prism::StringNode => :itself }.freeze
6
30
 
7
31
  private
8
32
 
9
- # Extracts the value from the node as either a string or symbol
10
- def extract_node_name(ast)
11
- case ast.type
12
- when :symbol_literal
13
- ast.jump(:ident).source.to_sym
14
- when :string_literal
15
- ast.jump(:tstring_content).source
16
- else
17
- nil
33
+ # The handled call as Prism reads it
34
+ def call_node
35
+ @call_node ||= begin
36
+ source = call_source
37
+ node = Prism.parse(source).value.statements.body.first
38
+ raise Unreadable, "`#{source}` is not a plain call" unless node.is_a?(Prism::CallNode)
39
+
40
+ node
18
41
  end
19
42
  end
20
43
 
21
- # Extracts the values from the node as either strings or symbols.
22
- # If the node isn't an array, it'll be converted to an array.
23
- def extract_node_names(ast, convert_to_array = true)
24
- if ast.is_a?(Array)
25
- ast.map { |child| extract_node_name(child) }
26
- elsif ast.nil? || ast.type == :array
27
- ast.children.map { |child| extract_node_name(child) }
28
- else
29
- node_name = extract_node_name(ast)
30
- convert_to_array ? [node_name] : node_name
44
+ # The handled call's source, as Prism reads it in the file. YARD's
45
+ # parser ends a statement before a trailing rational or imaginary
46
+ # literal (`after: 1r` reads `after:`, which Prism reads as a call to
47
+ # `after`) and past a trailing negative number (`-1 }`), so the call is
48
+ # the one Prism finds where the statement starts.
49
+ def call_source
50
+ FileSource.call_at(statement.full_source, statement.source_range.begin)&.slice || statement.source
51
+ end
52
+
53
+ # The calls of the file being documented, read once per file
54
+ module FileSource
55
+ @calls = nil
56
+
57
+ # The innermost call starting at character +offset+ of +source+
58
+ def self.call_at(source, offset)
59
+ @calls = [source, calls_by_offset(source)] unless @calls&.first.equal?(source)
60
+ @calls.last[offset]
61
+ end
62
+
63
+ def self.calls_by_offset(source)
64
+ calls = Prism.parse(source).value.breadth_first_search_all { it.is_a?(Prism::CallNode) }
65
+ calls.group_by { it.location.start_character_offset }.transform_values { it.min_by { it.location.length } }
66
+ end
67
+ end
68
+
69
+ # The call's positional arguments, as nodes
70
+ def positional_arguments
71
+ arguments = call_node.arguments&.arguments || []
72
+ options_node?(arguments.last) ? arguments[0...-1] : arguments
73
+ end
74
+
75
+ # The call's trailing options Hash, as [key node, value node] pairs
76
+ def option_pairs
77
+ last = call_node.arguments&.arguments&.last
78
+ options_node?(last) ? pairs(last) : []
79
+ end
80
+
81
+ def options_node?(node)
82
+ node.is_a?(Prism::KeywordHashNode) || node.is_a?(Prism::HashNode)
83
+ end
84
+
85
+ def pairs(node)
86
+ node.elements.map do |element|
87
+ unreadable(element) unless element.is_a?(Prism::AssocNode)
88
+
89
+ [element.key, element.value]
31
90
  end
32
91
  end
92
+
93
+ # The value of a literal: a Symbol, String, nil, true, false, number,
94
+ # or an Array or Hash of those
95
+ def literal(node)
96
+ case node
97
+ when *TEXTS.keys then node.unescaped.public_send(TEXTS.fetch(node.class))
98
+ when *KEYWORDS.keys then KEYWORDS.fetch(node.class)
99
+ when *NUMBERS then node.value
100
+ when Prism::ArrayNode then node.elements.map { literal(it) }
101
+ when Prism::HashNode then pairs(node).to_h { |key, value| [literal(key), literal(value)] }
102
+ else unreadable(node)
103
+ end
104
+ end
105
+
106
+ # A state, event or machine name: any literal the core takes as one,
107
+ # a Symbol, String, number, true or false (or nil, the nil state,
108
+ # when +nil_allowed+)
109
+ def name_literal(node, nil_allowed: false)
110
+ value = literal(node)
111
+ return value if NAMES.any? { value.is_a?(it) } || (nil_allowed && value.nil?)
112
+
113
+ unreadable(node)
114
+ end
115
+
116
+ # The names one argument gives: a name, or an Array of them
117
+ def names_in(node, nil_allowed: false)
118
+ return [name_literal(node, nil_allowed: nil_allowed)] unless node.is_a?(Prism::ArrayNode)
119
+
120
+ node.elements.map { name_literal(it, nil_allowed: nil_allowed) }
121
+ end
122
+
123
+ # The literal options among +keys+; any other option is left out. An
124
+ # option written as code is a Code of its source when it is one of
125
+ # +code+, and otherwise left out; either way with a warning, since
126
+ # the documentation cannot show its value.
127
+ def literal_options(keys, code: [])
128
+ option_pairs.each_with_object({}) do |(key, value), options|
129
+ name = literal(key)
130
+ next unless keys.include?(name)
131
+
132
+ options[name] = option_literal(name, value, code)
133
+ rescue Unreadable
134
+ next
135
+ end
136
+ end
137
+
138
+ def option_literal(name, node, code)
139
+ literal(node)
140
+ rescue Unreadable
141
+ documented = code.include?(name) ? 'documented as its source' : 'left out'
142
+ log.warn "state_machines-yard: #{name}: is code (`#{node.slice}`), #{documented} " \
143
+ "(#{parser.file}:#{statement.line})"
144
+ raise unless code.include?(name)
145
+
146
+ Code.new(node.slice)
147
+ end
148
+
149
+ def unreadable(node)
150
+ raise Unreadable, "`#{node.slice}` is code, not a literal"
151
+ end
152
+
153
+ # Logs that +what+ is left out of the documentation, and why
154
+ def skip(what, error)
155
+ log.warn "state_machines-yard: #{what} is not documented: #{error.message} " \
156
+ "(#{parser.file}:#{statement.line})"
157
+ end
33
158
  end
34
159
  end
35
160
  end