@graphql-eslint/eslint-plugin 3.14.0-alpha-20221222211539-5e993f5 → 3.14.0-alpha-20221223011700-eed94bd

package/esm/rules/require-description.js

@@ -0,0 +1,190 @@
+import { Kind, TokenKind } from 'graphql';
+import { getLocation, requireGraphQLSchemaFromContext, TYPES_KINDS } from '../utils.js';
+import { getRootTypeNames } from '@graphql-tools/utils';
+const RULE_ID = 'require-description';
+const ALLOWED_KINDS = [
+    ...TYPES_KINDS,
+    Kind.DIRECTIVE_DEFINITION,
+    Kind.FIELD_DEFINITION,
+    Kind.INPUT_VALUE_DEFINITION,
+    Kind.ENUM_VALUE_DEFINITION,
+    Kind.OPERATION_DEFINITION,
+];
+function getNodeName(node) {
+    const DisplayNodeNameMap = {
+        [Kind.OBJECT_TYPE_DEFINITION]: 'type',
+        [Kind.INTERFACE_TYPE_DEFINITION]: 'interface',
+        [Kind.ENUM_TYPE_DEFINITION]: 'enum',
+        [Kind.SCALAR_TYPE_DEFINITION]: 'scalar',
+        [Kind.INPUT_OBJECT_TYPE_DEFINITION]: 'input',
+        [Kind.UNION_TYPE_DEFINITION]: 'union',
+        [Kind.DIRECTIVE_DEFINITION]: 'directive',
+    };
+    switch (node.kind) {
+        case Kind.OBJECT_TYPE_DEFINITION:
+        case Kind.INTERFACE_TYPE_DEFINITION:
+        case Kind.ENUM_TYPE_DEFINITION:
+        case Kind.SCALAR_TYPE_DEFINITION:
+        case Kind.INPUT_OBJECT_TYPE_DEFINITION:
+        case Kind.UNION_TYPE_DEFINITION:
+            return `${DisplayNodeNameMap[node.kind]} ${node.name.value}`;
+        case Kind.DIRECTIVE_DEFINITION:
+            return `${DisplayNodeNameMap[node.kind]} @${node.name.value}`;
+        case Kind.FIELD_DEFINITION:
+        case Kind.INPUT_VALUE_DEFINITION:
+        case Kind.ENUM_VALUE_DEFINITION:
+            return `${node.parent.name.value}.${node.name.value}`;
+        case Kind.OPERATION_DEFINITION:
+            return node.name ? `${node.operation} ${node.name.value}` : node.operation;
+    }
+}
+const schema = {
+    type: 'array',
+    minItems: 1,
+    maxItems: 1,
+    items: {
+        type: 'object',
+        additionalProperties: false,
+        minProperties: 1,
+        properties: {
+            types: {
+                type: 'boolean',
+                description: `Includes:\n${TYPES_KINDS.map(kind => `- \`${kind}\``).join('\n')}`,
+            },
+            rootField: {
+                type: 'boolean',
+                description: 'Definitions within `Query`, `Mutation`, and `Subscription` root types.',
+            },
+            ...Object.fromEntries([...ALLOWED_KINDS].sort().map(kind => {
+                let description = `Read more about this kind on [spec.graphql.org](https://spec.graphql.org/October2021/#${kind}).`;
+                if (kind === Kind.OPERATION_DEFINITION) {
+                    description +=
+                        '\n> You must use only comment syntax `#` and not description syntax `"""` or `"`.';
+                }
+                return [kind, { type: 'boolean', description }];
+            })),
+        },
+    },
+};
+export const rule = {
+    meta: {
+        docs: {
+            category: 'Schema',
+            description: 'Enforce descriptions in type definitions and operations.',
+            url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+            examples: [
+                {
+                    title: 'Incorrect',
+                    usage: [{ types: true, FieldDefinition: true }],
+                    code: /* GraphQL */ `
+            type someTypeName {
+              name: String
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    usage: [{ types: true, FieldDefinition: true }],
+                    code: /* GraphQL */ `
+            """
+            Some type description
+            """
+            type someTypeName {
+              """
+              Name description
+              """
+              name: String
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    usage: [{ OperationDefinition: true }],
+                    code: /* GraphQL */ `
+            # Create a new user
+            mutation createUser {
+              # ...
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    usage: [{ rootField: true }],
+                    code: /* GraphQL */ `
+            type Mutation {
+              "Create a new user"
+              createUser: User
+            }
+
+            type User {
+              name: String
+            }
+          `,
+                },
+            ],
+            configOptions: [
+                {
+                    types: true,
+                    [Kind.DIRECTIVE_DEFINITION]: true,
+                    // rootField: true TODO enable in graphql-eslint v4
+                },
+            ],
+            recommended: true,
+        },
+        type: 'suggestion',
+        messages: {
+            [RULE_ID]: 'Description is required for `{{ nodeName }}`.',
+        },
+        schema,
+    },
+    create(context) {
+        const { types, rootField, ...restOptions } = context.options[0] || {};
+        const kinds = new Set(types ? TYPES_KINDS : []);
+        for (const [kind, isEnabled] of Object.entries(restOptions)) {
+            if (isEnabled) {
+                kinds.add(kind);
+            }
+            else {
+                kinds.delete(kind);
+            }
+        }
+        if (rootField) {
+            const schema = requireGraphQLSchemaFromContext(RULE_ID, context);
+            const rootTypeNames = getRootTypeNames(schema);
+            kinds.add(`:matches(ObjectTypeDefinition, ObjectTypeExtension)[name.value=/^(${[
+                ...rootTypeNames,
+            ].join(',')})$/] > FieldDefinition`);
+        }
+        const selector = [...kinds].join(',');
+        return {
+            [selector](node) {
+                var _a;
+                let description = '';
+                const isOperation = node.kind === Kind.OPERATION_DEFINITION;
+                if (isOperation) {
+                    const rawNode = node.rawNode();
+                    const { prev, line } = rawNode.loc.startToken;
+                    if (prev.kind === TokenKind.COMMENT) {
+                        const value = prev.value.trim();
+                        const linesBefore = line - prev.line;
+                        if (!value.startsWith('eslint') && linesBefore === 1) {
+                            description = value;
+                        }
+                    }
+                }
+                else {
+                    description = ((_a = node.description) === null || _a === void 0 ? void 0 : _a.value.trim()) || '';
+                }
+                if (description.length === 0) {
+                    context.report({
+                        loc: isOperation ? getLocation(node.loc.start, node.operation) : node.name.loc,
+                        messageId: RULE_ID,
+                        data: {
+                            nodeName: getNodeName(node),
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/esm/rules/require-field-of-type-query-in-mutation-result.js

@@ -0,0 +1,69 @@
+import { isObjectType } from 'graphql';
+import { requireGraphQLSchemaFromContext, getTypeName } from '../utils.js';
+const RULE_ID = 'require-field-of-type-query-in-mutation-result';
+export const rule = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            category: 'Schema',
+            description: 'Allow the client in one round-trip not only to call mutation but also to get a wagon of data to update their application.\n> Currently, no errors are reported for result type `union`, `interface` and `scalar`.',
+            url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+            requiresSchema: true,
+            examples: [
+                {
+                    title: 'Incorrect',
+                    code: /* GraphQL */ `
+            type User { ... }
+
+            type Mutation {
+              createUser: User!
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    code: /* GraphQL */ `
+            type User { ... }
+
+            type Query { ... }
+
+            type CreateUserPayload {
+              user: User!
+              query: Query!
+            }
+
+            type Mutation {
+              createUser: CreateUserPayload!
+            }
+          `,
+                },
+            ],
+        },
+        schema: [],
+    },
+    create(context) {
+        const schema = requireGraphQLSchemaFromContext(RULE_ID, context);
+        const mutationType = schema.getMutationType();
+        const queryType = schema.getQueryType();
+        if (!mutationType || !queryType) {
+            return {};
+        }
+        const selector = `:matches(ObjectTypeDefinition, ObjectTypeExtension)[name.value=${mutationType.name}] > FieldDefinition > .gqlType Name`;
+        return {
+            [selector](node) {
+                const typeName = node.value;
+                const graphQLType = schema.getType(typeName);
+                if (isObjectType(graphQLType)) {
+                    const { fields } = graphQLType.astNode;
+                    const hasQueryType = fields.some(field => getTypeName(field) === queryType.name);
+                    if (!hasQueryType) {
+                        context.report({
+                            node,
+                            message: `Mutation result type "${graphQLType.name}" must contain field of type "${queryType.name}"`,
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/esm/rules/require-id-when-available.js

@@ -0,0 +1,196 @@
+import { GraphQLInterfaceType, GraphQLObjectType, Kind, TypeInfo, visit, visitWithTypeInfo, } from 'graphql';
+import { asArray } from '@graphql-tools/utils';
+import { ARRAY_DEFAULT_OPTIONS, requireGraphQLSchemaFromContext, requireSiblingsOperations, englishJoinWords, } from '../utils.js';
+import { getBaseType } from '../estree-converter/index.js';
+const RULE_ID = 'require-id-when-available';
+const DEFAULT_ID_FIELD_NAME = 'id';
+const schema = {
+    definitions: {
+        asString: {
+            type: 'string',
+        },
+        asArray: ARRAY_DEFAULT_OPTIONS,
+    },
+    type: 'array',
+    maxItems: 1,
+    items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            fieldName: {
+                oneOf: [{ $ref: '#/definitions/asString' }, { $ref: '#/definitions/asArray' }],
+                default: DEFAULT_ID_FIELD_NAME,
+            },
+        },
+    },
+};
+export const rule = {
+    meta: {
+        type: 'suggestion',
+        hasSuggestions: true,
+        docs: {
+            category: 'Operations',
+            description: 'Enforce selecting specific fields when they are available on the GraphQL type.',
+            url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+            requiresSchema: true,
+            requiresSiblings: true,
+            examples: [
+                {
+                    title: 'Incorrect',
+                    code: /* GraphQL */ `
+            # In your schema
+            type User {
+              id: ID!
+              name: String!
+            }
+
+            # Query
+            query {
+              user {
+                name
+              }
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    code: /* GraphQL */ `
+            # In your schema
+            type User {
+              id: ID!
+              name: String!
+            }
+
+            # Query
+            query {
+              user {
+                id
+                name
+              }
+            }
+
+            # Selecting \`id\` with an alias is also valid
+            query {
+              user {
+                id: name
+              }
+            }
+          `,
+                },
+            ],
+            recommended: true,
+        },
+        messages: {
+            [RULE_ID]: "Field{{ pluralSuffix }} {{ fieldName }} must be selected when it's available on a type.\nInclude it in your selection set{{ addition }}.",
+        },
+        schema,
+    },
+    create(context) {
+        const schema = requireGraphQLSchemaFromContext(RULE_ID, context);
+        const siblings = requireSiblingsOperations(RULE_ID, context);
+        const { fieldName = DEFAULT_ID_FIELD_NAME } = context.options[0] || {};
+        const idNames = asArray(fieldName);
+        // Check selections only in OperationDefinition,
+        // skip selections of OperationDefinition and InlineFragment
+        const selector = 'OperationDefinition SelectionSet[parent.kind!=/(^OperationDefinition|InlineFragment)$/]';
+        const typeInfo = new TypeInfo(schema);
+        function checkFragments(node) {
+            for (const selection of node.selections) {
+                if (selection.kind !== Kind.FRAGMENT_SPREAD) {
+                    continue;
+                }
+                const [foundSpread] = siblings.getFragment(selection.name.value);
+                if (!foundSpread) {
+                    continue;
+                }
+                const checkedFragmentSpreads = new Set();
+                const visitor = visitWithTypeInfo(typeInfo, {
+                    SelectionSet(node, key, parent) {
+                        if (parent.kind === Kind.FRAGMENT_DEFINITION) {
+                            checkedFragmentSpreads.add(parent.name.value);
+                        }
+                        else if (parent.kind !== Kind.INLINE_FRAGMENT) {
+                            checkSelections(node, typeInfo.getType(), selection.loc.start, parent, checkedFragmentSpreads);
+                        }
+                    },
+                });
+                visit(foundSpread.document, visitor);
+            }
+        }
+        function checkSelections(node, type, 
+        // Fragment can be placed in separate file
+        // Provide actual fragment spread location instead of location in fragment
+        loc, 
+        // Can't access to node.parent in GraphQL AST.Node, so pass as argument
+        parent, checkedFragmentSpreads = new Set()) {
+            const rawType = getBaseType(type);
+            const isObjectType = rawType instanceof GraphQLObjectType;
+            const isInterfaceType = rawType instanceof GraphQLInterfaceType;
+            if (!isObjectType && !isInterfaceType) {
+                return;
+            }
+            const fields = rawType.getFields();
+            const hasIdFieldInType = idNames.some(name => fields[name]);
+            if (!hasIdFieldInType) {
+                return;
+            }
+            function hasIdField({ selections }) {
+                return selections.some(selection => {
+                    if (selection.kind === Kind.FIELD) {
+                        if (selection.alias && idNames.includes(selection.alias.value)) {
+                            return true;
+                        }
+                        return idNames.includes(selection.name.value);
+                    }
+                    if (selection.kind === Kind.INLINE_FRAGMENT) {
+                        return hasIdField(selection.selectionSet);
+                    }
+                    if (selection.kind === Kind.FRAGMENT_SPREAD) {
+                        const [foundSpread] = siblings.getFragment(selection.name.value);
+                        if (foundSpread) {
+                            const fragmentSpread = foundSpread.document;
+                            checkedFragmentSpreads.add(fragmentSpread.name.value);
+                            return hasIdField(fragmentSpread.selectionSet);
+                        }
+                    }
+                    return false;
+                });
+            }
+            const hasId = hasIdField(node);
+            checkFragments(node);
+            if (hasId) {
+                return;
+            }
+            const pluralSuffix = idNames.length > 1 ? 's' : '';
+            const fieldName = englishJoinWords(idNames.map(name => `\`${(parent.alias || parent.name).value}.${name}\``));
+            const addition = checkedFragmentSpreads.size === 0
+                ? ''
+                : ` or add to used fragment${checkedFragmentSpreads.size > 1 ? 's' : ''} ${englishJoinWords([...checkedFragmentSpreads].map(name => `\`${name}\``))}`;
+            const problem = {
+                loc,
+                messageId: RULE_ID,
+                data: {
+                    pluralSuffix,
+                    fieldName,
+                    addition,
+                },
+            };
+            // Don't provide suggestions for selections in fragments as fragment can be in a separate file
+            if ('type' in node) {
+                problem.suggest = idNames.map(idName => ({
+                    desc: `Add \`${idName}\` selection`,
+                    fix: fixer => fixer.insertTextBefore(node.selections[0], `${idName} `),
+                }));
+            }
+            context.report(problem);
+        }
+        return {
+            [selector](node) {
+                const typeInfo = node.typeInfo();
+                if (typeInfo.gqlType) {
+                    checkSelections(node, typeInfo.gqlType, node.loc.start, node.parent);
+                }
+            },
+        };
+    },
+};

package/esm/rules/require-nullable-fields-with-oneof.js

@@ -0,0 +1,58 @@
+import { Kind } from 'graphql';
+const RULE_ID = 'require-nullable-fields-with-oneof';
+export const rule = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            category: 'Schema',
+            description: 'Require are `input` or `type` fields be non nullable with `@oneOf` directive.',
+            url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+            examples: [
+                {
+                    title: 'Incorrect',
+                    code: /* GraphQL */ `
+            input Input @oneOf {
+              foo: String!
+              b: Int
+            }
+          `,
+                },
+                {
+                    title: 'Correct',
+                    code: /* GraphQL */ `
+            input Input @oneOf {
+              foo: String
+              bar: Int
+            }
+          `,
+                },
+            ],
+        },
+        messages: {
+            [RULE_ID]: 'Field `{{fieldName}}` must be nullable.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            'Directive[name.value=oneOf]'({ parent, }) {
+                const isTypeOrInput = [
+                    Kind.OBJECT_TYPE_DEFINITION,
+                    Kind.INPUT_OBJECT_TYPE_DEFINITION,
+                ].includes(parent.kind);
+                if (!isTypeOrInput) {
+                    return;
+                }
+                for (const field of parent.fields) {
+                    if (field.gqlType.kind === Kind.NON_NULL_TYPE) {
+                        context.report({
+                            node: field.name,
+                            messageId: RULE_ID,
+                            data: { fieldName: field.name.value },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/esm/rules/require-type-pattern-with-oneof.js

@@ -0,0 +1,57 @@
+const RULE_ID = 'require-type-pattern-with-oneof';
+export const rule = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            category: 'Schema',
+            description: 'Enforce types with `@oneOf` directive have `error` and `ok` fields.',
+            url: `https://github.com/B2o5T/graphql-eslint/blob/master/docs/rules/${RULE_ID}.md`,
+            examples: [
+                {
+                    title: 'Correct',
+                    code: /* GraphQL */ `
+            type Mutation {
+              doSomething: DoSomethingMutationResult!
+            }
+
+            interface Error {
+              message: String!
+            }
+
+            type DoSomethingMutationResult @oneOf {
+              ok: DoSomethingSuccess
+              error: Error
+            }
+
+            type DoSomethingSuccess {
+              # ...
+            }
+          `,
+                },
+            ],
+        },
+        messages: {
+            [RULE_ID]: 'Type `{{typeName}}` should have `{{fieldName}}` field.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            'Directive[name.value=oneOf][parent.kind=ObjectTypeDefinition]'({ parent, }) {
+                const requiredFields = ['error', 'ok'];
+                for (const fieldName of requiredFields) {
+                    if (!parent.fields.some(field => field.name.value === fieldName)) {
+                        context.report({
+                            node: parent.name,
+                            messageId: RULE_ID,
+                            data: {
+                                typeName: parent.name.value,
+                                fieldName,
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};