rubocop-dev_doc 0.17.0 → 0.19.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 +461 -62
- data/config/obsoletion.yml +7 -3
- data/lib/dev_doc/i18n/pseudo_locale.rb +1 -1
- data/lib/dev_doc/i18n/tasks.rb +68 -0
- data/lib/dev_doc/railtie.rb +19 -0
- data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb +1 -1
- data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb +8 -3
- data/lib/dev_doc/test/lints/http_driven_controller_tests.rb +4 -0
- data/lib/dev_doc/test/lints/no_file_excludes.rb +1 -1
- data/lib/dev_doc/test/pseudo_i18n_crawler.rb +9 -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/hardcoded_text.rb +243 -0
- data/lib/rubocop/cop/dev_doc/i18n/localizable_props.rb +69 -19
- data/lib/rubocop/cop/dev_doc/i18n/require_translation.rb +13 -17
- data/lib/rubocop/cop/dev_doc/i18n/text_shape.rb +94 -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_bypassing_validation.rb +81 -26
- data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb +1 -1
- data/lib/rubocop/cop/dev_doc/rails/no_error_message_comparison.rb +178 -0
- data/lib/rubocop/cop/dev_doc/rails/no_errors_add_in_controller.rb +177 -0
- data/lib/rubocop/cop/dev_doc/rails/no_form_param_lookup_in_controller.rb +236 -0
- data/lib/rubocop/cop/dev_doc/style/avoid_kernel_array.rb +103 -0
- data/lib/rubocop/cop/dev_doc/style/in_memory_association_find.rb +162 -0
- data/lib/rubocop/cop/dev_doc/style/no_silent_rescue.rb +279 -0
- data/lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb +1 -1
- data/lib/rubocop/cop/dev_doc/style/prefer_allowlist_symbol_param.rb +193 -0
- data/lib/rubocop/cop/dev_doc/style/rescue_justification.rb +330 -0
- data/lib/rubocop/cop/dev_doc/style/use_g_log.rb +133 -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/prefer_find_sole_by.rb +146 -0
- 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/cop/dev_doc/test/test_name_special_characters.rb +108 -0
- data/lib/rubocop/cop/dev_doc/view/prefer_prop_over_name.rb +11 -1
- data/lib/rubocop/dev_doc/version.rb +1 -1
- metadata +24 -4
- data/lib/rubocop/cop/dev_doc/i18n/report_text.rb +0 -76
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Rake tasks wrapping the commands in docs/localization.md, so a project runs
|
|
2
|
+
# `bin/rails dev_doc:i18n:scan` instead of copying long rubocop invocations.
|
|
3
|
+
#
|
|
4
|
+
# Loaded by DevDoc::Railtie (lib/dev_doc/railtie.rb) in projects that bundle
|
|
5
|
+
# the gem with `require: 'dev_doc/railtie'`.
|
|
6
|
+
#
|
|
7
|
+
# Tasks (paths default to `app`; pass several as `[app/views,app/mailers]`):
|
|
8
|
+
#
|
|
9
|
+
# bin/rails dev_doc:i18n:scan[paths] Recipe A — hardcoded text
|
|
10
|
+
# bin/rails dev_doc:i18n:rekey[paths] Recipe B — keys to move
|
|
11
|
+
#
|
|
12
|
+
# Each task accepts OUT=<file> to save the findings instead of printing
|
|
13
|
+
# them (Recipe C hands that file to an AI assistant), and exit with rubocop's
|
|
14
|
+
# status: 0 clean, 1 findings, 2 error.
|
|
15
|
+
require 'rake'
|
|
16
|
+
require 'fileutils'
|
|
17
|
+
|
|
18
|
+
module DevDoc
|
|
19
|
+
module I18n
|
|
20
|
+
# `dev_doc:i18n:*` rake tasks: the localization recipes' commands, runnable
|
|
21
|
+
# from a project that bundles the gem.
|
|
22
|
+
module Tasks
|
|
23
|
+
extend Rake::DSL
|
|
24
|
+
|
|
25
|
+
HARDCODED_COPS = %w[
|
|
26
|
+
DevDoc/I18n/RequireTranslation
|
|
27
|
+
DevDoc/I18n/HardcodedText
|
|
28
|
+
DevDoc/I18n/AvoidTitleizeHumanize
|
|
29
|
+
].freeze
|
|
30
|
+
RUBOCOP_TASKS = {
|
|
31
|
+
scan: [HARDCODED_COPS, 'List hardcoded user-facing text (Recipe A)'],
|
|
32
|
+
rekey: [%w[DevDoc/I18n/TranslationKeyPrefix], 'List lazy keys and keys outside AllowedPrefixes (Recipe B)']
|
|
33
|
+
}.freeze
|
|
34
|
+
DEFAULT_PATHS = %w[app].freeze
|
|
35
|
+
|
|
36
|
+
def self.define
|
|
37
|
+
namespace :dev_doc do
|
|
38
|
+
namespace :i18n do
|
|
39
|
+
RUBOCOP_TASKS.each do |name, (cops, summary)|
|
|
40
|
+
desc "#{summary}; OUT=<file> saves the findings"
|
|
41
|
+
task(name) { |_t, args| run_rubocop(cops, args.to_a) }
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def self.rubocop_args(cops, paths, out: nil)
|
|
48
|
+
args = %w[--format clang]
|
|
49
|
+
# --out binds to the --format before it, so it must follow it directly.
|
|
50
|
+
args += ['--out', out] if out
|
|
51
|
+
args + ['--only', cops.join(','), *(paths.empty? ? DEFAULT_PATHS : paths)]
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def self.run_rubocop(cops, paths)
|
|
55
|
+
require 'rubocop'
|
|
56
|
+
|
|
57
|
+
out = ENV.fetch('OUT', '')
|
|
58
|
+
out = nil if out.empty?
|
|
59
|
+
FileUtils.mkdir_p(File.dirname(out)) if out
|
|
60
|
+
status = RuboCop::CLI.new.run(rubocop_args(cops, paths, out: out))
|
|
61
|
+
puts "Findings written to #{out}" if out && status != 2
|
|
62
|
+
exit(status) unless status.zero?
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
DevDoc::I18n::Tasks.define
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Registers dev-doc's rake tasks in a Rails app. Projects name this file as the
|
|
2
|
+
# gem's require instead of `require: false`:
|
|
3
|
+
#
|
|
4
|
+
# group :development, :test do
|
|
5
|
+
# gem 'rubocop-dev_doc', require: 'dev_doc/railtie'
|
|
6
|
+
# end
|
|
7
|
+
#
|
|
8
|
+
# Booting the app loads only this Railtie; RuboCop itself is loaded when a task
|
|
9
|
+
# runs, so app boot stays as light as with `require: false`.
|
|
10
|
+
require 'rails/railtie'
|
|
11
|
+
|
|
12
|
+
module DevDoc
|
|
13
|
+
# Loads the `dev_doc:*` rake tasks when Rails loads the app's tasks.
|
|
14
|
+
class Railtie < Rails::Railtie
|
|
15
|
+
rake_tasks do
|
|
16
|
+
require 'dev_doc/i18n/tasks'
|
|
17
|
+
end
|
|
18
|
+
end
|
|
19
|
+
end
|
|
@@ -102,7 +102,7 @@ module DevDoc
|
|
|
102
102
|
end
|
|
103
103
|
|
|
104
104
|
def normalize(emails)
|
|
105
|
-
Array(emails).compact.map { |email| email.to_s.downcase }
|
|
105
|
+
Array(emails).compact.map { |email| email.to_s.downcase } # rubocop:disable DevDoc/Style/AvoidKernelArray -- recipients may be one address or a list
|
|
106
106
|
end
|
|
107
107
|
private_class_method :normalize
|
|
108
108
|
end
|
|
@@ -71,18 +71,23 @@ module DevDoc
|
|
|
71
71
|
leaked = CrossTenantCanaryCheck.leaked_markers(__dev_doc_response_body, foreign)
|
|
72
72
|
return if leaked.empty?
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
allowed_list = Array(allowed).join(', ') # rubocop:disable DevDoc/Style/AvoidKernelArray -- a persona's allowed tenant keys are one or many by config
|
|
75
|
+
raise Minitest::Assertion, __dev_doc_canary_message(allowed_list, leaked)
|
|
75
76
|
end
|
|
76
77
|
|
|
77
78
|
def __dev_doc_response_body
|
|
78
79
|
response&.body.to_s
|
|
79
80
|
rescue StandardError
|
|
81
|
+
# rescue-reason: side-effect: the canary rides on every request test
|
|
82
|
+
# and must not fail it.
|
|
83
|
+
# silent-rescue: the canary check must never fail on an unreadable
|
|
84
|
+
# response body; an empty body simply carries no markers to match.
|
|
80
85
|
''
|
|
81
86
|
end
|
|
82
87
|
|
|
83
|
-
def __dev_doc_canary_message(
|
|
88
|
+
def __dev_doc_canary_message(allowed_list, leaked)
|
|
84
89
|
<<~MSG
|
|
85
|
-
Cross-tenant leak: this persona (allowed tenants: #{
|
|
90
|
+
Cross-tenant leak: this persona (allowed tenants: #{allowed_list}) received a
|
|
86
91
|
response containing #{leaked.join(', ')}, which belongs to a tenant it must not see.
|
|
87
92
|
Route: #{__dev_doc_route_label}
|
|
88
93
|
Another tenant's data rendered into this persona's response — a cross-tenant read leak.
|
|
@@ -103,6 +103,10 @@ module DevDoc
|
|
|
103
103
|
def __dev_doc_source_file
|
|
104
104
|
method(name).source_location&.first
|
|
105
105
|
rescue NameError
|
|
106
|
+
# rescue-reason: side-effect: the source file only labels the failure
|
|
107
|
+
# message; it must not replace the assertion with a NameError.
|
|
108
|
+
# silent-rescue: an unresolvable test-method name means the source
|
|
109
|
+
# file is unknown; the location line renders without it.
|
|
106
110
|
nil
|
|
107
111
|
end
|
|
108
112
|
|
|
@@ -51,7 +51,7 @@ module DevDoc
|
|
|
51
51
|
# Literal-path (non-glob, non-allowlisted) entries of one section's
|
|
52
52
|
# `Exclude:` list.
|
|
53
53
|
def literal_excludes(section_config)
|
|
54
|
-
Array(section_config['Exclude']).select do |entry|
|
|
54
|
+
Array(section_config['Exclude']).select do |entry| # rubocop:disable DevDoc/Style/AvoidKernelArray -- a section's Exclude may be a bare string or a list (both spellings are flagged)
|
|
55
55
|
entry.is_a?(String) && !entry.match?(GLOB_CHARACTERS) && !@allowed_files.include?(entry)
|
|
56
56
|
end
|
|
57
57
|
end
|
|
@@ -123,6 +123,10 @@ module DevDoc
|
|
|
123
123
|
def parse_json(body)
|
|
124
124
|
JSON.parse(body)
|
|
125
125
|
rescue JSON::ParserError
|
|
126
|
+
# rescue-reason: boundary-parse: crawled response bodies are not
|
|
127
|
+
# known to be JSON until parsed.
|
|
128
|
+
# silent-rescue: non-JSON bodies are expected here — scan_body only
|
|
129
|
+
# wants the parseable ones and skips the rest.
|
|
126
130
|
nil
|
|
127
131
|
end
|
|
128
132
|
|
|
@@ -170,6 +174,11 @@ module DevDoc
|
|
|
170
174
|
data = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true)
|
|
171
175
|
collect_strings(data, set)
|
|
172
176
|
rescue Psych::Exception
|
|
177
|
+
# rescue-reason: bulkhead: one unparsable fixture file must not
|
|
178
|
+
# abort the scan of the rest.
|
|
179
|
+
# silent-rescue: an unparsable fixture is skipped; its strings
|
|
180
|
+
# then count as noise candidates instead of exclusions, which
|
|
181
|
+
# shows up in the report rather than hiding anything.
|
|
173
182
|
next
|
|
174
183
|
end
|
|
175
184
|
end
|
|
@@ -19,39 +19,76 @@ module RuboCop
|
|
|
19
19
|
# lines. Use this when the checked node is a class/module declaration:
|
|
20
20
|
# there the "trailing comment on a preceding code line" rule would let a
|
|
21
21
|
# marker trailing the PREVIOUS class's `end` silence the next class.
|
|
22
|
+
#
|
|
23
|
+
# `leading_body_marker?` adds the third placement the rescue cops
|
|
24
|
+
# accept: the body's leading comment block directly below a `rescue`
|
|
25
|
+
# keyword.
|
|
22
26
|
module AdjacentJustification
|
|
23
27
|
private
|
|
24
28
|
|
|
25
29
|
def adjacent_justification?(node, standalone_only: false, marker: justification_marker)
|
|
30
|
+
adjacent_marker_comments(node, standalone_only: standalone_only, marker: marker).any?
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# Every adjacent comment carrying the marker, for hosts that read
|
|
34
|
+
# what follows it (a category word).
|
|
35
|
+
def adjacent_marker_comments(node, standalone_only: false, marker: justification_marker)
|
|
36
|
+
marker = marker.downcase if marker.is_a?(String)
|
|
37
|
+
comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
|
|
38
|
+
|
|
39
|
+
select_markers(comments_by_line[node.first_line], marker) +
|
|
40
|
+
marker_comments_above(node.first_line - 1, comments_by_line, marker, standalone_only)
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# The marker also counts in a rescue body's own leading comment
|
|
44
|
+
# block — the contiguous comment-only lines directly below the
|
|
45
|
+
# `rescue` keyword, where adopters naturally state the reason. A
|
|
46
|
+
# comment after the first body statement is not adjacent to the
|
|
47
|
+
# rescue.
|
|
48
|
+
def leading_body_marker?(node, marker: justification_marker)
|
|
49
|
+
leading_body_marker_comments(node, marker: marker).any?
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
def leading_body_marker_comments(node, marker: justification_marker)
|
|
26
53
|
marker = marker.downcase if marker.is_a?(String)
|
|
27
54
|
comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
|
|
55
|
+
line = rescue_header_last_line(node) + 1
|
|
56
|
+
found = []
|
|
57
|
+
while (line_comments = comments_by_line[line]) && comment_only_line?(line)
|
|
58
|
+
found.concat(select_markers(line_comments, marker))
|
|
59
|
+
line += 1
|
|
60
|
+
end
|
|
28
61
|
|
|
29
|
-
|
|
62
|
+
found
|
|
63
|
+
end
|
|
30
64
|
|
|
31
|
-
|
|
65
|
+
# An exception list may wrap; the body starts below its last line.
|
|
66
|
+
def rescue_header_last_line(node)
|
|
67
|
+
(node.exception_variable || node.exceptions.last || node.loc.keyword).last_line
|
|
32
68
|
end
|
|
33
69
|
|
|
34
70
|
# Walk the contiguous comment block upward from the line directly
|
|
35
71
|
# above. A trailing comment on a preceding code line also counts —
|
|
36
72
|
# still adjacent, still a deliberate statement — except in
|
|
37
73
|
# standalone_only mode.
|
|
38
|
-
def
|
|
74
|
+
def marker_comments_above(line, comments_by_line, marker, standalone_only)
|
|
75
|
+
found = []
|
|
39
76
|
while (line_comments = comments_by_line[line])
|
|
40
77
|
break if standalone_only && !comment_only_line?(line)
|
|
41
|
-
return true if contains_marker?(line_comments, marker)
|
|
42
78
|
|
|
79
|
+
found.concat(select_markers(line_comments, marker))
|
|
43
80
|
line -= 1
|
|
44
81
|
end
|
|
45
82
|
|
|
46
|
-
|
|
83
|
+
found
|
|
47
84
|
end
|
|
48
85
|
|
|
49
86
|
def comment_only_line?(line)
|
|
50
87
|
processed_source.lines[line - 1].lstrip.start_with?('#')
|
|
51
88
|
end
|
|
52
89
|
|
|
53
|
-
def
|
|
54
|
-
|
|
90
|
+
def select_markers(comments, marker)
|
|
91
|
+
(comments || []).select do |comment|
|
|
55
92
|
text = comment.text.downcase
|
|
56
93
|
marker.is_a?(Regexp) ? marker.match?(text) : text.include?(marker)
|
|
57
94
|
end
|
|
@@ -132,11 +132,11 @@ module RuboCop
|
|
|
132
132
|
private
|
|
133
133
|
|
|
134
134
|
def load_resource_method_names
|
|
135
|
-
Array(cop_config.fetch('LoadResourceMethodNames', ['glib_load_resource'])).map(&:to_sym)
|
|
135
|
+
Array(cop_config.fetch('LoadResourceMethodNames', ['glib_load_resource'])).map(&:to_sym) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one method name or a list
|
|
136
136
|
end
|
|
137
137
|
|
|
138
138
|
def current_user_assertion_method_names
|
|
139
|
-
Array(cop_config.fetch('CurrentUserAssertionMethodNames', ['assert_current_user_present'])).map(&:to_sym)
|
|
139
|
+
Array(cop_config.fetch('CurrentUserAssertionMethodNames', ['assert_current_user_present'])).map(&:to_sym) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one method name or a list
|
|
140
140
|
end
|
|
141
141
|
|
|
142
142
|
def load_resource_method?(method_name)
|
|
@@ -152,7 +152,7 @@ module RuboCop
|
|
|
152
152
|
|
|
153
153
|
def login_only_predicates
|
|
154
154
|
@login_only_predicates ||=
|
|
155
|
-
Array(cop_config.fetch('LoginOnlyPredicates', %w[user_signed_in? everyone])).map(&:to_sym)
|
|
155
|
+
Array(cop_config.fetch('LoginOnlyPredicates', %w[user_signed_in? everyone])).map(&:to_sym) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one predicate or a list
|
|
156
156
|
end
|
|
157
157
|
|
|
158
158
|
def justification_marker
|
|
@@ -158,7 +158,7 @@ module RuboCop
|
|
|
158
158
|
|
|
159
159
|
def non_enumerable_keys
|
|
160
160
|
@non_enumerable_keys ||=
|
|
161
|
-
Array(cop_config.fetch('NonEnumerableKeys', %w[uuid token secret_key])).map(&:to_sym)
|
|
161
|
+
Array(cop_config.fetch('NonEnumerableKeys', %w[uuid token secret_key])).map(&:to_sym) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one key or a list
|
|
162
162
|
end
|
|
163
163
|
|
|
164
164
|
def offense_message(node)
|
|
@@ -181,7 +181,7 @@ module RuboCop
|
|
|
181
181
|
end
|
|
182
182
|
|
|
183
183
|
def finder_methods
|
|
184
|
-
@finder_methods ||= Array(cop_config.fetch('FinderMethods', %w[find find_by find_by!])).map(&:to_sym)
|
|
184
|
+
@finder_methods ||= Array(cop_config.fetch('FinderMethods', %w[find find_by find_by!])).map(&:to_sym) # rubocop:disable DevDoc/Style/AvoidKernelArray -- cop config accepts one method name or a list
|
|
185
185
|
end
|
|
186
186
|
|
|
187
187
|
def justification_marker
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
module RuboCop
|
|
2
|
+
module Cop
|
|
3
|
+
module DevDoc
|
|
4
|
+
module Bundler
|
|
5
|
+
# Flags Gemfile gems that duplicate a concern glib already provides.
|
|
6
|
+
#
|
|
7
|
+
# ## Rationale
|
|
8
|
+
# glib-web ships the concerns a glib app needs: versioning and audit
|
|
9
|
+
# history via `Glib::SnapshotV2` (active_snapshot), authorization via
|
|
10
|
+
# Pundit, uploads via ActiveStorage. A second library for one of those
|
|
11
|
+
# concerns splits the codebase between two ways of doing one thing and
|
|
12
|
+
# loses glib's integration — snapshot diffs in the admin timeline,
|
|
13
|
+
# Pundit scopes on index pages, `fields_file` uploads binding to
|
|
14
|
+
# attachments. The `ConflictingGems` map is keyed by gem name and each
|
|
15
|
+
# offense names the glib replacement, so the author knows what to use
|
|
16
|
+
# instead of what to delete.
|
|
17
|
+
#
|
|
18
|
+
# ## Exception
|
|
19
|
+
# A migration period where both libraries coexist (moving records onto
|
|
20
|
+
# the glib concern one model at a time) is legitimate: disable for the
|
|
21
|
+
# duration, bounded to the gem's own line, naming why:
|
|
22
|
+
#
|
|
23
|
+
# # rubocop:disable DevDoc/Bundler/ConflictingGem -- SnapshotV2 backfill in progress
|
|
24
|
+
# gem 'paper_trail'
|
|
25
|
+
# # rubocop:enable DevDoc/Bundler/ConflictingGem
|
|
26
|
+
#
|
|
27
|
+
# NOTE: Only direct Gemfile entries are checked, never transitive
|
|
28
|
+
# dependencies in `Gemfile.lock` or gemspec `add_dependency` lines.
|
|
29
|
+
# The list only knows conflicts someone has named — a gem that
|
|
30
|
+
# overlaps a glib concern without being in the map is still a
|
|
31
|
+
# conflict; the residual guidance lives in
|
|
32
|
+
# `best_practices/backend/en/01_basic.md` item 7.
|
|
33
|
+
#
|
|
34
|
+
# Configure via `ConflictingGems` in .rubocop.yml: a consumer adds an
|
|
35
|
+
# entry by giving it a message, and drops one by setting its value to
|
|
36
|
+
# `null`, `false` or empty, without disabling the cop.
|
|
37
|
+
#
|
|
38
|
+
# @example
|
|
39
|
+
# # bad
|
|
40
|
+
# gem 'paper_trail', '~> 17.0'
|
|
41
|
+
#
|
|
42
|
+
# # good
|
|
43
|
+
# # nothing to add — include the glib concern in the model instead
|
|
44
|
+
# class Order < ApplicationRecord
|
|
45
|
+
# include Glib::SnapshotV2
|
|
46
|
+
# end
|
|
47
|
+
class ConflictingGem < Base
|
|
48
|
+
MSG = '`%<gem>s` conflicts with the glib way: %<replacement>s'.freeze
|
|
49
|
+
|
|
50
|
+
RESTRICT_ON_SEND = %i[gem].freeze
|
|
51
|
+
|
|
52
|
+
def on_send(node)
|
|
53
|
+
return if node.receiver
|
|
54
|
+
|
|
55
|
+
gem_name = node.first_argument
|
|
56
|
+
return unless gem_name&.str_type?
|
|
57
|
+
|
|
58
|
+
replacement = conflicting_gems[gem_name.value]
|
|
59
|
+
return unless replacement.is_a?(String) && !replacement.empty?
|
|
60
|
+
|
|
61
|
+
add_offense(gem_name, message: format(MSG, gem: gem_name.value, replacement: replacement))
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
private
|
|
65
|
+
|
|
66
|
+
def conflicting_gems
|
|
67
|
+
config = cop_config['ConflictingGems']
|
|
68
|
+
config.is_a?(Hash) ? config : {}
|
|
69
|
+
end
|
|
70
|
+
end
|
|
71
|
+
end
|
|
72
|
+
end
|
|
73
|
+
end
|
|
74
|
+
end
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
module RuboCop
|
|
2
|
+
module Cop
|
|
3
|
+
module DevDoc
|
|
4
|
+
# Shared exception-class matching for the rescue cops. RuboCop has no
|
|
5
|
+
# type information, so a rescued class is matched by its constant as
|
|
6
|
+
# written: the source, leading `::` stripped, either equals a list
|
|
7
|
+
# entry or starts with an entry ending in `::` (a namespace entry such
|
|
8
|
+
# as `Errno::`). Anything that is not a plain constant — a splat, a
|
|
9
|
+
# method call, a local — never matches, and neither does a bare
|
|
10
|
+
# `rescue` (an empty exception list), so callers fail closed.
|
|
11
|
+
module ExceptionClassList
|
|
12
|
+
private
|
|
13
|
+
|
|
14
|
+
def all_exceptions_listed?(resbody, entries)
|
|
15
|
+
exceptions = resbody.exceptions
|
|
16
|
+
return false if exceptions.empty?
|
|
17
|
+
|
|
18
|
+
exceptions.all? { |exception| listed_exception?(exception, entries) }
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
def listed_exception?(node, entries)
|
|
22
|
+
return false unless node.const_type?
|
|
23
|
+
|
|
24
|
+
name = node.source.delete_prefix('::')
|
|
25
|
+
entries.any? do |entry|
|
|
26
|
+
entry.end_with?('::') ? name.start_with?(entry) : name == entry
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
end
|
|
32
|
+
end
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
require_relative 'text_shape'
|
|
2
|
+
require_relative 'localizable_props'
|
|
3
|
+
|
|
4
|
+
module RuboCop
|
|
5
|
+
module Cop
|
|
6
|
+
module DevDoc
|
|
7
|
+
module I18n
|
|
8
|
+
# Warn on any string literal that reads like user-facing copy, wherever
|
|
9
|
+
# it sits — not only in glib text props.
|
|
10
|
+
#
|
|
11
|
+
# ## Rationale
|
|
12
|
+
# `DevDoc/I18n/RequireTranslation` checks the value of a known text prop
|
|
13
|
+
# on a known component. Copy escapes it whenever it reaches the screen
|
|
14
|
+
# by any other route: a ternary or `||` fallback inside the prop
|
|
15
|
+
# (`text: signed_in ? 'Sign out' : 'Sign in'`), a hash built in a local
|
|
16
|
+
# and passed in later (`required = { message: 'Required' }`), a model
|
|
17
|
+
# method that builds select options, a controller error string, a mailer
|
|
18
|
+
# subject, a constant. Each of those ships English-only text that can
|
|
19
|
+
# never be translated.
|
|
20
|
+
#
|
|
21
|
+
# This cop inspects every `str`/`dstr` node and reports the ones whose
|
|
22
|
+
# *shape* is prose (two or more words, a capitalised word, or non-ASCII
|
|
23
|
+
# letters) and whose *position* is not a known non-text one. It skips:
|
|
24
|
+
#
|
|
25
|
+
# * identifier-shaped strings — keys, CSS class lists, paths, URLs,
|
|
26
|
+
# MIME types, emails, constants, inline CSS, SQL, `strftime` formats;
|
|
27
|
+
# * `t(...)`/`translate`/`l`/`localize` keys (a literal `default:` is
|
|
28
|
+
# still checked — it is the English the user sees when the key is
|
|
29
|
+
# missing);
|
|
30
|
+
# * hash keys, and values under `ExemptKeys` (`styleClass:`,
|
|
31
|
+
# `class_name:`, `url:` ...);
|
|
32
|
+
# * receivers and direct arguments of `ExemptMethods` (SQL builders,
|
|
33
|
+
# comparisons, string matching, hash lookups, `require` ...);
|
|
34
|
+
# * anything inside `DeveloperFacingMethods` (`raise`, `warn`, ...), a
|
|
35
|
+
# `logger.*` call, or a call on a `DeveloperFacingReceivers` constant
|
|
36
|
+
# (error trackers such as `Rollbar.error`) — exception, log and
|
|
37
|
+
# error-report text is for developers;
|
|
38
|
+
# * `when` conditions, and the parts of regexps and backticks;
|
|
39
|
+
# * literals `RequireTranslation` already checks (see below).
|
|
40
|
+
#
|
|
41
|
+
# An interpolated string is judged by its literal parts, with each
|
|
42
|
+
# interpolation counted as a word: `"#{count} items"` is prose,
|
|
43
|
+
# `"#{a}. #{b}"` and `"badge--#{state}"` are not.
|
|
44
|
+
#
|
|
45
|
+
# It cannot tell copy a user sees from prose that never leaves the
|
|
46
|
+
# server, so it is a **review aid**: disabled by default, `warning`
|
|
47
|
+
# severity. Run it during a localization pass and either localize each
|
|
48
|
+
# hit or disable it inline with the reason it is not user-facing.
|
|
49
|
+
#
|
|
50
|
+
# ## Relationship with RequireTranslation
|
|
51
|
+
# The two split the work so each literal is reported by exactly one of
|
|
52
|
+
# them. `RequireTranslation` owns a literal that is the direct value of
|
|
53
|
+
# a text prop on a watched glib component (`view.p text: 'Welcome'`,
|
|
54
|
+
# `json.title 'Orders'`) and flags it whatever its shape; this cop
|
|
55
|
+
# skips those and covers every other position, using that cop's
|
|
56
|
+
# `WatchedMethods` and `LocalizableKeys` to tell them apart. Two cases
|
|
57
|
+
# inside a prop stay here because `RequireTranslation` lets them
|
|
58
|
+
# through: a literal wrapped in a ternary or `||`, and an interpolated
|
|
59
|
+
# string that also calls `t(...)`
|
|
60
|
+
# (`text: "#{t('orders.title')} this month"`). Run both during a
|
|
61
|
+
# localization pass — on its own, this cop does not see literal glib
|
|
62
|
+
# props.
|
|
63
|
+
#
|
|
64
|
+
# NOTE: ERB templates are not parsed by RuboCop, so literal text in
|
|
65
|
+
# `.html.erb`/`.text.erb` (mailers, layouts) is not checked. Text built
|
|
66
|
+
# at runtime (`titleize`, `humanize`, ActiveRecord attribute names in
|
|
67
|
+
# `errors.full_messages`) is not a literal either — see
|
|
68
|
+
# `DevDoc/I18n/AvoidTitleizeHumanize` for the former.
|
|
69
|
+
#
|
|
70
|
+
# ⚠️ English-only — can't be translated
|
|
71
|
+
# view.button text: signed_in ? 'Sign out' : 'Sign in'
|
|
72
|
+
# required = { required: { message: 'Required' } }
|
|
73
|
+
# render_error 'Could not save the record'
|
|
74
|
+
# mail to: user.email, subject: "Welcome, #{user.name}"
|
|
75
|
+
#
|
|
76
|
+
# ✔️ Resolved through I18n
|
|
77
|
+
# view.button text: t(signed_in ? 'auth.sign_out' : 'auth.sign_in')
|
|
78
|
+
# render_error t('records.save_failed')
|
|
79
|
+
#
|
|
80
|
+
# @example
|
|
81
|
+
# # warning (fallback branch of a text prop)
|
|
82
|
+
# view.button text: signed_in ? 'Sign out' : 'Sign in'
|
|
83
|
+
#
|
|
84
|
+
# # warning (hash built outside the component call)
|
|
85
|
+
# required = { required: { message: 'Required' } }
|
|
86
|
+
#
|
|
87
|
+
# # warning (literal words around a translation)
|
|
88
|
+
# view.label text: "#{t('orders.title')} this month"
|
|
89
|
+
#
|
|
90
|
+
# # good
|
|
91
|
+
# view.button text: t(signed_in ? 'auth.sign_out' : 'auth.sign_in')
|
|
92
|
+
#
|
|
93
|
+
# # good (identifier-shaped)
|
|
94
|
+
# view.panels_vertical styleClass: 'card card--active'
|
|
95
|
+
#
|
|
96
|
+
# # good (developer-facing)
|
|
97
|
+
# raise ArgumentError, "Unknown step: #{step}"
|
|
98
|
+
class HardcodedText < Base
|
|
99
|
+
MSG ='Possible hardcoded text: this string reads like user-facing copy. ' \
|
|
100
|
+
'Use `t(...)`, or disable inline with the reason it is never shown to a user.'.freeze
|
|
101
|
+
|
|
102
|
+
TRANSLATION_METHODS = %i[t translate l localize].freeze
|
|
103
|
+
LOGGER_METHODS = %i[debug info warn error fatal unknown add log].freeze
|
|
104
|
+
# Nodes a value passes through on its way to a key or call
|
|
105
|
+
# (`[a, b]`, `x ? a : b`, `x || a`, `(a)`), so `styleClass: x ? 'a' : 'b'`
|
|
106
|
+
# is judged by its key just like `styleClass: 'a'`.
|
|
107
|
+
VALUE_WRAPPERS = %i[array splat if or and begin].freeze
|
|
108
|
+
|
|
109
|
+
def on_str(node)
|
|
110
|
+
return if part_of_enclosing_literal?(node)
|
|
111
|
+
return if node.source == '__FILE__'
|
|
112
|
+
|
|
113
|
+
check(node)
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
def on_dstr(node)
|
|
117
|
+
return if part_of_enclosing_literal?(node)
|
|
118
|
+
|
|
119
|
+
check(node)
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
private
|
|
123
|
+
|
|
124
|
+
def check(node)
|
|
125
|
+
return unless TextShape.prose?(literal_text(node))
|
|
126
|
+
return if exempt_position?(node)
|
|
127
|
+
return if checked_by_require_translation?(node)
|
|
128
|
+
|
|
129
|
+
add_offense(node)
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
# Adjacent/continued literals and interpolated strings are judged as
|
|
133
|
+
# a whole at their outermost `dstr`; regexp and backtick contents are
|
|
134
|
+
# patterns and commands, not copy.
|
|
135
|
+
def part_of_enclosing_literal?(node)
|
|
136
|
+
return true if %i[dstr dsym].include?(node.parent&.type)
|
|
137
|
+
|
|
138
|
+
node.each_ancestor(:regexp, :xstr).any?
|
|
139
|
+
end
|
|
140
|
+
|
|
141
|
+
def literal_text(node)
|
|
142
|
+
return node.value.to_s if node.str_type?
|
|
143
|
+
return TextShape::PLACEHOLDER unless node.dstr_type?
|
|
144
|
+
|
|
145
|
+
node.children.map { |child| literal_text(child) }.join
|
|
146
|
+
end
|
|
147
|
+
|
|
148
|
+
def exempt_position?(node)
|
|
149
|
+
value = outermost_value(node)
|
|
150
|
+
parent = value.parent
|
|
151
|
+
|
|
152
|
+
return true if exempt_pair?(value, parent)
|
|
153
|
+
return true if exempt_call_position?(value, parent)
|
|
154
|
+
return true if parent&.when_type? && parent.conditions.include?(value)
|
|
155
|
+
return true if node.each_ancestor(:in_pattern).any?
|
|
156
|
+
|
|
157
|
+
developer_facing?(node)
|
|
158
|
+
end
|
|
159
|
+
|
|
160
|
+
def checked_by_require_translation?(node)
|
|
161
|
+
# RequireTranslation accepts a string that interpolates `t(...)`,
|
|
162
|
+
# so the literal words around it are left for this cop.
|
|
163
|
+
return false if node.dstr_type? && LocalizableProps.translated_interpolation?(node)
|
|
164
|
+
|
|
165
|
+
require_translation = config.for_cop('DevDoc/I18n/RequireTranslation')
|
|
166
|
+
LocalizableProps.inspected_value?(
|
|
167
|
+
node,
|
|
168
|
+
require_translation.fetch('WatchedMethods', LocalizableProps::DEFAULT_WATCHED_METHODS),
|
|
169
|
+
require_translation.fetch('LocalizableKeys', LocalizableProps::DEFAULT_LOCALIZABLE_KEYS)
|
|
170
|
+
)
|
|
171
|
+
end
|
|
172
|
+
|
|
173
|
+
def outermost_value(node)
|
|
174
|
+
current = node
|
|
175
|
+
while (parent = current.parent) && VALUE_WRAPPERS.include?(parent.type)
|
|
176
|
+
break if parent.if_type? && parent.condition.equal?(current)
|
|
177
|
+
|
|
178
|
+
current = parent
|
|
179
|
+
end
|
|
180
|
+
current
|
|
181
|
+
end
|
|
182
|
+
|
|
183
|
+
def exempt_pair?(value, parent)
|
|
184
|
+
return false unless parent&.pair_type?
|
|
185
|
+
return true if parent.key.equal?(value)
|
|
186
|
+
|
|
187
|
+
key = parent.key
|
|
188
|
+
(key.sym_type? || key.str_type?) && exempt_keys.include?(key.value.to_s)
|
|
189
|
+
end
|
|
190
|
+
|
|
191
|
+
def exempt_call_position?(value, parent)
|
|
192
|
+
return false unless parent&.call_type?
|
|
193
|
+
return true if translation_key?(value, parent)
|
|
194
|
+
return false unless exempt_methods.include?(parent.method_name.to_s)
|
|
195
|
+
|
|
196
|
+
parent.receiver.equal?(value) || parent.arguments.any? { |arg| arg.equal?(value) }
|
|
197
|
+
end
|
|
198
|
+
|
|
199
|
+
def translation_key?(value, call)
|
|
200
|
+
return false unless TRANSLATION_METHODS.include?(call.method_name)
|
|
201
|
+
|
|
202
|
+
receiver = call.receiver
|
|
203
|
+
(receiver.nil? || (receiver.const_type? && receiver.const_name == 'I18n')) &&
|
|
204
|
+
call.first_argument.equal?(value)
|
|
205
|
+
end
|
|
206
|
+
|
|
207
|
+
def developer_facing?(node)
|
|
208
|
+
node.each_ancestor(:send, :csend).any? { |call| developer_facing_call?(call) }
|
|
209
|
+
end
|
|
210
|
+
|
|
211
|
+
def developer_facing_call?(call)
|
|
212
|
+
receiver = call.receiver
|
|
213
|
+
return developer_facing_methods.include?(call.method_name.to_s) if receiver.nil?
|
|
214
|
+
return true if receiver.const_type? && developer_facing_receivers.include?(receiver.const_name)
|
|
215
|
+
|
|
216
|
+
LOGGER_METHODS.include?(call.method_name) && logger_receiver?(receiver)
|
|
217
|
+
end
|
|
218
|
+
|
|
219
|
+
def logger_receiver?(receiver)
|
|
220
|
+
(receiver.send_type? || receiver.lvar_type? || receiver.ivar_type?) &&
|
|
221
|
+
receiver.source.match?(/logger\z/i)
|
|
222
|
+
end
|
|
223
|
+
|
|
224
|
+
def exempt_keys
|
|
225
|
+
cop_config.fetch('ExemptKeys', [])
|
|
226
|
+
end
|
|
227
|
+
|
|
228
|
+
def exempt_methods
|
|
229
|
+
cop_config.fetch('ExemptMethods', [])
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
def developer_facing_methods
|
|
233
|
+
cop_config.fetch('DeveloperFacingMethods', [])
|
|
234
|
+
end
|
|
235
|
+
|
|
236
|
+
def developer_facing_receivers
|
|
237
|
+
cop_config.fetch('DeveloperFacingReceivers', [])
|
|
238
|
+
end
|
|
239
|
+
end
|
|
240
|
+
end
|
|
241
|
+
end
|
|
242
|
+
end
|
|
243
|
+
end
|