rubocop-rspec-guide 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbcc5261e61c2e9d16ccfa146e62046779e7e48f782a8fdb5003203cd55a99a4
+  data.tar.gz: 3b8c2dae7e97d1d892ba9077944c93de7370803ed3c92edfeb2e43e33a4f9c3f
+SHA512:
+  metadata.gz: f599508c8ad0870461f04847d6b6c727647557c645231b46df9e8bc63737e2118f50d9590fe7cfbec29668941170fe138187bb939bb0d750938f696c5de4bb2c
+  data.tar.gz: 8c9820bc4f21d0a7e82b1711f3abfc85a7131bc7b27b7b46b72c719f02c9426b4ad53f42512e6050677aa41ba903a1db1d45444fba35cd80fe609f0252b75b56

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,37 @@
+require:
+  - ./lib/rubocop-rspec-guide
+
+inherit_gem:
+  standard: config/base.yml
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+    - '.devbox/**/*'
+
+# Enable our custom cops
+RSpecGuide/CharacteristicsAndContexts:
+  Enabled: true
+
+RSpecGuide/HappyPathFirst:
+  Enabled: true
+
+RSpecGuide/ContextSetup:
+  Enabled: true
+
+RSpecGuide/DuplicateLetValues:
+  Enabled: true
+
+RSpecGuide/DuplicateBeforeHooks:
+  Enabled: true
+
+RSpecGuide/InvariantExamples:
+  Enabled: true
+  MinLeafContexts: 3
+
+FactoryBotGuide/DynamicAttributesForTimeAndRandom:
+  Enabled: true

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+## [Unreleased]
+
+## [0.2.0] - 2025-10-28
+
+### Changed
+- **RSpecGuide/ContextSetup**: `subject` is no longer accepted as valid context setup (BREAKING)
+  - Subject describes the object under test and should be at describe level
+  - Use `RSpec/LeadingSubject` cop to enforce subject placement
+  - Context setup now only accepts: `let`, `let!`, `before`
+
+### Removed
+- **RSpecGuide/TravelWithoutTravelBack**: Removed cop as it's redundant
+  - Rails automatically cleans up time stubs via `after_teardown` in `RailsExampleGroup`
+  - `MinitestLifecycleAdapter` is included by default in rspec-rails
+  - Manual `after { travel_back }` is not needed
+
+### Fixed
+- **RSpecGuide/ContextSetup**: Fixed logic to properly detect setup in context body
+- **RSpecGuide/CharacteristicsAndContexts**: Fixed AST traversal to handle `begin` nodes
+- **RSpecGuide/HappyPathFirst**: Fixed AST traversal to handle `begin` nodes
+- Test expectations now include cop name prefixes (e.g., `RSpecGuide/ContextSetup:`)
+
+## [0.1.0] - 2025-10-28
+
+### Added
+
+- Initial release with 7 custom RuboCop cops for RSpec best practices
+- **RSpecGuide/CharacteristicsAndContexts**: Requires at least 2 contexts in describe blocks (Rule 4)
+- **RSpecGuide/HappyPathFirst**: Ensures happy paths come before corner cases (Rule 7)
+- **RSpecGuide/ContextSetup**: Requires setup (let/before) in contexts (Rule 9)
+- **RSpecGuide/DuplicateLetValues**: Detects duplicate let declarations with same values (Rule 6)
+- **RSpecGuide/DuplicateBeforeHooks**: Detects duplicate before hooks (Rule 6)
+- **RSpecGuide/InvariantExamples**: Finds examples repeated in all leaf contexts (Rule 6)
+- **FactoryBotGuide/DynamicAttributesForTimeAndRandom**: Ensures Time.now and SecureRandom are wrapped in blocks
+- Comprehensive test suite with RSpec
+- Default configuration file (config/default.yml)
+- Documentation and usage examples in README

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 installer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,296 @@
+# RuboCop RSpec Guide
+
+Custom RuboCop cops that enforce best practices from the [RSpec Style Guide](https://github.com/AlexeyMatskevich/rspec-guide).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rubocop-rspec-guide', require: false
+```
+
+Or install it yourself:
+
+```bash
+gem install rubocop-rspec-guide
+```
+
+## Usage
+
+Add to your `.rubocop.yml`:
+
+```yaml
+require:
+  - rubocop-rspec-guide
+
+# Optionally inherit the default config
+inherit_gem:
+  rubocop-rspec-guide: config/default.yml
+
+# Recommended: Enable RSpec/LeadingSubject to ensure subject is at describe level
+RSpec/LeadingSubject:
+  Enabled: true
+```
+
+Or configure cops individually:
+
+```yaml
+require:
+  - rubocop-rspec-guide
+
+RSpecGuide/CharacteristicsAndContexts:
+  Enabled: true
+
+RSpecGuide/HappyPathFirst:
+  Enabled: true
+
+RSpecGuide/ContextSetup:
+  Enabled: true
+
+RSpecGuide/DuplicateLetValues:
+  Enabled: true
+
+RSpecGuide/DuplicateBeforeHooks:
+  Enabled: true
+
+RSpecGuide/InvariantExamples:
+  Enabled: true
+  MinLeafContexts: 3
+
+FactoryBotGuide/DynamicAttributesForTimeAndRandom:
+  Enabled: true
+```
+
+## Cops
+
+### RSpecGuide/CharacteristicsAndContexts
+
+Requires at least 2 contexts in a describe block (happy path + edge cases).
+
+```ruby
+# bad
+describe '#calculate' do
+  it 'works' { expect(result).to eq(100) }
+end
+
+# good
+describe '#calculate' do
+  context 'with valid data' do
+    it { expect(result).to eq(100) }
+  end
+
+  context 'with invalid data' do
+    it { expect(result).to be_error }
+  end
+end
+```
+
+### RSpecGuide/HappyPathFirst
+
+Ensures corner cases are not placed before happy paths.
+
+```ruby
+# bad
+describe '#process' do
+  context 'but user is blocked' do
+    # ...
+  end
+  context 'when user is valid' do
+    # ...
+  end
+end
+
+# good
+describe '#process' do
+  context 'when user is valid' do
+    # ...
+  end
+  context 'but user is blocked' do
+    # ...
+  end
+end
+```
+
+### RSpecGuide/ContextSetup
+
+Requires contexts to have setup (let/let!/let_it_be/let_it_be!/before) to distinguish them from parent.
+
+**Note:** `subject` should be defined at `describe` level, not in contexts, as it describes the object under test. Use `RSpec/LeadingSubject` cop to ensure subject is defined first.
+
+```ruby
+# bad - no setup
+context 'when premium' do
+  it { expect(user).to have_access }
+end
+
+# bad - subject in context (should be in describe)
+context 'when premium' do
+  subject { user }  # Wrong place!
+  it { is_expected.to have_access }
+end
+
+# good - let defines context-specific state
+context 'when premium' do
+  let(:user) { create(:user, :premium) }
+  it { expect(user).to have_access }
+end
+
+# good - let_it_be for performance (from test-prof/rspec-rails)
+context 'when premium' do
+  let_it_be(:user) { create(:user, :premium) }
+  it { expect(user).to have_access }
+end
+
+# good - before sets up context
+context 'when premium' do
+  before { user.upgrade_to_premium! }
+  it { expect(user).to have_access }
+end
+```
+
+### RSpecGuide/DuplicateLetValues
+
+Detects duplicate let declarations across sibling contexts with severity levels.
+
+**Severity Levels:**
+- **ERROR** - When let is duplicated in ALL sibling contexts → must extract to parent
+- **WARNING** - When let is duplicated in 2+ contexts but not all → suggests bad test hierarchy
+
+```ruby
+# bad - ERROR (in ALL contexts)
+context 'A' do
+  let(:currency) { :usd }
+end
+context 'B' do
+  let(:currency) { :usd }  # duplicate in all!
+end
+
+# bad - WARNING (partial duplicate, code smell)
+context 'A' do
+  let(:currency) { :usd }
+end
+context 'B' do
+  let(:currency) { :usd }  # duplicated in 2/3 contexts
+end
+context 'C' do
+  let(:currency) { :eur }  # different value
+end
+
+# good
+let(:currency) { :usd }  # extract to parent
+context 'A' do; end
+context 'B' do; end
+```
+
+**Configuration:**
+```yaml
+RSpecGuide/DuplicateLetValues:
+  WarnOnPartialDuplicates: true  # Show warnings for partial duplicates (default: true)
+```
+
+### RSpecGuide/DuplicateBeforeHooks
+
+Detects duplicate before hooks across sibling contexts with severity levels.
+
+**Severity Levels:**
+- **ERROR** - When before hook is duplicated in ALL sibling contexts → must extract to parent
+- **WARNING** - When before hook is duplicated in 2+ contexts but not all → suggests bad test hierarchy
+
+```ruby
+# bad - ERROR (in ALL contexts)
+context 'A' do
+  before { sign_in(user) }
+end
+context 'B' do
+  before { sign_in(user) }  # duplicate in all!
+end
+
+# bad - WARNING (partial duplicate, code smell)
+context 'A' do
+  before { setup }
+end
+context 'B' do
+  # no before
+end
+context 'C' do
+  before { setup }  # duplicated in 2/3 contexts
+end
+
+# good
+before { sign_in(user) }  # extract to parent
+context 'A' do; end
+context 'B' do; end
+```
+
+**Configuration:**
+```yaml
+RSpecGuide/DuplicateBeforeHooks:
+  WarnOnPartialDuplicates: true  # Show warnings for partial duplicates (default: true)
+```
+
+### RSpecGuide/InvariantExamples
+
+Detects examples repeated in all leaf contexts.
+
+```ruby
+# bad - same example in all 3 contexts
+context 'A' do
+  it 'responds to valid?' { }
+end
+context 'B' do
+  it 'responds to valid?' { }
+end
+context 'C' do
+  it 'responds to valid?' { }
+end
+
+# good - extract to shared_examples
+shared_examples 'a validator' do
+  it 'responds to valid?' { }
+end
+
+context 'A' do
+  it_behaves_like 'a validator'
+end
+```
+
+### FactoryBotGuide/DynamicAttributesForTimeAndRandom
+
+Ensures time and random values are wrapped in blocks.
+
+```ruby
+# bad
+factory :user do
+  created_at Time.now       # evaluated once!
+  token SecureRandom.hex    # same token for all users!
+end
+
+# good
+factory :user do
+  created_at { Time.now }
+  token { SecureRandom.hex }
+end
+```
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## References
+
+- [RSpec Style Guide](https://github.com/AlexeyMatskevich/rspec-guide)
+- [RuboCop RSpec](https://github.com/rubocop/rubocop-rspec)

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/config/default.yml

@@ -0,0 +1,38 @@
+---
+RSpecGuide/CharacteristicsAndContexts:
+  Description: "Require at least 2 contexts in describe block (happy path + edge cases)"
+  Enabled: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+RSpecGuide/DuplicateLetValues:
+  Description: "Detect duplicate let values in sibling contexts (ERROR if in all, WARNING if partial)"
+  Enabled: true
+  WarnOnPartialDuplicates: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+RSpecGuide/DuplicateBeforeHooks:
+  Description: "Detect duplicate before hooks in sibling contexts (ERROR if in all, WARNING if partial)"
+  Enabled: true
+  WarnOnPartialDuplicates: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+RSpecGuide/InvariantExamples:
+  Description: "Invariant examples should be in leaf contexts or extracted to shared_examples"
+  Enabled: true
+  MinLeafContexts: 3
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+RSpecGuide/HappyPathFirst:
+  Description: "Corner cases should not be first context (happy path first)"
+  Enabled: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+RSpecGuide/ContextSetup:
+  Description: "Context must have setup (let/before) to distinguish it from parent. Subject should be at describe level."
+  Enabled: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+
+FactoryBotGuide/DynamicAttributesForTimeAndRandom:
+  Description: "Wrap Time.now, SecureRandom and method calls in blocks for dynamic evaluation"
+  Enabled: true
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"

data/devbox.json

@@ -0,0 +1,14 @@
+{
+  "$schema":  "https://raw.githubusercontent.com/jetify-com/devbox/0.16.0/.schema/devbox.schema.json",
+  "packages": ["ruby@latest"],
+  "shell": {
+    "init_hook": [
+      "echo 'Welcome to devbox!' > /dev/null"
+    ],
+    "scripts": {
+      "test": [
+        "echo \"Error: no test specified\" && exit 1"
+      ]
+    }
+  }
+}

data/devbox.lock

@@ -0,0 +1,74 @@
+{
+  "lockfile_version": "1",
+  "packages": {
+    "github:NixOS/nixpkgs/nixpkgs-unstable": {
+      "last_modified": "2025-10-23T16:27:14Z",
+      "resolved": "github:NixOS/nixpkgs/d5faa84122bc0a1fd5d378492efce4e289f8eac1?lastModified=1761236834&narHash=sha256-%2Bpthv6hrL5VLW2UqPdISGuLiUZ6SnAXdd2DdUE%2BfV2Q%3D"
+    },
+    "ruby@latest": {
+      "last_modified": "2025-10-09T02:37:25Z",
+      "plugin_version": "0.0.2",
+      "resolved": "github:NixOS/nixpkgs/2dad7af78a183b6c486702c18af8a9544f298377#ruby_3_4",
+      "source": "devbox-search",
+      "version": "3.4.7",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/apawwv6ln4qlhar4x31hk83x35d88d4n-ruby-3.4.7",
+              "default": true
+            },
+            {
+              "name": "devdoc",
+              "path": "/nix/store/hwsjj4lwr4j6i4s71kgn82pq3wqdyk84-ruby-3.4.7-devdoc"
+            }
+          ],
+          "store_path": "/nix/store/apawwv6ln4qlhar4x31hk83x35d88d4n-ruby-3.4.7"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/wxx9v5gnz8nm8rwzy6snbkrbf859j0dp-ruby-3.4.7",
+              "default": true
+            },
+            {
+              "name": "devdoc",
+              "path": "/nix/store/iij6p6v02ffajhy821hz48q24a5rzc0i-ruby-3.4.7-devdoc"
+            }
+          ],
+          "store_path": "/nix/store/wxx9v5gnz8nm8rwzy6snbkrbf859j0dp-ruby-3.4.7"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/8qdy0dzskl8n46ywhmirkmhlrvsshc76-ruby-3.4.7",
+              "default": true
+            },
+            {
+              "name": "devdoc",
+              "path": "/nix/store/9wlpxwwrxs3bw9aqyl80sr4kvsrpvxan-ruby-3.4.7-devdoc"
+            }
+          ],
+          "store_path": "/nix/store/8qdy0dzskl8n46ywhmirkmhlrvsshc76-ruby-3.4.7"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/lgf2l2wkr5845485qw254skgc0bdvbnc-ruby-3.4.7",
+              "default": true
+            },
+            {
+              "name": "devdoc",
+              "path": "/nix/store/shxiyxnzkw8wk1xm1v7l2n61w9wpxqkm-ruby-3.4.7-devdoc"
+            }
+          ],
+          "store_path": "/nix/store/lgf2l2wkr5845485qw254skgc0bdvbnc-ruby-3.4.7"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module FactoryBotGuide
+      # Checks that time-related and random methods in FactoryBot definitions
+      # are wrapped in blocks for dynamic evaluation.
+      #
+      # @example
+      #   # bad
+      #   factory :user do
+      #     created_at Time.now
+      #     token SecureRandom.hex
+      #     expires_at 1.day.from_now
+      #   end
+      #
+      #   # good
+      #   factory :user do
+      #     created_at { Time.now }
+      #     token { SecureRandom.hex }
+      #     expires_at { 1.day.from_now }
+      #     name "John"  # Static values are OK
+      #   end
+      #
+      class DynamicAttributesForTimeAndRandom < Base
+        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
+end