betterlint 1.28.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 070e58e2493975205fb3f5f52f1c6082109835db4388e67d7876bfd471861e59
-  data.tar.gz: 73a4c6ddd11054bd6b2c3add1e3963f62b6849241b2eb4be2a41a1bec41cc2f7
+  metadata.gz: 4be70714f121b7f33abf6c01f95ff109af80785e27d242225d3e4b0dcf3baa2a
+  data.tar.gz: 233a10f1796cd42ebdebfa2ef715d7252f9d30abc6498e4f5cb5cec57b3f28a9
 SHA512:
-  metadata.gz: c212dd812b46431b40bea0876f5aeefe5d4f657ef59bb0355342a4e22d19e167cbe950ca7edd237ad581e17cc2400f7c08cabc84ce677b16731f56957ba517d6
-  data.tar.gz: 486bdb3b54a34ee2363cf482e113a928840bda36ca94a9407e2b269748fa534a24d75e407df839d5b86561dedb50c9a1648558b507ae49acf6152b77866cfb8a
+  metadata.gz: 7eebfe8e66e6098b8f78a2c5e564b51500bbbb5391f7fb341558495b0a8a8e3124f11be94a0d25ea7a3648a56c7d945d8f39815bdc30d28b8aff5374a7b768f2
+  data.tar.gz: d3f7249277cc5268cd7b6182fd4a21f98cf9e8150c6544a10af4476b879bded4675a9851b8b7f9faf541cc1863de573e6c4d6ef4969e8382338fd78620b3a08b

data/README.md

@@ -367,3 +367,59 @@ the `coder` keyword argument.
 - And you've opted into 7.1 defaults (namely, `config.active_record.default_column_serializer = nil`)
 
 ...you can safely disable this cop, since failing to pass a deserializer will raise an exception.
+
+### Betterment/SpecDescribeMethodName
+
+This cop requires each spec to name the class under test and the method under test using `describe` blocks. The outermost `describe` blocks should be the class constant, and second level `describe` blocks should be of the form `"#instance_method"` or `".class_method"`. This structure works with [mutant](https://github.com/mbj/mutant) and creates consistently shaped specs
+
+```ruby
+# BAD - the outer describe is a string
+RSpec.describe "Invoice" do
+  # ...
+end
+
+# BAD - no method label
+RSpec.describe Invoice do
+  it "sums the line items" do
+    # ...
+  end
+end
+
+# BAD - the context block breaks the "Invoice#total" label
+RSpec.describe Invoice do
+  context "when the account is delinquent" do
+    describe "#total" do
+      # ...
+    end
+  end
+end
+
+# BAD - a second class describe breaks the "Invoice::Item#total" label.
+# Give Invoice::Item its own spec file.
+RSpec.describe Invoice do
+  describe Invoice::Item do
+    describe "#total" do
+      # ...
+    end
+  end
+end
+
+# GOOD - shared setup above the method labels
+RSpec.describe Invoice do
+  let(:account) { create(:account, :delinquent) }
+
+  describe "#total" do
+    it "adds the late fee" do
+      # ...
+    end
+  end
+
+  describe ".open" do
+    it "excludes paid invoices" do
+      # ...
+    end
+  end
+end
+```
+
+This cop is disabled by default, because it reports many offenses in applications with older specs. To use it, enable it in your `.rubocop.yml`. By default it examines all files in `spec/`, except for the `features`, `requests`, `routing`, `system`, and `views` directories, where integration style tests that don't test one class and method are common. Examples in shared example groups are also ignored.

data/config/default.yml

@@ -114,6 +114,19 @@ Betterment/SitePrismLoaded:
     - spec/features/**/*_spec.rb
     - spec/system/**/*_spec.rb
 
+Betterment/SpecDescribeMethodName:
+  Description: Requires spec `describe` blocks to be labeled with a class constant and method names.
+  Enabled: false
+  StyleGuide: '#bettermentspecdescribemethodname'
+  Include:
+    - spec/**/*_spec.rb
+  Exclude:
+    - spec/features/**/*_spec.rb
+    - spec/requests/**/*_spec.rb
+    - spec/routing/**/*_spec.rb
+    - spec/system/**/*_spec.rb
+    - spec/views/**/*_spec.rb
+
 Betterment/UnsafeJob:
   Enabled: false
   StyleGuide: '#bettermentunsafejob'

data/lib/betterlint/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Betterlint
-  VERSION = '1.28.0'
+  VERSION = '1.29.0'
 end

data/lib/rubocop/cop/betterment/spec_describe_method_name.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Betterment
+      class SpecDescribeMethodName < Base
+        MSG_CLASS_LABEL = 'Label the outer `describe` with the class constant, not a string.'
+        MSG_METHOD_LABEL = 'Put examples inside a `describe` labeled with a method name, such as `"#instance_method"` or `".class_method"`.'
+        MSG_DIRECTLY_INSIDE = 'Put the method `describe` directly inside the class `describe`, and share setup with `let` or `before`.'
+        MSG_ONE_CLASS = 'Describe one class in each spec file, and put the method `describe` directly inside the outer `describe`.'
+
+        METHOD_LABEL = /\A[#.]\S/
+
+        DESCRIBE_METHODS = %i(describe fdescribe xdescribe).freeze
+        EXAMPLE_GROUP_METHODS = %i(describe fdescribe xdescribe context fcontext xcontext).freeze
+        SHARED_GROUP_METHODS = %i(shared_examples shared_examples_for shared_context).freeze
+        EXAMPLE_METHODS = %i(
+          it its specify example scenario
+          fit fspecify fexample fscenario
+          xit xspecify xexample xscenario
+        ).freeze
+
+        RESTRICT_ON_SEND = (DESCRIBE_METHODS + EXAMPLE_METHODS).freeze
+
+        def on_send(node)
+          if DESCRIBE_METHODS.include?(node.method_name)
+            check_describe(node) if rspec_receiver?(node)
+          elsif node.receiver.nil?
+            check_example(node)
+          end
+        end
+        alias on_csend on_send
+
+        private
+
+        def check_describe(node)
+          groups = enclosing_groups(node)
+          return if groups.any? { |group| shared_group?(group) }
+
+          check_class_label(node) if groups.empty?
+          check_method_describe_placement(node, groups)
+        end
+
+        def check_example(node)
+          groups = enclosing_groups(node)
+          return if groups.any? { |group| shared_group?(group) || method_describe?(group) }
+          return unless groups.any? { |group| class_describe?(group) }
+
+          add_offense(node, message: MSG_METHOD_LABEL)
+        end
+
+        def check_class_label(send_node)
+          label = send_node.first_argument
+          return if label.nil? || label.const_type?
+
+          add_offense(label, message: MSG_CLASS_LABEL)
+        end
+
+        def check_method_describe_placement(send_node, groups)
+          return unless method_describe?(send_node)
+
+          parent = groups.first
+          return if parent.nil? || (groups.one? && class_describe?(parent))
+          return unless groups.any? { |group| class_describe?(group) }
+
+          add_offense(send_node, message: class_describe?(parent) ? MSG_ONE_CLASS : MSG_DIRECTLY_INSIDE)
+        end
+
+        def enclosing_groups(node)
+          node.each_ancestor(:block, :numblock).filter_map do |ancestor|
+            send_node = ancestor.send_node
+            next if send_node.equal?(node)
+
+            send_node if example_group?(send_node) || shared_group?(send_node)
+          end
+        end
+
+        def example_group?(send_node)
+          EXAMPLE_GROUP_METHODS.include?(send_node.method_name) && rspec_receiver?(send_node)
+        end
+
+        def shared_group?(send_node)
+          SHARED_GROUP_METHODS.include?(send_node.method_name) && rspec_receiver?(send_node)
+        end
+
+        def describe?(send_node)
+          DESCRIBE_METHODS.include?(send_node.method_name) && rspec_receiver?(send_node)
+        end
+
+        def class_describe?(send_node)
+          return false unless describe?(send_node)
+
+          send_node.first_argument&.const_type? || false
+        end
+
+        def method_describe?(send_node)
+          return false unless describe?(send_node)
+
+          label = send_node.first_argument
+          return false unless label&.str_type?
+
+          METHOD_LABEL.match?(label.value)
+        end
+
+        def rspec_receiver?(send_node)
+          receiver = send_node.receiver
+          return true if receiver.nil?
+
+          receiver.const_type? && receiver.short_name == :RSpec && (receiver.namespace.nil? || receiver.namespace.cbase_type?)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/betterment.rb

@@ -21,6 +21,7 @@ require 'rubocop/cop/betterment/render_status'
 require 'rubocop/cop/betterment/server_error_assertion'
 require 'rubocop/cop/betterment/simple_delegator'
 require 'rubocop/cop/betterment/site_prism_loaded'
+require 'rubocop/cop/betterment/spec_describe_method_name'
 require 'rubocop/cop/betterment/spec_helper_required_outside_spec_dir'
 require 'rubocop/cop/betterment/timeout'
 require 'rubocop/cop/betterment/unsafe_job'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: betterlint
 version: !ruby/object:Gem::Version
-  version: 1.28.0
+  version: 1.29.0
 platform: ruby
 authors:
 - Development
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lint_roller
@@ -189,6 +188,7 @@ files:
 - lib/rubocop/cop/betterment/server_error_assertion.rb
 - lib/rubocop/cop/betterment/simple_delegator.rb
 - lib/rubocop/cop/betterment/site_prism_loaded.rb
+- lib/rubocop/cop/betterment/spec_describe_method_name.rb
 - lib/rubocop/cop/betterment/spec_helper_required_outside_spec_dir.rb
 - lib/rubocop/cop/betterment/timeout.rb
 - lib/rubocop/cop/betterment/unsafe_job.rb
@@ -203,13 +203,12 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/Betterment/betterlint
-  source_code_uri: https://github.com/Betterment/betterlint/tree/v1.28.0
-  changelog_uri: https://github.com/Betterment/betterlint/blob/v1.28.0/CHANGELOG.md
+  source_code_uri: https://github.com/Betterment/betterlint/tree/v1.29.0
+  changelog_uri: https://github.com/Betterment/betterlint/blob/v1.29.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/Betterment/betterlint/issues
-  documentation_uri: https://www.rubydoc.info/gems/betterlint/1.28.0
+  documentation_uri: https://www.rubydoc.info/gems/betterlint/1.29.0
   rubygems_mfa_required: 'true'
   default_lint_roller_plugin: Betterlint::Plugin
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -224,8 +223,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Betterment rubocop configuration
 test_files: []