rubbycop 0.49.0

data/lib/rubbycop/cop/variable_force/scope.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubbyCop
+  module Cop
+    class VariableForce
+      # A Scope represents a context of local variable visibility.
+      # This is a place where local variables belong to.
+      # A scope instance holds a scope node and variable entries.
+      class Scope
+        OUTER_SCOPE_CHILD_INDICES = {
+          defs:   0..0,
+          module: 0..0,
+          class:  0..1,
+          sclass: 0..0,
+          block:  0..0
+        }.freeze
+
+        attr_reader :node, :variables, :naked_top_level
+        alias naked_top_level? naked_top_level
+
+        def initialize(node)
+          unless SCOPE_TYPES.include?(node.type)
+            # Accept any node type for top level scope
+            if node.parent
+              raise ArgumentError,
+                    "Node type must be any of #{SCOPE_TYPES}, " \
+                    "passed #{node.type}"
+            end
+            @naked_top_level = true
+          end
+          @node = node
+          @variables = {}
+        end
+
+        def ==(other)
+          @node.equal?(other.node)
+        end
+
+        def name
+          # TODO: Add an else clause
+          case @node.type
+          when :def  then @node.children[0]
+          when :defs then @node.children[1]
+          end
+        end
+
+        def body_node
+          if naked_top_level?
+            node
+          else
+            child_index = case node.type
+                          when :module, :sclass     then 1
+                          when :def, :class, :block then 2
+                          when :defs                then 3
+                          end
+
+            node.children[child_index]
+          end
+        end
+
+        def include?(target_node)
+          !belong_to_outer_scope?(target_node) &&
+            !belong_to_inner_scope?(target_node)
+        end
+
+        def each_node(&block)
+          return to_enum(__method__) unless block_given?
+          yield node if naked_top_level?
+          scan_node(node, &block)
+        end
+
+        private
+
+        def scan_node(node, &block)
+          node.each_child_node do |child_node|
+            next unless include?(child_node)
+            yield child_node
+            scan_node(child_node, &block)
+          end
+        end
+
+        def belong_to_outer_scope?(target_node)
+          return true if !naked_top_level? && target_node.equal?(node)
+          return true if ancestor_node?(target_node)
+          return false unless target_node.parent.equal?(node)
+          indices = OUTER_SCOPE_CHILD_INDICES[target_node.parent.type]
+          return false unless indices
+          indices.include?(target_node.sibling_index)
+        end
+
+        def belong_to_inner_scope?(target_node)
+          return false if !target_node.parent || target_node.parent.equal?(node)
+          return false unless SCOPE_TYPES.include?(target_node.parent.type)
+          indices = OUTER_SCOPE_CHILD_INDICES[target_node.parent.type]
+          return true unless indices
+          !indices.include?(target_node.sibling_index)
+        end
+
+        def ancestor_node?(target_node)
+          node.each_ancestor.any? do |ancestor_node|
+            ancestor_node.equal?(target_node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubbycop/cop/variable_force/variable.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RubbyCop
+  module Cop
+    class VariableForce
+      # A Variable represents existence of a local variable.
+      # This holds a variable declaration node,
+      # and some states of the variable.
+      class Variable
+        VARIABLE_DECLARATION_TYPES =
+          (VARIABLE_ASSIGNMENT_TYPES + ARGUMENT_DECLARATION_TYPES).freeze
+
+        attr_reader :name, :declaration_node, :scope,
+                    :assignments, :references, :captured_by_block
+        alias captured_by_block? captured_by_block
+
+        def initialize(name, declaration_node, scope)
+          unless VARIABLE_DECLARATION_TYPES.include?(declaration_node.type)
+            raise ArgumentError,
+                  "Node type must be any of #{VARIABLE_DECLARATION_TYPES}, " \
+                  "passed #{declaration_node.type}"
+          end
+
+          @name = name.to_sym
+          @declaration_node = declaration_node
+          @scope = scope
+
+          @assignments = []
+          @references = []
+          @captured_by_block = false
+        end
+
+        def assign(node)
+          @assignments << Assignment.new(node, self)
+        end
+
+        def referenced?
+          !@references.empty?
+        end
+
+        def reference!(node)
+          reference = Reference.new(node, @scope)
+          @references << reference
+          consumed_branches = Set.new
+
+          @assignments.reverse_each do |assignment|
+            next if consumed_branches.include?(assignment.branch)
+
+            unless assignment.run_exclusively_with?(reference)
+              assignment.reference!
+            end
+
+            break if !assignment.branch || assignment.branch == reference.branch
+
+            unless assignment.branch.may_run_incompletely?
+              consumed_branches << assignment.branch
+            end
+          end
+        end
+
+        def capture_with_block!
+          @captured_by_block = true
+        end
+
+        # This is a convenient way to check whether the variable is used
+        # in its entire variable lifetime.
+        # For more precise usage check, refer Assignment#used?.
+        #
+        # Once the variable is captured by a block, we have no idea
+        # when, where and how many times the block would be invoked
+        # and it means we cannot track the usage of the variable.
+        # So we consider it's used to suppress false positive offenses.
+        def used?
+          @captured_by_block || referenced?
+        end
+
+        def should_be_unused?
+          name.to_s.start_with?('_')
+        end
+
+        def argument?
+          ARGUMENT_DECLARATION_TYPES.include?(@declaration_node.type)
+        end
+
+        def method_argument?
+          argument? && %i[def defs].include?(@scope.node.type)
+        end
+
+        def block_argument?
+          argument? && @scope.node.block_type?
+        end
+
+        def keyword_argument?
+          %i[kwarg kwoptarg].include?(@declaration_node.type)
+        end
+
+        def explicit_block_local_variable?
+          @declaration_node.shadowarg_type?
+        end
+      end
+    end
+  end
+end

data/lib/rubbycop/cop/variable_force/variable_table.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RubbyCop
+  module Cop
+    class VariableForce
+      # A VariableTable manages the lifetime of all scopes and local variables
+      # in a program.
+      # This holds scopes as stack structure, and provides a way to add local
+      # variables to current scope and find local variables by considering
+      # variable visibility of the current scope.
+      class VariableTable
+        def initialize(hook_receiver = nil)
+          @hook_receiver = hook_receiver
+        end
+
+        def invoke_hook(hook_name, *args)
+          @hook_receiver.send(hook_name, *args) if @hook_receiver
+        end
+
+        def scope_stack
+          @scope_stack ||= []
+        end
+
+        def push_scope(scope_node)
+          scope = Scope.new(scope_node)
+          invoke_hook(:before_entering_scope, scope)
+          scope_stack.push(scope)
+          invoke_hook(:after_entering_scope, scope)
+          scope
+        end
+
+        def pop_scope
+          scope = current_scope
+          invoke_hook(:before_leaving_scope, scope)
+          scope_stack.pop
+          invoke_hook(:after_leaving_scope, scope)
+          scope
+        end
+
+        def current_scope
+          scope_stack.last
+        end
+
+        def current_scope_level
+          scope_stack.count
+        end
+
+        def declare_variable(name, node)
+          variable = Variable.new(name, node, current_scope)
+          invoke_hook(:before_declaring_variable, variable)
+          current_scope.variables[variable.name] = variable
+          invoke_hook(:after_declaring_variable, variable)
+          variable
+        end
+
+        def assign_to_variable(name, node)
+          variable = find_variable(name)
+
+          unless variable
+            raise "Assigning to undeclared local variable \"#{name}\" " \
+                 "at #{node.source_range}, #{node.inspect}"
+          end
+
+          variable.assign(node)
+          mark_variable_as_captured_by_block_if_so(variable)
+        end
+
+        def reference_variable(name, node)
+          variable = find_variable(name)
+
+          # In this code:
+          #
+          #   foo = 1 unless foo
+          #
+          #   (if
+          #     (lvar :foo) nil
+          #     (lvasgn :foo
+          #       (int 1)))
+          #
+          # Parser knows whether the foo is a variable or method invocation.
+          # This means that if a :lvar node is shown in AST, the variable is
+          # assumed to be already declared, even if we haven't seen any :lvasgn
+          # or :arg node before the :lvar node.
+          #
+          # We don't invoke #declare_variable here otherwise
+          # Variable#declaration_node will be :lvar node, that is actually not.
+          # So just skip.
+          return unless variable
+
+          variable.reference!(node)
+          mark_variable_as_captured_by_block_if_so(variable)
+        end
+
+        def find_variable(name)
+          name = name.to_sym
+
+          scope_stack.reverse_each do |scope|
+            variable = scope.variables[name]
+            return variable if variable
+            # Only block scope allows referencing outer scope variables.
+            return nil unless scope.node.block_type?
+          end
+
+          nil
+        end
+
+        def variable_exist?(name)
+          find_variable(name)
+        end
+
+        def accessible_variables
+          scope_stack.reverse_each.each_with_object([]) do |scope, variables|
+            variables.concat(scope.variables.values)
+            break variables unless scope.node.block_type?
+          end
+        end
+
+        private
+
+        def mark_variable_as_captured_by_block_if_so(variable)
+          return unless current_scope.node.block_type?
+          return if variable.scope == current_scope
+          variable.capture_with_block!
+        end
+      end
+    end
+  end
+end

data/lib/rubbycop/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubbyCop
+  # An Error exception is different from an Offense with severity 'error'
+  # When this exception is raised, it means that RubbyCop is unable to perform
+  # a requested action (probably due to misconfiguration) and must stop
+  # immediately, rather than carrying on
+  class Error < StandardError; end
+
+  class ValidationError < Error; end
+end

data/lib/rubbycop/formatter/base_formatter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# rubbycop:disable Metrics/LineLength
+
+module RubbyCop
+  module Formatter
+    # Abstract base class for formatter, implements all public API methods.
+    #
+    # ## Creating Custom Formatter
+    #
+    # You can create a custom formatter by subclassing
+    # `RubbyCop::Formatter::BaseFormatter` and overriding some methods,
+    # or by implementing all the methods by duck typing.
+    #
+    # ## Using Custom Formatter in Command Line
+    #
+    # You can tell RubbyCop to use your custom formatter with a combination of
+    # `--format` and `--require` option.
+    # For example, when you have defined `MyCustomFormatter` in
+    # `./path/to/my_custom_formatter.rb`, you would type this command:
+    #
+    #     rubbycop --require ./path/to/my_custom_formatter --format MyCustomFormatter
+    #
+    # Note: The path passed to `--require` is directly passed to
+    # `Kernel.require`.
+    # If your custom formatter file is not in `$LOAD_PATH`,
+    # you need to specify the path as relative path prefixed with `./`
+    # explicitly, or absolute path.
+    #
+    # ## Method Invocation Order
+    #
+    # For example, when RubbyCop inspects 2 files,
+    # the invocation order should be like this:
+    #
+    # * `#initialize`
+    # * `#started`
+    # * `#file_started`
+    # * `#file_finished`
+    # * `#file_started`
+    # * `#file_finished`
+    # * `#finished`
+    #
+    class BaseFormatter
+      # rubbycop:enable Metrics/LineLength
+
+      # @api public
+      #
+      # @!attribute [r] output
+      #
+      # @return [IO]
+      #   the IO object passed to `#initialize`
+      #
+      # @see #initialize
+      attr_reader :output
+
+      # @api public
+      #
+      # @!attribute [r] options
+      #
+      # @return [Hash]
+      attr_reader :options
+
+      # @api public
+      #
+      # @param output [IO]
+      #   `$stdout` or opened file
+      def initialize(output, options = {})
+        @output = output
+        @options = options
+      end
+
+      # @api public
+      #
+      # Invoked once before any files are inspected.
+      #
+      # @param target_files [Array(String)]
+      #   all target file paths to be inspected
+      #
+      # @return [void]
+      def started(target_files); end
+
+      # @api public
+      #
+      # Invoked at the beginning of inspecting each files.
+      #
+      # @param file [String]
+      #   the file path
+      #
+      # @param options [Hash]
+      #   file specific information, currently this is always empty.
+      #
+      # @return [void]
+      def file_started(file, options); end
+
+      # @api public
+      #
+      # Invoked at the end of inspecting each files.
+      #
+      # @param file [String]
+      #   the file path
+      #
+      # @param offenses [Array(RubbyCop::Cop::Offense)]
+      #   all detected offenses for the file
+      #
+      # @return [void]
+      #
+      # @see RubbyCop::Cop::Offense
+      def file_finished(file, offenses); end
+
+      # @api public
+      #
+      # Invoked after all files are inspected, or interrupted by user.
+      #
+      # @param inspected_files [Array(String)]
+      #   the inspected file paths.
+      #   This would be same as `target_files` passed to `#started`
+      #   unless RubbyCop is interrupted by user.
+      #
+      # @return [void]
+      def finished(inspected_files); end
+    end
+  end
+end