graph_weaver 0.5.1 → 0.6.1

data/docs/getting_started.md

@@ -1,8 +1,8 @@
 # Getting started: the production path (Rails)
 
-The setup that ships: queries live as `.graphql` files, generation writes
-`# typed: strict` Ruby you check in, and CI fails when anything drifts.
-In Rails one generator does the setup. (Exploring an API from a console
+The setup that ships, end to end: queries live as `.graphql` files, generation
+writes `# typed: strict` Ruby you check in, and CI fails when anything drifts.
+Follow it once when you add the gem to an app. (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
@@ -24,6 +24,7 @@ rails g graph_weaver:install https://api.example.com/graphql
 ```
       create  config/initializers/graph_weaver.rb
       create  app/graphql/queries/.keep
+      create  app/graphql/fragments/.keep
       create  app/graphql/generated/.keep
       create  graphql.config.yml
   introspect  app/graphql/schema.json from https://api.example.com/graphql
@@ -57,7 +58,7 @@ What it wrote:
   into generated source, so they have to run first:
 
   ```ruby
-  GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+  GraphWeaver.register_scalar("Money", Money)   # a scalar the registry can't know
   ```
 
   A registration that names one of your own constants — a `T::Enum` for
@@ -84,13 +85,15 @@ What it wrote:
   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.
+- **`app/graphql/queries/`, `app/graphql/fragments/`, `app/graphql/generated/`.**
+  Where you write queries, where shared fragments live, 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`.
+and its registrations — runs first. The generated modules load at boot from
+a `to_prepare` block, so a helper or enum you registered in one is already
+in place when the file that names it loads.
 
 ### Your app's own schema, in-process
 
@@ -122,11 +125,16 @@ client = GraphWeaver.new(MyApp::Schema, context: { current_user: })
 PetQuery.execute!(client:, id: "1").pet.owner   # => the context's user
 ```
 
+Each query gets its own copy of that hash, so a resolver writing
+`context[:loader] =` can't hand what it wrote to the next request — which
+matters because one in-process client is normally the whole app's.
+
 **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:
+your own repo, so rebuild it with graphql-ruby's own rake task, ahead of
+`verify` in CI:
 
 ```ruby
 # lib/tasks/graphql.rake
@@ -140,13 +148,16 @@ rake graphql:schema:json     # rewrites app/graphql/schema.json
 rake graph_weaver:generate
 ```
 
-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.)
+A stale dump makes `verify` fail on a query that is fine. `queries:check` is
+unaffected: running in-process it validates against the live class, not the
+dump. (`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.)
+
+**Scaffolding the app too?** On a `rails new --skip-active-record`,
+`rails g graphql:install` writes `config.active_record.query_log_tags` lines
+into `config/application.rb` that an app without ActiveRecord can't boot
+with — a graphql-ruby bug. Run it as
+`rails g graphql:install --skip-query-logs`, or delete the lines it wrote.
 
 ### A schema dump you already have
 
@@ -174,19 +185,28 @@ query($id: ID!) {
 rake graph_weaver:generate   # writes app/graphql/generated/person_query.rb
 ```
 
-Commit the schema dump and the generated files. Generated code is
-reviewed like any other code — and never edited by hand.
-
 ```ruby
 PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```
 
-### Autocomplete while you write the query
+Commit the schema dump and the generated files. Generated code is reviewed like
+any other code — and never edited by hand. The module name comes from the file
+name; the full set of naming rules is in
+[generated modules](generated_modules.md#naming).
 
 `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).
 
+**In development you don't type that command again.** While the server is
+running, a `.graphql` edit — or a refreshed schema dump — regenerates before
+the next request, the way a route or a locale change takes effect. A query that
+doesn't compile is logged with its file and position while the modules already
+loaded keep serving, so a file saved mid-edit doesn't take the server down.
+Development only, and `config.graph_weaver.watch = false` turns it off. The
+generated files are still what ships: commit them, and keep `rake
+graph_weaver:verify` in CI.
+
 ### Shared fragments
 
 Define reusable fragments once and spread them from any query:
@@ -205,29 +225,10 @@ Fragment files hold only fragments (no operations), and names are unique across
 them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
 default `app/graphql/fragments`).
 
-### Shared unions
-
-When a shared fragment *is* the whole selection on a union field, its type is
-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:
-
-```graphql
-# app/graphql/fragments/feed_item.graphql
-fragment FeedItemFields on FeedItem {
-  __typename
-  ... on Post { title }
-  ... on Photo { url }
-}
-
-# any query
-query { feed { ...FeedItemFields } }   # feed : T::Array[FeedItemFields::Type]
-```
-
-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
+One payoff worth knowing about: when a shared fragment *is* the whole selection
+on a union field, its type is hoisted once into `GraphQLTypes` and every query
+that spreads it gets the same Ruby type — so one exhaustive `case … T.absurd`
+works everywhere. See
 [abstract types](generated_modules.md#abstract-types).
 
 ## 4. Test against fakes
@@ -241,47 +242,74 @@ require "graph_weaver/rspec"
 it "renders the empty state", graphql: :fake do … end   # or tag the describe
 ```
 
+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. Pinning values,
+simulating failures, and the federated `graphql: :router` are in
+[testing](testing.md).
+
 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).
-
 ## 5. Verify in CI
 
-```sh
-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?
+Four questions, four tasks — the last only on a federated graph:
+
+| ask | task | needs network |
+|---|---|---|
+| is the checked-in Ruby fresh? | `rake graph_weaver:verify` | no |
+| has the server's schema drifted from the dump? | `rake graph_weaver:schema:diff` | yes |
+| did that drift break any of my queries? | `rake graph_weaver:queries:check` | yes |
+| did a subgraph change without a recompose? | `rake graph_weaver:federation:diff` | no |
+
+`verify` compares the committed generated files against what the current
+schema + queries + registrations would produce, so it belongs in every CI
+build. `schema:diff` needs a dump with a recorded source url (introspected
+dumps have one) and `GRAPHWEAVER_AUTH` for private APIs — run it on a
+schedule and repair with `rake graph_weaver:schema:refresh`.
+`federation:diff` needs no network either, so it goes in the same PR run;
+see [federation](federation.md#has-the-supergraph-been-recomposed).
+
+`schema:diff` names what moved, breaking changes first — breaking meaning
+a query written against your dump stops validating, or stops casting:
+
 ```
+app/graphql/schema.json vs https://api.example.com/graphql: 8 changes, 5 breaking
+
+breaking:
+  AdoptionInput.nickname          String -> String!
+  Person.email                    removed
+  Person.pets                     [Pet!]! -> [Pet!]
+  Query.person(includeArchived:)  argument added: Boolean! — required
+  Species.CAT                     enum value removed
 
-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).
+other:
+  Person.birthday  deprecated: use bornOn
+  Pet.nickname     added: String
+  Species.BIRD     enum value added
 
-`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.
+app/graphql/schema.json is stale — the server's schema has drifted (rake graph_weaver:schema:refresh)
+```
 
-`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`.
+Nullability is judged from your side, which is why the two above point
+opposite ways: `Person.pets` losing its `!` hands a generated struct the
+nil it declared it wouldn't get, while `AdoptionInput.nickname` gaining
+one rejects a query that omits it. Any drift exits non-zero — whether a
+change matters is yours to judge.
 
-`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:
+`GraphWeaver::SchemaLoader.diff(path)` is the same summary as an object —
+`#breaking`, `#compatible`, `#to_h`, and `#empty?` for the plain "has it
+drifted" question.
+
+`queries:check` answers the question that actually matters when the schema
+*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, and exits non-zero:
 
 ```
 app/graphql/queries/person.graphql
@@ -290,9 +318,6 @@ app/graphql/queries/person.graphql
 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):
 
@@ -303,18 +328,17 @@ GraphWeaver.check_queries
 #         "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:
+Empty means everything validates. Pass `schema:` a *loaded* schema (not a path)
+and nothing touches the network — handy for checking a proposed subgraph 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)).
+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
 

data/docs/logging.md

@@ -14,8 +14,9 @@ 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 and any unregistered scalars, query modules loaded |
-| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` |
+| `info` | schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
+| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
+| `error` | development only: a `.graphql` edit that won't compile, with its file and position — the modules already loaded keep serving |
 
 Every line carries `graph_weaver` as the progname, so formatter-based
 filtering works out of the box. Wire lines are tagged
@@ -24,8 +25,37 @@ name — so a request's lines stay paired when threads interleave.
 
 **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.
+info or above. Auth headers never log at any level.
+
+## Filtered variables
+
+Debug gets switched on during an incident, which is exactly when a
+`login(password:)` mutation's variables must not land in the log. So the
+values of sensitive keys are replaced with `[FILTERED]` before the line is
+written — at any depth, including inside input objects.
+
+In Rails you configure nothing: the railtie adopts the app's own
+`config.filter_parameters`, so GraphWeaver scrubs whatever the request logs
+already scrub.
+
+Everywhere else, one list:
+
+```ruby
+GraphWeaver.filter_parameters = [:password, /token/]
+```
+
+Strings and Symbols match as case-insensitive substrings — `:token` covers
+`apiToken` — and Regexps match themselves. The default is `[:password,
+:token, :secret, :authorization]`, which covers the usual names before
+anyone configures anything; assigning replaces it rather than adding to it,
+and `[]` turns filtering off. Anything answering `#filter(hash)` is used
+as-is, which is how the railtie hands over an
+`ActiveSupport::ParameterFilter`.
+
+The same list scrubs error messages, which reach the log at `warn` rather
+than `debug`: a variable, input field, or entity key whose name is filtered
+is rejected with `[FILTERED]` in place of the value — everything else keeps
+quoting it, since `expected an Int, got "lots"` is the whole diagnosis.
 
 ## Instrumentation
 

data/docs/real_world.md

@@ -19,10 +19,10 @@ require "graph_weaver"
 # 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).
-# 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")
+# GitHub's DateTime needs no registration — it is one of the names the
+# registry knows (docs/scalars.md). A scalar of your own would go here;
+# registrations are global and codegen-time, so one line types your
+# console and your checked-in code identically.
 
 RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {