rubocop-ast 0.5.1 → 1.0.0

data/lib/rubocop/ast/node_pattern/builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    class NodePattern
+      # Responsible to build the AST nodes for `NodePattern`
+      #
+      # Doc on how this fits in the compiling process:
+      #   /doc/modules/ROOT/pages/node_pattern.md
+      class Builder
+        def emit_capture(capture_token, node)
+          return node if capture_token.nil?
+
+          emit_unary_op(:capture, capture_token, node)
+        end
+
+        def emit_atom(type, value)
+          n(type, [value])
+        end
+
+        def emit_unary_op(type, _operator = nil, *children)
+          n(type, children)
+        end
+
+        def emit_list(type, _begin, children, _end)
+          n(type, children)
+        end
+
+        def emit_call(type, selector, args = nil)
+          _begin_t, arg_nodes, _end_t = args
+          n(type, [selector, *arg_nodes])
+        end
+
+        def emit_union(begin_t, pattern_lists, end_t)
+          children = union_children(pattern_lists)
+
+          type = optimizable_as_set?(children) ? :set : :union
+          emit_list(type, begin_t, children, end_t)
+        end
+
+        def emit_subsequence(node_list)
+          return node_list.first if node_list.size == 1 # Don't put a single child in a subsequence
+
+          emit_list(:subsequence, nil, node_list, nil)
+        end
+
+        private
+
+        def optimizable_as_set?(children)
+          children.all?(&:matches_within_set?)
+        end
+
+        def n(type, *args)
+          Node::MAP[type].new(type, *args)
+        end
+
+        def union_children(pattern_lists)
+          if pattern_lists.size == 1 # {a b c} => [[a, b, c]] => [a, b, c]
+            children = pattern_lists.first
+            raise NodePattern::Invalid, 'A union can not be empty' if children.empty?
+
+            children
+          else # { a b | c } => [[a, b], [c]] => [s(:subsequence, a, b), c]
+            pattern_lists.map do |list|
+              emit_subsequence(list)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node_pattern/comment.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    class NodePattern
+      # A NodePattern comment, simplified version of ::Parser::Source::Comment
+      class Comment
+        attr_reader :location
+        alias loc location
+
+        ##
+        # @param [Parser::Source::Range] range
+        #
+        def initialize(range)
+          @location = ::Parser::Source::Map.new(range)
+          freeze
+        end
+
+        # @return [String]
+        def text
+          loc.expression.source.freeze
+        end
+
+        ##
+        # Compares comments. Two comments are equal if they
+        # correspond to the same source range.
+        #
+        # @param [Object] other
+        # @return [Boolean]
+        #
+        def ==(other)
+          other.is_a?(Comment) &&
+            @location == other.location
+        end
+
+        ##
+        # @return [String] a human-readable representation of this comment
+        #
+        def inspect
+          "#<NodePattern::Comment #{@location.expression} #{text.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node_pattern/compiler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    class NodePattern
+      # The top-level compiler holding the global state
+      # Defers work to its subcompilers
+      #
+      # Doc on how this fits in the compiling process:
+      #   /doc/modules/ROOT/pages/node_pattern.md
+      class Compiler
+        extend Forwardable
+        attr_reader :captures, :named_parameters, :positional_parameters, :binding
+
+        def initialize
+          @temp_depth = 0 # avoid name clashes between temp variables
+          @captures = 0 # number of captures seen
+          @positional_parameters = 0 # highest % (param) number seen
+          @named_parameters = Set[] # keyword parameters
+          @binding = Binding.new # bound variables
+          @atom_subcompiler = self.class::AtomSubcompiler.new(self)
+        end
+
+        def_delegators :binding, :bind
+
+        def positional_parameter(number)
+          @positional_parameters = number if number > @positional_parameters
+          "param#{number}"
+        end
+
+        def named_parameter(name)
+          @named_parameters << name
+          name
+        end
+
+        # Enumerates `enum` while keeping track of state accross
+        # union branches (captures and unification).
+        def each_union(enum, &block)
+          enforce_same_captures(binding.union_bind(enum), &block)
+        end
+
+        def compile_as_atom(node)
+          @atom_subcompiler.compile(node)
+        end
+
+        def compile_as_node_pattern(node, **options)
+          self.class::NodePatternSubcompiler.new(self, **options).compile(node)
+        end
+
+        def compile_sequence(sequence, var:)
+          self.class::SequenceSubcompiler.new(self, sequence: sequence, var: var).compile_sequence
+        end
+
+        def parser
+          @parser ||= Parser.new
+        end
+
+        # Utilities
+
+        def with_temp_variables(*names, &block)
+          @temp_depth += 1
+          suffix = @temp_depth if @temp_depth > 1
+          names = block.parameters.map(&:last) if names.empty?
+          names.map! { |name| "#{name}#{suffix}" }
+          yield(*names)
+        ensure
+          @temp_depth -= 1
+        end
+
+        def next_capture
+          "captures[#{new_capture}]"
+        end
+
+        def freeze
+          @named_parameters.freeze
+          super
+        end
+
+        private
+
+        def enforce_same_captures(enum)
+          return to_enum __method__, enum unless block_given?
+
+          captures_before = captures_after = nil
+          enum.each do |node|
+            captures_before ||= @captures
+            @captures = captures_before
+            yield node
+            captures_after ||= @captures
+            if captures_after != @captures
+              raise Invalid, 'each branch must have same number of captures'
+            end
+          end
+        end
+
+        def new_capture
+          @captures
+        ensure
+          @captures += 1
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node_pattern/compiler/atom_subcompiler.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    class NodePattern
+      class Compiler
+        # Generates code that evaluates to a value (Ruby object)
+        # This value responds to `===`.
+        #
+        # Doc on how this fits in the compiling process:
+        #   /doc/modules/ROOT/pages/node_pattern.md
+        class AtomSubcompiler < Subcompiler
+          private
+
+          def visit_unify
+            compiler.bind(node.child) do
+              raise Invalid, 'unified variables can not appear first as argument'
+            end
+          end
+
+          def visit_symbol
+            node.child.inspect
+          end
+          alias visit_number visit_symbol
+          alias visit_string visit_symbol
+          alias visit_regexp visit_symbol
+
+          def visit_const
+            node.child
+          end
+
+          def visit_named_parameter
+            compiler.named_parameter(node.child)
+          end
+
+          def visit_positional_parameter
+            compiler.positional_parameter(node.child)
+          end
+
+          def visit_set
+            set = node.children.map(&:child).to_set.freeze
+            NodePattern::Sets[set]
+          end
+
+          # Assumes other types are node patterns.
+          def visit_other_type
+            compiler.with_temp_variables do |compare|
+              code = compiler.compile_as_node_pattern(node, var: compare)
+              "->(#{compare}) { #{code} }"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node_pattern/compiler/binding.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    class NodePattern
+      class Compiler
+        # Holds the list of bound variable names
+        class Binding
+          def initialize
+            @bound = {}
+          end
+
+          # Yields the first time a given name is bound
+          #
+          # @return [String] bound variable name
+          def bind(name)
+            var = @bound.fetch(name) do
+              yield n = @bound[name] = "unify_#{name.gsub('-', '__')}"
+              n
+            end
+
+            if var == :forbidden_unification
+              raise Invalid, "Wildcard #{name} was first seen in a subset of a" \
+                             " union and can't be used outside that union"
+            end
+            var
+          end
+
+          # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          def union_bind(enum)
+            # We need to reset @bound before each branch is processed.
+            # Moreover we need to keep track of newly encountered wildcards.
+            # Var `newly_bound_intersection` will hold those that are encountered
+            # in all branches; these are not a problem.
+            # Var `partially_bound` will hold those encountered in only a subset
+            # of the branches; these can't be used outside of the union.
+
+            return to_enum __method__, enum unless block_given?
+
+            newly_bound_intersection = nil
+            partially_bound = []
+            bound_before = @bound.dup
+
+            result = enum.each do |e|
+              @bound = bound_before.dup if newly_bound_intersection
+              yield e
+              newly_bound = @bound.keys - bound_before.keys
+              if newly_bound_intersection.nil?
+                # First iteration
+                newly_bound_intersection = newly_bound
+              else
+                union = newly_bound_intersection | newly_bound
+                newly_bound_intersection &= newly_bound
+                partially_bound |= union - newly_bound_intersection
+              end
+            end
+
+            # At this point, all members of `newly_bound_intersection` can be used
+            # for unification outside of the union, but partially_bound may not
+
+            forbid(partially_bound)
+
+            result
+          end
+          # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+          private
+
+          def forbid(names)
+            names.each do |name|
+              @bound[name] = :forbidden_unification
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node_pattern/compiler/debug.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'rainbow'
+
+module RuboCop
+  module AST
+    class NodePattern
+      class Compiler
+        # Variant of the Compiler with tracing information for nodes
+        class Debug < Compiler
+          # Compiled node pattern requires a named parameter `trace`,
+          # which should be an instance of this class
+          class Trace
+            def initialize
+              @visit = {}
+            end
+
+            def enter(node_id)
+              @visit[node_id] = false
+              true
+            end
+
+            def success(node_id)
+              @visit[node_id] = true
+            end
+
+            # return nil (not visited), false (not matched) or true (matched)
+            def matched?(node_id)
+              @visit[node_id]
+            end
+          end
+
+          attr_reader :node_ids
+
+          # @api private
+          class Colorizer
+            COLOR_SCHEME = {
+              not_visitable: :lightseagreen,
+              nil => :yellow,
+              false => :red,
+              true => :green
+            }.freeze
+
+            # Result of a NodePattern run against a particular AST
+            # Consider constructor is private
+            Result = Struct.new(:colorizer, :trace, :returned, :ruby_ast) do
+              # @return [String] a Rainbow colorized version of ruby
+              def colorize(color_scheme = COLOR_SCHEME)
+                map = color_map(color_scheme)
+                ast.loc.expression.source_buffer.source.chars.map.with_index do |char, i|
+                  Rainbow(char).color(map[i])
+                end.join
+              end
+
+              # @return [Hash] a map for {character_position => color}
+              def color_map(color_scheme = COLOR_SCHEME)
+                @color_map ||=
+                  match_map
+                  .transform_values { |matched| color_scheme.fetch(matched) }
+                  .map { |node, color| color_map_for(node, color) }
+                  .inject(:merge)
+                  .tap { |h| h.default = color_scheme.fetch(:not_visitable) }
+              end
+
+              # @return [Hash] a map for {node => matched?}, depth-first
+              def match_map
+                @match_map ||=
+                  ast
+                  .each_node
+                  .to_h { |node| [node, matched?(node)] }
+              end
+
+              # @return a value of `Trace#matched?` or `:not_visitable`
+              def matched?(node)
+                id = colorizer.compiler.node_ids.fetch(node) { return :not_visitable }
+                trace.matched?(id)
+              end
+
+              private
+
+              def color_map_for(node, color)
+                return {} unless (range = node.loc&.expression)
+
+                range.to_a.to_h { |char| [char, color] }
+              end
+
+              def ast
+                colorizer.node_pattern.ast
+              end
+            end
+
+            Compiler = Debug
+
+            attr_reader :pattern, :compiler, :node_pattern
+
+            def initialize(pattern, compiler: self.class::Compiler.new)
+              @pattern = pattern
+              @compiler = compiler
+              @node_pattern = ::RuboCop::AST::NodePattern.new(pattern, compiler: @compiler)
+            end
+
+            # @return [Node] the Ruby AST
+            def test(ruby, trace: self.class::Compiler::Trace.new)
+              ruby = ruby_ast(ruby) if ruby.is_a?(String)
+              returned = @node_pattern.as_lambda.call(ruby, trace: trace)
+              self.class::Result.new(self, trace, returned, ruby)
+            end
+
+            private
+
+            def ruby_ast(ruby)
+              buffer = ::Parser::Source::Buffer.new('(ruby)', source: ruby)
+              ruby_parser.parse(buffer)
+            end
+
+            def ruby_parser
+              require 'parser/current'
+              builder = ::RuboCop::AST::Builder.new
+              ::Parser::CurrentRuby.new(builder)
+            end
+          end
+
+          def initialize
+            super
+            @node_ids = Hash.new { |h, k| h[k] = h.size }.compare_by_identity
+          end
+
+          def named_parameters
+            super << :trace
+          end
+
+          def parser
+            @parser ||= Parser::WithMeta.new
+          end
+
+          def_delegators :parser, :comments, :tokens
+
+          # @api private
+          module InstrumentationSubcompiler
+            def do_compile
+              "#{tracer(:enter)} && #{super} && #{tracer(:success)}"
+            end
+
+            private
+
+            def tracer(kind)
+              "trace.#{kind}(#{node_id})"
+            end
+
+            def node_id
+              compiler.node_ids[node]
+            end
+          end
+
+          # @api private
+          class NodePatternSubcompiler < Compiler::NodePatternSubcompiler
+            include InstrumentationSubcompiler
+          end
+
+          # @api private
+          class SequenceSubcompiler < Compiler::SequenceSubcompiler
+            include InstrumentationSubcompiler
+          end
+        end
+      end
+    end
+  end
+end