uses 1.0.0.pre.beta1

data/lib/uses/circular_dependency/analyzer.rb

@@ -0,0 +1,60 @@
+require_relative "log_notifier"
+require_relative "ignore_notifier"
+require_relative "raise_error_notifier"
+
+module Uses
+  module CircularDependency
+    class Analyzer
+      def initialize(uses_method_args)
+        @uses_method_args = uses_method_args
+      end
+
+      def analyze!
+        @dependency, @path_to_dependency = transitive_dependency?(@uses_method_args.klass_with_uses,@uses_method_args.klass_being_used)
+      end
+
+      def circular_dependency?
+        !!@dependency
+      end
+
+      def notify!
+        raise "You have not called analyze!" if @dependency.nil?
+        notifier = case @uses_method_args.uses_config.on_circular_dependency
+                   when :warn        then Uses::CircularDependency::LogNotifer.new(@uses_method_args, @path_to_dependency)
+                   when :ignore      then Uses::CircularDependency::IgnoreNotifier.new(@uses_method_args, @path_to_dependency)
+                   when :raise_error then Uses::CircularDependency::RaiseErrorNotifier.new(@uses_method_args, @path_to_dependency)
+                   end
+        notifier.notify!
+      end
+
+    private
+
+      def transitive_dependency?(klass_with_uses,klass_being_analyzed, path=[])
+        other_class_has_uses = klass_being_analyzed.respond_to?(:__uses_dependent_classes)
+
+        if other_class_has_uses
+          if klass_with_uses == klass_being_analyzed
+            [ true, path ]
+          else
+            # Want to stop searching as soon as we find something
+            procs_to_check_for_transitive_dependencies = klass_being_analyzed.__uses_dependent_classes.keys.map { |klass|
+              ->() { transitive_dependency?(klass_with_uses,klass, path + [ klass_being_analyzed ]) }
+            }
+            first_proc_to_find_a_dependency = procs_to_check_for_transitive_dependencies.detect { |p|
+              transitive_dependency, _ = p.()
+              transitive_dependency
+            }
+            if first_proc_to_find_a_dependency
+              _, path_to_dependency = first_proc_to_find_a_dependency.()
+              [ true, path_to_dependency ]
+            else
+              false
+            end
+          end
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/uses/circular_dependency/base_notifier.rb

@@ -0,0 +1,18 @@
+module Uses
+  module CircularDependency
+    class BaseNotifier
+      def initialize(uses_method_args, path_to_dependency)
+        path = if path_to_dependency.empty?
+                 nil
+               else
+                 " via #{path_to_dependency.map(&:to_s).join(',')}"
+               end
+        @message =  "#{uses_method_args.klass_being_used} and #{uses_method_args.klass_with_uses} have a circular dependency#{path}. This may cause unforseen issues, or just be generally confusing"
+      end
+
+      def notify!
+        raise "subclass must implement"
+      end
+    end
+  end
+end

data/lib/uses/circular_dependency/error.rb

@@ -0,0 +1,7 @@
+require_relative "../error"
+module Uses
+  module CircularDependency
+    class Error < Uses::Error
+    end
+  end
+end

data/lib/uses/circular_dependency/ignore_notifier.rb

@@ -0,0 +1,10 @@
+require_relative "base_notifier"
+module Uses
+  module CircularDependency
+    class IgnoreNotifier < BaseNotifier
+      def notify!
+        Rails.logger.debug(@message)
+      end
+    end
+  end
+end

data/lib/uses/circular_dependency/log_notifier.rb

@@ -0,0 +1,10 @@
+require_relative "base_notifier"
+module Uses
+  module CircularDependency
+    class LogNotifer < BaseNotifier
+      def notify!
+        Rails.logger.warn(@message)
+      end
+    end
+  end
+end

data/lib/uses/circular_dependency/raise_error_notifier.rb

@@ -0,0 +1,11 @@
+require_relative "base_notifier"
+require_relative "error"
+module Uses
+  module CircularDependency
+    class RaiseErrorNotifier < BaseNotifier
+      def notify!
+        raise Uses::CircularDependency::Error.new(@message)
+      end
+    end
+  end
+end

data/lib/uses/config.rb

@@ -0,0 +1,38 @@
+require "active_support/core_ext/object/inclusion"
+module Uses
+  class Config
+    # Configure what should happen when a circular dependency is detected.
+    #
+    # :warn:: Emit a warning, but allow it (default)
+    # :raise_error:: Raise an exception, effectively making your app unusable until
+    #                you resolve the circular dependencies
+    # :ignore:: Emit a warning at DEBUG level, effectively allowing you to ignore these issues.
+    attr_reader :on_circular_dependency
+
+    # The array of custom initializers.  Generally you should use
+    # `Uses.initializers do |initializers|` to manipulate this
+    attr_reader :initializers
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      self.on_circular_dependency = :warn
+      @initializers = {}
+    end
+
+    ON_CIRCULAR_DEPENDENCY_VALUES = [
+      :ignore,
+      :raise_error,
+      :warn,
+    ]
+    def on_circular_dependency=(new_value)
+      if !new_value.in?(ON_CIRCULAR_DEPENDENCY_VALUES)
+        raise ArgumentError, "#{new_value} is not a valid value for on_circular_dependency. Use one of #{ON_CIRCULAR_DEPENDENCY_VALUES}"
+      end
+      @on_circular_dependency = new_value
+    end
+
+  end
+end

data/lib/uses/error.rb

@@ -0,0 +1,4 @@
+module Uses
+  class Error < StandardError
+  end
+end

data/lib/uses/initializer/base_initializer.rb

@@ -0,0 +1,19 @@
+module Uses
+  module Initializer
+    class BaseInitializer
+      def initialize(uses_method_args)
+        @proc = self.create_proc(uses_method_args)
+      end
+
+      def call
+        @proc.()
+      end
+
+    private
+
+      def create_proc(uses_method_args)
+        raise "subclass must implement"
+      end
+    end
+  end
+end

data/lib/uses/initializer/from_initializers.rb

@@ -0,0 +1,9 @@
+require_relative "base_initializer"
+
+class Uses::Initializer::FromInitializers < Uses::Initializer::BaseInitializer
+  def create_proc(uses_method_args)
+    uses_method_args.uses_config.initializers.fetch(uses_method_args.klass_being_used)
+  rescue KeyError
+    raise "An initializer for #{uses_method_args.klass_being_used.name} has not been defined. #{uses_method_args.klass_with_uses.name} has set initialize: to :config_initializers, which means it's assuming some other file (e.g. in config/initializers) has called Uses.initializers to set up the initialization"
+  end
+end

data/lib/uses/initializer/new_no_args.rb

@@ -0,0 +1,11 @@
+require_relative "base_initializer"
+
+class Uses::Initializer::NewNoArgs < Uses::Initializer::BaseInitializer
+  def create_proc(uses_method_args)
+    initialize_method = uses_method_args.klass_being_used.instance_method(:initialize)
+    if !initialize_method.arity.in?([0,-1])
+      raise "#{uses_method_args.klass_being_used}'s initializer has required arguments, but has been used in #{uses_method_args.klass_with_uses.class} to initializer with no arguments passed to ::new. Please use initialize: with a Proc or :config_initializers to control how the instance is created"
+    end
+    ->() { uses_method_args.klass_being_used.new }
+  end
+end

data/lib/uses/initializer/proc_based.rb

@@ -0,0 +1,7 @@
+require_relative "base_initializer"
+
+class Uses::Initializer::ProcBased < Uses::Initializer::BaseInitializer
+  def create_proc(uses_method_args)
+    uses_method_args.initializer_strategy
+  end
+end

data/lib/uses/initializer.rb

@@ -0,0 +1,35 @@
+require_relative "error"
+require_relative "initializer/new_no_args"
+require_relative "initializer/from_initializers"
+require_relative "initializer/proc_based"
+
+module Uses
+  module Initializer
+    def self.from_args(uses_method_args)
+      strategy_klass(uses_method_args).new(uses_method_args)
+    end
+
+  private
+
+    def self.strategy_klass(uses_method_args)
+      case uses_method_args.initializer_strategy
+      when :new_no_args         then NewNoArgs
+      when :config_initializers then FromInitializers
+      when Proc                 then ProcBased
+      else
+        raise UnknownInitializerStrategy.new(uses_method_args.initializer_strategy)
+      end
+    end
+
+
+    class UnknownInitializerStrategy < Uses::Error
+      def initialize(strategy)
+        if strategy.kind_of?(Symbol)
+          super("initialize: received #{strategy}, which is not supported. Should be either the symbol :config_initializers, a Proc, or simply omitted")
+        else
+          super("initialize: received a #{strategy.class}, which is not supported. Should be either the symbol :config_initializers, a Proc, or simply omitted")
+        end
+      end
+    end
+  end
+end

data/lib/uses/inject_double.rb

@@ -0,0 +1,76 @@
+module Uses
+  # Convienience methods for test to inject mocks/doubles into a class under test.
+  #
+  # An advantage of "injecting" dependencies is that you can provide alternate implementations 
+  # for testing that simplify your tests.  While Ruby doesn't strictly require that you make
+  # dependencies injectible, it is nice to have a bit of help in doing to so for a test.
+  #
+  # If using RSpec, use `inject_rspec_double`.
+  module InjectDouble
+    # Inject an instantiated double into subject, returing the double.
+    #
+    # subject:: the instance of the class under test where you want a double injected
+    # injectsion:: a hash of size 1 where the key is the class given to `uses` and
+    #              the value is the doubled object
+    def inject_double(subject, injections)
+      if injections.size != 1
+        raise "expected a single key/value to inject_double, but got #{injections.size}"
+      end
+
+      klass    = injections.first[0]
+      instance = injections.first[1]
+
+      subject_must_use_uses!(subject)
+      injected_class_must_be_class!(klass)
+
+      name = dependency_method_name!(subject, klass)
+
+      subject.__uses_dependent_instances[name] = instance
+
+      instance
+    end
+
+    #
+    # For Rspec users, you might do:
+    #
+    #     dependent_service = instance_doule(DependentService)
+    #     allow(DependentService).to receive(:new).and_return(dependent_service)
+    #
+    # The problem is that it would be nice to know if your class under test actually uses the 
+    # dependent service, plus it's annoying to have to write two lines of code.
+    #
+    # Instead:
+    #
+    #     dependent_service = instance_double(object_under_test, DependentService)
+    #
+    # If you depend in DependentService, this will replace the real instance with yours.  If you do not
+    # it will raise an error.
+    def inject_rspec_double(subject, klass)
+      self.inject_double(subject, klass => instance_double(klass))
+    end
+
+  private
+
+    def subject_must_use_uses!(subject)
+      if !subject.class.respond_to?(:__uses_dependent_classes)
+        raise Uses::Error, "#{subject.class} does not include Uses::Method, so you cannot inject a double into it"
+      end
+    end
+
+    def injected_class_must_be_class!(klass)
+      if !klass.kind_of?(Class)
+        raise Uses::Error, "Pass the actual class, not a #{klass.class}."
+      end
+    end
+
+    def dependency_method_name!(subject, klass)
+      name = subject.class.__uses_dependent_classes[klass].to_s
+
+      if name.blank?
+        raise Uses::Error, "#{subject.class} does not depend on a #{klass}, so there is no reason to inject a mock"
+      end
+      name
+    end
+
+  end
+end

data/lib/uses/invalid_method_name.rb

@@ -0,0 +1,5 @@
+require_relative "error"
+module Uses
+  class InvalidMethodName < Uses::Error
+  end
+end

data/lib/uses/method.rb

@@ -0,0 +1,87 @@
+require "active_support/concern"
+require "active_support/core_ext/string/inflections"
+
+require_relative "config"
+require_relative "method_name"
+require_relative "initializer"
+require_relative "uses_method_args"
+require_relative "circular_dependency/analyzer"
+
+module Uses
+  # Provides a very basic mechanism for dependency management between classes in your service
+  # layer.  This is done via the method `uses`.
+  #
+  # The simplest use of this module is to create a base class for all classes in your service layer:
+  #
+  #     # app/services/application_service.rb
+  #     class ApplicationService
+  #       include Uses::Method
+  #     end
+  #
+  # Then, all services inherit from this and have access to the uses method.
+  #
+  # Note that any class or method without RubyDoc should be treated as private/internal, and you
+  # should not depend on.
+  module Method
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declare that the class including the Uses::Method module depends on another
+      # class.  This will create an instance method on this class that returns a memoized
+      # instance of the class passed in (klass).
+      #
+      # klass:: the class of what is dependend-upon.
+      # as:: if given, overrides the default naming for the instance method.
+      #      By default (when as: is omitted or set to nil), the name will
+      #      be `klass.underscore.gsub(/\//,"_")` (see Uses::MethodName),
+      #      so for a class named SomeClass, it would be `some_class`, however for
+      #      a class named SomeNamespace::SomeClass, it would be `some_namespace_some_class`.
+      #      If you set a value for `as:` that value would be used instead of this auto-generated value.
+      # initialize: Controls how the instance is initialized:
+      #             :new_no_args:: create the instance with `.new` an no args. This is the default, since
+      #                            most service-layer classes should not need initializer arguments.
+      #             :config_initializers:: Indicates that an intiailzation proc has been previously
+      #                                    configured and should be used.  See ::initializers above.
+      #             a Proc:: The `Proc` is called to return the new instance.  Generally you would
+      #                      only use this if your class required special initialization but is only
+      #                      used in *this* class.  Keep in mind that this couples the service with
+      #                      how to iniltialize its dependent, which is not often a good thing.  But
+      #                      sometimes you have to.
+      def uses(klass, as: nil, initialize: :new_no_args)
+        uses_method_args = Uses::UsesMethodArgs.new(
+          klass_being_used: klass,
+          klass_with_uses: self,
+          method_name_override: as,
+          initializer_strategy: initialize,
+          uses_config: Uses.config
+        )
+
+        name                         = Uses::MethodName.new(uses_method_args)
+        circular_dependency_analyzer = Uses::CircularDependency::Analyzer.new(uses_method_args)
+        initializer                  = Uses::Initializer.from_args(uses_method_args)
+
+        circular_dependency_analyzer.analyze!
+
+        if circular_dependency_analyzer.circular_dependency?
+          circular_dependency_analyzer.notify!
+        end
+
+        self.__uses_dependent_classes[klass] = name
+
+        define_method name.to_s do
+          self.__uses_dependent_instances[name.to_s] ||= initializer.()
+        end
+        private name.to_s
+      end
+
+      def __uses_dependent_classes
+        @__uses_dependent_classes ||= {}
+      end
+    end
+
+    def __uses_dependent_instances
+      @__uses_dependent_instances ||= {}
+    end
+  end
+end

data/lib/uses/method_name.rb

@@ -0,0 +1,23 @@
+require_relative "invalid_method_name"
+module Uses
+  class MethodName
+
+    def self.derive_method_name(klass)
+      klass.name.to_s.underscore.gsub(/\//,"_")
+    end
+
+    def initialize(uses_method_args)
+      @name = if uses_method_args.method_name_override.nil?
+                self.class.derive_method_name(uses_method_args.klass_being_used)
+              else
+                uses_method_args.method_name_override.to_s
+              end
+        if @name !~ /^[a-z0-9_]+$/
+          raise Uses::InvalidMethodName.new("Cannot determine a default name for #{uses_method_args.klass_being_used} used by #{uses_method_args.klass_with_uses}. Use as: to specify the name")
+        end
+    end
+    def to_s
+      @name
+    end
+  end
+end

data/lib/uses/uses_method_args.rb

@@ -0,0 +1,24 @@
+module Uses
+  class UsesMethodArgs
+
+    attr_reader :klass_being_used,
+                :klass_with_uses,
+                :method_name_override,
+                :initializer_strategy,
+                :uses_config
+
+    def initialize(klass_being_used:,
+                   klass_with_uses:,
+                   method_name_override:,
+                   initializer_strategy:,
+                   uses_config:)
+
+      @klass_being_used     = klass_being_used
+      @klass_with_uses      = klass_with_uses
+      @method_name_override = method_name_override
+      @initializer_strategy = initializer_strategy
+      @uses_config          = uses_config
+
+    end
+  end
+end

data/lib/uses/version.rb

@@ -0,0 +1,3 @@
+module Uses
+  VERSION="1.0.0-beta1"
+end

data/lib/uses.rb

@@ -0,0 +1,49 @@
+module Uses
+  # Yields a hash of initializer, with the intention that you insert
+  # the initializer for your service into this hash. The key should be the class name
+  # that would be given to a `uses` invocation, and the value should be a proc
+  # that returns an instance of that class.
+  #
+  # The reason you would do this is if your service requires special setup beyond calling
+  # new without arguments.  For example:
+  #
+  #
+  #    require "uses"
+  #    Uses.initializers do |initializers|
+  #      initializers[Aws::S3::Client] = ->(*) {
+  #        Aws::S3::Client.new(
+  #          access_key_id: ENV["AWS_ACCESS_KEY_ID"],
+  #          secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"],
+  #          region: ENV["AWS_REGION"],
+  #       )
+  #      }
+  #    end
+  #
+  #    # Then, in a service that uses this:
+  #
+  #    class MyService
+  #      include Uses::Method
+  #
+  #      uses Aws::S3::Client, as: :s3, initialize: :config_initializers
+  #
+  #      def some_method
+  #        s3.whatever # s3 has been initialized using the Proc above
+  #      end
+  #    end
+  def self.initializers
+    yield(config.initializers) if block_given?
+    config.initializers
+  end
+
+  # Yields the Uses::Config instance governing this
+  # gem's behavior.  You should call this in an intializer.
+  # See Uses::Config for what options exist
+  def self.config
+    @@config ||= Uses::Config.new
+    yield(@@config) if block_given?
+    @@config
+  end
+
+end
+require_relative "uses/version"
+require_relative "uses/method"

data/uses.gemspec

@@ -0,0 +1,29 @@
+require_relative "lib/uses/version"
+
+Gem::Specification.new do |spec|
+  spec.name     = "uses"
+  spec.version  = Uses::VERSION
+  spec.authors  = ["Dave Copeland"]
+  spec.email    = ["davec@naildrivin5.com"]
+  spec.summary  = %q{Declare that one classes uses an instance of another to help your code be a bit more sustainable}
+  spec.homepage = "https://github.com/sustainable-rails/uses"
+  spec.license  = "Hippocratic"
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/sustainable-rails/uses"
+  spec.metadata["changelog_uri"] = "https://github.com/sustainable-rails/uses/releases"
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("activesupport")
+  spec.add_development_dependency("rspec")
+  spec.add_development_dependency("rspec_junit_formatter")
+  spec.add_development_dependency("confidence-check")
+end