graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/internal/schemas.rb

@@ -0,0 +1,50 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphWeaver
+  module Internal
+    # The graphql-ruby schema classes already in this process, and what each
+    # one defines. Where {SchemaLoader} *builds* a schema from a source — a
+    # path, SDL, an introspection dump — this reads classes the app loaded
+    # itself.
+    #
+    # Two features ask exactly these two questions, and match a schema on the
+    # coordinates it defines rather than on its class name: {Internal::Subgraphs}
+    # (which schema serves which subgraph) and {Federation::Drift} (has a
+    # subgraph changed without a recompose). What they share is this evidence,
+    # not the verdict: Subgraphs wants every type AND field, Drift only the
+    # types — a schema that lost a field is not a candidate to run against, but
+    # is exactly the one Drift has to recognize to report the loss.
+    module Schemas
+      class << self
+        # Every named GraphQL::Schema in the process. An anonymous one is
+        # graphql-ruby building from SDL — the router's own view of the
+        # supergraph is one — and never an app's subgraph.
+        def loaded
+          descendants(GraphQL::Schema).select(&:name)
+        end
+
+        # Does this schema carry the coordinate — "Type", or "Type.field"?
+        def defines?(schema, coordinate)
+          type_name, field_name = coordinate.split(".", 2)
+          type = schema.get_type(type_name) or return false
+          return true unless field_name
+
+          return type.fields.key?(field_name) if type.respond_to?(:fields)
+          # an input object's members are arguments, not fields
+          return type.arguments.key?(field_name) if type.respond_to?(:arguments)
+
+          false
+        end
+
+        private
+
+        def descendants(klass)
+          klass.subclasses.flat_map { |subclass| [subclass] + descendants(subclass) }
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/selection.rb

@@ -0,0 +1,127 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphWeaver
+  module Internal
+    # Shared query-selection walking — the rules Codegen, FakeClient, and
+    # the cassette Anonymizer all follow, in one place so they can't drift:
+    # how fragments flatten into selections, and when a type condition
+    # applies. Hosts set @schema and call load_operation before walking.
+    module Selection
+      include Kernel # for sorbet: hosts are Objects
+
+      # Every method here becomes an instance method of its host (Codegen,
+      # FakeClient, the cassette Anonymizer) — private so the walk stays the
+      # host's own business rather than part of its API.
+      private
+
+      # Parse a query, stash its fragment definitions for the walk, and
+      # return the operation.
+      def load_operation(query)
+        doc = GraphQL.parse(query)
+        @fragments = doc.definitions
+          .grep(GraphQL::Language::Nodes::FragmentDefinition)
+          .to_h { |fragment| [fragment.name, fragment] }
+
+        operations = doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition)
+        # One file, one operation. Requests do carry operationName now, so a
+        # second operation would run fine on the wire — what has no answer is
+        # naming: a module is named after its FILE (person.graphql =>
+        # PersonQuery), and one file can't name two. A convention, not a limit.
+        if operations.size > 1
+          names = operations.map { |op| op.name ? "'#{op.name}'" : "an anonymous operation" }
+          raise GraphWeaver::Error,
+            "document defines #{operations.size} operations (#{names.join(", ")}) — " \
+            "split them into one file each, since a module is named after its file"
+        end
+
+        operations.first
+      end
+
+      # The schema type an operation's selections start from.
+      def operation_root_type(operation)
+        case operation&.operation_type
+        when "query", nil then @schema.query
+        when "mutation" then @schema.mutation
+        else raise GraphWeaver::Error, "unsupported operation: #{operation.operation_type}"
+        end
+      end
+
+      # Flatten a selection set as seen by `type`, yielding (result_key,
+      # field_node, conditional) per field: plain fields yield directly; inline
+      # fragments and named spreads recurse when their type condition applies.
+      # `conditional` is true when any fragment on the way down carried
+      # @skip/@include — the whole block may be absent from the response, so
+      # everything under it is as optional as a directly-skipped field.
+      def each_field(type, selections, visiting = Set.new, conditional: false, &block)
+        selections.each do |selection|
+          case selection
+          when GraphQL::Language::Nodes::Field
+            yield(selection.alias || selection.name, selection, conditional)
+          when GraphQL::Language::Nodes::InlineFragment
+            next unless applies?(selection.type&.name, type)
+
+            each_field(type, selection.selections, visiting,
+              conditional: conditional || conditional?(selection), &block)
+          when GraphQL::Language::Nodes::FragmentSpread
+            fragment = @fragments.fetch(selection.name) do
+              raise ArgumentError, "unknown fragment: #{selection.name}"
+            end
+            if visiting.include?(selection.name)
+              raise GraphWeaver::Error, "fragment cycle through #{selection.name}"
+            end
+
+            if applies?(fragment.type.name, type)
+              # the directive rides on the SPREAD, not the definition it names
+              each_field(type, fragment.selections, visiting | [selection.name],
+                conditional: conditional || conditional?(selection), &block)
+            end
+          else
+            raise GraphWeaver::Error, "unsupported selection: #{selection.class}"
+          end
+        end
+      end
+
+      # each_field grouped by result key: repeated selections of one field
+      # (`a { x } a { y }`, or the same field reached through two fragments)
+      # collect together, so callers MERGE their sub-selections rather than
+      # last-writer-wins. Codegen relies on this; FakeClient/Anonymizer must too,
+      # or they'd fabricate/keep a shape the generated struct can't cast.
+      def gather(type, selections)
+        gather_conditional(type, selections).transform_values { |occurrences| occurrences.map(&:first) }
+      end
+
+      # gather, keeping each occurrence's [field_node, conditional] — the wire
+      # key is guaranteed only when SOME occurrence is unconditional.
+      def gather_conditional(type, selections)
+        out = {}
+        each_field(type, selections) { |key, node, conditional| (out[key] ||= []) << [node, conditional] }
+        out
+      end
+
+      # Directives that can drop a selection from the response whatever the
+      # schema says — the reason a conditional field's generated type is nilable.
+      CONDITIONAL_DIRECTIVES = %w[skip include].freeze
+
+      # Is this AST node (field, inline fragment, or spread) behind @skip/@include?
+      def conditional?(node)
+        node.directives.any? { |directive| CONDITIONAL_DIRECTIVES.include?(directive.name) }
+      end
+
+      # A fragment's type condition applies when it names this type exactly,
+      # or an interface/union this type belongs to (`... on Named { ... }`).
+      def applies?(condition, type)
+        return true if condition.nil? || condition == type.graphql_name
+
+        condition_type = @schema.get_type(condition)
+        return false unless condition_type
+
+        kind = condition_type.kind.name
+        (kind == "INTERFACE" || kind == "UNION") &&
+          @schema.possible_types(condition_type).include?(type)
+      end
+    end
+  end
+end

data/lib/graph_weaver/{testing → internal}/subgraphs.rb

@@ -4,10 +4,10 @@
 require "graphql"
 
 require_relative "../schema_loader"
-require_relative "../schemas"
+require_relative "schemas"
 
 module GraphWeaver
-  module Testing
+  module Internal
     # Which Ruby schema serves which subgraph — for the subgraphs this
     # process serves at all.
     #
@@ -19,19 +19,20 @@ module GraphWeaver
     # `AccountsSchema`, `Subgraphs::Accounts`), and a wrong guess points a
     # suite at the wrong resolvers and still passes.
     #
-    # Two matches refuse, naming both — both fit the evidence, so picking
-    # either would be the guess this module exists to avoid. **No match is
-    # not a refusal**: a supergraph is routinely only partly local, the rest
-    # served by another process, so a subgraph nothing here defines is left
-    # out of the map. Only a query that reaches its fields fails, at plan
-    # time — see {Router}.
+    # Neither of the two ways detection can come up short is a reason to
+    # refuse a whole suite, because neither is a fact about the query in
+    # hand. **No match** means the subgraph runs in another process, which is
+    # routine mid-migration. **Two matches** means two loaded classes fit the
+    # evidence equally, and picking one would be the guess this module exists
+    # to avoid. Both leave the subgraph unserved, and {Router} refuses the
+    # query that reaches its fields — each with its own fix.
     #
     # `"reviews" => :fake` asks for schema-correct fabricated data instead of
     # that refusal (see {FakeSubgraph}).
     #
-    # The same check runs over a map you pass explicitly, which is how a
-    # swapped pair fails at construction rather than as a mystery three
-    # fetches later.
+    # A map you pass explicitly is a claim rather than a derivation, so it
+    # goes through the same check *and refuses at construction* — a swapped
+    # pair fails there rather than as a mystery three fetches later.
     module Subgraphs
       # how many coordinates a message names before it says "and N more"
       SAMPLE = 5
@@ -39,29 +40,38 @@ module GraphWeaver
       # answer this subgraph with fabricated data rather than refusing
       FAKE = :fake
 
+      # What detection settled and what it couldn't: `served` is
+      # { "accounts" => Accounts::Schema, … } (with FAKE for a faked one),
+      # `ambiguous` is { "reviews" => ["App::Reviews::Schema", …] } for the
+      # ones several loaded classes fit. A subgraph in neither is absent.
+      Resolution = Struct.new(:served, :ambiguous)
+
       class << self
-        # { "accounts" => Accounts::Schema, … } for the subgraphs this
-        # process serves — one nothing defines is absent, and left out.
         # Names in `given` skip detection (:fake included); the rest are
         # derived, and both go through the same check.
         def resolve(table, given = nil, schemas: nil)
-          named = (given || {}).to_h { |name, schema| [name.to_s, schema] }
-          unknown = named.keys - table.subgraphs
-          if unknown.any?
-            raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
-              "this supergraph doesn't have (its subgraphs are #{table.subgraphs.join(", ")})"
+          named = table.named_subgraphs(given)
+          searched = schemas || Schemas.loaded
+          resolution = Resolution.new({}, {})
+          table.subgraphs.each do |name|
+            if named.key?(name)
+              resolution.served[name] = check!(table, name, named[name])
+              next
+            end
+
+            found = candidates(table, name, searched)
+            next resolution.served[name] = found.first if found.one?
+            # by name: a dev reload leaves two class objects spelled the same,
+            # and naming one of them twice reads as a bug in the message
+            resolution.ambiguous[name] = found.map(&:name).uniq.sort if found.any?
           end
-
-          searched = schemas || GraphWeaver::Schemas.loaded
-          table.subgraphs.filter_map do |name|
-            served = named.key?(name) ? check!(table, name, named[name]) : detect(table, name, searched)
-            [name, served] if served
-          end.to_h
+          resolution
         end
 
         # every loaded schema that defines what the table says `name` resolves
-        def candidates(table, name, schemas = GraphWeaver::Schemas.loaded)
-          schemas.select { |schema| missing(table, name, schema).empty? }
+        def candidates(table, name, schemas = Schemas.loaded)
+          wanted = expected(table, name)
+          schemas.select { |schema| wanted.all? { |coordinate| Schemas.defines?(schema, coordinate) } }
         end
 
         # The schema coordinates the supergraph says `name` resolves — "Type"
@@ -78,27 +88,19 @@ module GraphWeaver
 
         # which of them `schema` doesn't define
         def missing(table, name, schema)
-          expected(table, name).reject { |coordinate| GraphWeaver::Schemas.defines?(schema, coordinate) }
+          expected(table, name).reject { |coordinate| Schemas.defines?(schema, coordinate) }
         end
 
-        private
-
-        # The schema serving `name`, or nil when nothing here does — the
-        # subgraph is somebody else's, which is not an error until a query
-        # asks for it.
-        def detect(table, name, schemas)
-          found = candidates(table, name, schemas)
-          return found.first if found.one?
-          return if found.empty?
-
-          # by name: a dev reload leaves two class objects spelled the same,
-          # and naming one of them twice reads as a bug in the message
-          names = found.map(&:name).uniq.sort
-          raise GraphWeaver::ConfigurationError, "#{names.size} loaded schemas define everything the " \
-            "supergraph says #{name.inspect} resolves (#{names.join(", ")}) — pass subgraphs: naming " \
-            "the one you mean"
+        # Is this subgraph served in this process? Exactly one candidate is
+        # what that means: none is somebody else's service, and several is a
+        # question only the caller can answer, so neither is something a suite
+        # can run against.
+        def served?(table, name, schemas = Schemas.loaded)
+          candidates(table, name, schemas).one?
         end
 
+        private
+
         def check!(table, name, schema)
           return FAKE if schema == FAKE
 

data/lib/graph_weaver/internal/values.rb

@@ -0,0 +1,181 @@
+# typed: true
+# frozen_string_literal: true
+
+require "date"
+
+# The value engine behind FakeClient and Cassette#anonymize!: seeded,
+# type-correct scalar generation with optional faker-backed semantics
+# matched on field names — strings (name/email/url/...) and numbers
+# (age/price/count/latitude/...) alike. Keeps a consistent id mapping so
+# the same original id always anonymizes to the same fake id.
+class GraphWeaver::Internal::Values
+  include GraphWeaver::Inflect
+
+  STRING_SEMANTICS = {
+    /email/ => -> { ::Faker::Internet.email },
+    /(^|_)first_name$/ => -> { ::Faker::Name.first_name },
+    /(^|_)last_name$/ => -> { ::Faker::Name.last_name },
+    /(^|_)(full_)?name$/ => -> { ::Faker::Name.name },
+    /(^|_)(url|website|link)$/ => -> { ::Faker::Internet.url },
+    /phone/ => -> { ::Faker::PhoneNumber.phone_number },
+    /(^|_)address$/ => -> { ::Faker::Address.full_address },
+    /(^|_)(city)$/ => -> { ::Faker::Address.city },
+    /(^|_)(title|description)$/ => -> { ::Faker::Lorem.sentence(word_count: 3) },
+  }.freeze
+
+  NUMBER_SEMANTICS = {
+    /(^|_)age$/ => ->(rng) { rng.rand(1..99) },
+    /(^|_)(price|amount|cost|total)(_cents)?$/ => ->(rng) { (rng.rand(1.0..10_000.0) * 100).round / 100.0 },
+    /(^|_)(count|quantity|size)$/ => ->(rng) { rng.rand(0..100) },
+    /latitude/ => ->(rng) { rng.rand(-90.0..90.0).round(6) },
+    /longitude/ => ->(rng) { rng.rand(-180.0..180.0).round(6) },
+    /(^|_)year$/ => ->(rng) { rng.rand(1970..2030) },
+  }.freeze
+
+  # The Ruby shape a fabricated value has to take, keyed by the class the
+  # scalar registry says the scalar deserializes into. That registry is what
+  # codegen emitted the prop and its cast from, so a scalar registered as
+  # Time needs an iso8601 string whatever the schema happens to call it.
+  REGISTERED_SHAPES = {
+    "String" => :string,
+    "Integer" => :integer,
+    "Float" => :float,
+    "T::Boolean" => :boolean,
+    "Date" => :date,
+    "Time" => :time,
+    "DateTime" => :time,
+  }.freeze
+
+  # What Codegen.scalar reports for a scalar nobody registered
+  UNREGISTERED = "T.untyped"
+
+  # The fallback, for a scalar nobody registered: its prop is T.untyped, so
+  # anything holds and a plausible shape beats a placeholder.
+  NAMED_SHAPES = {
+    "ID" => :id,
+    "String" => :string,
+    "Int" => :integer,
+    "Float" => :float,
+    "Boolean" => :boolean,
+    "Date" => :date,
+    "DateTime" => :time,
+    "Time" => :time,
+    "ISO8601DateTime" => :time,
+  }.freeze
+
+  attr_reader :rng
+
+  # pins: what the fake uses instead of inventing a value, keyed by schema
+  # name. Only the scalar-type keys ("Money") are read here — a coordinate
+  # pin is resolved against the query, which is the fake's job. Left unsaid
+  # they are the suite's, so a scalar only the app can write for is
+  # fabricable from the cassette anonymizer too.
+  def initialize(seed: nil, values: nil, pins: nil)
+    @rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
+    @pins = (pins || GraphWeaver::Testing.config.overrides).transform_keys(&:to_s)
+    @style = resolve_style(values)
+    @sequence = 0
+    @id_map = {}
+    @resolved = {}
+  end
+
+  # coordinate: the "Type.field" this value is for, so a per-field
+  # register_scalar resolves the way codegen resolved it when it emitted the
+  # cast — and so a refusal can advise an override key that pins this field
+  # alone. at: where the walk is ("reader.orders.0.total"), for that refusal;
+  # a walk that doesn't track one leaves it unsaid.
+  def scalar(type_name, field_name, coordinate = nil, at: nil)
+    return GraphWeaver::Internal::Overrides.resolve(@pins[type_name], rng) if @pins.key?(type_name)
+
+    registered, shape = resolve(type_name, coordinate)
+    prop = underscore(field_name)
+
+    if @style == :faker
+      # rebind per call: several Values instances may interleave (e.g. two
+      # seeded fakes), and faker's rng is global
+      ::Faker::Config.random = @rng
+      case shape
+      when :string
+        STRING_SEMANTICS.each { |pattern, faker| return faker.call if pattern.match?(prop) }
+      when :integer, :float
+        NUMBER_SEMANTICS.each do |pattern, gen|
+          next unless pattern.match?(prop)
+
+          value = gen.call(@rng)
+          return (shape == :integer) ? value.to_i : value.to_f
+        end
+      end
+    end
+
+    case shape
+    when :id then (@sequence += 1).to_s
+    when :string then "#{field_name}-#{@sequence += 1}"
+    when :integer then @rng.rand(0..1_000)
+    when :float then @rng.rand(0.0..1_000.0).round(2)
+    when :boolean then [true, false].sample(random: @rng)
+    when :date then (Date.new(2020, 1, 1) + @rng.rand(0..2_000)).iso8601
+    when :time then Time.at(1_600_000_000 + @rng.rand(0..100_000_000)).utc.iso8601
+    when :unregistered then "#{type_name}-#{@sequence += 1}" # nobody registered it: prop is T.untyped
+    else unfakeable!(type_name, field_name, registered, coordinate, at)
+    end
+  end
+
+  # same original id => same fake id, so relationships survive anonymization
+  def mapped_id(original)
+    @id_map[original] ||= (@sequence += 1).to_s
+  end
+
+  private
+
+  # The registration in play and the shape it wants, memoized per scalar (or
+  # per coordinate, where a field-level registration overrides it).
+  def resolve(type_name, coordinate)
+    @resolved[coordinate || type_name] ||= begin
+      registered = GraphWeaver::Codegen.scalar(type_name, coordinate)
+      [registered, shape_of(type_name, registered.type)]
+    end
+  end
+
+  # ID asks by name as well as by class: it registers as String, and an id
+  # repeated across a list breaks a `find` or `group_by` in the code under
+  # test. Registered as anything else, it takes that type's treatment.
+  def shape_of(type_name, ruby_type)
+    if type_name == "ID" && ruby_type == "String"
+      :id
+    elsif (shape = REGISTERED_SHAPES[ruby_type])
+      shape
+    elsif ruby_type == UNREGISTERED
+      NAMED_SHAPES[type_name] || :unregistered
+    else
+      :unfakeable
+    end
+  end
+
+  # An app class is the one Ruby type nothing here can invent a wire value
+  # for — `Money.parse` accepts what its author decided it accepts — and
+  # guessing hands the generated cast a placeholder, which fails deep inside
+  # from_h blaming the codec.
+  def unfakeable!(type_name, field_name, registered, coordinate, at)
+    raise GraphWeaver::Error, "can't fabricate a #{type_name} #{at ? "at #{at}" : "for #{field_name.inspect}"}: " \
+      "it deserializes into #{registered.type}, and only you know what wire value that accepts. " \
+      "Pin the type — overrides: { #{type_name.inspect} => ... } — or this one field: " \
+      "overrides: { #{(coordinate || field_name).inspect} => ... }. Suite-wide, that's " \
+      "GraphWeaver::Testing.config.overrides."
+  end
+
+  # :faker is an explicit ask — fail loudly when the gem is missing; auto
+  # (nil) quietly falls back to :literal
+  def resolve_style(style)
+    case style
+    when :faker
+      raise ArgumentError, "values: :faker requires the faker gem (add it to your Gemfile's test group)" unless defined?(::Faker)
+
+      :faker
+    when :literal then :literal
+    when nil then defined?(::Faker) ? :faker : :literal
+    else
+      raise ArgumentError, "values: must be one of #{GraphWeaver::Testing::VALUE_STYLES.inspect} " \
+        "(or nil for auto), got #{style.inspect}"
+    end
+  end
+end