Merge branch 'ld-enforce-graphql-description-starts' into 'master'

Enforce GraphQL descriptions styleguide for A/The

See merge request gitlab-org/gitlab!67473

.rubocop_manual_todo.yml

@@ -22,6 +22,273 @@ Graphql/Descriptions:
     - 'ee/app/graphql/types/vulnerability_report_type_enum.rb'
     - 'ee/app/graphql/types/vulnerability_severity_enum.rb'
     - 'ee/app/graphql/types/vulnerability_state_enum.rb'
+    - 'app/graphql/mutations/admin/sidekiq_queues/delete_jobs.rb'
+    - 'app/graphql/mutations/alert_management/alerts/set_assignees.rb'
+    - 'app/graphql/mutations/alert_management/base.rb'
+    - 'app/graphql/mutations/alert_management/http_integration/create.rb'
+    - 'app/graphql/mutations/alert_management/http_integration/destroy.rb'
+    - 'app/graphql/mutations/alert_management/http_integration/http_integration_base.rb'
+    - 'app/graphql/mutations/alert_management/http_integration/reset_token.rb'
+    - 'app/graphql/mutations/alert_management/http_integration/update.rb'
+    - 'app/graphql/mutations/alert_management/prometheus_integration/create.rb'
+    - 'app/graphql/mutations/alert_management/prometheus_integration/prometheus_integration_base.rb'
+    - 'app/graphql/mutations/alert_management/prometheus_integration/reset_token.rb'
+    - 'app/graphql/mutations/alert_management/prometheus_integration/update.rb'
+    - 'app/graphql/mutations/alert_management/update_alert_status.rb'
+    - 'app/graphql/mutations/award_emojis/base.rb'
+    - 'app/graphql/mutations/boards/common_mutation_arguments.rb'
+    - 'app/graphql/mutations/boards/create.rb'
+    - 'app/graphql/mutations/boards/destroy.rb'
+    - 'app/graphql/mutations/boards/lists/destroy.rb'
+    - 'app/graphql/mutations/boards/update.rb'
+    - 'app/graphql/mutations/ci/ci_cd_settings_update.rb'
+    - 'app/graphql/mutations/ci/job/base.rb'
+    - 'app/graphql/mutations/ci/job/play.rb'
+    - 'app/graphql/mutations/ci/job/retry.rb'
+    - 'app/graphql/mutations/ci/job_token_scope/add_project.rb'
+    - 'app/graphql/mutations/ci/job_token_scope/remove_project.rb'
+    - 'app/graphql/mutations/ci/pipeline/base.rb'
+    - 'app/graphql/mutations/ci/pipeline/retry.rb'
+    - 'app/graphql/mutations/ci/runner/update.rb'
+    - 'app/graphql/mutations/ci/runners_registration_token/reset.rb'
+    - 'app/graphql/mutations/commits/create.rb'
+    - 'app/graphql/mutations/concerns/mutations/assignable.rb'
+    - 'app/graphql/mutations/concerns/mutations/can_mutate_spammable.rb'
+    - 'app/graphql/mutations/concerns/mutations/resolves_subscription.rb'
+    - 'app/graphql/mutations/container_expiration_policies/update.rb'
+    - 'app/graphql/mutations/container_repositories/destroy.rb'
+    - 'app/graphql/mutations/custom_emoji/create.rb'
+    - 'app/graphql/mutations/design_management/base.rb'
+    - 'app/graphql/mutations/design_management/delete.rb'
+    - 'app/graphql/mutations/design_management/move.rb'
+    - 'app/graphql/mutations/design_management/upload.rb'
+    - 'app/graphql/mutations/discussions/toggle_resolve.rb'
+    - 'app/graphql/mutations/environments/canary_ingress/update.rb'
+    - 'app/graphql/mutations/groups/update.rb'
+    - 'app/graphql/mutations/issues/base.rb'
+    - 'app/graphql/mutations/issues/create.rb'
+    - 'app/graphql/mutations/issues/move.rb'
+    - 'app/graphql/mutations/issues/set_due_date.rb'
+    - 'app/graphql/mutations/issues/set_subscription.rb'
+    - 'app/graphql/mutations/issues/update.rb'
+    - 'app/graphql/mutations/jira_import/import_users.rb'
+    - 'app/graphql/mutations/jira_import/start.rb'
+    - 'app/graphql/mutations/labels/create.rb'
+    - 'app/graphql/mutations/merge_requests/accept.rb'
+    - 'app/graphql/mutations/merge_requests/base.rb'
+    - 'app/graphql/mutations/merge_requests/create.rb'
+    - 'app/graphql/mutations/merge_requests/reviewer_rereview.rb'
+    - 'app/graphql/mutations/merge_requests/set_labels.rb'
+    - 'app/graphql/mutations/merge_requests/set_milestone.rb'
+    - 'app/graphql/mutations/merge_requests/set_subscription.rb'
+    - 'app/graphql/mutations/merge_requests/update.rb'
+    - 'app/graphql/mutations/metrics/dashboard/annotations/create.rb'
+    - 'app/graphql/mutations/namespace/package_settings/update.rb'
+    - 'app/graphql/mutations/notes/base.rb'
+    - 'app/graphql/mutations/notes/create/base.rb'
+    - 'app/graphql/mutations/notes/create/note.rb'
+    - 'app/graphql/mutations/notes/destroy.rb'
+    - 'app/graphql/mutations/notes/reposition_image_diff_note.rb'
+    - 'app/graphql/mutations/notes/update/base.rb'
+    - 'app/graphql/mutations/notes/update/note.rb'
+    - 'app/graphql/mutations/release_asset_links/create.rb'
+    - 'app/graphql/mutations/release_asset_links/delete.rb'
+    - 'app/graphql/mutations/release_asset_links/update.rb'
+    - 'app/graphql/mutations/releases/create.rb'
+    - 'app/graphql/mutations/releases/delete.rb'
+    - 'app/graphql/mutations/releases/update.rb'
+    - 'app/graphql/mutations/snippets/base.rb'
+    - 'app/graphql/mutations/snippets/create.rb'
+    - 'app/graphql/mutations/snippets/destroy.rb'
+    - 'app/graphql/mutations/snippets/mark_as_spam.rb'
+    - 'app/graphql/mutations/snippets/update.rb'
+    - 'app/graphql/mutations/todos/create.rb'
+    - 'app/graphql/mutations/todos/mark_done.rb'
+    - 'app/graphql/mutations/todos/restore.rb'
+    - 'app/graphql/mutations/todos/restore_many.rb'
+    - 'app/graphql/mutations/user_callouts/create.rb'
+    - 'app/graphql/resolvers/admin/analytics/usage_trends/measurements_resolver.rb'
+    - 'app/graphql/resolvers/blobs_resolver.rb'
+    - 'app/graphql/resolvers/board_resolver.rb'
+    - 'app/graphql/resolvers/ci/config_resolver.rb'
+    - 'app/graphql/resolvers/concerns/resolves_snippets.rb'
+    - 'app/graphql/resolvers/design_management/design_at_version_resolver.rb'
+    - 'app/graphql/resolvers/design_management/version/design_at_version_resolver.rb'
+    - 'app/graphql/resolvers/design_management/version_in_collection_resolver.rb'
+    - 'app/graphql/resolvers/design_management/version_resolver.rb'
+    - 'app/graphql/resolvers/design_management/versions_resolver.rb'
+    - 'app/graphql/resolvers/full_path_resolver.rb'
+    - 'app/graphql/resolvers/labels_resolver.rb'
+    - 'app/graphql/resolvers/merge_requests_resolver.rb'
+    - 'app/graphql/resolvers/milestones_resolver.rb'
+    - 'app/graphql/resolvers/package_details_resolver.rb'
+    - 'app/graphql/resolvers/paginated_tree_resolver.rb'
+    - 'app/graphql/resolvers/release_resolver.rb'
+    - 'app/graphql/resolvers/repository_branch_names_resolver.rb'
+    - 'app/graphql/resolvers/snippets_resolver.rb'
+    - 'app/graphql/resolvers/todo_resolver.rb'
+    - 'app/graphql/resolvers/tree_resolver.rb'
+    - 'app/graphql/resolvers/users/snippets_resolver.rb'
+    - 'app/graphql/types/admin/analytics/usage_trends/measurement_type.rb'
+    - 'app/graphql/types/admin/sidekiq_queues/delete_jobs_response_type.rb'
+    - 'app/graphql/types/alert_management/alert_type.rb'
+    - 'app/graphql/types/award_emojis/award_emoji_type.rb'
+    - 'app/graphql/types/ci/config/job_restriction_type.rb'
+    - 'app/graphql/types/ci/config/status_enum.rb'
+    - 'app/graphql/types/ci/pipeline_type.rb'
+    - 'app/graphql/types/ci_configuration/sast/ui_component_size_enum.rb'
+    - 'app/graphql/types/commit_action_type.rb'
+    - 'app/graphql/types/container_repository_cleanup_status_enum.rb'
+    - 'app/graphql/types/container_repository_tag_type.rb'
+    - 'app/graphql/types/container_repository_type.rb'
+    - 'app/graphql/types/custom_emoji_type.rb'
+    - 'app/graphql/types/design_management/design_at_version_type.rb'
+    - 'app/graphql/types/design_management/design_fields.rb'
+    - 'app/graphql/types/diff_paths_input_type.rb'
+    - 'app/graphql/types/environment_type.rb'
+    - 'app/graphql/types/eventable_type.rb'
+    - 'app/graphql/types/group_type.rb'
+    - 'app/graphql/types/merge_request_type.rb'
+    - 'app/graphql/types/metadata/kas_type.rb'
+    - 'app/graphql/types/milestone_wildcard_id_enum.rb'
+    - 'app/graphql/types/namespace_type.rb'
+    - 'app/graphql/types/notes/note_type.rb'
+    - 'app/graphql/types/notes/position_type_enum.rb'
+    - 'app/graphql/types/packages/composer/json_type.rb'
+    - 'app/graphql/types/packages/package_details_type.rb'
+    - 'app/graphql/types/packages/package_file_type.rb'
+    - 'app/graphql/types/packages/package_tag_type.rb'
+    - 'app/graphql/types/packages/package_type.rb'
+    - 'app/graphql/types/project_type.rb'
+    - 'app/graphql/types/prometheus_alert_type.rb'
+    - 'app/graphql/types/query_type.rb'
+    - 'app/graphql/types/range_input_type.rb'
+    - 'app/graphql/types/release_asset_link_shared_input_arguments.rb'
+    - 'app/graphql/types/release_assets_input_type.rb'
+    - 'app/graphql/types/release_type.rb'
+    - 'app/graphql/types/repository/blob_type.rb'
+    - 'app/graphql/types/root_storage_statistics_type.rb'
+    - 'app/graphql/types/snippet_type.rb'
+    - 'app/graphql/types/snippets/blob_type.rb'
+    - 'app/graphql/types/snippets/visibility_scopes_enum.rb'
+    - 'app/graphql/types/terraform/state_type.rb'
+    - 'app/graphql/types/terraform/state_version_type.rb'
+    - 'app/graphql/types/timelog_type.rb'
+    - 'app/graphql/types/todo_state_enum.rb'
+    - 'app/graphql/types/todo_target_enum.rb'
+    - 'app/graphql/types/todo_type.rb'
+    - 'app/graphql/types/user_interface.rb'
+    - 'app/graphql/types/user_merge_request_interaction_type.rb'
+    - 'app/graphql/types/user_state_enum.rb'
+    - 'ee/app/graphql/ee/mutations/alert_management/http_integration/create.rb'
+    - 'ee/app/graphql/ee/mutations/alert_management/http_integration/update.rb'
+    - 'ee/app/graphql/ee/mutations/boards/issues/issue_move_list.rb'
+    - 'ee/app/graphql/ee/mutations/issues/create.rb'
+    - 'ee/app/graphql/ee/mutations/issues/update.rb'
+    - 'ee/app/graphql/ee/types/alert_management/http_integration_type.rb'
+    - 'ee/app/graphql/ee/types/board_list_type.rb'
+    - 'ee/app/graphql/ee/types/board_type.rb'
+    - 'ee/app/graphql/ee/types/group_type.rb'
+    - 'ee/app/graphql/ee/types/project_type.rb'
+    - 'ee/app/graphql/ee/types/query_type.rb'
+    - 'ee/app/graphql/mutations/app_sec/fuzzing/api/ci_configuration/create.rb'
+    - 'ee/app/graphql/mutations/boards/epic_boards/create.rb'
+    - 'ee/app/graphql/mutations/boards/epic_boards/epic_move_list.rb'
+    - 'ee/app/graphql/mutations/boards/epic_boards/update.rb'
+    - 'ee/app/graphql/mutations/boards/epic_lists/destroy.rb'
+    - 'ee/app/graphql/mutations/boards/lists/update_limit_metrics.rb'
+    - 'ee/app/graphql/mutations/boards/update_epic_user_preferences.rb'
+    - 'ee/app/graphql/mutations/compliance_management/frameworks/create.rb'
+    - 'ee/app/graphql/mutations/compliance_management/frameworks/destroy.rb'
+    - 'ee/app/graphql/mutations/compliance_management/frameworks/update.rb'
+    - 'ee/app/graphql/mutations/concerns/mutations/shared_epic_arguments.rb'
+    - 'ee/app/graphql/mutations/dast/profiles/create.rb'
+    - 'ee/app/graphql/mutations/dast/profiles/update.rb'
+    - 'ee/app/graphql/mutations/dast_on_demand_scans/create.rb'
+    - 'ee/app/graphql/mutations/dast_scanner_profiles/create.rb'
+    - 'ee/app/graphql/mutations/dast_scanner_profiles/update.rb'
+    - 'ee/app/graphql/mutations/dast_site_profiles/create.rb'
+    - 'ee/app/graphql/mutations/dast_site_profiles/delete.rb'
+    - 'ee/app/graphql/mutations/dast_site_profiles/update.rb'
+    - 'ee/app/graphql/mutations/dast_site_tokens/create.rb'
+    - 'ee/app/graphql/mutations/dast_site_validations/create.rb'
+    - 'ee/app/graphql/mutations/dast_site_validations/revoke.rb'
+    - 'ee/app/graphql/mutations/epic_tree/reorder.rb'
+    - 'ee/app/graphql/mutations/epics/add_issue.rb'
+    - 'ee/app/graphql/mutations/epics/base.rb'
+    - 'ee/app/graphql/mutations/epics/create.rb'
+    - 'ee/app/graphql/mutations/epics/set_subscription.rb'
+    - 'ee/app/graphql/mutations/gitlab_subscriptions/activate.rb'
+    - 'ee/app/graphql/mutations/incident_management/escalation_policy/base.rb'
+    - 'ee/app/graphql/mutations/incident_management/escalation_policy/create.rb'
+    - 'ee/app/graphql/mutations/incident_management/escalation_policy/destroy.rb'
+    - 'ee/app/graphql/mutations/incident_management/escalation_policy/update.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_rotation/base.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_rotation/create.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_rotation/destroy.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_rotation/update.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_schedule/create.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_schedule/destroy.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_schedule/oncall_schedule_base.rb'
+    - 'ee/app/graphql/mutations/incident_management/oncall_schedule/update.rb'
+    - 'ee/app/graphql/mutations/issues/common_ee_mutation_arguments.rb'
+    - 'ee/app/graphql/mutations/issues/promote_to_epic.rb'
+    - 'ee/app/graphql/mutations/issues/set_iteration.rb'
+    - 'ee/app/graphql/mutations/iterations/cadences/create.rb'
+    - 'ee/app/graphql/mutations/iterations/cadences/update.rb'
+    - 'ee/app/graphql/mutations/iterations/create.rb'
+    - 'ee/app/graphql/mutations/namespaces/base.rb'
+    - 'ee/app/graphql/mutations/quality_management/test_cases/create.rb'
+    - 'ee/app/graphql/mutations/requirements_management/update_requirement.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/confirm.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/create_external_issue_link.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/destroy_external_issue_link.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/dismiss.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/resolve.rb'
+    - 'ee/app/graphql/mutations/vulnerabilities/revert_to_detected.rb'
+    - 'ee/app/graphql/resolvers/dora_metrics_resolver.rb'
+    - 'ee/app/graphql/resolvers/geo/geo_node_resolver.rb'
+    - 'ee/app/graphql/resolvers/network_policy_resolver.rb'
+    - 'ee/app/graphql/resolvers/requirements_management/requirements_resolver.rb'
+    - 'ee/app/graphql/types/alert_management/payload_alert_field_input_type.rb'
+    - 'ee/app/graphql/types/alert_management/payload_alert_mapping_field_type.rb'
+    - 'ee/app/graphql/types/analytics/devops_adoption/snapshot_type.rb'
+    - 'ee/app/graphql/types/app_sec/fuzzing/api/scan_profile_type.rb'
+    - 'ee/app/graphql/types/ci/code_quality_degradation_type.rb'
+    - 'ee/app/graphql/types/ci/minutes/namespace_monthly_usage_type.rb'
+    - 'ee/app/graphql/types/ci/minutes/project_monthly_usage_type.rb'
+    - 'ee/app/graphql/types/clusters/agent_token_type.rb'
+    - 'ee/app/graphql/types/clusters/agent_type.rb'
+    - 'ee/app/graphql/types/dast/profile_branch_type.rb'
+    - 'ee/app/graphql/types/dast/profile_type.rb'
+    - 'ee/app/graphql/types/dast/site_profile_auth_input_type.rb'
+    - 'ee/app/graphql/types/dast/site_profile_auth_type.rb'
+    - 'ee/app/graphql/types/dast_scanner_profile_type.rb'
+    - 'ee/app/graphql/types/dast_site_profile_type.rb'
+    - 'ee/app/graphql/types/epic_tree/epic_tree_node_input_type.rb'
+    - 'ee/app/graphql/types/epic_type.rb'
+    - 'ee/app/graphql/types/geo/geo_node_type.rb'
+    - 'ee/app/graphql/types/incident_management/escalation_policy_type.rb'
+    - 'ee/app/graphql/types/incident_management/escalation_rule_input_type.rb'
+    - 'ee/app/graphql/types/incident_management/escalation_rule_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_participant_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_rotation_active_period_input_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_rotation_active_period_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_rotation_date_input_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_rotation_length_input_type.rb'
+    - 'ee/app/graphql/types/incident_management/oncall_user_input_type.rb'
+    - 'ee/app/graphql/types/move_type_enum.rb'
+    - 'ee/app/graphql/types/network_policy_kind_enum.rb'
+    - 'ee/app/graphql/types/path_lock_type.rb'
+    - 'ee/app/graphql/types/pipeline_security_report_finding_type.rb'
+    - 'ee/app/graphql/types/scanned_resource_type.rb'
+    - 'ee/app/graphql/types/security_report_summary_section_type.rb'
+    - 'ee/app/graphql/types/timebox_metrics_type.rb'
+    - 'ee/app/graphql/types/vulnerability/issue_link_type.rb'
+    - 'ee/app/graphql/types/vulnerability_details/commit_type.rb'
+    - 'ee/app/graphql/types/vulnerability_type.rb'
+    - 'ee/app/graphql/types/vulnerable_dependency_type.rb'
+    - 'ee/app/graphql/types/vulnerable_package_type.rb'
 
 # WIP: See https://gitlab.com/gitlab-org/gitlab/-/issues/220040
 Rails/SaveBang:

doc/development/api_graphql_styleguide.md

@@ -837,7 +837,7 @@ descriptions:
 - Mention the name of the resource in the description. Example:
   `'Labels of the issue'` (issue being the resource).
 - Use `"{x} of the {y}"` where possible. Example: `'Title of the issue'`.
-  Do not start descriptions with `The`.
+  Do not start descriptions with `The` or `A`, for consistency and conciseness.
 - Descriptions of `GraphQL::Types::Boolean` fields should answer the question: "What does
   this field do?". Example: `'Indicates project has a Git repository'`.
 - Always include the word `"timestamp"` when describing an argument or

rubocop/cop/graphql/descriptions.rb

@@ -32,7 +32,7 @@
 #
 #     field :some_field,
 #       GraphQL::Types::String,
-#       description: "A thorough and compelling description."
+#       description: "Thorough and compelling description."
 #   end
 #
 #   class GoodEnum
@@ -43,8 +43,10 @@ module RuboCop
   module Cop
     module Graphql
       class Descriptions < RuboCop::Cop::Cop
-        MSG_NO_DESCRIPTION = 'Please add a `description` property.'
-        MSG_NO_PERIOD = '`description` strings must end with a `.`.'
+        MSG_STYLE_GUIDE_LINK = 'See the description style guide: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#description-style-guide'
+        MSG_NO_DESCRIPTION = "Please add a `description` property. #{MSG_STYLE_GUIDE_LINK}"
+        MSG_NO_PERIOD = "`description` strings must end with a `.`. #{MSG_STYLE_GUIDE_LINK}"
+        MSG_BAD_START = "`description` strings should not start with \"A...\" or \"The...\". #{MSG_STYLE_GUIDE_LINK}"
 
         def_node_matcher :graphql_describable?, <<~PATTERN
           (send nil? {:field :argument :value} ...)
@@ -75,6 +77,7 @@ module RuboCop
           return add_offense(node, location: :expression, message: MSG_NO_DESCRIPTION) unless description
 
           add_offense(node, location: :expression, message: MSG_NO_PERIOD) if no_period?(description)
+          add_offense(node, location: :expression, message: MSG_BAD_START) if bad_start?(description)
         end
 
         # Autocorrect missing periods at end of description.
@@ -100,12 +103,19 @@ module RuboCop
         end
 
         def no_period?(description)
-          # Test that the description node is a `:str` (as opposed to
-          # a `#copy_field_description` call) before checking.
-          description.type == :str && !description.value.strip.end_with?('.')
+          string?(description) && !description.value.strip.end_with?('.')
         end
 
-        # Returns a Parser::Source::Range that ends just before the final String delimiter.
+        def bad_start?(description)
+          string?(description) && description.value.strip.downcase.start_with?('a ', 'the ')
+        end
+
+        # Returns true if `description` node is a `:str` (as opposed to a `#copy_field_description` call)
+        def string?(description)
+          description.type == :str
+        end
+
+        # Returns a `Parser::Source::Range` that ends just before the final `String` delimiter.
         def before_end_quote(string)
           return string.source_range.adjust(end_pos: -1) unless string.heredoc?
 

spec/rubocop/cop/graphql/descriptions_spec.rb

@@ -12,7 +12,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             field :a_thing,
-            ^^^^^^^^^^^^^^^ Please add a `description` property.
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_NO_DESCRIPTION}
               GraphQL::Types::String,
               null: false
           end
@@ -25,10 +25,38 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             field :a_thing,
-            ^^^^^^^^^^^^^^^ `description` strings must end with a `.`.
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_NO_PERIOD}
               GraphQL::Types::String,
               null: false,
-              description: 'A descriptive description'
+              description: 'Description of a thing'
+          end
+        end
+      TYPE
+    end
+
+    it 'adds an offense when description begins with "A"' do
+      expect_offense(<<~TYPE)
+        module Types
+          class FakeType < BaseObject
+            field :a_thing,
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
+              GraphQL::Types::String,
+              null: false,
+              description: 'A description of the thing.'
+          end
+        end
+      TYPE
+    end
+
+    it 'adds an offense when description begins with "The"' do
+      expect_offense(<<~TYPE)
+        module Types
+          class FakeType < BaseObject
+            field :a_thing,
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
+              GraphQL::Types::String,
+              null: false,
+              description: 'The description of the thing.'
           end
         end
       TYPE
@@ -41,7 +69,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
             field :a_thing,
               GraphQL::Types::String,
               null: false,
-              description: 'A descriptive description.'
+              description: 'Description of a thing.'
           end
         end
       TYPE
@@ -64,7 +92,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             argument :a_thing,
-            ^^^^^^^^^^^^^^^^^^ Please add a `description` property.
+            ^^^^^^^^^^^^^^^^^^ #{described_class::MSG_NO_DESCRIPTION}
               GraphQL::Types::String,
               null: false
           end
@@ -77,7 +105,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             argument :a_thing,
-            ^^^^^^^^^^^^^^^^^^ `description` strings must end with a `.`.
+            ^^^^^^^^^^^^^^^^^^ #{described_class::MSG_NO_PERIOD}
               GraphQL::Types::String,
               null: false,
               description: 'Behold! A description'
@@ -86,6 +114,34 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
       TYPE
     end
 
+    it 'adds an offense when description begins with "A"' do
+      expect_offense(<<~TYPE)
+        module Types
+          class FakeType < BaseObject
+            argument :a_thing,
+            ^^^^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
+              GraphQL::Types::String,
+              null: false,
+              description: 'A description.'
+          end
+        end
+      TYPE
+    end
+
+    it 'adds an offense when description begins with "The"' do
+      expect_offense(<<~TYPE)
+        module Types
+          class FakeType < BaseObject
+            argument :a_thing,
+            ^^^^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
+              GraphQL::Types::String,
+              null: false,
+              description: 'The description.'
+          end
+        end
+      TYPE
+    end
+
     it 'does not add an offense when description is correct' do
       expect_no_offenses(<<~TYPE.strip)
         module Types
@@ -106,7 +162,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeEnum < BaseEnum
             value 'FOO', value: 'foo'
-            ^^^^^^^^^^^^^^^^^^^^^^^^^ Please add a `description` property.
+            ^^^^^^^^^^^^^^^^^^^^^^^^^ #{described_class::MSG_NO_DESCRIPTION}
           end
         end
       TYPE
@@ -117,7 +173,29 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeEnum < BaseEnum
             value 'FOO', value: 'foo', description: 'bar'
-            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `description` strings must end with a `.`.
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{described_class::MSG_NO_PERIOD}
+          end
+        end
+      TYPE
+    end
+
+    it 'adds an offense when description begins with "The"' do
+      expect_offense(<<~TYPE.strip)
+        module Types
+          class FakeEnum < BaseEnum
+            value 'FOO', value: 'foo', description: 'The description.'
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
+          end
+        end
+      TYPE
+    end
+
+    it 'adds an offense when description begins with "A"' do
+      expect_offense(<<~TYPE.strip)
+        module Types
+          class FakeEnum < BaseEnum
+            value 'FOO', value: 'foo', description: 'A description.'
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{described_class::MSG_BAD_START}
           end
         end
       TYPE
@@ -150,7 +228,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             field :a_thing,
-            ^^^^^^^^^^^^^^^ `description` strings must end with a `.`.
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_NO_PERIOD}
               GraphQL::Types::String,
               null: false,
               description: 'Behold! A description'
@@ -175,7 +253,7 @@ RSpec.describe RuboCop::Cop::Graphql::Descriptions do
         module Types
           class FakeType < BaseObject
             field :a_thing,
-            ^^^^^^^^^^^^^^^ `description` strings must end with a `.`.
+            ^^^^^^^^^^^^^^^ #{described_class::MSG_NO_PERIOD}
               GraphQL::Types::String,
               null: false,
               description: <<~DESC