Skip to content

Commit 8990cac

Browse files
Samuel Bodinmillotpshortcuts
authored
fix(spec): cleanup summary (#451)
Co-authored-by: Pierre Millot <[email protected]> Co-authored-by: Clément Vannicatte <[email protected]>
1 parent 4be8998 commit 8990cac

36 files changed

+101
-118
lines changed

‎.eslintrc.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ module.exports = {
4343
overrides: [{
4444
files: ['specs/**/*.yml'],
4545
rules: {
46-
"automation-custom/description-dot": "error",
46+
"automation-custom/end-with-dot": "error",
4747
"automation-custom/single-quote-ref": "error",
4848
},
4949
overrides: [

‎.github/.cache_version

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
9.2.0.0
1+
9.2.2

‎.github/actions/cache/action.yml

Lines changed: 10 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ inputs:
1515
spec:
1616
description: The name of the spec to restore, used for client matrix gen.
1717
required: false
18+
specPath:
19+
description: The path of the spec to hash
20+
required: false
1821

1922
runs:
2023
using: composite
@@ -45,14 +48,14 @@ runs:
4548

4649
# Restore bundled specs from input: used during 'client' generation
4750
- name: Restore ${{ inputs.spec }} built spec
48-
if: ${{ inputs.job == 'client' && inputs.spec }}
51+
if: ${{ inputs.job == 'client' && inputs.spec && inputs.specPath }}
4952
uses: actions/cache@v3
5053
with:
5154
path: ${{ format('specs/bundled/{0}.yml', inputs.spec) }}
5255
key: |
5356
${{ env.CACHE_VERSION }}-${{
5457
hashFiles(
55-
format('specs/{0}/**', inputs.spec),
58+
format('specs/{0}/**', inputs.specPath),
5659
'specs/common/**'
5760
)}}
5861
@@ -220,10 +223,11 @@ runs:
220223
key: |
221224
${{ env.CACHE_VERSION }}-${{
222225
hashFiles(
223-
'clients/algoliasearch-client-javascript/packages/algoliasearch/**',
224-
'clients/algoliasearch-client-javascript/packages/client-search/**',
225-
'clients/algoliasearch-client-javascript/packages/client-analytics/**',
226-
'clients/algoliasearch-client-javascript/packages/client-personalization/**'
226+
'specs/bundled/search.yml',
227+
'specs/bundled/analytics.yml',
228+
'specs/bundled/personalization.yml',
229+
'templates/javascript/**',
230+
'generators/src/**'
227231
)}}
228232
229233
- name: Restore built JavaScript algoliasearch-lite client
@@ -234,10 +238,6 @@ runs:
234238
key: |
235239
${{ env.CACHE_VERSION }}-${{
236240
hashFiles(
237-
'clients/algoliasearch-client-javascript/packages/algoliasearch-lite/src/**',
238-
'clients/algoliasearch-client-javascript/packages/algoliasearch-lite/model/**',
239-
'clients/algoliasearch-client-javascript/packages/algoliasearch-lite/builds/**',
240-
'clients/algoliasearch-client-javascript/packages/algoliasearch-lite/package.json',
241241
'specs/bundled/algoliasearch-lite.yml',
242242
'templates/javascript/**',
243243
'generators/src/**'
@@ -251,10 +251,6 @@ runs:
251251
key: |
252252
${{ env.CACHE_VERSION }}-${{
253253
hashFiles(
254-
'clients/algoliasearch-client-javascript/packages/client-search/src/**',
255-
'clients/algoliasearch-client-javascript/packages/client-search/model/**',
256-
'clients/algoliasearch-client-javascript/packages/client-search/builds/**',
257-
'clients/algoliasearch-client-javascript/packages/client-search/package.json',
258254
'specs/bundled/search.yml',
259255
'templates/javascript/**',
260256
'generators/src/**'
@@ -268,10 +264,6 @@ runs:
268264
key: |
269265
${{ env.CACHE_VERSION }}-${{
270266
hashFiles(
271-
'clients/algoliasearch-client-javascript/packages/recommend/src/**',
272-
'clients/algoliasearch-client-javascript/packages/recommend/model/**',
273-
'clients/algoliasearch-client-javascript/packages/recommend/builds/**',
274-
'clients/algoliasearch-client-javascript/packages/recommend/package.json',
275267
'specs/bundled/recommend.yml',
276268
'templates/javascript/**',
277269
'generators/src/**'
@@ -285,10 +277,6 @@ runs:
285277
key: |
286278
${{ env.CACHE_VERSION }}-${{
287279
hashFiles(
288-
'clients/algoliasearch-client-javascript/packages/client-query-suggestions/src/**',
289-
'clients/algoliasearch-client-javascript/packages/client-query-suggestions/model/**',
290-
'clients/algoliasearch-client-javascript/packages/client-query-suggestions/builds/**',
291-
'clients/algoliasearch-client-javascript/packages/client-query-suggestions/package.json',
292280
'specs/bundled/query-suggestions.yml',
293281
'templates/javascript/**',
294282
'generators/src/**'
@@ -302,10 +290,6 @@ runs:
302290
key: |
303291
${{ env.CACHE_VERSION }}-${{
304292
hashFiles(
305-
'clients/algoliasearch-client-javascript/packages/client-personalization/src/**',
306-
'clients/algoliasearch-client-javascript/packages/client-personalization/model/**',
307-
'clients/algoliasearch-client-javascript/packages/client-personalization/builds/**',
308-
'clients/algoliasearch-client-javascript/packages/client-personalization/package.json',
309293
'specs/bundled/personalization.yml',
310294
'templates/javascript/**',
311295
'generators/src/**'
@@ -319,10 +303,6 @@ runs:
319303
key: |
320304
${{ env.CACHE_VERSION }}-${{
321305
hashFiles(
322-
'clients/algoliasearch-client-javascript/packages/client-analytics/src/**',
323-
'clients/algoliasearch-client-javascript/packages/client-analytics/model/**',
324-
'clients/algoliasearch-client-javascript/packages/client-analytics/builds/**',
325-
'clients/algoliasearch-client-javascript/packages/client-analytics/package.json',
326306
'specs/bundled/analytics.yml',
327307
'templates/javascript/**',
328308
'generators/src/**'
@@ -336,10 +316,6 @@ runs:
336316
key: |
337317
${{ env.CACHE_VERSION }}-${{
338318
hashFiles(
339-
'clients/algoliasearch-client-javascript/packages/client-abtesting/src/**',
340-
'clients/algoliasearch-client-javascript/packages/client-abtesting/model/**',
341-
'clients/algoliasearch-client-javascript/packages/client-abtesting/builds/**',
342-
'clients/algoliasearch-client-javascript/packages/client-abtesting/package.json',
343319
'specs/bundled/abtesting.yml',
344320
'templates/javascript/**',
345321
'generators/src/**'
@@ -353,10 +329,6 @@ runs:
353329
key: |
354330
${{ env.CACHE_VERSION }}-${{
355331
hashFiles(
356-
'clients/algoliasearch-client-javascript/packages/client-insights/src/**',
357-
'clients/algoliasearch-client-javascript/packages/client-insights/model/**',
358-
'clients/algoliasearch-client-javascript/packages/client-insights/builds/**',
359-
'clients/algoliasearch-client-javascript/packages/client-insights/package.json',
360332
'specs/bundled/insights.yml',
361333
'templates/javascript/**',
362334
'generators/src/**'
@@ -370,10 +342,6 @@ runs:
370342
key: |
371343
${{ env.CACHE_VERSION }}-${{
372344
hashFiles(
373-
'clients/algoliasearch-client-javascript/packages/client-sources/src/**',
374-
'clients/algoliasearch-client-javascript/packages/client-sources/model/**',
375-
'clients/algoliasearch-client-javascript/packages/client-sources/builds/**',
376-
'clients/algoliasearch-client-javascript/packages/client-sources/package.json',
377345
'specs/bundled/sources.yml',
378346
'templates/javascript/**',
379347
'generators/src/**'
@@ -387,10 +355,6 @@ runs:
387355
key: |
388356
${{ env.CACHE_VERSION }}-${{
389357
hashFiles(
390-
'clients/algoliasearch-client-javascript/packages/client-predict/src/**',
391-
'clients/algoliasearch-client-javascript/packages/client-predict/model/**',
392-
'clients/algoliasearch-client-javascript/packages/client-predict/builds/**',
393-
'clients/algoliasearch-client-javascript/packages/client-predict/package.json',
394358
'specs/bundled/predict.yml',
395359
'templates/javascript/**',
396360
'generators/src/**'

‎.github/actions/setup/action.yml

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,6 @@ inputs:
1313
runs:
1414
using: composite
1515
steps:
16-
- name: Read current GitHub Actions cache version
17-
shell: bash
18-
run: echo "CACHE_VERSION=$(< .github/.cache_version)" >> $GITHUB_ENV
19-
2016
- name: Install Node
2117
uses: actions/setup-node@v2
2218
with:

‎.github/workflows/check.yml

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ jobs:
172172
job: client
173173
language: javascript
174174
spec: ${{ matrix.client.name }}
175+
specPath: ${{ matrix.client.specPath }}
175176
cache_hash: ${{ needs.setup.outputs.CACHE_COMMON_HASH }}
176177

177178
- name: Cache '${{ matrix.client.name }}' client
@@ -182,10 +183,6 @@ jobs:
182183
key: |
183184
${{ env.CACHE_VERSION }}-${{
184185
hashFiles(
185-
format('{0}/src/**', matrix.client.path),
186-
format('{0}/model/**', matrix.client.path),
187-
format('{0}/builds/**', matrix.client.path),
188-
format('{0}/package.json', matrix.client.path),
189186
format('specs/bundled/{0}.yml', matrix.client.name),
190187
'templates/javascript/**',
191188
'generators/src/**'
@@ -334,10 +331,11 @@ jobs:
334331
key: |
335332
${{ env.CACHE_VERSION }}-${{
336333
hashFiles(
337-
'clients/algoliasearch-client-javascript/packages/algoliasearch/**',
338-
'clients/algoliasearch-client-javascript/packages/client-search/**',
339-
'clients/algoliasearch-client-javascript/packages/client-analytics/**',
340-
'clients/algoliasearch-client-javascript/packages/client-personalization/**'
334+
'specs/bundled/search.yml',
335+
'specs/bundled/analytics.yml',
336+
'specs/bundled/personalization.yml',
337+
'templates/javascript/**',
338+
'generators/src/**'
341339
)}}
342340
343341
- name: Build 'algoliasearch' client

‎eslint/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"src/**.ts"
88
],
99
"scripts": {
10-
"build": "tsc",
10+
"build": "rm -rf dist/ && tsc",
1111
"test": "jest"
1212
},
1313
"devDependencies": {

‎eslint/src/index.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
import { descriptionDot } from './rules/descriptionDot';
1+
import { endWithDot } from './rules/endWithDot';
22
import { outOfLineEnum } from './rules/outOfLineEnum';
33
import { singleQuoteRef } from './rules/singleQuoteRef';
44

55
const rules = {
6-
'description-dot': descriptionDot,
6+
'end-with-dot': endWithDot,
77
'out-of-line-enum': outOfLineEnum,
88
'single-quote-ref': singleQuoteRef,
99
};

‎eslint/src/rules/descriptionDot.ts renamed to ‎eslint/src/rules/endWithDot.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
1-
/* eslint-disable no-console */
21
import type { Rule } from 'eslint';
32

43
import { isBLockScalar, isPairWithKey, isScalar } from '../utils';
54

6-
export const descriptionDot: Rule.RuleModule = {
5+
export const endWithDot: Rule.RuleModule = {
76
meta: {
87
docs: {
9-
description: 'description must end with a dot',
8+
description: '`description`, `summary` must end with a dot',
109
},
1110
messages: {
12-
descriptionNoDot: 'description does not end with a dot',
11+
endWithDot: 'content does not end with a dot',
1312
},
1413
fixable: 'code',
1514
},
@@ -20,12 +19,17 @@ export const descriptionDot: Rule.RuleModule = {
2019

2120
return {
2221
YAMLPair(node): void {
23-
if (!isPairWithKey(node, 'description')) {
22+
if (
23+
!isPairWithKey(node, 'description') &&
24+
!isPairWithKey(node, 'summary')
25+
) {
2426
return;
2527
}
28+
2629
if (!isScalar(node.value)) {
2730
return;
2831
}
32+
2933
const value = node.value;
3034
if (
3135
typeof value.value !== 'string' ||
@@ -46,7 +50,7 @@ export const descriptionDot: Rule.RuleModule = {
4650
}
4751
context.report({
4852
node: node as any,
49-
messageId: 'descriptionNoDot',
53+
messageId: 'endWithDot',
5054
fix(fixer) {
5155
return fixer.insertTextAfterRange(
5256
[0, value.range[1] - toTrim],

‎eslint/tests/descriptionDot.test.ts renamed to ‎eslint/tests/endWithDot.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
import { RuleTester } from 'eslint';
22

3-
import { descriptionDot } from '../src/rules/descriptionDot';
3+
import { endWithDot } from '../src/rules/endWithDot';
44

55
const ruleTester = new RuleTester({
66
parser: require.resolve('yaml-eslint-parser'),
77
});
88

9-
ruleTester.run('description-dot', descriptionDot, {
9+
ruleTester.run('end-with-dot', endWithDot, {
1010
valid: [
1111
`
1212
simple:

‎scripts/buildSpecs.ts

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,15 @@ const ALGOLIASEARCH_LITE_OPERATIONS = [
1919
'post',
2020
];
2121

22-
async function propagateTagsToOperations({
22+
/**
23+
* This function will transform properties in the bundle depending on the context.
24+
* E.g:
25+
* - Check tags definition
26+
* - Add name of the client in tags
27+
* - Remove unecessary punctuation for documentation
28+
* - etc...
29+
*/
30+
async function transformBundle({
2331
bundledPath,
2432
withDoc,
2533
clientName,
@@ -50,16 +58,23 @@ async function propagateTagsToOperations({
5058
// because open-api-generator will use this to determine the name of the client
5159
specMethod.tags = [clientName];
5260

53-
if (
54-
!withDoc ||
55-
!bundledDocSpec ||
56-
!bundledDocSpec.paths[pathKey][method].tags
57-
) {
61+
// Doc special cases
62+
if (!withDoc || !bundledDocSpec) {
63+
continue;
64+
}
65+
66+
const docMethod = bundledDocSpec.paths[pathKey][method];
67+
if (docMethod.summary) {
68+
// Remove dot at the end of summary for better sidebar display
69+
docMethod.summary = docMethod.summary.replace(/\.$/gm, '');
70+
}
71+
72+
if (!docMethod.tags) {
5873
continue;
5974
}
6075

6176
// Checks that specified tags are well defined at root level
62-
for (const tag of bundledDocSpec.paths[pathKey][method].tags) {
77+
for (const tag of docMethod.tags) {
6378
if (tag === clientName || (alias && tag === alias)) {
6479
return;
6580
}
@@ -162,7 +177,7 @@ async function buildLiteSpec({
162177
const liteBundledPath = `specs/bundled/${spec}.${outputFormat}`;
163178
await fsp.writeFile(toAbsolutePath(liteBundledPath), yaml.dump(parsed));
164179

165-
await propagateTagsToOperations({
180+
await transformBundle({
166181
bundledPath: toAbsolutePath(liteBundledPath),
167182
clientName: spec,
168183
// Lite does not need documentation because it's just a subset
@@ -223,7 +238,7 @@ async function buildSpec(
223238

224239
// Add the correct tags to be able to generate the proper client
225240
if (!isLite) {
226-
await propagateTagsToOperations({
241+
await transformBundle({
227242
bundledPath: toAbsolutePath(bundledPath),
228243
clientName: spec,
229244
withDoc: BUNDLE_WITH_DOC,

‎scripts/ci/createMatrix.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ type ClientMatrix = BaseMatrix & {
2020
api: string;
2121
capitalizedName: string;
2222
camelizedName: string;
23+
specPath: string;
2324
};
2425

2526
type SpecMatrix = BaseMatrix;
@@ -66,6 +67,7 @@ async function getClientMatrix({
6667
api: `${clientName}Client`,
6768
capitalizedName: clientName,
6869
camelizedName: camelize(client),
70+
specPath: client === 'algoliasearch-lite' ? 'search' : client,
6971
});
7072
}
7173

‎specs/search/paths/advanced/getLogs.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ get:
22
tags:
33
- Advanced
44
operationId: getLogs
5-
description: Return the lastest log entries.
6-
summary: Return the lastest log entries.
5+
description: Return the latest log entries.
6+
summary: Return the latest log entries.
77
parameters:
88
- name: offset
99
in: query

‎specs/search/paths/advanced/getTask.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ get:
33
- Indices
44
operationId: getTask
55
description: Check the current status of a given task.
6-
summary: Check the current status of a given task.
6+
summary: Check the status of a task.
77
parameters:
88
- $ref: '../../../common/parameters.yml#/IndexName'
99
- name: taskID

0 commit comments

Comments
 (0)