graph_weaver 0.4.4 → 0.5.0

data/docs/transports.md

@@ -1,10 +1,18 @@
 # Transports
 
-A *client* is anything with `execute(query, variables:)` whose result
+A *client* is anything with `execute(query, variables:, operation_name:)` whose result
 `to_h`s into `{"data" => ..., "errors" => ...}` — from a full
-`GraphWeaver::Client` down to a schema class (in-process execution), a
-[FakeClient](testing.md), or anything you write. Every slot that takes a
-client accepts any of them.
+`GraphWeaver::Client` down to a schema class
+([in-process execution](getting_started.md#your-apps-own-schema-in-process) —
+typed access to your own app's API, no socket), a [FakeClient](testing.md), or
+anything you write. Every slot that takes a client accepts any of them.
+
+**Anything holding a schema parses against it.** `client.parse(query)`, and
+the same on `InProcess`, `FakeClient` and `Testing::Router` — a typed module
+bound to that schema, running on that object, without naming either. It sits
+on top of the contract rather than in it: `Retry` wraps a client and holds no
+schema, so it has no `parse`, and a bare schema class fills the client slot
+without one. `load_queries!` is the same rule over a directory.
 
 A *transport* is the network end of that contract — GraphQL-over-HTTP. The bundled
 two — `Transport::HTTP` (net/http, zero dependencies, loaded by default)
@@ -22,31 +30,31 @@ Most apps need one line:
 github = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"])
 ```
 
-`GraphWeaver.new` builds a [`Client`](real_world.md): the best transport
-with auth applied (exposed as `client.transport`), the schema
-introspected lazily, and `parse`/`execute` bound to both.
+`GraphWeaver.new` builds a [`Client`](real_world.md): a transport with
+auth applied (exposed as `client.transport`), the schema introspected
+lazily, and `parse`/`run` bound to both. A `Client` answers the client
+contract itself, so it goes anywhere a transport does — `Retry.new(client)`,
+`subgraphs:`, a cassette recorder.
 
 - `auth:` — a token; "Bearer" is assumed unless the string carries its own
   scheme (`"Basic dXNlcjpwYXNz..."`)
+- `transport:` — `:http` (the default) or `:faraday`
 - `headers:` — anything else (API keys, custom headers)
 - `retries:` — off by default; `true` for a `Retry` with defaults,
   or a Hash of its options
+- `open_timeout:` / `read_timeout:` — seconds, defaulting to 10 and 30 on
+  either transport
 - `cache:` / `ttl:` — schema introspection caching (see
   [real world](real_world.md)); url clients only — a schema source never
   introspects, so passing them raises
 - a block customizes the Faraday connection (Faraday only — raises without it)
 
+What you pass is what you get; the client logs which transport it built at
+`info`.
+
 To wire generated modules that don't bake a client, make it the app's
 default: `GraphWeaver.client = github`. Anything satisfying the execute
-contract works there — testing's auto_fake swaps in a fake per example.
-
-**Transport pick**: `Transport::Faraday` when the app already loads
-faraday (its middleware/proxy/timeout ecosystem comes along), the
-zero-dependency `Transport::HTTP` otherwise. Detection is `defined?(Faraday)` —
-deliberately *not* a require: faraday rides along transitively in most
-bundles (stripe, octokit, ...), and try-requiring would silently switch
-transports on apps that never chose it. With faraday under
-`require: false`, load it before building the client.
+contract works there — testing's `graphql:` tag swaps in a client per example.
 
 ## Building blocks
 
@@ -54,16 +62,29 @@ The client is convenience, not the only door — construct and assign
 yourself for full control:
 
 ```ruby
-# zero-dependency Net::HTTP — persistent (keep-alive) connection,
-# mutex-serialized; timeouts raise retriable TransportError
+# zero-dependency Net::HTTP — a pool of persistent (keep-alive)
+# connections; timeouts raise retriable TransportError
 GraphWeaver::Transport::HTTP.new(
   url,
   headers: { ... },
   open_timeout: 10, read_timeout: 30,  # seconds (the defaults)
   keep_alive_timeout: 2,               # idle window before reconnecting
+  pool_size: 5,                        # concurrent requests in flight
+                                       # (default: RAILS_MAX_THREADS, else 5)
+
+  # TLS, forwarded to Net::HTTP.start — a private CA, or mTLS, without
+  # reaching for Faraday. Passing any of these to an http:// url raises
+  # rather than quietly doing nothing.
+  ca_file: "/etc/ssl/private-ca.pem",  # or ca_path: for a directory
+  cert: OpenSSL::X509::Certificate.new(File.read("client.crt")),
+  key: OpenSSL::PKey::RSA.new(File.read("client.key")),
+  verify_mode: OpenSSL::SSL::VERIFY_PEER,  # the default; VERIFY_NONE to skip
 )
 
-# Faraday: a url (+ optional middleware block), or a ready connection
+# Faraday: a url (+ optional middleware block), or a ready connection.
+# Timeouts default to the same 10/30 as Transport::HTTP — without them
+# Faraday inherits net/http's 60s/60s.
+GraphWeaver::Transport::Faraday.new(url, open_timeout: 10, read_timeout: 30)
 GraphWeaver::Transport::Faraday.new(url) do |conn|
   conn.request :authorization, "Bearer", -> { Tokens.fetch }  # dynamic tokens
   conn.response :logger
@@ -71,23 +92,83 @@ end
 GraphWeaver::Transport::Faraday.new(MyApp.faraday_connection)
 
 # One Faraday::Connection is reused for the transport's lifetime, but
-# socket keep-alive depends on the ADAPTER: Faraday's default net_http
-# adapter opens a fresh connection per request. For persistent sockets
-# (and real pooling), pick a persistent adapter:
+# socket keep-alive depends on the ADAPTER (see below) — the transport
+# logs the one it ended up with at :info:
 GraphWeaver::Transport::Faraday.new(url) do |conn|
-  conn.adapter :net_http_persistent   # gem "net-http-persistent"
+  conn.adapter :net_http_persistent
 end
 
+# In-process: a live graphql-ruby schema class, no socket — typed access
+# to your own app's API. The class alone works in any client slot; the
+# wrapper adds a request context, the same debug logging the network
+# transports emit, and errors branded under GraphWeaver::Error (a resolver
+# raise becomes a ServerError, status 500, with the original as #cause).
+GraphWeaver::InProcess.new(MySchema, context: { current_user: user })
+GraphWeaver.new(MySchema, context: { current_user: user })   # same, via a client
+
 GraphWeaver.client = ...   # the app default (a Client or any of the above)
 ```
 
+**Keeping Faraday's sockets alive.** Faraday's default `net_http` adapter
+opens a fresh connection per request — 10 TCP connections for 10 requests,
+and over HTTPS a TLS handshake each time. `:net_http_persistent` is the
+adapter that gets Faraday the connection reuse and thread-safe pooling
+`Transport::HTTP` has by default. It needs two gems, and the version
+pairing matters — **Faraday 2.x requires `faraday-net_http_persistent`
+2.x**; the Faraday-1.x-era 1.2.0 raises `NoMethodError: undefined method
+'dependency' for class Faraday::Adapter::NetHttpPersistent` at load:
+
+```ruby
+gem "net-http-persistent"                      # the HTTP client
+gem "faraday-net_http_persistent", "~> 2.0"    # the Faraday adapter for it
+```
+
+graph_weaver depends on neither and never selects an adapter for you.
+
+**Headers.** Both transports send `Content-Type: application/json`,
+`Accept: application/graphql-response+json, application/json;q=0.9` (the
+media type [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/)
+requires a conforming client to accept, with the legacy type as
+fallback), and `User-Agent: graph_weaver/<version>` so a server operator
+can attribute the traffic. Anything you pass in `headers:` wins over
+these. A prebuilt `Faraday::Connection` owns its own headers; only the
+ones it leaves unset are filled in.
+
+**Request body.** `{"query": ..., "variables": ...}`, plus
+`"operationName"` when the operation has a name — the field Apollo Studio,
+Hasura and most APMs key traces, rate limits and slow-query reports on.
+Generated modules always send one — an anonymous document is named after its
+module at generation, so the name is declared in the query too. A raw query
+string handed straight to a transport falls back to the name in the document,
+and a genuinely anonymous one sends no `operationName` key at all.
+
+**Concurrency.** One transport is normally the whole app's transport
+(`GraphWeaver.client = api`), so it has to serve every thread.
+`Transport::HTTP` opens up to `pool_size:` sockets lazily and reuses the
+warmest one; requests beyond that queue for a free slot rather than
+opening unbounded connections. A socket that errors is closed and its slot
+left empty, so the next call reconnects.
+
+`pool_size:` defaults to `RAILS_MAX_THREADS` (else 5) — the same variable
+Rails sizes its own connection pool from, because it is the same question:
+how many requests this process can have in flight at once. Lower it for a
+server that counts connections.
+
+Under a fiber scheduler (`async`, Falcon) everything here works unchanged —
+`SizedQueue`, `Mutex`, `net/http` and `Kernel#sleep` are all scheduler-aware,
+so requests multiplex on one thread at thread-equivalent throughput. But
+`pool_size:` is the same hard ceiling there, and nothing sets
+`RAILS_MAX_THREADS` for you, so set it to the concurrency you expect.
+Saturation is not silent: the first request that has to queue logs a warning
+naming how long it waited and what to raise.
+
 ## Client resolution
 
 The canonical order — how a generated module finds its client (each slot
 takes a `Client` or any bare transport/fake):
 
-1. per call: `execute(some_client, ...)` — the optional first positional
-   argument, so variables keep the entire kwarg namespace
+1. per call: `execute(client: some_client, ...)` — a kwarg like the
+   variables, and a name no GraphQL variable is allowed to take
 2. per module: `MyQuery.client = something`
 3. baked constant: `Codegen.generate(..., client: MyApi::CLIENT)`
 4. the app default: `GraphWeaver.client=`
@@ -112,11 +193,29 @@ GraphWeaver::Retry.new(
 ```
 
 Defaults: transport failures always retry (the request never arrived);
-`ServerError` only on 5xx — a 4xx is a bug in the request, retrying won't
-fix it. `retry_codes:` re-inspects response envelopes so GraphQL-level
-throttling can retry too (off by default — pass the codes your API uses).
-Exhausting `tries:` re-raises the last error (or returns the last
-code-matched response).
+`ServerError` on 5xx plus **408 and 429** — the rest of 4xx is a bug in
+the request, retrying won't fix it. `retry_codes:` re-inspects response
+envelopes so GraphQL-level throttling can retry too (off by default —
+pass the codes your API uses). Exhausting `tries:` re-raises the last
+error (or returns the last code-matched response).
+
+**`Retry-After` wins over the backoff.** When the server names a delay
+(seconds or an HTTP-date), that's the wait — the server is the only
+party that knows when its window reopens. It's clamped to `max:` so a
+"come back in an hour" can't park a thread for an hour, and not
+jittered, since it's an instruction rather than a guess.
+
+`ServerError` carries the response `#headers` (names downcased), so the
+rate-limit budget and request id are in hand without monkey-patching a
+transport:
+
+```ruby
+rescue GraphWeaver::ServerError => e
+  e.throttled?                          # 429, or 503 + Retry-After
+  e.retry_after                         # seconds, or nil
+  e.headers["x-ratelimit-remaining"]
+end
+```
 
 Or via the client: `GraphWeaver.new(url, retries: { tries: 5, retry_codes: ["THROTTLED"] })`.
 

data/docs/upgrading.md

@@ -0,0 +1,112 @@
+# Upgrading to 0.5.0
+
+0.5.0 is one large breaking release. Almost all of it is caught mechanically —
+the work is running three commands and following what they tell you.
+
+```sh
+rake graph_weaver:generate   # 1. regenerate; the emitted call shape changed
+srb tc                       # 2. every call site that moved is now a type error
+rake graph_weaver:verify     # 3. fails until the tree is regenerated
+```
+
+Generated code is `# typed: strict`, so step 2 finds the call sites for you.
+The rest of this page is what a typechecker can't see.
+
+## `execute` means one thing now
+
+Every client answers the same call — `execute(query, variables:, operation_name:)`,
+returning the raw response hash. `Client` used to spell something else under
+that name, which is why `Retry.new(client)` and `Sequence.new(client, fake)`
+raised `ArgumentError`. They work now.
+
+The one-shot sugar moved to `run`:
+
+```ruby
+client.execute!("query { … }", id: "1")   # before
+client.run!("query { … }", id: "1")       # after   (and #run for the envelope)
+
+GraphWeaver.execute(source, query, **vars)   # before
+GraphWeaver.run(source, query, **vars)       # after
+```
+
+**This one is worth grepping for.** `Client#execute` still exists, so a stale
+call fails at runtime rather than at typecheck: `rg '\.execute!?\(' --type ruby`
+and check each hit is passing `variables:` rather than loose kwargs.
+
+A generated module takes its per-call client as a **keyword**:
+
+```ruby
+PersonQuery.execute(some_client, id: "1")          # before
+PersonQuery.execute(client: some_client, id: "1")  # after
+```
+
+`GraphWeaver.resolve_transport` is gone; nothing needs unwrapping any more.
+
+## Path settings are lists
+
+`queries_paths`, `generated_paths`, `fragments_paths` — every entry is read.
+Assigning a String still works, so the change is the name:
+
+```ruby
+GraphWeaver.queries_path = "app/graphql/queries"    # before
+GraphWeaver.queries_paths = "app/graphql/queries"   # after
+```
+
+`schema_path` stays singular: one run reads one schema.
+
+## One reset
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests. The four
+narrow ones moved to where they live:
+
+```ruby
+GraphWeaver.reset_scalars!            # before
+GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalars!,
+                                      #          reset_type_helpers!)
+```
+
+## Smaller renames
+
+| before | after |
+|---|---|
+| `response.ok?` | `response.success?` |
+| `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
+| `register_scalar(…, coerce: :to_s)` | `coerce: true`, or a `cast:`/`serialize:` pair |
+| a mutation's `…Query` module | `…Mutation` |
+
+`Testing::LiveSchema` is gone. If your client points at a different API than the
+schema class your specs run in-process, name it once:
+
+```ruby
+GraphWeaver::Testing.config.schema = MySchema
+```
+
+## Registering from Rails
+
+A registration naming one of your own constants belongs in a `to_prepare` block
+— the same place the in-process client goes, and for the same reason:
+autoloading is set up after `config/initializers` run.
+
+```ruby
+Rails.application.config.to_prepare do
+  GraphWeaver.register_enum("Species", PetKind, fallback: PetKind::Unknown)
+  GraphWeaver.extend_type("Pet", PetHelpers)
+end
+```
+
+Generation depends on `:environment`, which runs `to_prepare` too, so the
+registration is in place before it emits.
+
+## If you use the federation router
+
+Detection only sees *loaded* schema classes, and Rails does not eager load for
+rake or in the default test environment. Both are one line:
+
+```ruby
+config.eager_load = true        # config/environments/test.rb
+config.rake_eager_load = true   # config/application.rb
+```
+
+Without them the `federation:*` tasks silently see nothing — and
+`federation:diff` now **fails** rather than reporting a green "matches" over
+zero subgraphs.

data/graph_weaver.gemspec

@@ -2,7 +2,9 @@ require_relative "lib/graph_weaver/version"
 
 Gem::Specification.new do |s|
   s.authors     = ["Daniel Pepper"]
-  s.description = "A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries, with federation, extensibility, and testing in mind"
+  # the README tagline, verbatim — the two pitches drifted apart once already,
+  # so spec/gemspec_spec.rb pins them together
+  s.description = "Your .graphql files, compiled into Sorbet types — and the fakes to test them."
   # ".yardopts" explicitly: `git ls-files *` skips dotfiles, and
   # rubydoc.info needs it shipped to render docstrings as markdown
   s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples'`.split("\n") + [".yardopts"]

data/lib/generators/graph_weaver/install_generator.rb

@@ -0,0 +1,259 @@
+# typed: ignore — Rails::Generators DSL, only loaded by `rails g`
+# frozen_string_literal: true
+
+require "graph_weaver"
+
+# rails g graph_weaver:install https://api.example.com/graphql
+# rails g graph_weaver:install MyApp::Schema
+# rails g graph_weaver:install db/schema.graphql
+#
+# Scaffolds the conventional layout — initializer, query/generated
+# directories, editor config — and bootstraps the schema dump, so the
+# setup in docs/getting_started.md is one command.
+#
+# The argument is what you'd pass to GraphWeaver.new, and the same three
+# source forms are accepted; the initializer it writes reflects the one
+# you chose. The source arrives on the command line rather than being read
+# from config: at install time the initializer doesn't exist yet.
+module GraphWeaver
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc <<~TEXT
+        Wire up GraphWeaver: initializer, app/graphql layout, editor config, schema dump.
+
+        SOURCE is what you'd pass to GraphWeaver.new:
+
+            rails g graph_weaver:install https://api.example.com/graphql   # an endpoint
+            rails g graph_weaver:install MyApp::Schema                     # a graphql-ruby schema, in-process
+            rails g graph_weaver:install db/schema.graphql                 # a schema dump you already have
+      TEXT
+
+      argument :source, type: :string, banner: "SOURCE",
+        desc: "what you'd pass to GraphWeaver.new: an endpoint url, a graphql-ruby schema class, or a schema dump path"
+
+      class_option :auth, type: :string,
+        desc: "name of the ENV var holding the auth token (url only) — default GRAPHWEAVER_AUTH"
+      class_option :schema, type: :boolean, default: true,
+        desc: "write the schema dump codegen reads"
+
+      # a Ruby constant path names a schema class; anything that is neither
+      # this nor a url is taken as a path to a dump
+      CONSTANT = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
+
+      DEFAULT_AUTH = "GRAPHWEAVER_AUTH"
+
+      # Before anything is written: a mistyped source or a flag that doesn't
+      # apply to it is a mistake in the command just typed, so say so there
+      # rather than at boot, three files later.
+      def check_source
+        if options[:auth] && form != :url
+          raise Thor::Error, "--auth applies to a url — #{source} is a #{form == :schema_class ? "schema class" : "schema dump"}"
+        end
+
+        schema_class if form == :schema_class
+      end
+
+      # Every write goes through create_file, so a re-run prompts with a
+      # diff rather than overwriting an initializer you've edited.
+      def create_initializer
+        create_file "config/initializers/graph_weaver.rb", initializer
+      end
+
+      def create_layout
+        create_file File.join(GraphWeaver.queries_paths.first, ".keep"), ""
+        create_file File.join(GraphWeaver.generated_paths.first, ".keep"), ""
+      end
+
+      # editor autocomplete + validation for .graphql files (docs/editors.md)
+      def create_editor_config
+        create_file "graphql.config.yml", editor_config
+      end
+
+      # A url is introspected and a schema class dumped; a dump the app
+      # already has is left where it is (schema_path points at it instead).
+      def fetch_schema
+        return unless options[:schema] && form != :path
+
+        if form == :url
+          # pass the var name, not just the token — it lands in the dump's
+          # provenance so schema:refresh/:diff read the same one the
+          # initializer does, instead of defaulting to GRAPHWEAVER_AUTH
+          GraphWeaver::SchemaLoader.refresh!(url: source, auth_env: auth_var)
+        else
+          # a schema class is its own introspection source; ttl: 0 so an
+          # existing dump never counts as fresh
+          GraphWeaver::SchemaLoader.introspect(schema_class, cache: schema_path, ttl: 0)
+        end
+        say_status :introspect, "#{schema_path} from #{source}"
+      rescue StandardError => e
+        # the files above are the valuable part — don't lose them to a bad
+        # token or an unreachable host
+        say_status :failed, "#{e.message} — retry with `#{refresh_command}`", :red
+      end
+
+      def next_steps
+        say <<~TEXT
+
+          Write a query in #{GraphWeaver.queries_paths.first}, then:
+
+              rake graph_weaver:generate
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/getting_started.md
+        TEXT
+
+        say federated_steps if subgraphs
+      end
+
+      private
+
+      # This install run is the one moment the user is guaranteed to be
+      # reading, and a composed supergraph changes what the next steps are:
+      # the test client is the interesting one, and there's a CI gate to add.
+      def federated_steps
+        <<~TEXT
+
+          #{source} is a composed supergraph (#{subgraphs.size} subgraphs: #{subgraphs.join(", ")}), so:
+
+              rake graph_weaver:federation:diff       # CI gate: a subgraph changed, nobody recomposed
+              rake graph_weaver:federation:subgraphs  # which schema here serves which subgraph
+
+          and specs run against your real resolvers across all of them, in-process:
+
+              describe "checkout", graphql: :router do ... end   # require "graph_weaver/rspec"
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/federation.md
+        TEXT
+      end
+
+      # The subgraph names this source composes, or nil when it isn't a
+      # composed supergraph. Read off the routing table rather than guessed —
+      # the same reader Testing::Router and federation:diff use.
+      def subgraphs
+        return @subgraphs if defined?(@subgraphs)
+
+        @subgraphs =
+          begin
+            (GraphWeaver::SchemaLoader.routing_table(source).subgraphs if form == :path)
+          rescue StandardError
+            # not a supergraph, or not readable — nothing to say either way
+            nil
+          end
+      end
+
+      # Which of GraphWeaver.new's source forms this is — the url test is
+      # its own, so the generator and the client can't disagree about what
+      # counts as one.
+      def form
+        @form ||=
+          if source.match?(GraphWeaver::Client::URL)
+            :url
+          elsif source.match?(CONSTANT)
+            :schema_class
+          else
+            :path
+          end
+      end
+
+      # The named schema class, resolved now: `rails g` boots the app, so a
+      # typo is catchable here rather than as a NameError at the next boot.
+      def schema_class
+        @schema_class ||= begin
+          klass = Object.const_get(source)
+          unless klass.respond_to?(:execute)
+            raise Thor::Error, "#{source} isn't a graphql-ruby schema (no .execute) — pass the class that inherits GraphQL::Schema"
+          end
+
+          klass
+        rescue NameError
+          raise Thor::Error, "uninitialized constant #{source} — pass your graphql-ruby schema class " \
+            "(rails g graphql:install writes app/graphql/<app>_schema.rb), an endpoint url, or a path to a schema dump"
+        end
+      end
+
+      # A dump the app already has stays where it is; every other form
+      # writes the conventional one.
+      def schema_path = (form == :path) ? source : GraphWeaver.schema_path
+
+      def auth_var = options[:auth] || DEFAULT_AUTH
+
+      def refresh_command
+        (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
+      end
+
+      def initializer
+        <<~RUBY
+          # frozen_string_literal: true
+
+          #{client_setup}
+          # Custom scalars, enums and type mixins go here — `rake graph_weaver:generate`
+          # bakes them into the generated source, so they must be registered first:
+          #
+          #   GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+          #   GraphWeaver.extend_type("Person", Greetable)
+        RUBY
+      end
+
+      # The load-bearing lines, per source form: what generated modules
+      # resolve to at execute time, and where codegen reads the schema.
+      def client_setup
+        case form
+        when :url
+          <<~RUBY
+            GraphWeaver.client = GraphWeaver.new(
+              "#{source}",
+              auth: ENV["#{auth_var}"],
+              cache: true, # reuse the committed dump; delete it to re-introspect
+            )
+          RUBY
+        when :schema_class
+          # to_prepare, not a bare assignment: the schema class is autoloaded,
+          # so it isn't resolvable this early, and a dev reload replaces it
+          # with a new class object the client would otherwise still hold.
+          <<~RUBY
+            Rails.application.config.to_prepare do
+              # queries run in-process against the app's own schema — no socket
+              GraphWeaver.client = GraphWeaver.new(#{source})
+            end
+          RUBY
+        when :path
+          if subgraphs
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A composed supergraph: your queries are generated against the whole
+              # graph, and a router serves it. Point the app default at the gateway:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://gateway.example.com/graphql")
+              #
+              # Specs don't need one — `graphql: :router` plans against this
+              # supergraph and runs your own subgraph resolvers in-process
+              # (docs/federation.md).
+            RUBY
+          else
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A dump is type information only — it has no resolvers, so it can't
+              # execute. Point the app default at whatever serves this API:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://api.example.com/graphql")
+            RUBY
+          end
+        end
+      end
+
+      # fragments are in documents: too — without them an editor reports
+      # `Unknown fragment` on any query that spreads a shared one
+      def editor_config
+        <<~YAML
+          # Autocomplete and validation for .graphql files in VS Code / RubyMine.
+          # https://github.com/dpep/graph_weaver/blob/main/docs/editors.md
+          schema: #{schema_path}
+          documents:
+            - #{GraphWeaver.queries_paths.first}/**/*.{graphql,gql}
+            - #{GraphWeaver.fragments_paths.first}/**/*.{graphql,gql}
+        YAML
+      end
+    end
+  end
+end