chore: clarify report message for require-description rule (#928)

dimaMachina · web-flow · commit af22d9daa25d · 2022-02-01T12:26:00.000+02:00
diff --git a/.changeset/fuzzy-chairs-tease.md b/.changeset/fuzzy-chairs-tease.md
@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': patch
+---
+
+chore: clarify report message for `require-description` rule
diff --git a/packages/plugin/src/rules/require-description.ts b/packages/plugin/src/rules/require-description.ts
@@ -1,4 +1,4 @@
-import { ASTKindToNode, Kind, TokenKind } from 'graphql';
+import { ASTKindToNode, Kind, NameNode, TokenKind } from 'graphql';
 import { GraphQLESLintRule, ValueOf } from '../types';
 import { getLocation, TYPES_KINDS } from '../utils';
 import { GraphQLESTreeNode } from '../estree-parser/estree-ast';
@@ -7,22 +7,53 @@ const RULE_ID = 'require-description';
 
 const ALLOWED_KINDS = [
   ...TYPES_KINDS,
+  Kind.DIRECTIVE_DEFINITION,
   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 SelectorNode = GraphQLESTreeNode<ValueOf<AllowedKindToNode>> & { parent: { name: NameNode } };
 
 export type RequireDescriptionRuleConfig = {
   types?: boolean;
 } & {
   [key in AllowedKind]?: boolean;
 };
 
+function getNodeName(node: SelectorNode) {
+  const DisplayNodeNameMap = {
+    [Kind.OBJECT_TYPE_DEFINITION]: 'type',
+    [Kind.INTERFACE_TYPE_DEFINITION]: 'interface',
+    [Kind.ENUM_TYPE_DEFINITION]: 'enum',
+    [Kind.SCALAR_TYPE_DEFINITION]: 'scalar',
+    [Kind.INPUT_OBJECT_TYPE_DEFINITION]: 'input',
+    [Kind.UNION_TYPE_DEFINITION]: 'union',
+    [Kind.DIRECTIVE_DEFINITION]: 'directive',
+  } as const;
+
+  switch (node.kind) {
+    case Kind.OBJECT_TYPE_DEFINITION:
+    case Kind.INTERFACE_TYPE_DEFINITION:
+    case Kind.ENUM_TYPE_DEFINITION:
+    case Kind.SCALAR_TYPE_DEFINITION:
+    case Kind.INPUT_OBJECT_TYPE_DEFINITION:
+    case Kind.UNION_TYPE_DEFINITION:
+      return `${DisplayNodeNameMap[node.kind]} ${node.name.value}`;
+    case Kind.DIRECTIVE_DEFINITION:
+      return `${DisplayNodeNameMap[node.kind]} @${node.name.value}`;
+    case Kind.FIELD_DEFINITION:
+    case Kind.INPUT_VALUE_DEFINITION:
+    case Kind.ENUM_VALUE_DEFINITION:
+      return `${node.parent.name.value}.${node.name.value}`;
+    case Kind.OPERATION_DEFINITION:
+      return node.name ? `${node.operation} ${node.name.value}` : node.operation;
+  }
+}
+
 const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
   meta: {
     docs: {
@@ -75,7 +106,7 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
     },
     type: 'suggestion',
     messages: {
-      [RULE_ID]: 'Description is required for nodes of type "{{ nodeType }}"',
+      [RULE_ID]: 'Description is required for `{{ nodeName }}`.',
     },
     schema: {
       type: 'array',
@@ -118,7 +149,7 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
     const selector = [...kinds].join(',');
 
     return {
-      [selector](node: GraphQLESTreeNode<ValueOf<AllowedKindToNode>>) {
+      [selector](node: SelectorNode) {
         let description = '';
         const isOperation = node.kind === Kind.OPERATION_DEFINITION;
         if (isOperation) {
@@ -140,7 +171,7 @@ const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
             loc: isOperation ? getLocation(node.loc, node.operation) : getLocation(node.name.loc, node.name.value),
             messageId: RULE_ID,
             data: {
-              nodeType: node.kind,
+              nodeName: getNodeName(node),
             },
           });
         }
diff --git a/packages/plugin/tests/__snapshots__/examples.spec.ts.snap b/packages/plugin/tests/__snapshots__/examples.spec.ts.snap
@@ -35,15 +35,15 @@ Array [
     filePath: examples/basic/schema.graphql,
     messages: Array [
       Object {
-        message: Description is required for nodes of type "FieldDefinition",
+        message: Description is required for \`Query.user\`.,
         ruleId: @graphql-eslint/require-description,
       },
       Object {
-        message: Description is required for nodes of type "FieldDefinition",
+        message: Description is required for \`User.id\`.,
         ruleId: @graphql-eslint/require-description,
       },
       Object {
-        message: Description is required for nodes of type "FieldDefinition",
+        message: Description is required for \`User.name\`.,
         ruleId: @graphql-eslint/require-description,
       },
     ],
diff --git a/packages/plugin/tests/__snapshots__/require-description.spec.ts.snap b/packages/plugin/tests/__snapshots__/require-description.spec.ts.snap
@@ -1,148 +1,60 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[` 1`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
->  3 |           gt: BSONDecimal
-     |           ^^ Description is required for nodes of type "InputValueDefinition"
-   4 |           gte: BSONDecimal
-   5 |           lt: BSONDecimal
-   6 |           lte: BSONDecimal
-   7 |           ne: BSONDecimal
-   8 |           in: [BSONDecimal]
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | type User { id: ID }
+    |      ^^^^ Description is required for \`type User\`.
 `;
 
 exports[` 2`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
->  4 |           gte: BSONDecimal
-     |           ^^^ Description is required for nodes of type "InputValueDefinition"
-   5 |           lt: BSONDecimal
-   6 |           lte: BSONDecimal
-   7 |           ne: BSONDecimal
-   8 |           in: [BSONDecimal]
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | interface Node { id: ID! }
+    |           ^^^^ Description is required for \`interface Node\`.
 `;
 
 exports[` 3`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
-   4 |           gte: BSONDecimal
->  5 |           lt: BSONDecimal
-     |           ^^ Description is required for nodes of type "InputValueDefinition"
-   6 |           lte: BSONDecimal
-   7 |           ne: BSONDecimal
-   8 |           in: [BSONDecimal]
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | enum Role { ADMIN }
+    |      ^^^^ Description is required for \`enum Role\`.
 `;
 
 exports[` 4`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
-   4 |           gte: BSONDecimal
-   5 |           lt: BSONDecimal
->  6 |           lte: BSONDecimal
-     |           ^^^ Description is required for nodes of type "InputValueDefinition"
-   7 |           ne: BSONDecimal
-   8 |           in: [BSONDecimal]
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | scalar Email
+    |        ^^^^^ Description is required for \`scalar Email\`.
 `;
 
 exports[` 5`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
-   4 |           gte: BSONDecimal
-   5 |           lt: BSONDecimal
-   6 |           lte: BSONDecimal
->  7 |           ne: BSONDecimal
-     |           ^^ Description is required for nodes of type "InputValueDefinition"
-   8 |           in: [BSONDecimal]
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | input CreateUserInput { email: Email! }
+    |       ^^^^^^^^^^^^^^^ Description is required for \`input CreateUserInput\`.
 `;
 
 exports[` 6`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
-   4 |           gte: BSONDecimal
-   5 |           lt: BSONDecimal
-   6 |           lte: BSONDecimal
-   7 |           ne: BSONDecimal
->  8 |           in: [BSONDecimal]
-     |           ^^ Description is required for nodes of type "InputValueDefinition"
-   9 |           nin: [BSONDecimal]
-  10 |         }
-  11 |       
+> 1 | union Media = Book | Movie
+    |       ^^^^^ Description is required for \`union Media\`.
 `;
 
 exports[` 7`] = `
-   1 |
-   2 |         input SalaryDecimalOperatorsFilterUpdateOneUserInput {
-   3 |           gt: BSONDecimal
-   4 |           gte: BSONDecimal
-   5 |           lt: BSONDecimal
-   6 |           lte: BSONDecimal
-   7 |           ne: BSONDecimal
-   8 |           in: [BSONDecimal]
->  9 |           nin: [BSONDecimal]
-     |           ^^^ Description is required for nodes of type "InputValueDefinition"
-  10 |         }
-  11 |       
+> 1 | directive @auth(requires: Role!) on FIELD_DEFINITION
+    |            ^^^^ Description is required for \`directive @auth\`.
 `;
 
 exports[` 8`] = `
-  1 |
-  2 |         enum EnumUserLanguagesSkill {
-> 3 |           basic
-    |           ^^^^^ Description is required for nodes of type "EnumValueDefinition"
-  4 |           fluent
-  5 |           native
-  6 |         }
-  7 |       
+> 1 | type User { email: Email! }
+    |             ^^^^^ Description is required for \`User.email\`.
 `;
 
 exports[` 9`] = `
-  1 |
-  2 |         enum EnumUserLanguagesSkill {
-  3 |           basic
-> 4 |           fluent
-    |           ^^^^^^ Description is required for nodes of type "EnumValueDefinition"
-  5 |           native
-  6 |         }
-  7 |       
+> 1 | input CreateUserInput { email: Email! }
+    |                         ^^^^^ Description is required for \`CreateUserInput.email\`.
 `;
 
 exports[` 10`] = `
-  1 |
-  2 |         enum EnumUserLanguagesSkill {
-  3 |           basic
-  4 |           fluent
-> 5 |           native
-    |           ^^^^^^ Description is required for nodes of type "EnumValueDefinition"
-  6 |         }
-  7 |       
+> 1 | enum Role { ADMIN }
+    |             ^^^^^ Description is required for \`Role.ADMIN\`.
 `;
 
 exports[` 11`] = `
   1 |
   2 |         type CreateOneUserPayload {
 > 3 |           recordId: MongoID
-    |           ^^^^^^^^ Description is required for nodes of type "FieldDefinition"
+    |           ^^^^^^^^ Description is required for \`CreateOneUserPayload.recordId\`.
   4 |           record: User
   5 |         }
   6 |       
@@ -153,7 +65,7 @@ exports[` 12`] = `
   2 |         type CreateOneUserPayload {
   3 |           recordId: MongoID
 > 4 |           record: User
-    |           ^^^^^^ Description is required for nodes of type "FieldDefinition"
+    |           ^^^^^^ Description is required for \`CreateOneUserPayload.record\`.
   5 |         }
   6 |       
 `;
@@ -163,27 +75,27 @@ exports[` 13`] = `
   2 |         # linesBefore !== 1
   3 |
 > 4 |         query {
-    |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+    |         ^^^^^ Description is required for \`query\`.
   5 |           foo
   6 |         }
   7 |       
 `;
 
 exports[` 14`] = `
-> 1 | mutation { test }
-    | ^^^^^^^^ Description is required for nodes of type "OperationDefinition"
+> 1 | mutation createUser { foo }
+    | ^^^^^^^^ Description is required for \`mutation createUser\`.
 `;
 
 exports[` 15`] = `
-> 1 | subscription { test }
-    | ^^^^^^^^^^^^ Description is required for nodes of type "OperationDefinition"
+> 1 | subscription commentAdded { foo }
+    | ^^^^^^^^^^^^ Description is required for \`subscription commentAdded\`.
 `;
 
 exports[` 16`] = `
   1 |
   2 |         # eslint-disable-next-line semi
 > 3 |         query {
-    |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+    |         ^^^^^ Description is required for \`query\`.
   4 |           foo
   5 |         }
   6 |       
@@ -197,7 +109,7 @@ exports[` 17`] = `
    5 |         }
    6 |
 >  7 |         query {
-     |         ^^^^^ Description is required for nodes of type "OperationDefinition"
+     |         ^^^^^ Description is required for \`query\`.
    8 |           user {
    9 |             ...UserFields
   10 |           }
diff --git a/packages/plugin/tests/require-description.spec.ts b/packages/plugin/tests/require-description.spec.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@graphql-eslint/eslint-plugin': patch
 +---
++
 +chore: clarify report message for `require-description` rule