@graphql-eslint/eslint-plugin 3.13.1-alpha-20221105230632-80b7067 → 3.13.1

package/README.md

@@ -0,0 +1,266 @@
+This project integrates GraphQL and ESLint, for a better developer experience.
+
+<img height="150" src="./logo.png">
+
+[![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](https://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
+- 🚀 Extended type info for more advanced usages
+- 🚀 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!
+
+<img src="https://thumbs.gfycat.com/ActualTerrificDog-size_restricted.gif" />
+
+## Getting Started
+
+- [Introducing GraphQL-ESLint!](https://the-guild.dev/blog/introducing-graphql-eslint) @ `the-guild.dev`
+
+### Installation
+
+Start by installing the plugin package, which includes everything you need:
+
+```sh
+yarn add -D @graphql-eslint/eslint-plugin
+```
+
+Or, with NPM:
+
+```sh
+npm install --save-dev @graphql-eslint/eslint-plugin
+```
+
+> Make sure you have `graphql` dependency in your project.
+
+## Configuration
+
+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
+{
+  "overrides": [
+    {
+      "files": ["*.graphql"],
+      "parser": "@graphql-eslint/eslint-plugin",
+      "plugins": ["@graphql-eslint"],
+      "rules": {
+        "@graphql-eslint/known-type-names": "error"
+      }
+    }
+  ]
+}
+```
+
+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](#extended-linting-rules-with-graphql-schema).
+
+### 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": ["*.js"],
++     "processor": "@graphql-eslint/graphql"
++   },
+    {
+      "files": ["*.graphql"],
+      "parser": "@graphql-eslint/eslint-plugin",
+      "plugins": ["@graphql-eslint"],
+      "rules": {
+        "@graphql-eslint/known-type-names": "error"
+      }
+    }
+  ]
+}
+```
+
+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.
+
+### Extended linting rules with GraphQL Schema
+
+Some rules require an understanding of the entire schema at once. For example, [no-unreachable-types](https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/no-unreachable-types.md#no-unreachable-types) checks that all types are reachable by root-level fields.
+
+To use these rules, you'll need to tell ESLint how to identify the entire set of schema definitions.
+
+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"],
+  "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).
+
+> 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 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:
+
+```diff
+{
+  "files": ["*.graphql"],
+  "parser": "@graphql-eslint/eslint-plugin",
+  "plugins": ["@graphql-eslint"],
+  "rules": {
+    "@graphql-eslint/unique-operation-name": "error"
+  },
+  "parserOptions": {
++   "operations": "./src/**/*.graphql",
+    "schema": "./schema.graphql"
+  }
+}
+```
+
+### VSCode Integration
+
+Use [ESLint VSCode extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) to integrate ESLint into VSCode.
+
+For syntax highlighting you need a GraphQL extension (which may potentially have its own linting), for example [GraphQL (by GraphQL Foundation)](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql).
+
+### Disabling Rules
+
+The `graphql-eslint` parser looks for GraphQL comments syntax (marked with `#`) and will send it to ESLint as directives. That means, you can use ESLint directives syntax to hint ESLint, just like in any other type of files.
+
+To disable ESLint for a specific line, you can do:
+
+```graphql
+# eslint-disable-next-line
+type Query {
+  foo: String!
+}
+```
+
+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).
+
+### Deprecated Rules
+
+See [docs/deprecated-rules.md](docs/deprecated-rules.md).
+
+## Available Configs
+
+<!-- prettier-ignore-start -->
+|Name|Description|
+|:-:|-|
+|[`schema-recommended`](packages/plugin/src/configs/schema-recommended.json)|enables recommended rules for schema (SDL) development|
+|[`schema-all`](packages/plugin/src/configs/schema-all.json)|enables all rules for schema (SDL) development, except for those that require `parserOptions.operations` option|
+|[`operations-recommended`](packages/plugin/src/configs/operations-recommended.json) |enables recommended rules for consuming GraphQL (operations) development|
+|[`operations-all`](packages/plugin/src/configs/operations-all.json)|enables all rules for consuming GraphQL (operations) development|
+|[`relay`](packages/plugin/src/configs/relay.json)|enables rules from Relay specification for schema (SDL) development|
+<!-- prettier-ignore-end -->
+
+> If you are in a project that develops the GraphQL schema, you'll need `schema` rules.
+
+> If you are in a project that develops GraphQL operations (query/mutation/subscription), you'll need `operations` rules.
+
+> If you are in a monorepo project, you probably need both sets of rules, see [example of configuration](examples/monorepo/.eslintrc.cjs).
+
+### Config usage
+
+For example, to enable the `schema-recommended` config, enable it in your `.eslintrc` file with the `extends` option:
+
+> All configs under the hood set `parser` as `@graphql-eslint/eslint-plugin` and add `@graphql-eslint` to `plugins` array, so you don't need to specify them.
+
+```diff
+{
+  "overrides": [
+    {
+      "files": ["*.js"],
+      "processor": "@graphql-eslint/graphql"
+    },
+    {
+      "files": ["*.graphql"],
+-     "parser": "@graphql-eslint/eslint-plugin",
+-     "plugins": ["@graphql-eslint"],
++     "extends": "plugin:@graphql-eslint/schema-recommended"
+    }
+  ]
+}
+```
+
+### `prettier` rule
+
+`eslint-plugin-prettier` supports `.graphql` files, and `v4.1.0` supports `graphql` blocks even better. You need to do the following:
+
+```js
+module.exports = {
+  overrides: [
+    {
+      files: ['*.js'],
+      processor: '@graphql-eslint/graphql',
+      extends: ['plugin:prettier/recommended']
+    },
+    {
+      files: ['*.graphql'],
+      parser: '@graphql-eslint/eslint-plugin',
+      plugins: ['@graphql-eslint'],
+      rules: {
+        'prettier/prettier': 'error'
+      }
+    }
+  ]
+}
+```
+
+You can take [`examples/prettier`](examples/prettier/.eslintrc.cjs) as example.
+
+## 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 below links:
+
+- [Writing Custom Rules](docs/custom-rules.md)
+- [How the parser works?](docs/parser.md)
+- [`parserOptions`](docs/parser-options.md)
+
+## Contributions
+
+Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!
+
+And if this is your first time contributing to this project, please do read our [Contributor Workflow Guide](https://github.com/the-guild-org/Stack/blob/master/CONTRIBUTING.md) before you get started off.
+
+### 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://contributor-covenant.org).
+
+## License
+
+Released under the [MIT license](LICENSE).

package/docs/README.md

@@ -0,0 +1,76 @@
+## Available Rules
+
+Each rule has emojis denoting:
+
+- 🚀 `graphql-eslint` rule
+- 🔮 `graphql-js` rule
+- 🔧 if some problems reported by the rule are automatically fixable by the `--fix` [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) option
+- 💡 if some problems reported by the rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+
+<!-- 🚨 IMPORTANT! Do not manually modify this table. Run: `yarn generate:docs` -->
+<!-- prettier-ignore-start -->
+Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|Description|&nbsp;&nbsp;&nbsp;&nbsp;Config&nbsp;&nbsp;&nbsp;&nbsp;|🚀&nbsp;/&nbsp;🔮|🔧&nbsp;/&nbsp;💡
+-|-|:-:|:-:|:-:
+[alphabetize](rules/alphabetize.md)|Enforce arrange in alphabetical order for type fields, enum values, input object fields, operation selections and more.|![all][]|🚀|🔧
+[description-style](rules/description-style.md)|Require all comments to follow the same style (either block or inline).|![recommended][]|🚀|💡
+[executable-definitions](rules/executable-definitions.md)|A GraphQL document is only valid for execution if all definitions are either operation or fragment definitions.|![recommended][]|🔮|
+[fields-on-correct-type](rules/fields-on-correct-type.md)|A GraphQL document is only valid if all fields selected are defined by the parent type, or are an allowed meta field such as `__typename`.|![recommended][]|🔮|
+[fragments-on-composite-type](rules/fragments-on-composite-type.md)|Fragments use a type condition to determine if they apply, since fragments can only be spread into a composite type (object, interface, or union), the type condition must also be a composite type.|![recommended][]|🔮|
+[input-name](rules/input-name.md)|Require mutation argument to be always called "input" and input type to be called Mutation name + "Input".|![all][]|🚀|💡
+[known-argument-names](rules/known-argument-names.md)|A GraphQL field is only valid if all supplied arguments are defined by that field.|![recommended][]|🔮|
+[known-directives](rules/known-directives.md)|A GraphQL document is only valid if all `@directive`s are known by the schema and legally positioned.|![recommended][]|🔮|
+[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 is only valid if when it contains an anonymous operation (the query short-hand) that it contains only that one operation definition.|![recommended][]|🔮|
+[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][]|🚀|💡
+[no-anonymous-operations](rules/no-anonymous-operations.md)|Require name for your GraphQL operations. This is useful since most GraphQL client libraries are using the operation name for caching purposes.|![recommended][]|🚀|💡
+[no-case-insensitive-enum-values-duplicates](rules/no-case-insensitive-enum-values-duplicates.md)|Disallow case-insensitive enum values duplicates.|![recommended][]|🚀|💡
+[no-deprecated](rules/no-deprecated.md)|Enforce that deprecated fields or enum values are not in use by operations.|![recommended][]|🚀|💡
+[no-duplicate-fields](rules/no-duplicate-fields.md)|Checks for duplicate fields in selection set, variables in operation definition, or in arguments set of a field.|![recommended][]|🚀|💡
+[no-fragment-cycles](rules/no-fragment-cycles.md)|A GraphQL fragment is only valid when it does not have cycles in fragments usage.|![recommended][]|🔮|
+[no-hashtag-description](rules/no-hashtag-description.md)|Requires to use `"""` or `"` for adding a GraphQL description instead of `#`.|![recommended][]|🚀|💡
+[no-root-type](rules/no-root-type.md)|Disallow using root types `mutation` and/or `subscription`.||🚀|💡
+[no-scalar-result-type-on-mutation](rules/no-scalar-result-type-on-mutation.md)|Avoid scalar result type on mutation type to make sure to return a valid state.|![all][]|🚀|💡
+[no-typename-prefix](rules/no-typename-prefix.md)|Enforces users to avoid using the type name in a field name while defining your schema.|![recommended][]|🚀|💡
+[no-undefined-variables](rules/no-undefined-variables.md)|A GraphQL operation is only valid if all variables encountered, both directly and via fragment spreads, are defined by that operation.|![recommended][]|🔮|
+[no-unreachable-types](rules/no-unreachable-types.md)|Requires all types to be reachable at some level by root level fields.|![recommended][]|🚀|💡
+[no-unused-fields](rules/no-unused-fields.md)|Requires all fields to be used at some level by siblings operations.||🚀|💡
+[no-unused-fragments](rules/no-unused-fragments.md)|A GraphQL document is only valid if all fragment definitions are spread within operations, or spread within other fragments spread within operations.|![recommended][]|🔮|
+[no-unused-variables](rules/no-unused-variables.md)|A GraphQL operation is only valid if all variables defined by an operation are used, either directly or within a spread fragment.|![recommended][]|🔮|
+[one-field-subscriptions](rules/one-field-subscriptions.md)|A GraphQL subscription is valid only if it contains a single root field.|![recommended][]|🔮|
+[overlapping-fields-can-be-merged](rules/overlapping-fields-can-be-merged.md)|A selection set is only valid if all fields (including spreading any fragments) either correspond to distinct response names or can be merged without ambiguity.|![recommended][]|🔮|
+[possible-fragment-spread](rules/possible-fragment-spread.md)|A fragment spread is only valid if the type condition could ever possibly be true: if there is a non-empty intersection of the possible parent types, and possible types which pass the type condition.|![recommended][]|🔮|
+[possible-type-extension](rules/possible-type-extension.md)|A type extension is only valid if the type is defined and has the same kind.||🔮|
+[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][]|🔮|
+[relay-arguments](rules/relay-arguments.md)|Set of rules to follow Relay specification for Arguments.||🚀|
+[relay-connection-types](rules/relay-connection-types.md)|Set of rules to follow Relay specification for Connection types.||🚀|
+[relay-edge-types](rules/relay-edge-types.md)|Set of rules to follow Relay specification for Edge types.||🚀|
+[relay-page-info](rules/relay-page-info.md)|Set of rules to follow Relay specification for `PageInfo` object.||🚀|
+[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 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][]|🔮|
+[selection-set-depth](rules/selection-set-depth.md)|Limit the complexity of the GraphQL operations solely by their depth. Based on [graphql-depth-limit](https://npmjs.com/package/graphql-depth-limit).|![recommended][]|🚀|💡
+[strict-id-in-types](rules/strict-id-in-types.md)|Requires output types to have one unique identifier unless they do not have a logical one. Exceptions can be used to ignore output types that do not have unique identifiers.|![recommended][]|🚀|
+[unique-argument-names](rules/unique-argument-names.md)|A GraphQL field or directive is only valid if all supplied arguments are uniquely named.|![recommended][]|🔮|
+[unique-directive-names](rules/unique-directive-names.md)|A GraphQL document is only valid if all defined directives have unique names.|![recommended][]|🔮|
+[unique-directive-names-per-location](rules/unique-directive-names-per-location.md)|A GraphQL document is only valid if all non-repeatable directives at a given location are uniquely named.|![recommended][]|🔮|
+[unique-enum-value-names](rules/unique-enum-value-names.md)|A GraphQL enum type is only valid if all its values are uniquely named.||🔮|
+[unique-field-definition-names](rules/unique-field-definition-names.md)|A GraphQL complex type is only valid if all its fields are uniquely named.|![recommended][]|🔮|
+[unique-fragment-name](rules/unique-fragment-name.md)|Enforce unique fragment names across your project.|![all][]|🚀|
+[unique-input-field-names](rules/unique-input-field-names.md)|A GraphQL input object value is only valid if all supplied fields are uniquely named.|![recommended][]|🔮|
+[unique-operation-name](rules/unique-operation-name.md)|Enforce unique operation names across your project.|![all][]|🚀|
+[unique-operation-types](rules/unique-operation-types.md)|A GraphQL document is only valid if it has only one type per operation.|![recommended][]|🔮|
+[unique-type-names](rules/unique-type-names.md)|A GraphQL document is only valid if all defined types have unique names.|![recommended][]|🔮|
+[unique-variable-names](rules/unique-variable-names.md)|A GraphQL operation is only valid if all its variables are uniquely named.|![recommended][]|🔮|
+[value-literals-of-correct-type](rules/value-literals-of-correct-type.md)|A GraphQL document is only valid if all value literals are of the type expected at their position.|![recommended][]|🔮|
+[variables-are-input-types](rules/variables-are-input-types.md)|A GraphQL operation is only valid if all the variables it defines are of input types (scalar, enum, or input object).|![recommended][]|🔮|
+[variables-in-allowed-position](rules/variables-in-allowed-position.md)|Variables passed to field arguments conform to type.|![recommended][]|🔮|
+<!-- prettier-ignore-end -->
+
+[recommended]: https://img.shields.io/badge/-recommended-green.svg
+[all]: https://img.shields.io/badge/-all-blue.svg

package/docs/custom-rules.md

@@ -0,0 +1,148 @@
+# Writing Custom Rules
+
+To get started with your own rules, start by understanding how [ESLint custom rules works](https://eslint.org/docs/developer-guide/working-with-rules).
+
+`graphql-eslint` converts the [GraphQL AST](https://graphql.org/graphql-js/language) into [ESTree structure](https://github.com/estree/estree), so it allows you to easily travel the GraphQL AST tree easily.
+
+You can visit any GraphQL AST node in your custom rules, and report this as error. You don't need to have special handlers for code-files, since `graphql-eslint` extracts usages of `gql` and magic `/* GraphQL */` comments automatically, and runs it through the parser, and eventually it knows to adjust errors location to fit in your code files original location.
+
+## Getting Started
+
+Start by creating a [simple ESLint rule file](https://eslint.org/docs/developer-guide/working-with-rules), and choose the AST nodes you wish to visit. It can either be a [simple AST node `Kind`](https://github.com/graphql/graphql-js/blob/master/src/language/kinds.d.ts) or a complex [ESLint selector](https://eslint.org/docs/developer-guide/selectors) that allows you to travel and filter AST nodes.
+
+We recommend you to read the [graphql-eslint parser documentation](parser.md) before getting started, to understand the differences between the AST structures.
+
+The `graphql-eslint` comes with a TypeScript wrapper for ESLint rules, and provides a testkit to simplify testing process with GraphQL schemas, so you can use that by importing `GraphQLESLintRule` type. But if you wish to use JavaScript - that's fine :)
+
+Here's an example for a simple rule that reports on anonymous GraphQL operations:
+
+```ts
+import { GraphQLESLintRule } from '@graphql-eslint/eslint-plugin'
+
+const rule: GraphQLESLintRule = {
+  create(context) {
+    return {
+      OperationDefinition(node) {
+        if (!node.name || !node.name.value) {
+          context.report({
+            node,
+            message: 'Oops, name is required!'
+          })
+        }
+      }
+    }
+  }
+}
+```
+
+So what happens here?
+
+1. `@graphql-eslint/eslint-plugin` handles the parsing process for your GraphQL content. It will load the GraphQL files (either from code files or from `.graphql` files with SDL), parse it using GraphQL parser, converts it to ESTree structure and let ESLint do the rest.
+1. Your rule is being loaded by ESLint, and executes just like any other ESLint rule.
+1. Our custom rule asks ESLint to run our function for every `OperationDefinition` found.
+1. If the `OperationDefinition` node doesn't have a valid `name` - we report an error to ESLint.
+
+#### More Examples
+
+You can scan the `packages/plugin/src/rules` directory in this repo for references for implementing rules. It coverts most of the use-cases and concepts of rules.
+
+## Accessing original GraphQL AST nodes
+
+Since our parser converts GraphQL AST to ESTree structure, there are some minor differences in the structure of the objects.
+If you are using TypeScript, and you typed your rule with `GraphQLESLintRule` - you'll see that each `node` is a bit different from the AST nodes of GraphQL (you can read more about that in [graphql-eslint parser documentation](parser.md)).
+
+If you need access to the original GraphQL AST `node`, you can use `.rawNode()` method on each node you get from the AST structure of ESLint.
+
+This is useful if you wish to use other GraphQL tools that works with the original GraphQL AST objects.
+
+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'
+
+export const rule = {
+  create(context) {
+    return {
+      OperationDefinition(node) {
+        const schema = requireGraphQLSchemaFromContext(context)
+
+        validate(context, schema, {
+          kind: Kind.DOCUMENT,
+          definitions: [node.rawNode()]
+        })
+      }
+    }
+  }
+}
+```
+
+## `TypeInfo` / `GraphQLSchema`
+
+If you provide GraphQL schema in your ESLint configuration, it will get loaded automatically, and become available in your rules in two ways:
+
+1. You'll be able to access the loaded `GraphQLSchema` object.
+2. In every visited node, you'll be able to use `.typeInfo()` method to get an object with complete type information on your visited node (see [TypeInfo documentation](https://graphql.org/graphql-js/utilities/#typeinfo)).
+
+#### Getting `GraphQLSchema`
+
+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)
+```
+
+#### Accessing TypeInfo
+
+If schema is provided and loaded successfully, the `typeInfo` will be available to use. Otherwise - it will be `undefined`.
+If your plugin requires `typeInfo` in order to operate and run, make sure to call `requireGraphQLSchemaFromContext` - it will validate that the schema is loaded.
+
+`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'
+
+export const rule = {
+  create(context) {
+    requireGraphQLSchemaFromContext('your-rule-name', context)
+
+    return {
+      SelectionSet(node) {
+        const typeInfo = node.typeInfo()
+        if (typeInfo.gqlType) {
+          console.log(`The GraphQLOutputType is: ${typeInfo.gqlType}`)
+        }
+      }
+    }
+  }
+}
+```
+
+The structure of the return value of `.typeInfo()` is [defined here](https://github.com/B2o5T/graphql-eslint/blob/master/packages/plugin/src/estree-converter/converter.ts#L32-L40). So based on the `node` you are using, you'll get a different values on `.typeInfo()` result.
+
+## Testing your rules
+
+To test your rules, you can either use the wrapped `GraphQLRuleTester` from this library, or use the built-it [`RuleTester`](https://eslint.org/docs/developer-guide/working-with-rules#rule-unit-tests) of ESLint.
+
+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'
+
+const ruleTester = new GraphQLRuleTester()
+
+ruleTester.runGraphQLTests('my-rule', rule, {
+  valid: [
+    {
+      code: 'query something { foo }'
+    }
+  ],
+  invalid: [
+    {
+      code: 'query invalid { foo }',
+      errors: [{ message: 'Your error message.' }]
+    }
+  ]
+})
+```

package/docs/deprecated-rules.md

@@ -0,0 +1,21 @@
+# Deprecated Rules
+
+## avoid-duplicate-fields
+
+This rule was renamed to [`no-duplicate-fields`](rules/no-duplicate-fields.md).
+
+## avoid-scalar-result-type-on-mutation
+
+This rule was renamed to [`no-scalar-result-type-on-mutation`](rules/no-scalar-result-type-on-mutation.md).
+
+## avoid-typename-prefix
+
+This rule was renamed to [`no-typename-prefix`](rules/no-typename-prefix.md).
+
+## avoid-operation-name-prefix
+
+This rule was removed because the same things can be validated using [`naming-convention`](rules/naming-convention.md).
+
+## no-operation-name-suffix
+
+This rule was removed because the same things can be validated using [`naming-convention`](rules/naming-convention.md).

package/docs/parser-options.md

@@ -0,0 +1,85 @@
+## Parser Options
+
+### `graphQLParserOptions`
+
+With this configuration, you can specify custom configurations for GraphQL's `parse` method. By default, `graphql-eslint` parser just adds `noLocation: false` to make sure all parsed AST has `location` set, since we need this for tokenizing and for converting the GraphQL AST into ESTree.
+
+You can find the [complete set of options for this object here](https://github.com/graphql/graphql-js/blob/6e48d16f92b9a6df8638b1486354c6be2537033b/src/language/parser.ts#L73)
+
+### `skipGraphQLConfig`
+
+If you are using [`graphql-config`](https://graphql-config.com) in your project, the parser will automatically use that to load your default GraphQL schema.
+
+You can disable this behaviour using `skipGraphQLConfig: true` in the `parserOptions`:
+
+```json
+  "parserOptions": {
+    "skipGraphQLConfig": true
+  }
+```
+
+### `schema`
+
+You can specify `parserOptions.schema` to load your GraphQL schema. The parser uses `graphql-tools` and it's loaders, that means you can either specify a URL, a path to a local `.json` (introspection) file, or a path to a local `.graphql` file(s). You can also use Glob expressions to load multiple files.
+
+Here are a few examples for a valid setup:
+
+```json
+  "parserOptions": {
+    "schema": "./schema.graphql"
+  }
+```
+
+```json
+  "parserOptions": {
+    "schema": "./schema.json"
+  }
+```
+
+```json
+  "parserOptions": {
+    "schema": "http://my-server/graphql"
+  }
+```
+
+```json
+  "parserOptions": {
+    "schema": "./src/**/*.graphql"
+  }
+```
+
+```json
+  "parserOptions": {
+    "schema": [
+      "src/schema-a.graphql",
+      "src/schema-b.graphql",
+      "src/schema-c.graphql"
+    ]
+  }
+```
+
+### `schemaOptions`
+
+If you wish to send additional configuration for the `graphql-tools` loaders that loads your schema, you can specify `schemaOptions` object:
+
+```json
+  "parserOptions": {
+    "schema": "http://my-server/graphql",
+    "schemaOptions": {
+      "headers": {
+        "Authorization": "Bearer MY_TOKEN"
+      }
+    }
+  }
+```
+
+```json
+  "parserOptions": {
+    "schema": "./src/**/*.graphql",
+    "schemaOptions": {
+      "assumeValid": true
+    }
+  }
+```
+
+> The configuration here is flexible, and will be sent to `graphql-tools` and it's loaders. So depends on the schema source, the options may vary. [You can read more about these loaders and their configuration here](https://graphql-tools.com/docs/api/interfaces/loaders_graphql_file_src.GraphQLFileLoaderOptions#properties).

package/docs/parser.md

@@ -0,0 +1,49 @@
+## GraphQL-ESLint Parser
+
+The `graphql-eslint` parser is works in the following way:
+
+1. Loads all relevant GraphQL code using ESLint core (either from `.graphql` files, or using [ESLint `processor`](https://eslint.org/docs/developer-guide/working-with-plugins#processors-in-plugins) to find in code-files).
+1. Is uses `graphql-js` (and `graphql-tools`) to parse the found string into a `DocumentNode`.
+1. Extracts all comments (marked as `# ...`) from the parsed AST, and provides to ESLint as directives hints.
+1. If `graphql-config` is used, or `schema` field is provided, the schema is being loaded and provided to the rules using `parserServices`.
+1. Converts the `DocumentNode` to ESTree structure (and enrich the nodes with `typeInfo`, if schema is loaded).
+
+### ESTree Conversion
+
+The GraphQL AST structure is very similar to ESTree structure, but there are a few differences that the `parser` does.
+
+Here's a list of changes that the parser performs, in order to make the GraphQL AST compatible with ESTree:
+
+---
+
+**Problem**: GraphQL uses `kind` field to define the kind of the AST node, while ESTree uses `type`.
+
+**Solution**: The parser adds `type` field on each node, and just copies the value from `kind` field.
+
+---
+
+**Problem**: Some GraphQL AST nodes are using `type` field (which conflicts with the ESTree kind).
+
+**Solution**: AST nodes that has `type` field are being transformed, and the `type` field changes to `gqlType`.
+
+---
+
+**Problem**: GraphQL AST structure allows circular JSON links (while ESTree might fail on `Maximum call stack exceeded`).
+
+**Solution**: The parser removes circular JSONs (specifically around GraphQL `Location` and the `Lexer`)
+
+---
+
+**Problem**: GraphQL uses `location` field to store the AST locations, while ESTree also uses it in a different structure.
+
+**Solution**: The parser creates a new `location` field that is compatible with ESTree.
+
+### Loading GraphQL Schema
+
+If you are using [`graphql-config`](https://graphql-config.com) in your project, the parser will automatically use that to load your default GraphQL schema (you can disable this behaviour using `skipGraphQLConfig: true` in the `parserOptions`).
+
+If you are not using `graphql-config`, you can specify `parserOptions.schema` to load your GraphQL schema. The parser uses `graphql-tools` and it's loaders, that means you can either specify a URL, a path to a local `.json` (introspection) file, or a path to a local `.graphql` file(s). You can also use Glob expressions to load multiple files.
+
+[You can find more detail on the `parserOptions` config here](parser-options.md)
+
+Providing the schema will make sure that rules that needs it will be able to access it, and it enriches every converted AST node with `typeInfo`.