inch 0.5.0.rc3 → 0.5.0.rc4

data/lib/inch/config/base.rb

@@ -4,49 +4,28 @@ module Inch
   # @see config/defaults.rb
   class Config
     class Base
+      attr_reader :language
 
-      def update(&block)
-        instance_eval(&block)
-      end
-
-      def development?
-        @development
+      def initialize(language)
+        @language = language.to_sym
       end
 
-      def development!
-        @development = true
+      def update(&block)
+        instance_eval(&block)
+        self
       end
 
       def codebase(&block)
-        @codebase ||= Config::Codebase.new
+        @codebase ||= Config::Codebase.new(@language)
         @codebase.update(&block) if block
         @codebase
       end
 
       def evaluation(&block)
-        @evaluation ||= Evaluation.new
+        @evaluation ||= Config::Evaluation.new(@language)
         @evaluation.update(&block) if block
         @evaluation
       end
-
-      class Evaluation
-        def update(&block)
-          instance_eval(&block)
-        end
-
-        def grade(symbol, &block)
-          ::Inch::Evaluation::Grade.grade(symbol, &block)
-        end
-
-        def priority(symbol, &block)
-          ::Inch::Evaluation::PriorityRange.priority_range(symbol, &block)
-        end
-
-        def schema(constant_name, &block)
-          constant = ::Inch::Evaluation::Proxy.const_get(constant_name)
-          constant.criteria(&block)
-        end
-      end
     end
   end
 end

data/lib/inch/config/codebase.rb

@@ -2,12 +2,15 @@ module Inch
   class Config
     # Stores the configuration for an individual single codebase
     class Codebase
-      attr_reader :included_files
-      attr_reader :excluded_files
+      attr_accessor :language
+      attr_accessor :included_files
+      attr_accessor :excluded_files
+      attr_accessor :read_dump_file
 
       YAML_FILE = ".inch.yml"
 
-      def initialize(included = nil, excluded = nil)
+      def initialize(language = :ruby, included = nil, excluded = nil)
+        @language = language
         @included_files = included || []
         @excluded_files = excluded || []
       end
@@ -22,13 +25,21 @@ module Inch
         YAML.load(File.read(yaml_file)) if File.exist?(yaml_file)
       end
 
+      # Update this Codebase config with the given block.
+      # @return [void]
       def update(&block)
         instance_eval(&block)
       end
 
+      # Search the given +dir+ for YAML_FILE and
+      # update this Codebase config with the contents if the file is found.
+      #
+      # @param dir [String] directory to search for the file
+      # @return [void]
       def update_via_yaml(dir)
-        if yaml = self.class.yaml(dir)
+        if (yaml = self.class.yaml(dir))
           Dir.chdir(dir) do
+            update_language yaml["language"]
             update_files yaml["files"]
           end
         end
@@ -42,6 +53,15 @@ module Inch
         @excluded_files.concat(files).flatten!
       end
 
+      # Sets the object provider (e.g. :YARD)
+      #
+      # @param sym [Symbol] the object provider
+      # @return [Symbol] the object provider
+      def object_provider(sym = nil)
+        return @object_provider if sym.nil?
+        @object_provider = sym
+      end
+
       private
 
       def expand_files(files)
@@ -57,9 +77,14 @@ module Inch
 
       def update_files(files)
         return if files.nil?
-        include_files expand_files(files["included"]) if files["included"]
-        exclude_files expand_files(files["excluded"]) if files["excluded"]
+        @included_files = expand_files(files["included"]) if files["included"]
+        @excluded_files = expand_files(files["excluded"]) if files["excluded"]
+      end
+
+      def update_language(language)
+        return if language.nil?
+        @language = language
       end
     end
   end
-end
+end

data/lib/inch/config/evaluation.rb

@@ -0,0 +1,61 @@
+module Inch
+  class Config
+    class Evaluation
+      def initialize(language)
+        @language = language
+        @criteria_blocks = {}
+      end
+
+      def update(&block)
+        instance_eval(&block)
+      end
+
+      def grade(symbol, &block)
+        ::Inch::Evaluation::Grade.grade(symbol, &block)
+      end
+
+      def priority(symbol, &block)
+        ::Inch::Evaluation::PriorityRange.priority_range(symbol, &block)
+      end
+
+      def schema(constant_name, &block)
+        @criteria_blocks[constant_name.to_s] = Criteria.new(&block)
+      end
+
+      def criteria_for(constant_name)
+        @criteria_blocks[constant_name.to_s]
+      end
+
+      # An Criteria describes how important certain parts of the docs are
+      # for the associated Object
+      class Criteria
+        extend Utils::ReadWriteMethods
+
+        rw_methods %w(
+          docstring
+          parameters
+          return_type
+          return_description
+          code_example_single
+          code_example_multi
+          unconsidered_tag
+        )
+
+        attr_reader :object
+
+        def initialize(&block)
+          @block = block
+        end
+
+        def evaluate(object)
+          @object = object
+          instance_eval(&@block)
+          # we are "deleting" the block/Proc here because it can't be
+          # serialized by Marshal
+          # TODO: find a nicer way to achieve this
+          @block = nil
+        end
+      end
+    end
+  end
+end

data/lib/inch/core_ext.rb

@@ -1 +1 @@
-require 'inch/core_ext/string'
+require "inch/core_ext/string"

data/lib/inch/core_ext/string.rb

@@ -1,3 +1,3 @@
-require 'term/ansicolor'
+require "term/ansicolor"
 
 String.send(:include, Term::ANSIColor)

data/lib/inch/evaluation.rb

@@ -2,34 +2,26 @@ module Inch
   # The Evaluation module concerns itself with the evaluation of code objects
   # with regard to their inline code documentation
   module Evaluation
-    def self.for(code_object)
-      class_for(code_object).new(code_object)
+    def self.for(language, code_object)
+      class_for(language, code_object).new(code_object)
     end
 
     private
 
-    def self.class_for(code_object)
-      class_name = code_object.class.to_s.split('::').last
-      const_get(class_name)
+    def self.class_for(language, code_object)
+      class_name = code_object.class.to_s.split("::").last
+      language_namespace = Evaluation::Ruby
+      language_namespace.const_get(class_name)
     end
   end
 end
 
-require 'inch/utils/read_write_methods'
+require "inch/utils/read_write_methods"
 
-require 'inch/evaluation/file'
-require 'inch/evaluation/grade'
-require 'inch/evaluation/grade_list'
-require 'inch/evaluation/object_schema'
-require 'inch/evaluation/priority_range'
+require "inch/evaluation/file"
+require "inch/evaluation/grade"
+require "inch/evaluation/grade_list"
+require "inch/evaluation/priority_range"
 
-require 'inch/evaluation/role/base'
-require 'inch/evaluation/role/missing'
-require 'inch/evaluation/role/object'
-require 'inch/evaluation/role/method'
-require 'inch/evaluation/role/method_parameter'
-require 'inch/evaluation/role/namespace'
-require 'inch/evaluation/role/constant'
-require 'inch/evaluation/role/class_variable'
-
-require 'inch/evaluation/proxy'
+require "inch/evaluation/proxy"
+require "inch/evaluation/role"

data/lib/inch/evaluation/file.rb

@@ -1,5 +1,7 @@
 module Inch
   module Evaluation
+    # Evaluation::File is used in the Suggest API/CLI to determine
+    # the importance of files
     class File
       attr_accessor :filename, :objects
 
@@ -16,7 +18,7 @@ module Inch
       end
 
       #
-      # grade, priority, and score are not meant to be displayed in the CLI
+      # grade, priority and score are not meant to be displayed in the CLI
       # they are just for internal evaluation purposes
       #
 
@@ -50,7 +52,7 @@ module Inch
       class << self
         def for(filename, objects)
           @cache ||= {}
-          if file = @cache[filename]
+          if (file = @cache[filename])
             file
           else
             @cache[filename] = new(filename, objects)

data/lib/inch/evaluation/grade_list.rb

@@ -6,16 +6,16 @@ module Inch
     class GradeList < Struct.new(:grade)
       extend Forwardable
 
-      def_delegators :grade, :scores, :label, :color, :bg_color,
-                              :to_s, :to_sym
+      def_delegators :grade,
+                     :scores, :label, :color, :bg_color, :to_s, :to_sym
 
       # Returns code_objects that received a score with the defined +scores+
       attr_reader :objects
 
       # Assigns code_objects that received a score with the defined +scores+
       #
-      # @param arr [Array<CodeObject::Proxy::Base>]
-      # @return [Array<CodeObject::Proxy::Base>]
+      # @param arr [Array<CodeObject::Proxy>]
+      # @return [Array<CodeObject::Proxy>]
       def objects=(arr)
         arr.each { |o| o.grade = grade }
         @objects = arr

data/lib/inch/evaluation/priority_range.rb

@@ -1,5 +1,8 @@
 module Inch
   module Evaluation
+    # PriorityRange objects are used to associate a given
+    # range of priorities with a symbol and an arrow.
+    #
     class PriorityRange
       extend Utils::ReadWriteMethods
       extend Forwardable

data/lib/inch/evaluation/proxy.rb

@@ -2,25 +2,150 @@ module Inch
   # The Evaluation module concerns itself with the evaluation of code objects
   # with regard to their inline code documentation
   module Evaluation
-    module Proxy
-      def self.for(code_object)
-        class_for(code_object).new(code_object)
+    # Base class for evaluations. This class provides the evaluation's
+    # process structure.
+    #
+    # @abstract
+    class Proxy
+      # Returns a Proxy object for the given +code_object+
+      #
+      # @param language [String,Symbol]
+      # @param object [Codebase::Object]
+      # @return [Evaluation::Proxy]
+      def self.for(language, object)
+        class_for(language, object.code_object).new(object)
+      end
+
+      extend Forwardable
+
+      MIN_SCORE = 0
+      MAX_SCORE = 100
+
+      # @return [Codebase::Object]
+      attr_reader :object
+
+      # @return [Array<Evaluation::Role::Base>]
+      attr_reader :roles
+
+      # @param object [Codebase::Object]
+      def initialize(object)
+        @object = object
+        evaluation_config = Config.for(object.language).evaluation
+        @criteria = eval_criteria(evaluation_config)
+        @roles = []
+        evaluate
+      end
+
+      # Evaluates the objects and assigns roles
+      # @note This is its own method so it can be overridden.
+      # @return [void]
+      def evaluate
+        __evaluate(object, relevant_roles)
+      end
+
+      # @return [Float] the max score that is assignable to +object+
+      def max_score
+        @__max_score = __max_score
+      end
+
+      # @return [Float] the min score that is assignable to +object+
+      def min_score
+        @__min_score = __min_score
+      end
+
+      # @return [Fixnum] the final score for +object+
+      def score
+        @__score ||= __score
+      end
+
+      # @return [Fixnum] the priority for +object+
+      def priority
+        @__priority ||= __priority
+      end
+
+      protected
+
+      def add_role(role)
+        @roles << role
+      end
+
+      # Evaluates a Criteria object with the object so that it can
+      # give us scores for docstring, return_type, etc.
+      #
+      # @param config [Config::Evaluation]
+      # @return [Evaluation::Criteria]
+      def eval_criteria(config)
+        object_type = self.class.to_s.split('::').last
+        c = config.criteria_for(object_type)
+        c.evaluate(object)
+        c
+      end
+
+      # Returns a key-value pair of Role classes and potential scores for
+      # each role (can be nil)
+      #
+      # @see #evaluate
+      # @return [Hash]
+      def relevant_roles
+        {}
+      end
+
+      # Returns a score for a given criterion.
+      #
+      # @param criterion_name [String] e.g. 'docstring' or 'return_type'
+      # @return [Float]
+      def score_for(criterion_name)
+        @criteria.send(criterion_name) * MAX_SCORE
+      end
+
+      # Iterates over the given +role_classes+ and assigns the individual
+      # roles, if applicable.
+      #
+      # @param object [Codebase::Object]
+      # @param role_classes [Hash]
+      # @return [void]
+      def __evaluate(object, role_classes)
+        role_classes.each do |role_class, score|
+          next unless role_class.applicable?(object)
+          add_role role_class.new(object, score)
+        end
+      end
+
+      # @return [Float] the max score that is assignable to +object+
+      def __max_score
+        arr = @roles.map(&:max_score).compact
+        [MAX_SCORE].concat(arr).min
+      end
+
+      # @return [Float] the max score that is assignable to +object+
+      def __min_score
+        arr = @roles.map(&:min_score).compact
+        [MIN_SCORE].concat(arr).max
+      end
+
+      # @return [Float]
+      def __score
+        value = @roles.reduce(0) { |sum, r| sum + r.score.to_f }.to_i
+        if value < min_score
+          min_score
+        elsif value > max_score
+          max_score
+        else
+          value
+        end
+      end
+
+      # @return [Fixnum]
+      def __priority
+        @roles.reduce(0) { |sum, r| sum + r.priority.to_i }
       end
 
       private
 
-      def self.class_for(code_object)
-        class_name = code_object.class.to_s.split('::').last
-        const_get(class_name)
+      def self.class_for(language, code_object)
+        class_name = code_object.class.to_s.split("::").last
+        Config.namespace(language, :Evaluation).const_get(class_name)
       end
     end
   end
 end
-
-require 'inch/evaluation/proxy/base'
-require 'inch/evaluation/proxy/namespace_object'
-require 'inch/evaluation/proxy/class_object'
-require 'inch/evaluation/proxy/class_variable_object'
-require 'inch/evaluation/proxy/constant_object'
-require 'inch/evaluation/proxy/method_object'
-require 'inch/evaluation/proxy/module_object'