rails-erd 0.1.0

data/lib/rails_erd/railtie.rb

@@ -0,0 +1,7 @@
+module RailsERD
+  class Railtie < Rails::Railtie #:nodoc:
+    rake_tasks do
+      load "rails_erd/tasks.rake"
+    end
+  end
+end

data/lib/rails_erd/relationship.rb

@@ -0,0 +1,85 @@
+module RailsERD
+  class Relationship
+    class << self
+      def from_associations(domain, associations) #:nodoc:
+        assoc_groups = associations.group_by { |assoc| association_identity(assoc) }
+        assoc_groups.collect { |_, assoc_group| Relationship.new(domain, assoc_group.to_a) }
+      end
+      
+      private
+      
+      def association_identity(assoc)
+        identifier = assoc.options[:join_table] || assoc.primary_key_name.to_s
+        Set[identifier, assoc.active_record, assoc.klass]
+      end
+    end
+
+    # Returns the domain in which this relationship is defined.
+    attr_reader :domain
+
+    # Returns the source entity. The source entity corresponds to the model
+    # that has defined a +has_one+ or +has_many+ association with the other
+    # model.
+    attr_reader :source
+    
+    # Returns the destination entity. The destination entity corresponds to the
+    # model that has defined a +belongs_to+ association with the other model.
+    attr_reader :destination
+  
+    def initialize(domain, associations) #:nodoc:
+      @domain = domain
+      @reverse_associations, @forward_associations = *associations.partition(&:belongs_to?)
+    
+      assoc = @forward_associations.first || @reverse_associations.first
+      @source, @destination = @domain.entity_for(assoc.active_record), @domain.entity_for(assoc.klass)
+      @source, @destination = @destination, @source if assoc.belongs_to?
+    end
+    
+    # Returns all +ActiveRecord+ association objects that describe this
+    # relationship.
+    def associations
+      @forward_associations + @reverse_associations
+    end
+    
+    # Returns the cardinality of this relationship. The cardinality may be
+    # one of Cardinality::OneToOne, Cardinality::OneToMany, or
+    # Cardinality::ManyToMany.
+    def cardinality
+      @forward_associations.collect { |assoc| Cardinality.from_macro(assoc.macro) }.max or Cardinality::OneToMany
+    end
+    
+    # Indicates if a relationship is indirect, that is, if it is defined
+    # through other relationships. Indirect relationships are created in
+    # Rails with <tt>has_many :through</tt> or <tt>has_one :through</tt>
+    # association macros.
+    def indirect?
+      @forward_associations.all?(&:through_reflection)
+    end
+    
+    # Indicates whether or not the relationship is defined by two inverse
+    # associations (e.g. a +has_many+ and a corresponding +belongs_to+
+    # association).
+    def mutual?
+      @forward_associations.any? and @reverse_associations.any?
+    end
+    
+    # Indicates whether or not this relationship connects an entity with itself.
+    def recursive?
+      @source == @destination
+    end
+    
+    # The strength of a relationship is equal to the number of associations
+    # that describe it.
+    def strength
+      associations.size
+    end
+
+    def inspect #:nodoc:
+      "#<#{self.class}:0x%.14x @source=#{source} @destination=#{destination}>" % (object_id << 1)
+    end
+  
+    def <=>(other) #:nodoc:
+      (source.name <=> other.source.name).nonzero? or (destination.name <=> other.destination.name)
+    end
+  end
+end

data/lib/rails_erd/relationship/cardinality.rb

@@ -0,0 +1,35 @@
+module RailsERD
+  class Relationship
+    class Cardinality
+      CARDINALITY_NAMES = %w{one_to_one one_to_many many_to_many} #:nodoc:
+      ORDER = {} #:nodoc:
+
+      class << self
+        attr_reader :type
+
+        def from_macro(macro) #:nodoc:
+          case macro
+          when :has_and_belongs_to_many then ManyToMany
+          when :has_many then OneToMany
+          when :has_one then OneToOne
+          end
+        end
+        
+        def <=>(other) #:nodoc:
+          ORDER[self] <=> ORDER[other]
+        end
+        
+        CARDINALITY_NAMES.each do |cardinality|
+          define_method :"#{cardinality}?" do
+            type == cardinality
+          end
+        end
+      end
+      
+      CARDINALITY_NAMES.each_with_index do |cardinality, i|
+        klass = Cardinality.const_set cardinality.camelize.to_sym, Class.new(Cardinality) { @@type = cardinality }
+        ORDER[klass] = i
+      end
+    end
+  end
+end

data/lib/rails_erd/tasks.rake

@@ -0,0 +1,38 @@
+def say(message)
+  puts message unless Rake.application.options.silent
+end
+
+namespace :erd do
+  task :options do
+    (RailsERD.options.keys.map(&:to_s) & ENV.keys).each do |option|
+      RailsERD.options[option.to_sym] = case ENV[option]
+      when "true" then true
+      when "false" then false
+      else ENV[option].to_sym
+      end
+    end
+  end
+  
+  task :load_models do
+    say "Loading ActiveRecord models..."
+
+    Rake::Task[:environment].invoke
+    Rails.application.config.paths.app.models.paths.each do |model_path|
+      Dir["#{model_path}/**/*.rb"].sort.each do |file|
+        require_dependency file
+      end
+    end
+  end
+  
+  task :generate => [:options, :load_models] do
+    say "Generating ERD diagram..."
+
+    require "rails_erd/diagram"
+    diagram = RailsERD::Diagram.generate
+
+    say "Done! Saved diagram to #{diagram.file_name}."
+  end
+end
+
+desc "Generate an Entity-Relationship Diagram based on your models"
+task :erd => "erd:generate"

data/lib/rails_erd/templates/node.erb

@@ -0,0 +1,13 @@
+<% if vertical? %>{<% end %>
+<table border="0" align="center" cellspacing="0.5" cellpadding="0" width="<%= NODE_WIDTH + 4 %>">
+  <tr><td align="center" valign="bottom" width="<%= NODE_WIDTH %>"><font face="Arial Bold" point-size="11"><%= entity.name %></font></td></tr>
+</table>|<% if attributes.any? %>
+  <table border="0" align="left" cellspacing="2" cellpadding="0" width="<%= NODE_WIDTH + 4 %>">
+    <% attributes.each do |attribute| %>
+      <tr>
+        <td align="left" width="<%= NODE_WIDTH %>" port="<%= attribute %>"><%= attribute %> <font face="Arial Italic" color="grey60"><%= attribute.type_description %></font></td>
+      </tr>
+    <% end %>
+  </table>
+<% end %>
+<% if vertical? %>}<% end %>

data/test/test_helper.rb

@@ -0,0 +1,72 @@
+require "test/unit"
+require "active_support/test_case"
+
+require "rails_erd/domain"
+
+require "rails"
+require "active_record"
+
+ActiveRecord::Base.establish_connection :adapter => "sqlite3", :database => ":memory:"
+
+include RailsERD
+
+class ActiveSupport::TestCase
+  teardown :reset_domain
+
+  def create_table(table, columns = {}, pk = nil)
+    opts = if pk then { :primary_key => pk } else { :id => false } end
+    ActiveRecord::Schema.define do
+      suppress_messages do
+        create_table table, opts do |t|
+          columns.each do |column, type|
+            t.send type, column
+          end
+        end
+      end
+    end
+  end
+  
+  def add_column(*args)
+    ActiveRecord::Schema.define do
+      suppress_messages do
+        add_column *args
+      end
+    end
+  end
+
+  def create_model(name, columns = {}, &block)
+    klass = Object.const_set name.to_sym, Class.new(ActiveRecord::Base)
+    klass.class_eval(&block) if block_given?
+    create_table Object.const_get(name.to_sym).table_name, columns, Object.const_get(name.to_sym).primary_key rescue nil
+  end
+    
+  def create_models(*names)
+    names.each do |name|
+      create_model name
+    end
+  end
+  
+  def collect_stdout
+    stdout = $stdout
+    $stdout = StringIO.new
+    yield
+    $stdout.rewind
+    $stdout.read
+  ensure
+    $stdout = stdout
+  end
+  
+  private
+  
+  def reset_domain
+    ActiveRecord::Base.descendants.each do |model|
+      Object.send :remove_const, model.name.to_sym
+    end
+    ActiveRecord::Base.connection.tables.each do |table|
+      ActiveRecord::Base.connection.drop_table table
+    end
+    ActiveRecord::Base.direct_descendants.clear
+    Arel::Relation.class_variable_set :@@connection_tables_primary_keys, {}
+    ActiveSupport::Dependencies::Reference.clear!
+  end
+end

data/test/unit/attribute_test.rb

@@ -0,0 +1,144 @@
+# encoding: utf-8
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+
+class AttributeTest < ActiveSupport::TestCase
+  def with_native_limit(type, new_limit)
+    ActiveRecord::Base.connection.class_eval do
+      define_method :native_database_types do
+        super().tap do |types|
+          types[type][:limit] = new_limit
+        end
+      end
+    end
+    yield
+  ensure
+    ActiveRecord::Base.connection.class_eval do
+      define_method :native_database_types do
+        super()
+      end
+    end
+  end
+  
+  def create_attribute(model, name)
+    Attribute.new(Domain.generate, model, model.arel_table.attributes[name].column)
+  end
+  
+  # Attribute ================================================================
+  test "column should return database column" do
+    create_model "Foo", :my_column => :string
+    assert_equal Foo.arel_table.attributes["my_column"].column,
+      Attribute.from_model(Domain.new, Foo).reject(&:primary_key?).first.column
+  end
+  
+  test "spaceship should sort attributes by name" do
+    create_model "Foo", :a => :string, :b => :string, :c => :string
+    a = Attribute.new(Domain.new, Foo, Foo.arel_table.attributes["a"].column)
+    b = Attribute.new(Domain.new, Foo, Foo.arel_table.attributes["b"].column)
+    c = Attribute.new(Domain.new, Foo, Foo.arel_table.attributes["c"].column)
+    assert_equal [a, b, c], [c, a, b].sort
+  end
+  
+  test "inspect should show column" do
+    create_model "Foo", :my_column => :string
+    assert_match %r{#<RailsERD::Attribute:.* @column="my_column" @type=:string>},
+      Attribute.new(Domain.new, Foo, Foo.arel_table.attributes["my_column"].column).inspect
+  end
+  
+  test "type should return attribute type" do
+    create_model "Foo", :a => :binary
+    assert_equal :binary, create_attribute(Foo, "a").type
+  end
+  
+  # Attribute properties =====================================================
+  test "mandatory should return false by default" do
+    create_model "Foo", :column => :string
+    assert_equal false, create_attribute(Foo, "column").mandatory?
+  end
+
+  test "mandatory should return true if attribute has a presence validator" do
+    create_model "Foo", :column => :string do
+      validates :column, :presence => true
+    end
+    assert_equal true, create_attribute(Foo, "column").mandatory?
+  end
+
+  test "mandatory should return true if attribute has a not null constraint" do
+    create_model "Foo"
+    add_column :foos, :column, :string, :null => false, :default => ""
+    assert_equal true, create_attribute(Foo, "column").mandatory?
+  end
+
+  test "primary_key should return false by default" do
+    create_model "Bar", :my_key => :integer
+    assert_equal false, create_attribute(Bar, "my_key").primary_key?
+  end
+
+  test "primary_key should return true if column is used as primary key" do
+    create_model "Bar", :my_key => :integer do
+      set_primary_key :my_key
+    end
+    assert_equal true, create_attribute(Bar, "my_key").primary_key?
+  end
+
+  test "foreign_key should return false by default" do
+    create_model "Foo", :bar => :references
+    assert_equal false, create_attribute(Foo, "bar_id").foreign_key?
+  end
+
+  test "foreign_key should return true if it is used in an association" do
+    create_model "Foo", :bar => :references do
+      belongs_to :bar
+    end
+    create_model "Bar"
+    assert_equal true, create_attribute(Foo, "bar_id").foreign_key?
+  end
+
+  test "foreign_key should return true if it is used in a remote association" do
+    create_model "Foo", :bar => :references
+    create_model "Bar" do
+      has_many :foos
+    end
+    assert_equal true, create_attribute(Foo, "bar_id").foreign_key?
+  end
+
+  test "timestamp should return false by default" do
+    create_model "Foo", :created => :datetime
+    assert_equal false, create_attribute(Foo, "created").timestamp?
+  end
+
+  test "timestamp should return true if it is named created_at/on or updated_at/on" do
+    create_model "Foo", :created_at => :string, :updated_at => :string, :created_on => :string, :updated_on => :string
+    assert_equal [true] * 4, [create_attribute(Foo, "created_at"), create_attribute(Foo, "updated_at"),
+      create_attribute(Foo, "created_on"), create_attribute(Foo, "updated_on")].collect(&:timestamp?)
+  end
+  
+  # Type descriptions ========================================================
+  test "type_description should return short type description" do
+    create_model "Foo", :a => :binary
+    assert_equal "blob", create_attribute(Foo, "a").type_description
+  end
+
+  test "type_description should return short type description without limit if standard" do
+    with_native_limit :string, 456 do
+      create_model "Foo"
+      add_column :foos, :my_str, :string, :limit => 255
+      ActiveRecord::Base.connection.native_database_types[:string]
+      assert_equal "str (255)", create_attribute(Foo, "my_str").type_description
+    end
+  end
+
+  test "type_description should return short type description with limit if nonstandard" do
+    with_native_limit :string, 456 do
+      create_model "Foo"
+      add_column :foos, :my_str, :string, :limit => 456
+      assert_equal "str", create_attribute(Foo, "my_str").type_description
+    end
+  end
+  
+  test "type_description should append hair space and low asterisk if field is mandatory" do
+    create_model "Foo", :a => :integer do
+      validates_presence_of :a
+    end
+    assert_equal "int ∗", create_attribute(Foo, "a").type_description
+  end
+end

data/test/unit/cardinality_test.rb

@@ -0,0 +1,8 @@
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+
+class CardinalityTest < ActiveSupport::TestCase
+  test "cardinalities should be sorted in order of maniness" do
+    assert_equal [Relationship::Cardinality::OneToOne, Relationship::Cardinality::OneToMany, Relationship::Cardinality::ManyToMany],
+      [Relationship::Cardinality::OneToMany, Relationship::Cardinality::ManyToMany, Relationship::Cardinality::OneToOne].sort
+  end
+end

data/test/unit/domain_test.rb

@@ -0,0 +1,125 @@
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+
+class DomainTest < ActiveSupport::TestCase
+  # Domain ===================================================================
+  test "generate should return domain" do
+    assert_kind_of Domain, Domain.generate
+  end
+  
+  test "name should return rails application name" do
+    Object::Quux = Module.new
+    Object::Quux::Application = Class.new Rails::Application
+    assert_equal "Quux", Domain.generate.name
+  end
+  
+  test "name should return nil outside rails" do
+    assert_nil Domain.generate.name
+  end
+  
+  # Entity processing ========================================================
+  test "entity_for should return associated entity for given model" do
+    create_model "Foo"
+    assert_equal Foo, Domain.generate.entity_for(Foo).model
+  end
+  
+  test "entities should return domain entities" do
+    create_models "Foo", "Bar"
+    assert_equal [Entity] * 2, Domain.generate.entities.collect(&:class)
+  end
+  
+  test "entities should return all domain entities sorted by name" do
+    create_models "Foo", "Bar", "Baz", "Qux"
+    assert_equal [Bar, Baz, Foo, Qux], Domain.generate.entities.collect(&:model)
+  end
+  
+  # Relationship processing ==================================================
+  test "relationships should return empty array for empty domain" do
+    assert_equal [], Domain.generate.relationships
+  end
+  
+  test "relationships should return relationships in domain model" do
+    create_models "Baz", "Qux"
+    create_model "Foo", :bar => :references, :qux => :references do
+      belongs_to :bar
+      belongs_to :qux
+    end
+    create_model "Bar", :baz => :references do
+      belongs_to :baz
+    end
+    assert_equal [Relationship] * 3, Domain.generate.relationships.collect(&:class)
+  end
+  
+  test "relationships should count mutual relationship as one" do
+    create_model "Foo", :bar => :references do
+      belongs_to :bar
+    end
+    create_model "Bar" do
+      has_many :foos
+    end
+    assert_equal [Relationship], Domain.generate.relationships.collect(&:class)
+  end
+  
+  test "relationships should count relationship between same models with distinct foreign key seperately" do
+    create_model "Foo", :bar => :references, :special_bar => :references do
+      belongs_to :bar
+    end
+    create_model "Bar" do
+      has_many :foos, :foreign_key => :special_bar_id
+    end
+    assert_equal [Relationship] * 2, Domain.generate.relationships.collect(&:class)
+  end
+  
+  # Erroneous associations ===================================================
+  test "relationships should omit bad has_many associations" do
+    create_model "Foo" do
+      has_many :flabs
+    end
+    assert_equal [], Domain.generate(:suppress_warnings => true).relationships
+  end
+  
+  test "relationships should omit bad has_many through association" do
+    create_model "Foo" do
+      has_many :flabs, :through => :bars
+    end
+    assert_equal [], Domain.generate(:suppress_warnings => true).relationships
+  end
+  
+  test "relationships should omit association to model outside domain" do
+    create_model "Foo" do
+      has_many :bars
+    end
+    create_model "Bar", :foo => :references
+    assert_equal [], Domain.new([Foo], :suppress_warnings => true).relationships
+  end
+
+  test "relationships should output a warning when a bad association is encountered" do
+    create_model "Foo" do
+      has_many :flabs
+    end
+    output = collect_stdout do
+      Domain.generate.relationships
+    end
+    assert_match /Invalid association :flabs on Foo/, output
+  end
+
+  test "relationships should output a warning when an association to model outside domain is encountered" do
+    create_model "Foo" do
+      has_many :bars
+    end
+    create_model "Bar", :foo => :references
+    output = collect_stdout do
+      Domain.new([Foo]).relationships
+    end
+    assert_match /model Bar exists, but is not included in the domain/, output
+  end
+
+  test "relationships should suppress warnings when a bad association is encountered if warning suppression is enabled" do
+    create_model "Foo" do
+      has_many :flabs
+    end
+    output = collect_stdout do
+      Domain.generate(:suppress_warnings => true).relationships
+    end
+    assert_equal "", output
+  end
+end