kaizo 0.7.0

data/config/default.yml

@@ -0,0 +1,210 @@
+# Default configuration for kaizo.
+#
+# These cops apply pressure toward good domain modeling and away from primitive
+# obsession: the `Kaizo/*` cops bound how many arguments a method declares, and
+# the `Kaizo/*` cops flag class names that describe an action rather than the
+# concept they model.
+
+# 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.
+Kaizo/KeywordArguments:
+  Description: 'Checks that a method does not declare too many keyword arguments.'
+  Enabled: true
+  VersionAdded: '0.1'
+  Max: 1
+
+Kaizo/PositionalArguments:
+  Description: 'Checks that a method does not declare too many positional arguments.'
+  Enabled: true
+  VersionAdded: '0.1'
+  Max: 1
+
+Kaizo/TotalArguments:
+  Description: 'Checks that a method does not declare too many arguments in total.'
+  Enabled: true
+  VersionAdded: '0.1'
+  Max: 2
+
+# `Kaizo/AgentNounClassName` flags `class` definitions and
+# `Struct.new`/`Data.define`/`Class.new` assignments whose name ends in `er`/`or`
+# (or in a `ForbiddenSuffixes` entry), unless it ends in an `AllowedSuffixes`
+# entry. `ForbiddenSuffixes` wins over `AllowedSuffixes`. Extend either list
+# without restating it using RuboCop's `inherit_mode: merge`.
+Kaizo/AgentNounClassName:
+  Description: 'Avoid naming classes as agent nouns (doers) rather than domain concepts.'
+  Enabled: true
+  VersionAdded: '0.2'
+  AllowedSuffixes:
+    - Adapter
+    - Anchor
+    - Author
+    - Banner
+    - Border
+    - Builder
+    - Character
+    - Cluster
+    - Color
+    - Container
+    - Controller
+    - Corner
+    - Cursor
+    - Customer
+    - Decorator
+    - Door
+    - Driver
+    - Enumerator
+    - Error
+    - Folder
+    - Footer
+    - Header
+    - Identifier
+    - Iterator
+    - Layer
+    - Ledger
+    - Letter
+    - Logger
+    - Mailer
+    - Marker
+    - Member
+    - Mirror
+    - Monitor
+    - Number
+    - Order
+    - Owner
+    - Paper
+    - Parameter
+    - Parser
+    - Partner
+    - Pointer
+    - Poster
+    - Presenter
+    - Quarter
+    - Register
+    - Router
+    - Sector
+    - Sensor
+    - Serializer
+    - Server
+    - User
+    - Vector
+    - Vendor
+    - Visitor
+    - Wrapper
+  ForbiddenSuffixes:
+    - Service
+    - Util
+    - Utils
+
+# `Kaizo/NestedMethodCalls` flags calls whose arguments are themselves calls,
+# nested deeper than `Max` levels -- e.g. `foo(SomeClass.new(another("bar").chain))`.
+# Only argument nesting is counted (receiver chains are a separate concern);
+# operator methods never count; `AllowedMethods` exempts named methods.
+Kaizo/NestedMethodCalls:
+  Description: 'Checks for method calls nested too deeply in argument positions.'
+  Enabled: true
+  VersionAdded: '0.4'
+  Max: 1
+  AllowedMethods: []
+
+# `Kaizo/SpecComment` treats comments in spec files as a smell -- a comment
+# usually wants to be a `context`/`it` description or a better-structured
+# 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.
+Kaizo/SpecComment:
+  Description: 'Avoid comments in spec files; express the intent as well-structured specs.'
+  Enabled: true
+  VersionAdded: '0.5'
+  Include:
+    - '**/*_spec.rb'
+  AllowedPatterns: []
+
+# `Kaizo/ExplicitBegin` requires an explicit `begin`/`end` block when a method
+# body attaches a `rescue` or `ensure` directly to the `def` (an "implicit
+# begin"). Modifier `rescue` (`foo rescue nil`) and endless method definitions
+# are never flagged. Autocorrection wraps the body in `begin`/`end`, but is
+# skipped when the body does not sit on its own lines between `def` and `end`,
+# or holds a heredoc or other multiline string, symbol, or regexp literal, where
+# re-indenting could change their contents.
+Kaizo/ExplicitBegin:
+  Description: 'Require an explicit `begin` block when a method body uses `rescue` or `ensure`.'
+  Enabled: true
+  VersionAdded: '0.6'
+
+# `Kaizo/NextInNonVoidEnumerable` flags `next` inside the block of a
+# value-returning `Enumerable` method (`map`, `select`, `reduce`, ...), where
+# `next` is control-flow-as-value. Void iteration methods (`each`,
+# `each_with_object`, ...) and non-`Enumerable` loops (`loop`, `while`) are never
+# flagged; a `next` bound to a nested block or loop is attributed to that inner
+# scope. `AllowedMethods`/`AllowedPatterns` exempt named methods. No autocorrection.
+Kaizo/NextInNonVoidEnumerable:
+  Description: 'Avoid `next` in the block of a value-returning `Enumerable` method.'
+  Enabled: true
+  VersionAdded: '0.6'
+  AllowedMethods: []
+  AllowedPatterns: []
+
+# `Style/RedundantBegin` enforces the exact opposite of `Kaizo/ExplicitBegin`
+# (and its autocorrection would fight ours -- the two would loop forever), so
+# loading this plugin disables it. Re-enable it explicitly in your own
+# `.rubocop.yml` at your peril.
+Style/RedundantBegin:
+  Enabled: false
+# `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.
+Kaizo/SpecDescriptionProse:
+  Description: 'Require RSpec it/context descriptions to read as one-behavior prose.'
+  Enabled: true
+  VersionAdded: '0.6'
+  Include:
+    - '**/*_spec.rb'
+  Conjunctions:
+    - and
+    - but
+    - or
+    - nor
+    - so
+    - yet
+    - when
+    - whenever
+    - if
+    - unless
+    - while
+    - until
+    - because
+    - although
+    - though
+  ContextPrefixes:
+    - when
+    - with
+    - without
+    - after
+
+# `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
+# qualified call, and a namespace that already mixes `FileUtils` in, are left
+# alone; nested classes/modules are counted on their own. No autocorrection.
+Kaizo/FileUtilsInclusion:
+  Description: 'Include or extend FileUtils instead of repeatedly qualifying its methods.'
+  Enabled: true
+  VersionAdded: '0.6'
+
+# `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
+# exempt by default (override with the standard Include/Exclude). No autocorrection.
+Kaizo/PreferPathname:
+  Description: 'Prefer Pathname over File for methods Pathname provides.'
+  Enabled: true
+  VersionAdded: '0.6'
+  Include:
+    - '**/*.rb'
+  Exclude:
+    - 'exe/**/*'
+    - 'bin/**/*'

data/lib/kaizo/plugin.rb

@@ -0,0 +1,27 @@
+require "lint_roller"
+
+module Kaizo
+  # A plugin that integrates kaizo with RuboCop's plugin system.
+  class Plugin < LintRoller::Plugin
+    def about
+      LintRoller::About.new(
+        name: "kaizo",
+        version: VERSION,
+        homepage: "https://github.com/flipmine/kaizo",
+        description: "A strict, punishing set of design cops for AI-agent-authored Ruby.",
+      )
+    end
+
+    def supported?(context)
+      context.engine == :rubocop
+    end
+
+    def rules(_context)
+      LintRoller::Rules.new(
+        type: :path,
+        config_format: :rubocop,
+        value: Pathname.new(__dir__).join("../../config/default.yml"),
+      )
+    end
+  end
+end

data/lib/kaizo/version.rb

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

data/lib/kaizo.rb

@@ -0,0 +1,15 @@
+require "rubocop"
+
+require_relative "kaizo/version"
+require_relative "kaizo/plugin"
+
+require_relative "rubocop/cop/kaizo_cops"
+
+# Kaizo ships a strict, punishing set of RuboCop cops aimed at AI-agent-authored
+# code: they bound argument counts, flag agent-noun class names, flag calls
+# nested too deeply in other calls' arguments, and treat comments and loose
+# descriptions in specs as structure that wants to be expressed properly.
+module Kaizo
+  # Base error class for kaizo.
+  class Error < StandardError; end
+end

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

@@ -0,0 +1,76 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks for classes named as agent nouns ("doers") rather than the domain
+      # concepts they model. A class whose name ends in `er` or `or` (`Manager`,
+      # `Processor`, `Handler`) -- or in any configured `ForbiddenSuffixes` such
+      # as `Service` -- usually signals procedural behavior that wants a clearer
+      # domain name or a different home.
+      #
+      # Names ending in an `AllowedSuffixes` entry are exempt; the match is by
+      # suffix, so `Controller` clears both `Controller` and `UsersController`.
+      # `ForbiddenSuffixes` always flags, even when also matched by
+      # `AllowedSuffixes` -- which is how you drop a default exemption.
+      #
+      # `class` definitions and `Struct.new`/`Data.define`/`Class.new` constant
+      # assignments are both checked. There is no autocorrection: renaming a
+      # class is a design decision.
+      #
+      # @example
+      #   # bad
+      #   class PaymentProcessor
+      #   end
+      #
+      #   # good
+      #   class Payment
+      #   end
+      #
+      # @example
+      #   # good - ends in an allowed suffix
+      #   class UsersController
+      #   end
+      #
+      class AgentNounClassName < Base
+        MSG = "Avoid the doer-style class name `%<name>s`. " \
+              "Prefer a name for the concept it models over the action it performs.".freeze
+        AGENT_NOUN = /(?:er|or)\z/i
+
+        # @!method class_builder_assignment(node)
+        def_node_matcher :class_builder_assignment, <<~PATTERN
+          (casgn _ $_ {
+            (send (const _ {:Struct :Data :Class}) {:new :define} ...)
+            (block (send (const _ {:Struct :Data :Class}) {:new :define} ...) ...)
+          })
+        PATTERN
+
+        def on_class(node)
+          check_name(node.identifier.short_name.to_s, node.loc.name)
+        end
+
+        def on_casgn(node)
+          return unless (name = class_builder_assignment(node))
+
+          check_name(name.to_s, node.loc.name)
+        end
+
+        private
+
+        def check_name(name, location)
+          return unless offending?(name)
+
+          add_offense(location, message: format(MSG, name: name))
+        end
+
+        def offending?(name)
+          return true if ends_with_any?(name, "ForbiddenSuffixes")
+
+          AGENT_NOUN.match?(name) && !ends_with_any?(name, "AllowedSuffixes")
+        end
+
+        def ends_with_any?(name, config_key)
+          Array(cop_config[config_key]).any? { |suffix| name.end_with?(suffix) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Shared traversal and counting for the argument-arity cops.
+      #
+      # 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.
+      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
+        MSG = "Method has too many %<kind>s. [%<count>d/%<max>d]".freeze
+
+        def on_def(node)
+          return if allowed_initialize?(node)
+
+          check_arity(node)
+        end
+        alias on_defs on_def
+
+        def on_block(node)
+          check_arity(node) if DEFINE_METHODS.include?(node.method_name)
+        end
+        alias on_numblock on_block
+        alias on_itblock on_block
+
+        private
+
+        def positional_arity(arguments)
+          arguments.count { |argument| POSITIONAL_TYPES.include?(argument.type) }
+        end
+
+        def keyword_arity(arguments)
+          arguments.count { |argument| KEYWORD_TYPES.include?(argument.type) }
+        end
+
+        def check_arity(node)
+          max = cop_config["Max"]
+          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 }
+        end
+
+        def offense_location(node)
+          node.any_block_type? ? node.send_node.loc.selector : node.loc.name
+        end
+
+        def allowed_initialize?(node)
+          node.method?(:initialize) && struct_or_data_definition?(enclosing_block(node))
+        end
+
+        # The block a method definition lives in, seen through the `begin` that
+        # wraps the body when the block holds more than one statement.
+        def enclosing_block(node)
+          parent = node.parent
+          parent&.begin_type? ? parent.parent : parent
+        end
+
+        def struct_or_data_definition?(node)
+          return false unless node&.block_type?
+
+          receiver = node.receiver
+          receiver&.const_type? && node.method?(STRUCT_OR_DATA[receiver.const_name])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Requires an explicit `begin`...`end` block when a method body has a
+      # `rescue` or `ensure` clause, instead of attaching the clause directly
+      # to the method definition (an "implicit begin"). This is the inverse
+      # of `Style/RedundantBegin`, which kaizo's default configuration
+      # disables so the two cops do not fight each other.
+      #
+      # An explicit `begin` names the unit of work being guarded, keeps the
+      # rescue/ensure visually bound to it, and leaves room for the method to
+      # grow other statements around the guarded region without silently
+      # widening what the `rescue` covers.
+      #
+      # Modifier `rescue` expressions (`foo rescue nil`) and endless method
+      # definitions are not flagged.
+      #
+      # @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
+      #   for bodies containing heredocs or other multiline string, symbol, or
+      #   regexp literals, because re-indenting those lines could change their
+      #   contents.
+      #
+      # @example
+      #   # bad
+      #   def foo
+      #     do_something
+      #   ensure
+      #     cleanup
+      #   end
+      #
+      #   # good
+      #   def foo
+      #     begin
+      #       do_something
+      #     ensure
+      #       cleanup
+      #     end
+      #   end
+      #
+      class ExplicitBegin < Base
+        include Alignment
+        include RangeHelp
+        include RescueNode
+        extend AutoCorrector
+
+        MSG = "Use an explicit `begin` block for `rescue`/`ensure` in a method body.".freeze
+
+        def on_def(node)
+          return if node.endless?
+
+          body = node.body
+          return unless implicit_begin?(body)
+
+          range = clause_keyword(body)
+          if safe_to_correct?(node, body)
+            add_offense(range) { |corrector| wrap_in_begin(corrector, node, body) }
+          else
+            add_offense(range)
+          end
+        end
+        alias on_defs on_def
+
+        private
+
+        def implicit_begin?(body)
+          return false unless body
+
+          body.ensure_type? || clause_rescue?(body)
+        end
+
+        def clause_rescue?(node)
+          node&.rescue_type? && !rescue_modifier?(node.resbody_branches.first)
+        end
+
+        def clause_keyword(body)
+          clause = first_clause(body)
+          clause.rescue_type? ? clause.resbody_branches.first.loc.keyword : clause.loc.keyword
+        end
+
+        def first_clause(body)
+          return body unless body.ensure_type?
+
+          inner = body.children.first
+          clause_rescue?(inner) ? inner : body
+        end
+
+        def safe_to_correct?(node, body)
+          own_body_lines?(node, body) && !multiline_literal?(body)
+        end
+
+        def own_body_lines?(node, body)
+          node.loc.keyword.line < body.first_line && body.last_line < node.loc.end.line
+        end
+
+        def multiline_literal?(body)
+          body.each_descendant(:any_str, :any_sym, :regexp).any? do |literal|
+            literal.multiline? || (literal.respond_to?(:heredoc?) && literal.heredoc?)
+          end
+        end
+
+        def wrap_in_begin(corrector, node, body)
+          body_range = range_by_whole_lines(body.source_range)
+          indent = indentation(node)
+          corrector.replace(body_range, wrapped_body(body_range, indent))
+        end
+
+        def wrapped_body(body_range, indent)
+          step = " " * configured_indentation_width
+          shifted = body_range.source.each_line.map do |line|
+            line.strip.empty? ? line : "#{step}#{line}"
+          end.join
+          "#{indent}begin\n#{shifted.chomp}\n#{indent}end"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Requires `FileUtils` to be mixed in with `include` (or `extend`) once it
+      # is used more than once in a class or module, rather than qualifying every
+      # call with the `FileUtils.` receiver.
+      #
+      # Repeating the `FileUtils.` receiver is noise; mixing the module in once
+      # names the capability and lets the body call `mkdir_p`, `cp`, and friends
+      # directly. Use `include` for instance-level use and `extend` for
+      # class/singleton-level use. A single qualified call is left alone, and a
+      # class or module that already mixes `FileUtils` in is not flagged.
+      #
+      # The class or module is reported once. Nested classes and modules are
+      # counted on their own -- one call in an outer class and one in a nested
+      # class do not add up -- and a `FileUtils` call in the superclass
+      # expression does not count toward the class body.
+      #
+      # There is no autocorrection: whether to `include` or `extend`, and where
+      # the mixin belongs, is a judgment call for a human.
+      #
+      # @example
+      #   # bad - the `FileUtils.` receiver is repeated
+      #   class Backup
+      #     def run
+      #       FileUtils.mkdir_p(dir)
+      #       FileUtils.cp(src, dir)
+      #     end
+      #   end
+      #
+      #   # good - mix it in once, then call unqualified
+      #   class Backup
+      #     include FileUtils
+      #
+      #     def run
+      #       mkdir_p(dir)
+      #       cp(src, dir)
+      #     end
+      #   end
+      #
+      class FileUtilsInclusion < Base
+        MSG = "`FileUtils` is used %<count>d times in this %<scope>s; " \
+              "`include`/`extend` FileUtils and call its methods unqualified.".freeze
+
+        # @!method file_utils_call?(node)
+        def_node_matcher :file_utils_call?, <<~PATTERN
+          (send (const {nil? cbase} :FileUtils) ...)
+        PATTERN
+
+        # @!method file_utils_mixin?(node)
+        def_node_matcher :file_utils_mixin?, <<~PATTERN
+          (send nil? {:include :extend} (const {nil? cbase} :FileUtils) ...)
+        PATTERN
+
+        def on_class(node)
+          check(node, "class")
+        end
+
+        def on_module(node)
+          check(node, "module")
+        end
+
+        private
+
+        def check(node, scope)
+          return if own_sends(node) { |send| file_utils_mixin?(send) }.any?
+
+          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))
+        end
+
+        # Sends in `namespace`'s own body that match the block -- not its
+        # superclass expression, and not a nested class or module (those own
+        # their sends and are checked on their own).
+        def own_sends(namespace)
+          body = namespace.body
+          return [] unless body
+
+          [body, *body.each_descendant].select do |send_node|
+            send_node.send_type? && yield(send_node) && owning_namespace(send_node).equal?(namespace)
+          end
+        end
+
+        def owning_namespace(node)
+          node.each_ancestor(:class, :module).first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module RuboCop
+  module Cop
+    module Kaizo
+      # Checks that a method does not declare too many keyword arguments.
+      #
+      # Keyword arguments are self-documenting, but a long list of them is still
+      # a sign that the related values want to be modeled as an object. Required
+      # (`kwarg`) and optional (`kwoptarg`) parameters are counted; `**rest` is
+      # not.
+      #
+      # @example Max: 2
+      #   # bad
+      #   def calculate_volume(width:, length:, height:)
+      #   end
+      #
+      #   # good
+      #   def calculate_volume(shape)
+      #   end
+      #
+      class KeywordArguments < Base
+        include ArgumentCounting
+
+        exclude_limit "Max"
+
+        KIND = "keyword arguments".freeze
+
+        private
+
+        def arity(arguments)
+          keyword_arity(arguments)
+        end
+      end
+    end
+  end
+end