rubocop-dev_doc 0.13.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5792a89cab7f1814ee9633da4b5c4150e2c281967aa3b718213aeca1d5eea921
-  data.tar.gz: fcdb36d319b4aae6389cc665fade58bc7093890249f371d28bd3439e844841e0
+  metadata.gz: 1f6961dde0d54631bae2f2dae6325183cc678f81701aa06575abab88cc1b0f7b
+  data.tar.gz: cc20cca8c229dca80fbd57d9950794b71560ccb2c13e0ace82c9b6cab0a0c93c
 SHA512:
-  metadata.gz: a5736e1156b6e7535bbe62089bd4d0f197b249df25b0fe4949c4dea682725a536cf211292728398ba68cdb455456a23de761c311f12da00e0b33eb3610e30555
-  data.tar.gz: c8a1ecc40eedfd40c9f553a2867a34032bdb37abdbb981204a419036acf9160c0e5b45938718166d84429f65425fd70754c2630f259607dd431017d5d7bd178a
+  metadata.gz: cdf5e192d7d3b526311ca7e9b6d6d3d81a50b3a14d8bd9b4b4a5d4459c0ed4d34c4695e1087e109614cf6f5dc040a12b0e7686f4e4cf509e16f4c9b770a0ccfa
+  data.tar.gz: 3664cc36ac24eb3f1a0bd6061a3671c32695113d50dd87753a35ec13536d02330fa7f10c7188439e90726a9b3a80dac227205cbaf88f539cb668dd7d18ea628d

data/config/default.yml

@@ -250,10 +250,14 @@ DevDoc/Style/TapBlockIgnoresValue:
   Enabled: true
 
 DevDoc/Style/AvoidHeadResponse:
-  Description: "Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations."
+  Description: "Avoid `head()` with error or no-content statuses; render a body (an exception page, validation errors, or an action spec) instead."
   Enabled: true
   Include:
     - "app/controllers/**/*.rb"
+  # Error statuses: delegate to Rails exceptions / model validations.
+  # No-content "successes" (no_content/reset_content): a bodyless response is
+  # ambiguous to a backend-driven JSON client -- render an action response,
+  # even an empty one.
   FlaggedStatuses:
     - not_found
     - unprocessable_entity
@@ -263,6 +267,8 @@ DevDoc/Style/AvoidHeadResponse:
     - conflict
     - gone
     - method_not_allowed
+    - no_content
+    - reset_content
     - "404"
     - "422"
     - "403"
@@ -271,6 +277,8 @@ DevDoc/Style/AvoidHeadResponse:
     - "409"
     - "410"
     - "405"
+    - "204"
+    - "205"
 
 DevDoc/Migration/AvoidConditionalSchemaChanges:
   Description: "Avoid conditional schema helpers (`add_column_if_not_exists`, `column_exists?`, etc.) in migrations."

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

@@ -2,7 +2,7 @@ module RuboCop
   module Cop
     module DevDoc
       module Style
-        # Avoid `head()` with error status codes in controllers.
+        # Avoid `head()` with error or no-content status codes in controllers.
         #
         # ## Rationale
         # Using `head()` for error responses returns an empty body with no
@@ -10,8 +10,15 @@ module RuboCop
         # to Rails exceptions (e.g. `ActiveRecord::RecordNotFound`) or model
         # validations instead, which give the client more context.
         #
-        # Success statuses like `:ok`, `:no_content`, and `:accepted` are
-        # legitimate uses of `head()` and are not flagged.
+        # `head :no_content` (and `:reset_content`) is flagged for a different
+        # reason: in a backend-driven JSON UI a bodyless "success" is
+        # ambiguous — the client needs a response body (even an empty action
+        # spec) to know what to do. A production `head :no_content` escape
+        # hatch surfaced as an error snackbar in front of a customer before
+        # this was flagged.
+        #
+        # Success statuses that normally carry a body (`:ok`, `:accepted`)
+        # are legitimate uses of `head()` and are not flagged.
         #
         # The set of flagged statuses is configurable via `FlaggedStatuses:`.
         #
@@ -26,12 +33,18 @@ module RuboCop
         #     @user = User.find(params[:id])
         #   end
         #
-        #   ✔️ Success response — empty body is correct here
+        #   ❌ Bodyless success — a JSON-driven client learns nothing
         #   def destroy
         #     @resource.destroy!
         #     head :no_content
         #   end
         #
+        #   ✔️ Tell the client what to do, even when that is "nothing"
+        #   def destroy
+        #     @resource.destroy!
+        #     render json: {}
+        #   end
+        #
         # @example
         #   # bad
         #   head(:not_found)
@@ -39,10 +52,10 @@ module RuboCop
         #   # bad
         #   head(:unprocessable_entity)
         #
-        #   # good (success status — not flagged)
+        #   # bad (bodyless success — ambiguous to a JSON-driven client)
         #   head(:no_content)
         #
-        #   # good (success status — not flagged)
+        #   # good (success status with a body expected — not flagged)
         #   head(:ok)
         #
         #   # good (dynamic status — not flagged to avoid false positives)
@@ -51,13 +64,18 @@ module RuboCop
           MSG = 'Avoid `head(%<status>s)` for error handling. ' \
                 'Delegate to Rails exceptions or model validations instead.'.freeze
 
+          NO_CONTENT_MSG = 'Avoid `head(%<status>s)`: a bodyless response tells a JSON-driven ' \
+                           'client nothing. Render an action response (even an empty one) instead.'.freeze
+
           RESTRICT_ON_SEND = %i[head].freeze
 
-          DEFAULT_FLAGGED_STATUSES = %w[
+          NO_CONTENT_STATUSES = %w[no_content reset_content 204 205].freeze
+
+          DEFAULT_FLAGGED_STATUSES = (%w[
             not_found unprocessable_entity forbidden unauthorized
             bad_request conflict gone method_not_allowed
             404 422 403 401 400 409 410 405
-          ].freeze
+          ] + NO_CONTENT_STATUSES).freeze
 
           def on_send(node)
             # `self.head(...)` is the same controller call — a bare receiver
@@ -68,7 +86,8 @@ module RuboCop
             return unless status_node
             return unless flagged_literal?(status_node)
 
-            add_offense(node.loc.selector, message: format(MSG, status: status_display(status_node)))
+            template = NO_CONTENT_STATUSES.include?(status_node.value.to_s) ? NO_CONTENT_MSG : MSG
+            add_offense(node.loc.selector, message: format(template, status: status_display(status_node)))
           end
 
           private

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.13.2".freeze
+    VERSION = "0.14.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.14.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-06 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport