graph_weaver 0.4.6 → 0.5.0

data/docs/cassettes.md

@@ -1,76 +1,103 @@
 # 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.)
+(`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.
 
-Replaying an unrecorded request raises `MissingRecording` with the query
-and the path — no silent fabrication.
+## Has a recording gone stale?
 
-## Anonymization
+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.
 
-Anonymizing rewrites recorded values through the same engine
-[FakeClient](testing.md) uses, while preserving everything that makes
-the recording faithful:
+```sh
+rake graph_weaver:cassettes:check
+```
 
-| preserved | replaced |
-|-----------|----------|
-| shape: keys, list lengths, null positions | strings (semantically: emails look like emails) |
-| enums, booleans, `__typename` | numbers, dates |
-| id *relationships* (same original id → same fake id) | the id values themselves |
+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:
+
+```
+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
+```
 
-Three ways to run it:
+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.
 
 ```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
-
-# 2. after the fact, per cassette
-GraphWeaver::Testing::Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
 ```
 
+Values are rewritten through the same engine [FakeClient](testing.md) uses,
+preserving everything that makes the recording faithful:
+
+| preserved | replaced |
+|-----------|----------|
+| shape: keys, list lengths, null positions | strings (semantically: emails look like emails) |
+| enums, booleans, `__typename` | numbers, dates |
+| id *relationships* (same original id → same fake id) | the id values themselves |
+
+It needs the schema — it walks each recorded query's selections to know which
+values are enums, dates, ids. Variables are NOT anonymized: they're the replay
+matching key, so don't record with secret variables.
+
+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).

data/docs/errors.md

@@ -11,6 +11,7 @@ response = PersonQuery.execute(id: "1")   # => GraphWeaver::Response[Result]
 response.data           # T.nilable(Result) — typed, present even on partial success
 response.errors         # Array[GraphWeaver::GraphQLError]
 response.errors?        # any top-level errors?
+response.success?       # the same question the other way round
 response.extensions     # { "cost" => … } — rides on success too
 response.data!          # the Result, or raise GraphWeaver::QueryError
 ```
@@ -22,17 +23,27 @@ Every `GraphQLError` exposes `#message`, `#locations`, `#path`, `#extensions`,
 and `#code` (`extensions["code"]`) — match on the **code**, not the message
 string (`response.errors.first.code == "THROTTLED"`).
 
-Everything GraphWeaver raises descends from `GraphWeaver::Error`, split by where
-it failed:
+Everything GraphWeaver *concludes* descends from `GraphWeaver::Error` — a
+transport failure, a rejected query, a response that wouldn't cast, a plan the
+[local router](federation.md) refused, a subgraph map that doesn't add up. The
+subclass says where it failed:
 
 | Class | When |
 |-------|------|
 | `TransportError` | never reached the server — DNS, connection refused, TLS, timeout |
-| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
-| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
+| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body`, `#headers`, `#retry_after`, `#throttled?` |
+| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes`, `#throttled?` |
 | `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
-| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field — `#field`, `#struct` |
+| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#field`, `#struct` |
 | `ValidationError` | build time: the query didn't validate against the schema |
+| `ConfigurationError` | setup judged against your schema — which Ruby schema serves which subgraph (`Testing::Router`, `federation:diff`) |
+| `Testing::Unplannable` | the local test router won't plan this operation — `#category`, `#detail` |
+
+An argument that is wrong *on its face* raises a plain `ArgumentError` instead
+(`pool_size: must be >= 1`, `cast: must be a Symbol, Proc, :itself, or nil`),
+like any Ruby method — a bug at the call site, not a condition to rescue. The
+line is whether the library had to read your schema to reach the verdict: it
+did for `ConfigurationError`, which is why a spec helper can rescue that one.
 
 ```ruby
 begin
@@ -40,30 +51,22 @@ begin
 rescue GraphWeaver::TransportError
   retry                                   # network blip
 rescue GraphWeaver::ServerError => e
-  e.status >= 500 ? backoff : raise       # retry 5xx; a 4xx is our bug
+  e.throttled? || e.status >= 500 ? backoff : raise  # a plain 4xx is our bug
 rescue GraphWeaver::QueryError => e
-  e.codes.include?("THROTTLED") ? backoff : raise
+  e.throttled? ? backoff : raise          # the same question, asked of the errors array
 end
 ```
 
-Or skip the hand-rolling — `Retry` wraps any transport with
-configurable retries:
-
-```ruby
-transport = GraphWeaver::Retry.new(
-  GraphWeaver::Transport::HTTP.new(url),
-  tries: 5,                        # total attempts
-  backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
-  base: 0.5, max: 30,              # seconds, clamped at max:
-  jitter: true,                    # randomize each delay by 50-100%
-  retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
-)
-```
+`#throttled?` deliberately spells the same on both: an API may say "slow
+down" with a 429 or with a `THROTTLED` error in a 200 body, and a caller
+shouldn't have to know which. It recognizes the codes the big graphs
+actually send (`GraphWeaver::GraphQLError::THROTTLE_CODES` — Shopify's
+`THROTTLED`, GitHub's `RATE_LIMITED`, and friends); pass that constant to
+`Retry`'s `retry_codes:` instead of hand-writing the strings.
 
-Defaults match the rescue block above: transport failures always retry,
-`ServerError` only on 5xx (a 4xx is your bug — retrying won't fix it;
-override with `retry_if:`), and GraphQL-level codes only when listed in
-`retry_codes:`. Exhausting `tries:` re-raises the last error.
+Or skip the hand-rolling: [`Retry`](transports.md#retries) wraps any client and
+already defaults to exactly the policy above — transport failures always,
+`ServerError` on 5xx plus 408/429, and GraphQL error codes you name.
 
 **Top-level scalar variables** fail like any Ruby method call, *outside* the
 hierarchy on purpose — passing the wrong Ruby type for a scalar kwarg is a
@@ -73,10 +76,9 @@ String"), a missing required one a plain `ArgumentError` ("missing keyword: :id"
 
 **Input-object variables** are the caller-input case, so they're *inside* the
 hierarchy. When you pass an input object as a hash (or struct) it's built
-through the generated `coerce`, and any problem there — an unknown/typo'd key, a
-missing required field, an out-of-range enum, a wrong-typed field — raises
-`GraphWeaver::InputError`. That's one rescue point for turning invalid input
-into a 422:
+through the generated `coerce`, and anything wrong in there raises
+`GraphWeaver::InputError` — one rescue point for turning invalid input into a
+422:
 
 ```ruby
 rescue GraphWeaver::InputError => e
@@ -94,8 +96,8 @@ Business/validation failures returned *as data* (Shopify-style `userErrors { fie
 message code }`) aren't errors here — they're just fields you selected, so they
 deserialize onto `response.data` like anything else and you inspect them there.
 
-The one-shot `GraphWeaver.execute` / `execute!` mirror this: `execute` returns
-the envelope, `execute!` the result-or-raise.
+The one-shot `GraphWeaver.run` / `run!` mirror this: `run` returns
+the envelope, `run!` the result-or-raise.
 
 ## Extending TransportError