Add WithTotalDefaultRule validation rule

Enforce that the withTotal query parameter, if present, must have a default value of false to optimize query performance.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mo-alras

ctp-validators/src/main/kotlin/com/commercetools/rmf/validators/WithTotalDefaultRule.kt

@@ -0,0 +1,63 @@
+package com.commercetools.rmf.validators
+
+import io.vrap.rmf.raml.model.resources.Method
+import io.vrap.rmf.raml.model.resources.Resource
+import org.eclipse.emf.common.util.Diagnostic
+import java.util.*
+
+@ValidatorSet
+class WithTotalDefaultRule(severity: RuleSeverity, options: List<RuleOption>? = null) : ResourcesRule(severity, options) {
+
+    private val exclude: List<String> =
+        (options?.filter { ruleOption -> ruleOption.type.lowercase(Locale.getDefault()) == RuleOptionType.EXCLUDE.toString() }?.map { ruleOption -> ruleOption.value }?.plus("") ?: defaultExcludes)
+
+    override fun caseMethod(method: Method): List<Diagnostic> {
+        val validationResults: MutableList<Diagnostic> = ArrayList()
+
+        method.queryParameters.forEach { queryParameter ->
+            run {
+                if (queryParameter.name == "withTotal") {
+                    val resourcePath = (method.eContainer() as Resource).fullUri.template
+                    if (exclude.contains("${method.method.name} $resourcePath").not()) {
+                        val defaultValue = queryParameter.type.default
+                        if (defaultValue == null) {
+                            validationResults.add(
+                                create(
+                                    queryParameter,
+                                    "Query parameter \"withTotal\" of method \"{0} {1}\" must have a default value of \"false\"",
+                                    method.method.name,
+                                    resourcePath
+                                )
+                            )
+                        } else if (defaultValue.value.toString() != "false") {
+                            validationResults.add(
+                                create(
+                                    queryParameter,
+                                    "Query parameter \"withTotal\" of method \"{0} {1}\" must have a default value of \"false\", found \"{2}\"",
+                                    method.method.name,
+                                    resourcePath,
+                                    defaultValue.value.toString()
+                                )
+                            )
+                        }
+                    }
+                }
+            }
+        }
+        return validationResults
+    }
+
+    companion object : ValidatorFactory<WithTotalDefaultRule> {
+        private val defaultExcludes by lazy { listOf("") }
+
+        @JvmStatic
+        override fun create(options: List<RuleOption>?): WithTotalDefaultRule {
+            return WithTotalDefaultRule(RuleSeverity.ERROR, options)
+        }
+
+        @JvmStatic
+        override fun create(severity: RuleSeverity, options: List<RuleOption>?): WithTotalDefaultRule {
+            return WithTotalDefaultRule(severity, options)
+        }
+    }
+}

ctp-validators/src/test/groovy/com/commercetools/rmf/validators/ValidatorRulesTest.groovy

@@ -528,4 +528,15 @@ class ValidatorRulesTest extends Specification implements ValidatorFixtures {
         then:
         result.validationResults.size() == 9
     }
+
+    def "with total default rule"() {
+        when:
+        def validators = Arrays.asList(new ResourcesValidator(Arrays.asList(WithTotalDefaultRule.create(emptyList()))))
+        def uri = uriFromClasspath("/with-total-default-rule.raml")
+        def result = new RamlModelBuilder(validators).buildApi(uri)
+        then:
+        result.validationResults.size() == 2
+        result.validationResults[0].message == "Query parameter \"withTotal\" of method \"GET /invalid-resource-true\" must have a default value of \"false\", found \"true\""
+        result.validationResults[1].message == "Query parameter \"withTotal\" of method \"GET /invalid-resource-no-default\" must have a default value of \"false\""
+    }
 }

ctp-validators/src/test/resources/with-total-default-rule.raml

@@ -0,0 +1,32 @@
+#%RAML 1.0
+title: with total default rule
+
+/valid-resource:
+  get:
+    queryParameters:
+      withTotal:
+        type: boolean
+        default: false
+        required: false
+
+/invalid-resource-true:
+  get:
+    queryParameters:
+      withTotal:
+        type: boolean
+        default: true
+        required: false
+
+/invalid-resource-no-default:
+  get:
+    queryParameters:
+      withTotal:
+        type: boolean
+        required: false
+
+/unrelated-resource:
+  get:
+    queryParameters:
+      limit:
+        type: number
+        default: 20