rumld 0.4.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+VERSION 0.1
+= Initial ideas pertaining to the permission layer

data/README

@@ -0,0 +1 @@
+Ruby UML Diagrammer

data/Rakefile

@@ -0,0 +1,102 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'spec/rake/spectask'
+require 'lib/rumld'
+
+NAME = 'rumld'
+VERS = '0.4.0'
+RDOC_OPTS = ['--all', '--quiet', '--title', 'Ruby UML Diagrammer', '--main', 'README', '--inline-source']
+
+desc "Does a full compile, test run"
+task :default => [:test]
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.options += RDOC_OPTS
+  rdoc.main = "README"
+  rdoc.rdoc_files.add ['README', 'CHANGELOG',  'lib/**/*.rb']
+end
+
+spec =
+Gem::Specification.new do |s|
+  s.name = NAME
+  s.add_dependency('mocha', '>=0.5.2')
+  s.add_dependency('activesupport', '>=1.3.1')
+  s.add_dependency('hpricot', '>=0.6')
+  s.bindir = 'bin'
+  s.executables = ['rumld']
+  
+  s.version = VERS
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.rdoc_options += RDOC_OPTS
+  s.extra_rdoc_files = ["README", "CHANGELOG", "TODO"]
+  s.summary = "A simple UML Grapher for Rails objects"
+  s.description = s.summary
+  s.author = "Jeremy Friesen"
+  s.email = 'jeremyf@lightsky.com'
+  s.homepage = 'http://www.lightsky.com/'
+
+  s.files = %w(README Rakefile CHANGELOG TODO) +
+  Dir.glob("{doc,test,lib,spec,bin}/**/*") +
+
+  s.require_path = ["lib"]
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_tar = true
+  p.gem_spec = spec
+end
+
+desc "Run all the tests"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+
+namespace :doc do
+  desc "Generate documentation for the application"
+  Rake::RDocTask.new("app") { |rdoc|
+    rdoc.rdoc_dir = 'doc/'
+    rdoc.title    = "Rails Application Documentation"
+    rdoc.options << '--line-numbers'
+    rdoc.rdoc_files.include('lib/rumld/**/*.rb')
+  }
+
+  task :graph => :reapp do
+
+    Dir.glob(File.join(File.dirname(__FILE__), 'test', '**', '*.rb')).each do |f|
+      require f
+    end
+    file_list = ARGV.grep(/^FILE(S)=/)
+    files =
+    if file_list.empty?
+      ['*.rb']
+    else
+      file_list.pop.sub(/^FILE(S)=/, '').split(/(,\ )/).collect{|f| "#{f}#{'.rb' unless f.match(/\.rb$/)}"}
+    end
+    doc_folder = (ARGV.grep(/^DOC_DIR=(.*)/).pop.sub(/^DOC_DIR=/, '') rescue File.join(File.dirname(__FILE__), 'doc'))
+
+    source_folder_list = ARGV.grep(/^SOURCE_DIR(S)=/)
+    source_folders =
+    if source_folder_list.empty?
+      [File.join(File.dirname(__FILE__), 'lib' ), File.join(File.dirname(__FILE__), 'app', 'models' )]
+    else
+      source_folder_list.pop.sub(/^SOURCE_DIR(S)=/, '').split(/(,\ )/).collect{|f| "#{f}"}
+    end
+
+    File.open(File.join(File.dirname(__FILE__), 'my_graph.dot'), 'w') do |f|
+      f.puts Rumld::Graph.new( doc_folder, source_folders , files ).to_dot
+    end
+  end
+end

data/TODO

@@ -0,0 +1,16 @@
+✓ Better define how to layout a Module that has methods as well as sub-Modules
+✓ Draw edges for included Modules as Interface
+✓ Draw edges for ActiveRecord::Association
+✓ Subclass edges
+✓ Try to determine polymorphic relations
+✓ Generate a command line interface for rumld
+✓ Need to run the process against a rails project
+✓ Need to switch on whether rumld is running against a rails project
+- Refactor/rethink collection vs. render
+- Convert to RSpec
+- Check for referenced modules inside methods to infer additional relations
+- Exception Nodes should appear differently
+- Research ruby new gem
+
+Bug?
+- Check generator for like named constants in different module spaces (i.e. A::E & B::E)

data/bin/rumld

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + "/../lib"))
+
+class RailsLoader
+  class << self
+    # Prevents Rails application from writing to STDOUT
+    def disable_stdout
+      @old_stdout = STDOUT.dup
+      STDOUT.reopen(PLATFORM =~ /mswin/ ? "NUL" : "/dev/null")
+    end
+
+    # Restore STDOUT
+    def enable_stdout
+      STDOUT.reopen(@old_stdout)
+    end
+
+    def load_environment
+      begin
+        disable_stdout
+        puts 'Loading Rails...'
+        require "config/environment"
+        enable_stdout
+      rescue LoadError
+        enable_stdout
+      end
+    end
+  end
+end
+
+RailsLoader.load_environment
+
+require 'rumld'
+require 'rumld/options_struct'
+RUMLD_DEFAULT_FILES = ['*.rb']
+options = Rumld::OptionsStruct.new
+
+options.parse ARGV
+
+
+grapher = Rumld::Graph.new( options.doc_dir, options.source_dirs , options.files )
+
+
+`rm -rf #{options.doc_dir}`
+
+rdoc = "rdoc --op #{options.doc_dir} #{grapher.files_to_process.join(' ')}"
+`#{rdoc}`
+
+File.open(options.outfile, 'w') do |f|
+  f.puts grapher.to_dot
+end

data/lib/rumld/graph.rb

@@ -0,0 +1,66 @@
+class Rumld::Graph
+  extend Forwardable
+  attr_accessor :files, :doc_dir, :source_dirs
+
+  def initialize(doc_dir, source_dirs = [], files = [])
+    self.doc_dir = doc_dir
+    self.source_dirs = source_dirs
+    self.files = files
+  end
+  def_delegator :tree, :to_dot
+
+  def files_to_process
+    unless @files_to_process
+      @files_to_process  = []
+      source_dirs.each do |dir|
+        files.each { |file| @files_to_process += Dir.glob(File.join(dir, '**', file)) } if files
+      end
+      @files_to_process.uniq!
+      @files_to_process.each{|f| require f}
+    end
+    @files_to_process
+  end
+
+  def tree
+    @tree ||= Rumld::Tree.new(self, defined_constant_names)
+  end
+
+  protected
+
+  # Get a list of constants that RDoc says have been defined
+  def defined_constant_names
+    @defined_constant_names ||=
+    files_to_process.collect do |filename|
+      collect_possible_constant_names(constants_defined(File.readlines(filename))).select do |constant_name|
+        File.exists?(Rumld::RDocInspector.doc_file_for(doc_dir, constant_name))
+      end
+    end.flatten
+  end
+
+
+  # This is a little on the ugly.  Psuedo-combinatorially collect the constants
+  # You'll want to check the tests to see what I mean
+  def collect_possible_constant_names(constant_names = [], prefix = nil)
+    work = []
+    constant_names.each_with_index do |c1, i|
+      constant_name ="#{(prefix + '::') if prefix}#{c1}"
+      work << constant_name
+      work += collect_possible_constant_names(constant_names[(i+1)..-1], constant_name).flatten
+    end
+    work.uniq.sort
+  end
+
+  # This method makes no effort to properly establish the constant hierarchy
+  # It just tries to determine the constants that are being defined
+  def constants_defined(strings = [])
+    constants = strings.grep(/^\W*(class|module)/).collect do |constant|
+      constant.sub(/^\W*(class\W*<<|class|module)/, '').strip.sub(/\W\<.*/, '')
+    end
+
+    # only keeping constants
+    constants.select do |c|
+      c.match(/[A-Z]/)
+    end
+  end
+
+end

data/lib/rumld/node.rb

@@ -0,0 +1,151 @@
+class Rumld::Node
+  extend Forwardable
+  attr_reader :constant_name, :tree, :constant
+
+  def_delegator :tree, :doc_dir
+  def_delegator :rdoc_inspector, :doc_is_for_module?, :constant_is_module?
+  def_delegator :rdoc_inspector, :methods_by_section
+  def_delegator :rdoc_inspector, :doc_file_for
+
+  def initialize(tree, constant_name)
+    @constant_name = constant_name
+    @tree = tree
+  end
+
+  def constant
+    @constant ||= constant_name.constantize
+  end
+
+  def node_to_dot
+    if children?
+      children.sort!{|a,b| a.constant_name <=> b.constant_name}
+      %(subgraph cluster#{detached_constant_name} {
+        label = "#{detached_constant_name}";
+        color = grey;
+        #{self_to_dot(:style=>"dotted")}
+        #{children.collect{|n| n.node_to_dot}.join("\n")}
+      })
+    else
+      self_to_dot
+    end
+  end
+
+  def inheritence_edge_to_dot
+    if constant.respond_to?(:superclass) && ancestor_node = tree.node_for(constant.superclass)
+      %("#{constant_name}" -> "#{ancestor_node.constant_name}" [arrowhead=empty])
+    end
+  end
+
+  def included_associations_to_dot
+    active_record_associations.collect do |assoc|
+      case assoc.macro.to_s
+      when 'belongs_to'               then to_dot_for_belongs_to(assoc)
+      when 'has_one'                  then has_one_to_dot(assoc)
+      when 'has_many'                 then has_many_to_dot(assoc)
+      when 'has_and_belongs_to_many'  then habtm_to_dot(assoc)
+      end
+    end
+  end
+
+  def included_modules_to_dot
+    included_modules.collect do |mod|
+      %("#{constant_name}" -> "#{mod}" [style=dotted, arrowhead=empty])
+    end
+  end
+
+  def self_and_descendants
+    ([self] + children.collect{|n| n.self_and_descendants}).flatten
+  end
+
+  def children
+    @children ||= []
+  end
+
+  def children?
+    !children.empty?
+  end
+
+  def included_modules
+    rdoc_inspector.all_included_modules & tree.constant_names
+  end
+
+  # I only want constants that are one module level
+  # deeper than the current constant_name
+  def should_be_parent_of?(other_constant_name)
+    if match = other_constant_name.match(/^#{Regexp.escape(constant_name + '::')}/)
+      %(#{match}#{other_constant_name.split('::').last}) == other_constant_name
+    else
+      false
+    end
+  end
+
+  protected
+
+  # We can skip this one because, for now its un-needed
+  def to_dot_for_belongs_to(assoc)
+    if assoc.options[:polymorphic]
+      %(
+      "#{assoc.class_name}" [shape = "record"]
+      "#{constant_name}" -> "#{assoc.class_name}" [headlabel="*", taillabel="1"]
+      )
+    else
+      ''
+    end
+  end
+
+  def has_one_to_dot(assoc)
+    if assoc.options[:as]
+      %("#{constant_name}" -> "#{assoc.options[:as].to_s.classify}" [arrowhead=empty, style=dotted, label="by :#{assoc.name}"])
+    elsif tree.constant_names.include?(assoc.class_name)
+      %("#{constant_name}" -> "#{assoc.class_name}" [headlabel="1", taillabel="1"])
+    else
+      ''
+    end
+  end
+
+  def has_many_to_dot(assoc)
+    if assoc.options[:as]
+      %("#{constant_name}" -> "#{assoc.options[:as].to_s.classify}" [arrowhead=empty, style=dotted, label="by :#{assoc.name}"])
+    elsif tree.constant_names.include?(assoc.class_name)
+      %("#{constant_name}" -> "#{assoc.class_name}" [headlabel="1", taillabel="*"])
+    else
+      ''
+    end
+  end
+
+  def habtm_to_dot(assoc)
+    ''
+  end
+
+  def active_record_associations
+    constant.respond_to?(:reflect_on_all_associations) ? constant.reflect_on_all_associations : []
+  end
+
+  def self_to_dot(options = {})
+    default_options = { :shape => "record", :label => "{#{dot_formatted_node_header}||#{format_methods(methods_by_section[:public_class], '.')}#{format_methods(methods_by_section[:public_instance], '#')}}"}
+    options = default_options.merge(options)
+  %("#{constant_name}" [#{options.collect{|key, value| key.to_s + '="' + value.to_s + '"'}.join(', ') }] )
+end
+
+def detached_constant_name
+  constant_name.split('::').last
+end
+
+def rdoc_inspector
+  @rdoc_inspector ||= Rumld::RDocInspector.new( self, constant_name )
+end
+
+# Add a << module >> to the doc if its a Module
+def dot_formatted_node_header
+  "#{'\\<\\< module \\>\\>\\l' if constant_is_module?}#{detached_constant_name}"
+end
+
+def format_methods(methods = [], prefix = '')
+  if (methods && !methods.empty?)
+    methods.collect do |method| 
+      prefix.to_s + method.gsub(/([{}>\|])/){|match| "\\#{match.to_s}"}
+    end.join('\\l') + '\\l'
+  end
+end
+
+end

data/lib/rumld/options_struct.rb

@@ -0,0 +1,59 @@
+require 'ostruct'
+
+module Rumld
+  class OptionsStruct < OpenStruct
+
+    require 'optparse'
+
+    def initialize
+      default_options = { :doc_dir => './doc',
+        :files => RUMLD_DEFAULT_FILES,
+        :outfile => './ruml.dot',
+      :source_dirs => ['./lib', './app/models'] }
+      super(default_options)
+    end
+
+    def parse(args)
+      @opt_parser = OptionParser.new do |opts|
+        opts.banner = "Usage: rumld [options]"
+        opts.separator ""
+        opts.separator "Options:"
+        opts.on("-d", "--doc_dir ./ruml_doc", "Directory to generate rumld's", "working RDoc") do |value|
+          self.doc_dir = value
+        end
+
+        opts.on("-o", "--outfile ruml.dot", "Output file") do |value|
+          self.outfile = value
+        end
+
+        opts.on("-s", "--source_dirs lib,app/models", Array, "Directories for files") do |value|
+          self.source_dirs = value
+        end
+        opts.on("-f", "--files file1[,fileN]", Array, "Files to graph", "defaults to #{RUMLD_DEFAULT_FILES.join(',')}") do |value|
+          self.files = value
+        end
+
+      end
+
+      begin
+        @opt_parser.parse!(args)
+      rescue OptionParser::AmbiguousOption
+        option_error "Ambiguous option"
+      rescue OptionParser::InvalidOption
+        option_error "Invalid option"
+      rescue OptionParser::InvalidArgument
+        option_error "Invalid argument"
+      rescue OptionParser::MissingArgument
+        option_error "Missing argument"
+      end
+    end
+
+    private
+
+    def option_error(msg)
+      STDERR.print "Error: #{msg}\n\n #{@opt_parser}\n"
+      exit 1
+    end
+
+  end
+end

data/lib/rumld/rdoc_inspector.rb

@@ -0,0 +1,70 @@
+class Rumld::RDocInspector
+
+  class << self
+    def doc_file_for(doc_dir, constant_name)
+      File.join(doc_dir, 'classes', "#{constant_name.gsub('::', '/')}.html")
+    end
+  end
+
+  XPATH_TO_METHOD_SECTION_HEADER = '#methods > h3'
+  METHOD_HEADING_TABLE = {'Public Class methods' => :public_class,
+    'Public Instance methods' => :public_instance,
+    'Protected Instance methods' => :protected_instance,
+    'Protected Class methods' => :protected_class
+  }
+  attr_reader :node, :constant_name
+  def initialize(node, constant_name)
+    @node = node
+    @constant_name = constant_name
+  end
+
+  def doc
+    @doc ||= open( doc_file_for ) {|f| Hpricot(f)}
+  end
+
+  def doc_file_for
+    self.class.doc_file_for(node.doc_dir, constant_name)
+  end
+
+  def all_included_modules
+    self.doc.search('#includes #includes-list .include-name').collect{|n| n.inner_text}
+  end
+
+  def doc_is_for_module?
+    if @doc_is_for_module.nil?
+      @doc_is_for_module =  (self.doc.search('#classHeader table.header-table tr td strong')[0].inner_html == 'Module')
+    end
+    @doc_is_for_module
+  end
+
+  # Given an RDoc class.html file, kick back a hash of methods
+  def methods_by_section
+    unless @methods_by_section
+      @methods_by_section = {}
+      (self.doc/XPATH_TO_METHOD_SECTION_HEADER).each do |method_section|
+        if collector_key = METHOD_HEADING_TABLE[method_section.inner_html]
+          @methods_by_section[collector_key] = find_methods_in_section(method_section)
+        end
+      end
+    end
+    @methods_by_section
+  end
+
+  def find_methods_in_section(method_section)
+    collector = []
+    # Oh why did method_section lose the following method?
+    child = method_section.next_sibling
+    while child && !child.css_path.include?(XPATH_TO_METHOD_SECTION_HEADER)
+      # We got to a new section, so drop out of this silly non-sense
+      break if child.css_path.include?(XPATH_TO_METHOD_SECTION_HEADER)
+      (child/'.method-heading a').each do |signature|
+        if string = signature.inner_text.strip.chomp
+          collector << string
+        end
+      end
+      child = child.next_sibling
+    end
+    collector.sort!
+  end
+
+end

data/lib/rumld/tree.rb

@@ -0,0 +1,62 @@
+class Rumld::Tree
+  extend Forwardable
+  def_delegator :graph, :doc_dir
+  attr_reader :constant_names, :graph
+  def initialize( graph, constant_names = [])
+    @graph = graph
+    @constant_names = constant_names.uniq.sort
+    build_nodes
+  end
+  
+  def to_dot
+    %(digraph uml_diagram {\n  graph[rotate=landscape, ratio=fill, overlap=false, splines=true]
+      #{draw_nodes}
+      #{draw_included_modules}
+      #{draw_associations}
+      #{draw_inheritence_edges}
+    }
+    )
+  end
+  
+  def nodes
+    @nodes ||= []
+  end
+  
+  def all_nodes
+    nodes.collect{|n| n.self_and_descendants}.flatten
+  end  
+  
+  def node_for( constant )
+    all_nodes.detect{|node| node.constant == constant || node.constant_name == constant}
+  end
+  
+  protected
+  
+  def draw_inheritence_edges
+    all_nodes.collect{|n| n.inheritence_edge_to_dot}.flatten.join("\n")
+  end
+  
+  def draw_nodes
+    nodes.collect{|n| n.node_to_dot}.flatten.join("\n")
+  end
+  
+  def draw_associations
+    all_nodes.collect{|n| n.included_associations_to_dot}.flatten.join("\n")
+  end
+  
+  def draw_included_modules
+    all_nodes.collect{|n| n.included_modules_to_dot}.flatten.join("\n")
+  end
+  
+  def build_nodes
+    constant_names.each do |constant_name|
+      if node = all_nodes.detect{|node| node.should_be_parent_of?(constant_name)}
+        node.children << Rumld::Node.new(self, constant_name)
+      else
+        nodes << Rumld::Node.new(self, constant_name)
+      end
+    end
+    nodes.sort!{|a,b| a.constant_name <=> b.constant_name}
+  end  
+  
+end

data/lib/rumld.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+gem 'hpricot'
+
+require 'hpricot'
+require 'mocha'
+
+unless defined? RAILS_ENV
+  gem 'activesupport'
+  require 'active_support/core_ext/string'
+end
+
+module Rumld
+end
+
+require File.join(File.dirname(__FILE__), 'rumld','graph')
+require File.join(File.dirname(__FILE__), 'rumld','tree')
+require File.join(File.dirname(__FILE__), 'rumld','node')
+require File.join(File.dirname(__FILE__), 'rumld','rdoc_inspector')

data/spec/rumld_graph_spec.rb

@@ -0,0 +1,43 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+module Rumld
+  describe Graph do
+    before(:each) do
+      @graph = Rumld::Graph.new('', [],[])      
+    end
+    it 'delegates to_dot to tree' do
+      @graph.expects(:tree).returns(stub('Tree', :to_dot => :to_dot))
+      @graph.to_dot.should == :to_dot
+    end
+    
+    it 'collects possible constant names should recursively build a larger constant list' do
+      @graph.send(:collect_possible_constant_names, ['One', 'Two::A', 'Three']).should == ['One', 'One::Two::A', 'One::Two::A::Three', 'Three', 'Two::A', 'Two::A::Three']
+    end
+    
+    it 'collects all of the demodulized constants that are declared' do
+       file = <<-EOV
+       class One
+         class Two::Three < One
+           include Eight
+           extend Nine
+           def function(one)
+           end
+         end
+         module Four
+         end
+         class << self
+         end
+      
+         class << Five
+         end
+       end
+       EOV
+       @graph.send(:constants_defined, file.split("\n")).should == ['One', 'Two::Three', 'Four', 'Five']
+    end
+    
+    it 'uniquely determines all the matching files to process' do
+      @graph = Rumld::Graph.new(nil, [File.dirname(__FILE__),File.dirname(__FILE__)], [File.basename(__FILE__)])
+      @graph.send(:files_to_process).should == [__FILE__]
+    end
+  end
+end