If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rmosolgo/graphql-ruby shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rmosolgo/graphql-ruby repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rmosolgo/graphql-ruby.

What it runs against: a local clone of rmosolgo/graphql-ruby — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rmosolgo/graphql-ruby | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rmosolgo/graphql-ruby. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rmosolgo/graphql-ruby.git
#   cd graphql-ruby
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rmosolgo/graphql-ruby and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rmosolgo/graphql-ruby(\\.git)?\\b" \\
  && ok "origin remote is rmosolgo/graphql-ruby" \\
  || miss "origin remote is not rmosolgo/graphql-ruby (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/graphql.rb" \\
  && ok "lib/graphql.rb" \\
  || miss "missing critical file: lib/graphql.rb"
test -f "lib/graphql/schema.rb" \\
  && ok "lib/graphql/schema.rb" \\
  || miss "missing critical file: lib/graphql/schema.rb"
test -f "lib/graphql/execution/executor.rb" \\
  && ok "lib/graphql/execution/executor.rb" \\
  || miss "missing critical file: lib/graphql/execution/executor.rb"
test -f "lib/graphql/language/parser.rb" \\
  && ok "lib/graphql/language/parser.rb" \\
  || miss "missing critical file: lib/graphql/language/parser.rb"
test -f "lib/graphql/type/definition.rb" \\
  && ok "lib/graphql/type/definition.rb" \\
  || miss "missing critical file: lib/graphql/type/definition.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rmosolgo/graphql-ruby"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

graphql-ruby is a complete Ruby implementation of the GraphQL specification, enabling developers to build GraphQL servers and parse GraphQL queries natively in Ruby. It provides a full-featured runtime with type system, query execution, validation, and introspection, plus optional C-based parsing (via graphql-c_parser) for performance. The gem ships with Rails scaffolding generators and supports Relay patterns out of the box. Monolithic gem structure: lib/ contains the main GraphQL engine (type system, execution, validation), graphql-c_parser/ is a native extension for parsing, benchmark/ holds performance test suites, spec/ contains comprehensive test coverage, and lib/generators/graphql holds Rails integration scaffolding. Gemfiles directory manages CI matrix for different Rails/dependency versions.

Ruby/Rails developers building GraphQL APIs who want native language support without external service dependencies. Also used by gem maintainers extending GraphQL functionality (Pro, Relay, Enterprise plugins). Contributors range from Ruby community members to teams operating production GraphQL services at scale.

Highly mature and production-ready. The repo shows 3.5M lines of Ruby, active CI via GitHub Actions (ci.yaml workflow), multiple parallel gemfile configurations testing Rails 7.2–8.1+master branches, and deep changelog history (CHANGELOG.md, CHANGELOG-pro.md, CHANGELOG-relay.md, CHANGELOG-enterprise.md). This is an established, well-maintained project with commercial backing (GraphQL::Pro subscriptions).

Low technical risk for core library usage; moderate risk for adopters of bleeding-edge features. The C parser extension (graphql-c_parser/) introduces native code compilation complexity (extconf.rb, lexer.rl → lexer.c). Heavy reliance on single maintainer (rmosolgo) for core—though Pro/Enterprise tiers suggest organizational support. Breaking changes are released per semantic versioning but require migration effort on major bumps.

Actively developed with continuous integration testing across Rails 7.2, 8.0, 8.1, and master branches (visible in gemfiles/ and .github/workflows/). The project maintains separate enterprise and pro feature tracks (CHANGELOG-enterprise.md, CHANGELOG-pro.md). Recent activity focuses on Rails 8.x compatibility and performance optimizations (evidenced by benchmark/ suite).

git clone https://github.com/rmosolgo/graphql-ruby.git
cd graphql-ruby
bundle install
bundle exec rake test

Daily commands:

bundle exec rake # runs test suite
bundle exec rake benchmark:run # runs performance benchmarks
# For Rails integration: rails generate graphql:install

• lib/graphql.rb — Entry point and main module namespace for the entire GraphQL implementation; defines the public API surface
• lib/graphql/schema.rb — Core schema definition and validation engine; every GraphQL query execution depends on schema structure
• lib/graphql/execution/executor.rb — Query execution engine that resolves fields and handles the entire GraphQL lifecycle from parse to result
• lib/graphql/language/parser.rb — Parses GraphQL query strings into AST; foundation for query validation and execution
• lib/graphql/type/definition.rb — Base type system implementation (ObjectType, InterfaceType, etc.); defines how fields and types are structured
• graphql.gemspec — Gem manifest and dependency declaration; critical for understanding Ruby version requirements and optional dependencies

• Schema (Ruby classes, introspection) — Stores type definitions, field signatures, directives, and validation rules; acts as the contract for all queries
  • Failure mode: Invalid schema definition → GraphQL errors at execution time; missing types → validation failures
• Parser (Ruby Lexer/Parser or C extension) — Converts GraphQL query strings into an abstract syntax tree; tokenizes input and enforces GraphQL grammar
  • Failure mode: Malformed query → parse error with line/column info; C parser missing → falls back to Ruby (slower)
• Validator (Visitor pattern over AST) — Checks AST against schema and GraphQL spec rules (e.g., no undefined fields, no cycles in fragments, correct variable types)
  • Failure mode: Invalid query → validation errors returned before execution; skipped if schema.validation_rules is empty

Add a custom scalar type

1. Create a new class inheriting from GraphQL::ScalarType in your schema file or a dedicated scalars directory (lib/graphql/type/definition.rb (reference implementation))
2. Implement serialize, parse_value, and parse_literal methods to define how the scalar converts to/from JSON and GraphQL literal values (lib/graphql/type/definition.rb (see ScalarType class))
3. Register the scalar in your schema by adding it to schema.types or field definitions (lib/graphql/schema.rb (example: schema.orphan_types))

Add a new field resolver with dataloader

1. Define a field in your ObjectType with a resolve block or method (lib/graphql/type/definition.rb (see field definition examples))
2. Use context.dataloader to queue batch loading operations instead of direct queries (lib/graphql/dataloader.rb (see DataLoader#batch and #load APIs))
3. Define a corresponding DataLoader source class that batches the actual database queries in the load_many method (lib/graphql/dataloader.rb (see example datasources))

Add authorization/visibility to a field

1. Add a visible? or authorize? block to your field definition (lib/graphql/type/definition.rb (field options))
2. Implement logic that checks context.current_user or other context values to determine field visibility or access (guides/authorization/visibility.md (reference patterns))
3. Return false/nil to hide the field or raise GraphQL::ExecutionError to return an error in the response (lib/graphql/error.rb (error handling))

Add a custom validation rule

1. Create a class inheriting from GraphQL::StaticValidation::ValidationRule in lib/graphql/validation/rules/ (lib/graphql/validation/rules.rb (base class))
2. Implement on_enter and on_leave methods to traverse the query AST and collect violations (lib/graphql/language/visitor.rb (AST visitor pattern))
3. Register the rule in your schema via schema.validation_rules or pass it to context (lib/graphql/schema.rb (validation_rules configuration))

• Ruby as primary language — Native integration with Rails ecosystem; allows middleware and introspection at runtime; good for rapid prototyping and metaprogramming
• Optional C parser (graphql-c_parser) — Parsing large/complex queries is CPU-intensive; C extension provides 3–5× speedup for production workloads while maintaining Ruby fallback
• DataLoader for batch operations — Prevents N+1 query problems in nested resolvers; standardizes batching across databases and APIs; matches GraphQL best practices
• Relay spec support — Standardizes cursor-based pagination and mutations; enables interop with Apollo Client and other Relay-compliant frameworks

• Pure Ruby parser with optional C fallback

  • Why: Ruby parser is maintainable and always available; C parser is optional (requires compilation) but much faster
  • Consequence: Default setup is slower but more portable; users must opt-in to C parser for performance gains

• Executor and Interpreter as two separate execution strategies

  • Why: Executor is simple and compatible with older versions; Interpreter is faster for complex queries
  • Consequence: Code duplication and maintenance overhead; users must choose between compatibility and performance

• Schema validation at schema build time, not parse time

  • Why: Catches errors early and avoids repeated validation per query; enables optimizations
  • Consequence: Schema errors are discovered when gem loads, not when query fails; harder to dynamically modify schema at runtime

• Subscriptions via Redis Pub/Sub by default

  • Why: Works with distributed systems and multiple processes; doesn't require WebSocket library in core
  • Consequence: Requires external Redis dependency for subscriptions; simple setups must manage Redis infrastructure

• Not a GraphQL server framework (no HTTP routing or deployment utilities; see graphql-rails or other gems for that)
• Not a real-time protocol implementation (subscriptions are implemented via pub/sub, not strict GraphQL over WebSocket)
• Not database-agnostic; requires explicit resolver code for ORM integration
• Does not provide authentication/authorization primitives (that responsibility is on the schema author)

1. C Parser Optional But Not Default: graphql-c_parser requires native compilation (extconf.rb). On systems without build tools, parsing falls back to pure Ruby—silently slower. Check GraphQL::Language::Parser.default_parser to verify which is active. 2. Rails Generator Mutates Gemfile: rails generate graphql:install modifies the Gemfile directly (adds graphiql-rails, graphql-pro dependencies); no dry-run mode. 3. Custom Cop Rules Required for Development: cop/development/ contains lint rules (ContextIsPassedCop, NoEvalCop, TraceMethods). Contributing code without running bundle exec rubocop will fail CI. 4. Gemfile Matrix for Testing: Separate gemfiles/ for mongoid_8/9, rails_7.2, rails_8.0+master. You must test against the specific Rails version the feature targets; bundle exec rake test uses your Gemfile only. 5. Spec/Changelog Duplication: Four separate CHANGELOG files (CHANGELOG.md, CHANGELOG-pro.md, CHANGELOG-relay.md, CHANGELOG-enterprise.md) require coordination when releasing; easy to forget a file.

• GraphQL Execution Algorithm — Core to lib/graphql/execution/executor.rb; understanding how queries are resolved, fields traversed, and resolvers called is essential for debugging and optimizing resolvers
• Type Coercion & Serialization — lib/graphql/types/ implements coerce_input/coerce_result for scalar types; misunderstanding this causes bugs in field resolvers and custom scalar definitions
• Lexer & Parser (Ragel) — graphql-c_parser/ext/graphql_c_parser_ext/lexer.rl is compiled via Ragel → C; understanding tokenization (lexing) vs AST building (parsing) matters for debugging parse errors and contributing performance improvements
• GraphQL Validation Rules — lib/graphql/validation/rules/ implements 30+ spec-mandated rules (FieldsOnCorrectType, PossibleFragmentSpreads, etc.); contributors extending validation or debugging unexpected query rejections must understand the rule system
• Relay Cursor Connections — CHANGELOG-relay.md and graphql-relay-ruby integrate cursor-based pagination patterns; teams using Relay must understand how global IDs, edges, and pageInfo are encoded
• Introspection & Schema Reflection — lib/graphql/types/__schema.rb implements GraphQL's self-descriptive introspection; critical for developer tooling (GraphiQL), documentation generation, and client code generation
• Middleware & Plugin Hooks — graphql-ruby supports trace hooks and middleware chains for observability, authorization, and caching; understanding lib/graphql/execution/execute.rb's instrumentation APIs enables custom middleware

• graphql/graphql-js — Reference GraphQL implementation in JavaScript; graphql-ruby maintains spec parity with this, useful for comparing behavior on edge cases
• rmosolgo/graphql-relay-ruby — Relay.js server-side helpers and patterns for graphql-ruby; used by teams implementing Relay pagination, global IDs, and mutations
• rails/rails — graphql-ruby ships Rails generators and active integration tested against Rails 7.2–8.1+ in CI; understanding Rails conventions is essential
• apollo-server/apollo-server — Apollo's Node.js GraphQL server; graphql-ruby is often compared against Apollo on feature set and performance; useful for backporting ideas
• strawberry-graphql/strawberry — Modern Python GraphQL framework; represents alternative design patterns (dataclass-based types, async-first) that inform graphql-ruby architecture discussions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for graphql-c_parser C extension edge cases

The graphql-c_parser subdirectory contains C code (lexer.c, parser.c) with no visible test files in the file structure. Given this is a critical parsing component used by the main gem, adding tests for edge cases (malformed queries, deeply nested fragments, large queries) would improve reliability and catch regressions early. This is especially important since C code behavior varies across platforms.

• [ ] Create spec/graphql/c_parser_spec.rb (or similar) to test graphql-c_parser/lib/graphql/c_parser.rb
• [ ] Add test cases for edge cases: invalid syntax, deeply nested selections, large query documents, Unicode handling
• [ ] Add integration tests comparing C parser output with the Ruby fallback parser for consistency
• [ ] Verify tests pass across supported Ruby versions in CI

Create GitHub Action workflow for testing against multiple Node.js versions for graphql-ruby-client

The package.json shows graphql-ruby-client is a JavaScript package with node >=10 engine requirement, but .github/workflows only shows Ruby-focused CI (ci.yaml, pronto.yaml, website.yaml). There's no dedicated Node.js testing workflow. Adding a CI job would catch compatibility issues with supported Node versions and catch dependency breakage early.

• [ ] Create .github/workflows/javascript-ci.yaml that runs npm test across Node versions 14, 16, 18, 20
• [ ] Include steps to run: npm install, npm run test, and TypeScript compilation (tsc)
• [ ] Add matrix strategy to test against multiple GraphQL peer dependency versions (>=14.3.1, >=15.0.0)
• [ ] Ensure the workflow is triggered on pushes to main/master and pull requests affecting JavaScript files

Add integration tests for schema parsing with all Gemfile configurations

The gemfiles/ directory contains 6+ Gemfile variants (mongoid_8, rails_7.2, rails_8.0, rails_master, etc.) but there's no evidence of integration tests that verify the gem works correctly with each dependency combination. This is critical for a widely-used library to catch subtle compatibility regressions.

• [ ] Create spec/integration/gemfile_compatibility_spec.rb to test core functionality against real gem combinations
• [ ] Add tests verifying: schema definition, query execution, and basic validation work with each Gemfile
• [ ] Update .github/workflows/ci.yaml to run test suite once for each gemfile (similar to Dependabot's matrix testing)
• [ ] Document in .github/contributing.md how to locally test against different Gemfile configurations

• Add missing validation rule documentation: lib/graphql/validation/rules/ contains ~30 rule classes but lib/graphql/validation/ lacks a rules overview file mapping rule names to descriptions. Create spec/graphql/validation/rules/RULES_GUIDE.md linking each rule to its use case.: Low-risk documentation contribution; no code changes, helps onboarding
• Extend benchmark suite for recently added features: benchmark/ has big_query.graphql, abstract_fragments.graphql but no benchmarks for subscriptions, deferred queries, or streaming payloads (GraphQL::Pro features). Add benchmark_streaming.rb to measure defer/stream execution time.: Tooling improvement; shows performance implications of new patterns; unblocks optimization discussions
• Fill in missing type coercion tests: lib/graphql/types/ defines scalar coercion but spec/graphql/types/coercion_spec.rb likely lacks edge cases (null handling, custom scalar conversion failures, Date/Time coercion in different timezones). Add 5–10 edge case tests.: Strengthens robustness of a core subsystem; reproducible test writing; low risk of breaking changes

• High · Outdated TypeScript Version — package.json - devDependencies.typescript. TypeScript 5.3.3 is pinned in package.json devDependencies. This version is from late 2023 and may contain known vulnerabilities. TypeScript should be regularly updated to the latest stable version to receive security patches and improvements. Fix: Update TypeScript to the latest stable version (6.0+) and regularly audit for security updates. Use npm audit to identify and fix vulnerabilities.
• High · Vulnerable Dependency: glob ^13.0.6 — package.json - dependencies.glob. The glob package version ^13.0.6 in dependencies may have known vulnerabilities. The glob package has had a history of security issues related to path traversal and denial of service attacks. Fix: Run npm audit to identify specific vulnerabilities. Update to the latest patched version of glob and implement security updates as they are released. Consider using npm ci for deterministic installations.
• Medium · Permissive Node Engine Requirement — package.json - engines.node. The package.json specifies Node.js >=10, which is extremely outdated. Node.js 10 reached end-of-life in April 2021 and no longer receives security updates. This allows installation on vulnerable Node versions. Fix: Update the minimum Node.js requirement to at least LTS version 18.x or higher (e.g., '>=18.0.0'). This ensures users are running supported versions with active security patches.
• Medium · Pinned C Parser Extension — graphql-c_parser/ext/graphql_c_parser_ext/. The graphql-c_parser subdirectory contains C extensions (lexer.c, parser.c) which require compilation. C code vulnerabilities could lead to buffer overflows, memory corruption, or arbitrary code execution if not properly validated. Fix: Conduct regular security audits of C code, use static analysis tools (e.g., cppcheck, clang-analyzer), implement input validation, and use memory-safe practices. Keep dependencies like Ragel (used in lexer.rl) updated.
• Medium · Outdated Ably Dependency — package.json - devDependencies.ably. Ably version 1.2.50 is pinned in devDependencies. This is a significantly outdated version from 2021 that may contain known security vulnerabilities. Ably is a critical dependency for real-time functionality. Fix: Update Ably to the latest available version (currently 2.x). Run npm audit to identify specific vulnerabilities and apply patches regularly.
• Low · Missing Security Configuration Files — Repository root. While the repository contains .codeclimate.yml for code quality and .rubocop.yml for linting, there is no visible security policy file (SECURITY.md), no security scanning configuration in GitHub workflows beyond standard CI/CD, and no evidence of dependabot security updates being enforced. Fix: Add SECURITY.md to document vulnerability reporting procedures. Enable GitHub security features like Dependabot alerts, secret scanning, and code scanning (CodeQL). Add security checks to CI/CD workflows.
• Low · Broad Dependency Version Ranges — package.json - devDependencies. Several dependencies use permissive version ranges (^) in devDependencies which could introduce breaking changes or security issues. Examples: @apollo/client >=3.3.13, @types/node ^18.0.0, jest ^29.0.0. Fix: Use more restrictive version ranges (e.g., ~18.0.0 instead of ^18.0.0) for critical dependencies. Regularly run npm audit and npm update with caution. Consider using lock files and npm ci for production deployments.
• Low · No Explicit Security Headers Configuration — guides/ directory and related configuration. The guides directory contains documentation but there is no visible security headers configuration (e.g., no CSP, HSTS, X-Frame-Options setup) in the provided files. Fix: Document security best practices for implementing GraphQL security headers. Provide examples of Content Security Policy, X-Frame-Options, and other security headers in

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.