update docs (#2754)

dimaMachina · web-flow · commit b2c97d663c73 · 2024-11-24T01:51:02.000+07:00
* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd

* upd
diff --git a/examples/multiple-projects-graphql-config/graphql.config.ts b/examples/multiple-projects-graphql-config/graphql.config.ts
@@ -1,4 +1,4 @@
-import type { IGraphQLConfig, GraphQLTagPluckOptions } from '@graphql-eslint/eslint-plugin';
+import type { GraphQLTagPluckOptions, IGraphQLConfig } from '@graphql-eslint/eslint-plugin';
 
 const config: IGraphQLConfig = {
   projects: {
diff --git a/packages/plugin/src/configs/index.ts b/packages/plugin/src/configs/index.ts
@@ -1,4 +1,4 @@
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 import { ConfigName } from '../types.js';
 import operationsAllConfig from './operations-all.js';
 import operationsRecommendedConfig from './operations-recommended.js';
diff --git a/packages/plugin/src/configs/operations-all.ts b/packages/plugin/src/configs/operations-all.ts
@@ -2,7 +2,7 @@
  * 🚨 IMPORTANT! Do not manually modify this file. Run: `pnpm generate:configs`
  */
 
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default {
   extends: './configs/operations-recommended',
diff --git a/packages/plugin/src/configs/operations-recommended.ts b/packages/plugin/src/configs/operations-recommended.ts
@@ -2,7 +2,7 @@
  * 🚨 IMPORTANT! Do not manually modify this file. Run: `pnpm generate:configs`
  */
 
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default {
   parser: '@graphql-eslint/eslint-plugin',
diff --git a/packages/plugin/src/configs/schema-all.ts b/packages/plugin/src/configs/schema-all.ts
@@ -2,7 +2,7 @@
  * 🚨 IMPORTANT! Do not manually modify this file. Run: `pnpm generate:configs`
  */
 
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default {
   extends: './configs/schema-recommended',
diff --git a/packages/plugin/src/configs/schema-recommended.ts b/packages/plugin/src/configs/schema-recommended.ts
@@ -2,7 +2,7 @@
  * 🚨 IMPORTANT! Do not manually modify this file. Run: `pnpm generate:configs`
  */
 
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default {
   parser: '@graphql-eslint/eslint-plugin',
diff --git a/packages/plugin/src/configs/schema-relay.ts b/packages/plugin/src/configs/schema-relay.ts
@@ -1,4 +1,4 @@
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default {
   parser: '@graphql-eslint/eslint-plugin',
diff --git a/packages/plugin/src/rules/require-selections/index.ts b/packages/plugin/src/rules/require-selections/index.ts
@@ -103,6 +103,8 @@ export const rule: GraphQLESLintRule<RuleOptions, true> = {
         },
       ],
       recommended: true,
+      whenNotToUseIt:
+        "Relay Compiler automatically adds an `id` field to any type that has an `id` field, even if it hasn't been explicitly requested. Requesting a field that is not used directly in the code can conflict with another Relay rule: `relay/unused-fields`.",
     },
     messages: {
       [RULE_ID]:
diff --git a/packages/plugin/src/types.ts b/packages/plugin/src/types.ts
@@ -56,6 +56,7 @@ export type RuleDocsInfo<T> = Omit<RuleMetaDataDocs, 'category' | 'suggestion'>
   configOptions?: T | { schema?: T; operations?: T };
   graphQLJSRuleName?: string;
   isDisabledForAllConfig?: true;
+  whenNotToUseIt?: string;
 };
 
 export type GraphQLESLintRuleListener<WithTypeInfo extends boolean = false> = Record<
diff --git a/scripts/generate-configs.ts b/scripts/generate-configs.ts
@@ -23,7 +23,7 @@ type WriteFile = {
 const writeFormattedFile: WriteFile = async (filePath, code) => {
   if (filePath.startsWith('configs')) {
     code = `
-import type { Linter } from 'eslint';
+import { Linter } from 'eslint';
 
 export default ${JSON.stringify(code)} satisfies Linter.LegacyConfig`;
   }
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
@@ -141,6 +141,10 @@ async function generateDocs(): Promise<void> {
       blocks.push('## Config Schema', md(jsonSchema, '##'));
     }
 
+    if (docs.whenNotToUseIt) {
+      blocks.push('## When Not To Use It', docs.whenNotToUseIt);
+    }
+
     blocks.push('## Resources');
 
     if (graphQLJSRuleName) {
diff --git a/website/app/play/page.client.tsx b/website/app/play/page.client.tsx
@@ -115,7 +115,7 @@ export const ClientPage: FC<{
           ...(schemaConfig && configs[`flat/${schemaConfig}`].rules),
           ...(schemaRule && {
             [`@graphql-eslint/${schemaRule}`]:
-             // @ts-expect-error -- TODO: fix type error
+              // @ts-expect-error -- TODO: fix type error
               configs['flat/schema-all'].rules[`@graphql-eslint/${schemaRule}`],
           }),
         }}
@@ -132,7 +132,7 @@ export const ClientPage: FC<{
           ...(operationConfig && configs[`flat/${operationConfig}`].rules),
           ...(operationRule && {
             [`@graphql-eslint/${operationRule}`]:
-            // @ts-expect-error -- TODO: fix type error
+              // @ts-expect-error -- TODO: fix type error
               configs['flat/operations-all'].rules[`@graphql-eslint/${operationRule}`],
           }),
         }}
diff --git a/website/content/docs/getting-started.mdx b/website/content/docs/getting-started.mdx
@@ -1,107 +1,127 @@
-import { Callout } from '@theguild/components'
-
-# 🚧 Getting Started
-
-<WIP />
+# Getting Started
 
 ## Configuration
 
 To get started, define an override in your ESLint config to apply this plugin to `.graphql` files.
 Add the [rules](/rules) you want applied.
 
-<Callout type="error" emoji="🚨">
-  **Note**: This step is necessary even if you are declaring operations and/or schema in code files.
-</Callout>
-
-```json filename=".eslintrc.json"
-{
-  "overrides": [
-    {
-      "files": ["*.graphql"],
-      "parser": "@graphql-eslint/eslint-plugin",
-      "plugins": ["@graphql-eslint"],
-      "rules": {
-        "@graphql-eslint/known-type-names": "error"
-      }
+> [!WARNING]
+>
+> This step is necessary even if you are declaring operations and/or schema in code files[^1].
+
+```js filename="eslint.config.js"
+import graphqlPlugin from '@graphql-eslint/eslint-plugin'
+
+export default [
+  // ... other config
+  {
+    files: ['**/*.graphql'],
+    languageOptions: {
+      parser: graphqlPlugin.parser
+    },
+    plugins: {
+      '@graphql-eslint': graphqlPlugin
+    },
+    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 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 filename=".eslintrc.json"
-{
-  "overrides": [
-+   {
-+     "files": ["*.js"],
-+     "processor": "@graphql-eslint/graphql"
-+   },
-    {
-      "files": ["*.graphql"],
-      "parser": "@graphql-eslint/eslint-plugin",
-      "plugins": ["@graphql-eslint"],
-      "rules": {
-        "@graphql-eslint/known-type-names": "error"
-      }
+## Extend Plugin Functionality to GraphQL Definitions in Code Files[^1]
+
+When defining GraphQL schemas or operations directly in code files[^1], you need to add an override
+to ensure that this plugin's functionality is applied to those definitions as well.
+
+```diff filename="eslint.config.js"
+import graphqlPlugin from '@graphql-eslint/eslint-plugin';
+
+export default [
++ {
++   files: ['**/*.js'],
++   processor: graphqlPlugin.processor
++ },
+  {
+    files: ['**/*.graphql'],
+    languageOptions: {
+      parser: graphqlPlugin.parser
+    },
+    plugins: {
+      '@graphql-eslint': graphqlPlugin
+    },
+    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://the-guild.dev/graphql/eslint/rules/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://the-guild.dev/graphql/config), 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 filename=".eslintrc.json"
-{
-  "files": ["*.graphql"],
-  "parser": "@graphql-eslint/eslint-plugin",
-  "plugins": ["@graphql-eslint"],
-  "rules": {
-    "@graphql-eslint/no-unreachable-types": "error"
-  },
-+ "parserOptions": {
-+   "schema": "./schema.graphql"
-+ }
+> [!TIP]
+>
+> Under the hood, the processor extracts schema and operation files from `files: ['**/*.js']` and
+> treats them as virtual GraphQL documents with `.graphql` extensions. This enables the overrides
+> you define for `.graphql` files, under `files: ['**/*.graphql']`, to be applied to the definitions
+> within your code files[^1].
+
+## Extended Linting Rules with GraphQL Schema
+
+Some linting rules require access to the entire GraphQL schema. For example, the
+[no-unreachable-types](../rules/no-unreachable-types) rule checks that all types are reachable
+through root-level fields.
+
+To enable these rules, you need to inform ESLint how to identify and load your complete schema.
+
+The GraphQL ESLint plugin integrates seamlessly with
+[GraphQL Config](https://the-guild.dev/graphql/config) which it uses to automatically load your
+schema. GraphQL Config supports multiple ways to specify your schema, including `.json`
+(introspection) file, `.graphql` files, a URL endpoint, or a raw string.
+
+> This integration uses [`graphql-tools`](https://the-guild.dev/graphql/tools) under the hood to
+> handle the schema loading.
+
+Here’s an example of a basic `graphql.config.js` file:
+
+```js filename="graphql.config.js"
+export default {
+  schema: './schema.graphql'
 }
 ```
 
-> You can find a complete
-> [documentation of the `parserOptions` here](/docs/getting-started/parser-options).
-
-> Some rules require type information to operate, it's marked in the docs for each rule!
+Alternatively, you can define the schema directly within your ESLint configuration by specifying
+`languageOptions.parserOptions.graphQLConfig.schema`.
+
+```diff filename="eslint.config.js"
+import graphqlPlugin from '@graphql-eslint/eslint-plugin'
+
+export default [
+  // ... other config
+  {
+    files: ['**/*.graphql'],
+    languageOptions: {
+      parser: graphqlPlugin.parser,
++     parserOptions: {
++       graphQLConfig: {
++         schema: './schema.graphql'
++       }
++     }
+    },
+    plugins: {
+      '@graphql-eslint': graphqlPlugin
+    },
+    rules: {
+      '@graphql-eslint/no-unreachable-types': 'error'
+    }
+  }
+]
+```
 
-### Extended Linting Rules with Siblings Operations
+## 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.
@@ -114,19 +134,41 @@ To workaround that, we allow you to provide additional information on your Graph
 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 filename=".eslintrc.json"
-{
-  "files": ["*.graphql"],
-  "parser": "@graphql-eslint/eslint-plugin",
-  "plugins": ["@graphql-eslint"],
-  "rules": {
-    "@graphql-eslint/unique-operation-name": "error"
-  },
-  "parserOptions": {
-+   "operations": "./src/**/*.graphql",
-    "schema": "./schema.graphql"
-  }
+just specify a glob expression(s) that points to your code[^1] and/or `.graphql` files:
+
+```diff filename="graphql.config.js"
+export default {
+  schema: './schema.graphql',
++ documents: './src/**/*.graphql'
 }
 ```
+
+or via programmatic usage:
+
+```diff filename="eslint.config.js"
+import graphqlPlugin from '@graphql-eslint/eslint-plugin'
+
+export default [
+  // ... other config
+  {
+    files: ['**/*.graphql'],
+    languageOptions: {
+      parser: graphqlPlugin.parser,
+      parserOptions: {
+        graphQLConfig: {
+          schema: './schema.graphql',
++         documents: './src/**/*.graphql'
+        }
+      }
+    },
+    plugins: {
+      '@graphql-eslint': graphqlPlugin
+    },
+    rules: {
+      '@graphql-eslint/unique-operation-name': 'error'
+    }
+  }
+]
+```
+
+[^1]: Code files (e.g., `.js`, `.jsx`, `.ts`, `.tsx` files)
diff --git a/website/content/docs/parser-options.mdx b/website/content/docs/parser-options.mdx
diff --git a/website/content/rules/require-selections.mdx b/website/content/rules/require-selections.mdx

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { IGraphQLConfig, GraphQLTagPluckOptions } from '@graphql-eslint/eslint-plugin';`
	`1`	`+import type { GraphQLTagPluckOptions, IGraphQLConfig } from '@graphql-eslint/eslint-plugin';`
`2`	`2`
`3`	`3`	`const config: IGraphQLConfig = {`
`4`	`4`	`projects: {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { Linter } from 'eslint';`
	`1`	`+import { Linter } from 'eslint';`
`2`	`2`	`import { ConfigName } from '../types.js';`
`3`	`3`	`import operationsAllConfig from './operations-all.js';`
`4`	`4`	`import operationsRecommendedConfig from './operations-recommended.js';`
Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@ type WriteFile = {`
`23`	`23`	`const writeFormattedFile: WriteFile = async (filePath, code) => {`
`24`	`24`	`if (filePath.startsWith('configs')) {`
`25`	`25`	code = `
`26`		`-import type { Linter } from 'eslint';`
	`26`	`+import { Linter } from 'eslint';`
`27`	`27`
`28`	`28`	export default ${JSON.stringify(code)} satisfies Linter.LegacyConfig`;
`29`	`29`	`}`