rubocop-gusto 11.2.0 → 11.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd7d9b067df7edfe822d63daa4c1ffb54b54086cbf80f185ca20888a513d88ec
-  data.tar.gz: 4f62f8d399612f2aa26e929b765b33e54324bee3306c27f515b43e15f0c3111f
+  metadata.gz: 42abd3d1b5e56856b77781b5554a87abea61c419665b553d7bc61053203383cb
+  data.tar.gz: 5989d13ccea81744e6a44524003952a304df90e054a2a64ca572ec50d6e2d473
 SHA512:
-  metadata.gz: 5393a0a5937de49f0f70bfd74f401bcabe17a0c24292a9921277d2f81dbf51661e730995b16db0c3de5888ef7e3842236016f156fc94b7446f1eb8693a8beb77
-  data.tar.gz: 53114fe101a37c7d0a34f291e038b70c16186c8b4352991d7b7bd03e40b8b293281e62b1adc8fd4d2c6fdeabcc143bd7ff262baaef4c471e5e895f00e843803d
+  metadata.gz: 5f77ba3fdfcc4ad8fe904599840fc2388baf724b826e0722544d724e9f679b1e5ea2b00cb99f184a3b5b8ae45efccec0b6466cf87c43654ba33b7492f9ffd524
+  data.tar.gz: 64f68fa5679a0207ccd9f843447349211cc65f617a08cdd636e5903987c758945eae9317feea61f8a9286d030b3fbf2c3a4fc99168805a85d68097e79acf1672

data/CHANGELOG.md

@@ -3,6 +3,68 @@
 - Remove redundant `Rails: Enabled: true` from `config/rails.yml` (already set by rubocop-rails' own defaults)
 - Enable `Rails/DefaultScope` cop (disabled by default in rubocop-rails)
 
+## [11.8.0](https://github.com/Gusto/rubocop-gusto/compare/v11.7.1...v11.8.0) (2026-09-02)
+
+
+### Features
+
+* add the Gusto/Graphql cop department, backed by rubocop-graphql ([#170](https://github.com/Gusto/rubocop-gusto/issues/170)) ([98cd994](https://github.com/Gusto/rubocop-gusto/commit/98cd99467d1c50a4c3fb50f48f1dfa0e2905f6b4))
+
+## [11.7.1](https://github.com/Gusto/rubocop-gusto/compare/v11.7.0...v11.7.1) (2026-08-17)
+
+
+### Bug Fixes
+
+* scope Gusto/VcrRecordings to specs ([#161](https://github.com/Gusto/rubocop-gusto/issues/161)) ([923d1b1](https://github.com/Gusto/rubocop-gusto/commit/923d1b1ab4b2af56a6e786afe13755aefdff502e))
+
+## [11.7.0](https://github.com/Gusto/rubocop-gusto/compare/v11.6.1...v11.7.0) (2026-08-11)
+
+
+### Features
+
+* add Gusto/Sorbet/PredicateBooleanReturn (opt-in) and Gusto/SuddenAssociations cops ([#157](https://github.com/Gusto/rubocop-gusto/issues/157)) ([f123bbb](https://github.com/Gusto/rubocop-gusto/commit/f123bbbcafdf5b2e38339fa6c541444b4902eb9c))
+
+## [11.6.1](https://github.com/Gusto/rubocop-gusto/compare/v11.6.0...v11.6.1) (2026-07-27)
+
+
+### Bug Fixes
+
+* allow serialize/from_hash/insert_record overrides in Style/OptionalBooleanParameter ([#152](https://github.com/Gusto/rubocop-gusto/issues/152)) ([28e5a3e](https://github.com/Gusto/rubocop-gusto/commit/28e5a3eaa78b592d724a8d3b3044ef847d81e3dc))
+
+## [11.6.0](https://github.com/Gusto/rubocop-gusto/compare/v11.5.0...v11.6.0) (2026-07-22)
+
+
+### Features
+
+* enable Sorbet/RedundantTLetForLiteral and bump rubocop-sorbet for RedundantTLet cops ([#154](https://github.com/Gusto/rubocop-gusto/issues/154)) ([3098b7e](https://github.com/Gusto/rubocop-gusto/commit/3098b7e413c53831354c4c9e8e5337ab743d2a27))
+* enable Sorbet/RedundantTLetForLiteral, bump rubocop-sorbet for RedundantTLet cops ([3098b7e](https://github.com/Gusto/rubocop-gusto/commit/3098b7e413c53831354c4c9e8e5337ab743d2a27))
+
+
+### Bug Fixes
+
+* remove git dependency from Gusto/UnreferencedLet ([#153](https://github.com/Gusto/rubocop-gusto/issues/153)) ([933f5b0](https://github.com/Gusto/rubocop-gusto/commit/933f5b0ec86b422caf0d6e6d460c468e8c00c408))
+
+## [11.5.0](https://github.com/Gusto/rubocop-gusto/compare/v11.4.0...v11.5.0) (2026-07-14)
+
+
+### Features
+
+* add Gusto/RedundantSpecHelperRequire cop (ADR 116, with autofix) ([#149](https://github.com/Gusto/rubocop-gusto/issues/149)) ([83c22c9](https://github.com/Gusto/rubocop-gusto/commit/83c22c9ee4fb0bc8a5faff11769570009892cccd))
+
+## [11.4.0](https://github.com/Gusto/rubocop-gusto/compare/v11.3.0...v11.4.0) (2026-07-13)
+
+
+### Features
+
+* add Gusto/ConstantSafety cop ([#148](https://github.com/Gusto/rubocop-gusto/issues/148)) ([7ee7925](https://github.com/Gusto/rubocop-gusto/commit/7ee7925094a7df531d1a9eb078e474fa89b3c133))
+
+## [11.3.0](https://github.com/Gusto/rubocop-gusto/compare/v11.2.0...v11.3.0) (2026-06-29)
+
+
+### Features
+
+* add Gusto/FeatureFlagConstants cop (RR-890) ([#144](https://github.com/Gusto/rubocop-gusto/issues/144)) ([9058e0e](https://github.com/Gusto/rubocop-gusto/commit/9058e0e3055445a6be1818f2c142013239773bb5))
+
 ## [11.2.0](https://github.com/Gusto/rubocop-gusto/compare/v11.1.1...v11.2.0) (2026-06-26)
 
 

data/README.md

@@ -32,6 +32,47 @@ This adds `rubocop-gusto` to your `.rubocop.yml` `plugins:` list and includes an
 
 If this is an existing project, it is recommended to run the autocorrector (`bundle exec rubocop -a`) and then to regenerate the `.rubocop_todo.yml` (`bundle exec rubocop --auto-gen-config`), so issues can be dealt with piecemeal.
 
+#### GraphQL configuration
+
+The `Gusto/Graphql` cops lint the [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) schema
+DSL. They live in `config/graphql.yml`, which also configures the `GraphQL` cops from
+[rubocop-graphql](https://github.com/DmitryTsepelev/rubocop-graphql) — several of them cops Gusto
+contributed upstream rather than keep here. Neither is in `config/default.yml`, so projects without
+a GraphQL schema are not linted for those patterns.
+
+Running `bundle exec rubocop-gusto init` does all of it when `graphql` is in your `Gemfile` or
+`Gemfile.lock`: adds `rubocop-graphql` to your Gemfile and `plugins:` list, and adds
+`config/graphql.yml` to your `inherit_gem` list. rubocop-graphql is deliberately *not* a dependency
+of this gem, for the same reason rubocop-rails is not — so rubocop-gusto stays usable from a plain
+gem.
+
+`GraphQL/DisallowedTypes` is where a project names the types it has decided not to expose. It is
+inert until configured, and the reason is per type, so it needs no `Details:`:
+
+```yaml
+GraphQL/DisallowedTypes:
+  Types:
+    Float: 'Use MyApp::GraphQL::Scalars::Decimal, which serializes as a string.'
+    MyApp::Scalars::LegacyDate: 'Use GraphQL::Types::ISO8601Date.'
+```
+
+By default the `Gusto/Graphql` department is scoped to `**/graphql/**/*`.
+`Gusto/Graphql/ResolverIgnoresObject` reads `NodeAccessors`, which lists methods your GraphQL base
+classes provide that read the node without naming `object`; leave it empty and the cop reports
+those resolvers as offenses.
+
+Several of these cops replace a project-specific convention with a generic message. Put the
+convention your project actually follows in the cop's `Details:`, and set
+`AllCops: ExtraDetails: true` so it is appended to the offense message:
+
+```yaml
+AllCops:
+  ExtraDetails: true
+
+Gusto/Graphql/PaginateArrays:
+  Details: 'Use `paginated_list(<Type>)`, or `non_paginated_list(<Type>)` for a bounded list.'
+```
+
 #### Sidekiq configuration
 
 Sidekiq-specific cops live in `config/sidekiq.yml` and are **not** included in `config/default.yml`, so projects without Sidekiq are not linted for those patterns. Running `bundle exec rubocop-gusto init` adds `config/sidekiq.yml` to your `inherit_gem` list automatically when Sidekiq is listed in your `Gemfile` or `Gemfile.lock`.
@@ -52,6 +93,7 @@ If your project also uses Rails, include `config/rails.yml` as well (order does
 Custom cops live under the following namespaces:
 
 - `Gusto/` — general Gusto-specific cops (see [`lib/rubocop/cop/gusto/`](lib/rubocop/cop/gusto/))
+- `Gusto/Graphql/` — cops scoped to the graphql-ruby schema DSL (see [`lib/rubocop/cop/gusto/graphql/`](lib/rubocop/cop/gusto/graphql/)); configured in [`config/graphql.yml`](config/graphql.yml)
 - `Sidekiq/` — cops scoped to Sidekiq patterns (see [`lib/rubocop/cop/sidekiq/`](lib/rubocop/cop/sidekiq/)); configured in [`config/sidekiq.yml`](config/sidekiq.yml)
 - `Rack/` — cops scoped to Rack middleware patterns (see [`lib/rubocop/cop/rack/`](lib/rubocop/cop/rack/))
 

data/config/default.yml

@@ -274,6 +274,11 @@ Sorbet/ForbidTUnsafe:
   # reorganizing the code over silently turning off the type checker.
   Enabled: true
 
+Sorbet/RedundantTLetForLiteral:
+  # Still marked pending upstream, we'd like to enable it now. Remove this
+  # override once it's no longer pending in rubocop-sorbet.
+  Enabled: true
+
 Sorbet/Refinement:
   # Still marked pending upstream, we contributed this and enable it here.
   Enabled: true
@@ -498,6 +503,11 @@ Style/OptionalBooleanParameter:
   AllowedMethods:
     - respond_to_missing?
     - perform # Sidekiq does not support keyword arguments.
+    - serialize # Overrides Sorbet's T::Props::Serializable#serialize(strict=true).
+    - from_hash # Overrides Sorbet's T::Props::Serializable#from_hash(hash, strict=false).
+    - insert_record # Overrides Rails' ActiveRecord::Associations::HasManyThroughAssociation#insert_record.
+    - lock # Overrides Rails' ActiveRecord::QueryMethods#lock(locks=true).
+    - lock! # Overrides Rails' ActiveRecord::Locking::Pessimistic#lock!(lock=true).
 
 Style/PercentLiteralDelimiters:
   PreferredDelimiters:

data/config/graphql.yml

@@ -0,0 +1,44 @@
+#
+# This file should be inherited alongside default.yml for projects using graphql-ruby
+#
+# It configures both the `Gusto/Graphql` cops in this gem and the `GraphQL` cops from
+# rubocop-graphql, which `init` adds to the project's Gemfile and `plugins:` list.
+#
+# After you add a rule, sort this file with `bundle exec rubocop-gusto sort config/graphql.yml`
+
+GraphQL/DefaultForOptionalArgument:
+  Enabled: true
+
+GraphQL/DisallowedTypes:
+  Enabled: true
+  # Nothing is disallowed until a project fills this in; the keys are matched against the
+  # written constant exactly or as a trailing segment, so `Float` also covers
+  # `GraphQL::Types::Float`.
+  Types: {}
+
+GraphQL/NullabilityMismatch:
+  Enabled: true
+
+Gusto/Graphql/IdFieldArgumentDescription:
+  Enabled: true
+
+Gusto/Graphql/IdFieldDescription:
+  Enabled: true
+
+Gusto/Graphql/IdInputArgumentDescription:
+  Enabled: true
+
+Gusto/Graphql/PaginateArrays:
+  Enabled: true
+
+Gusto/Graphql/PreventContextHashAccess:
+  Enabled: true
+
+Gusto/Graphql/PreventFieldCanCanAction:
+  Enabled: true
+
+Gusto/Graphql/ResolverIgnoresObject:
+  Enabled: true
+
+Gusto/Graphql/TypeVariables:
+  Enabled: true

data/config/gusto_cops.yml

@@ -12,6 +12,9 @@
 Gusto/BootsnapLoadFile:
   Description: 'Do not use Bootsnap to load files. Use `require` instead.'
 
+Gusto/ConstantSafety:
+  Description: 'Flags safe navigation (`&.`) on a constant (class/module or SCREAMING_CASE); constants are never nil, so `.` should be used instead.'
+
 Gusto/DatadogConstant:
   Exclude:
     # calling DataDog directly only allowed in initializers, its library, and tests
@@ -43,6 +46,50 @@ Gusto/FactoryClassesOrModules:
   Include:
     - 'spec/**/factories/*.rb'
 
+Gusto/FeatureFlagConstants:
+  Description: 'FeatureFlag keys should be constants, not strings.'
+
+Gusto/Graphql:
+  # GraphQL code conventionally lives under a `graphql` directory. Projects that lay it out
+  # differently should override this Include rather than each cop's.
+  Include:
+    - '**/graphql/**/*'
+
+Gusto/Graphql/IdFieldArgumentDescription:
+  Description: 'Requires ID arguments on query fields to follow the standard description template.'
+  Enabled: false
+
+Gusto/Graphql/IdFieldDescription:
+  Description: 'Requires ID fields to follow the standard description template.'
+  Enabled: false
+
+Gusto/Graphql/IdInputArgumentDescription:
+  Description: 'Requires ID arguments on mutations and input objects to follow the standard description template.'
+  Enabled: false
+
+Gusto/Graphql/PaginateArrays:
+  Description: 'Flags a GraphQL field typed as an unbounded array rather than a paginated list.'
+  Enabled: false
+
+Gusto/Graphql/PreventContextHashAccess:
+  Description: 'Disallows hash access on the GraphQL context; use typed context methods instead.'
+  Enabled: false
+
+Gusto/Graphql/PreventFieldCanCanAction:
+  Description: 'Flags the deprecated `can_can_action:` option on a GraphQL field declaration.'
+  Enabled: false
+
+Gusto/Graphql/ResolverIgnoresObject:
+  Description: 'Flags a GraphQL field whose resolver never reads `object`, so the value is the same for every node.'
+  Enabled: false
+  # Methods inherited from a base class that read the node without naming `object`. A project
+  # whose GraphQL bases offer such helpers must list them here or the cop reports false positives.
+  NodeAccessors: []
+
+Gusto/Graphql/TypeVariables:
+  Description: 'Requires `type_member` and `type_template` in GraphQL objects to name a type rather than `T.untyped`.'
+  Enabled: false
+
 Gusto/MinByMaxBy:
   Description: 'Checks for the use of `min` or `max` with a proc. Corrects to `min_by` or `max_by`.'
   Safe: false
@@ -89,6 +136,12 @@ Gusto/RakeConstants:
     - '**/*.rake'
     - 'Rakefile'
 
+Gusto/RedundantSpecHelperRequire:
+  Description: "Removes an inline require 'spec_helper'/'rails_helper' already auto-required by the governing .rspec."
+  Include:
+    - '**/spec/**/*'
+  SafeAutoCorrect: false
+
 Gusto/RegexpBypass:
   Description: 'Ensures regular expressions use \A and \z anchors instead of ^ and $ for security validation.'
   Exclude:
@@ -108,6 +161,21 @@ Gusto/SmartTodoTeam:
   Description: 'TODO comments must be SmartTodo-formatted and target a valid team (CodeTeams).'
   Enabled: false
 
+Gusto/Sorbet/PredicateBooleanReturn:
+  Description: 'Predicate methods in Sorbet-typed files should return T::Boolean.'
+  # Opted into via config/sorbet.yml when the project depends on Sorbet.
+  Enabled: false
+  # Autocorrect rewrites the signature and coerces the return value with `!!()`,
+  # which can change behavior in subtle ways.
+  SafeAutoCorrect: false
+
+Gusto/SuddenAssociations:
+  Description: 'Prevents defining Rails associations on another class from outside the class body.'
+  # Opted into via config/rails.yml; the association DSL only exists in a Rails project.
+  Enabled: false
+  Exclude:
+    - '**/spec/**/*' # allow stubbing, although this is still odd
+
 Gusto/ToplevelConstants:
   Description: 'Prevents top-level constants from being defined outside of initializers.'
   Include:
@@ -137,6 +205,8 @@ Gusto/UsePaintNotColorize:
 
 Gusto/VcrRecordings:
   Description: 'VCR should be set to not record in tests. Use vcr: {record: :none}.'
+  Include:
+    - '**/spec/**/*'
 
 # We extend this via Gusto/SmartTodoTeam; don't let the upstream cop run standalone.
 SmartTodo/SmartTodoCop:

data/config/obsoletion.yml

@@ -0,0 +1,24 @@
+# Obsolete configuration reported by `ConfigObsoletion`, registered from
+# `RuboCop::Gusto::Plugin#rules`.
+#
+# The `Graphql/*` department was a private, in-repo department before these cops moved into
+# this gem, where they live in the `Gusto/Graphql` sub-department. `Graphql` also sits one
+# capital letter away from `GraphQL`, the department shipped by rubocop-graphql, so keeping
+# the old spelling would have left two near-identical departments in one config.
+#
+# Four of them were contributed to rubocop-graphql itself and are not duplicated here, so
+# they point into that gem's `GraphQL` department instead. `PreventFloat` and
+# `PreventScalarsDate` were generalized into one config-driven `GraphQL/DisallowedTypes`.
+renamed:
+  Graphql/DefaultForOptionalArgument: GraphQL/DefaultForOptionalArgument
+  Graphql/IdFieldArgumentDescription: Gusto/Graphql/IdFieldArgumentDescription
+  Graphql/IdFieldDescription: Gusto/Graphql/IdFieldDescription
+  Graphql/IdInputArgumentDescription: Gusto/Graphql/IdInputArgumentDescription
+  Graphql/NullabilityMismatch: GraphQL/NullabilityMismatch
+  Graphql/PaginateArrays: Gusto/Graphql/PaginateArrays
+  Graphql/PreventContextHashAccess: Gusto/Graphql/PreventContextHashAccess
+  Graphql/PreventFieldCanCanAction: Gusto/Graphql/PreventFieldCanCanAction
+  Graphql/PreventFloat: GraphQL/DisallowedTypes
+  Graphql/PreventScalarsDate: GraphQL/DisallowedTypes
+  Graphql/ResolverIgnoresObject: Gusto/Graphql/ResolverIgnoresObject
+  Graphql/TypeVariables: Gusto/Graphql/TypeVariables

data/config/rails.yml

@@ -21,6 +21,9 @@ Gusto/DiscouragedGem:
 Gusto/PluckOnSelect:
   Description: "Do not use `.pluck` on `.select`. Use one or the other."
 
+Gusto/SuddenAssociations:
+  Enabled: true
+
 Performance/DoubleStartEndWith:
   IncludeActiveSupportAliases: true
 

data/config/sorbet.yml

@@ -0,0 +1,7 @@
+#
+# This file should be inherited alongside default.yml for projects using Sorbet
+#
+# After you add a rule, sort this file with `bundle exec rubocop-gusto sort config/sorbet.yml`
+
+Gusto/Sorbet/PredicateBooleanReturn:
+  Enabled: true

data/lib/rubocop/cop/gusto/constant_safety.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      # Flags safe navigation (`&.`) called on a constant, covering both
+      # class/module constants (`Model&.find`) and SCREAMING_CASE constants
+      # (`CONST&.each`).
+      #
+      # A constant reference is never `nil`, an undefined constant raises
+      # `NameError` before the call is even attempted, so the safe navigation
+      # operator is always redundant. Use the plain `.` operator instead.
+      #
+      # @example
+      #   # bad
+      #   Model&.find(id)
+      #   ENTITY_TYPES&.each { |type| type.to_s }
+      #   Foo::Bar&.call
+      #   ::Foo&.call
+      #
+      #   # good
+      #   Model.find(id)
+      #   ENTITY_TYPES.each { |type| type.to_s }
+      #   Foo::Bar.call
+      #   ::Foo.call
+      class ConstantSafety < Base
+        extend AutoCorrector
+
+        MSG = "Do not use safe navigation (`&.`) on a constant; constants are never `nil`, so use `.` instead."
+
+        def on_csend(node)
+          return unless node.receiver.const_type?
+
+          add_offense(node.loc.dot) do |corrector|
+            corrector.replace(node.loc.dot, ".")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/gusto/feature_flag_constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      # Enforces that `FeatureFlag.active?` is called with a constant rather than a
+      # string literal. Defining flag keys as constants keeps them in one place,
+      # makes typos a load-time error instead of a silent always-off flag, and lets
+      # tools find every reference to a flag.
+      #
+      # `FeatureFlag` is a constant, so it is never nil and safe navigation
+      # (`FeatureFlag&.active?`) is never used; the cop only handles `on_send`.
+      #
+      # @example
+      #   # bad
+      #   FeatureFlag.active?("some_feature_flag")
+      #
+      #   # good
+      #   FeatureFlag.active?(SomeModule::SOME_FEATURE_FLAG)
+      class FeatureFlagConstants < Base
+        MSG = "FeatureFlag keys should be constants, not strings"
+        RESTRICT_ON_SEND = %i(active?).freeze
+
+        # @!method feature_flag_with_string?(node)
+        def_node_matcher :feature_flag_with_string?, <<~PATTERN
+          (send (const nil? :FeatureFlag) :active? (str _) ...)
+        PATTERN
+
+        def on_send(node)
+          add_offense(node) if feature_flag_with_string?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/gusto/graphql/id_description_concerns.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      module Graphql
+        module IdDescriptionConcerns
+          # analytics_id is intentionally excluded
+          PRIMARY_ID_FIELDS = %i(id uuid).freeze
+
+          # Matches a GraphQL field declaration capturing name and type node.
+          FIELD_CALL_PATTERN = RuboCop::AST::NodePattern.new(<<~PATTERN)
+            (send nil? :field (sym $_name) $_ ...)
+          PATTERN
+
+          # Matches a GraphQL argument declaration capturing name and type node.
+          ARGUMENT_CALL_PATTERN = RuboCop::AST::NodePattern.new(<<~PATTERN)
+            (send nil? :argument (sym $_name) $_ ...)
+          PATTERN
+
+          # Mutation / input-object base classes conventionally end in one of these final
+          # segments (e.g. `Base::PermissionedMutation`, `Gusto::GraphQL::Objects::BaseInputObject`,
+          # `Base::Input`). We match on the base class's final name segment rather than a substring
+          # of its source, so unrelated bases that merely *contain* the word (e.g.
+          # `GraphQLMutationTool`, `MutationHelper`) are not misclassified.
+          MUTATION_OR_INPUT_BASE_SUFFIXES = %w(Mutation InputObject Input).freeze
+
+          def field_call?(node, &block)
+            FIELD_CALL_PATTERN.match(node, &block)
+          end
+
+          def argument_call?(node, &block)
+            ARGUMENT_CALL_PATTERN.match(node, &block)
+          end
+
+          private
+
+          def id_type?(type_node)
+            return false unless type_node
+            return false unless type_node.const_type?
+
+            const_name = type_node.const_name
+            const_name == "ID" || const_name == "GraphQL::Types::ID"
+          end
+
+          def array_id_type?(type_node)
+            return false unless type_node
+
+            # Match: [ID] or [GraphQL::Types::ID]
+            if type_node.array_type?
+              inner = type_node.children.first
+              return id_type?(inner)
+            end
+
+            false
+          end
+
+          def extract_description(node)
+            description_from_positional_argument(node) ||
+              description_from_keyword_argument(node) ||
+              description_from_block(node)
+          end
+
+          def description_from_positional_argument(node)
+            node.arguments.find(&:str_type?)&.value
+          end
+
+          def description_from_keyword_argument(node)
+            node.each_child_node(:hash) do |arg|
+              arg.each_pair do |key, value|
+                return value.value if key.sym_type? && key.value == :description && value.str_type?
+              end
+            end
+
+            nil
+          end
+
+          def description_from_block(node)
+            parent = node.parent
+            return nil unless parent&.block_type? && parent.send_node == node
+
+            parent.body&.each_node(:send) do |send_node|
+              if send_node.method?(:description) && send_node.first_argument&.str_type?
+                return send_node.first_argument.value
+              end
+            end
+
+            nil
+          end
+
+          # Find the GraphQL type name for the enclosing class or module
+          # Prefers graphql_name declaration over Ruby class/module name
+          # Returns nil if the name cannot be determined
+          def find_graphql_type_name(node)
+            # Try class first (most common), then module (for interfaces)
+            type_node = node.each_ancestor(:class).first || node.each_ancestor(:module).first
+            return nil unless type_node
+
+            # Look for graphql_name declaration in the type body
+            graphql_name = find_graphql_name_declaration(type_node)
+            return graphql_name if graphql_name
+
+            # Fall back to Ruby class/module name, stripping common suffixes
+            # GraphQL-ruby automatically strips "Type" from class names
+            # Interfaces conventionally use "Interface" suffix
+            # Also strip module namespacing, only use the final name
+            const_node = type_node.children.first
+            return nil unless const_node
+
+            full_name = const_node.const_name
+            type_name = full_name.split("::").last
+            strip_graphql_suffix(type_name)
+          end
+
+          def strip_graphql_suffix(name)
+            name.chomp("Type").chomp("Interface")
+          end
+
+          def find_graphql_name_declaration(type_node)
+            type_body = type_node.body
+            return nil unless type_body
+
+            nodes = type_body_nodes(type_body)
+            graphql_name_call = find_graphql_name_call(nodes)
+            return nil unless graphql_name_call
+
+            first_arg = graphql_name_call.first_argument
+            first_arg.value if first_arg&.str_type?
+          end
+
+          def type_body_nodes(type_body)
+            if type_body.begin_type?
+              type_body.children
+            else
+              [type_body]
+            end
+          end
+
+          def find_graphql_name_call(nodes)
+            nodes.find { |node| node.send_type? && node.method?(:graphql_name) }
+          end
+
+          def in_mutation_or_input_object?(node)
+            node.each_ancestor(:class).any? do |class_node|
+              base = class_node.parent_class
+              next false unless base&.const_type?
+
+              base.short_name.to_s.end_with?(*MUTATION_OR_INPUT_BASE_SUFFIXES)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/gusto/graphql/id_field_argument_description.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "id_description_concerns"
+
+module RuboCop
+  module Cop
+    module Gusto
+      module Graphql
+        # Ensures ID type arguments on query fields follow the standardized description template:
+        # "The identifier of the <ObjectName> (`<ObjectName.fieldName>`) to filter by"
+        # "The identifiers of each <ObjectName> (`<ObjectName.fieldName>`) to filter by" (for arrays)
+        #
+        # This cop only applies to arguments on regular GraphQL objects/queries,
+        # NOT on mutations or input objects (see IdInputArgumentDescription for those).
+        #
+        # @example Bad
+        #   argument :employee_id, ID, 'Employee ID', required: true
+        #
+        # @example Good
+        #   argument :employee_id, ID, 'The identifier of the Employee (`Employee.id`) to filter by', required: true
+        #   argument :employee_ids, [ID], 'The identifiers of each Employee (`Employee.id`) to filter by', required: true
+        #
+        class IdFieldArgumentDescription < Base
+          include IdDescriptionConcerns
+
+          MSG = "ID argument description should match template: " \
+                "'The identifier of the <ObjectName> (`<ObjectName.fieldName>`) to filter by'."
+
+          RESTRICT_ON_SEND = %i(argument).freeze
+
+          # A single "<ObjectName> (`<ObjectName.fieldName>`)" reference. Multiple may be joined
+          # with " or " for arguments that accept an id from more than one entity.
+          TYPE_REF = /\w+ \(`\w+\.\w+`\)/
+
+          # Single: "The identifier of the <ObjectName> (`<ObjectName.fieldName>`) to filter by"
+          SINGLE_PATTERN = /\AThe identifier of the #{TYPE_REF}(?: or #{TYPE_REF})* to filter by/
+
+          # Array: "The identifiers of each <ObjectName> (`<ObjectName.fieldName>`) to filter by"
+          ARRAY_PATTERN = /\AThe identifiers of each #{TYPE_REF}(?: or #{TYPE_REF})* to filter by/
+
+          def on_send(node)
+            # Skip if we're in a mutation or input object context because there's another cop for that
+            return if in_mutation_or_input_object?(node)
+
+            argument_call?(node) do |_name, type_node|
+              is_array = array_id_type?(type_node)
+              return unless id_type?(type_node) || is_array
+
+              desc = extract_description(node)
+              return if desc.nil? # No description - let other cops handle missing descriptions
+              return if valid_argument_description?(desc, is_array)
+
+              add_offense(node)
+            end
+          end
+
+          private
+
+          def valid_argument_description?(desc, is_array)
+            # Only validate the pattern format, not the object name.
+            # The object name should reference the actual GraphQL type,
+            # which may differ from what we'd infer from the argument name.
+            # e.g., argument :device_id could reference TrustedDevice type
+            pattern = is_array ? ARRAY_PATTERN : SINGLE_PATTERN
+            pattern.match?(desc)
+          end
+        end
+      end
+    end
+  end
+end