kaizo 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a167afcda94e477c2fd351f0f88c4c4f69b4adb987e0e74a59f50c516aa6080
-  data.tar.gz: f002c0b1464262edc8eb988f046b935fb9347d2258585c143acc6dd46911f86b
+  metadata.gz: a33b49134e0a0a871e9b6358cf3fcc9ab88d9ebaca5e8928003de08594c01a11
+  data.tar.gz: 7ed8c9d6780bc64c233b94135850694da8b2bfa1e314dd7369dddf7560f7d42d
 SHA512:
-  metadata.gz: 41ec7ca0e3f99dc13c761540b9ac7c06bd66f1cbcdecf776db8f1dd4dcd0c412008ae70f6ac73e6d9295662a27d70b3c2b2973930674ea7229fc1d173b4bb33e
-  data.tar.gz: f3ea240a663c70959adf03f95c5b49452ae3ae71a93818b8dcdedcf8bf1b72f10acd9d1db95494e12f7ee592a3162b8590a5d99603caca710126c810147bdaca
+  metadata.gz: b4c8a8645f32a48c82b52d23966d37d2608c63a0c84e4820e33c15ed6f58bb84c40658eef9de990874e3e0d304c8d6d27abec8ef5f708ff3468f6430663cdd12
+  data.tar.gz: f4189d76f5bb36959f71c84f0497b33805e77ae4e8b04941c78e8517a9012f92447dbbb08c8063b5738746018330fba474abcee324656461af7ec83f2946a96a

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+- Add `Kaizo/PluralCollectionName` cop: flags a method that returns an array
+  under a singular name (`def user` handing back `[first, second]`), since a
+  plural name documents what the caller gets. Ruby has no return types, so the
+  detection is a heuristic and errs toward silence — a method is flagged only
+  when every value it can return is unambiguously an array, so one branch
+  returning `nil` keeps it quiet. `ArrayMethods` covers calls whose result is an
+  `Array` whatever the receiver; `select` and `reject` are excluded on purpose,
+  since on a `Hash` they return a `Hash`. Predicate, writer, and operator
+  methods are exempt, as is `initialize`. `IrregularPlurals` handles plurals
+  without a trailing `s`. No autocorrection. Enabled by default.
+- The argument-counting cops (`Kaizo/PositionalArguments`, `Kaizo/TotalArguments`,
+  `Kaizo/KeywordArguments`) no longer flag **operator methods**. The arity of `[]=`
+  is fixed by Ruby's syntax — an index (or indices) plus the assigned value — so it
+  cannot be modeled away; the same holds for `[]`, `<=>`, `+`, `<<`, `==`, and the
+  rest of the operator family. Covers `def`, `def self.`, and the
+  `define_method(:[]=)` form; a `define_method` whose name is computed at runtime is
+  still checked, since the name cannot be known statically. This joins the existing
+  `Struct.new`/`Data.define` `initialize` exemption. Ordinary writers
+  (`def name=(value)`) are unaffected.
+- The Public Config now ships `Style/HashSyntax` with
+  `EnforcedShorthandSyntax: always`, preferring Ruby 3.1's hash-value shorthand
+  (`Session.new(table:)` over `Session.new(table: table)`). Override it in your own
+  config if you want the explicit form. *(Landed on `master` after 0.7.0 was
+  published, so it has not reached gem users yet and was never recorded here.)*
+- Expanded the `Kaizo/NestedMethodCalls` README guidance to spell out that the
+  *name* is the point, not the assignment — extracting to a local called `result`
+  or `tmp` satisfies the rule while missing what it asks for. The offense message
+  itself is unchanged.
+
 ## 0.6.0
 
 - **Renamed the gem from `rubocop-design` to `kaizo`**, and moved every cop from

data/README.md

@@ -129,6 +129,24 @@ Data.define(:width, :height, :depth, :weight) do
 end
 ```
 
+**Operator methods** are exempt too. The arity of `[]=` is fixed by Ruby's syntax
+— an index (or indices) plus the value being assigned — so there is no object to
+extract and no primitive obsession to correct. The same holds for `[]`, `<=>`,
+`+`, `<<`, `==`, and the rest of the operator family:
+
+```ruby
+# not flagged
+def []=(row, column, value)
+  @cells[row][column] = value
+end
+```
+
+This covers `def`, `def self.`, and `define_method(:[]=)`. A `define_method` whose
+name is computed at runtime is still checked — the cop cannot know what the name
+resolves to. Note the exemption is for *operator* methods, not ordinary writers:
+`def name=(value)` takes a single argument and was never in danger of tripping the
+limits anyway.
+
 There is intentionally **no autocorrection**: the fix is a design decision (what
 object should these arguments become?), and that belongs to a human.
 
@@ -214,13 +232,21 @@ intermediate results want names. Reaching for the right name (or extracting a
 method) almost always reads better, and is easier to debug, than peeling
 parentheses apart.
 
+The point is not the assignment, it is the **name**. A local called `result` or
+`tmp` buys nothing; a name that says what the value *is* turns the step into its
+own documentation.
+
 ```ruby
 # bad
 wrap(parse(read(io)))
 
-# good - name the intermediate result
-parsed = parse(read(io))
-wrap(parsed)
+# bad - named, but the name says nothing
+result = parse(read(io))
+wrap(result)
+
+# good - the name documents what the value is
+parsed_config = parse(read(io))
+wrap(parsed_config)
 
 # good - a single nested call is fine
 puts compute(value)
@@ -515,6 +541,56 @@ Kaizo/NextInNonVoidEnumerable:
   AllowedPatterns: []
 ```
 
+## Plural names for collections
+
+`Kaizo/PluralCollectionName` flags a method that hands back an array under a
+singular name. The plural does the documenting for free — `users` tells the
+caller what they are getting; `user` actively misleads them.
+
+```ruby
+# bad
+def user
+  [first_match, second_match]
+end
+
+# good
+def users
+  [first_match, second_match]
+end
+```
+
+Ruby has no return types, so "returns an array" is a heuristic — and this cop
+deliberately errs toward silence. A method is flagged only when **every** value
+it can return is unambiguously an array: an array literal, or a call to a method
+in `ArrayMethods` whose result is an `Array` whatever its receiver. A single
+branch returning something else is enough to leave the method alone:
+
+```ruby
+# good - not confidently a collection, so not flagged
+def user
+  return nil if missing?
+
+  [first_match, second_match]
+end
+```
+
+`select` and `reject` are absent from the default `ArrayMethods` on purpose: on a
+`Hash` they return a `Hash`, and including them would turn this into a
+false-positive mill. A name counts as plural when it ends in `s` or appears in
+`IrregularPlurals`. Predicate (`?`), writer (`=`), and operator methods are
+exempt, as is `initialize`.
+
+```yaml
+Kaizo/PluralCollectionName:
+  AllowedMethods: []
+  IrregularPlurals:
+    - people        # plural without a trailing `s`
+    - children
+```
+
+As with the other cops there is **no autocorrection** — only the author knows
+the right plural.
+
 ## Development
 
 ```bash

data/config/default.yml

@@ -7,15 +7,38 @@
 
 # The `Kaizo/*` cops check `def`, `def self.`, `define_method`, and
 # `define_singleton_method`. `*rest`, `**keyword-rest`, and `&block` parameters
-# are not counted. 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.
+# are not counted. Operator methods (`[]=`, `[]`, `<=>`, ...) and the `initialize`
+# of a `Struct.new`/`Data.define` block are exempt -- their arity is fixed by Ruby
+# 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.
 Kaizo/KeywordArguments:
   Description: 'Checks that a method does not declare too many keyword arguments.'
   Enabled: true
   VersionAdded: '0.1'
   Max: 1
 
+# `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`.
+Kaizo/PluralCollectionName:
+  Description: 'Checks that a method returning a collection is named in the plural.'
+  Enabled: true
+  VersionAdded: '0.8'
+  AllowedMethods: []
+  IrregularPlurals:
+    - people
+    - children
+    - men
+    - women
+    - data
+    - media
+    - criteria
+
 Kaizo/PositionalArguments:
   Description: 'Checks that a method does not declare too many positional arguments.'
   Enabled: true
@@ -153,6 +176,14 @@ Kaizo/NextInNonVoidEnumerable:
 # `.rubocop.yml` at your peril.
 Style/RedundantBegin:
   Enabled: false
+
+# Prefer Ruby 3.1's hash-value shorthand -- `Session.new(table:)` over
+# `Session.new(table: table)` -- everywhere key and value name match. Shipped on
+# by default because kaizo targets modern Ruby; override in your own config if
+# you want the explicit form.
+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

data/lib/kaizo/version.rb

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

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

@@ -58,7 +58,7 @@ module RuboCop
         def check_name(name, location)
           return unless offending?(name)
 
-          add_offense(location, message: format(MSG, name: name))
+          add_offense(location, message: format(MSG, name:))
         end
 
         def offending?(name)

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

@@ -6,30 +6,60 @@ module RuboCop
       # Walks method definitions written with `def`, `def self.`, `define_method`,
       # and `define_singleton_method`, and reports when the argument count
       # produced by the including cop exceeds the configured `Max`. Including cops
-      # must define a private `arity(arguments)` method and a `KIND` constant. The
-      # `initialize` of a `Struct.new`/`Data.define` block is exempt.
+      # must define a private `arity(arguments)` method and a `KIND` constant.
+      # Operator methods (`[]=`, `[]`, `<=>`, ...) and the `initialize` of a
+      # `Struct.new`/`Data.define` block are exempt.
       module ArgumentCounting
         POSITIONAL_TYPES = %i[arg optarg].freeze
         KEYWORD_TYPES = %i[kwarg kwoptarg].freeze
         DEFINE_METHODS = %i[define_method define_singleton_method].freeze
         STRUCT_OR_DATA = { "Struct" => :new, "Data" => :define }.freeze
+
+        # Ruby's operator method names, mirroring the list behind RuboCop's
+        # `operator_method?` (private upstream, so it cannot be reused). Needed
+        # only for the `define_method(:[]=)` form, where the name being defined is
+        # a symbol argument rather than a `def` node we could ask directly.
+        OPERATOR_METHOD_NAMES = [
+          :!, :!=, :"!@", :!~, :%, :&, :*, :**, :+, :+@, :-, :-@, :/, :<, :<<, :<=,
+          :<=>, :==, :===, :=~, :>, :>=, :>>, :[], :[]=, :^, :`, :|, :~, :"~@"
+        ].freeze
         MSG = "Method has too many %<kind>s. [%<count>d/%<max>d]".freeze
 
         def on_def(node)
-          return if allowed_initialize?(node)
+          return if exempt?(node)
 
           check_arity(node)
         end
         alias on_defs on_def
 
         def on_block(node)
-          check_arity(node) if DEFINE_METHODS.include?(node.method_name)
+          return unless DEFINE_METHODS.include?(node.method_name)
+          return if defines_operator?(node)
+
+          check_arity(node)
         end
         alias on_numblock on_block
         alias on_itblock on_block
 
         private
 
+        # A definition whose argument count is not a design choice. An operator
+        # method's arity is fixed by Ruby's syntax -- `[]=` takes the indices plus
+        # the assigned value, `<=>` takes its right-hand side -- so it cannot be
+        # 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)
+        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)
+          defined_name = node.send_node.first_argument
+          defined_name&.sym_type? && OPERATOR_METHOD_NAMES.include?(defined_name.value)
+        end
+
         def positional_arity(arguments)
           arguments.count { |argument| POSITIONAL_TYPES.include?(argument.type) }
         end
@@ -43,8 +73,8 @@ module RuboCop
           count = arity(node.arguments)
           return unless max && count > max
 
-          message = format(MSG, kind: self.class::KIND, count: count, max: max)
-          add_offense(offense_location(node), message: message) { self.max = count }
+          message = format(MSG, kind: self.class::KIND, count:, max:)
+          add_offense(offense_location(node), message:) { self.max = count }
         end
 
         def offense_location(node)

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

@@ -68,7 +68,7 @@ module RuboCop
           count = own_sends(node) { |send| file_utils_call?(send) }.size
           return if count < 2
 
-          add_offense(node.loc.name, message: format(MSG, count: count, scope: scope))
+          add_offense(node.loc.name, message: format(MSG, count:, scope:))
         end
 
         # Sends in `namespace`'s own body that match the block -- not its

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

@@ -5,8 +5,10 @@ module RuboCop
       #
       # A call whose arguments are themselves the results of other calls --
       # `foo(SomeClass.new(another("bar").chain))` -- packs several steps into one
-      # expression. Naming the intermediate results (or extracting a method) almost
-      # always reads better and is easier to debug than peeling parentheses apart.
+      # expression. Giving the intermediate results descriptive names (or extracting
+      # a method) almost always reads better and is easier to debug than peeling
+      # parentheses apart. The point is not the assignment but the name: it should
+      # say what the value is, so the step documents itself.
       #
       # Only nesting through *argument* positions is counted; a receiver chain such
       # as `user.account.owner.name` is a separate concern. Operator methods
@@ -21,9 +23,9 @@ module RuboCop
       #   # bad
       #   wrap(parse(read(io)))
       #
-      #   # good - name the intermediate result
-      #   parsed = parse(read(io))
-      #   wrap(parsed)
+      #   # good - a name that documents what the value is
+      #   parsed_config = parse(read(io))
+      #   wrap(parsed_config)
       #
       #   # good - a single nested call is allowed
       #   puts compute(value)
@@ -48,7 +50,7 @@ module RuboCop
           depth = nesting_depth(node)
           return unless max && depth > max
 
-          add_offense(node, message: format(MSG, depth: depth, max: max)) do
+          add_offense(node, message: format(MSG, depth:, max:)) do
             self.max = depth
           end
         end

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

@@ -113,11 +113,11 @@ module RuboCop
         private
 
         def flag_block_local_nexts(block_node, method)
-          message = format(MSG, method: method)
+          message = format(MSG, method:)
 
           block_node.each_child_node do |child|
             each_block_local_next(child) do |next_node|
-              add_offense(next_node.loc.keyword, message: message)
+              add_offense(next_node.loc.keyword, message:)
             end
           end
         end

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

@@ -0,0 +1,111 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks that a method returning a collection is named in the plural. A
+      # singular name on a method handing back an array (`def user` returning
+      # `[first, second]`) misdescribes what the caller gets; the plural does the
+      # documenting for free.
+      #
+      # Ruby has no return types, so "returns an array" is a heuristic, and this
+      # cop deliberately errs toward silence. A method is only flagged when
+      # *every* value it can return is unambiguously an array: an array literal,
+      # or a call to a method that returns an `Array` whatever its receiver
+      # (`ArrayMethods`, e.g. `map`, `to_a`, `sort`). One branch returning `nil`
+      # is enough to leave the method alone. Methods like `select` and `reject`
+      # are absent by design -- on a `Hash` they hand back a `Hash`.
+      #
+      # A name counts as plural when it ends in `s` or appears in
+      # `IrregularPlurals`. Predicate (`?`), writer (`=`), and operator methods
+      # are exempt, as is `initialize`, and `AllowedMethods` exempts names
+      # outright. There is no autocorrection: renaming a method is a design
+      # decision, and only its author knows the right plural.
+      #
+      # @example
+      #   # bad
+      #   def user
+      #     [first_match, second_match]
+      #   end
+      #
+      #   # good
+      #   def users
+      #     [first_match, second_match]
+      #   end
+      #
+      # @example
+      #   # good - not confidently an array, so not flagged
+      #   def user
+      #     return nil if missing?
+      #
+      #     [first_match, second_match]
+      #   end
+      #
+      class PluralCollectionName < Base
+        include AllowedMethods
+
+        MSG = "Name a method that returns a collection in the plural. " \
+              "`%<name>s` returns an array.".freeze
+
+        # 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[
+          map flat_map collect collect_concat to_a entries sort sort_by zip
+        ].freeze
+
+        def on_def(node)
+          return if exempt?(node)
+          return unless returns_array?(node.body)
+
+          add_offense(node.loc.name, message: format(MSG, name: node.method_name))
+        end
+        alias on_defs on_def
+
+        private
+
+        def exempt?(node)
+          return true if node.predicate_method? || node.assignment_method?
+          return true if node.operator_method? || node.method?(:initialize)
+
+          plural?(node.method_name.to_s) || allowed_method?(node.method_name)
+        end
+
+        def plural?(name)
+          name.end_with?("s") || irregular_plurals.include?(name)
+        end
+
+        def irregular_plurals
+          Array(cop_config["IrregularPlurals"])
+        end
+
+        # Every value the method can hand back must be an array before it is
+        # worth flagging, so that a single `return nil` keeps the cop quiet.
+        def returns_array?(body)
+          return false unless body
+
+          results = [final_expression(body), *explicit_returns(body)]
+          results.all? { |result| array_result?(result) }
+        end
+
+        def final_expression(body)
+          body.begin_type? ? body.children.last : body
+        end
+
+        # The value of each `return`, with a bare `return` contributing `nil` --
+        # which is exactly what should stop the method being flagged.
+        def explicit_returns(body)
+          body.each_descendant(:return).map { |node| node.children.first }
+        end
+
+        # A block-bearing call (`rows.map { ... }`) is a block node wrapping the
+        # send, so the method name lives one level down.
+        def array_result?(node)
+          return false unless node
+          return true if node.array_type?
+
+          call = node.any_block_type? ? node.send_node : node
+          call.call_type? && ARRAY_METHODS.include?(call.method_name)
+        end
+      end
+    end
+  end
+end

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

@@ -78,7 +78,7 @@ module RuboCop
           message = violation(node.method_name, text)
           return unless message
 
-          add_offense(node.first_argument, message: message)
+          add_offense(node.first_argument, message:)
         end
 
         private
@@ -95,7 +95,7 @@ module RuboCop
           return COMMA_MSG if text.include?(",")
 
           word = forbidden(text, conjunctions)
-          return format(CONJUNCTION_MSG, word: word) if word
+          return format(CONJUNCTION_MSG, word:) if word
 
           CODE_MSG if code?(text)
         end

data/lib/rubocop/cop/kaizo_cops.rb

@@ -1,5 +1,6 @@
 require_relative "kaizo/argument_counting"
 require_relative "kaizo/keyword_arguments"
+require_relative "kaizo/plural_collection_name"
 require_relative "kaizo/positional_arguments"
 require_relative "kaizo/total_arguments"
 require_relative "kaizo/agent_noun_class_name"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kaizo
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - David Gillis
@@ -62,6 +62,7 @@ files:
 - lib/rubocop/cop/kaizo/keyword_arguments.rb
 - lib/rubocop/cop/kaizo/nested_method_calls.rb
 - lib/rubocop/cop/kaizo/next_in_non_void_enumerable.rb
+- lib/rubocop/cop/kaizo/plural_collection_name.rb
 - lib/rubocop/cop/kaizo/positional_arguments.rb
 - lib/rubocop/cop/kaizo/prefer_pathname.rb
 - lib/rubocop/cop/kaizo/spec_comment.rb
@@ -90,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: A strict, punishing set of RuboCop design cops for AI-agent-authored Ruby.
 test_files: []