Merge pull request #55 from dotansimha/prepare-to-release

Initial release preparation

Author: dotansimha

.changeset/brave-years-float.md

@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': minor
+---
+
+Initial minor release from this repo.

.changeset/config.json

@@ -6,5 +6,5 @@
   "access": "restricted",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",
-  "ignore": []
-}
+  "ignore": ["@graphql-eslint/example"]
+}

.github/future_workflows/canary.yml renamed to .github/workflows/canary.yml

@@ -12,6 +12,7 @@ This project integrates GraphQL AST parser and ESLint.
 - 🚀 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
 
 Special thanks to [ilyavolodin](https://github.com/ilyavolodin) for his work on a similar project!
 
@@ -61,7 +62,7 @@ If you are using code files to store your GraphQL schema or your GraphQL operati
 }
 ```
 
-#### Extended linting with GraphQL Schema
+#### Extended linting rules with GraphQL Schema
 
 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!
 
@@ -80,6 +81,8 @@ The parser allow you to specify a json file / graphql files(s) / url / raw strin
 }
 ```
 
+> 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!
 
 ### VSCode Integration
@@ -97,8 +100,33 @@ In order to enable it processing other extensions, add the following section in
 }
 ```
 
+### 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, `next-line` or (current) `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 plugins here](./docs/README.md)
 
 > This repo doesn't exports a "recommended" set of rules - feel free to recommend us!
+
+## 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))
+
+## Contributing
+
+If you think a rule is missing, or can be modified, feel free to report issues, on open PRs. We always welcome contributions.

.github/future_workflows/release.yml renamed to .github/workflows/release.yml

@@ -13,6 +13,8 @@
 - [`prettier`](./rules/prettier.md)
 - [`require-description`](./rules/require-description.md)
 
-## Writing your own rules
+## Further Reading
 
-TBD
+- [Writing Custom Rules](./custom-rules.md)
+- [How the parser works?](./parser.md)
+- [`parserOptions`](./parser-options.md)

README.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 && (!node.name || node.name.value === '')) {
+          context.report({
+            node: 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. You 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 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-js';
+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(context);
+
+    return {
+      SelectionSet(node) {
+        const typeInfo = node.typeInfo();
+
+        if (typeInfo && 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.
+
+## 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 }`,
+    },
+  ],
+});
+```

docs/README.md

@@ -0,0 +1,79 @@
+## Parser Options
+
+### `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://www.graphql-tools.com/docs/api/interfaces/_loaders_graphql_file_src_index_.graphqlfileloaderoptions).

docs/custom-rules.md

@@ -0,0 +1,37 @@
+## 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, and renames the GraphQL `location` to `gqlLocation`.
+
+### 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`.

docs/parser-options.md

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "eslint": "7.10.0",
-    "@graphql-eslint/eslint-plugin": "0.0.1",
+    "@graphql-eslint/eslint-plugin": "0.2.1",
     "graphql": "15.3.0",
     "typescript": "4.0.3"
   }