Skip to content

Commit fb8fa9c

Browse files
lovisaberggrenlovisaberggren
authored
CLOUDP-304968: IPA rule xgen-IPA-117-description-should-not-use-inline-tables (#605)
1 parent 93ee87d commit fb8fa9c

File tree

4 files changed

+217
-0
lines changed

4 files changed

+217
-0
lines changed

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

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
import testRule from './__helpers__/testRule';
2+
import { DiagnosticSeverity } from '@stoplight/types';
3+
4+
testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
5+
{
6+
name: 'valid description',
7+
document: {
8+
components: {
9+
schemas: {
10+
Schema: {
11+
properties: {
12+
valid: {
13+
description: 'Description.',
14+
},
15+
validWithVerticalBar: {
16+
description: 'Must be true | false',
17+
},
18+
},
19+
},
20+
},
21+
},
22+
},
23+
errors: [],
24+
},
25+
{
26+
name: 'invalid descriptions',
27+
document: {
28+
components: {
29+
schemas: {
30+
Schema: {
31+
properties: {
32+
table: {
33+
description: '|Title|\n|-----|\n|Description|',
34+
},
35+
tableLeftAlignment: {
36+
description: '|Title|\n|:-----|\n|Description|',
37+
},
38+
tableCenterAlignment: {
39+
description: '|Title|\n|:-----:|\n|Description|',
40+
},
41+
tableRightAlignment: {
42+
description: '|Title|\n|-----:|\n|Description|',
43+
},
44+
largeTable: {
45+
description: '|Title|H1|H2|H3\n|-----|\n|Description|Description1|Description2|Description3|',
46+
},
47+
},
48+
},
49+
},
50+
},
51+
},
52+
errors: [
53+
{
54+
code: 'xgen-IPA-117-description-should-not-use-inline-tables',
55+
message:
56+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
57+
path: ['components', 'schemas', 'Schema', 'properties', 'table'],
58+
severity: DiagnosticSeverity.Warning,
59+
},
60+
{
61+
code: 'xgen-IPA-117-description-should-not-use-inline-tables',
62+
message:
63+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
64+
path: ['components', 'schemas', 'Schema', 'properties', 'tableLeftAlignment'],
65+
severity: DiagnosticSeverity.Warning,
66+
},
67+
{
68+
code: 'xgen-IPA-117-description-should-not-use-inline-tables',
69+
message:
70+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
71+
path: ['components', 'schemas', 'Schema', 'properties', 'tableCenterAlignment'],
72+
severity: DiagnosticSeverity.Warning,
73+
},
74+
{
75+
code: 'xgen-IPA-117-description-should-not-use-inline-tables',
76+
message:
77+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
78+
path: ['components', 'schemas', 'Schema', 'properties', 'tableRightAlignment'],
79+
severity: DiagnosticSeverity.Warning,
80+
},
81+
{
82+
code: 'xgen-IPA-117-description-should-not-use-inline-tables',
83+
message:
84+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
85+
path: ['components', 'schemas', 'Schema', 'properties', 'largeTable'],
86+
severity: DiagnosticSeverity.Warning,
87+
},
88+
],
89+
},
90+
{
91+
name: 'invalid descriptions with exceptions',
92+
document: {
93+
components: {
94+
schemas: {
95+
Schema: {
96+
properties: {
97+
table: {
98+
description: '|Title|\n|-----|\n|Description|',
99+
'x-xgen-IPA-exception': {
100+
'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
101+
},
102+
},
103+
tableLeftAlignment: {
104+
description: '|Title|\n|:-----|\n|Description|',
105+
'x-xgen-IPA-exception': {
106+
'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
107+
},
108+
},
109+
tableCenterAlignment: {
110+
description: '|Title|\n|:-----:|\n|Description|',
111+
'x-xgen-IPA-exception': {
112+
'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
113+
},
114+
},
115+
tableRightAlignment: {
116+
description: '|Title|\n|-----:|\n|Description|',
117+
'x-xgen-IPA-exception': {
118+
'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
119+
},
120+
},
121+
largeTable: {
122+
description: '|Title|H1|H2|H3\n|--------------|\n|Description|Description1|Description2|Description3|',
123+
'x-xgen-IPA-exception': {
124+
'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
125+
},
126+
},
127+
},
128+
},
129+
},
130+
},
131+
},
132+
errors: [],
133+
},
134+
]);

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ functions:
66
- IPA117DescriptionStartsWithUpperCase
77
- IPA117DescriptionEndsWithPeriod
88
- IPA117DescriptionMustNotUseHtml
9+
- IPA117DescriptionShouldNotUseTables
910

1011
rules:
1112
xgen-IPA-117-description:
@@ -107,3 +108,28 @@ rules:
107108
- '$.components.parameters[*]'
108109
then:
109110
function: 'IPA117DescriptionMustNotUseHtml'
111+
xgen-IPA-117-description-should-not-use-inline-tables:
112+
description: |
113+
Descriptions should not include inline tables as this may not work well with all tools, in particular generated client code.
114+
115+
##### Implementation details
116+
Rule checks the format of the descriptions for components:
117+
- Info object
118+
- Tags
119+
- Operation objects
120+
- Inline schema properties for operation object requests and responses
121+
- Parameter objects (in operations and components)
122+
- Schema properties
123+
The rule validates that the description content does not include inline markdown tables.
124+
message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-117-description-should-not-use-inline-tables'
125+
severity: warn
126+
given:
127+
- '$.info'
128+
- '$.tags[*]'
129+
- '$.paths[*][get,put,post,delete,options,head,patch,trace]'
130+
- '$.paths[*][get,put,post,delete,options,head,patch,trace].parameters[*]'
131+
- '$.paths[*][get,put,post,delete,options,head,patch,trace]..content..properties[*]'
132+
- '$.components.schemas..properties[*]'
133+
- '$.components.parameters[*]'
134+
then:
135+
function: 'IPA117DescriptionShouldNotUseTables'

‎tools/spectral/ipa/rulesets/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -617,6 +617,21 @@ Rule checks the format of the descriptions for components:
617617
- Schema properties
618618
The rule validates that the description content does not include opening and/or closing HTML tags.
619619

620+
#### xgen-IPA-117-description-should-not-use-inline-tables
621+
622+
![warn](https://img.shields.io/badge/warning-yellow)
623+
Descriptions should not include inline tables as this may not work well with all tools, in particular generated client code.
624+
625+
##### Implementation details
626+
Rule checks the format of the descriptions for components:
627+
- Info object
628+
- Tags
629+
- Operation objects
630+
- Inline schema properties for operation object requests and responses
631+
- Parameter objects (in operations and components)
632+
- Schema properties
633+
The rule validates that the description content does not include inline markdown tables.
634+
620635

621636

622637
### IPA-123

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { hasException } from './utils/exceptions.js';
2+
import {
3+
collectAdoption,
4+
collectAndReturnViolation,
5+
collectException,
6+
handleInternalError,
7+
} from './utils/collectionUtils.js';
8+
9+
const RULE_NAME = 'xgen-IPA-117-description-should-not-use-inline-tables';
10+
const ERROR_MESSAGE =
11+
'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.';
12+
13+
export default (input, opts, { path }) => {
14+
// Ignore missing descriptions
15+
if (!input['description']) {
16+
return;
17+
}
18+
19+
if (hasException(input, RULE_NAME)) {
20+
collectException(input, RULE_NAME, path);
21+
return;
22+
}
23+
24+
const errors = checkViolationsAndReturnErrors(input['description'], path);
25+
if (errors.length !== 0) {
26+
return collectAndReturnViolation(path, RULE_NAME, errors);
27+
}
28+
collectAdoption(path, RULE_NAME);
29+
};
30+
31+
function checkViolationsAndReturnErrors(description, path) {
32+
const tablePattern = new RegExp(`[|]:?-+:?[|]`);
33+
34+
try {
35+
if (tablePattern.test(description)) {
36+
return [{ path, message: ERROR_MESSAGE }];
37+
}
38+
return [];
39+
} catch (e) {
40+
handleInternalError(RULE_NAME, path, e);
41+
}
42+
}

0 commit comments

Comments
 (0)