CLOUDP-297705: POC generate operation ID from method+path

package.json

@@ -14,6 +14,9 @@
         "transform": {
             "^.+\\.[t|j]sx?$": "babel-jest"
         },
+        "transformIgnorePatterns": [
+            "/node_modules/(?!ember-inflector)"
+        ],
         "testPathIgnorePatterns": [
             "__helpers__",
             "metrics/data"
@@ -26,9 +29,12 @@
         "@stoplight/spectral-functions": "^1.9.3",
         "@stoplight/spectral-ref-resolver": "^1.0.5",
         "@stoplight/spectral-ruleset-bundler": "^1.6.1",
+        "active-inflector": "^0.1.0",
         "apache-arrow": "^19.0.1",
         "dotenv": "^16.4.7",
+        "ember-inflector": "^5.0.2",
         "eslint-plugin-jest": "^28.10.0",
+        "inflector-js": "^1.0.1",
         "markdown-table": "^3.0.4",
         "openapi-to-postmanv2": "4.25.0",
         "parquet-wasm": "^0.6.1"

tools/spectral/ipa/__tests__/utils/generateOperationId.test.js

@@ -0,0 +1,134 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  generateOperationIdForCustomMethod,
+  generateOperationIdForStandardMethod,
+} from '../../rulesets/functions/utils/generateOperationId.js';
+
+const customMethodCases = [
+  // Real examples that work well
+  {
+    path: '/api/atlas/v2/orgs/{orgId}/resourcePolicies:validate',
+    expectedOperationId: 'validateOrgResourcePolicies',
+  },
+  {
+    path: '/api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/lineItems:search',
+    expectedOperationId: 'searchOrgInvoiceLineItems',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}:migrate',
+    expectedOperationId: 'migrateGroup',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/serviceAccounts/{clientId}:invite',
+    expectedOperationId: 'inviteGroupServiceAccountsClient',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/streams/{tenantName}/processor/{processorName}:stop',
+    expectedOperationId: 'stopGroupStreamsTenantProcessor',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/flexClusters:tenantUpgrade',
+    expectedOperationId: 'tenantGroupFlexClustersUpgrade',
+  },
+  {
+    path: '/api/atlas/v2/orgs/{orgId}/users/{userId}:addRole',
+    expectedOperationId: 'addOrgUserRole',
+  },
+  // Some examples to show some edge cases
+  {
+    path: '/api/atlas/v2/orgs/{orgId}/billing/costExplorer:getUsage',
+    expectedOperationId: 'getOrgBillingCostExplorerUsage', // Double parent case works well here
+  },
+  // Some examples to show some caveats
+  {
+    path: '/api/atlas/v2/groups/{groupId}/streams:withSampleConnections',
+    method: 'get',
+    expectedOperationId: 'withGroupStreamsSampleConnections', // This one has a weird custom method, ideally it would be /streams:createWithSampleConnections
+  },
+];
+
+const standardMethodCases = [
+  // Real examples that work well
+  {
+    path: '/api/atlas/v2/groups/{groupId}/serviceAccounts',
+    method: 'list',
+    expectedOperationId: 'listGroupServiceAccounts',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/serviceAccounts/{clientId}',
+    method: 'get',
+    expectedOperationId: 'getGroupServiceAccountsClient',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/pushBasedLogExport',
+    method: 'delete',
+    expectedOperationId: 'deleteGroupPushBasedLogExport',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/processes/{processId}/measurements',
+    method: 'list',
+    expectedOperationId: 'listGroupProcessMeasurements',
+  },
+  // Some examples to show some caveats
+  {
+    path: '/api/atlas/v2/groups/{groupId}/serviceAccounts',
+    method: 'create',
+    expectedOperationId: 'createGroupServiceAccounts', // Ideally singular instead of plural
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/invites/{invitationId}',
+    method: 'get',
+    expectedOperationId: 'getGroupInvitation',
+  },
+  {
+    path: '/api/atlas/v2/federationSettings/{federationSettingsId}/connectedOrgConfigs/{orgId}/roleMappings/{id}',
+    method: 'delete',
+    expectedOperationId: 'deleteFederationSettingsConnectedOrgConfigsOrgRoleMappings',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/clusters/{hostName}/logs/{logName}.gz',
+    method: 'get',
+    expectedOperationId: 'getGroupClustersHostLog',
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/serverless/{name}',
+    method: 'delete',
+    expectedOperationId: 'deleteGroupServerless', // Ideally it should be something like /{instanceName} -> deleteGroupServerlessInstance
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/cloudProviderAccess/{cloudProvider}/{roleId}',
+    method: 'get',
+    expectedOperationId: 'getGroupCloudRole', // Ideally the provider from cloudProvider wouldn't be stripped here
+  },
+  {
+    path: '/api/atlas/v2/orgs',
+    method: 'list',
+    expectedOperationId: 'listOrgs',
+  },
+  {
+    path: '/api/atlas/v2/orgs/{orgId}/apiKeys/{apiUserId}',
+    method: 'get',
+    expectedOperationId: 'getOrgApiKeysApiUser', // This one is a bit weird, ideally it would be /apiKeys/{apiKeyId} -> getOrgApiKey
+  },
+  {
+    path: '/api/atlas/v2/groups/{groupId}/privateEndpoint/{cloudProvider}/endpointService/{endpointServiceId}/endpoint/{endpointId}',
+    method: 'delete',
+    expectedOperationId: 'deleteGroupPrivateEndpointCloudEndpointServiceEndpoint', // This gets complicated, and ideally for this case cloudProvider wouldn't be stripped to only 'cloud'
+  },
+];
+
+describe('tools/spectral/ipa/rulesets/functions/utils/generateOperationId.js', () => {
+  for (const testCase of customMethodCases) {
+    it.concurrent(`Custom method ${testCase.path} gets operationId ${testCase.expectedOperationId}`, () => {
+      expect(generateOperationIdForCustomMethod(testCase.path)).toBe(testCase.expectedOperationId);
+    });
+  }
+  for (const testCase of standardMethodCases) {
+    it.concurrent(
+      `Standard method ${testCase.method} ${testCase.path} gets operationId ${testCase.expectedOperationId}`,
+      () => {
+        expect(generateOperationIdForStandardMethod(testCase.path, testCase.method)).toBe(testCase.expectedOperationId);
+      }
+    );
+  }
+});

tools/spectral/ipa/rulesets/IPA-XXX.yaml

@@ -0,0 +1,21 @@
+# Operation ID
+
+functions:
+  - operationIdFormat
+  - operationIdFormatInflector
+
+rules:
+  xgen-IPA-XXX-operation-id-format:
+    description: 'Operation IDs must follow the IPA guidelines'
+    message: '{{error}}'
+    severity: error
+    given: '$..operationId'
+    then:
+      function: 'operationIdFormat'
+  xgen-IPA-XXX-operation-id-format-inflector:
+    description: 'Operation IDs must follow the IPA guidelines'
+    message: '{{error}}'
+    severity: error
+    given: '$..operationId'
+    then:
+      function: 'operationIdFormatInflector'

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

@@ -0,0 +1,79 @@
+import {
+  getResourcePathItems,
+  isSingleResourceIdentifier,
+  isCustomMethodIdentifier,
+  isSingletonResource,
+} from './utils/resourceEvaluation.js';
+import {
+  generateOperationIdForCustomMethod,
+  generateOperationIdForStandardMethod,
+} from './utils/generateOperationId.js';
+
+const BASE_PATH = '/api/atlas/v2';
+
+export default (input, _, { path, documentInventory }) => {
+  const operationId = input;
+  const oas = documentInventory.resolved;
+  const operationPath = path[1];
+  const method = path[2];
+  const resourcePathItems = getResourcePathItems(operationPath, oas.paths);
+
+  if (operationPath === BASE_PATH) {
+    const expectedOperationId = 'getSystemStatus';
+    if (operationId !== expectedOperationId) {
+      return [
+        {
+          message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+        },
+      ];
+    }
+    return;
+  }
+
+  if (isCustomMethodIdentifier(operationPath)) {
+    const expectedOperationId = generateOperationIdForCustomMethod(operationPath);
+    if (operationId !== expectedOperationId) {
+      return [
+        {
+          message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+        },
+      ];
+    }
+    return;
+  }
+
+  let expectedOperationId = '';
+  switch (method) {
+    case 'get':
+      if (isSingleResourceIdentifier(operationPath) || isSingletonResource(resourcePathItems)) {
+        expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'get');
+      } else {
+        expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'list');
+      }
+      break;
+    case 'post':
+      expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'create');
+      break;
+    case 'patch':
+      expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'update');
+      break;
+    case 'put':
+      expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'update');
+      break;
+    case 'delete':
+      expectedOperationId = generateOperationIdForStandardMethod(operationPath, 'delete');
+      break;
+  }
+  if (!expectedOperationId) {
+    console.error('Unsupported http method');
+    return;
+  }
+
+  if (operationId !== expectedOperationId) {
+    return [
+      {
+        message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+      },
+    ];
+  }
+};

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

@@ -0,0 +1,92 @@
+import {
+  getResourcePathItems,
+  isSingleResourceIdentifier,
+  isCustomMethodIdentifier,
+  isSingletonResource,
+  isResourceCollectionIdentifier,
+} from './utils/resourceEvaluation.js';
+import {
+  generateOperationIdForCustomMethod_inflector,
+  generateOperationIdForStandardMethod_inflector,
+} from './utils/generateOperationId.js';
+
+const BASE_PATH = '/api/atlas/v2';
+
+export default (input, _, { path, documentInventory }) => {
+  const operationId = input;
+  const oas = documentInventory.resolved;
+  const operationPath = path[1];
+  const method = path[2];
+  const resourcePathItems = getResourcePathItems(operationPath, oas.paths);
+
+  if (operationPath === BASE_PATH) {
+    const expectedOperationId = 'getSystemStatus';
+    if (operationId !== expectedOperationId) {
+      return [
+        {
+          message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+        },
+      ];
+    }
+    return;
+  }
+
+  if (isCustomMethodIdentifier(operationPath)) {
+    const expectedOperationId = generateOperationIdForCustomMethod_inflector(operationPath);
+    if (operationId !== expectedOperationId) {
+      return [
+        {
+          message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+        },
+      ];
+    }
+    return;
+  }
+
+  let expectedOperationId = '';
+  switch (method) {
+    case 'get':
+      if (isResourceCollectionIdentifier(operationPath)) {
+        if (isSingletonResource(resourcePathItems)) {
+          expectedOperationId = generateOperationIdForStandardMethod_inflector(operationPath, 'get', false);
+        } else {
+          expectedOperationId = generateOperationIdForStandardMethod_inflector(operationPath, 'list', false);
+        }
+      } else {
+        expectedOperationId = generateOperationIdForStandardMethod_inflector(
+          operationPath,
+          'get',
+          isSingleResourceIdentifier(operationPath)
+        );
+      }
+      break;
+    case 'post':
+      expectedOperationId = generateOperationIdForStandardMethod_inflector(operationPath, 'create', true);
+      break;
+    case 'patch':
+      expectedOperationId = generateOperationIdForStandardMethod_inflector(
+        operationPath,
+        'update',
+        !isSingletonResource(resourcePathItems)
+      );
+      break;
+    case 'put':
+      expectedOperationId = generateOperationIdForStandardMethod_inflector(operationPath, 'update', true);
+      break;
+    case 'delete':
+      expectedOperationId = generateOperationIdForStandardMethod_inflector(operationPath, 'delete', true);
+      break;
+  }
+  if (!expectedOperationId) {
+    console.error('Unsupported http method');
+    return;
+  }
+
+  if (operationId !== expectedOperationId) {
+    return [
+      {
+        message: `Invalid operation ID ${operationId}, please change to ${expectedOperationId}`,
+      },
+    ];
+  }
+};