rubocop-rspec-guide 0.2.0

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+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
+      #
+      #   # good
+      #   describe '#process' do
+      #     context 'when data is valid' do
+      #       it 'processes successfully' do
+      #         expect(subject.process).to be_success
+      #       end
+      #     end
+      #
+      #     context 'when data is invalid' do
+      #       it 'returns error' do
+      #         expect(subject.process).to be_error
+      #       end
+      #     end
+      #   end
+      #
+      class CharacteristicsAndContexts < Base
+        MSG = "Describe block should have at least 2 contexts " \
+              "(happy path + 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpecGuide
+      # Checks that context blocks have setup (let/before) to distinguish
+      # them from the parent context.
+      #
+      # 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
+      #   context 'when user is premium' do
+      #     it 'has access' do
+      #       expect(user).to have_access
+      #     end
+      #   end
+      #
+      #   # good
+      #   context 'when user is premium' do
+      #     let(:user) { create(:user, :premium) }
+      #
+      #     it 'has access' do
+      #       expect(user).to have_access
+      #     end
+      #   end
+      #
+      #   # good
+      #   context 'when user is premium' do
+      #     before { user.upgrade_to_premium! }
+      #
+      #     it 'has access' do
+      #       expect(user).to have_access
+      #     end
+      #   end
+      #
+      class ContextSetup < 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
+
+        # @!method before_hook?(node)
+        def_node_matcher :before_hook?, <<~PATTERN
+          (block (send nil? :before ...) ...)
+        PATTERN
+
+        def on_block(node)
+          return unless context_block?(node)
+
+          # Check if context has at least one setup node (let or before)
+          # Note: subject is NOT counted as context setup because it describes
+          # the object under test, not context-specific state
+          has_setup = has_context_setup?(node)
+
+          add_offense(node) unless has_setup
+        end
+
+        private
+
+        def has_context_setup?(context_node)
+          # Look for let/before blocks directly in this context
+          context_node.each_descendant(:block) do |block_node|
+            # Only check immediate children (not nested contexts)
+            is_immediate_child = block_node.parent == context_node ||
+              (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)
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @example
+      #   # bad
+      #   describe 'Controller' do
+      #     context 'as admin' do
+      #       before { sign_in(user) }
+      #       it { expect(response).to be_successful }
+      #     end
+      #
+      #     context 'as guest' do
+      #       before { sign_in(user) }  # Duplicate!
+      #       it { expect(response).to be_forbidden }
+      #     end
+      #   end
+      #
+      #   # good
+      #   describe 'Controller' do
+      #     before { sign_in(user) }  # Extracted to parent
+      #
+      #     context 'as admin' do
+      #       it { expect(response).to be_successful }
+      #     end
+      #
+      #     context 'as guest' do
+      #       it { expect(response).to be_forbidden }
+      #     end
+      #   end
+      #
+      class DuplicateBeforeHooks < 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
+          (block (send nil? :context ...) ...)
+        PATTERN
+
+        # @!method before_hook?(node)
+        def_node_matcher :before_hook?, <<~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)
+          return unless example_group?(node)
+
+          # Collect all sibling contexts
+          sibling_contexts = collect_sibling_contexts(node)
+          return if sibling_contexts.size < 2
+
+          # Collect before hooks from each context
+          befores_by_context = sibling_contexts.map do |ctx|
+            collect_before_hooks(ctx)
+          end
+
+          # Find duplicates
+          find_duplicate_befores(befores_by_context)
+        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
+
+        def collect_before_hooks(context_node)
+          befores = []
+
+          # The context block has a body that may contain before hooks
+          # We need to search within the body for before blocks
+          context_node.each_descendant(:block) do |block_node|
+            # Only check direct children of the context (not nested in sub-contexts)
+            is_immediate_child = block_node.parent == context_node ||
+              (block_node.parent.begin_type? && block_node.parent.parent == context_node)
+            next unless is_immediate_child
+
+            before_hook?(block_node) do |body|
+              befores << {body_source: normalize_source(body.source), node: block_node}
+            end
+          end
+
+          befores
+        end
+
+        def find_duplicate_befores(befores_by_context)
+          # Get all unique before hook sources
+          all_befores = befores_by_context.flatten
+          unique_sources = all_befores.map { |b| b[:body_source] }.uniq
+          total_contexts = befores_by_context.size
+
+          unique_sources.each do |source|
+            # Count how many contexts have this before hook
+            contexts_with_this_before = befores_by_context.count do |context_befores|
+              context_befores.any? { |b| b[:body_source] == source }
+            end
+
+            # Skip if only in one context
+            next if contexts_with_this_before <= 1
+
+            # ERROR: If this before hook is in ALL sibling contexts
+            if contexts_with_this_before == total_contexts
+              all_befores.each do |before_info|
+                next unless before_info[:body_source] == source
+
+                add_offense(before_info[:node], message: MSG_ERROR)
+              end
+            # WARNING: If duplicated in multiple (but not all) contexts
+            elsif cop_config.fetch("WarnOnPartialDuplicates", true) && contexts_with_this_before >= 2
+              all_befores.each do |before_info|
+                next unless before_info[:body_source] == source
+
+                add_offense(
+                  before_info[:node],
+                  message: format(MSG_WARNING, count: contexts_with_this_before, total: total_contexts),
+                  severity: :warning
+                )
+              end
+            end
+          end
+        end
+
+        def normalize_source(source)
+          # Normalize code for comparison:
+          # - Remove extra whitespace
+          # - Remove line breaks at start/end
+          source.strip.gsub(/\s+/, " ")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @example
+      #   # bad
+      #   describe 'Calculator' do
+      #     context 'with addition' do
+      #       let(:currency) { :usd }
+      #       it { expect(result).to eq(10) }
+      #     end
+      #
+      #     context 'with subtraction' do
+      #       let(:currency) { :usd }  # Duplicate!
+      #       it { expect(result).to eq(5) }
+      #     end
+      #   end
+      #
+      #   # good
+      #   describe 'Calculator' do
+      #     let(:currency) { :usd }  # Extracted to parent
+      #
+      #     context 'with addition' do
+      #       it { expect(result).to eq(10) }
+      #     end
+      #
+      #     context 'with subtraction' do
+      #       it { expect(result).to eq(5) }
+      #     end
+      #   end
+      #
+      class DuplicateLetValues < 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
+          (block (send nil? :context ...) ...)
+        PATTERN
+
+        # @!method let_declaration?(node)
+        def_node_matcher :let_declaration?, <<~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)
+          return unless example_group?(node)
+
+          # Collect all sibling contexts
+          sibling_contexts = collect_sibling_contexts(node)
+          return if sibling_contexts.size < 2
+
+          # Collect let declarations from each context
+          lets_by_context = sibling_contexts.map do |ctx|
+            collect_lets_in_context(ctx)
+          end
+
+          # Find duplicates
+          find_duplicate_lets(lets_by_context)
+        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
+
+        def collect_lets_in_context(context_node)
+          lets = {}
+
+          # Search within the context body for let declarations
+          context_node.each_descendant(:block) do |block_node|
+            # Only check direct children of the context (not nested in sub-contexts)
+            is_immediate_child = block_node.parent == context_node ||
+              (block_node.parent.begin_type? && block_node.parent.parent == context_node)
+            next unless is_immediate_child
+
+            let_declaration?(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}
+              end
+            end
+          end
+
+          lets
+        end
+
+        def find_duplicate_lets(lets_by_context)
+          # Get all let names across contexts
+          all_let_names = lets_by_context.flat_map(&:keys).uniq
+          total_contexts = lets_by_context.size
+
+          all_let_names.each do |let_name|
+            # Find contexts that have this let
+            contexts_with_let = lets_by_context.select { |lets| lets.key?(let_name) }
+
+            # Skip if only in one context
+            next if contexts_with_let.size <= 1
+
+            # Collect all values
+            values = contexts_with_let.map { |lets| lets[let_name][:value] }
+
+            # Skip if values differ
+            next unless values.uniq.size == 1
+
+            value = values.first
+
+            # ERROR: If let with same value is in ALL contexts
+            if contexts_with_let.size == total_contexts
+              contexts_with_let.each do |lets|
+                add_offense(
+                  lets[let_name][:node],
+                  message: format(MSG_ERROR, name: let_name, value: value)
+                )
+              end
+            # WARNING: If duplicated in multiple (but not all) contexts
+            elsif cop_config.fetch("WarnOnPartialDuplicates", true) && contexts_with_let.size >= 2
+              contexts_with_let.each do |lets|
+                add_offense(
+                  lets[let_name][:node],
+                  message: format(MSG_WARNING, name: let_name, value: value,
+                    count: contexts_with_let.size, total: total_contexts),
+                  severity: :warning
+                )
+              end
+            end
+          end
+        end
+
+        def simple_value?(node)
+          # Values we can safely compare by source
+          return true if node.sym_type? || node.str_type? || node.int_type? || node.float_type?
+          return true if node.true_type? || node.false_type? || node.nil_type?
+
+          # Handle hash pair nodes (key-value pairs inside hashes)
+          if node.pair_type?
+            return simple_value?(node.key) && simple_value?(node.value)
+          end
+
+          if node.hash_type?
+            # Hash children are pair nodes
+            return node.children.all? { |child| simple_value?(child) }
+          end
+
+          if node.array_type?
+            # Array children can be any simple values
+            return node.children.all? { |child| simple_value?(child) }
+          end
+
+          # Method calls like create(:user), build(:post), etc.
+          # We can compare these by source code
+          return true if node.send_type?
+
+          # Blocks like { Time.now } - compare by source
+          return true if node.block_type?
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @example
+      #   # bad
+      #   describe '#process' do
+      #     context 'but user is blocked' do
+      #       # ...
+      #     end
+      #     context 'when user is valid' do
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # bad
+      #   describe '#activate' do
+      #     context 'when user does NOT exist' do
+      #       # ...
+      #     end
+      #     context 'when user exists' do
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # good
+      #   describe '#subscribe' do
+      #     context 'with valid card' do
+      #       # ...
+      #     end
+      #     context 'but payment fails' do
+      #       # ...
+      #     end
+      #   end
+      #
+      class HappyPathFirst < Base
+        MSG = "Place happy path contexts before corner cases. " \
+              "First context appears to be a corner case: %<description>s"
+
+        # Words indicating corner cases
+        CORNER_CASE_WORDS = %w[
+          error failure invalid suspended blocked denied
+          fails missing absent unavailable
+        ].freeze
+
+        # @!method context_with_description?(node)
+        def_node_matcher :context_with_description?, <<~PATTERN
+          (block
+            (send nil? :context (str $_description) ...)
+            ...)
+        PATTERN
+
+        # @!method example_group?(node)
+        def_node_matcher :example_group?, <<~PATTERN
+          (block
+            (send nil? {:describe :context} ...)
+            ...)
+        PATTERN
+
+        def on_block(node)
+          return unless example_group?(node)
+
+          contexts = collect_direct_child_contexts(node)
+          return if contexts.size < 2
+
+          # Check first context
+          context_with_description?(contexts.first) do |description|
+            if corner_case_context?(description)
+              add_offense(
+                contexts.first,
+                message: format(MSG, description: description)
+              )
+            end
+          end
+        end
+
+        private
+
+        def collect_direct_child_contexts(node)
+          body = node.body
+          return [] unless body
+
+          if body.begin_type?
+            # Multiple children wrapped in begin node
+            body.children.select { |child| child.block_type? && context_with_description?(child) }
+          elsif body.block_type? && context_with_description?(body)
+            # Single context child
+            [body]
+          else
+            []
+          end
+        end
+
+        def corner_case_context?(description)
+          lower_desc = description.downcase
+
+          # 1. Starts with "but" (opposition)
+          return true if description.start_with?("but ")
+
+          # 2. Contains NOT in caps (explicit negation)
+          return true if description.include?(" NOT ")
+
+          # 3. Contains negative words
+          return true if CORNER_CASE_WORDS.any? { |word| lower_desc.include?(word) }
+
+          # 4. "without" is NOT a corner case - it's a binary alternative
+          false
+        end
+      end
+    end
+  end
+end