Skip to content

Commit cb2c62e

Browse files
lovisaberggrenlovisaberggren
authored
feat(ipa): new rule xgen-IPA-117-operation-summary-single-item-wording (#913)
1 parent 5590ee6 commit cb2c62e

File tree

4 files changed

+186
-0
lines changed

4 files changed

+186
-0
lines changed

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

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
import testRule from './__helpers__/testRule';
2+
import { DiagnosticSeverity } from '@stoplight/types';
3+
4+
testRule('xgen-IPA-117-operation-summary-single-item-wording', [
5+
{
6+
name: 'valid summary',
7+
document: {
8+
paths: {
9+
'/resource/{id}': {
10+
get: {
11+
summary: 'Return One Resource by ID',
12+
},
13+
},
14+
},
15+
},
16+
errors: [],
17+
},
18+
{
19+
name: 'invalid summaries',
20+
document: {
21+
paths: {
22+
'/resource1/{id}': {
23+
get: {
24+
summary: 'Return One Resource for the Provided Group',
25+
},
26+
},
27+
'/resource2/{id}': {
28+
get: {
29+
summary: 'Return the Specified Resource by ID',
30+
},
31+
},
32+
'/resource3/{id}': {
33+
get: {
34+
summary: 'Return a Resource by ID',
35+
},
36+
},
37+
'/resource4/{id}': {
38+
get: {
39+
summary: 'Return a Resource for the Provided Group',
40+
},
41+
},
42+
},
43+
},
44+
errors: [
45+
{
46+
code: 'xgen-IPA-117-operation-summary-single-item-wording',
47+
message: 'Operation summary referring to a single item must use "one" instead of "provided".',
48+
path: ['paths', '/resource1/{id}', 'get'],
49+
severity: DiagnosticSeverity.Warning,
50+
},
51+
{
52+
code: 'xgen-IPA-117-operation-summary-single-item-wording',
53+
message: 'Operation summary referring to a single item must use "one" instead of "specified".',
54+
path: ['paths', '/resource2/{id}', 'get'],
55+
severity: DiagnosticSeverity.Warning,
56+
},
57+
{
58+
code: 'xgen-IPA-117-operation-summary-single-item-wording',
59+
message: 'Operation summary referring to a single item must use "one" instead of "a".',
60+
path: ['paths', '/resource3/{id}', 'get'],
61+
severity: DiagnosticSeverity.Warning,
62+
},
63+
{
64+
code: 'xgen-IPA-117-operation-summary-single-item-wording',
65+
message: 'Operation summary referring to a single item must use "one" instead of "a".',
66+
path: ['paths', '/resource4/{id}', 'get'],
67+
severity: DiagnosticSeverity.Warning,
68+
},
69+
{
70+
code: 'xgen-IPA-117-operation-summary-single-item-wording',
71+
message: 'Operation summary referring to a single item must use "one" instead of "provided".',
72+
path: ['paths', '/resource4/{id}', 'get'],
73+
severity: DiagnosticSeverity.Warning,
74+
},
75+
],
76+
},
77+
{
78+
name: 'invalid summary with exceptions',
79+
document: {
80+
paths: {
81+
'/resource1/{id}': {
82+
get: {
83+
summary: 'Return One Resource for the Provided Group',
84+
'x-xgen-IPA-exception': {
85+
'xgen-IPA-117-operation-summary-single-item-wording': 'reason',
86+
},
87+
},
88+
},
89+
'/resource2/{id}': {
90+
get: {
91+
summary: 'Return the Specified Resource by ID',
92+
'x-xgen-IPA-exception': {
93+
'xgen-IPA-117-operation-summary-single-item-wording': 'reason',
94+
},
95+
},
96+
},
97+
'/resource3/{id}': {
98+
get: {
99+
summary: 'Return a Resource by ID',
100+
'x-xgen-IPA-exception': {
101+
'xgen-IPA-117-operation-summary-single-item-wording': 'reason',
102+
},
103+
},
104+
},
105+
},
106+
},
107+
errors: [],
108+
},
109+
]);

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ functions:
1313
- IPA117ParameterHasExamplesOrSchema
1414
- IPA117OperationSummaryFormat
1515
- IPA117OperationSummaryStartsWith
16+
- IPA117OperationSummarySingleItemWording
1617

1718
aliases:
1819
OperationObject:
@@ -361,3 +362,27 @@ rules:
361362
allowedStartVerbs:
362363
- Delete
363364
- Remove
365+
xgen-IPA-117-operation-summary-single-item-wording:
366+
description: |
367+
API Producers must use "One" when referring to a single item instead of "a" or "specified".
368+
369+
##### Implementation details
370+
- The rule checks that the `summary` property of operations does not use the words "a", "specified" or "provided"
371+
- This rule applies to all operations, including custom methods
372+
##### Configuration
373+
This rule includes a configuration option:
374+
- `preferredWords`: List of words that the operation summary should use for single items, defaults to `['one']`. Only used for error messages
375+
- `forbiddenWords`: List of words (lowercase) that the operation summary should not use, defaults to `['a', 'specified']`
376+
message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-117-operation-summary-single-item-wording'
377+
severity: warn
378+
given:
379+
- '#OperationObject.summary'
380+
then:
381+
function: 'IPA117OperationSummarySingleItemWording'
382+
functionOptions:
383+
preferredWords:
384+
- one
385+
forbiddenWords:
386+
- a
387+
- specified
388+
- provided

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -940,6 +940,19 @@ In operation summaries, use 'Delete' when the operation is destroying a resource
940940
This rule includes a configuration option:
941941
- `allowedStartVerbs`: Allow list of verb that the operation summary can start with, defaults to `['Delete', 'Remove']`
942942

943+
#### xgen-IPA-117-operation-summary-single-item-wording
944+
945+
![warn](https://img.shields.io/badge/warning-yellow)
946+
API Producers must use "One" when referring to a single item instead of "a" or "specified".
947+
948+
##### Implementation details
949+
- The rule checks that the `summary` property of operations does not use the words "a", "specified" or "provided"
950+
- This rule applies to all operations, including custom methods
951+
##### Configuration
952+
This rule includes a configuration option:
953+
- `preferredWords`: List of words that the operation summary should use for single items, defaults to `['one']`. Only used for error messages
954+
- `forbiddenWords`: List of words (lowercase) that the operation summary should not use, defaults to `['a', 'specified']`
955+
943956

944957

945958
### IPA-118

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import { evaluateAndCollectAdoptionStatus, handleInternalError } from './utils/collectionUtils.js';
2+
import { resolveObject } from './utils/componentUtils.js';
3+
4+
export default (input, { preferredWords, forbiddenWords }, { path, rule, documentInventory }) => {
5+
const operationObjectPath = path.slice(0, -1);
6+
const operationObject = resolveObject(documentInventory.resolved, operationObjectPath);
7+
8+
const errors = checkViolationsAndReturnErrors(input, preferredWords, forbiddenWords, operationObjectPath, rule.name);
9+
return evaluateAndCollectAdoptionStatus(errors, rule.name, operationObject, operationObjectPath);
10+
};
11+
12+
function checkViolationsAndReturnErrors(summary, preferredWords, forbiddenWords, path, ruleName) {
13+
try {
14+
const errors = [];
15+
const words = summary.toLowerCase().split(' ');
16+
17+
forbiddenWords.forEach((forbiddenWord) => {
18+
words.forEach((word) => {
19+
if (word === forbiddenWord) {
20+
if (preferredWords.length === 1) {
21+
errors.push({
22+
path,
23+
message: `Operation summary referring to a single item must use "${preferredWords[0]}" instead of "${forbiddenWord}".`,
24+
});
25+
} else {
26+
errors.push({
27+
path,
28+
message: `Operation summary referring to a single item must use one of the words [${preferredWords}] instead of ${forbiddenWords}.`,
29+
});
30+
}
31+
}
32+
});
33+
});
34+
35+
return errors;
36+
} catch (e) {
37+
return handleInternalError(ruleName, path, e);
38+
}
39+
}

0 commit comments

Comments
 (0)