rubocop-rspec-guide 0.2.1 → 0.4.0

data/lib/rubocop/cop/factory_bot_guide/dynamic_attributes_for_time_and_random.rb

@@ -1,120 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "dynamic_attribute_evaluation"
+
 module RuboCop
   module Cop
     module FactoryBotGuide
-      # Checks that time-related and random methods in FactoryBot definitions
-      # are wrapped in blocks for dynamic evaluation.
+      # @deprecated Use `DynamicAttributeEvaluation` instead.
+      #   This cop has been renamed to better reflect its broader scope.
       #
-      # @example
-      #   # bad
-      #   factory :user do
-      #     created_at Time.now
-      #     token SecureRandom.hex
-      #     expires_at 1.day.from_now
-      #   end
+      # Checks that method calls in FactoryBot attribute definitions
+      # are wrapped in blocks for dynamic evaluation.
       #
-      #   # good
-      #   factory :user do
-      #     created_at { Time.now }
-      #     token { SecureRandom.hex }
-      #     expires_at { 1.day.from_now }
-      #     name "John"  # Static values are OK
-      #   end
+      # This cop is deprecated and will be removed in a future release.
+      # Please use `FactoryBotGuide/DynamicAttributeEvaluation` instead.
       #
-      class DynamicAttributesForTimeAndRandom < Base
+      class DynamicAttributesForTimeAndRandom < DynamicAttributeEvaluation
+        # Override to provide deprecation warning with the old cop name
         MSG = "Use block syntax for attribute `%<attribute>s` because `%<method>s` " \
               "is evaluated once at factory definition time. " \
               "Wrap in block: `%<attribute>s { %<value>s }`"
-
-        TIME_CLASSES = %w[Time Date DateTime].freeze
-        RANDOM_CLASSES = %w[SecureRandom].freeze
-
-        # @!method factory_block?(node)
-        def_node_matcher :factory_block?, <<~PATTERN
-          (block
-            (send {nil? (const {nil? cbase} :FactoryBot)} :factory ...)
-            ...)
-        PATTERN
-
-        # @!method attribute_assignment?(node)
-        def_node_matcher :attribute_assignment?, <<~PATTERN
-          (send nil? $_ $_value)
-        PATTERN
-
-        def on_block(node)
-          return unless factory_block?(node)
-
-          # Check all attribute assignments within the factory
-          node.each_descendant(:send) do |send_node|
-            check_attribute(send_node)
-          end
-        end
-
-        private
-
-        def check_attribute(node)
-          attribute_assignment?(node) do |attribute_name, value|
-            # Skip if value is already a block
-            next if value.block_type?
-
-            # Check if the value is a dangerous method call
-            next unless dangerous_method_call?(value)
-
-            add_offense(
-              node,
-              message: format(
-                MSG,
-                attribute: attribute_name,
-                method: method_description(value),
-                value: value.source
-              )
-            )
-          end
-        end
-
-        def dangerous_method_call?(node)
-          # Only method calls are potentially dangerous
-          return false unless node.send_type?
-
-          # Time.now, Date.today, DateTime.now, etc.
-          return true if time_method?(node)
-
-          # SecureRandom.hex, SecureRandom.uuid, etc.
-          return true if random_method?(node)
-
-          # Any other method calls (e.g., 1.day.ago, Array.new, etc.)
-          # are evaluated at factory load time
-          true
-        end
-
-        def time_method?(node)
-          return false unless node.receiver
-
-          receiver_name = if node.receiver.const_type?
-            node.receiver.const_name
-          end
-
-          TIME_CLASSES.include?(receiver_name)
-        end
-
-        def random_method?(node)
-          return false unless node.receiver
-
-          receiver_name = if node.receiver.const_type?
-            node.receiver.const_name
-          end
-
-          RANDOM_CLASSES.include?(receiver_name)
-        end
-
-        def method_description(node)
-          if node.receiver
-            "#{node.receiver.source}.#{node.method_name}"
-          else
-            node.method_name.to_s
-          end
-        end
       end
     end
   end

data/lib/rubocop/cop/rspec_guide/characteristics_and_contexts.rb

@@ -1,90 +1,25 @@
 # frozen_string_literal: true
 
+require_relative "minimum_behavioral_coverage"
+
 module RuboCop
   module Cop
     module RSpecGuide
-      # Checks that describe blocks have at least 2 context blocks
-      # to separate happy path from corner cases.
-      #
-      # @example
-      #   # bad
-      #   describe '#process' do
-      #     it 'works' do
-      #       expect(subject.process).to be_success
-      #     end
-      #   end
-      #
-      #   # bad
-      #   describe '#process' do
-      #     context 'when data is valid' do
-      #       it 'processes' do
-      #         expect(subject.process).to be_success
-      #       end
-      #     end
-      #   end
+      # @deprecated Use `MinimumBehavioralCoverage` instead.
+      #   This cop has been renamed to better reflect its purpose.
       #
-      #   # good
-      #   describe '#process' do
-      #     context 'when data is valid' do
-      #       it 'processes successfully' do
-      #         expect(subject.process).to be_success
-      #       end
-      #     end
+      # Checks that describe blocks test at least 2 behavioral variations.
       #
-      #     context 'when data is invalid' do
-      #       it 'returns error' do
-      #         expect(subject.process).to be_error
-      #       end
-      #     end
-      #   end
+      # This cop is deprecated and will be removed in a future release.
+      # Please use `RSpecGuide/MinimumBehavioralCoverage` instead.
       #
-      class CharacteristicsAndContexts < Base
-        MSG = "Describe block should have at least 2 contexts " \
-              "(happy path + edge cases). " \
+      class CharacteristicsAndContexts < MinimumBehavioralCoverage
+        # Override to provide deprecation warning with the old cop name
+        MSG = "Describe block should test at least 2 behavioral variations: " \
+              "either use 2+ sibling contexts (happy path + edge cases), " \
+              "or combine it-blocks for default behavior with context-blocks for edge cases. " \
               "Use `# rubocop:disable RSpecGuide/CharacteristicsAndContexts` " \
-              "if truly no edge cases exist."
-
-        # @!method describe_block?(node)
-        def_node_matcher :describe_block?, <<~PATTERN
-          (block
-            (send nil? :describe ...)
-            ...)
-        PATTERN
-
-        # @!method context_block?(node)
-        def_node_matcher :context_block?, <<~PATTERN
-          (block (send nil? :context ...) ...)
-        PATTERN
-
-        def on_block(node)
-          return unless describe_block?(node)
-
-          # Collect direct child context blocks
-          contexts = collect_sibling_contexts(node)
-
-          # Add offense if less than 2 contexts
-          add_offense(node) if contexts.size < 2
-        end
-
-        private
-
-        def collect_sibling_contexts(node)
-          # The body of a describe/context block may be:
-          # 1. A single block node (if only one child)
-          # 2. A begin node containing multiple children
-          body = node.body
-          return [] unless body
-
-          if body.begin_type?
-            # Multiple children wrapped in begin node
-            body.children.select { |child| child.block_type? && context_block?(child) }
-          elsif body.block_type? && context_block?(body)
-            # Single context child
-            [body]
-          else
-            []
-          end
-        end
+              "for simple cases (e.g., getters) with no edge cases."
       end
     end
   end

data/lib/rubocop/cop/rspec_guide/context_setup.rb

@@ -6,58 +6,108 @@ module RuboCop
       # Checks that context blocks have setup (let/before) to distinguish
       # them from the parent context.
       #
+      # Contexts exist to test different scenarios or states. Without explicit setup,
+      # the context doesn't actually change anything from its parent, making the
+      # context boundary meaningless and confusing.
+      #
+      # Valid setup methods: let, let!, let_it_be, let_it_be!, before
+      #
       # Note: subject should be defined at describe level, not in contexts,
       # as it describes the object under test, not context-specific state.
       # Use RSpec/LeadingSubject cop to ensure subject is defined first.
       #
-      # @example
-      #   # bad
+      # @safety
+      #   This cop is safe to run automatically. It only checks for presence
+      #   of setup, not for semantic correctness.
+      #
+      # @example Bad - no setup
+      #   # bad - context has no setup, so what's different?
       #   context 'when user is premium' do
-      #     it 'has access' do
-      #       expect(user).to have_access
-      #     end
+      #     it { expect(user).to have_access }
+      #   end
+      #
+      #   # bad - subject in context (should be in describe)
+      #   context 'with custom config' do
+      #     subject { Calculator.new(config) }  # Wrong place!
+      #     it { is_expected.to be_valid }
       #   end
       #
-      #   # good
+      # @example Good - using let
+      #   # good - let defines context-specific state
       #   context 'when user is premium' do
       #     let(:user) { create(:user, :premium) }
+      #     it { expect(user).to have_access }
+      #   end
       #
-      #     it 'has access' do
-      #       expect(user).to have_access
-      #     end
+      #   # good - let! for immediate evaluation
+      #   context 'with existing records' do
+      #     let!(:records) { create_list(:record, 3) }
+      #     it { expect(Record.count).to eq(3) }
       #   end
       #
-      #   # good
-      #   context 'when user is premium' do
+      # @example Good - using let_it_be (test-prof/rspec-rails)
+      #   # good - let_it_be for performance (created once per context)
+      #   context 'with many users' do
+      #     let_it_be(:users) { create_list(:user, 100) }
+      #     it { expect(users.size).to eq(100) }
+      #   end
+      #
+      #   # good - let_it_be! for immediate evaluation
+      #   context 'with frozen time' do
+      #     let_it_be!(:timestamp) { Time.current }
+      #     it { expect(timestamp).to be_frozen }
+      #   end
+      #
+      # @example Good - using before
+      #   # good - before modifies existing state
+      #   context 'when user is upgraded' do
       #     before { user.upgrade_to_premium! }
+      #     it { expect(user).to be_premium }
+      #   end
+      #
+      #   # good - before with multiple setup steps
+      #   context 'with configured environment' do
+      #     before do
+      #       allow(ENV).to receive(:[]).with('API_KEY').and_return('test-key')
+      #       allow(ENV).to receive(:[]).with('API_URL').and_return('http://test')
+      #     end
+      #     it { expect(api_client).to be_configured }
+      #   end
+      #
+      # @example Subject placement
+      #   # bad - subject in context
+      #   describe Calculator do
+      #     context 'with custom config' do
+      #       subject { Calculator.new(custom_config) }  # Wrong!
+      #       it { is_expected.to be_valid }
+      #     end
+      #   end
+      #
+      #   # good - subject in describe, config in context
+      #   describe Calculator do
+      #     subject { Calculator.new(config) }
       #
-      #     it 'has access' do
-      #       expect(user).to have_access
+      #     context 'with custom config' do
+      #       let(:config) { CustomConfig.new }  # Right!
+      #       it { is_expected.to be_valid }
       #     end
       #   end
       #
-      class ContextSetup < Base
+      class ContextSetup < RuboCop::Cop::RSpec::Base
         MSG = "Context should have setup (let/let!/let_it_be/let_it_be!/before) to distinguish it from parent context"
 
-        # @!method context_block?(node)
-        def_node_matcher :context_block?, <<~PATTERN
-          (block
-            (send nil? :context ...)
-            ...)
-        PATTERN
-
-        # @!method let_declaration?(node)
-        def_node_matcher :let_declaration?, <<~PATTERN
-          (block (send nil? {:let :let! :let_it_be :let_it_be!} ...) ...)
-        PATTERN
+        # Using rubocop-rspec API: let?(node) and hook?(node) from Base
+        # Custom matcher for context-only:
 
-        # @!method before_hook?(node)
-        def_node_matcher :before_hook?, <<~PATTERN
-          (block (send nil? :before ...) ...)
+        # @!method context_only?(node)
+        def_node_matcher :context_only?, <<~PATTERN
+          (block (send nil? :context ...) ...)
         PATTERN
 
         def on_block(node)
-          return unless context_block?(node)
+          # Fast pre-check: only process context blocks
+          return unless node.method?(:context)
+          return unless context_only?(node)
 
           # Check if context has at least one setup node (let or before)
           # Note: subject is NOT counted as context setup because it describes
@@ -77,7 +127,8 @@ module RuboCop
               (block_node.parent.begin_type? && block_node.parent.parent == context_node)
             next unless is_immediate_child
 
-            return true if let_declaration?(block_node) || before_hook?(block_node)
+            # Use rubocop-rspec API matchers
+            return true if let?(block_node) || (hook?(block_node) && block_node.method?(:before))
           end
 
           false

data/lib/rubocop/cop/rspec_guide/duplicate_before_hooks.rb

@@ -3,11 +3,19 @@
 module RuboCop
   module Cop
     module RSpecGuide
-      # Detects duplicate before hooks with identical code across all sibling contexts.
-      # These should be extracted to the parent context.
+      # Detects duplicate before hooks with identical code across sibling contexts.
       #
-      # @example
-      #   # bad
+      # When the same before hook appears in multiple sibling contexts,
+      # it indicates one of two problems:
+      # 1. ERROR: Duplicate in ALL contexts → must extract to parent
+      # 2. WARNING: Duplicate in SOME contexts → suggests poor test hierarchy
+      #
+      # @safety
+      #   This cop is safe to run automatically. It compares hook bodies for
+      #   exact matches, not semantic equivalence.
+      #
+      # @example ERROR - duplicate in ALL contexts
+      #   # bad - before hook duplicated in all 2 contexts
       #   describe 'Controller' do
       #     context 'as admin' do
       #       before { sign_in(user) }
@@ -15,14 +23,14 @@ module RuboCop
       #     end
       #
       #     context 'as guest' do
-      #       before { sign_in(user) }  # Duplicate!
+      #       before { sign_in(user) }  # ERROR: in all contexts!
       #       it { expect(response).to be_forbidden }
       #     end
       #   end
       #
-      #   # good
+      #   # good - extracted to parent
       #   describe 'Controller' do
-      #     before { sign_in(user) }  # Extracted to parent
+      #     before { sign_in(user) }  # Moved to parent
       #
       #     context 'as admin' do
       #       it { expect(response).to be_successful }
@@ -33,33 +41,92 @@ module RuboCop
       #     end
       #   end
       #
-      class DuplicateBeforeHooks < Base
+      # @example WARNING - duplicate in SOME contexts
+      #   # bad - before hook duplicated in 2/3 contexts (code smell)
+      #   describe 'API' do
+      #     context 'scenario A' do
+      #       before { setup_api }
+      #       it { expect(response).to be_ok }
+      #     end
+      #
+      #     context 'scenario B' do
+      #       before { setup_api }  # WARNING: duplicated in 2/3
+      #       it { expect(response).to be_ok }
+      #     end
+      #
+      #     context 'scenario C' do
+      #       before { setup_different_api }  # Different setup
+      #       it { expect(response).to be_ok }
+      #     end
+      #   end
+      #
+      #   # good - refactor hierarchy
+      #   describe 'API' do
+      #     context 'with standard setup' do
+      #       before { setup_api }
+      #
+      #       context 'scenario A' do
+      #         it { expect(response).to be_ok }
+      #       end
+      #
+      #       context 'scenario B' do
+      #         it { expect(response).to be_ok }
+      #       end
+      #     end
+      #
+      #     context 'with different setup' do
+      #       before { setup_different_api }
+      #
+      #       context 'scenario C' do
+      #         it { expect(response).to be_ok }
+      #       end
+      #     end
+      #   end
+      #
+      # @example Configuration
+      #   # To disable warnings for partial duplicates:
+      #   RSpecGuide/DuplicateBeforeHooks:
+      #     WarnOnPartialDuplicates: false  # Only report full duplicates
+      #
+      # @example Edge case - different hooks
+      #   # good - different before hooks (no duplicate)
+      #   describe 'Service' do
+      #     context 'with user A' do
+      #       before { sign_in(user_a) }
+      #       it { expect(service.call).to be_success }
+      #     end
+      #
+      #     context 'with user B' do
+      #       before { sign_in(user_b) }  # Different, OK
+      #       it { expect(service.call).to be_success }
+      #     end
+      #   end
+      #
+      class DuplicateBeforeHooks < RuboCop::Cop::RSpec::Base
         MSG_ERROR = "Duplicate `before` hook in ALL sibling contexts. " \
                     "Extract to parent context."
         MSG_WARNING = "Before hook duplicated in %<count>d/%<total>d sibling contexts. " \
                       "Consider refactoring test hierarchy - this suggests poor organization."
 
-        # @!method context_block?(node)
-        def_node_matcher :context_block?, <<~PATTERN
+        # Using rubocop-rspec API: example_group?(node) and hook?(node) from Base
+        # Custom matchers:
+
+        # @!method context_only?(node)
+        def_node_matcher :context_only?, <<~PATTERN
           (block (send nil? :context ...) ...)
         PATTERN
 
-        # @!method before_hook?(node)
-        def_node_matcher :before_hook?, <<~PATTERN
+        # @!method before_hook_with_body?(node)
+        def_node_matcher :before_hook_with_body?, <<~PATTERN
           (block
             (send nil? :before ...)
             (args)
             $_body)
         PATTERN
 
-        # @!method example_group?(node)
-        def_node_matcher :example_group?, <<~PATTERN
-          (block
-            (send nil? {:describe :context} ...)
-            ...)
-        PATTERN
-
         def on_block(node)
+          # Fast pre-check: only process describe/context blocks
+          return unless node.method?(:describe) || node.method?(:context)
           return unless example_group?(node)
 
           # Collect all sibling contexts
@@ -86,8 +153,8 @@ module RuboCop
 
           if body.begin_type?
             # Multiple children wrapped in begin node
-            body.children.select { |child| child.block_type? && context_block?(child) }
-          elsif body.block_type? && context_block?(body)
+            body.children.select { |child| child.block_type? && context_only?(child) }
+          elsif body.block_type? && context_only?(body)
             # Single context child
             [body]
           else
@@ -106,7 +173,7 @@ module RuboCop
               (block_node.parent.begin_type? && block_node.parent.parent == context_node)
             next unless is_immediate_child
 
-            before_hook?(block_node) do |body|
+            before_hook_with_body?(block_node) do |body|
               befores << {body_source: normalize_source(body.source), node: block_node}
             end
           end