feat: add new option OperationDefinition in require-description rule (#912)

dimaMachina · web-flow · commit 0da135fdedf1 · 2022-01-24T14:27:01.000+01:00
* feat: add new option `OperationDefinition` in `require-description` rule

* docs: note about comment syntax instead description syntax

* fix non-breaking space
diff --git a/.changeset/dull-geckos-tickle.md b/.changeset/dull-geckos-tickle.md
@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': minor
+---
+
+feat: add new option `OperationDefinition` in `require-description` rule
diff --git a/docs/README.md b/docs/README.md
@@ -44,7 +44,7 @@ Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs
 [provided-required-arguments](rules/provided-required-arguments.md)|A field or directive is only valid if all required (non-null without a default value) field arguments have been provided.|![recommended][]|🔮
 [require-deprecation-date](rules/require-deprecation-date.md)|Require deletion date on `@deprecated` directive. Suggest removing deprecated things after deprecated date.|![all][]|🚀
 [require-deprecation-reason](rules/require-deprecation-reason.md)|Require all deprecation directives to specify a reason.|![recommended][]|🚀
-[require-description](rules/require-description.md)|Enforce descriptions in your type definitions.|![recommended][]|🚀
+[require-description](rules/require-description.md)|Enforce descriptions in type definitions and operations.|![recommended][]|🚀
 [require-field-of-type-query-in-mutation-result](rules/require-field-of-type-query-in-mutation-result.md)|Allow the client in one round-trip not only to call mutation but also to get a wagon of data to update their application.|![all][]|🚀
 [require-id-when-available](rules/require-id-when-available.md)|Enforce selecting specific fields when they are available on the GraphQL type.|![recommended][]|🚀
 [scalar-leafs](rules/scalar-leafs.md)|A GraphQL document is valid only if all leaf fields (fields without sub selections) are of scalar or enum types.|![recommended][]|🔮
diff --git a/docs/rules/require-description.md b/docs/rules/require-description.md
@@ -7,7 +7,7 @@
 - Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
 - Requires GraphQL Operations: `false` [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
 
-Enforce descriptions in your type definitions.
+Enforce descriptions in type definitions and operations.
 
 ## Usage Examples
 
@@ -37,6 +37,17 @@ type someTypeName {
 }
 ```
 
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-description: ['error', { OperationDefinition: true }]
+
+# Create a new user
+mutation createUser {
+  # ...
+}
+```
+
 ## Config Schema
 
 The schema defines the following properties:
@@ -84,6 +95,12 @@ Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October
 
 Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#ObjectTypeDefinition).
 
+### `OperationDefinition` (boolean)
+
+Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#OperationDefinition).
+
+> You must use only comment syntax `#` and not description syntax `"""` or `"`.
+
 ### `ScalarTypeDefinition` (boolean)
 
 Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#ScalarTypeDefinition).
diff --git a/packages/plugin/src/rules/require-description.ts b/packages/plugin/src/rules/require-description.ts
@@ -1,22 +1,23 @@
-import { ASTKindToNode, Kind } from 'graphql';
+import { ASTKindToNode, Kind, TokenKind } from 'graphql';
 import { GraphQLESLintRule, ValueOf } from '../types';
-import { TYPES_KINDS, getLocation } from '../utils';
+import { getLocation, TYPES_KINDS } from '../utils';
 import { GraphQLESTreeNode } from '../estree-parser/estree-ast';
 
-const REQUIRE_DESCRIPTION_ERROR = 'REQUIRE_DESCRIPTION_ERROR';
+const RULE_ID = 'require-description';
 
 const ALLOWED_KINDS = [
   ...TYPES_KINDS,
   Kind.FIELD_DEFINITION,
   Kind.INPUT_VALUE_DEFINITION,
   Kind.ENUM_VALUE_DEFINITION,
   Kind.DIRECTIVE_DEFINITION,
+  Kind.OPERATION_DEFINITION,
 ] as const;
 
 type AllowedKind = typeof ALLOWED_KINDS[number];
 type AllowedKindToNode = Pick<ASTKindToNode, AllowedKind>;
 
-type RequireDescriptionRuleConfig = {
+export type RequireDescriptionRuleConfig = {
   types?: boolean;
 } & {
   [key in AllowedKind]?: boolean;
@@ -26,8 +27,8 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
   meta: {
     docs: {
       category: 'Schema',
-      description: 'Enforce descriptions in your type definitions.',
-      url: 'https://github.com/dotansimha/graphql-eslint/blob/master/docs/rules/require-description.md',
+      description: 'Enforce descriptions in type definitions and operations.',
+      url: `https://github.com/dotansimha/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
       examples: [
         {
           title: 'Incorrect',
@@ -53,6 +54,16 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
             }
           `,
         },
+        {
+          title: 'Correct',
+          usage: [{ OperationDefinition: true }],
+          code: /* GraphQL */ `
+            # Create a new user
+            mutation createUser {
+              # ...
+            }
+          `,
+        },
       ],
       configOptions: [
         {
@@ -64,7 +75,7 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
     },
     type: 'suggestion',
     messages: {
-      [REQUIRE_DESCRIPTION_ERROR]: 'Description is required for nodes of type "{{ nodeType }}"',
+      [RULE_ID]: 'Description is required for nodes of type "{{ nodeType }}"',
     },
     schema: {
       type: 'array',
@@ -80,20 +91,20 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
             description: `Includes:\n\n${TYPES_KINDS.map(kind => `- \`${kind}\``).join('\n')}`,
           },
           ...Object.fromEntries(
-            [...ALLOWED_KINDS].sort().map(kind => [
-              kind,
-              {
-                type: 'boolean',
-                description: `Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#${kind}).`,
-              },
-            ])
+            [...ALLOWED_KINDS].sort().map(kind => {
+              let description = `Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#${kind}).`;
+              if (kind === Kind.OPERATION_DEFINITION) {
+                description += '\n\n> You must use only comment syntax `#` and not description syntax `"""` or `"`.';
+              }
+              return [kind, { type: 'boolean', description }];
+            })
           ),
         },
       },
     },
   },
   create(context) {
-    const { types, ...restOptions } = context.options[0];
+    const { types, ...restOptions } = context.options[0] || {};
 
     const kinds: Set<string> = new Set(types ? TYPES_KINDS : []);
     for (const [kind, isEnabled] of Object.entries(restOptions)) {
@@ -108,11 +119,26 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
 
     return {
       [selector](node: GraphQLESTreeNode<ValueOf<AllowedKindToNode>>) {
-        const description = node.description?.value || '';
-        if (description.trim().length === 0) {
+        let description = '';
+        const isOperation = node.kind === Kind.OPERATION_DEFINITION;
+        if (isOperation) {
+          const rawNode = node.rawNode();
+          const { prev, line } = rawNode.loc.startToken;
+          if (prev.kind === TokenKind.COMMENT) {
+            const value = prev.value.trim();
+            const linesBefore = line - prev.line;
+            if (!value.startsWith('eslint') && linesBefore === 1) {
+              description = value;
+            }
+          }
+        } else {
+          description = node.description?.value.trim() || '';
+        }
+
+        if (description.length === 0) {
           context.report({
-            loc: getLocation(node.name.loc, node.name.value),
-            messageId: REQUIRE_DESCRIPTION_ERROR,
+            loc: isOperation ? getLocation(node.loc, node.operation) : getLocation(node.name.loc, node.name.value),
+            messageId: RULE_ID,
             data: {
               nodeType: node.kind,
             },
diff --git a/packages/plugin/tests/__snapshots__/require-description.spec.ts.snap b/packages/plugin/tests/__snapshots__/require-description.spec.ts.snap
@@ -157,3 +157,50 @@ exports[` 12`] = `
   5 |         }
   6 |       
 `;
+
+exports[` 13`] = `
+  1 |
+  2 |         # linesBefore !== 1
+  3 |
+> 4 |         query {
+    |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+  5 |           foo
+  6 |         }
+  7 |       
+`;
+
+exports[` 14`] = `
+> 1 | mutation { test }
+    | ^^^^^^^^ Description is required for nodes of type "OperationDefinition"
+`;
+
+exports[` 15`] = `
+> 1 | subscription { test }
+    | ^^^^^^^^^^^^ Description is required for nodes of type "OperationDefinition"
+`;
+
+exports[` 16`] = `
+  1 |
+  2 |         # eslint-disable-next-line semi
+> 3 |         query {
+    |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+  4 |           foo
+  5 |         }
+  6 |       
+`;
+
+exports[` 17`] = `
+   1 |
+   2 |         # BAD
+   3 |         fragment UserFields on User {
+   4 |           id
+   5 |         }
+   6 |
+>  7 |         query {
+     |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+   8 |           user {
+   9 |             ...UserFields
+  10 |           }
+  11 |         }
+  12 |       
+`;
diff --git a/packages/plugin/tests/require-description.spec.ts b/packages/plugin/tests/require-description.spec.ts
@@ -1,9 +1,12 @@
 import { GraphQLRuleTester } from '../src';
-import rule from '../src/rules/require-description';
+import rule, { RequireDescriptionRuleConfig } from '../src/rules/require-description';
 
 const ruleTester = new GraphQLRuleTester();
 
-ruleTester.runGraphQLTests('require-description', rule, {
+const ERROR = { message: 'Description is required for nodes of type "OperationDefinition"' };
+const OPERATION = { OperationDefinition: true };
+
+ruleTester.runGraphQLTests<[RequireDescriptionRuleConfig]>('require-description', rule, {
   valid: [
     {
       code: /* GraphQL */ `
@@ -54,6 +57,24 @@ ruleTester.runGraphQLTests('require-description', rule, {
       `,
       options: [{ types: true, FieldDefinition: true }],
     },
+    {
+      code: /* GraphQL */ `
+        # OK
+        query {
+          test
+        }
+      `,
+      options: [OPERATION],
+    },
+    {
+      code: /* GraphQL */ `
+        # ignore fragments
+        fragment UserFields on User {
+          id
+        }
+      `,
+      options: [OPERATION],
+    },
   ],
   invalid: [
     {
@@ -103,5 +124,57 @@ ruleTester.runGraphQLTests('require-description', rule, {
       ],
       errors: 2,
     },
+    {
+      name: 'should report because of linesBefore !== 1',
+      code: /* GraphQL */ `
+        # linesBefore !== 1
+
+        query {
+          foo
+        }
+      `,
+      options: [OPERATION],
+      errors: [ERROR],
+    },
+    {
+      name: 'should validate mutation',
+      code: 'mutation { test }',
+      options: [OPERATION],
+      errors: [ERROR],
+    },
+    {
+      name: 'should validate subscription',
+      code: 'subscription { test }',
+      options: [OPERATION],
+      errors: [ERROR],
+    },
+    {
+      name: 'should report because skips previous comment that starts with `eslint`',
+      code: /* GraphQL */ `
+        # eslint-disable-next-line semi
+        query {
+          foo
+        }
+      `,
+      options: [OPERATION],
+      errors: [ERROR],
+    },
+    {
+      name: 'should ignore comments before fragment definition',
+      code: /* GraphQL */ `
+        # BAD
+        fragment UserFields on User {
+          id
+        }
+
+        query {
+          user {
+            ...UserFields
+          }
+        }
+      `,
+      options: [OPERATION],
+      errors: [ERROR],
+    },
   ],
 });
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
@@ -7,6 +7,7 @@ import { rules } from '../packages/plugin/src';
 import { DISABLED_RULES_FOR_ALL_CONFIG } from './constants';
 
 const BR = '';
+const NBSP = '&nbsp;';
 const DOCS_PATH = resolve(process.cwd(), 'docs');
 
 enum Icon {
@@ -158,10 +159,10 @@ function generateDocs(): void {
       '<!-- 🚨 IMPORTANT! Do not manually modify this table. Run: `yarn generate:docs` -->',
       printMarkdownTable(
         [
-          `Name${'&nbsp;'.repeat(20)}`,
+          `Name${NBSP.repeat(20)}`,
           'Description',
-          { name: `${'&nbsp;'.repeat(4)}Config${'&nbsp;'.repeat(4)}`, align: 'center' },
-          { name: `${Icon.GRAPHQL_ESLINT}&nbsp;/&nbsp;${Icon.GRAPHQL_JS}`, align: 'center' },
+          { name: `${NBSP.repeat(4)}Config${NBSP.repeat(4)}`, align: 'center' },
+          { name: `${Icon.GRAPHQL_ESLINT}${NBSP}/${NBSP}${Icon.GRAPHQL_JS}`, align: 'center' },
         ],
         sortedRules
       ),

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@graphql-eslint/eslint-plugin': minor
 +---
++
 +feat: add new option `OperationDefinition` in `require-description` rule