rubocop-rspec-guide 0.2.2 → 0.4.0

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

@@ -3,11 +3,19 @@
 module RuboCop
   module Cop
     module RSpecGuide
-      # Detects duplicate let declarations with identical values across all sibling contexts.
-      # These should be extracted to the parent context.
+      # Detects duplicate let declarations with identical values across sibling contexts.
       #
-      # @example
-      #   # bad
+      # When the same let with the same value 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 only detects duplicates,
+      #   not semantic issues.
+      #
+      # @example ERROR - duplicate in ALL contexts
+      #   # bad - let(:currency) duplicated in all 2 contexts
       #   describe 'Calculator' do
       #     context 'with addition' do
       #       let(:currency) { :usd }
@@ -15,14 +23,14 @@ module RuboCop
       #     end
       #
       #     context 'with subtraction' do
-      #       let(:currency) { :usd }  # Duplicate!
+      #       let(:currency) { :usd }  # ERROR: in all contexts!
       #       it { expect(result).to eq(5) }
       #     end
       #   end
       #
-      #   # good
+      #   # good - extracted to parent
       #   describe 'Calculator' do
-      #     let(:currency) { :usd }  # Extracted to parent
+      #     let(:currency) { :usd }  # Moved to parent
       #
       #     context 'with addition' do
       #       it { expect(result).to eq(10) }
@@ -33,33 +41,92 @@ module RuboCop
       #     end
       #   end
       #
-      class DuplicateLetValues < Base
+      # @example WARNING - duplicate in SOME contexts
+      #   # bad - let(:mode) duplicated in 2/3 contexts (code smell)
+      #   describe 'Processor' do
+      #     context 'scenario A' do
+      #       let(:mode) { :standard }
+      #       it { expect(result).to eq('A') }
+      #     end
+      #
+      #     context 'scenario B' do
+      #       let(:mode) { :standard }  # WARNING: duplicated in 2/3
+      #       it { expect(result).to eq('B') }
+      #     end
+      #
+      #     context 'scenario C' do
+      #       let(:mode) { :advanced }  # Different value
+      #       it { expect(result).to eq('C') }
+      #     end
+      #   end
+      #
+      #   # good - refactor hierarchy
+      #   describe 'Processor' do
+      #     context 'with standard mode' do
+      #       let(:mode) { :standard }
+      #
+      #       context 'scenario A' do
+      #         it { expect(result).to eq('A') }
+      #       end
+      #
+      #       context 'scenario B' do
+      #         it { expect(result).to eq('B') }
+      #       end
+      #     end
+      #
+      #     context 'with advanced mode' do
+      #       let(:mode) { :advanced }
+      #
+      #       context 'scenario C' do
+      #         it { expect(result).to eq('C') }
+      #       end
+      #     end
+      #   end
+      #
+      # @example Configuration
+      #   # To disable warnings for partial duplicates:
+      #   RSpecGuide/DuplicateLetValues:
+      #     WarnOnPartialDuplicates: false  # Only report full duplicates
+      #
+      # @example Edge case - different values
+      #   # good - same let name but different values (no duplicate)
+      #   describe 'Converter' do
+      #     context 'to USD' do
+      #       let(:currency) { :usd }
+      #       it { expect(convert).to eq(100) }
+      #     end
+      #
+      #     context 'to EUR' do
+      #       let(:currency) { :eur }  # Different value, OK
+      #       it { expect(convert).to eq(85) }
+      #     end
+      #   end
+      #
+      class DuplicateLetValues < RuboCop::Cop::RSpec::Base
         MSG_ERROR = "Duplicate `let(:%<name>s)` with same value `%<value>s` " \
                     "in ALL sibling contexts. Extract to parent context."
         MSG_WARNING = "Let `:%<name>s` with value `%<value>s` duplicated in %<count>d/%<total>d 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) from Base
+        # Custom matchers:
+
+        # @!method context_only?(node)
+        def_node_matcher :context_only?, <<~PATTERN
           (block (send nil? :context ...) ...)
         PATTERN
 
-        # @!method let_declaration?(node)
-        def_node_matcher :let_declaration?, <<~PATTERN
+        # @!method let_with_name_and_value?(node)
+        def_node_matcher :let_with_name_and_value?, <<~PATTERN
           (block
             (send nil? {:let :let!} (sym $_name))
             (args)
             $_value)
         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
@@ -105,7 +172,7 @@ module RuboCop
               (block_node.parent.begin_type? && block_node.parent.parent == context_node)
             next unless is_immediate_child
 
-            let_declaration?(block_node) do |name, value|
+            let_with_name_and_value?(block_node) do |name, value|
               # Only check simple values that can be compared by source
               if simple_value?(value)
                 lets[name] = {value: value.source, node: block_node}

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

@@ -4,55 +4,88 @@ module RuboCop
   module Cop
     module RSpecGuide
       # Checks that corner cases are not the first context in a describe block.
-      # Happy path should come first for better readability.
+      #
+      # Placing happy path scenarios first improves test readability by establishing
+      # the expected behavior before diving into edge cases. This makes it easier for
+      # readers to understand the primary purpose of the code being tested.
       #
       # The cop allows corner case contexts to appear first if there are
       # example blocks (it/specify) before the first context, as those examples
       # represent the happy path.
       #
-      # @example
-      #   # bad
+      # @safety
+      #   This cop is safe to run automatically. It detects corner case indicators
+      #   like 'but', 'however', 'not', 'without', 'except', etc.
+      #
+      # @example Bad - corner case first
+      #   # bad - starts with negative case
       #   describe '#process' do
       #     context 'but user is blocked' do
-      #       # ...
+      #       it { expect { process }.to raise_error }
       #     end
+      #
       #     context 'when user is valid' do
-      #       # ...
+      #       it { expect(process).to be_success }
       #     end
       #   end
       #
-      #   # bad
+      #   # bad - starts with NOT condition
       #   describe '#activate' do
       #     context 'when user does NOT exist' do
-      #       # ...
+      #       it { expect { activate }.to raise_error(NotFound) }
       #     end
+      #
       #     context 'when user exists' do
-      #       # ...
+      #       it { expect(activate).to be_truthy }
       #     end
       #   end
       #
-      #   # good
+      # @example Good - happy path first
+      #   # good - happy path comes first
       #   describe '#subscribe' do
       #     context 'with valid card' do
-      #       # ...
+      #       it { expect(subscribe).to be_success }
       #     end
+      #
       #     context 'but payment fails' do
-      #       # ...
+      #       it { expect(subscribe).to be_failure }
+      #     end
+      #   end
+      #
+      #   # good - positive case before negative
+      #   describe '#send_notification' do
+      #     context 'when user has email' do
+      #       it { expect(send_notification).to be_sent }
+      #     end
+      #
+      #     context 'without email' do
+      #       it { expect(send_notification).to be_skipped }
       #     end
       #   end
       #
+      # @example Edge case - it-blocks represent happy path
       #   # good - examples before first context represent happy path
       #   describe '#add_child' do
       #     it 'adds child to children collection' do
-      #       # ...
+      #       expect { add_child(child) }.to change(parent.children, :count).by(1)
       #     end
       #
       #     context 'but child is already in collection' do
-      #       # ...
+      #       it { expect { add_child(child) }.not_to change(parent.children, :count) }
       #     end
       #   end
       #
-      class HappyPathFirst < Base
+      #   # good - multiple it-blocks as happy path
+      #   describe '#calculate' do
+      #     it { expect(calculate).to be_a(Numeric) }
+      #     it { expect(calculate).to be_positive }
+      #
+      #     context 'with invalid input' do
+      #       it { expect { calculate }.to raise_error }
+      #     end
+      #   end
+      #
+      class HappyPathFirst < RuboCop::Cop::RSpec::Base
         MSG = "Place happy path contexts before corner cases. " \
               "First context appears to be a corner case: %<description>s"
 
@@ -62,6 +95,9 @@ module RuboCop
           fails missing absent unavailable
         ].freeze
 
+        # Using rubocop-rspec API: example_group?(node) from Base
+        # Custom matcher for context with description:
+
         # @!method context_with_description?(node)
         def_node_matcher :context_with_description?, <<~PATTERN
           (block
@@ -69,14 +105,9 @@ module RuboCop
             ...)
         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)
 
           contexts = collect_direct_child_contexts(node)

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

@@ -4,10 +4,21 @@ module RuboCop
   module Cop
     module RSpecGuide
       # Detects examples that repeat in all leaf contexts.
-      # These invariants should be extracted to shared_examples.
       #
-      # @example
-      #   # bad
+      # When the same test appears in all leaf contexts, it indicates an invariant -
+      # a property that holds true regardless of the context. These invariants represent
+      # interface contracts and should be extracted to shared_examples for reusability
+      # and clarity.
+      #
+      # The cop only reports when examples appear in MinLeafContexts or more contexts
+      # (default: 3) to avoid false positives.
+      #
+      # @safety
+      #   This cop is safe to run automatically. It compares example descriptions
+      #   for exact string matches.
+      #
+      # @example Bad - repeated invariant
+      #   # bad - 'responds to valid?' repeated in all 3 contexts
       #   describe 'Validator' do
       #     context 'with valid data' do
       #       it 'responds to valid?' do
@@ -28,7 +39,8 @@ module RuboCop
       #     end
       #   end
       #
-      #   # good
+      # @example Good - extracted to shared_examples
+      #   # good - invariant extracted to shared_examples
       #   shared_examples 'a validator' do
       #     it 'responds to valid?' do
       #       expect(subject).to respond_to(:valid?)
@@ -38,44 +50,72 @@ module RuboCop
       #   describe 'Validator' do
       #     context 'with valid data' do
       #       it_behaves_like 'a validator'
+      #       it { expect(subject.valid?).to be true }
       #     end
       #
       #     context 'with invalid data' do
       #       it_behaves_like 'a validator'
+      #       it { expect(subject.valid?).to be false }
       #     end
       #
       #     context 'with empty data' do
       #       it_behaves_like 'a validator'
+      #       it { expect(subject.valid?).to be false }
       #     end
       #   end
       #
-      class InvariantExamples < Base
+      # @example Configuration
+      #   # Adjust minimum contexts threshold:
+      #   RSpecGuide/InvariantExamples:
+      #     MinLeafContexts: 3  # Default: report if in 3+ contexts
+      #
+      #   # For larger test suites, use higher threshold:
+      #   RSpecGuide/InvariantExamples:
+      #     MinLeafContexts: 5  # Only report if in 5+ contexts
+      #
+      # @example Edge case - not in all contexts
+      #   # good - test only in 2 out of 3 contexts (not invariant)
+      #   describe 'Calculator' do
+      #     context 'with addition' do
+      #       it 'returns numeric' { expect(result).to be_a(Numeric) }
+      #     end
+      #
+      #     context 'with subtraction' do
+      #       it 'returns numeric' { expect(result).to be_a(Numeric) }
+      #     end
+      #
+      #     context 'with division by zero' do
+      #       it 'raises error' { expect { result }.to raise_error }
+      #       # 'returns numeric' not here - not an invariant
+      #     end
+      #   end
+      #
+      class InvariantExamples < RuboCop::Cop::RSpec::Base
         MSG = "Example `%<description>s` repeats in all %<count>d leaf contexts. " \
               "Consider extracting to shared_examples as an interface invariant."
 
-        # @!method example_with_description?(node)
-        def_node_matcher :example_with_description?, <<~PATTERN
-          (block
-            (send nil? {:it :specify :example} (str $_description))
-            ...)
-        PATTERN
+        # Using rubocop-rspec API: example_group?(node) from Base for top-level check
+        # Custom matchers for performance-critical internal checks:
 
-        # @!method context_or_describe?(node)
-        def_node_matcher :context_or_describe?, <<~PATTERN
+        # Fast local matcher for nested context/describe checks (performance-critical)
+        # @!method context_or_describe_block?(node)
+        def_node_matcher :context_or_describe_block?, <<~PATTERN
           (block
             (send nil? {:describe :context} ...)
             ...)
         PATTERN
 
-        # @!method top_level_describe?(node)
-        def_node_matcher :top_level_describe?, <<~PATTERN
+        # @!method example_with_description?(node)
+        def_node_matcher :example_with_description?, <<~PATTERN
           (block
-            (send nil? :describe ...)
+            (send nil? {:it :specify :example} (str $_description))
             ...)
         PATTERN
 
         def on_block(node)
-          return unless top_level_describe?(node)
+          # Fast pre-check: only process top-level describe (not context)
+          return unless node.method?(:describe)
+          return unless example_group?(node)
 
           # Find all leaf contexts (contexts with no nested contexts)
           leaf_contexts = find_leaf_contexts(node)
@@ -113,11 +153,12 @@ module RuboCop
           leaves = []
 
           node.each_descendant(:block) do |child|
-            next unless context_or_describe?(child)
+            # Use fast local matcher for performance-critical nested checks
+            next unless context_or_describe_block?(child)
 
             # Check if this context has nested contexts
             has_nested = child.each_descendant(:block).any? do |nested|
-              context_or_describe?(nested) && nested != child
+              context_or_describe_block?(nested) && nested != child
             end
 
             leaves << child unless has_nested

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpecGuide
+      # Checks that describe blocks test at least 2 behavioral variations.
+      #
+      # Testing only a single scenario (happy path OR edge case) provides
+      # insufficient coverage. Tests should verify both expected behavior
+      # and edge case handling to ensure comprehensive validation.
+      #
+      # This can be achieved in two ways:
+      # 1. Use 2+ sibling context blocks (happy path + edge cases)
+      # 2. Combine it-blocks (default behavior) with context-blocks (edge cases)
+      #
+      # @safety
+      #   This cop is safe to run automatically. For simple methods like getters
+      #   with no edge cases, use `# rubocop:disable RSpecGuide/MinimumBehavioralCoverage`
+      #
+      # @example Traditional approach - 2+ sibling contexts
+      #   # bad - only one scenario (no edge case testing)
+      #   describe '#calculate' do
+      #     context 'with valid data' do
+      #       it { expect(result).to eq(100) }
+      #     end
+      #   end
+      #
+      #   # good - multiple scenarios (happy path + edge cases)
+      #   describe '#calculate' do
+      #     context 'with valid data' do
+      #       it { expect(result).to eq(100) }
+      #     end
+      #
+      #     context 'with invalid data' do
+      #       it { expect { result }.to raise_error(ValidationError) }
+      #     end
+      #   end
+      #
+      #   # good - more comprehensive coverage
+      #   describe '#calculate' do
+      #     context 'with positive numbers' do
+      #       it { expect(result).to eq(100) }
+      #     end
+      #
+      #     context 'with zero' do
+      #       it { expect(result).to eq(0) }
+      #     end
+      #
+      #     context 'with negative numbers' do
+      #       it { expect { result }.to raise_error(ArgumentError) }
+      #     end
+      #   end
+      #
+      # @example New pattern - it-blocks + context-blocks
+      #   # bad - only default behavior, no edge cases
+      #   describe '#calculate' do
+      #     it 'calculates sum' { expect(result).to eq(100) }
+      #   end
+      #
+      #   # good - default behavior + edge case
+      #   describe '#calculate' do
+      #     it 'calculates sum with defaults' { expect(result).to eq(100) }
+      #
+      #     context 'with invalid input' do
+      #       it { expect { result }.to raise_error(ValidationError) }
+      #     end
+      #   end
+      #
+      #   # good - multiple it-blocks for defaults, context for edge case
+      #   describe '#calculate' do
+      #     it 'returns numeric result' { expect(result).to be_a(Numeric) }
+      #     it 'is positive' { expect(result).to be > 0 }
+      #
+      #     context 'with special conditions' do
+      #       it { expect(result).to eq(0) }
+      #     end
+      #   end
+      #
+      # @example Edge case - setup before tests (allowed)
+      #   # good - setup + it-blocks + contexts
+      #   describe '#calculate' do
+      #     let(:calculator) { Calculator.new }
+      #     before { calculator.configure }
+      #
+      #     it 'works with defaults' { expect(result).to eq(100) }
+      #
+      #     context 'with custom config' do
+      #       it { expect(result).to eq(200) }
+      #     end
+      #   end
+      #
+      # @example When to disable this cop
+      #   # Simple getter with no edge cases - disable is acceptable
+      #   describe '#name' do # rubocop:disable RSpecGuide/MinimumBehavioralCoverage
+      #     it { expect(subject.name).to eq('test') }
+      #   end
+      #
+      class MinimumBehavioralCoverage < RuboCop::Cop::RSpec::Base
+        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/MinimumBehavioralCoverage` " \
+              "for simple cases (e.g., getters) with no edge cases."
+
+        # Using rubocop-rspec API matchers (inherited from RuboCop::Cop::RSpec::Base):
+        # - example_group?(node) - checks describe/context blocks
+        # - example?(node) - checks it/specify blocks
+        # Custom matcher for context-only:
+
+        # @!method context_only?(node)
+        def_node_matcher :context_only?, <<~PATTERN
+          (block (send nil? :context ...) ...)
+        PATTERN
+
+        def on_block(node)
+          # Fast pre-check: only process describe blocks (not context)
+          return unless node.method?(:describe)
+          return unless example_group?(node)
+
+          children = collect_children(node)
+          contexts = children.select { |child| context_only?(child) }
+          its = children.select { |child| example?(child) }
+
+          # Valid if: 2+ contexts OR (1+ it-blocks before contexts AND 1+ contexts)
+          return if contexts.size >= 2
+          return if valid_it_then_context_pattern?(children, its, contexts)
+
+          add_offense(node)
+        end
+
+        private
+
+        def collect_children(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(&:block_type?)
+          elsif body.block_type?
+            # Single child
+            [body]
+          else
+            []
+          end
+        end
+
+        def valid_it_then_context_pattern?(children, its, contexts)
+          # Need at least one it-block and at least one context-block
+          return false if its.empty? || contexts.empty?
+
+          # Find positions of first it-block and first context-block
+          first_it_index = children.index { |child| example?(child) }
+          first_context_index = children.index { |child| context_only?(child) }
+
+          # All it-blocks must come before all context-blocks
+          first_it_index < first_context_index
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/rspec/guide/inject.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Inject our default configuration into RuboCop
+# This ensures config/default.yml is loaded automatically
+module RuboCop
+  module RSpec
+    module Guide
+      # Inject default configuration
+      module Inject
+        DEFAULT_FILE = File.expand_path("../../../../../config/default.yml", __FILE__)
+
+        def self.defaults!
+          path = DEFAULT_FILE
+          hash = ConfigLoader.send(:load_yaml_configuration, path)
+          config = Config.new(hash, path).tap(&:make_excludes_absolute)
+          puts "configuration from #{path}" if ConfigLoader.debug?
+          config = ConfigLoader.merge_with_default(config, path)
+          ConfigLoader.instance_variable_set(:@default_configuration, config)
+        end
+      end
+    end
+  end
+end
+
+# Inject defaults when the gem is loaded
+RuboCop::RSpec::Guide::Inject.defaults!

data/lib/rubocop/rspec/guide/plugin.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module RSpec
+    module Guide
+      # Plugin integration for RuboCop 1.72+
+      #
+      # This class provides the modern plugin API for RuboCop.
+      # It allows loading the gem via the `plugins:` configuration
+      # in .rubocop.yml instead of the legacy `require:` approach.
+      #
+      # @example Modern approach (RuboCop 1.72+)
+      #   # .rubocop.yml
+      #   plugins:
+      #     - rubocop-rspec-guide
+      #
+      # @example Legacy approach (still supported)
+      #   # .rubocop.yml
+      #   require:
+      #     - rubocop-rspec-guide
+      class Plugin
+        # Initialize the plugin
+        #
+        # @param config [RuboCop::Config, nil] the RuboCop configuration
+        def initialize(config = nil)
+          @config = config
+        end
+
+        # Plugin metadata
+        #
+        # @return [String] the plugin name
+        def name
+          "rubocop-rspec-guide"
+        end
+
+        # Plugin version
+        #
+        # @return [String] the plugin version
+        def version
+          RuboCop::RSpec::Guide::VERSION
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/rspec/guide/version.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module RSpec
     module Guide
-      VERSION = "0.2.2"
+      VERSION = "0.4.0"
     end
   end
 end