Create new lone-executable-definition rule (#1316)

FloEdelmann · dimaMachina · web-flow · commit 1f21fc8276d4 · 2022-12-20T14:55:11.000+01:00
* Create new `lone-executable-definition` rule

* Generate docs and configs

* Other prettier changes

* Allow ignoring first definition

* refactor

* fix typecheck on GraphQL 15

* add changeset

Co-authored-by: Dimitri POSTOLOV &lt;dmytropostolov@gmail.com&gt;
diff --git a/.changeset/good-baboons-bathe.md b/.changeset/good-baboons-bathe.md
@@ -2,4 +2,5 @@
 '@graphql-eslint/eslint-plugin': minor
 ---
 
-[require-description] add `rootField` option for only field definitions within `Query`, `Mutation`, and `Subscription` root types
+[require-description] add `rootField` option for only field definitions within `Query`, `Mutation`,
+and `Subscription` root types
diff --git a/.changeset/strange-donuts-warn.md b/.changeset/strange-donuts-warn.md
@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': minor
+---
+
+feat: add `lone-executable-definition` to tequire all queries, mutations, subscriptions and fragments to be located in separate files
diff --git a/.gitignore b/.gitignore
@@ -103,6 +103,5 @@ dist
 # TernJS port file
 .tern-port
 
-
 .bob/
 .idea/
diff --git a/.husky/_/husky.sh b/.husky/_/husky.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 if [ -z "$husky_skip_init" ]; then
-  debug () {
+  debug() {
     [ "$HUSKY_DEBUG" = "1" ] && echo "husky (debug) - $1"
   }
 
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-## Available Rules
+# Available Rules
 
 Each rule has emojis denoting:
 
@@ -26,6 +26,7 @@ Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs
 [known-fragment-names](rules/known-fragment-names.md)|A GraphQL document is only valid if all `...Fragment` fragment spreads refer to fragments defined in the same document.|![recommended][]|📦|🔮|
 [known-type-names](rules/known-type-names.md)|A GraphQL document is only valid if referenced types (specifically variable definitions and fragment conditions) are defined by the type schema.|![recommended][]|📄 📦|🔮|💡
 [lone-anonymous-operation](rules/lone-anonymous-operation.md)|A GraphQL document that contains an anonymous operation (the `query` short-hand) is only valid if it contains only that one operation definition.|![recommended][]|📦|🔮|
+[lone-executable-definition](rules/lone-executable-definition.md)|Require all queries, mutations, subscriptions and fragments to be located in separate files.|![all][]|📦|🚀|
 [lone-schema-definition](rules/lone-schema-definition.md)|A GraphQL document is only valid if it contains only one schema definition.|![recommended][]|📄|🔮|
 [match-document-filename](rules/match-document-filename.md)|This rule allows you to enforce that the file name should match the operation name.|![all][]|📦|🚀|
 [naming-convention](rules/naming-convention.md)|Require names to follow specified conventions.|![recommended][]|📄 📦|🚀|💡
diff --git a/docs/rules/lone-executable-definition.md b/docs/rules/lone-executable-definition.md
@@ -0,0 +1,59 @@
+# `lone-executable-definition`
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/lone-executable-definition`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Require all queries, mutations, subscriptions and fragments to be located in separate files.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/lone-executable-definition: 'error'
+
+query Foo {
+  id
+}
+fragment Bar on Baz {
+  id
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/lone-executable-definition: 'error'
+
+query Foo {
+  id
+}
+```
+
+## Config Schema
+
+The schema defines the following properties:
+
+### `ignore` (array)
+
+Allow certain definitions to be placed alongside others.
+
+The elements of the array can contain the following enum values:
+
+- `fragment`
+- `query`
+- `mutation`
+- `subscription`
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/lone-executable-definition.ts)
+- [Test source](../../packages/plugin/tests/lone-executable-definition.spec.ts)
diff --git a/docs/rules/require-description.md b/docs/rules/require-description.md
@@ -82,7 +82,7 @@ Includes:
 
 ### `rootField` (boolean)
 
-Definitions within `Query`, `Mutation`, and `Subscription` root types
+Definitions within `Query`, `Mutation`, and `Subscription` root types.
 
 ### `DirectiveDefinition` (boolean)
 
diff --git a/packages/plugin/src/configs/operations-all.json b/packages/plugin/src/configs/operations-all.json
@@ -9,6 +9,7 @@
         "arguments": ["Field", "Directive"]
       }
     ],
+    "@graphql-eslint/lone-executable-definition": "error",
     "@graphql-eslint/match-document-filename": [
       "error",
       {
diff --git a/packages/plugin/src/rules/index.ts b/packages/plugin/src/rules/index.ts
@@ -6,6 +6,7 @@ import { GRAPHQL_JS_VALIDATIONS } from './graphql-js-validation';
 import { rule as alphabetize } from './alphabetize';
 import { rule as descriptionStyle } from './description-style';
 import { rule as inputName } from './input-name';
+import { rule as loneExecutableDefinition } from './lone-executable-definition';
 import { rule as matchDocumentFilename } from './match-document-filename';
 import { rule as namingConvention } from './naming-convention';
 import { rule as noAnonymousOperations } from './no-anonymous-operations';
@@ -37,6 +38,7 @@ export const rules = {
   alphabetize,
   'description-style': descriptionStyle,
   'input-name': inputName,
+  'lone-executable-definition': loneExecutableDefinition,
   'match-document-filename': matchDocumentFilename,
   'naming-convention': namingConvention,
   'no-anonymous-operations': noAnonymousOperations,
diff --git a/packages/plugin/src/rules/lone-executable-definition.ts b/packages/plugin/src/rules/lone-executable-definition.ts
@@ -0,0 +1,98 @@
+import { GraphQLESLintRule } from '../types';
+import { ExecutableDefinitionNode } from 'graphql';
+import { GraphQLESTreeNode } from '../estree-converter';
+import { ARRAY_DEFAULT_OPTIONS, pascalCase, getLocation } from '../utils';
+
+const RULE_ID = 'lone-executable-definition';
+
+type Definition = 'fragment' | 'query' | 'mutation' | 'subscription';
+
+const types: Definition[] = ['fragment', 'query', 'mutation', 'subscription'];
+
+export interface LoneExecutableDefinitionConfig {
+  ignore?: typeof types;
+}
+
+type DefinitionESTreeNode = GraphQLESTreeNode<ExecutableDefinitionNode>;
+
+export const rule: GraphQLESLintRule<[LoneExecutableDefinitionConfig]> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      category: 'Operations',
+      description:
+        'Require all queries, mutations, subscriptions and fragments to be located in separate files.',
+      url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+      examples: [
+        {
+          title: 'Incorrect',
+          code: /* GraphQL */ `
+            query Foo {
+              id
+            }
+            fragment Bar on Baz {
+              id
+            }
+          `,
+        },
+        {
+          title: 'Correct',
+          code: /* GraphQL */ `
+            query Foo {
+              id
+            }
+          `,
+        },
+      ],
+    },
+    messages: {
+      [RULE_ID]: '{{name}} should be in a separate file.',
+    },
+    schema: {
+      type: 'array',
+      minItems: 0,
+      maxItems: 1,
+      items: {
+        type: 'object',
+        minProperties: 1,
+        additionalProperties: false,
+        properties: {
+          ignore: {
+            ...ARRAY_DEFAULT_OPTIONS,
+            maxItems: 3, // ignore all 4 types is redundant
+            items: {
+              enum: types,
+            },
+            description: 'Allow certain definitions to be placed alongside others.',
+          },
+        },
+      },
+    },
+  },
+  create(context) {
+    const ignore = new Set(context.options[0]?.ignore || []);
+    const definitions: { type: Definition; node: DefinitionESTreeNode }[] = [];
+    return {
+      ':matches(OperationDefinition, FragmentDefinition)'(node: DefinitionESTreeNode) {
+        const type = 'operation' in node ? node.operation : 'fragment';
+        if (!ignore.has(type)) {
+          definitions.push({ type, node });
+        }
+      },
+      'Program:exit'() {
+        for (const { node, type } of definitions.slice(1) /* ignore first definition */) {
+          let name = pascalCase(type);
+          const definitionName = node.name?.value;
+          if (definitionName) {
+            name += ` "${definitionName}"`;
+          }
+          context.report({
+            loc: node.name?.loc || getLocation(node.loc.start, type),
+            messageId: RULE_ID,
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};
diff --git a/packages/plugin/src/rules/require-description.ts b/packages/plugin/src/rules/require-description.ts
@@ -140,7 +140,7 @@ export const rule: GraphQLESLintRule<[RequireDescriptionRuleConfig]> = {
           },
           rootField: {
             type: 'boolean',
-            description: 'Definitions within `Query`, `Mutation`, and `Subscription` root types',
+            description: 'Definitions within `Query`, `Mutation`, and `Subscription` root types.',
           },
           ...Object.fromEntries(
             [...ALLOWED_KINDS].sort().map(kind => {
diff --git a/packages/plugin/src/utils.ts b/packages/plugin/src/utils.ts
@@ -61,7 +61,7 @@ export const TYPES_KINDS = [
 
 export type CaseStyle = 'camelCase' | 'PascalCase' | 'snake_case' | 'UPPER_CASE' | 'kebab-case';
 
-const pascalCase = (str: string): string =>
+export const pascalCase = (str: string): string =>
   lowerCase(str)
     .split(' ')
     .map(word => word.charAt(0).toUpperCase() + word.slice(1))
diff --git a/packages/plugin/tests/__snapshots__/lone-executable-definition.spec.md b/packages/plugin/tests/__snapshots__/lone-executable-definition.spec.md
@@ -0,0 +1,122 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`should allow fragments if they are ignored 1`] = `
+#### ⌨️ Code
+
+       1 |         query Foo {
+       2 |           id
+       3 |         }
+       4 |         fragment Bar on Bar {
+       5 |           id
+       6 |         }
+       7 |         mutation Baz($name: String!) {
+       8 |           createFoo {
+       9 |             name
+      10 |           }
+      11 |         }
+
+#### ⚙️ Options
+
+    {
+      "ignore": [
+        "fragment"
+      ]
+    }
+
+#### ❌ Error
+
+      6 |         }
+    > 7 |         mutation Baz($name: String!) {
+        |                  ^^^ Mutation "Baz" should be in a separate file.
+      8 |           createFoo {
+`;
+
+exports[`should report additional definitions 1`] = `
+#### ⌨️ Code
+
+       1 |         query Valid {
+       2 |           id
+       3 |         }
+       4 |         {
+       5 |           id
+       6 |         }
+       7 |         fragment Bar on Bar {
+       8 |           id
+       9 |         }
+      10 |         mutation ($name: String!) {
+      11 |           createFoo {
+      12 |             name
+      13 |           }
+      14 |         }
+      15 |         mutation Baz($name: String!) {
+      16 |           createFoo {
+      17 |             name
+      18 |           }
+      19 |         }
+      20 |         subscription {
+      21 |           id
+      22 |         }
+      23 |         subscription Sub {
+      24 |           id
+      25 |         }
+
+#### ❌ Error 1/6
+
+      3 |         }
+    > 4 |         {
+        |         ^^^^^ Query should be in a separate file.
+      5 |           id
+
+#### ❌ Error 2/6
+
+      6 |         }
+    > 7 |         fragment Bar on Bar {
+        |                  ^^^ Fragment "Bar" should be in a separate file.
+      8 |           id
+
+#### ❌ Error 3/6
+
+       9 |         }
+    > 10 |         mutation ($name: String!) {
+         |         ^^^^^^^^ Mutation should be in a separate file.
+      11 |           createFoo {
+
+#### ❌ Error 4/6
+
+      14 |         }
+    > 15 |         mutation Baz($name: String!) {
+         |                  ^^^ Mutation "Baz" should be in a separate file.
+      16 |           createFoo {
+
+#### ❌ Error 5/6
+
+      19 |         }
+    > 20 |         subscription {
+         |         ^^^^^^^^^^^^ Subscription should be in a separate file.
+      21 |           id
+
+#### ❌ Error 6/6
+
+      22 |         }
+    > 23 |         subscription Sub {
+         |                      ^^^ Subscription "Sub" should be in a separate file.
+      24 |           id
+`;
+
+exports[`should report definitions after short-hand query 1`] = `
+#### ⌨️ Code
+
+      1 |         {
+      2 |           id
+      3 |         }
+      4 |         fragment Bar on Bar {
+      5 |           id
+      6 |         }
+
+#### ❌ Error
+
+      3 |         }
+    > 4 |         fragment Bar on Bar {
+        |                  ^^^ Fragment "Bar" should be in a separate file.
+      5 |           id
+`;
diff --git a/packages/plugin/tests/lone-executable-definition.spec.ts b/packages/plugin/tests/lone-executable-definition.spec.ts
diff --git a/packages/plugin/tests/no-unreachable-types.spec.ts b/packages/plugin/tests/no-unreachable-types.spec.ts
diff --git a/packages/plugin/tests/possible-type-extension.spec.ts b/packages/plugin/tests/possible-type-extension.spec.ts
diff --git a/packages/plugin/tests/require-field-of-type-query-in-mutation-result.spec.ts b/packages/plugin/tests/require-field-of-type-query-in-mutation-result.spec.ts
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@graphql-eslint/eslint-plugin': minor
 +---
++
 +feat: add `lone-executable-definition` to tequire all queries, mutations, subscriptions and fragments to be located in separate files
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`#!/bin/sh`
`2`	`2`	`if [ -z "$husky_skip_init" ]; then`
`3`		`- debug () {`
	`3`	`+ debug() {`
`4`	`4`	`[ "$HUSKY_DEBUG" = "1" ] && echo "husky (debug) - $1"`
`5`	`5`	`}`
`6`	`6`
Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`"arguments": ["Field", "Directive"]`
`10`	`10`	`}`
`11`	`11`	`],`
	`12`	`+ "@graphql-eslint/lone-executable-definition": "error",`
`12`	`13`	`"@graphql-eslint/match-document-filename": [`
`13`	`14`	`"error",`
`14`	`15`	`{`