add an example with custom graphql rules (#2787)

* aa

* aa

* aa

* aa

* aa

* Update examples/custom-rules/package.json

* aa

* polish

* fix test

* tiny fix

* aa

* aa

* aa

* Update .changeset/strong-otters-mate.md

Author: dimaMachina

.changeset/strong-otters-mate.md

@@ -0,0 +1,5 @@
+---
+'@graphql-eslint/eslint-plugin': patch
+---
+
+add an example with [custom graphql rules](https://github.com/dimaMachina/graphql-eslint/tree/master/examples/custom-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": "workspace:*",
+    "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-rules/test.graphql,
+    messages: [
+      {
+        column: 1,
+        endColumn: 16,
+        endLine: 3,
+        line: 1,
+        message: Oops, name is required!,
+        nodeType: OperationDefinition,
+        ruleId: @internal/my-rule,
+        severity: 2,
+      },
+    ],
+  },
+]
+`;

packages/plugin/__tests__/examples.spec.ts

@@ -121,6 +121,16 @@ 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);
+    // Windows has some offset for `range`, I think due \r\n handling
+    if (os.platform() !== 'win32') {
+      expect(normalizeResults(flatResults)).toMatchSnapshot();
+    }
+    expect(countErrors(flatResults)).toBe(1);
+  });
 });
 
 function testESLintOutput(cwd: string, errorCount: number): void {

pnpm-lock.yaml

@@ -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/custom-rules.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' }}
+/>