graphql-doctor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 227a766e280cad57f2425bdb6806a7f0ef894142dca02f9bf7e2916f30ae47b2
+  data.tar.gz: 42590b9a638b5bcd94b701869fe86453bb82b39718e54bbc45ac6d3c81afac31
+SHA512:
+  metadata.gz: '0921f5b6fd1ad4187ac438b6c0425cafebcf9488a0a9524f47fb2cf76ae706ccbde78bcaae58325abc70c1cea22b37dd5d3a1c661d5529bdf7d42c27065eaa1d'
+  data.tar.gz: 370503328e8b9b424739d9f78e17ff11c29d679e737c6950b9c43c7d19885001478d96bc6eca53cf9fee480e58935c2b34398010942cb9ecd573a175d4ee2acc

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,71 @@
+# graphql-doctor
+
+`graphql-doctor` maps GraphQL-Ruby's runtime schema back to Prism-parsed Ruby source and checks resolver contracts before a query reaches production.
+
+## Installation
+
+Add it to the application that owns the schema:
+
+```ruby
+group :development, :test do
+  gem "graphql-doctor"
+end
+```
+
+The gem supports Ruby 3.1+ and GraphQL-Ruby 2.0+. GraphQL-Ruby 2.0.0 itself cannot build interface schemas on Ruby 3.4, so use 2.0.32 or newer for that combination. The gem's only runtime dependency is Prism.
+
+## Configuration
+
+Create `.graphql-doctor.yml` in the application root:
+
+```yaml
+schema: MyAppSchema
+require: ./config/environment
+include:
+  - app/graphql/**/*.rb
+exclude:
+  - app/graphql/legacy/**/*.rb
+
+checks:
+  GQLD201: { severity: warning }
+  GQLD305: { enabled: true }
+
+allow_underlying_object:
+  - Types::UserType
+abstract_classes:
+  - Mutations::BaseMutation
+```
+
+## Commands
+
+```sh
+bundle exec graphql-doctor check
+bundle exec graphql-doctor check app/graphql --format github
+bundle exec graphql-doctor dump-schema --out tmp/schema.json
+bundle exec graphql-doctor check --no-boot --schema-dump tmp/schema.json
+bundle exec graphql-doctor coverage
+bundle exec graphql-doctor explain GQLD301
+```
+
+`check` exits with `0` when the configured threshold is clear, `1` for diagnostics at or above `--fail-level`, and `2` for configuration or boot failures. Formats are `text`, `json`, `sarif`, and `github`. `NO_COLOR` and `--no-color` disable ANSI output.
+
+For CI split boot from checking by passing the output of `dump-schema` to `--schema-dump`. Cache files are stored under `.graphql-doctor/cache`; add `.graphql-doctor/` to the target application's `.gitignore`.
+
+## Suppression
+
+Suppress one line or a whole file:
+
+```ruby
+def resolve(id:) # graphql-doctor:disable GQLD301 -- handled by an extension
+# graphql-doctor:disable-file GQLD201 -- objects provide all fields
+```
+
+Set `require_suppression_reason: true` to ignore suppression comments without trailing reasons.
+
+## Development
+
+Run `bundle exec rake test`. See [diagnostic references](docs/diagnostics) for causes and fixes.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task test: :spec
+task default: :spec

data/docs/diagnostics/GQLD101.md

@@ -0,0 +1,7 @@
+# GQLD101: Schema boot failed
+
+- Cause: the configured environment could not load or the schema constant could not be resolved.
+- Runtime impact: runtime-backed checks cannot run.
+- Fix: correct `require:` and `schema:` in `.graphql-doctor.yml`.
+- False positives: none; the underlying exception is included.
+- Suppression: not supported because this is an execution failure.

data/docs/diagnostics/GQLD102.md

@@ -0,0 +1,7 @@
+# GQLD102: Source-only field
+
+- Cause: a statically declared field is absent from the selected runtime schema.
+- Runtime impact: the field is not queryable in that schema.
+- Fix: register its owner or remove the declaration.
+- False positives: visibility rules and multiple schemas can cause this; the check is off by default.
+- Suppression: use `graphql-doctor:disable GQLD102` or disable the check in configuration.

data/docs/diagnostics/GQLD103.md

@@ -0,0 +1,7 @@
+# GQLD103: Dynamic definition
+
+- Cause: a field or argument is declared under a loop, condition, include, or unsupported macro.
+- Runtime impact: no contract error is asserted; source mapping is incomplete.
+- Fix: use a literal GraphQL DSL declaration when source mapping is required.
+- False positives: intentional metaprogramming is expected; the check is off by default.
+- Suppression: use `graphql-doctor:disable GQLD103`.

data/docs/diagnostics/GQLD104.md

@@ -0,0 +1,7 @@
+# GQLD104: Ruby parse failed
+
+- Cause: Prism could not parse a selected Ruby file.
+- Runtime impact: declarations in that file are skipped.
+- Fix: correct the reported Ruby syntax or exclude unsupported generated input.
+- False positives: version-specific syntax requires a compatible Prism version.
+- Suppression: fix or exclude the file; hiding parse failures is discouraged.

data/docs/diagnostics/GQLD201.md

@@ -0,0 +1,7 @@
+# GQLD201: Resolver method not found
+
+- Cause: no type or resolver method was found for a field without `hash_key:` or `dig:`.
+- Runtime impact: GraphQL-Ruby may fall through to the underlying object or raise at execution.
+- Fix: define the method or add the owner to `allow_underlying_object`.
+- False positives: underlying domain objects are intentionally not guessed; severity is warning.
+- Suppression: use `graphql-doctor:disable GQLD201`.

data/docs/diagnostics/GQLD202.md

@@ -0,0 +1,7 @@
+# GQLD202: Explicit resolver method not found
+
+- Cause: `resolver_method:` or a resolver class points to a missing method.
+- Runtime impact: executing the field raises a method error.
+- Fix: define or rename the resolver method.
+- False positives: dynamically installed methods are not visible to static source indexing.
+- Suppression: use `graphql-doctor:disable GQLD202` for deliberate metaprogramming.

data/docs/diagnostics/GQLD203.md

@@ -0,0 +1,7 @@
+# GQLD203: Explicit field method not found
+
+- Cause: `method:` names a method missing from a statically known underlying object class.
+- Runtime impact: field execution can raise a method error.
+- Fix: correct `method:` or define the target method.
+- False positives: opaque underlying objects are reported as GQLD201 instead, without asserting that the method is absent.
+- Suppression: use `graphql-doctor:disable GQLD203` when the target is dynamic.

data/docs/diagnostics/GQLD204.md

@@ -0,0 +1,7 @@
+# GQLD204: Resolver method is not public
+
+- Cause: a resolver target is declared private or protected.
+- Runtime impact: GraphQL-Ruby uses public dispatch and cannot call it.
+- Fix: make the method public or point the field at a public method.
+- False positives: none for statically declared visibility.
+- Suppression: use `graphql-doctor:disable GQLD204` only with a custom dispatch layer.

data/docs/diagnostics/GQLD205.md

@@ -0,0 +1,7 @@
+# GQLD205: Invalid prepare callback
+
+- Cause: a symbolic `prepare:` method is missing or has the wrong visibility or arity.
+- Runtime impact: argument preparation fails before resolver execution.
+- Fix: define the named callback without required keywords. GraphQL-Ruby first uses a public Object instance method taking `value`; since 2.1.8, Resolver and Mutation arguments may fall back to a class method taking `value, context`.
+- False positives: dynamically defined callbacks cannot be confirmed.
+- Suppression: use `graphql-doctor:disable GQLD205`.

data/docs/diagnostics/GQLD301.md

@@ -0,0 +1,7 @@
+# GQLD301: GraphQL keyword is not accepted
+
+- Cause: a runtime argument keyword or extra is absent from the Ruby signature.
+- Runtime impact: resolver dispatch raises an unknown keyword error.
+- Fix: accept the reported keyword or `**arguments`; respect `loads:` and `as:` conversions.
+- False positives: dynamic forwarding is skipped automatically.
+- Suppression: use `graphql-doctor:disable GQLD301`.

data/docs/diagnostics/GQLD302.md

@@ -0,0 +1,7 @@
+# GQLD302: Ruby requires an input GraphQL cannot provide
+
+- Cause: a required Ruby keyword has no runtime GraphQL argument or extra, or the resolver requires a positional argument.
+- Runtime impact: resolver dispatch raises a missing keyword or wrong-number-of-arguments error.
+- Fix: rename/remove the keyword, declare the matching GraphQL argument, or change positional parameters to keywords.
+- False positives: extensions may supply unknown values; model them as extras or accept `**arguments`.
+- Suppression: use `graphql-doctor:disable GQLD302`.

data/docs/diagnostics/GQLD303.md

@@ -0,0 +1,7 @@
+# GQLD303: Optional GraphQL argument is required by Ruby
+
+- Cause: GraphQL may omit an argument but the Ruby method requires its keyword.
+- Runtime impact: queries that omit it raise a missing keyword error.
+- Fix: use `keyword: nil`, add `default_value:`, use non-null/`:nullable`, or accept `**arguments`.
+- False positives: none when runtime argument metadata is available.
+- Suppression: use `graphql-doctor:disable GQLD303`.

data/docs/diagnostics/GQLD305.md

@@ -0,0 +1,7 @@
+# GQLD305: Unknown optional Ruby keyword
+
+- Cause: an optional Ruby keyword has no known GraphQL argument or extra.
+- Runtime impact: usually none; an extension may supply it.
+- Fix: remove stale parameters or declare the source of the keyword.
+- False positives: extension-provided keywords are common; the check is off by default.
+- Suppression: use `graphql-doctor:disable GQLD305`.

data/docs/diagnostics/GQLD306.md

@@ -0,0 +1,7 @@
+# GQLD306: GraphQL extra is not accepted
+
+- Cause: `extras:` adds a keyword absent from the resolver signature.
+- Runtime impact: resolver dispatch raises an unknown keyword error.
+- Fix: accept the named extra or `**arguments`.
+- False positives: none when runtime extras are reflected.
+- Suppression: use `graphql-doctor:disable GQLD306`.

data/docs/diagnostics/GQLD307.md

@@ -0,0 +1,7 @@
+# GQLD307: Callback signature mismatch
+
+- Cause: `ready?`, `authorized?`, or an enabled experimental execution callback has an incompatible signature.
+- Runtime impact: callback dispatch fails before or during resolution.
+- Fix: accept the runtime argument set; experimental callbacks must accept their fixed keywords and `**arguments`.
+- False positives: forwarding (`...`) callbacks are skipped.
+- Suppression: use `graphql-doctor:disable GQLD307`.

data/docs/diagnostics/GQLD401.md

@@ -0,0 +1,7 @@
+# GQLD401: Resolver or mutation is unregistered
+
+- Cause: a concrete resolver or mutation class is not referenced by any runtime field.
+- Runtime impact: the member is unreachable through the schema.
+- Fix: register it or remove dead code; list abstract bases under `abstract_classes`.
+- False positives: a different schema may register the class.
+- Suppression: use `graphql-doctor:disable GQLD401`.

data/docs/diagnostics/README.md

@@ -0,0 +1,29 @@
+# Diagnostic reference
+
+Each diagnostic page explains the cause, runtime impact, fix, possible false positives, and suppression options.
+Read one from the command line with:
+
+```sh
+bundle exec graphql-doctor explain GQLD301
+```
+
+| Code | Diagnostic | Default |
+| --- | --- | --- |
+| [GQLD101](GQLD101.md) | Schema boot failed | error |
+| [GQLD102](GQLD102.md) | Source-only field | info, disabled |
+| [GQLD103](GQLD103.md) | Dynamic definition | info, disabled |
+| [GQLD104](GQLD104.md) | Ruby parse failed | error |
+| [GQLD201](GQLD201.md) | Resolver method not found | warning |
+| [GQLD202](GQLD202.md) | Explicit resolver method not found | error |
+| [GQLD203](GQLD203.md) | Explicit field method not found | error |
+| [GQLD204](GQLD204.md) | Resolver method is not public | warning |
+| [GQLD205](GQLD205.md) | Invalid prepare callback | error |
+| [GQLD301](GQLD301.md) | GraphQL keyword is not accepted | error |
+| [GQLD302](GQLD302.md) | Ruby requires an input GraphQL cannot provide | error |
+| [GQLD303](GQLD303.md) | Optional GraphQL argument is required by Ruby | error |
+| [GQLD305](GQLD305.md) | Unknown optional Ruby keyword | info, disabled |
+| [GQLD306](GQLD306.md) | GraphQL extra is not accepted | error |
+| [GQLD307](GQLD307.md) | Callback signature mismatch | error |
+| [GQLD401](GQLD401.md) | Resolver or mutation is unregistered | warning |
+
+Configure severities and opt-in checks under `checks` in `.graphql-doctor.yml`. See the project [README](../../README.md#configuration) for configuration and suppression examples.

data/exe/graphql-doctor

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

data/lib/graphql/doctor/cache.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require_relative "source/index"
+
+module GraphQL
+  module Doctor
+    class Cache
+      FORMAT_VERSION = 3
+
+      def initialize(directory: ".graphql-doctor/cache")
+        @directory = directory
+      end
+
+      def fetch(path, config_digest: "")
+        begin
+          source = File.binread(path)
+        rescue SystemCallError
+          return yield
+        end
+
+        key = Digest::SHA256.hexdigest(
+          [File.expand_path(path), source, VERSION, FORMAT_VERSION, config_digest].join("\0")
+        )
+        cache_path = File.join(@directory, "#{key}.json")
+        if File.file?(cache_path)
+          begin
+            return Source::Index.from_h(JSON.parse(File.read(cache_path)))
+          rescue StandardError
+            nil
+          end
+        end
+
+        value = yield(source)
+        begin
+          FileUtils.mkdir_p(@directory)
+          File.write(cache_path, JSON.generate(value.to_h))
+        rescue SystemCallError
+          nil
+        end
+        value
+      end
+    end
+  end
+end

data/lib/graphql/doctor/checks/argument_keyword_match.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module GraphQL
+  module Doctor
+    module Checks
+      class ArgumentKeywordMatch < Base
+        def call(field)
+          return [] unless field.status == :matched && field.source.confidence != :dynamic
+
+          owner, _name, method = method_target(field)
+          diagnostics = experimental_diagnostics(field, owner)
+          return diagnostics unless method && !method.dynamic
+
+          expected = expected_keywords(field)
+          diagnostics.concat(argument_diagnostics(field, method, expected))
+          diagnostics.concat(extra_diagnostics(field, method, expected[:extras]))
+          diagnostics.concat(prepare_diagnostics(field))
+          diagnostics.concat(callback_diagnostics(field, owner, expected))
+          diagnostics.compact
+        end
+
+        private
+
+        def expected_keywords(field)
+          always = []
+          maybe = []
+          field.runtime.fetch("arguments", []).each do |argument|
+            source = source_argument(field, argument)
+            present = argument.fetch("required", argument["non_null"]) || argument["has_default"] ||
+                      source&.required == :nullable
+            (present ? always : maybe) << argument["keyword"].to_sym
+          end
+          {always: always, maybe: maybe, extras: field.runtime.fetch("extras", []).map(&:to_sym)}
+        end
+
+        def argument_diagnostics(field, method, expected)
+          accepted = method.required_keywords + method.optional_keywords
+          expected_arguments = expected[:always] + expected[:maybe]
+          diagnostics = []
+          unless method.accepts_keyword_rest
+            (expected_arguments - accepted).each do |keyword|
+              diagnostics << missing_keyword(field, method, keyword)
+            end
+            (method.required_keywords - expected_arguments - expected[:extras]).each do |keyword|
+              diagnostics << unexpected_required(field, keyword, expected_arguments)
+            end
+            if @config.check_enabled?("GQLD305")
+              (method.optional_keywords - expected_arguments - expected[:extras]).each do |keyword|
+                diagnostics << unexpected_optional(field, method, keyword)
+              end
+            end
+          end
+          (expected[:maybe] & method.required_keywords).each do |keyword|
+            diagnostics << required_optional(field, method, keyword)
+          end
+          diagnostics << required_positional(field, method) if method.required_positionals.to_i.positive?
+          diagnostics
+        end
+
+        def extra_diagnostics(field, method, extras)
+          return [] if method.accepts_keyword_rest
+
+          accepted = method.required_keywords + method.optional_keywords
+          (extras - accepted).filter_map do |extra|
+            diagnostic(
+              "GQLD306",
+              "GraphQL extra `#{extra}:` is not accepted by `##{method.name}`",
+              field.source.definition_location,
+              fingerprint: fingerprint(field, "GQLD306", extra)
+            )
+          end
+        end
+
+        def prepare_diagnostics(field)
+          field.runtime.fetch("arguments", []).filter_map do |argument|
+            name = argument["prepare"]
+            next unless name
+
+            owner, method, positional_count = prepare_target(field, argument, name)
+            next if valid_prepare?(method, positional_count, argument)
+
+            source = source_argument(field, argument)
+            diagnostic(
+              "GQLD205",
+              "Prepare method `#{owner}##{name}` must exist and accept one value plus optional context",
+              source&.definition_location || field.source.definition_location,
+              fingerprint: fingerprint(field, "GQLD205", name)
+            )
+          end
+        end
+
+        def prepare_target(field, argument, name)
+          source_location = argument["prepare_source_location"]
+          case argument["prepare_method_dispatch"]
+          when "object"
+            owner = field.runtime["owner"]
+            [owner, find_method(owner, name, source_location: source_location), 1]
+          when "resolver"
+            owner = field.runtime["resolver_class"]
+            [owner, find_singleton_method(owner, name, source_location: source_location), 2]
+          when nil
+            if argument.key?("prepare_method_dispatch")
+              return [field.runtime["resolver_class"] || field.runtime["owner"], nil, 0]
+            end
+
+            legacy_prepare_target(field, name, source_location)
+          end
+        end
+
+        def legacy_prepare_target(field, name, source_location)
+          owner = field.runtime["resolver_class"] || field.runtime["owner"]
+          method = if field.runtime["resolver_class"]
+                     find_singleton_method(owner, name, source_location: source_location)
+                   else
+                     find_method(owner, name, source_location: source_location)
+                   end
+          [owner, method, field.runtime["resolver_class"] ? 2 : 1]
+        end
+
+        def callback_diagnostics(field, owner, expected)
+          return [] unless field.runtime["resolver_class"]
+
+          locations = field.runtime.fetch("callback_source_locations", {})
+          signatures = field.runtime.fetch("callback_signatures", {})
+          %i[ready? authorized?].filter_map do |name|
+            method = reflected_method(
+              owner,
+              name,
+              source_location: locations[name.to_s],
+              signature: signatures[name.to_s],
+              fallback_location: field.source.definition_location
+            )
+            next unless method && !method.dynamic
+
+            accepted = method.required_keywords + method.optional_keywords
+            expected_keywords = expected[:always] + expected[:maybe] + expected[:extras]
+            missing = method.accepts_keyword_rest ? [] : expected_keywords - accepted
+            invalid_optional = expected[:maybe] & method.required_keywords
+            unexpected = method.required_keywords - expected_keywords
+            required_positionals = method.required_positionals || 0
+            next if missing.empty? && invalid_optional.empty? && unexpected.empty? && required_positionals.zero?
+
+            diagnostic(
+              "GQLD307",
+              "Callback `#{owner}##{name}` has an incompatible GraphQL argument signature",
+              method.location,
+              fingerprint: fingerprint(field, "GQLD307", name)
+            )
+          end
+        end
+
+        def accepts_positionals?(method, count)
+          required = method.required_positionals || method.positionals.length
+          optional = method.optional_positionals || 0
+          required <= count && (method.accepts_positional_rest || count <= required + optional)
+        end
+
+        def valid_prepare_method?(method, positional_count)
+          method && method.visibility == :public && method.required_keywords.empty? &&
+            accepts_positionals?(method, positional_count)
+        end
+
+        def valid_prepare?(method, positional_count, argument)
+          runtime_valid = argument["prepare_method_valid"]
+          return runtime_valid unless runtime_valid.nil?
+          return method.visibility == :public if method&.dynamic
+          return valid_prepare_method?(method, positional_count) if method
+          return argument["prepare_method_valid"] if argument.key?("prepare_method_valid")
+
+          argument["prepare_source_location"]
+        end
+
+        def experimental_diagnostics(field, owner)
+          return [] unless @config["experimental"].fetch("new_execution_api", false)
+
+          signatures = {
+            resolve_static: [:context],
+            resolve_batch: %i[objects context],
+            resolve_each: %i[object context]
+          }
+          signatures.filter_map do |name, required|
+            method = find_method(owner, name)
+            next unless method
+            next if method.required_keywords.sort == required.sort && method.accepts_keyword_rest
+
+            keywords = required.map { |key| "#{key}:" }.join(", ")
+            diagnostic(
+              "GQLD307",
+              "Experimental callback `#{owner}##{name}` must require #{keywords} and accept `**arguments`",
+              method.location,
+              fingerprint: fingerprint(field, "GQLD307", name)
+            )
+          end
+        end
+
+        def missing_keyword(field, method, keyword)
+          source = runtime_argument_source(field, keyword)
+          accepted = method.required_keywords + method.optional_keywords
+          suggestion = if source&.loads && accepted.include?(source.ruby_name)
+                         source.ruby_name
+                       else
+                         nearest(accepted, keyword)
+                       end
+          message = "GraphQL keyword `#{keyword}:` is not accepted by `##{method.name}`"
+          if source&.loads
+            message = "GraphQL argument `#{source.graphql_name}` is passed to Ruby as `#{keyword}:` after `loads:`"
+          end
+          suggestion_message = "Did you mean `#{keyword}:` instead of `#{suggestion}:`?" if suggestion
+          diagnostic(
+            "GQLD301",
+            message,
+            method.parameter_locations[suggestion] || source&.definition_location || field.source.definition_location,
+            suggestions: suggestion_message ? [Suggestion.new(message: suggestion_message)] : [],
+            fingerprint: fingerprint(field, "GQLD301", keyword)
+          )
+        end
+
+        def unexpected_required(field, keyword, expected)
+          method = method_target(field).last
+          suggestion = nearest(expected, keyword)
+          source_argument = field.source.arguments.find { |argument| argument.ruby_name == keyword }
+          loads_note = source_argument&.loads ? " (after `loads:` conversion)" : ""
+          diagnostic(
+            "GQLD302",
+            "Required Ruby keyword `#{keyword}:` has no GraphQL argument#{loads_note}",
+            method.parameter_locations.fetch(keyword, method.location),
+            suggestions: suggestion ? [Suggestion.new(message: "Did you mean `#{suggestion}:`?")] : [],
+            fingerprint: fingerprint(field, "GQLD302", keyword)
+          )
+        end
+
+        def required_optional(field, method, keyword)
+          suggestion = "Use `#{keyword}: nil`, add a GraphQL default, or accept `**arguments`."
+          diagnostic(
+            "GQLD303",
+            "GraphQL keyword `#{keyword}:` may be omitted but `##{method.name}` requires it",
+            method.parameter_locations.fetch(keyword, method.location),
+            suggestions: [Suggestion.new(message: suggestion)],
+            fingerprint: fingerprint(field, "GQLD303", keyword)
+          )
+        end
+
+        def unexpected_optional(field, method, keyword)
+          diagnostic(
+            "GQLD305",
+            "Optional Ruby keyword `#{keyword}:` has no known GraphQL argument",
+            method.parameter_locations.fetch(keyword, method.location),
+            fingerprint: fingerprint(field, "GQLD305", keyword)
+          )
+        end
+
+        def required_positional(field, method)
+          count = method.required_positionals
+          noun = count == 1 ? "argument" : "arguments"
+          diagnostic(
+            "GQLD302",
+            "Resolver method `##{method.name}` requires #{count} positional #{noun}, but GraphQL passes keywords only",
+            method.location || field.source.definition_location,
+            fingerprint: fingerprint(field, "GQLD302", "positional")
+          )
+        end
+
+        def source_argument(field, runtime_argument)
+          candidates = field.source.arguments
+          if field.runtime["resolver_class"]
+            candidates += @source_index.arguments.select do |argument|
+              argument.owner == field.runtime["resolver_class"] && argument.field_name.nil?
+            end
+          end
+          candidates.find do |argument|
+            argument.graphql_name == runtime_argument["graphql_name"] ||
+              argument.ruby_name.to_s == runtime_argument["keyword"]
+          end
+        end
+
+        def runtime_argument_source(field, keyword)
+          runtime = field.runtime.fetch("arguments", []).find { |argument| argument["keyword"] == keyword.to_s }
+          runtime && source_argument(field, runtime)
+        end
+
+        def nearest(candidates, keyword)
+          candidates.min_by { |candidate| levenshtein(candidate.to_s, keyword.to_s) }.then do |candidate|
+            candidate if candidate && levenshtein(candidate.to_s, keyword.to_s) <= 2
+          end
+        end
+
+        def levenshtein(left, right)
+          row = (0..right.length).to_a
+          left.each_char.with_index(1) do |left_char, index|
+            previous = row
+            row = [index]
+            right.each_char.with_index(1) do |right_char, other_index|
+              row << [row[-1] + 1, previous[other_index] + 1,
+                      previous[other_index - 1] + (left_char == right_char ? 0 : 1)].min
+            end
+          end
+          row.last
+        end
+
+        def fingerprint(field, code, detail)
+          [field.source.owner, field.source.graphql_name, code, detail].join(":")
+        end
+      end
+    end
+  end
+end