Add new RSpec/IncludeExamples cop to prefer it_behaves_like over include_examples

[dvandersluis]

Add cop to enforce using it_behaves_like over include_examples due to the potential footguns from include_examples. Users can disable this cop if they want to use include_examples.

Follows #2065 (comment) action item 2.

---

Before submitting the PR make sure the following are checked:

• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Updated documentation.
• Added an entry to the CHANGELOG.md if the new code introduces user-observable changes.
• The build (bundle exec rake) passes (be sure to run this locally, since it may produce updated documentation that you will need to commit).

If you have created a new cop:

• Added the new cop to config/default.yml.
• The cop is configured as Enabled: pending in config/default.yml.
• The cop is configured as Enabled: true in .rubocop.yml.
• The cop documents examples of good and bad code.
• The tests assert both that bad code is reported and that good code is not reported.
• Set VersionAdded: "<<next>>" in default/config.yml.

If you have modified an existing cop's configuration options:

• Set VersionChanged: "<<next>>" in config/default.yml.

[pirj]

Thank you! 🤩

I was unaware that we use include_examples so extensively in our specs.

[Copilot]

Pull Request Overview

This PR introduces a new RSpec cop, RSpec/IncludeExamples, which enforces the use of it_behaves_like over include_examples to help prevent potential pitfalls when shared examples create unintended side effects. Key changes include replacing include_examples with it_behaves_like in the tests, adding a new cop implementation in lib, and updating configuration and documentation.

Reviewed Changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
spec/rubocop/rspec/hook_spec.rb	Replaces include_examples with it_behaves_like in hook tests.
spec/rubocop/cop/rspec/subject_declaration_spec.rb	Replaces include_examples with it_behaves_like in subject declaration tests.
spec/rubocop/cop/rspec/predicate_matcher_spec.rb	Replaces include_examples with it_behaves_like in predicate matcher tests.
spec/rubocop/cop/rspec/message_spies_spec.rb	Replaces include_examples with it_behaves_like in message spy tests.
spec/rubocop/cop/rspec/message_expectation_spec.rb	Replaces include_examples with it_behaves_like in message expectation tests.
spec/rubocop/cop/rspec/include_examples_spec.rb	Adds tests for the new RSpec/IncludeExamples cop.
spec/rubocop/cop/rspec/implicit_expect_spec.rb	Replaces include_examples with it_behaves_like in implicit expect tests.
spec/rubocop/cop/rspec/hook_argument_spec.rb	Replaces include_examples with it_behaves_like in hook argument tests.
spec/rubocop/cop/rspec/empty_line_after_hook_spec.rb	Replaces include_examples with it_behaves_like in empty line hook tests.
spec/rubocop/cop/rspec/base_spec.rb	Replaces include_examples with it_behaves_like in base tests.
lib/rubocop/cop/rspec_cops.rb	Updates requires to load the new RSpec/IncludeExamples cop.
lib/rubocop/cop/rspec/include_examples.rb	Implements the new cop enforcing it_behaves_like over include_examples.
config/default.yml	Adds default configuration for the new cop with pending status.
CHANGELOG.md	Updates changelog with an entry for the new RSpec/IncludeExamples cop.
.rubocop.yml	Enables the RSpec/IncludeExamples cop.

Files not reviewed (2)

• docs/modules/ROOT/pages/cops.adoc: Language not supported
• docs/modules/ROOT/pages/cops_rspec.adoc: Language not supported

[bquorning]

Learning from the fate of #2065, could we have use RSpec/Dialect instead of adding this new cop too?

[pirj]

Good point.
But would it be semantically correct? include_examples is not exactly just an alias.
Also, having Dialect default config for this substitution would not reveal the problem with include_examples.
I don’t have a strong opinion either way.