rubocop-kata 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30d894b4455161e0ce3dac01fa4c627de974cf89e7d1372a610749ee9ba0ad26
-  data.tar.gz: 6bfcc2c6b38d212c8ff6ac0efc16bd4b563a74b972ccc546013619b813c0f6e2
+  metadata.gz: da7876f7f43029f7dfb90b0fb9527987fe9c50ee40336d0ba4fffdcc2cbad83f
+  data.tar.gz: 902e0c01d3cc5e71553d3c90c68a707b7f3a554cc3e6ec1228f0640ae8772d6a
 SHA512:
-  metadata.gz: f7c5bd992aa75df3b4f38c9182005dc7f346b4ea0db83e5756fb02f638acbc034b32a7146dece44e7c9421ce4d04cd064e02ce46309d6ba4513a8e5560540c5e
-  data.tar.gz: '08f28bf480cf2fcef885db1d5df0c92d3200a53b898dcc01fc026172214276a5a83a1a2b0b6bc807e2e4aed9ac78439cac6c50b7a53643986e44c05bf7a0e388'
+  metadata.gz: 99fdeb3a9f112fbc7232f59da504bde048071f20d50e55ef367e5516119a307a68a4f071a371cdbbe7810248268ef526f5bbdec08c5e9068e14d17cee03661ca
+  data.tar.gz: 9603d8560c96c877a5cb8f614bf10cab2aabf63aa5aace3209cc0596b06dab7a0edd4372919068a5c345b48cff076c1964b453ba38caa1dd3d026a96ad6c8371

data/CHANGELOG.md

@@ -1,6 +1,87 @@
 # Changelog
 
-## [Unreleased]
+## [0.8.0] - 2026-08-20
+
+- New `rubocop-kata plan` command: buckets the backlog into `structure`,
+  `naming`, `prose` and `rest`, and names the stage to take next. Kata's
+  structural cops create names and its naming cops charge for them, so the net
+  offense count moves the wrong way mid-refactor and cannot be read as progress.
+- New `rubocop-kata skill` command: prints an agent skill to stdout, so
+  redirecting it installs the skill wherever an agent reads them from. It works
+  the stage `plan` names one file at a time, checks every name it introduces
+  against the dictionary `Kata/RealWords` reads, and reports removed and
+  created separately.
+- `Kata/AgentNoun` no longer truncates a compound to its prefix. Truncation is
+  not injective — `EvidencePoller`, `EvidenceValidator` and `EvidenceWaiter`
+  were each told to become `Evidence` — and it lands on names that already
+  exist elsewhere, which a per-file cop cannot see. It now derives the agent
+  word and keeps the rest, so `EvidenceValidator` suggests
+  `EvidenceValidation`, and stays quiet when no derivation applies.
+- `Kata/AgentNoun` `AllowedNames` gains `Controller`, `Mailer` and
+  `Serializer`: suffixes a framework resolves a class by are contracts, not
+  naming choices.
+- `Kata/EnvDiscipline` no longer flags `ENV` as a parameter default.
+  `def enabled?(env = ENV)` is the injection the cop asks for: the parameter
+  is the seam, and the default is what the boot layer would pass anyway.
+- Every cop that excluded `spec/**/*` now excludes `test/**/*` too. Fifteen
+  cops shipped an RSpec-only exclusion, so a Minitest suite got the
+  production rules.
+- The boot layer that `Kata/EnvDiscipline`, `Kata/IoDiscipline` and
+  `Kata/ClockDiscipline` exempt now covers an application's, not only a gem's:
+  `config/`, `db/seeds.rb`, `db/seeds/`, `lib/tasks/`, `Rakefile` and
+  `*.rake`, alongside `bin/` and `exe/`.
+- `Kata/NoComments` now exempts `Gemfile` as it already exempts `*.gemspec`. A
+  dependency manifest cannot say why a dependency is pinned in code.
+- `Metrics/MethodLength` counts an array, hash, heredoc or method call that
+  spans lines as one line. `Max: 5` and `Layout/LineLength: 120` were
+  otherwise unsatisfiable together: wrapping a long line spent method budget.
+- `Layout/ArgumentAlignment` now uses `with_fixed_indentation`. Its default
+  aligns continuation arguments under the first argument's column, a step
+  `Elegant/MonotonicIndents` rejects.
+- `Layout/EmptyLinesAroundAttributeAccessor` is off. It requires a blank line
+  after `attr_reader` where `Elegant/NoEmptyLinesInBlocks` forbids one; inside
+  an `included do` block the two autocorrect in a loop.
+- `Lint/NumberConversion` is off. Its message names a replacement that
+  raises: `Integer(x, 10)` is only valid when `x` is a String, and a `.to_i`
+  receiver is usually a Time, a BigDecimal or an Integer.
+- The five bundled cops that exempt test files now also match Rails'
+  `foo_test.rb`, `foo_spec.rb`, and suites addressed by directory. Upstream
+  matched `**/*Test.rb` and `**/test_*.rb` only.
+- `Elegant/ClassInModule` is off. Its offenses cannot be cleared: it reports a
+  class nested in a class as global, and `Elegant/NoClassInModule` forbids the
+  module its message asks for, so the pair admits no shape. It also reads a
+  top-level constant as a defect, which is how Rails resolves one. Reported
+  upstream as yegor256/rubocop-elegant#75.
+- `Elegant/PairedBrackets` autocorrect is off. It inserts a newline beside a
+  bracket without taking the whitespace already there, so corrected lines drift
+  right and `Elegant/MonotonicIndents` then reports the line it just wrote. The
+  rule still reports; fix the brackets by hand. Reported upstream as
+  yegor256/rubocop-elegant#76.
+- Development runs against giacope/rubocop-elegant#fixes, the released gem plus
+  five open pull requests. A gemspec cannot name a git source, so consumers who
+  want the fixes rather than the workarounds add the same line to their own
+  Gemfile; the README says how.
+
+## [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`:
@@ -49,32 +53,133 @@ bundle exec rubocop
 
 That's it. The plugin loads the bundled extensions and the shared defaults, so your `.rubocop.yml` keeps only what's specific to your project. Requires Ruby >= 3.4 and RuboCop ~> 1.75.
 
+### The bundled rubocop-elegant
+
+The released `rubocop-elegant` 0.7.1 has four defects this project reported
+upstream: `NoRedundantVariable` autocorrect corrupts Ruby 3.1 shorthand
+([#74](https://github.com/yegor256/rubocop-elegant/issues/74)), `ClassInModule`
+reports a class nested in a class as global
+([#75](https://github.com/yegor256/rubocop-elegant/issues/75)),
+`PairedBrackets` autocorrect drifts the indent
+([#76](https://github.com/yegor256/rubocop-elegant/issues/76)), and the
+test-file exclusions never match a Rails or RSpec suite
+([#77](https://github.com/yegor256/rubocop-elegant/issues/77)).
+
+The defaults here neutralise all four. `Elegant/ClassInModule` is off, because
+its offences cannot be cleared: the cop it ships beside forbids the module it
+asks for. The two broken correctors are set to report only, because their
+offences can be cleared, by hand. The exclusions are widened. Nothing corrupts
+your code out of the box, and nothing reports a defect you cannot fix.
+
+A gemspec cannot name a git source, so to take the fixes themselves rather than
+the workarounds, add this to your own `Gemfile`:
+
+```ruby
+gem "rubocop-elegant", github: "giacope/rubocop-elegant", branch: "fixes"
+```
+
+That branch is the released gem plus the five pull requests, with the version
+pinned so Bundler resolves it. With it in place you can turn the two correctors
+back on:
+
+```yaml
+Elegant/NoRedundantVariable:
+  AutoCorrect: true
+
+Elegant/PairedBrackets:
+  AutoCorrect: true
+
+Elegant/ClassInModule:
+  Enabled: true
+```
+
+Drop all three once upstream releases the fixes. On a Rails codebase, consider
+leaving `Elegant/ClassInModule` off for good: it wants every class inside a
+module, and Zeitwerk resolves `class Account` from `app/models/account.rb` as a
+top-level constant by design.
+
 ## The cops
 
 | 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/IoDiscipline` | on | No bare `puts`/`warn`/`pp`/`p` outside the test suite and the boot layer; 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. |
 | `Kata/NoUtilName` | on | No junk-drawer names (`Util`, `Helper`, `Manager`, `Service`, …). Tune via `BannedNames`. |
 | `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. |
 | `Kata/NoHashAsObject` | on | A hash with `MaxKeys`+ keys (default 4) wants to be an object. Keyword-argument call sites exempt. |
 | `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/`). |
+| `Kata/EnvDiscipline` | on | `ENV` reads only in the boot layer (`config/`, `db/seeds*`, `lib/tasks/`, rake files, `bin/`, `exe/`) — or as a parameter default, which is the seam the cop asks for. |
+
+## 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.
+
+## Adoption order
+
+Kata's structural cops create names and its naming cops charge for them, so a
+structural refactor removes offenses and adds more. A single total cannot tell
+progress from regression. `plan` buckets the backlog into the stages that cause
+each other and names the one to take next.
+
+```sh
+bundle exec rubocop-kata plan            # or: plan path/to/project
+```
+
+```
+structure     184  Kata/ConstructorDiscipline 92, Kata/NoHashAsObject 48, Kata/EnvDiscipline 44
+naming        263  Kata/RealWords 141, Kata/GoodVariableName 88, Kata/AgentNoun 34
+prose          57  Kata/NoComments 57
+rest          412  Elegant/PairedBrackets 300, Layout/LineLength 112
+next: structure — 184 offenses in 61 files; these mint the names `naming` then prices, so take them first
+densest: app/models/account.rb (14)
+```
+
+Structure before naming, because doing naming first means renaming things the
+structural pass is about to move.
+
+The gem also ships an agent skill that runs this loop: it works the stage `plan`
+names, checks every name it introduces against the same dictionary
+`Kata/RealWords` reads, and reports removed and created separately instead of a
+net total.
+
+```sh
+mkdir -p .claude/skills/rubocop-kata
+bundle exec rubocop-kata skill > .claude/skills/rubocop-kata/SKILL.md
+```
+
+It writes to stdout, so the same command installs it anywhere an agent reads
+skills from — a project, `~/.claude/skills/`, or a plugin.
 
 ## 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,19 +11,31 @@ 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`. The default list holds the suffixes a framework
+    resolves a class by, which are contracts rather than naming choices.
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.8"
   AllowedNames:
     - Error
+    - Controller
+    - Mailer
+    - Serializer
 
 Kata/NoComments:
   Description: "Say it in the code; keep only comments the machine or the law reads."
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "*.gemspec"
+    - "Gemfile"
+    - "**/Gemfile"
 
 Kata/GoodMethodName:
   Description: >-
@@ -141,11 +153,18 @@ Kata/IoDiscipline:
   Description: "Write through an injected io, not bare puts/warn/pp/p."
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
     - "Rakefile"
+    - "**/*.rake"
     - "*.gemspec"
 
 Kata/ProsePlacement:
@@ -202,12 +221,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."
@@ -215,6 +236,7 @@ Kata/NoBooleanFlag:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Kata/ConstructorDiscipline:
   Description: "Constructors assign; they do not compute."
@@ -222,6 +244,7 @@ Kata/ConstructorDiscipline:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Kata/NoClassMethodLogic:
   Description: "Classes construct; instances work."
@@ -229,6 +252,7 @@ Kata/NoClassMethodLogic:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
   AllowedNames:
     - build
     - parse
@@ -241,27 +265,43 @@ Kata/NoHashAsObject:
   MaxKeys: 4
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "config/**/*"
 
 Kata/ClockDiscipline:
   Description: "Read time from an injected clock, not the ambient one."
   Enabled: true
   VersionAdded: "0.3"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
+    - "Rakefile"
+    - "**/*.rake"
+    - "*.gemspec"
 
 Kata/EnvDiscipline:
   Description: "ENV belongs in the boot layer; pass configuration in."
   Enabled: true
   VersionAdded: "0.3"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
-    - "config/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
     - "Rakefile"
+    - "**/*.rake"
     - "*.gemspec"
 
 Style/Documentation:
@@ -308,26 +348,42 @@ Layout/LineEndStringConcatenationIndentation:
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "*.gemspec"
 
 Metrics/ClassLength:
   Max: 100
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+    - "**/*_test.rb"
 
 Metrics/ModuleLength:
   Max: 100
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
+    - "**/*_test.rb"
 
+# A wrapped call reads as one line, so it costs one; otherwise Max and
+# Layout/LineLength cannot both be satisfied.
 Metrics/MethodLength:
   Max: 5
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Metrics/ParameterLists:
   Max: 4
   CountKeywordArgs: true
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 RSpec/ExampleLength:
   CountAsOne:
@@ -339,10 +395,12 @@ RSpec/VerifiedDoubles:
 Elegant/NoEmptyLinesInBlocks:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Elegant/NoEmptyLinesInMethods:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Elegant/NoComments:
   Enabled: false
@@ -364,6 +422,16 @@ Layout/ClosingParenthesisIndentation:
 Layout/FirstArgumentIndentation:
   Enabled: false
 
+# Its default aligns continuation arguments under the first argument's column,
+# an arbitrary step Elegant/MonotonicIndents rejects; a fixed step is +2.
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+# Requires a blank line after `attr_reader` where Elegant/NoEmptyLinesInBlocks
+# forbids one; inside an `included do` block the two loop.
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: false
+
 Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
@@ -379,21 +447,32 @@ 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.
 Elegant/NoRedundantVariable:
   AutoCorrect: false
 
+# Inserts a newline beside a bracket without taking the whitespace already
+# there, so every corrected line drifts right and MonotonicIndents then
+# reports the line it just wrote.
+Elegant/PairedBrackets:
+  AutoCorrect: false
+
 # Rewrites reopened classes into modules, clashing with the primary
 # class definition at boot.
 Style/StaticClass:
   AutoCorrect: false
 
-# Turns lenient `.to_i` into strict Integer(x, 10), which raises on
-# nils/Integers call sites legitimately receive.
+# Its message names a replacement that raises: Integer(x, 10) is only
+# valid when x is a String, and most `.to_i` receivers are not.
 Lint/NumberConversion:
-  AutoCorrect: false
+  Enabled: false
 
 # Alphabetizing requires breaks load-order-dependent boot sequences.
 Style/RequireOrder:
@@ -402,3 +481,39 @@ Style/RequireOrder:
 ThreadSafety/DirChdir:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
+
+# --- Elegant's test-file exclusions never match Rails' `foo_test.rb`, nor a
+# suite addressed by directory.
+# Off until upstream ships: it reports a class nested in a class as global, and
+# Elegant/NoClassInModule forbids the module the message asks for, so the pair
+# admits no shape. It also reads a top-level constant as a defect, which is how
+# Rails resolves one. https://github.com/yegor256/rubocop-elegant/issues/75
+Elegant/ClassInModule:
+  Enabled: false
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+
+Elegant/NoClassInModule:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+
+Elegant/OneClassPerFile:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+

data/exe/rubocop-kata

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubocop-kata"
+require "rubocop/kata/checkup"
+require "rubocop/kata/plan"
+require "rubocop/kata/kit"
+
+COMMANDS = { "doctor" => RuboCop::Kata::Checkup, "plan" => RuboCop::Kata::Plan, "skill" => RuboCop::Kata::Kit }.freeze
+
+command = COMMANDS[ARGV.first]
+abort("usage: rubocop-kata #{COMMANDS.keys.join("|")} [path]") if command.nil?
+
+exit(command.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,33 @@ 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 allowed?(name) = Array(cop_config["AllowedNames"]).map(&:to_s).include?(name)
+  def suggestion(name)
+    head, tail = split(name)
+    DERIVATIONS.filter_map { proposal(head + tail.sub(it.first, it.last)) }.first
+  end
+
+  def split(name)
+    segments = name.scan(SEGMENT)
+    [segments[0..-2].join, segments.last.to_s]
+  end
+
+  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/env_discipline.rb

@@ -6,6 +6,11 @@ class RuboCop::Cop::Kata::EnvDiscipline < RuboCop::Cop::Base
   def on_const(node)
     return unless node.short_name == :ENV
     return unless node.namespace.nil? || node.namespace.cbase_type?
+    return if seam?(node)
     add_offense(node, message: MSG)
   end
+
+  private
+
+  def seam?(node) = node.each_ancestor(:optarg, :kwoptarg).any?
 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/kit.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class RuboCop::Kata::Kit
+  SOURCE = File.expand_path("../../../skills/rubocop-kata/SKILL.md", __dir__)
+  MISSING = "the gem ships no skill at %s"
+
+  def initialize(_root, io: $stdout)
+    @io = io
+  end
+
+  def run
+    return missing unless File.file?(SOURCE)
+    @io.print(File.read(SOURCE))
+    0
+  end
+
+  private
+
+  def missing
+    @io.puts(format(MISSING, SOURCE))
+    1
+  end
+end

data/lib/rubocop/kata/plan.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+class RuboCop::Kata::Plan
+  STAGES = {
+    "structure" => %w[
+      Kata/ConstructorDiscipline Kata/NoClassMethodLogic Kata/NoHashAsObject
+      Kata/NoBooleanFlag Kata/IoDiscipline Kata/ClockDiscipline Kata/EnvDiscipline
+    ],
+    "naming" => %w[
+      Kata/RealWords Kata/GoodMethodName Kata/GoodVariableName Kata/AgentNoun
+      Kata/BuilderNoun Kata/NoUtilName
+    ],
+    "prose" => %w[Kata/NoComments Kata/ProsePlacement]
+  }.freeze
+  REST = "rest"
+  ROW = "%-10s %6d  %s"
+  NEXT = "next: %s — %d offense%s in %d file%s%s"
+  MINTS = "; these mint the names `naming` then prices, so take them first"
+  DENSE = "densest: %s (%d)"
+  CLEAN = "clean"
+
+  def initialize(root, io: $stdout)
+    @root = root
+    @io = io
+  end
+
+  def run
+    found = offenses
+    return clean if found.empty?
+    STAGES.keys.push(REST).each { row(it, found) }
+    advise(found)
+    1
+  end
+
+  private
+
+  def clean
+    @io.puts(CLEAN)
+    0
+  end
+
+  def row(stage, found)
+    picked = within(found, stage)
+    return if picked.empty?
+    @io.puts(format(ROW, stage, picked.length, breakdown(picked)))
+  end
+
+  def breakdown(picked)
+    picked.group_by { it.fetch("cop") }
+      .sort_by { |_, list| -list.length }
+      .first(3)
+      .map { |cop, list| "#{cop} #{list.length}" }
+      .join(", ")
+  end
+
+  def advise(found)
+    picked = within(found, upcoming(found))
+    @io.puts(headline(upcoming(found), picked))
+    @io.puts(format(DENSE, *hottest(picked)))
+  end
+
+  def upcoming(found) = STAGES.keys.find { |stage| within(found, stage).any? } || REST
+
+  def headline(stage, picked)
+    files = picked.map { it.fetch("path") }.uniq
+    format(NEXT, stage, picked.length, plural(picked), files.length, plural(files), note(stage))
+  end
+
+  def note(stage) = stage == REST ? "" : MINTS
+
+  def hottest(picked) = picked.map { it.fetch("path") }.tally.max_by(&:last)
+
+  def plural(list) = list.one? ? "" : "s"
+
+  def within(found, stage) = found.select { it.fetch("stage") == stage }
+
+  def offenses = report.fetch("files", []).flat_map { rows(it) }
+
+  def rows(file)
+    file.fetch("offenses", []).map do
+      { "path" => file.fetch("path"), "cop" => it.fetch("cop_name"), "stage" => stage(it.fetch("cop_name")) }
+    end
+  end
+
+  def stage(cop) = STAGES.find { |_, cops| cops.include?(cop) }&.first || REST
+
+  def report = @_report ||= JSON.parse(inspection)
+
+  def inspection = Dir.chdir(@root) { sweep }
+
+  def sweep
+    Tempfile.create("rubocop-kata-plan") do |sink|
+      RuboCop::CLI.new.run(["--format", "json", "--out", sink.path, "."])
+      File.read(sink.path)
+    end
+  end
+end

data/lib/rubocop/kata/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Kata
-    VERSION = "0.6.0"
+    VERSION = "0.8.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"

data/skills/rubocop-kata/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: rubocop-kata
+description: >-
+  Adopt rubocop-kata's rules on an existing codebase without the offense count going
+  the wrong way. Kata's structural cops (ConstructorDiscipline, NoHashAsObject,
+  Io/Clock/EnvDiscipline, NoClassMethodLogic, NoBooleanFlag) create names, and its naming
+  cops (RealWords, GoodMethodName, GoodVariableName, AgentNoun, BuilderNoun, NoUtilName)
+  charge for every name created — so a structural refactor removes offenses and adds more,
+  and a single total cannot tell progress from regression. This skill sequences the work by
+  stage, picks names that are already clean by checking them against the dictionary the cops
+  read, and reports removed and created separately. Use when adopting rubocop-kata, working
+  down a large kata backlog, deciding what to fix next, or when kata offenses went up after a
+  refactor. Triggers on "rubocop-kata", "kata offenses", "kata offences", "kata backlog",
+  "adopt kata".
+---
+
+# rubocop-kata adoption
+
+> The count goes up mid-refactor because the refactor is doing its job. Stop reading the
+> total; read the two numbers underneath it.
+
+## The problem this solves
+
+Move a collaborator out of a constructor and you satisfy `Kata/ConstructorDiscipline`. You
+also mint a parameter, an ivar, and probably a reader — three names, each priced by
+`Kata/RealWords`, `Kata/GoodVariableName`, and `Kata/BuilderNoun`. Net offenses can rise
+while the code strictly improves. There is no configuration that fixes this, because the
+names are real and someone has to choose them.
+
+So choose them well the first time. Every name is checkable *before* it is written, against
+the same dictionary the cops read. Do that and the naming debt is never created.
+
+## Procedure
+
+### 1. Clear dead configuration first
+
+```
+rubocop-kata doctor
+```
+
+It reports `.rubocop.yml` entries for cops the inherited config already disables, and
+`rubocop:disable` comments naming a cop that is not enabled where the comment sits. RuboCop
+reports neither. Delete what it names — it is free, and it stops you tuning knobs that are
+not connected to anything.
+
+### 2. Read the plan
+
+```
+rubocop-kata plan
+```
+
+It buckets every offense into four stages and names the one to work:
+
+- **structure** — the cops that change the shape of the code, and in doing so mint names.
+- **naming** — the cops that price names.
+- **prose** — `NoComments`, `ProsePlacement`.
+- **rest** — bundled and core cops; mostly mechanical, mostly autocorrectable.
+
+Work the stage `plan` names, in that order. Structure before naming is the whole point: doing
+naming first means renaming things the structural pass is about to move or delete.
+
+### 3. Work one file at a time
+
+Take the file `plan` calls densest. Fix its offenses for the **current stage only** — leave
+the other stages' offenses alone even when they are on the line you are editing. Mixing
+stages is what makes a diff unreviewable and a count unreadable.
+
+For `rest`, prefer `rubocop -a` (safe corrections). Do not run `-A` (unsafe) across a
+codebase; kata turns off the correctors known to rewrite code wrongly, but unsafe correctors
+outside that list still change behaviour.
+
+### 4. Check every name before you write it
+
+This is the step that keeps the count honest. Kata's naming rules, condensed:
+
+| rule | cop |
+| --- | --- |
+| one word, lowercase, ≤16 chars | `GoodMethodName`, `GoodVariableName` |
+| a second word only via a role prefix (`after_fork`), a role suffix (`file_of`), or a reviewed `Terms` entry | same |
+| never smash the underscore out — `errorcount` fails too | `RealWords` |
+| every segment is a real word; no `cfg`, `ctx`, `msg`, `tmp`, … | `RealWords` |
+| classes are not `-er`/`-or` doers | `AgentNoun` |
+| no `Util`, `Helper`, `Manager`, `Service`, `Common`, `Shared` | `NoUtilName` |
+| a method that returns something is named for what it returns, not `get_`/`calculate_`/`compute_` | `BuilderNoun` |
+| memoization ivars are `@_name` | `Naming/MemoizedInstanceVariableName` |
+
+Check a candidate against the shipped dictionary before committing to it:
+
+```
+ruby -rrubocop-kata -e 'puts ARGV.map { |w| "#{w}: #{RuboCop::Kata::Dictionary::ENTRIES.include?(w.downcase)}" }' clock sink cursor
+```
+
+If a word the domain genuinely needs is not in the dictionary, that is a `Terms` entry in
+`.rubocop.yml`, not a reason to pick a worse name — but add it deliberately, one at a time,
+and say why in the commit.
+
+When a name is genuinely two words and neither the prefix nor the suffix list fits, that is
+usually the cop telling you an object is missing. `evidence_poller` wants to be
+`Evidence#poll` or an `EvidenceValidation`. Prefer extracting the object over adding a
+`Terms` entry.
+
+### 5. Re-run `plan` and report two numbers
+
+```
+rubocop-kata plan
+```
+
+Report the delta as **removed** and **created**, never as a net total:
+
+> structure 184 → 142 (−42). naming 263 → 263 (+0 created, 21 names introduced, all clean).
+
+A rising `naming` number after a structural pass means step 4 was skipped, not that the
+refactor was wrong. Go back and fix the names you just wrote — it is cheaper now than after
+they spread.
+
+## Rules of engagement
+
+- **Never `rubocop --auto-gen-config` to make a stage disappear.** A todo file converts a
+  backlog you can see into one you cannot. If a cop is genuinely wrong for this codebase,
+  turn it off in `.rubocop.yml` with a comment saying why; `doctor` will tell you later if
+  that entry stops meaning anything.
+- **Never widen `AllowedNames`/`Terms` in bulk.** One entry, one reviewed reason.
+- **One stage per commit.** The reviewer needs to see a structural move as a structural move.
+- **Stop and ask** when a fix requires a decision you cannot verify from the code: what a
+  domain word means, whether a class is part of a public API, whether a framework resolves a
+  class by its name. Guessing on those creates rework that lints clean.

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-kata
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Giacomo GK
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -112,10 +112,13 @@ description: Bundles a curated RuboCop stack (rspec, performance, elegant, packa
   and adds fifteen cops of its own — naming (GoodMethodName, GoodVariableName, dictionary-backed
   RealWords, AgentNoun, BuilderNoun, NoUtilName), discipline (IoDiscipline, ClockDiscipline,
   EnvDiscipline, ConstructorDiscipline, NoClassMethodLogic), and shape (NoComments,
-  NoBooleanFlag, NoHashAsObject, ProsePlacement).
+  NoBooleanFlag, NoHashAsObject, ProsePlacement). The rubocop-kata command reports
+  dead configuration (doctor), buckets a backlog into the stages that cause each other
+  (plan), and prints an agent skill for working it (skill).
 email:
 - giaco@hey.com
-executables: []
+executables:
+- rubocop-kata
 extensions: []
 extra_rdoc_files: []
 files:
@@ -128,6 +131,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,8 +148,13 @@ 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/kit.rb
+- lib/rubocop/kata/plan.rb
 - lib/rubocop/kata/plugin.rb
 - lib/rubocop/kata/version.rb
+- skills/rubocop-kata/SKILL.md
 homepage: https://github.com/giacope/rubocop-kata
 licenses:
 - MIT