graph_weaver 0.4.4 → 0.5.0

data/docs/getting_started.md

@@ -2,11 +2,11 @@
 
 The setup that ships: queries live as `.graphql` files, generation writes
 `# typed: strict` Ruby you check in, and CI fails when anything drifts.
-Mostly copy/paste. (Exploring an API from a console instead? Start with
-[dynamic mode](real_world.md) — no build step.)
+In Rails one generator does the setup. (Exploring an API from a console
+instead? Start with [dynamic mode](real_world.md) — no build step.)
 
 Rails is assumed below; the [non-Rails note](#not-rails) at the bottom
-covers the one difference.
+covers the differences.
 
 ## 1. Install
 
@@ -15,55 +15,150 @@ covers the one difference.
 gem "graph_weaver"
 ```
 
-## 2. Bootstrap the schema dump
+## 2. Run the generator
 
-Codegen reads a schema dump at `app/graphql/schema.json`
-(`GraphWeaver.schema_path`). You never write this file by hand —
-`cache: true` writes it on first introspection. Bootstrap once from a
-console:
+```sh
+rails g graph_weaver:install https://api.example.com/graphql
+```
+
+```
+      create  config/initializers/graph_weaver.rb
+      create  app/graphql/queries/.keep
+      create  app/graphql/generated/.keep
+      create  graphql.config.yml
+  introspect  app/graphql/schema.json from https://api.example.com/graphql
+```
+
+The argument is whatever you'd pass to `GraphWeaver.new` — the generator
+takes the same three source forms the library does, and writes the
+initializer that fits:
+
+| source | |
+|---|---|
+| `https://api.example.com/graphql` | an endpoint: introspected now, and the dump committed |
+| `MyApp::Schema` | your own graphql-ruby schema, executing [in-process](#your-apps-own-schema-in-process) |
+| `db/schema.graphql` | a [dump you already have](#a-schema-dump-you-already-have) — pointed at, not copied |
+
+| flag | |
+|---|---|
+| `--auth` | name of the ENV var holding the auth token — default `GRAPHWEAVER_AUTH`. Url only. Name a different one and the initializer follows, but `schema:refresh`/`schema:diff` still read `GRAPHWEAVER_AUTH` — set both |
+| `--no-schema` | skip writing the dump; `rake graph_weaver:schema:refresh URL=...` does it later |
+
+Re-running is safe — every file goes through the usual Rails conflict
+prompt, so an initializer you've edited is never overwritten silently.
+
+What it wrote:
+
+- **`config/initializers/graph_weaver.rb`.** `GraphWeaver.client =` is the
+  load-bearing line: generated modules without a baked transport resolve to
+  it at execute time (the full
+  [resolution order](transports.md#client-resolution)). Custom
+  scalars/enums/type helpers register here too — the rake tasks bake them
+  into generated source, so they have to run first:
+
+  ```ruby
+  GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+  ```
+
+  A registration that names one of your own constants — a `T::Enum` for
+  `register_enum`, a mixin for `extend_type` — goes 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. Generation depends on
+  `:environment`, which runs `to_prepare` too, so the registration is in place
+  before it emits.
+
+  ```ruby
+  Rails.application.config.to_prepare do
+    GraphWeaver.register_enum("Species", PetKind, fallback: PetKind::Unknown)
+    GraphWeaver.extend_type("Pet", PetHelpers)
+  end
+  ```
+
+- **`app/graphql/schema.json`.** The schema dump codegen reads
+  (`GraphWeaver.schema_path`) — never written by hand, always committed.
+  `cache: true` in the initializer reuses it; delete the file to
+  re-introspect. Prefer PR-reviewable diffs? `cache: :graphql` writes SDL
+  instead; both generate identical code. (`cache:`/`ttl:` apply only to url
+  clients — a schema source never introspects, so passing them raises.)
+- **`graphql.config.yml`.** Five lines of YAML that give VS Code and
+  RubyMine schema autocomplete, hover docs, and validation as you type in
+  `.graphql` files — no JS project, no `npm install`. Details and the honest
+  limits in [editors](editors.md).
+- **`app/graphql/queries/`, `app/graphql/generated/`.** Where you write
+  queries and where generation writes Ruby.
+
+Rake needs no wiring either: in Rails the `graph_weaver:*` tasks register
+themselves (a Railtie) and depend on `:environment`, so your initializer —
+and its registrations — runs first. The generated modules load at boot the
+same way, after `config/initializers`.
+
+### Your app's own schema, in-process
+
+An app that *serves* GraphQL with graphql-ruby can have the same typed
+access to its own API — same generated structs, no socket, no HTTP:
+
+```sh
+rails g graph_weaver:install MyApp::Schema
+```
 
 ```ruby
-GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"], cache: true).schema
+# config/initializers/graph_weaver.rb
+Rails.application.config.to_prepare do
+  # queries run in-process against the app's own schema — no socket
+  GraphWeaver.client = GraphWeaver.new(MyApp::Schema)
+end
 ```
 
-Skip this step and the generate task tells you exactly that — the error
-message is the documentation. Prefer PR-reviewable diffs? `cache: :graphql`
-writes SDL instead of introspection JSON; both generate identical code.
+`to_prepare`, not a bare assignment: the schema class is autoloaded, so it
+isn't resolvable while initializers run, and a dev reload replaces it with
+a new class object that a captured one would go stale against.
 
-Note `cache:`/`ttl:` apply only to url clients — a schema source (a live
-class or a dump) never introspects, so passing them raises.
+**Context is per request, not per app.** A resolver reading
+`context[:current_user]` gets nil from the app default — build a client
+where you know the request and pass it per call:
 
-## 3. Wire the client
+```ruby
+client = GraphWeaver.new(MyApp::Schema, context: { current_user: })
+PetQuery.execute!(client:, id: "1").pet.owner   # => the context's user
+```
+
+**Keep the dump in step with the schema.** Codegen reads the committed
+dump at `GraphWeaver.schema_path`, never the live class — that's what
+makes `rake graph_weaver:verify` a deterministic CI check. The generator
+writes the first dump; after that it's an artifact derived from code in
+your own repo, so rebuild it with graphql-ruby's own rake task:
 
 ```ruby
-# config/initializers/graph_weaver.rb
-GraphWeaver.client = GraphWeaver.new(
-  "https://api.example.com/graphql",
-  auth: ENV["API_TOKEN"],
-  cache: true,   # reuses the committed dump; delete the file to re-introspect
-)
+# lib/tasks/graphql.rake
+require "graphql/rake_task"
+GraphQL::RakeTask.new(schema_name: "MyApp::Schema", directory: "app/graphql",
+  dependencies: [:environment])
+```
 
-# custom scalars/enums/type helpers — register globally, so the rake
-# tasks bake them into generated source
-GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+```sh
+rake graphql:schema:json     # rewrites app/graphql/schema.json
+rake graph_weaver:generate
 ```
 
-`GraphWeaver.client =` is the load-bearing line: generated modules
-without a baked transport resolve to it at execute time (the full
-[resolution order](transports.md#client-resolution)). The generated
-modules themselves load at boot automatically (the Railtie requires
-everything under `generated_path`, after your initializers run) —
-outside Rails, call `GraphWeaver.load_generated!` wherever your app
-boots.
+Run the dump step ahead of `rake graph_weaver:verify` in CI — that check
+compares committed Ruby against the committed dump, so a stale dump makes
+it fail on a query that is fine. `rake graph_weaver:queries:check` is
+unaffected: when `GraphWeaver.client` runs in-process it validates
+against the live class, not the dump. (`graph_weaver:schema:diff` and
+`:refresh` are for servers you *don't* own; a dump taken from a schema
+class records no url, and they say so.)
 
-## 4. Rake tasks — nothing to do
+### A schema dump you already have
 
-In Rails the `graph_weaver:*` tasks register themselves (a Railtie), and
-they depend on `:environment`, so your initializer — and its
-registrations, which are baked into generated source — runs first.
-Outside Rails, add `require "graph_weaver/tasks"` to your Rakefile.
+```sh
+rails g graph_weaver:install db/schema.graphql
+```
 
-## 5. Write a query, generate, commit
+Sets `GraphWeaver.schema_path` to that file rather than writing a second
+copy, and introspects nothing. A dump has no resolvers, so it can't
+execute — set `GraphWeaver.client` to whatever serves the API.
+
+## 3. Write a query, generate, commit
 
 ```graphql
 # app/graphql/queries/person.graphql
@@ -86,6 +181,12 @@ reviewed like any other code — and never edited by hand.
 PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```
 
+### Autocomplete while you write the query
+
+`graphql.config.yml` is already there, so VS Code and RubyMine validate the
+`.graphql` files as you type, with schema autocomplete and hover docs — see
+[editors](editors.md).
+
 ### Shared fragments
 
 Define reusable fragments once and spread them from any query:
@@ -107,8 +208,8 @@ default `app/graphql/fragments`).
 ### Shared unions
 
 When a shared fragment *is* the whole selection on a union field, its type is
-hoisted once into a `GraphQLUnions` module and every query that spreads it
-aliases the same type — so a `union` selected across many queries becomes one
+hoisted once into the shared `GraphQLTypes` module and every query that spreads
+it aliases the same type — so a `union` selected across many queries becomes one
 Ruby type family, and you write one exhaustive `case … when … T.absurd` that
 works everywhere:
 
@@ -124,43 +225,96 @@ fragment FeedItemFields on FeedItem {
 query { feed { ...FeedItemFields } }   # feed : T::Array[FeedItemFields::Type]
 ```
 
-Hoisting is what the shared fragment buys you — there's no flag. It triggers
-only when the union field's selection is exactly that one spread (mix in other
-fields, or shadow the fragment with a query-local one of the same name, and the
-union stays inlined in that query). Named like the inputs module from the output
-path (`GraphQLUnions`, or `GithubUnions` in a multi-schema layout); override
-with `GraphWeaver.unions_module=`.
+There's no flag: hoisting triggers when the union field's selection is exactly
+that one spread. Mix in other fields, or shadow the fragment with a query-local
+one of the same name, and the union stays inlined in that query — see
+[abstract types](generated_modules.md#abstract-types).
 
-## 6. Test against fakes
+## 4. Test against fakes
 
 ```ruby
 # spec/support/graph_weaver.rb
 require "graph_weaver/rspec"
+```
 
-GraphWeaver::Testing.configure { |config| config.auto_fake = true }
+```ruby
+it "renders the empty state", graphql: :fake do … end   # or tag the describe
 ```
 
-The opt-in is deliberate (no surprise fakes); once on, the schema
-auto-locates from the committed dump and every query in every example
-executes against a seeded, schema-correct `FakeClient` — no server, no
-stubs, and `rspec --seed 1234` reproduces the fake data along with test
-order. Pin values with `overrides:`, simulate failures with `Failure.*`
+A fresh `rails g rspec:install` leaves the `spec/support` glob commented
+out in `spec/rails_helper.rb`, so uncomment it — or put the require in
+`rails_helper.rb` itself. Nothing warns you that a support file went
+unread.
+
+The tag installs a seeded, schema-correct `FakeClient` for that example —
+no server, no stubs, and `rspec --seed 1234` reproduces the fake data along
+with test order. The schema it fabricates from is derived (the committed
+dump, or your client's), so there's nothing to configure. Tag
+`graphql: :in_process` instead and the same example runs against your real
+resolvers; pin values with `overrides:`, simulate failures with `Failure.*`
 — see [testing](testing.md).
 
-## 7. Verify in CI
+## 5. Verify in CI
 
 ```sh
-rake graph_weaver:verify          # generated code fresh? fails on any drift
-rake graph_weaver:schema:verify   # server drifted? re-introspects and compares
+rake graph_weaver:verify         # generated code fresh? fails on any drift
+rake graph_weaver:schema:diff    # server drifted? re-introspects and compares
+rake graph_weaver:queries:check  # did that drift break any of your queries?
 ```
 
-Two different questions. `graph_weaver:verify` checks that the committed
-generated files match what the current schema + queries + registrations
-would produce — run it in every CI build. `graph_weaver:schema:verify`
-asks whether the *server* has moved since the dump was taken — it needs
-network, a dump with a recorded source url (introspected dumps have one),
-and `GRAPHWEAVER_AUTH` for private APIs; run it on a schedule and refresh
-with `rake graph_weaver:schema:refresh`.
+Three different questions — four on a federated graph, where
+`rake graph_weaver:federation:diff` asks whether anyone changed a subgraph
+without recomposing the supergraph you committed. It needs no network
+either, so it belongs in the same PR run; see
+[federation](federation.md#has-the-supergraph-been-recomposed).
+
+`graph_weaver:verify` compares the committed generated files against what the
+current schema + queries + registrations would produce. No network — run it in
+every CI build.
+
+`graph_weaver:schema:diff` asks whether the *server* has moved since the
+dump was taken. It needs network, a dump with a recorded source url
+(introspected dumps have one), and `GRAPHWEAVER_AUTH` for private APIs;
+run it on a schedule and refresh with `rake graph_weaver:schema:refresh`.
+
+`graph_weaver:queries:check` answers the question that actually matters
+when it *has* moved: **which of your queries no longer validate, and
+why.** It re-introspects the recorded url (without rewriting the dump) and
+validates every `.graphql` file against the schema as it is right now,
+naming each error's line and column:
+
+```
+app/graphql/queries/person.graphql
+  4:5  Field 'nmae' doesn't exist on type 'Person' (Did you mean `name`?)
+
+1 invalid query
+```
+
+It exits non-zero when anything fails, so it drops straight into CI or a
+scheduled job.
+
+The Ruby behind it returns the same thing as data, so you can wire it into
+whatever you already have (a spec, a Slack ping, an issue):
+
+```ruby
+GraphWeaver.check_queries
+# => { "app/graphql/queries/person.graphql" =>
+#      [{ "message" => "Field 'nmae' doesn't exist on type 'Person' (Did you mean `name`?)",
+#         "line" => 4, "column" => 5 }] }
+```
+
+Empty means everything validates. Pass `schema:` a loaded schema and nothing
+touches the network — handy for checking a *proposed* schema (a subgraph about
+to ship) before it's live:
+
+```ruby
+GraphWeaver.check_queries(schema: GraphWeaver::SchemaLoader.load("proposed.graphql"))
+```
+
+It wants the loaded schema, not the path. Left off, it re-introspects the url
+the dump records — and when that dump is a composed supergraph, each error also
+names the subgraphs behind the type it points at
+([federation](federation.md#the-routing-table)).
 
 ## Sorbet, with or without
 
@@ -181,8 +335,24 @@ and marked "do not edit," so excluding `generated/**` from rubocop is also fine.
 
 ## Not Rails?
 
-Everything above works the same, minus the Railtie conveniences: add
-`require "graph_weaver/tasks"` to your Rakefile yourself, and — since
-there's no `:environment` hook to run your registrations — require the
-file that does them from the Rakefile too. `GraphWeaver.load_generated!`
-goes wherever your app boots instead of an initializer.
+There's no generator, but what it writes is short — a few lines wherever
+your app boots, two directories, and the schema dump:
+
+```ruby
+GraphWeaver.client = GraphWeaver.new(
+  "https://api.example.com/graphql",
+  auth: ENV["GRAPHWEAVER_AUTH"],
+  cache: true,
+)
+GraphWeaver.load_generated!   # no Railtie to require the generated files
+```
+
+```sh
+mkdir -p app/graphql/queries app/graphql/generated
+rake graph_weaver:schema:refresh URL=https://api.example.com/graphql
+```
+
+Add `require "graph_weaver/tasks"` to your Rakefile for the rake tasks —
+and, since there's no `:environment` hook to run your registrations,
+require the file that does them from the Rakefile too. `graphql.config.yml`
+is copy/paste from [editors](editors.md).

data/docs/logging.md

@@ -14,7 +14,7 @@ What logs at which level — pick the level, get the story:
 | Level | What you see |
 |-------|--------------|
 | `debug` | the wire: query + variables per call (long queries truncated), response status/bytes, request timing, connection open/drop, dynamically parsed modules |
-| `info` | schema introspection (with timing) and cache hits/misses, generated files written, query modules loaded |
+| `info` | schema introspection (with timing) and cache hits/misses, generated files written and any unregistered scalars, query modules loaded |
 | `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` |
 
 Every line carries `graph_weaver` as the progname, so formatter-based
@@ -22,12 +22,41 @@ filtering works out of the box. Wire lines are tagged
 `[req 3 FilteredPokemon]` — a per-process request id plus the operation
 name — so a request's lines stay paired when threads interleave.
 
-Debugging a misbehaving integration is the intended use: crank to
-`Logger::DEBUG` and you'll see exactly what went on the wire, what came
-back, whether the schema came from cache or a live introspection, and
-which connection served it.
-
 **PII note**: queries, variables, and response sizes appear at debug
 only — variables can carry user data, so keep production loggers at
 info or above (or scrub in your formatter). Auth headers never log at
 any level.
+
+## Instrumentation
+
+A logger tells a human what happened; an APM needs to time it and count
+it. `GraphWeaver.instrumenter` is one callable wrapping every request —
+over the wire *and* in-process, one seam for both paths. It's a no-op
+until you set one, and `ActiveSupport::Notifications` is a two-line
+adapter:
+
+```ruby
+GraphWeaver.instrumenter = lambda do |event, payload, &block|
+  ActiveSupport::Notifications.instrument(event, payload, &block)
+end
+
+ActiveSupport::Notifications.subscribe(GraphWeaver::EXECUTE_EVENT) do |*, payload|
+  StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", ...)
+end
+```
+
+The one event is `GraphWeaver::EXECUTE_EVENT`
+(`"graph_weaver.execute"`), a single request from start to parsed
+response. Its payload carries:
+
+| Key | |
+|-----|--|
+| `:url` | the endpoint — nil in-process |
+| `:schema` | the schema class, in-process only |
+| `:operation` | the operation name sent with the request (a generated module always has one) — what a trace keys on |
+| `:status` | the HTTP status, added once the response lands |
+
+Your callable **must** call the block and return its value. A failure
+propagates through it, so the hook sees the exception and can record it.
+The query text and the variables are deliberately absent: they carry
+PII, and belong at debug on the logger where the level gates them.

data/docs/real_world.md

@@ -6,24 +6,23 @@ ships is the checked-in codegen path in the [getting started](getting_started.md
 this page is how you get there (the `parse` below becomes a `.graphql`
 file plus `rake graph_weaver:generate`, everything else stays).
 
-Everything hangs off a client — transport, schema, and scalars for one
-server. GitHub's API, end to end:
+Everything hangs off a client — transport and schema for one server. GitHub's
+API, end to end:
 
 ```ruby
 require "graph_weaver"
 
-# transport + auth in one object (see docs/transports.md for retries and
+# transport + auth in one object (docs/transports.md for retries and
 # advanced setup). cache: true dumps the schema at GraphWeaver.schema_path
-# on first introspection — the same file rake graph_weaver:generate reads —
-# and any fresh dump already present is reused regardless of format. The
-# extension picks the format: .json verbatim, .graphql SDL (reviewable
-# diffs) — or say cache: :graphql. Introspected dumps record their source
-# url in a header, so a stale dump says where it came from.
+# on first introspection — the same file rake graph_weaver:generate reads
+# (docs/getting_started.md for the formats), with the source url recorded
+# in a header, so a stale dump says where it came from.
 github = GraphWeaver.new("https://api.github.com/graphql", auth: `gh auth token`.strip, cache: true)
 
-# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse) —
-# scoped to this client; GraphWeaver.register_scalar sets the global default
-github.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse).
+# Registrations are global and codegen-time, so this line types your
+# console and your checked-in code identically (docs/scalars.md).
+GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
 
 RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {
@@ -41,10 +40,17 @@ repo&.created_at        # => 2026-07-07 ... (a real Time)
 repo&.stargazer_count   # => Integer
 ```
 
-Clients are independent — build one per server, each with its own
-transport, schema, and scalar mappings. The introspection step (seconds
-on a big API) happens lazily on first `schema`/`parse` and caches per
-`cache:`/`ttl:`; for finer control the pieces are all public
+Clients are independent — build one per server, each with its own transport
+and schema. When you're ready to check the generated code in, the same client
+is the schema `generate!` wants:
+
+```ruby
+GraphWeaver.generate!(schema: github)   # no dump on disk needed
+```
+
+The introspection step (seconds on a big API) happens lazily on first
+`schema`/`parse` and caches per `cache:`/`ttl:`; for finer control the
+pieces are all public
 (`GraphWeaver::SchemaLoader.introspect(transport, cache:, ttl:)`, or cache
 `introspect(transport).to_json` in Rails.cache and `SchemaLoader.load` it).