metasploit-concern 0.0.2 → 0.0.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MDM5ZDczNDk1NzkwNTYzMTMzZGZlMTNlMmY3NzJjNDExMDMyNDg1Zg==
+    MzYzMTU5MmEzNWYwZjI0MWM1NDVlNTJmYThhYWU5ZjVmMmYxMmU5Yw==
   data.tar.gz: !binary |-
-    ODI3MTBjNzAxNDdhNWY3ZTliYjVmMjFjN2NmNWU0MTM5NTY5Mjc2OA==
+    NjdjZDdlYzRlN2JjNTJmOWQyMTJiNTI2YTZlYzA3YTAzNDFiNDZlMw==
 SHA512:
   metadata.gz: !binary |-
-    MDBiMzliNWFlYzk5OWZjOGExMjc4MDYxZjQyMzJlNjRlYzIxNjJiNWFkM2Y3
-    N2ViNjYxY2MyZmM3MzUxMGY5YTg2NmE5YmJmNTkxZTU3MGY5Mzk3YmNhMjZk
-    NTk4YmMyODYwYTI1YTk0MWI2MDRmNjc4NTVkMTRlMjE3ZWI0NTQ=
+    YTIwZDRmNmZiNmNhODA4NDExYmRlNWQ4MDJjZTFhOWE1MDQ2NjRiYzUxYTIz
+    ZWRkZGU2ZDgxMzhhNDZjZGFiYzI5NWRkNTgyNzhkNGYwYWMxY2NlNGU5YmJh
+    OWQ1YjdhYjRiNzQyMGU0NWM2ODU1NWE0ZjdiMmRkZDBjYjIyNzk=
   data.tar.gz: !binary |-
-    ODM0MGY3YTZiMTNkOTYwYTg5NWRjMDIxN2JlZDA2ZDllYTVmN2E2Y2ZkZDEy
-    OGU3MDQyZWEyZmY5ZWFlZDcxM2ZlODg0Zjg4MGVkNmU2YjM4ZjUwYjc3YWY4
-    YThlYzE0Mjg5MGYyMmE4ZjlmYTZjNDAyMGJkMWI5ZTIxYWU4NmY=
+    NjUzY2U3YjkwNWNmMmJmNWE0MGI2NDkwZWUwMmIxNDk0ZDVmZTkwOGM3ODVk
+    ODJhMDk4YzZmZmIxZTEzMWU2Y2M3MjA4MjU1YTkzOTg4NGE3NTE4MDZhNDAz
+    NDIwM2FmYjQ3NDdiNTRiZmVmYjZhODJiM2VjNjI0MDE3YjVlNzQ=

data/README.md

@@ -1,7 +1,121 @@
 # Metasploit::Concern [![Build Status](https://travis-ci.org/rapid7/metasploit-concern.png)](https://travis-ci.org/rapid7/metasploit-concern)[![Code Climate](https://codeclimate.com/github/rapid7/metasploit-concern.png)](https://codeclimate.com/github/rapid7/metasploit-concern)[![Coverage Status](https://coveralls.io/repos/rapid7/metasploit-concern/badge.png)](https://coveralls.io/r/rapid7/metasploit-concern)[![Dependency Status](https://gemnasium.com/rapid7/metasploit-concern.png)](https://gemnasium.com/rapid7/metasploit-concern)[![Gem Version](https://badge.fury.io/rb/metasploit-concern.png)](http://badge.fury.io/rb/metasploit-concern)
 
+`Metasploit::Concern` allows you to define concerns in `app/concerns` that will automatically be included in matching
+classes.  It can be used to automate adding new associations to `ActiveRecord::Base` models from gems and
+`Rails::Engine`s.
+
 ## Versioning
 
 `Metasploit::Concern` is versioned using [semantic versioning 2.0](http://semver.org/spec/v2.0.0.html).  Each branch
 should set `Metasploit::Concern::Version::PRERELEASE` to the branch name, while master should have no `PRERELEASE`
 and the `PRERELEASE` section of `Metasploit::Concern::VERSION` does not exist.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+    gem 'metasploit-concern'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install metasploit-concern
+
+## Supporting concerns
+
+`Metasploit::Concern` support is a cooperative effort that involves the classes from the gem being setup
+to allow downstream dependents to inject concerns.
+
+In order for `Metasploit::Concern` to load concerns for `app/concerns`, the class on which `Module#include` will be
+called must support `ActiveSupport` load hooks with a specific name format.  You can run the appropriate load hooks
+at the bottom of the class body:
+
+    class GemNamespace::GemClass < ActiveRecord::Base
+      # class body
+
+      Metasploit::Concern.run(self)
+    end
+
+### Testing
+
+Include the shared examples from `Metasploit::Concern` in your `spec_helper.rb`:
+
+
+    Dir[Metasploit::Concern.root.join("spec/support/**/*.rb")].each do |f|
+      require f
+    end
+
+
+To verify that your classes call `Metasploit::Concern.run` correctly, you can use the `'Metasploit::Concern.run'` shared
+example:
+
+    # spec/app/models/gem_namespace/gem_class_spec.rb
+    describe GemNamespace::GemClass do
+      it_should_behave_like 'Metasploit::Concern.run'
+    end
+
+## Using concerns
+
+Concerns are added in downstream dependents of gems that support concerns.  These dependents can be a `Rails::Engines`
+or full `Rails::Application`.
+
+### app/concerns
+
+#### Rails::Application
+
+Add this line to your application's `config/application.rb`:
+
+    config.paths.add 'app/concerns', autoload: true
+
+Or if you're already using `config.autoload_paths +=`:
+
+    config.autoload_paths += config.root.join('app', 'concerns')
+
+#### Rails::Engine
+
+Add this line to your engine's class body:
+
+    module EngineNamespace
+      class Engine < ::Rails::Engine
+        config.paths.add 'app/concerns', autoload: true
+      end
+    end
+
+### Concerns
+
+Define concerns for class under `app/concerns` by creating files under directories named after the namespaced class
+names:
+
+    $ mkdir -p app/concerns/gem_namespace/gem_class
+    $ edit app/concerns/gem_namespace/gem_class/my_concern.rb
+
+Inside each concern, make sure the `module` name matches file name:
+
+    module GemNamespace::GemClass::MyConcern
+      ...
+    end
+
+Each concern is included using `Module#include` which means that the `included` method on each concern will be called.
+Using `ActiveSupport::Concern` allow you to add new associations and or validations to `ActiveRecord::Base` subclass:
+
+    module GemNamespace::GemClass::MyConcern
+      extend ActiveSupport::Concern
+
+      included do
+        #
+        # Associations
+        #
+
+        # @!attribute widgets
+        #  Widgets for this gem_class.
+        #
+        #  @return [ActiveRecord::Relation<Widget>]
+        has_many :widgets,
+                 class_name: 'Widget',
+                 dependent: :destroy,
+                 inverse_of :gem_namespace_gem_class
+      end
+    end

data/Rakefile

@@ -30,6 +30,13 @@ Dir.glob(rakefile_glob) do |rakefile|
   load rakefile
 end
 
+require 'cucumber'
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = 'features --format pretty'
+end
+
 begin
   require 'rspec/core'
 rescue LoadError

data/app/models/metasploit/concern/loader.rb

@@ -6,7 +6,7 @@ class Metasploit::Concern::Loader
   # Attributes
   #
 
-  # @!attributes [rw] root
+  # @!attribute [rw] root
   #   Pathname under which to find concerns.
   #
   #   @return [Pathname]

data/lib/metasploit/concern.rb

@@ -1,8 +1,23 @@
+#
+# Gems
+#
+
+# `String#underscore``
+require 'active_support/core_ext/string/inflections'
+# `ActiveSupport.run_load_hooks`
+require 'active_support/lazy_load_hooks'
+
+#
+# Project
+#
+
 # Only include the Rails engine when using Rails.  This is for compatibility with metasploit-framework.
 if defined? Rails
   require 'metasploit/concern/engine'
 end
 
+require 'metasploit/concern/version'
+
 # Shared namespace for metasploit gems; used in {https://github.com/rapid7/metasploit-concern metasploit-concern},
 # {https://github.com/rapid7/metasploit-framework metasploit-framework}, and
 # {https://github.com/rapid7/metasploit-model metasploit-model}
@@ -10,13 +25,12 @@ module Metasploit
   # Automates the inclusion of concerns into classes and models from other `Rail::Engine`s by use of an app/concerns
   # directory in the `Rails::Engine` that declares the concerns.
   #
-  # The `Class` or `Module` must support the use of concerns by calling ActiveSupport.run_load_hooks with a symbol equal
-  # to the underscore of its name with any '/' replaced with underscores also.
+  # The `Class` or `Module` must support the use of concerns by calling {run}.
   #
   # @example engine_that_supports_concerns/app/models/model_that_supports_concerns.rb
   #   class EngineThatSupportsConcerns::ModelThatSupportsConcerns
   #     # declared as last statement in body so that concerns can redefine everything in class
-  #     ActiveSupport.run_load_hooks(:engine_that_supports_concerns_model_that_supports_concerns, self)
+  #     Metasploit::Concern.run(self)
   #   end
   #
   # To include concerns from a Rails::Application add 'app/concerns' to paths and then declare concerns under
@@ -68,6 +82,29 @@ module Metasploit
   #     end
   #   end
   module Concern
+    # @note If `Rails` is loaded and {Metasploit::Concern::Engine} is defined, just use
+    #   `Metasploit::Concern::Engine.root`.
+    #
+    # The root of the `metasploit-concern` gem's file tree.
+    #
+    # @return [Pathname]
+    def self.root
+      @root ||= Pathname.new(__FILE__).parent.parent.parent
+    end
 
+    # @note As `ActiveSupport.run_load_hooks` is used, it is safe to call {run} prior to {Metasploit::Concern}'s
+    # initializer {Metasploit::Concern::Loader#register registering} all the load hooks as any late load hooks will run
+    # as they are registered.
+    #
+    # @note `klass` must have a `Module#name` so that the load hook symbol can be derived.
+    #
+    # Runs the load hooks setup to include app/concerns concerns this `klass`.
+    #
+    # @param klass [Class] A class that should support loading concerns from app/concerns.
+    # @return [void]
+    def self.run(klass)
+      load_hook_name = klass.name.underscore.gsub('/', '_').to_sym
+      ActiveSupport.run_load_hooks(load_hook_name, klass)
+    end
   end
 end

data/lib/metasploit/concern/version.rb

@@ -7,7 +7,7 @@ module Metasploit
       # The minor version number, scoped to the {MAJOR} version number.
       MINOR = 0
       # The patch number, scoped to the {MINOR} version number.
-      PATCH = 2
+      PATCH = 4
 
       # 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.

data/spec/support/shared/examples/metasploit/concern/run.rb

@@ -0,0 +1,34 @@
+shared_examples_for 'Metasploit::Concern.run' do
+  let(:load_hook_name) {
+    described_class.name.underscore.gsub('/', '_').to_sym
+  }
+
+  let(:loaded_bases_by_name) {
+    ActiveSupport.module_eval { @loaded }
+  }
+
+  context 'with correct base' do
+    it 'calls ActiveSupport.run_load_hooks with correct load hook name' do
+      actual_names = []
+
+      loaded_bases_by_name.each do |name, bases|
+        bases.each do |base|
+          if base == described_class
+            actual_names << name
+            break
+          end
+        end
+      end
+
+      expect(actual_names).to include(load_hook_name)
+    end
+  end
+
+  context 'with correct load hook name' do
+    it 'calls ActiveSupport.run_load_hooks with correct base' do
+      actual_bases = loaded_bases_by_name[load_hook_name]
+
+      expect(actual_bases).to include(described_class)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metasploit-concern
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Luke Imhoff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-16 00:00:00.000000000 Z
+date: 2014-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -48,6 +48,7 @@ files:
 - lib/metasploit/concern/engine.rb
 - lib/metasploit/concern/version.rb
 - lib/tasks/yard.rake
+- spec/support/shared/examples/metasploit/concern/run.rb
 homepage: https://github.com/rapid7/metasploit-concern
 licenses:
 - BSD-3-clause