fix(specs): remove periods on summaries (#3013)

Author: kai687

.eslintrc.cjs

@@ -9,7 +9,7 @@ module.exports = {
     '**/target',
     '**/.yarn',
     'website/specs',
-    '**/project.packagespec.json'
+    '**/project.packagespec.json',
   ],
 
   overrides: [
@@ -52,6 +52,7 @@ module.exports = {
           files: ['specs/**/*.yml'],
           rules: {
             'automation-custom/end-with-dot': 'error',
+            'automation-custom/no-final-dot': 'error',
             'automation-custom/single-quote-ref': 'error',
           },
           overrides: [
@@ -149,7 +150,7 @@ module.exports = {
 
       parserOptions: {
         tsconfigRootDir: __dirname,
-        project: './clients/algoliasearch-client-javascript/tsconfig.json'
+        project: './clients/algoliasearch-client-javascript/tsconfig.json',
       },
 
       rules: {
@@ -183,6 +184,6 @@ module.exports = {
       rules: {
         'automation-custom/no-new-line': 'error',
       },
-    }
+    },
   ],
 };

eslint/src/index.ts

@@ -1,11 +1,13 @@
 import { endWithDot } from './rules/endWithDot';
+import { noFinalDot } from './rules/noFinalDot';
 import { noNewLine } from './rules/noNewLine';
 import { createOutOfLineRule } from './rules/outOfLineRule';
 import { singleQuoteRef } from './rules/singleQuoteRef';
 import { validACL } from './rules/validACL';
 
 const rules = {
   'end-with-dot': endWithDot,
+  'no-final-dot': noFinalDot,
   'out-of-line-enum': createOutOfLineRule({ property: 'enum' }),
   'out-of-line-one-of': createOutOfLineRule({ property: 'oneOf' }),
   'out-of-line-all-of': createOutOfLineRule({ property: 'allOf' }),

eslint/src/rules/endWithDot.ts

@@ -5,10 +5,10 @@ import { isBlockScalar, isPairWithKey, isScalar } from '../utils';
 export const endWithDot: Rule.RuleModule = {
   meta: {
     docs: {
-      description: '`description`, `summary` must end with a dot',
+      description: '`description` must end with a period',
     },
     messages: {
-      endWithDot: 'content does not end with a dot',
+      endWithDot: 'description does not end with a period',
     },
     fixable: 'code',
   },
@@ -20,8 +20,7 @@ export const endWithDot: Rule.RuleModule = {
     return {
       YAMLPair(node): void {
         if (
-          !isPairWithKey(node, 'description') &&
-          !isPairWithKey(node, 'summary')
+          !isPairWithKey(node, 'description')
         ) {
           return;
         }

eslint/src/rules/noFinalDot.ts

@@ -0,0 +1,52 @@
+import type { Rule } from 'eslint';
+
+import { isPairWithKey, isScalar } from '../utils';
+
+export const noFinalDot: Rule.RuleModule = {
+  meta: {
+    docs: {
+      description: '`summary` must not end with a period',
+    },
+    messages: {
+      noFinalDot: 'summary ends with a period',
+    },
+    fixable: 'code',
+  },
+  create(context) {
+    if (!context.sourceCode.parserServices.isYAML) {
+      return {};
+    }
+
+    return {
+      YAMLPair(node): void {
+        if (!isPairWithKey(node, 'summary')) {
+          return;
+        }
+
+        if (!isScalar(node.value)) {
+          return;
+        }
+
+        const value = node.value;
+        if (
+          typeof value.value !== 'string' ||
+          !value.value.trim().endsWith('.')
+        ) {
+          // The rule is respected if:
+          // the summary is not a string
+          // or it doesn't end with a dot.
+          return;
+        }
+
+        context.report({
+          node: node as any,
+          messageId: 'noFinalDot',
+          fix(fixer) {
+            const end = node.range[1];
+            return fixer.removeRange([end - 1, end]);
+          },
+        });
+      },
+    };
+  },
+};

eslint/tests/noFinalDot.test.ts

@@ -0,0 +1,27 @@
+import { RuleTester } from 'eslint';
+
+import { noFinalDot } from '../src/rules/noFinalDot';
+
+const ruleTester = new RuleTester({
+  parser: require.resolve('yaml-eslint-parser'),
+});
+
+ruleTester.run('no-final-dot', noFinalDot, {
+  valid: [`summary: Valid summary`],
+  invalid: [
+    {
+      code: `summary: Has final dot.`,
+      errors: [{ messageId: 'noFinalDot' }],
+      output: `summary: Has final dot`,
+    },
+    {
+      code: `summary: With dot and newline.
+
+      `,
+      errors: [{ messageId: 'noFinalDot' }],
+      output: `summary: With dot and newline
+
+      `,
+    },
+  ],
+});

specs/abtesting/paths/abtest.yml

@@ -4,7 +4,7 @@ get:
   operationId: getABTest
   x-acl:
     - analytics
-  summary: Retrieve A/B test details.
+  summary: Retrieve A/B test details
   description: Retrieves the details for an A/B test by its ID.
   parameters:
     - $ref: '../common/parameters.yml#/ID'
@@ -37,7 +37,7 @@ delete:
   operationId: deleteABTest
   x-acl:
     - editSettings
-  summary: Delete an A/B test.
+  summary: Delete an A/B test
   description: Deletes an A/B test by its ID.
   parameters:
     - $ref: '../common/parameters.yml#/ID'

specs/abtesting/paths/abtests.yml

@@ -4,7 +4,7 @@ post:
   operationId: addABTests
   x-acl:
     - editSettings
-  summary: Create an A/B test.
+  summary: Create an A/B test
   description: Creates a new A/B test.
   requestBody:
     required: true
@@ -59,7 +59,7 @@ get:
   operationId: listABTests
   x-acl:
     - analytics
-  summary: List all A/B tests.
+  summary: List all A/B tests
   description: Lists all A/B tests you configured for this application.
   parameters:
     - $ref: '../../common/parameters.yml#/Offset'

specs/abtesting/paths/stopABTest.yml

@@ -4,7 +4,7 @@ post:
   operationId: stopABTest
   x-acl:
     - editSettings
-  summary: Stop an A/B test.
+  summary: Stop an A/B test
   description: |
     Stops an A/B test by its ID.
 

specs/analytics/paths/click/getAddToCartRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getAddToCartRate
   x-acl:
     - analytics
-  summary: Retrieve add-to-cart rate.
+  summary: Retrieve add-to-cart rate
   description: |
     Retrieves the add-to-cart rate for all of your searches with at least one add-to-cart event, including a daily breakdown.
 

specs/analytics/paths/click/getAverageClickPosition.yml

@@ -4,7 +4,7 @@ get:
   operationId: getAverageClickPosition
   x-acl:
     - analytics
-  summary: Retrieve average click position.
+  summary: Retrieve average click position
   description: |
     Retrieves the average click position of your search results, including a daily breakdown.
 

specs/analytics/paths/click/getClickPositions.yml

@@ -4,7 +4,7 @@ get:
   operationId: getClickPositions
   x-acl:
     - analytics
-  summary: Retrieve click positions.
+  summary: Retrieve click positions
   description: |
     Retrieves the positions in the search results and their associated number of clicks.
 

specs/analytics/paths/click/getClickThroughRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getClickThroughRate
   x-acl:
     - analytics
-  summary: Retrieve click-through rate.
+  summary: Retrieve click-through rate
   description: |
     Retrieves the click-through rate for all of your searches with at least one click event, including a daily breakdown
 

specs/analytics/paths/click/getConversionRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getConversionRate
   x-acl:
     - analytics
-  summary: Retrieve conversion rate.
+  summary: Retrieve conversion rate
   description: |
     Retrieves the conversion rate for all of your searches with at least one conversion event, including a daily breakdown.
 

specs/analytics/paths/click/getPurchaseRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getPurchaseRate
   x-acl:
     - analytics
-  summary: Retrieve purchase rate.
+  summary: Retrieve purchase rate
   description: |
     Retrieves the purchase rate for all of your searches with at least one purchase event, including a daily breakdown.
 

specs/analytics/paths/revenue/getRevenue.yml

@@ -4,7 +4,7 @@ get:
   operationId: getRevenue
   x-acl:
     - analytics
-  summary: Retrieve revenue data.
+  summary: Retrieve revenue data
   description: |
     Retrieves revenue-related metrics, such as the total revenue or the average order value.
 

specs/analytics/paths/search/getNoClickRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getNoClickRate
   x-acl:
     - analytics
-  summary: Retrieve no click rate.
+  summary: Retrieve no click rate
   description: |
     Retrieves the fraction of searches that didn't lead to any click within a time range, including a daily breakdown.
 

specs/analytics/paths/search/getNoResultsRate.yml

@@ -4,7 +4,7 @@ get:
   operationId: getNoResultsRate
   x-acl:
     - analytics
-  summary: Retrieve no results rate.
+  summary: Retrieve no results rate
   description: |
     Retrieves the fraction of searches that didn't return any results within a time range, including a daily breakdown.
 

specs/analytics/paths/search/getSearchesCount.yml

@@ -4,7 +4,7 @@ get:
   operationId: getSearchesCount
   x-acl:
     - analytics
-  summary: Retrieve number of searches.
+  summary: Retrieve number of searches
   description: |
     Retrieves the number of searches within a time range, including a daily breakdown.
 

specs/analytics/paths/search/getSearchesNoClicks.yml

@@ -4,7 +4,7 @@ get:
   operationId: getSearchesNoClicks
   x-acl:
     - analytics
-  summary: Retrieve top searches without clicks.
+  summary: Retrieve top searches without clicks
   description: Retrieves the most popular searches that didn't lead to any clicks, from the 1,000 most frequent searches.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getSearchesNoResults.yml

@@ -4,7 +4,7 @@ get:
   operationId: getSearchesNoResults
   x-acl:
     - analytics
-  summary: Retrieve top searches without results.
+  summary: Retrieve top searches without results
   description: Retrieves the most popular searches that didn't return any results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getTopCountries.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopCountries
   x-acl:
     - analytics
-  summary: Retrieve top countries.
+  summary: Retrieve top countries
   description: Retrieves the countries with the most searches to your index.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getTopFilterAttributes.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopFilterAttributes
   x-acl:
     - analytics
-  summary: Retrieve top filters.
+  summary: Retrieve top filters
   description: |
     Retrieves the most frequently used filter attributes.
 

specs/analytics/paths/search/getTopFilterForAttribute.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopFilterForAttribute
   x-acl:
     - analytics
-  summary: Retrieve top filter values.
+  summary: Retrieve top filter values
   description: |
     Retrieves the most frequent filter (facet) values for a filter attribute.
 

specs/analytics/paths/search/getTopFiltersNoResults.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopFiltersNoResults
   x-acl:
     - analytics
-  summary: Retrieve top filters for a search without results.
+  summary: Retrieve top filters for a search without results
   description: |
     Retrieves the most frequently used filters for a search that didn't return any results.
 

specs/analytics/paths/search/getTopHits.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopHits
   x-acl:
     - analytics
-  summary: Retrieve top search results.
+  summary: Retrieve top search results
   description: Retrieves the object IDs of the most frequent search results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getTopSearches.yml

@@ -4,7 +4,7 @@ get:
   operationId: getTopSearches
   x-acl:
     - analytics
-  summary: Retrieve top searches.
+  summary: Retrieve top searches
   description: Returns the most popular search terms.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getUsersCount.yml

@@ -4,7 +4,7 @@ get:
   operationId: getUsersCount
   x-acl:
     - analytics
-  summary: Retrieve number of users.
+  summary: Retrieve number of users
   description: |
     Retrieves the number of unique users within a time range, including a daily breakdown.
 

specs/analytics/paths/status/getStatus.yml

@@ -4,7 +4,7 @@ get:
   operationId: getStatus
   x-acl:
     - analytics
-  summary: Retrieve update status.
+  summary: Retrieve update status
   description: |
     Retrieves the time when the Analytics data for the specified index was last updated.
 

specs/common/schemas/CustomRequest.yml

@@ -1,5 +1,5 @@
 customRequest:
-  summary: Send requests to the Algolia REST API.
+  summary: Send requests to the Algolia REST API
   description: This method allow you to send requests to the Algolia REST API.
   parameters:
     - $ref: '#/PathInPath'