feat(ipa):child path identifiers inherit parent path exceptions

Author: yelizhenden-mdb

tools/spectral/ipa/__tests__/IPA102CollectionIdentifierCamelCase.test.js

@@ -254,4 +254,20 @@ testRule('xgen-IPA-102-collection-identifier-camelCase', [
       },
     ],
   },
+  {
+    name: 'child paths inherit parent exceptions',
+    document: {
+      paths: {
+        '/resource_groups': {
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-102-collection-identifier-camelCase': 'Legacy API path that cannot be changed',
+          },
+        },
+        '/resource_groups/{id}': {},
+        '/resource_groups/{id}/User-Profiles': {},
+        '/resource_groups/{id}/User-Profiles/{profileId}': {},
+      },
+    },
+    errors: [],
+  },
 ]);

tools/spectral/ipa/__tests__/IPA102CollectionIdentifierPattern.test.js

@@ -89,4 +89,20 @@ testRule('xgen-IPA-102-collection-identifier-pattern', [
     },
     errors: [],
   },
+  {
+    name: 'child paths inherit parent exceptions',
+    document: {
+      paths: {
+        '/resource-groups': {
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-102-collection-identifier-pattern': 'Legacy API path that cannot be changed',
+          },
+        },
+        '/resource-groups/{id}': {},
+        '/resource-groups/{id}/sub_resources': {},
+        '/resource-groups/{id}/sub_resources/{subId}': {},
+      },
+    },
+    errors: [],
+  },
 ]);

tools/spectral/ipa/__tests__/IPA102EachPathAlternatesBetweenResourceNameAndPathParam.test.js

@@ -152,4 +152,19 @@ testRule('xgen-IPA-102-path-alternate-resource-name-path-param', [
     },
     errors: [],
   },
+  {
+    name: 'child paths inherit parent exceptions',
+    document: {
+      paths: {
+        '/api/atlas/v2/resourceName1/resourceName2': {
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-102-path-alternate-resource-name-path-param': 'parent exception reason',
+          },
+        },
+        '/api/atlas/v2/resourceName1/resourceName2/child': {},
+        '/api/atlas/v2/resourceName1/resourceName2/child/{id}': {},
+      },
+    },
+    errors: [],
+  },
 ]);

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

@@ -1,6 +1,10 @@
-import { evaluateAndCollectAdoptionStatus, handleInternalError } from './utils/collectionUtils.js';
+import {
+  evaluateAndCollectAdoptionStatus,
+  handleInternalError,
+} from './utils/collectionUtils.js';
 import { isPathParam } from './utils/componentUtils.js';
 import { casing } from '@stoplight/spectral-functions';
+import { findExceptionInPathHierarchy } from './utils/exceptions.js';
 
 const RULE_NAME = 'xgen-IPA-102-collection-identifier-camelCase';
 const ERROR_MESSAGE = 'Collection identifiers must be in camelCase.';
@@ -21,7 +25,11 @@ export default (input, options, { path, documentInventory }) => {
 
   const violations = checkViolations(pathKey, path, ignoredValues);
 
-  return evaluateAndCollectAdoptionStatus(violations, RULE_NAME, oas.paths[input], path);
+  // Check for exceptions in path hierarchy
+  const pathWithException = findExceptionInPathHierarchy(oas, pathKey, RULE_NAME);
+  const objectToCheck = pathWithException ? oas.paths[pathWithException] : oas.paths[input];
+
+  return evaluateAndCollectAdoptionStatus(violations, RULE_NAME, objectToCheck, path);
 };
 
 function checkViolations(pathKey, path, ignoredValues = []) {

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

@@ -1,4 +1,5 @@
 import { evaluateAndCollectAdoptionStatus } from './utils/collectionUtils.js';
+import { findExceptionInPathHierarchy } from './utils/exceptions.js';
 
 const RULE_NAME = 'xgen-IPA-102-collection-identifier-pattern';
 const ERROR_MESSAGE =
@@ -17,7 +18,11 @@ export default (input, _, { path, documentInventory }) => {
 
   const violations = checkViolations(input, path);
 
-  return evaluateAndCollectAdoptionStatus(violations, RULE_NAME, oas.paths[input], path);
+  // Check for exceptions in path hierarchy
+  const pathWithException = findExceptionInPathHierarchy(oas, input, RULE_NAME);
+  const objectToCheck = pathWithException ? oas.paths[pathWithException] : oas.paths[input];
+
+  return evaluateAndCollectAdoptionStatus(violations, RULE_NAME, objectToCheck, path);
 };
 
 function checkViolations(pathKey, path) {

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

@@ -1,6 +1,10 @@
 import { isPathParam } from './utils/componentUtils.js';
-import { evaluateAndCollectAdoptionStatus, handleInternalError } from './utils/collectionUtils.js';
+import {
+  evaluateAndCollectAdoptionStatus,
+  handleInternalError,
+} from './utils/collectionUtils.js';
 import { AUTH_PREFIX, UNAUTH_PREFIX } from './utils/resourceEvaluation.js';
+import { findExceptionInPathHierarchy } from './utils/exceptions.js';
 
 const RULE_NAME = 'xgen-IPA-102-path-alternate-resource-name-path-param';
 const ERROR_MESSAGE = 'API paths must alternate between resource name and path params.';
@@ -37,7 +41,11 @@ export default (input, _, { path, documentInventory }) => {
 
   const errors = checkViolationsAndReturnErrors(suffixWithLeadingSlash, path);
 
-  return evaluateAndCollectAdoptionStatus(errors, RULE_NAME, oas.paths[input], path);
+  // Check for exceptions in path hierarchy
+  const pathWithException = findExceptionInPathHierarchy(oas, input, RULE_NAME);
+  const objectToCheck = pathWithException ? oas.paths[pathWithException] : oas.paths[input];
+
+  return evaluateAndCollectAdoptionStatus(errors, RULE_NAME, objectToCheck, path);
 };
 
 function checkViolationsAndReturnErrors(suffixWithLeadingSlash, path) {

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

@@ -13,3 +13,32 @@ export function hasException(object, ruleName) {
   }
   return false;
 }
+
+/**
+ * Finds an exception in the path hierarchy of an OpenAPI Specification (OAS) document
+ * for a specific rule name, starting from the current path and traversing up to parent paths.
+ *
+ * @param {object} oas - OpenAPI Specification document containing the paths.
+ * @param {string} currentPath - Current path to check for exceptions.
+ * @param {string} ruleName - Name of the rule for which the exception is being checked.
+ * @return {string|null} Returns the path where the exception is found,
+ * or null if no exception is found in the current path or its hierarchy.
+ */
+export function findExceptionInPathHierarchy(oas, currentPath, ruleName) {
+  // Check current path first
+  if (hasException(oas.paths[currentPath], ruleName)) {
+    return currentPath;
+  }
+
+  // Check parent paths by removing segments from the end
+  const pathSegments = currentPath.split('/').filter(segment => segment !== '');
+
+  for (let i = pathSegments.length - 1; i > 0; i--) {
+    const parentPath = '/' + pathSegments.slice(0, i).join('/');
+    if (oas.paths[parentPath] && hasException(oas.paths[parentPath], ruleName)) {
+      return parentPath;
+    }
+  }
+
+  return null;
+}