inch 0.0.1 → 0.1.0

data/lib/inch/cli/command_parser.rb

@@ -0,0 +1,82 @@
+# This was adapted from https://github.com/lsegal/yard/blob/master/lib/yard/cli/command_parser.rb
+module Inch
+  module CLI
+    # This class parses a command name out of the +inch+ CLI command and calls
+    # that command in the form:
+    #
+    #   $ inch command_name [options]
+    #
+    # If no command or arguments are specified, or if the arguments immediately
+    # begin with a +--opt+ (not +--help+), the {default_command} will be used
+    # (which itself defaults to +:doc+).
+    #
+    class CommandParser
+      include TraceHelper
+
+      class << self
+        # @return [Hash{Symbol => Command}] the mapping of command names to
+        #   command classes to parse the user command.
+        attr_accessor :commands
+
+        # @return [Symbol] the default command name to use when no options
+        #   are specified or
+        attr_accessor :default_command
+      end
+
+      self.commands = {
+        :console => Command::Console,
+        :inspect => Command::Inspect,
+        :list => Command::List,
+        :show => Command::Show,
+        :stats => Command::Stats,
+        :suggest => Command::Suggest,
+      }
+
+      self.default_command = :suggest
+
+      # Convenience method to create a new CommandParser and call {#run}
+      # @return (see #run)
+      def self.run(*args)
+        new.run(*args)
+      end
+
+      def initialize
+        #log.show_backtraces = false
+      end
+
+      # Runs the {Command} object matching the command name of the first
+      # argument.
+      # @return [void]
+      def run(*args)
+        unless ['--help', '-h'].include?(args.join)
+          if args.size == 0 || args.first =~ /^-/
+            command_name = self.class.default_command
+          else
+            command_name = args.first.to_sym
+            args.shift
+          end
+          if commands.has_key?(command_name)
+            return commands[command_name].run(*args)
+          end
+        end
+        list_commands
+      end
+
+      private
+
+      def commands
+        self.class.commands
+      end
+
+      def list_commands
+        trace "Usage: inch <command> [options]"
+        trace
+        trace "Commands:"
+        commands.keys.sort_by {|k| k.to_s }.each do |command_name|
+          command = commands[command_name].new
+          trace "  %-8s %s" % [command_name, command.description]
+        end
+      end
+    end
+  end
+end

data/lib/inch/cli/sparkline_helper.rb

@@ -0,0 +1,31 @@
+module Inch
+  module CLI
+    module SparklineHelper
+      def ranges_sparkline(_ranges)
+        ranges = _ranges.reverse
+        list = ranges.map { |r| r.objects.size }
+        sparkline = Sparkr::Sparkline.new(list)
+        sparkline.format do |tick, count, index|
+          t = tick.color(ranges[index].color)
+          index == 0 ? t + ' ' : t
+        end
+      end
+
+      def grades_sparkline(objects)
+        grades = {}
+        objects.each do |o|
+          grades[o.grade] ||= 0
+          grades[o.grade] += 1
+        end
+        ranges = Evaluation.new_score_ranges.reverse
+        order = ranges.map(&:grade)
+        list = order.map { |g| grades[g] }
+        sparkline = Sparkr::Sparkline.new(list)
+        sparkline.format do |tick, count, index|
+          t = tick.color(ranges[index].color)
+          index == 0 ? t + ' ' : t
+        end
+      end
+    end
+  end
+end

data/lib/inch/cli/trace_helper.rb

@@ -0,0 +1,42 @@
+module Inch
+  module CLI
+    module TraceHelper
+      def debug(msg)
+        return unless ENV['DEBUG']
+        msg.to_s.lines.each do |line|
+          trace edged :dark, line.gsub(/\n$/,'').dark
+        end
+      end
+
+      # Writes the given +text+ to stdout
+      # @param text [String]
+      # @return [void]
+      def trace(text = "")
+        puts text
+      end
+
+      def trace_header(text, color, bg_color = nil)
+        trace header(text, color, bg_color)
+        trace if !use_color?
+      end
+
+      private
+
+      def edged(color, msg, edge = "┃ ")
+        edge.color(color) + msg
+      end
+
+      def header(text, color, bg_color = nil)
+        bg_color ||= "intense_#{color}"
+        bar = " #{text}".ljust(CLI::COLUMNS-1)
+                .on_color(bg_color).color(:color16)
+        "#".color(color).on_color(color) + bar
+      end
+
+      def use_color?
+        Term::ANSIColor::coloring?
+      end
+
+    end
+  end
+end

data/lib/inch/cli/yardopts_helper.rb

@@ -0,0 +1,49 @@
+module Inch
+  module CLI
+    module YardoptsHelper
+      # @return [Array<String>] list of Ruby source files to process
+      attr_accessor :yard_files
+
+      # @return [Array<String>] list of excluded paths (regexp matches)
+      attr_accessor :excluded
+
+      VALID_YARD_SWITCHES = %w(--private --no-private --protected --no-public
+          --plugin --load --safe --yardopts --no-yardopts --document --no-document)
+
+      # Parses the option and gracefully handles invalid switches
+      #
+      # @param [OptionParser] opts the option parser object
+      # @param [Array<String>] args the arguments passed from input. This
+      #   array will be modified.
+      # @return [void]
+      def parse_yardopts_options(opts, args)
+        wrapper = YardoptsWrapper.new()
+
+        dupped_args = args.dup
+        dupped_args.delete("--help")
+        dupped_args.delete_if do |arg|
+          arg =~ /^\-/ && !VALID_YARD_SWITCHES.include?(arg)
+        end
+
+        debug "Sending args to YARD:\n" \
+              "  args: #{dupped_args}"
+
+        wrapper.parse_arguments(*dupped_args)
+
+        self.yard_files = wrapper.files
+        self.excluded = wrapper.excluded
+      end
+
+      def yardopts_options(opts)
+        wrapper = YardoptsWrapper.new()
+        wrapper.add_yardoc_options(opts)
+      end
+
+      class YardoptsWrapper < YARD::CLI::Yardoc
+        def add_yardoc_options(opts)
+          yardopts_options(opts)
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object.rb

@@ -0,0 +1,8 @@
+module Inch
+  module CodeObject
+  end
+end
+
+require_relative 'code_object/docstring'
+require_relative 'code_object/nodoc_helper'
+require_relative 'code_object/proxy'

data/lib/inch/code_object/docstring.rb

@@ -0,0 +1,97 @@
+module Inch
+  module CodeObject
+    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.last =~ /^Returns\ /
+      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}::",
+          /^#{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)
+        mention_parameter_patterns(name).map do |pattern|
+          r = pattern.is_a?(Regexp) ? pattern : Regexp.escape(pattern)
+          /^#{r}\s?\S+/
+        end + 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

data/lib/inch/code_object/nodoc_helper.rb

@@ -0,0 +1,84 @@
+module Inch
+  module CodeObject
+    module NodocHelper
+
+      # Returns true if the code object is somehow marked not to be
+      # documented.
+      #
+      # @note Doesnot recognize ":startdoc:" and ":stopdoc:"
+      #
+      def nodoc?
+        object.tag(:private) || 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
+
+      def declarations
+        @declarations ||= files.map do |(filename, line_no)|
+          get_line_no(filename, line_no)
+        end
+      end
+
+      def files
+        object.files
+      rescue YARD::CodeObjects::ProxyMethodError
+        []
+      end
+
+      def get_line_no(filename, n)
+        f = File.open(filename)
+        n.times{f.gets}
+        result = $_
+        f.close
+        result
+      end
+    end
+  end
+end

data/lib/inch/code_object/proxy.rb

@@ -0,0 +1,37 @@
+module Inch
+  module CodeObject
+    module Proxy
+      class << self
+        def for(code_object)
+          @cache ||= {}
+          if proxy_object = @cache[cache_key(code_object)]
+            proxy_object
+          else
+            @cache[cache_key(code_object)] = class_for(code_object).new(code_object)
+          end
+        end
+
+        private
+
+        def class_for(code_object)
+          class_name = code_object.class.to_s.split('::').last
+          eval("::Inch::CodeObject::Proxy::#{class_name}")
+        rescue
+          Base
+        end
+
+        def cache_key(o)
+          o.path
+        end
+      end
+    end
+  end
+end
+
+require_relative 'proxy/base'
+require_relative 'proxy/namespace_object'
+require_relative 'proxy/class_object'
+require_relative 'proxy/constant_object'
+require_relative 'proxy/method_object'
+require_relative 'proxy/method_parameter_object'
+require_relative 'proxy/module_object'

data/lib/inch/code_object/proxy/base.rb

@@ -0,0 +1,194 @@
+require 'forwardable'
+
+module Inch
+  module CodeObject
+    module Proxy
+      class Base
+        extend Forwardable
+        include NodocHelper
+
+        # the actual (YARD) code object
+        attr_accessor :object
+
+        # @return [Symbol]
+        #   when objects are assigned to ScoreRanges, this grade is set to
+        #   enable easier querying for objects of a certain grade
+        attr_writer :grade
+
+        # Tags considered by wrapper methods like {#has_code_example?}
+        CONSIDERED_YARD_TAGS = %w(example param private return)
+
+        # convenient shortcuts to (YARD) code object
+        def_delegators :object, :type, :path, :name, :namespace, :source, :source_type, :signature, :group, :dynamic, :visibility, :docstring
+
+        # convenient shortcuts to evalution object
+        def_delegators :evaluation, :score, :roles, :priority
+
+        def initialize(object)
+          self.object = object
+        end
+
+        # To be overridden
+        # @see Proxy::NamespaceObject
+        # @return [Array,nil] the children of the current object or +nil+
+        def children
+          nil
+        end
+
+        def docstring
+          @docstring ||= Docstring.new(object.docstring)
+        end
+
+        def evaluation
+          @evaluation ||= Evaluation.for(self)
+        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.size > 0 ? files[0][0] : nil
+        end
+
+        def grade
+          @grade ||= Evaluation.new_score_ranges.detect { |range|
+                range.range.include?(score)
+              }.grade
+        end
+
+        def has_alias?
+          !object.aliases.empty?
+        end
+
+        def has_code_example?
+          !object.tags(:example).empty? ||
+            docstring.contains_code_example?
+        end
+
+        def has_doc?
+          !docstring.empty?
+        end
+
+        def has_multiple_code_examples?
+          if object.tags(:example).size > 1 || docstring.code_examples.size > 1
+            true
+          else
+            if tag = object.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_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
+
+        # In the following example, the height of +Foo+ is 3
+        # (the height of the top-level is 4):
+        #
+        #   Foo::Bar::Baz#initialize
+        #    ^    ^    ^      ^
+        #    0 >> 1 >> 2  >>  3
+        #
+        # +height+ answers the question "how many layers of code objects are
+        # underneath this one?"
+        #
+        # @param i [Fixnum] a counter for recursive method calls
+        # @return [Fixnum] the height of the object in terms of namespace
+        def height(i = 0)
+          if children && !children.empty?
+            children.map do |child|
+              child.height(i+1)
+            end.max
+          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
+
+        # @return [Array,nil] the parent of the current object or +nil+
+        def parent
+          Proxy.for(object.parent) if object.parent
+        end
+
+        def private?
+          visibility == :private
+        end
+
+        def private_tag?
+          !!object.tag(:private)
+        end
+
+        def protected?
+          visibility == :protected
+        end
+
+        def public?
+          visibility == :public
+        end
+
+        # @return [Boolean] +true+ if the object has no documentation at all
+        def undocumented?
+          docstring.empty? && object.tags.empty?
+        end
+
+        # @return [Array]
+        #   YARD tags that are not already covered by other wrapper methods
+        def unconsidered_tags
+          @unconsidered_tags ||= object.tags.reject do |tag|
+              CONSIDERED_YARD_TAGS.include?(tag.tag_name)
+            end
+        end
+
+        def inspect
+          "#<#{self.class.to_s}: #{path}>"
+        end
+
+        private
+
+        def multi_code_examples?(text)
+          text =~ /\b#{Regexp.escape(name)}[^_0-9\!\?]/
+        end
+      end
+    end
+  end
+end