graph_weaver 0.6.1 → 0.7.1

data/docs/alternatives.md

@@ -0,0 +1,195 @@
+# Alternatives
+
+Why another Ruby GraphQL client, what else exists, and where each one wins.
+Read it before adopting — including the last section, which is where this gem
+loses.
+
+*Figures checked 2026-09-12. Every claim carries its source in an HTML comment
+beside it; a maintainer re-checking this page should follow those, not trust the
+prose.*
+
+## Why another one
+
+Ruby has **one** real GraphQL client — GitHub's `graphql-client` — and the two
+maintained alternatives are wrappers around it.<!-- graphlient.gemspec deps: faraday ~>2.0, graphql-client; artemis.gemspec deps include graphql-client >= 0.13.0 — https://rubygems.org/api/v1/gems/graphlient.json, https://rubygems.org/api/v1/gems/artemis.json -->
+All three share one design: the result object is built at runtime by
+metaprogramming against an introspected schema, so a field you misspelled is a
+`NoMethodError` on a production request rather than a red build.<!-- graphql-client lib/graphql/client/schema/object_type.rb:231-266 — method_missing raises UnimplementedFieldError/UnfetchedFieldError at runtime; a camelCase typo re-raises plain NoMethodError at :248-250 -->
+And none of them ship anything to test with.<!-- graphql-client: no fakes/stubs/fixtures anywhere in lib/, no testing guide among its 14 guides — https://github.com/github-community-projects/graphql-client/tree/master/guides -->
+
+GraphWeaver makes a different structural bet: **the schema is known at
+generation time**, so result types can be real files on disk that `srb tc`
+reads, and the same knowledge that makes them exact is what lets the gem
+fabricate them for your tests. That second half is the part every code generator
+in every language skips — and it is the reason precise types usually feel
+expensive.
+
+The honest counter: if your app doesn't use Sorbet, most of that value
+evaporates, and [graphlient](#graphlient) is the better answer.
+
+## The table
+
+`graphql-ruby` isn't a column because it isn't a client — see
+[graphql-ruby alone](#graphql-ruby-alone). "Hand-rolled" is `Net::HTTP` or
+Faraday plus a query string and `response["data"]["..."]`, which is what most
+vendor SDKs actually do.
+
+| | **graph_weaver** | **graphql-client** | **graphlient** | **artemis** | **hand-rolled** |
+|---|---|---|---|---|---|
+| **Query lives in** | a `.graphql` file, one operation each<!-- README.md; DECISIONS.md "Directories organize queries" --> | a heredoc assigned to a Ruby constant (enforced)<!-- lib/graphql/client.rb:345-347 raises DynamicQueryError when definition.name is nil --> | a heredoc, a Ruby block DSL, or `parse`<!-- https://github.com/ashkan18/graphlient#usage ; lib/graphlient/query/serializer.rb --> | a `.graphql` file under `app/operations`<!-- https://github.com/yuki24/artemis#the-convention --> | a string in your code |
+| **A result is** | a checked-in nested `T::Struct`<!-- README.md; lib/graph_weaver/result_struct.rb --> | an anonymous class, readers per selected field<!-- lib/graphql/client/schema/object_type.rb:10-22, 56-60 --> | the same (it returns graphql-client's `Response`)<!-- lib/graphlient/client.rb:41 --> | the same<!-- artemis lib/artemis/client.rb #execute delegates to client.query --> | a `Hash` |
+| **A typo is caught** | at `srb tc`, before you run it | at runtime, on the request<!-- object_type.rb:243-266 --> | at runtime | at runtime | never |
+| **Schema needed** | at codegen time: live class, introspection dump, SDL, or supergraph<!-- README.md; lib/graph_weaver/schema_loader.rb --> | at boot: dump recommended; SDL support merged but unreleased<!-- README.md:34-42; https://github.com/github-community-projects/graphql-client/pull/60 merged 2025-12-06, not in 0.26.0 --> | at runtime: introspects over HTTP lazily unless you pass `schema_path`<!-- lib/graphlient/schema.rb:16; lib/graphlient/client.rb:76 --> | a checked-in dump per service<!-- lib/artemis/railtie.rb schema_path vendor/graphql/schema/<service>.json --> | none |
+| **Codegen** | yes — you check the Ruby in | none, all runtime metaprogramming<!-- lib/graphql/client/schema.rb:68-81 --> | none | none | none |
+| **Typing** | Sorbet `# typed: strict`, per query<!-- README.md --> | none shipped; Tapioca PR stalled since 2024-11, and schema-wide not per-operation<!-- https://github.com/github-community-projects/graphql-client/pull/7 — open, mergeable_state blocked, last touched 2024-11-07 --> | none<!-- no .rbs/.rbi/sig in the gem --> | none | none |
+| **Testing** | schema-driven fakes, pinning, failure simulation, cassettes<!-- docs/testing.md; lib/graph_weaver/rspec.rb; lib/graph_weaver/testing/ --> | nothing ships<!-- no stub/fake/fixture in lib/ --> | documented WebMock patterns only<!-- https://github.com/ashkan18/graphlient#testing-with-graphlient-and-rspec --> | `stub_graphql` + YAML fixtures, unvalidated against the schema<!-- lib/artemis/test_helper.rb; lib/artemis/adapters/test_adapter.rb returns fixtures verbatim --> | WebMock |
+| **Federation** | plans and runs a supergraph in-process<!-- docs/federation.md; lib/graph_weaver/federation.rb --> | none; open crash against federated routers<!-- https://github.com/github-community-projects/graphql-client/issues/78 open since 2026-01-15 --> | none | none | none |
+| **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.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
+
+**Where it shines.** It is GitHub's, it has a decade of production use, and 94M
+downloads means someone has hit your problem before you. The duck-typed
+`execute:` slot is genuinely good design — point it at a graphql-ruby schema and
+queries run in-process with no socket.<!-- https://github.com/github-community-projects/graphql-client/blob/master/guides/local-queries.md -->
+It ships two RuboCop cops, including `GraphQL/Overfetch`, which nobody else
+has.<!-- lib/rubocop/cop/graphql/ in the unpacked gem -->
+
+**Where it gaps.** Custom scalars don't deserialize when the schema came from a
+dump — the path its own README recommends — and the suggested workaround is
+monkey-patching `GraphQL::Schema::BUILT_IN_TYPES`; the issue has been open since
+February 2024.<!-- https://github.com/github-community-projects/graphql-client/issues/17 --> Network
+errors are discarded: a 403 surfaces as `KeyError: key not found: "data"`.<!-- https://github.com/github-community-projects/graphql-client/issues/67 open since 2025-04-11 -->
+Fragments enforce Relay-style data masking, so a field another fragment fetched
+raises even though the value is right there in the response — and users file
+issues asking for plain reuse.<!-- object_type.rb:161-168, 261-264; https://github.com/github-community-projects/graphql-client/issues/76 -->
+Its CI matrix stops at Ruby 3.2 and Rails 7.1.<!-- https://github.com/github-community-projects/graphql-client/blob/master/.github/workflows/ci.yml -->
+Nine issues and seven PRs are open, several waiting on a maintainer to approve a
+CI run.<!-- gh api search/issues, repo:github-community-projects/graphql-client, 2026-09-12 -->
+
+**Pick it over graph_weaver when** institutional safety outweighs static types,
+or when you need data masking as a feature rather than a constraint.
+
+## graphlient
+
+**Where it shines.** Quietly the healthiest Ruby client: 0.9.0 shipped
+2026-08-02, more recently than graphql-client itself, adding DSL fragments,
+directives and scalar registration.<!-- https://github.com/ashkan18/graphlient/blob/master/CHANGELOG.md -->
+It fixes the failure everyone hits with its substrate — it raises a real,
+rescuable error hierarchy instead of handing you a half-populated response.<!-- lib/graphlient/errors/ --> Faraday
+means your existing middleware just works.
+
+**Where it gaps.** It is a wrapper, so it inherits graphql-client's result
+model, its fragment isolation, and its untyped everything — its own README
+offers `to_query_string` as "the escape hatch if you want to replace the
+graphql-client dependency entirely".<!-- https://github.com/ashkan18/graphlient#readme, 0.9.0 -->
+Read and write timeouts default to nil, i.e. none.<!-- README config table; lib/graphlient/adapters/http/adapter.rb:33-40 -->
+No Rails integration, no field aliasing, and 18 open issues, the most-reacted
+dating to 2017.<!-- https://github.com/ashkan18/graphlient/issues/10 ; gh api repos/ashkan18/graphlient -->
+
+**Pick it over graph_weaver when** you want to call an API without thinking
+about it. For that job graph_weaver is over-engineered, and this is the right
+answer.
+
+## artemis
+
+**Where it shines.** The best Rails story of the three: `rails g
+artemis:install` writes the client, the config and the schema dump; `.graphql`
+files map to methods by convention; `before_execute`/`after_execute` are real
+hooks; and it has the only shipped test harness among the alternatives —
+`stub_graphql(Artsy, :artist).to_return(:yayoi_kusama)` against YAML
+fixtures.<!-- lib/artemis/test_helper.rb; https://github.com/yuki24/artemis#testing -->
+It also batches, via `Client.multiplex`.<!-- lib/artemis/client.rb .multiplex/MultiplexQueue -->
+
+**Where it gaps.** Fixtures are returned verbatim — nothing checks them against
+the schema or the query's selection set, so a fixture can drift from reality and
+stay green.<!-- lib/artemis/adapters/test_adapter.rb#execute -->
+Its reloader and production preload are both gated on *not* using Zeitwerk,
+which every Rails 7+ app does, so the README's preloading claim no longer
+applies.<!-- lib/artemis/railtie.rb — graphql.client.set_reloader and graphql.client.preload both gated on not_on_zeitwerk -->
+Last release August 2024; Rails 8 support exists only on `main`, and there have
+been no commits since December 2025.<!-- gh api repos/yuki24/artemis/compare/v1.1.0...main ; last commit 8b3d76a 2025-12-04 -->
+
+**Pick it over graph_weaver when** you want convention-over-configuration Rails
+ergonomics and don't need types.
+
+## graphql-ruby alone
+
+`graphql-ruby` is a **server** library and ships no HTTP client at all — its
+only three runtime dependencies are `base64`, `fiber-storage` and `logger`, and
+the only `Net::HTTP` call in the gem fetches a checksum for graphql-pro.<!-- gem spec graphql-2.6.10.gem dependencies; lib/graphql/rake_task/validate.rb:38-44 -->
+The thing called "client" in its docs is
+[JavaScript](https://graphql-ruby.org/javascript_client/overview).
+
+What it does give a client author is the substrate everyone here builds on:
+[`GraphQL.parse`](https://graphql-ruby.org/api-doc/2.6.10/GraphQL.html),
+[`GraphQL::Schema.from_definition`](https://graphql-ruby.org/schema/sdl.html)
+and `from_introspection`, and `GraphQL::StaticValidation::Validator` for
+checking a document against a schema.<!-- lib/graphql.rb:49; lib/graphql/schema.rb:105,115; lib/graphql/static_validation/validator.rb:11-18 -->
+GraphWeaver uses exactly these — it is a code generator on top of graphql-ruby,
+not a reimplementation of it.
+
+**Subscriptions are server-side only** across the whole ecosystem: graphql-ruby
+delivers them over ActionCable and every documented consumer is
+JavaScript,<!-- https://graphql-ruby.org/subscriptions/action_cable_implementation — "See client usage for: Apollo Client, Relay Modern, GraphiQL" -->
+and no Ruby gem consumes GraphQL subscriptions over websockets.<!-- rubygems search graphql+websocket, graphql-ws, subscriptions-transport-ws all return 0 results, 2026-09-12 -->
+Nobody in Ruby has this, GraphWeaver included.
+
+## Hand-rolled HTTP — the real incumbent
+
+Most Ruby code talking to a GraphQL API isn't using a client library. It POSTs a
+string and reads a hash, and that includes the vendors' own SDKs.
+
+Shopify is the sharpest example. `shopify_api` v10 **removed** graphql-client,
+saying so in its breaking-changes doc — "There is no need to dump the schema to
+a local JSON file before using it anymore" — and the migration example replaces
+`result.data.shop.name` with `response.body["data"]["shop"]["name"]`.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/BREAKING_CHANGES_FOR_V10.md:3,115,140-159 -->
+The current gemspec declares `httparty`, `oj` and `sorbet-runtime` and no
+`graphql` at all.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/shopify_api.gemspec:35-46 -->
+The gem is `# typed: strict` throughout — and the GraphQL payload is typed
+`T.any(T::Hash[String, T.untyped], String, OpenStruct)`.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_response.rb#L15-L16 -->
+A Sorbet shop, shipping a Sorbet-typed SDK, with untyped GraphQL. Braintree does
+the same thing without the Sorbet.<!-- https://github.com/braintree/braintree_ruby/blob/master/lib/braintree/graphql_client.rb#L13-L26 -->
+
+**Where it shines.** Zero dependencies, zero build step, nothing to learn, and
+it never gets in your way. For three queries against a stable API this is
+genuinely the correct engineering call.
+
+**Where it gaps.** Nothing validates the query, nothing knows the schema
+changed, every response is `T.untyped`, and the error handling is a 40-line
+layer you write once per project. The cost is invisible until the schema moves.
+
+**Pick it over graph_weaver when** you have a handful of queries and no
+appetite for a build step.
+
+## Where graph_weaver loses
+
+Said plainly.
+
+- **Sorbet is a hard dependency.** `sorbet-runtime` is a runtime
+  dependency,<!-- graph_weaver.gemspec: s.add_dependency "sorbet-runtime" --> and
+  the payoff — a typo caught before you run — needs `srb tc` in your build. No
+  RBS output. If Sorbet isn't in your stack, you're carrying the cost of
+  generated code for a fraction of the benefit.
+- **Codegen is a build step.** You check generated Ruby in, and regenerate on
+  every gem upgrade, because any release can change what codegen emits. `rake
+  graph_weaver:verify` exists precisely because that step is easy to skip. The
+  alternatives have no build step at all.
+- **No subscriptions.** A subscription document is refused outright:
+  `GraphWeaver::Error: unsupported operation: subscription`.<!-- lib/graph_weaver/internal/selection.rb:48 --> Nobody
+  in Ruby has this, but that doesn't make it present here.
+- **No `@defer`, no file uploads, no persisted queries, no batching.** artemis
+  has multiplex batching;<!-- lib/artemis/client.rb .multiplex --> this gem has
+  none of the four.
+- **One author, and it's new.** First commit July 2026, 4 stars, pre-1.0, and
+  about 30 breaking-change notes in the changelog so far.<!-- gh api repos/dpep/graph_weaver created_at 2026-07-07, stargazers_count 4; grep -c -i breaking CHANGELOG.md -->
+  Codegen is unforgiving and there is a lot of surface to get wrong.
+  `verify` mitigates drift; nothing mitigates the maintainer. "No static types"
+  is a cost many teams will rationally accept over that.
+
+If you read that list and none of it stops you, the thing you get in exchange is
+in [getting started](getting_started.md).

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,9 +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.** 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.
+
+**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?
 
@@ -37,34 +52,29 @@ 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)
-  DashboardQuery {"id" => "b1"}
+  DashboardQuery {"id":"b1"}
     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|
@@ -82,17 +92,22 @@ preserving everything that makes the recording faithful:
 | enums, booleans, `__typename` | numbers, dates |
 | 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.
+
 `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:
 
@@ -102,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.
@@ -123,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: