Initial commit

.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stateoscope.gemspec
+gemspec

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Patrick Oscity
+
+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.

README.md

@@ -0,0 +1,50 @@
+# Stateoscope
+
+Visualize State Machines using GraphViz
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stateoscope'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+To generate a state machine visualization for your `Model`, run
+
+```ruby
+rake 'stateoscope:visualize[Model]'
+```
+
+If you have multiple state machines defined on your model, you can pass the name
+of the state machine as second parameter
+
+```ruby
+rake 'stateoscope:visualize[Model,specific_state_machine]'
+```
+
+In both cases, a PDF file containing the graph visualization will be saved to
+the current directory.
+
+## Integrations
+
+Stateoscope is currently integrated with the following state machine gems:
+
+* [AASM](https://github.com/aasm/aasm)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/stateoscope.
+

Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "stateoscope"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

lib/stateoscope.rb

@@ -0,0 +1,18 @@
+require 'stateoscope/version'
+require 'stateoscope/integrations'
+require 'stateoscope/visualizer'
+
+require 'stateoscope/railtie' if defined?(Rails)
+
+module Stateoscope
+  def self.visualize(klass, options = {})
+    state_machine_name = options.fetch(:state_machine_name, nil)
+    integration = Integrations.new_for(klass, state_machine_name)
+    filename = options.fetch(:filename, filename_for(integration))
+    Visualizer.new(integration.graph).output(filename)
+  end
+
+  def self.filename_for(integration)
+    "#{integration.full_state_machine_name}-#{Time.now.utc.strftime('%Y%m%d%H%M%s')}"
+  end
+end

lib/stateoscope/graph.rb

@@ -0,0 +1,29 @@
+require 'ostruct'
+
+module Stateoscope
+  class Graph
+    attr_accessor :initial_state, :states, :final_states, :transitions
+
+    def initialize
+      @states = []
+      @final_states = []
+      @transitions = []
+    end
+
+    def add_state(state)
+      @states << state
+    end
+
+    def add_transition(from, to, event)
+      @transitions << OpenStruct.new(from: from, to: to, event: event)
+    end
+
+    def detect_final_states!
+      @final_states = states - transitions.map(&:from)
+    end
+
+    def final_state?(state)
+      @final_states.include?(state)
+    end
+  end
+end

lib/stateoscope/integrations.rb

@@ -0,0 +1,14 @@
+require 'stateoscope/graph'
+require 'stateoscope/integrations/aasm'
+
+module Stateoscope
+  module Integrations
+    def self.new_for(klass, state_machine_name)
+      if klass.ancestors.include?(::AASM)
+        ::Stateoscope::Integrations::AASM.new(klass, state_machine_name)
+      else
+        fail NotImplementedError, "unsupported state machine implementation"
+      end
+    end
+  end
+end

lib/stateoscope/integrations/aasm.rb

@@ -0,0 +1,39 @@
+module Stateoscope
+  module Integrations
+    class AASM < Struct.new(:klass, :state_machine_name)
+      def graph
+        graph = Graph.new
+
+        graph.initial_state = state_machine.initial_state.to_s
+
+        state_machine.states.each do |state|
+          graph.add_state(state.name.to_s)
+        end
+
+        state_machine.events.each do |event|
+          event.transitions.each do |transition|
+            graph.add_transition(transition.from.to_s, transition.to.to_s, event.name.to_s)
+          end
+        end
+
+        graph.detect_final_states!
+
+        graph
+      end
+
+      def full_state_machine_name
+        [
+          "aasm",
+          klass.name,
+          state_machine_name
+        ].compact.join('-').dasherize
+      end
+
+      private
+
+      def state_machine
+        klass.public_send(:aasm, state_machine_name.presence)
+      end
+    end
+  end
+end

lib/stateoscope/railtie.rb

@@ -0,0 +1,9 @@
+module Stateoscope
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      Dir.glob File.expand_path('../../tasks/*.rake', __FILE__) do |rake_task|
+        load rake_task
+      end
+    end
+  end
+end

lib/stateoscope/version.rb

@@ -0,0 +1,3 @@
+module Stateoscope
+  VERSION = "0.1.0"
+end

lib/stateoscope/visualizer.rb

@@ -0,0 +1,69 @@
+require 'ruby-graphviz'
+
+module Stateoscope
+  class Visualizer < Struct.new(:graph)
+    def initialize(graph)
+      super
+      parse_graph!
+    end
+
+    def parse_graph!
+      @viz = GraphViz.new(:G, type: 'digraph')
+      add_entry_point
+      add_states
+      add_entry_point_transition
+      add_state_transitions
+    end
+
+    def output(filename)
+      @viz.output(pdf: "#{filename}.pdf")
+    end
+
+    private
+
+    ENTRY_POINT = '__ENTRY_POINT__'
+
+    def filename
+      "#{integration.name}-#{state_machine_name}-#{Time.now.utc.strftime('%Y%m%d%H%M%s')}"
+    end
+
+    def add_entry_point
+      return unless graph.initial_state
+      add_node(ENTRY_POINT, shape: 'circle', label: '', style: 'filled', color: 'black', fixedsize: true, width: 0.3)
+    end
+
+    def add_states
+      graph.states.each do |state|
+        add_node(state, peripheries: graph.final_state?(state) ? 2 : 1)
+      end
+    end
+
+    def add_entry_point_transition
+      return unless graph.initial_state
+      add_edge(ENTRY_POINT, graph.initial_state)
+    end
+
+    def add_state_transitions
+      graph.transitions.each do |transition|
+        add_edge(transition.from, transition.to, transition.event)
+      end
+    end
+
+    def add_node(label, options = {})
+      options.reverse_merge!(shape: 'ellipse')
+      options.reverse_merge!(global_options)
+      @viz.add_nodes(label, options)
+    end
+
+    def add_edge(from, to, label = nil, options = {})
+      options.reverse_merge!(label: label) if label
+      options.reverse_merge!(fontsize: 9, fontcolor: '#888888', labelangle: 45)
+      options.reverse_merge!(global_options)
+      @viz.add_edges(from, to, options)
+    end
+
+    def global_options
+      {fontname: 'Helvetica', fontsize: 10}
+    end
+  end
+end

lib/tasks/stateoscope.rake

@@ -0,0 +1,8 @@
+namespace :stateoscope do
+  desc 'visualize state machine for a given class'
+  task :visualize, [:class, :state_machine_name] => :environment do |t, args|
+    fail ArgumentError 'missing required argument <class>' unless args[:class].present?
+    klass = args[:class].classify.constantize
+    Stateoscope.visualize(klass, state_machine_name: args[:state_machine_name])
+  end
+end

spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'stateoscope'

spec/stateoscope_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe Stateoscope do
+  it 'has a version number' do
+    expect(Stateoscope::VERSION).not_to be nil
+  end
+
+  pending 'does something useful'
+end

stateoscope.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stateoscope/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "stateoscope"
+  spec.version       = Stateoscope::VERSION
+  spec.authors       = ["Patrick Oscity"]
+  spec.email         = ["[email protected]"]
+
+  spec.summary       = %q{State Machine Visualizer}
+  spec.description   = %q{Visualize State Machines using GraphViz}
+  spec.homepage      = "https://github.com/padde/stateoscope"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ruby-graphviz"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end