CLOUDP-304968: IPA rule xgen-IPA-117-description-should-not-use-inline-tables

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

@@ -0,0 +1,134 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
+  {
+    name: 'valid description',
+    document: {
+      components: {
+        schemas: {
+          Schema: {
+            properties: {
+              valid: {
+                description: 'Description.',
+              },
+              validWithVerticalBar: {
+                description: 'Must be true | false',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid descriptions',
+    document: {
+      components: {
+        schemas: {
+          Schema: {
+            properties: {
+              table: {
+                description: '|Title|\n|-----|\n|Description|',
+              },
+              tableLeftAlignment: {
+                description: '|Title|\n|:-----|\n|Description|',
+              },
+              tableCenterAlignment: {
+                description: '|Title|\n|:-----:|\n|Description|',
+              },
+              tableRightAlignment: {
+                description: '|Title|\n|-----:|\n|Description|',
+              },
+              largeTable: {
+                description: '|Title|H1|H2|H3\n|-----|\n|Description|Description1|Description2|Description3|',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema', 'properties', 'table'],
+        severity: DiagnosticSeverity.Warning,
+      },
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema', 'properties', 'tableLeftAlignment'],
+        severity: DiagnosticSeverity.Warning,
+      },
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema', 'properties', 'tableCenterAlignment'],
+        severity: DiagnosticSeverity.Warning,
+      },
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema', 'properties', 'tableRightAlignment'],
+        severity: DiagnosticSeverity.Warning,
+      },
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema', 'properties', 'largeTable'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'invalid descriptions with exceptions',
+    document: {
+      components: {
+        schemas: {
+          Schema: {
+            properties: {
+              table: {
+                description: '|Title|\n|-----|\n|Description|',
+                'x-xgen-IPA-exception': {
+                  'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+                },
+              },
+              tableLeftAlignment: {
+                description: '|Title|\n|:-----|\n|Description|',
+                'x-xgen-IPA-exception': {
+                  'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+                },
+              },
+              tableCenterAlignment: {
+                description: '|Title|\n|:-----:|\n|Description|',
+                'x-xgen-IPA-exception': {
+                  'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+                },
+              },
+              tableRightAlignment: {
+                description: '|Title|\n|-----:|\n|Description|',
+                'x-xgen-IPA-exception': {
+                  'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+                },
+              },
+              largeTable: {
+                description: '|Title|H1|H2|H3\n|--------------|\n|Description|Description1|Description2|Description3|',
+                'x-xgen-IPA-exception': {
+                  'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

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

@@ -6,6 +6,7 @@ functions:
   - IPA117DescriptionStartsWithUpperCase
   - IPA117DescriptionEndsWithPeriod
   - IPA117DescriptionMustNotUseHtml
+  - IPA117DescriptionShouldNotUseTables
 
 rules:
   xgen-IPA-117-description:
@@ -107,3 +108,28 @@ rules:
       - '$.components.parameters[*]'
     then:
       function: 'IPA117DescriptionMustNotUseHtml'
+  xgen-IPA-117-description-should-not-use-inline-tables:
+    description: |
+      Descriptions should not include inline tables as this may not work well with all tools, in particular generated client code.
+
+      ##### Implementation details
+      Rule checks the format of the descriptions for components:
+        - Info object
+        - Tags
+        - Operation objects
+        - Inline schema properties for operation object requests and responses
+        - Parameter objects (in operations and components)
+        - Schema properties
+      The rule validates that the description content does not include inline markdown tables.
+    message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-117-description-should-not-use-inline-tables'
+    severity: warn
+    given:
+      - '$.info'
+      - '$.tags[*]'
+      - '$.paths[*][get,put,post,delete,options,head,patch,trace]'
+      - '$.paths[*][get,put,post,delete,options,head,patch,trace].parameters[*]'
+      - '$.paths[*][get,put,post,delete,options,head,patch,trace]..content..properties[*]'
+      - '$.components.schemas..properties[*]'
+      - '$.components.parameters[*]'
+    then:
+      function: 'IPA117DescriptionShouldNotUseTables'

tools/spectral/ipa/rulesets/README.md

@@ -617,6 +617,21 @@ Rule checks the format of the descriptions for components:
   - Schema properties
 The rule validates that the description content does not include opening and/or closing HTML tags.
 
+#### xgen-IPA-117-description-should-not-use-inline-tables
+
+ ![warn](https://img.shields.io/badge/warning-yellow) 
+Descriptions should not include inline tables as this may not work well with all tools, in particular generated client code.
+
+##### Implementation details
+Rule checks the format of the descriptions for components:
+  - Info object
+  - Tags
+  - Operation objects
+  - Inline schema properties for operation object requests and responses
+  - Parameter objects (in operations and components)
+  - Schema properties
+The rule validates that the description content does not include inline markdown tables.
+
 
 
 ### IPA-123

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

@@ -0,0 +1,42 @@
+import { hasException } from './utils/exceptions.js';
+import {
+  collectAdoption,
+  collectAndReturnViolation,
+  collectException,
+  handleInternalError,
+} from './utils/collectionUtils.js';
+
+const RULE_NAME = 'xgen-IPA-117-description-should-not-use-inline-tables';
+const ERROR_MESSAGE =
+  'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.';
+
+export default (input, opts, { path }) => {
+  // Ignore missing descriptions
+  if (!input['description']) {
+    return;
+  }
+
+  if (hasException(input, RULE_NAME)) {
+    collectException(input, RULE_NAME, path);
+    return;
+  }
+
+  const errors = checkViolationsAndReturnErrors(input['description'], path);
+  if (errors.length !== 0) {
+    return collectAndReturnViolation(path, RULE_NAME, errors);
+  }
+  collectAdoption(path, RULE_NAME);
+};
+
+function checkViolationsAndReturnErrors(description, path) {
+  const tablePattern = new RegExp(`[|]:?-+:?[|]`);
+
+  try {
+    if (tablePattern.test(description)) {
+      return [{ path, message: ERROR_MESSAGE }];
+    }
+    return [];
+  } catch (e) {
+    handleInternalError(RULE_NAME, path, e);
+  }
+}