From 839c1a81bc7075c61cc967b53a3218901b5ca43b Mon Sep 17 00:00:00 2001 From: Lovisa Berggren Date: Tue, 25 Mar 2025 18:05:39 +0000 Subject: [PATCH 1/2] CLOUDP-304968: IPA rule xgen-IPA-117-description-should-not-use-inline-tables --- ...PA117DescriptionShouldNotUseTables.test.js | 134 ++++++++++++++++++ tools/spectral/ipa/rulesets/IPA-117.yaml | 26 ++++ tools/spectral/ipa/rulesets/README.md | 15 ++ .../IPA117DescriptionShouldNotUseTables.js | 42 ++++++ 4 files changed, 217 insertions(+) create mode 100644 tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js create mode 100644 tools/spectral/ipa/rulesets/functions/IPA117DescriptionShouldNotUseTables.js diff --git a/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js b/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js new file mode 100644 index 0000000000..97d23eed9b --- /dev/null +++ b/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: [], + }, +]); diff --git a/tools/spectral/ipa/rulesets/IPA-117.yaml b/tools/spectral/ipa/rulesets/IPA-117.yaml index 3fae95e33f..c66a7aabe9 100644 --- a/tools/spectral/ipa/rulesets/IPA-117.yaml +++ b/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' diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index cbca189c46..bbc876b77a 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/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 diff --git a/tools/spectral/ipa/rulesets/functions/IPA117DescriptionShouldNotUseTables.js b/tools/spectral/ipa/rulesets/functions/IPA117DescriptionShouldNotUseTables.js new file mode 100644 index 0000000000..ae713cd37b --- /dev/null +++ b/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); + } +} From 1422821586506aa08ac590089301ab93c181b737 Mon Sep 17 00:00:00 2001 From: Lovisa Berggren Date: Tue, 25 Mar 2025 18:09:08 +0000 Subject: [PATCH 2/2] CLOUDP-304968: Fix --- .../ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js b/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js index 97d23eed9b..dd25fbce69 100644 --- a/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js +++ b/tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js @@ -119,7 +119,7 @@ testRule('xgen-IPA-117-description-should-not-use-inline-tables', [ }, }, largeTable: { - description: '|Title|H1|H2|H3\n|-----|\n|Description|Description1|Description2|Description3|', + 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', },