rubocop-kata 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d84b32b4beb311cd73ed3af609400cc07a4a1e7fb41258e813feab7a7477ae9
-  data.tar.gz: 3038bc491f3197c6623f30f68742fda4008c4519cbacc2c95dc36e0ebc10276c
+  metadata.gz: 6c1ecc1a90d7d43dba2861011f7f9c8c1ecc97e71040908f1018df3199aca660
+  data.tar.gz: 216cb124bc0565ab89d5cf3ee52225e24771d6f4d0812e8a272b0fc14517e45e
 SHA512:
-  metadata.gz: b38144839ec596e2f646f89f2c28328978cf030d7bbc9c31deccad49fe94ad9775e75a2af69d51961cfed832f3acc7b49c32c43f0830fc98d300c8033cda1230
-  data.tar.gz: 5ab77b46b9eab5d756368860c1f40866111964217dc0fda9cda532c49574fc6472dc60fb2a091c1e3d54269b63266b956f4bfd9a900ad50528dae96a8a8dd3de
+  metadata.gz: 5a806b0b657d6fa01fe422361616304f6581e23e041f76a70d3dc33f61814a600a808439282417de3f8ea34d03612927fdfcbced3f18010b90660407ffa165f7
+  data.tar.gz: 687dd4b67fb477cd51e4440e79f7d81a020f4712c1802541447eb489f97be8fab728cb26460c947113a2789f1fddf1f0e93ecd9bad70d2eadd232cbe025bf74d

data/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## [0.9.0] - 2026-08-27
+
+- The shared rule behind the naming cops is now explicit: compound syntax is
+  not the smell — multiple semantic concepts are. A name should name one thing,
+  not describe where it came from, what it manipulates, or which layer it
+  lives in.
+- New `Kata/GoodClassName` replaces `Kata/AgentNoun` and the class half of
+  `Kata/NoUtilName`: a class names one object that exists in the model. It
+  keeps the doer check and its derived suggestions, adds junk-drawer names
+  matched whole or as a trailing segment (`Service` catches `InvoiceService`),
+  and flags names packing more than `MaxWords` concepts
+  (`CustomerOrderPayment`) unless `Terms` blesses them as one concept
+  (`CreditCard`). The default `Terms` ships the established technical
+  compounds: `AbstractSyntaxTree`, `RedBlackTree`, `UnitOfWork`,
+  `TimeWithZone`, `HashWithIndifferentAccess` and kin.
+- New `Kata/GoodModuleName` replaces the module half of `Kata/NoUtilName`: a
+  module names a domain vocabulary, not an implementation category. Layer
+  buckets (`Services`, `Helpers`, `Logic` — so `BusinessLogic` too), vague
+  shared namespaces (`Common`, `Shared`, `Core`), doer modules, and crowded
+  names are flagged; `AccessControl` and `Billing` pass.
+- `Kata/GoodMethodName` flags names chaining actions with a conjunction
+  (`validate_and_save`, `find_or_create`): each action wants its own method.
+  Traversal names (`customer_address`) were already priced by the word rule;
+  the message stays advisory — the cop cannot know your object model.
+- `Kata/GoodMethodName` and `Kata/GoodVariableName` bless grammatical
+  suffixes `id` and `ms` (`user_id`, `timeout_ms`) alongside `at`, the role
+  prefixes `max`/`min`/`start`/`end` (`max_retries`, `start_time`), and ship
+  established lexical compounds and protocol vocabulary as default `Terms`:
+  `first_name`, `postal_code`, `time_zone`, `ip_address`, `user_agent`,
+  `mime_type`, `status_code`, `access_token` and kin — names that read as one
+  concept. Where names must mirror an external schema, `Exclude` the file:
+  the file is the boundary.
+- The defaults were then pressure-tested against corpora of real stdlib, gem,
+  Rails, and business-domain names, and grew to absorb what any codebase hits:
+  role suffixes (`number`, `code`, `price`, `rate`, `date`, `path`, `url`,
+  `count`, `size`, `key`, `token`, `params`, `secret`, `level`, `file`, `dir`,
+  `period`, `seconds`, `cents`), role prefixes (`current`, `default`, `total`,
+  `new`, `other`, `raw`, `set`, `sort`, `expected`, `actual`, `assert`),
+  domain terms (`line_item`, `credit_card`, `payment_method`,
+  `billing_address`, `date_of_birth`, `dry_run`, `stack_trace` and kin), and
+  the contract names of Ruby, Rails, Sidekiq, Devise, Pundit and RSpec
+  (`perform_async`, `deconstruct_keys`, `authenticate_user!`, `policy_scope`,
+  `failure_message` and kin). Name suffixes that would bless owner+property
+  (`name`, `message`, `amount`) stayed out on purpose: `user_name` and
+  `error_message` are still priced.
+- `Kata/GoodClassName` `AllowedNames` also covers the class families a
+  framework resolves or subclasses by name (`Validator`, `Decorator`,
+  `Presenter`, `Helper`, `Job`, `Logger`, `Delegator`, `Enumerator`,
+  `Driver`) and more thing-words (`Center`, `Transfer`);
+  `Kata/GoodModuleName` mirrors the class cop's allowed list, and its
+  `BannedNames` grows the layer plurals (`Jobs`, `Workers`, `Queries`,
+  `Policies`, `Forms`, `Decorators`, `Presenters`, `Serializers`,
+  `Validators`, `Mixins`, `Extensions`).
+- The doer check no longer flags thing-words that merely end in `-er`/`-or`:
+  `User`, `Order`, `Customer`, `Monitor`, `Buffer` and kin ship in
+  `Kata/GoodClassName` `AllowedNames`. `Kata/GoodModuleName` ships the
+  framework suffixes (`Controller`, `Mailer`, `Serializer`) so reopening
+  `ActionController` is not an offense. `Kata/GoodMethodName` exempts the
+  names Ruby and Rails resolve by contract: `method_missing`,
+  `respond_to_missing?`, `marshal_dump`, `deep_dup`, `table_name`,
+  `primary_key` and kin.
+
+## [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

data/README.md

@@ -14,10 +14,10 @@ that dodge with a shipped dictionary instead of a word list you maintain:
 
 - **One dependency.** Bundles rubocop-rspec, rubocop-performance, rubocop-elegant, rubocop-packaging, and rubocop-thread_safety behind a single gem.
 - **Opinionated defaults.** Methods under 5 lines, classes under 100, 4 parameters max, 120-column lines, double quotes, `NewCops: enable`. See [config/default.yml](config/default.yml).
-- **Fifteen house cops.** Naming, dependency discipline, and data honesty in the Elegant Objects spirit — from `Kata/AgentNoun` to `Kata/ClockDiscipline`.
+- **Fifteen house cops.** Naming, dependency discipline, and data honesty in the Elegant Objects spirit — from `Kata/GoodClassName` to `Kata/ClockDiscipline`.
 
 ```ruby
-class PaymentProcessor  # Kata/AgentNoun: `PaymentProcessor` names a doer; name the class
+class PaymentProcessor  # Kata/GoodClassName: `PaymentProcessor` names a doer; name the class
 end                     #   for the thing it is, not the work it does. Try `Payment`.
 
 class Payment           # OK
@@ -53,17 +53,62 @@ 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. Suggests the better name when it can derive one. `AllowedNames` matches a whole name or a trailing segment, so `Error` covers `UsageError`. |
+| `Kata/GoodClassName` | on | A class names one object that exists in the model: no `-er`/`-or` doers (suggests the better name when it can derive one), no junk drawers (`Service`, `Util`, `Data`), no packing several concepts into one name (`CustomerOrderPayment`). Compound syntax is not the smell — `CreditCard` is one concept, and `Terms` holds those. `AllowedNames` and `BannedNames` match a whole name or a trailing segment, so `Error` covers `UsageError` and `Service` catches `InvoiceService`. |
+| `Kata/GoodModuleName` | on | A module names a domain vocabulary (`Billing`, `AccessControl`), not an implementation category: no layer buckets (`Services`, `Helpers`, `Logic`), no vague shared namespaces (`Common`, `Shared`, `Core`), no doers. Tune via `BannedNames`/`Terms`/`AllowedNames`. |
 | `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/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. A name chaining actions (`validate_and_save`, `find_or_create`) is flagged as two methods in one. 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`/`AllowedNames`. |
 | `Kata/NoBooleanFlag` | on | No positional boolean arguments; split the method or use a keyword. |
@@ -71,7 +116,7 @@ That's it. The plugin loads the bundled extensions and the shared defaults, so y
 | `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
 
@@ -92,6 +137,42 @@ lib/registry.rb:44: the directive names `Elegant/GoodMethodName`, which is not e
 
 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/GoodClassName 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`,