@graphql-eslint/eslint-plugin 2.4.1 → 2.5.0-alpha-14532ce.0

package/README.md

@@ -6,18 +6,18 @@ This project integrates GraphQL and ESLint, for a better developer experience.
 
 [![npm version](https://badge.fury.io/js/%40graphql-eslint%2Feslint-plugin.svg)](https://badge.fury.io/js/%40graphql-eslint%2Feslint-plugin)
 
-> Created and maintained by [The Guild](http://the-guild.dev/)
+> Created and maintained by [The Guild](http://the-guild.dev)
 
 ## Key Features
 
-- 🚀 Integrates with ESLint core (as a ESTree parser).
-- 🚀 Works on `.graphql` files, `gql` usages and `/* GraphQL */` magic comments.
-- 🚀 Lints both GraphQL schema and GraphQL operations.
+- 🚀 Integrates with ESLint core (as a ESTree parser)
+- 🚀 Works on `.graphql` files, `gql` usages and `/* GraphQL */` magic comments
+- 🚀 Lints both GraphQL schema and GraphQL operations
 - 🚀 Extended type info for more advanced usages
-- 🚀 Supports ESLint directives (for example: `disable-next-line`)
-- 🚀 Easily extendable - supports custom rules based on GraphQL's AST and ESLint API.
-- 🚀 Validates, lints, prettifies and checks for best practices across GraphQL schema and GraphQL operations.
-- 🚀 Integrates with [`graphql-config`](https://graphql-config.com/)
+- 🚀 Supports ESLint directives (for example: `eslint-disable-next-line`)
+- 🚀 Easily extendable - supports custom rules based on GraphQL's AST and ESLint API
+- 🚀 Validates, lints, prettifies and checks for best practices across GraphQL schema and GraphQL operations
+- 🚀 Integrates with [`graphql-config`](https://graphql-config.com)
 - 🚀 Integrates and visualizes lint issues in popular IDEs (VSCode / WebStorm)
 
 > Special thanks to [ilyavolodin](https://github.com/ilyavolodin) for his work on a similar project!
@@ -42,11 +42,13 @@ Or, with NPM:
 npm install --save-dev @graphql-eslint/eslint-plugin
 ```
 
-> Also, make sure you have `graphql` dependency in your project.
+> Make sure you have `graphql` dependency in your project.
 
 ### Configuration
 
-To get started, create an override configuration for your ESLint, while applying it to `.graphql` files (do that even if you are declaring your operations in code files):
+To get started, define an override in your ESLint config to apply this plugin to `.graphql` files. Add the [rules](docs/README.md) you want applied.
+
+> 🚨 Important! This step is necessary even if you are declaring operations and/or schema in code files.
 
 ```json
 {
@@ -56,74 +58,90 @@ To get started, create an override configuration for your ESLint, while applying
       "parser": "@graphql-eslint/eslint-plugin",
       "plugins": ["@graphql-eslint"],
       "rules": {
-        ...
+        "@graphql-eslint/known-type-names": "error"
       }
     }
   ]
 }
 ```
 
-If you are using code files to store your GraphQL schema or your GraphQL operations, you can extend the behaviour of ESLint and extract those, by adding **an additional `override`** that does that extraction processes:
+If your GraphQL definitions are defined only in `.graphql` files, and you're only using rules that apply to individual files, you should be good to go 👍. If you would like use a remote schema or use rules that apply across the entire collection of definitions at once, see [here](#using-a-remote-schema-or-rules-with-constraints-that-span-the-entire-schema).
 
-```json
+#### Tell ESLint to apply this plugin to GraphQL definitions defined in code files
+
+If you are defining GraphQL schema or GraphQL operations in code files, you'll want to define an additional override to extend the functionality of this plugin to the schema and operations in those files.
+
+```diff
 {
   "overrides": [
-    {
-      "files": ["*.tsx", "*.ts", "*.jsx", "*.js"],
-      "processor": "@graphql-eslint/graphql"
-    },
++   {
++     "files": ["*.js"],
++     "processor": "@graphql-eslint/graphql"
++   },
     {
       "files": ["*.graphql"],
       "parser": "@graphql-eslint/eslint-plugin",
       "plugins": ["@graphql-eslint"],
       "rules": {
-        ...
+        "@graphql-eslint/known-type-names": "error"
       }
     }
   ]
 }
 ```
 
-#### Extended linting rules with GraphQL Schema
+Under the hood, specifying the `@graphql-eslint/graphql` processor for code files will cause `graphql-eslint/graphql` to extract the schema and operation definitions from these files into virtual GraphQL documents with `.graphql` extensions. This will allow the overrides you've defined for `.graphql` files, via `"files": ["*.graphql"]`, to get applied to the definitions defined in your code files.
 
-If you are using [`graphql-config`](https://graphql-config.com/) - you are good to go. This package integrates with it automatically, and will use it to load your schema!
+#### Using a remote schema or rules with constraints that span the entire schema
 
-Linting process can be enriched and extended with GraphQL type information, if you are able to provide your GraphQL schema.
+Some rules require an understanding of the entire schema at once. For example, [no-unreachable-types](https://github.com/dotansimha/graphql-eslint/blob/master/docs/rules/no-unreachable-types.md#no-unreachable-types) checks that all types are reachable by root-level fields.
 
-The parser allow you to specify a json file / graphql files(s) / url / raw string to locate your schema (We are using `graphql-tools` to do that). Just add `parserOptions.schema` to your configuration file:
+To use these rules, you'll need to tell ESLint how to identify the entire set of schema definitions.
 
-```json
+If you are using [`graphql-config`](https://graphql-config.com), you are good to go. `graphql-eslint` integrates with it automatically and will use it to load your schema!
+
+Alternatively, you can define `parserOptions.schema` in the `*.graphql` override in your ESLint config.
+
+The parser allows you to specify a json file / graphql files(s) / url / raw string to locate your schema (We are using `graphql-tools` to do that). Just add `parserOptions.schema` to your configuration file:
+
+```diff
 {
   "files": ["*.graphql"],
   "parser": "@graphql-eslint/eslint-plugin",
   "plugins": ["@graphql-eslint"],
-  "parserOptions": {
-    "schema": "./schema.graphql"
-  }
+  "rules": {
+    "@graphql-eslint/no-unreachable-types": "error"
+  },
++ "parserOptions": {
++   "schema": "./schema.graphql"
++ }
 }
 ```
 
-> You can find a complete [documentation of the `parserOptions` here](./docs/parser-options.md)
+> You can find a complete [documentation of the `parserOptions` here](docs/parser-options.md).
 
-> Some rules requires type information to operate, it's marked in the docs of each plugin!
+> Some rules require type information to operate, it's marked in the docs for each rule!
 
 #### Extended linting rules with siblings operations
 
 While implementing this tool, we had to find solutions for a better integration of the GraphQL ecosystem and ESLint core.
 
-GraphQL operations can be distributed across many files, while ESLint operates on one file at a time. If you are using GraphQL fragments in separate files, some rules might yield incorrect results, due the the missing information.
+GraphQL operations can be distributed across many files, while ESLint operates on one file at a time. If you are using GraphQL fragments in separate files, some rules might yield incorrect results, due the missing information.
 
 To workaround that, we allow you to provide additional information on your GraphQL operations, making it available for rules while doing the actual linting.
 
-To provide that, we are using `@graphql-tools` loaders to load your sibling operations and fragments, just specify a glob expression(s) that points to your code/.graphql files:
+To provide that, we are using `graphql-tools` loaders to load your sibling operations and fragments, just specify a glob expression(s) that points to your code/`.graphql` files:
 
-```json
+```diff
 {
   "files": ["*.graphql"],
   "parser": "@graphql-eslint/eslint-plugin",
   "plugins": ["@graphql-eslint"],
+  "rules": {
+    "@graphql-eslint/unique-operation-name": "error"
+  },
   "parserOptions": {
-    "operations": ["./src/**/*.graphql"],
++   "operations": "./src/**/*.graphql",
     "schema": "./schema.graphql"
   }
 }
@@ -131,13 +149,13 @@ To provide that, we are using `@graphql-tools` loaders to load your sibling oper
 
 ### VSCode Integration
 
-By default, [ESLint VSCode plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) will not lint files with extensions other then js, jsx, ts, tsx.
+By default, [ESLint VSCode plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) will not lint files with extensions other than `js`, `jsx`, `ts` and `tsx`.
 
 In order to enable it processing other extensions, add the following section in `settings.json` or workspace configuration.
 
 ```json
 {
-  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "graphql"],
+  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "graphql"]
 }
 ```
 
@@ -156,13 +174,13 @@ type Query {
 }
 ```
 
-You can also specify specific rules to disable, apply it over the entire file, `next-line` or (current) `line`.
+You can also specify specific rules to disable, apply it over the entire file, `eslint-disable-next-line` or current `eslint-disable-line`.
 
 You can find a list of [ESLint directives here](https://eslint.org/docs/2.13.1/user-guide/configuring#disabling-rules-with-inline-comments).
 
 ## Available Rules
 
-You can find a complete list of [all available rules here](./docs/README.md)
+You can find a complete list of [all available rules here](docs/README.md).
 
 ## Available Configs
 
@@ -177,19 +195,13 @@ Enable it in your `.eslintrc` file with the `extends` option.
   "overrides": [
     {
       "files": ["*.js"],
-      "processor": "@graphql-eslint/graphql",
-      "rules": {
-        // your rules for JavaScript files
-      }
+      "processor": "@graphql-eslint/graphql"
     },
     {
       "files": ["*.graphql"],
 -     "parser": "@graphql-eslint/eslint-plugin",
 -     "plugins": ["@graphql-eslint"],
-+     "extends": "plugin:@graphql-eslint/recommended", // or plugin:@graphql-eslint/all
-      "rules": {
-        // your rules for GraphQL files
-      }
++     "extends": "plugin:@graphql-eslint/recommended" // or plugin:@graphql-eslint/all
     }
   ]
 }
@@ -197,26 +209,23 @@ Enable it in your `.eslintrc` file with the `extends` option.
 
 ### `prettier` rule
 
-The original `prettier` rule has been removed because `eslint-plugin-prettier` supports `.graphql` files well actually.
-
-All you need to do is like the following for now:
+`eslint-plugin-prettier` supports `.graphql` files. You need to do the following:
 
 ```js
-// .eslintrc.js
 module.exports = {
   overrides: [
     {
       files: ['*.js'],
       processor: '@graphql-eslint/graphql',
-      extends: ['plugin:prettier/recommended'],
+      extends: ['plugin:prettier/recommended']
     },
     {
       files: ['*.graphql'],
       parser: '@graphql-eslint/eslint-plugin',
       plugins: ['@graphql-eslint'],
       rules: {
-        'prettier/prettier': 'error',
-      },
+        'prettier/prettier': 'error'
+      }
     },
     // the following is required for `eslint-plugin-prettier@<=3.4.0` temporarily
     // after https://github.com/prettier/eslint-plugin-prettier/pull/415
@@ -224,22 +233,22 @@ module.exports = {
     {
       files: ['*.js/*.graphql'],
       rules: {
-        'prettier/prettier': 'off',
-      },
-    },
-  ],
-};
+        'prettier/prettier': 'off'
+      }
+    }
+  ]
+}
 ```
 
 You can take [`examples/prettier`](examples/prettier/.eslintrc.js) as example.
 
-It could be better to remove the unnecessary `*.js/*.graphql` overrides setting if <https://github.com/prettier/eslint-plugin-prettier/pull/415> will be merged and released.
+It could be better to remove the unnecessary `*.js/*.graphql` override setting if <https://github.com/prettier/eslint-plugin-prettier/pull/415> will be merged and released.
 
 Please help to vote up if you want to speed up the progress.
 
 ## Further Reading
 
-If you wish to learn more about this project, how the parser works, how to add custom rules and more, [please refer to the docs directory](./docs/README.md))
+If you wish to learn more about this project, how the parser works, how to add custom rules and more, [please refer to the docs directory](docs/README.md).
 
 ## Contributions
 
@@ -249,8 +258,8 @@ And if this is your first time contributing to this project, please do read our
 
 ### Code of Conduct
 
-Help us keep GraphQL ESLint open and inclusive. Please read and follow our [Code of Conduct](https://github.com/the-guild-org/Stack/blob/master/CODE_OF_CONDUCT.md) as adopted from [Contributor Covenant](https://www.contributor-covenant.org/)
+Help us keep GraphQL ESLint open and inclusive. Please read and follow our [Code of Conduct](https://github.com/the-guild-org/Stack/blob/master/CODE_OF_CONDUCT.md) as adopted from [Contributor Covenant](https://contributor-covenant.org).
 
 ## License
 
-Released under the [MIT license](./LICENSE).
+Released under the [MIT license](LICENSE).

package/docs/custom-rules.md

@@ -17,22 +17,22 @@ The `graphql-eslint` comes with a TypeScript wrapper for ESLint rules, and provi
 Here's an example for a simple rule that reports on anonymous GraphQL operations:
 
 ```ts
-import { GraphQLESLintRule } from '@graphql-eslint/eslint-plugin';
+import { GraphQLESLintRule } from '@graphql-eslint/eslint-plugin'
 
 const rule: GraphQLESLintRule = {
   create(context) {
     return {
       OperationDefinition(node) {
-        if (node && (!node.name || node.name.value === '')) {
+        if (!node.name || !node.name.value) {
           context.report({
-            node: node,
-            message: `Oops, name is required!`,
-          });
+            node,
+            message: 'Oops, name is required!'
+          })
         }
-      },
-    };
-  },
-};
+      }
+    }
+  }
+}
 ```
 
 So what happens here?
@@ -58,23 +58,23 @@ This is useful if you wish to use other GraphQL tools that works with the origin
 Here's an example for using original `graphql-js` validate method to validate `OperationDefinition`:
 
 ```ts
-import { validate } from 'graphql';
-import { requireGraphQLSchemaFromContext } from '@graphql-eslint/eslint-plugin';
+import { validate } from 'graphql'
+import { requireGraphQLSchemaFromContext } from '@graphql-eslint/eslint-plugin'
 
 export const rule = {
   create(context) {
     return {
       OperationDefinition(node) {
-        const schema = requireGraphQLSchemaFromContext(context);
+        const schema = requireGraphQLSchemaFromContext(context)
 
         validate(context, schema, {
           kind: Kind.DOCUMENT,
-          definitions: [node.rawNode()],
-        });
-      },
-    };
-  },
-};
+          definitions: [node.rawNode()]
+        })
+      }
+    }
+  }
+}
 ```
 
 ## `TypeInfo` / `GraphQLSchema`
@@ -89,7 +89,7 @@ If you provide GraphQL schema in your ESLint configuration, it will get loaded a
 To mark your ESLint rules as a rule that needs access to GraphQL schema, start by running `requireGraphQLSchemaFromContext` from the plugin package, it will make sure to return a schema, or throw an error for the user about the missing schema.
 
 ```ts
-const schema = requireGraphQLSchemaFromContext(context);
+const schema = requireGraphQLSchemaFromContext(context)
 ```
 
 #### Accessing TypeInfo
@@ -100,23 +100,23 @@ If your plugin requires `typeInfo` in order to operate and run, make sure to cal
 `typeInfo` is provided on every node, based on the type of that node, for example, to access the `GraphQLOutputType` while you are visiting a `SelectionSet` node, you can do:
 
 ```ts
-import { requireGraphQLSchemaFromContext } from '@graphql-eslint/eslint-plugin';
+import { requireGraphQLSchemaFromContext } from '@graphql-eslint/eslint-plugin'
 
 export const rule = {
   create(context) {
-    requireGraphQLSchemaFromContext(context);
+    requireGraphQLSchemaFromContext(context)
 
     return {
       SelectionSet(node) {
-        const typeInfo = node.typeInfo();
+        const typeInfo = node.typeInfo()
 
         if (typeInfo && typeInfo.gqlType) {
-          console.log(`The GraphQLOutputType is: ${typeInfo.gqlType}`);
+          console.log(`The GraphQLOutputType is: ${typeInfo.gqlType}`)
         }
-      },
-    };
-  },
-};
+      }
+    }
+  }
+}
 ```
 
 The structure of the return value of `.typeInfo()` is [defined here](https://github.com/dotansimha/graphql-eslint/blob/master/packages/plugin/src/estree-parser/converter.ts#L38-L46). So based on the `node` you are using, you'll get a different values on `.typeInfo()` result.
@@ -128,21 +128,21 @@ To test your rules, you can either use the wrapped `GraphQLRuleTester` from this
 The wrapped `GraphQLRuleTester` provides built-in configured parser, and a schema loader, if you need to test your rule with a loaded schema.
 
 ```ts
-import { GraphQLRuleTester } from '@graphql-eslint/eslint-plugin';
-import { rule } from './my-rule';
+import { GraphQLRuleTester } from '@graphql-eslint/eslint-plugin'
+import { rule } from './my-rule'
 
-const ruleTester = new GraphQLRuleTester();
+const ruleTester = new GraphQLRuleTester()
 
 ruleTester.runGraphQLTests('my-rule', rule, {
   valid: [
     {
-      code: `query something { foo }`,
-    },
+      code: 'query something { foo }'
+    }
   ],
   invalid: [
     {
-      code: `query invalid { foo }`,
-    },
-  ],
-});
+      code: 'query invalid { foo }'
+    }
+  ]
+})
 ```

package/index.js

@@ -3634,7 +3634,12 @@ function getReachableTypes(schema) {
         Directive: collect,
         NamedType: collect,
     };
-    for (const type of [schema.getQueryType(), schema.getMutationType(), schema.getSubscriptionType()]) {
+    for (const type of [
+        schema,
+        schema.getQueryType(),
+        schema.getMutationType(),
+        schema.getSubscriptionType(),
+    ]) {
         if (type) {
             graphql.visit(type.astNode, visitor);
         }

package/index.mjs

@@ -3628,7 +3628,12 @@ function getReachableTypes(schema) {
         Directive: collect,
         NamedType: collect,
     };
-    for (const type of [schema.getQueryType(), schema.getMutationType(), schema.getSubscriptionType()]) {
+    for (const type of [
+        schema,
+        schema.getQueryType(),
+        schema.getMutationType(),
+        schema.getSubscriptionType(),
+    ]) {
         if (type) {
             visit(type.astNode, visitor);
         }

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@graphql-eslint/eslint-plugin",
-  "version": "2.4.1",
+  "version": "2.5.0-alpha-14532ce.0",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {
-    "@graphql-tools/code-file-loader": "^7.0.2",
-    "@graphql-tools/graphql-tag-pluck": "^7.0.2",
-    "@graphql-tools/import": "^6.3.1",
-    "@graphql-tools/utils": "^8.0.2",
-    "graphql-config": "^4.0.1",
+    "@babel/code-frame": "7.16.0",
+    "@graphql-tools/code-file-loader": "7.2.2",
+    "@graphql-tools/graphql-tag-pluck": "7.1.3",
+    "@graphql-tools/import": "6.6.1",
+    "@graphql-tools/utils": "8.5.3",
+    "graphql-config": "4.1.0",
     "graphql-depth-limit": "1.1.0",
-    "lodash.lowercase": "^4.3.0"
+    "lodash.lowercase": "4.3.0"
   },
   "repository": "https://github.com/dotansimha/graphql-eslint",
   "author": "Dotan Simha <dotansimha@gmail.com>",