jw-rails-erd 1.4.5

data/lib/rails_erd/domain/entity.rb

@@ -0,0 +1,104 @@
+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 corresponding
+      # 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 ||= generalized? ? [] : Attribute.from_model(domain, model)
+      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 either
+      # models that are defined as +abstract_class+ or they 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 or !!model.abstract_class?
+      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?
+        !!model 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 virtual?
+        generalized? or specialized?
+      end
+      alias_method :abstract?, :virtual?
+
+      # 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/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 inverting 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/relationship.rb

@@ -0,0 +1,203 @@
+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_identifier(association)
+          Set[identifier, association_owner(association), association_target(association)]
+        end
+
+        def association_identifier(association)
+          if association.macro == :has_and_belongs_to_many
+            # Rails 4+ supports the join_table method, and doesn't expose it
+            # as an option if it's an implicit default.
+            (association.respond_to?(:join_table) && association.join_table) || association.options[:join_table]
+          else
+            association.options[:through] || association.send(Domain.foreign_key_method_name).to_s
+          end
+        end
+
+        def association_owner(association)
+          association.options[:as] ? association.options[:as].to_s.classify : association.active_record.name
+        end
+
+        def association_target(association)
+          association.options[:polymorphic] ? association.class_name : association.klass.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 = partition_associations(associations)
+
+        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 partition_associations(associations)
+        if any_habtm?(associations)
+          # 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.map(&:active_record).sort_by(&:name).first
+          associations.partition { |association| association.active_record != source }
+        else
+          associations.partition(&:belongs_to?)
+        end
+      end
+
+      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.active_record.abstract_class? and association.belongs_to?
+          column = association.active_record.columns_hash[association.send(Domain.foreign_key_method_name)] and !column.null
+        end
+      end
+    end
+  end
+end

data/lib/rails_erd/domain/specialization.rb

@@ -0,0 +1,90 @@
+module RailsERD
+  class Domain
+    # Describes the specialization of an entity. Specialized entities correspond
+    # to inheritance or polymorphism. In Rails, specialization is referred to
+    # as single table inheritance, while generalization is referred to as
+    # polymorphism or abstract classes.
+    class Specialization
+      class << self
+        def from_models(domain, models) # @private :nodoc:
+          models = polymorphic_from_models(domain, models) +
+            inheritance_from_models(domain, models) +
+            abstract_from_models(domain, models)
+          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
+
+        def abstract_from_models(domain, models)
+          models.select(&:abstract_class?).collect(&:descendants).flatten.collect { |model|
+            new(domain, domain.entity_by_name(model.superclass.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 = domain
+        @generalized = generalized || NullGeneralized.new
+        @specialized = specialized || NullSpecialization.new
+      end
+
+      def generalization?
+        generalized.generalized?
+      end
+      alias_method :polymorphic?, :generalization?
+
+      def specialization?
+        !generalization?
+      end
+      alias_method :inheritance?, :specialization?
+
+      def <=>(other) # @private :nodoc:
+        (generalized.name <=> other.generalized.name).nonzero? or (specialized.name <=> other.specialized.name)
+      end
+    end
+
+    class NullSpecialization
+      def name
+        ""
+      end
+      def generalized?
+        false
+      end
+    end
+
+    class NullGeneralized
+      def name
+        ""
+      end
+      def generalized?
+        true
+      end
+    end
+  end
+end

data/lib/rails_erd/domain.rb

@@ -0,0 +1,153 @@
+require "rails_erd"
+require "rails_erd/domain/attribute"
+require "rails_erd/domain/entity"
+require "rails_erd/domain/relationship"
+require "rails_erd/domain/specialization"
+
+module RailsERD
+  # The domain describes your Rails domain model. This class is the starting
+  # point to get information about your models.
+  #
+  # === Options
+  #
+  # The following options are available:
+  #
+  # warn:: When set to +false+, no warnings are printed to the
+  #        command line while processing the domain model. Defaults
+  #        to +true+.
+  class Domain
+    class << self
+      # Generates a domain model object based on all loaded subclasses of
+      # <tt>ActiveRecord::Base</tt>. Make sure your models are loaded before calling
+      # this method.
+      #
+      # The +options+ hash allows you to override the default options. For a
+      # list of available options, see RailsERD.
+      def generate(options = {})
+        new ActiveRecord::Base.descendants, options
+      end
+
+      # Returns the method name to retrieve the foreign key from an
+      # association reflection object.
+      def foreign_key_method_name # @private :nodoc:
+        @foreign_key_method_name ||= ActiveRecord::Reflection::AssociationReflection.method_defined?(:foreign_key) ? :foreign_key : :primary_key_name
+      end
+    end
+
+    extend Inspectable
+    inspection_attributes
+
+    # The options that are used to generate this domain model.
+    attr_reader :options
+
+    # Create a new domain model object based on the given array of models.
+    # The given models are assumed to be subclasses of <tt>ActiveRecord::Base</tt>.
+    def initialize(models = [], options = {})
+      @source_models, @options = models, RailsERD.options.merge(options)
+    end
+
+    # Returns the domain model name, which is the name of your Rails
+    # application or +nil+ outside of Rails.
+    def name
+      defined? Rails and Rails.application and Rails.application.class.parent.name
+    end
+
+    # Returns all entities of your domain model.
+    def entities
+      @entities ||= Entity.from_models(self, models)
+    end
+
+    # Returns all relationships in your domain model.
+    def relationships
+      @relationships ||= Relationship.from_associations(self, associations)
+    end
+
+    # Returns all specializations in your domain model.
+    def specializations
+      @specializations ||= Specialization.from_models(self, models)
+    end
+
+    # Returns a specific entity object for the given Active Record model.
+    def entity_by_name(name) # @private :nodoc:
+      entity_mapping[name]
+    end
+
+    # Returns an array of relationships for the given Active Record model.
+    def relationships_by_entity_name(name) # @private :nodoc:
+      relationships_mapping[name] or []
+    end
+
+    def specializations_by_entity_name(name)
+      specializations_mapping[name] or []
+    end
+
+    def warn(message) # @private :nodoc:
+      puts "Warning: #{message}" if options.warn
+    end
+
+    private
+
+    def entity_mapping
+      @entity_mapping ||= {}.tap do |mapping|
+        entities.each do |entity|
+          mapping[entity.name] = entity
+        end
+      end
+    end
+
+    def relationships_mapping
+      @relationships_mapping ||= {}.tap do |mapping|
+        relationships.each do |relationship|
+          (mapping[relationship.source.name] ||= []) << relationship
+          (mapping[relationship.destination.name] ||= []) << relationship
+        end
+      end
+    end
+
+    def specializations_mapping
+      @specializations_mapping ||= {}.tap do |mapping|
+        specializations.each do |specialization|
+          (mapping[specialization.generalized.name] ||= []) << specialization
+          (mapping[specialization.specialized.name] ||= []) << specialization
+        end
+      end
+    end
+
+    def models
+      @models ||= @source_models.select { |model| check_model_validity(model) }.reject { |model| check_habtm_model(model) }
+    end
+
+    def associations
+      @associations ||= models.collect(&:reflect_on_all_associations).flatten.select { |assoc| check_association_validity(assoc) }
+    end
+
+    def check_model_validity(model)
+      model.abstract_class? or model.table_exists? or raise "table #{model.table_name} does not exist"
+    rescue => e
+      warn "Ignoring invalid model #{model.name} (#{e.message})"
+    end
+
+    def check_association_validity(association)
+      # Raises an ActiveRecord::ActiveRecordError if the association is broken.
+      association.check_validity!
+
+      if association.options[:polymorphic]
+        entity_name = association.class_name
+        entity_by_name(entity_name) or raise "polymorphic interface #{entity_name} does not exist"
+      else
+        entity_name = association.klass.name # Raises NameError if the associated class cannot be found.
+        entity_by_name(entity_name) or raise "model #{entity_name} exists, but is not included in domain"
+      end
+    rescue => e
+      warn "Ignoring invalid association #{association_description(association)} (#{e.message})"
+    end
+
+    def association_description(association)
+      "#{association.name.inspect} on #{association.active_record}"
+    end
+
+    def check_habtm_model(model)
+      model.name.start_with?("HABTM_")
+    end
+  end
+end

data/lib/rails_erd/railtie.rb

@@ -0,0 +1,10 @@
+module RailsERD
+  # Rails ERD integrates with Rails 3. If you add it to your +Gemfile+, you
+  # will gain a Rake task called +erd+, which you can use to generate diagrams
+  # of your domain model.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "rails_erd/tasks.rake"
+    end
+  end
+end