CLOUDP-313321: Add a new Spectral lint rule that validates that at any time, an endpoint can only have one API version marked as “upcoming”

tools/spectral/.spectral.yaml

@@ -15,7 +15,18 @@ aliases:
     - "#OperationObject.parameters[?(@ && @.in)]"
     - "$.components.schemas[*]..properties[?(@ && @.type)]"
 
+functions:
+  - acceptHeaderUpcomingVersionLimit
+
 rules:
+  accept-header-upcoming-version-limit:
+    description: Ensure that each operation has at most one upcoming API Accept header.
+    message: "An operation must not have more than one upcoming API Accept header (format: application/vnd.atlas.YYYY-MM-DD.upcoming+format)."
+    severity: error
+    given: $.paths[*][*]
+    then:
+      function: "acceptHeaderUpcomingVersionLimit"
+
   xgen-schema-name-pascal-case:
     description: OpenAPI Schema names should use PascalCase. PascalCase ensures consistency with OpenAPI generated code.
     message: "`{{property}}` name must follow PascalCase. Please verify if you have provided valid @Schema(name='') annotation"

tools/spectral/functions/acceptHeaderUpcomingVersionLimit.js

@@ -0,0 +1,41 @@
+module.exports = function (input) {
+  // Get operationId from context, if this fails return an error
+  const operationId = input.operationId;
+  if (!operationId) {
+    return;
+  }
+
+  // List of errors
+  const errors = [];
+
+  // Validate versions in 200 responses
+  const responseErr = validateContent(operationId, 'response', input?.responses?.[200]?.content);
+  if (responseErr != null) errors.push(responseErr);
+
+  // Validate versions in requests
+  const requestErr = validateContent(operationId, 'request', input?.requestBody?.content);
+  if (requestErr != null) errors.push(requestErr);
+
+  return errors.length > 0 ? errors : undefined;
+};
+
+// Check for upcoming API Accept headers
+const upcomingRegex = /^application\/vnd\.atlas\.\d{4}-\d{2}-\d{2}\.upcoming\+.+$/;
+
+function validateContent(operationId, section, content) {
+  if (content == null) {
+    return null;
+  }
+
+  const contentTypes = Object.keys(content);
+  const upcomingContentTypes = contentTypes.filter((k) => upcomingRegex.test(k));
+  // If there's less than or equal to one upcoming header then the operation is valid
+  if (upcomingContentTypes.length <= 1) {
+    return null;
+  }
+
+  // Return an error message
+  return {
+    message: `OperationId: ${operationId} - Found ${upcomingContentTypes.length} upcoming API Accept headers (section: ${section}): ${upcomingContentTypes.join(', ')}`,
+  };
+}