kaizo 0.8.0 → 0.9.2

data/config/default.yml

@@ -12,24 +12,50 @@
 # syntax or by the value object's members, not by a modeling choice. The defaults
 # are deliberately strict -- at most one positional and one keyword argument -- to
 # apply maximum pressure; loosen them if that is too aggressive for your codebase.
+# Exempt individual methods by name (`AllowedMethods`, e.g. `initialize`) or by
+# regexp (`AllowedPatterns`).
+#
+# The keyword-counting cops (`KeywordArguments`, `TotalArguments`) skip `spec/`
+# and `test/` trees: wide keyword interfaces are the testing idiom there
+# (FactoryBot-style `create`/`build` helpers), and the total bound would
+# re-police the keywords the exemption frees. `PositionalArguments` runs
+# everywhere -- positional arguments communicate nothing unless they are solo.
 Kaizo/KeywordArguments:
   Description: 'Checks that a method does not declare too many keyword arguments.'
   Enabled: true
   VersionAdded: '0.1'
+  VersionChanged: '0.9.1'
   Max: 1
+  AllowedMethods: []
+  AllowedPatterns: []
+  Exclude:
+    - '**/spec/**/*'
+    - '**/test/**/*'
 
 # `Kaizo/PluralCollectionName` flags a method that hands back an array under a
 # singular name. Ruby has no return types, so this is a heuristic, and it errs
 # toward silence: a method is flagged only when every value it can return is
 # unambiguously an array. `ArrayMethods` is the set whose result is an `Array`
 # whatever the receiver -- `select` and `reject` are absent on purpose, since on
-# a `Hash` they return a `Hash`. A name counts as plural when it ends in `s` or
-# appears in `IrregularPlurals`.
+# a `Hash` they return a `Hash`; extend it (with `inherit_mode: merge`) to
+# cover your own collection-returning helpers. A name counts as plural when it
+# ends in `s` or appears in `IrregularPlurals`.
 Kaizo/PluralCollectionName:
   Description: 'Checks that a method returning a collection is named in the plural.'
   Enabled: true
   VersionAdded: '0.8'
+  VersionChanged: '0.9'
   AllowedMethods: []
+  ArrayMethods:
+    - map
+    - flat_map
+    - collect
+    - collect_concat
+    - to_a
+    - entries
+    - sort
+    - sort_by
+    - zip
   IrregularPlurals:
     - people
     - children
@@ -43,13 +69,22 @@ Kaizo/PositionalArguments:
   Description: 'Checks that a method does not declare too many positional arguments.'
   Enabled: true
   VersionAdded: '0.1'
+  VersionChanged: '0.9'
   Max: 1
+  AllowedMethods: []
+  AllowedPatterns: []
 
 Kaizo/TotalArguments:
   Description: 'Checks that a method does not declare too many arguments in total.'
   Enabled: true
   VersionAdded: '0.1'
+  VersionChanged: '0.9.1'
   Max: 2
+  AllowedMethods: []
+  AllowedPatterns: []
+  Exclude:
+    - '**/spec/**/*'
+    - '**/test/**/*'
 
 # `Kaizo/AgentNounClassName` flags `class` definitions and
 # `Struct.new`/`Data.define`/`Class.new` assignments whose name ends in `er`/`or`
@@ -137,12 +172,18 @@ Kaizo/NestedMethodCalls:
 # example. Magic comments, `# rubocop:` directives, and shebangs are exempt;
 # add more exemptions with `AllowedPatterns`. Broaden `Include` (e.g. add
 # `**/spec/**/*` or `**/*_test.rb`) to cover support files or Minitest.
+# `spec/helpers` and `spec/support` hold infrastructure, not specs, so they
+# are excluded by default; override `Exclude` to change that.
 Kaizo/SpecComment:
   Description: 'Avoid comments in spec files; express the intent as well-structured specs.'
   Enabled: true
   VersionAdded: '0.5'
+  VersionChanged: '0.9'
   Include:
     - '**/*_spec.rb'
+  Exclude:
+    - '**/spec/helpers/**/*'
+    - '**/spec/support/**/*'
   AllowedPatterns: []
 
 # `Kaizo/ExplicitBegin` requires an explicit `begin`/`end` block when a method
@@ -185,16 +226,22 @@ Style/HashSyntax:
   EnforcedShorthandSyntax: always
 
 # `Kaizo/SpecDescriptionProse` requires RSpec `it`/`context` descriptions to
-# read as one-behavior prose: no commas, conjunctions (`Conjunctions`), or code
-# in an `it` description; `context` descriptions carry no code and open with a
-# `ContextPrefixes` word. `describe` strings are exempt. No autocorrection.
+# read as one-behavior prose: no commas, none of the `ForbiddenWords`
+# (conjunctions and conditionals whose presence signals a hidden split), and no
+# code in an `it` description; `context` descriptions carry no code and must
+# open with one of the `RequiredContextPrefixes`. Error class names
+# (`Foo::Error`) read as prose, since the error is part of the specified
+# behavior. Exempt whole descriptions with `AllowedPatterns`. `describe`
+# strings are exempt. No autocorrection.
 Kaizo/SpecDescriptionProse:
   Description: 'Require RSpec it/context descriptions to read as one-behavior prose.'
   Enabled: true
   VersionAdded: '0.6'
+  VersionChanged: '0.9'
   Include:
     - '**/*_spec.rb'
-  Conjunctions:
+  AllowedPatterns: []
+  ForbiddenWords:
     - and
     - but
     - or
@@ -210,12 +257,28 @@ Kaizo/SpecDescriptionProse:
     - because
     - although
     - though
-  ContextPrefixes:
+  RequiredContextPrefixes:
     - when
     - with
     - without
     - after
 
+# `Kaizo/SpecSubject` requires the unit under test to be declared with
+# `subject`, not `let`. A `let`/`let!` is flagged when its block confidently
+# builds the class under test: a `.new` on `described_class`, on the constant
+# an enclosing `describe`/`context` names (full or short name), or on a
+# constant matching the spec's file name. Deliberate second instances (an
+# `other` in an equality spec) are exempted with `AllowedMethods` /
+# `AllowedPatterns`, matched against the `let` name. No autocorrection.
+Kaizo/SpecSubject:
+  Description: 'Declare the unit under test with subject, not let.'
+  Enabled: true
+  VersionAdded: '0.9'
+  Include:
+    - '**/*_spec.rb'
+  AllowedMethods: []
+  AllowedPatterns: []
+
 # `Kaizo/FileUtilsInclusion` requires `FileUtils` to be mixed in with `include`
 # or `extend` once it is used more than once in a class or module, instead of
 # repeating the `FileUtils.` receiver. The namespace is reported once. A single
@@ -226,6 +289,16 @@ Kaizo/FileUtilsInclusion:
   Enabled: true
   VersionAdded: '0.6'
 
+# `Kaizo/TempfileCreate` requires block-form `Tempfile.create`, the only
+# temp-file API that closes and removes the file deterministically.
+# `Tempfile.new`/`Tempfile.open` rely on a GC finalizer that may run late or
+# never; blockless `Tempfile.create` returns a plain `File` that is never
+# removed automatically. No autocorrection.
+Kaizo/TempfileCreate:
+  Description: 'Use block-form Tempfile.create; Tempfile.new/open clean up unpredictably.'
+  Enabled: true
+  VersionAdded: '0.9'
+
 # `Kaizo/PreferPathname` flags calls to `File` class methods that have a
 # `Pathname` instance-method equivalent (`File.read`, `File.exist?`, `File.join`,
 # ...), preferring `Pathname`. Runs on `**/*.rb`; `exe/**/*` and `bin/**/*` are

data/lib/kaizo/version.rb

@@ -1,3 +1,3 @@
 module Kaizo
-  VERSION = "0.8.0".freeze
+  VERSION = "0.9.2".freeze
 end

data/lib/rubocop/cop/kaizo/agent_noun_class_name.rb

@@ -16,6 +16,29 @@ module RuboCop
       # assignments are both checked. There is no autocorrection: renaming a
       # class is a design decision.
       #
+      # == Configuration
+      #
+      # [+AllowedSuffixes+] Suffixes exempt from the `er`/`or` rule, matched
+      #                     against the end of the name (+Controller+ clears
+      #                     +UsersController+ too). Default: a broad list of
+      #                     legitimate `-er`/`-or` domain nouns and framework
+      #                     terms (+Adapter+, +Controller+, +Error+, +User+,
+      #                     ...) -- see +config/default.yml+ for all of them.
+      # [+ForbiddenSuffixes+] Suffixes always flagged, even when matched by
+      #                       +AllowedSuffixes+ -- which is how a default
+      #                       exemption is dropped. Default: +Service+, +Util+,
+      #                       +Utils+.
+      #
+      # Extend either list without restating it via RuboCop's
+      # <tt>inherit_mode: merge</tt>:
+      #
+      #   Kaizo/AgentNounClassName:
+      #     inherit_mode:
+      #       merge:
+      #         - AllowedSuffixes
+      #     AllowedSuffixes:
+      #       - Voucher     # PaymentVoucher now passes
+      #
       # @example
       #   # bad
       #   class PaymentProcessor

data/lib/rubocop/cop/kaizo/argument_counting.rb

@@ -10,6 +10,9 @@ module RuboCop
       # Operator methods (`[]=`, `[]`, `<=>`, ...) and the `initialize` of a
       # `Struct.new`/`Data.define` block are exempt.
       module ArgumentCounting
+        include AllowedMethods
+        include AllowedPattern
+
         POSITIONAL_TYPES = %i[arg optarg].freeze
         KEYWORD_TYPES = %i[kwarg kwoptarg].freeze
         DEFINE_METHODS = %i[define_method define_singleton_method].freeze
@@ -34,7 +37,7 @@ module RuboCop
 
         def on_block(node)
           return unless DEFINE_METHODS.include?(node.method_name)
-          return if defines_operator?(node)
+          return if exempt_defined_name?(node)
 
           check_arity(node)
         end
@@ -49,15 +52,22 @@ module RuboCop
         # modeled away, and a `Struct`/`Data` `initialize` just mirrors the members
         # the value object was declared with.
         def exempt?(node)
-          node.operator_method? || allowed_initialize?(node)
+          node.operator_method? || allowed_initialize?(node) || allowed_name?(node.method_name)
         end
 
-        # The same exemption for `define_method(:[]=)`, which names the method it
-        # defines with a symbol argument. A computed name is still checked -- we
-        # cannot know what it resolves to.
-        def defines_operator?(node)
+        # The same exemptions for `define_method(:[]=)`, which names the method it
+        # defines with a symbol (or string) argument. A computed name is still
+        # checked -- we cannot know what it resolves to.
+        def exempt_defined_name?(node)
           defined_name = node.send_node.first_argument
-          defined_name&.sym_type? && OPERATOR_METHOD_NAMES.include?(defined_name.value)
+          return false unless defined_name&.type?(:sym, :str)
+
+          name = defined_name.value.to_sym
+          OPERATOR_METHOD_NAMES.include?(name) || allowed_name?(name)
+        end
+
+        def allowed_name?(name)
+          allowed_method?(name) || matches_allowed_pattern?(name.to_s)
         end
 
         def positional_arity(arguments)

data/lib/rubocop/cop/kaizo/explicit_begin.rb

@@ -15,6 +15,15 @@ module RuboCop
       # Modifier `rescue` expressions (`foo rescue nil`) and endless method
       # definitions are not flagged.
       #
+      # == Configuration
+      #
+      # No cop-specific options; the standard per-cop settings (+Enabled+,
+      # +Severity+, +AutoCorrect+, +Include+/+Exclude+) apply. Note that
+      # loading the kaizo plugin disables `Style/RedundantBegin`, this cop's
+      # exact inverse. To opt out of explicit begins, disable this cop;
+      # re-enable `Style/RedundantBegin` only alongside that, since with both
+      # enabled each flags the form the other mandates.
+      #
       # @safety
       #   Autocorrection is skipped when the body does not sit on its own lines
       #   between `def` and `end` (a single-line definition, for example), and

data/lib/rubocop/cop/kaizo/file_utils_inclusion.rb

@@ -19,6 +19,11 @@ module RuboCop
       # There is no autocorrection: whether to `include` or `extend`, and where
       # the mixin belongs, is a judgment call for a human.
       #
+      # == Configuration
+      #
+      # No cop-specific options; the standard per-cop settings (+Enabled+,
+      # +Severity+, +Include+/+Exclude+) apply.
+      #
       # @example
       #   # bad - the `FileUtils.` receiver is repeated
       #   class Backup

data/lib/rubocop/cop/kaizo/keyword_arguments.rb

@@ -8,6 +8,23 @@ module RuboCop
       # (`kwarg`) and optional (`kwoptarg`) parameters are counted; `**rest` is
       # not.
       #
+      # == Configuration
+      #
+      # [+Max+] Most keyword arguments a method may declare. Default: +1+.
+      # [+AllowedMethods+] Method names exempt from the limit. Default: none.
+      # [+AllowedPatterns+] Regexps matched against the method name; a match is
+      #                     exempt. Default: none.
+      # [+Exclude+] Paths the cop skips. Default: <tt>**/spec/**/*</tt> and
+      #             <tt>**/test/**/*</tt> -- wide keyword interfaces are the
+      #             testing idiom (FactoryBot-style builders), so keyword
+      #             counts are not policed there. Set it to <tt>[]</tt> to
+      #             police tests too.
+      #
+      #   Kaizo/KeywordArguments:
+      #     Max: 2
+      #     AllowedMethods:
+      #       - initialize
+      #
       # @example Max: 2
       #   # bad
       #   def calculate_volume(width:, length:, height:)
@@ -17,6 +34,11 @@ module RuboCop
       #   def calculate_volume(shape)
       #   end
       #
+      # @example AllowedMethods: ['initialize'] (default: [])
+      #   # good - exempt by name
+      #   def initialize(host:, port:, ssl: true)
+      #   end
+      #
       class KeywordArguments < Base
         include ArgumentCounting
 

data/lib/rubocop/cop/kaizo/nested_method_calls.rb

@@ -16,6 +16,18 @@ module RuboCop
       # Depth is measured from each outermost call and reported once. There is no
       # autocorrection: choosing the intermediate name is a design decision.
       #
+      # == Configuration
+      #
+      # [+Max+] Deepest allowed nesting of calls in argument positions; +1+
+      #         permits one nested call. Default: +1+.
+      # [+AllowedMethods+] Calls to these methods neither count toward depth
+      #                    nor get flagged. Default: none.
+      #
+      #   Kaizo/NestedMethodCalls:
+      #     Max: 2
+      #     AllowedMethods:
+      #       - expect      # don't count RSpec's expect(...) wrapper
+      #
       # @example Max: 1 (default)
       #   # bad
       #   foo(SomeClass.new(another("bar").chain))

data/lib/rubocop/cop/kaizo/next_in_non_void_enumerable.rb

@@ -21,6 +21,17 @@ module RuboCop
       # clause might become a ternary, a `select`/`reject`, a `filter_map`, or a
       # restructured block.
       #
+      # == Configuration
+      #
+      # [+AllowedMethods+] Enumerable methods whose blocks may use `next`.
+      #                    Default: none.
+      # [+AllowedPatterns+] Regexps matched against the enumerable method's
+      #                     name; a match is exempt. Default: none.
+      #
+      #   Kaizo/NextInNonVoidEnumerable:
+      #     AllowedMethods:
+      #       - reduce      # allow `next acc` guards in reduce/inject
+      #
       # @example
       #   # bad
       #   array.map do |item|

data/lib/rubocop/cop/kaizo/plural_collection_name.rb

@@ -20,6 +20,30 @@ module RuboCop
       # outright. There is no autocorrection: renaming a method is a design
       # decision, and only its author knows the right plural.
       #
+      # == Configuration
+      #
+      # [+ArrayMethods+] Calls treated as returning an +Array+ whatever their
+      #                  receiver. Default: +map+, +flat_map+, +collect+,
+      #                  +collect_concat+, +to_a+, +entries+, +sort+, +sort_by+,
+      #                  +zip+.
+      # [+IrregularPlurals+] Names accepted as plural despite not ending in
+      #                      +s+. Default: +people+, +children+, +men+,
+      #                      +women+, +data+, +media+, +criteria+.
+      # [+AllowedMethods+] Method names never flagged. Default: none.
+      #
+      # Extend a list without restating its default via RuboCop's
+      # <tt>inherit_mode: merge</tt>:
+      #
+      #   Kaizo/PluralCollectionName:
+      #     inherit_mode:
+      #       merge:
+      #         - ArrayMethods
+      #         - IrregularPlurals
+      #     ArrayMethods:
+      #       - fetch_all
+      #     IrregularPlurals:
+      #       - alumni
+      #
       # @example
       #   # bad
       #   def user
@@ -48,7 +72,7 @@ module RuboCop
         # Methods whose result is an `Array` regardless of the receiver. Kept
         # deliberately short: anything whose return type follows its receiver
         # (`select` on a `Hash`) would turn this cop into a false-positive mill.
-        ARRAY_METHODS = %i[
+        DEFAULT_ARRAY_METHODS = %i[
           map flat_map collect collect_concat to_a entries sort sort_by zip
         ].freeze
 
@@ -103,7 +127,11 @@ module RuboCop
           return true if node.array_type?
 
           call = node.any_block_type? ? node.send_node : node
-          call.call_type? && ARRAY_METHODS.include?(call.method_name)
+          call.call_type? && array_methods.include?(call.method_name)
+        end
+
+        def array_methods
+          @array_methods ||= Array(cop_config.fetch("ArrayMethods", DEFAULT_ARRAY_METHODS)).map(&:to_sym)
         end
       end
     end

data/lib/rubocop/cop/kaizo/positional_arguments.rb

@@ -8,6 +8,22 @@ module RuboCop
       # and optional (`optarg`) parameters are counted; `*rest` and `&block` are
       # not.
       #
+      # Unlike the keyword-counting cops, this one runs everywhere, spec and
+      # test trees included: positional arguments communicate nothing unless
+      # they are solo, in test code as much as anywhere else.
+      #
+      # == Configuration
+      #
+      # [+Max+] Most positional arguments a method may declare. Default: +1+.
+      # [+AllowedMethods+] Method names exempt from the limit. Default: none.
+      # [+AllowedPatterns+] Regexps matched against the method name; a match is
+      #                     exempt. Default: none.
+      #
+      #   Kaizo/PositionalArguments:
+      #     Max: 0        # force every argument to be a keyword
+      #     AllowedMethods:
+      #       - initialize
+      #
       # @example Max: 2
       #   # bad
       #   def move(x, y, z)

data/lib/rubocop/cop/kaizo/prefer_pathname.rb

@@ -15,6 +15,19 @@ module RuboCop
       # There is no autocorrection: rewriting `File.read(path)` as
       # `Pathname(path).read` changes the receiver and is left to a human.
       #
+      # == Configuration
+      #
+      # [+Include+] Files the cop runs on. Default: <tt>**/*.rb</tt>.
+      # [+Exclude+] Files the cop skips even when included. Default:
+      #             <tt>exe/**/*</tt> and <tt>bin/**/*</tt>.
+      #
+      #   Kaizo/PreferPathname:
+      #     inherit_mode:
+      #       merge:
+      #         - Exclude
+      #     Exclude:
+      #       - 'db/**/*'      # add your own
+      #
       # @example
       #   # bad
       #   File.read(path)

data/lib/rubocop/cop/kaizo/spec_comment.rb

@@ -9,12 +9,34 @@ module RuboCop
       # `context`/`it` description, a clearer example name, or another example --
       # not prose riding alongside the code.
       #
-      # By default only `*_spec.rb` files are inspected (see `Include`). Magic
+      # By default only `*_spec.rb` files are inspected, and `spec/helpers` and
+      # `spec/support` are excluded -- they hold infrastructure, not specs. Magic
       # comments (`# frozen_string_literal: true`, `# encoding: ...`), RuboCop
       # directives (any `# rubocop:` comment), and shebangs are
       # never flagged; add further exemptions with `AllowedPatterns`. There is no
       # autocorrection: turning an explanation into a spec is a design decision.
       #
+      # == Configuration
+      #
+      # [+Include+] Files the cop runs on. Default: <tt>**/*_spec.rb</tt>.
+      #             Broaden it to cover support files or a Minitest suite.
+      # [+Exclude+] Files the cop skips even when included. Default:
+      #             <tt>**/spec/helpers/**/*</tt> and
+      #             <tt>**/spec/support/**/*</tt>. Set it to <tt>[]</tt> to
+      #             inspect those too.
+      # [+AllowedPatterns+] Regexps matched against the full comment text,
+      #                     leading +#+ included; a match is exempt.
+      #                     Default: none.
+      #
+      #   Kaizo/SpecComment:
+      #     inherit_mode:
+      #       merge:
+      #         - Include
+      #     Include:
+      #       - '**/*_test.rb'     # Minitest too
+      #     AllowedPatterns:
+      #       - '\A#\s*@rbs'       # rbs-inline type annotations
+      #
       # @example
       #   # bad
       #   it 'permits the request' do

data/lib/rubocop/cop/kaizo/spec_description_prose.rb

@@ -5,16 +5,19 @@ module RuboCop
       # specifications, after the spec-skeleton naming law.
       #
       # An `it`/`specify`/`example` description must not contain a comma (a list
-      # is several behaviors), a coordinating or conditional conjunction
-      # (`Conjunctions` -- joined clauses are separate examples; a condition
-      # belongs in a `context`), or code (`_ : # = { } ! [ ]`, a backtick, or a
-      # nested quoted literal -- a description is prose, not identifiers or wire
-      # values). Each rule is structural: it signals that one example is really
-      # more than one, or that the assertion is leaking into the name.
+      # is several behaviors), a forbidden word (`ForbiddenWords` -- conjunctions
+      # join clauses that are separate examples; a conditional signals a hidden
+      # `context`), or code (`_ : # = { } ! [ ]`, a backtick, or a nested quoted
+      # literal -- a description is prose, not identifiers or wire values). Each
+      # rule is structural: it signals that one example is really more than one,
+      # or that the assertion is leaking into the name.
       #
       # A `context` description must not contain code, and must open with one of
-      # `ContextPrefixes` (`when`/`with`/`without`/`after`). `describe` strings
-      # name the unit under test and are exempt.
+      # `RequiredContextPrefixes` (`when`/`with`/`without`/`after`). `describe`
+      # strings name the unit under test and are exempt. An error class name
+      # (`Foo::Error`, `Timeout::DeadlineException`) reads as prose, not code:
+      # the error is part of the specified behavior and is what the user
+      # ultimately sees raised.
       #
       # Wording preferences that do not change the spec's structure (e.g. `should`
       # vs a present-tense verb) are out of scope -- see rubocop-rspec's
@@ -23,6 +26,32 @@ module RuboCop
       # There is no autocorrection: splitting an example, or extracting a
       # condition into a `context`, is a modelling decision for a human.
       #
+      # == Configuration
+      #
+      # [+ForbiddenWords+] Words that force a split when they appear in an
+      #                    example description, matched as whole words, case
+      #                    insensitively. Default: +and+, +but+, +or+, +nor+,
+      #                    +so+, +yet+, +when+, +whenever+, +if+, +unless+,
+      #                    +while+, +until+, +because+, +although+, +though+.
+      # [+RequiredContextPrefixes+] Words a `context` description may open
+      #                             with. Default: +when+, +with+, +without+,
+      #                             +after+.
+      # [+AllowedPatterns+] Regexps matched against the whole description; a
+      #                     match exempts it from every rule. The escape hatch
+      #                     for a description that must quote something
+      #                     code-shaped. Default: none.
+      # [+Include+] Files the cop runs on. Default: <tt>**/*_spec.rb</tt>.
+      #
+      #   Kaizo/SpecDescriptionProse:
+      #     inherit_mode:
+      #       merge:
+      #         - ForbiddenWords
+      #         - AllowedPatterns
+      #     ForbiddenWords:
+      #       - given            # flag `given ...` too
+      #     AllowedPatterns:
+      #       - 'Foo::Widget'    # allow this one identifier
+      #
       # @example
       #   # bad
       #   it "renders the name, image, and flag"
@@ -39,6 +68,8 @@ module RuboCop
       #   end
       #
       class SpecDescriptionProse < Base
+        include AllowedPattern
+
         EXAMPLE_METHODS = %i[
           it specify example fit xit fspecify xspecify fexample xexample
         ].freeze
@@ -46,8 +77,8 @@ module RuboCop
         RESTRICT_ON_SEND = (EXAMPLE_METHODS + CONTEXT_METHODS).freeze
 
         COMMA_MSG = "Split this example: its description contains a comma.".freeze
-        CONJUNCTION_MSG = "Split this example: its description contains `%<word>s`; " \
-                          "use separate examples or a `context`.".freeze
+        FORBIDDEN_WORD_MSG = "Split this example: its description contains `%<word>s`; " \
+                             "use separate examples or a `context`.".freeze
         CODE_MSG = "Write the description as prose; it contains code, not English.".freeze
         CONTEXT_CODE_MSG = "Write the context description as prose; it contains code, not English.".freeze
         CONTEXT_PREFIX_MSG = "Begin the context description with %<prefixes>s.".freeze
@@ -57,15 +88,19 @@ module RuboCop
         # Homographs like `even`/`given`/`regardless` are deliberately absent --
         # they collide with adjectives/nouns (`even numbers`) -- add them via
         # config if you want them.
-        DEFAULT_CONJUNCTIONS = %w[
+        DEFAULT_FORBIDDEN_WORDS = %w[
           and but or nor so yet
           when whenever if unless while until because although though
         ].freeze
-        DEFAULT_CONTEXT_PREFIXES = %w[when with without after].freeze
+        DEFAULT_REQUIRED_CONTEXT_PREFIXES = %w[when with without after].freeze
 
         CODE_CHARS = /[_:#={}!`\[\]]/
         NESTED_QUOTE = /(['"]).+\1/
 
+        # An error class name is part of the specified behavior -- it is what
+        # the user sees raised -- so it is masked to prose before the checks.
+        ERROR_CONSTANT = /(?:::)?\b(?:[A-Z]\w*::)*(?:[A-Z]\w*)?(?:Error|Exception)\b/
+
         # @!method description(node)
         def_node_matcher :description, <<~PATTERN
           (send nil? _ (str $_) ...)
@@ -74,8 +109,9 @@ module RuboCop
         def on_send(node)
           text = description(node)
           return unless text
+          return if matches_allowed_pattern?(text)
 
-          message = violation(node.method_name, text)
+          message = violation(node.method_name, without_error_constants(text))
           return unless message
 
           add_offense(node.first_argument, message:)
@@ -83,6 +119,10 @@ module RuboCop
 
         private
 
+        def without_error_constants(text)
+          text.gsub(ERROR_CONSTANT, "error")
+        end
+
         def violation(method, text)
           if EXAMPLE_METHODS.include?(method)
             example_violation(text)
@@ -94,8 +134,8 @@ module RuboCop
         def example_violation(text)
           return COMMA_MSG if text.include?(",")
 
-          word = forbidden(text, conjunctions)
-          return format(CONJUNCTION_MSG, word:) if word
+          word = forbidden(text, forbidden_words)
+          return format(FORBIDDEN_WORD_MSG, word:) if word
 
           CODE_MSG if code?(text)
         end
@@ -116,19 +156,19 @@ module RuboCop
         end
 
         def prefix_regexp
-          /\A\s*(?:#{context_prefixes.map { |prefix| Regexp.escape(prefix) }.join("|")})\b/i
+          /\A\s*(?:#{required_context_prefixes.map { |prefix| Regexp.escape(prefix) }.join("|")})\b/i
         end
 
         def quoted_prefixes
-          context_prefixes.map { |prefix| "`#{prefix}`" }.join("/")
+          required_context_prefixes.map { |prefix| "`#{prefix}`" }.join("/")
         end
 
-        def conjunctions
-          cop_config.fetch("Conjunctions", DEFAULT_CONJUNCTIONS)
+        def forbidden_words
+          cop_config.fetch("ForbiddenWords", DEFAULT_FORBIDDEN_WORDS)
         end
 
-        def context_prefixes
-          cop_config.fetch("ContextPrefixes", DEFAULT_CONTEXT_PREFIXES)
+        def required_context_prefixes
+          cop_config.fetch("RequiredContextPrefixes", DEFAULT_REQUIRED_CONTEXT_PREFIXES)
         end
       end
     end