aasm-vis 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abab34e1ec6ea9364f7963c0ed11f5e81527206bfea2c296cba867c5c19a2d2b
-  data.tar.gz: c03d37d981466d01cad1c651ac1eeb8859f73d2d04180bfdd853fcab911255bf
+  metadata.gz: d7b6d25b80b1bd50f15e6ab175b28ce0b7370fce404effdc28106a866ecdc96b
+  data.tar.gz: 6b18f5d5a8c0282f30b707dce7501dfb5904cdd9d3860b34215a4d940012f206
 SHA512:
-  metadata.gz: c2790e89a20c09851e858f0a375140c1a0966686bdeae2bfbb26ba1ff794e210e1a2f5f12916e4abd7445aaf72847d42124b6f035b3d8ad0abfbea5e91ee8d7f
-  data.tar.gz: ac07cd5d3f3359f48d6ea3c84acfa3613dc36ec28cbb66f62e2229362bda5ea7ae46f16b4b12fc5adf030b6f961399eec38a28a2e6e4c81578a40203a8541412
+  metadata.gz: f90915660c6b6ec2d5010b21fcdf8d495df6d50344ddd1d9b06060b25685b9a6f432769edcae87dbb52b8d0e2f7a9314fd9ca34ea61723489372a573ac5f3871
+  data.tar.gz: ba9a2e7ca3070ce3b53b29002c2085b554afd14a1a508f809f9d9c22ab3743248de285fe390e71bffef75609fa53a82d20f91cce21052be78146d8a6fc9573af

data/.rubocop.yml

@@ -11,3 +11,8 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+# Example-heavy spec files legitimately exceed the default block length.
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-23
+
+### Added
+
+- Label each state-diagram edge with the event that triggers the transition
+  (`from --> to : event_name`), so transitions leaving the same state are no
+  longer ambiguous.
+- Limit generation to specific classes via rake task arguments, e.g.
+  `rake 'aasm_vis:generate[Job,Order]'`. With no arguments every machine is
+  still generated.

data/CODEOWNERS

@@ -0,0 +1 @@
+* @kamil-gwozdz

data/README.md

@@ -10,7 +10,19 @@ Add `gem 'aasm-vis', group: :development` to your `Gemfile` and run `bundle`.
 
 `bundle exec rake aasm_vis:generate`
 
-To visualise the results you can use the [github cli](https://cli.github.com/): `gh gist create tmp/assm-vis.md` or any other tool that can render markdown files supporting mermaid.
+To visualise the results you can use the [github cli](https://cli.github.com/): `gh gist create tmp/aasm-vis.md` or any other tool that can render markdown files supporting mermaid.
+
+### Selecting models
+
+By default every AASM state machine in the application is diagrammed. To limit
+the output to specific classes, pass them as rake task arguments:
+
+```sh
+bundle exec rake 'aasm_vis:generate[Job,Order]'
+```
+
+The quotes are required in zsh, which otherwise treats the brackets as a glob.
+Namespaced classes must be given in full, e.g. `'aasm_vis:generate[Billing::Invoice]'`.
 
 ## Example
 
@@ -18,23 +30,31 @@ The following ruby code defines a simple state machine for a `Job` model:
 ```ruby
 class Job < ApplicationRecord
   include AASM
-  
+
   aasm :state do
     state :created, initial: true
     state :running
     state :finished_successfully
     state :finished_with_error
-    
-    event :run, after: :notify_somebody do
+
+    event :run do
       transitions from: :created, to: :running
-      transitions from: :running, to: :finished_with_error
+    end
+
+    event :succeed do
       transitions from: :running, to: :finished_successfully
     end
+
+    event :error do
+      transitions from: :running, to: :finished_with_error
+    end
   end
 end
 ```
 
-It will generate the following mermaid diagram:
+It will generate the following mermaid diagram. Each edge is labelled with the
+event that triggers the transition, so transitions leaving the same state stay
+distinguishable:
 
 ```mermaid
 ---
@@ -46,14 +66,13 @@ created : Created
 running : Running
 finished_successfully : Finished successfully
 finished_with_error : Finished with error
-  
-[*] --> created
-created --> running
-running --> finished_with_error
-running --> finished_successfully
 
-finished_with_error --> [*]
+created --> running : run
+running --> finished_successfully : succeed
+running --> finished_with_error : error
+
 finished_successfully --> [*]
+finished_with_error --> [*]
 ```
 
 ## Development

data/lib/aasm/vis/tasks/generate.rake

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 class Helper
   include AASM::Vis
 end
 
 namespace :aasm_vis do
-  desc 'Generate markdown file with visualisation of AASM state machines.'
+  desc "Generate markdown file with visualisation of AASM state machines. " \
+       "Optionally limit to specific classes, e.g. aasm_vis:generate[Job,Order]."
 
   dependencies = defined?(Rails) ? [:environment] : []
-  task generate: dependencies do
-    helper = Helper.new
-    helper.generate_markdown
+  task :generate, [:only] => dependencies do |_task, args|
+    Helper.new.generate_markdown(only: args.to_a)
   end
 end

data/lib/aasm/vis/version.rb

@@ -2,6 +2,6 @@
 
 module AASM
   module Vis
-    VERSION = "0.1.4"
+    VERSION = "0.2.0"
   end
 end

data/lib/aasm/vis.rb

@@ -3,51 +3,108 @@
 require_relative "vis/version"
 
 module AASM
+  # Generates Mermaid state-diagram markdown for every AASM state machine
+  # registered in the host application. Mix into a class and call
+  # +generate_markdown+ (the rake task does this) or +build_diagrams+ to get the
+  # markdown as a string.
   module Vis
-    require_relative 'vis/railtie' if defined?(Rails)
+    require_relative "vis/railtie" if defined?(Rails)
 
     class Error < StandardError; end
 
-    def generate_markdown
+    # Writes the Mermaid markdown for the AASM state machines to +tmp/aasm-vis.md+.
+    #
+    # @param only [Array<String>, nil] class names to include; nil or empty
+    #   generates every machine (the default).
+    # @return [void]
+    def generate_markdown(only: nil)
       Rails.application.eager_load! if defined?(Rails)
 
-      results = []
+      path = File.join(Dir.pwd, "tmp", "aasm-vis.md")
+      File.write(path, build_diagrams(only: only))
+      puts "File written to: #{path}"
+    end
+
+    # Builds the Mermaid markdown for the AASM state machines.
+    #
+    # @param only [Array<String>, nil] class names to include; nil or empty
+    #   includes every machine. Namespaced classes must be given in full
+    #   (e.g. "Billing::Invoice").
+    # @return [String] concatenated ```mermaid blocks, one per state machine.
+    def build_diagrams(only: nil)
+      filter = Array(only).map(&:to_s).reject(&:empty?)
+      diagrams = []
 
       AASM::StateMachineStore.stores.each do |klass_name, klass_store|
-        klass_store.keys.each do |column|
-          transitions = []
-          klass = klass_name.safe_constantize
-          klass.aasm(column).events.each do |event|
-            event.name
-            event.default_display_name
-
-            event.transitions.each do |transition|
-              transitions << [transition.from, transition.to]
-            end
-          end
-
-          results << <<~TXT
-            ```mermaid
-            ---
-            title: #{klass}##{column}
-            ---
-            stateDiagram-v2
-            
-              #{klass.aasm(column).states.map { |state| "#{state.name} : #{state.default_display_name}" }.join("\n") }
-              
-              #{transitions.map { |from, to| "#{from.nil? ? "[*]" : from } --> #{to}" }.join("\n") }
-
-              #{transitions.map { |_from, to| "#{to} --> [*]" if transitions.none? { |t| t[0] == to } }.reject(&:nil?).join("\n")}
-            ```
-          TXT
-        end
+        next unless included?(klass_name, filter)
+
+        klass = klass_name.safe_constantize
+        klass_store.machine_names.each { |column| diagrams << diagram_for(klass, column) }
       end
 
-      path = File.join(Dir.pwd,'tmp', 'assm-vis.md')
-      results = results.join("\n\n")
+      diagrams.join("\n\n")
+    end
 
-      File.write(path, results)
-      puts "File written to: #{path}"
+    private
+
+    # @return [Boolean] true when filter is empty (include all) or names this class.
+    def included?(klass_name, filter)
+      filter.empty? || filter.include?(klass_name.to_s)
+    end
+
+    # Builds a single ```mermaid stateDiagram-v2 block for one machine.
+    #
+    # Each transition is rendered as a labelled edge (+from --> to : event_name+)
+    # so transitions between the same pair of states triggered by different
+    # events stay distinguishable.
+    #
+    # @param klass [Class] the AASM-including class.
+    # @param column [String] the state machine name (e.g. "state").
+    # @return [String]
+    def diagram_for(klass, column)
+      machine = klass.aasm(column)
+      transitions = collect_transitions(machine)
+
+      <<~TXT
+        ```mermaid
+        ---
+        title: #{klass}##{column}
+        ---
+        stateDiagram-v2
+
+          #{state_nodes(machine).join("\n")}
+
+          #{transition_edges(transitions).join("\n")}
+
+          #{terminal_edges(transitions).join("\n")}
+        ```
+      TXT
+    end
+
+    # @return [Array<Array(Symbol, Symbol, Symbol)>] [from, to, event_name] tuples.
+    def collect_transitions(machine)
+      machine.events.flat_map do |event|
+        event.transitions.map { |transition| [transition.from, transition.to, event.name] }
+      end
+    end
+
+    # @return [Array<String>] +state_id : Display Name+ node declarations.
+    def state_nodes(machine)
+      machine.states.map { |state| "#{state.name} : #{state.default_display_name}" }
+    end
+
+    # @return [Array<String>] labelled +from --> to : event+ edges.
+    def transition_edges(transitions)
+      transitions.map { |from, to, name| "#{from.nil? ? "[*]" : from} --> #{to} : #{name}" }
+    end
+
+    # States that are never a transition source are terminal; link them to the
+    # final pseudo-state.
+    #
+    # @return [Array<String>] +state --> [*]+ edges, de-duplicated.
+    def terminal_edges(transitions)
+      transitions.map { |_from, to, _name| "#{to} --> [*]" if transitions.none? { |t| t[0] == to } }
+                 .compact.uniq
     end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: aasm-vis
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Kamil Gwóźdź
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-18 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aasm
@@ -63,6 +62,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CODEOWNERS
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -82,7 +82,6 @@ metadata:
   homepage_uri: https://github.com/kamil-gwozdz/aasm-vis
   source_code_uri: https://github.com/kamil-gwozdz/aasm-vis
   changelog_uri: https://github.com/kamil-gwozdz/aasm-vis/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,8 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.6
 specification_version: 4
 summary: Gem for visualizing AASM state machines.
 test_files: []