rubocop-rspec-guide 0.2.1 → 0.4.0

data/README.md

@@ -1,5 +1,11 @@
 # RuboCop RSpec Guide
 
+[![Gem Version](https://badge.fury.io/rb/rubocop-rspec-guide.svg)](https://badge.fury.io/rb/rubocop-rspec-guide)
+[![CI](https://github.com/rspec-guide/rubocop-rspec-guide/workflows/CI/badge.svg)](https://github.com/rspec-guide/rubocop-rspec-guide/actions)
+[![Downloads](https://img.shields.io/gem/dt/rubocop-rspec-guide.svg)](https://rubygems.org/gems/rubocop-rspec-guide)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-blue.svg)](https://www.ruby-lang.org)
+
 Custom RuboCop cops that enforce best practices from the [RSpec Style Guide](https://github.com/AlexeyMatskevich/rspec-guide).
 
 ## Installation
@@ -18,28 +24,225 @@ gem install rubocop-rspec-guide
 
 ## Usage
 
-Add to your `.rubocop.yml`:
+### Quick Start
+
+1. **Add to Gemfile:**
+   ```ruby
+   group :development, :test do
+     gem 'rubocop-rspec-guide', require: false
+   end
+   ```
+
+2. **Install:**
+   ```bash
+   bundle install
+   ```
+
+3. **Configure `.rubocop.yml`:**
+   
+   **Minimal configuration (v0.4.0+):**
+   ```yaml
+   # RuboCop 1.72+
+   plugins:
+     - rubocop-rspec-guide
+   
+   # RuboCop < 1.72
+   require:
+     - rubocop-rspec-guide
+   ```
+   
+   The gem automatically loads its default configuration, including RSpec Language settings.
+   
+   **Optional - explicit config inheritance:**
+   
+   If you want to explicitly inherit the config (not required):
+   ```yaml
+   plugins:
+     - rubocop-rspec-guide
+   
+   inherit_gem:
+     rubocop-rspec-guide: config/default.yml
+   ```
+
+4. **Run RuboCop:**
+   ```bash
+   bundle exec rubocop
+   ```
+
+5. **Fix offenses automatically (where possible):**
+   ```bash
+   bundle exec rubocop -a
+   # or for safe autocorrection only:
+   bundle exec rubocop -A
+   ```
+
+### Autocorrection Support
+
+Some cops support **automatic correction** with `rubocop -a`:
+
+| Cop | Autocorrect | Safety |
+|-----|-------------|--------|
+| `FactoryBotGuide/DynamicAttributeEvaluation` | ✅ Yes | Safe |
+| `RSpecGuide/MinimumBehavioralCoverage` | ❌ No | - |
+| `RSpecGuide/HappyPathFirst` | ❌ No | - |
+| `RSpecGuide/ContextSetup` | ❌ No | - |
+| `RSpecGuide/DuplicateLetValues` | ❌ No | - |
+| `RSpecGuide/DuplicateBeforeHooks` | ❌ No | - |
+| `RSpecGuide/InvariantExamples` | ❌ No | - |
+
+**Example of autocorrection:**
+
+```ruby
+# Before: offense detected
+factory :user do
+  created_at Time.now
+  token SecureRandom.hex
+end
+
+# After: rubocop -a
+factory :user do
+  created_at { Time.now }
+  token { SecureRandom.hex }
+end
+```
+
+### Common Patterns
+
+#### Pattern 1: Testing Happy Path + Edge Cases
+
+```ruby
+# Before (offense)
+describe '#calculate_discount' do
+  it 'calculates discount' do
+    expect(calculate_discount(100)).to eq(10)
+  end
+end
+
+# After (fixed)
+describe '#calculate_discount' do
+  context 'with standard price' do
+    it { expect(calculate_discount(100)).to eq(10) }
+  end
+
+  context 'with zero price' do
+    it { expect(calculate_discount(0)).to eq(0) }
+  end
+
+  context 'with negative price' do
+    it { expect { calculate_discount(-10) }.to raise_error(ArgumentError) }
+  end
+end
+```
+
+#### Pattern 2: It-blocks + Context-blocks
+
+```ruby
+# Good - default behavior + edge cases
+describe '#process_payment' do
+  it 'processes payment successfully' do
+    expect(process_payment).to be_success
+  end
+
+  context 'when payment gateway is down' do
+    before { stub_gateway_down }
+    it { expect(process_payment).to be_failure }
+  end
+
+  context 'with insufficient funds' do
+    let(:balance) { 0 }
+    it { expect(process_payment).to be_declined }
+  end
+end
+```
+
+#### Pattern 3: Extracting Duplicate Setup
+
+```ruby
+# Before (offense - duplicate let in all contexts)
+describe 'PaymentProcessor' do
+  context 'with credit card' do
+    let(:currency) { :usd }
+    it { expect(process).to be_success }
+  end
+
+  context 'with paypal' do
+    let(:currency) { :usd }  # Duplicate!
+    it { expect(process).to be_success }
+  end
+end
+
+# After (fixed - extracted to parent)
+describe 'PaymentProcessor' do
+  let(:currency) { :usd }  # Moved to parent
+
+  context 'with credit card' do
+    it { expect(process).to be_success }
+  end
+
+  context 'with paypal' do
+    it { expect(process).to be_success }
+  end
+end
+```
+
+### Configuration Examples
+
+#### Complete Setup (with rubocop-rspec and rubocop-factory_bot)
+
+Most projects use `rubocop-rspec-guide` alongside `rubocop-rspec` and `rubocop-factory_bot`. Here's a complete configuration:
 
 ```yaml
+# .rubocop.yml
+
+# Load all RSpec-related extensions
 require:
+  - rubocop-rspec
+  - rubocop-rspec_rails  # If using Rails
+  - rubocop-factory_bot
   - rubocop-rspec-guide
 
-# Optionally inherit the default config
-inherit_gem:
-  rubocop-rspec-guide: config/default.yml
+# Or use plugins syntax (RuboCop 1.72+):
+# plugins:
+#   - rubocop-rspec
+#   - rubocop-rspec_rails
+#   - rubocop-factory_bot
+#   - rubocop-rspec-guide
+
+# RSpec cops (from rubocop-rspec)
+RSpec/VerifiedDoubles:
+  Enabled: true
+
+RSpec/MessageSpies:
+  Enabled: true
+  EnforcedStyle: have_received
+
+# FactoryBot cops (from rubocop-factory_bot)
+FactoryBot/CreateList:
+  Enabled: true
+
+# RSpec Style Guide cops (from rubocop-rspec-guide)
+RSpecGuide/MinimumBehavioralCoverage:
+  Enabled: true
+
+RSpecGuide/HappyPathFirst:
+  Enabled: true
 
-# Recommended: Enable RSpec/LeadingSubject to ensure subject is at describe level
-RSpec/LeadingSubject:
+RSpecGuide/ContextSetup:
+  Enabled: true
+
+FactoryBotGuide/DynamicAttributeEvaluation:
   Enabled: true
 ```
 
-Or configure cops individually:
+**Note:** The gem automatically injects RSpec Language configuration (v0.4.0+), so no `inherit_gem` is needed.
+
+#### Strict Mode (for new projects)
 
 ```yaml
 require:
   - rubocop-rspec-guide
 
-RSpecGuide/CharacteristicsAndContexts:
+RSpecGuide/MinimumBehavioralCoverage:
   Enabled: true
 
 RSpecGuide/HappyPathFirst:
@@ -50,23 +253,200 @@ RSpecGuide/ContextSetup:
 
 RSpecGuide/DuplicateLetValues:
   Enabled: true
+  WarnOnPartialDuplicates: true
 
 RSpecGuide/DuplicateBeforeHooks:
   Enabled: true
+  WarnOnPartialDuplicates: true
 
 RSpecGuide/InvariantExamples:
   Enabled: true
   MinLeafContexts: 3
 
+FactoryBotGuide/DynamicAttributeEvaluation:
+  Enabled: true
+```
+
+#### Relaxed Mode (for legacy projects)
+
+```yaml
+require:
+  - rubocop-rspec-guide
+
+# Enable only critical cops
+RSpecGuide/MinimumBehavioralCoverage:
+  Enabled: true
+
+RSpecGuide/ContextSetup:
+  Enabled: true
+
+# Disable warnings for partial duplicates
+RSpecGuide/DuplicateLetValues:
+  Enabled: true
+  WarnOnPartialDuplicates: false
+
+RSpecGuide/DuplicateBeforeHooks:
+  Enabled: true
+  WarnOnPartialDuplicates: false
+
+# More lenient threshold for invariants
+RSpecGuide/InvariantExamples:
+  Enabled: true
+  MinLeafContexts: 5  # Only report if in 5+ contexts
+
+# Disable strict cops
+RSpecGuide/HappyPathFirst:
+  Enabled: false
+
+FactoryBotGuide/DynamicAttributeEvaluation:
+  Enabled: true
+```
+
+### Troubleshooting
+
+#### Issue: Too many offenses in existing codebase
+
+**Solution:** Enable cops gradually:
+
+```yaml
+# Start with most important cops
+RSpecGuide/ContextSetup:
+  Enabled: true
+
+FactoryBotGuide/DynamicAttributeEvaluation:
+  Enabled: true
+
+# Disable others temporarily
+RSpecGuide/MinimumBehavioralCoverage:
+  Enabled: false
+
+RSpecGuide/DuplicateLetValues:
+  Enabled: false
+```
+
+Then enable one cop at a time, fix offenses, and move to the next.
+
+#### Issue: False positives on simple getters
+
+**Solution:** Disable cop for specific tests:
+
+```ruby
+describe '#name' do # rubocop:disable RSpecGuide/MinimumBehavioralCoverage
+  it { expect(subject.name).to eq('test') }
+end
+```
+
+#### Issue: "Duplicate let" warning but values are contextual
+
+**Solution:** This usually indicates poor test hierarchy. Refactor:
+
+```ruby
+# Before - partial duplicates (2/3 contexts)
+describe 'Converter' do
+  context 'scenario A' do
+    let(:format) { :json }
+    # ...
+  end
+  context 'scenario B' do
+    let(:format) { :json }  # Duplicate!
+    # ...
+  end
+  context 'scenario C' do
+    let(:format) { :xml }  # Different
+    # ...
+  end
+end
+
+# After - better hierarchy
+describe 'Converter' do
+  context 'with JSON format' do
+    let(:format) { :json }
+    
+    context 'scenario A' do
+      # ...
+    end
+    
+    context 'scenario B' do
+      # ...
+    end
+  end
+  
+  context 'with XML format' do
+    let(:format) { :xml }
+    
+    context 'scenario C' do
+      # ...
+    end
+  end
+end
+```
+
+### Migration Guide
+
+#### Upgrading to v0.4.0
+
+**Configuration changes:**
+
+Starting from v0.4.0, the gem automatically injects its default configuration, including RSpec Language settings. You can simplify your `.rubocop.yml`:
+
+```yaml
+# Before (v0.3.x) - explicit inheritance required
+plugins:
+  - rubocop-rspec-guide
+
+inherit_gem:
+  rubocop-rspec-guide: config/default.yml
+
+# After (v0.4.0+) - automatic config injection
+plugins:
+  - rubocop-rspec-guide
+```
+
+**What changed:**
+- ✅ `let_it_be` and `let_it_be!` are now automatically recognized (from `test-prof` / `rspec-rails`)
+- ✅ All cops now use `RuboCop::Cop::RSpec::Base` for better RSpec DSL detection
+- ✅ Significant performance improvement: `InvariantExamples` is 4.25x faster
+- ✅ More accurate detection of RSpec constructs
+
+**No code changes needed** - your existing RSpec tests will work as before, but with better analysis.
+
+#### From CharacteristicsAndContexts to MinimumBehavioralCoverage
+
+The old name still works as an alias, but you should update your config:
+
+```yaml
+# Old (deprecated)
+RSpecGuide/CharacteristicsAndContexts:
+  Enabled: true
+
+# New (recommended)
+RSpecGuide/MinimumBehavioralCoverage:
+  Enabled: true
+```
+
+No code changes needed - the cop behavior is the same.
+
+#### From DynamicAttributesForTimeAndRandom to DynamicAttributeEvaluation
+
+The old name still works as an alias:
+
+```yaml
+# Old (deprecated)
 FactoryBotGuide/DynamicAttributesForTimeAndRandom:
   Enabled: true
+
+# New (recommended)
+FactoryBotGuide/DynamicAttributeEvaluation:
+  Enabled: true
 ```
 
+The new cop checks ALL method calls, not just Time/Random, providing better coverage.
+
 ## Cops
 
-### RSpecGuide/CharacteristicsAndContexts
+### RSpecGuide/MinimumBehavioralCoverage
 
-Requires at least 2 contexts in a describe block (happy path + edge cases).
+Requires at least 2 behavioral variations in a describe block: either 2+ sibling contexts OR it-blocks + context-blocks.
 
 ```ruby
 # bad
@@ -74,7 +454,7 @@ describe '#calculate' do
   it 'works' { expect(result).to eq(100) }
 end
 
-# good
+# good - 2+ contexts
 describe '#calculate' do
   context 'with valid data' do
     it { expect(result).to eq(100) }
@@ -84,8 +464,21 @@ describe '#calculate' do
     it { expect(result).to be_error }
   end
 end
+
+# good - it-blocks + context-blocks
+describe '#calculate' do
+  it 'works with defaults' do
+    expect(result).to eq(100)
+  end
+
+  context 'with invalid data' do
+    it { expect(result).to be_error }
+  end
+end
 ```
 
+**Note:** The old name `RSpecGuide/CharacteristicsAndContexts` is deprecated but still works as an alias.
+
 ### RSpecGuide/HappyPathFirst
 
 Ensures corner cases are not placed before happy paths.
@@ -255,24 +648,44 @@ context 'A' do
 end
 ```
 
-### FactoryBotGuide/DynamicAttributesForTimeAndRandom
+### FactoryBotGuide/DynamicAttributeEvaluation
 
-Ensures time and random values are wrapped in blocks.
+Ensures method calls in factory attributes are wrapped in blocks for dynamic evaluation.
 
 ```ruby
-# bad
+# bad - method calls evaluated once at factory load time
 factory :user do
-  created_at Time.now       # evaluated once!
+  created_at Time.now       # same timestamp for all users!
   token SecureRandom.hex    # same token for all users!
+  expires_at 1.day.from_now # same expiry for all users!
+  tags Array.new            # same array instance shared!
 end
 
-# good
+# good - wrapped in blocks for dynamic evaluation
 factory :user do
   created_at { Time.now }
   token { SecureRandom.hex }
+  expires_at { 1.day.from_now }
+  tags { Array.new }
+  name "John"               # static values are OK
 end
 ```
 
+**Note:** The old name `FactoryBotGuide/DynamicAttributesForTimeAndRandom` is deprecated but still works as an alias.
+
+## Documentation
+
+Full API documentation is available:
+
+- **Generate locally**: `bundle exec rake doc`
+- **View documentation**: Open `doc/index.html` in your browser
+- **Quick open**: `bundle exec rake doc_open`
+
+The documentation includes:
+- Detailed cop descriptions with examples
+- Configuration options for each cop
+- API reference for all classes and modules
+
 ## Development
 
 After checking out the repo:
@@ -282,10 +695,24 @@ bundle install
 bundle exec rspec
 ```
 
+Generate documentation:
+
+```bash
+bundle exec rake doc
+```
+
+Run benchmarks:
+
+```bash
+bundle exec rake benchmark:quick
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub.
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -8,3 +8,52 @@ RSpec::Core::RakeTask.new(:spec)
 require "standard/rake"
 
 task default: %i[spec standard]
+
+namespace :benchmark do
+  desc "Run quick benchmarks for all cops (fast feedback, ~1 minute)"
+  task :quick do
+    ruby "benchmark/cops_benchmark.rb"
+  end
+
+  desc "Run performance benchmarks for all cops"
+  task :cops do
+    ruby "benchmark/cops_benchmark.rb"
+  end
+
+  desc "Run scalability benchmarks"
+  task :scalability do
+    ruby "benchmark/scalability_benchmark.rb"
+  end
+
+  desc "Run all benchmarks in quick mode (~2 minutes)"
+  task all: [:cops, :scalability]
+
+  desc "Run full benchmarks with accurate measurements (~5 minutes)"
+  task :full do
+    ENV["FULL_BENCHMARK"] = "1"
+    Rake::Task["benchmark:all"].invoke
+  end
+end
+
+desc "Run all benchmarks in quick mode"
+task benchmark: "benchmark:all"
+
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = ["--output-dir", "doc", "--readme", "README.md"]
+  end
+
+  desc "Generate documentation and open in browser"
+  task doc_open: :doc do
+    system("open doc/index.html") || system("xdg-open doc/index.html")
+  end
+rescue LoadError
+  # YARD not available, skip doc tasks
+  desc "Generate YARD documentation (YARD not installed)"
+  task :doc do
+    abort "YARD is not available. Install it with: gem install yard"
+  end
+end