rubocop-kata 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30d894b4455161e0ce3dac01fa4c627de974cf89e7d1372a610749ee9ba0ad26
-  data.tar.gz: 6bfcc2c6b38d212c8ff6ac0efc16bd4b563a74b972ccc546013619b813c0f6e2
+  metadata.gz: 4d84b32b4beb311cd73ed3af609400cc07a4a1e7fb41258e813feab7a7477ae9
+  data.tar.gz: 3038bc491f3197c6623f30f68742fda4008c4519cbacc2c95dc36e0ebc10276c
 SHA512:
-  metadata.gz: f7c5bd992aa75df3b4f38c9182005dc7f346b4ea0db83e5756fb02f638acbc034b32a7146dece44e7c9421ce4d04cd064e02ce46309d6ba4513a8e5560540c5e
-  data.tar.gz: '08f28bf480cf2fcef885db1d5df0c92d3200a53b898dcc01fc026172214276a5a83a1a2b0b6bc807e2e4aed9ac78439cac6c50b7a53643986e44c05bf7a0e388'
+  metadata.gz: b38144839ec596e2f646f89f2c28328978cf030d7bbc9c31deccad49fe94ad9775e75a2af69d51961cfed832f3acc7b49c32c43f0830fc98d300c8033cda1230
+  data.tar.gz: 5ab77b46b9eab5d756368860c1f40866111964217dc0fda9cda532c49574fc6472dc60fb2a091c1e3d54269b63266b956f4bfd9a900ad50528dae96a8a8dd3de

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## [Unreleased]
+## [0.7.0] - 2026-08-16
+
+- New `rubocop-kata doctor` command: reports `.rubocop.yml` entries that
+  configure a cop the inherited configuration already disables, and
+  `rubocop:disable`/`enable` comments naming a cop that is not enabled where
+  the comment sits. RuboCop reports neither. Exits non-zero when it finds
+  something.
+- `Style/DisableCopsWithinSourceCodeDirective` is now on.
+- `Kata/AgentNoun` suggests a name when it can derive one: a compound minus its
+  agent word (`PaymentProcessor` -> `Payment`), or a regular
+  -ator/-ector/-isor/-izer noun the shipped dictionary confirms (`Selector` ->
+  `Selection`, `Synthesizer` -> `Synthesis`). It never proposes a name it would
+  flag in turn.
+- `Kata/AgentNoun` `AllowedNames` entries now match a whole name or a trailing
+  segment of one, so the default `Error` also exempts `UsageError` and
+  `ParseError` without listing them.
+- `Kata/BuilderNoun` gained `AllowedNames`, for the method whose name an
+  external API dictates (`get_callbacks`).
+- The dictionary moved to `RuboCop::Kata::Dictionary`, shared by
+  `Kata/RealWords` and `Kata/AgentNoun`.
 
 ## [0.6.0] - 2026-08-15
 

data/README.md

@@ -17,13 +17,17 @@ that dodge with a shipped dictionary instead of a word list you maintain:
 - **Fifteen house cops.** Naming, dependency discipline, and data honesty in the Elegant Objects spirit — from `Kata/AgentNoun` to `Kata/ClockDiscipline`.
 
 ```ruby
-class PaymentProcessor  # Kata/AgentNoun: `PaymentProcessor` names a doer;
-end                     #   name the class for the thing it is, not the work it does.
+class PaymentProcessor  # Kata/AgentNoun: `PaymentProcessor` names a doer; name the class
+end                     #   for the thing it is, not the work it does. Try `Payment`.
 
 class Payment           # OK
 end
 ```
 
+It suggests a name only when it can derive one: a compound minus its agent word,
+or a regular `-ator`/`-ector`/`-isor`/`-izer` noun the shipped dictionary
+confirms (`Selector` → `Selection`, `Synthesizer` → `Synthesis`).
+
 ## Getting started
 
 Add the gem to your `Gemfile`:
@@ -53,7 +57,7 @@ That's it. The plugin loads the bundled extensions and the shared defaults, so y
 
 | Cop | Default | What it enforces |
 | --- | --- | --- |
-| `Kata/AgentNoun` | on | Classes named for what they are, not `-er`/`-or` doers. Allow exceptions via `AllowedNames`. |
+| `Kata/AgentNoun` | on | Classes named for what they are, not `-er`/`-or` doers. Suggests the better name when it can derive one. `AllowedNames` matches a whole name or a trailing segment, so `Error` covers `UsageError`. |
 | `Kata/NoComments` | on | No prose comments; say it in the code. Magic comments, linter directives, and licence headers survive. Autocorrects. |
 | `Kata/IoDiscipline` | on | No bare `puts`/`warn`/`pp`/`p` outside specs/scripts; write through an injected `@io` or an explicit receiver. |
 | `Kata/ProsePlacement` | off | Sentence-length strings belong in the presentation layer. Enable with an `Include`/`Exclude` matching your layering. |
@@ -61,7 +65,7 @@ That's it. The plugin loads the bundled extensions and the shared defaults, so y
 | `Kata/RealWords` | on | Every name segment is a word the shipped dictionary knows — `errorcount` (smash) and `cfg` (abbreviation) both fail, with no word list to maintain. Tune via `Terms`/`BannedWords`/`AllowedNames`. |
 | `Kata/GoodMethodName` | on | One word per method name; a second word needs a role prefix (`after_fork`), a role suffix (`file_of`), or a reviewed `Terms` entry. Tune via `MaxWords`/`Prefixes`/`Suffixes`/`Terms`/`AllowedNames`. |
 | `Kata/GoodVariableName` | on | The same rule for locals, parameters, ivars, class variables, and globals; `_name` and `@_name` stay exempt. |
-| `Kata/BuilderNoun` | on | Builders named for what they return: `total`, not `calculate_total`. Tune via `BannedPrefixes`. |
+| `Kata/BuilderNoun` | on | Builders named for what they return: `total`, not `calculate_total`. Tune via `BannedPrefixes`/`AllowedNames`. |
 | `Kata/NoBooleanFlag` | on | No positional boolean arguments; split the method or use a keyword. |
 | `Kata/ConstructorDiscipline` | on | `initialize` assigns, raises, or freezes — never computes. |
 | `Kata/NoClassMethodLogic` | on | Class methods construct (`build`, `parse`, `of`, `from_*`); instances do the work. |
@@ -69,12 +73,32 @@ That's it. The plugin loads the bundled extensions and the shared defaults, so y
 | `Kata/ClockDiscipline` | on | No bare `Time.now`/`Date.today`/`.current`; inject a clock. |
 | `Kata/EnvDiscipline` | on | `ENV` reads only in the boot layer (`config/`, `bin/`, `exe/`). |
 
+## Dead configuration
+
+`doctor` reports configuration that no longer does anything: a `.rubocop.yml`
+entry for a cop the inherited configuration disables, and a
+`rubocop:disable`/`enable` comment naming a cop that is not enabled where the
+comment sits. RuboCop reports neither.
+
+```sh
+bundle exec rubocop-kata doctor          # or: doctor path/to/project
+```
+
+```
+.rubocop.yml:20: `Elegant/GoodMethodName` is disabled by the configuration this project inherits; the entry does nothing.
+lib/registry.rb:44: the directive names `Elegant/GoodMethodName`, which is not enabled here; the comment does nothing.
+2 dead entries
+```
+
+It exits non-zero when it finds something, so it can gate CI.
+
 ## The defaults
 
 Double-quoted strings, `Metrics/MethodLength: 5`, `Metrics/ClassLength: 100`,
 `Metrics/ParameterLists: 4`, 120-column lines, endless methods on one line,
-`rescue => error`, `NewCops: enable`, and heredocs counted as one line in
-spec examples. See
+`rescue => error`, `NewCops: enable`, heredocs counted as one line in spec
+examples, and no inline `rubocop:disable` comments
+(`Style/DisableCopsWithinSourceCodeDirective`). See
 [config/default.yml](config/default.yml).
 
 ## License

data/config/default.yml

@@ -11,9 +11,13 @@ AllCops:
     - "vendor/**/*"
 
 Kata/AgentNoun:
-  Description: "Name classes for the thing they are, not the work they do."
+  Description: >-
+    Name classes for the thing they are, not the work they do. `AllowedNames`
+    entries match a whole name or a trailing segment of one, so `Error` also
+    exempts `UsageError`.
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.7"
   AllowedNames:
     - Error
 
@@ -202,12 +206,14 @@ Kata/BuilderNoun:
   Description: "Builders are named for what they return; verbs are for side effects."
   Enabled: true
   VersionAdded: "0.3"
+  VersionChanged: "0.7"
   BannedPrefixes:
     - get
     - calculate
     - compute
     - retrieve
     - generate
+  AllowedNames: []
 
 Kata/NoBooleanFlag:
   Description: "A boolean flag is two methods trapped in one."
@@ -379,6 +385,11 @@ Layout/EmptyLinesAroundAccessModifier:
 Layout/EmptyLinesAfterModuleInclusion:
   Enabled: false
 
+# --- A disable comment is a note saying what the code should have said;
+# `rubocop-kata doctor` finds the ones core cannot see.
+Style/DisableCopsWithinSourceCodeDirective:
+  Enabled: true
+
 # --- Correctors known to rewrite code incorrectly; report only.
 # Inlines a variable past side effects (ivar resets, later statements) and
 # corrupts Ruby 3.1 keyword shorthand.

data/exe/rubocop-kata

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubocop-kata"
+require "rubocop/kata/checkup"
+
+abort("usage: rubocop-kata doctor [path]") unless ARGV.first == "doctor"
+
+exit(RuboCop::Kata::Checkup.new(ARGV.fetch(1, Dir.pwd)).run)

data/lib/rubocop/cop/kata/agent_noun.rb

@@ -2,8 +2,10 @@
 
 class RuboCop::Cop::Kata::AgentNoun < RuboCop::Cop::Base
   MSG = "`%s` names a doer; name the class for the thing it is, not the work it does."
-
+  HINT = "#{MSG} Try `%s`.".freeze
   SUFFIX = /(?:er|or)\z/
+  SEGMENT = /[A-Z]+(?=[A-Z][a-z]|\z)|[A-Z][a-z0-9]*/
+  DERIVATIONS = [[/ator\z/, "ation"], [/ector\z/, "ection"], [/isor\z/, "ision"], [/i[zs]er\z/, "is"]].freeze
 
   def on_class(node) = check(node)
 
@@ -15,8 +17,29 @@ class RuboCop::Cop::Kata::AgentNoun < RuboCop::Cop::Base
     name = node.identifier.short_name.to_s
     return unless SUFFIX.match?(name)
     return if allowed?(name)
-    add_offense(node.identifier, message: format(MSG, name))
+    add_offense(node.identifier, message: message(name))
+  end
+
+  def message(name)
+    hint = suggestion(name)
+    hint ? format(HINT, name, hint) : format(MSG, name)
+  end
+
+  def suggestion(name)
+    segments = name.scan(SEGMENT)
+    return proposal(segments[0..-2].join) if segments.length > 1
+    DERIVATIONS.filter_map { proposal(name.sub(it.first, it.last)) }.first
   end
 
-  def allowed?(name) = Array(cop_config["AllowedNames"]).map(&:to_s).include?(name)
+  def proposal(name)
+    return if name.empty? || SUFFIX.match?(name)
+    return unless known?(name)
+    name
+  end
+
+  def known?(name) = RuboCop::Kata::Dictionary::ENTRIES.include?(name.scan(SEGMENT).last.to_s.downcase)
+
+  def allowed?(name) = list.any? { name.end_with?(it) }
+
+  def list = Array(cop_config["AllowedNames"]).map(&:to_s).reject(&:empty?)
 end

data/lib/rubocop/cop/kata/builder_noun.rb

@@ -12,10 +12,12 @@ class RuboCop::Cop::Kata::BuilderNoun < RuboCop::Cop::Base
   def check(node)
     name = node.method_name.to_s
     verb = prefix(name)
-    return unless verb
+    return if verb.nil? || allowed?(name)
     add_offense(node.loc.name, message: format(MSG, name.delete_prefix("#{verb}_"), name))
   end
 
+  def allowed?(name) = Array(cop_config["AllowedNames"]).map(&:to_s).include?(name)
+
   def prefix(name)
     Array(cop_config["BannedPrefixes"]).map(&:to_s).find { name.start_with?("#{it}_") }
   end

data/lib/rubocop/cop/kata/real_words.rb

@@ -1,18 +1,9 @@
 # frozen_string_literal: true
 
-require "zlib"
-
 class RuboCop::Cop::Kata::RealWords < RuboCop::Cop::Base
   MSG = "%s is not in the dictionary — restore the underscore between smashed words, spell the " \
     "abbreviation out, or add it to `Terms` if it is one domain term here."
   ABBREVIATION_MSG = "%s is an abbreviation; spell the word out."
-  WORDS = File.expand_path("../../../../data/words.txt.gz", __dir__)
-  SOFTWARE = File.expand_path("../../../../data/software.txt.gz", __dir__)
-  EXTRA = File.expand_path("../../../../data/supplement.txt", __dir__)
-  DICTIONARY = Set.new(
-    [WORDS, SOFTWARE].flat_map { Zlib.gunzip(File.binread(it)).split("\n") } +
-      File.readlines(EXTRA, chomp: true)
-  ).freeze
   SIGIL = /\A(@@|@|\$)/
   DERIVATIONS = [
     [/s\z/, ""], [/es\z/, ""], [/ies\z/, "y"],
@@ -63,7 +54,7 @@ class RuboCop::Cop::Kata::RealWords < RuboCop::Cop::Base
 
   def word?(segment) = segment.length < 2 || term?(segment) || (known?(segment) && !banned?(segment))
 
-  def known?(segment) = forms(segment).any? { DICTIONARY.include?(it) }
+  def known?(segment) = forms(segment).any? { RuboCop::Kata::Dictionary::ENTRIES.include?(it) }
 
   def forms(segment)
     base = segment.sub(/\d+\z/, "")

data/lib/rubocop/kata/checkup.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+class RuboCop::Kata::Checkup
+  INERT = "%s:%d: `%s` is disabled by the configuration this project inherits; the entry does nothing."
+  DEAD = "%s:%d: the directive names `%s`, which is not enabled here; the comment does nothing."
+  TALLY = "%d dead entr%s"
+  KEY = %r{\A([A-Z]\w*/\w+):}
+
+  def initialize(root, io: $stdout)
+    @root = root
+    @io = io
+  end
+
+  def run
+    found = inert + dead
+    found.each { @io.puts(it) }
+    @io.puts(found.empty? ? "clean" : tally(found))
+    found.empty? ? 0 : 1
+  end
+
+  private
+
+  def tally(found) = format(TALLY, found.length, found.one? ? "y" : "ies")
+
+  def inert
+    entries.filter_map { |key, line| format(INERT, file, line, key) unless live?(key) }
+  end
+
+  def entries
+    lines.each_with_index.filter_map { |text, index| [text[KEY, 1], index + 1] if text.match?(KEY) }
+  end
+
+  def lines = File.file?(file) ? File.readlines(file) : []
+
+  def file = File.join(@root, ".rubocop.yml")
+
+  def live?(key) = config.cop_enabled?(key) || off?(key)
+
+  def off?(key) = project.dig(key, "Enabled") == false
+
+  def project = @_project ||= (YAML.safe_load_file(file, aliases: true) if File.file?(file)) || {}
+
+  def dead = targets.flat_map { directives(it) }
+
+  def targets = RuboCop::TargetFinder.new(store).find([@root], :only_recognized_file_types)
+
+  def directives(path)
+    RuboCop::ProcessedSource.from_file(path, config.target_ruby_version).comments
+      .map { RuboCop::DirectiveComment.new(it) }
+      .filter_map { finding(path, it) }
+  rescue StandardError
+    []
+  end
+
+  def finding(path, directive)
+    return unless directive.start_with_marker? && !directive.all_cops?
+    stale = directive.cop_names.reject { active?(it, path) }
+    return if stale.empty?
+    format(DEAD, path, directive.line_number, stale.join("`, `"))
+  end
+
+  def active?(name, path)
+    configuration = store.for_file(path)
+    cop = RuboCop::Cop::Registry.global.find_by_cop_name(name)
+    configuration.cop_enabled?(name) && cop&.new(configuration)&.relevant_file?(path)
+  end
+
+  def config = @_config ||= store.for_dir(@root)
+
+  def store = @_store ||= RuboCop::ConfigStore.new
+end

data/lib/rubocop/kata/dictionary.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module RuboCop::Kata::Dictionary
+  WORDS = File.expand_path("../../../data/words.txt.gz", __dir__)
+  SOFTWARE = File.expand_path("../../../data/software.txt.gz", __dir__)
+  EXTRA = File.expand_path("../../../data/supplement.txt", __dir__)
+  ENTRIES = Set.new(
+    [WORDS, SOFTWARE].flat_map { Zlib.gunzip(File.binread(it)).split("\n") } +
+      File.readlines(EXTRA, chomp: true)
+  ).freeze
+end

data/lib/rubocop/kata/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Kata
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/rubocop-kata.rb

@@ -27,5 +27,6 @@ require_relative "rubocop/cop/kata/no_hash_as_object"
 require_relative "rubocop/cop/kata/no_util_name"
 require_relative "rubocop/cop/kata/prose_placement"
 require_relative "rubocop/cop/kata/real_words"
+require_relative "rubocop/kata/dictionary"
 require_relative "rubocop/kata/plugin"
 require_relative "rubocop/kata/version"

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-kata
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Giacomo GK
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -115,7 +115,8 @@ description: Bundles a curated RuboCop stack (rspec, performance, elegant, packa
   NoBooleanFlag, NoHashAsObject, ProsePlacement).
 email:
 - giaco@hey.com
-executables: []
+executables:
+- rubocop-kata
 extensions: []
 extra_rdoc_files: []
 files:
@@ -128,6 +129,7 @@ files:
 - data/software.txt.gz
 - data/supplement.txt
 - data/words.txt.gz
+- exe/rubocop-kata
 - lib/rubocop-kata.rb
 - lib/rubocop/cop/kata/agent_noun.rb
 - lib/rubocop/cop/kata/builder_noun.rb
@@ -144,6 +146,8 @@ files:
 - lib/rubocop/cop/kata/no_util_name.rb
 - lib/rubocop/cop/kata/prose_placement.rb
 - lib/rubocop/cop/kata/real_words.rb
+- lib/rubocop/kata/checkup.rb
+- lib/rubocop/kata/dictionary.rb
 - lib/rubocop/kata/plugin.rb
 - lib/rubocop/kata/version.rb
 homepage: https://github.com/giacope/rubocop-kata