rubocop-dev_doc 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/config/default.yml +184 -2
  3. data/lib/dev_doc/i18n/pseudo_locale.rb +1 -1
  4. data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb +1 -1
  5. data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb +6 -3
  6. data/lib/dev_doc/test/lints/http_driven_controller_tests.rb +2 -0
  7. data/lib/dev_doc/test/lints/no_file_excludes.rb +1 -1
  8. data/lib/dev_doc/test/pseudo_i18n_crawler.rb +4 -0
  9. data/lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb +44 -7
  10. data/lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb +2 -2
  11. data/lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb +1 -1
  12. data/lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb +2 -2
  13. data/lib/rubocop/cop/dev_doc/bundler/conflicting_gem.rb +74 -0
  14. data/lib/rubocop/cop/dev_doc/exception_class_list.rb +32 -0
  15. data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb +1 -1
  16. data/lib/rubocop/cop/dev_doc/migration/legacy_migration.rb +26 -0
  17. data/lib/rubocop/cop/dev_doc/migration/redundant_reference_index.rb +5 -15
  18. data/lib/rubocop/cop/dev_doc/migration/require_reference_index.rb +115 -0
  19. data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb +1 -1
  20. data/lib/rubocop/cop/dev_doc/rails/create_or_find_by.rb +66 -0
  21. data/lib/rubocop/cop/dev_doc/rails/find_or_create_by_justification.rb +106 -0
  22. data/lib/rubocop/cop/dev_doc/rails/no_error_message_comparison.rb +178 -0
  23. data/lib/rubocop/cop/dev_doc/rails/no_form_param_lookup_in_controller.rb +1 -1
  24. data/lib/rubocop/cop/dev_doc/rails/rescue_record_not_unique_index.rb +212 -0
  25. data/lib/rubocop/cop/dev_doc/rails/unique_index_backing.rb +205 -0
  26. data/lib/rubocop/cop/dev_doc/style/avoid_kernel_array.rb +103 -0
  27. data/lib/rubocop/cop/dev_doc/style/no_silent_rescue.rb +36 -26
  28. data/lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb +1 -1
  29. data/lib/rubocop/cop/dev_doc/style/rescue_justification.rb +330 -0
  30. data/lib/rubocop/cop/dev_doc/test/justification_covers.rb +216 -0
  31. data/lib/rubocop/cop/dev_doc/test/justification_header.rb +86 -5
  32. data/lib/rubocop/cop/dev_doc/test/require_job_invocation_in_job_tests.rb +154 -0
  33. data/lib/rubocop/cop/dev_doc/test/require_unit_test_justification.rb +5 -24
  34. data/lib/rubocop/cop/dev_doc/test/test_file_placement.rb +30 -2
  35. data/lib/rubocop/dev_doc/version.rb +1 -1
  36. metadata +16 -3
@@ -0,0 +1,330 @@
1
+ module RuboCop
2
+ module Cop
3
+ module DevDoc
4
+ module Style
5
+ # Flag a block-form `rescue` clause that has no reason to exist on
6
+ # record: it rescues something other than a failure no validator can
7
+ # prevent, does not propagate, and carries no
8
+ # `rescue-reason: <category>: <why>` comment.
9
+ #
10
+ # ## Rationale
11
+ # A rescue is a claim that the operation can still fail HERE. On data
12
+ # a validator already accepted, that claim contradicts the validator:
13
+ # either the validator has a gap (close it) or the rescue is dead
14
+ # (drop it). Leaving the rescue in place is worse than either. A
15
+ # clause that turns an exception into a plausible value
16
+ # (`rescue StandardError; false`) converts a bug in our own code, or
17
+ # a value the validator should have refused, into a wrong answer
18
+ # rather than no answer: the condition "did not match", the record
19
+ # "was not found", and the symptom surfaces weeks later far from the
20
+ # cause. Reporting the exception on the way (which
21
+ # `DevDoc/Style/NoSilentRescue` asks for) does not fix this; a log
22
+ # line nobody is paged for still hides that the answer was wrong.
23
+ #
24
+ # Three kinds of clause are legitimate without a stated reason:
25
+ #
26
+ # - **Concurrency verdicts** (`ActiveRecord::RecordNotUnique`,
27
+ # `Deadlocked`, `LockWaitTimeout`, `StaleObjectError`,
28
+ # `SerializationFailure`). Validation is point-in-time; under a
29
+ # race the database constraint is the only check that holds, and
30
+ # rescuing its verdict is how the code learns it lost.
31
+ # - **I/O to another system** (`Errno::`, `Net::`, `Timeout::Error`,
32
+ # `IOError`, `EOFError`, `SocketError`, `OpenSSL::SSL::SSLError`,
33
+ # lost database connections). Nothing of ours validated the other
34
+ # side.
35
+ # - **Propagation.** A body that re-raises, raises a domain error in
36
+ # translation (`rescue JSON::ParserError => e; raise ApiError,
37
+ # ...`) or `throw`s is error translation at a boundary, not
38
+ # distrust of a value.
39
+ #
40
+ # Everything else states its reason, including parse errors of
41
+ # untrusted input: the `boundary-parse` category is one line, and
42
+ # writing it is the author asserting that the input is external and
43
+ # the parse is the validation.
44
+ #
45
+ # ## Matching is fail-closed
46
+ # RuboCop has no type information, so the cop matches each rescued
47
+ # constant AS WRITTEN (leading `::` ignored). Anything it does not
48
+ # recognise needs a marker: a bare `rescue`, `rescue => e`,
49
+ # `StandardError`, `ArgumentError`, `ActiveRecord::RecordInvalid`,
50
+ # `JSON::ParserError`, a splat (`rescue *RETRYABLE`), a method call
51
+ # in class position, and a project's own error class written
52
+ # unqualified (`rescue TimeoutError` inside a namespace that defines
53
+ # one). A clause rescuing several classes passes only when EVERY
54
+ # one is allowed. This is what keeps the cop generic: a new gem's
55
+ # error class or a new project exception never slips through by
56
+ # resembling a listed one. It either goes on the project's
57
+ # `ExpectedErrorClasses` (one reviewed config line, for a class that
58
+ # really is external I/O — an HTTP client's or a payment API's
59
+ # error root) or each rescue of it states a reason.
60
+ #
61
+ # ## What an offense means
62
+ # An offense does NOT assert the rescue is wrong; it asserts nobody
63
+ # has said why it is right. The remedies, in order of preference:
64
+ #
65
+ # 1. Drop the rescue when a validator upstream already guarantees
66
+ # the operation succeeds, or close the validator's gap so that it
67
+ # does.
68
+ # 2. Narrow it to the external classes when the failure really is
69
+ # I/O (`rescue Net::OpenTimeout, SocketError` instead of
70
+ # `rescue StandardError` around an HTTP call).
71
+ # 3. State the reason. The category is one of a closed set, so a
72
+ # reviewer can sort and audit every rescue of a codebase in one
73
+ # grep; the free text after it is what the reviewer judges.
74
+ #
75
+ # ❌ an evaluator bug becomes "the condition did not match"
76
+ # def matches?(member)
77
+ # evaluate(member)
78
+ # rescue StandardError => e
79
+ # GLog.error(e)
80
+ # false
81
+ # end
82
+ #
83
+ # ✔️ no rescue — the seed validator rejects what cannot evaluate
84
+ # def matches?(member)
85
+ # evaluate(member)
86
+ # end
87
+ #
88
+ # ✔️ one failing unit must not abort the sweep, reason stated
89
+ # members.find_each do |member|
90
+ # deliver(member)
91
+ # rescue StandardError => e # rescue-reason: bulkhead: one member's failure must not stop the batch
92
+ # GLog.error(e)
93
+ # end
94
+ #
95
+ # ## Categories
96
+ # `bulkhead` (one failure unit of a batch or async sweep must not
97
+ # abort the rest; one per unit of work, reported), `side-effect` (a
98
+ # secondary effect that must not fail the primary action it rides
99
+ # on), `degrade` (a user-facing path that degrades to a fallback and
100
+ # reports), `boundary-parse` (untrusted external input parsed here;
101
+ # the parse is the validation), `surface` (a non-bang wrapper
102
+ # turning a bang method's exception into the contract's failure
103
+ # channel, false + errors), `delivery` (a controller rendering a
104
+ # domain error raised below it). `delivery` is the one category with
105
+ # a structural signature, so the cop checks it: it is accepted only
106
+ # in files under `app/controllers/`. The other five have no static
107
+ # signature; their text is what the reviewer judges.
108
+ #
109
+ # ## Relationship with `DevDoc/Style/NoSilentRescue`
110
+ # Orthogonal. NoSilentRescue judges the BODY (does the failure leave
111
+ # a trace?); this cop judges the CLAUSE (should it exist?). A site
112
+ # can pass either and fail the other: a reported
113
+ # `rescue StandardError` passes NoSilentRescue and needs a reason
114
+ # here; a `rescue ActiveRecord::RecordNotUnique; nil` passes both
115
+ # (NoSilentRescue's `ExpectedOutcomeClasses`). The two markers are
116
+ # different on purpose and a site may carry both — a bulkhead that
117
+ # also degrades silently states each.
118
+ #
119
+ # Modifier rescues (`value rescue fallback`) are out of scope, as in
120
+ # NoSilentRescue: `Style/RescueModifier` flags every one on form
121
+ # alone, and the modifier form has no room for a marker.
122
+ #
123
+ # ## Configuration
124
+ # `JustificationMarker` (default: `rescue-reason:`) — accepted in
125
+ # three placements: trailing on the `rescue` line, in the contiguous
126
+ # block of comment-only lines ending directly above it, or in the
127
+ # body's leading comment block directly below it. Unlike
128
+ # NoSilentRescue, a comment trailing a code line above does not
129
+ # count: in a multi-clause rescue that line is the previous clause's
130
+ # body, and its reason is that clause's. The category is the first
131
+ # word after the marker, case-insensitive, ending at whitespace or
132
+ # `:`, with a trailing `-` stripped. Every marker in every placement
133
+ # is read, and one naming a valid category is enough.
134
+ #
135
+ # `ExpectedErrorClasses` — the race and I/O classes above. An entry
136
+ # ending in `::` matches a namespace (`Errno::`). Setting the key in
137
+ # a project REPLACES the default list (RuboCop's normal semantics
138
+ # for list config): copy the default from the gem's
139
+ # `config/default.yml` and append the project's external-I/O roots,
140
+ # e.g. `Stripe::StripeError`, `OAuth2::Error`, `Google::Cloud::Error`,
141
+ # `Google::Apis::ClientError`, `RestClient::`,
142
+ # `Twilio::REST::TwilioError`. `ActiveRecord::StatementInvalid` and
143
+ # `PG::Error` are deliberately absent: they carry SQL bugs as well
144
+ # as connectivity.
145
+ #
146
+ # `Categories` — `name: { Meaning: ..., Path: ... }`. `Meaning` is
147
+ # rendered into the offense message; `Path`, when present, restricts
148
+ # the category to files whose path contains it.
149
+ #
150
+ # NOTE: The propagation walk is syntactic and shared with
151
+ # NoSilentRescue: a `raise` on any branch of the body exempts the
152
+ # clause, and so does any call named `raise`/`fail`/`throw` whatever
153
+ # its receiver. One marker in an empty clause's body also sits
154
+ # directly above the next clause's `rescue` and justifies both.
155
+ # Nested bulkheads (a per-trigger rescue around a per-entity rescue
156
+ # around an evaluator rescue) span methods and are not
157
+ # detected; the markers make them a one-glance review finding
158
+ # instead — two `bulkhead` markers on one call chain. Only `app/` and
159
+ # `lib/` are inspected.
160
+ #
161
+ # @example
162
+ # # bad — StandardError around our own code, no reason
163
+ # begin
164
+ # evaluate(tree)
165
+ # rescue StandardError
166
+ # false
167
+ # end
168
+ #
169
+ # # good — a lost race is an expected verdict
170
+ # begin
171
+ # Run.create!(member: member)
172
+ # rescue ActiveRecord::RecordNotUnique
173
+ # nil
174
+ # end
175
+ #
176
+ # # good — error translation at a boundary
177
+ # begin
178
+ # JSON.parse(body)
179
+ # rescue JSON::ParserError => e
180
+ # raise ApiError, e.message
181
+ # end
182
+ #
183
+ # # good — reason stated
184
+ # begin
185
+ # JSON.parse(params[:payload])
186
+ # rescue JSON::ParserError # rescue-reason: boundary-parse: webhook body from the vendor
187
+ # head :bad_request
188
+ # end
189
+ class RescueJustification < Base
190
+ include Auth::AdjacentJustification
191
+ include ExceptionClassList
192
+ include RescueNode
193
+
194
+ MSG = 'This rescue needs a stated reason. A rescue claims the operation can still fail here; on ' \
195
+ 'data a validator already accepted, that claim contradicts the validator — fix the validator ' \
196
+ 'or drop the rescue. Only failures no validator of ours can prevent pass without one: a ' \
197
+ 'concurrency verdict (%<race>s) or I/O to another system (%<io>s; add a project\'s wrapper ' \
198
+ 'classes to ExpectedErrorClasses). First remedy: rescue those classes instead of ' \
199
+ 'StandardError. Otherwise state the reason in a "%<marker>s <category>: <why>" comment beside ' \
200
+ 'the rescue, category one of: %<categories>s. See ' \
201
+ 'best_practices/backend/en/01a_defensive_programming.md item 6.'.freeze
202
+
203
+ MSG_UNKNOWN_CATEGORY = '"%<marker>s %<given>s" is not a known category. Use one of: ' \
204
+ '%<categories>s.%<path_note>s'.freeze
205
+
206
+ RACE_CLASSES = NoSilentRescue::DEFAULT_EXPECTED_OUTCOME_CLASSES
207
+
208
+ IO_CLASSES = %w[
209
+ ActiveRecord::ConnectionNotEstablished ActiveRecord::NoDatabaseError
210
+ ActiveRecord::ConnectionTimeoutError Errno:: Net:: Timeout::Error IOError EOFError
211
+ SocketError OpenSSL::SSL::SSLError
212
+ ].freeze
213
+
214
+ DEFAULT_EXPECTED_ERROR_CLASSES = (RACE_CLASSES + IO_CLASSES).freeze
215
+
216
+ # Samples for the message: at most four names each, so it stays
217
+ # readable.
218
+ RACE_SAMPLE = RACE_CLASSES.first(4).join(', ').freeze
219
+ IO_SAMPLE = %w[Errno::* Net::* Timeout::Error SocketError].join(', ').freeze
220
+
221
+ DEFAULT_CATEGORIES = {
222
+ 'bulkhead' => { 'Meaning' => 'one failure unit of a batch or async sweep must not abort the ' \
223
+ 'rest; one per unit of work, reported' },
224
+ 'side-effect' => { 'Meaning' => 'a secondary effect that must not fail the primary action it rides on' },
225
+ 'degrade' => { 'Meaning' => 'a user-facing path that degrades to a fallback and reports (01a item 5)' },
226
+ 'boundary-parse' => { 'Meaning' => 'untrusted external input parsed here; the parse is the validation' },
227
+ 'surface' => { 'Meaning' => "a non-bang wrapper turning a bang method's exception into the " \
228
+ "contract's failure channel (false + errors)" },
229
+ 'delivery' => { 'Meaning' => 'a controller rendering a domain error raised below it',
230
+ 'Path' => 'app/controllers/' }
231
+ }.freeze
232
+
233
+ def on_resbody(node)
234
+ return if rescue_modifier?(node)
235
+ return if all_exceptions_listed?(node, expected_error_classes)
236
+ return if propagates?(node.body)
237
+
238
+ message = offense_message(node)
239
+ add_offense(node.loc.keyword, message: message) if message
240
+ end
241
+
242
+ private
243
+
244
+ # Any valid marker in any placement passes; otherwise the first one
245
+ # found names the problem. Only comment-only lines count above the
246
+ # rescue: a trailing comment on the previous clause's body belongs
247
+ # to that clause.
248
+ def offense_message(node)
249
+ comments = adjacent_marker_comments(node, standalone_only: true) + leading_body_marker_comments(node)
250
+ messages = comments.map { |comment| marker_message(category_word(comment)) }
251
+ return if messages.include?(nil)
252
+
253
+ messages.first || missing_reason_message
254
+ end
255
+
256
+ def marker_message(category)
257
+ return missing_reason_message if category.empty?
258
+
259
+ category_message(category)
260
+ end
261
+
262
+ # nil when the category is known and allowed in this file.
263
+ def category_message(category)
264
+ definition = categories[category]
265
+ return unknown_category_message(category, '') if definition.nil?
266
+
267
+ path = definition['Path']
268
+ return if path.nil? || processed_source.file_path.to_s.include?(path)
269
+
270
+ unknown_category_message(category, " (#{category} is only valid under #{path})")
271
+ end
272
+
273
+ # Same propagation half as NoSilentRescue's body walk: any
274
+ # `raise`/`fail`/`throw` anywhere in the body.
275
+ def propagates?(body)
276
+ return false if body.nil?
277
+
278
+ body.each_node(:send, :csend).any? do |call|
279
+ NoSilentRescue::PROPAGATING_METHODS.include?(call.method_name)
280
+ end
281
+ end
282
+
283
+ # The first word after the marker in the comment that carries it,
284
+ # lowercased, ending at whitespace or a `:` (so `bulkhead:one`
285
+ # reads `bulkhead`), a trailing `-` stripped. Empty when the marker
286
+ # ends the comment.
287
+ def category_word(comment)
288
+ text = comment.text.downcase
289
+ marker = justification_marker
290
+ rest = if marker.is_a?(Regexp)
291
+ text.match(marker)&.post_match.to_s
292
+ else
293
+ text.split(marker.downcase, 2).last.to_s
294
+ end
295
+ rest.strip.split(/[\s:]+/).first.to_s.sub(/-+\z/, '')
296
+ end
297
+
298
+ def missing_reason_message
299
+ format(MSG, race: RACE_SAMPLE, io: IO_SAMPLE, marker: justification_marker,
300
+ categories: rendered_categories)
301
+ end
302
+
303
+ def unknown_category_message(given, path_note)
304
+ format(MSG_UNKNOWN_CATEGORY, marker: justification_marker, given: given,
305
+ categories: rendered_categories, path_note: path_note)
306
+ end
307
+
308
+ def rendered_categories
309
+ categories.map { |name, definition| "#{name} (#{definition['Meaning']})" }.join(', ')
310
+ end
311
+
312
+ def categories
313
+ @categories ||= cop_config.fetch('Categories', DEFAULT_CATEGORIES).to_h do |name, definition|
314
+ [name.to_s.downcase, definition || {}]
315
+ end
316
+ end
317
+
318
+ def expected_error_classes
319
+ @expected_error_classes ||=
320
+ Array(cop_config.fetch('ExpectedErrorClasses', DEFAULT_EXPECTED_ERROR_CLASSES)) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one class name or a list
321
+ end
322
+
323
+ def justification_marker
324
+ cop_config.fetch('JustificationMarker', 'rescue-reason:')
325
+ end
326
+ end
327
+ end
328
+ end
329
+ end
330
+ end
@@ -0,0 +1,216 @@
1
+ require_relative 'justification_header'
2
+ require_relative 'test_file_placement'
3
+
4
+ module RuboCop
5
+ module Cop
6
+ module DevDoc
7
+ module Test
8
+ # Every test under a justification header must call a method its
9
+ # `Covers:` line lists.
10
+ #
11
+ # A justification header licenses a whole FILE at the keyboard, but
12
+ # its impossibility claim is usually about one BEHAVIOUR. The
13
+ # `Covers:` line pins the file to that claim: it names the methods
14
+ # the claim covers (`method`, `Class#method`, `Class.method` or a
15
+ # constant name, comma-separated), and every test in the file must
16
+ # call one of them. The list may wrap onto the next comment line
17
+ # only while it ends with a trailing comma — prose after a complete
18
+ # list is justification text, never entries.
19
+ #
20
+ # ## Rationale
21
+ # The shape that slipped through an approved review: a header
22
+ # justifying one method sat in an open unit file, a later test of a
23
+ # different, HTTP-reachable method was added under it, and every
24
+ # safeguard stayed silent — the placement cop is satisfied by the
25
+ # header that already exists, and the reviewer rule in the testing
26
+ # best practice triggers only when a diff edits the header itself.
27
+ # `Covers:` makes the licence explicit and moves the check to the
28
+ # keyboard: a test of an unlisted method offends here, and the only
29
+ # way to quiet the offense is to edit `Covers:` — a header edit,
30
+ # the one diff shape the reviewer rule already treats as "this
31
+ # claim needs tracing".
32
+ #
33
+ # ## Breadth
34
+ # An entry is as wide as the method it names: `valid?`, `save!` or
35
+ # `perform` on a model re-licenses most of a file. The cop cannot
36
+ # judge breadth; review judges each `Covers:` entry as it judges
37
+ # the impossibility claim itself (the testing best-practice
38
+ # reviewer rule covers this). A header whose claim covers the whole
39
+ # file lists its methods — a cron job lists `perform`, a
40
+ # rake-backed command lists its public commands. There is
41
+ # deliberately no wildcard entry.
42
+ #
43
+ # ## Exception
44
+ # None beyond extending `Covers:` with a new entry justified in the
45
+ # header; an inline disable is not the intended path. A test that
46
+ # exercises an unlisted method usually wants to be a request test —
47
+ # the escape hatch in DevDoc/Test/AvoidUnitTest lists the patterns
48
+ # (inject a failure at a chokepoint the real request hits, assert
49
+ # the observable through the real path) that make seemingly
50
+ # unit-only behaviour reachable end-to-end.
51
+ #
52
+ # NOTE: entries match on METHOD NAME — the part after the last `#`
53
+ # or `.` of each entry; receiver types are not statically knowable,
54
+ # so a `Class#`/`Class.` prefix is documentation for the reviewer,
55
+ # not a discriminator. An entry may instead name a CONSTANT (a
56
+ # drift guard over a constant matches the reference to it), and a
57
+ # literal `send`/`public_send` dispatch counts as the method it
58
+ # names. A header can also go stale: a new HTTP caller of a covered
59
+ # method re-opens what the claim licensed — no cop catches that;
60
+ # the wiring line's claim is what review checks when it drifts.
61
+ # And a header whose subject is a FILE rather than a method or
62
+ # constant (a schedule-table or config-lint guard) cannot be
63
+ # matched by any entry: name the method the test reads the file
64
+ # through, or move the check to a build-time lint.
65
+ #
66
+ # @example
67
+ # # bad — the header's claim covers merge_profiles!, but the test
68
+ # # drives create_with_defaults!, which a request reaches:
69
+ # # deliberate exception: merge_profiles! has no HTTP write path.
70
+ # # Wiring: member_merges_test drives the request write paths.
71
+ # # Covers: Member#merge_profiles!
72
+ # class MemberTest < Glib::LastResortUnitTest
73
+ # test 'create rolls back on a duplicate handle' do
74
+ # assert_raises(RecordInvalid) { member.create_with_defaults! }
75
+ # end
76
+ # end
77
+ #
78
+ # # good — the test drives the covered method:
79
+ # # deliberate exception: merge_profiles! has no HTTP write path.
80
+ # # Wiring: member_merges_test drives the request write paths.
81
+ # # Covers: Member#merge_profiles!
82
+ # class MemberTest < Glib::LastResortUnitTest
83
+ # test 'merge is idempotent' do
84
+ # 2.times { member.merge_profiles!(other) }
85
+ # end
86
+ # end
87
+ class JustificationCovers < Base
88
+ include JustificationHeader
89
+ include TestFilePlacement
90
+
91
+ MSG_MISSING = 'Justification header lacks a "%<phrase>s" line naming the methods its ' \
92
+ 'claim covers. Each test in the file must call one of them; a test of ' \
93
+ 'anything else wants a request test (see DevDoc/Test/AvoidUnitTest), or ' \
94
+ 'a header that justifies it.'.freeze
95
+
96
+ MSG_UNCOVERED = 'This test calls none of the header\'s `Covers:` methods (%<covers>s). ' \
97
+ 'Write it as a request test (see the escape hatch in ' \
98
+ 'DevDoc/Test/AvoidUnitTest), or extend `Covers:` and justify the new ' \
99
+ 'entry in the header.'.freeze
100
+
101
+ # A `perform` entry also matches the job-invocation family job tests use.
102
+ PERFORM_FAMILY = %w[perform_now perform_later perform_enqueued_jobs].freeze
103
+
104
+ # A literal `obj.send(:private_thing)` dispatches to private_thing —
105
+ # the call set counts the dispatched name, not just `send`.
106
+ DISPATCH_METHODS = %w[send public_send __send__].freeze
107
+
108
+ def on_new_investigation
109
+ # Cop instances are reused across files within a run; the
110
+ # same-file helper index is per investigation.
111
+ @same_file_defs = nil
112
+ return if processed_source.blank?
113
+ return unless justification_header_required?
114
+ # A missing header is RequireUnitTestJustification's to report;
115
+ # this cop never double-reports it.
116
+ return unless leading_comments_contain?(marker_phrase)
117
+
118
+ covers = covers_entries
119
+ if covers.empty?
120
+ add_offense(offense_range, message: format(MSG_MISSING, phrase: covers_phrase))
121
+ else
122
+ check_test_definitions(covers)
123
+ end
124
+ end
125
+
126
+ private
127
+
128
+ def check_test_definitions(covers)
129
+ accepted = covers + (covers.include?('perform') ? PERFORM_FAMILY : [])
130
+ each_test_definition do |anchor, body|
131
+ next if calls_covered?(body, accepted)
132
+
133
+ add_offense(anchor, message: format(MSG_UNCOVERED, covers: covers.join(', ')))
134
+ end
135
+ end
136
+
137
+ # `test '...' do` blocks and `def test_*` methods, each with the
138
+ # range an offense anchors on and the body whose calls count.
139
+ def each_test_definition(&)
140
+ return unless processed_source.ast
141
+
142
+ each_test_block(&)
143
+ each_test_method(&)
144
+ end
145
+
146
+ def each_test_block
147
+ processed_source.ast.each_node(:block, :numblock) do |node|
148
+ next unless node.send_node.method?(:test)
149
+
150
+ yield node.send_node.loc.selector, node.body
151
+ end
152
+ end
153
+
154
+ def each_test_method
155
+ processed_source.ast.each_node(:def) do |node|
156
+ next unless node.method_name.to_s.start_with?('test_')
157
+
158
+ yield node.loc.name, node.body
159
+ end
160
+ end
161
+
162
+ def calls_covered?(body, accepted)
163
+ calls_of(body, Set.new).any? { |name| accepted.include?(name) }
164
+ end
165
+
166
+ # The names a body references: every send/csend's method (a literal
167
+ # `send`/`public_send` argument counts as the method it dispatches
168
+ # to), every constant's name (an entry may name a constant the
169
+ # header's claim licenses), plus the bodies of same-file `def`s it
170
+ # calls, transitively. setup/teardown are never part of a test's
171
+ # body, so their fixture calls never count toward a test.
172
+ def calls_of(node, names, walked = Set.new)
173
+ return names unless node
174
+
175
+ node.each_node(:send, :csend, :const) do |child|
176
+ if child.const_type?
177
+ names << child.children.last.to_s
178
+ else
179
+ collect_call(child, names, walked)
180
+ end
181
+ end
182
+ names
183
+ end
184
+
185
+ def collect_call(call, names, walked)
186
+ name = call.method_name.to_s
187
+ names << name
188
+ collect_dispatched_name(call, names) if DISPATCH_METHODS.include?(name)
189
+
190
+ helper = same_file_defs[name]
191
+ return if helper.nil? || walked.include?(name)
192
+
193
+ walked << name
194
+ calls_of(helper.body, names, walked)
195
+ end
196
+
197
+ def collect_dispatched_name(call, names)
198
+ arg = call.first_argument
199
+ return unless arg && (arg.sym_type? || arg.str_type?)
200
+
201
+ names << arg.value.to_s
202
+ end
203
+
204
+ def same_file_defs
205
+ @same_file_defs ||= begin
206
+ defs = {}
207
+ root = processed_source.ast
208
+ root&.each_node(:def) { |defn| defs[defn.method_name.to_s] ||= defn }
209
+ defs
210
+ end
211
+ end
212
+ end
213
+ end
214
+ end
215
+ end
216
+ end
@@ -7,8 +7,9 @@ module RuboCop
7
7
  # first class/module) that contain the marker phrase (why a controller
8
8
  # test can't cover this) AND a wiring line (which request test still
9
9
  # covers the HTTP path its subject participates in — or why no runtime
10
- # HTTP path exists). Host cops must provide `offense_range` and
11
- # `cop_config`.
10
+ # HTTP path exists). The `Covers:` line (which methods the header's
11
+ # claim licenses) is parsed here too. Host cops must provide
12
+ # `cop_config`; `offense_range` is provided here.
12
13
  module JustificationHeader
13
14
  MSG_JUSTIFY = 'Unit-test file without a justification header. Controller tests catch the ' \
14
15
  'wiring bugs unit tests miss, so first assume a controller test IS possible ' \
@@ -54,9 +55,8 @@ module RuboCop
54
55
  end
55
56
 
56
57
  def leading_comments_contain?(phrase)
57
- processed_source.comments.any? do |comment|
58
- comment.location.line < first_definition_line &&
59
- comment.text.downcase.include?(phrase.downcase)
58
+ leading_comments.any? do |comment|
59
+ comment.text.downcase.include?(phrase.downcase)
60
60
  end
61
61
  end
62
62
 
@@ -70,9 +70,90 @@ module RuboCop
70
70
  (definition || root).first_line
71
71
  end
72
72
 
73
+ # The header's `Covers:` entries as matched names: the part after
74
+ # the last `#`, `.` or `::` of each comma-separated entry (a
75
+ # method entry matches its method name; a constant entry its
76
+ # constant's short name). The list wraps onto the next comment
77
+ # line only while it ends with a trailing comma (see
78
+ # fold_continuations). Empty when the header has no `Covers:`
79
+ # line at all.
80
+ def covers_entries
81
+ body = covers_comment_body
82
+ return [] if body.empty?
83
+
84
+ body.split(',').map { |entry| entry.strip.split(/::|[#.]/).last.to_s.strip }.reject(&:empty?)
85
+ end
86
+
87
+ # The text of the `Covers:` line plus its continuations, joined.
88
+ def covers_comment_body
89
+ comments = leading_comments
90
+ start = covers_comment_index(comments)
91
+ return '' if start.nil?
92
+
93
+ covers_comment = comments[start]
94
+ remainder = strip_comment_marker(covers_comment)[covers_phrase.length..].to_s
95
+ fold_continuations(comments[(start + 1)..], remainder, covers_comment.location.line + 1)
96
+ end
97
+
98
+ def covers_comment_index(comments)
99
+ comments.index { |comment| covers_line?(comment) }
100
+ end
101
+
102
+ # A continuation joins the list only while the accumulated text
103
+ # ends with a trailing comma (the list is syntactically
104
+ # incomplete) AND the line is the next physical comment line; a
105
+ # blank comment line or another header label ends it. Prose after
106
+ # a complete list is never folded in — it is justification text,
107
+ # not entries.
108
+ def fold_continuations(comments, text, next_line)
109
+ comments.each do |comment|
110
+ break unless text.rstrip.end_with?(',')
111
+ break if comment.location.line != next_line
112
+
113
+ line = strip_comment_marker(comment)
114
+ break if line.strip.empty? || labeled_line?(line)
115
+
116
+ text += " #{line}"
117
+ next_line += 1
118
+ end
119
+ text
120
+ end
121
+
122
+ # The header window: comments before the first class/module, the
123
+ # same window leading_comments_contain? matches in.
124
+ def leading_comments
125
+ processed_source.comments.select { |comment| comment.location.line < first_definition_line }
126
+ end
127
+
128
+ def covers_line?(comment)
129
+ strip_comment_marker(comment).downcase.start_with?(covers_phrase.downcase)
130
+ end
131
+
132
+ def strip_comment_marker(comment)
133
+ comment.text.sub(/\A#\s*/, '')
134
+ end
135
+
136
+ # Another header label (`Wiring:`, a second `Covers:`) ends a
137
+ # continuation: its content belongs to that line, not to Covers.
138
+ # A namespaced constant (`Registry::SEGMENT_MAP`) is NOT a label
139
+ # — the negative lookahead keeps `Registry:` from matching.
140
+ def labeled_line?(text)
141
+ text.match?(/\A[A-Za-z]\w*:(?!:)/)
142
+ end
143
+
73
144
  def marker_phrase = cop_config.fetch('MarkerPhrase', 'deliberate exception')
74
145
 
75
146
  def wiring_phrase = cop_config.fetch('WiringPhrase', 'wiring:').to_s
147
+
148
+ def covers_phrase = cop_config.fetch('CoversPhrase', 'covers:')
149
+
150
+ # The one-line range a file-level offense anchors on: the first
151
+ # line of the AST (a require, when present) or of the first
152
+ # comment. Provided here so every header cop anchors identically.
153
+ def offense_range
154
+ range = processed_source.ast&.source_range || processed_source.comments.first&.source_range
155
+ range.with(end_pos: range.begin_pos + [range.source_line.length, 1].max)
156
+ end
76
157
  end
77
158
  end
78
159
  end