rails-erd 0.3.0 → 0.4.0

data/lib/rails_erd/domain/entity.rb

@@ -0,0 +1,102 @@
+module RailsERD
+  class Domain
+    # Entities represent your Active Record models. Entities may be connected
+    # to other entities.
+    class Entity
+      class << self
+        def from_models(domain, models) # @private :nodoc:
+          (concrete_from_models(domain, models) + abstract_from_models(domain, models)).sort
+        end
+        
+        private
+        
+        def concrete_from_models(domain, models)
+          models.collect { |model| new(domain, model.name, model) }
+        end
+        
+        def abstract_from_models(domain, models)
+          models.collect(&:reflect_on_all_associations).flatten.collect { |association|
+            association.options[:as].to_s.classify if association.options[:as]
+          }.flatten.compact.uniq.collect { |name| new(domain, name) }
+        end
+      end
+      
+      extend Inspectable
+      inspection_attributes :model
+    
+      # The domain in which this entity resides.
+      attr_reader :domain
+    
+      # The Active Record model that this entity corresponds to.
+      attr_reader :model
+      
+      # The name of this entity. Equal to the class name of the corersponding
+      # model (for concrete entities) or given name (for abstract entities).
+      attr_reader :name
+
+      def initialize(domain, name, model = nil) # @private :nodoc:
+        @domain, @name, @model = domain, name, model
+      end
+    
+      # Returns an array of attributes for this entity.
+      def attributes
+        @attributes ||= if generalized? then [] else Attribute.from_model(domain, model) end
+      end
+    
+      # Returns an array of all relationships that this entity has with other
+      # entities in the domain model.
+      def relationships
+        domain.relationships_by_entity_name(name)
+      end
+
+      # Returns +true+ if this entity has any relationships with other models,
+      # +false+ otherwise.
+      def connected?
+        relationships.any?
+      end
+
+      # Returns +true+ if this entity has no relationships with any other models,
+      # +false+ otherwise. Opposite of +connected?+.
+      def disconnected?
+        relationships.none?
+      end
+      
+      # Returns +true+ if this entity is a generalization, which does not
+      # correspond with a database table. Generalized entities are constructed
+      # from polymorphic interfaces. Any +has_one+ or +has_many+ association
+      # that defines a polymorphic interface with <tt>:as => :name</tt> will
+      # lead to a generalized entity to be created.
+      def generalized?
+        !model
+      end
+    
+      # Returns +true+ if this entity descends from another entity, and is
+      # represented in the same table as its parent. In Rails this concept is
+      # referred to as single-table inheritance. In entity-relationship
+      # diagrams it is called specialization.
+      def specialized?
+        !generalized? and !model.descends_from_active_record?
+      end
+      
+      # Returns +true+ if this entity does not correspond directly with a
+      # database table (if and only if the entity is specialized or
+      # generalized).
+      def abstract?
+        specialized? or generalized?
+      end
+      
+      # Returns all child entities, if this is a generalized entity.
+      def children
+        @children ||= domain.specializations_by_entity_name(name).map(&:specialized)
+      end
+  
+      def to_s # @private :nodoc:
+        name
+      end
+  
+      def <=>(other) # @private :nodoc:
+        self.name <=> other.name
+      end
+    end
+  end
+end

data/lib/rails_erd/domain/relationship.rb

@@ -0,0 +1,189 @@
+require "set"
+require "active_support/core_ext/module/delegation"
+require "rails_erd/domain/relationship/cardinality"
+
+module RailsERD
+  class Domain
+    # Describes a relationship between two entities. A relationship is detected
+    # based on Active Record associations. One relationship may represent more
+    # than one association, however. Related associations are grouped together.
+    # Associations are related if they share the same foreign key, or the same
+    # join table in the case of many-to-many associations.
+    class Relationship
+      N = Cardinality::N
+    
+      class << self
+        def from_associations(domain, associations) # @private :nodoc:
+          assoc_groups = associations.group_by { |assoc| association_identity(assoc) }
+          assoc_groups.collect { |_, assoc_group| new(domain, assoc_group.to_a) }
+        end
+      
+        private
+      
+        def association_identity(association)
+          identifier = association.options[:join_table] || association.options[:through] || association.primary_key_name.to_s
+          Set[identifier, association_owner(association), association_target(association)]
+        end
+        
+        def association_owner(association)
+          association.options[:as] ? association.options[:as].to_s.classify : association.active_record.name
+        end
+        
+        def association_target(association)
+          association.class_name
+        end
+      end
+      
+      extend Inspectable
+      inspection_attributes :source, :destination
+
+      # The domain in which this relationship is defined.
+      attr_reader :domain
+
+      # The source entity. It corresponds to the model that has defined a
+      # +has_one+ or +has_many+ association with the other model.
+      attr_reader :source
+    
+      # The destination entity. It corresponds to the model that has defined
+      # a +belongs_to+ association with the other model.
+      attr_reader :destination
+    
+      delegate :one_to_one?, :one_to_many?, :many_to_many?, :source_optional?,
+        :destination_optional?, :to => :cardinality
+  
+      def initialize(domain, associations) # @private :nodoc:
+        @domain = domain
+        @reverse_associations, @forward_associations = *unless any_habtm?(associations)
+          associations.partition(&:belongs_to?)
+        else
+          # Many-to-many associations don't have a clearly defined direction.
+          # We sort by name and use the first model as the source.
+          source = associations.first.active_record
+          associations.partition { |association| association.active_record == source }
+        end
+      
+        assoc = @forward_associations.first || @reverse_associations.first
+        @source = @domain.entity_by_name(self.class.send(:association_owner, assoc))
+        @destination = @domain.entity_by_name(self.class.send(:association_target, assoc))
+        @source, @destination = @destination, @source if assoc.belongs_to?
+      end
+    
+      # Returns all Active Record association objects that describe this
+      # relationship.
+      def associations
+        @forward_associations + @reverse_associations
+      end
+    
+      # Returns the cardinality of this relationship.
+      def cardinality
+        @cardinality ||= begin
+          reverse_max = any_habtm?(associations) ? N : 1
+          forward_range = associations_range(@forward_associations, N)
+          reverse_range = associations_range(@reverse_associations, reverse_max)
+          Cardinality.new(reverse_range, forward_range)
+        end
+      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.empty? and @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
+    
+      # Indicates whether the destination cardinality class of this relationship
+      # is equal to one. This is +true+ for one-to-one relationships only.
+      def to_one?
+        cardinality.cardinality_class[1] == 1
+      end
+    
+      # Indicates whether the destination cardinality class of this relationship
+      # is equal to infinity. This is +true+ for one-to-many or
+      # many-to-many relationships only.
+      def to_many?
+        cardinality.cardinality_class[1] != 1
+      end
+    
+      # Indicates whether the source cardinality class of this relationship
+      # is equal to one. This is +true+ for one-to-one or
+      # one-to-many relationships only.
+      def one_to?
+        cardinality.cardinality_class[0] == 1
+      end
+    
+      # Indicates whether the source cardinality class of this relationship
+      # is equal to infinity. This is +true+ for many-to-many relationships only.
+      def many_to?
+        cardinality.cardinality_class[0] != 1
+      end
+    
+      # The strength of a relationship is equal to the number of associations
+      # that describe it.
+      def strength
+        if source.generalized? then 1 else associations.size end
+      end
+
+      def <=>(other) # @private :nodoc:
+        (source.name <=> other.source.name).nonzero? or (destination.name <=> other.destination.name)
+      end
+    
+      private
+
+      def associations_range(associations, absolute_max)
+        # The minimum of the range is the maximum value of each association
+        # minimum. If there is none, it is zero by definition. The reasoning is
+        # that from all associations, if only one has a required minimum, then
+        # this side of the relationship has a cardinality of at least one.
+        min = associations.map { |assoc| association_minimum(assoc) }.max || 0
+
+        # The maximum of the range is the maximum value of each association
+        # maximum. If there is none, it is equal to the absolute maximum. If
+        # only one association has a high cardinality on this side, the
+        # relationship itself has the same maximum cardinality.
+        max = associations.map { |assoc| association_maximum(assoc) }.max || absolute_max
+
+        min..max
+      end
+    
+      def association_minimum(association)
+        minimum = association_validators(:presence, association).any? ||
+          foreign_key_required?(association) ? 1 : 0
+        length_validators = association_validators(:length, association)
+        length_validators.map { |v| v.options[:minimum] }.compact.max or minimum
+      end
+
+      def association_maximum(association)
+        maximum = association.collection? ? N : 1      
+        length_validators = association_validators(:length, association)
+        length_validators.map { |v| v.options[:maximum] }.compact.min or maximum
+      end
+    
+      def association_validators(kind, association)
+        association.active_record.validators_on(association.name).select { |v| v.kind == kind }
+      end
+    
+      def any_habtm?(associations)
+        associations.any? { |association| association.macro == :has_and_belongs_to_many }
+      end
+    
+      def foreign_key_required?(association)
+        if association.belongs_to?
+          column = association.active_record.columns_hash[association.primary_key_name] and !column.null
+        end
+      end
+    end
+  end
+end

data/lib/rails_erd/domain/relationship/cardinality.rb

@@ -0,0 +1,118 @@
+module RailsERD
+  class Domain
+    class Relationship
+      class Cardinality
+        extend Inspectable
+        inspection_attributes :source_range, :destination_range
+        
+        N = Infinity = 1.0/0 # And beyond.
+      
+        CLASSES = {
+          [1, 1] => :one_to_one,
+          [1, N] => :one_to_many,
+          [N, 1] => :many_to_one,
+          [N, N] => :many_to_many
+        } # @private :nodoc:
+
+        # Returns a range that indicates the source (left) cardinality.
+        attr_reader :source_range
+      
+        # Returns a range that indicates the destination (right) cardinality.
+        attr_reader :destination_range
+
+        # Create a new cardinality based on a source range and a destination
+        # range. These ranges describe which number of values are valid.
+        def initialize(source_range, destination_range) # @private :nodoc:
+          @source_range = compose_range(source_range)
+          @destination_range = compose_range(destination_range)
+        end
+      
+        # Returns the name of this cardinality, based on its two cardinal
+        # numbers (for source and destination). Can be any of
+        # +:one_to_one:+, +:one_to_many+, or +:many_to_many+. The name
+        # +:many_to_one+ also exists, but Rails ERD always normalises these
+        # kinds of relationships by inversing them, so they become
+        # +:one_to_many+ associations.
+        #
+        # You can also call the equivalent method with a question mark, which
+        # will return true if the name corresponds to that method. For example:
+        #
+        #   cardinality.one_to_one?
+        #   #=> true
+        #   cardinality.one_to_many?
+        #   #=> false
+        def name
+          CLASSES[cardinality_class]
+        end
+      
+        # Returns +true+ if the source (left side) is not mandatory.
+        def source_optional?
+          source_range.first < 1
+        end
+      
+        # Returns +true+ if the destination (right side) is not mandatory.
+        def destination_optional?
+          destination_range.first < 1
+        end
+      
+        # Returns the inverse cardinality. Destination becomes source, source
+        # becomes destination.
+        def inverse
+          self.class.new destination_range, source_range
+        end
+      
+        CLASSES.each do |cardinality_class, name|
+          class_eval <<-RUBY
+            def #{name}?
+              cardinality_class == #{cardinality_class.inspect}
+            end
+          RUBY
+        end
+      
+        def ==(other) # @private :nodoc:
+          source_range == other.source_range and destination_range == other.destination_range
+        end
+      
+        def <=>(other) # @private :nodoc:
+          (cardinality_class <=> other.cardinality_class).nonzero? or
+          compare_with(other) { |x| x.source_range.first + x.destination_range.first }.nonzero? or
+          compare_with(other) { |x| x.source_range.last + x.destination_range.last }.nonzero? or
+          compare_with(other) { |x| x.source_range.last }.nonzero? or
+          compare_with(other) { |x| x.destination_range.last }
+        end
+      
+        # Returns an array with the cardinality classes for the source and
+        # destination of this cardinality. Possible return values are:
+        # <tt>[1, 1]</tt>, <tt>[1, N]</tt>, <tt>[N, N]</tt>, and (in theory)
+        # <tt>[N, 1]</tt>.
+        def cardinality_class
+          [source_cardinality_class, destination_cardinality_class]
+        end
+      
+        protected
+
+        # The cardinality class of the source (left side). Either +1+ or +Infinity+.
+        def source_cardinality_class
+          source_range.last == 1 ? 1 : N
+        end
+      
+        # The cardinality class of the destination (right side). Either +1+ or +Infinity+.
+        def destination_cardinality_class
+          destination_range.last == 1 ? 1 : N
+        end
+      
+        private
+      
+        def compose_range(r)
+          return r..r if r.kind_of?(Integer) && r > 0
+          return (r.begin)..(r.end - 1) if r.exclude_end?
+          r
+        end
+
+        def compare_with(other, &block)
+          yield(self) <=> yield(other)
+        end
+      end
+    end
+  end
+end

data/lib/rails_erd/domain/specialization.rb

@@ -0,0 +1,58 @@
+module RailsERD
+  class Domain
+    # Describes the specialization of an entity. Specialized entites correspond
+    # to inheritance. In Rails, specialization is referred to as single table
+    # inheritance.
+    class Specialization
+      class << self
+        def from_models(domain, models) # @private :nodoc:
+          (inheritance_from_models(domain, models) + polymorphic_from_models(domain, models)).sort
+        end
+        
+        private
+        
+        def polymorphic_from_models(domain, models)
+          models.collect(&:reflect_on_all_associations).flatten.collect { |association|
+            [association.options[:as].to_s.classify, association.active_record.name] if association.options[:as]
+          }.compact.uniq.collect { |names|
+            new(domain, domain.entity_by_name(names.first), domain.entity_by_name(names.last))
+          }
+        end
+        
+        def inheritance_from_models(domain, models)
+          models.reject(&:descends_from_active_record?).collect { |model|
+            new(domain, domain.entity_by_name(model.base_class.name), domain.entity_by_name(model.name))
+          }
+        end
+      end
+      
+      extend Inspectable
+      inspection_attributes :generalized, :specialized
+
+      # The domain in which this specialization is defined.
+      attr_reader :domain
+
+      # The source entity.
+      attr_reader :generalized
+    
+      # The destination entity.
+      attr_reader :specialized
+      
+      def initialize(domain, generalized, specialized) # @private :nodoc:
+        @domain, @generalized, @specialized = domain, generalized, specialized
+      end
+      
+      def inheritance?
+        !polymorphic?
+      end
+      
+      def polymorphic?
+        generalized.generalized?
+      end
+
+      def <=>(other) # @private :nodoc:
+        (generalized.name <=> other.generalized.name).nonzero? or (specialized.name <=> other.specialized.name)
+      end
+    end
+  end
+end