rubocop-callbacksystems 0.1.0

data/lib/rubocop/callbacksystems/class_structure/reference_order.rb

@@ -0,0 +1,36 @@
+# The order that reads each name before the names it refers to, walked depth first from the seeds it is given. The graph
+# maps a name to the names it refers to, and a name the graph does not hold is skipped.
+class RuboCop::Callbacksystems::ClassStructure::ReferenceOrder
+  include Enumerable
+
+  delegate :each, to: :ordered
+
+  def initialize(seeds, graph)
+    @seeds = seeds
+    @graph = graph
+  end
+
+  private
+    attr_reader :seeds, :graph
+
+    def ordered
+      @ordered ||= seeds.each_with_object([]) { |name, order| gather(name, order) }
+    end
+
+    def gather(name, order)
+      stack = [ name ]
+
+      until stack.empty?
+        current = stack.pop
+        next if visited.include?(current) || graph.exclude?(current)
+
+        visited.add(current)
+        order << current
+        graph.fetch(current).reverse_each { stack << it if visited.exclude?(it) }
+      end
+    end
+
+    def visited
+      @visited ||= Set.new
+    end
+end

data/lib/rubocop/callbacksystems/class_structure/statement_rank.rb

@@ -0,0 +1,84 @@
+# The place a statement takes in the order a class body reads: the mixins and the class attribute assignments first,
+# then the values, the classes declared in a line, the state, the associations, the delegates, the other macros, the
+# methods, and last the nested classes with a body of their own. The siblings are the statements of the same body, which
+# a `private_constant` needs to find the constant it hides.
+class RuboCop::Callbacksystems::ClassStructure::StatementRank
+  include RuboCop::Callbacksystems::Helpers
+
+  MIXIN = 0
+  VALUE = 1
+  CLASS_DECLARATION = 2
+  ATTRIBUTE = 3
+  ASSOCIATION = 4
+  DELEGATE = 5
+  MACRO = 6
+  METHOD = 7
+  NESTED_CLASS = 8
+
+  def initialize(node, siblings)
+    @node = node
+    @siblings = siblings
+  end
+
+  def to_i
+    shape_rank || marker_rank || macro_rank || METHOD
+  end
+
+  private
+    attr_reader :node, :siblings
+
+    def shape_rank
+      if nested_body?(statement)
+        NESTED_CLASS
+      elsif statement.casgn_type?
+        value_name? ? VALUE : CLASS_DECLARATION
+      end
+    end
+
+    # `include Detection if Rails.env.local?` is the include, whatever the condition around it.
+    def statement
+      node.if_type? && node.modifier_form? ? node.if_branch : node
+    end
+
+    # `Naming/ConstantName` wants SCREAMING_SNAKE_CASE on a value and not on a class, so the case tells them apart.
+    def value_name?
+      statement.name.match?(/\A[A-Z][A-Z0-9_]*\z/)
+    end
+
+    # `private_constant :X` belongs with the `X` it hides, so it takes that declaration's rank.
+    def marker_rank
+      marked_ranks.max || VALUE if private_constant_marker?
+    end
+
+    def private_constant_marker?
+      bare_send?(macro) && macro.method?(:private_constant)
+    end
+
+    # `has_many :blocks do ... end` is the `has_many`, whatever the block adds to it.
+    def macro
+      call_of(statement)
+    end
+
+    def marked_ranks
+      siblings.select { marked_names.include?(declared_name_of(it)) }
+        .map { self.class.new(it, siblings).to_i }
+    end
+
+    def marked_names
+      @marked_names ||= private_constant_names_of(node)
+    end
+
+    def macro_rank
+      case
+      when mixin_macro?(macro) || class_attribute_assignment? then MIXIN
+      when attribute_macro?(macro) then ATTRIBUTE
+      when association_macro?(macro) then ASSOCIATION
+      when delegate_macro?(macro) then DELEGATE
+      when bare_send?(macro) then MACRO
+      end
+    end
+
+    def class_attribute_assignment?
+      statement.send_type? && statement.receiver&.self_type? && statement.assignment_method?
+    end
+end

data/lib/rubocop/callbacksystems/class_structure/statement_run.rb

@@ -0,0 +1,42 @@
+# Statements written together with nothing between them, rewritten into the order given when every one has a place in
+# it. The block names each statement the way the order does, and a statement answers `range` and `source`.
+class RuboCop::Callbacksystems::ClassStructure::StatementRun
+  include RuboCop::Callbacksystems::Helpers
+
+  def initialize(statements, order:, &name_of)
+    @statements = statements
+    @order = order
+    @name_of = name_of
+  end
+
+  def rewrite(corrector)
+    corrector.replace(range, ordered_source) if reorderable?
+  end
+
+  def reorderable?
+    ordered != statements && statements.none?(&:contains_tooling_comment?)
+  end
+
+  private
+    attr_reader :statements, :order, :name_of
+
+    def ordered
+      @ordered ||= placed? ? statements.sort_by { positions.fetch(name_of.call(it)) } : statements
+    end
+
+    def placed?
+      statements.all? { positions.key?(name_of.call(it)) }
+    end
+
+    def positions
+      @positions ||= order.each_with_index.reverse_each.to_h
+    end
+
+    def range
+      span_of(statements.map(&:range))
+    end
+
+    def ordered_source
+      ordered.map(&:source).join("\n\n")
+    end
+end

data/lib/rubocop/callbacksystems/class_structure/visibility.rb

@@ -0,0 +1,84 @@
+# The visibility established by one class body, indexed once for every reader of that body. Section modifiers apply to
+# the statements below them, while named modifiers are kept separately because they reach definitions above them.
+class RuboCop::Callbacksystems::ClassStructure::Visibility
+  include RuboCop::Callbacksystems::Helpers
+
+  Assignment = Data.define(:kind, :name, :position, :level)
+
+  class << self
+    def for(body)
+      body ? CACHE_LOCK.synchronize { CACHE[body] ||= new(body) } : new(nil)
+    end
+
+    private
+      CACHE = ObjectSpace::WeakMap.new
+      CACHE_LOCK = Mutex.new
+  end
+
+  def initialize(body)
+    @body = body
+  end
+
+  def each_statement
+    if block_given?
+      statements.each_with_index { |statement, index| yield statement, transitions[index] }
+    else
+      to_enum(__method__)
+    end
+  end
+
+  def level_at(node)
+    statement_index_at(node)&.then { transitions[it] } || transitions.last
+  end
+
+  def assignment_after(node, singleton:)
+    assignments.fetch([ singleton ? :singleton : :instance, node.method_name ], []).last&.then do |assignment|
+      assignment if assignment.position >= node.source_range.end_pos
+    end
+  end
+
+  private
+    NAMED_LEVELS = {
+      public: [ :instance, :public ],
+      protected: [ :instance, :protected ],
+      private: [ :instance, :private ],
+      public_class_method: [ :singleton, :public ],
+      private_class_method: [ :singleton, :private ]
+    }
+
+    attr_reader :body
+
+    def statements
+      @statements ||= statements_in(body)
+    end
+
+    def transitions
+      @transitions ||= statements.each_with_object([ :public ]) do |statement, levels|
+        levels << (visibility_modifier_of(statement) || levels.last)
+      end
+    end
+
+    def statement_index_at(node)
+      statement_end_positions.bsearch_index { it > node.source_range.begin_pos }
+    end
+
+    def statement_end_positions
+      @statement_end_positions ||= statements.map { it.source_range.end_pos }
+    end
+
+    def assignments
+      @assignments ||= statements.flat_map { assignments_from(it) }.group_by { [ it.kind, it.name ] }
+    end
+
+    def assignments_from(statement)
+      named_level_of(statement)&.then do |kind, level|
+        name_arguments_of(statement).map do |name|
+          Assignment.new(kind:, name: name.value.to_sym, position: statement.source_range.begin_pos, level:)
+        end
+      end || []
+    end
+
+    def named_level_of(statement)
+      NAMED_LEVELS[statement.method_name] if bare_send?(statement)
+    end
+end

data/lib/rubocop/callbacksystems/cops_document.rb

@@ -0,0 +1,78 @@
+require "yaml"
+
+class RuboCop::Callbacksystems::CopsDocument
+  DEFAULT_PATH = File.expand_path("../../../docs/cops.md", __dir__)
+  HEADING = <<~MARKDOWN
+    # Cops
+
+    <!-- Generated by `bin/docs`. Do not edit by hand. -->
+
+    Every cop lives under the `Callbacksystems/` namespace and ships enabled. Each one links to its source, where an `@example` block contrasts the code it rejects with the code it asks for, and `config/default.yml` holds its options and default scope.
+  MARKDOWN
+  TABLE_HEADER = [ "| Cop | Autocorrect | Description |", "|---|---|---|" ]
+
+  def initialize(path = DEFAULT_PATH)
+    @path = path
+  end
+
+  def save
+    File.write path, text
+  end
+
+  def text
+    [ HEADING, *TABLE_HEADER, *rows, "" ].join("\n")
+  end
+
+  def committed
+    File.read(path)
+  end
+
+  def undescribed
+    rows.select { it.description.blank? }.map(&:name)
+  end
+
+  private
+    SOURCE_DIRECTORY = "../lib/rubocop/cop/callbacksystems"
+
+    attr_reader :path
+
+    def rows
+      @rows ||= cops.map { Row.new(it, descriptions[it.cop_name]) }
+    end
+
+    def cops
+      RuboCop::Cop::Registry.global.cops.select { it.department == :Callbacksystems }.sort_by(&:cop_name)
+    end
+
+    def descriptions
+      YAML.load_file(RuboCop::Callbacksystems::Plugin::CONFIGURATION_PATH).transform_values { it["Description"] }
+    end
+
+    class Row
+      attr_reader :description
+
+      def initialize(cop, description)
+        @cop = cop
+        @description = description
+      end
+
+      def to_s
+        "| [`#{name}`](#{source_path}) | #{autocorrection} | #{description} |"
+      end
+
+      def name
+        cop.cop_name
+      end
+
+      private
+        attr_reader :cop
+
+        def source_path
+          "#{SOURCE_DIRECTORY}/#{cop.badge.cop_name.underscore}.rb"
+        end
+
+        def autocorrection
+          "yes" if cop.support_autocorrect?
+        end
+    end
+end

data/lib/rubocop/callbacksystems/execution/deferred_local_variables.rb

@@ -0,0 +1,138 @@
+# Local variables captured or reassigned by callable bodies that execute after their surrounding expression.
+class RuboCop::Callbacksystems::Execution::DeferredLocalVariables
+  include RuboCop::Callbacksystems::Helpers
+
+  delegate :include?, :exclude?, to: :names
+
+  def initialize(body)
+    @body = body
+  end
+
+  private
+    attr_reader :body
+
+    def names
+      @names ||= Traversal.new(body).to_set.freeze
+    end
+
+    # An iterative lexical walk keeps bindings paired with entry and exit while deferred bodies are visited.
+    class Traversal
+      include Enumerable
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(body)
+        @context = Context.new(Visit.new(body, false))
+      end
+
+      def each
+        if block_given?
+          advance { yield it }
+        else
+          to_enum(__method__)
+        end
+      end
+
+      private
+        attr_reader :context
+
+        def advance
+          context.next_event.perform(context) { yield it } while context.pending?
+        end
+    end
+
+    class Context
+      def initialize(first_event)
+        @pending = [ first_event ]
+        @binding_counts = Hash.new(0)
+      end
+
+      def pending?
+        pending.any?
+      end
+
+      def next_event
+        pending.pop
+      end
+
+      def queue(*events)
+        pending.concat(events.reverse)
+      end
+
+      def enter(names)
+        names.each { binding_counts[it] += 1 }
+      end
+
+      def leave(names)
+        names.each { binding_counts[it] -= 1 }
+      end
+
+      def bound?(name)
+        binding_counts[name].positive?
+      end
+
+      private
+        attr_reader :pending, :binding_counts
+    end
+
+    class Visit < Data.define(:node, :deferred)
+      include RuboCop::Callbacksystems::Helpers
+
+      def perform(context)
+        if node
+          if any_block_type?(node)
+            queue_block(context)
+          elsif lexical_definition?(node)
+            context.queue(*input_visits)
+          else
+            yield variable_name_of(node) if captured_variable?(context)
+            queue_children(context)
+          end
+        end
+      end
+
+      private
+        def queue_block(context)
+          bindings = binding_names
+          body_deferred = deferred || deferred_callable_block?(node) || method_definition_block?(node)
+
+          context.queue \
+            *input_visits,
+            EnterBindings.new(bindings),
+            self.class.new(argument_node, body_deferred),
+            self.class.new(node.body, body_deferred),
+            LeaveBindings.new(bindings)
+        end
+
+        def binding_names
+          node.argument_list.filter_map(&:name)
+        end
+
+        def input_visits
+          immediate_inputs_of(node).map { self.class.new(it, deferred) }
+        end
+
+        def argument_node
+          node.arguments if node.arguments.respond_to?(:type)
+        end
+
+        def captured_variable?(context)
+          deferred && node.type?(:lvar, :lvasgn, :match_var) && !context.bound?(variable_name_of(node))
+        end
+
+        def queue_children(context)
+          context.queue(*node.each_child_node.map { self.class.new(it, deferred) })
+        end
+    end
+
+    class EnterBindings < Data.define(:names)
+      def perform(context)
+        context.enter(names)
+      end
+    end
+
+    class LeaveBindings < Data.define(:names)
+      def perform(context)
+        context.leave(names)
+      end
+    end
+end

data/lib/rubocop/callbacksystems/execution/discarded_expression.rb

@@ -0,0 +1,45 @@
+# Whether an expression's value is ignored, following final values through sequences and definition bodies.
+class RuboCop::Callbacksystems::Execution::DiscardedExpression
+  def initialize(expression)
+    @current = expression
+  end
+
+  def discarded?
+    disposition == :discarded
+  end
+
+  private
+    attr_reader :current
+    delegate :parent, to: :current, private: true
+
+    def disposition
+      advance until @disposition
+      @disposition
+    end
+
+    def advance
+      if parent.nil? || discarded_sequence?
+        @disposition = :discarded
+      elsif transparent?
+        @current = parent
+      else
+        @disposition = :observed
+      end
+    end
+
+    def discarded_sequence?
+      sequence? && current.right_sibling
+    end
+
+    def sequence?
+      parent.type?(:begin, :kwbegin)
+    end
+
+    def transparent?
+      sequence? || definition_body?
+    end
+
+    def definition_body?
+      parent.type?(:class, :module, :sclass) && parent.body.equal?(current)
+    end
+end

data/lib/rubocop/callbacksystems/execution/eager_evaluation_path.rb

@@ -0,0 +1,73 @@
+# The path to a read where an already evaluated value can move without becoming conditional, running repeatedly, or
+# crossing earlier work whose result the moved evaluation could change.
+class RuboCop::Callbacksystems::Execution::EagerEvaluationPath
+  SEQUENTIAL_PARENT_TYPES = %i[
+    array begin block_pass break casgn csend cvasgn dstr dsym erange gvasgn hash irange ivasgn kwbegin lvasgn next pair
+    kwsplat regexp return send splat super yield
+  ]
+  EAGER_FIRST_CHILD_PARENT_TYPES = %i[ and case case_match if or ]
+  BLOCK_PARENT_TYPES = %i[ block numblock itblock ]
+  INERT_NODE_TYPES = %i[ self lvar ]
+
+  def initialize(read, within:)
+    @read = read
+    @boundary = within
+  end
+
+  def preserves_order?
+    read_within_boundary? && steps_preserve_order?
+  end
+
+  private
+    attr_reader :read, :boundary
+
+    def read_within_boundary?
+      read.equal?(boundary) || read.each_ancestor.any? { it.equal?(boundary) }
+    end
+
+    def steps_preserve_order?
+      cursor = read
+      cursor = cursor.parent while !cursor.equal?(boundary) && Step.new(cursor).preserves_order?
+      cursor.equal?(boundary)
+    end
+
+    class Step
+      def initialize(node)
+        @node = node
+      end
+
+      def preserves_order?
+        eager_once? && preceding_nodes.all? { inert?(it) }
+      end
+
+      private
+        attr_reader :node
+
+        delegate :parent, to: :node, private: true
+
+        def eager_once?
+          sequential? || eager_first_child? || immediate_block_call?
+        end
+
+        def sequential?
+          SEQUENTIAL_PARENT_TYPES.include?(parent.type) &&
+            (!parent.csend_type? || parent.receiver.equal?(node))
+        end
+
+        def eager_first_child?
+          EAGER_FIRST_CHILD_PARENT_TYPES.include?(parent.type) && parent.children.first.equal?(node)
+        end
+
+        def immediate_block_call?
+          BLOCK_PARENT_TYPES.include?(parent.type) && parent.send_node.equal?(node)
+        end
+
+        def preceding_nodes
+          parent.each_child_node.take_while { !it.equal?(node) }
+        end
+
+        def inert?(candidate)
+          candidate.recursive_basic_literal? || INERT_NODE_TYPES.include?(candidate.type)
+        end
+    end
+end

data/lib/rubocop/callbacksystems/execution/immediate.rb

@@ -0,0 +1,71 @@
+# The nodes an expression can execute now, without entering a definition or a callable whose body runs later.
+class RuboCop::Callbacksystems::Execution::Immediate
+  include Enumerable
+
+  def initialize(node, deferred_blocks: [])
+    @node = node
+    @deferred_blocks = {}.compare_by_identity
+    deferred_blocks.each { @deferred_blocks[it] = true }
+  end
+
+  def nodes_of_type(*types)
+    select { it.type?(*types) }
+  end
+
+  def each
+    if block_given?
+      execution.each { yield it }
+    else
+      enum_for
+    end
+  end
+
+  private
+    attr_reader :node, :deferred_blocks
+
+    def execution
+      Traversal.new(node, deferred_blocks)
+    end
+
+    # An iterative walk that keeps its cursor and pending nodes together with the shared boundary index.
+    class Traversal
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(node, deferred_blocks)
+        @pending = [ node ]
+        @deferred_blocks = deferred_blocks
+      end
+
+      def each
+        until pending.empty?
+          advance
+          visit { yield it } if current
+        end
+      end
+
+      private
+        attr_reader :pending, :deferred_blocks, :current
+
+        def advance
+          @current = pending.pop
+        end
+
+        def visit
+          if execution_boundary?
+            queue immediate_inputs_of(current)
+          else
+            yield current
+            queue current.each_child_node
+          end
+        end
+
+        def execution_boundary?
+          lexical_definition?(current) || deferred_callable_block?(current) || method_definition_block?(current) ||
+            deferred_blocks.key?(current)
+        end
+
+        def queue(nodes)
+          pending.concat(nodes.to_a.reverse)
+        end
+    end
+end