graph_weaver 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f9913a2f1dba64e814682cd54d4f6f3da0696071e1f20f0045aaf585eb8fe4b
-  data.tar.gz: 57f2f2b701f09c52235dd0acedee77891b8ed0a570f28a086e140ef3c7a7c57b
+  metadata.gz: af7804f6f324bf878d1b11ba4da8e2adc8e2ea4c055fb80a703e91d8ca4eb3cd
+  data.tar.gz: fe6fd6340203a8937c836281342c0efcdb701203295e8a4fcf37260892a5afec
 SHA512:
-  metadata.gz: 469bff9b186698995c51ed7997957ecccb613c70da29ea0a9788e9597cb9c4cb4a679ceb95cd23aade6475159dbbd47fa7f13c5073ee5a28b5f3f2b0e4dc3483
-  data.tar.gz: 0144261b27419fd180a96193c0cfc1a6bc2d023fbb9d2cbb55e45f9608118385b91d4e2ee5a453a21c0022a0804aa88e598981c925322b3519144bfd246d0c45
+  metadata.gz: 1e5bd51d719bec6ddb81a75bab2bc68bb7b7ab9fd0c656fbbb0fd2497433ebe733893bda80e7d5dc1b4735487c1d787c5d10156dd7b0f8634e6740907af4fe01
+  data.tar.gz: 4fd87cae3d8c320c9dfb61b08f4464d3d2978c831a35c0b26c4262b27929e90da52e1a528d411b6b1689d45e24edca5d2727c3e9dc42bb5bf6202589d0973d71

data/CHANGELOG.md

@@ -1,3 +1,131 @@
+###  v0.5.1  (2026-09-07)
+- **A union's catch-all struct keeps the fields an interface fragment asked
+  for.** `... on Named { name }` under a union types `name` on every member the
+  query named, but the catch-all — the member it didn't name, including one the
+  schema grows later — carried only `__typename`, so a `name` the server
+  actually sent was dropped on the floor. Those fields are `T.nilable`: the
+  member that arrives needn't implement the interface. **Regenerate** to pick
+  it up.
+- **`schema_stale?` now recognises the drift a graphql-ruby server reports.**
+  It matched Apollo's one flat code plus a message pattern, but graphql-ruby —
+  which this library ships as its in-process client — names the rule that fired
+  in `extensions.code`. So a renamed type, a removed argument, an argument that
+  became required and four other drift shapes all raised without the one
+  sentence telling you to refresh the dump and regenerate, and `to_h` reported
+  `"schema_stale": false`.
+- **A cast failure keeps the server's own explanation.** A field that came back
+  null *with a reason* — a permission rule, a partial outage — raised only
+  Sorbet's nil complaint, because the generated envelope built `data` before it
+  read `errors`. The reason is now in the message. **Regenerate** to pick it up.
+- **Cassette anonymization missed `errors` and `extensions`.** It walked
+  `data` and nothing else, so a rejected request's error message — which
+  routinely quotes the input that caused it — and whatever the server hangs
+  off `extensions` went to disk verbatim, under a flag that says real data
+  never reaches it. **Re-run `rake graph_weaver:cassettes:anonymize` on any
+  cassette you've already committed**, or re-record it. Neither key has a
+  schema behind it, so both are now walked by shape: keys, nesting, nulls and
+  booleans survive and every string and number is replaced, with `path`,
+  `locations` and an error's `extensions.code` kept because they describe the
+  request rather than the data.
+- **Recording flags a credential that lands in the file.** A cassette gets
+  committed as written, and its query and variables can't be anonymized —
+  they're the key replay matches on. So the bytes headed for disk are checked
+  for the shapes that are unmistakable (a JWT, `AKIA…`, `ghp_…`, `xox…`,
+  `sk_live_…`, a PEM block, a `Bearer` header) and named on stderr once per
+  cassette. Nothing is rewritten; a password like `hunter2` has no shape, so a
+  quiet run still isn't a clean bill of health.
+- **An anonymized cassette no longer drops a key selected twice.** The
+  anonymizer kept the last occurrence's sub-selection where codegen merges
+  them, so `a { x } a { y }` came back holding only `y` — a recording that
+  then failed its own `cassettes:check`.
+- **Three generated types disagreed with the schema.** `srb tc` proves the
+  generated code is self-consistent, not that it is true, so each of these was a
+  lie the typechecker endorsed. **Regenerate** to pick them up:
+  - A field reached only through a `@skip`/`@include`-guarded occurrence, where
+    the same key is also selected unguarded, was typed as guaranteed. The server
+    legitimately omits it, so `from_h` raised `key not found` on a valid
+    response — and a union whose `__typename` arrived that way crashed its own
+    dispatch. Those children are nilable now, and the `__typename` case refuses
+    at generation as it already did for the plainer spelling.
+  - A narrowed abstract inside a non-null list made the *list* nilable
+    (`[Thing!]!` with `... on Widget` → `T.nilable(T::Array[…])`). Only the
+    elements can be nil; the array is always there.
+  - An input field the schema gives a default is optional, but a non-null one
+    emitted `const :x, String, default: nil` — so `x.upcase` typechecked and
+    was a `NoMethodError`.
+- **`rake graph_weaver:federation:coverage` no longer counts a subgraph as
+  served here when two loaded schemas fit it.** `Router.new` refuses that case
+  — picking either would be a coin flip — so the report was promising a run
+  the suite can't have. It now lands in the "nothing here serves what they
+  reach" list, whose advice (name a schema for those subgraphs) is the fix.
+- **A supergraph that renamed the join spec is now refused instead of read as
+  empty.** `@link(url: ".../join/v0.3", as: "j")` spells every marker `j__`,
+  which the routing table doesn't follow — so it reported a composed graph with
+  *no subgraphs* and nothing unsupported, and `Testing::Router` built happily on
+  top of that. It now lands in `unsupported`, so the router and
+  `federation:coverage` refuse at construction and say why.
+- **`rake graph_weaver:cassettes:anonymize` now finds an SDL schema dump.** It
+  opened `GraphWeaver.schema_path` directly instead of locating the dump the
+  way every sibling task does, so an app whose committed dump is
+  `schema.graphql` (what the generator writes for a supergraph) got a raw
+  `Errno::ENOENT`. A missing dump now says so.
+- **`rake graph_weaver:queries:check` now authenticates with the token your
+  app uses.** It re-introspects the url the dump records, but read
+  `GRAPHWEAVER_AUTH` rather than the ENV var the dump named — so an app
+  installed with `--auth MY_TOKEN` reached its private API while the check
+  401'd. Every re-introspection now goes through `SchemaLoader.source_transport`,
+  which is also now public.
+- **A `graphql: :router` example now starts from the same fabricated data
+  whether it runs alone or after two hundred others.** The router is built once
+  for the suite, and a faked subgraph kept fabricating from wherever the last
+  example left its sequence — so `rspec spec/foo_spec.rb:12` disagreed with the
+  same example in a full run, which is the opposite of what `--seed` promises.
+  `Router#reset!` is the example boundary (`reset_trace` still clears only the
+  trace); the rspec tag calls it for you.
+- **An override key given as a Symbol now pins.** `graphql_fake(overrides: { name: "Ada" })`
+  validated clean and silently fabricated a random value, because lookup is by
+  String — the exact silent-green failure the override validation exists to
+  prevent.
+- **A helper no longer contradicts `config.default_mode`.** With
+  `default_mode = :fake`, an untagged example calling `graphql_in_process`
+  raised *"this example is tagged graphql: :fake"* — naming a tag that wasn't
+  there, and blocking the untagged form the docs recommend. Only an explicit
+  tag can disagree with a helper now.
+- **A variable default that isn't a Boolean no longer reaches a subgraph.** An
+  enum or input-object default is a parser AST node; sending one put a
+  back-pointer to the lexer on the wire, and an input object raised
+  `NoMethodError` outside any rescue. Only `@skip`/`@include` read these, and
+  they read Booleans; a subgraph applies its own defaults from the variable
+  declaration it already receives.
+- The local router asks the schema for one type by name rather than rebuilding
+  the whole type map, at four sites — one of them per response row. On a
+  1200-type supergraph a stitched query over 200 rows was **5x** slower than it
+  needed to be; the cost is now flat in schema size.
+- **`graphql: :in_process` ran the committed schema dump instead of your live
+  schema class.** A dump loads as an anonymous `GraphQL::Schema` subclass, which
+  looks like a runnable class and has no resolvers — so every app that followed
+  `getting_started.md` (the generator always commits a dump) got a graphql-ruby
+  500 blaming its own resolver, and the error that was written to explain this
+  was unreachable. Nothing to do; if you worked around it with
+  `Testing.config.schema = MySchema`, that still works and still wins.
+- **`GraphWeaver.parse(query:)` accepts a `Pathname`.** `schema:` already did,
+  so `GraphWeaver.parse(schema: Rails.root.join("schema.graphql"), query:
+  Rails.root.join("app/graphql/queries/person.graphql"))` died on the query
+  argument with `undefined method 'end_with?'`. Same for `client.parse(path)`.
+- **`rake graph_weaver:cassettes:check` and `:anonymize` now find cassettes
+  from any working directory.** Both read `config.cassette_dir` raw, while
+  `Cassette.new` resolves it against `Rails.root` — so run from anywhere but
+  the app root, `check` aborted with "this checked nothing, so it proved
+  nothing" and `anonymize` silently did nothing, both while a spec run found
+  the same files fine. They now use the same resolution the recordings do.
+- **An `extend_type(alias:)` name a struct instance already answers to now
+  refuses** instead of silently overriding it. `alias: { hash: "…" }` emitted
+  `def hash`, which breaks every `Hash` and `Set` holding that struct;
+  `inspect`, `to_s`, `method` and `class` were the same story. A *wire field*
+  by any of those names was already refused, so this is the same rule reaching
+  the same case from the other side. **If generation now refuses an alias you
+  had**, rename it — the accessor it generated was overriding a Ruby method.
+
 ###  v0.5.0  (2026-09-07)
 - **`graphql_in_process(SomeSchema)`** runs one example against that schema
   class's real resolvers — the sibling of `graphql_fake`, and how a federated

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.5.0)
+    graph_weaver (0.5.1)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -176,7 +176,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.5.0)
+  graph_weaver (0.5.1)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

data/README.md

@@ -97,7 +97,7 @@ fetches:
 The trace is the query plan: every node at a level in one `_entities` call, so two
 products cost one fetch. Anything it can't answer *faithfully* it refuses at plan
 time rather than guessing — and it's diffed against a real `@apollo/gateway` over
-the same supergraph, currently 42 queries identical, 1 refused, 0 wrong
+the same supergraph, currently 72 queries identical, 2 refused, 0 wrong
 ([`spec/integration/router_parity_spec.rb`](spec/integration/router_parity_spec.rb)).
 See [federation](docs/federation.md).
 

data/docs/cassettes.md

@@ -82,9 +82,29 @@ preserving everything that makes the recording faithful:
 | enums, booleans, `__typename` | numbers, dates |
 | id *relationships* (same original id → same fake id) | the id values themselves |
 
-It needs the schema — it walks each recorded query's selections to know which
-values are enums, dates, ids. Variables are NOT anonymized: they're the replay
-matching key, so don't record with secret variables.
+`data` is walked against the schema — which is why it needs one, to know which
+values are enums, dates, ids. `errors` and `extensions` have none behind them,
+so they're walked by shape instead: keys, nesting and structure survive, every
+string and number is replaced. `path`, `locations` and an error's
+`extensions.code` are kept, because they describe the request rather than the
+data — and call sites branch on `code` the way they branch on an enum.
+
+**The query and its variables are not anonymized.** They're the key replay
+matches on, so scrubbing them would make the recording unfindable. A mutation's
+input is often the sensitive part, so record with placeholder variables, or
+don't record that request.
+
+Recording says so when the bytes it wrote look like a credential:
+
+```
+graph_weaver: spec/cassettes/github.yml contains a JWT, a GitHub token — a
+cassette is committed as written, so review this one first. …
+```
+
+It recognizes tokens by shape — a JWT, `AKIA…`, `ghp_…`, `xox…`, `sk_live_…`, a
+PEM block, a `Bearer` header — which is every credential that is unmistakable
+and nothing else. A password like `hunter2` has no shape, so a quiet run is not
+a clean bill of health: **read a cassette before committing it.**
 
 For cassettes recorded before the flag was on:
 

data/docs/errors.md

@@ -36,8 +36,10 @@ subclass says where it failed:
 | `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
 | `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#field`, `#struct` |
 | `ValidationError` | build time: the query didn't validate against the schema |
+| `Codegen::Aliases::UnknownSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path names a field no type here has — a typo, so `optional: true` won't skip it |
 | `ConfigurationError` | setup judged against your schema — which Ruby schema serves which subgraph (`Testing::Router`, `federation:diff`) |
 | `Testing::Unplannable` | the local test router won't plan this operation — `#category`, `#detail` |
+| `Testing::MissingRecording` | a [cassette](cassettes.md) holds no entry for this request — the message prints the variables, and the ones it did record |
 
 An argument that is wrong *on its face* raises a plain `ArgumentError` instead
 (`pool_size: must be >= 1`, `cast: must be a Symbol, Proc, :itself, or nil`),

data/docs/federation.md

@@ -67,7 +67,7 @@ metadata.
 
 The derivation is diffed against Apollo's own `composeServices` +
 `toAPISchema()` in
-[`spec/integration/api_schema_spec.rb`](../spec/integration/api_schema_spec.rb),
+[`spec/integration/api_schema_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/integration/api_schema_spec.rb),
 over composed supergraphs carrying `@interfaceObject`, `@join__unionMember`,
 `@join__enumValue` and an aliased `@inaccessible` — identical in each.
 
@@ -224,10 +224,10 @@ is which subgraphs a code path touched and a service object rarely runs one
 query. The rspec tag resets it before each example; outside rspec call
 `router.reset_trace` around the code path you're measuring.
 
-**[`examples/federation.rb`](../examples/federation.rb)** is the whole shape
+**[`examples/federation.rb`](https://github.com/dpep/graph_weaver/blob/main/examples/federation.rb)** is the whole shape
 in one runnable file, and the only example that needs no network: three real
 subgraphs, a boundary-crossing query through a generated module, the trace,
-and a refusal. [`spec/router_spec.rb`](../spec/router_spec.rb) is the
+and a refusal. [`spec/router_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/router_spec.rb) is the
 exhaustive reference — every plan shape, every refusal, the partly-local
 graph and the `:fake` opt-in, each as a named example.
 
@@ -435,7 +435,8 @@ $ rake graph_weaver:federation:coverage SUPERGRAPH=supergraph.graphql
 the graph — could the router split this query faithfully at all. *Servable
 here* is what your suite actually gets: every subgraph that plan reaches is one
 this process serves. In a [partly-local supergraph](#a-supergraph-only-partly-local)
-they differ, and the plannable number alone reads optimistically:
+they differ, and the plannable number alone reads optimistically — sketched
+here on a graph whose `billing` and `shipping` run elsewhere:
 
 ```
 5/5 queries plannable locally (100%), 2 servable here
@@ -454,14 +455,14 @@ the second number and says it counted planning only. The subgraph line says
 which subgraphs each query touches, so a graph whose queries all sit in one is
 visibly a different situation from one that stitches everywhere. Anything
 refused is listed after it, grouped by category, so one glance says whether the
-gap is one construct or many. The runs above are against the demo graph in
+gap is one construct or many. The first run above is the demo graph in
 `spec/support/federation`, not a real app's mix.
 
 ### How the refusals are kept honest
 
 A double that quietly answered *differently* from the router would be worse
 than no double at all, so
-[`spec/integration/router_parity_spec.rb`](../spec/integration/router_parity_spec.rb)
+[`spec/integration/router_parity_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/integration/router_parity_spec.rb)
 serves the demo subgraphs over HTTP, boots a real `@apollo/gateway` on the same
 supergraph, and runs the whole corpus through both. Three outcomes, one of them
 a defect: match, refuse, or answer differently — and the spec fails on the
@@ -547,4 +548,4 @@ And a `@key(..., resolvable: false)` declares a key this subgraph does *not*
 answer for, so it builds nothing. Key fields typed as scalars get their
 registered Ruby type; anything else (a nested selection) is an open `Hash` the
 runtime narrows. Every shape above is a named example in
-[`spec/federation_spec.rb`](../spec/federation_spec.rb).
+[`spec/federation_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/federation_spec.rb).

data/docs/generated_modules.md

@@ -409,7 +409,7 @@ The name is a function of that field's own position and nothing else, which is
 the property that matters when generated code is checked in and referenced from
 app code: **adding, removing, or reordering an unrelated selection can never
 rename a struct you already use.**
-[`spec/naming_spec.rb`](../spec/naming_spec.rb) asserts each of those three
+[`spec/naming_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/naming_spec.rb) asserts each of those three
 edits leaves the name alone.
 
 The key is used verbatim — no pluralization heuristics, so a list field `pets`
@@ -521,7 +521,7 @@ the generated struct in your own file and add sig'd methods; Sorbet merges the
 bodies.
 
 Every form above, and every error it raises, is a named example in
-[`spec/aliases_spec.rb`](../spec/aliases_spec.rb).
+[`spec/aliases_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/aliases_spec.rb).
 
 ## Clients
 

data/docs/getting_started.md

@@ -41,7 +41,7 @@ initializer that fits:
 
 | 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 |
+| `--auth` | name of the ENV var holding the auth token — default `GRAPHWEAVER_AUTH`. Url only. The name is recorded into the dump, so `schema:refresh`/`schema:diff`/`queries:check` read the same one the initializer does |
 | `--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

data/docs/logging.md

@@ -52,7 +52,7 @@ response. Its payload carries:
 | Key | |
 |-----|--|
 | `:url` | the endpoint — nil in-process |
-| `:schema` | the schema class, in-process only |
+| `:schema` | the schema class's name, in-process only — a String, so a payload logs as it stands |
 | `: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 |
 

data/docs/testing.md

@@ -62,7 +62,7 @@ DashboardQuery.execute!.me.username
 ```
 
 All three modes, tagged and running end to end, are
-[`spec/rspec_spec.rb`](../spec/rspec_spec.rb) — the reference for anything
+[`spec/rspec_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/rspec_spec.rb) — the reference for anything
 this page leaves out.
 
 ## Nothing to configure
@@ -72,9 +72,9 @@ looked for — rather than guessing**:
 
 - **the schema** is `config.schema` if you set one, else the committed dump
   at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to.
-  (`config.schema` refuses a federation *subgraph* class: fakes are fabricated
-  against it too, so one subgraph would be a fraction of the graph. A
-  federated graph has no one schema class — that's what `:router` is.)
+  (A federated app has no one schema class, so `config.schema` is the whole
+  graph's shape and an example names the subgraph whose resolvers it wants —
+  see `graphql_in_process` below.)
 - **`:in_process`** needs the live schema *class*, since only that has
   resolvers: the one your client already runs in-process, else the loaded
   class that defines everything the schema declares — the same
@@ -310,9 +310,10 @@ them offline, above the transport (no HTTP interception):
 client = GraphWeaver::Testing.cassette("github", client: live)
 ```
 
-Re-record with `GRAPHWEAVER_RECORD=1`, and set `config.anonymize = true` so
-real data never lands in a committed file — the full workflow guide is
-**[cassettes](cassettes.md)**.
+Re-record with `GRAPHWEAVER_RECORD=1`, and set `config.anonymize = true` so the
+response is scrubbed on its way to disk — the query and its variables are the
+replay key and are recorded verbatim, so read a cassette before committing it.
+The full workflow guide is **[cassettes](cassettes.md)**.
 
 ## Real resolvers, one schema — `graphql: :in_process`
 

data/docs/upgrading.md

@@ -1,16 +1,27 @@
 # 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.
+0.5.0 is one large breaking release. Almost all of it is caught mechanically,
+in this order:
 
 ```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
+# 1. rename the path settings first — generate won't load without them
+#    (queries_path -> queries_paths, generated_path -> generated_paths,
+#     fragments_path -> fragments_paths; see "One plurality rule" below)
+
+bundle exec tapioca gem graph_weaver   # 2. regenerate the RBI
+rake graph_weaver:generate             # 3. the emitted call shape changed
+srb tc                                 # 4. every call site that moved is an error
+rake graph_weaver:verify               # 5. 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.
+**Step 2 is not optional.** Against the 0.4.6 RBI, `srb tc` reports errors
+pointing into your `generated/` directory — `QueryModule`, `client_for`,
+`check_envelope!` — which read as though codegen emitted broken Ruby. It
+didn't; sorbet is checking new generated code against the old gem's types.
+Regenerate the RBI and what remains is only your own call sites.
+
+Generated code is `# typed: strict`, so step 4 finds those for you. The rest of
+this page is what a typechecker can't see.
 
 ## `execute` means one thing now
 
@@ -30,7 +41,9 @@ 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`
+call fails at runtime rather than at typecheck — as do `GraphWeaver.execute`
+and `GraphWeaver.reset_scalars!`, which are simply gone and will not be flagged
+until the RBI is regenerated (step 2): `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**:
@@ -69,16 +82,25 @@ GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalar
 
 | 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` |
+| `graphql: :none` (rspec tag) | `graphql: false` |
+
+**The shared types module was three, and is now one.** `GraphQLInputs`,
+`GraphQLEnums` and `GraphQLUnions` are all `GraphQLTypes`, and the files move
+with them — `generated/inputs/` becomes `generated/types/`. The three settings
+that named them (`inputs_module=`, `enums_module=`, `unions_module=`) are one
+`types_module=`. Regenerating writes the new tree; delete the old directory,
+which pruning leaves behind empty.
 
-`Testing::LiveSchema` is gone. If your client points at a different API than the
-schema class your specs run in-process, name it once:
+If your specs run one schema class in-process while your client points at a
+different API, name it — per example, since a federated suite runs more than
+one:
 
 ```ruby
-GraphWeaver::Testing.config.schema = MySchema
+graphql_in_process(MySchema)                     # in the example
+GraphWeaver::Testing.config.schema = MySchema    # or once, for the whole suite
 ```
 
 ## Registering from Rails

data/graph_weaver.gemspec

@@ -7,13 +7,27 @@ Gem::Specification.new do |s|
   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"]
+  # CLAUDE.md/PLAN.md/REVIEW.md/NOTES.md/DECISIONS.md are written for whoever
+  # works on the gem, not whoever installs it — and REVIEW.md carries examples
+  # from before the API it describes was rewritten
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples' \
+                     ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
+                     ':!:DECISIONS.md' ':!:Makefile' ':!:design'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
-  s.summary     = "GraphWeaver"
+  # rubygems.org shows summary as the headline, description below it
+  s.summary     = "A typed GraphQL client for Ruby"
   s.version     = GraphWeaver::VERSION
 
+  s.metadata = {
+    "bug_tracker_uri" => "#{s.homepage}/issues",
+    "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{s.homepage}/tree/main/docs",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => s.homepage,
+  }
+
   s.required_ruby_version = ">= 3.3"
 
   # 2.6.7 fills defaulted directive arguments when building from SDL

data/lib/generators/graph_weaver/install_generator.rb

@@ -31,17 +31,14 @@ module GraphWeaver
       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"
 
+      # the default is SchemaLoader's, not one restated here — an --auth the
+      # generator omits from the dump is one the schema tasks then can't find
       class_option :auth, type: :string,
-        desc: "name of the ENV var holding the auth token (url only) — default GRAPHWEAVER_AUTH"
+        desc: "name of the ENV var holding the auth token (url only) — " \
+          "default #{GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV}"
       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.
@@ -140,14 +137,16 @@ module GraphWeaver
           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.
+      # Which of GraphWeaver.new's source forms this is. Neither test is its
+      # own — a url is whatever the client calls one, a constant path whatever
+      # codegen will spell — so the generator can't disagree with either about
+      # what it just wrote an initializer for. Anything that is neither is
+      # taken as a path to a dump.
       def form
         @form ||=
           if source.match?(GraphWeaver::Client::URL)
             :url
-          elsif source.match?(CONSTANT)
+          elsif source.match?(GraphWeaver::Codegen::CONSTANT_NAME)
             :schema_class
           else
             :path
@@ -174,7 +173,7 @@ module GraphWeaver
       # writes the conventional one.
       def schema_path = (form == :path) ? source : GraphWeaver.schema_path
 
-      def auth_var = options[:auth] || DEFAULT_AUTH
+      def auth_var = options[:auth] || GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV
 
       def refresh_command
         (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
@@ -243,15 +242,16 @@ module GraphWeaver
       end
 
       # fragments are in documents: too — without them an editor reports
-      # `Unknown fragment` on any query that spreads a shared one
+      # `Unknown fragment` on any query that spreads a shared one. The glob is
+      # codegen's, so the editor validates exactly the files codegen reads.
       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}
+            - #{File.join(GraphWeaver.queries_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
+            - #{File.join(GraphWeaver.fragments_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
         YAML
       end
     end

data/lib/graph_weaver/client.rb

@@ -36,12 +36,16 @@ class GraphWeaver::Client
 
   URL = %r{\Ahttps?://}i
 
+  # refused from two branches — a url source, and a schema source with
+  # nothing to hand a context to — so the two can't word it differently
+  CONTEXT_IN_PROCESS = "context: applies to a schema class executing in-process"
+
   def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil,
     open_timeout: nil, read_timeout: nil, context: nil, &middleware)
     check_source!(source)
 
     if source.is_a?(String) && source.match?(URL)
-      raise ArgumentError, "context: applies to a schema class executing in-process" if context
+      raise ArgumentError, CONTEXT_IN_PROCESS if context
 
       built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
       @transport = wrap_retries(built, retries)
@@ -65,7 +69,7 @@ class GraphWeaver::Client
       if context && !(source.is_a?(Module) && transport.nil?)
         # nothing would ever read it — a dump has no resolvers, and an
         # explicit transport carries its own
-        raise ArgumentError, "context: applies to a schema class executing in-process"
+        raise ArgumentError, CONTEXT_IN_PROCESS
       end
 
       # InProcess adds context:, logging and branded errors to the bare

data/lib/graph_weaver/codegen/aliases.rb

@@ -56,9 +56,14 @@ class GraphWeaver::Codegen
       "#{@module_name}: #{message}"
     end
 
+    # An alias emits a plain instance method, so it is held to the same bar
+    # as a wire field's prop: a name the struct already answers to would be
+    # silently overridden, and `hash` or `inspect` breaks the object rather
+    # than the file.
     def check_alias_name!(node, name)
       taken = node.fields.any? { |f| f.prop == name } ||
-        ALIAS_RESERVED.include?(name) || RUBY_KEYWORDS.include?(name)
+        STRUCT_METHODS.include?(name) || ALIAS_RESERVED.include?(name) ||
+        RUBY_KEYWORDS.include?(name)
       return unless taken
 
       raise GraphWeaver::Error,
@@ -70,9 +75,10 @@ class GraphWeaver::Codegen
       GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
     end
 
-    # methods every generated struct already answers to; Ruby keywords are
-    # checked alongside (RUBY_KEYWORDS is defined by the class this mixes into)
-    ALIAS_RESERVED = %w[from_h serialize to_h].to_set.freeze
+    # The CLASS methods a generated struct defines; STRUCT_METHODS covers the
+    # instance side, and both are checked with RUBY_KEYWORDS alongside (all
+    # three are defined by the class this mixes into).
+    ALIAS_RESERVED = %w[from_h].to_set.freeze
     # list selectors — pick one element out of a list-typed hop, always nilable
     # (the list may be empty). Everything else is a field prop.
     LIST_SELECTORS = %w[first last].freeze

data/lib/graph_weaver/codegen/emit.rb

@@ -500,9 +500,12 @@ class GraphWeaver::Codegen
       out << "  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }"
       out << "  def self.from_response(response)"
       out << "    raw = GraphWeaver.check_envelope!(response.to_h, Result)"
+      # errors first: a cast failure is usually a field the server nulled for
+      # a reason it stated, and that reason belongs in the raised error
+      out << "    errors = (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) }"
       out << "    GraphWeaver::Response[Result].new("
-      out << "      data: (Result.from_h(raw[\"data\"]) if raw[\"data\"]),"
-      out << "      errors: (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) },"
+      out << "      data: (GraphWeaver.cast_data(Result, raw[\"data\"], errors) if raw[\"data\"]),"
+      out << "      errors:,"
       out << "      extensions: raw[\"extensions\"] || {},"
       out << "    )"
       out << "  end"
@@ -548,8 +551,13 @@ class GraphWeaver::Codegen
         out << ""
       end
       node.fields.each do |field|
+        # A schema default makes the field optional here, so the prop has to
+        # admit the nil that omitting it leaves behind — the same widening
+        # execute's kwargs already get.
+        type = field.node.prop_type
+        type = "T.nilable(#{type})" if !field.required && field.node.non_null? && type != "T.untyped"
         default = field.required ? "" : ", default: nil"
-        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
+        out << "#{pad}  const :#{field.prop}, #{type}#{default}"
       end
       out << ""
       out << "#{pad}  # (prop, wire, required, serializer, coercer) per field"

data/lib/graph_weaver/codegen/enum_type.rb

@@ -27,9 +27,7 @@ class GraphWeaver::Codegen
       # autoloading is set up after those run. Say where it does resolve.
       if type.is_a?(String)
         raise ArgumentError, "type: is the T::Enum itself, not its name — " \
-          "register_enum(#{@graphql_name.inspect}, #{type}). An autoloaded constant isn't " \
-          "resolvable while config/initializers run; register from a " \
-          "Rails.application.config.to_prepare block, which generation also runs first."
+          "register_enum(#{@graphql_name.inspect}, #{type}). #{GraphWeaver::Codegen::AUTOLOAD_HINT}"
       end
       unless type.is_a?(Class) && type < T::Enum
         raise ArgumentError, "type: must be a T::Enum subclass, got #{type.inspect}"