graphql-doctor 0.1.0

data/lib/graphql/doctor/correlation/correlator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    module Correlation
+      CorrelatedField = Struct.new(:source, :runtime, :status, keyword_init: true)
+
+      class Correlator
+        attr_reader :fields
+
+        def initialize(source_index, runtime_ir)
+          @source_index = source_index
+          @runtime_fields = runtime_ir.fetch("types", []).flat_map { |type| type.fetch("fields", []) }
+          @fields = correlate
+        end
+
+        def matched
+          fields.select { |field| field.status == :matched }
+        end
+
+        def runtime_only
+          fields.select { |field| field.status == :runtime_only }
+        end
+
+        def source_only
+          fields.select { |field| field.status == :source_only }
+        end
+
+        def mapped_field_ratio
+          denominator = matched.length + runtime_only.length
+          denominator.zero? ? 1.0 : matched.length.fdiv(denominator)
+        end
+
+        private
+
+        def correlate
+          remaining = @source_index.fields.dup
+          correlations = @runtime_fields.map do |runtime|
+            source = find_source(remaining, runtime)
+            remaining.delete(source) if source
+            CorrelatedField.new(source: source, runtime: runtime, status: source ? :matched : :runtime_only)
+          end
+          correlations + remaining.map do |source|
+            CorrelatedField.new(source: source, runtime: nil, status: :source_only)
+          end
+        end
+
+        def find_source(sources, runtime)
+          sources.find do |source|
+            source.owner == runtime["owner"] && source.ruby_name.to_s == runtime["method_sym"]
+          end || sources.find do |source|
+            source.owner == runtime["owner"] && source.graphql_name == runtime["graphql_name"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/diagnostic.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    SEVERITY_RANK = {"error" => 3, "warning" => 2, "info" => 1}.freeze
+
+    Suggestion = Struct.new(:message, :replacement, :location, keyword_init: true) do
+      def initialize(**attributes)
+        super
+        freeze
+      end
+
+      def to_h
+        {message: message, replacement: replacement, location: location&.to_h}.compact
+      end
+    end
+
+    Diagnostic = Struct.new(
+      :code, :severity, :message, :location, :suggestions, :notes, :fingerprint,
+      keyword_init: true
+    ) do
+      def initialize(suggestions: [], notes: [], **attributes)
+        super(suggestions: suggestions.freeze, notes: notes.freeze, **attributes)
+        freeze
+      end
+
+      def self.from_h(hash)
+        values = hash.transform_keys(&:to_sym)
+        values[:location] = Location.from_h(values[:location]) if values[:location]
+        values[:suggestions] = Array(values[:suggestions]).map do |suggestion|
+          suggestion = suggestion.transform_keys(&:to_sym)
+          suggestion[:location] = Location.from_h(suggestion[:location]) if suggestion[:location]
+          Suggestion.new(**suggestion)
+        end
+        new(**values)
+      end
+
+      def to_h
+        {
+          code: code,
+          severity: severity.to_s,
+          message: message,
+          location: location&.to_h,
+          suggestions: suggestions.map(&:to_h),
+          notes: notes,
+          fingerprint: fingerprint
+        }.compact
+      end
+    end
+  end
+end

data/lib/graphql/doctor/ir.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    module IR
+      TypeDefinition = Struct.new(:owner, :superclass, :kind, :location, :confidence, keyword_init: true)
+      FieldDefinition = Struct.new(
+        :owner, :graphql_name, :ruby_name, :type_expression, :options, :arguments,
+        :block_location, :definition_location, :confidence,
+        keyword_init: true
+      )
+      ArgumentDefinition = Struct.new(
+        :owner, :field_name, :graphql_name, :ruby_name, :type_expression, :required,
+        :default_value, :loads, :as, :prepare, :extras, :definition_location, :confidence,
+        keyword_init: true
+      )
+      MethodDefinition = Struct.new(
+        :owner, :name, :visibility, :singleton, :required_keywords, :optional_keywords,
+        :keyword_defaults, :accepts_keyword_rest, :forbids_keywords, :positionals,
+        :location, :parameter_locations, :dynamic, :required_positionals, :optional_positionals,
+        :accepts_positional_rest,
+        keyword_init: true
+      )
+      InterfaceImplementation = Struct.new(:owner, :interface, :location, keyword_init: true)
+      MutationRegistration = Struct.new(:owner, :mutation, :location, keyword_init: true)
+      DynamicDefinition = Struct.new(:owner, :kind, :reason, :location, keyword_init: true)
+      SourceComment = Struct.new(:text, :location, keyword_init: true)
+    end
+  end
+end

data/lib/graphql/doctor/location.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module GraphQL
+  module Doctor
+    Location = Struct.new(
+      :path, :start_line, :end_line, :start_column, :end_column, :start_offset, :end_offset,
+      keyword_init: true
+    ) do
+      def initialize(**attributes)
+        super
+        freeze
+      end
+
+      def self.from_prism(path, location)
+        new(
+          path: path,
+          start_line: location.start_line,
+          end_line: location.end_line,
+          start_column: location.start_column,
+          end_column: location.end_column,
+          start_offset: location.start_offset,
+          end_offset: location.end_offset
+        )
+      end
+
+      def self.from_h(hash)
+        new(**hash.transform_keys(&:to_sym))
+      end
+
+      def to_h
+        members.to_h { |name| [name, public_send(name)] }
+      end
+
+      def start_code_units_column(encoding = Encoding::UTF_16LE)
+        code_units_columns(encoding).first
+      end
+
+      def end_code_units_column(encoding = Encoding::UTF_16LE)
+        code_units_columns(encoding).last
+      end
+
+      def code_units_columns(encoding = Encoding::UTF_16LE, source: nil)
+        source ||= Prism.parse(File.binread(path)).source
+        [source.code_units_column(start_offset, encoding), source.code_units_column(end_offset, encoding)]
+      rescue SystemCallError, EncodingError, RuntimeError
+        [start_column, end_column]
+      end
+    end
+  end
+end

data/lib/graphql/doctor/reporters/github.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    module Reporters
+      class Github
+        LEVELS = {"error" => "error", "warning" => "warning", "info" => "notice"}.freeze
+
+        def initialize(io:, **)
+          @io = io
+        end
+
+        def report(diagnostics)
+          diagnostics.each do |diagnostic|
+            location = diagnostic.location
+            properties = "file=#{escape_property(location.path)},line=#{location.start_line}," \
+                         "col=#{location.start_column + 1},title=#{diagnostic.code}"
+            @io.puts "::#{LEVELS.fetch(diagnostic.severity)} #{properties}::#{escape_message(diagnostic.message)}"
+          end
+        end
+
+        private
+
+        def escape_property(value)
+          escape_message(value).gsub(":", "%3A").gsub(",", "%2C")
+        end
+
+        def escape_message(value)
+          value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/reporters/json.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQL
+  module Doctor
+    module Reporters
+      class Json
+        def initialize(io:, **)
+          @io = io
+        end
+
+        def report(diagnostics)
+          @io.puts JSON.pretty_generate(diagnostics.map(&:to_h))
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/reporters/sarif.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module GraphQL
+  module Doctor
+    module Reporters
+      class Sarif
+        SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+
+        def initialize(io:, **)
+          @io = io
+          @sources = {}
+        end
+
+        def report(diagnostics)
+          @io.puts JSON.pretty_generate(
+            "version" => "2.1.0",
+            "$schema" => SCHEMA,
+            "runs" => [{
+              "tool" => {"driver" => driver(diagnostics)},
+              "columnKind" => "unicodeCodePoints",
+              "results" => diagnostics.map { |diagnostic| result(diagnostic) }
+            }]
+          )
+        end
+
+        private
+
+        def driver(diagnostics)
+          {
+            "name" => "graphql-doctor",
+            "version" => VERSION,
+            "informationUri" => "https://github.com/ydah/graphql-doctor",
+            "rules" => diagnostics.uniq(&:code).map do |diagnostic|
+              {
+                "id" => diagnostic.code,
+                "shortDescription" => {"text" => diagnostic.message.lines.first.chomp},
+                "helpUri" => "https://github.com/ydah/graphql-doctor/blob/main/docs/diagnostics/#{diagnostic.code}.md"
+              }
+            end
+          }
+        end
+
+        def result(diagnostic)
+          location = diagnostic.location
+          start_column, end_column = code_units_columns(location)
+          {
+            "ruleId" => diagnostic.code,
+            "level" => {"error" => "error", "warning" => "warning", "info" => "note"}.fetch(diagnostic.severity),
+            "message" => {"text" => diagnostic.message},
+            "locations" => [{
+              "physicalLocation" => {
+                "artifactLocation" => {"uri" => location.path},
+                "region" => {
+                  "startLine" => location.start_line,
+                  "startColumn" => start_column + 1,
+                  "endLine" => location.end_line,
+                  "endColumn" => end_column + 1
+                }
+              }
+            }],
+            "partialFingerprints" => {"primaryLocationLineHash" => fingerprint(diagnostic)}
+          }
+        end
+
+        def fingerprint(diagnostic)
+          value = diagnostic.fingerprint || [diagnostic.code, diagnostic.location.path, diagnostic.message].join(":")
+          Digest::SHA256.hexdigest(value)
+        end
+
+        def code_units_columns(location)
+          source = @sources[location.path] ||= Prism.parse(File.binread(location.path)).source
+          location.code_units_columns(Encoding::UTF_32LE, source: source)
+        rescue SystemCallError
+          [location.start_column, location.end_column]
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/reporters/text.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    module Reporters
+      class Text
+        def initialize(io:, color: true)
+          @io = io
+          @color = color && !ENV.key?("NO_COLOR")
+        end
+
+        def report(diagnostics)
+          diagnostics.each { |diagnostic| render(diagnostic) }
+        end
+
+        private
+
+        def render(diagnostic)
+          location = diagnostic.location
+          @io.puts "#{location.path}:#{location.start_line}:#{location.start_column + 1}: " \
+                   "#{paint(diagnostic.severity, diagnostic.severity)} #{diagnostic.code}: #{diagnostic.message}"
+          render_source(location)
+          diagnostic.suggestions.each { |suggestion| @io.puts "  #{suggestion.message}" }
+          diagnostic.notes.each { |note| @io.puts "  Note: #{note}" }
+        end
+
+        def render_source(location)
+          line = File.readlines(location.path, chomp: true)[location.start_line - 1]
+          return unless line
+
+          width = [location.end_column - location.start_column, 1].max
+          @io.puts "  #{line}"
+          @io.puts "  #{' ' * location.start_column}#{'^' * width}"
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def paint(text, severity)
+          return text unless @color
+
+          code = {"error" => 31, "warning" => 33, "info" => 36}.fetch(severity.to_s, 0)
+          "\e[#{code}m#{text}\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/graphql/doctor/runner.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Doctor
+    class Runner
+      Result = Struct.new(:diagnostics, :runtime_error, keyword_init: true)
+
+      def initialize(config:, root: Dir.pwd, cache: true, jobs: 1, boot: true, schema_dump: nil)
+        @config = config
+        @root = root
+        @cache = cache
+        @jobs = jobs
+        @boot = boot
+        @schema_dump = schema_dump
+      end
+
+      def check(paths = [])
+        source = Source::Loader.new(root: @root, config: @config, cache: @cache).load(paths, jobs: @jobs)
+        runtime = load_runtime(source)
+        return Result.new(diagnostics: static_diagnostics(source), runtime_error: false) unless runtime
+
+        correlation = Correlation::Correlator.new(source, runtime)
+        diagnostics = Checks::Engine.new(source, runtime, correlation, @config).call
+        diagnostics = Suppression.filter(
+          source.diagnostics + diagnostics,
+          source.comments,
+          require_reason: @config["require_suppression_reason"]
+        )
+        Result.new(diagnostics: diagnostics, runtime_error: false)
+      rescue Error => e
+        location = Location.new(
+          path: @config["require"].to_s, start_line: 1, end_line: 1,
+          start_column: 0, end_column: 1, start_offset: 0, end_offset: 1
+        )
+        message = e.message.sub(/\AGQLD101:\s*/, "")
+        diagnostic = Diagnostic.new(code: "GQLD101", severity: "error", message: message, location: location)
+        diagnostics = defined?(source) && source ? static_diagnostics(source) : []
+        Result.new(diagnostics: diagnostics + [diagnostic], runtime_error: true)
+      end
+
+      private
+
+      def load_runtime(source)
+        return Runtime::Dump.read(@schema_dump) if @schema_dump
+        return unless @boot
+
+        schema = Runtime::SchemaLoader.load(@config, root: @root)
+        Runtime::Reflector.new(
+          schema, source_index: source, abstract_classes: @config["abstract_classes"]
+        ).call
+      end
+
+      def static_diagnostics(source)
+        diagnostics = source.diagnostics.dup
+        if @config.check_enabled?("GQLD103")
+          diagnostics.concat(source.dynamics.map do |definition|
+            Diagnostic.new(
+              code: "GQLD103",
+              severity: @config.severity_for("GQLD103", "info"),
+              message: "Dynamic #{definition.kind} definition could not be analyzed",
+              location: definition.location
+            )
+          end)
+        end
+        Suppression.filter(
+          diagnostics, source.comments, require_reason: @config["require_suppression_reason"]
+        )
+      end
+    end
+  end
+end

data/lib/graphql/doctor/runtime/dump.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQL
+  module Doctor
+    module Runtime
+      module Dump
+        module_function
+
+        def write(runtime_ir, io)
+          io.write(JSON.pretty_generate(runtime_ir))
+          io.write("\n")
+        end
+
+        def read(path)
+          value = JSON.parse(File.read(path))
+          raise Error, "Schema dump must be an object" unless value.is_a?(Hash)
+          raise Error, "Unsupported schema dump version: #{value['version']}" unless value["version"] == 1
+          raise Error, "Schema dump types must be an array" unless value["types"].is_a?(Array)
+
+          validate_types(value["types"])
+          orphans = value.fetch("orphan_members", [])
+          unless orphans.is_a?(Array) && orphans.all?(String)
+            raise Error, "Schema dump orphan_members must be an array of strings"
+          end
+
+          value
+        rescue JSON::ParserError, SystemCallError => e
+          raise Error, "Invalid schema dump: #{e.message}"
+        end
+
+        def validate_types(types)
+          types.each { |type| validate_type(type) }
+        end
+
+        def validate_type(type)
+          raise Error, "Schema dump type must be an object" unless type.is_a?(Hash)
+
+          fields = type.fetch("fields", [])
+          raise Error, "Schema dump fields must be an array" unless fields.is_a?(Array)
+
+          fields.each { |field| validate_field(field) }
+        end
+
+        def validate_field(field)
+          keys = %w[owner graphql_name method_sym resolver_method]
+          valid = field.is_a?(Hash) && keys.all? { |key| field[key].is_a?(String) }
+          raise Error, "Schema dump field is invalid" unless valid
+
+          validate_field_values(field)
+
+          arguments = field.fetch("arguments", [])
+          validate_field_collections(arguments, field.fetch("extras", []), field.fetch("extensions", []))
+          return if arguments.all? { |argument| valid_argument?(argument) }
+
+          raise Error, "Schema dump argument is invalid"
+        end
+
+        def validate_field_values(field)
+          unless %w[resolver_class type hash_key underlying_object_class].all? do |key|
+            optional_string?(field, key)
+          end
+            raise Error, "Schema dump field values are invalid"
+          end
+          unless source_location?(field["resolver_source_location"]) &&
+                 optional_boolean?(field, "underlying_method_defined") &&
+                 method_signature?(field["resolver_signature"]) &&
+                 callback_locations?(field) && callback_signatures?(field)
+            raise Error, "Schema dump field values are invalid"
+          end
+        end
+
+        def validate_field_collections(arguments, extras, extensions)
+          unless arguments.is_a?(Array) && [extras, extensions].all? do |items|
+            items.is_a?(Array) && items.all?(String)
+          end
+            raise Error, "Schema dump field collections must be arrays"
+          end
+        end
+
+        def valid_argument?(argument)
+          return false unless argument.is_a?(Hash)
+          return false unless %w[graphql_name keyword].all? { |key| argument[key].is_a?(String) }
+          return false unless %w[type loads as prepare].all? { |key| optional_string?(argument, key) }
+          return false unless source_location?(argument["prepare_source_location"])
+          return false unless optional_boolean?(argument, "prepare_method_valid")
+          return false unless [nil, "object", "resolver"].include?(argument["prepare_method_dispatch"])
+
+          %w[non_null required has_default].all? do |key|
+            !argument.key?(key) || argument[key] == true || argument[key] == false
+          end
+        end
+
+        def optional_string?(value, key)
+          !value.key?(key) || value[key].nil? || value[key].is_a?(String)
+        end
+
+        def optional_boolean?(value, key)
+          !value.key?(key) || value[key].nil? || value[key] == true || value[key] == false
+        end
+
+        def source_location?(value)
+          value.nil? || (value.is_a?(Array) && value.length == 2 && value[0].is_a?(String) && value[1].is_a?(Integer))
+        end
+
+        def callback_locations?(field)
+          callbacks = field.fetch("callback_source_locations", {})
+          callbacks.is_a?(Hash) && callbacks.keys.all? { |name| %w[ready? authorized?].include?(name) } &&
+            callbacks.values.all? { |location| source_location?(location) }
+        end
+
+        def callback_signatures?(field)
+          callbacks = field.fetch("callback_signatures", {})
+          callbacks.is_a?(Hash) && callbacks.keys.all? { |name| %w[ready? authorized?].include?(name) } &&
+            callbacks.values.all? { |signature| method_signature?(signature) }
+        end
+
+        def method_signature?(signature)
+          return true if signature.nil?
+          return false unless signature.is_a?(Hash)
+          return false unless %w[public protected private].include?(signature["visibility"])
+          return false unless %w[required_keywords optional_keywords].all? do |key|
+            signature[key].is_a?(Array) && signature[key].all?(String)
+          end
+          return false unless %w[accepts_keyword_rest accepts_positional_rest].all? do |key|
+            [true, false].include?(signature[key])
+          end
+
+          %w[required_positionals optional_positionals].all? do |key|
+            signature[key].is_a?(Integer) && signature[key] >= 0
+          end
+        end
+      end
+    end
+  end
+end