From 52bccd05562fdf4368b06cb4a810d4a625b7a923 Mon Sep 17 00:00:00 2001 From: Vlad Wolanyk Date: Tue, 21 Oct 2025 16:48:04 -0400 Subject: [PATCH 1/2] Correct block traversal Update to correct how desc is traversed to include blocks where only a single option is defined. remove unnecessary rubocop disable Changelog: changed --- .rubocop_todo/api/description_detail.yml | 40 ------------------- .../spec/fixtures/test_audit_events.rb | 4 +- rubocop/cop/api/description_detail.rb | 7 +--- .../cop/api/description_detail_spec.rb | 10 +++++ 4 files changed, 13 insertions(+), 48 deletions(-) diff --git a/.rubocop_todo/api/description_detail.yml b/.rubocop_todo/api/description_detail.yml index c687fdd898d8e1..5e83f8baac5823 100644 --- a/.rubocop_todo/api/description_detail.yml +++ b/.rubocop_todo/api/description_detail.yml @@ -8,19 +8,13 @@ API/DescriptionDetail: - 'ee/lib/api/admin_member_roles.rb' - 'ee/lib/api/ai/duo_workflows/workflows.rb' - 'ee/lib/api/ai/duo_workflows/workflows_internal.rb' - - 'ee/lib/api/ai/llm/git_command.rb' - 'ee/lib/api/analytics/code_review_analytics.rb' - - 'ee/lib/api/analytics/product_analytics.rb' - 'ee/lib/api/analytics/project_deployment_frequency.rb' - 'ee/lib/api/audit_events.rb' - 'ee/lib/api/code_suggestions.rb' - - 'ee/lib/api/compliance_external_controls.rb' - 'ee/lib/api/dependencies.rb' - - 'ee/lib/api/dependency_list_exports.rb' - 'ee/lib/api/dora/metrics.rb' - - 'ee/lib/api/elasticsearch_indexed_namespaces.rb' - 'ee/lib/api/epic_links.rb' - - 'ee/lib/api/epics.rb' - 'ee/lib/api/geo_nodes.rb' - 'ee/lib/api/geo_sites.rb' - 'ee/lib/api/gitlab_subscriptions/subscriptions.rb' @@ -28,10 +22,6 @@ API/DescriptionDetail: - 'ee/lib/api/group_enterprise_users.rb' - 'ee/lib/api/group_protected_branches.rb' - 'ee/lib/api/group_service_accounts.rb' - - 'ee/lib/api/internal/app_sec/dast/site_validations.rb' - - 'ee/lib/api/internal/search/zoekt.rb' - - 'ee/lib/api/license.rb' - - 'ee/lib/api/manage/groups.rb' - 'ee/lib/api/managed_licenses.rb' - 'ee/lib/api/member_roles.rb' - 'ee/lib/api/merge_request_approval_rules.rb' @@ -39,16 +29,10 @@ API/DescriptionDetail: - 'ee/lib/api/merge_request_dependencies.rb' - 'ee/lib/api/project_aliases.rb' - 'ee/lib/api/project_approval_rules.rb' - - 'ee/lib/api/project_google_cloud_integration.rb' - 'ee/lib/api/project_mirror.rb' - 'ee/lib/api/project_push_rule.rb' - 'ee/lib/api/provider_identity.rb' - 'ee/lib/api/related_epic_links.rb' - - 'ee/lib/api/remote_development/internal/agents/agentw/agent_info.rb' - - 'ee/lib/api/remote_development/internal/agents/agentw/authorize_user_access.rb' - - 'ee/lib/api/remote_development/internal/agents/agentw/server_config.rb' - - 'ee/lib/api/sbom/occurrences.rb' - - 'ee/lib/api/scim/group_scim.rb' - 'ee/lib/api/scim/instance_scim.rb' - 'ee/lib/api/security/vulnerability_scanning/sbom_scans.rb' - 'ee/lib/api/security_scans.rb' @@ -60,27 +44,21 @@ API/DescriptionDetail: - 'ee/lib/api/vulnerability_findings.rb' - 'ee/lib/api/vulnerability_issue_links.rb' - 'ee/lib/ee/api/geo.rb' - - 'ee/lib/ee/api/group_milestones.rb' - 'ee/lib/ee/api/groups.rb' - - 'ee/lib/ee/api/internal/kubernetes.rb' - 'ee/lib/ee/api/issues.rb' - 'ee/lib/ee/api/members.rb' - 'ee/lib/ee/api/merge_request_approvals.rb' - - 'ee/lib/ee/api/merge_requests.rb' - 'ee/lib/ee/api/namespaces.rb' - - 'ee/lib/ee/api/project_milestones.rb' - 'ee/lib/ee/api/projects.rb' - 'ee/lib/ee/api/todos.rb' - 'ee/lib/gitlab_subscriptions/api/internal/members.rb' - 'ee/lib/gitlab_subscriptions/api/internal/namespaces.rb' - 'ee/lib/gitlab_subscriptions/api/internal/subscriptions.rb' - - 'ee/lib/gitlab_subscriptions/api/internal/upcoming_reconciliations.rb' - 'ee/lib/gitlab_subscriptions/api/internal/users.rb' - 'lib/api/admin/batched_background_migrations.rb' - 'lib/api/admin/ci/variables.rb' - 'lib/api/admin/dictionary.rb' - 'lib/api/admin/migrations.rb' - - 'lib/api/admin/sidekiq.rb' - 'lib/api/alert_management_alerts.rb' - 'lib/api/appearance.rb' - 'lib/api/avatar.rb' @@ -98,35 +76,22 @@ API/DescriptionDetail: - 'lib/api/commit_statuses.rb' - 'lib/api/commits.rb' - 'lib/api/custom_attributes_endpoints.rb' - - 'lib/api/deploy_keys.rb' - 'lib/api/discussions.rb' - 'lib/api/draft_notes.rb' - 'lib/api/environments.rb' - 'lib/api/files.rb' - 'lib/api/geo.rb' - 'lib/api/group_milestones.rb' - - 'lib/api/group_placeholder_reassignments.rb' - 'lib/api/group_variables.rb' - 'lib/api/groups.rb' - - 'lib/api/hooks/custom_headers.rb' - - 'lib/api/hooks/url_variables.rb' - - 'lib/api/integrations.rb' - 'lib/api/integrations/slack/events.rb' - - 'lib/api/internal/auto_flow.rb' - 'lib/api/internal/coverage.rb' - - 'lib/api/internal/kubernetes.rb' - - 'lib/api/internal/lfs.rb' - - 'lib/api/internal/pages.rb' - 'lib/api/invitations.rb' - 'lib/api/issues.rb' - 'lib/api/labels.rb' - 'lib/api/markdown_uploads.rb' - 'lib/api/members.rb' - 'lib/api/merge_request_approvals.rb' - - 'lib/api/ml/mlflow/entrypoint.rb' - - 'lib/api/ml/mlflow/registered_models.rb' - - 'lib/api/ml/mlflow_artifacts/artifacts.rb' - - 'lib/api/ml/mlflow_artifacts/entrypoint.rb' - 'lib/api/notes.rb' - 'lib/api/pages_domains.rb' - 'lib/api/project_container_registry_protection_rules.rb' @@ -141,21 +106,16 @@ API/DescriptionDetail: - 'lib/api/remote_mirrors.rb' - 'lib/api/repositories.rb' - 'lib/api/resource_state_events.rb' - - 'lib/api/search.rb' - 'lib/api/settings.rb' - - 'lib/api/sidekiq_metrics.rb' - 'lib/api/snippets.rb' - 'lib/api/statistics.rb' - 'lib/api/submodules.rb' - 'lib/api/subscriptions.rb' - 'lib/api/suggestions.rb' - - 'lib/api/system_hooks.rb' - 'lib/api/tags.rb' - 'lib/api/todos.rb' - - 'lib/api/topics.rb' - 'lib/api/unleash.rb' - 'lib/api/usage_data.rb' - - 'lib/api/user_runners.rb' - 'lib/api/users.rb' - 'lib/api/vs_code/settings/vs_code_settings_sync.rb' - 'lib/api/wikis.rb' diff --git a/gems/gitlab-grape-openapi/spec/fixtures/test_audit_events.rb b/gems/gitlab-grape-openapi/spec/fixtures/test_audit_events.rb index 7eacb30d41c565..515103e9138163 100644 --- a/gems/gitlab-grape-openapi/spec/fixtures/test_audit_events.rb +++ b/gems/gitlab-grape-openapi/spec/fixtures/test_audit_events.rb @@ -19,13 +19,13 @@ class TestAuditEvents < Grape::API get do end - # rubocop:disable API/DescriptionTags,API/DescriptionDetail -- Needed to test this edge case + # rubocop:disable API/DescriptionTags -- Needed to test this edge case desc 'Define endpoint with no tags' do detail 'This is an endpoint with no tags!' end get do end - # rubocop:enable API/DescriptionTags,API/DescriptionDetail + # rubocop:enable API/DescriptionTags end end end diff --git a/rubocop/cop/api/description_detail.rb b/rubocop/cop/api/description_detail.rb index 12854256f7a4be..3ad1c550ca9b7a 100644 --- a/rubocop/cop/api/description_detail.rb +++ b/rubocop/cop/api/description_detail.rb @@ -34,12 +34,7 @@ class DescriptionDetail < RuboCop::Cop::Base MSG = 'API desc blocks must define a valid detail string. https://docs.gitlab.com/development/api_styleguide#defining-endpoint-details.' # @!method desc_block_with_valid_detail?(node) - def_node_matcher :desc_block_with_valid_detail?, <<~PATTERN - (block - (send nil? :desc ...) - (args) - (begin <(send nil? :detail {(str _) (dstr ...)}) ...>)) - PATTERN + def_node_matcher :desc_block_with_valid_detail?, '`(send nil? :detail {(str _) (dstr ...)})' def on_block(node) return unless node.method?(:desc) diff --git a/spec/rubocop/cop/api/description_detail_spec.rb b/spec/rubocop/cop/api/description_detail_spec.rb index 9e24a696c28cf0..47f966bec8687c 100644 --- a/spec/rubocop/cop/api/description_detail_spec.rb +++ b/spec/rubocop/cop/api/description_detail_spec.rb @@ -24,6 +24,16 @@ RUBY end end + + context "when desc block only contains detail" do + it "does not add an offense" do + expect_no_offenses(<<~'RUBY') + desc "Get a list of #{interpolated} things" do + detail 'This endpoint was introduced in 18.2' + end + RUBY + end + end end context 'when desc block does not have a detail' do -- GitLab From 4685fcf7bb9df4af9138f1cb87b3893a2852dfe9 Mon Sep 17 00:00:00 2001 From: Vlad Wolanyk Date: Wed, 22 Oct 2025 09:41:21 -0400 Subject: [PATCH 2/2] Update method name --- rubocop/cop/api/description_detail.rb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rubocop/cop/api/description_detail.rb b/rubocop/cop/api/description_detail.rb index 3ad1c550ca9b7a..cc2ca7f05099c6 100644 --- a/rubocop/cop/api/description_detail.rb +++ b/rubocop/cop/api/description_detail.rb @@ -33,12 +33,12 @@ class DescriptionDetail < RuboCop::Cop::Base MSG = 'API desc blocks must define a valid detail string. https://docs.gitlab.com/development/api_styleguide#defining-endpoint-details.' - # @!method desc_block_with_valid_detail?(node) - def_node_matcher :desc_block_with_valid_detail?, '`(send nil? :detail {(str _) (dstr ...)})' + # @!method has_valid_detail?(node) + def_node_matcher :has_valid_detail?, '`(send nil? :detail {(str _) (dstr ...)})' def on_block(node) return unless node.method?(:desc) - return if desc_block_with_valid_detail?(node) + return if has_valid_detail?(node) add_offense(node) end -- GitLab