When and why is graphql-config or parserOption.schema required?

[JustinTRoss]

Hey Team!

Trying to set this up, I've found it difficult to understand when and why graphql-config or parserOption.schema is required.

Some circumstances seem to function perfectly just using the files specifier in eslintrc override: files: ["*.graphql"],. Others seem to require using either graphql-config or parserOption.schema.

For example, using the extends: "plugin:@graphql-eslint/recommended" option throws an error unless you specify one of these.

Would someone mind explaining the expected functionality around this behavior? I don't mind translating that info into docs and PRing them. Just need to understand it first 😅 .

Cheers,
Justin

[dimaMachina]

Some rules require either schema or operations to be set and loaded. It's doesn't matter how you will set up schema or operations either parserOptions or graphql-config.

[JustinTRoss]

Thanks. I understand this. My question is what these do differently from files: ["*.graphql"] and why a situation would require them?

[dimaMachina]

when you define files: ["*.graphql"] overrides object you tell for ESLint how to treat files with .graphql extension.

When you configure processor for code files:

{
    files: ['*.tsx', '*.ts', '*.jsx', '*.js'],
    processor: '@graphql-eslint/graphql'
}

graphql-eslint will extract GraphQL documents under a virtual filename that will end with .graphql extension, so your overrides section with files: ["*.graphql"] configuration will match for them.

For example, let's imagine you have get-users.ts code file:

// the following document will be extracted and will have get-users.ts/0_document.graphql filename
const USER_FIELDS = gql`
  fragment UserFields on User {
    id
    email
  }
`

// the following document will be extracted and will have get-users.ts/1_document.graphql filename
const GET_USERS = /* GraphQL */ `
  query Users {
    users {
      id
      firstName
    }
  }
`

[JustinTRoss]

Ahh. Thank you. This is helpful. I had wondered how these two played together.

It still doesn't quite get at the heart of the question I'm asking. I'll try to deduce below.

If files: ["*.graphql"] tells ESLint to modify the way it treats ".graphql" files as it processes them, then it should be sufficient to achieve any linting that can be done on a per-file basis. Thus, I imagine specifying schema files via graphql-config or parserOptions.schema must be necessary only in two scenarios:

1. When using lint rules that require an understanding of the entire schema at once.
2. When using a schema that isn't local to the repo.

Am I getting that right?

[JustinTRoss]

I notice https://github.com/dotansimha/graphql-eslint/blob/master/docs/rules/avoid-scalar-result-type-on-mutation.md requires schema be specified however, and I can't see how it would fit into one of those two categories.

[dimaMachina]

In the case of avoid-scalar-result-type-on-mutation rule full schema is required for one reason - to catch case when Mutation root type is named differently than Mutation. So we require full schema only to determine the name of the root type mutation.
For example, this rule will catch this case:

  schema {
    mutation: MyMutationName
  }
  
  type MyMutationName {
    createUser: Boolean # will report an error
  }

Also, to understand how to work with rule, you can always refer to the rule test file, the link is specified in the documentation of each rule at the bottom.

[JustinTRoss]

That makes sense. Thanks again for your help and all your hard work! 🙏

I'm hearing that my inference above is roughly correct, regarding the two scenarios in which schema definition is required. I'll try to fit it into the docs and PR it.

[dimaMachina]

PR are always welcome !