rubocop-rspec-guide 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9093b8623b631c2b9ddaf15d1b72a1638c499d93e9820687dd37ec6e71f27d30
-  data.tar.gz: '09d4eb92564fcfd55bb9d72b15eaf690a5d1e8ada0621f6f281de369a2c1c683'
+  metadata.gz: bcebf8b42eee358b662dc641b3e07c805897742a37cb5dd88464b6423b7ca2fa
+  data.tar.gz: 8b903dbd42050fbef4a51e61ed961ac6c1175ac997ca80ed4305b4cdfa529027
 SHA512:
-  metadata.gz: beaebca72cb64609567dd9bc687961cfe193d228d1a25a50de8371a1e605f8265cc596ed2695e942b0d5f679a1f23d2581ef8a8aec176d7c26a5174c323146eb
-  data.tar.gz: 3783cee1af2fa2d784f0ad67ce7bcf08019aab358e7d6f5c2f9d53f7b26d5bf0dbe9dd55566c0bb347e30c331ae26f0f6467d3c51972cf1071cda15cab1e8d4c
+  metadata.gz: 30c52761374276952c116c748486a52373b4d8f3158826d1d5ed59e2e1e3a993e460e76e1c9a267a1545cfd5fb21d985a0d947b818ad31d850d24ce2d0fa0ab5
+  data.tar.gz: 13833dbdb0ff5094a33e683f248fb4b1378fdb5e57d6afb40906dc78da0a843622a87fa604d3e07eee617eef7425e3fc834c26b42b0d6d2839e6b9d2b2d2afec

data/.rubocop.yml

@@ -8,13 +8,13 @@ AllCops:
   NewCops: enable
   TargetRubyVersion: 3.0
   Exclude:
-    - 'vendor/**/*'
-    - 'tmp/**/*'
-    - 'bin/**/*'
-    - '.devbox/**/*'
+    - "vendor/**/*"
+    - "tmp/**/*"
+    - "bin/**/*"
+    - ".devbox/**/*"
 
 # Enable our custom cops
-RSpecGuide/CharacteristicsAndContexts:
+RSpecGuide/MinimumBehavioralCoverage:
   Enabled: true
 
 RSpecGuide/HappyPathFirst:
@@ -33,5 +33,5 @@ RSpecGuide/InvariantExamples:
   Enabled: true
   MinLeafContexts: 3
 
-FactoryBotGuide/DynamicAttributesForTimeAndRandom:
+FactoryBotGuide/DynamicAttributeEvaluation:
   Enabled: true

data/.yardopts

@@ -0,0 +1,9 @@
+--output-dir doc
+--readme README.md
+--markup markdown
+--no-private
+lib/**/*.rb
+- CHANGELOG.md
+- CONTRIBUTING.md
+- INTEGRATION_TESTING.md
+- LICENSE.txt

data/CHANGELOG.md

@@ -1,5 +1,91 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-30
+
+### Added
+- **Integration with RuboCop::Cop::RSpec::Base**: All 6 RSpec cops now inherit from `RuboCop::Cop::RSpec::Base`
+  - Leverages rubocop-rspec Language API for better RSpec DSL detection
+  - Native support for `let_it_be` and `let_it_be!` from rspec-rails
+  - More accurate detection of RSpec constructs
+- **RSpec Language configuration**: Added comprehensive RSpec/Language config in `config/default.yml`
+  - Enables rubocop-rspec API matchers: `example_group?()`, `example?()`, `let?()`, `hook?()`
+  - Supports ExampleGroups, Examples, Helpers, Hooks, and Subjects
+- **Configuration injection**: Created `lib/rubocop/rspec/guide/inject.rb` to automatically load gem config
+- **Test helper improvements**: Added `rubocop_config_with_rspec_language` helper for consistent test setup
+
+### Changed
+- **Removed duplicate node matchers**: Eliminated ~30 lines of code that duplicated rubocop-rspec functionality
+  - `example_group?()` - now uses API instead of custom matcher
+  - `example?()` - now uses API instead of custom matcher  
+  - `let?()` - now uses API (also recognizes let_it_be/let_it_be!)
+  - `hook?()` - now uses API instead of custom matcher
+- **Kept strategic custom matchers**: Retained specific matchers where needed
+  - `context_only?()` - for filtering only context blocks
+  - `let_with_name_and_value?()` - captures let name and value
+  - `before_hook_with_body?()` - captures hook body
+  - `example_with_description?()` - captures example description
+
+### Performance
+- **Optimized for production use**: Applied two-level optimization strategy
+  - Fast pre-checks: Added `node.method?(:describe)` checks before API calls
+  - Local matchers for hot paths: InvariantExamples uses fast local matching in O(n²) loops
+- **InvariantExamples**: **4.25x faster** than v0.3.1 baseline (1,504 → 6,395 i/s) 🚀
+- **Other cops**: 10-25% slower than baseline, acceptable trade-off for correctness and maintainability
+- **Real-world impact**: All cops remain fast enough for CI/CD pipelines (1,200-6,395 i/s)
+- **Detailed analysis**: See `PERFORMANCE_REPORT.md` for comprehensive performance documentation
+
+### Fixed
+- **ContextSetup**: Now correctly recognizes `let_it_be` and `let_it_be!` as valid context setup
+
+## [0.3.1] - 2025-10-30
+
+### Added
+- **Plugin support for RuboCop 1.72+**: Added `lib/rubocop/rspec/guide/plugin.rb` for modern plugin system
+  - Now supports both `plugins:` (recommended for RuboCop 1.72+) and `require:` (legacy) configuration
+  - Fully backward compatible with older RuboCop versions
+- **Version metadata in config/default.yml**: Added `VersionAdded` and `VersionChanged` fields to all cops
+  - Follows RuboCop conventions for tracking cop history
+  - Helps users understand when cops were introduced and modified
+
+### Changed
+- **README.md**: Updated with both modern (`plugins:`) and legacy (`require:`) configuration examples
+  - Clear documentation for different RuboCop versions
+  - Migration guidance for users upgrading RuboCop
+
+### Fixed
+- **Build process**: Added `*.gem` to `.gitignore` to prevent built gems from being committed
+
+## [0.3.0] - 2025-10-30
+
+### Added
+- **RSpecGuide/MinimumBehavioralCoverage**: New cop replacing CharacteristicsAndContexts with enhanced functionality
+  - Now supports two patterns for behavioral variations:
+    1. Traditional: 2+ sibling context blocks
+    2. New: it-blocks (default behavior) + context-blocks (edge cases)
+  - Better reflects the goal: ensuring minimum behavioral coverage in tests
+- **FactoryBotGuide/DynamicAttributeEvaluation**: New cop replacing DynamicAttributesForTimeAndRandom
+  - More accurate name reflecting broader scope: checks ALL method calls, not just Time/Random
+  - Covers Time.now, SecureRandom.hex, 1.day.from_now, Array.new, and any other method calls
+  - Ensures dynamic evaluation by requiring block syntax for all method-based attributes
+- **config/obsoletion.yml**: Added cop obsoletion configuration for tracking renamed cops
+
+### Changed
+- **RSpecGuide/MinimumBehavioralCoverage**: Enhanced to accept it-blocks + context-blocks pattern
+  - Validates that it-blocks appear before context-blocks (strict ordering)
+  - Allows tests with before/let setup + it-blocks + context-blocks
+  - Updated error messages to explain both valid patterns
+- Improved documentation and examples in README.md
+  - Added examples for new it-blocks + context-blocks pattern
+  - Clarified that deprecated cop names still work as aliases
+
+### Deprecated
+- **RSpecGuide/CharacteristicsAndContexts**: Deprecated in favor of MinimumBehavioralCoverage
+  - Still works as an alias for backward compatibility
+  - Will be removed in a future major version
+- **FactoryBotGuide/DynamicAttributesForTimeAndRandom**: Deprecated in favor of DynamicAttributeEvaluation
+  - Still works as an alias for backward compatibility
+  - Will be removed in a future major version
+
 ## [0.2.2] - 2025-10-29
 
 ### Fixed

data/CONTRIBUTING.md

@@ -0,0 +1,358 @@
+# Contributing to RuboCop RSpec Guide
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Creating a New Cop](#creating-a-new-cop)
+- [Writing Tests](#writing-tests)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Submitting Changes](#submitting-changes)
+- [Commit Message Guidelines](#commit-message-guidelines)
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you are expected to uphold this code.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/rubocop-rspec-guide.git
+   cd rubocop-rspec-guide
+   ```
+3. Add the upstream repository:
+   ```bash
+   git remote add upstream https://github.com/AlexeyMatskevich/rubocop-rspec-guide.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.0 or higher
+- Bundler
+
+### Install Dependencies
+
+```bash
+bundle install
+```
+
+### Run Tests
+
+```bash
+bundle exec rspec
+```
+
+All tests should pass before you start making changes.
+
+### Run RuboCop
+
+```bash
+bundle exec rubocop
+```
+
+Make sure your code follows the project's style guidelines.
+
+## Creating a New Cop
+
+### 1. Generate Cop File
+
+Create a new file in the appropriate directory:
+
+- For RSpec cops: `lib/rubocop/cop/rspec_guide/your_cop_name.rb`
+- For FactoryBot cops: `lib/rubocop/cop/factory_bot_guide/your_cop_name.rb`
+
+### 2. Basic Cop Structure
+
+```ruby
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpecGuide
+      # Short description of what the cop checks.
+      #
+      # Longer explanation of WHY this is important and what problems
+      # it prevents or solves.
+      #
+      # @safety
+      #   Describe if the cop is safe to run automatically.
+      #
+      # @example Bad code
+      #   # bad - explain what's wrong
+      #   describe 'Something' do
+      #     # problematic code
+      #   end
+      #
+      # @example Good code
+      #   # good - explain why this is better
+      #   describe 'Something' do
+      #     # correct code
+      #   end
+      #
+      # @example Edge cases
+      #   # good - explain edge case
+      #   describe 'Something' do
+      #     # edge case example
+      #   end
+      #
+      class YourCopName < Base
+        MSG = "Your cop's message to the user"
+
+        # @!method pattern_to_match?(node)
+        def_node_matcher :pattern_to_match?, <<~PATTERN
+          (block
+            (send nil? :describe ...)
+            ...)
+        PATTERN
+
+        def on_block(node)
+          return unless pattern_to_match?(node)
+
+          # Your cop logic here
+          add_offense(node) if offense_detected?(node)
+        end
+
+        private
+
+        def offense_detected?(node)
+          # Your detection logic
+        end
+      end
+    end
+  end
+end
+```
+
+### 3. Key Components
+
+- **MSG**: The message shown to users when an offense is detected
+- **Node Matchers**: Use `def_node_matcher` to match AST patterns
+- **Callbacks**: Implement `on_block`, `on_send`, etc. to inspect nodes
+- **YARD Documentation**: Add comprehensive examples and explanations
+
+### 4. Register Your Cop
+
+Add your cop to `lib/rubocop-rspec-guide.rb`:
+
+```ruby
+require_relative "rubocop/cop/rspec_guide/your_cop_name"
+```
+
+### 5. Add Default Configuration
+
+Add your cop to `config/default.yml`:
+
+```yaml
+RSpecGuide/YourCopName:
+  Description: "Short description of your cop"
+  Enabled: true
+  VersionAdded: 'X.Y.Z'
+  StyleGuideUrl: "https://github.com/AlexeyMatskevich/rspec-guide"
+```
+
+## Writing Tests
+
+### Test File Location
+
+Create a test file in `spec/rubocop/cop/`:
+
+- For RSpec cops: `spec/rubocop/cop/rspec_guide/your_cop_name_spec.rb`
+- For FactoryBot cops: `spec/rubocop/cop/factory_bot_guide/your_cop_name_spec.rb`
+
+### Test Structure
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe RuboCop::Cop::RSpecGuide::YourCopName, :config do
+  let(:config) { RuboCop::Config.new }
+
+  context 'when code has offense' do
+    it 'registers an offense' do
+      expect_offense(<<~RUBY)
+        describe 'Something' do
+        ^^^^^^^^^^^^^^^^^^^^^^^ Your cop's message
+          # problematic code
+        end
+      RUBY
+    end
+  end
+
+  context 'when code is correct' do
+    it 'does not register an offense' do
+      expect_no_offenses(<<~RUBY)
+        describe 'Something' do
+          # correct code
+        end
+      RUBY
+    end
+  end
+
+  context 'with edge case' do
+    it 'does not register an offense' do
+      expect_no_offenses(<<~RUBY)
+        describe 'Something' do
+          # edge case code
+        end
+      RUBY
+    end
+  end
+end
+```
+
+### Testing Best Practices
+
+1. **Test both offenses and non-offenses**: Ensure your cop correctly identifies problems AND doesn't create false positives
+2. **Test edge cases**: Cover boundary conditions and unusual patterns
+3. **Test with configuration options**: If your cop has configuration options, test different settings
+4. **Use descriptive context names**: Make it clear what scenario each test covers
+5. **Follow the behavior-first pattern**: Describe WHAT behavior is being tested, not implementation details
+
+### Running Specific Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests for a specific cop
+bundle exec rspec spec/rubocop/cop/rspec_guide/your_cop_name_spec.rb
+
+# Run a specific test
+bundle exec rspec spec/rubocop/cop/rspec_guide/your_cop_name_spec.rb:10
+```
+
+## Code Style Guidelines
+
+This project follows standard RuboCop style guidelines:
+
+1. **Use 2 spaces for indentation** (no tabs)
+2. **Keep lines under 120 characters**
+3. **Use frozen string literals** (`# frozen_string_literal: true`)
+4. **Write descriptive variable names**
+5. **Add YARD documentation** for public methods and classes
+6. **Follow RuboCop's own style guide**
+
+Run `bundle exec rubocop` to check your code style.
+
+## Submitting Changes
+
+### Before Submitting
+
+1. **Run all tests**: `bundle exec rspec`
+2. **Run RuboCop**: `bundle exec rubocop`
+3. **Update CHANGELOG.md**: Add a note about your change under `[Unreleased]`
+4. **Update documentation**: If you added a new cop, update README.md
+
+### Pull Request Process
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes and commit**:
+   ```bash
+   git add .
+   git commit -m "Add YourCopName to detect X pattern"
+   ```
+
+3. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+4. **Open a Pull Request** on GitHub
+
+5. **PR Checklist**:
+   - [ ] Tests pass (`bundle exec rspec`)
+   - [ ] RuboCop passes (`bundle exec rubocop`)
+   - [ ] New cop has comprehensive YARD documentation (3+ examples)
+   - [ ] New cop has tests covering offenses, non-offenses, and edge cases
+   - [ ] CHANGELOG.md updated
+   - [ ] README.md updated (if adding new cop)
+   - [ ] config/default.yml updated (if adding new cop)
+
+### PR Title Format
+
+- **For new cops**: `Add RSpecGuide/YourCopName cop`
+- **For bug fixes**: `Fix RSpecGuide/YourCopName false positive on X`
+- **For improvements**: `Improve RSpecGuide/YourCopName to handle Y`
+- **For documentation**: `Update documentation for RSpecGuide/YourCopName`
+
+## Commit Message Guidelines
+
+Follow these conventions for commit messages:
+
+### Format
+
+```
+Short summary (50 chars or less)
+
+Detailed explanation if needed. Wrap at 72 characters.
+Explain WHAT changed and WHY, not HOW (code shows how).
+
+- Bullet points are okay
+- Use present tense: "Add feature" not "Added feature"
+- Reference issues: "Fixes #123" or "Closes #456"
+```
+
+### Examples
+
+**Good commit messages:**
+
+```
+Add MinimumBehavioralCoverage cop
+
+Checks that describe blocks test at least 2 behavioral variations.
+Supports both traditional (2+ contexts) and new (it-blocks + contexts)
+patterns.
+
+Closes #42
+```
+
+```
+Fix ContextSetup false positive on nested describes
+
+The cop was incorrectly flagging contexts inside nested describes
+when setup was present in the parent describe block.
+
+Fixes #89
+```
+
+**Bad commit messages:**
+
+```
+fix bug
+```
+
+```
+updated code
+```
+
+```
+WIP - will finish later
+```
+
+## Questions?
+
+If you have questions or need help:
+
+1. Check existing [Issues](https://github.com/AlexeyMatskevich/rubocop-rspec-guide/issues)
+2. Check existing [Pull Requests](https://github.com/AlexeyMatskevich/rubocop-rspec-guide/pulls)
+3. Open a new issue with the `question` label
+
+## Resources
+
+- [RuboCop Development Guide](https://docs.rubocop.org/rubocop/development.html)
+- [RuboCop AST Documentation](https://docs.rubocop.org/rubocop-ast/)
+- [RSpec Style Guide](https://github.com/AlexeyMatskevich/rspec-guide)
+- [Parser AST Explorer](https://ruby-ast-explorer.herokuapp.com/) - Visualize Ruby AST
+
+Thank you for contributing! 🎉