kaizo 0.7.0 → 0.9.2

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

@@ -9,12 +9,34 @@ module RuboCop
       # `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
+      # By default only `*_spec.rb` files are inspected, and `spec/helpers` and
+      # `spec/support` are excluded -- they hold infrastructure, not specs. 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.
       #
+      # == Configuration
+      #
+      # [+Include+] Files the cop runs on. Default: <tt>**/*_spec.rb</tt>.
+      #             Broaden it to cover support files or a Minitest suite.
+      # [+Exclude+] Files the cop skips even when included. Default:
+      #             <tt>**/spec/helpers/**/*</tt> and
+      #             <tt>**/spec/support/**/*</tt>. Set it to <tt>[]</tt> to
+      #             inspect those too.
+      # [+AllowedPatterns+] Regexps matched against the full comment text,
+      #                     leading +#+ included; a match is exempt.
+      #                     Default: none.
+      #
+      #   Kaizo/SpecComment:
+      #     inherit_mode:
+      #       merge:
+      #         - Include
+      #     Include:
+      #       - '**/*_test.rb'     # Minitest too
+      #     AllowedPatterns:
+      #       - '\A#\s*@rbs'       # rbs-inline type annotations
+      #
       # @example
       #   # bad
       #   it 'permits the request' do

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

@@ -5,16 +5,19 @@ module RuboCop
       # 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.
+      # is several behaviors), a forbidden word (`ForbiddenWords` -- conjunctions
+      # join clauses that are separate examples; a conditional signals a hidden
+      # `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.
+      # `RequiredContextPrefixes` (`when`/`with`/`without`/`after`). `describe`
+      # strings name the unit under test and are exempt. An error class name
+      # (`Foo::Error`, `Timeout::DeadlineException`) reads as prose, not code:
+      # the error is part of the specified behavior and is what the user
+      # ultimately sees raised.
       #
       # 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
@@ -23,6 +26,32 @@ module RuboCop
       # There is no autocorrection: splitting an example, or extracting a
       # condition into a `context`, is a modelling decision for a human.
       #
+      # == Configuration
+      #
+      # [+ForbiddenWords+] Words that force a split when they appear in an
+      #                    example description, matched as whole words, case
+      #                    insensitively. Default: +and+, +but+, +or+, +nor+,
+      #                    +so+, +yet+, +when+, +whenever+, +if+, +unless+,
+      #                    +while+, +until+, +because+, +although+, +though+.
+      # [+RequiredContextPrefixes+] Words a `context` description may open
+      #                             with. Default: +when+, +with+, +without+,
+      #                             +after+.
+      # [+AllowedPatterns+] Regexps matched against the whole description; a
+      #                     match exempts it from every rule. The escape hatch
+      #                     for a description that must quote something
+      #                     code-shaped. Default: none.
+      # [+Include+] Files the cop runs on. Default: <tt>**/*_spec.rb</tt>.
+      #
+      #   Kaizo/SpecDescriptionProse:
+      #     inherit_mode:
+      #       merge:
+      #         - ForbiddenWords
+      #         - AllowedPatterns
+      #     ForbiddenWords:
+      #       - given            # flag `given ...` too
+      #     AllowedPatterns:
+      #       - 'Foo::Widget'    # allow this one identifier
+      #
       # @example
       #   # bad
       #   it "renders the name, image, and flag"
@@ -39,6 +68,8 @@ module RuboCop
       #   end
       #
       class SpecDescriptionProse < Base
+        include AllowedPattern
+
         EXAMPLE_METHODS = %i[
           it specify example fit xit fspecify xspecify fexample xexample
         ].freeze
@@ -46,8 +77,8 @@ module RuboCop
         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
+        FORBIDDEN_WORD_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
@@ -57,15 +88,19 @@ module RuboCop
         # 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[
+        DEFAULT_FORBIDDEN_WORDS = %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
+        DEFAULT_REQUIRED_CONTEXT_PREFIXES = %w[when with without after].freeze
 
         CODE_CHARS = /[_:#={}!`\[\]]/
         NESTED_QUOTE = /(['"]).+\1/
 
+        # An error class name is part of the specified behavior -- it is what
+        # the user sees raised -- so it is masked to prose before the checks.
+        ERROR_CONSTANT = /(?:::)?\b(?:[A-Z]\w*::)*(?:[A-Z]\w*)?(?:Error|Exception)\b/
+
         # @!method description(node)
         def_node_matcher :description, <<~PATTERN
           (send nil? _ (str $_) ...)
@@ -74,15 +109,20 @@ module RuboCop
         def on_send(node)
           text = description(node)
           return unless text
+          return if matches_allowed_pattern?(text)
 
-          message = violation(node.method_name, text)
+          message = violation(node.method_name, without_error_constants(text))
           return unless message
 
-          add_offense(node.first_argument, message: message)
+          add_offense(node.first_argument, message:)
         end
 
         private
 
+        def without_error_constants(text)
+          text.gsub(ERROR_CONSTANT, "error")
+        end
+
         def violation(method, text)
           if EXAMPLE_METHODS.include?(method)
             example_violation(text)
@@ -94,8 +134,8 @@ module RuboCop
         def example_violation(text)
           return COMMA_MSG if text.include?(",")
 
-          word = forbidden(text, conjunctions)
-          return format(CONJUNCTION_MSG, word: word) if word
+          word = forbidden(text, forbidden_words)
+          return format(FORBIDDEN_WORD_MSG, word:) if word
 
           CODE_MSG if code?(text)
         end
@@ -116,19 +156,19 @@ module RuboCop
         end
 
         def prefix_regexp
-          /\A\s*(?:#{context_prefixes.map { |prefix| Regexp.escape(prefix) }.join("|")})\b/i
+          /\A\s*(?:#{required_context_prefixes.map { |prefix| Regexp.escape(prefix) }.join("|")})\b/i
         end
 
         def quoted_prefixes
-          context_prefixes.map { |prefix| "`#{prefix}`" }.join("/")
+          required_context_prefixes.map { |prefix| "`#{prefix}`" }.join("/")
         end
 
-        def conjunctions
-          cop_config.fetch("Conjunctions", DEFAULT_CONJUNCTIONS)
+        def forbidden_words
+          cop_config.fetch("ForbiddenWords", DEFAULT_FORBIDDEN_WORDS)
         end
 
-        def context_prefixes
-          cop_config.fetch("ContextPrefixes", DEFAULT_CONTEXT_PREFIXES)
+        def required_context_prefixes
+          cop_config.fetch("RequiredContextPrefixes", DEFAULT_REQUIRED_CONTEXT_PREFIXES)
         end
       end
     end

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

@@ -0,0 +1,117 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Requires the unit under test to be declared with `subject`, not `let`.
+      # `subject` is RSpec's name for the object being specified; hiding it in a
+      # `let` obscures which object the examples are about and forfeits
+      # `is_expected`/one-liner syntax.
+      #
+      # A `let` (or `let!`) is flagged when the value it returns is confidently
+      # an instance of the class under test: the block's final expression is a
+      # `.new` call on `described_class`, on the constant named by an enclosing
+      # `describe`/`context` (full or short name), or on a constant matching the
+      # spec's file name (`pool_spec.rb` names `Pool`, `api_client_spec.rb`
+      # names `APIClient`).
+      #
+      # A `let` that builds a second instance on purpose -- an `other` for an
+      # equality spec, say -- is exempted through `AllowedMethods` or
+      # `AllowedPatterns`, both matched against the `let` name.
+      #
+      # There is no autocorrection: renaming the helper every example refers to
+      # is a change the spec's author should make deliberately.
+      #
+      # == Configuration
+      #
+      # [+AllowedMethods+] `let` names never flagged. Default: none.
+      # [+AllowedPatterns+] Regexps matched against the `let` name; a match is
+      #                     exempt. Default: none.
+      # [+Include+] Files the cop runs on. Default: <tt>**/*_spec.rb</tt>.
+      #
+      #   Kaizo/SpecSubject:
+      #     AllowedMethods:
+      #       - other       # a second instance for equality specs
+      #     AllowedPatterns:
+      #       - '\Aother_'
+      #
+      # @example
+      #   # bad
+      #   RSpec.describe Session::Pool do
+      #     let(:pool) { described_class.new }
+      #   end
+      #
+      #   # good
+      #   RSpec.describe Session::Pool do
+      #     subject(:pool) { described_class.new }
+      #   end
+      #
+      # @example AllowedMethods: ['other'] (default: [])
+      #   # good - a deliberate second instance
+      #   RSpec.describe Session::Pool do
+      #     subject(:pool) { described_class.new }
+      #
+      #     let(:other) { described_class.new }
+      #   end
+      #
+      class SpecSubject < Base
+        include AllowedMethods
+        include AllowedPattern
+
+        MSG = "Declare the unit under test with `subject(:%<name>s)`, not `let`.".freeze
+
+        # @!method let_declaration(node)
+        def_node_matcher :let_declaration, <<~PATTERN
+          (block (send nil? {:let :let!} (sym $_)) _ $_)
+        PATTERN
+
+        # @!method constructed_class(node)
+        def_node_matcher :constructed_class, <<~PATTERN
+          (send ${(send nil? :described_class) (const _ _)} :new ...)
+        PATTERN
+
+        # @!method described_constant(node)
+        def_node_matcher :described_constant, <<~PATTERN
+          (block (send {(const {nil? cbase} :RSpec) nil?} {:describe :context} $(const ...) ...) ...)
+        PATTERN
+
+        def on_block(node)
+          name, body = let_declaration(node)
+          return unless name
+          return if allowed_method?(name) || matches_allowed_pattern?(name.to_s)
+          return unless unit_under_test?(node, final_expression(body))
+
+          add_offense(node.send_node.loc.selector, message: format(MSG, name:))
+        end
+
+        private
+
+        def final_expression(body)
+          body&.begin_type? ? body.children.last : body
+        end
+
+        def unit_under_test?(node, expression)
+          receiver = expression && constructed_class(expression)
+          return false unless receiver
+          return true if receiver.send_type?
+
+          described?(node, receiver)
+        end
+
+        def described?(node, const_node)
+          described_constants(node).any? do |described|
+            described.const_name == const_node.const_name ||
+              described.short_name == const_node.short_name
+          end || file_named_after?(const_node.short_name)
+        end
+
+        def described_constants(node)
+          node.each_ancestor(:block).filter_map { |ancestor| described_constant(ancestor) }
+        end
+
+        def file_named_after?(short_name)
+          base = processed_source.file_path&.[](%r{([^/]+)_spec\.rb\z}, 1)
+          base && short_name.to_s.downcase == base.delete("_")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Requires temporary files to be created with block-form `Tempfile.create`,
+      # and flags `Tempfile.new`, `Tempfile.open`, and blockless `Tempfile.create`.
+      #
+      # Only the block form cleans up deterministically: the file is closed and
+      # removed when the block returns, however it returns. A `Tempfile` built
+      # with `.new` or `.open` is removed by a GC finalizer that runs at some
+      # unpredictable point -- possibly never -- and blockless `Tempfile.create`
+      # hands back a plain `File` that is never removed automatically at all.
+      #
+      # There is no autocorrection: moving the file's users into the block is a
+      # restructuring, and the block's return value replaces the handle the old
+      # code held onto.
+      #
+      # == Configuration
+      #
+      # No cop-specific options; the standard per-cop settings (+Enabled+,
+      # +Severity+, +Include+/+Exclude+) apply.
+      #
+      # @example
+      #   # bad
+      #   file = Tempfile.new("report")
+      #   file = Tempfile.open("report")
+      #   file = Tempfile.create("report")
+      #
+      #   # good
+      #   Tempfile.create("report") do |file|
+      #     file.write(data)
+      #   end
+      #
+      class TempfileCreate < Base
+        MSG = "Use `Tempfile.create` with a block instead of `Tempfile.%<method>s`; " \
+              "finalizer-based cleanup is unpredictable.".freeze
+        BLOCKLESS_CREATE_MSG = "Pass a block to `Tempfile.create`; " \
+                               "without one the file is never removed.".freeze
+
+        RESTRICT_ON_SEND = %i[new open create].freeze
+
+        # @!method tempfile_call?(node)
+        def_node_matcher :tempfile_call?, <<~PATTERN
+          (send (const {nil? cbase} :Tempfile) _ ...)
+        PATTERN
+
+        def on_send(node)
+          return unless tempfile_call?(node)
+          return if node.method?(:create) && block_given_to?(node)
+
+          range = node.receiver.source_range.join(node.loc.selector)
+          add_offense(range, message: message_for(node))
+        end
+
+        private
+
+        def message_for(node)
+          return BLOCKLESS_CREATE_MSG if node.method?(:create)
+
+          format(MSG, method: node.method_name)
+        end
+
+        def block_given_to?(node)
+          return true if node.last_argument&.block_pass_type?
+
+          parent = node.parent
+          parent&.any_block_type? && parent.send_node.equal?(node)
+        end
+      end
+    end
+  end
+end

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

@@ -12,6 +12,24 @@ module RuboCop
       # `initialize` of a `Struct.new`/`Data.define` block is exempt, since those
       # parameters mirror the value object's attributes.
       #
+      # == Configuration
+      #
+      # [+Max+] Most arguments -- positional plus keyword -- a method may
+      #         declare. Default: +2+.
+      # [+AllowedMethods+] Method names exempt from the limit. Default: none.
+      # [+AllowedPatterns+] Regexps matched against the method name; a match is
+      #                     exempt. Default: none.
+      # [+Exclude+] Paths the cop skips. Default: <tt>**/spec/**/*</tt> and
+      #             <tt>**/test/**/*</tt>, matching `KeywordArguments` -- a
+      #             total bound would re-police the keyword freedom tests get.
+      #             `PositionalArguments` alone still bounds positional
+      #             arguments there. Set it to <tt>[]</tt> to police tests too.
+      #
+      #   Kaizo/TotalArguments:
+      #     Max: 3
+      #     AllowedMethods:
+      #       - initialize
+      #
       # @example Max: 3
       #   # bad
       #   def calculate_volume(width, length, height, shape_type)

data/lib/rubocop/cop/kaizo_cops.rb

@@ -1,12 +1,15 @@
 require_relative "kaizo/argument_counting"
 require_relative "kaizo/keyword_arguments"
+require_relative "kaizo/plural_collection_name"
 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/spec_subject"
 require_relative "kaizo/file_utils_inclusion"
 require_relative "kaizo/prefer_pathname"
 require_relative "kaizo/explicit_begin"
 require_relative "kaizo/next_in_non_void_enumerable"
+require_relative "kaizo/tempfile_create"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kaizo
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.2
 platform: ruby
 authors:
 - David Gillis
@@ -62,10 +62,13 @@ files:
 - lib/rubocop/cop/kaizo/keyword_arguments.rb
 - lib/rubocop/cop/kaizo/nested_method_calls.rb
 - lib/rubocop/cop/kaizo/next_in_non_void_enumerable.rb
+- lib/rubocop/cop/kaizo/plural_collection_name.rb
 - lib/rubocop/cop/kaizo/positional_arguments.rb
 - lib/rubocop/cop/kaizo/prefer_pathname.rb
 - lib/rubocop/cop/kaizo/spec_comment.rb
 - lib/rubocop/cop/kaizo/spec_description_prose.rb
+- lib/rubocop/cop/kaizo/spec_subject.rb
+- lib/rubocop/cop/kaizo/tempfile_create.rb
 - lib/rubocop/cop/kaizo/total_arguments.rb
 - lib/rubocop/cop/kaizo_cops.rb
 homepage: https://github.com/flipmine/kaizo
@@ -90,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.18
 specification_version: 4
 summary: A strict, punishing set of RuboCop design cops for AI-agent-authored Ruby.
 test_files: []