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.
Files changed (48) hide show
  1. checksums.yaml +4 -4
  2. data/config/default.yml +461 -62
  3. data/config/obsoletion.yml +7 -3
  4. data/lib/dev_doc/i18n/pseudo_locale.rb +1 -1
  5. data/lib/dev_doc/i18n/tasks.rb +68 -0
  6. data/lib/dev_doc/railtie.rb +19 -0
  7. data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb +1 -1
  8. data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb +8 -3
  9. data/lib/dev_doc/test/lints/http_driven_controller_tests.rb +4 -0
  10. data/lib/dev_doc/test/lints/no_file_excludes.rb +1 -1
  11. data/lib/dev_doc/test/pseudo_i18n_crawler.rb +9 -0
  12. data/lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb +44 -7
  13. data/lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb +2 -2
  14. data/lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb +1 -1
  15. data/lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb +2 -2
  16. data/lib/rubocop/cop/dev_doc/bundler/conflicting_gem.rb +74 -0
  17. data/lib/rubocop/cop/dev_doc/exception_class_list.rb +32 -0
  18. data/lib/rubocop/cop/dev_doc/i18n/hardcoded_text.rb +243 -0
  19. data/lib/rubocop/cop/dev_doc/i18n/localizable_props.rb +69 -19
  20. data/lib/rubocop/cop/dev_doc/i18n/require_translation.rb +13 -17
  21. data/lib/rubocop/cop/dev_doc/i18n/text_shape.rb +94 -0
  22. data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb +1 -1
  23. data/lib/rubocop/cop/dev_doc/migration/legacy_migration.rb +26 -0
  24. data/lib/rubocop/cop/dev_doc/migration/redundant_reference_index.rb +5 -15
  25. data/lib/rubocop/cop/dev_doc/migration/require_reference_index.rb +115 -0
  26. data/lib/rubocop/cop/dev_doc/rails/avoid_bypassing_validation.rb +81 -26
  27. data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb +1 -1
  28. data/lib/rubocop/cop/dev_doc/rails/no_error_message_comparison.rb +178 -0
  29. data/lib/rubocop/cop/dev_doc/rails/no_errors_add_in_controller.rb +177 -0
  30. data/lib/rubocop/cop/dev_doc/rails/no_form_param_lookup_in_controller.rb +236 -0
  31. data/lib/rubocop/cop/dev_doc/style/avoid_kernel_array.rb +103 -0
  32. data/lib/rubocop/cop/dev_doc/style/in_memory_association_find.rb +162 -0
  33. data/lib/rubocop/cop/dev_doc/style/no_silent_rescue.rb +279 -0
  34. data/lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb +1 -1
  35. data/lib/rubocop/cop/dev_doc/style/prefer_allowlist_symbol_param.rb +193 -0
  36. data/lib/rubocop/cop/dev_doc/style/rescue_justification.rb +330 -0
  37. data/lib/rubocop/cop/dev_doc/style/use_g_log.rb +133 -0
  38. data/lib/rubocop/cop/dev_doc/test/justification_covers.rb +216 -0
  39. data/lib/rubocop/cop/dev_doc/test/justification_header.rb +86 -5
  40. data/lib/rubocop/cop/dev_doc/test/prefer_find_sole_by.rb +146 -0
  41. data/lib/rubocop/cop/dev_doc/test/require_job_invocation_in_job_tests.rb +154 -0
  42. data/lib/rubocop/cop/dev_doc/test/require_unit_test_justification.rb +5 -24
  43. data/lib/rubocop/cop/dev_doc/test/test_file_placement.rb +30 -2
  44. data/lib/rubocop/cop/dev_doc/test/test_name_special_characters.rb +108 -0
  45. data/lib/rubocop/cop/dev_doc/view/prefer_prop_over_name.rb +11 -1
  46. data/lib/rubocop/dev_doc/version.rb +1 -1
  47. metadata +24 -4
  48. 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
- raise Minitest::Assertion, __dev_doc_canary_message(allowed, leaked)
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(allowed, leaked)
88
+ def __dev_doc_canary_message(allowed_list, leaked)
84
89
  <<~MSG
85
- Cross-tenant leak: this persona (allowed tenants: #{Array(allowed).join(', ')}) received a
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
- return true if contains_marker?(comments_by_line[node.first_line], marker)
62
+ found
63
+ end
30
64
 
31
- marker_in_block_above?(node.first_line - 1, comments_by_line, marker, standalone_only)
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 marker_in_block_above?(line, comments_by_line, marker, standalone_only)
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
- false
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 contains_marker?(comments, marker)
54
- Array(comments).any? do |comment|
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