state_machines-yard 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ae4aeccc3211632b5b25f19bfa30b576adfcc4fc
-  data.tar.gz: 797a207f6c1a883619c089148ab7d76fa4c5640c
+SHA256:
+  metadata.gz: f44c4181dbd4a72f83b7a3c39b41c12a70decb9cc9479f942322eead08cab927
+  data.tar.gz: 6c992389d5a3ab8cda9e879871ceccc9fd071283278b292e69e8bd54b0e80f00
 SHA512:
-  metadata.gz: 3bd4c0b651acab5ea3469ec81e33a78209ebbec1f81c84adc89159fa42cba8b97178570d662223388855c7cbe8493c65a84c9cc0d9ffcdedbcd4d063939065d2
-  data.tar.gz: f027b5799f58e0a5a43d1910013ee1d55d8d0eb0af5ae75ea57c39b7e90e5ba19139c6f486bb5b092841ebabae7b811d31344dc32fdd2e4cba840288b5fba72b
+  metadata.gz: 31dbd1176ec57de4d9fb5221008d7bc651f7508a47fe407b401f536ac738f7788b2b5555bfbf4c1d0913838bb5f3ca5b7762ef022b4ed40b3955bc9c567692b4
+  data.tar.gz: 1a298b682b5ff8a3c1074e49f54bdf41b8b06e5f2122825fcc4465d052e1efed9455228b95162ca53dad431cdc13ecad8c3691056bd3257c25982802c14d2193

data/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.0'
+        bundler-cache: true
+    - name: Install graphviz  
+      run: sudo apt-get update && sudo apt-get install -y graphviz
+    - name: Run tests
+      run: bundle exec rake

data/.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: googleapis/release-please-action@v3
+        with:
+          release-type: ruby
+          package-name: state_machines-yard

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2025-03-18)
+
+
+### Features
+
+* add tests ([37d6f34](https://github.com/state-machines/state_machines-yard/commit/37d6f3482d98222dfbb4940cf1f2ba846d95ca5f))

data/Gemfile

@@ -1,2 +1,4 @@
 source 'https://rubygems.org'
 gemspec
+
+gem 'ruby-graphviz', github: 'seuros/ruby-graphviz'

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Copyright (c) 2006-2012 Aaron Pfeifer
-Copyright (c) 2014 Abdelkader Boudih
+Copyright (c) 2014-2025 Abdelkader Boudih
 
 MIT License
 

data/README.md

@@ -16,10 +16,17 @@ Or install it yourself as:
 
     $ gem install state_machines-yard
 
+## Testing
+
+A comprehensive test suite is included for the gem. To run all tests:
+
+```
+rake test
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/seuros/state_machines-yard/fork )
+1. Fork it ( https://github.com/state-machines/state_machines-yard/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -1 +1,12 @@
 require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+  t.warning = false
+end
+
+desc 'Run tests'
+task default: :test

data/lib/state_machines/yard/handlers/base.rb

@@ -1,8 +1,8 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     module Handlers
       # Handles and processes nodes
-      class Base < ::YARD::Handlers::Ruby::Base
+      class Base < YARD::Handlers::Ruby::Base
 
         private
 
@@ -21,7 +21,9 @@ module StateMachine
         # Extracts the values from the node as either strings or symbols.
         # If the node isn't an array, it'll be converted to an array.
         def extract_node_names(ast, convert_to_array = true)
-          if [nil, :array].include?(ast.type)
+          if ast.is_a?(Array)
+            ast.map { |child| extract_node_name(child) }
+          elsif ast.nil? || ast.type == :array
             ast.children.map { |child| extract_node_name(child) }
           else
             node_name = extract_node_name(ast)

data/lib/state_machines/yard/handlers/event.rb

@@ -1,9 +1,12 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     module Handlers
       # Handles and processes #event
       class Event < Base
         handles method_call(:event)
+        
+        # Store the handled method name for testing
+        @handles_method = :event
 
         def process
           if owner.is_a?(StateMachines::Machine)
@@ -13,8 +16,10 @@ module StateMachine
 
             names.each do |name|
               owner.event(name) do
-                # Parse the block
-                handler.parse_block(statement.last.last, owner: self)
+                # Parse the block only if it exists
+                if statement.block
+                  handler.parse_block(statement.block.last, owner: self)
+                end
               end
             end
           end

data/lib/state_machines/yard/handlers/machine.rb

@@ -1,10 +1,13 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     module Handlers
       # Handles and processes #state_machine
       class Machine < Base
         handles method_call(:state_machine)
         namespace_only
+        
+        # Store the handled method name for testing
+        @handles_method = :state_machine
 
         # The generated state machine
         attr_reader :machine
@@ -85,7 +88,7 @@ module StateMachine
             namespace.inheritance_tree.each do |ancestor|
               begin
                 ensure_loaded!(ancestor)
-              rescue ::YARD::Handlers::NamespaceMissingError
+              rescue YARD::Handlers::NamespaceMissingError
                 # Ignore: just means that we can't access an ancestor
               end
             end
@@ -103,7 +106,7 @@ module StateMachine
         # Gets members of this class's superclasses have already been loaded
         # by YARD
         def loaded_superclasses
-          namespace.inheritance_tree.select { |ancestor| ancestor.is_a?(::YARD::CodeObjects::ClassObject) }
+          namespace.inheritance_tree.select { |ancestor| ancestor.is_a?(YARD::CodeObjects::ClassObject) }
         end
 
         # Gets a list of all attributes for the current class, including those
@@ -132,10 +135,11 @@ module StateMachine
 
         # Defines auto-generated macro methods for the given machine
         def define_macro_methods
-          return if inherited_machine
-
-          # Human state name lookup
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}", :class))
+          # Don't exit early for inherited machine since we need to register instance methods
+          # even for inherited machines
+          
+          # Human state name lookup (class method)
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}", :class))
           m.docstring = [
               'Gets the humanized name for the given state.',
               "@param [#{state_type}] state The state to look up",
@@ -143,14 +147,17 @@ module StateMachine
           ]
           m.parameters = ['state']
 
-          # Human event name lookup
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:event_name)}", :class))
+          # Human event name lookup (class method)
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:event_name)}", :class))
           m.docstring = [
               'Gets the humanized name for the given event.',
               "@param [#{event_type}] event The event to look up",
               '@return [String] The human event name'
           ]
           m.parameters = ['event']
+          
+          # Skip the rest if this is an inherited machine
+          return if inherited_machine
 
           # Only register attributes when the accessor isn't explicitly defined
           # by the class / superclass *and* isn't defined by inference from the
@@ -160,7 +167,7 @@ module StateMachine
             namespace.attributes[:instance][attribute] = {}
 
             # Machine attribute getter
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, attribute))
             namespace.attributes[:instance][attribute][:read] = m
             m.docstring = [
                 'Gets the current attribute value for the machine',
@@ -168,7 +175,7 @@ module StateMachine
             ]
 
             # Machine attribute setter
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
             namespace.attributes[:instance][attribute][:write] = m
             m.docstring = [
                 'Sets the current value for the machine',
@@ -182,7 +189,7 @@ module StateMachine
             namespace.attributes[:instance][attribute] = {}
 
             # Machine event attribute getter
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, attribute))
             namespace.attributes[:instance][attribute][:read] = m
             m.docstring = [
                 'Gets the current event attribute value for the machine',
@@ -190,7 +197,7 @@ module StateMachine
             ]
 
             # Machine event attribute setter
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
             namespace.attributes[:instance][attribute][:write] = m
             m.docstring = [
                 'Sets the current value for the machine',
@@ -199,8 +206,10 @@ module StateMachine
             m.parameters = ["new_#{attribute}"]
           end
 
+          # These instance methods are always defined, even for inherited machines
+          
           # Presence query
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{machine.name}?"))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{machine.name}?"))
           m.docstring = [
               'Checks the given state name against the current state.',
               "@param [#{state_type}] state_name The name of the state to check",
@@ -210,21 +219,29 @@ module StateMachine
           m.parameters = ['state_name']
 
           # Internal state name
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:name)))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:name)))
           m.docstring = [
               'Gets the internal name of the state for the current value.',
               "@return [#{state_type}] The internal name of the state"
           ]
 
-          # Human state name
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}"))
+          # Human state name instance method - this is always defined regardless of inheritance
+          # Ensure the name is correct - we explicitly check the attribute name to make sure it's generated correctly
+          human_method_name = "human_#{machine.attribute(:name)}"
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, human_method_name))
           m.docstring = [
               'Gets the human-readable name of the state for the current value.',
               '@return [String] The human-readable state name'
           ]
+          
+          # Debug output for testing - we want to make sure we're registering the method correctly
+          # puts "Registered instance method: #{namespace}##{human_method_name} (#{m})"
+          
+          # The below methods should only be defined for non-inherited machines
+          return if inherited_machine
 
           # Available events
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:events)))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:events)))
           m.docstring = [
               "Gets the list of events that can be fired on the current #{machine.name} (uses the *unqualified* event names)",
               '@param [Hash] requirements The transition requirements to test against',
@@ -237,7 +254,7 @@ module StateMachine
           m.parameters = [['requirements', '{}']]
 
           # Available transitions
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:transitions)))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:transitions)))
           m.docstring = [
               "Gets the list of transitions that can be made for the current #{machine.name}",
               '@param [Hash] requirements The transition requirements to test against',
@@ -250,7 +267,7 @@ module StateMachine
           m.parameters = [['requirements', '{}']]
 
           # Available transition paths
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:paths)))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:paths)))
           m.docstring = [
               "Gets the list of sequences of transitions that can be run for the current #{machine.name}",
               '@param [Hash] requirements The transition requirements to test against',
@@ -263,7 +280,7 @@ module StateMachine
           m.parameters = [['requirements', '{}']]
 
           # Generic event fire
-          register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "fire_#{machine.attribute(:event)}"))
+          register(m = YARD::CodeObjects::MethodObject.new(namespace, "fire_#{machine.attribute(:event)}"))
           m.docstring = [
               "Fires an arbitrary #{machine.name} event with the given argument list",
               "@param [#{event_type}] event The name of the event to fire",
@@ -279,11 +296,11 @@ module StateMachine
             next if inherited_machine && inherited_machine.events[event.name]
 
             # Event query
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "can_#{event.qualified_name}?"))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "can_#{event.qualified_name}?"))
             m.docstring = [
                 "Checks whether #{event.name.inspect} can be fired.",
                 '@param [Hash] requirements The transition requirements to test against',
-                "@option requirements [#{state_type}] :from (the current state) One or more initial states",
+                "@option requirements [#{state_type}] :from One or more initial states",
                 "@option requirements [#{state_type}] :to One or more target states",
                 '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
                 "@return [Boolean] +true+ if #{event.name.inspect} can be fired, otherwise +false+"
@@ -291,11 +308,11 @@ module StateMachine
             m.parameters = [['requirements', '{}']]
 
             # Event transition
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}_transition"))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}_transition"))
             m.docstring = [
                 "Gets the next transition that would be performed if #{event.name.inspect} were to be fired.",
                 '@param [Hash] requirements The transition requirements to test against',
-                "@option requirements [#{state_type}] :from (the current state) One or more initial states",
+                "@option requirements [#{state_type}] :from One or more initial states",
                 "@option requirements [#{state_type}] :to One or more target states",
                 '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
                 '@return [StateMachines::Transition] The transition that would be performed or +nil+'
@@ -303,7 +320,7 @@ module StateMachine
             m.parameters = [['requirements', '{}']]
 
             # Fire event
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, event.qualified_name))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, event.qualified_name))
             m.docstring = [
                 "Fires the #{event.name.inspect} event.",
                 '@param [Array] args Optional arguments to include in transition callbacks',
@@ -312,7 +329,7 @@ module StateMachine
             m.parameters = ['*args']
 
             # Fire event (raises exception)
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}!"))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}!"))
             m.docstring = [
                 "Fires the #{event.name.inspect} event, raising an exception if it fails.",
                 '@param [Array] args Optional arguments to include in transition callbacks',
@@ -329,7 +346,7 @@ module StateMachine
             next if inherited_machine && inherited_machine.states[state.name] || !state.name
 
             # State query
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{state.qualified_name}?"))
+            register(m = YARD::CodeObjects::MethodObject.new(namespace, "#{state.qualified_name}?"))
             m.docstring = [
                 "Checks whether #{state.name.inspect} is the current state.",
                 '@return [Boolean] +true+ if this is the current state, otherwise +false+'

data/lib/state_machines/yard/handlers/state.rb

@@ -1,9 +1,12 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     module Handlers
       # Handles and processes #state
       class State < Base
         handles method_call(:state)
+        
+        # Store the handled method name for testing
+        @handles_method = :state
 
         def process
           if owner.is_a?(StateMachines::Machine)
@@ -13,8 +16,10 @@ module StateMachine
 
             names.each do |name|
               owner.state(name) do
-                # Parse the block
-                handler.parse_block(statement.last.last, owner: self)
+                # Parse the block only if it exists
+                if statement.block
+                  handler.parse_block(statement.block.last, owner: self)
+                end
               end
             end
           end

data/lib/state_machines/yard/handlers/transition.rb

@@ -1,9 +1,12 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     module Handlers
       # Handles and processes #transition
       class Transition < Base
         handles method_call(:transition)
+        
+        # Store the handled method name for testing
+        @handles_method = :transition
 
         def process
           if [StateMachines::Machine, StateMachines::Event, StateMachines::State].include?(owner.class)
@@ -13,7 +16,7 @@ module StateMachine
             ast = statement.parameters.first
             ast.children.each do |assoc|
               # Skip conditionals
-              next if %w(if unless).include?(assoc[0].jump(:ident).source)
+              next if %w(if :if unless :unless).include?(assoc[0].jump(:ident).source)
 
               options[extract_requirement(assoc[0])] = extract_requirement(assoc[1])
             end

data/lib/state_machines/yard/handlers.rb

@@ -1,12 +1,8 @@
-module StateMachine
-  module YARD
+module StateMachines
+  module Yard
     # YARD custom handlers for integrating the state_machine DSL with the
     # YARD documentation system
     module Handlers
     end
   end
-end
-
-Dir["#{File.dirname(__FILE__)}/handlers/*.rb"].sort.each do |path|
-  require "state_machines/yard/handlers/#{File.basename(path)}"
-end
+end

data/lib/state_machines/yard/version.rb

@@ -1,5 +1,5 @@
 module StateMachines
   module Yard
-    VERSION = '0.0.1'
+    VERSION = '0.1.0'
   end
 end

data/lib/state_machines/yard.rb

@@ -1,10 +1,15 @@
-require 'state_machines/yard/version'
+require 'yard'
+require_relative 'yard/version'
 module StateMachines
   # YARD plugin for automated documentation
   module Yard
   end
 end
 
-require 'tempfile'
-require 'state_machines/yard/handlers'
-require 'state_machines/yard/templates'
+require_relative 'yard/handlers'
+require_relative 'yard/handlers/base'
+require_relative 'yard/handlers/event'
+require_relative 'yard/handlers/machine'
+require_relative 'yard/handlers/state'
+require_relative 'yard/handlers/transition'
+require_relative 'yard/templates'

data/state_machines-yard.gemspec

@@ -1,7 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'state_machines/yard/version'
+require_relative 'lib/state_machines/yard/version'
 
 Gem::Specification.new do |spec|
   spec.name = 'state_machines-yard'
@@ -10,16 +7,19 @@ Gem::Specification.new do |spec|
   spec.email = ['terminale@gmail.com']
   spec.summary = %q(State machines YARD plugin)
   spec.description = %q(State machines YARD plugin for automated documentation)
-  spec.homepage = 'https://github.com/seuros/state_machines-yard'
+  spec.homepage = 'https://github.com/state-machines/state_machines-yard'
   spec.license = 'MIT'
 
-  spec.required_ruby_version     = '>= 1.9.3'
+  spec.required_ruby_version     = '>= 3.0'
 
   spec.files = `git ls-files -z`.split("\x0")
   spec.require_paths = ['lib']
 
   spec.add_dependency 'yard'
   spec.add_dependency 'state_machines-graphviz'
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake'
+  spec.add_dependency 'rdoc'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'nokogiri'
 end

data/test/handlers/base_test.rb

@@ -0,0 +1,76 @@
+require 'test_helper'
+
+class BaseHandlerTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_extract_node_name_with_symbol
+    code = <<-RUBY
+      class TestClass
+        state_machine :status do
+          # Test using a symbol
+          state :parked
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    # We can't directly test the extract_node_name method since it's private
+    # But we can test that symbol nodes were correctly processed
+    test_class = YARD::Registry.at('TestClass')
+    refute_nil test_class, "TestClass should be registered"
+    
+    parked_method = YARD::Registry.at('TestClass#parked?')
+    refute_nil parked_method, "parked? method should be registered"
+  end
+
+  def test_extract_node_name_with_string
+    code = <<-RUBY
+      class TestClass
+        state_machine :status do
+          # Test using a string
+          state "moving"
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    # Test that string nodes were correctly processed
+    test_class = YARD::Registry.at('TestClass')
+    refute_nil test_class, "TestClass should be registered"
+    
+    moving_method = YARD::Registry.at('TestClass#moving?')
+    refute_nil moving_method, "moving? method should be registered"
+  end
+
+  def test_extract_node_names_with_array
+    code = <<-RUBY
+      class TestClass
+        state_machine :status do
+          # Test using an array
+          state :parked, :idling, :moving
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    # Test that array nodes were correctly processed
+    test_class = YARD::Registry.at('TestClass')
+    refute_nil test_class, "TestClass should be registered"
+    
+    %w(parked idling moving).each do |state|
+      method = YARD::Registry.at("TestClass##{state}?")
+      refute_nil method, "#{state}? method should be registered"
+    end
+  end
+end