graph_weaver 0.7.1 → 0.7.3

data/lib/graph_weaver/codegen.rb

@@ -59,15 +59,10 @@ class GraphWeaver::Codegen
 
   attr_reader :name
 
-  # A client is anything responding to `execute(query, variables:)`
-  # whose result `to_h`s into {"data" => ..., "errors" => ...} — a
-  # GraphWeaver::Client, a transport, a schema class, a fake.
-  #
-  # client: (a constant, or its name as a string) becomes the generated
-  # module's baked default; when omitted, generated code falls back to
-  # the app default (GraphWeaver.client=). graph_name: is the graph the
-  # module belongs to, baked in so a test mode can build its stand-in from
-  # the right schema. name: is the module the file
+  # graph_name: is the graph the module belongs to, baked in because it is
+  # the one thing a module can't be told at call time: it decides which
+  # client the module runs against (GraphWeaver::QueryModule) and which
+  # schema a test mode fabricates from. name: is the module the file
   # defines, defaulting to the operation's own name; default_name: is
   # parse's container-scoped fallback (file generation stays strict — a
   # checked-in file deserves a deliberate name). types_namespace: is the shared-types workflow (see
@@ -78,7 +73,7 @@ class GraphWeaver::Codegen
   # whole-union field spread as one of them resolves to a canonical type in the
   # shared module (see used_union_names). path: is the file the query was read
   # from, named alongside line and column in validation errors.
-  def initialize(schema:, query:, name: nil, client: nil, default_name: nil,
+  def initialize(schema:, query:, name: nil, default_name: nil,
     types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil,
     graph_name: nil, registry: GraphWeaver::Codegen.registry)
     renamed!(module_name)
@@ -96,28 +91,10 @@ class GraphWeaver::Codegen
     @used_unions = []
     # scalars this generation had no registration for (see report_untyped_scalars)
     @untyped_scalars = []
-    @client_const = CLIENT_CONST.call(client)
-    # the graph this module belongs to, baked in beside the client: a test
-    # mode builds its stand-in from the module's own schema, and only the
-    # module can say whose that is (GraphWeaver::Internal::TestClients).
-    # A Symbol, as GraphWeaver.graph makes it — the name is the identity.
+    # the graph this module belongs to: its client and, under a test mode,
+    # its stand-in are both read off it, and only the module can say whose
+    # it is. A Symbol, as GraphWeaver.graph makes it — the name is the identity.
     @graph_name = graph_name&.to_sym
-
-    if client && @client_const.nil?
-      # a live object can't be spelled in generated source — parse can
-      # set one via the module's writer, but file generation cannot
-      raise ArgumentError, "client: must be a named constant or String (got #{client.inspect}) — " \
-        "put the object in a constant and name it, client: \"MyApi::CLIENT\"; pass live objects to parse"
-    end
-    # The String is written into the module verbatim, so anything that isn't a
-    # constant path emits source that doesn't parse. A url is the way to get
-    # here — it is where the endpoint is spelled everywhere else — so the fix
-    # names the value that was passed.
-    if @client_const && !@client_const.match?(CONSTANT_NAME)
-      raise ArgumentError, "client: #{@client_const.inspect} isn't a constant — generated source " \
-        "spells this name, so it has to be one: CLIENT = GraphWeaver.new(#{@client_const.inspect}), " \
-        "then client \"CLIENT\""
-    end
   end
 
   # 0.5 spelled it module_name:, in two of the three doors. One knob, one
@@ -129,33 +106,19 @@ class GraphWeaver::Codegen
   end
   private :renamed!
 
-  # The constant name a client can be referenced by in generated
-  # source — nil when it can't be (live objects, anonymous modules).
-  # A lambda rather than a method: both `parse` and `initialize` need it,
-  # from the class and from an instance.
-  CLIENT_CONST = lambda do |client|
-    case client
-    when String then client
-    when Module then client.name
-    end
-  end
-  private_constant :CLIENT_CONST
-
   # one-step shorthand
-  def self.generate(schema:, query:, name: nil, client: nil, path: nil, module_name: nil)
-    new(schema:, query:, name:, client:, path:, module_name:).generate
+  def self.generate(schema:, query:, name: nil, path: nil, module_name: nil)
+    new(schema:, query:, name:, path:, module_name:).generate
   end
 
   # Development convenience: generate + eval in one step, no build
   # artifact or checked-in file. Same runtime semantics as the generated
   # file, but invisible to srb tc — use the build step for static typing.
-  # Evaluates into an anonymous container, so no global constants leak;
-  # client: additionally accepts a live object (set via .client=).
+  # Evaluates into an anonymous container, so no global constants leak.
+  # client: is the client the parsed module runs against — it has no graph to
+  # read one off — and a per-call `client:` still wins over it.
   def self.parse(schema:, query:, name: nil, client: nil, path: nil, module_name: nil, graph_name: nil)
-    client_const = CLIENT_CONST.call(client)
-
-    codegen = new(schema:, query:, name:, client: client_const, path:, module_name:, graph_name:,
-      default_name: "Query")
+    codegen = new(schema:, query:, name:, path:, module_name:, graph_name:, default_name: "Query")
     source = codegen.generate
 
     container = Module.new
@@ -167,9 +130,10 @@ class GraphWeaver::Codegen
     container.module_eval(source, "(graph_weaver)", 1)
     mod = container.const_get(codegen.name)
     GraphWeaver::Internal::Log.log(:debug) { "parsed #{codegen.name} (dynamic module, #{source.bytesize} bytes)" }
-    # live objects (or anonymous modules) can't be referenced from
-    # generated source — set them via the module's writer instead
-    mod.client = client if client && client_const.nil?
+    # a parsed module generates no file, so it has no graph to read a client
+    # off — client: binds one, whatever kind of object it is. The writer is
+    # private: parsing is the only thing that may bind one.
+    mod.send(:client=, client) if client
     mod
   end
 

data/lib/graph_weaver/graph.rb

@@ -65,7 +65,24 @@ module GraphWeaver
 
     def queries = @queries || GraphWeaver.queries_paths
     def output = @output || GraphWeaver.generated_paths.first
-    def client = @client
+
+    # The client this graph's modules call: the object `client` named, or the
+    # constant its name spells. nil when the graph names none — its modules
+    # go to GraphWeaver.client, like every other module.
+    #
+    # Resolved here, at call time, rather than spelled into generated source:
+    # renaming the constant is then an initializer edit and not a regeneration
+    # of every module, and a graph can name a live object.
+    def client
+      return @client unless @client.is_a?(String)
+
+      Object.const_get(@client)
+    rescue NameError
+      raise GraphWeaver::Error, "the client#{described} names #{@client.inspect} and nothing " \
+        "defines that constant, so its modules have no server to reach. Define it where the graph " \
+        "block can see it (config/initializers), or name the object itself: client " \
+        "GraphWeaver.new(\"https://api.example.com/graphql\")"
+    end
 
     # Every constant this graph generates lives under `namespace:` — the query
     # modules and the shared types module alike. Two schemas that each have a
@@ -95,7 +112,7 @@ module GraphWeaver
 
     # The dump this graph's schema was named by, when it was named by a file —
     # what a validation error's subgraph branding is read off. nil for a live
-    # class, a Client, or inline SDL.
+    # class, inline SDL, or a Client built from any of those.
     def dump_path
       path = named_dump_path
       path if path && File.exist?(path)
@@ -109,6 +126,9 @@ module GraphWeaver
       return GraphWeaver::SchemaLoader.locate_path unless @schema
 
       source = named_source
+      # a client built from a dump names that dump: the file is where a
+      # supergraph's routing table is, and the loaded schema is not
+      source = source.schema_source if source.respond_to?(:schema_source) && source.schema_source
       path = source.respond_to?(:to_path) ? source.to_path : source
       path if path.is_a?(String) && GraphWeaver::SchemaLoader.dump_path?(path)
     end
@@ -133,26 +153,16 @@ module GraphWeaver
       url || live_schema
     end
 
-    # The url this graph's modules post to, or nil. `client:` holds a constant
-    # or its name — codegen spells it into source — so a name is resolved here
-    # the way the generated DEFAULT_CLIENT lambda resolves it; a graph baking
-    # none posts to the app default, which is where its modules go too.
+    # The url this graph's modules post to, or nil — the graph's own client,
+    # else the app default, which is where its modules go too. What
+    # `schema:refresh` bootstraps a missing dump from, and what `rake
+    # graph_weaver:graphs` reports; a client with no url (a schema class
+    # running in-process) has none to report.
     def client_url
-      client = @client.is_a?(String) ? resolve_client! : @client
-      client ||= GraphWeaver.client
-      target = (client.transport if client.respond_to?(:transport)) || client
+      target = client || GraphWeaver.client
+      target = (target.transport if target.respond_to?(:transport)) || target
       target.url if target.respond_to?(:url)
     end
-    private :client_url
-
-    def resolve_client!
-      Object.const_get(@client)
-    rescue NameError
-      raise GraphWeaver::Error, "graph #{name.inspect} bakes client #{@client.inspect} into its " \
-        "modules and nothing defines that constant, so there is no endpoint to introspect " \
-        "#{named_dump_path} from"
-    end
-    private :resolve_client!
 
     # The composed supergraph this graph plans against, or nil — the dump it
     # names (for the default graph, the conventional one) when that dump
@@ -222,13 +232,12 @@ module GraphWeaver
       # The same three calls an app already writes at the top level, scoped here
       # to this graph alone.
       REGISTRATIONS = %i[register_scalar register_enum extend_type].freeze
-      # These three end up spelled in generated source, so each takes the
-      # constant or its name and stores the name.
-      CONSTANT_SETTINGS = %i[client namespace types_module].freeze
-      # …and these two are spelled as a `module` DEFINITION rather than a
-      # reference, which is why a root anchor is refused on them below.
+      # These two are spelled in generated source, as a `module` DEFINITION,
+      # so each takes the constant or its name and stores the name — and a
+      # root anchor is refused on them below. `client` isn't spelled anywhere:
+      # the graph resolves it at call time, so it takes the object.
       MODULE_SETTINGS = %i[namespace types_module].freeze
-      private_constant :CONSTANT_SETTINGS, :MODULE_SETTINGS
+      private_constant :MODULE_SETTINGS
 
       attr_reader :settings, :registrations
 
@@ -283,17 +292,18 @@ module GraphWeaver
       def respond_to_missing?(name, _private = false) = false
 
       # A Module where a constant's name goes says the same thing, and is what
-      # `client Billing::CLIENT` reads like. Anything else passes through:
-      # a schema is a path, SDL, a class, a Client, or a callable.
+      # `namespace Billing` reads like. Anything else passes through: a schema
+      # is a path, SDL, a class, a Client, or a callable, and a client is
+      # whatever object answers #execute.
       # On the singleton so the define_method setters above can reach it — srb
       # reads a define_method block's self as the class.
       def self.constant_name(setting, value)
-        return value unless CONSTANT_SETTINGS.include?(setting)
+        return value unless MODULE_SETTINGS.include?(setting)
 
         # Generated modules are defined at the top level, where a root anchor
         # says nothing — and `module ::A::B` is not a name const_get can spell,
         # so it used to surface as a verdict on the .graphql file's name.
-        if MODULE_SETTINGS.include?(setting) && value.is_a?(String) && value.start_with?("::")
+        if value.is_a?(String) && value.start_with?("::")
           raise ArgumentError, "#{setting} #{value.inspect}: drop the leading `::` — #{setting} " \
             "names a module generated source defines, and it defines it at the top level either way"
         end

data/lib/graph_weaver/internal/test_clients.rb

@@ -8,13 +8,12 @@ module GraphWeaver
     # a `graphql_*` helper writes to.
     #
     # A tag used to work by swapping GraphWeaver.client, which is the LAST
-    # place a module looks: one generated with `client:` reads its baked
-    # DEFAULT_CLIENT first and never got there, so the tag quietly didn't
-    # apply. The mode installs itself here instead, and QueryModule asks
-    # before it reads that constant — so a tag reaches every module the
-    # example runs, bound or not.
+    # place a module looks: one whose graph names a client of its own reads
+    # that first and never got there, so the tag quietly didn't apply. The
+    # mode installs itself here instead, and QueryModule asks before it reads
+    # the graph — so a tag reaches every module the example runs.
     #
-    # Keyed by the graph a module was generated from (its baked GRAPH), since
+    # Keyed by the graph a module was generated from (its GRAPH), since
     # the honest answer varies: :fake for a billing module has to fabricate
     # billing's shapes, not the other schema's. A helper names its graphs the
     # same way and lands in the same table, so what an example says applies to
@@ -254,11 +253,8 @@ module GraphWeaver
         # generated before its graph was declared, or by an older release —
         # and guessing would fake one schema's shapes at another's module.
         def graph_for!(mod)
-          graphs = GraphWeaver.graphs
-          return graphs.first if graphs.one?
-
           name = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
-          found = graphs.find { |graph| graph.name == name }
+          found = Util.graph_named(name)
           return found if found
 
           # Two doors produce a module, so the fix has two spellings: a file
@@ -268,7 +264,7 @@ module GraphWeaver
           raise GraphWeaver::Error, "#{mod} doesn't say which of this app's graphs " \
             "(#{declared_names}) it was generated from, so #{@mode.inspect} has nothing to run " \
             "it against — regenerate it (rake graph_weaver:generate), or, if it came from " \
-            "GraphWeaver.parse, say which there (graph: #{graphs.first.name.inspect})."
+            "GraphWeaver.parse, say which there (graph: #{GraphWeaver.graphs.first.name.inspect})."
         end
       end
     end

data/lib/graph_weaver/internal.rb

@@ -141,6 +141,21 @@ module GraphWeaver
           schema && GraphWeaver.graphs.find { |candidate| candidate.live_schema.equal?(schema) }
         end
 
+        # The declared graph `name` names, or nil — how a generated module
+        # finds the graph whose client it runs against, and whose schema a
+        # test mode fabricates from.
+        #
+        # One graph in an app is the answer whatever a module calls it: a
+        # module generated before its graph was named, or by an older release,
+        # still belongs to the only graph there is. With several, guessing
+        # would send one schema's query to another's endpoint.
+        def graph_named(name)
+          graphs = GraphWeaver.graphs
+          return graphs.first if graphs.one?
+
+          graphs.find { |graph| graph.name == name }
+        end
+
         # Where generated modules are READ from: the configured patterns, plus
         # any graph writing somewhere they don't already cover. generated_paths'
         # default glob (app/graphql/*/generated) covers the conventional layout,

data/lib/graph_weaver/query_module.rb

@@ -12,21 +12,21 @@ module GraphWeaver
   # Runtime for generated query modules: the client plumbing, which is the
   # one part of a generated module that carries no per-query type
   # information — every module's copy was identical. `extend
-  # GraphWeaver::QueryModule` supplies `client`/`client=`; execute and
-  # from_response stay generated, since their sigs are the query's types and
-  # those are the point.
+  # GraphWeaver::QueryModule` supplies `client`; execute and from_response
+  # stay generated, since their sigs are the query's types and those are the
+  # point.
   #
-  # Resolution order, per the docs: per call → per module (`MyQuery.client =`)
-  # → a test mode's stand-in (Internal::TestClients) → the module's baked
-  # DEFAULT_CLIENT → `GraphWeaver.client`.
+  # Resolution order, per the docs: per call → a test mode's stand-in
+  # (Internal::TestClients) → the client the module's graph names →
+  # `GraphWeaver.client`. A module has no fifth slot you can set: a parsed
+  # module runs against whatever parsed it (GraphWeaver.parse(client:)),
+  # which is a property of parsing rather than a per-module override.
   module QueryModule
     extend T::Sig
 
-    sig { params(client: T.untyped).void }
-    attr_writer :client
-
-    # the default client (a GraphWeaver::Client or any transport) for
-    # execute: per-module override, else the baked default, else the app one
+    # What this module would execute through, right now — the client a parse
+    # bound it to, else the order above. A diagnostic, and what `execute`
+    # reads when the call names none.
     sig { returns(T.untyped) }
     def client
       @client || default_client
@@ -34,6 +34,13 @@ module GraphWeaver
 
     private
 
+    # Bound by GraphWeaver.parse, which is the only caller: a parsed module
+    # generates no file, so it has no graph to read a client off. Private
+    # because a generated module's client comes from its graph — one way to
+    # say a thing.
+    sig { params(client: T.untyped).void }
+    attr_writer :client
+
     # The one call a generated `execute` makes: resolve the client, run this
     # module's own operation, hand the raw response back for from_response to
     # wrap. Here rather than emitted, so what has to BRACKET a request — the
@@ -55,9 +62,7 @@ module GraphWeaver
       mod = T.unsafe(self)
       # the graph codegen baked in, never one inferred from the client — a
       # wrong label on a request is worse than no label
-      graph = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
-
-      GraphWeaver::Internal::Log.with_graph(graph) do
+      GraphWeaver::Internal::Log.with_graph(graph_name) do
         client_for(client).execute(mod.const_get(:QUERY), variables:,
           operation_name: mod.const_get(:OPERATION_NAME))
       end
@@ -79,20 +84,28 @@ module GraphWeaver
         "#{self}: client must respond to #execute(query, variables:), got #{target.class}"
     end
 
-    # Codegen's `client:` constant, emitted as a DEFAULT_CLIENT lambda so the
-    # constant it names is resolved on first use rather than at load — a
-    # generated file may load before the initializer that builds the client.
+    # A module knows which graph it belongs to, and the graph knows how to
+    # reach it: the client that graph names, else the app default. Read at
+    # call time, so renaming the constant a graph names is an initializer
+    # edit rather than a regeneration of every module.
     #
-    # A test mode stands in for it: what codegen baked in is exactly what a
-    # `graphql:` tag means to replace, so a bound module is covered by the
-    # tag like every other one.
+    # A test mode stands in ahead of it: the graph's client is exactly what a
+    # `graphql:` tag means to replace, so a tagged example reaches a module
+    # whose graph names a client like every other one.
     sig { returns(T.untyped) }
     def default_client
-      mod = T.unsafe(self)
-      stand_in = GraphWeaver::Internal::TestClients.for(mod)
+      stand_in = GraphWeaver::Internal::TestClients.for(T.unsafe(self))
       return stand_in if stand_in
 
-      mod.const_defined?(:DEFAULT_CLIENT, false) ? mod.const_get(:DEFAULT_CLIENT).call : GraphWeaver.client!
+      GraphWeaver::Internal::Util.graph_named(graph_name)&.client || GraphWeaver.client!
+    end
+
+    # The graph codegen baked in, by name — nil for a module generated before
+    # graphs existed, or by a GraphWeaver.parse that named none.
+    sig { returns(T.untyped) }
+    def graph_name
+      mod = T.unsafe(self)
+      mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
     end
   end
 end