graphql-modernize
A safe, static codemod for migrating deprecated graphql-ruby APIs
Features · Installation · Quick Start · Configuration · How It Works · Documentation
graphql-modernize migrates deprecated graphql-ruby APIs without booting the
application. It parses Ruby with Prism through astel,
preserves formatting, validates every rewrite, and reports changes before
writing them.
Features
- Static analysis with no application boot or
graphqlgem dependency - Project-wide GraphQL class and inheritance detection
- Safe, unsafe, and manual migration rules
- Formatting-preserving, transactional rewrites
- Syntax validation after every correction
- Unified diff, JSON, GitHub Actions, and SARIF output
- Inline, range, and file-wide suppression directives
- Parallel file processing with deterministic results
- Git safety checks before writing files
Installation
Until the first gem release, add the repository to your Gemfile:
gem "graphql-modernize", github: "ydah/graphql-modernize"Then install:
bundle installRequirements
- Ruby 3.3 or newer
- A Git repository for guarded
--writeoperations
The tool reads graphql-ruby source code but does not depend on or boot the
graphql gem.
Quick Start
Inspect the project and inferred versions:
bundle exec graphql-modernize doctorRun a dry migration and review the diff:
bundle exec graphql-modernize runApply safe corrections:
bundle exec graphql-modernize run --write
git diff
bundle exec rspecUnsafe corrections require an explicit opt-in and can be run one rule at a time:
bundle exec graphql-modernize run --only GQLM307 --unsafe --writeWithout --force, writes require a clean Git working tree. Every target must
be tracked, non-symlinked, and inside that working tree.
Commands
| Command | Description |
|---|---|
graphql-modernize run [PATHS...] |
Detect migrations and optionally rewrite files |
graphql-modernize list |
List available rules and safety levels |
graphql-modernize explain RULE_ID |
Show rule details and migration guidance |
graphql-modernize doctor |
Validate configuration and detected inputs |
graphql-modernize version |
Print the installed version |
Configuration
Create .graphql-modernize.yml in the project root:
from_version: "1.13"
target_version: "2.6"
ruby_version: "3.3"
include:
- "app/graphql/**/*.rb"
- "lib/graphql/**/*.rb"
exclude:
- "app/graphql/legacy/**/*.rb"
base_classes:
object: ["ApplicationObjectType"]
resolver: ["ApplicationResolver"]
schema: ["ApplicationSchema"]
rules:
GQLM401:
enabled: true
GQLM307:
migration_errors: true
apply_unsafe: false
require_suppression_reason: true
iterations: 3| Option | Default | Description |
|---|---|---|
from_version |
Gemfile.lock |
Current graphql-ruby version |
target_version |
Gemfile.lock |
Target graphql-ruby version |
ruby_version |
Current parser default | Ruby syntax version passed to astel |
include |
GraphQL paths under app/ and lib/
|
Ruby file patterns to inspect |
exclude |
vendor/**/*, tmp/**/*
|
Paths excluded from inspection |
base_classes |
{} |
Application-specific GraphQL base classes |
rules |
{} |
Per-rule enablement and options |
apply_unsafe |
false |
Apply unsafe corrections |
require_suppression_reason |
false |
Require a reason on suppression directives |
iterations |
3 |
Rewrite rounds before final convergence retries |
CLI options override configuration. GQLM401 and GQLM402 are disabled by default because they can create large style-only diffs.
Suppression Directives
Suppress a rule on one line:
field :name, types.String # graphql-modernize:disable GQLM105 -- staged migrationSuppress a range:
# graphql-modernize:disable GQLM401 -- keep explicit defaults here
argument :id, ID, required: true
argument :name, String, required: true
# graphql-modernize:enable GQLM401Use graphql-modernize:disable-file GQLM101 -- reason near the top of a file
for file-wide suppression. Unused suppressions are reported as GQLM000.
Output and Exit Status
graphql-modernize run --format json
graphql-modernize run --format github
graphql-modernize run --format sarif --out results.sarif| Status | Meaning |
|---|---|
0 |
No unresolved offenses remain |
1 |
Manual or uncorrected offenses remain |
2 |
Configuration, strict parse, or internal failure |
How It Works
- File discovery expands configured Ruby paths and exclusions.
- Prism parses each file through astel without loading the application.
- A project-wide class hierarchy identifies GraphQL types and schemas.
- Rules register transactional edits against matching AST nodes.
- astel applies edits and validates the rewritten Ruby syntax.
- The CLI reports the result and writes only when
--writeis present.
Documentation
Development
bundle install
bundle exec rake
bundle exec rake buildContributing
Bug reports and pull requests are welcome at https://github.com/ydah/graphql-modernize.
License
Released under the MIT License.