rubocop-dev_doc 0.5.0.beta1 → 0.6.0.beta1

data/lib/rubocop/cop/dev_doc/style/tap_block_ignores_value.rb

@@ -0,0 +1,123 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag `Object#tap` whose block ignores the yielded value.
+        #
+        # ## Rationale
+        # `tap` exists to **operate on the yielded receiver and return it** —
+        # `obj.tap { |x| configure(x) }`. The yielded value is the whole
+        # point of the method.
+        #
+        # When the block **ignores** the yielded value, `tap` is no longer
+        # doing that job. It's being used purely as a temp-variable-elision
+        # trick for "run a side effect, then return the receiver":
+        #
+        #   ❌ Block never references the yielded value — `tap` is eliding a temp var
+        #   read_value.tap { do_side_effect }
+        #
+        # This costs readability for no benefit:
+        #
+        # - **It hides the return value in the receiver position.** `tap`'s
+        #   "returns self" behaviour is its *less obvious* property. A reader
+        #   has to stop and recall that the expression returns the receiver,
+        #   not the block's value. The explicit form puts the return value on
+        #   its own line where "what does this return" is literal.
+        # - **Footgun magnet.** Return-value semantics here are subtle — it's
+        #   easy to nearby-edit the block into something whose value you think
+        #   matters, or to confuse it with the broken `expr; side_effect`
+        #   sequence (which returns the side effect's value, not `expr`'s).
+        #   Code whose contract is "return this value" reads and edits more
+        #   safely when the return is explicit.
+        # - **Equal stakes → prefer the duller form.** Both forms are correct
+        #   and neither is faster. With no functional difference, the more
+        #   obvious one wins in a shared codebase.
+        #
+        #   ✔️ Explicit intent, return value on its own line
+        #   result = read_value
+        #   do_side_effect
+        #   result
+        #
+        # ## When `tap` IS the right choice
+        # Reserve `tap` for its canonical use — when the block references the
+        # yielded value:
+        #
+        #   ✔️ Block uses the yielded value — this is what `tap` is for
+        #   Model.new.tap { |m| m.role = :admin; m.save }
+        #   record.tap { |r| logger.debug(r.to_sql) }
+        #
+        # ## Exception
+        # Genuine intentional uses (e.g. a logging side effect that reads
+        # clearer in tap position) go through an inline `# rubocop:disable`
+        # with a reason. The friction is the feature — it forces the choice
+        # to be articulated and reviewed.
+        #
+        # NOTE: Numbered-param (`_1`) and implicit-`it` (Ruby 3.4+) forms are
+        # not flagged — by construction, those forms reference the yielded
+        # value, which is the canonical use of `tap`. Block-pass (`&:sym`) is
+        # likewise not flagged; it isn't a block node.
+        #
+        # NOTE: If a nested block *shadows* the outer arg name
+        # (`tap { |v| items.each { |v| v.foo } }`), the inner reference is
+        # treated as covering the outer — a rare residual false negative.
+        # Inline-disable if it ever matters.
+        #
+        # @example
+        #   # bad — block ignores the yielded value
+        #   read_value.tap { do_side_effect }
+        #   record.tap { |r| log_event }
+        #   value.tap { }
+        #
+        #   # good — block references the yielded value
+        #   Model.new.tap { |m| m.role = :admin; m.save }
+        #   record.tap { |r| logger.debug(r.to_sql) }
+        #
+        #   # good — a reference inside a nested block still counts
+        #   items.tap { |i| [1, 2].each { i << _1 } }
+        #
+        #   # good — preferred explicit form when the value is unused
+        #   result = read_value
+        #   do_side_effect
+        #   result
+        class TapBlockIgnoresValue < Base
+          MSG = '`tap` is for operating on the yielded value — when the ' \
+                'block ignores it, prefer an explicit assign-and-return. ' \
+                'Disable with a reason when the side effect reads clearer ' \
+                'in `tap` position.'.freeze
+
+          def on_block(node)
+            return unless node.send_node.method?(:tap)
+            return if block_uses_yielded_value?(node)
+
+            add_offense(node.send_node.loc.selector)
+          end
+
+          private
+
+          def block_uses_yielded_value?(node)
+            args = node.arguments
+            return false unless args
+            return false if args.children.empty? # no param declared → value ignored
+
+            # `tap` yields one value; multi-arg / destructuring is unusual.
+            # Be conservative — don't flag what we can't confidently call
+            # "ignoring the value".
+            return true if args.children.length >= 2
+
+            arg = args.children.first
+            return true unless arg.respond_to?(:name)
+
+            return false unless node.body # empty body with declared arg → flag
+
+            # Walk from the block node (not `body`): `each_descendant`
+            # excludes the receiver, so a body that *is* an lvar
+            # (`tap { |v| v }`) would be missed otherwise. Nested blocks
+            # are walked too, so a reference inside one counts as "used".
+            # The shadowing edge case is documented above as a NOTE.
+            node.each_descendant(:lvar).any? { |n| n.children.first == arg.name }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb

@@ -13,6 +13,18 @@ module RuboCop
         # controller test (very rare) — e.g. a search-ranking detail the
         # controller never exposes.
         #
+        # The danger a unit test hides: it can stay green while the feature is
+        # broken in production. It proves a method works in isolation — NOT that
+        # the real request path calls that method, in the right order, inside the
+        # transaction it needs. A model method can be flawless in a unit test
+        # while the controller calls the wrong method, skips it, or runs it
+        # outside its transaction; the unit test stays green and the feature is
+        # broken. Controller tests fail when the *wiring* is wrong — which is
+        # where regressions actually live. So a passing unit test is not evidence
+        # the feature works; it is false confidence about production. Reach for
+        # one only when you are sure a controller test genuinely cannot reach the
+        # path, not because it is quicker to write.
+        #
         # This cop flags only the literal `< ActiveSupport::TestCase`
         # superclass. The blessed blackbox bases —
         # `ActionDispatch::IntegrationTest`, `Glib::IntegrationTest`,
@@ -20,6 +32,18 @@ module RuboCop
         # though they inherit from `ActiveSupport::TestCase` transitively.
         #
         # ## Escape hatch
+        # Before reaching for a unit test, assume a controller test IS possible
+        # and look harder — that conclusion is almost always premature. Behaviour
+        # that feels inherently unit-level is usually reachable end-to-end:
+        #   - Transaction rollback / "a failure mid-request": inject the failure
+        #     at a class-method chokepoint the gem/service calls (stub it to
+        #     raise), drive the real request, and assert the observable rollback
+        #     (e.g. `assert_no_difference` on the record count). Even atomicity,
+        #     which feels inherently unit-level, is reachable this way.
+        #   - "The controller wraps it in a transaction so I can't isolate the
+        #     model's own": you usually don't need to — assert the *observable*
+        #     guarantee through the real path; that is what matters in production.
+        #
         # When a unit test is genuinely necessary, suppress with a reason that
         # explains why a controller test can't cover the path. That reason IS the
         # required justification — keep it specific and reviewable:

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.5.0.beta1".freeze
+    VERSION = "0.6.0.beta1".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.5.0.beta1
+  version: 0.6.0.beta1
 platform: ruby
 authors:
 - dev-doc contributors
@@ -91,10 +91,11 @@ files:
 - lib/rubocop-dev_doc.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
+- lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb
+- lib/rubocop/cop/dev_doc/i18n/localizable_props.rb
 - lib/rubocop/cop/dev_doc/i18n/report_text.rb
 - lib/rubocop/cop/dev_doc/i18n/require_translation.rb
 - lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb
-- lib/rubocop/cop/dev_doc/i18n/unverified_translation.rb
 - lib/rubocop/cop/dev_doc/migration/amount_column_in_cents.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
@@ -109,7 +110,9 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb
+- lib/rubocop/cop/dev_doc/rails/avoid_ordering_by_id.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb
+- lib/rubocop/cop/dev_doc/rails/avoid_raw_sql.rb
 - lib/rubocop/cop/dev_doc/rails/bang_save_in_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb
 - lib/rubocop/cop/dev_doc/rails/enum_must_be_symbolized.rb
@@ -125,9 +128,11 @@ files:
 - lib/rubocop/cop/dev_doc/style/avoid_send.rb
 - lib/rubocop/cop/dev_doc/style/minimize_variable_scope.rb
 - lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb
+- lib/rubocop/cop/dev_doc/style/prefer_public_send.rb
 - lib/rubocop/cop/dev_doc/style/repeated_bracket_read.rb
 - lib/rubocop/cop/dev_doc/style/repeated_safe_navigation_receiver.rb
 - lib/rubocop/cop/dev_doc/style/string_symbol_comparison.rb
+- lib/rubocop/cop/dev_doc/style/tap_block_ignores_value.rb
 - lib/rubocop/cop/dev_doc/test/avoid_glib_travel_freeze.rb
 - lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb
 - lib/rubocop/cop/dev_doc/test/response_assert_equal.rb

data/lib/rubocop/cop/dev_doc/i18n/unverified_translation.rb

@@ -1,106 +0,0 @@
-module RuboCop
-  module Cop
-    module DevDoc
-      module I18n
-        # Warn when a glib text prop is set from a non-literal value that isn't
-        # a `t(...)` call — it may be an unlocalized string.
-        #
-        # ## Rationale
-        # `DevDoc/I18n/RequireTranslation` only catches string literals written
-        # at the call site. A value passed through a variable or method
-        # (`label: label_text`) escapes it — the literal could be one hop away.
-        # This cop flags those values so a human can confirm they resolve
-        # through I18n.
-        #
-        # It can't tell a stashed literal from genuinely dynamic data
-        # (`user.name`) or a translation reached via a variable, so it's a
-        # review aid, not a clean lint: it's **disabled by default** and runs at
-        # `info` severity. Run it during a localization pass, not on every
-        # commit. Values that are obviously translated (`t(...)`, `translate`,
-        # `I18n.t`) are excluded; literals are left to `RequireTranslation`.
-        #
-        #   ⚠️ Can't be verified — confirm it's localized
-        #   view.fields_text label: label_text
-        #   view.p text: user.name
-        #
-        #   ✔️ Obviously localized — not flagged
-        #   view.p text: t('home.welcome')
-        #
-        # @example
-        #   # warning (non-literal — may be unlocalized)
-        #   view.fields_text label: label_text
-        #
-        #   # warning (attribute — may be unlocalized)
-        #   view.p text: user.name
-        #
-        #   # good (obviously localized — not flagged)
-        #   view.p text: t('home.welcome')
-        #
-        #   # ignored (literal — handled by RequireTranslation)
-        #   view.p text: 'Welcome'
-        class UnverifiedTranslation < Base
-          MSG = 'Possibly unlocalized: `%<key>s:` is set from a non-literal. ' \
-                'Use `t(...)` if this is user-facing text.'.freeze
-
-          DYNAMIC_TYPES = %i[lvar ivar send csend].freeze
-          TRANSLATION_METHODS = %i[t translate].freeze
-
-          DEFAULT_WATCHED_METHODS = %w[
-            h1 h2 h3 h4 h5 p label markdown
-            fields_text fields_number fields_select fields_password
-            fields_textarea fields_check fields_checkGroup fields_chipGroup
-            fields_timeZone fields_radioGroup fields_date fields_datetime
-          ].freeze
-
-          DEFAULT_LOCALIZABLE_KEYS = %w[
-            title subtitle subsubtitle label placeholder text
-          ].freeze
-
-          def on_send(node)
-            return unless watched_methods.include?(node.method_name.to_s)
-
-            node.arguments.each do |arg|
-              next unless arg.hash_type?
-
-              arg.pairs.each { |pair| check_pair(pair) }
-            end
-          end
-          alias on_csend on_send
-
-          private
-
-          def check_pair(pair)
-            key = pair.key
-            return unless key.sym_type?
-            return unless localizable_keys.include?(key.value.to_s)
-            return unless unverified?(pair.value)
-
-            add_offense(pair.value, message: format(MSG, key: key.value))
-          end
-
-          # A value we can neither confirm nor deny is localized: a variable or
-          # method result (but not an obvious `t(...)`/`translate` call). String
-          # and other literals are excluded — those are RequireTranslation's job.
-          def unverified?(node)
-            return false unless DYNAMIC_TYPES.include?(node.type)
-
-            !translation_call?(node)
-          end
-
-          def translation_call?(node)
-            (node.send_type? || node.csend_type?) &&
-              TRANSLATION_METHODS.include?(node.method_name)
-          end
-
-          def watched_methods
-            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
-          end
-
-          def localizable_keys
-            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
-          end
-        end
-      end
-    end
-  end
-end