graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver.rb

@@ -2,7 +2,9 @@ require "graphql"
 require "sorbet-runtime"
 
 require_relative "graph_weaver/logging"
+require_relative "graph_weaver/internal"
 require_relative "graph_weaver/errors"
+require_relative "graph_weaver/coerce"
 require_relative "graph_weaver/hints"
 require_relative "graph_weaver/input_struct"
 require_relative "graph_weaver/query_module"
@@ -27,6 +29,7 @@ module GraphWeaver
   # How far into a file to look for it: the header sits under the `typed:` and
   # `frozen_string_literal:` magic comments, never deeper.
   HEADER_SCAN_LINES = 10
+  private_constant :GENERATED_HEADER, :HEADER_SCAN_LINES
 
   class << self
     # A client for one GraphQL server — transport, schema, and scoped
@@ -58,17 +61,47 @@ module GraphWeaver
       # being loaded is what says which suggestion is the useful one
       @client or raise Error, "no client configured — " + if defined?(Testing::RSpecIntegration)
         "tag the example graphql: :fake (or :in_process / :router), or build one with graphql_fake"
+      elsif defined?(::RSpec)
+        # a graphql: tag without graph_weaver/rspec is silent, and lands here
+        "set GraphWeaver.client= or pass a client; if you tagged this example graphql:, " \
+          "require \"graph_weaver/rspec\" in your spec helper — the tag does nothing without it"
       else
         "set GraphWeaver.client= or pass a client"
       end
     end
 
+    # Called by generated code — not semver'd for direct use.
+    #
+    # Cast a response's data, keeping the server's own errors on a failure.
+    # The common cause of a cast failure is a field that came back null *with
+    # a reason attached* — a permission rule, a partial outage — and raising
+    # only Sorbet's nil complaint throws that reason away, leaving whoever is
+    # on call with a type error and no explanation.
+    sig do
+      params(struct: T.untyped, data: T.untyped, errors: T::Array[GraphWeaver::GraphQLError])
+        .returns(T.untyped)
+    end
+    def cast_data(struct, data, errors)
+      struct.from_h(data)
+    rescue GraphWeaver::TypeError => e
+      raise if errors.empty?
+
+      detail = e.message.delete_prefix("failed to cast response into #{struct}: ")
+      raise GraphWeaver::TypeError.new(
+        struct:,
+        message: "#{detail} — the server also reported: #{errors.map(&:message).join("; ")}",
+      )
+    end
+
+    # Called by generated code — not semver'd for direct use.
+    #
     # Shape-check a raw response envelope, returning it. Generated
     # from_response is public API taking anything with #to_h, so a malformed
     # body has to brand rather than escape as a raw Sorbet TypeError from a sig
     # (which fires before the struct's own rescue can see it). Lives here rather
     # than unrolled into every generated module.
     def check_envelope!(raw, struct)
+      raw = raw.to_h if !raw.is_a?(Hash) && raw.respond_to?(:to_h)
       unless raw.is_a?(Hash)
         raise GraphWeaver::TypeError.new(struct:, message: "response must be an object, got #{raw.class}")
       end
@@ -85,36 +118,37 @@ module GraphWeaver
         raise GraphWeaver::TypeError.new(struct:, message: "response \"errors\" must be an array of objects")
       end
 
+      # A response with neither key isn't a GraphQL response at all — a client
+      # that returned nil, one keying the envelope by symbol, one that typo'd
+      # "dat". Each otherwise passes as a success carrying no data.
+      unless raw.key?("data") || raw.key?("errors")
+        found = raw.empty? ? "it is empty" : "got #{raw.keys.first(5).map(&:inspect).join(", ")}"
+        raise GraphWeaver::TypeError.new(struct:, message:
+          "response carried neither \"data\" nor \"errors\" — #{found}; " \
+          "the keys are the wire's own, as strings")
+      end
+
       raw
     end
 
-    # The module a .graphql file generates, and the basename of the file it
-    # generates into: the camelized file name plus the operation's own word.
-    #
-    #      person.graphql          => PersonQuery       (person_query.rb)
-    #      save_list_entry.graphql => SaveListEntryMutation
-    #                                 (save_list_entry_mutation.rb)
-    #
-    # Every naming site goes through here — generate!, parse(path), and
-    # load_queries! — so the constant a file produces is the same one
-    # whichever door you came in by, and the file it lands in matches it.
-    def generated_names(path, source)
-      base = File.basename(path, ".*")
-      suffix = operation_suffix(source)
-      ["#{Inflect.camelize(base)}#{suffix}", "#{base}_#{suffix.downcase}.rb"]
-    end
+    # What every relative path setting below is relative to: Rails.root in a
+    # Rails app, the working directory otherwise. So a dev server or an rspec
+    # run started from a subdirectory reads the same files a rake task does.
+    # An absolute setting is left alone.
+    attr_writer :root
+
+    def root = (@root || rails_root || Dir.pwd).to_s
 
-    # just the module name — see generated_names
-    def module_name(path, source) = generated_names(path, source).first
+    # Not memoized: Rails.root isn't set when the gem is required. const_get
+    # rather than a bare Rails — sorbet can't resolve a constant the gem
+    # doesn't depend on, and something else may be named Rails.
+    def rails_root
+      return unless Object.const_defined?(:Rails)
 
-    # "Mutation" for a mutation document, "Query" for everything else.
-    def operation_suffix(source)
-      operation = GraphQL.parse(source).definitions
-        .grep(GraphQL::Language::Nodes::OperationDefinition).first
-      (operation&.operation_type == "mutation") ? "Mutation" : "Query"
-    rescue GraphQL::ParseError
-      "Query" # unparseable: codegen brands the real error a moment later
+      rails = Object.const_get(:Rails)
+      rails.root if rails.respond_to?(:root)
     end
+    private :rails_root
 
     # Conventional locations. Every directory setting is a LIST,
     # factory_bot-style: extra locations (a test-only dir, an engine's) can be
@@ -131,11 +165,6 @@ module GraphWeaver
     # read. A second schema is a second generate! (schema: names it).
     attr_writer :schema_path
 
-    # Set by every graph_weaver rake task: those tasks WRITE the generated
-    # files, so loading them first lets a stale one block its own repair.
-    # None of them needs the modules loaded.
-    attr_accessor :skip_generated_load
-
     def queries_paths = @queries_paths ||= ["app/graphql/queries"]
     def generated_paths = @generated_paths ||= ["app/graphql/generated", "app/graphql/*/generated"]
 
@@ -159,11 +188,10 @@ module GraphWeaver
 
     def schema_path = @schema_path || "app/graphql/schema.json"
 
-    # Every query document under these directories, sorted — the files
-    # generate!, verify_generated!, check_queries and load_queries! all read.
-    def query_files(paths = queries_paths)
-      Array(paths).flat_map { |dir| Dir[File.join(dir, Codegen::DOCUMENT_GLOB)].sort }
-    end
+    # Set by every graph_weaver rake task: those tasks WRITE the generated
+    # files, so loading them first lets a stale one block its own repair.
+    # None of them needs the modules loaded.
+    attr_accessor :skip_generated_load
 
     # The name of the shared module — the types that live once per schema
     # (input types, enums, unions hoisted from shared fragments) and are
@@ -183,38 +211,58 @@ module GraphWeaver
     #
     #      GraphWeaver.generate!   # queries_paths -> generated_paths.first
     #
-    # person.graphql => person_query.rb defining PersonQuery. Returns the
-    # written paths. Generated files the plan no longer produces are deleted
+    # person.graphql => person_query.rb defining PersonQuery. Returns every
+    # path the plan produces; a file already byte-identical is left untouched
+    # (see #changed_files). Generated files the plan no longer produces are deleted
     # (see #orphaned), so renaming or dropping a .graphql leaves nothing
     # behind. Pair with a freshness spec (docs/generated_modules.md).
     def generate!(schema: nil, queries: queries_paths, output: generated_paths.first, client: nil,
       types_module: nil)
       schema = schema ? schema_for(schema) : locate_schema!
 
+      if Internal::Util.query_files(queries).empty?
+        # a brand-new app legitimately has none; a mistyped queries_paths looks
+        # exactly the same, and prints nothing either way
+        Internal::Log.log(:warn) { "no query documents under #{Array(queries).join(", ")} — nothing to generate" }
+      end
+
       plan = generation_plan(queries:, schema:, client:, types_module:)
+      @unmatched_registrations = Codegen.unmatched_registrations(schema)
+      @changed_files = []
       written = plan.map do |filename, source|
-        target = File.join(output, filename)
+        target = File.join(Internal::Util.resolve(output), filename)
+        next target if current?(target, source)
+
         FileUtils.mkdir_p(File.dirname(target))
-        File.write(target, source)
-        log(:info) { "generated #{target}" }
+        # a rake task beside a watching dev server writes the same file: a
+        # truncating write can leave a prefix that no longer parses, and it is
+        # the running app that requires it next
+        Internal::Util.atomic_write(target, source)
+        reported = Internal::Util.relative(target)
+        @changed_files << reported
+        Internal::Log.log(:info) { "generated #{reported}" }
         target
       end
 
       orphaned(output, written).each do |orphan|
         File.delete(orphan)
-        log(:info) { "pruned #{orphan}" }
+        Internal::Log.log(:info) { "pruned #{Internal::Util.relative(orphan)}" }
       end
 
-      written
+      written.map { |target| Internal::Util.relative(target) }
     end
 
+    # Which of those files the last generate! actually wrote — the rest were
+    # already byte-identical, so a run that changed one query touches one file
+    # and a watching dev server has one module to reload.
+    def changed_files = @changed_files || []
+
     # Generated files under output the current plan no longer produces — a
     # query renamed or deleted, a type dropped from the schema, a union no
     # longer hoisted. Left alone they'd keep being required by
     # load_generated!, resolving against a query that no longer exists.
     def orphaned(output, produced)
-      current = produced.map { |path| File.expand_path(path) }
-      generated_files(output).reject { |path| current.include?(File.expand_path(path)) }
+      generated_files(output) - produced
     end
     private :orphaned
 
@@ -223,7 +271,7 @@ module GraphWeaver
     # safe: this is a real directory, and a hand-written file in it must
     # survive regeneration.
     def generated_files(output)
-      Dir[File.join(output, "**/*.rb")].sort.select do |path|
+      Dir[File.join(Internal::Util.resolve(output), "**/*.rb")].sort.select do |path|
         File.foreach(path).first(HEADER_SCAN_LINES).any? { |line| line.start_with?(GENERATED_HEADER) }
       end
     end
@@ -240,24 +288,46 @@ module GraphWeaver
     #      end
     def verify_generated!(schema: nil, queries: queries_paths, output: generated_paths.first, client: nil,
       types_module: nil)
+      if Internal::Util.query_files(queries).empty?
+        # green over nothing is worse than red: a CI gate stays passing
+        # forever because someone typed app/graphql/querys
+        raise Error, "no query documents under #{Array(queries).join(", ")} — this checked nothing, " \
+          "so it proved nothing (set GraphWeaver.queries_paths, or pass queries:)"
+      end
+
       schema = schema ? schema_for(schema) : locate_schema!
       plan = generation_plan(queries:, schema:, client:, types_module:)
+      @unmatched_registrations = Codegen.unmatched_registrations(schema)
       stale = plan.filter_map do |filename, source|
-        target = File.join(output, filename)
-        # git's autocrlf rewrites line endings on checkout — a Windows working
-        # copy is not stale generated code, so don't fail CI over it
-        target unless File.exist?(target) && File.read(target).gsub("\r\n", "\n") == source.gsub("\r\n", "\n")
+        target = File.join(Internal::Util.resolve(output), filename)
+        target unless current?(target, source)
       end
       # strays: a generated file the current schema + queries no longer produce
-      stale += orphaned(output, plan.map { |filename, _| File.join(output, filename) })
+      stale += orphaned(output, plan.map { |filename, _| File.join(Internal::Util.resolve(output), filename) })
 
       unless stale.empty?
-        raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): #{stale.join(", ")}"
+        raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): " \
+          "#{stale.map { |path| Internal::Util.relative(path) }.join(", ")}"
       end
 
       true
     end
 
+    # Whether the file on disk is already what the plan would write — asked
+    # before writing it, and before calling it stale. autocrlf rewrites line
+    # endings on checkout, and a Windows working copy is neither stale
+    # generated code nor a file worth rewriting.
+    def current?(target, source)
+      File.exist?(target) && File.read(target).gsub("\r\n", "\n") == source.gsub("\r\n", "\n")
+    end
+    private :current?
+
+    # What the last generate!/verify_generated! couldn't match in the schema it
+    # ran against — one sentence per registration, empty after a clean run. The
+    # same list codegen logs at warn, kept here so the build can print it once
+    # instead of once per query file.
+    def unmatched_registrations = @unmatched_registrations || []
+
     # Which checked-in queries no longer validate — breaking-change
     # detection scoped to the operations you actually ship. Reports rather
     # than raising, keyed by file, JSON-ready like every #to_h here:
@@ -287,9 +357,9 @@ module GraphWeaver
       schema = schema ? schema_for(schema) : refreshed_schema
       shared = Codegen.load_fragments(fragments)
 
-      query_files(queries).each_with_object({}) do |path, failures|
+      Internal::Util.query_files(queries).each_with_object({}) do |path, failures|
         errors = validation_errors(schema, File.read(path), shared, table)
-        failures[path] = errors if errors.any?
+        failures[Internal::Util.relative(path)] = errors if errors.any?
       end
     end
 
@@ -300,7 +370,7 @@ module GraphWeaver
     # nil when a live schema class is what gets checked, since the dump then
     # isn't what the errors came from.
     def checked_routing_table
-      return if live_schema
+      return if Internal::Util.live_schema
 
       path = SchemaLoader.locate_path
       return unless path&.end_with?(".graphql", ".gql")
@@ -319,31 +389,19 @@ module GraphWeaver
     # class — hand-written SDL, a composed supergraph — have nothing to
     # re-read, so they're checked as they are.
     def refreshed_schema
-      live = live_schema
+      live = Internal::Util.live_schema
       return live if live
 
       # locate_schema! raises the conventional "no schema dump" message
       path = SchemaLoader.locate_path or locate_schema!
-      meta = SchemaLoader.provenance(path)
-      return SchemaLoader.load(path) unless meta&.key?("url")
+      return SchemaLoader.load(path) unless SchemaLoader.provenance(path)&.key?("url")
 
-      SchemaLoader.introspect(new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).transport)
+      # source_transport rather than one built here: it reads the auth ENV var
+      # the dump named, so `--auth MY_TOKEN` reaches this path too
+      SchemaLoader.introspect(SchemaLoader.source_transport(path))
     end
     private :refreshed_schema
 
-    # The graphql-ruby schema class the app default executes against, when it
-    # runs in-process — a Client wrapping one, or the class in the slot bare.
-    # nil for every network client. Not memoized: in dev the class object is
-    # replaced on reload. (Public because testing's :in_process mode asks:
-    # a client already running in-process names its own schema class.)
-    def live_schema
-      # through #transport, not #schema: a url client's #schema introspects,
-      # so asking it would answer this question over the network
-      target = client.is_a?(Client) ? client.transport : client
-      target = target.schema if target.is_a?(InProcess)
-      target if target.is_a?(Class) && target <= GraphQL::Schema
-    end
-
     # One query's schema-validation errors as JSON-ready hashes, with the
     # source position graphql-ruby reports. Unparseable counts as an error
     # too — it doesn't validate either, and inline_fragments (which parses
@@ -403,20 +461,68 @@ module GraphWeaver
     # a schema migration).
     def load_generated!(path = nil)
       paths = path ? [path] : generated_paths
-      files = paths.flat_map { |dir| Dir[File.join(dir, "**/*.rb")].sort }.uniq
+      files = paths.flat_map { |dir| Dir[File.join(Internal::Util.resolve(dir), "**/*.rb")].sort }.uniq
       files.each do |file|
-        require File.expand_path(file)
+        require file
       rescue NameError => e
+        reported = Internal::Util.relative(file)
         # a dropped extend_type leaves this include dangling; say so here,
         # because the raw NameError points at generated code and names no fix
-        helper = e.message[/GraphWeaver::TypeHelpers::(\w+)/, 1] or raise
-        raise Error, "#{file} includes GraphWeaver::TypeHelpers::#{helper}, but nothing registers it — " \
-          "the extend_type(#{helper.inspect}) it was generated from is gone. Re-add that registration, " \
-          "or regenerate without it: rake graph_weaver:generate"
+        helper = e.message[/GraphWeaver::TypeHelpers::(\w+)/, 1]
+        if helper
+          raise Error, "#{reported} includes GraphWeaver::TypeHelpers::#{helper}, but nothing registers it — " \
+            "the extend_type(#{helper.inspect}) it was generated from is gone. Re-add that registration, " \
+            "or regenerate without it: rake graph_weaver:generate"
+        end
+
+        # an app's own mixin or enum class named by extend_type/register_enum
+        raise Error, "#{reported} can't load: #{e.message}. It was generated with an extend_type or " \
+          "register_enum whose constant is gone — re-add it, or regenerate: rake graph_weaver:generate"
+      end
+      Internal::Log.log(:info) do
+        "loaded #{files.size} generated module(s) from #{paths.map { |dir| Internal::Util.relative(dir) }.join(", ")}"
+      end
+      files.map { |file| Internal::Util.relative(file) }
+    end
+
+    # Load the generated modules again after generate! rewrote them in a
+    # running process — the second half of watch mode (see the Railtie), and
+    # what a console needs after regenerating in another terminal:
+    #
+    #      GraphWeaver.reload_generated!
+    #
+    # `require` no-ops on a file it has already seen, and re-running one whose
+    # constants still exist raises (a T::Enum refuses a second definition), so
+    # the constants generation owns go first. Same caveat as load_queries!: an
+    # object built from the previous module stays an instance of it. A module
+    # whose query was just deleted keeps its old constant until restart —
+    # nothing on disk says what it was called any more.
+    def reload_generated!
+      names = Internal::Util.query_files.map { |path| Internal::Util.module_name(path, File.read(path)) } << types_module
+      names.each { |name| undefine(name) }
+
+      generated_paths.each do |dir|
+        Dir[File.join(Internal::Util.resolve(dir), "**/*.rb")].each do |file|
+          # require stores the realpath; the path load_generated! passed is
+          # the other one under a symlinked checkout
+          $LOADED_FEATURES.delete(file)
+          $LOADED_FEATURES.delete(File.realpath(file))
+        end
+      end
+      load_generated!
+    end
+
+    # remove_const takes a bare name, and types_module may be namespaced
+    def undefine(name)
+      *outer, base = name.split("::")
+      owner = outer.reduce(Object) do |mod, part|
+        return unless mod.const_defined?(part, false)
+
+        mod.const_get(part, false)
       end
-      log(:info) { "loaded #{files.size} generated module(s) from #{paths.join(", ")}" }
-      files
+      owner.send(:remove_const, base) if owner.const_defined?(base, false)
     end
+    private :undefine
 
     # Anywhere GraphWeaver takes schema:, a Client stands for its schema — so
     # the console object and the rake task point at the same thing. A path
@@ -453,11 +559,12 @@ module GraphWeaver
 
       seen = {} # module name => the file that produced it, for the collision message
 
-      plan = query_files(queries).map do |path|
+      plan = Internal::Util.query_files(queries).map do |path|
         source = File.read(path)
-        name, filename = generated_names(path, source)
+        name, filename = Internal::Util.generated_names(path, source)
         if (earlier = seen[name])
-          raise Error, "duplicate query module #{name} — #{earlier} and #{path} both generate it; " \
+          raise Error, "duplicate query module #{name} — #{Internal::Util.relative(earlier)} and " \
+            "#{Internal::Util.relative(path)} both generate it; " \
             "the module name comes from the file name alone (directories don't namespace it), so rename one"
         end
         seen[name] = path
@@ -465,7 +572,7 @@ module GraphWeaver
         codegen = Codegen.new(
           schema:,
           query: Codegen.inline_fragments(source, shared, path),
-          module_name: name,
+          name:,
           client:,
           types_namespace: types_module,
           hoistable_unions: Codegen.shared_fragment_spreads(source, shared, path),
@@ -478,7 +585,7 @@ module GraphWeaver
       end
 
       if used_unions.any? || used.values.any?(&:any?)
-        codegen = Codegen.new(schema:, query: "", module_name: types_module)
+        codegen = Codegen.new(schema:, query: "", name: types_module)
         plan = codegen.generate_types(
           inputs: used[:inputs], enums: used[:enums] + used[:mapped],
           unions: used_unions, fragments: shared,
@@ -489,15 +596,6 @@ module GraphWeaver
     end
     private :generation_plan
 
-    # coerce: true for every scalar that doesn't say coerce: itself —
-    # the same switch at global scope, resolved lazily at generation time
-    # (so set it any time before you generate, no ordering dance):
-    #
-    #      GraphWeaver.auto_coerce = true
-    #
-    # An explicit coerce: on a registration always wins.
-    attr_accessor :auto_coerce
-
     # Whether generated modules/structs emit `extend T::Sig` (so `sig`
     # resolves standalone). Default (nil) auto-detects: an app that globally
     # injects T::Sig (`class Module; include T::Sig`) makes the per-struct
@@ -516,15 +614,7 @@ module GraphWeaver
     # Whether the host app has globally injected T::Sig into every module
     # (`class Module; include T::Sig`) — extracted so it's stubbable in tests.
     def global_tsig? = Module.include?(T::Sig)
-
-    # The closest entry in `dictionary` to `term` — a "did you mean" suggestion,
-    # or nil (also nil when did_you_mean isn't loadable). One home for the guard
-    # used by codegen validation, alias resolution, and the runtime prop hints.
-    def did_you_mean(dictionary, term)
-      return unless defined?(DidYouMean::SpellChecker)
-
-      DidYouMean::SpellChecker.new(dictionary: dictionary).correct(term).first
-    end
+    private :global_tsig?
 
     # Teach the generator how a GraphQL custom scalar deserializes into a
     # rich Ruby object (and serializes back onto the wire when used as a
@@ -540,12 +630,17 @@ module GraphWeaver
     # Proc(expr) => code string, or :itself to force pass-through. requires:
     # (a String or Array) names files the generated code needs — validated,
     # and actually required to confirm it resolves when type: is a real class.
-    # coerce: true makes a variable of this scalar accept the value OR its
-    # raw input (e.g. "12.00"), normalizing the latter before serializing —
-    # it raises on bad input, so some safety survives; GraphWeaver.auto_coerce
-    # is the same switch for every scalar at once. Built-in scalars are
+    # cast: is also what an untyped variable input coerces through, so a
+    # variable of this scalar takes the value OR its raw input ("12.00") with
+    # no static loosening — see GraphWeaver::Coerce. Built-in scalars are
     # pre-registered the same way, so this also overrides them.
     #
+    # A scalar registered as a class of your own is the one value the testing
+    # harness can't invent — only your `cast:` knows what it accepts — so it
+    # refuses rather than feed the cast a placeholder. Say it in test config,
+    # where the rest of that answer lives: `overrides: { "Money" => "12.00" }`
+    # (see docs/testing.md).
+    #
     # Pass a `Type.field` coordinate instead of a scalar name to override just
     # that one field — so the same scalar can deserialize as different Ruby
     # types across fields (a `Date` for `User.birthday`, a `Time` elsewhere):
@@ -554,8 +649,8 @@ module GraphWeaver
     #
     # A field-level override wins over the scalar-name registration. Same
     # signature either way. Call before generating.
-    def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
-      Codegen.register_scalar(graphql_name, type, cast:, serialize:, requires:, coerce:)
+    def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil)
+      Codegen.register_scalar(graphql_name, type, cast:, serialize:, requires:)
     end
 
     # Map a GraphQL enum onto an app-owned T::Enum, so generated code
@@ -593,8 +688,9 @@ module GraphWeaver
     end
 
     # Every registry back to its starting state: built-in scalars restored,
-    # enum mappings and type helpers dropped — the clean slate between
-    # tests. (One registry at a time is a Codegen call:
+    # enum mappings and type helpers dropped — the clean slate between tests,
+    # or between generations for different schemas. (One registry at a time
+    # is a Codegen call:
     # GraphWeaver::Codegen.reset_enums!, .reset_scalars!, .clear_scalars!,
     # .reset_type_helpers!)
     def reset_registrations!
@@ -607,23 +703,30 @@ module GraphWeaver
     #
     # schema: is a graphql-ruby schema or a Client (its schema, and its
     # transport as the module's default). query is a .graphql/.gql path (module
-    # name derived from the file name
-    # and the operation — see #module_name) or a raw query string (name
-    # derived from the operation name,
-    # falling back to "Query" for anonymous operations — collisions are
-    # impossible since each parse gets its own container). Pass name: to
-    # override, client: to bake the module's default client/transport.
+    # name derived from the file name and the operation — see #module_name) or
+    # a raw query string (name derived from the operation name, falling back to
+    # "Query" for anonymous operations — collisions are impossible since each
+    # parse gets its own container). Pass name: to override, client: to bake
+    # the module's default client/transport.
     def parse(schema:, query:, name: nil, client: nil, fragments: fragments_paths)
       client ||= schema if schema.is_a?(Client)
       schema = schema_for(schema)
+      # Rails.root.join(...) hands you a Pathname, and to_path is the
+      # ecosystem's "I am a path" — the same conversion schema: gets through
+      # SchemaLoader.load. Without it end_with? below is a NoMethodError.
+      query = query.to_path if query.respond_to?(:to_path)
       path = query if query.end_with?(".graphql", ".gql")
       if path
-        query = File.read(path)
-        name ||= module_name(path, query)
+        query = File.read(Internal::Util.resolve(path))
+        name ||= Internal::Util.module_name(path, query)
+      elsif !query.include?("{")
+        # every document has a selection set, so this is a path we won't read
+        # — and it would otherwise fail as a syntax error about SCHEMA/SCALAR
+        raise Error, "#{query.inspect} is not a GraphQL document — a query file must be named .graphql or .gql"
       end
       query = Codegen.inline_fragments(query, Codegen.load_fragments(fragments), path)
 
-      Codegen.parse(schema:, query:, module_name: name, client:, path:)
+      Codegen.parse(schema:, query:, name:, client:, path:)
     end
 
     # One-shot dynamic execution — a throwaway client, no build step:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -227,16 +227,10 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
-- CLAUDE.md
-- DECISIONS.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- Makefile
-- NOTES.md
-- PLAN.md
 - README.md
-- REVIEW.md
 - docs/cassettes.md
 - docs/editors.md
 - docs/errors.md
@@ -260,12 +254,20 @@ files:
 - lib/graph_weaver/codegen/nodes.rb
 - lib/graph_weaver/codegen/scalar_type.rb
 - lib/graph_weaver/codegen/type_helpers.rb
+- lib/graph_weaver/coerce.rb
 - lib/graph_weaver/errors.rb
 - lib/graph_weaver/federation.rb
 - lib/graph_weaver/hints.rb
 - lib/graph_weaver/in_process.rb
 - lib/graph_weaver/inflect.rb
 - lib/graph_weaver/input_struct.rb
+- lib/graph_weaver/internal.rb
+- lib/graph_weaver/internal/overrides.rb
+- lib/graph_weaver/internal/planner.rb
+- lib/graph_weaver/internal/schemas.rb
+- lib/graph_weaver/internal/selection.rb
+- lib/graph_weaver/internal/subgraphs.rb
+- lib/graph_weaver/internal/values.rb
 - lib/graph_weaver/logging.rb
 - lib/graph_weaver/parsing.rb
 - lib/graph_weaver/query_module.rb
@@ -274,9 +276,8 @@ files:
 - lib/graph_weaver/response.rb
 - lib/graph_weaver/retry.rb
 - lib/graph_weaver/rspec.rb
+- lib/graph_weaver/schema_diff.rb
 - lib/graph_weaver/schema_loader.rb
-- lib/graph_weaver/schemas.rb
-- lib/graph_weaver/selection.rb
 - lib/graph_weaver/tasks.rb
 - lib/graph_weaver/testing.rb
 - lib/graph_weaver/testing/cassette.rb
@@ -285,8 +286,6 @@ files:
 - lib/graph_weaver/testing/fake_client.rb
 - lib/graph_weaver/testing/fake_subgraph.rb
 - lib/graph_weaver/testing/router.rb
-- lib/graph_weaver/testing/subgraphs.rb
-- lib/graph_weaver/testing/values.rb
 - lib/graph_weaver/transport.rb
 - lib/graph_weaver/transport/faraday.rb
 - lib/graph_weaver/transport/http.rb
@@ -294,7 +293,12 @@ files:
 homepage: https://github.com/dpep/graph_weaver
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/dpep/graph_weaver/issues
+  changelog_uri: https://github.com/dpep/graph_weaver/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/dpep/graph_weaver/tree/main/docs
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dpep/graph_weaver
 rdoc_options: []
 require_paths:
 - lib
@@ -311,5 +315,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: GraphWeaver
+summary: A typed GraphQL client for Ruby
 test_files: []