dm-visualizer 0.1.0

data/.gitignore

@@ -0,0 +1,9 @@
+doc
+pkg
+tmp/*
+.DS_Store
+.yardoc
+*.db
+*.log
+*.swp
+*~

data/.specopts

@@ -0,0 +1 @@
+--colour --format specdoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'dm-visualizer Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,9 @@
+### 0.1.0 / 2010-05-27
+
+* Initial release:
+  * Safely loads the models of a project.
+  * Supports using [Gem Bundler](http://gembundler.com/).
+  * Generates GraphViz diagrams for a project.
+    * Provides Rake tasks for both Ruby libraries and Rails3 apps.
+  * Supports both DataMapper 0.10.2 and 1.0.0.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+
+Copyright (c) 2010 Hal Brodigan
+
+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.
+

data/README.md

@@ -0,0 +1,48 @@
+# dm-visualizer
+
+* [github.com/postmodern/dm-visualizer](http://github.com/postmodern/dm-visualizer/)
+* [github.com/postmodern/dm-visualizer/issues](http://github.com/postmodern/dm-visualizer/issues)
+* Postmodern (postmodern.mod3 at gmail.com)
+
+## Description
+
+DataMapper Visualizer is both a library and a command-line utility for
+visualizing the Models, Properties and Relationships defined in a
+DataMapper based Ruby project.
+
+## Features
+
+* Safely loads the models of a project.
+* Supports using [Gem Bundler](http://gembundler.com/).
+* Generates GraphViz diagrams for a project.
+  * Provides Rake tasks for both Ruby libraries and Rails3 apps.
+* Supports both DataMapper 0.10.2 and 1.0.0.
+
+## Examples
+
+Add the `dm:doc:graphviz` rake task to a Ruby library:
+
+    require 'dm-visualizer/rake/graphviz_task'
+    DataMapper::Visualizer::Rake::GraphVizTask.new(
+      :include => ['lib'],
+      :require => ['my_library/models']
+    )
+
+Add the `db:doc:graphviz` rake task to a Rails3 / [dm-rails](http://github.com/datamapper/dm-rails) app:
+
+    require 'dm-visualizer/rake/rails/graphviz_task'
+    DataMapper::Visualizer::Rake::Rails::GraphVizTask.new
+
+## Requirements
+
+* [ruby-graphviz](http://rubygems.org/gems/ruby-graphviz) >= 0.9.10
+* [dm-core](http://github.com/datamapper/dm-core) >= 0.10.2
+
+## Install
+
+    $ sudo gem install dm-visualizer
+
+## License
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'dm-visualizer'
+    gem.license = 'MIT'
+    gem.summary = %Q{Visualizes the Models, Properties and Relationships defined in a DataMapper based Ruby project.}
+    gem.description = %Q{DataMapper Visualizer is both a library and a command-line utility for visualizing the Models, Properties and Relationships defined in a DataMapper based Ruby project.}
+    gem.email = 'postmodern.mod3@gmail.com'
+    gem.homepage = 'http://github.com/postmodern/dm-visualizer'
+    gem.authors = ['Postmodern']
+    gem.add_dependency 'ruby-graphviz', '>= 0.9.10'
+    gem.add_dependency 'dm-core', '>= 0.10.2'
+    gem.add_dependency 'thor', '>= 0.13.4'
+    gem.add_development_dependency 'rspec', '~> 1.3.0'
+    gem.add_development_dependency 'yard', '~> 0.5.3'
+    gem.has_rdoc = 'yard'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs += ['lib', 'spec']
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--options', '.specopts']
+end
+
+task :spec => :check_dependencies
+task :default => :spec
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/dm-visualizer.gemspec

@@ -0,0 +1,100 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dm-visualizer}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Postmodern"]
+  s.date = %q{2010-05-27}
+  s.description = %q{DataMapper Visualizer is both a library and a command-line utility for visualizing the Models, Properties and Relationships defined in a DataMapper based Ruby project.}
+  s.email = %q{postmodern.mod3@gmail.com}
+  s.extra_rdoc_files = [
+    "ChangeLog.md",
+     "LICENSE.txt",
+     "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     ".specopts",
+     ".yardopts",
+     "ChangeLog.md",
+     "LICENSE.txt",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "dm-visualizer.gemspec",
+     "lib/dm-visualizer.rb",
+     "lib/dm-visualizer/graphviz.rb",
+     "lib/dm-visualizer/project.rb",
+     "lib/dm-visualizer/rake/graphviz_task.rb",
+     "lib/dm-visualizer/rake/rails/graphviz_task.rb",
+     "lib/dm-visualizer/rake/rails/tasks.rb",
+     "lib/dm-visualizer/rake/task.rb",
+     "lib/dm-visualizer/visualization.rb",
+     "spec/dm_visualizer_spec.rb",
+     "spec/helpers/project.rb",
+     "spec/helpers/projects/library/lib/blog.rb",
+     "spec/helpers/projects/library/lib/blog/comment.rb",
+     "spec/helpers/projects/library/lib/blog/post.rb",
+     "spec/helpers/projects/library/lib/blog/user.rb",
+     "spec/helpers/projects/rails/app/models/comment.rb",
+     "spec/helpers/projects/rails/app/models/post.rb",
+     "spec/helpers/projects/rails/app/models/user.rb",
+     "spec/project_examples.rb",
+     "spec/project_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/visualization_spec.rb"
+  ]
+  s.has_rdoc = %q{yard}
+  s.homepage = %q{http://github.com/postmodern/dm-visualizer}
+  s.licenses = ["MIT"]
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Visualizes the Models, Properties and Relationships defined in a DataMapper based Ruby project.}
+  s.test_files = [
+    "spec/project_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/visualization_spec.rb",
+     "spec/project_examples.rb",
+     "spec/helpers/project.rb",
+     "spec/helpers/projects/library/lib/blog.rb",
+     "spec/helpers/projects/library/lib/blog/post.rb",
+     "spec/helpers/projects/library/lib/blog/user.rb",
+     "spec/helpers/projects/library/lib/blog/comment.rb",
+     "spec/helpers/projects/rails/app/models/post.rb",
+     "spec/helpers/projects/rails/app/models/user.rb",
+     "spec/helpers/projects/rails/app/models/comment.rb",
+     "spec/dm_visualizer_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ruby-graphviz>, [">= 0.9.10"])
+      s.add_runtime_dependency(%q<dm-core>, [">= 0.10.2"])
+      s.add_runtime_dependency(%q<thor>, [">= 0.13.4"])
+      s.add_development_dependency(%q<rspec>, ["~> 1.3.0"])
+      s.add_development_dependency(%q<yard>, ["~> 0.5.3"])
+    else
+      s.add_dependency(%q<ruby-graphviz>, [">= 0.9.10"])
+      s.add_dependency(%q<dm-core>, [">= 0.10.2"])
+      s.add_dependency(%q<thor>, [">= 0.13.4"])
+      s.add_dependency(%q<rspec>, ["~> 1.3.0"])
+      s.add_dependency(%q<yard>, ["~> 0.5.3"])
+    end
+  else
+    s.add_dependency(%q<ruby-graphviz>, [">= 0.9.10"])
+    s.add_dependency(%q<dm-core>, [">= 0.10.2"])
+    s.add_dependency(%q<thor>, [">= 0.13.4"])
+    s.add_dependency(%q<rspec>, ["~> 1.3.0"])
+    s.add_dependency(%q<yard>, ["~> 0.5.3"])
+  end
+end
+

data/lib/dm-visualizer.rb

@@ -0,0 +1,2 @@
+require 'dm-visualizer/project'
+require 'dm-visualizer/graphviz'

data/lib/dm-visualizer/graphviz.rb

@@ -0,0 +1,168 @@
+require 'dm-visualizer/visualization'
+
+begin
+  require 'graphviz'
+rescue Gem::LoadError => e
+  raise(e)
+rescue ::LoadError
+  STDERR.puts "GraphViz not available. Install it with: gem install ruby-graphviz"
+end
+
+module DataMapper
+  module Visualizer
+    #
+    # Visualizes projects by generating a
+    # [GraphViz](http://www.graphviz.org/) diagram.
+    #
+    class GraphViz < Visualization
+
+      # The output file
+      attr_accessor :file
+
+      # The output file format (`:png`)
+      attr_accessor :format
+
+      # The colors to use
+      attr_reader :colors
+
+      # The labels to use
+      attr_reader :labels
+
+      #
+      # Creates a new GraphViz object.
+      #
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [String] :file
+      #   The output file path.
+      #
+      # @option options [Symbol] :format (:png)
+      #   The format of the generated graph.
+      #
+      # @option options [Hash] :colors
+      #   The colors to use for `:one_to_many` and `:one_to_one`
+      #   relationship edges.
+      #
+      # @option options [Hash] :labels
+      #   The labels to use for `:one_to_many` and `:one_to_one`
+      #   relationship edges.
+      #
+      def initialize(options={})
+        super(options)
+
+        @format = :png
+
+        @colors = {
+          :one_to_many => 'blue',
+          :one_to_one => 'red',
+          :inheritence => 'cyan'
+        }
+        @labels = {
+          :one_to_many => '1:m',
+          :one_to_one => '1:1'
+        }
+
+        if options[:file]
+          @file = File.expand_path(options[:file])
+        end
+
+        if options[:format]
+          @format = options[:format].to_sym
+        end
+
+        if options[:colors]
+          options[:colors].each do |name,value|
+            @colors[name.to_sym] = value.to_s
+          end
+        end
+
+        if options[:labels]
+          options[:labels].each do |name,value|
+            @labels[name.to_sym] = value.to_s
+          end
+        end
+      end
+
+      #
+      # The full output path.
+      #
+      # @return [String]
+      #   The full output path, including file extension.
+      #
+      def path
+        "#{@file}.#{@format}"
+      end
+
+      protected
+
+      #
+      # Generates a GraphViz diagram for a project.
+      #
+      # @param [String] path
+      #   The path to save the graph image to.
+      #
+      def visualize
+        graph = ::GraphViz.new(:G, :type => :digraph)
+
+        # Create node for each model
+        project.each_model do |model|
+          properties = project.each_property(model).map do |property|
+            "#{property_name(property)}: #{property_type_name(property)}"
+          end
+
+          foreign_keys = project.each_foreign_key(model).map do |key,model|
+            "#{foreign_key_name(key)}: #{model_name(model)}"
+          end
+
+          columns = (properties + foreign_keys)
+          label = "{ #{model_name(model)} | #{columns.join("\n")} }"
+
+          graph.add_node(
+            model_name(model),
+            :shape => 'record',
+            :label => label
+          )
+        end
+
+        # Connect model nodes together by relationship
+        project.each_relationship do |relationship,model|
+          source_node = graph.get_node(model_name(model))
+          target_node = graph.get_node(model_name(relationship.target_model))
+
+          case relationship
+          when DataMapper::Associations::OneToMany::Relationship
+            graph.add_edge(
+              source_node,
+              target_node,
+              :color => @colors[:one_to_many],
+              :label => " #{@labels[:one_to_many]}"
+            )
+          when DataMapper::Associations::OneToOne::Relationship
+            graph.add_edge(
+              source_node,
+              target_node,
+              :color => @colors[:one_to_one],
+              :label => " #{@labels[:one_to_one]}"
+            )
+          end
+        end
+
+        # Connect model nodes by inheritence
+        project.each_model_inheritence do |model,ancestor|
+          source_node = graph.get_node(model_name(ancestor))
+          target_node = graph.get_node(model_name(model))
+
+          graph.add_edge(
+            source_node,
+            target_node,
+            :color => @colors[:inheritence]
+          )
+        end
+
+        graph.output(@format => self.path)
+      end
+
+    end
+  end
+end

data/lib/dm-visualizer/project.rb

@@ -0,0 +1,315 @@
+require 'set'
+require 'dm-core'
+
+require 'enumerator'
+
+module DataMapper
+  module Visualizer
+    #
+    # Defines the paths and directories to load for a DataMapper project.
+    #
+    class Project
+
+      # Specifies which Bundler groups to activate.
+      attr_reader :bundle
+
+      # The directories to include
+      attr_reader :include_dirs
+
+      # The paths to require
+      attr_reader :require_paths
+
+      # The path glob patterns to require
+      attr_reader :require_globs
+
+      #
+      # Creates a new project.
+      #
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [Array] :include
+      #   The directories to include into the `$LOAD_PATH` global variable.
+      #
+      # @option options [Boolean, Array] :bundle
+      #   Specifies which groups of dependencies to activate using Bundler.
+      #
+      # @option options [Array] :require
+      #   The paths to require.
+      #
+      # @option options [Array] :require_all
+      #   The path globs to require.
+      #
+      def initialize(options={})
+        @bundle = nil
+        @include_dirs = Set[]
+        @require_paths = Set[]
+        @require_globs = Set[]
+
+        if options[:include]
+          options[:include].each do |dir|
+            @include_dirs << File.expand_path(dir)
+          end
+        end
+
+        if options[:bundle]
+          @bundle = Set[]
+
+          options[:bundle].each do |group|
+            @bundle << group.to_sym
+          end
+        end
+
+        if options[:require]
+          @require_paths += options[:require]
+        end
+
+        if options[:require_all]
+          @require_globs += options[:require_all]
+        end
+      end
+
+      #
+      # Activates dependencies of the project using Bundler.
+      #
+      # @return [true]
+      #
+      def bundle!
+        unless File.file?('Gemfile')
+          log "Gemfile is missing or not a valid file."
+        end
+
+        begin
+          require 'bundler'
+        rescue LoadError => e
+          log "Gemfile exists, but bundler is not installed"
+          log "Run `gem install bundler` to install bundler."
+        end
+
+        begin
+          Bundler.setup(*@bundle)
+        rescue Bundler::BundleError => e
+          log e.message
+          log "Run `bundle install` to install missing gems"
+        end
+
+        return true
+      end
+
+      #
+      # Activates the project by adding it's include directories to the
+      # `$LOAD_PATH` global variable.
+      #
+      # @return [true]
+      #
+      def activate!
+        @include_dirs.each do |dir|
+          $LOAD_PATH << dir if File.directory?(dir)
+        end
+
+        # use Bundler if a Gemfile is present
+        bundle! if (@bundle && File.file?('Gemfile'))
+
+        return true
+      end
+
+      #
+      # De-activates the project by removing it's include directories to the
+      # `$LOAD_PATH` global variable.
+      #
+      # @return [true]
+      #
+      def deactivate!
+        $LOAD_PATH.reject! { |dir| @include_dirs.include?(dir) }
+        return true
+      end
+
+      #
+      # Attempts to load all of the projects files.
+      #
+      # @return [true]
+      #
+      def load!
+        activate!
+
+        @require_paths.each do |path|
+          begin
+            require path
+          rescue LoadError => e
+            log "dm-visualizer: unable to load #{path}"
+            log "dm-visualizer: #{e.message}"
+          end
+        end
+
+        @require_globs.each do |glob|
+          @include_dirs.each do |dir|
+            Dir[File.join(dir,glob)].each do |path|
+              relative_path = path[(dir.length + 1)..-1]
+
+              begin
+                require relative_path
+              rescue LoadError => e
+                log "dm-visualizer: unable to load #{relative_path} from #{dir}"
+                log "dm-visualizer: #{e.message}"
+              end
+            end
+          end
+        end
+
+        deactivate!
+        return true
+      end
+
+      #
+      # Enumerates over each DataMapper Model loaded from the project.
+      #
+      # @yield [model]
+      #   The given block will be passed every model registered with
+      #   DataMapper.
+      #
+      # @yieldparam [DataMapper::Model]
+      #   A model loaded from the project.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each_model(&block)
+        DataMapper::Model.descendants.each(&block)
+      end
+
+      #
+      # Enumerates over each DataMapper Model loaded from the project,
+      # and their direct ancestors.
+      #
+      # @yield [model, direct_ancestor]
+      #   The given block will be passed every model and their immediate
+      #   ancestor.
+      #
+      # @yieldparam [DataMapper::Model] model
+      #   The model.
+      #
+      # @yieldparam [DataMapper::Model] direct_ancestor
+      #   The first ancestor of the model.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each_model_inheritence
+        unless block_given?
+          return Enumerator.new(self,:each_model_inheritence)
+        end
+
+        each_model do |model|
+          direct_ancestor = model.ancestors[1]
+
+          if direct_ancestor.class == Class
+            yield model, direct_ancestor
+          end
+        end
+      end
+
+      #
+      # Enumerates over each DataMapper property from a given model.
+      #
+      # @param [DataMapper::Model] model
+      #   The given model.
+      #
+      # @yield [property]
+      #   The given block will be passed every property from the given
+      #   model.
+      #
+      # @yieldparam [DataMapper::Property] property
+      #   The property.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each_property(model)
+        unless block_given?
+          return Enumerator.new(self,:each_property,model)
+        end
+
+        model.properties.each do |property|
+          yield property
+        end
+      end
+
+      #
+      # Enumerates over every foreign-key in a given model.
+      #
+      # @param [DataMapper::Model] model
+      #   The given model.
+      #
+      # @yield [foreign_key, foreign_model]
+      #   The given block will be passed every foreign-key and the model
+      #   that the foreign-key will reference.
+      #
+      # @yieldparam [String] foreign_key
+      #   The name of the foreign-key.
+      #
+      # @yieldparam [DataMapper::Model] foreign_model
+      #   The model that the foreign-key references.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each_foreign_key(model)
+        unless block_given?
+          return Enumerator.new(self,:each_foreign_key,model)
+        end
+
+        model.relationships.each_value do |relationship|
+          next if relationship.respond_to?(:through)
+
+          case relationship
+          when Associations::ManyToOne::Relationship,
+               Associations::OneToOne::Relationship
+            yield relationship.child_key.first.name,
+                  relationship.parent_model
+          end
+        end
+      end
+
+      #
+      # Enumerates over each DataMapper relationship between each model.
+      #
+      # @yield [relationship,model]
+      #   The given block will be passed every relationship from every
+      #   model registered with DataMapper.
+      #
+      # @yieldparam [DataMapper::Relationship] relationship
+      #   The relationship.
+      #
+      # @yieldparam [DataMapper::Model] model
+      #   The model that the relationship belongs to.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each_relationship
+        return Enumerator.new(self,:each_relationship) unless block_given?
+
+        each_model do |model|
+          model.relationships.each_value do |relationship|
+            unless relationship.respond_to?(:through)
+              yield relationship, model
+            end
+          end
+        end
+      end
+
+      protected
+
+      #
+      # Prints a message to `STDERR`.
+      #
+      # @param [String] message
+      #   The message to print.
+      #
+      def log(message)
+        STDERR.puts "dm-visualizer: #{message}"
+      end
+
+    end
+  end
+end