feat: introduce graphql linting by tatomyr · Pull Request #2856 · Redocly/redocly-cli

tatomyr · 2026-06-05T14:29:18Z

What/Why/How?

Added experimental graphql linting.

Reference

Testing

Screenshots (optional)

Check yourself

This PR follows the contributing guide
All new/updated code is covered by tests
Core code changed? - Tested with other Redocly products (internal contributions only)
New package installed? - Tested in different environments (browser/node)
Documentation update has been considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

Note

Medium Risk
New lint path and dependency affect core lint/resolve behavior for GraphQL files only; feature is experimental and well-tested but expands the config/rules surface area.

Overview
Adds experimental GraphQL SDL linting for .graphql / .gql files through redocly lint, wired as a new graphql spec alongside existing OpenAPI-style formats.

Core engine: .graphql/.gql paths skip YAML parsing and use graphql-js to parse SDL and run AST visitors. Built-in rules include struct (syntax + buildASTSchema / validateSchema), no-unused-types, and type-description, plus assertions via a GraphQL adapter that reuses shared configurable-rule checks on AST kinds (ObjectTypeDefinition, etc.). The graphql ruleset omits no-unresolved-refs; bundle treats GraphQL as non-bundlable.

Config & CLI: graphqlRules in presets, graphql plugin rules, config schema extended with GraphQL AST kinds for subject.type, and checkIfRulesetExist counts GraphQL rules. New graphql dependency on @redocly/openapi-core.

Docs & tests: New lint-graphql guide, lint command cross-links, changeset (minor), unit and e2e coverage for valid/invalid schemas and per-api configurable rule severity.

^{Reviewed by Cursor Bugbot for commit 9c8e4ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-06-05T14:29:24Z

🦋 Changeset detected

Latest commit: 9c8e4ce

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-06-05T14:31:32Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	81.69% (🎯 81%)	7586 / 9286
🔵	Statements	81.04% (🎯 80%)	7893 / 9739
🔵	Functions	85.01% (🎯 84%)	1526 / 1795
🔵	Branches	73.24% (🎯 73%)	5122 / 6993

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/utils/miscellaneous.ts	61.67%	58.2%	78.04%	60.97%	75, 140, 197-247, 273-274, 284-285, 300, 304, 307, 313, 317-320, 328-361, 372, 397, 406, 414-452, 567, 576
packages/core/src/detect-spec.ts	90.9%	92.42%	100%	90.9%	20-23, 29
packages/core/src/lint.ts	91.89%	85.71%	100%	91.66%	108-119, 142
packages/core/src/oas-types.ts	100%	100%	100%	100%
packages/core/src/resolve.ts	95.34%	94.69%	100%	95.2%	94, 141, 285, 460-468
packages/core/src/bundle/bundle-visitor.ts	72.72%	68.42%	100%	72.72%	37, 41-49, 60-64, 71, 80, 88, 93-118, 188-200, 217-218, 236-237, 251-252, 285
packages/core/src/config/all.ts	100%	100%	100%	100%
packages/core/src/config/builtIn.ts	100%	100%	100%	100%
packages/core/src/config/config-resolvers.ts	76.21%	60.98%	94.11%	77.01%	73, 101-104, 154, 193, 201, 257, 268, 277, 290, 300, 303-307, 312-321, 345-347, 357, 360, 363, 366, 369, 372, 385-387, 391, 397, 400, 403-406, 409-412, 415-418, 432-434, 441, 444, 447, 450, 453, 456, 481-483, 488-494
packages/core/src/config/config.ts	62.96%	64.58%	75.6%	63.09%	179-209, 235, 239, 243-264, 296, 314-334, 418-448
packages/core/src/config/minimal.ts	100%	100%	100%	100%
packages/core/src/config/recommended-strict.ts	100%	100%	100%	100%
packages/core/src/config/recommended.ts	100%	100%	100%	100%
packages/core/src/config/rules.ts	100%	100%	100%	100%
packages/core/src/config/spec.ts	100%	100%	100%	100%
packages/core/src/config/utils.ts	97.4%	81.81%	100%	98.68%	35, 84-86
packages/core/src/graphql/assertions.ts	95%	87.23%	100%	98.11%	39, 42, 63-65
packages/core/src/graphql/detect-graphql.ts	100%	100%	100%	100%
packages/core/src/graphql/lint-graphql.ts	95.23%	50%	100%	95%	32
packages/core/src/graphql/visitor.ts	92%	81.48%	100%	100%	54, 111
packages/core/src/rules/utils.ts	92%	88.7%	100%	91.3%	65, 99, 109-113, 129, 140-144, 237
packages/core/src/rules/common/struct.ts	97.22%	91.78%	100%	97.01%	79-83, 190-194
packages/core/src/rules/common/assertions/utils.ts	84%	65.51%	69.23%	88.29%	50, 54, 58, 83-85, 89-91, 142, 163-165, 172, 184-192, 252, 272-273, 289
packages/core/src/rules/graphql/index.ts	100%	100%	100%	100%
packages/core/src/rules/graphql/no-unused-types.ts	100%	73.07%	100%	100%
packages/core/src/rules/graphql/struct.ts	66.66%	33.33%	75%	66.66%	18, 27, 32-42
packages/core/src/rules/graphql/type-description.ts	100%	100%	100%	100%
packages/core/src/types/redocly-yaml.ts	92.92%	84.9%	100%	92.7%	412, 444, 450, 494-501, 503, 662-667, 670-675

Generated in workflow #10375 for commit 9c8e4ce by the Vitest Coverage Report Action

github-actions · 2026-06-05T14:33:02Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)
cli-next	▓ 1.01x ± 0.01	▓ 1.00x ± 0.01	▓ 1.03x ± 0.01

RomanHotsiy · 2026-06-08T09:27:03Z

+'@redocly/cli': minor
+---
+
+Added initial support for linting GraphQL SDL schema files (`.graphql` / `.gql`).


Let's mark it as experimental for now

RomanHotsiy · 2026-06-08T09:30:13Z

      "operation-summary": "error",
    },
+    "graphql": {
+      "no-empty-servers": "error",


what is this?

Those are unused rules propagated from the root rules config section.

RomanHotsiy · 2026-06-08T09:37:54Z

+import type { Config } from './config/index.js';
+import { initRules } from './config/rules.js';
+import { isGraphqlRef } from './graphql/extensions.js';
+import { runGraphqlRules, type InitializedGraphqlRule } from './graphql/run.js';


let's use dynamic import here so it won't load for everyone and slow them down

I haven't noticed any perf degradation so far. Would you still like to have it imported dynamcally?

AlbinaBlazhko17 · 2026-06-16T17:28:01Z

+## GraphQL rules
+
+To expand the linting checks for a GraphQL schema, enable the built-in GraphQL rules.
+Unlike the shared `struct` rule (configured under `rules`), GraphQL-specific built-in rules are configured under the `graphqlRules` section.


Looks like we have mismatch in docs. We can also configure graphQL specific rules under rules section, you are listed this below.

AlbinaBlazhko17 · 2026-06-16T17:30:19Z

+  for (const kind of Object.keys(visitor) as Array<keyof GraphqlVisitor>) {
+    const handler = visitor[kind];
+    if (!handler) continue;
+    const enter = typeof handler === 'function' ? handler : handler.enter;


Did you miss the skip visitor or you leave it for the future implementation?

I haven't found a proper use case for it in GraphQL. We can implement it later if needed.

AlbinaBlazhko17 · 2026-06-16T17:36:30Z

    "cookie": "^0.7.2",
    "dotenv": "16.4.7",
    "glob": "^13.0.5",
+    "graphql": "^16.14.1",


I haven't found where we use this package. Could you please explain the purpose of this package?

For example, in packages/core/src/graphql/visitor.ts or in packages/core/src/graphql/lint-graphql.ts for parsing the docs AST.

Oh, you mean in the CLI package? Yes, it was a transitive one, not needed anymore.

AlbinaBlazhko17 · 2026-06-17T14:00:31Z

+  config: Config;
+}): NormalizedProblem[] {
+  const { document, config } = opts;
+  const source = document.source;


Could you please add a guard for the empty GraphQL file to return Unexpected <EOF> error.

AlbinaBlazhko17 · 2026-06-17T14:10:31Z

+
+  // GraphQL SDL is not a JSON/YAML tree, so it runs through a separate engine.
+  if (isGraphqlRef(document.source.absoluteRef)) {
+    return lintGraphqlDocument({ document, config });


I think, that we can add dynamic imports for the GraphQL in the lint command, because now we have esbuild and chunks, so the dynamic import should go to the separate chunk. It should decrease the influence of the GraphQL on the performance.

AlbinaBlazhko17 · 2026-06-17T14:17:46Z

@@ -481,6 +487,7 @@ function createAssertionDefinitionSubject(nodeNames: string[]): NodeType {
      type: {
        enum: [...new Set(['any', ...nodeNames, 'SpecExtension'])],
        description: 'REQUIRED. Locates the OpenAPI node type that the lint command evaluates.',


I am wondering if we add assertions for the GraphQL, do we need to add GraphQL mention there? Or currently it's just an experimental feature?

Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9c8e4ce. Configure here.}

cursor · 2026-06-22T07:08:22Z

+      return [syntaxErrorToProblem(e, source)];
+    }
+    throw e;
+  }


Empty GraphQL file unguarded

Medium Severity

Linting does not treat a wholly empty GraphQL file as a parse failure before parse runs. An empty or whitespace-only body can parse to an empty document and skip the explicit Unexpected <EOF>-style syntax error expected for empty SDL.

^{Reviewed by Cursor Bugbot for commit 9c8e4ce. Configure here.}

tatomyr self-assigned this Jun 5, 2026

RomanHotsiy reviewed Jun 8, 2026

View reviewed changes

tatomyr requested a review from RomanHotsiy June 12, 2026 08:07

tatomyr force-pushed the feat/lint-graphql branch from 7f3750d to 7bd109c Compare June 12, 2026 08:15

tatomyr marked this pull request as ready for review June 12, 2026 08:15

tatomyr requested review from a team as code owners June 12, 2026 08:16

cursor Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread packages/core/src/rules/graphql/no-unused-types.ts

Comment thread packages/core/src/graphql/visitor.ts

Comment thread packages/core/src/config/config.ts

JLekawa reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/@v2/guides/lint-graphql.md Outdated

JLekawa approved these changes Jun 12, 2026

View reviewed changes

tatomyr force-pushed the feat/lint-graphql branch 2 times, most recently from 8723a0d to 73e2aff Compare June 16, 2026 08:18

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread packages/core/src/graphql/assertions.ts

Comment thread packages/core/src/graphql/lint-graphql.ts

tatomyr force-pushed the feat/lint-graphql branch from 73e2aff to 6bdd8fe Compare June 16, 2026 14:35

AlbinaBlazhko17 reviewed Jun 16, 2026

View reviewed changes

cursor Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread packages/core/src/config/config.ts

tatomyr force-pushed the feat/lint-graphql branch from 2b29c2e to c580a1b Compare June 17, 2026 06:10

AlbinaBlazhko17 reviewed Jun 17, 2026

View reviewed changes

tatomyr added 4 commits June 22, 2026 09:49

feat: introduce graphql linting

bc205c8

resolve fixmes and the unused no-unresolved-refs rule warning

47c55cb

refactor visitor and linter; partially resolve review

5b2581c

add graphql to cli as well

45693e9

tatomyr and others added 15 commits June 22, 2026 09:49

remove redundant wrapper

4000e8f

unify InitializedGraphqlRule

147dcfa

enable linting by configurable rules

5b5c671

remove type-pascal-case

234684e

fix configurable rules by adding the where

495018a

make the built-in rule off in recommended

f976901

add graphql visitor types

ee1224c

add no-unused-types rule

56f4e8a

Apply suggestions from code review

9c35eb1

Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>

Apply suggestion from @JLekawa

5160daf

fix indentation

9635534

treat schema definitions and extensions differently

953461c

deslop

f689689

fix docs

e3530af

fix package-lock

9c8e4ce

tatomyr force-pushed the feat/lint-graphql branch from b69ae8e to 9c8e4ce Compare June 22, 2026 07:05

tatomyr marked this pull request as draft June 22, 2026 07:08

cursor Bot reviewed Jun 22, 2026

View reviewed changes

Conversation

tatomyr commented Jun 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

github-actions Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlbinaBlazhko17 Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 22, 2026

Choose a reason for hiding this comment

Empty GraphQL file unguarded

tatomyr commented Jun 5, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Jun 5, 2026 •

edited

Loading

github-actions Bot commented Jun 5, 2026 •

edited

Loading

github-actions Bot commented Jun 5, 2026 •

edited

Loading

AlbinaBlazhko17 Jun 16, 2026 •

edited

Loading