spoom 1.2.1 → 1.2.3

data/lib/spoom/deadcode/indexer.rb

@@ -0,0 +1,403 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Spoom
+  module Deadcode
+    class Indexer < SyntaxTree::Visitor
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :path, :file_name
+
+      sig { returns(Index) }
+      attr_reader :index
+
+      sig { params(path: String, source: String, index: Index, plugins: T::Array[Plugins::Base]).void }
+      def initialize(path, source, index, plugins: [])
+        super()
+
+        @path = path
+        @file_name = T.let(File.basename(path), String)
+        @source = source
+        @index = index
+        @plugins = plugins
+        @previous_node = T.let(nil, T.nilable(SyntaxTree::Node))
+        @names_nesting = T.let([], T::Array[String])
+        @nodes_nesting = T.let([], T::Array[SyntaxTree::Node])
+        @in_const_field = T.let(false, T::Boolean)
+        @in_opassign = T.let(false, T::Boolean)
+        @in_symbol_literal = T.let(false, T::Boolean)
+      end
+
+      # Visit
+
+      sig { override.params(node: T.nilable(SyntaxTree::Node)).void }
+      def visit(node)
+        return unless node
+
+        @nodes_nesting << node
+        super
+        @nodes_nesting.pop
+        @previous_node = node
+      end
+
+      sig { override.params(node: SyntaxTree::AliasNode).void }
+      def visit_alias(node)
+        reference_method(node_string(node.right), node)
+      end
+
+      sig { override.params(node: SyntaxTree::ARef).void }
+      def visit_aref(node)
+        super
+
+        reference_method("[]", node)
+      end
+
+      sig { override.params(node: SyntaxTree::ARefField).void }
+      def visit_aref_field(node)
+        super
+
+        reference_method("[]=", node)
+      end
+
+      sig { override.params(node: SyntaxTree::ArgBlock).void }
+      def visit_arg_block(node)
+        value = node.value
+
+        case value
+        when SyntaxTree::SymbolLiteral
+          # If the block call is something like `x.select(&:foo)`, we need to reference the `foo` method
+          reference_method(symbol_string(value), node)
+        when SyntaxTree::VCall
+          # If the block call is something like `x.select { ... }`, we need to visit the block
+          super
+        end
+      end
+
+      sig { override.params(node: SyntaxTree::Binary).void }
+      def visit_binary(node)
+        super
+
+        op = node.operator
+
+        # Reference the operator itself
+        reference_method(op.to_s, node)
+
+        case op
+        when :<, :>, :<=, :>=
+          # For comparison operators, we also reference the `<=>` method
+          reference_method("<=>", node)
+        end
+      end
+
+      sig { override.params(node: SyntaxTree::CallNode).void }
+      def visit_call(node)
+        visit_send(
+          Send.new(
+            node: node,
+            name: node_string(node.message),
+            recv: node.receiver,
+            args: call_args(node.arguments),
+          ),
+        )
+      end
+
+      sig { override.params(node: SyntaxTree::ClassDeclaration).void }
+      def visit_class(node)
+        const_name = node_string(node.constant)
+        @names_nesting << const_name
+        define_class(T.must(const_name.split("::").last), @names_nesting.join("::"), node)
+
+        # We do not call `super` here because we don't want to visit the `constant` again
+        visit(node.superclass) if node.superclass
+        visit(node.bodystmt)
+
+        @names_nesting.pop
+      end
+
+      sig { override.params(node: SyntaxTree::Command).void }
+      def visit_command(node)
+        visit_send(
+          Send.new(
+            node: node,
+            name: node_string(node.message),
+            args: call_args(node.arguments),
+            block: node.block,
+          ),
+        )
+      end
+
+      sig { override.params(node: SyntaxTree::CommandCall).void }
+      def visit_command_call(node)
+        visit_send(
+          Send.new(
+            node: node,
+            name: node_string(node.message),
+            recv: node.receiver,
+            args: call_args(node.arguments),
+            block: node.block,
+          ),
+        )
+      end
+
+      sig { override.params(node: SyntaxTree::Const).void }
+      def visit_const(node)
+        reference_constant(node.value, node) unless @in_symbol_literal
+      end
+
+      sig { override.params(node: SyntaxTree::ConstPathField).void }
+      def visit_const_path_field(node)
+        # We do not call `super` here because we don't want to visit the `constant` again
+        visit(node.parent)
+
+        name = node.constant.value
+        full_name = [*@names_nesting, node_string(node.parent), name].join("::")
+        define_constant(name, full_name, node)
+      end
+
+      sig { override.params(node: SyntaxTree::DefNode).void }
+      def visit_def(node)
+        super
+
+        name = node_string(node.name)
+        define_method(name, [*@names_nesting, name].join("::"), node)
+      end
+
+      sig { override.params(node: SyntaxTree::Field).void }
+      def visit_field(node)
+        visit(node.parent)
+
+        name = node.name
+        case name
+        when SyntaxTree::Const
+          name = name.value
+          full_name = [*@names_nesting, node_string(node.parent), name].join("::")
+          define_constant(name, full_name, node)
+        when SyntaxTree::Ident
+          reference_method(name.value, node) if @in_opassign
+          reference_method("#{name.value}=", node)
+        end
+      end
+
+      sig { override.params(node: SyntaxTree::ModuleDeclaration).void }
+      def visit_module(node)
+        const_name = node_string(node.constant)
+        @names_nesting << const_name
+        define_module(T.must(const_name.split("::").last), @names_nesting.join("::"), node)
+
+        # We do not call `super` here because we don't want to visit the `constant` again
+        visit(node.bodystmt)
+
+        @names_nesting.pop
+      end
+
+      sig { override.params(node: SyntaxTree::OpAssign).void }
+      def visit_opassign(node)
+        # Both `FOO = x` and `FOO += x` yield a VarField node, but the former is a constant definition and the latter is
+        # a constant reference. We need to distinguish between the two cases.
+        @in_opassign = true
+        super
+        @in_opassign = false
+      end
+
+      sig { params(send: Send).void }
+      def visit_send(send)
+        visit(send.recv)
+
+        case send.name
+        when "attr_reader"
+          send.args.each do |arg|
+            next unless arg.is_a?(SyntaxTree::SymbolLiteral)
+
+            name = symbol_string(arg)
+            define_attr_reader(name, [*@names_nesting, name].join("::"), arg)
+          end
+        when "attr_writer"
+          send.args.each do |arg|
+            next unless arg.is_a?(SyntaxTree::SymbolLiteral)
+
+            name = symbol_string(arg)
+            define_attr_writer("#{name}=", "#{[*@names_nesting, name].join("::")}=", arg)
+          end
+        when "attr_accessor"
+          send.args.each do |arg|
+            next unless arg.is_a?(SyntaxTree::SymbolLiteral)
+
+            name = symbol_string(arg)
+            full_name = [*@names_nesting, name].join("::")
+            define_attr_reader(name, full_name, arg)
+            define_attr_writer("#{name}=", "#{full_name}=", arg)
+          end
+        else
+          @plugins.each do |plugin|
+            plugin.on_send(self, send)
+          end
+
+          reference_method(send.name, send.node)
+          visit_all(send.args)
+          visit(send.block)
+        end
+      end
+
+      sig { override.params(node: SyntaxTree::SymbolLiteral).void }
+      def visit_symbol_literal(node)
+        # Something like `:FOO` will yield a Const node but we do not want to treat it as a constant reference.
+        # So we need to distinguish between the two cases.
+        @in_symbol_literal = true
+        super
+        @in_symbol_literal = false
+      end
+
+      sig { override.params(node: SyntaxTree::TopConstField).void }
+      def visit_top_const_field(node)
+        define_constant(node.constant.value, node.constant.value, node)
+      end
+
+      sig { override.params(node: SyntaxTree::VarField).void }
+      def visit_var_field(node)
+        value = node.value
+        case value
+        when SyntaxTree::Const
+          if @in_opassign
+            reference_constant(value.value, node)
+          else
+            name = value.value
+            define_constant(name, [*@names_nesting, name].join("::"), node)
+          end
+        when SyntaxTree::Ident
+          reference_method(value.value, node) if @in_opassign
+          reference_method("#{value.value}=", node)
+        end
+      end
+
+      sig { override.params(node: SyntaxTree::VCall).void }
+      def visit_vcall(node)
+        visit_send(Send.new(node: node, name: node_string(node.value)))
+      end
+
+      # Definition indexing
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_attr_reader(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::AttrReader,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_accessor(self, definition) }
+      end
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_attr_writer(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::AttrWriter,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_accessor(self, definition) }
+      end
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_class(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::Class,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_class(self, definition) }
+      end
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_constant(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::Constant,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_constant(self, definition) }
+      end
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_method(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::Method,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_method(self, definition) }
+      end
+
+      sig { params(name: String, full_name: String, node: SyntaxTree::Node).void }
+      def define_module(name, full_name, node)
+        definition = Definition.new(
+          kind: Definition::Kind::Module,
+          name: name,
+          full_name: full_name,
+          location: node_location(node),
+        )
+        @index.define(definition)
+        @plugins.each { |plugin| plugin.on_define_module(self, definition) }
+      end
+
+      # Reference indexing
+
+      sig { params(name: String, node: SyntaxTree::Node).void }
+      def reference_constant(name, node)
+        @index.reference(Reference.new(name: name, kind: Reference::Kind::Constant, location: node_location(node)))
+      end
+
+      sig { params(name: String, node: SyntaxTree::Node).void }
+      def reference_method(name, node)
+        @index.reference(Reference.new(name: name, kind: Reference::Kind::Method, location: node_location(node)))
+      end
+
+      # Node utils
+
+      sig { params(node: T.any(Symbol, SyntaxTree::Node)).returns(String) }
+      def node_string(node)
+        case node
+        when Symbol
+          node.to_s
+        else
+          T.must(@source[node.location.start_char...node.location.end_char])
+        end
+      end
+
+      sig { params(node: SyntaxTree::Node).returns(Location) }
+      def node_location(node)
+        Location.from_syntax_tree(@path, node.location)
+      end
+
+      sig { params(node: SyntaxTree::Node).returns(String) }
+      def symbol_string(node)
+        node_string(node).delete_prefix(":")
+      end
+
+      sig do
+        params(
+          node: T.any(SyntaxTree::Args, SyntaxTree::ArgParen, SyntaxTree::ArgsForward, NilClass),
+        ).returns(T::Array[SyntaxTree::Node])
+      end
+      def call_args(node)
+        case node
+        when SyntaxTree::ArgParen
+          call_args(node.arguments)
+        when SyntaxTree::Args
+          node.parts
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/spoom/deadcode/location.rb

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Spoom
+  module Deadcode
+    class Location
+      extend T::Sig
+
+      include Comparable
+
+      class LocationError < Spoom::Error; end
+
+      class << self
+        extend T::Sig
+
+        sig { params(file: String, location: SyntaxTree::Location).returns(Location) }
+        def from_syntax_tree(file, location)
+          new(file, location.start_line, location.start_column, location.end_line, location.end_column)
+        end
+      end
+
+      sig { returns(String) }
+      attr_reader :file
+
+      sig { returns(Integer) }
+      attr_reader :start_line, :start_column, :end_line, :end_column
+
+      sig do
+        params(
+          file: String,
+          start_line: Integer,
+          start_column: Integer,
+          end_line: Integer,
+          end_column: Integer,
+        ).void
+      end
+      def initialize(file, start_line, start_column, end_line, end_column)
+        @file = file
+        @start_line = start_line
+        @start_column = start_column
+        @end_line = end_line
+        @end_column = end_column
+      end
+
+      sig { override.params(other: BasicObject).returns(T.nilable(Integer)) }
+      def <=>(other)
+        return unless Location === other
+
+        to_s <=> other.to_s
+      end
+
+      sig { returns(String) }
+      def to_s
+        "#{@file}:#{@start_line}:#{@start_column}-#{@end_line}:#{@end_column}"
+      end
+    end
+  end
+end

data/lib/spoom/deadcode/plugins/base.rb

@@ -0,0 +1,201 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "set"
+
+module Spoom
+  module Deadcode
+    module Plugins
+      class Base
+        extend T::Sig
+        extend T::Helpers
+
+        abstract!
+
+        class << self
+          extend T::Sig
+
+          # Plugins DSL
+
+          # Mark methods matching `names` as ignored.
+          #
+          # Names can be either strings or regexps:
+          #
+          # ~~~rb
+          # class MyPlugin < Spoom::Deadcode::Plugins::Base
+          #   ignore_method_names(
+          #     "foo",
+          #     "bar",
+          #     /baz.*/,
+          #   )
+          # end
+          # ~~~
+          sig { params(names: T.any(String, Regexp)).void }
+          def ignore_method_names(*names)
+            save_names_and_patterns(names, :@ignored_method_names, :@ignored_method_patterns)
+          end
+
+          private
+
+          sig { params(names: T::Array[T.any(String, Regexp)], names_variable: Symbol, patterns_variable: Symbol).void }
+          def save_names_and_patterns(names, names_variable, patterns_variable)
+            ignored_names = instance_variable_set(names_variable, Set.new)
+            ignored_patterns = instance_variable_set(patterns_variable, [])
+
+            names.each do |name|
+              case name
+              when String
+                ignored_names << name
+              when Regexp
+                ignored_patterns << name
+              end
+            end
+          end
+        end
+
+        # Indexing event methods
+
+        # Called when an accessor is defined.
+        #
+        # Will be called when the indexer processes a `attr_reader`, `attr_writer` or `attr_accessor` node.
+        # Note that when this method is called, the definition for the node has already been added to the index.
+        # It is still possible to ignore it from the plugin:
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_define_accessor(indexer, definition)
+        #     definition.ignored! if definition.name == "foo"
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, definition: Definition).void }
+        def on_define_accessor(indexer, definition)
+          # no-op
+        end
+
+        # Called when a class is defined.
+        #
+        # Will be called when the indexer processes a `class` node.
+        # Note that when this method is called, the definition for the node has already been added to the index.
+        # It is still possible to ignore it from the plugin:
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_define_class(indexer, definition)
+        #     definition.ignored! if definition.name == "Foo"
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, definition: Definition).void }
+        def on_define_class(indexer, definition)
+          # no-op
+        end
+
+        # Called when a constant is defined.
+        #
+        # Will be called when the indexer processes a `CONST =` node.
+        # Note that when this method is called, the definition for the node has already been added to the index.
+        # It is still possible to ignore it from the plugin:
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_define_constant(indexer, definition)
+        #     definition.ignored! if definition.name == "FOO"
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, definition: Definition).void }
+        def on_define_constant(indexer, definition)
+          # no-op
+        end
+
+        # Called when a method is defined.
+        #
+        # Will be called when the indexer processes a `def` or `defs` node.
+        # Note that when this method is called, the definition for the node has already been added to the index.
+        # It is still possible to ignore it from the plugin:
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_define_method(indexer, definition)
+        #     super # So the `ignore_method_names` DSL is still applied
+        #
+        #     definition.ignored! if definition.name == "foo"
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, definition: Definition).void }
+        def on_define_method(indexer, definition)
+          definition.ignored! if ignored_method_name?(definition.name)
+        end
+
+        # Called when a module is defined.
+        #
+        # Will be called when the indexer processes a `module` node.
+        # Note that when this method is called, the definition for the node has already been added to the index.
+        # It is still possible to ignore it from the plugin:
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_define_module(indexer, definition)
+        #     definition.ignored! if definition.name == "Foo"
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, definition: Definition).void }
+        def on_define_module(indexer, definition)
+          # no-op
+        end
+
+        # Called when a send is being processed
+        #
+        # ~~~rb
+        # class MyPlugin < Spoom::Deadcode::Plugins::Base
+        #   def on_send(indexer, send)
+        #     return unless send.name == "dsl_method"
+        #     return if send.args.empty?
+        #
+        #     method_name = indexer.node_string(send.args.first).delete_prefix(":")
+        #     indexer.reference_method(method_name, send.node)
+        #   end
+        # end
+        # ~~~
+        sig { params(indexer: Indexer, send: Send).void }
+        def on_send(indexer, send)
+          # no-op
+        end
+
+        private
+
+        sig { params(name: String).returns(T::Boolean) }
+        def ignored_method_name?(name)
+          ignored_name?(name, :@ignored_method_names, :@ignored_method_patterns)
+        end
+
+        sig { params(const: Symbol).returns(T::Set[String]) }
+        def names(const)
+          self.class.instance_variable_get(const) || Set.new
+        end
+
+        sig { params(name: String, names_variable: Symbol, patterns_variable: Symbol).returns(T::Boolean) }
+        def ignored_name?(name, names_variable, patterns_variable)
+          names(names_variable).include?(name) || patterns(patterns_variable).any? { |pattern| pattern.match?(name) }
+        end
+
+        sig { params(const: Symbol).returns(T::Array[Regexp]) }
+        def patterns(const)
+          self.class.instance_variable_get(const) || []
+        end
+
+        sig { params(indexer: Indexer, send: Send).void }
+        def reference_send_first_symbol_as_method(indexer, send)
+          first_arg = send.args.first
+          return unless first_arg.is_a?(SyntaxTree::SymbolLiteral)
+
+          name = indexer.node_string(first_arg.value)
+          indexer.reference_method(name, send.node)
+        end
+      end
+    end
+  end
+end