Add static analysis for GraphQL query complexity to prevent regressions

Summary

Following the regression in #580576 (closed) where a GraphQL query exceeded the complexity limit (271 > 250), we need to implement static analysis tooling to detect and prevent GraphQL complexity regressions before they reach production.

Problem

GraphQL queries can exceed complexity limits due to:

  • Adding new fields or nested relationships to existing queries
  • Increasing pagination limits or default values
  • Modifying field complexity scores without testing impact on existing queries
  • Lack of visibility into query complexity during development and code review

The Vulnerability Report regression (#580576 (closed)) affected GitLab Ultimate customers with 366 occurrences in 24 hours, demonstrating the need for proactive detection.

Proposal

Implement static analysis that:

  1. Analyzes GraphQL queries at build/test time to calculate their complexity scores
  2. Fails CI/CD pipelines when queries exceed or approach the complexity limit (250)
  3. Tracks complexity trends for critical queries over time
  4. Provides actionable feedback to developers during code review

Implementation considerations

Tooling options:

  • Leverage existing GraphQL complexity calculation logic from app/graphql/gitlab_schema.rb
  • Create a custom analyzer that parses .graphql files and frontend query definitions
  • Consider tools like graphql-ruby's static query analyzer or custom RSpec matchers

Scope:

  • Analyze queries in app/assets/javascripts/**/*.graphql and ee/app/assets/javascripts/**/*.graphql
  • Include queries defined in Vue components and JavaScript files
  • Test with realistic variable values (e.g., pagination limits, filter combinations)

Integration points:

  • Add to CI pipeline as a required check
  • Integrate with danger-bot for MR warnings when complexity increases
  • Consider adding to pre-commit hooks for immediate developer feedback

Reporting:

  • Generate reports showing query complexity scores
  • Flag queries approaching the limit (e.g., >200) with warnings
  • Track complexity changes in MR diffs

Acceptance criteria

  • Static analysis tool identifies GraphQL queries and calculates their complexity
  • CI pipeline fails when queries exceed the complexity limit of 250
  • Warnings are shown for queries with complexity >200 (80% threshold)
  • Tool provides clear error messages indicating which query failed and its complexity score
  • Documentation added for developers on how to optimize query complexity
  • Existing queries are baselined and tracked for regression detection

Related issues

  • #580576 (closed) - Original regression that prompted this issue
  • #580593 - Investigation into GraphQL complexity errors

Benefits

  • Prevent GraphQL complexity regressions from reaching production
  • Improve developer awareness of query complexity during development
  • Reduce customer impact from complexity-related errors
  • Enable proactive optimization of complex queries
Edited by 🤖 GitLab Bot 🤖