add an example with custom graphql rules

.changeset/strong-otters-mate.md

@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': patch
+---
+
+add an example with custom graphql rules

examples/custom-rules/eslint.config.js

@@ -0,0 +1,21 @@
+import graphqlPlugin from '@graphql-eslint/eslint-plugin';
+import { rule } from './my-rule.js';
+
+export default [
+  {
+    files: ['**/*.graphql'],
+    languageOptions: {
+      parser: graphqlPlugin.parser,
+    },
+    plugins: {
+      '@internal': {
+        rules: {
+          'my-rule': rule,
+        },
+      },
+    },
+    rules: {
+      '@internal/my-rule': 'error',
+    },
+  },
+];

examples/custom-rules/my-rule.js

@@ -0,0 +1,14 @@
+export const rule = {
+  create(context) {
+    return {
+      OperationDefinition(node) {
+        if (!node.name?.value) {
+          context.report({
+            node,
+            message: 'Oops, name is required!',
+          });
+        }
+      },
+    };
+  },
+};

examples/custom-rules/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@graphql-eslint/example-custom-rules",
+  "version": "0.0.0",
+  "type": "module",
+  "repository": "https://github.com/dimaMachina/graphql-eslint",
+  "author": "Dimitri POSTOLOV <[email protected]>",
+  "private": true,
+  "scripts": {
+    "lint": "eslint --cache ."
+  },
+  "dependencies": {
+    "graphql": "16.9.0"
+  },
+  "devDependencies": {
+    "@graphql-eslint/eslint-plugin": "4.1.0",
+    "eslint": "9.15.0"
+  }
+}

examples/custom-rules/test.graphql

@@ -0,0 +1,3 @@
+query {
+  foo
+}

packages/plugin/__tests__/__snapshots__/examples.spec.md

@@ -2133,3 +2133,23 @@ exports[`Examples > should work with \`graphql-config\` 2`] = `
   },
 ]
 `;
+
+exports[`Examples > should work with custom rules 1`] = `
+[
+  {
+    filePath: examples/custom-rule/test.graphql,
+    messages: [
+      {
+        column: 1,
+        endColumn: 13,
+        endLine: 1,
+        line: 1,
+        message: Oops, name is required!,
+        nodeType: OperationDefinition,
+        ruleId: @internal/my-rule,
+        severity: 2,
+      },
+    ],
+  },
+]
+`;

packages/plugin/__tests__/examples.spec.ts

@@ -121,6 +121,13 @@ describe('Examples', () => {
     const cwd = path.join(CWD, 'examples', 'multiple-projects-graphql-config');
     testESLintOutput(cwd, 4);
   });
+
+  it('should work with custom rules', () => {
+    const cwd = path.join(CWD, 'examples', 'custom-rules');
+    const flatResults = getFlatESLintOutput(cwd);
+    expect(normalizeResults(flatResults)).toMatchSnapshot();
+    expect(countErrors(flatResults)).toBe(1);
+  });
 });
 
 function testESLintOutput(cwd: string, errorCount: number): void {

website/content/docs/usage/custom-rules.mdx

@@ -0,0 +1,11 @@
+---
+sidebarTitle: Custom GraphQL Rules
+---
+
+# Usage with custom GraphQL rules
+
+<ESLintConfigs gitFolder="custom-rules" additionalFiles={{ 'Custom GraphQL Rule': 'my-rule.js' }} />
+
+> [!TIP]
+>
+> Check out the [custom rules](/docs/custom-rules) guide to learn how to create your own rules.

website/content/docs/usage/graphql.mdx

@@ -5,4 +5,7 @@ icon: GraphQLIcon
 
 # Usage with `.graphql` files
 
-<ESLintConfigs gitFolder="graphql-config" graphqlConfigFile="graphql.config.js" />
+<ESLintConfigs
+  gitFolder="graphql-config"
+  additionalFiles={{ 'GraphQL Config': 'graphql.config.js' }}
+/>

website/content/docs/usage/js.mdx

@@ -41,4 +41,4 @@ export default [
 
 ---
 
-<ESLintConfigs gitFolder="code-file" graphqlConfigFile="graphql.config.js" />
+<ESLintConfigs gitFolder="code-file" additionalFiles={{ 'GraphQL Config': 'graphql.config.js' }} />

website/content/docs/usage/multiple-projects.mdx

@@ -5,4 +5,7 @@ icon: StackIcon
 
 # Usage to lint different schemas
 
-<ESLintConfigs gitFolder="multiple-projects-graphql-config" graphqlConfigFile="graphql.config.ts" />
+<ESLintConfigs
+  gitFolder="multiple-projects-graphql-config"
+  additionalFiles={{ 'GraphQL Config': 'graphql.config.ts' }}
+/>

website/content/docs/usage/schema-and-operations.mdx

@@ -5,4 +5,4 @@ icon: HalfIcon
 
 # Usage to lint both schema/operations
 
-<ESLintConfigs gitFolder="monorepo" graphqlConfigFile="graphql.config.js" />
+<ESLintConfigs gitFolder="monorepo" additionalFiles={{ 'GraphQL Config': 'graphql.config.js' }} />

website/mdx-components.tsx

@@ -8,42 +8,52 @@ import {
 } from '@theguild/components/server';
 
 const docsComponents = getDocsMDXComponents({
-  async ESLintConfigs({ gitFolder, graphqlConfigFile = '' }) {
+  async ESLintConfigs({
+    gitFolder,
+    additionalFiles,
+  }: {
+    gitFolder: string;
+    additionalFiles: Record<string, string>;
+  }) {
     const user = 'dimaMachina';
     const repo = 'graphql-eslint';
     const branch = 'master';
     const docsPath = path.join(process.cwd(), '..', 'examples', gitFolder);
-    const { ext } = path.parse(graphqlConfigFile);
 
-    const graphqlConfig =
-      graphqlConfigFile &&
-      `
-## GraphQL Config
+    const promises = Object.entries({
+      ...additionalFiles,
+      'ESLint Flat Config': 'eslint.config.js',
+    }).map(async ([heading, filePath]) => {
+      const { ext } = path.parse(filePath);
+      return `## ${heading}
 
-\`\`\`${ext.slice(1)} filename="${graphqlConfigFile}"
-${(await fs.readFile(`${docsPath}/${graphqlConfigFile}`, 'utf8')).trim()}
-\`\`\`
-`;
+\`\`\`${ext.slice(1)} filename="${filePath}"
+${(await fs.readFile(`${docsPath}/${filePath}`, 'utf8')).trim()}
+\`\`\``;
+    });
+    const files = await Promise.all(promises);
+
+    const hasLegacyConfig = await fs
+      .access(`${docsPath}/.eslintrc.cjs`)
+      .then(() => true)
+      .catch(() => '');
 
     return (
       <MDXRemote
         compiledSource={await compileMdx(`
 > [!NOTE]
 >
 > Check out
-> [the official examples](https://github.com/${user}/${repo}/tree/${branch}/examples/${gitFolder})
+> [the official example${hasLegacyConfig && 's'}](https://github.com/${user}/${repo}/tree/${branch}/examples/${gitFolder})
 > for
 > [ESLint Flat Config](https://github.com/${user}/${repo}/blob/${branch}/examples/${gitFolder}/eslint.config.js)
-> or
-> [ESLint Legacy Config](https://github.com/${user}/${repo}/blob/${branch}/examples/${gitFolder}/.eslintrc.cjs)
-> .
+${hasLegacyConfig ? `> or [ESLint Legacy Config](https://github.com/${user}/${repo}/blob/${branch}/examples/${gitFolder}/.eslintrc.cjs).` : '>.'}
 
-${graphqlConfig}
-## ESLint Flat Config
-\`\`\`js filename="eslint.config.js"
-${(await fs.readFile(`${docsPath}/eslint.config.js`, 'utf8')).trim()}
-\`\`\`
+${files.join('\n')}
 
+${
+  hasLegacyConfig &&
+  `
 ## ESLint Legacy Config
 
 > [!WARNING]
@@ -52,7 +62,9 @@ ${(await fs.readFile(`${docsPath}/eslint.config.js`, 'utf8')).trim()}
 
 \`\`\`js filename=".eslintrc.cjs"
 ${(await fs.readFile(`${docsPath}/.eslintrc.cjs`, 'utf8')).trim()}
-\`\`\``)}
+\`\`\``
+}
+`)}
       />
     );
   },