graph_weaver 0.4.6 → 0.5.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.4.6)
+    graph_weaver (0.5.1)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -42,7 +42,7 @@ GEM
     google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    graphql (2.6.7)
+    graphql (2.6.10)
       base64
       fiber-storage
       logger
@@ -54,7 +54,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.20.0)
+    json (2.21.2)
     logger (1.7.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
@@ -99,16 +99,16 @@ GEM
     rubydex (0.2.7-arm64-darwin)
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
-    simplecov (1.0.3)
-    sorbet (0.6.13365)
-      sorbet-static (= 0.6.13365)
-    sorbet-runtime (0.6.13365)
-    sorbet-static (0.6.13365-aarch64-linux)
-    sorbet-static (0.6.13365-universal-darwin)
-    sorbet-static (0.6.13365-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13365)
-      sorbet (= 0.6.13365)
-      sorbet-runtime (= 0.6.13365)
+    simplecov (1.1.1)
+    sorbet (0.6.13454)
+      sorbet-static (= 0.6.13454)
+    sorbet-runtime (0.6.13454)
+    sorbet-static (0.6.13454-aarch64-linux)
+    sorbet-static (0.6.13454-universal-darwin)
+    sorbet-static (0.6.13454-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13454)
+      sorbet (= 0.6.13454)
+      sorbet-runtime (= 0.6.13454)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -176,12 +176,12 @@ 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.4.6)
-  graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
+  graph_weaver (0.5.1)
+  graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
-  json (2.20.0) sha256=9362bc6e55a952b056abf9167cf053358181c904cb70cd6eee0808ea830fc32b
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
@@ -206,13 +206,13 @@ CHECKSUMS
   rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
-  simplecov (1.0.3) sha256=38ef0514f16ae7562f0d0f4df02610071115103d301b6de7dacbcc000082e39b
-  sorbet (0.6.13365) sha256=3a642fe7afb031ad670c2e6161b3d5492dd67705cbcafb132c9e87ded7ccf676
-  sorbet-runtime (0.6.13365) sha256=0657cddfd2319c9695a0b6e13aa7a7c7b093149e5589448c03b911adf1e243cb
-  sorbet-static (0.6.13365-aarch64-linux) sha256=14b7bf3a227ee102c119763158618bc6b677994cebfda2705b94bca56e4c25e1
-  sorbet-static (0.6.13365-universal-darwin) sha256=0f6033dde8a0dc7b7e72ada3ce73e1e3097843be16e473fb8bb2b8fb6199212b
-  sorbet-static (0.6.13365-x86_64-linux) sha256=f94daadcae55f2e0f7797f8fdc8a250c89ec62e11f2d41905ed6fb1e60ff708e
-  sorbet-static-and-runtime (0.6.13365) sha256=9768c114686f7cac0a6f2e222db4213887d294df6059802242ba6e4e08adbad9
+  simplecov (1.1.1) sha256=25825ef13f0b2e74694d769817dad6ab8e90131dabdaa666e522fea105521e78
+  sorbet (0.6.13454) sha256=3273dda082b8aa5ecf79b7675e2b79127f202a45370d881124af3af19a3c2b35
+  sorbet-runtime (0.6.13454) sha256=b9441ae4bd265f51861c54240e8c5888f6355e3284885b21c5154b184e791d80
+  sorbet-static (0.6.13454-aarch64-linux) sha256=e09dd1e6cd7e63b3fb6c8c9c6785eeb55a6c4afecb0f932538ee4401b4552632
+  sorbet-static (0.6.13454-universal-darwin) sha256=6ac0cf10ae2b4e0e9ecabb886f9be739046424dc35d100e7888c8538a223f93a
+  sorbet-static (0.6.13454-x86_64-linux) sha256=569c52ea926e514ebfdc64825f65cd188b7aba5c1b480cc26e1870fd53d5e2c0
+  sorbet-static-and-runtime (0.6.13454) sha256=defc00684a6f8bd498bb70a4541f293b9232938a776137946247cba4baed3d20
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/README.md

@@ -3,14 +3,19 @@ GraphWeaver
 ![Gem](https://img.shields.io/gem/dt/graph_weaver?style=plastic)
 [![codecov](https://codecov.io/gh/dpep/graph_weaver/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/graph_weaver)
 
-A typed GraphQL client for Ruby, built for federation, extensibility, Sorbet, and testing.
+**Your `.graphql` files, compiled into Sorbet types — and the fakes to test them.**
 
-GraphWeaver generates `# typed: strict` Ruby from your queries: nested `T::Struct`s, casting code, and a typed `execute` — so `srb tc` sees the exact shape of every query result, and a typo'd field is a static error, not a runtime surprise.
+GraphWeaver is graphql-codegen for Ruby. Write a query as a `.graphql` file and it
+generates checked-in `# typed: strict` Ruby — nested `T::Struct`s, casting, a typed
+`execute` — so `srb tc` knows the exact shape of every result. The schema can be a
+live graphql-ruby class, an introspection dump, SDL, or an Apollo supergraph;
+at runtime the only dependencies are `graphql` and `sorbet-runtime`.
 
 ```graphql
-# queries/person.graphql
+# app/graphql/queries/person.graphql
 query($id: ID!) {
   person(id: $id) {
+    id
     name
     birthday
     pets { name }
@@ -18,132 +23,146 @@ query($id: ID!) {
 }
 ```
 
+`rake graph_weaver:generate` turns that file into a `PersonQuery` module, and what
+comes back is a struct rather than a Hash you have to trust:
+
 ```ruby
-result = PersonQuery.execute!(id: "1")   # typed result, or raises on errors (execute returns an envelope)
+result = PersonQuery.execute!(id: "1")   # or #execute, for the Response envelope
 
-result.person&.name       # => "Daniel" (typed String)
-result.person&.birthday   # => Date (custom scalars deserialize)
-result.person&.nmae       # => srb tc: Method `nmae` does not exist
-```
+result.person&.name                # => "Daniel"
+result.person&.birthday            # => #<Date: 1990-06-15>   custom scalars deserialize
+result.person&.pets&.map(&:name)   # => ["Shelby", "Brownie"]
 
-New here? The **[getting started](docs/getting_started.md)** guide walks the
-production setup end to end — initializer, codegen, fakes, CI. Or run the
-**[examples](examples/)**, smallest first: `examples/countries.rb` (public
-API, no auth, all dynamic), `examples/rick_and_morty.rb` (filtering,
-pagination, a block-built type helper), and `examples/github/run.rb`
-(auth + checked-in generated modules; it stars this repo ⭐ and introduces
-you to your fellow stargazers).
+result.person&.nmae
+# srb tc: Method `nmae` does not exist on `PersonQuery::Result::Person`
+#         Did you mean `name`?
+```
 
-#### Features
+`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.
 
-- **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
-- **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), **custom scalars** (pluggable registry), `@skip`/`@include` nullability
-- **Any schema source**: live schema class, introspection JSON, or SDL — including Apollo Federation supergraph SDL; introspect live endpoints with caching
-- **Any transport**: in-process schema execution, the zero-dependency HTTP executor, or Faraday with your own middleware — plus a composable `Retry` (exponential/linear/custom backoff, jitter, retry-by-error-class or GraphQL code) — swap per call with `executor:`
-- **Structured errors**: a typed response envelope (partial data + extensions survive), an error hierarchy split by failure site, field-level reports with entity ids, and `schema_stale?` detection — every error dual-surfaced as a human message plus JSON-ready `#to_h`
-- **Testing built in**: schema-correct fakes, failure simulation, record/replay cassettes with anonymization, rspec integration
-- **Dynamic mode** for development: `GraphWeaver.parse(...)` generates and evals on the fly, no build step
+Typed structs are the part every generator gets right. What decides whether you're
+still happy six months in is everything around them.
 
-#### Usage
+## Precise types are expensive to fake, so it fakes them for you
 
-Three ways to run a query — pick by context:
+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
+fabricator. One line in the spec helper:
 
-| Context | Use |
-|---------|-----|
-| Production | checked-in codegen (`rake graph_weaver:generate`) — reviewed, `srb tc`-checked |
-| Development, consoles | `client.parse` / `client.load_queries!` — no build step |
-| Scripts, one-offs | `client.execute!` — no module at all |
+```ruby
+require "graph_weaver/rspec"
+```
 
-The production path assembled is the [getting started](docs/getting_started.md);
-the pieces:
+then one tag says what an example runs against:
 
 ```ruby
-require "graph_weaver"
-
-# a client for one server: transport (Faraday when loaded), auth, and a
-# lazily introspected schema. The first argument is a url or any schema
-# source — a live schema class, or a .json/.graphql dump
-api = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"], cache: true)
-
-# make it the app default — generated modules execute through it
-GraphWeaver.client = api
-
-# generate checked-in typed modules (rake graph_weaver:generate, or directly)
-source = GraphWeaver::Codegen.generate(
-  schema: api.schema,
-  query: File.read("queries/person.graphql"),
-  module_name: "PersonQuery",
-)
-File.write("app/queries/person_query.rb", source)
-
-# at runtime
-PersonQuery.execute(id: "1")                        # via GraphWeaver.client
-PersonQuery.execute(other_client, id: "1")          # or per call
+it "shows the profile", graphql: :fake do
+  person = PersonQuery.execute!(id: "1").person
+
+  person.name       # => "Shakita Stark"      fabricated from your schema
+  person.birthday   # => #<Date: 2024-12-16>  custom scalars included
+  person.pets.size  # => 2
+end
 ```
 
-Module names derive from the operation name (`query GetPerson` →
-`GetPerson`) or, for `parse` on a `.graphql` file, from the file name;
-pass `module_name:`/`name:` to override. Pass `client:` (a constant) to
-bake a default client into the generated module. Prefer Faraday? It's
-opt-in (`gem "faraday"`), and the client picks it up when loaded —
-middleware blocks and ready connections in [transports](docs/transports.md).
+No fixture, no stub, no HTTP — and the values are seeded from rspec's own seed, so
+`--seed 4242` hands back that same person and a failure reproduces. The tag also
+picks a *real* client when you want one: `:in_process` runs your resolvers,
+`:router` runs them across a federated graph. Field-level failure simulation and
+record/replay cassettes with anonymization are in [testing](docs/testing.md).
 
-In development, skip the build step entirely — modules from `client.parse`
-carry the client's transport, no global wiring needed:
+## Federation without a gateway
 
-```ruby
-# parse a query into a typed module on the fly — a .graphql path or a raw string
-PersonQuery = api.parse("queries/person.graphql")
-PersonQuery.execute(id: "1")
+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:
+
+```
+$ bundle exec examples/federation.rb
+#<GraphWeaver::Testing::Router subgraphs=["accounts", "products", "reviews"]>
 
-# or every query file at once (queries_path convention), named like generation would
-api.load_queries!
+dpep reviewed 2 products:
+  Table ($899) — Love it
+  Couch ($1299) — Too expensive
 
-# or one-shot, no module at all — variables are plain kwargs
-api.execute!("query($id: ID!) { person(id: $id) { name } }", id: "1")
+fetches:
+  → accounts  root fields
+  → reviews   _entities × 1 User
+  → products  _entities × 2 Product
 ```
 
+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 72 queries identical, 2 refused, 0 wrong
+([`spec/integration/router_parity_spec.rb`](spec/integration/router_parity_spec.rb)).
+See [federation](docs/federation.md).
 
-#### Dig deeper
+## The schema keeps itself honest
 
-- **[Getting started](docs/getting_started.md)** — the production path in Rails,
-  step by step: initializer, rake tasks, fakes, CI, Sorbet or not
-- **[Generated modules](docs/generated_modules.md)** — module anatomy, typed
-  variables (enums, input objects), fragments/unions/interfaces,
-  `@skip`/`@include`, naming, clients, dynamic mode
-- **[Against a real API](docs/real_world.md)** — the exploratory tour:
-  introspect a live endpoint (GitHub end to end), dynamic mode, schema caching
-- **[Federation](docs/federation.md)** — Apollo Federation: supergraph vs API
-  schema, feeding weaver a composed graph, the `@inaccessible` caveat
-- **[Transports](docs/transports.md)** — clients, the execute contract,
-  Faraday, retries and backoff
-- **[Custom scalars](docs/scalars.md)** — the registry: codec inference,
-  requires, input coercion
-- **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy,
-  field-level reports with entity ids, stale-schema detection
-- **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger:
-  wire traffic at debug, introspection/cache/codegen at info, errors at warn
-- **[Testing](docs/testing.md)** — schema-correct fakes, failure simulation,
-  rspec integration
-- **[Cassettes](docs/cassettes.md)** — capture and replay real API
-  responses; anonymized recording (`GRAPHWEAVER_RECORD=1`, rake tasks)
+The lifecycle is rake tasks, not a CI pipeline you assemble yourself:
+`schema:refresh` re-introspects the committed dump, `schema:diff` fails when the
+server has drifted, `queries:check` names the queries that drift broke and where,
+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).
 
-----
-## Installation
+## Start here
 
 ```ruby
 # Gemfile
 gem "graph_weaver"
 ```
 
-or
+In Rails, setup is then one command:
 
 ```sh
-gem install graph_weaver
+rails g graph_weaver:install https://api.example.com/graphql
 ```
 
+which writes the initializer, the `app/graphql` layout, the editor config and the
+schema dump. **[Getting started](docs/getting_started.md)** walks the production
+setup end to end. Or skip the build step entirely 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
+federated graph above.
+
+#### 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
+- **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
+
+#### Dig deeper
+
+- **[Getting started](docs/getting_started.md)** — the production path in Rails, step by step
+- **[Generated modules](docs/generated_modules.md)** — module anatomy, typed variables, fragments/unions/interfaces, naming, clients, dynamic mode
+- **[Testing](docs/testing.md)** — fakes, failure simulation, the rspec tags
+- **[Federation](docs/federation.md)** — supergraph vs API schema, the local router, what it refuses
+- **[Transports](docs/transports.md)** — the execute contract, Faraday, retries and backoff
+- **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy, field-level reports
+- **[Custom scalars](docs/scalars.md)** — the registry: codec inference, requires, input coercion
+- **[Cassettes](docs/cassettes.md)** — capture and replay real responses, anonymized
+- **[Editor support](docs/editors.md)** — five lines of YAML for schema autocomplete in `.graphql` files, no JS project
+- **[Against a real API](docs/real_world.md)** — introspecting a live endpoint, GitHub end to end
+- **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger
+
 ----
 ## Development
 
 - `make check` — regenerate spec fixtures, run specs, typecheck
-- `make integration` — one-off checks against the live GitHub and Countries APIs
+- `make integration` — one-off checks against live APIs (GitHub needs a token) and a federation gateway (needs node)

data/docs/cassettes.md

@@ -1,40 +1,80 @@
 # 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 file of `{query, variables, response}`
-entries, matched on the normalized query + variables.
+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.
 
-## The workflow
+`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.
 
 ```ruby
-# spec: replay when the cassette exists, record against `live` when not
-cassette = GraphWeaver::Testing::Cassette.use("github", client: live)
-result = RepoQuery.execute!(cassette, owner: "dpep", name: "graph_weaver")
+client = GraphWeaver::Testing.cassette("github", client: live)
+result = RepoQuery.execute!(client:, owner: "dpep", name: "graph_weaver")
 ```
 
-1. **Record** — first run hits the live API and writes
-   `spec/cassettes/github.yml` (`Testing.config.cassette_dir` resolves bare
-   names).
-2. **Anonymize** — cassettes hold real data; scrub before committing (below).
-3. **Commit** — tests now run offline, fast, deterministic.
-4. **Re-record** when the API's real behavior changes:
+That first run writes `spec/cassettes/github.yml` (`Testing.config.cassette_dir`
+resolves bare names). Commit it — with anonymization on (below), since
+recordings hold real data — and the suite runs offline from then on. Re-record
+when the API's real behavior changes:
 
-   ```sh
-   GRAPHWEAVER_RECORD=1 bundle exec rspec   # every Cassette.use records afresh
-   ```
+```sh
+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.
+
+## Has a recording gone stale?
+
+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:
 
-   (`Testing.config.record = true` is the programmatic equivalent.)
+```
+spec/cassettes/dashboard.yml: 1 stale (3 checked, 1 not sent by any query module)
+  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
+```
 
-Replaying an unrecorded request raises `MissingRecording` with the query
-and the path — no silent fabrication.
+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
 
-Anonymizing rewrites recorded values through the same engine
-[FakeClient](testing.md) uses, while preserving everything that makes
-the recording faithful:
+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|
+  config.schema = MySchema
+  config.anonymize = true
+end
+```
+
+Values are rewritten through the same engine [FakeClient](testing.md) uses,
+preserving everything that makes the recording faithful:
 
 | preserved | replaced |
 |-----------|----------|
@@ -42,35 +82,42 @@ the recording faithful:
 | enums, booleans, `__typename` | numbers, dates |
 | id *relationships* (same original id → same fake id) | the id values themselves |
 
-Three ways to run it:
+`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.
 
-```ruby
-# 1. as recordings happen — assertions you write against the recording
-#    run hold on replay, and real data never touches disk
-GraphWeaver::Testing.configure do |config|
-  config.schema = MySchema
-  config.anonymize = true
-end
+**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:
 
-# 2. after the fact, per cassette
-GraphWeaver::Testing::Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
 ```
+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:
 
 ```sh
-# 3. the whole cassette_dir at once
-rake graph_weaver:cassettes:anonymize
+rake graph_weaver:cassettes:anonymize   # every cassette in cassette_dir, in place
 ```
 
-Anonymization 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; don't record with secret
-variables.
+Anonymization preserves shape, so an anonymized cassette still passes
+`cassettes:check`.
 
-## When to use what
+## Cassette or FakeClient?
 
-- **FakeClient** — no recording needed; schema-correct random data.
-  Best default for unit tests.
-- **Cassettes** — real response *shapes* from a real API (pagination
-  quirks, actual union members, servers' null habits). Best for
-  integration-ish tests and regression pinning.
-- **Anonymized cassettes** — cassette fidelity, committable without PII.
+[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.

data/docs/editors.md

@@ -0,0 +1,82 @@
+# 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
+
+```yaml
+# graphql.config.yml — repo root
+schema: app/graphql/schema.json
+documents:
+  - app/graphql/queries/**/*.{graphql,gql}
+  - 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.
+
+An SDL dump works just as well if you took one (`cache: :graphql`):
+
+```yaml
+schema: app/graphql/schema.graphql
+```
+
+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.
+
+## 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:
+
+- 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
+
+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.
+
+## 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.
+
+So the division of labour is:
+
+| Question | Answered by |
+|---|---|
+| Is this query valid, right now, as I type it? | the editor plugin |
+| Do the result types match the query? | `rake graph_weaver:generate` + `srb tc` |
+| Is my checked-in Ruby stale? | `rake graph_weaver:verify` |
+| Did the server break my queries? | `rake graph_weaver:queries:check` |
+
+The last two are the Ruby-side answers, and they need no JS at all — see
+[getting started](getting_started.md#5-verify-in-ci).