graph_weaver 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0953218f185ebe717f72c69937276325bc22f50eb9052547861857ba3274b062'
-  data.tar.gz: 6affb87a7444cb7a6dcfb62335cbeb3b1342ac028c3b856899dd20ca76bb0fea
+  metadata.gz: e0ae9c23b2566bfa26c786e07703e4fad357cbd09a29112d3e0c9dd5d3af916c
+  data.tar.gz: fb5f4534174e5ba9cb7b9d323af26c2a13456c022f8682bcc3ccae5e512a1c96
 SHA512:
-  metadata.gz: 61465762c1cf75a539d00e7d7236d7c5ab1872e0131ca523667bb56e7ced985ad4b4793764bdb15cd30174ef5141eb5f0f984ab97a96ed06cd81ac80f0a20212
-  data.tar.gz: f72e17d16c336a66beb3f421dd4c0ae5754dae985d309eda617666189488c5ca6c9aea6082a55f228b169a886a2a61bd0bcb5eaf5d09458ed8171e50db9c1fd3
+  metadata.gz: dc780e4f155ea89b9977822a7bb62ed9880d3b7e707fd5046229b1c91c843a9c1ec37c39fb5e2039e71c9095dfb7a0df006347a19ce4544f75f2b3fe13a35a5c
+  data.tar.gz: 3dcc86b06e670408ebc18eaaaad7447d5825d1d580b9640ed8860133ba29908eb42553d52da4a2619eb23f072f4999f5aceb622271fafc8d5431fd57a3106ed3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.0)
+    graph_weaver (0.7.1)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -240,7 +240,7 @@ GEM
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
     webrick (1.9.2)
-    yard (0.9.44)
+    yard (0.9.45)
     zeitwerk (2.8.3)
 
 PLATFORMS
@@ -299,7 +299,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.7.0)
+  graph_weaver (0.7.1)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
@@ -367,7 +367,7 @@ CHECKSUMS
   useragent (0.16.11) sha256=700e6413ad4bb954bb63547fa098dddf7b0ebe75b40cc6f93b8d54255b173844
   webmock (3.26.4) sha256=8d8da206d217ebe6968cfb09c77f4533c23074e1432bad865f3994eacbaad50d
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
-  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
   zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
 
 BUNDLED WITH

data/README.md

@@ -39,21 +39,15 @@ result.person&.nmae
 ```
 
 `person` is `T.nilable` because the schema says the field is nullable — the `&.`
-isn't defensive, it's the schema talking. A field you misspelled, or never
-selected, is a typecheck error rather than a `NoMethodError` in production.
-Static Sorbet is optional: `sorbet-runtime` is the only Sorbet gem this one
-needs, so if your app doesn't run `srb tc`, that same typo surfaces as a
-`NoMethodError` the first time the line runs instead of in CI — [Sorbet, with or
+isn't defensive, it's the schema talking. Static Sorbet is optional:
+`sorbet-runtime` is the only Sorbet gem this one needs, so in an app that doesn't
+run `srb tc` the same typo surfaces as a `NoMethodError` the first time the line
+runs, rather than in CI — [Sorbet, with or
 without](docs/getting_started.md#sorbet-with-or-without).
 
 ## Start here
 
-```ruby
-# Gemfile
-gem "graph_weaver"
-```
-
-In Rails, setup is one command:
+Add `gem "graph_weaver"` to your Gemfile. In Rails, the rest is one command:
 
 ```sh
 rails g graph_weaver:install https://api.example.com/graphql
@@ -63,41 +57,19 @@ which writes the initializer, the `app/graphql` layout, the editor config and th
 schema dump. **[Getting started](docs/getting_started.md)** walks the production
 setup end to end.
 
-You then rarely type `rake graph_weaver:generate` again: while the dev server is
-up, a `.graphql` edit regenerates and reloads before the next request, the way a
-route change does. Run it when you're ready to commit the Ruby.
-
-A second schema is a second `GraphWeaver.graph` — its own queries, output,
-client, namespace and scalar registrations — and the same one command generates
-and verifies the app: **[more than one
-schema](docs/getting_started.md#more-than-one-schema)**.
-
-Or skip the build step and poke at an API from a console —
-anything holding a schema parses, and the module runs on what parsed it:
-
-```ruby
-api = GraphWeaver.new("https://countries.trevorblades.com/")
-CountryQuery = api.parse("queries/country.graphql")   # a path or a raw string
-CountryQuery.execute!(code: "JP").country&.capital    # => "Tokyo"
-
-api.run!("query { continents { name } }").continents  # or no module at all
-```
-
-The **[examples](examples/)** run that path for real, smallest first: a public API
-in 30 lines, a paginated search, the production path against GitHub, and the
+Or skip the build step and poke at an API from a console: `GraphWeaver.new(url)`
+parses a query into a module on the spot, and `run!` executes one without a module
+at all — [against a real API](docs/real_world.md). The
+**[examples](examples/)** run that path for real, smallest first: a public API in
+30 lines, a paginated search, the production path against GitHub, and the
 federated graph below.
 
 ## Precise types are expensive to fake, so it fakes them for you
 
 Generation makes result types exact, which makes them tedious to build by hand —
 and most generators stop there and leave you the fixtures. GraphWeaver ships the
-fakes. One line in the spec helper:
-
-```ruby
-require "graph_weaver/rspec"
-```
-
-then one tag says what an example runs against:
+fakes. One line in the spec helper (`require "graph_weaver/rspec"`), then one tag
+says what an example runs against:
 
 ```ruby
 it "shows the profile", graphql: :fake do
@@ -113,71 +85,51 @@ No fixture, no stub, no HTTP — and the values are seeded from rspec's own seed
 `--seed 4242` hands back that same person and a failure reproduces.
 
 Random data answers "does this render". When the example is *about* the data, pin
-the fields it's about and let the rest stay fabricated:
+the fields it's about — `graphql_fake("Person.name" => "Ada")`, or a whole type
+off your factory — and everything else in the selection stays fabricated. Pins are
+schema names, checked and spellchecked, so a typo raises rather than leaving the
+example green against random data.
 
-```ruby
-graphql_fake("Person.name" => "Ada", "Person.pets" => [{ "name" => "Shelby" }, {}])
-
-person.name                 # => "Ada"
-person.pets.first.name      # => "Shelby"  — the second pet is still fabricated
-person.pets.size            # => 2         — a pinned list is as long as you write it
-```
-
-Keys are schema names — a field, or a whole type: `"Person" => build(:person)`
-reads the selected fields off your factory's object and fabricates the rest. They
-are checked and spellchecked, so a typo raises instead of leaving the example
-green against random data. The tag also picks a *real* client
-when you want one: `:in_process` runs your resolvers, `:router` runs them across a
-federated graph, and `:wire` serves either at your own endpoint, so the transport
-you ship runs too. Field-level failure simulation and record/replay cassettes with
-anonymization are in [testing](docs/testing.md).
+The tag also picks a *real* client when you want one: `:in_process` runs your
+resolvers, `:router` runs them across a federated graph, and `:wire` serves either
+at your own endpoint, so the transport you ship runs too. Field-level failure
+simulation and record/replay cassettes with anonymization are in
+[testing](docs/testing.md).
 
 ## Federation without a gateway
 
 When your app is both a GraphQL client and a subgraph, the local router plans a
 query across the composed supergraph and runs your **real resolvers** over the
-boundary — no gateway process, no node, no sockets. That's
-[`examples/federation.rb`](examples/federation.rb), the example that needs no
-network. Part of what it prints:
-
-```
-fetches:
-  → accounts  root fields
-  → reviews   _entities × 1 User
-  → products  _entities × 2 Product
-```
-
-The trace is the query plan: every node at a level goes in one `_entities` call,
-so two products cost one fetch. Anything it can't answer *faithfully* it refuses
-at plan time rather than guessing — the example prints one of those too, naming
-the coordinate that stopped it and what to rename. And it's diffed against a real
-`@apollo/gateway` over the same supergraph:
-currently 73 queries identical, 2 refused, 0 wrong
+boundary — no gateway process, no node, no sockets. It prints the plan as it
+fetches, batching every node at a level into one `_entities` call, and anything it
+can't answer *faithfully* it refuses at plan time rather than guessing, naming the
+coordinate that stopped it. It is diffed against a real `@apollo/gateway` over the
+same supergraph: currently 73 queries identical, 2 refused, 0 wrong
 ([`spec/integration/router_parity_spec.rb`](spec/integration/router_parity_spec.rb)).
-See [federation](docs/federation.md).
+[`examples/federation.rb`](examples/federation.rb) runs the whole thing with no
+network; see [federation](docs/federation.md).
 
 ## The schema keeps itself honest
 
 The lifecycle is rake tasks, not a CI pipeline you assemble yourself:
 `schema:refresh` re-introspects the committed dump, `schema:diff` names what
-changed when whatever that dump came from — an endpoint, your own schema class —
-has moved past it, `queries:check` names the queries that drift broke and where,
-`unused` names the selections your app stopped reading, and `verify` fails when
-the checked-in Ruby is stale.
-Generation is deterministic — same schema and queries, byte-identical files — so
-regenerating never shows a diff you didn't earn. See
+changed when whatever that dump came from has moved past it, `queries:check` names
+the queries that drift broke and where, `unused` names the selections your app
+stopped reading, and `verify` fails when the checked-in Ruby is stale. Generation
+is deterministic — same schema and queries, byte-identical files — so regenerating
+never shows a diff you didn't earn. See
 [getting started](docs/getting_started.md#5-verify-in-ci).
 
-**Any release can change what codegen emits**, patch releases included — fixing a
-generated type is a byte change. So `rake graph_weaver:generate` is part of every
-upgrade, and `verify` is what tells you when you've skipped it.
+**Any release can change what codegen emits**, patch releases included. So `rake
+graph_weaver:generate` is part of every upgrade, and `verify` is what tells you
+when you've skipped it.
 
 #### Also in the box
 
-- **Queries and mutations** with typed variable kwargs — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults. Results are generated per selection set; an input object has no selection set, so [its whole closure is](docs/generated_modules.md#an-input-object-generates-its-whole-closure)
-- **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), `@skip`/`@include` nullability
-- **Any transport**: in-process execution, a zero-dependency HTTP client, or Faraday with your own middleware — plus a composable `Retry` with backoff and jitter
-- **Structured errors**: a typed envelope that keeps partial data and extensions, an error hierarchy split by failure site, field-level reports with entity ids, and stale-schema detection
+- **Typed variable kwargs** — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
+- **Fragments**, **unions and interfaces** (member structs, `__typename` dispatch), `@skip`/`@include` nullability
+- **Any transport** — in-process, a zero-dependency HTTP client, or Faraday with your own middleware, plus a composable `Retry`
+- **Structured errors** — an envelope that keeps partial data and extensions, a hierarchy split by failure site, field-level reports, stale-schema detection
 
 #### Dig deeper
 

data/docs/alternatives.md

@@ -27,12 +27,6 @@ expensive.
 The honest counter: if your app doesn't use Sorbet, most of that value
 evaporates, and [graphlient](#graphlient) is the better answer.
 
-This idea was tried once before. `yogurt` generated Sorbet types from GraphQL
-documents, shipped two versions 70 minutes apart in November 2020, and stopped —
-its own README concedes it lacked named fragments and that the author "probably
-got a lot of the decisions wrong".<!-- https://raw.githubusercontent.com/theorygeek/yogurt/master/README.md ; versions 0.1.1 16:52 and 0.2.0 18:02 on 2020-11-26 — https://rubygems.org/api/v1/versions/yogurt.json ; last real commit 29ef902 2020-11-26 -->
-So the thesis is unproven, not proven wrong.
-
 ## The table
 
 `graphql-ruby` isn't a column because it isn't a client — see
@@ -53,7 +47,7 @@ vendor SDKs actually do.
 | **Errors** | typed envelope keeping partial data, hierarchy by failure site<!-- docs/errors.md; lib/graph_weaver/errors.rb --> | raw hashes; HTTP errors become a fake `errors` array<!-- lib/graphql/client/http.rb:80-85; https://github.com/github-community-projects/graphql-client/issues/67 --> | raises a real class hierarchy on every failure<!-- lib/graphlient/errors/ --> | thin hierarchy, mostly never raised<!-- lib/artemis/exceptions.rb — GraphQLError/GraphQLServerError defined, never raised --> | yours to write |
 | **Transport** | `Net::HTTP` (pooled) or Faraday, plus `Retry`<!-- docs/transports.md; lib/graph_weaver/transport/ --> | stock adapter self-described as trivial<!-- lib/graphql/client/http.rb:17-19 "Production applications should consider implementing their own network adapter" --> | Faraday 2.x, full middleware access<!-- lib/graphlient/adapters/http/faraday_adapter.rb:36-48 --> | four adapters, no middleware layer<!-- lib/artemis/adapters.rb; https://github.com/yuki24/artemis/issues/57 open since 2019 --> | whatever you picked |
 | **Rails** | generator, railtie, reload-on-edit, rake lifecycle<!-- lib/generators/graph_weaver/install_generator.rb; lib/graph_weaver/railtie.rb; lib/graph_weaver/tasks.rb --> | opt-in railtie, no generators; docs call the boot order "a mess"<!-- lib/graphql/client/railtie.rb:34-37 TODO; https://github.com/github-community-projects/graphql-client/blob/master/guides/rails-configuration.md --> | none | the whole pitch: generators, config, callbacks<!-- lib/artemis/railtie.rb; lib/generators/artemis/ --> | n/a |
-| **Last release** | v0.7.0, 2026-09-12 | v0.26.0, 2025-05-29<!-- https://rubygems.org/api/v1/gems/graphql-client.json --> | v0.9.0, 2026-08-02<!-- https://rubygems.org/api/v1/gems/graphlient.json --> | v1.1.0, 2024-08-16<!-- https://rubygems.org/api/v1/gems/artemis.json --> | n/a |
+| **Last release** | v0.7.1, 2026-09-13 | v0.26.0, 2025-05-29<!-- https://rubygems.org/api/v1/gems/graphql-client.json --> | v0.9.0, 2026-08-02<!-- https://rubygems.org/api/v1/gems/graphlient.json --> | v1.1.0, 2024-08-16<!-- https://rubygems.org/api/v1/gems/artemis.json --> | n/a |
 | **Downloads** | 7.5k<!-- 7,478 — https://rubygems.org/api/v1/gems/graph_weaver.json --> | 94M<!-- 94,408,657 --> | 32M<!-- 32,287,626 --> | 430k<!-- 425,737 --> | n/a |
 
 ## graphql-client

data/docs/cassettes.md

@@ -1,15 +1,12 @@
 # Cassettes: capture and replay
 
 Cassettes record real API responses and replay them in tests — above the
-transport (a client wrapping a client), so there's no HTTP interception and
-they work identically over HTTP, Faraday, or in-process execution. A cassette
-is a YAML list of `{query, variables, operationName, response}` entries,
-matched on everything but the response — the request's identity as the server
-sees it.
+transport (a client wrapping a client), so there's no HTTP interception and they
+work identically over HTTP, Faraday, or in-process execution.
 
 `Testing.cassette(name, client:)` returns a client that replays
 `spec/cassettes/<name>.yml`, recording it through `client:` first if the file
-doesn't exist yet.
+doesn't exist yet:
 
 ```ruby
 client = GraphWeaver::Testing.cassette("github", client: live)
@@ -17,7 +14,7 @@ result = RepoQuery.execute!(client:, owner: "dpep", name: "graph_weaver")
 ```
 
 That first run writes `spec/cassettes/github.yml` (`Testing.config.cassette_dir`
-resolves bare names). Commit it — with anonymization on (below), since
+resolves bare names). Commit it — with [anonymization](#anonymization) on, since
 recordings hold real data — and the suite runs offline from then on. Re-record
 when the API's real behavior changes:
 
@@ -27,20 +24,27 @@ GRAPHWEAVER_RECORD=1 bundle exec rspec   # every Testing.cassette records afresh
 
 (`Testing.config.record = true` is the programmatic equivalent.) A call with no
 `client:` raises there, rather than quietly replaying the recording it was told
-to refresh. A *request* with no recording raises
-`GraphWeaver::Testing::MissingRecording`, naming the variables it was called
-with and the ones recorded for that same query — what usually differs.
+to refresh; a *request* with no recording raises
+`GraphWeaver::Testing::MissingRecording`, naming the variables it was called with
+and the ones recorded for that same query — what usually differs.
 
-**One entry per request.** The request key is the query, its variables and the
-operation name together, and a cassette holds one entry per key: re-recording a
-request *replaces* its entry, and a request the file hasn't seen appends one. So
-however often `GRAPHWEAVER_RECORD=1` runs, no cassette ends up with two entries
-for the same request.
+**One entry per request.** A cassette is a YAML list of
+`{query, variables, operationName, response}` entries, and the first three
+together are the request key — the request's identity as the server sees it.
+Re-recording a request *replaces* its entry and a request the file hasn't seen
+appends one, so however often `GRAPHWEAVER_RECORD=1` runs, no cassette ends up
+with two entries for the same request.
 
 Editing a query changes the key, so the re-record writes a new entry and the old
 one stays behind — a recording of a request nothing sends any more.
-`cassettes:check` counts those ("1 not sent by any query module", below); the
-way to clear them is to delete the cassette and record it afresh.
+`cassettes:check` counts those ("1 not sent by any query module", below); the way
+to clear them is to delete the cassette and record it afresh.
+
+**Recording under `parallel_tests` is safe.** Writing rewrites the whole file, so
+a recorder re-reads it inside an exclusive lock on a `<cassette>.yml.lock`
+sidecar — a mutex for this process's threads, an `flock` for the other
+processes — and every worker's entries survive. That sidecar is an empty lock
+target: gitignore it, or let it sit; nothing reads it.
 
 ## Has a recording gone stale?
 
@@ -48,16 +52,11 @@ A cassette is the one artifact here recorded from *someone else's* server, and
 none of the other checks can see it drift: `verify` asks whether the generated
 Ruby is fresh, `queries:check` whether a query still validates, `schema:diff`
 whether the server's schema moved. When the recorded *answers* stop fitting the
-structs your schema generated — a field that was `Int!` when you recorded and
-is `String!` now — nothing notices until a spec dies mid-run on a cast error
-naming a struct and nothing else.
-
-```sh
-rake graph_weaver:cassettes:check
-```
-
-It replays every recording through the generated modules — no network — so it
-belongs in the normal PR run beside `verify`, and exits non-zero on drift:
+structs your schema generated — a field that was `Int!` when you recorded and is
+`String!` now — nothing notices until a spec dies mid-run on a cast error naming
+a struct and nothing else. `rake graph_weaver:cassettes:check` replays every
+recording through the generated modules — no network — so it belongs in the
+normal PR run beside `verify`, and exits non-zero on drift:
 
 ```
 spec/cassettes/dashboard.yml: 1 stale (3 checked, 1 not sent by any query module)
@@ -65,17 +64,17 @@ spec/cassettes/dashboard.yml: 1 stale (3 checked, 1 not sent by any query module
     failed to cast response into DashboardQuery::Result::Me::Reviews::Book: Parameter 'price_cents': Can't set …price_cents to 4200 (instance of Integer) - need a String
 ```
 
-A recording is matched to the module that sends its query, so one written by
-hand is skipped and counted rather than guessed at. Checking **none** of them
-fails too: a green run that compared nothing would pass whatever the recordings
-said. The fix is a re-record (`GRAPHWEAVER_RECORD=1`, with a live `client:`) —
-or `rake graph_weaver:generate`, if it was the schema dump that moved first.
+A recording is matched to the module that sends its query, so one written by hand
+is skipped and counted rather than guessed at. Checking **none** of them fails
+too: a green run that compared nothing would pass whatever the recordings said.
+The fix is a re-record (`GRAPHWEAVER_RECORD=1`, with a live `client:`) — or
+`rake graph_weaver:generate`, if it was the schema dump that moved first.
 
 ## Anonymization
 
-Cassettes hold real responses, so scrub them as they're recorded: real data
-never reaches disk, and the caller sees the anonymized response too, so
-assertions written during the recording run still hold on replay.
+Cassettes hold real responses, so scrub them as they're recorded: real data never
+reaches disk, and the caller sees the anonymized response too, so assertions
+written during the recording run still hold on replay.
 
 ```ruby
 GraphWeaver::Testing.configure do |config|
@@ -94,21 +93,21 @@ preserving everything that makes the recording faithful:
 | id *relationships* (same original id → same fake id) | the id values themselves |
 
 **Every plain string goes**, not the PII-shaped ones — nothing here can tell a
-user's name from a product's, so a recorded `"pikachu"` replays as `"name-1"`
-and an assertion pinned to it fails. Leave it off for a public, non-sensitive
-API, where the real values *are* the point of the cassette.
+user's name from a product's, so a recorded `"pikachu"` replays as `"name-1"` and
+an assertion pinned to it fails. Leave it off for a public, non-sensitive API,
+where the real values *are* the point of the cassette.
 
 `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
+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.
+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:
 
@@ -118,20 +117,16 @@ 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:
-
-```sh
-rake graph_weaver:cassettes:anonymize   # every cassette in cassette_dir, in place
-```
-
-Anonymization preserves shape, so an anonymized cassette still passes
-`cassettes:check` — including a custom scalar, whose replacement is the same
-one [`FakeClient`](testing.md#fabricated-data--graphql-fake) would fabricate.
-A scalar registered as *your own* class needs a pin for the type in
+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,
+`rake graph_weaver:cassettes:anonymize` does every cassette in `cassette_dir`, in
+place. Anonymization preserves shape, so an anonymized cassette still passes
+`cassettes:check` — including a custom scalar, whose replacement is the same one
+[`FakeClient`](testing.md#fabricated-data--graphql-fake) would fabricate. A scalar
+registered as *your own* class needs a pin for the type in
 `Testing.config.overrides` (`{ "Money" => "12.00" }` — [pins](testing.md#pins)),
 which the anonymizer reads too; without one, anonymizing refuses rather than
 writing a value the codec can't read back.
@@ -139,6 +134,6 @@ writing a value the codec can't read back.
 ## Cassette or FakeClient?
 
 [FakeClient](testing.md) needs no recording and is the better default for unit
-tests. Reach for a cassette when the *shape* of a real API's answers is the
-point — pagination quirks, which union member came back, where that server puts
-its nulls — and for pinning a regression.
+tests. Reach for a cassette when the *shape* of a real API's answers is the point
+— pagination quirks, which union member came back, where that server puts its
+nulls — and for pinning a regression.

data/docs/editors.md

@@ -1,14 +1,10 @@
 # Editor support: five lines of YAML
 
-Your `.graphql` files are plain GraphQL documents and your schema dump is a
-plain introspection result, so the whole JavaScript GraphQL editor toolchain
-works on a Ruby repo — **with no JS project, no `package.json`, and no `npm
-install`**. It just needs one config file telling it where the two live.
-
-Ruby developers mostly don't know this, which is the only reason it's worth a
-page.
-
-## The file
+Your `.graphql` files are plain GraphQL documents and your schema dump is a plain
+introspection result, so the whole JavaScript GraphQL editor toolchain works on a
+Ruby repo — **with no JS project, no `package.json`, and no `npm install`**. It
+just needs one config file telling it where the two live. Ruby developers mostly
+don't know this, which is the only reason it's worth a page.
 
 ```yaml
 # graphql.config.yml — repo root
@@ -18,58 +14,47 @@ documents:
   - app/graphql/fragments/**/*.{graphql,gql}
 ```
 
-That's the whole setup. The paths are graph_weaver's conventions
-(`GraphWeaver.schema_path`, `queries_paths`, `fragments_paths`) — if you moved
-them, move these to match. Include the fragments directory: an editor
-validating a query that spreads a shared fragment reports `Unknown fragment`
-unless the fragment files are in `documents` too. The generator writes that
-line whether or not you have fragments yet — the directory it names doesn't
-exist until you add one, and a glob matching nothing is fine.
-
-An SDL dump works just as well if you took one (`cache: :graphql`):
-
-```yaml
-schema: app/graphql/schema.graphql
-```
+That's the whole setup, and `rails g graph_weaver:install` writes it. The paths
+are graph_weaver's conventions (`GraphWeaver.schema_path`, `queries_paths`,
+`fragments_paths`) — if you moved them, move these to match. Include the
+fragments directory: an editor validating a query that spreads a shared fragment
+reports `Unknown fragment` unless the fragment files are in `documents` too. The
+generator writes that line whether or not you have fragments yet, and a glob
+matching nothing is fine.
 
 Introspection JSON is read directly — graphql-config ships a JSON loader, so
-`schema.json` needs no conversion step. graph_weaver also writes a
-`graph_weaver` provenance key alongside the introspection result; if some tool
-objects to it, point `schema:` at an SDL dump instead.
+`schema.json` needs no conversion step. An SDL dump works just as well if you
+took one (`cache: :graphql`): point `schema:` at `app/graphql/schema.graphql`.
+graph_weaver also writes a `graph_weaver` provenance key alongside the
+introspection result; if some tool objects to it, use the SDL dump instead.
 
 ## What it buys you
 
-The two editor plugins that read this file:
-
-- **[vscode-graphql](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)**
-  — its README states it **requires** a graphql-config file, which is why
-  nothing works without the YAML above.
-- **The JetBrains GraphQL plugin**, bundled with recent RubyMine, reads the
-  same file.
-
-Either one gives you, inside a `.graphql` file:
+Two editor plugins read this file:
+**[vscode-graphql](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)**,
+whose README states it **requires** a graphql-config file — which is why nothing
+works without the YAML above — and **the JetBrains GraphQL plugin**, bundled with
+recent RubyMine. Either one gives you, inside a `.graphql` file:
 
 - validation as you type — a typo'd field is red before you run anything
 - field and argument autocomplete off the real schema
-- go-to-definition and hover docs into schema types, including the
-  descriptions the API author wrote
+- go-to-definition and hover docs into schema types, including the descriptions
+  the API author wrote
 
 That is the same feedback the generator gives you, one round trip earlier — you
-find the typo while typing the query, not at `rake graph_weaver:generate`.
-
-The same globs also feed the JS CI tools, if you want them (these *do* need
-npm, unlike the editor path):
-[graphql-inspector](https://the-guild.dev/graphql/inspector) `validate` and
-[@graphql-eslint](https://the-guild.dev/graphql/eslint/docs) for lint rules
-over your documents.
+find the typo while typing the query, not at `rake graph_weaver:generate`. The
+same globs also feed the JS CI tools, if you want them (these *do* need npm,
+unlike the editor path): [graphql-inspector](https://the-guild.dev/graphql/inspector)
+`validate` and [@graphql-eslint](https://the-guild.dev/graphql/eslint/docs) for
+lint rules over your documents.
 
 ## What it doesn't buy you
 
 **Nothing links a `.graphql` file to the Ruby it generates.** There is no
-go-to-definition from a query field to its `T::Struct`, no rename that moves
-both, no warning that a struct went unused. The editor plugin understands
-GraphQL and Sorbet understands Ruby, and no tool in any ecosystem bridges the
-two except where documents and types share a single language service.
+go-to-definition from a query field to its `T::Struct`, no rename that moves both,
+no warning that a struct went unused. The editor plugin understands GraphQL and
+Sorbet understands Ruby, and no tool in any ecosystem bridges the two except
+where documents and types share a single language service.
 
 So the division of labour is: