rubocop-vicenzo 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '094cfb18e36f28e2f311e80f435b1b5159f22875cfb8f13b5a0551ca9b5e9218'
-  data.tar.gz: b96a9634c956e7cec399e10a2f7f512a5f2894822ba07fecf7294a502fee56b5
+  metadata.gz: e5b813b05ed3c69c557d8b01bb90a4f142cbbb4ff06240d2df571f23ca5b720b
+  data.tar.gz: c121942b02a939b96de5a264fd53db21ebba6dd85e85c9e95424538e59c5240c
 SHA512:
-  metadata.gz: ba554984ec7092154352415043f2868cd59bd89015de29b0098e01c1f0b2016b8b3a837845cd22e8219e1115b37f4b6e80eb3d5861d0f3325c0ad2894466de23
-  data.tar.gz: 031a968654d68f7fa65e7a57a6178fc97651ae8c20cb4861f25a1f4c9feb5c6d044a3bc7e269e4de392a9a38483ce51296517f852abe61e88ba804ad723140b4
+  metadata.gz: 3d6832e1b1d8a011f1ded3b21451e79f1722234bd7424ccf418a59550a79b20edd4b8a3632345df748982b356b32d868d530fe96267ce5b81689f32d8e9559ae
+  data.tar.gz: b2513e3ab2f35243a88029d8f08ff2bd1bd29c08552c305e919cb76b10717e113cccf837276bc77b390bb87b5f34b276b08415adc1fd64c05566028107f65471

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.9.0"
 }

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: config/style.yml
+
 plugins:
   - rubocop-performance
   - rubocop-rake
@@ -5,39 +7,17 @@ plugins:
   - rubocop-vicenzo
   - rubocop-internal_affairs
 
-AllCops:
-  Exclude:
-    - 'bin/**/*'
-    - 'vendor/**/*'
-  NewCops: enable
-
 InternalAffairs/UndefinedConfig: # False positive because conflicts with Rubocop Layout namespace
   Exclude:
     - 'lib/rubocop/cop/vicenzo/layout/**/*'
 
-Metrics/BlockLength:
-  Exclude:
-    - 'rakelib/**/*'
-    - 'Rakefile'
-
 Naming/FileName:
   Exclude:
     - lib/rubocop-vicenzo.rb
 
-RSpec/ContextWording:
-  Prefixes:
-    - and
-    - but
-    - when
-    - with
-    - without
-
 RSpec/ExampleLength:
   Enabled: false
 
-RSpec/NestedGroups:
-  Enabled: false
-
 Vicenzo/RSpec/LeakyDefinition:
   Exclude:
     - 'spec/support/**/*'

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.9.0](https://github.com/bvicenzo/rubocop-vicenzo/compare/v0.8.0...v0.9.0) (2026-09-23)
+
+
+### Features
+
+* add Vicenzo/Naming/AnonymousUnusedName cop ([#33](https://github.com/bvicenzo/rubocop-vicenzo/issues/33)) ([fabbad6](https://github.com/bvicenzo/rubocop-vicenzo/commit/fabbad655dac0c362924dd0aaf245abd2c7023e1))
+* add Vicenzo/Naming/ShortName cop and an opinionated config/style.yml ([#35](https://github.com/bvicenzo/rubocop-vicenzo/issues/35)) ([1b67f46](https://github.com/bvicenzo/rubocop-vicenzo/commit/1b67f4643b4348f5768a8fbb3b88cea35046e5e2))
+* add Vicenzo/RSpec/DescribeInsideContext cop ([#37](https://github.com/bvicenzo/rubocop-vicenzo/issues/37)) ([3f3d6ae](https://github.com/bvicenzo/rubocop-vicenzo/commit/3f3d6aeb95d087e32594e8ded3d1ce0e3715dee7))
+* add Vicenzo/RSpec/UnnestedContextImproperStart cop ([#36](https://github.com/bvicenzo/rubocop-vicenzo/issues/36)) ([0a8fb0f](https://github.com/bvicenzo/rubocop-vicenzo/commit/0a8fb0fec62370ac331b9a3275b95a0b22998b1d))
+
 ## [0.8.0](https://github.com/bvicenzo/rubocop-vicenzo/compare/v0.7.0...v0.8.0) (2026-09-09)
 
 

data/README.md

@@ -11,7 +11,7 @@ Add it to the `development`/`test` group of your `Gemfile`:
 <!-- x-release-please-start-version -->
 ```ruby
 group :development, :test do
-  gem 'rubocop-vicenzo', '~> 0.8.0', require: false
+  gem 'rubocop-vicenzo', '~> 0.9.0', require: false
 end
 ```
 <!-- x-release-please-end-version -->
@@ -64,6 +64,31 @@ cops together with the standard cops.
 rubocop --plugin rubocop-vicenzo
 ```
 
+## Opinionated style guide
+
+Loading the plugin gives you the `Vicenzo/*` cops and nothing else: their defaults
+live in `config/default.yml` and are applied automatically.
+
+The gem also ships `config/style.yml`, an opinionated configuration of the cops the
+`Vicenzo/*` ones build on — line length, multiline layout, metrics, and the naming
+rules that back `Vicenzo/Naming/ShortName` (notably `Naming/BlockParameterName`,
+which RuboCop ships with `MinNameLength: 1` and which therefore never fires). It is
+**opt-in**:
+
+```yaml
+inherit_gem:
+  rubocop-vicenzo: config/style.yml
+```
+
+That single line brings the configuration **and** the plugins it builds on
+(`rubocop-rspec` and this gem's own cops), so there is no `plugins:` key left for you
+to write.
+
+> [!NOTE]
+> `AllCops: CacheRootDirectory` is not inheritable. RuboCop reads it from the
+> top-level config file before resolving `inherit_from`/`inherit_gem`, so it has to
+> stay in your own `.rubocop.yml`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -4,8 +4,8 @@ require 'bundler/setup'
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = '--format progress'
+RSpec::Core::RakeTask.new(:spec) do |rspec_task|
+  rspec_task.rspec_opts = '--format progress'
 end
 
 require 'rubocop/rake_task'

data/config/default.yml

@@ -5,6 +5,19 @@ Vicenzo/Layout/MultilineMethodCallLineBreaks:
   IndentationWidth: 2
   VersionAdded: '0.3.0'
 
+Vicenzo/Naming/AnonymousUnusedName:
+  Description: 'An unused declaration must not be anonymous; name it after what it stands for.'
+  Enabled: true
+  Severity: convention
+  VersionAdded: '0.9.0'
+
+Vicenzo/Naming/ShortName:
+  Description: 'A name too short to carry meaning; spell out whole words from the domain.'
+  Enabled: true
+  Severity: convention
+  MinNameLength: 3
+  VersionAdded: '0.9.0'
+
 Vicenzo/Rails/EnumInclusionOfValidation:
   Description: 'Check if the enum has the inclusion of validation defined.'
   Enabled: true
@@ -45,6 +58,17 @@ Vicenzo/RSpec/DerivedPremises:
     - '**/spec/factories/**/*'
   VersionAdded: '0.6.0'
 
+Vicenzo/RSpec/DescribeInsideContext:
+  Description: 'A describe must not be nested in a context, which is a scenario of the behaviour a describe names.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.9.0'
+
 Vicenzo/RSpec/DynamicExampleGeneration:
   Description: 'Do not use iteration to dynamically generate example groups or examples.'
   Enabled: true
@@ -194,6 +218,21 @@ Vicenzo/RSpec/TopLevelSubject:
     - '**/spec/factories/**/*'
   VersionAdded: '0.8.0'
 
+Vicenzo/RSpec/UnnestedContextImproperStart:
+  Description: 'Check if a context with no parent scenario starts with a conjunction.'
+  Enabled: true
+  Severity: convention
+  ForbiddenPrefixes:
+    - and
+    - but
+    - however
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.9.0'
+
 Vicenzo/Style/JsonParseSymbolizeNames:
   Description: 'Enforces passing `symbolize_names: true` to `JSON.parse` so keys are symbols.'
   Enabled: true

data/config/style.yml

@@ -0,0 +1,228 @@
+plugins:
+  - rubocop-vicenzo
+  - rubocop-rspec
+
+AllCops:
+  SuggestExtensions: false
+  NewCops: enable
+  Exclude:
+    - 'node_modules/**/*'
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - '.git/**/*'
+    - 'db/**/*'
+
+##### LAYOUT #####
+
+Layout/ArgumentAlignment:
+  Enabled: true
+  EnforcedStyle: with_fixed_indentation
+
+Layout/CaseIndentation:
+  Enabled: true
+  EnforcedStyle: end
+
+Layout/EndAlignment:
+  Enabled: true
+  EnforcedStyleAlignWith: variable
+
+Layout/FirstArgumentIndentation:
+  Enabled: true
+  EnforcedStyle: consistent
+
+Layout/FirstArrayElementIndentation:
+  Enabled: true
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  Enabled: true
+  EnforcedStyle: consistent
+
+Layout/FirstMethodArgumentLineBreak:
+  Enabled: true
+
+Layout/LineLength:
+  Max: 120
+  # (\A|\s)   -> Start of line or whitespace
+  # #         -> The hash character
+  # (?!\{)    -> Negative lookahead: NOT followed by `{` (prevents matching interpolation)
+  AllowedPatterns: ['(\A|\s)#(?!\{)']
+
+Layout/MultilineMethodArgumentLineBreaks:
+  Enabled: true
+
+Layout/MultilineMethodCallBraceLayout:
+  Enabled: true
+  EnforcedStyle: new_line
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+
+Layout/FirstArrayElementLineBreak:
+  Enabled: true
+
+Layout/MultilineArrayLineBreaks:
+  Enabled: true
+
+Layout/MultilineArrayBraceLayout:
+  Enabled: true
+  EnforcedStyle: new_line
+
+Layout/FirstHashElementLineBreak:
+  Enabled: true
+
+Layout/MultilineHashKeyLineBreaks:
+  Enabled: true
+
+Layout/MultilineHashBraceLayout:
+  Enabled: true
+  EnforcedStyle: new_line
+
+##### STYLE #####
+
+Style/PreferredHashMethods:
+  Enabled: true
+  Safe: false
+  EnforcedStyle: verbose
+
+Style/SymbolArray:
+  Enabled: true
+  EnforcedStyle: percent
+  MinSize: 3
+
+Style/WordArray:
+  Enabled: true
+  EnforcedStyle: percent
+  MinSize: 3
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: true
+  EnforcedStyle: literal
+
+Style/LambdaCall:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+##### LINT #####
+
+Lint/MissingSuper:
+  Enabled: false
+
+##### NAMING #####
+
+Naming/InclusiveLanguage:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  ForbiddenPrefixes:
+    - is_
+    - have_
+    # allows `has_` predicate
+
+# A single letter says nothing about what was rescued.
+Naming/RescuedExceptionsVariableName:
+  Enabled: true
+  PreferredName: error
+
+# Vicenzo/Naming/ShortName covers local variables. Block parameters are the core
+# cop's job, but it ships with MinNameLength: 1 and therefore never fires — raise
+# it so both halves of the rule agree.
+Naming/BlockParameterName:
+  MinNameLength: 3
+
+###### METRICS #####
+
+Metrics/AbcSize:
+  Enabled: true
+  Max: 22
+
+Metrics/BlockLength:
+  Enabled: true
+  CountComments: false
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - 'describe'
+    - 'context'
+    - 'it'
+    - 'let'
+    - 'subject'
+    - 'namespace'
+    - 'task'
+    - 'configure'
+  Exclude:
+    - '**/*.gemspec'
+    - 'Rakefile'
+    - 'rakelib/**/*'
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Enabled: true
+  Max: 200
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+
+Metrics/MethodLength:
+  Enabled: true
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  Max: 20
+
+Metrics/ModuleLength:
+  Enabled: true
+  Max: 200
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+
+##### RSPEC #####
+
+RSpec/ContextWording:
+  Prefixes:
+    - and
+    - but
+    - when
+    - with
+    - without
+
+RSpec/ExampleLength:
+  Max: 20
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/PredicateMatcher:
+  Strict: false
+
+##### VICENZO #####
+
+Vicenzo/Style/MultilineMethodCallParentheses:
+  AllowedMethods:
+    - to
+    - not_to
+    - to_not

data/lib/rubocop/cop/vicenzo/naming/anonymous_unused_name.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module Naming
+        # Requires every declaration to carry a name, even when the value it
+        # holds is not used.
+        #
+        # A bare `_` states that a value is being ignored, but erases what that
+        # value is. Unused today does not mean unusable tomorrow: when the code
+        # grows, nobody reading the signature can tell whether the discarded
+        # value is the one the new problem needs.
+        #
+        # The cop only demands that a name exists — it cannot judge whether a
+        # name is a good one. That is the author's call, and the offense message
+        # asks for a name taken from the domain (`_previous_owner`) rather than
+        # one taken from the shape of the value (`_value`, `_key`, `_item`).
+        #
+        # Anonymous forwarding parameters (`*`, `**`, `&`, `...`) are ignored:
+        # they forward arguments instead of discarding them, and `Style/ArgumentsForwarding`
+        # actively pushes code towards that form.
+        #
+        # @example block parameters
+        #   # bad
+        #   catalog.each { |_, copies| copies.each(&:reserve) }
+        #
+        #   # good
+        #   catalog.each { |_isbn, copies| copies.each(&:reserve) }
+        #
+        # @example destructured block parameters
+        #   # bad
+        #   entries.each { |(_, id)| track(id) }
+        #
+        #   # good
+        #   entries.each { |(_label, id)| track(id) }
+        #
+        # @example method parameters
+        #   # bad
+        #   def notify(reader, _)
+        #     reader.deliver
+        #   end
+        #
+        #   # good
+        #   def notify(reader, _delivery_channel)
+        #     reader.deliver
+        #   end
+        #
+        # @example multiple assignment
+        #   # bad
+        #   title, _ = line.split(';')
+        #
+        #   # good
+        #   title, _author = line.split(';')
+        #
+        # @example rescued errors
+        #   # bad
+        #   begin
+        #     shelf.reorder
+        #   rescue ShelfLocked => _
+        #     shelf.skip
+        #   end
+        #
+        #   # good
+        #   begin
+        #     shelf.reorder
+        #   rescue ShelfLocked => _lock_conflict
+        #     shelf.skip
+        #   end
+        #
+        # @example anonymous forwarding (ignored)
+        #   # good
+        #   def notify(*)
+        #     channel.deliver(*)
+        #   end
+        #
+        #   # good
+        #   def notify(...)
+        #     channel.deliver(...)
+        #   end
+        class AnonymousUnusedName < Base
+          MSG = 'Name this %<subject>s: an unused value still means something, and `_` hides what. ' \
+                'Name it after what it stands for in the domain (`_previous_owner`), not after its ' \
+                'shape (`_value`, `_key`, `_item`) — that tells the next reader nothing.'
+
+          BLOCK_PARAMETER  = 'block parameter'
+          METHOD_PARAMETER = 'method parameter'
+          DISCARDED_VALUE  = 'discarded value'
+          RESCUED_ERROR    = 'rescued error'
+
+          ANONYMOUS_NAME_PATTERN = /\A_+\z/
+
+          NAMED_ARGUMENT_TYPES = %i[arg optarg restarg kwarg kwoptarg kwrestarg blockarg shadowarg].freeze
+          DEFAULT_VALUE_ARGUMENT_TYPES = %i[optarg kwoptarg].freeze
+
+          # Numbered (`_1`) and implicit (`it`) block parameters are never
+          # declared, so they carry no name to check — both node types answer
+          # `arguments` with an empty list.
+          def on_block(node)
+            check_arguments(node.arguments, BLOCK_PARAMETER)
+          end
+          alias on_numblock on_block
+          alias on_itblock on_block
+
+          def on_def(node)
+            check_arguments(node.arguments, METHOD_PARAMETER)
+          end
+          alias on_defs on_def
+
+          def on_masgn(node)
+            node.lhs.assignments.each do |assignment|
+              next unless assignment.respond_to?(:lvasgn_type?) && assignment.lvasgn_type?
+
+              register_offense(assignment, DISCARDED_VALUE) if anonymous_name?(assignment.children.first)
+            end
+          end
+
+          def on_resbody(node)
+            error = node.exception_variable
+            return if error.nil?
+
+            register_offense(error, RESCUED_ERROR) if anonymous_name?(error.children.first)
+          end
+
+          private
+
+          def check_arguments(arguments, subject)
+            arguments.each do |argument|
+              if argument.mlhs_type?
+                check_arguments(argument.children, subject)
+              elsif anonymous_argument?(argument)
+                register_offense(argument_range(argument), subject)
+              end
+            end
+          end
+
+          # An anonymous forwarding parameter (`*`, `**`, `&`) carries no name
+          # child at all, and `...` is a `forward_arg`, outside the listed types.
+          # Both fall through as allowed.
+          def anonymous_argument?(argument)
+            NAMED_ARGUMENT_TYPES.include?(argument.type) && anonymous_name?(argument.children.first)
+          end
+
+          # An argument carrying a default value spans the whole expression, so
+          # only its name is highlighted; every other form is short enough that
+          # showing it whole (`*_`, `**_`, `&_`) tells the reader more.
+          def argument_range(argument)
+            return argument.loc.name if DEFAULT_VALUE_ARGUMENT_TYPES.include?(argument.type)
+
+            argument.source_range
+          end
+
+          def anonymous_name?(name)
+            !name.nil? && ANONYMOUS_NAME_PATTERN.match?(name.to_s)
+          end
+
+          def register_offense(node, subject)
+            add_offense(node, message: format(MSG, subject: subject))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/naming/short_name.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module Naming
+        # Checks local variable names for how many letters they actually spell.
+        #
+        # A single letter or a two-letter abbreviation almost never carries the
+        # business meaning of the value it holds. `p`, `w`, `v`, `i` say nothing,
+        # and `_p` is still a single letter with an underscore in front of it.
+        #
+        # Underscores do not count towards the length, so `a_b` spells two
+        # letters, not three. The cop does not judge which name is a good one —
+        # it only measures how much was written down; whether the name belongs to
+        # the domain is the author's call, and the message asks for it.
+        #
+        # Block and method parameters are left to `Naming/BlockParameterName` and
+        # `Naming/MethodParameterName`; this gem's `config/style.yml` raises the
+        # former to the same minimum. Rescued errors are left to
+        # `Naming/RescuedExceptionsVariableName`, and names made only of
+        # underscores belong to `Vicenzo/Naming/AnonymousUnusedName`.
+        #
+        # A short name that exists only to feed a keyword argument shorthand is
+        # allowed: the name was imposed by the signature that receives it, not
+        # chosen, and it is that signature the parameter cops point at. The fix
+        # cascades from there.
+        #
+        # @example
+        #   # bad
+        #   v = shelf.capacity
+        #
+        #   # good
+        #   volume = shelf.capacity
+        #
+        # @example multiple assignment
+        #   # bad
+        #   x, y = coordinates
+        #
+        #   # good
+        #   column, row = coordinates
+        #
+        # @example underscores do not count as letters
+        #   # bad
+        #   a_b = shelf.capacity
+        #
+        #   # good
+        #   available_books = shelf.capacity
+        #
+        # @example an unused name is still a name
+        #   # bad
+        #   _p = catalog.first
+        #
+        #   # good
+        #   _publisher = catalog.first
+        #
+        # @example keyword argument shorthand (allowed)
+        #   # good
+        #   height = 10
+        #   width = 15
+        #   area(height:, width:)
+        #
+        #   # good — `h` and `w` are imposed by the signature of `area`
+        #   h = 10
+        #   w = 15
+        #   area(h:, w:)
+        #
+        # @example MinNameLength: 5
+        #   # bad
+        #   book = build
+        #
+        #   # good
+        #   book_title = build
+        class ShortName < Base
+          MSG = 'Name `%<name>s` spells %<length>d letter(s); at least %<minimum>d are required. ' \
+                'A letter or an abbreviation carries no meaning to the next reader — write the ' \
+                'whole word, in the language of the domain (`waiting_time`), not a shapeless ' \
+                'label (`key`, `value`, `item`).'
+
+          DEFAULT_MIN_NAME_LENGTH = 3
+
+          ANONYMOUS_NAME_PATTERN = /\A_+\z/
+
+          SCOPE_TYPES = %i[def defs block numblock itblock].freeze
+
+          def on_lvasgn(node)
+            name = node.children.first
+            return if anonymous?(name) || rescued_error?(node) || forwarded_by_shorthand?(node, name)
+
+            length = spelled_length(name)
+            return if length >= min_name_length
+
+            add_offense(node.loc.name, message: format(MSG, name: name, length: length, minimum: min_name_length))
+          end
+
+          private
+
+          # Underscores separate words, they do not spell any, so they are not
+          # counted: `a_b` is two letters long.
+          def spelled_length(name)
+            name.to_s.delete('_').length
+          end
+
+          def anonymous?(name)
+            ANONYMOUS_NAME_PATTERN.match?(name.to_s)
+          end
+
+          def rescued_error?(node)
+            parent = node.parent
+            parent&.resbody_type? && parent.exception_variable == node
+          end
+
+          # `area(h:)` omits the value, so `h` is the name the receiving signature
+          # asks for. Looking within the enclosing scope keeps unrelated calls
+          # elsewhere in the file from excusing the name.
+          def forwarded_by_shorthand?(node, name)
+            enclosing_scope(node)
+              .each_node(:pair)
+              .any? { |pair| pair.value_omission? && pair.key.value == name }
+          end
+
+          def enclosing_scope(node)
+            node.each_ancestor(*SCOPE_TYPES).first || processed_source.ast
+          end
+
+          def min_name_length
+            cop_config.fetch('MinNameLength', DEFAULT_MIN_NAME_LENGTH)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/describe_inside_context.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A describe nested in a context names a behaviour after the scenario was already set. Describe the
+        # behaviour first, and put the scenario inside it.
+        #
+        # The tree answers three questions, in this order: `describe` - what is being described;
+        # `context` - under which circumstances; `it` - with which outcome. A context only means something
+        # as a scenario of a behaviour, so a describe below it turns the question upside down.
+        #
+        # It usually comes from wanting to write a scenario once for two behaviours. Repeat the context
+        # under each describe that needs it instead: each behaviour then reads on its own. Do not reach for
+        # a `shared_context` to avoid the repetition - it becomes a single place every caller leans on,
+        # conditionals creep in to serve each of them, and years later nobody knows why they are there.
+        #
+        # When the describe states a circumstance rather than a behaviour, it is a context written with the
+        # wrong keyword.
+        #
+        # @example
+        #   # bad - the scenario is set before the behaviours it belongs to
+        #   RSpec.describe Person do
+        #     context 'when the person is a minor' do
+        #       subject(:person) { described_class.new(age: 17) }
+        #
+        #       describe '#adult?' do
+        #         it { is_expected.not_to be_adult }
+        #       end
+        #
+        #       describe '#voter?' do
+        #         it { is_expected.not_to be_voter }
+        #       end
+        #     end
+        #   end
+        #
+        #   # good - each behaviour carries its own scenario
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       context 'when the person is a minor' do
+        #         subject(:person) { described_class.new(age: 17) }
+        #
+        #         it { is_expected.not_to be_adult }
+        #       end
+        #     end
+        #
+        #     describe '#voter?' do
+        #       context 'when the person is a minor' do
+        #         subject(:person) { described_class.new(age: 17) }
+        #
+        #         it { is_expected.not_to be_voter }
+        #       end
+        #     end
+        #   end
+        class DescribeInsideContext < RuboCop::Cop::RSpec::Base
+          MSG = 'Do not describe inside a context: a context is a scenario of the behaviour a describe names. ' \
+                'Describe the behaviour first and repeat the context under each describe that needs it. ' \
+                'If this block states a circumstance, it is a context.'
+
+          # Only the groups that name a behaviour. Aliases a project adds to the RSpec language, such as
+          # rswag's `response`, are left out: they do not describe anything.
+          DESCRIBES = %i[describe fdescribe xdescribe feature ffeature xfeature example_group].freeze
+          CONTEXTS = %i[context fcontext xcontext].freeze
+
+          # @!method describe_definition?(node)
+          def_node_matcher :describe_definition?, <<~PATTERN
+            (any_block (send #rspec? {#{DESCRIBES.map(&:inspect).join(' ')}} ...) ...)
+          PATTERN
+
+          # @!method context_definition?(node)
+          def_node_matcher :context_definition?, <<~PATTERN
+            (any_block (send nil? {#{CONTEXTS.map(&:inspect).join(' ')}} ...) ...)
+          PATTERN
+
+          def on_block(node)
+            add_offense(node.send_node) if describe_definition?(node) && inside_a_context?(node)
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          # A shared group's scenario lives where it is included, so it cannot be judged here.
+          def inside_a_context?(node)
+            parent = node.each_ancestor(:any_block).find { |ancestor| spec_group?(ancestor) }
+
+            parent && context_definition?(parent)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/dynamic_example_generation.rb

@@ -46,10 +46,25 @@ module RuboCop
           ENUMERATION_METHODS = %i[each each_with_index each_with_object map flat_map].freeze
 
           EXAMPLE_GROUP_DSL = %i[
-            context describe feature experiment
-            it specify example scenario focus
-            let let! subject subject! before after around
-            shared_examples shared_context shared_examples_for
+            context
+            describe
+            feature
+            experiment
+            it
+            specify
+            example
+            scenario
+            focus
+            let
+            let!
+            subject
+            subject!
+            before
+            after
+            around
+            shared_examples
+            shared_context
+            shared_examples_for
           ].freeze
 
           # @!method enumeration_block?(node)

data/lib/rubocop/cop/vicenzo/rspec/mutated_premises.rb

@@ -76,8 +76,19 @@ module RuboCop
                             'trait/transient, or declare the final state in the context that needs it.'
 
           PERSISTENCE_METHODS = %i[
-            update update! update_attribute update_column update_columns save save! destroy destroy! touch
-            increment! decrement! toggle!
+            update
+            update!
+            update_attribute
+            update_column
+            update_columns
+            save
+            save!
+            destroy
+            destroy!
+            touch
+            increment!
+            decrement!
+            toggle!
           ].freeze
 
           COLLECTION_METHODS = %i[<< push concat unshift store merge! deep_merge! clear delete].freeze

data/lib/rubocop/cop/vicenzo/rspec/nested_let_redefinition.rb

@@ -92,7 +92,7 @@ module RuboCop
           def check_let(let_node, let_definitions)
             name = (let_name(let_node) || let_it_be_name(let_node))&.to_s&.to_sym
 
-            if let_definitions.key?(name)
+            if let_definitions.has_key?(name)
               add_offense(let_node, message: redefined_let_message(name, let_definitions))
 
               let_definitions[name] += [line_location(let_node)]

data/lib/rubocop/cop/vicenzo/rspec/nested_subject_redefinition.rb

@@ -94,7 +94,7 @@ module RuboCop
           def check_subject(subject_node, subject_definitions)
             name = name_for(subject_node)
 
-            if subject_definitions.key?(name)
+            if subject_definitions.has_key?(name)
               add_offense(subject_node, message: redefined_subject_message(name, subject_definitions))
               subject_definitions[name] += [line_location(subject_node)]
             else

data/lib/rubocop/cop/vicenzo/rspec/unnested_context_improper_start.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Checks for `context` blocks with no parent scenario that start with "and", "but", or "however".
+        # It suggests starting them with "when", "with", or "without" instead.
+        #
+        # A conjunction continues the scenario of the enclosing context. When the closest example group is
+        # not a context - a `describe`, or no group at all - there is no scenario to continue, and the
+        # description reads as a fragment. It usually shows up after a subtree is moved up a level: the
+        # parent goes away, the titles stay as they were.
+        #
+        # The closest example group decides. A shared group is left alone, since the scenario it continues
+        # lives where it is included.
+        #
+        # The words that continue a scenario come from `ForbiddenPrefixes`, compared against the first word
+        # of the description, ignoring case. Setting it replaces the defaults; to add words to them, declare
+        # `inherit_mode: { merge: [ForbiddenPrefixes] }` for the cop.
+        #
+        # @example
+        #   # bad
+        #   describe '#available_colors' do
+        #     context 'but the color pink is not available' do
+        #       it 'does not show the pink option'
+        #     end
+        #   end
+        #
+        #   # good
+        #   describe '#available_colors' do
+        #     context 'when the color pink is not available' do
+        #       it 'does not show the pink option'
+        #     end
+        #   end
+        #
+        # @example ForbiddenPrefixes: ['and', 'but', 'however', 'also']
+        #   # bad
+        #   describe '#available_colors' do
+        #     context 'also when the color pink is not available' do
+        #       it 'does not show the pink option'
+        #     end
+        #   end
+        class UnnestedContextImproperStart < RuboCop::Cop::RSpec::Base
+          MSG = 'Unnested `context` should start with `when`, `with`, or `without`, not `%<prefix>s`.'
+
+          CONTEXTS = %i[context fcontext xcontext].freeze
+          DEFAULT_FORBIDDEN_PREFIXES = %w[and but however].freeze
+
+          # @!method context_definition?(node)
+          def_node_matcher :context_definition?, <<~PATTERN
+            (any_block (send nil? {#{CONTEXTS.map(&:inspect).join(' ')}} ...) ...)
+          PATTERN
+
+          def on_block(node)
+            return unless context_definition?(node)
+            return if continues_a_scenario?(node)
+
+            prefix = first_word(node)
+
+            add_offense(node.send_node, message: format(MSG, prefix:)) if forbidden_prefixes.include?(prefix)
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          # A context continues its scenario, and a shared group's scenario lives where it is included, so
+          # neither can be judged here.
+          def continues_a_scenario?(node)
+            parent = node.each_ancestor(:any_block).find { |ancestor| spec_group?(ancestor) }
+
+            parent && (shared_group?(parent) || context_definition?(parent))
+          end
+
+          def first_word(node)
+            description = node.send_node.first_argument
+
+            description.value.lstrip[/\A[[:alpha:]]+/]&.downcase if description&.str_type?
+          end
+
+          def forbidden_prefixes
+            cop_config.fetch('ForbiddenPrefixes', DEFAULT_FORBIDDEN_PREFIXES).map(&:downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo_cops.rb

@@ -3,6 +3,7 @@
 require_relative 'vicenzo/rspec/competing_subjects'
 require_relative 'vicenzo/rspec/conditional_in_spec'
 require_relative 'vicenzo/rspec/derived_premises'
+require_relative 'vicenzo/rspec/describe_inside_context'
 require_relative 'vicenzo/rspec/dynamic_example_generation'
 require_relative 'vicenzo/rspec/inconsistent_sibling_structure'
 require_relative 'vicenzo/rspec/iteration_inside_example'
@@ -19,7 +20,10 @@ require_relative 'vicenzo/rspec/top_level_example'
 require_relative 'vicenzo/rspec/top_level_hook'
 require_relative 'vicenzo/rspec/top_level_let'
 require_relative 'vicenzo/rspec/top_level_subject'
+require_relative 'vicenzo/rspec/unnested_context_improper_start'
 require_relative 'vicenzo/rails/enum_inclusion_of_validation'
 require_relative 'vicenzo/layout/multiline_method_call_line_breaks'
+require_relative 'vicenzo/naming/anonymous_unused_name'
+require_relative 'vicenzo/naming/short_name'
 require_relative 'vicenzo/style/json_parse_symbolize_names'
 require_relative 'vicenzo/style/multiline_method_call_parentheses'

data/lib/rubocop/vicenzo/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Vicenzo
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/rakelib/docs.rake

@@ -155,16 +155,26 @@ end
 def render_metadata_table(cop)
   enabled     = cop[:enabled] ? 'Enabled' : 'Disabled'
   autocorrect = cop[:autocorrect] ? 'Yes' : 'No'
-  ['[cols="1,1,1,1"]', '|===', '| Enabled by default | Safe | Supports autocorrection | Version Added',
-   '', "| #{enabled}", '| Yes', "| #{autocorrect}", "| #{cop[:version]}", '|===', '']
+  [
+    '[cols="1,1,1,1"]',
+    '|===',
+    '| Enabled by default | Safe | Supports autocorrection | Version Added',
+    '',
+    "| #{enabled}",
+    '| Yes',
+    "| #{autocorrect}",
+    "| #{cop[:version]}",
+    '|===',
+    ''
+  ]
 end
 
 def render_example(example, index)
   title = if example[:title].empty?
-            index.zero? ? 'Example' : "Example #{index + 1}"
-          else
-            example[:title]
-          end
+    index.zero? ? 'Example' : "Example #{index + 1}"
+  else
+    example[:title]
+  end
   ["=== #{title}", '', '[source,ruby]', '----', *example[:code], '----', '']
 end
 
@@ -198,13 +208,28 @@ def installation_section_lines
 end
 
 def gemfile_installation_lines
-  ['Add to your `Gemfile`:', '', '[source,ruby]', '----',
-   "gem 'rubocop-vicenzo', require: false", '----', '']
+  [
+    'Add to your `Gemfile`:',
+    '',
+    '[source,ruby]',
+    '----',
+    "gem 'rubocop-vicenzo', require: false",
+    '----',
+    ''
+  ]
 end
 
 def rubocop_yml_installation_lines
-  ['Then add to your `.rubocop.yml`:', '', '[source,yaml]', '----',
-   'plugins:', '  - rubocop-vicenzo', '----', '']
+  [
+    'Then add to your `.rubocop.yml`:',
+    '',
+    '[source,yaml]',
+    '----',
+    'plugins:',
+    '  - rubocop-vicenzo',
+    '----',
+    ''
+  ]
 end
 
 def index_cops_table_lines(cop_data)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-vicenzo
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Bruno Vicenzo
@@ -70,14 +70,18 @@ files:
 - Rakefile
 - antora-playbook.yml
 - config/default.yml
+- config/style.yml
 - docs/antora.yml
 - docs/supplemental-ui/partials/header-content.hbs
 - lib/rubocop-vicenzo.rb
 - lib/rubocop/cop/vicenzo/layout/multiline_method_call_line_breaks.rb
+- lib/rubocop/cop/vicenzo/naming/anonymous_unused_name.rb
+- lib/rubocop/cop/vicenzo/naming/short_name.rb
 - lib/rubocop/cop/vicenzo/rails/enum_inclusion_of_validation.rb
 - lib/rubocop/cop/vicenzo/rspec/competing_subjects.rb
 - lib/rubocop/cop/vicenzo/rspec/conditional_in_spec.rb
 - lib/rubocop/cop/vicenzo/rspec/derived_premises.rb
+- lib/rubocop/cop/vicenzo/rspec/describe_inside_context.rb
 - lib/rubocop/cop/vicenzo/rspec/dynamic_example_generation.rb
 - lib/rubocop/cop/vicenzo/rspec/inconsistent_sibling_structure.rb
 - lib/rubocop/cop/vicenzo/rspec/iteration_inside_example.rb
@@ -98,6 +102,7 @@ files:
 - lib/rubocop/cop/vicenzo/rspec/top_level_hook.rb
 - lib/rubocop/cop/vicenzo/rspec/top_level_let.rb
 - lib/rubocop/cop/vicenzo/rspec/top_level_subject.rb
+- lib/rubocop/cop/vicenzo/rspec/unnested_context_improper_start.rb
 - lib/rubocop/cop/vicenzo/style/json_parse_symbolize_names.rb
 - lib/rubocop/cop/vicenzo/style/multiline_method_call_parentheses.rb
 - lib/rubocop/cop/vicenzo_cops.rb
@@ -131,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Cops of Bruno Vicenzo
 test_files: []