prependers 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c33986e6c228a6eea44d3093e16717cb5327b57f23439bc492a8bea1154b7be8
-  data.tar.gz: f4e7cc9175ba8b51a242346f8ee5d08dcee79fe4befb0f806a45706f2b61f394
+  metadata.gz: 30c53a5f64db0e3ee8454289403fbf6aa00a7d90fdee76c504a5cc878324ef88
+  data.tar.gz: 14db78d2c2160984cd891f35f9b1794e55ec011068db5c50834538df430eebf2
 SHA512:
-  metadata.gz: b71e78f24c52085bac6e5102306626097601799bb377c8e9dbb6bf768122fccd3a4cc853164c13f98239ba9db722426319c766f261fe1cc303fcc8220c2d0f37
-  data.tar.gz: a105daf60dd5b44393f9719ad1b2c1913a52cb2d6a90f5d9d2486a4ee6a1672b7c07d38693487f22568739e53bfb851d3858807b66bdc33a24fffcaeb8882922
+  metadata.gz: '0660258db42ece336874d2868b93652a89128076a612057144861a8961d61c1330d8d65d0b4369a81ad2361fdd3d33eeb634b4dab72921a5a1a027a308ba5ecc'
+  data.tar.gz: ab60f96d45f3fecb4abb1689260e6f5aa8b47d52700035ab6a33aebd0e111bf56fb1053d33b380474224a56dab9b1fa11e32bb5e047393a5d2f4e6eacfc21d12

data/.rubocop-https---relaxed-ruby-style-rubocop-yml

@@ -1,5 +1,5 @@
 # Relaxed.Ruby.Style
-## Version 2.4
+## Version 2.5
 
 Style/Alias:
   Enabled: false
@@ -145,30 +145,9 @@ Lint/AssignmentInCondition:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
 
-Metrics/AbcSize:
+Layout/LineLength:
   Enabled: false
 
-Metrics/BlockNesting:
-  Enabled: false
-
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Metrics/LineLength:
-  Enabled: false
-
-Metrics/MethodLength:
-  Enabled: false
-
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/PerceivedComplexity:
+Metrics:
   Enabled: false
 

data/.rubocop.yml

@@ -12,5 +12,11 @@ AllCops:
 Metrics/BlockLength:
   Enabled: false
 
+RSpec/ExampleLength:
+  Enabled: false
+
 Style/GuardClause:
   Enabled: false
+
+Style/FormatStringToken:
+  EnforcedStyle: template

data/CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
-## [Unreleased](https://github.com/nebulab/prependers/tree/HEAD)
+## [v0.3.0](https://github.com/nebulab/prependers/tree/v0.3.0) (2020-04-24)
 
-[Full Changelog](https://github.com/nebulab/prependers/compare/v0.2.0...HEAD)
+[Full Changelog](https://github.com/nebulab/prependers/compare/v0.2.0...v0.3.0)
 
 **Merged pull requests:**
 

data/README.md

@@ -18,7 +18,6 @@ And then execute:
 $ bundle
 ```
 
-
 Or install it yourself as:
 
 ```console
@@ -27,13 +26,13 @@ $ gem install prependers
 
 ## Usage
 
-To define a prepender manually, simply include the `Prependers::Prepender.new` module. For instance,
+To define a prepender manually, simply include the `Prependers::Prepender[]` module. For instance,
 if you have installed an `animals` gem and you want to extend the `Animals::Dog` class, you can
 define a module like the following:
 
 ```ruby
 module Animals::Dog::AddBarking
-  include Prependers::Prepender.new
+  include Prependers::Prepender[]
 
   def bark
     puts 'Woof!'
@@ -50,7 +49,7 @@ prepender:
 
 ```ruby
 module Animals::Dog::AddFamily
-  include Prependers::Prepender.new
+  include Prependers::Prepender[]
 
   module ClassMethods
     def family
@@ -62,13 +61,100 @@ end
 Animals::Dog.family # => 'Canids'
 ```
 
-As you can see, the `ClassMethods` module has automagically been `prepend`ed to the `Animals::Dog`'s
+As you can see, the `ClassMethods` module has automagically been `prepend`ed to `Animals::Dog`'s
 singleton class.
 
+### Using a namespace
+
+It can be useful to have a prefix namespace for your prependers. That way, you don't have to worry
+about accidentally overriding any vendor modules. This is actually the recommended way to define
+your prependers.
+
+You can accomplish this by passing the `:namespace` option when including `Prependers::Prepender`:
+
+```ruby
+module MyApp
+  module Animals
+    module Dog
+      module AddBarking
+        include Prependers::Prepender[namespace: MyApp]
+
+        def bark
+          puts 'Woof!'
+        end
+      end
+    end
+  end
+end
+```
+
+### Verifying original sources
+
+One issue you may run into when extending third-party code is that, when the original implementation
+is updated, it's not always obvious whether you have to update any of your extensions.
+
+Prependers make this a bit easier with the concept of original source verification: you can compute
+a SHA1 hash of the original implementation, store it along with your prepender, and then verify it
+against the current hash when your application loads. If the original source changes, you get an
+error asking you to ensure your prepender is still relevant.
+
+To use original source verification in your prependers, pass the `:verify` option:
+
+```ruby
+module Animals::Dog::AddBarking
+  include Prependers::Prepender[verify: nil]
+
+  # ...
+end
+```
+
+When you load your application now, you will get an error with instructions on how to set the proper
+hash:
+
+```
+Prependers::OutdatedPrependerError:
+  You have not defined an original hash for Animals::Dog in Animals::Dog::AddBarking.
+
+  You can define the hash by updating your include statement as follows:
+
+      include Prependers::Prepender[verify: 'f7175533215c39f3f3328aa5829ac6b1bb168218']
+```
+
+At this point, you should update your prepender with the correct hash:
+
+```ruby
+module Animals::Dog::AddBarking
+  include Prependers::Prepender[verify: 'f7175533215c39f3f3328aa5829ac6b1bb168218']
+
+  # ...
+end
+```
+
+Now, when the underlying implementation of `Animals::Dog` changes because of a dependency update or
+other reasons, Prependers will raise an error such as the following:
+
+```
+Prependers::OutdatedPrependerError:
+  The stored hash for Animals::Dog in Animals::Dog::AddBarking is
+  f7175533215c39f3f3328aa5829ac6b1bb168218, but the current hash is
+  2f05682e4f46b509c23a8418d9427a9eeaa8a79e instead.
+
+  This most likely means that the original source has changed.
+
+  Check that your prepender is still valid, then update the stored hash:
+
+      include Prependers::Prepender[verify: '2f05682e4f46b509c23a8418d9427a9eeaa8a79e']
+```
+
+Original source verification also works when a module is defined in multiple locations. 
+
+*NOTE: Due to limitations in Ruby's API, it is not possible to use source verification with modules
+that don't define any methods. Prependers will raise an error if you try to do this.*
+
 ### Autoloading prependers
 
-If you don't want to include `Prependers::Prepender`, you can also autoload prependers from a path,
-they will be loaded in alphabetical order.
+If you don't want to include `Prependers::Prepender[]`, you can also autoload prependers from a
+path, they will be loaded in alphabetical order.
 
 Here's the previous example, but with autoloading:
 
@@ -84,6 +170,9 @@ end
 Prependers.load_paths(File.expand_path('app/prependers'))
 ```
 
+Note that, in order for autoprepending to work, the paths of your prependers must match the names
+of the prependers you defined.
+
 You can pass multiple arguments to `#load_paths`, which is useful if you have subdirectories in
 `app/prependers`:
 
@@ -95,37 +184,14 @@ Prependers.load_paths(
 )
 ```
 
-Note that, in order for autoprepending to work, the paths of your prependers must match the names
-of the prependers you defined.
-
-### Using a namespace
-
-It can be useful to have a prefix namespace for your prependers. That way, you don't have to worry
-about accidentally overriding any vendor modules. This is actually the recommended way to define
-your prependers.
-
-You can accomplish this by passing an argument when including the `Prependers::Prepender` module:
-
-```ruby
-module MyApp
-  module Animals
-    module Dog
-      module AddBarking
-        include Prependers::Prepender.new(MyApp)
-
-        def bark
-          puts 'Woof!'
-        end
-      end
-    end
-  end
-end
-```
-
-If you use autoloading, you can pass the base namespace to `#load_paths`:
+You can pass the `:namespace` option to `#load_paths` to have it forwarded to all prependers:
 
 ```ruby
-Prependers.load_paths(File.expand_path('app/prependers'), namespace: MyApp)
+Prependers.load_paths(
+  File.expand_path('app/prependers/controllers'),
+  File.expand_path('app/prependers/models'),
+  namespace: Acme,
+)
 ```
 
 ### Integrating with Rails
@@ -137,8 +203,7 @@ To use prependers in your Rails app, simply create them under `app/prependers/mo
 Prependers.setup_for_rails
 ```
 
-If you want to use a namespace, just pass the `:namespace` option to `#setup_for_rails` and name
-your files and modules accordingly.
+`#setup_for_rails` accepts the same options as `#load_paths`.
 
 ## Development
 

data/lib/prependers.rb

@@ -1,28 +1,40 @@
 # frozen_string_literal: true
 
+require "digest"
+
 require "prependers/version"
 require "prependers/errors"
+require "prependers/annotate/namespace"
+require "prependers/annotate/verify"
 require "prependers/prepender"
 require "prependers/loader"
 
 module Prependers
-  class << self
-    def load_paths(*paths, **options)
-      paths.flatten.each do |path|
-        Loader.new(path, options).load
-      end
+  def self.load_paths(*paths, **options)
+    paths.flatten.each do |path|
+      Loader.new(path, options).load
     end
+  end
 
-    def setup_for_rails(load_options = {})
-      prependers_directories = Rails.root.join('app', 'prependers').glob('*')
+  def self.setup_for_rails(load_options = {})
+    prependers_directories = Rails.root.join('app', 'prependers').glob('*')
 
-      Rails.application.config.tap do |config|
-        config.autoload_paths += prependers_directories
+    Rails.application.config.tap do |config|
+      config.autoload_paths += prependers_directories
 
-        config.to_prepare do
-          Prependers.load_paths(prependers_directories, load_options)
-        end
+      config.to_prepare do
+        Prependers.load_paths(prependers_directories, load_options)
       end
     end
   end
+
+  def self.prependable_for(prepender)
+    prependable = prepender.name.split('::')[0..-2].join('::')
+
+    if prepender.respond_to?(:__prependers_namespace__)
+      prependable = (prependable[(prepender.__prependers_namespace__.name.length + 2)..-1]).to_s
+    end
+
+    Object.const_get(prependable)
+  end
 end

data/lib/prependers/annotate/namespace.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Prependers
+  module Annotate
+    class Namespace < Module
+      attr_reader :namespace
+
+      def self.[](namespace)
+        new(namespace)
+      end
+
+      def initialize(namespace)
+        @namespace = namespace
+      end
+
+      def included(base)
+        base.singleton_class.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def __prependers_namespace__
+            #{@namespace}
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/prependers/annotate/verify.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Prependers
+  module Annotate
+    class Verify < Module
+      WRONG_HASH_ERROR = \
+        "The stored hash for %{prepended_module} in %{prepender} is %{stored_hash}, but the " \
+        "current hash is %{current_hash} instead.\n\n" \
+        "This most likely means that the original source has changed.\n\n" \
+        "Check that your prepender is still valid, then update the stored hash:\n\n" \
+        "    include Prependers::Prepender[verify: '%{current_hash}']"
+
+      UNSET_HASH_ERROR = \
+        "You have not defined an original hash for %{prepended_module} in %{prepender}.\n\n" \
+        "You can define the hash by updating your include statement as follows:\n\n" \
+        "    include Prependers::Prepender[verify: '%{current_hash}']"
+
+      attr_reader :original_hash
+
+      def self.[](original_hash)
+        new(original_hash)
+      end
+
+      def initialize(original_hash)
+        @original_hash = original_hash
+      end
+
+      def included(prepender)
+        prependable = Prependers.prependable_for(prepender)
+        current_hash = compute_hash(prependable)
+
+        return if current_hash == original_hash
+
+        error = (original_hash ? WRONG_HASH_ERROR : UNSET_HASH_ERROR) % {
+          prepended_module: prependable,
+          prepender: prepender.name,
+          stored_hash: original_hash,
+          current_hash: current_hash,
+        }
+
+        raise OutdatedPrependerError, error
+      end
+
+      private
+
+      def compute_hash(constant)
+        methods = constant.methods(false).map(&constant.method(:method)) +
+                  constant.instance_methods(false).map(&constant.method(:instance_method))
+
+        raise NameError, "#{constant} has no methods" if methods.empty?
+
+        source_locations = methods.map(&:source_location).compact.map(&:first).uniq.sort
+
+        contents = source_locations.map { |path| File.read(path) }.join
+
+        Digest::SHA1.hexdigest(contents)
+      end
+    end
+  end
+end

data/lib/prependers/errors.rb

@@ -4,4 +4,6 @@ module Prependers
   class Error < StandardError; end
 
   class NoPrependerError < Error; end
+
+  class OutdatedPrependerError < Error; end
 end

data/lib/prependers/loader.rb

@@ -2,6 +2,11 @@
 
 module Prependers
   class Loader
+    UNDEFINED_PREPENDER_ERROR = \
+      "Expected `%{path}` to define `%{prepender}`, but it is not defined.\n\n" \
+      "This is most likely because the file has not been required.\n\n" \
+      "Require the file yourself before calling `Prependers.load_paths`."
+
     attr_reader :base_path, :options
 
     def initialize(base_path, options = {})
@@ -14,21 +19,20 @@ module Prependers
         absolute_path = Pathname.new(File.expand_path(path))
         relative_path = absolute_path.relative_path_from(base_path)
 
-        prepender_module_name = expected_module_for(relative_path)
+        prepender_name = expected_module_for(relative_path)
 
-        unless Object.const_defined?(prepender_module_name)
-          error = <<~ERROR
-            Expected #{absolute_path} to define #{prepender_module_name}, but module is not defined.
+        unless Object.const_defined?(prepender_name)
+          raise NoPrependerError, UNDEFINED_PREPENDER_ERROR % {
+            path: absolute_path,
+            prepender: prepender_name,
+          }
+        end
 
-            Note that Prependers does not require files automatically - you will have to do that
-            yourself before calling `#load_paths`.
-          ERROR
+        prepender = Object.const_get(prepender_name)
 
-          raise NoPrependerError, error
+        if prepender.ancestors.none? { |ancestor| ancestor.is_a?(Prependers::Prepender) }
+          prepender.include(Prepender.new(options))
         end
-
-        prepender_module = Object.const_get(prepender_module_name)
-        prepender_module.include Prepender.new(options[:namespace])
       end
     end
 

data/lib/prependers/prepender.rb

@@ -2,26 +2,40 @@
 
 module Prependers
   class Prepender < Module
-    CLASS_METHODS_MODULE_NAME = 'ClassMethods'
+    def self.[](options = {})
+      new(options)
+    end
+
+    attr_reader :options
+
+    NAMESPACE_DEPRECATION = \
+      "[DEPRECATION] Passing a namespace to `Prependers::Prepender#[]` is deprecated. Use the " \
+      "`:namespace` option instead."
 
-    attr_reader :namespace
+    def initialize(options_or_namespace = {})
+      if options_or_namespace.is_a?(Module)
+        warn NAMESPACE_DEPRECATION % { namespace: options_or_namespace }
+        options_or_namespace = { namespace: options_or_namespace }
+      end
 
-    def initialize(namespace = nil)
-      @namespace = namespace
+      @options = options_or_namespace
     end
 
     def included(base)
-      prepended_module_name = base.name.split('::')[0..-2].join('::')
+      if options.key?(:namespace)
+        base.include Prependers::Annotate::Namespace.new(options[:namespace])
+      end
 
-      if namespace
-        prepended_module_name = (prepended_module_name[(namespace.name.length + 2)..-1]).to_s
+      if options.key?(:verify)
+        base.include Prependers::Annotate::Verify.new(options[:verify])
       end
 
-      prepended_module = Object.const_get(prepended_module_name)
-      prepended_module.prepend base
+      prependable = Prependers.prependable_for(base)
+
+      prependable.prepend(base)
 
-      if base.const_defined?(CLASS_METHODS_MODULE_NAME)
-        prepended_module.singleton_class.prepend base.const_get(CLASS_METHODS_MODULE_NAME)
+      if base.const_defined?('ClassMethods')
+        prependable.singleton_class.prepend(base.const_get('ClassMethods'))
       end
     end
   end

data/lib/prependers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Prependers
-  VERSION = "0.3.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prependers
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-24 00:00:00.000000000 Z
+date: 2020-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -157,6 +157,8 @@ files:
 - bin/console
 - bin/setup
 - lib/prependers.rb
+- lib/prependers/annotate/namespace.rb
+- lib/prependers/annotate/verify.rb
 - lib/prependers/errors.rb
 - lib/prependers/loader.rb
 - lib/prependers/prepender.rb