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.
- checksums.yaml +4 -4
- data/config/default.yml +184 -2
- data/lib/dev_doc/i18n/pseudo_locale.rb +1 -1
- data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb +1 -1
- data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb +6 -3
- data/lib/dev_doc/test/lints/http_driven_controller_tests.rb +2 -0
- data/lib/dev_doc/test/lints/no_file_excludes.rb +1 -1
- data/lib/dev_doc/test/pseudo_i18n_crawler.rb +4 -0
- data/lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb +44 -7
- data/lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb +2 -2
- data/lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb +1 -1
- data/lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb +2 -2
- data/lib/rubocop/cop/dev_doc/bundler/conflicting_gem.rb +74 -0
- data/lib/rubocop/cop/dev_doc/exception_class_list.rb +32 -0
- data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb +1 -1
- data/lib/rubocop/cop/dev_doc/migration/legacy_migration.rb +26 -0
- data/lib/rubocop/cop/dev_doc/migration/redundant_reference_index.rb +5 -15
- data/lib/rubocop/cop/dev_doc/migration/require_reference_index.rb +115 -0
- data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb +1 -1
- data/lib/rubocop/cop/dev_doc/rails/create_or_find_by.rb +66 -0
- data/lib/rubocop/cop/dev_doc/rails/find_or_create_by_justification.rb +106 -0
- data/lib/rubocop/cop/dev_doc/rails/no_error_message_comparison.rb +178 -0
- data/lib/rubocop/cop/dev_doc/rails/no_form_param_lookup_in_controller.rb +1 -1
- data/lib/rubocop/cop/dev_doc/rails/rescue_record_not_unique_index.rb +212 -0
- data/lib/rubocop/cop/dev_doc/rails/unique_index_backing.rb +205 -0
- data/lib/rubocop/cop/dev_doc/style/avoid_kernel_array.rb +103 -0
- data/lib/rubocop/cop/dev_doc/style/no_silent_rescue.rb +36 -26
- data/lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb +1 -1
- data/lib/rubocop/cop/dev_doc/style/rescue_justification.rb +330 -0
- data/lib/rubocop/cop/dev_doc/test/justification_covers.rb +216 -0
- data/lib/rubocop/cop/dev_doc/test/justification_header.rb +86 -5
- data/lib/rubocop/cop/dev_doc/test/require_job_invocation_in_job_tests.rb +154 -0
- data/lib/rubocop/cop/dev_doc/test/require_unit_test_justification.rb +5 -24
- data/lib/rubocop/cop/dev_doc/test/test_file_placement.rb +30 -2
- data/lib/rubocop/dev_doc/version.rb +1 -1
- 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).
|
|
11
|
-
#
|
|
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
|
-
|
|
58
|
-
comment.
|
|
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
|