kaizo 0.7.0

data/lib/rubocop/cop/kaizo/nested_method_calls.rb

@@ -0,0 +1,130 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks for method calls nested too deeply in argument positions.
+      #
+      # A call whose arguments are themselves the results of other calls --
+      # `foo(SomeClass.new(another("bar").chain))` -- packs several steps into one
+      # expression. Naming the intermediate results (or extracting a method) almost
+      # always reads better and is easier to debug than peeling parentheses apart.
+      #
+      # Only nesting through *argument* positions is counted; a receiver chain such
+      # as `user.account.owner.name` is a separate concern. Operator methods
+      # (`a + b`, `arr[i]`) never count, and calls to `AllowedMethods` are exempt.
+      # Depth is measured from each outermost call and reported once. There is no
+      # autocorrection: choosing the intermediate name is a design decision.
+      #
+      # @example Max: 1 (default)
+      #   # bad
+      #   foo(SomeClass.new(another("bar").chain))
+      #
+      #   # bad
+      #   wrap(parse(read(io)))
+      #
+      #   # good - name the intermediate result
+      #   parsed = parse(read(io))
+      #   wrap(parsed)
+      #
+      #   # good - a single nested call is allowed
+      #   puts compute(value)
+      #
+      class NestedMethodCalls < Base
+        include AllowedMethods
+
+        exclude_limit "Max"
+
+        MSG = "Avoid nesting method calls in arguments; name an intermediate " \
+              "result instead. [%<depth>d/%<max>d]".freeze
+
+        # Node types whose children sit in argument position -- looked through to
+        # reach nested calls (but never into a block body).
+        TRANSPARENT_ARGUMENT_TYPES = %i[array hash begin pair splat kwsplat].freeze
+
+        def on_send(node)
+          return if nested_in_call_argument?(node)
+          return if allowed_method?(node.method_name)
+
+          max = cop_config["Max"]
+          depth = nesting_depth(node)
+          return unless max && depth > max
+
+          add_offense(node, message: format(MSG, depth: depth, max: max)) do
+            self.max = depth
+          end
+        end
+        alias on_csend on_send
+
+        private
+
+        # Longest chain of significant calls reachable through this call's
+        # argument positions. Receivers and block bodies are not traversed.
+        def nesting_depth(call)
+          nested = argument_calls(call)
+          return 0 if nested.empty?
+
+          1 + nested.map { |inner| nesting_depth(inner) }.max
+        end
+
+        def argument_calls(call)
+          call.arguments.flat_map { |argument| calls_in(argument) }
+        end
+
+        # Significant calls at the top of an argument expression, seen through
+        # array/hash literals but never into a block body.
+        def calls_in(node)
+          return significant_calls(node) if node.call_type?
+          return significant_calls(node.send_node) if node.any_block_type?
+          return [] unless TRANSPARENT_ARGUMENT_TYPES.include?(node.type)
+
+          node.children.flat_map { |child| calls_in(child) }
+        end
+
+        # `node` wrapped in an array when it is a significant call, else empty.
+        def significant_calls(node)
+          significant_call?(node) ? [node] : []
+        end
+
+        def significant_call?(node)
+          return false unless node.call_type?
+          return false if node.operator_method?
+          return false if allowed_method?(node.method_name)
+
+          chain_takes_arguments?(node)
+        end
+
+        # A call reads as a real nested step -- rather than a plain receiver
+        # chain like `user.account.owner.name` -- only when it, or some call in
+        # its receiver chain, actually takes arguments. Bare reader chains do
+        # not count (that is the planned chaining cop's concern), while
+        # `another("bar").chain` still does.
+        def chain_takes_arguments?(node)
+          return false unless node.call_type?
+          return true if node.arguments.any?
+
+          node.receiver ? chain_takes_arguments?(node.receiver) : false
+        end
+
+        # Whether `node` sits in an enclosing call's argument list (through
+        # literal containers or the call a block is attached to), so an outer
+        # call already accounts for it.
+        def nested_in_call_argument?(node)
+          parent = node.parent
+          return false unless parent
+          return parent.arguments.include?(node) if parent.call_type?
+          return nested_in_call_argument?(parent) if reached_through?(parent, node)
+
+          false
+        end
+
+        # A parent an outer call sees through to reach `node`: any literal
+        # container, or a block -- but only via the call it is attached to,
+        # never its body.
+        def reached_through?(parent, node)
+          return true if TRANSPARENT_ARGUMENT_TYPES.include?(parent.type)
+
+          parent.any_block_type? && parent.send_node.equal?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/next_in_non_void_enumerable.rb

@@ -0,0 +1,134 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Flags `next` used inside the block of a value-returning `Enumerable`
+      # method such as `map`, `select`, or `reduce`, whose block value is
+      # significant. In those methods `next` doubles as a way to produce the
+      # block's value through control flow, which this cop discourages in
+      # favor of an expression that produces the value directly.
+      #
+      # "Void" iteration methods, whose block return value is ignored (`each`,
+      # `each_with_index`, `each_slice`, `each_with_object`, `reverse_each`,
+      # and so on), are intentionally *not* flagged: there `next` merely skips
+      # to the next iteration. The same goes for non-`Enumerable` looping
+      # constructs such as `loop`, `Integer#times`, and `while`. Additional
+      # methods can be exempted through `AllowedMethods` / `AllowedPatterns`.
+      #
+      # A `next` that binds to a nested block or loop is attributed to that
+      # inner scope, so an inner `each { next }` does not flag an outer `map`.
+      #
+      # There is no autocorrection: the right fix depends on intent -- a guard
+      # clause might become a ternary, a `select`/`reject`, a `filter_map`, or a
+      # restructured block.
+      #
+      # @example
+      #   # bad
+      #   array.map do |item|
+      #     next if skip?(item)
+      #
+      #     transform(item)
+      #   end
+      #
+      #   # bad - `next <value>` is still control-flow-as-value
+      #   array.reduce(0) do |sum, item|
+      #     next sum if skip?(item)
+      #
+      #     sum + item
+      #   end
+      #
+      #   # good - a void iteration method skips with `next`
+      #   array.each do |item|
+      #     next if skip?(item)
+      #
+      #     process(item)
+      #   end
+      #
+      #   # good - express the intent with a value-returning form
+      #   array.filter_map do |item|
+      #     transform(item) unless skip?(item)
+      #   end
+      #
+      # @example AllowedMethods: ['reduce'] (default: [])
+      #   # good - `reduce` exempted by configuration
+      #   array.reduce(0) do |sum, item|
+      #     next sum if skip?(item)
+      #
+      #     sum + item
+      #   end
+      #
+      class NextInNonVoidEnumerable < Base
+        include AllowedMethods
+        include AllowedPattern
+
+        MSG = "Avoid `next` inside `%<method>s`; return a value from the " \
+              "block instead of using `next` for control flow.".freeze
+
+        # `Enumerable` methods whose block return value determines the result.
+        # Void iteration methods (`each`, `each_with_object`, `reverse_each`,
+        # `cycle`, ...) are deliberately absent, which is why `next` is allowed
+        # in them.
+        FLAGGED_METHODS = %i[
+          all? any? none? one?
+          chunk_while
+          collect collect_concat
+          count
+          detect
+          drop_while
+          filter filter_map find find_all find_index
+          flat_map
+          grep grep_v
+          group_by
+          inject
+          map
+          max_by min_by minmax_by
+          partition
+          reduce reject
+          select
+          slice_when
+          sort_by
+          sum
+          take_while
+        ].freeze
+
+        # Node types that introduce a new `next` binding. A `next` found below
+        # one of these belongs to that inner scope, not the enumerable block
+        # under inspection, so descent stops here.
+        SCOPE_BOUNDARIES = %i[
+          block numblock itblock while until while_post until_post for
+        ].freeze
+
+        def on_block(node)
+          call = node.children.first
+          return unless call.respond_to?(:method_name)
+
+          method = call.method_name
+          return unless FLAGGED_METHODS.include?(method)
+          return if allowed_method?(method) || matches_allowed_pattern?(method.to_s)
+
+          flag_block_local_nexts(node, method)
+        end
+        alias on_numblock on_block
+        alias on_itblock on_block
+
+        private
+
+        def flag_block_local_nexts(block_node, method)
+          message = format(MSG, method: method)
+
+          block_node.each_child_node do |child|
+            each_block_local_next(child) do |next_node|
+              add_offense(next_node.loc.keyword, message: message)
+            end
+          end
+        end
+
+        def each_block_local_next(node, &)
+          yield node if node.next_type?
+          return if SCOPE_BOUNDARIES.include?(node.type)
+
+          node.each_child_node { |child| each_block_local_next(child, &) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/positional_arguments.rb

@@ -0,0 +1,35 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks that a method does not declare too many positional arguments.
+      #
+      # Positional arguments are unnamed and order-dependent, which makes a long
+      # list of them especially prone to primitive obsession. Required (`arg`)
+      # and optional (`optarg`) parameters are counted; `*rest` and `&block` are
+      # not.
+      #
+      # @example Max: 2
+      #   # bad
+      #   def move(x, y, z)
+      #   end
+      #
+      #   # good
+      #   def move(point)
+      #   end
+      #
+      class PositionalArguments < Base
+        include ArgumentCounting
+
+        exclude_limit "Max"
+
+        KIND = "positional arguments".freeze
+
+        private
+
+        def arity(arguments)
+          positional_arity(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/prefer_pathname.rb

@@ -0,0 +1,63 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Prefer `Pathname` over `File` for the operations `Pathname` provides.
+      #
+      # Once a path is a `Pathname`, calling `pathname.read` or `pathname.exist?`
+      # reads better than threading a string through `File.read(...)` or
+      # `File.exist?(...)`. This cop flags calls to `File` class methods that have
+      # a `Pathname` instance-method equivalent.
+      #
+      # By default the cop runs on `**/*.rb` and skips `exe/**/*` and `bin/**/*`
+      # (executables often work with raw path strings); adjust with the standard
+      # `Include`/`Exclude` options.
+      #
+      # There is no autocorrection: rewriting `File.read(path)` as
+      # `Pathname(path).read` changes the receiver and is left to a human.
+      #
+      # @example
+      #   # bad
+      #   File.read(path)
+      #   File.exist?(path)
+      #   File.join(dir, name)
+      #
+      #   # good
+      #   path.read
+      #   path.exist?
+      #   dir.join(name)
+      #
+      class PreferPathname < Base
+        MSG = "Use `Pathname#%<method>s` instead of `File.%<method>s`.".freeze
+
+        # `File` class methods that have a `Pathname` instance-method equivalent:
+        # the intersection of File's class methods and Pathname's own public
+        # instance methods, excluding generic Object methods. `public_` matters:
+        # `Pathname#path` is protected, so `File.path` must not be suggested.
+        # Regenerate with:
+        #   (Pathname.public_instance_methods(false) & File.methods).reject { |m| Object.respond_to?(m) }.sort
+        RESTRICT_ON_SEND = %i[
+          atime basename binread binwrite birthtime blockdev? chardev? chmod
+          chown ctime delete directory? dirname empty? executable?
+          executable_real? exist? expand_path extname file? fnmatch fnmatch?
+          ftype grpowned? join lchmod lchown lstat lutime mtime open owned?
+          pipe? read readable? readable_real? readlines readlink
+          realdirpath realpath rename setgid? setuid? size size? socket? split
+          stat sticky? symlink? sysopen truncate unlink utime world_readable?
+          world_writable? writable? writable_real? write zero?
+        ].freeze
+
+        # @!method file_call?(node)
+        def_node_matcher :file_call?, <<~PATTERN
+          (send (const {nil? cbase} :File) _ ...)
+        PATTERN
+
+        def on_send(node)
+          return unless file_call?(node)
+
+          range = node.receiver.source_range.join(node.loc.selector)
+          add_offense(range, message: format(MSG, method: node.method_name))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/spec_comment.rb

@@ -0,0 +1,75 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks for comments in spec files.
+      #
+      # A comment in a spec is almost always a sign that the spec is doing the
+      # job of its own description. If you need a sentence to explain what an
+      # example sets up or asserts, that sentence usually wants to be a
+      # `context`/`it` description, a clearer example name, or another example --
+      # not prose riding alongside the code.
+      #
+      # By default only `*_spec.rb` files are inspected (see `Include`). Magic
+      # comments (`# frozen_string_literal: true`, `# encoding: ...`), RuboCop
+      # directives (any `# rubocop:` comment), and shebangs are
+      # never flagged; add further exemptions with `AllowedPatterns`. There is no
+      # autocorrection: turning an explanation into a spec is a design decision.
+      #
+      # @example
+      #   # bad
+      #   it 'permits the request' do
+      #     # an admin can see everything
+      #     user = create(:user, admin: true)
+      #     expect(policy).to permit(user)
+      #   end
+      #
+      #   # good
+      #   it 'permits an admin to see everything' do
+      #     admin = create(:user, admin: true)
+      #     expect(policy).to permit(admin)
+      #   end
+      #
+      class SpecComment < Base
+        include AllowedPattern
+
+        MSG = "Avoid comments in specs. Express the intent as a `context`/`it` " \
+              "description or a clearer example instead.".freeze
+
+        def on_new_investigation
+          processed_source.comments.each do |comment|
+            next if allowed?(comment)
+
+            add_offense(comment)
+          end
+        end
+
+        private
+
+        def allowed?(comment)
+          magic_comment?(comment) ||
+            directive_comment?(comment) ||
+            shebang?(comment) ||
+            matches_allowed_pattern?(comment.text)
+        end
+
+        def magic_comment?(comment)
+          comment.loc.line <= leading_magic_comment_limit && MagicComment.parse(comment.text).any?
+        end
+
+        # Magic comments are only honoured at the top of the file (the first
+        # line, or the second after a shebang); below that they are plain comments.
+        def leading_magic_comment_limit
+          processed_source.lines.first&.start_with?("#!") ? 2 : 1
+        end
+
+        def directive_comment?(comment)
+          DirectiveComment.new(comment).start_with_marker?
+        end
+
+        def shebang?(comment)
+          comment.text.start_with?("#!")
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/spec_description_prose.rb

@@ -0,0 +1,136 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Requires RSpec `it`/`context` descriptions to read as one-behavior prose
+      # specifications, after the spec-skeleton naming law.
+      #
+      # An `it`/`specify`/`example` description must not contain a comma (a list
+      # is several behaviors), a coordinating or conditional conjunction
+      # (`Conjunctions` -- joined clauses are separate examples; a condition
+      # belongs in a `context`), or code (`_ : # = { } ! [ ]`, a backtick, or a
+      # nested quoted literal -- a description is prose, not identifiers or wire
+      # values). Each rule is structural: it signals that one example is really
+      # more than one, or that the assertion is leaking into the name.
+      #
+      # A `context` description must not contain code, and must open with one of
+      # `ContextPrefixes` (`when`/`with`/`without`/`after`). `describe` strings
+      # name the unit under test and are exempt.
+      #
+      # Wording preferences that do not change the spec's structure (e.g. `should`
+      # vs a present-tense verb) are out of scope -- see rubocop-rspec's
+      # `RSpec/ExampleWording`.
+      #
+      # There is no autocorrection: splitting an example, or extracting a
+      # condition into a `context`, is a modelling decision for a human.
+      #
+      # @example
+      #   # bad
+      #   it "renders the name, image, and flag"
+      #   it "omits the key when the role is unset"
+      #   it "renders the :cpu member"
+      #   context "the role is unset" do
+      #   end
+      #
+      #   # good
+      #   it "renders the name"
+      #   it "renders the cpu member"
+      #   context "when the role is unset" do
+      #     it "omits the key"
+      #   end
+      #
+      class SpecDescriptionProse < Base
+        EXAMPLE_METHODS = %i[
+          it specify example fit xit fspecify xspecify fexample xexample
+        ].freeze
+        CONTEXT_METHODS = %i[context fcontext xcontext].freeze
+        RESTRICT_ON_SEND = (EXAMPLE_METHODS + CONTEXT_METHODS).freeze
+
+        COMMA_MSG = "Split this example: its description contains a comma.".freeze
+        CONJUNCTION_MSG = "Split this example: its description contains `%<word>s`; " \
+                          "use separate examples or a `context`.".freeze
+        CODE_MSG = "Write the description as prose; it contains code, not English.".freeze
+        CONTEXT_CODE_MSG = "Write the context description as prose; it contains code, not English.".freeze
+        CONTEXT_PREFIX_MSG = "Begin the context description with %<prefixes>s.".freeze
+
+        # Coordinating (FANBOYS, minus the preposition-heavy `for`) plus the
+        # conditional subordinators that reliably signal a hidden "given".
+        # Homographs like `even`/`given`/`regardless` are deliberately absent --
+        # they collide with adjectives/nouns (`even numbers`) -- add them via
+        # config if you want them.
+        DEFAULT_CONJUNCTIONS = %w[
+          and but or nor so yet
+          when whenever if unless while until because although though
+        ].freeze
+        DEFAULT_CONTEXT_PREFIXES = %w[when with without after].freeze
+
+        CODE_CHARS = /[_:#={}!`\[\]]/
+        NESTED_QUOTE = /(['"]).+\1/
+
+        # @!method description(node)
+        def_node_matcher :description, <<~PATTERN
+          (send nil? _ (str $_) ...)
+        PATTERN
+
+        def on_send(node)
+          text = description(node)
+          return unless text
+
+          message = violation(node.method_name, text)
+          return unless message
+
+          add_offense(node.first_argument, message: message)
+        end
+
+        private
+
+        def violation(method, text)
+          if EXAMPLE_METHODS.include?(method)
+            example_violation(text)
+          else
+            context_violation(text)
+          end
+        end
+
+        def example_violation(text)
+          return COMMA_MSG if text.include?(",")
+
+          word = forbidden(text, conjunctions)
+          return format(CONJUNCTION_MSG, word: word) if word
+
+          CODE_MSG if code?(text)
+        end
+
+        def context_violation(text)
+          return CONTEXT_CODE_MSG if code?(text)
+          return if text.match?(prefix_regexp)
+
+          format(CONTEXT_PREFIX_MSG, prefixes: quoted_prefixes)
+        end
+
+        def code?(text)
+          CODE_CHARS.match?(text) || NESTED_QUOTE.match?(text)
+        end
+
+        def forbidden(text, words)
+          words.find { |word| text.match?(/\b#{Regexp.escape(word)}\b/i) }
+        end
+
+        def prefix_regexp
+          /\A\s*(?:#{context_prefixes.map { |prefix| Regexp.escape(prefix) }.join("|")})\b/i
+        end
+
+        def quoted_prefixes
+          context_prefixes.map { |prefix| "`#{prefix}`" }.join("/")
+        end
+
+        def conjunctions
+          cop_config.fetch("Conjunctions", DEFAULT_CONJUNCTIONS)
+        end
+
+        def context_prefixes
+          cop_config.fetch("ContextPrefixes", DEFAULT_CONTEXT_PREFIXES)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo/total_arguments.rb

@@ -0,0 +1,39 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks that a method does not declare too many arguments in total
+      # (positional plus keyword).
+      #
+      # The goal is to apply pressure toward good domain modeling: a long
+      # argument list is often a sign of primitive obsession, and bundling the
+      # related values into an object usually expresses the intent better.
+      #
+      # `*rest`, `**keyword-rest`, and `&block` arguments are not counted. The
+      # `initialize` of a `Struct.new`/`Data.define` block is exempt, since those
+      # parameters mirror the value object's attributes.
+      #
+      # @example Max: 3
+      #   # bad
+      #   def calculate_volume(width, length, height, shape_type)
+      #   end
+      #
+      #   # good
+      #   def calculate_volume(shape)
+      #   end
+      #
+      class TotalArguments < Base
+        include ArgumentCounting
+
+        exclude_limit "Max"
+
+        KIND = "arguments".freeze
+
+        private
+
+        def arity(arguments)
+          positional_arity(arguments) + keyword_arity(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/kaizo_cops.rb

@@ -0,0 +1,12 @@
+require_relative "kaizo/argument_counting"
+require_relative "kaizo/keyword_arguments"
+require_relative "kaizo/positional_arguments"
+require_relative "kaizo/total_arguments"
+require_relative "kaizo/agent_noun_class_name"
+require_relative "kaizo/nested_method_calls"
+require_relative "kaizo/spec_comment"
+require_relative "kaizo/spec_description_prose"
+require_relative "kaizo/file_utils_inclusion"
+require_relative "kaizo/prefer_pathname"
+require_relative "kaizo/explicit_begin"
+require_relative "kaizo/next_in_non_void_enumerable"