CLOUDP-304931: Adds xgen-IPA-105-resource-has-list (#515)

Author: lovisaberggren

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

@@ -0,0 +1,98 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-105-resource-has-list', [
+  {
+    name: 'valid methods',
+    document: {
+      paths: {
+        '/standard': {
+          post: {},
+          get: {},
+        },
+        '/standard/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+        '/standard/{exampleId}/nested': {
+          post: {},
+          get: {},
+        },
+        '/standard/{exampleId}/nested/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid methods',
+    document: {
+      paths: {
+        '/standard': {
+          post: {},
+        },
+        '/standard/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+        '/standard/{exampleId}/nested': {
+          post: {},
+        },
+        '/standard/{exampleId}/nested/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-105-resource-has-list',
+        message: 'APIs must provide a List method for resources. http://go/ipa/105',
+        path: ['paths', '/standard'],
+        severity: DiagnosticSeverity.Warning,
+      },
+      {
+        code: 'xgen-IPA-105-resource-has-list',
+        message: 'APIs must provide a List method for resources. http://go/ipa/105',
+        path: ['paths', '/standard/{exampleId}/nested'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'invalid method with exception',
+    document: {
+      paths: {
+        '/standard': {
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-105-resource-has-list': 'reason',
+          },
+          post: {},
+        },
+        '/standard/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+        '/standard/{exampleId}/nested': {
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-105-resource-has-list': 'reason',
+          },
+          post: {},
+        },
+        '/standard/{exampleId}/nested/{exampleId}': {
+          get: {},
+          patch: {},
+          delete: {},
+        },
+      },
+    },
+    errors: [],
+  },
+]);

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

@@ -4,6 +4,7 @@
 functions:
   - listResponseCodeShouldBe200OK
   - listMethodHasNoRequestBody
+  - eachResourceHasListMethod
 
 rules:
   xgen-IPA-105-list-method-response-code-is-200:
@@ -20,3 +21,11 @@ rules:
     given: '$.paths[*].get'
     then:
       function: 'listMethodHasNoRequestBody'
+  xgen-IPA-105-resource-has-list:
+    description: 'APIs must provide a List method for resources. http://go/ipa/105'
+    message: '{{error}} http://go/ipa/105'
+    severity: warn
+    given: '$.paths'
+    then:
+      field: '@key'
+      function: 'eachResourceHasListMethod'

tools/spectral/ipa/rulesets/README.md

@@ -46,6 +46,7 @@ For rule definitions, see [IPA-105.yaml](https://github.com/mongodb/openapi/blob
 | --------------------------------------------- | ------------------------------------------------------------------ | -------- |
 | xgen-IPA-105-list-method-response-code-is-200 | The List method must return a 200 OK response. http://go/ipa/105   | warn     |
 | xgen-IPA-105-list-method-no-request-body      | The List method request must not include a body. http://go/ipa/105 | warn     |
+| xgen-IPA-105-resource-has-list                | APIs must provide a List method for resources. http://go/ipa/105   | warn     |
 
 ### IPA-106
 

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

@@ -0,0 +1,37 @@
+import {
+  hasGetMethod,
+  isSingletonResource,
+  getResourcePathItems,
+  isResourceCollectionIdentifier,
+} from './utils/resourceEvaluation.js';
+import { hasException } from './utils/exceptions.js';
+import { collectAdoption, collectAndReturnViolation, collectException } from './utils/collectionUtils.js';
+
+const RULE_NAME = 'xgen-IPA-105-resource-has-list';
+const ERROR_MESSAGE = 'APIs must provide a List method for resources.';
+
+export default (input, _, { path, documentInventory }) => {
+  const oas = documentInventory.resolved;
+
+  if (!isResourceCollectionIdentifier(input) || isSingletonResource(getResourcePathItems(input, oas.paths))) {
+    return;
+  }
+
+  if (hasException(oas.paths[input], RULE_NAME)) {
+    collectException(oas.paths[input], RULE_NAME, path);
+    return;
+  }
+
+  const errors = checkViolationsAndReturnErrors(oas.paths[input], input, path);
+  if (errors.length !== 0) {
+    return collectAndReturnViolation(path, RULE_NAME, errors);
+  }
+  collectAdoption(path, RULE_NAME);
+};
+
+function checkViolationsAndReturnErrors(pathItem, input, path) {
+  if (!hasGetMethod(pathItem)) {
+    return [{ path, message: ERROR_MESSAGE }];
+  }
+  return [];
+}