metasploit-erd 0.0.1

data/lib/metasploit/erd/entity/class.rb

@@ -0,0 +1,69 @@
+# Entity for Entity-Relationship Diagram that wraps a `Class<ActiveRecord::Base>` to assist with finding its
+# {#class_set directly related classes}
+class Metasploit::ERD::Entity::Class
+  include Metasploit::ERD::Clusterable
+
+  #
+  # Attributes
+  #
+
+  attr_reader :klass
+
+  # @!attribute [r] klass
+  #   The class whose `belongs_to` associations should be followed to generate
+  #   {#class_set set of Classes on which it depends}.
+  #
+  #   @return [Class<ActiveRecord::Base>]
+
+  #
+  # Instance Methods
+  #
+
+  # @param klass [Class<ActiveRecord::Base>]
+  def initialize(klass)
+    @klass = klass
+  end
+
+  # Returns all classes to which the {#klass} has a `belongs_to` association.  Only `belongs_to` associations are traced
+  # because they have foreign keys and without the belongs_to associations the foreign keys would have no primary keys
+  # to which to point.
+  #
+  # @param source [Class<ActiveRecord::Base>] an `ActiveRecord::Base` subclass.
+  # @return [Set<Class<ActiveRecord::Base>>]
+  def class_set
+    reflections = klass.reflect_on_all_associations(:belongs_to)
+
+    reflections.each_with_object(Set.new) { |reflection, set|
+      relationship = Metasploit::ERD::Relationship.new(reflection)
+      set.merge(relationship.class_set)
+    }
+  end
+
+  # Cluster seeded with {#klass}.
+  #
+  # @return [Metasploit::ERD::Cluster]
+  def cluster
+    Metasploit::ERD::Cluster.new(klass)
+  end
+
+  # (see Metasploit::ERD::Clusterable#diagram)
+  #
+  # @example Generate ERD for a Class in directory
+  #   klass = Klass
+  #   entity = Metasploit::ERD::Entity::Class.new(klass)
+  #   # will add default .png extension
+  #   diagram = entity.diagram(directory: directory)
+  #   diagram.create
+  #
+  # @option options [String] :basename ("<klass.name.underscore>.erd") The basename to use for the `:filename`
+  #   option.
+  # @option options [String] :title ("<klass.name> Namespace Entity-Relationship Diagram") Title for diagram.
+  def diagram(options={})
+    super_options = {
+        basename: "#{klass.name.underscore}.erd",
+        title: "#{klass} Entity-Relationship Diagram"
+    }.merge(options)
+
+    super(super_options)
+  end
+end

data/lib/metasploit/erd/entity/namespace.rb

@@ -0,0 +1,66 @@
+# Entity for a namespace with a given {#namespace_name name}.
+class Metasploit::ERD::Entity::Namespace
+  include Metasploit::ERD::Clusterable
+
+  #
+  # Attributes
+  #
+
+  attr_reader :namespace_name
+
+  # @!attribute [r] namespace_name
+  #   The `Module#name` of a namespace module for a collection of `Class<ActiveRecord::Base>`
+  #
+  #   @return [String]
+
+  #
+  # Instance Methods
+  #
+
+  # @param namespace_name [String]
+  def initialize(namespace_name)
+    @namespace_name = namespace_name
+  end
+
+  # @note Caller must load all `ActiveRecord::Base` descendants that should be in the search domain.
+  #
+  # The entities in the namespace with `namespace_name`.
+  #
+  # @param namespace_name [String] The `Module#name` of the `Class` or `Module` that is the namespace for a collection
+  #   of `ActiveRecord::Base` descendants.
+  # @return [Array<Class<ActiveRecord::Base>
+  def classes
+    ActiveRecord::Base.descendants.select { |klass|
+      klass.parents.any? { |parent|
+        parent.name == namespace_name
+      }
+    }
+  end
+
+  # Cluster seeded with all {#classes} in this namespace.
+  #
+  # @return [Metasploit::ERD::Cluster]
+  def cluster
+    Metasploit::ERD::Cluster.new(*classes)
+  end
+
+  # (see Metasploit::ERD::Clusterable#diagram)
+  #
+  # @example Generate ERD for namespace in directory
+  #   entity = Metasploit::ERD::Entity::Namespace.new('Nested::Namespace')
+  #   # will add default .png extension
+  #   diagram = entity.diagram(directory: directory)
+  #   diagram.create
+  #
+  # @option options [String] :basename ("<namespace_name.underscore>.erd") The basename to use for the `:filename`
+  #   option.
+  # @option options [String] :title ("<namespace_name> Namespace Entity-Relationship Diagram") Title for diagram.
+  def diagram(options={})
+    super_options = {
+        basename: "#{namespace_name.underscore}.erd",
+        title: "#{namespace_name} Namespace Entity-Relationship Diagram"
+    }.merge(options)
+
+    super(super_options)
+  end
+end

data/lib/metasploit/erd/relationship.rb

@@ -0,0 +1,57 @@
+# The relationship in an Entity-Relationship Diagram.  Modelled using an {#association} extracted from a
+# `Class<ActiveRecord::Base>` using reflection.
+class Metasploit::ERD::Relationship
+  #
+  # Attributes
+  #
+
+  attr_reader :association
+
+  # @!attribute [r] association
+  #   A `belongs_to` association.
+  #
+  #   @return [ActiveRecord::Associations::BelongsToAssociation]
+
+  #
+  # Instance Methods
+  #
+
+  # @param association [ActiveRecord::Associations::BelongsToAssociation]
+  def initialize(association)
+    @association = association
+  end
+
+  # Set of classes pointed to by this association.  Differs from `association.klass` as {#class_set} properly handles
+  # polymorphic associations by finding all `Class<ActiveRecord::Base>` that `has_many <inverse>, as: <name>` and so
+  # can fulfill `belongs_to <name>, polymorpic: true`.
+  #
+  # @return [Set<Class<ActiveRecord::Base>>]
+  def class_set
+    if association.options[:polymorphic]
+      polymorphic_class_set
+    else
+      Set.new([association.klass])
+    end
+  end
+
+  private
+
+  # Finds the target classes for `belongs_to <name>, polymorphic: true`.
+  #
+  # @return [Set<Class<ActiveRecord::Base>>]
+  def polymorphic_class_set
+    name = association.name
+
+    ActiveRecord::Base.descendants.each_with_object(Set.new) { |descendant, class_set|
+      has_many_reflections = descendant.reflect_on_all_associations(:has_many)
+
+      has_many_reflections.each do |has_many_reflection|
+        as = has_many_reflection.options[:as]
+
+        if as == name
+          class_set.add descendant
+        end
+      end
+    }
+  end
+end

data/lib/metasploit/erd/version.rb

@@ -0,0 +1,31 @@
+module Metasploit
+  module ERD
+    # Holds components of {VERSION} as defined by {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0}.
+    module Version
+      # The major version number.
+      MAJOR = 0
+      # The minor version number, scoped to the {MAJOR} version number.
+      MINOR = 0
+      # The patch number, scoped to the {MINOR} version number.
+      PATCH = 1
+
+      # The full version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the `PRERELEASE` in the
+      # {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0} format.
+      #
+      # @return [String] '{MAJOR}.{MINOR}.{PATCH}' on master.  '{MAJOR}.{MINOR}.{PATCH}-`<PRERELEASE>`' on any branch
+      #   other than master.
+      def self.full
+        version = "#{MAJOR}.#{MINOR}.#{PATCH}"
+
+        if defined? PRERELEASE
+          version = "#{version}-#{PRERELEASE}"
+        end
+
+        version
+      end
+    end
+
+    # @see Version.full
+    VERSION = Version.full
+  end
+end

data/lib/tasks/yard.rake

@@ -0,0 +1,32 @@
+# @note All options not specific to any given rake task should go in the .yardopts file so they are available to both
+#   the below rake tasks and when invoking `yard` from the command line
+
+if defined? YARD
+  namespace :yard do
+    YARD::Rake::YardocTask.new(:doc) do |t|
+      # --no-stats here as 'stats' task called after will print fuller stats
+      t.options = ['--no-stats']
+
+      t.after = Proc.new {
+        Rake::Task['yard:stats'].execute
+      }
+    end
+
+    task :doc
+
+    desc "Shows stats for YARD Documentation including listing undocumented modules, classes, constants, and methods"
+    task :stats do
+      stats = YARD::CLI::Stats.new
+      stats.run('--compact', '--list-undoc')
+    end
+  end
+
+  # @todo Figure out how to just clone description from yard:doc
+  desc "Generate YARD documentation"
+  # allow calling namespace to as a task that goes to default task for namespace
+  task :yard => ['yard:doc']
+
+  task :default => :yard
+else
+  puts 'YARD not defined, so yard tasks cannot be setup.'
+end

data/metasploit-erd.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'metasploit/erd/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'metasploit-erd'
+  spec.version       = Metasploit::ERD::VERSION
+  spec.authors       = ['Luke Imhoff']
+  spec.email         = ['luke_imhoff@rapid7.com']
+  spec.summary       = 'Extensions to rails-erd to find clusters of models to generate subdomains specific to each model'
+  spec.description   = 'Traces the belongs_to associations on ActiveRecord::Base descendants to find the minimum ' \
+                       'cluster in which all foreign keys are fulfilled in the Entity-Relationship Diagram.'
+  spec.homepage      = 'https://github.com/rapid7/metasploit-erd'
+  spec.license       = 'BSD-3-clause'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake', '~> 10.3'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+
+  # restrict from rails 4.0 to be compatible with rest of metasploit ecosystem.
+  # @todo Update to work with rails 4 (MSP-9836)
+  rails_version_constraints = ['>= 3.2', '< 4.0.0']
+
+  spec.add_runtime_dependency 'activerecord', *rails_version_constraints
+  spec.add_runtime_dependency 'activesupport', *rails_version_constraints
+  spec.add_runtime_dependency 'rails-erd', '~> 1.1'
+end

data/spec/metasploit/erd/cluster_spec.rb

@@ -0,0 +1,158 @@
+require 'spec_helper'
+
+describe Metasploit::ERD::Cluster do
+  include_context 'ActiveRecord::Base connection'
+  include_context 'ActiveRecord::Base.descendants cleaner'
+
+  subject(:cluster) {
+    described_class.new(*roots)
+  }
+
+  context '#class_set' do
+    subject(:class_set) {
+      cluster.class_set
+    }
+
+    context 'with roots' do
+      context 'with cycle' do
+        let(:roots) do
+          A
+        end
+
+        #
+        # Callbacks
+        #
+
+        before(:each) do
+          a_class = Class.new(ActiveRecord::Base) {
+            belongs_to :b,
+                       class_name: 'B',
+                       inverse_of: :as
+
+            has_many :cs,
+                     class_name: 'C',
+                     inverse_of: :a
+          }
+
+          stub_const('A', a_class)
+
+          ActiveRecord::Migration.verbose = false
+
+          ActiveRecord::Migration.create_table :as do |t|
+            t.references :b
+          end
+
+          b_class = Class.new(ActiveRecord::Base) {
+            has_many :as,
+                     class_name: 'A',
+                     inverse_of: :b
+
+            belongs_to :c,
+                       class_name: 'C',
+                       inverse_of: :bs
+
+          }
+
+          stub_const('B', b_class)
+
+          ActiveRecord::Migration.create_table :bs do |t|
+            t.references :c
+          end
+
+          c_class = Class.new(ActiveRecord::Base) {
+            belongs_to :a,
+                       class_name: 'A',
+                       inverse_of: :cs
+
+            has_many :bs,
+                     class_name: 'B',
+                     inverse_of: :c
+          }
+
+          stub_const('C', c_class)
+
+          ActiveRecord::Migration.create_table :cs do |t|
+            t.references :a
+          end
+        end
+
+        it 'includes all classes in cycle' do
+          expect(class_set).to include A
+          expect(class_set).to include B
+          expect(class_set).to include C
+        end
+      end
+
+      context 'with superclasses' do
+        #
+        # lets
+        #
+
+        let(:subclass) {
+          Class.new(superclass)
+        }
+
+        let(:superclass) {
+          Class.new(ActiveRecord::Base)
+        }
+
+        #
+        # Callbacks
+        #
+
+        before(:each) do
+          stub_const('Superclass', superclass)
+          stub_const('Subclass', subclass)
+
+          ActiveRecord::Migration.verbose = false
+
+          ActiveRecord::Migration.create_table superclass.table_name do |t|
+            # type column for hold Class#name for Single Table Inheritance (STI)
+            t.string :type, null: false
+          end
+        end
+
+        context 'with subclass as root' do
+          let(:roots) {
+            [
+                subclass
+            ]
+          }
+
+          it 'includes subclass' do
+            expect(class_set).to include(subclass)
+          end
+
+          it 'includes superclass' do
+            expect(class_set).to include(superclass)
+          end
+        end
+
+        context 'with superclass as root' do
+          let(:roots) {
+            [
+                superclass
+            ]
+          }
+
+          it 'includes superclass' do
+            expect(class_set).to include(superclass)
+          end
+
+          it 'does not include subclasses because subclasses should not have additional foreign keys' do
+            expect(class_set).not_to include(subclass)
+          end
+        end
+      end
+    end
+
+    context 'without roots' do
+      let(:roots) do
+        []
+      end
+
+      it { should be_a Set }
+      it { should be_empty }
+    end
+  end
+end