ruby-lint 0.0.4 → 0.0.5

data/lib/ruby-lint/docstring/mapping.rb

@@ -0,0 +1,55 @@
+module RubyLint
+  module Docstring
+    ##
+    # {RubyLint::Docstring::Mapping} is a small data container for storing
+    # docstring tags separately and optionally by their names (e.g. for
+    # parameter tags).
+    #
+    # @!attribute [r] param_tags
+    #  @return [Hash]
+    #
+    # @!attribute [r] return_tag
+    #  @return [RubyLint::Docstring::ReturnTag]
+    #
+    class Mapping
+      attr_reader :param_tags, :return_tag
+
+      ##
+      # Hash containing the known tag classes and their callback methods.
+      #
+      # @return [Hash]
+      #
+      TAG_METHODS = {
+        ParamTag  => :on_param_tag,
+        ReturnTag => :on_return_tag
+      }
+
+      ##
+      # @param [Array] tags
+      #
+      def initialize(tags = [])
+        @param_tags = {}
+
+        tags.each do |tag|
+          send(TAG_METHODS[tag.class], tag)
+        end
+      end
+
+      private
+
+      ##
+      # @param [RubyLint::Docstring::ParamTag] tag
+      #
+      def on_param_tag(tag)
+        @param_tags[tag.name] = tag
+      end
+
+      ##
+      # @param [RubyLint::Docstring::ReturnTag] tag
+      #
+      def on_return_tag(tag)
+        @return_tag = tag
+      end
+    end # Mapping
+  end # Docstring
+end # RubyLint

data/lib/ruby-lint/docstring/param_tag.rb

@@ -0,0 +1,29 @@
+module RubyLint
+  module Docstring
+    ##
+    # The ParamTag class contains information about YARD `@param` tags such as
+    # the types of the parameter.
+    #
+    # @!attribute [r] name
+    #  @return [String]
+    #
+    # @!attribute [r] types
+    #  @return [Array]
+    #
+    # @!attribute [r] description
+    #  @return [String]
+    #
+    class ParamTag
+      attr_reader :name, :types, :description
+
+      ##
+      # @param [Hash] options
+      #
+      def initialize(options = {})
+        @name        = options[:name]
+        @types       = options[:types] || []
+        @description = options[:description]
+      end
+    end # ParamTag
+  end # Docstring
+end # RubyLint

data/lib/ruby-lint/docstring/parser.rb

@@ -0,0 +1,133 @@
+module RubyLint
+  module Docstring
+    ##
+    # {RubyLint::Docstring::Parser} parses a collection of Ruby source comments
+    # and tries to extract various YARD tags out of them. These tags can then
+    # be used as extra information for building definitions (e.g. the arguments
+    # of a method definition).
+    #
+    class Parser
+      ##
+      # Regexp used to get rid of leading `#` markers. This makes the regular
+      # expressions used for tags a little bit easier.
+      #
+      # @return [Regexp]
+      #
+      COMMENT_REGEXP = /^#+\s*/
+
+      ##
+      # The character used for separating types in a tag.
+      #
+      # @return [String]
+      #
+      TYPE_SEPARATOR = '|'
+
+      ##
+      # Hash containing regular expressions and their corresponding callback
+      # methods.
+      #
+      # @return [Hash]
+      #
+      KNOWN_TAGS = {
+        # Matches: @param [Type] name description
+        # Matches: @param [Type<Value>] name description
+        /^@param\s+\[(.+)\]\s+(\S+)\s*(.+)*/ => :on_param_with_type,
+
+        # Matches: @param name description
+        /^@param\s+(\S+)\s*(.+)*/ => :on_param,
+
+        # Matches: @return [Type] description
+        /^@return\s+\[(.+)\]\s*(.+)*/ => :on_return_with_type,
+
+        # Matches; @return description
+        /^@return\s+(.+)/ => :on_return,
+      }
+
+      ##
+      # Parses an Array of comments and returns a collection of docstring tags.
+      #
+      # @param [Array] comments
+      # @return [Array]
+      #
+      def parse(comments)
+        tags = []
+
+        comments.each do |comment|
+          comment = comment.gsub(COMMENT_REGEXP, '').strip
+
+          KNOWN_TAGS.each do |regexp, method|
+            matchdata = comment.match(regexp)
+
+            if matchdata
+              retval = send(method, *matchdata.captures)
+
+              if retval
+                tags << retval
+                break
+              end
+            end
+          end
+        end
+
+        return tags
+      end
+
+      private
+
+      ##
+      # Processes a `@param` tag without a given type.
+      #
+      # @param [String] name The name of the argument.
+      # @param [String] description The description of the argument.
+      # @return [RubyLint::Docstring::ParamTag]
+      #
+      def on_param(name, description)
+        return ParamTag.new(:name => name, :description => description)
+      end
+
+      ##
+      # Processes a `@param` tag with a set of types specified.
+      #
+      # @param [String] types The argument types.
+      # @see #on_param
+      #
+      def on_param_with_type(types, name, description)
+        # The inner values of compound types are ignored since ruby-lint
+        # doesn't have the means to store this information.
+        types = types.split(TYPE_SEPARATOR).map do |type|
+          type.gsub(/<.+>/, '')
+        end
+
+        return ParamTag.new(
+          :name        => name,
+          :description => description,
+          :types       => types
+        )
+      end
+
+      ##
+      # Processes a `@return` tag with just the description.
+      #
+      # @param [String] description
+      # @return [RubyLint::Docstring::ReturnTag]
+      #
+      def on_return(description)
+        return ReturnTag.new(:description => description)
+      end
+
+      ##
+      # Processes a `@return` tag with the type and description.
+      #
+      # @param [String] types The return types.
+      # @param [String] description
+      # @return [RubyLint::Docstring::ReturnTag]
+      #
+      def on_return_with_type(types, description)
+        return ReturnTag.new(
+          :description => description,
+          :types       => types.split(TYPE_SEPARATOR)
+        )
+      end
+    end # DocstringParser
+  end # Docstring
+end # RubyLint

data/lib/ruby-lint/docstring/return_tag.rb

@@ -0,0 +1,24 @@
+module RubyLint
+  module Docstring
+    ##
+    # The ReturnTag class contains information about a YARD `@return` tag.
+    #
+    # @!attribute [r] types
+    #  @return [Array]
+    #
+    # @!attribute [r] description
+    #  @return [String]
+    #
+    class ReturnTag
+      attr_reader :types, :description
+
+      ##
+      # @param [Hash] options
+      #
+      def initialize(options = {})
+        @types       = options[:types] || []
+        @description = options[:description]
+      end
+    end # ReturnTag
+  end # Docstring
+end # RubyLint

data/lib/ruby-lint/file_loader.rb

@@ -0,0 +1,96 @@
+module RubyLint
+  ##
+  # {RubyLint::FileLoader} iterates over an AST and given a constant node will
+  # try to find the corresponding filepath using {RubyLint::FileScanner}.
+  #
+  # ## Options
+  #
+  # The following options must be set when creating an instance of this class:
+  #
+  # * `:directories`: the directories to scan for files.
+  # * `:ignore_paths`: a list of paths to ignore when scanning for files.
+  #
+  # @!attribute [r] file_scanner
+  #  @return [RubyLint::FileScanner]
+  #
+  # @!attribute [r] parser
+  #  @return [RubyLint::Parser]
+  #
+  # @!attribute [r] nodes
+  #  @return [Array] A list of extra nodes (and their comments) a VM instance
+  #   should process before processing the file being analyzed.
+  #
+  # @!attribute [r] debug
+  #  @return [TrueClass|FalseClass]
+  #
+  # @!attribute [r] paths
+  #  @return [Set]
+  #
+  class FileLoader < Iterator
+    include Helper::ConstantPaths
+
+    attr_reader :file_scanner, :parser, :nodes, :comments, :debug, :paths
+
+    ##
+    # Called after a new instance of this class is created.
+    #
+    def after_initialize
+      @file_scanner = FileScanner.new(@directories, @ignore_paths)
+      @parser       = Parser.new
+      @nodes        = []
+      @paths        = Set.new
+    end
+
+    ##
+    # @param [RubyLint::AST::Node] node
+    #
+    def on_const(node)
+      segments      = constant_segments(node)
+      constant_path = segments.join('::')
+      files         = file_scanner.scan(constant_path)
+
+      paths << node.file
+
+      files.each do |path|
+        next if paths.include?(path)
+
+        paths << path
+
+        debug_message("Processing extra file: #{path}")
+
+        process_file(segments[-1], path)
+      end
+    end
+
+    private
+
+    ##
+    # @param [String] constant_name
+    # @param [String] path
+    #
+    def process_file(constant_name, path)
+      code = File.read(path)
+
+      unless code.include?(constant_name)
+        debug_message(
+          %Q{  Skipping since "#{constant_name}" was not found in this file}
+        )
+
+        return
+      end
+
+      ast, comments = parser.parse(code, path)
+
+      iterate(ast)
+
+      nodes << [ast, comments]
+    end
+
+    ##
+    # @param [String] message
+    #
+    def debug_message(message)
+      STDERR.puts(message) if debug
+    end
+  end # FileLoader
+end # RubyLint

data/lib/ruby-lint/file_scanner.rb

@@ -0,0 +1,91 @@
+module RubyLint
+  ##
+  # {RubyLint::FileScanner} is used for finding a list of files that could
+  # potentially define a given Ruby constant (path).
+  #
+  # @!attribute [r] directories
+  #  @return [Array]
+  #
+  # @!attribute [r] ignore
+  #  @return [Array]
+  #
+  class FileScanner
+    attr_reader :directories, :ignore
+
+    ##
+    # @param [Array] directories A collection of base directories to search in.
+    # @param [Array] ignore A list of paths to ignore.
+    #
+    def initialize(directories = [Dir.pwd], ignore = [])
+      unless directories.respond_to?(:each)
+        raise TypeError, 'Directories must be specified as an Enumerable'
+      end
+
+      @directories = directories
+      @ignore      = ignore || []
+    end
+
+    ##
+    # Tries to find `constant` in one of the directories. The return value is
+    # an Array of file paths sorted from top-level to deeply nested structures
+    # (e.g. `a.rb` comes before `foo/a.rb`).
+    #
+    # @param [String] constant
+    # @return [Array]
+    #
+    def scan(constant)
+      segment = constant_to_path(constant)
+      paths   = Dir.glob(glob_pattern(segment))
+
+      # Lets see if we can find anything when using dashes for the directory
+      # names instead of underscores.
+      if paths.empty?
+        segment = constant_to_dashed_path(constant)
+        paths   = Dir.glob(glob_pattern(segment))
+      end
+
+      ignore.each do |pattern|
+        paths.reject! do |path|
+          path.include?(pattern)
+        end
+      end
+
+      # Ensure that the order is from top-level -> deeply nested files instead
+      # of a random order.
+      paths.sort! do |left, right|
+        left.length <=> right.length
+      end
+
+      return paths
+    end
+
+    private
+
+    ##
+    # @param [String] constant
+    # @return [String]
+    #
+    def constant_to_path(constant)
+      return constant.gsub('::', '/').snake_case
+    end
+
+    ##
+    # @see #constant_to_path
+    #
+    def constant_to_dashed_path(constant)
+      segments = constant.split('::')
+      last     = segments[-1]
+      path     = segments[0..-2].join('/').snake_case.gsub('_', '-')
+
+      return "#{path}/#{last.snake_case}"
+    end
+
+    ##
+    # @param [String] segment
+    # @return [String]
+    #
+    def glob_pattern(segment)
+      return "{#{directories.join(',')}}/**/#{segment}.rb"
+    end
+  end # FileScanner
+end # RubyLint

data/lib/ruby-lint/global_scope.rb

@@ -0,0 +1,56 @@
+module RubyLint
+  module GlobalScope
+    ##
+    # @return [RubyLint::Definition::RubyObject]
+    #
+    def self.definitions
+      return @definitions ||= Definition::RubyObject.new(
+        :name => 'global',
+        :type => :global
+      )
+    end
+
+    ##
+    # Looks up the given constant in the global scope. If it does not exist
+    # this method will try to load it from one of the existing definitions.
+    #
+    # @param [String] name
+    # @return [RubyLint::Definition::RubyObject]
+    #
+    def self.global_constant(name)
+      found = definitions.lookup_constant_path(name)
+
+      if !found and !constant_loader.loaded?(name)
+        constant_loader.load_constant(name)
+
+        found = definitions.lookup_constant_path(name)
+      end
+
+      return found
+    end
+
+    class << self
+      # This allows the ConstantProxy class to use the same code while still
+      # being able to use the global scope as its input.
+      alias_method :lookup_constant_path, :global_constant
+    end
+
+    ##
+    # Creates a new proxy for a global constant.
+    #
+    # @param [String] name The name of the constant, can include an entire
+    #  constant path in the form of `Foo::Bar`.
+    # @return [RubyLint::Definition::ConstantProxy]
+    #
+    def self.constant_proxy(name)
+      return Definition::ConstantProxy.new(self, name)
+    end
+
+    ##
+    # @return [RubyLint::ConstantLoader]
+    #
+    def self.constant_loader
+      return @constant_loader ||= ConstantLoader.new
+    end
+  end # GlobalScope
+end # RubyLint