inch 0.2.3 → 0.3.0.rc1

data/lib/inch/code_object.rb

@@ -3,6 +3,6 @@ module Inch
   end
 end
 
-require_relative 'code_object/docstring'
-require_relative 'code_object/nodoc_helper'
+require_relative 'code_object/converter'
+require_relative 'code_object/provider'
 require_relative 'code_object/proxy'

data/lib/inch/code_object/converter.rb

@@ -0,0 +1,89 @@
+module Inch
+  module CodeObject
+    # The Converter takes code object representations from a provider and
+    # converts them into attributes hashes.
+    # These attributes can then be used to initialize a CodeObject::Proxy.
+    #
+    # @see CodeObject::Proxy.for
+    module Converter
+      OBJECT_ATTRIBUTES = %w(
+        name
+        fullname
+        files
+        filename
+
+        children_fullnames
+        parent_fullname
+
+        api_tag?
+        attributes
+        bang_name?
+        constant?
+        constructor?
+        depth
+        docstring
+        getter?
+        has_alias?
+        has_children?
+        has_code_example?
+        has_doc?
+        has_multiple_code_examples?
+        has_unconsidered_tags?
+        method?
+        nodoc?
+        namespace?
+        overridden?
+        overridden_method_fullname
+        parameters
+        private?
+        private_api_tag?
+        private_tag?
+        protected?
+        public?
+        questioning_name?
+        return_described?
+        return_mentioned?
+        return_typed?
+        in_root?
+        setter?
+        source
+        unconsidered_tag_count
+        undocumented?
+        visibility
+        ).map(&:to_sym)
+
+      PARAMETER_ATTRIBUTES = %w(
+        name
+        block?
+        described?
+        mentioned?
+        splat?
+        typed?
+        wrongly_mentioned?
+        ).map(&:to_sym)
+
+      # Returns an attributes Hash for a given code object
+      #
+      # @param o [Provider::YARD::Object::Base]
+      # @return [Hash]
+      def self.to_hash(o)
+        attributes = {}
+        OBJECT_ATTRIBUTES.each do |name|
+          if o.respond_to?(name)
+            attributes[name] = o.method(name).call
+          end
+        end
+        attributes[:parameters] = o.parameters.map do |parameter|
+          hash = {}
+          PARAMETER_ATTRIBUTES.each do |pname|
+            if parameter.respond_to?(pname)
+              hash[pname] = parameter.method(pname).call
+            end
+          end
+          hash
+        end
+        attributes
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider.rb

@@ -0,0 +1,36 @@
+module Inch
+  module CodeObject
+    # Provider modules "provide" a Codebase object with code objects.
+    # They are the intermediary between the raw representation that tools
+    # like YARD deliver and the "interface" that Inch expects.
+    #
+    # YARD Example:
+    #
+    # YARD's SourceParser returns ::YARD::CodeObject objects, which are
+    # cast to Provider::YARD::Object::Base objects that can ensure naming
+    # conventions et al. follow certain rules. These objects are then again
+    # converted into CodeObject::Proxy::Base objects that form the codebase:
+    #
+    #                        ::YARD::CodeObject
+    #                               ↓
+    #           ::Inch::CodeObject::Provider::YARD::Object::Base
+    #                               ↓
+    #                             (Hash)
+    #                               ↓
+    #                   ::Inch::CodeObject::Proxy::Base
+    #
+    #
+    module Provider
+      def self.parse(dir, paths, excluded, type = :YARD)
+        provider_for(type).parse(dir, paths, excluded)
+      end
+
+      # @return [Module]
+      def self.provider_for(type)
+        eval("::Inch::CodeObject::Provider::#{type}")
+      end
+    end
+  end
+end
+
+require_relative 'provider/yard'

data/lib/inch/code_object/provider/yard.rb

@@ -0,0 +1,19 @@
+module Inch
+  module CodeObject
+    module Provider
+      # Parses the source tree (using YARD)
+      module YARD
+
+        def self.parse(dir, paths, excluded)
+          Parser.parse(dir, paths, excluded)
+        end
+
+      end
+    end
+  end
+end
+
+require_relative 'yard/parser'
+require_relative 'yard/docstring'
+require_relative 'yard/nodoc_helper'
+require_relative 'yard/object'

data/lib/inch/code_object/provider/yard/docstring.rb

@@ -0,0 +1,106 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        class Docstring
+          def initialize(text)
+            @text = text.to_s
+          end
+
+          def empty?
+            @text.strip.empty?
+          end
+
+          def contains_code_example?
+            !code_examples.empty?
+          end
+
+          def code_examples
+            @code_examples ||= parse_code_examples
+          end
+
+          def describes_parameter?(name)
+            describe_parameter_regexps(name).any? do |pattern|
+              @text.index(pattern)
+            end
+          end
+
+          def mentions_parameter?(name)
+            mention_parameter_regexps(name).any? do |pattern|
+              @text.index(pattern)
+            end
+          end
+
+          def mentions_return?
+            @text.lines.to_a.last =~ /^Returns\ /
+          end
+
+          def describes_return?
+            @text.lines.to_a.last =~ /^Returns\ (\w+\s){2,}/
+          end
+
+          def parse_code_examples
+            code_examples = []
+            example = nil
+            @text.lines.each_with_index do |line, index|
+              if line =~/^\s*+$/
+                code_examples << example if example
+                example = []
+              elsif line =~/^\ {2,}\S+/
+                example << line if example
+              else
+                code_examples << example if example
+                example = nil
+              end
+            end
+            code_examples << example if example
+            code_examples.delete_if(&:empty?).map(&:join)
+          end
+
+          private
+
+          def mention_parameter_patterns(name)
+            [
+              "+#{name}+",
+              "+#{name}+::",
+              "<tt>#{name}</tt>",
+              "<tt>#{name}</tt>::",
+              "#{name}::",
+              /^#{Regexp.escape(name)}\ \-\ /
+            ]
+          end
+
+          def describe_parameter_extra_regexps(name)
+            [
+              "#{name}::",
+              "+#{name}+::",
+              "<tt>#{name}</tt>::",
+            ].map do |pattern|
+              r = pattern.is_a?(Regexp) ? pattern : Regexp.escape(pattern)
+              /#{r}\n\ {2,}.+/m
+            end
+          end
+
+          def describe_parameter_regexps(name)
+            same_line_regexps = mention_parameter_patterns(name).map do |pattern|
+              r = pattern.is_a?(Regexp) ? pattern : Regexp.escape(pattern)
+              /^#{r}\s?\S+/
+            end
+            same_line_regexps + describe_parameter_extra_regexps(name)
+          end
+
+          def mention_parameter_regexps(name)
+            mention_parameter_patterns(name).map do |pattern|
+              if pattern.is_a?(Regexp)
+                pattern
+              else
+                r = Regexp.escape(pattern)
+                /\W#{r}\W/
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/nodoc_helper.rb

@@ -0,0 +1,93 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module NodocHelper
+
+          # Returns true if the code object is somehow marked not to be
+          # documented.
+          #
+          # @note Doesnot recognize ":startdoc:" and ":stopdoc:"
+          #
+          def nodoc?
+            private_tag? || nodoc_comment?
+          end
+
+          NO_DOC_REGEX = /#\s*\:nodoc\:/
+          NO_DOC_ALL_REGEX = /#\s*\:nodoc\:\s*all/
+          DOC_REGEX = /#\s*\:doc\:/
+
+          def nodoc_comment?
+            explicit_nodoc_comment? || implicit_nodoc_comment?
+          end
+
+          def explicit_nodoc_comment?
+            declarations.any? { |str| str =~ NO_DOC_REGEX }
+          end
+
+          def explicit_nodoc_all_comment?
+            declarations.any? { |str| str =~ NO_DOC_ALL_REGEX }
+          end
+
+          def explicit_doc_comment?
+            declarations.any? { |str| str =~ DOC_REGEX }
+          end
+
+          def implicit_nodoc_all_comment?
+            if parent
+              parent.explicit_nodoc_all_comment? ||
+                parent.implicit_nodoc_all_comment?
+            end
+          end
+
+          def implicit_nodoc_comment?
+            return false if explicit_doc_comment?
+
+            if parent
+              return false if parent.explicit_doc_comment?
+
+              if namespace?
+                if parent.explicit_nodoc_all_comment?
+                  return true
+                else
+                  return parent.implicit_nodoc_all_comment?
+                end
+              else
+                if parent.explicit_nodoc_comment?
+                  return true
+                else
+                  return parent.implicit_nodoc_all_comment?
+                end
+              end
+            end
+          end
+
+          # Returns all lines in all files declaring the object
+          #
+          # @example
+          #   declarations # => ["class Base # :nodoc:", "class Foo < Base"]
+          #
+          # @return [Array<String>]
+          def declarations
+            @declarations ||= files.map do |f|
+              get_line_no(f.filename, f.line_no)
+            end
+          end
+
+          # Returns a +line_number+ from a file
+          #
+          # @param filename [String]
+          # @param line_number [Fixnum]
+          # @return [String]
+          def get_line_no(filename, line_number)
+            f = File.open(filename)
+            line_number.times{f.gets}
+            result = $_
+            f.close
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object.rb

@@ -0,0 +1,55 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        # CodeObject::Provider::YARD::Object object represent code objects.
+        #
+        module Object
+          class << self
+            # Returns a Proxy object for the given +yard_object+
+            #
+            # @param yard_object [YARD::CodeObject]
+            # @return [Provider::YARD::Object]
+            def for(yard_object)
+              @cache ||= {}
+              if proxy_object = @cache[cache_key(yard_object)]
+                proxy_object
+              else
+                @cache[cache_key(yard_object)] = class_for(yard_object).new(yard_object)
+              end
+            end
+
+            private
+
+            # Returns a Proxy class for the given +yard_object+
+            #
+            # @param yard_object [YARD::CodeObject]
+            # @return [Class]
+            def class_for(yard_object)
+              class_name = yard_object.class.to_s.split('::').last
+              eval("::Inch::CodeObject::Provider::YARD::Object::#{class_name}")
+            rescue
+              Base
+            end
+
+            # Returns a cache key for the given +yard_object+
+            #
+            # @param yard_object [YARD::CodeObject]
+            # @return [String]
+            def cache_key(yard_object)
+              yard_object.path
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'object/base'
+require_relative 'object/namespace_object'
+require_relative 'object/class_object'
+require_relative 'object/constant_object'
+require_relative 'object/method_object'
+require_relative 'object/method_parameter_object'
+require_relative 'object/module_object'

data/lib/inch/code_object/provider/yard/object/base.rb

@@ -0,0 +1,262 @@
+require 'forwardable'
+
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          # @abstract
+          class Base
+            extend Forwardable
+            include YARD::NodocHelper
+
+            # @return [YARD::CodeObjects::Base] the actual (YARD) code object
+            attr_reader :object
+
+            # @return [String] the codebase's directory
+            attr_accessor :base_dir
+
+            # Tags considered by wrapper methods like {#has_code_example?}
+            CONSIDERED_YARD_TAGS = %w(api example param private return)
+
+            # convenient shortcuts to (YARD) code object
+            def_delegators :object, :type, :namespace, :source, :source_type, :signature, :group, :dynamic, :visibility
+
+            # @param object [YARD::CodeObjects::Base] the actual (YARD) code object
+            def initialize(object)
+              @object = object
+            end
+
+            def api_tag?
+              !api_tag.nil?
+            end
+
+            def api_tag
+              tag(:api) || (parent && parent.api_tag)
+            end
+
+            # To be overridden
+            # @see Proxy::NamespaceObject
+            # @return [CodeObject::Proxy::Base,nil] the child inside the current object or +nil+
+            def child(name)
+              nil
+            end
+
+            # @return [Array,nil] the full names of the children of the current object
+            def children_fullnames
+              []
+            end
+
+            # To be overridden
+            # @see Proxy::NamespaceObject
+            def children
+              []
+            end
+
+            RUBY_CORE = %w(Array Bignum BasicObject Object Module Class Complex NilClass Numeric String Float Fiber FiberError Continuation Dir File Encoding Enumerator StopIteration Enumerator::Generator Enumerator::Yielder Exception SystemExit SignalException Interrupt StandardError TypeError ArgumentError IndexError KeyError RangeError ScriptError SyntaxError LoadError NotImplementedError NameError NoMethodError RuntimeError SecurityError NoMemoryError EncodingError SystemCallError Encoding::CompatibilityError File::Stat IO Hash ENV IOError EOFError ARGF RubyVM RubyVM::InstructionSequence Math::DomainError ZeroDivisionError FloatDomainError Integer Fixnum Data TrueClass FalseClass Mutex Thread Proc LocalJumpError SystemStackError Method UnboundMethod Binding Process::Status Random Range Rational RegexpError Regexp MatchData Symbol Struct ThreadGroup ThreadError Time Encoding::UndefinedConversionError Encoding::InvalidByteSequenceError Encoding::ConverterNotFoundError Encoding::Converter RubyVM::Env) +
+                      %w(Comparable Kernel File::Constants Enumerable Errno FileTest GC ObjectSpace GC::Profiler IO::WaitReadable IO::WaitWritable Marshal Math Process Process::UID Process::GID Process::Sys Signal)
+            def core?
+              RUBY_CORE.include?(name.to_s)
+            end
+
+            # @return [Docstring]
+            def docstring
+              @docstring ||= Docstring.new(object.docstring)
+            end
+
+            # Returns all files declaring the object in the form of an Array of
+            # Arrays containing the filename and the line number of their
+            # declaration.
+            #
+            # @example
+            #   files # => [["lib/inch.rb", 3],
+            #                ["lib/inch/cli.rb", 1],
+            #                 ["lib/inch/version.rb", 1],
+            #
+            # @return [Array<Array(String, Fixnum)>]
+            def files
+              object.files.map do |(filename, line_no)|
+                CodeLocation.new(base_dir, filename, line_no)
+              end
+            rescue ::YARD::CodeObjects::ProxyMethodError
+              # this error is raised by YARD
+              # see broken.rb in test fixtures
+              []
+            end
+
+            # CodeLocation is a utility class to find declarations of objects in files
+            class CodeLocation < Struct.new(:base_dir, :relative_path, :line_no)
+              def filename
+                File.join(base_dir, relative_path)
+              end
+            end
+
+            # Returns the name of the file where the object is declared first
+            # @return [String] a filename
+            def filename
+              # just checking the first file (which is the file where an object
+              # is first declared)
+              files.first && files.first.filename
+            end
+
+            def fullname
+              object.path
+            end
+
+            def name
+              object.name
+            end
+
+            def has_alias?
+              false
+            end
+
+            def has_children?
+              !children.empty?
+            end
+
+            def has_code_example?
+              !tags(:example).empty? ||
+                docstring.contains_code_example?
+            end
+
+            def has_doc?
+              !docstring.empty?
+            end
+
+            def has_multiple_code_examples?
+              if tags(:example).size > 1 || docstring.code_examples.size > 1
+                true
+              else
+                if tag = tag(:example)
+                  multi_code_examples?(tag.text)
+                elsif text = docstring.code_examples.first
+                  multi_code_examples?(text)
+                else
+                  false
+                end
+              end
+            end
+
+            def has_unconsidered_tags?
+              !unconsidered_tags.empty?
+            end
+
+            def in_in_root?
+              depth == 1
+            end
+
+            # The depth of the following is 4:
+            #
+            #   Foo::Bar::Baz#initialize
+            #    ^    ^    ^      ^
+            #    1 << 2 << 3  <<  4
+            #
+            # +depth+ answers the question "how many layers of code objects are
+            # above this one?"
+            #
+            # @note top-level counts, that's why Foo has depth 1!
+            #
+            # @param i [Fixnum] a counter for recursive method calls
+            # @return [Fixnum] the depth of the object in terms of namespace
+            def depth(i = 0)
+              if parent
+                parent.depth(i+1)
+              else
+                i
+              end
+            end
+
+            # @return [Boolean] +true+ if the object represents a method
+            def method?
+              false
+            end
+
+            # @return [Boolean] +true+ if the object represents a namespace
+            def namespace?
+              false
+            end
+
+            def parameters
+              []
+            end
+
+            # @return [Array,nil] the parent of the current object or +nil+
+            def parent
+              YARD::Object.for(object.parent) if object.parent
+            end
+
+            def private?
+              visibility == :private
+            end
+
+            # @return [Boolean]
+            #   +true+ if the object or its parent is tagged as @private
+            def private_tag?
+              !private_tag.nil?
+            end
+
+            def private_tag
+              tag(:private) || (parent && parent.private_tag)
+            end
+
+            def private_api_tag?
+              api_tag && api_tag.text == 'private'
+            end
+
+            def protected?
+              visibility == :protected
+            end
+
+            def public?
+              visibility == :public
+            end
+
+            def in_root?
+              depth == 1
+            end
+
+            # @return [Boolean] +true+ if the object has no documentation at all
+            def undocumented?
+              docstring.empty? && tags.empty?
+            end
+
+            def unconsidered_tag_count
+              unconsidered_tags.size
+            end
+
+            def inspect
+              "#<#{self.class.to_s}: #{path}>"
+            end
+
+            protected
+
+            def multi_code_examples?(text)
+              text.scan(/\b(#{Regexp.escape(name)})[^_0-9\!\?]/m).size > 1
+            end
+
+            def tag(name)
+              tags(name).first
+            end
+
+            def tags(name = nil)
+              object.tags(name)
+            rescue ::YARD::CodeObjects::ProxyMethodError
+              # this error is raised by YARD
+              # see broken.rb in test fixtures
+              []
+            end
+
+            # @return [Array]
+            #   YARD tags that are not already covered by other wrapper methods
+            def unconsidered_tags
+              @unconsidered_tags ||= tags.reject do |tag|
+                  CONSIDERED_YARD_TAGS.include?(tag.tag_name)
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end