Merge pull request #30 from dotansimha/docs

Docs & README

Author: dotansimha

README.md

@@ -1,2 +1,106 @@
-# graphql-eslint
-graphql-eslint
+This project integrates GraphQL AST parser and ESLint.
+
+## 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: `disable-next-line`)
+- 🚀 Easily extendable - supports custom rules.
+
+Special thanks to [ilyavolodin](https://github.com/ilyavolodin) for his work on a similar project!
+
+## Getting Started
+
+### Installation
+
+Start by installing the plugin package, which includes everything you need:
+
+```
+yarn add -D @graphql-eslint/eslint-plugin
+```
+
+Or, with NPM:
+
+```
+npm install --save-dev @graphql-eslint/eslint-plugin
+```
+
+> Also, make sure you have `graphql` dependency in your project.
+
+### Configuration
+
+To get started, create an override configuration for your ESLint, while applying it to to `.graphql` files (do that even if you are declaring your operations in code files):
+
+```json
+{
+  "overrides": [
+    {
+      "files": ["*.graphql"],
+      "parser": "@graphql-eslint/eslint-plugin",
+      "plugins": ["@graphql-eslint"],
+      "rules": {
+        ...
+      }
+    }
+  ]
+}
+```
+
+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 the following to your setup:
+
+```json
+{
+  "processor": "@graphql-eslint/graphql",
+  "overrides": [ ... ]
+}
+```
+
+#### Extended linting 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!
+
+Linting process can be enriched and extended with GraphQL type information, if you are able to provide your GraphQL schema.
+
+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:
+
+```json
+{
+  "files": ["*.graphql"],
+  "parser": "@graphql-eslint/eslint-plugin",
+  "plugins": ["@graphql-eslint"],
+  "parserOptions": {
+    "schema": "./schema.graphql"
+  }
+}
+```
+
+> Some rules requires type information to operate, it's marked in the docs of each plugin!
+
+### 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.
+
+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.options": {
+    "extentions": [".js", ".graphql"]
+  }
+}
+```
+
+## 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!

docs/README.md

@@ -0,0 +1,14 @@
+## Available Rules
+
+- [`avoid-operation-name-prefix`](./avoid-operation-name-prefix.md)
+- [`input-name`](./input-name.md)
+- [`description-style`](./description-style.md)
+- [`naming-convention`](./naming-convention.md)
+- [`no-anonymous-operations`](./no-anonymous-operations.md)
+- [`require-deprecation-reason`](./require-deprecation-reason.md)
+- [`no-case-insensitive-enum-values-duplicates`](./no-case-insensitive-enum-values-duplicates.md)
+- [`no-operation-name-suffix`](./no-operation-name-suffix.md)
+- [`require-id-when-available`](./require-id-when-available.md)
+- [`validate-against-schema`](./validate-against-schema.md)
+- [`prettier`](./prettier.md)
+- [`require-description`](./require-description.md)

docs/rules/avoid-operation-name-prefix.md

@@ -0,0 +1,32 @@
+## Avoid Prefix in GraphQL operation name
+
+- Name: `avoid-operation-name-prefix`
+- Requires GraphQL Schema: `false`
+
+Allow you to enforce and avoid operation name prefix, useful if you wish to avoid prefix in your root fields,like `getSomething`.
+
+### Usage Example
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/avoid-operation-name-prefix: ["error", { keywords: "get" }]
+
+query getUserDetails {
+  # ...
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/avoid-operation-name-prefix: ["error", { keywords: "get" }]
+
+query userDetails {
+  # ...
+}
+```
+
+### Configuration
+
+- `keywords`: array of prefixes you with to avoid in operation names.

docs/rules/description-style.md

@@ -0,0 +1,38 @@
+# Enforce style of the description comments
+
+- Name: `description-style`
+- Requires GraphQL Schema: `false`
+
+Following the same style for description comments in your code will make them easier to read.
+
+## Rule Details
+
+This rule enforces same style for all description comments in your code. This rule has one option: `style` that can be set to either `block` or `inline` (default).
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/description-style: ["error", { style: "inline" }]
+
+""" Description """
+type someTypeName {
+    ...
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/description-style: ["error", { style: "inline" }]
+
+" Description "
+type SomeTypeName {
+  someFieldName: String
+}
+```
+
+## Options
+
+This rule accepts configuration object with one option:
+
+- `style: 'block'|'inline'` - Will require all comments to be either in block style (`"""`) or inline style (`"`)

docs/rules/input-name.md

@@ -0,0 +1,42 @@
+# Enforce names of input parameters and input types
+
+- Name: `input-name`
+- Requires GraphQL Schema: `false`
+
+Using the same name for all input parameters will make your schemas easier to consume and more predictable. Using the same name as mutation for InputType will make it easier to find mutations that InputType belongs to.
+
+## Rule Details
+
+This rule enforces all input parameters to be named `input`, and all InputTypes to use the name of the mutation + `'Input'`.
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/input-name: ["error", { checkInputType: true }]
+
+type Mutation {
+  SetMessage(message: InputMessage): String
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/input-name: ["error", { checkInputType: true }]
+
+type Mutation {
+  SetMessage(input: SetMessageInput): String
+}
+```
+
+```graphql
+# eslint @graphql-eslint/input-name: ["error", { checkInputType: false }]
+
+type Mutation {
+  SetMessage(input: AnyInputTypeName): String
+}
+```
+
+## Configuration
+
+This rule accepts one option `checkInputType`. If `true` (default) it will verify that the name of the input type matches name of the mutation + 'Input'. If `false` it will not check InputType name.

docs/rules/naming-convention.md

@@ -0,0 +1,43 @@
+# Enforce naming conventions patterns in your typeDefs
+
+- Name: `naming-convention`
+- Requires GraphQL Schema: `false`
+
+Following the same naming conventions in all your type definitions will make them easier to read and more predictable.
+
+## Rule Details
+
+This rule enforces naming conventions patterns for your type definitions. It can control if the names should be in PascalCase, camelCase, snake_case or UPPER_CASE. It can also allow or disallow trailing and leading underscores.
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/naming-convention: ["error", { ObjectTypeDefinition: "PascalCase" }]
+
+type someTypeName {
+    ...
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/naming-convention: ["error", { FieldDefinition: "camelCase", ObjectTypeDefinition: "PascalCase" }]
+
+type SomeTypeName {
+  someFieldName: String
+}
+```
+
+## Options
+
+This rule accepts configuration object with multiple options:
+
+- `ObjectTypeDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of types, input objects, enums and interfaces
+- `FieldDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of type fields
+- `EnumValueDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of enumeration values
+- `InputValueDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of input properties
+- `FragmentDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of fragments
+- `ScalarTypeDefinition: 'PascalCase'|'camelCase'|'snake_case'|'UPPER_CASE'` - Will affect names of scalars
+- `leadingUnderscore: 'allow'|'forbid'` - Will allow or forbid leading underscores in all names. Default value is `forbid`.
+- `trailingUnderscore: 'allow'|'forbid'` - Will allow of forbid trailing underscores in all names. Default value is `forbid`.

docs/rules/no-anonymous-operations.md

@@ -0,0 +1,28 @@
+## Avoid Anonymous GraphQL operations
+
+- Name: `no-anonymous-operations`
+- Requires GraphQL Schema: `false`
+
+Allow you to require name for your GraphQL operations. This is useful since most GraphQL client libraries are using the operation name for caching purposes.
+
+### Usage Example
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-anonymous-operations: ["error"]
+
+query {
+  # ...
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-anonymous-operations: ["error"]
+
+query something {
+  # ...
+}
+```

docs/rules/no-case-insensitive-enum-values-duplicates.md

@@ -0,0 +1,32 @@
+## Avoid Duplicates In Enum Values
+
+- Name: `no-case-insensitive-enum-values-duplicates`
+- Requires GraphQL Schema: `false`
+
+Checks enums values for duplicate values defined (case-insensitive).
+
+### Usage Example
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-case-insensitive-enum-values-duplicates: ["error"]
+
+enum MyEnum {
+  Value
+  VALUE
+  ValuE
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-case-insensitive-enum-values-duplicates: ["error"]
+
+enum MyEnum {
+  Value1
+  Value2
+  Value3
+}
+```

docs/rules/no-operation-name-suffix.md

@@ -0,0 +1,28 @@
+## No Operation Name Suffix
+
+- Name: `no-operation-name-suffix`
+- Requires GraphQL Schema: `false`
+
+Makes sure you are not adding the operation type to the name of the operation.
+
+### Usage Example
+
+Examples of **incorrect** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-operation-name-suffix: ["error"]
+
+query userQuery {
+  # ...
+}
+```
+
+Examples of **correct** code for this rule:
+
+```graphql
+# eslint @graphql-eslint/no-operation-name-suffix: ["error"]
+
+query user {
+  # ...
+}
+```

docs/rules/prettier.md

@@ -0,0 +1,12 @@
+# Enforces styling consistency in your type definitions
+
+- Name: `prettier`
+- Requires GraphQL Schema: `false`
+
+Having all your code follow the same styling guidelines makes it easier to read and understand the code
+
+## Rule Details
+
+This rule is a copy of the rule in [eslint-plugin-prettier](https://github.com/prettier/eslint-plugin-prettier) adjusted to work for GraphQL.
+
+Please see [documentation](https://github.com/prettier/eslint-plugin-prettier#options) for available options and configurations.