graphql-doctor 0.1.0

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../ir"
+
+module GraphQL
+  module Doctor
+    module Checks
+      SEVERITIES = {
+        "GQLD102" => "info", "GQLD103" => "info",
+        "GQLD201" => "warning", "GQLD204" => "warning", "GQLD401" => "warning",
+        "GQLD202" => "error", "GQLD203" => "error", "GQLD205" => "error",
+        "GQLD301" => "error", "GQLD302" => "error", "GQLD303" => "error",
+        "GQLD305" => "info", "GQLD306" => "error", "GQLD307" => "error"
+      }.freeze
+
+      class Base
+        def initialize(source_index, config)
+          @source_index = source_index
+          @config = config
+        end
+
+        private
+
+        def diagnostic(code, message, location, suggestions: [], notes: [], fingerprint: nil)
+          return unless @config.check_enabled?(code)
+
+          Diagnostic.new(
+            code: code,
+            severity: @config.severity_for(code, SEVERITIES.fetch(code)),
+            message: message,
+            location: location,
+            suggestions: suggestions,
+            notes: notes,
+            fingerprint: fingerprint
+          )
+        end
+
+        def find_method(owner, name, source_location: nil)
+          method_at(source_location, name: name, singleton: false) ||
+            @source_index.method_definitions.reverse_each.find do |method|
+              method.owner == owner && method.name == name.to_sym && !method.singleton
+            end
+        end
+
+        def find_singleton_method(owner, name, source_location: nil)
+          method_at(source_location, name: name, singleton: true) ||
+            @source_index.method_definitions.reverse_each.find do |method|
+              method.owner == owner && method.name == name.to_sym && method.singleton
+            end
+        end
+
+        def method_target(field)
+          runtime = field.runtime
+          source = field.source
+          owner = runtime["resolver_class"] || source.owner
+          name = if runtime["resolver_class"] || source.options[:resolver_method] || source.options[:method]
+                   runtime["resolver_method"]
+                 else
+                   runtime["method_sym"]
+                 end
+          name = name.to_sym
+          method = reflected_method(
+            owner,
+            name,
+            source_location: runtime["resolver_source_location"],
+            signature: runtime["resolver_signature"],
+            fallback_location: source.definition_location
+          )
+          [owner, name, method]
+        end
+
+        def reflected_method(owner, name, source_location:, signature:, fallback_location:)
+          source_method = method_at(source_location, name: name, singleton: false)
+          if signature
+            return runtime_method(
+              owner, name, signature,
+              source_method&.location || fallback_location,
+              source_method&.parameter_locations || {}
+            )
+          end
+
+          source_method || find_method(owner, name, source_location: source_location)
+        end
+
+        def runtime_method(owner, name, signature, location, parameter_locations)
+          IR::MethodDefinition.new(
+            owner: owner,
+            name: name.to_sym,
+            visibility: signature.fetch("visibility").to_sym,
+            singleton: false,
+            required_keywords: signature.fetch("required_keywords").map(&:to_sym),
+            optional_keywords: signature.fetch("optional_keywords").map(&:to_sym),
+            keyword_defaults: {},
+            accepts_keyword_rest: signature.fetch("accepts_keyword_rest"),
+            forbids_keywords: false,
+            positionals: [],
+            location: location,
+            parameter_locations: parameter_locations,
+            dynamic: false,
+            required_positionals: signature.fetch("required_positionals"),
+            optional_positionals: signature.fetch("optional_positionals"),
+            accepts_positional_rest: signature.fetch("accepts_positional_rest")
+          )
+        end
+
+        def method_at(source_location, name:, singleton:)
+          return unless source_location
+
+          path, line = source_location
+          return unless path && line
+
+          @source_index.method_definitions.find do |method|
+            location = method.location
+            method.name == name.to_sym && method.singleton == singleton && location && location.start_line == line &&
+              path.tr("\\", "/").end_with?(location.path.tr("\\", "/"))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "argument_keyword_match"
+require_relative "resolver_method_presence"
+
+module GraphQL
+  module Doctor
+    module Checks
+      class Engine
+        def initialize(source_index, runtime_ir, correlation, config)
+          @source_index = source_index
+          @runtime_ir = runtime_ir
+          @correlation = correlation
+          @config = config
+        end
+
+        def call
+          checks = [
+            ResolverMethodPresence.new(@source_index, @config),
+            ArgumentKeywordMatch.new(@source_index, @config)
+          ]
+          diagnostics = @correlation.matched.flat_map do |field|
+            checks.flat_map { |check| check.call(field) }
+          end
+          diagnostics.concat(source_only_diagnostics)
+          diagnostics.concat(dynamic_diagnostics)
+          diagnostics.concat(orphan_diagnostics)
+          diagnostics.compact
+        end
+
+        private
+
+        def source_only_diagnostics
+          return [] unless @config.check_enabled?("GQLD102")
+
+          @correlation.source_only.filter_map do |field|
+            next if field.source.confidence == :dynamic
+
+            diagnostic("GQLD102", "Source field is absent from the runtime schema", field.source.definition_location)
+          end
+        end
+
+        def dynamic_diagnostics
+          return [] unless @config.check_enabled?("GQLD103")
+
+          @source_index.dynamics.filter_map do |definition|
+            diagnostic("GQLD103", "Dynamic #{definition.kind} definition could not be analyzed", definition.location)
+          end
+        end
+
+        def orphan_diagnostics
+          @runtime_ir.fetch("orphan_members", []).filter_map do |name|
+            type = @source_index.types.find { |definition| definition.owner == name }
+            next unless type
+
+            diagnostic("GQLD401", "Resolver or mutation `#{name}` is not registered in the schema", type.location)
+          end
+        end
+
+        def diagnostic(code, message, location)
+          return unless @config.check_enabled?(code)
+
+          Diagnostic.new(
+            code: code,
+            severity: @config.severity_for(code, SEVERITIES.fetch(code)),
+            message: message,
+            location: location,
+            fingerprint: [location.path, location.start_line, code].join(":")
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module GraphQL
+  module Doctor
+    module Checks
+      class ResolverMethodPresence < Base
+        def call(field)
+          return [] unless field.status == :matched && field.source.confidence != :dynamic
+          return [] if field.runtime["hash_key"] || field.runtime["dig_keys"]
+          return [] if field.source.options[:hash_key] || field.source.options[:dig]
+
+          owner, name, method = method_target(field)
+          return visibility_diagnostic(field, method) if method
+          return [] if field.runtime["resolver_source_location"]
+          return [] if field.runtime["underlying_method_defined"]
+          return [] if experimental_method?(owner)
+          return [] if @config["allow_underlying_object"].include?(field.source.owner)
+
+          [missing_diagnostic(field, owner, name)].compact
+        end
+
+        private
+
+        def visibility_diagnostic(field, method)
+          return [] if method.visibility == :public
+
+          [diagnostic(
+            "GQLD204",
+            "Resolver method `#{method.owner}##{method.name}` is #{method.visibility}",
+            method.location,
+            fingerprint: fingerprint(field, "GQLD204")
+          )].compact
+        end
+
+        def missing_diagnostic(field, owner, name)
+          options = field.source.options
+          if options[:resolver_method]
+            code = "GQLD202"
+            message = "Explicit resolver method `#{owner}##{name}` does not exist"
+          elsif field.runtime["resolver_class"]
+            code = "GQLD202"
+            message = "Resolver method `#{owner}##{name}` does not exist"
+          elsif options[:method] && field.runtime["underlying_object_class"]
+            code = "GQLD203"
+            target = field.runtime["underlying_object_class"]
+            message = "Explicit field method `#{target}##{field.runtime['method_sym']}` does not exist"
+          else
+            code = "GQLD201"
+            message = "Resolver method `#{owner}##{name}` was not found; the underlying object may provide it"
+          end
+          diagnostic(code, message, field.source.definition_location, fingerprint: fingerprint(field, code))
+        end
+
+        def fingerprint(field, code)
+          [field.source.owner, field.source.graphql_name, code].join(":")
+        end
+
+        def experimental_method?(owner)
+          return false unless @config["experimental"].fetch("new_execution_api", false)
+
+          %i[resolve_static resolve_batch resolve_each].any? { |name| find_method(owner, name) }
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/cli.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "etc"
+require_relative "../doctor"
+require_relative "reporters/text"
+require_relative "reporters/json"
+require_relative "reporters/sarif"
+require_relative "reporters/github"
+
+module GraphQL
+  module Doctor
+    class CLI
+      REPORTERS = {
+        "text" => Reporters::Text,
+        "json" => Reporters::Json,
+        "sarif" => Reporters::Sarif,
+        "github" => Reporters::Github
+      }.freeze
+      HELP = <<~TEXT
+        Usage: graphql-doctor COMMAND [options] [paths]
+
+        Commands:
+          check [paths]       Check resolver contracts (default)
+          dump-schema        Dump runtime schema as JSON
+          coverage           Show source/runtime mapping coverage
+          explain CODE       Explain a diagnostic
+          version            Print the version
+      TEXT
+
+      def self.start(argv = ARGV, out: $stdout, err: $stderr)
+        new(argv, out: out, err: err).run
+      end
+
+      def initialize(argv, out:, err:)
+        @argv = argv.dup
+        @out = out
+        @err = err
+      end
+
+      def run
+        if %w[help --help -h].include?(@argv.first)
+          @out.puts(HELP)
+          return 0
+        end
+
+        @argv[0] = {"--version" => "version", "-v" => "version"}.fetch(@argv.first, @argv.first)
+        command = @argv.first&.start_with?("-") ? "check" : (@argv.shift || "check")
+        case command
+        when "version"
+          @out.puts(VERSION)
+          0
+        when "help", "--help", "-h"
+          @out.puts(HELP)
+          0
+        when "check" then check
+        when "dump-schema"
+          dump_schema
+          0
+        when "coverage"
+          coverage
+          0
+        when "explain" then explain
+        else
+          @err.puts("Command #{command.inspect} is not implemented yet")
+          2
+        end
+      rescue Error, OptionParser::ParseError, SystemCallError => e
+        @err.puts(e.message)
+        2
+      end
+
+      private
+
+      def check
+        values = options
+        return 0 unless values
+
+        config = Config.load(values[:config], required: values[:config_given])
+        config = config.with_only(values[:only]) if values[:only]
+        result = Runner.new(
+          config: config,
+          cache: values[:cache],
+          jobs: values[:jobs],
+          boot: values[:boot],
+          schema_dump: values[:schema_dump]
+        ).check(@argv)
+        diagnostics = select_diagnostics(result.diagnostics, values[:only])
+        sort_diagnostics(diagnostics)
+        reporter(values[:format], output_io(values[:out]), values[:color]).report(diagnostics)
+        @err.puts("Runtime checks skipped: --no-boot") unless values[:boot] || values[:schema_dump]
+        return 2 if result.runtime_error
+
+        threshold = SEVERITY_RANK.fetch(values[:fail_level]) { raise Error, "Invalid fail level" }
+        diagnostics.any? { |diagnostic| SEVERITY_RANK.fetch(diagnostic.severity) >= threshold } ? 1 : 0
+      ensure
+        @output_file&.close
+        @output_file = nil
+      end
+
+      def options
+        values = {
+          config: ".graphql-doctor.yml", config_given: false, out: nil, schema_dump: nil, boot: true,
+          cache: true, jobs: Etc.nprocessors, format: "text", only: nil,
+          fail_level: "error", color: true
+        }
+        parser = OptionParser.new
+        configure_options(parser, values)
+        catch(:help) { parser.parse!(@argv) } || (return nil)
+        validate_options(values)
+        values
+      end
+
+      def configure_options(parser, values)
+        parser.banner = HELP.lines.first.chomp
+        parser.on("--config PATH") do |value|
+          values[:config] = value
+          values[:config_given] = true
+        end
+        parser.on("--out PATH") { |value| values[:out] = value }
+        parser.on("--schema-dump PATH") { |value| values[:schema_dump] = value }
+        parser.on("--no-boot") { values[:boot] = false }
+        parser.on("--[no-]cache") { |value| values[:cache] = value }
+        parser.on("--jobs N", Integer) { |value| values[:jobs] = value }
+        parser.on("--format FORMAT") { |value| values[:format] = value }
+        parser.on("--only CODES") { |value| values[:only] = value.split(",") }
+        parser.on("--fail-level LEVEL") { |value| values[:fail_level] = value }
+        parser.on("--[no-]color") { |value| values[:color] = value }
+        parser.on("--help") do
+          @out.puts(parser)
+          throw :help
+        end
+      end
+
+      def validate_options(values)
+        raise Error, "Unknown output format: #{values[:format]}" unless REPORTERS.key?(values[:format])
+        raise Error, "Invalid fail level: #{values[:fail_level]}" unless SEVERITY_RANK.key?(values[:fail_level])
+        raise Error, "Jobs must be greater than zero" unless values[:jobs].positive?
+
+        unknown = Array(values[:only]) - Config::CHECK_CODES
+        raise Error, "Unknown diagnostic code(s): #{unknown.join(', ')}" unless unknown.empty?
+      end
+
+      def select_diagnostics(diagnostics, only)
+        return diagnostics unless only
+
+        selected = only + Config::FIXED_ERROR_CODES
+        diagnostics.select { |diagnostic| selected.include?(diagnostic.code) }
+      end
+
+      def sort_diagnostics(diagnostics)
+        diagnostics.sort_by! do |diagnostic|
+          [diagnostic.location.path, diagnostic.location.start_line, diagnostic.location.start_column, diagnostic.code]
+        end
+      end
+
+      def dump_schema
+        values = options
+        return 0 unless values
+
+        config = Config.load(values[:config], required: values[:config_given])
+        source = Source::Loader.new(config: config, cache: values[:cache]).load([], jobs: values[:jobs])
+        schema = Runtime::SchemaLoader.load(config)
+        runtime = Runtime::Reflector.new(
+          schema, source_index: source, abstract_classes: config["abstract_classes"]
+        ).call
+        write_output(values[:out]) { |io| Runtime::Dump.write(runtime, io) }
+      end
+
+      def explain
+        code = @argv.shift.to_s.upcase
+        raise Error, "A diagnostic code is required" unless code.match?(/\AGQLD\d+\z/)
+
+        path = File.expand_path("../../../docs/diagnostics/#{code}.md", __dir__)
+        raise Error, "Unknown diagnostic code: #{code}" unless File.file?(path)
+
+        @out.write(File.read(path))
+        0
+      end
+
+      def coverage
+        values = options
+        return 0 unless values
+
+        config = Config.load(values[:config], required: values[:config_given])
+        source = Source::Loader.new(config: config, cache: values[:cache]).load(@argv, jobs: values[:jobs])
+        runtime = runtime_ir(values, config, source)
+        correlation = Correlation::Correlator.new(source, runtime)
+        write_output(values[:out]) do |io|
+          total = correlation.matched.length + correlation.runtime_only.length
+          io.puts format("Mapped fields: %<matched>d/%<total>d (%<ratio>.1f%%)",
+                         matched: correlation.matched.length, total: total, ratio: correlation.mapped_field_ratio * 100)
+          correlation.runtime_only.each do |field|
+            io.puts "Unmapped runtime field: #{field.runtime['owner']}.#{field.runtime['graphql_name']}"
+          end
+          source.dynamics.each do |definition|
+            io.puts "Dynamic definition: #{definition.location.path}:#{definition.location.start_line}"
+          end
+        end
+      end
+
+      def runtime_ir(values, config, source)
+        return Runtime::Dump.read(values[:schema_dump]) if values[:schema_dump]
+        raise Error, "--no-boot requires --schema-dump" unless values[:boot]
+
+        schema = Runtime::SchemaLoader.load(config)
+        Runtime::Reflector.new(schema, source_index: source, abstract_classes: config["abstract_classes"]).call
+      end
+
+      def write_output(path, &)
+        return yield(@out) unless path
+
+        File.open(path, "w", &)
+      end
+
+      def output_io(path)
+        return @out unless path
+
+        @output_file = File.open(path, "w")
+      end
+
+      def reporter(format, io, color)
+        REPORTERS.fetch(format).new(io: io, color: color)
+      end
+    end
+  end
+end

data/lib/graphql/doctor/config.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module GraphQL
+  module Doctor
+    class Config
+      DEFAULTS = {
+        "schema" => nil,
+        "require" => "./config/environment",
+        "include" => ["app/graphql/**/*.rb"],
+        "exclude" => [],
+        "checks" => {
+          "GQLD102" => {"enabled" => false},
+          "GQLD103" => {"enabled" => false},
+          "GQLD201" => {"severity" => "warning"},
+          "GQLD305" => {"enabled" => false}
+        },
+        "allow_underlying_object" => [],
+        "abstract_classes" => [],
+        "experimental" => {"new_execution_api" => false},
+        "require_suppression_reason" => false
+      }.freeze
+      CHECK_CODES = %w[
+        GQLD101 GQLD102 GQLD103 GQLD104 GQLD201 GQLD202 GQLD203 GQLD204 GQLD205
+        GQLD301 GQLD302 GQLD303 GQLD305 GQLD306 GQLD307 GQLD401
+      ].freeze
+      FIXED_ERROR_CODES = %w[GQLD101 GQLD104].freeze
+      CONFIGURABLE_CHECK_CODES = (CHECK_CODES - FIXED_ERROR_CODES).freeze
+
+      attr_reader :values
+
+      def initialize(values = {})
+        raise Error, "Configuration must be a mapping" unless values.is_a?(Hash)
+
+        unknown = values.keys.map(&:to_s) - DEFAULTS.keys
+        raise Error, "Unknown configuration key(s): #{unknown.join(', ')}" unless unknown.empty?
+
+        normalized = values.to_h { |key, value| [key.to_s, value] }
+        normalized["checks"] = normalize_checks(normalized.fetch("checks", {}))
+        normalized["experimental"] = normalize_experimental(normalized.fetch("experimental", {}))
+        validate_values(normalized)
+        merged = DEFAULTS.merge(normalized)
+        merged["checks"] = DEFAULTS["checks"].merge(normalized.fetch("checks", {}))
+        @values = immutable(merged)
+      end
+
+      def self.load(path = ".graphql-doctor.yml", required: false)
+        unless File.file?(path)
+          raise Error, "Configuration file does not exist: #{path}" if required
+
+          return new
+        end
+
+        content = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false) || {}
+        raise Error, "Configuration must be a mapping" unless content.is_a?(Hash)
+
+        new(content)
+      rescue Psych::Exception => e
+        raise Error, "Invalid configuration: #{e.message}"
+      end
+
+      def [](key)
+        values.fetch(key.to_s)
+      end
+
+      def check_enabled?(code)
+        values["checks"].fetch(code, {}).fetch("enabled", true)
+      end
+
+      def severity_for(code, default)
+        values["checks"].fetch(code, {}).fetch("severity", default).to_s
+      end
+
+      def with_only(codes)
+        checks = CONFIGURABLE_CHECK_CODES.to_h do |code|
+          settings = values["checks"].fetch(code, {}).merge("enabled" => codes.include?(code))
+          [code, settings]
+        end
+        self.class.new(values.merge("checks" => checks))
+      end
+
+      private
+
+      def normalize_checks(checks)
+        raise Error, "Configuration key `checks` must be a mapping" unless checks.is_a?(Hash)
+
+        checks.to_h do |code, settings|
+          code = code.to_s
+          raise Error, "Unknown diagnostic code in configuration: #{code}" unless CHECK_CODES.include?(code)
+          raise Error, "Check settings for #{code} must be a mapping" unless settings.is_a?(Hash)
+
+          settings = settings.to_h { |key, value| [key.to_s, value] }
+          validate_check_settings(code, settings)
+          [code, settings]
+        end
+      end
+
+      def validate_check_settings(code, settings)
+        if FIXED_ERROR_CODES.include?(code) && !settings.empty?
+          raise Error, "#{code} is an execution error and cannot be configured"
+        end
+
+        unknown = settings.keys - %w[enabled severity]
+        raise Error, "Unknown check setting(s) for #{code}: #{unknown.join(', ')}" unless unknown.empty?
+        if settings.key?("severity") && !SEVERITY_RANK.key?(settings["severity"].to_s)
+          raise Error, "Invalid severity for #{code}: #{settings['severity']}"
+        end
+        return if !settings.key?("enabled") || [true, false].include?(settings["enabled"])
+
+        raise Error, "Invalid enabled value for #{code}: #{settings['enabled'].inspect}"
+      end
+
+      def normalize_experimental(settings)
+        raise Error, "Configuration key `experimental` must be a mapping" unless settings.is_a?(Hash)
+
+        normalized = settings.to_h { |key, value| [key.to_s, value] }
+        unknown = normalized.keys - ["new_execution_api"]
+        raise Error, "Unknown experimental setting(s): #{unknown.join(', ')}" unless unknown.empty?
+
+        value = normalized["new_execution_api"]
+        return normalized unless normalized.key?("new_execution_api")
+        return normalized if [true, false].include?(value)
+
+        raise Error, "Invalid experimental setting `new_execution_api`: #{value.inspect}"
+      end
+
+      def validate_values(values)
+        validate_string_values(values)
+        validate_array_values(values)
+        return unless values.key?("require_suppression_reason")
+        return if [true, false].include?(values["require_suppression_reason"])
+
+        raise Error, "Configuration key `require_suppression_reason` must be boolean"
+      end
+
+      def validate_string_values(values)
+        %w[schema require].each do |key|
+          next unless values.key?(key)
+          next if values[key].nil? || values[key].is_a?(String)
+
+          raise Error, "Configuration key `#{key}` must be a string"
+        end
+        return unless values["schema"].is_a?(String) && values["schema"].strip.empty?
+
+        raise Error, "Configuration key `schema` must not be empty"
+      end
+
+      def validate_array_values(values)
+        %w[include exclude allow_underlying_object abstract_classes].each do |key|
+          next unless values.key?(key)
+          next if values[key].is_a?(Array) && values[key].all?(String)
+
+          raise Error, "Configuration key `#{key}` must be an array of strings"
+        end
+      end
+
+      def immutable(value)
+        case value
+        when Hash then value.transform_values { |item| immutable(item) }.freeze
+        when Array then value.map { |item| immutable(item) }.freeze
+        when String then value.dup.freeze
+        else value.freeze
+        end
+      end
+    end
+  end
+end