graphql-modernize 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 367624e4b4eb0dcd521cc6d637179eccebeebd2a97d1ec6b4a074496a693d2a7
+  data.tar.gz: 1b144aa928b31103102daffa6cfd6de727dee13fdd89ad5fd4b87bc1e52137f5
+SHA512:
+  metadata.gz: 9a0c14c313ab2c390d8aa22794a90246c1c5ed394d75820f83c1f5e2a3e3d784458eac33ee829e25d44e3f5b5223af0ac1535929c9ececb57800306decccf9bb
+  data.tar.gz: ec31abe6cae4bf0be75fa509e3c08b4e7f9f4e241541a0734d07e44b50abd2051a220b186ad4edddd0c1908b944ebe2488a783a5a290976c7878a6ae08027a16

data/.rubocop.yml

@@ -0,0 +1,40 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.3
+  UseCache: false
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Max: 100
+
+Metrics/BlockLength:
+  Exclude:
+    - "*.gemspec"
+    - "spec/**/*"
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ParameterLists:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Style/Documentation:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-08-31
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# graphql-modernize
+
+`graphql-modernize` migrates deprecated graphql-ruby APIs without booting the
+application. It parses Ruby with Prism through [astel](https://github.com/ydah/astel),
+preserves formatting, validates every rewrite, and reports changes before writing.
+
+## Installation
+
+```bash
+bundle add graphql-modernize
+```
+
+Ruby 3.3 or newer is required. The tool does not depend on the `graphql` gem.
+
+## Quick start
+
+Start with a dry run:
+
+```bash
+bundle exec graphql-modernize run
+```
+
+Review the unified diff, then apply safe rules:
+
+```bash
+bundle exec graphql-modernize run --write
+git diff
+bundle exec rspec
+```
+
+Without `--force`, writes require a clean Git working tree and every target
+must be a tracked, non-symlinked path inside that working tree.
+
+Unsafe rules require an explicit opt-in and can be run one at a time:
+
+```bash
+bundle exec graphql-modernize run --only GQLM307 --unsafe --write
+```
+
+Useful commands:
+
+```text
+graphql-modernize list
+graphql-modernize explain GQLM307
+graphql-modernize doctor
+graphql-modernize run --format json
+graphql-modernize run --format github
+graphql-modernize run --format sarif --out results.sarif
+```
+
+Exit status is `0` when no unresolved offenses remain, `1` when manual or
+unfixed offenses remain, and `2` for configuration, parse (`--strict`), or
+internal errors.
+
+## Configuration
+
+Create `.graphql-modernize.yml` in the project root:
+
+```yaml
+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"]
+rules:
+  GQLM401:
+    enabled: true
+  GQLM307:
+    migration_errors: true
+apply_unsafe: false
+require_suppression_reason: true
+```
+
+CLI options override configuration. GQLM401 and GQLM402 are disabled by
+default because they can create large style-only diffs.
+
+## Suppression comments
+
+```ruby
+field :name, types.String # graphql-modernize:disable GQLM105 -- staged migration
+
+# graphql-modernize:disable GQLM401 -- keep explicit defaults here
+argument :id, ID, required: true
+# graphql-modernize:enable GQLM401
+```
+
+Use `graphql-modernize:disable-file GQLM101 -- reason` near the top of a file
+for file-wide suppression. Unused suppressions are reported as GQLM000.
+
+See [the migration guide](docs/migration-guide.md), [rule index](docs/rules/README.md),
+and [rule authoring guide](docs/writing-rules.md).
+
+## Development
+
+Run `bundle install`, then `bundle exec rake`. Build the gem with
+`bundle exec rake build`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/ydah/graphql-modernize>.
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[spec rubocop]

data/docs/migration-guide.md

@@ -0,0 +1,23 @@
+# Migration guide
+
+## 1.13 to 2.x
+
+1. Run `bundle exec graphql-modernize run` and review the proposed safe changes.
+2. Apply them with `--write`, then run the application's tests.
+3. Run GQLM102 separately with `--unsafe`; resolve its manual fallbacks and
+   GQLM101, GQLM104, and GQLM108 before updating.
+4. Apply each unsafe superclass or Relay migration separately with
+   `--only RULE --unsafe --write` and test it.
+5. Update graphql-ruby and rerun the tool with the target version.
+
+## 2.3 to 2.6
+
+1. Remove obsolete execution and pagination settings with the safe rules.
+2. Review type-index consumers reported by GQLM308.
+3. Run GQLM307 by itself. Keep `migration_errors: true` while comparing Warden
+   and Visibility, then remove that option after the differences are resolved.
+4. Decide the validation and complexity migration modes reported by GQLM310
+   and GQLM501 before accepting the new behavior.
+
+Always review `git diff`; the tool deliberately leaves application-specific
+choices as manual offenses.

data/docs/research/changelog-survey.md

@@ -0,0 +1,68 @@
+# graphql-ruby migration survey
+
+Surveyed against graphql-ruby's `CHANGELOG.md` through 2.6.10 (2026-08-27),
+the historical official upgrader, rubocop-graphql's cop list, and astel 0.2.0.
+
+## Rules selected for the first releases
+
+| Rule | Upstream boundary | Static | Correction | Safety |
+|---|---:|---|---|---|
+| GQLM101 `.define` DSL | deprecated 1.10 | yes | guidance only | manual |
+| GQLM102 `resolve:` field option | removed 2.0.1 | yes | simple lambda to method | unsafe/manual fallback |
+| GQLM103 `GraphQL::Function` | removed 2.0 | yes | superclass replacement | unsafe |
+| GQLM104 `to_graphql` / `graphql_definition` | deprecated 1.13 | yes | guidance only | manual |
+| GQLM105 `types.X` | class API migration | yes | remove `types.` | safe |
+| GQLM106 `property:` | class API migration | yes | rename to `method:` | safe |
+| GQLM107 `field:` / `function:` | removed 2.0.1 | yes | remove option | safe |
+| GQLM108 `GraphQL::Query::Arguments` | removed 2.0 | yes | guidance only | manual |
+| GQLM201 Relay mutation | class API migration | yes | superclass replacement | unsafe |
+| GQLM205 load failure error | renamed 1.9.4 | yes | constant replacement | safe |
+| GQLM301 Interpreter plugin | default since 1.12 | yes | remove line | safe |
+| GQLM302 Analysis::AST plugin | default since 1.12 | yes | remove line | safe |
+| GQLM303 Connections plugin | default since 1.12 | yes | remove line | safe |
+| GQLM304 `error_bubbling(true)` | deprecated 2.2.7 | yes | guidance only | manual |
+| GQLM305 bidirectional pagination setting | deprecated 1.13.10 | yes | remove line | safe |
+| GQLM306 default nodes setting | deprecated 1.13.10 | yes | remove line | safe |
+| GQLM307 custom `visible?` without visibility plugin | required since 2.4.0 | project scan | insert plugin | unsafe |
+| GQLM308 possible type/reference keys | changed 2.3.5 | yes | guidance only | manual |
+| GQLM310 empty Union selections | deprecated behavior 2.5.3 | schema scan | guidance only | manual |
+| GQLM401 `required: true` | default since 1.13.0 | yes | remove option | safe, opt-in |
+| GQLM402 `null: true` | default since 1.13.0 | yes | remove option | safe, opt-in |
+| GQLM501 complexity cost mode | migration support 2.5.3 | schema scan | guidance only | manual |
+
+The remaining catalog entries need application-specific intent or do not have a
+single generally correct rewrite, so they are reported as manual guidance.
+
+GraphQL-Ruby 2.6.3 requires `Schema::Visibility` to be attached after root type
+configuration, so GQLM307 appends the plugin. GraphQL-Ruby 2.5.15 added the
+type-aware `legacy_invalid_empty_selections_on_union_with_type` hook; GQLM310
+recognizes either legacy-selection hook as an explicit policy.
+
+## Existing tools
+
+The removed official `GraphQL::Upgrader` targeted the `.define` to class API
+migration. Its transforms mixed regular expressions with `parser` AST
+processing and did not cover later 2.x deprecations.
+
+rubocop-graphql has `LegacyDSL`, but no equivalents of graphql-ruby's bundled
+`GraphQL/DefaultNullTrue` and `GraphQL/DefaultRequiredTrue` cops. GQLM401 and
+GQLM402 therefore overlap graphql-ruby's bundled cops and remain disabled by
+default. GQLM403 is omitted: graphql-ruby's `GraphQL/FieldTypeInBlock` enforces
+the opposite shape for lazy loading, so an automatic normalization would be a
+style conflict rather than a migration.
+
+## astel findings
+
+astel 0.2.0 provides every required write primitive: transactions, same-offset
+insertions, parse validation, keyword/list editing, body insertion, comments,
+and unified diff output. `NodePattern` handles the narrow node and field checks
+used here, but its DSL has no list literal syntax for argument-list matching.
+Rules therefore compile a broad call pattern once and use
+`Rewriter#find_keyword_argument` for keyword details.
+
+## Sources
+
+- <https://github.com/rmosolgo/graphql-ruby/blob/master/CHANGELOG.md>
+- <https://github.com/rmosolgo/graphql-ruby/issues/3056>
+- <https://github.com/DmitryTsepelev/rubocop-graphql/tree/master/lib/rubocop/cop/graphql>
+- <https://github.com/ydah/astel>

data/docs/rules/GQLM101.md

@@ -0,0 +1,5 @@
+# GQLM101 — `.define` DSL
+
+Safety: manual. GraphQL-Ruby deprecated `.define` in 1.10 and removed legacy
+definitions in 2.0. Replace each definition with the corresponding
+`GraphQL::Schema::*` class or module and verify hooks manually.

data/docs/rules/GQLM102.md

@@ -0,0 +1,12 @@
+# GQLM102 — `resolve:` field option
+
+Safety: unsafe. With `--unsafe`, a self-contained three-argument lambda is
+moved to an instance resolver method and legacy `obj` / `ctx` references become
+`object` / `context`. The generated method accepts and ignores extra keyword
+arguments, matching a legacy proc that did not read `args`. Captured locals,
+`args`, nested blocks, bare calls,
+dynamic field names, and method-name collisions are reported as manual because
+an automatic rewrite could change their meaning. Static declarations made with
+`attr`, `alias`, or `define_method` also count as existing methods. Duplicate
+`resolve:` options and calls containing dynamic keyword expansion (`**options`)
+are also left unchanged for manual resolution.

data/docs/rules/GQLM103.md

@@ -0,0 +1,5 @@
+# GQLM103 — `GraphQL::Function`
+
+Safety: unsafe. Replaces `GraphQL::Function` with
+`GraphQL::Schema::Resolver`. Review arguments, return type, and the resolver
+method after applying because the two class APIs are not identical.

data/docs/rules/GQLM104.md

@@ -0,0 +1,5 @@
+# GQLM104 — legacy definition conversion
+
+Safety: manual. `to_graphql` and `graphql_definition` disappeared with legacy
+definitions. Remove the call when its result is unused; otherwise migrate the
+consumer to class-based schema members.

data/docs/rules/GQLM105.md

@@ -0,0 +1,9 @@
+# GQLM105 — `types.X`
+
+Safety: safe. Rewrites the five legacy `TypeDefiner` scalars: `String` and
+`Float` keep their Ruby classes, `Int` becomes `Integer`, and `Boolean` / `ID`
+become `GraphQL::Types::Boolean` / `GraphQL::Types::ID`. Other `types.X` calls
+and calls with arguments or blocks are left unchanged. Automatic rewrites are
+limited to GraphQL type DSL arguments; other class-level uses and chained
+wrappers such as `types.String.to_non_null_type` are reported for manual
+class-API migration.

data/docs/rules/GQLM106.md

@@ -0,0 +1,7 @@
+# GQLM106 — `property:`
+
+Safety: safe. Renames the removed field option `property:` to its class API
+equivalent `method:` inside GraphQL object and interface definitions.
+Calls with duplicate `property:` or an existing `method:` are reported for
+manual resolution, as are calls containing dynamic keyword expansion
+(`**options`).

data/docs/rules/GQLM107.md

@@ -0,0 +1,7 @@
+# GQLM107 — removed field options
+
+Safety: safe. Removes `field:` and `function:` from field definitions. They
+were already no-ops before GraphQL-Ruby removed them in 2.0.1. Values that may
+have side effects are preserved and reported as manual. String-keyed hashes are
+not treated as legacy keyword options. Calls containing dynamic keyword
+expansion (`**options`) are also left unchanged for manual resolution.

data/docs/rules/GQLM108.md

@@ -0,0 +1,4 @@
+# GQLM108 — `GraphQL::Query::Arguments`
+
+Safety: manual. The legacy arguments container was removed in 2.0. Update code
+to consume the argument values supplied by the class-based resolver API.

data/docs/rules/GQLM201.md

@@ -0,0 +1,5 @@
+# GQLM201 — Relay mutation superclass
+
+Safety: unsafe. Replaces `GraphQL::Relay::Mutation` with
+`GraphQL::Schema::RelayClassicMutation`. Review the generated input and payload
+types after applying.

data/docs/rules/GQLM202.md

@@ -0,0 +1,4 @@
+# GQLM202 — connection type factory
+
+Safety: manual. Replace `GraphQL::Relay::ConnectionType.create_type` consumers
+with the class-based type's generated `connection_type`.

data/docs/rules/GQLM203.md

@@ -0,0 +1,5 @@
+# GQLM203 — Relay node field
+
+Safety: unsafe, detection only. Replace `GraphQL::Relay::Node.field` with an
+appropriate field and implement `GraphQL::Types::Relay::Node` on the owning
+type. The correct owner cannot be inferred statically.

data/docs/rules/GQLM204.md

@@ -0,0 +1,5 @@
+# GQLM204 — direct BaseConnection inheritance
+
+Safety: unsafe, detection only. Generate an application base connection and
+inherit from it instead of directly subclassing
+`GraphQL::Types::Relay::BaseConnection`.

data/docs/rules/GQLM205.md

@@ -0,0 +1,5 @@
+# GQLM205 — load failure error
+
+Safety: safe. Rewrites
+`GraphQL::Schema::Resolver::LoadApplicationObjectFailedError` to the name used
+since 1.9.4, `GraphQL::LoadApplicationObjectFailedError`.

data/docs/rules/GQLM301.md

@@ -0,0 +1,5 @@
+# GQLM301 — Interpreter plugin
+
+Safety: safe. Removes `use GraphQL::Execution::Interpreter`; Interpreter has
+been the schema default since 1.12. Conditional, option-bearing, and block-based
+uses, and uses with trailing comments, are preserved and reported as manual.

data/docs/rules/GQLM302.md

@@ -0,0 +1,5 @@
+# GQLM302 — Analysis::AST plugin
+
+Safety: safe. Removes `use GraphQL::Analysis::AST`; AST analysis has been the
+schema default since 1.12. Conditional, option-bearing, and block-based uses are
+preserved and reported as manual. Uses with trailing comments are also preserved.

data/docs/rules/GQLM303.md

@@ -0,0 +1,6 @@
+# GQLM303 — Connections plugin
+
+Safety: safe. Removes `use GraphQL::Pagination::Connections`; the new
+connection implementation has been the schema default since 1.12. Conditional,
+option-bearing, and block-based uses, and uses with trailing comments, are
+preserved and reported as manual.

data/docs/rules/GQLM304.md

@@ -0,0 +1,4 @@
+# GQLM304 — error bubbling
+
+Safety: manual. `error_bubbling(true)` is deprecated without a direct
+replacement. Test validation error responses before removing the setting.

data/docs/rules/GQLM305.md

@@ -0,0 +1,8 @@
+# GQLM305 — bidirectional pagination
+
+Safety: safe. Removes the obsolete
+`GraphQL::Relay::ConnectionType.bidirectional_pagination` assignment,
+which does not affect the current pagination implementation. Conditional
+assignments and values that may have side effects are reported as manual.
+Assignments nested in methods, blocks, or expressions and assignments with
+trailing comments are also preserved for manual review.

data/docs/rules/GQLM306.md

@@ -0,0 +1,8 @@
+# GQLM306 — default nodes field
+
+Safety: safe. Removes the obsolete
+`GraphQL::Relay::ConnectionType.default_nodes_field` assignment, which
+does not affect the current pagination implementation. Conditional assignments
+and values that may have side effects are reported as manual.
+Assignments nested in methods, blocks, or expressions and assignments with
+trailing comments are also preserved for manual review.

data/docs/rules/GQLM307.md

@@ -0,0 +1,11 @@
+# GQLM307 — Visibility plugin
+
+Safety: unsafe. When a GraphQL type defines the class method `visible?`, inserts
+`use GraphQL::Schema::Visibility, migration_errors: true` after existing schema
+configuration. Placement after root type configuration is required by
+GraphQL-Ruby 2.6.3 and newer. Resolve migration errors before removing the
+option. Existing one-line Visibility configuration is moved after root types;
+conditional, block-based, or trailing-comment configuration is reported as
+manual so its surrounding behavior and commentary are preserved. Conditional
+plugin calls do not count as guaranteed configuration and prevent automatic
+insertion until they are resolved.

data/docs/rules/GQLM308.md

@@ -0,0 +1,5 @@
+# GQLM308 — schema type index keys
+
+Safety: manual. Since 2.3.5, `Schema.possible_types` and
+`Schema.references_to` use type classes instead of GraphQL name strings as
+keys. Use `transform_keys(&:graphql_name)` only where the old shape is needed.

data/docs/rules/GQLM309.md

@@ -0,0 +1,4 @@
+# GQLM309 — `rescue_from`
+
+Safety: manual. Review schema error handler placement, exception specificity,
+and handler parameters against the target GraphQL-Ruby version.

data/docs/rules/GQLM310.md

@@ -0,0 +1,9 @@
+# GQLM310 — empty Union selections
+
+Safety: manual. GraphQL-Ruby 2.5.3 began migrating toward rejecting Union
+fields without subselections. Set
+`allow_legacy_invalid_empty_selections_on_union` deliberately while fixing
+affected queries. An override of
+`legacy_invalid_empty_selections_on_union_with_type` also counts as an explicit
+migration policy. Conditional configuration calls do not count as an explicit
+migration policy.

data/docs/rules/GQLM401.md

@@ -0,0 +1,6 @@
+# GQLM401 — redundant `required: true`
+
+Safety: safe, disabled by default. Removes `required: true`, the argument
+default since 1.13. Enable this rule explicitly when the style-only diff is
+acceptable. Calls containing dynamic keyword expansion (`**options`) are left
+unchanged for manual resolution, as are duplicate `required:` options.

data/docs/rules/GQLM402.md

@@ -0,0 +1,6 @@
+# GQLM402 — redundant `null: true`
+
+Safety: safe, disabled by default. Removes `null: true`, the field default
+since 1.13. Enable this rule explicitly when the style-only diff is acceptable.
+Calls containing dynamic keyword expansion (`**options`) are left unchanged
+for manual resolution, as are duplicate `null:` options.

data/docs/rules/GQLM501.md

@@ -0,0 +1,6 @@
+# GQLM501 — complexity cost mode
+
+Safety: manual. GraphQL-Ruby 2.5.3 added migration support for corrected
+complexity merging. Set `complexity_cost_calculation_mode` explicitly, compare
+limits, then adopt the corrected behavior. Conditional configuration calls do
+not count as an explicit migration policy.

data/docs/rules/GQLM502.md

@@ -0,0 +1,5 @@
+# GQLM502 — page size settings
+
+Safety: unsafe, detection only. Review `default_max_page_size` and split the
+intent between `default_page_size` and `max_page_size`; one automatic mapping
+would not preserve every application's behavior.

data/docs/rules/README.md

@@ -0,0 +1,35 @@
+# Rule index
+
+| ID | Safety | Migration |
+|---|---|---|
+| [GQLM101](GQLM101.md) | manual | `.define` DSL |
+| [GQLM102](GQLM102.md) | unsafe/manual fallback | `resolve:` option |
+| [GQLM103](GQLM103.md) | unsafe | `GraphQL::Function` |
+| [GQLM104](GQLM104.md) | manual | legacy definition calls |
+| [GQLM105](GQLM105.md) | safe | `types.X` |
+| [GQLM106](GQLM106.md) | safe | `property:` |
+| [GQLM107](GQLM107.md) | safe | removed field options |
+| [GQLM108](GQLM108.md) | manual | `Query::Arguments` |
+| [GQLM201](GQLM201.md) | unsafe | Relay mutation |
+| [GQLM202](GQLM202.md) | manual | connection type factory |
+| [GQLM203](GQLM203.md) | unsafe | Relay node field |
+| [GQLM204](GQLM204.md) | unsafe | base connection |
+| [GQLM205](GQLM205.md) | safe | load failure error |
+| [GQLM301](GQLM301.md) | safe | Interpreter plugin |
+| [GQLM302](GQLM302.md) | safe | Analysis plugin |
+| [GQLM303](GQLM303.md) | safe | Connections plugin |
+| [GQLM304](GQLM304.md) | manual | error bubbling |
+| [GQLM305](GQLM305.md) | safe | bidirectional pagination |
+| [GQLM306](GQLM306.md) | safe | default nodes field |
+| [GQLM307](GQLM307.md) | unsafe | Visibility plugin |
+| [GQLM308](GQLM308.md) | manual | schema type indexes |
+| [GQLM309](GQLM309.md) | manual | error handlers |
+| [GQLM310](GQLM310.md) | manual | empty Union selections |
+| [GQLM401](GQLM401.md) | safe, opt-in | redundant required |
+| [GQLM402](GQLM402.md) | safe, opt-in | redundant null |
+| [GQLM501](GQLM501.md) | manual | complexity mode |
+| [GQLM502](GQLM502.md) | unsafe | page size settings |
+
+GQLM403 is intentionally not provided because graphql-ruby's
+`GraphQL/FieldTypeInBlock` cop owns that style decision. GQLM503 was folded
+into the specific GQLM310 and GQLM501 diagnostics.

data/docs/writing-rules.md

@@ -0,0 +1,29 @@
+# Writing rules
+
+Rules inherit `GraphQL::Modernize::Rules::Base`, declare metadata once, and
+compile their astel node pattern at class load time.
+
+```ruby
+class PropertyOption < Base
+  rule id: "GQLM106", safety: :safe, summary: "property to method"
+  node_pattern :call_node, "(call_node receiver: nil name: :field)"
+
+  def on_match(node, _captures)
+    return unless inside?(node, :object, :interface)
+
+    arguments = keyword_arguments(node, :property)
+    return unless arguments.one? && !dynamic_keyword_arguments?(node)
+
+    argument = arguments.first
+
+    add_offense(argument.location, message: "replace property") do |rw|
+      rw.replace_keyword_key(argument, :method)
+    end
+  end
+end
+```
+
+Use the narrowest NodePattern that astel supports, then inspect GraphQL-specific
+details in Ruby. `add_offense` wraps corrections in an astel transaction.
+Every non-trivial correction needs a test for output, parse validity,
+idempotence, and an unrelated DSL false-positive case.

data/exe/graphql-modernize

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "graphql/modernize"
+
+exit GraphQL::Modernize::CLI.start