AGENTS.md

1# AI Agent Guide for RuboCop
2 
3RuboCop is a Ruby static code analyzer and formatter.
4Before contributing, read [CONTRIBUTING.md](CONTRIBUTING.md) and the
5[development docs](https://docs.rubocop.org/rubocop/development.html).
6 
7## Essential Commands
8 
9```bash
10bundle exec rake              # Full CI: codespell + doc syntax check + specs + self-lint
11bundle exec rake spec         # Run specs (Parser)
12bundle exec rake prism_spec   # Run specs (Prism parser)
13bundle exec rake internal_investigation  # RuboCop linting itself
14bundle exec rubocop --only Department/CopName  # Lint with a single cop
15```
16 
17Always run `bundle exec rake` before opening a PR.
18 
19## Project Layout
20 
21```
22lib/rubocop/cop/<department>/<cop_name>.rb   # Cop source
23spec/rubocop/cop/<department>/<cop_name>_spec.rb  # Cop spec
24config/default.yml                           # Default configuration for every cop
25changelog/                                   # Pending changelog entries (one per file)
26lib/rubocop/cop/<department>.rb              # Department module with `register_cop` directives for lazy loading (auto-updated by generator)
27```
28 
29Departments: `Bundler`, `Gemspec`, `Layout`, `Lint`, `Metrics`, `Migration`,
30`Naming`, `Security`, `Style`, `InternalAffairs`.
31 
32## Creating a New Cop
33 
34Scaffold:
35 
36```bash
37bundle exec rake 'new_cop[Department/CopName]'
38```
39 
40This generates the source file, spec file, `config/default.yml` entry, and
41a `register_cop` directive in the department module (`lib/rubocop/cop/<department>.rb`),
42which registers the cop for lazy loading. After generation:
43 
441. Update the description in `config/default.yml`.
452. Implement the cop.
463. Write specs.
474. Add a changelog entry: `bundle exec rake changelog:new`.
48 
49### Cop Class Structure
50 
51```ruby
52# frozen_string_literal: true
53 
54module RuboCop
55  module Cop
56    module Style
57      # One-line summary starting with a verb (e.g. "Checks for …", "Enforces …").
58      # Additional detail paragraph(s) if needed.
59      #
60      # @safety
61      #   Explain why autocorrect may be unsafe, or delete this section.
62      #
63      # @example
64      #   # bad
65      #   bad_code
66      #
67      #   # good
68      #   good_code
69      #
70      class MyCop < Base
71        extend AutoCorrector
72 
73        MSG = 'Use `#good_method` instead of `#bad_method`.'
74        RESTRICT_ON_SEND = %i[bad_method].freeze
75 
76        # @!method bad_method?(node)
77        def_node_matcher :bad_method?, <<~PATTERN
78          (send nil? :bad_method ...)
79        PATTERN
80 
81        def on_send(node)
82          return unless bad_method?(node)
83 
84          add_offense(node) do |corrector|
85            corrector.replace(node, 'good_method')
86          end
87        end
88        alias on_csend on_send
89      end
90    end
91  end
92end
93```
94 
95Key conventions:
96 
97- **`RESTRICT_ON_SEND`** — list method names so `on_send` is only called for
98  those methods (performance optimization). Required when using `on_send`.
99- **`alias on_csend on_send`** — handle safe navigation (`&.`). Add this
100  whenever you define `on_send`, unless the cop explicitly does not apply to
101  safe navigation.
102- **`alias on_numblock on_block`** and **`alias on_itblock on_block`** — handle
103  numbered-parameter blocks (`_1`) and `it`-blocks. Add these whenever you
104  define `on_block`.
105- **`extend AutoCorrector`** — declare this when the cop provides autocorrect.
106- **`def_node_matcher`** / **`def_node_search`** — DSL for AST pattern matching.
107  Document with a `@!method` YARD tag above each matcher.
108- **YARD `@example`** — every cop must have at least one `# bad` / `# good`
109  example pair. Examples must be **valid Ruby syntax** (the CI doc-syntax check
110  parses them).
111- **Cop description** — the first line of the YARD comment must be a complete
112  sentence starting with a verb and ending with a period.
113 
114## Writing Specs
115 
116```ruby
117# frozen_string_literal: true
118 
119RSpec.describe RuboCop::Cop::Style::MyCop, :config do
120  it 'registers an offense when using `#bad_method`' do
121    expect_offense(<<~RUBY)
122      bad_method(foo)
123      ^^^^^^^^^^^^^^^ Use `#good_method` instead of `#bad_method`.
124    RUBY
125 
126    expect_correction(<<~RUBY)
127      good_method(foo)
128    RUBY
129  end
130 
131  it 'does not register an offense when using `#good_method`' do
132    expect_no_offenses(<<~RUBY)
133      good_method(foo)
134    RUBY
135  end
136end
137```
138 
139- **`expect_offense`** — `^` carets mark the offense range and must align
140  exactly under the offending code. The message follows the last caret.
141- **`expect_correction`** — expected source after autocorrect. Must follow
142  `expect_offense` in the same example.
143- **`expect_no_offenses`** — assert no violations.
144- Use `%{variable}` in `expect_offense` heredocs to interpolate dynamic values.
145- Use `_{variable}` for offense-range placeholders.
146- Use RSpec metadata tags like `:ruby27`, `:ruby34` to set the target Ruby
147  version for a test.
148- Configuration: `let(:cop_config) { { 'EnforcedStyle' => 'bar' } }`.
149 
150## Changelog Entries
151 
152Every user-visible change needs a changelog entry:
153 
154```bash
155bundle exec rake changelog:fix    # Bug fix
156bundle exec rake changelog:new    # New feature
157bundle exec rake changelog:change # Changed behavior
158```
159 
160Format (single line):
161 
162```
163* [#123](https://github.com/rubocop/rubocop/issues/123): Description. ([@username][])
164```
165 
166- Must end with `([@username][])`.
167- `spec/project_spec.rb` validates the format in CI.
168- Skip the changelog only for purely internal changes (refactors with no
169  user-visible effect).
170 
171## PR and Commit Conventions
172 
173- Prefix commit messages with `[Fix #N]` when an issue exists.
174- Each distinct fix belongs in its own logical commit. When a PR bundles several
175  unrelated fixes (e.g. multiple cops, multiple false positives), give each one a
176  separate commit with its own changelog entry rather than squashing them all
177  into a single commit. Squash only commits that are part of the *same* fix.
178- Run `bundle exec rake` and ensure it passes before pushing.
179 
180## Common Mistakes
181 
1821. **Missing `alias on_csend on_send`** — cops that check `on_send` must also
183   handle safe navigation unless explicitly inapplicable.
1842. **Missing `alias on_numblock on_block` / `alias on_itblock on_block`** —
185   cops that check `on_block` must also handle numbered-parameter and
186   `it`-parameter block forms.
1873. **Invalid Ruby in YARD examples** — the CI `documentation_syntax_check` task
188   parses every `@example` block. Use only valid syntax.
1894. **Cop description not a sentence** — must start with a verb and end with a
190   period (e.g. `# Checks for ...`, not `# Check for ...`).
1915. **Missing `RESTRICT_ON_SEND`** — always define this when using `on_send`.
1926. **Missing `@!method` YARD tag** — every `def_node_matcher` /
193   `def_node_search` needs a `@!method` tag above it.
1947. **Forgetting changelog entry** — CI will flag it.
1958. **Manually creating changelog files** — use the rake tasks instead to get
196   the correct filename format.
1979. **Missing `extend AutoCorrector`** — required if the cop provides a
198   `corrector` block in `add_offense`.
19910. **Not running full `bundle exec rake`** — partial test runs miss lint and
200    doc-syntax failures.
20111. **Hardcoding node types instead of using node pattern matchers** — prefer
202    `def_node_matcher` over manual `node.type == :send` checks.
20312. **Not testing both `send` and `csend`** — if you alias `on_csend`, write
204    specs that cover the `&.` operator.
205