CLOUDP-306294: Refactored and commented opID related utilities

Author: Sophia Marie Terry

tools/spectral/ipa/rulesets/functions/IPA104ValidOperationID.js

@@ -2,7 +2,7 @@ import { generateOperationID } from './utils/operationIdGeneration.js';
 import { collectAdoption, collectAndReturnViolation, collectException } from './utils/collectionUtils.js';
 import { hasException } from './utils/exceptions.js';
 import { getResourcePathItems, isCustomMethodIdentifier } from './utils/resourceEvaluation.js';
-import { isGetOverride, isLegacyCustomMethod, isListOverride } from './utils/extensions.js';
+import { hasCustomMethodOverride, hasMethodVerbOverride } from './utils/extensions.js';
 import { invalidGetMethod } from './utils/methodLogic.js';
 
 const RULE_NAME = 'xgen-IPA-104-valid-operation-id';
@@ -14,10 +14,10 @@ export default (input, { methodName }, { path, documentInventory }) => {
   const resourcePaths = getResourcePathItems(resourcePath, oas.paths);
 
   if (
-    isLegacyCustomMethod(input) ||
+    hasCustomMethodOverride(input) ||
     isCustomMethodIdentifier(resourcePath) ||
-    isListOverride(input) ||
-    (invalidGetMethod(resourcePath, resourcePaths) && !isGetOverride(input))
+    hasMethodVerbOverride(input, "list") ||
+    (invalidGetMethod(resourcePath, resourcePaths) && !hasMethodVerbOverride(input, methodName))
   ) {
     return;
   }

tools/spectral/ipa/rulesets/functions/IPA105ValidOperationID.js

@@ -3,7 +3,7 @@ import { collectAdoption, collectAndReturnViolation, collectException } from './
 import { getResourcePathItems, isCustomMethodIdentifier } from './utils/resourceEvaluation.js';
 import { generateOperationID } from './utils/operationIdGeneration.js';
 import { invalidListMethod } from './utils/methodLogic.js';
-import { isLegacyCustomMethod, isGetOverride, isListOverride } from './utils/extensions.js';
+import { hasCustomMethodOverride, hasMethodVerbOverride } from './utils/extensions.js';
 
 const RULE_NAME = 'xgen-IPA-105-valid-operation-id';
 const ERROR_MESSAGE = 'Invalid OperationID.';
@@ -14,10 +14,10 @@ export default (input, { methodName }, { path, documentInventory }) => {
   const resourcePaths = getResourcePathItems(resourcePath, oas.paths);
 
   if (
-    isLegacyCustomMethod(input) ||
+    hasCustomMethodOverride(input) ||
     isCustomMethodIdentifier(resourcePath) ||
-    isGetOverride(input) ||
-    (invalidListMethod(resourcePath, resourcePaths) && !isListOverride(input))
+    hasMethodVerbOverride(input, 'get') ||
+    (invalidListMethod(resourcePath, resourcePaths) && !hasMethodVerbOverride(input, methodName))
   ) {
     return;
   }

tools/spectral/ipa/rulesets/functions/IPA106ValidOperationID.js

@@ -2,15 +2,15 @@ import { hasException } from './utils/exceptions.js';
 import { collectAdoption, collectException, collectAndReturnViolation } from './utils/collectionUtils.js';
 import { isCustomMethodIdentifier } from './utils/resourceEvaluation.js';
 import { generateOperationID } from './utils/operationIdGeneration.js';
-import { isLegacyCustomMethod } from './utils/extensions.js';
+import { hasCustomMethodOverride } from './utils/extensions.js';
 
 const RULE_NAME = 'xgen-IPA-106-valid-operation-id';
 const ERROR_MESSAGE = 'Invalid OperationID.';
 
 export default (input, { methodName }, { path }) => {
   const resourcePath = path[1];
 
-  if (isLegacyCustomMethod(input) || isCustomMethodIdentifier(resourcePath)) {
+  if (hasCustomMethodOverride(input) || isCustomMethodIdentifier(resourcePath)) {
     return;
   }
 

tools/spectral/ipa/rulesets/functions/IPA107ValidOperationID.js

@@ -2,15 +2,15 @@ import { hasException } from './utils/exceptions.js';
 import { collectAdoption, collectException, collectAndReturnViolation } from './utils/collectionUtils.js';
 import { isCustomMethodIdentifier } from './utils/resourceEvaluation.js';
 import { generateOperationID } from './utils/operationIdGeneration.js';
-import { isLegacyCustomMethod } from './utils/extensions.js';
+import { hasCustomMethodOverride } from './utils/extensions.js';
 
 const RULE_NAME = 'xgen-IPA-107-valid-operation-id';
 const ERROR_MESSAGE = 'Invalid OperationID.';
 
 export default (input, { methodName }, { path }) => {
   const resourcePath = path[1];
 
-  if (isCustomMethodIdentifier(resourcePath) || isLegacyCustomMethod(input)) {
+  if (isCustomMethodIdentifier(resourcePath) || hasCustomMethodOverride(input)) {
     return;
   }
 

tools/spectral/ipa/rulesets/functions/IPA108ValidOperationID.js

@@ -2,15 +2,15 @@ import { hasException } from './utils/exceptions.js';
 import { collectAdoption, collectException, collectAndReturnViolation } from './utils/collectionUtils.js';
 import { isCustomMethodIdentifier, isSingleResourceIdentifier } from './utils/resourceEvaluation.js';
 import { generateOperationID } from './utils/operationIdGeneration.js';
-import { isLegacyCustomMethod } from './utils/extensions.js';
+import { hasCustomMethodOverride } from './utils/extensions.js';
 
 const RULE_NAME = 'xgen-IPA-108-valid-operation-id';
 const ERROR_MESSAGE = 'Invalid OperationID.';
 
 export default (input, { methodName }, { path }) => {
   const resourcePath = path[1];
 
-  if (isCustomMethodIdentifier(resourcePath) || isLegacyCustomMethod(input)) {
+  if (isCustomMethodIdentifier(resourcePath) || hasCustomMethodOverride(input)) {
     return;
   }
 

tools/spectral/ipa/rulesets/functions/IPA109ValidOperationID.js

@@ -2,7 +2,7 @@ import { hasException } from './utils/exceptions.js';
 import { collectAdoption, collectException, collectAndReturnViolation } from './utils/collectionUtils.js';
 import { isCustomMethodIdentifier, getCustomMethodName, stripCustomMethodName } from './utils/resourceEvaluation.js';
 import { generateOperationID } from './utils/operationIdGeneration.js';
-import { hasMethodWithVerbOverride, isLegacyCustomMethod } from './utils/extensions.js';
+import { hasMethodWithVerbOverride, hasCustomMethodOverride } from './utils/extensions.js';
 
 const RULE_NAME = 'xgen-IPA-109-valid-operation-id';
 const ERROR_MESSAGE = 'Invalid OperationID.';
@@ -48,7 +48,7 @@ export default (input, _, { path }) => {
     for (let i = 0; i < methods.length; i++) {
       let obj = input[methods[i]];
       const operationId = obj.operationId;
-      if (isLegacyCustomMethod(obj)) {
+      if (hasCustomMethodOverride(obj)) {
         expectedOperationID = generateOperationID(obj['x-xgen-method-verb-override'].verb, resourcePath);
         if (operationId !== expectedOperationID) {
           errors.push({

tools/spectral/ipa/rulesets/functions/utils/extensions.js

@@ -1,42 +1,57 @@
 export const VERB_OVERRIDE_EXTENSION = 'x-xgen-method-verb-override';
 
-// for endpoint
+/**
+ * Checks if the endpoint has a method with an extension "x-xgen-method-verb-override"
+ *
+ * @param object the object to evaluate
+ * @returns {boolean} true if the object has the extension, otherwise false
+ */
 export function hasMethodWithVerbOverride(endpoint) {
   const keys = Object.keys(endpoint);
   for (let i = 0; i < keys.length; i++) {
-    if (endpoint[keys[i]][VERB_OVERRIDE_EXTENSION]) {
+    if (hasVerbOverride(endpoint[keys[i]])) {
       return true;
     }
   }
   return false;
 }
 
-// for method
-export function hasVerbOverride(object) {
-  if (!object[VERB_OVERRIDE_EXTENSION]) {
-    return false;
-  }
-  return true;
-}
-
-// for method
-export function isLegacyCustomMethod(object) {
+/**
+ * Checks if the object has an extension "x-xgen-method-verb-override" with the customMethod boolean set to true
+ *
+ * @param object the object to evaluate
+ * @returns {boolean} true if the object has an extension with customMethod=True, otherwise false
+ */
+export function hasCustomMethodOverride(object) {
   if (hasVerbOverride(object)) {
     return object[VERB_OVERRIDE_EXTENSION].customMethod;
   }
   return false;
 }
 
-export function isGetOverride(object) {
+/**
+ * Checks if the object has an extension "x-xgen-method-verb-override" with the verb set to a specific verb
+ *
+ * @param object the object to evaluate
+ * @param verb the verb to inspect the extension for
+ * @returns {boolean} true if the object has the extension with the given verb, otherwise false
+ */
+export function hasMethodVerbOverride(object, verb) {
   if (hasVerbOverride(object)) {
-    return object[VERB_OVERRIDE_EXTENSION].verb === 'get';
+    return object[VERB_OVERRIDE_EXTENSION].verb === verb;
   }
   return false;
 }
 
-export function isListOverride(object) {
-  if (hasVerbOverride(object)) {
-    return object[VERB_OVERRIDE_EXTENSION].verb === 'list';
+/**
+ * Checks if the object has an extension "x-xgen-method-verb-override"
+ *
+ * @param object the object to evaluate
+ * @returns {boolean} true if the object has the extension, otherwise false
+ */
+function hasVerbOverride(object) {
+  if (!object[VERB_OVERRIDE_EXTENSION]) {
+    return false;
   }
-  return false;
-}
+  return true;
+}

tools/spectral/ipa/rulesets/functions/utils/methodLogic.js

@@ -1,13 +1,34 @@
 import { isResourceCollectionIdentifier, isSingletonResource } from './resourceEvaluation';
 import { isPathParam } from './resourceEvaluation';
 
+/**
+ * Checks whether the get method at a given path is valid
+ * 
+ * @param resourcePath the resource path to inspect
+ * @param resourcePaths the resource paths generated by getResourcePathItems
+ * @returns true if the resourcePath has an invalid list method, false otherwise
+ */
 export function invalidGetMethod(resourcePath, resourcePaths) {
   return (
-    !isPathParam(resourcePath.split('/').pop()) &&
+    !lastIdentifierIsPathParam(resourcePath) &&
     !(isResourceCollectionIdentifier(resourcePath) && isSingletonResource(resourcePaths))
   );
 }
 
+/**
+ * Checks whether the list method at a given path is valid
+ * 
+ * @param resourcePath the resource path to inspect
+ * @param resourcePaths the resource paths generated by getResourcePathItems
+ * @returns true if the resourcePath has an invalid list method, false otherwise
+ */
 export function invalidListMethod(resourcePath, resourcePaths) {
-  return isPathParam(resourcePath.split('/').pop()) || isSingletonResource(resourcePaths);
+  return lastIdentifierIsPathParam(resourcePath) || isSingletonResource(resourcePaths);
 }
+
+function lastIdentifierIsPathParam(resourceIdentifier) {
+  if (resourceIdentifier.includes('.')) {
+    resourceIdentifier = resourceIdentifier.substring(0, resourceIdentifier.lastIndexOf('.'));
+  }
+  return isPathParam(resourceIdentifier.split('/').pop());
+}