graph_weaver 0.5.1 → 0.6.1

data/README.md

@@ -42,14 +42,47 @@ result.person&.nmae
 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.
 
-Typed structs are the part every generator gets right. What decides whether you're
-still happy six months in is everything around them.
+## Start here
+
+```ruby
+# Gemfile
+gem "graph_weaver"
+```
+
+In Rails, setup is one command:
+
+```sh
+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.
+
+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.
+
+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
+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
-fabricator. One line in the spec helper:
+fakes. One line in the spec helper:
 
 ```ruby
 require "graph_weaver/rspec"
@@ -68,77 +101,64 @@ end
 ```
 
 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).
+`--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:
+
+```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. 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:
+[`examples/federation.rb`](examples/federation.rb), the example that needs no
+network. Part of what it prints:
 
 ```
-$ bundle exec examples/federation.rb
-#<GraphWeaver::Testing::Router subgraphs=["accounts", "products", "reviews"]>
-
-dpep reviewed 2 products:
-  Table ($899) — Love it
-  Couch ($1299) — Too expensive
-
 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
+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
 ([`spec/integration/router_parity_spec.rb`](spec/integration/router_parity_spec.rb)).
 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` 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).
-
-## Start here
-
-```ruby
-# Gemfile
-gem "graph_weaver"
-```
-
-In Rails, setup is then one command:
-
-```sh
-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:
+`schema:refresh` re-introspects the committed dump, `schema:diff` names what
+changed 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).
 
-```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.
+**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.
 
 #### Also in the box
 
@@ -155,11 +175,12 @@ federated graph above.
 - **[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
+- **[Custom scalars](docs/scalars.md)** — what's registered already, codec inference, 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
+- **[Upgrading](docs/upgrading.md)** — regenerate on every bump, and what 0.5.0 moved
 
 ----
 ## Development

data/docs/cassettes.md

@@ -113,7 +113,12 @@ rake graph_weaver:cassettes:anonymize   # every cassette in cassette_dir, in pla
 ```
 
 Anonymization preserves shape, so an anonymized cassette still passes
-`cassettes:check`.
+`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.
 
 ## Cassette or FakeClient?
 

data/docs/editors.md

@@ -22,7 +22,9 @@ 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.
+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`):
 

data/docs/errors.md

@@ -1,8 +1,18 @@
 # Errors
 
-`execute` returns a typed **`Response` envelope** rather than raising on GraphQL
-errors — so partial data and top-level `extensions` (cost, throttle) survive.
-`execute!` is the shortcut when you just want the result:
+What comes back when something goes wrong, and what to rescue. Read it when you
+write the first `rescue` around a query, or when you need to tell "the network
+broke" apart from "the server said no" apart from "the response didn't fit".
+
+Two names travel together here, and they're close enough to trip on:
+
+- **`Result`** — the struct holding *this* query's data, e.g. `PersonQuery::Result`.
+- **`Response`** — the **envelope** around it, `GraphWeaver::Response[Result]`,
+  carrying `data`, `errors` and `extensions`.
+
+`execute` returns the envelope rather than raising on GraphQL errors, so partial
+data and top-level `extensions` (cost, throttle) survive. `execute!` is the
+shortcut to the result:
 
 ```ruby
 PersonQuery.execute!(id: "1")   # => Result, or raises QueryError  (== execute(...).data!)
@@ -30,7 +40,7 @@ subclass says where it failed:
 
 | Class | When |
 |-------|------|
-| `TransportError` | never reached the server — DNS, connection refused, TLS, timeout |
+| `TransportError` | no response came back — DNS, connection refused, TLS, timeout, a socket that died mid-body |
 | `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` |
@@ -70,17 +80,34 @@ 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
-programming bug, not caller input: a wrong-typed one raises sorbet-runtime's
-`TypeError` ("Parameter 'page': Expected type T.nilable(Integer), got type
-String"), a missing required one a plain `ArgumentError` ("missing keyword: :id").
+**A status with an obvious next step says it.** A 3xx appends "redirects are
+not followed" and the `Location` to repoint the client at — replaying a POST,
+with its `Authorization` header, at a host the server named isn't the
+library's call. A 401 or 403 appends "check `auth:` — the token, and its
+scopes".
+
+**Everything you pass to `execute` is caller input**, so a value that won't
+convert raises `GraphWeaver::InputError` — top-level scalar variables included.
+They name the variable and the operation, since the value alone locates nothing
+in an app that runs a hundred queries:
+
+```
+$count of Compute: expected an Int, got "lots"
+```
+
+The value is usually the whole diagnosis, so it is quoted — unless the key it
+arrived under is one your `filter_parameters` covers, in which case the message
+reads `$password of Login: [FILTERED]`. Error messages reach the log at `warn`,
+above the level that gates the variables line, so they are scrubbed by the same
+list ([logging](logging.md#filtered-variables)).
+
+A *missing* required kwarg is still a plain `ArgumentError` ("missing keyword:
+:id") — that's Ruby's, and it is a programming bug rather than bad input.
 
-**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 anything wrong in there raises
-`GraphWeaver::InputError` — one rescue point for turning invalid input into a
-422:
+**What's inside an input object** reports the same way. Pass one as a hash (or
+struct) and it's built through the generated `coerce`, and anything wrong in
+there raises `GraphWeaver::InputError` too — so one rescue point turns invalid
+input into a 422:
 
 ```ruby
 rescue GraphWeaver::InputError => e
@@ -92,7 +119,16 @@ end
 ```
 
 A nested filter reports the innermost input type, so the error points at the
-input that actually held the bad field.
+input that actually held the bad field. Passing something that is neither — a
+bare `String` where the input goes — reports the same way. A call site that
+*spells* the wrong type is caught earlier and better, by `srb tc`: the sig is
+as narrow as the schema, and only untyped values reach the runtime check
+([why](generated_modules.md#variables-become-typed-kwargs)).
+
+`#struct` is the generated input struct *class* where generation produced one,
+and the GraphQL type *name* where it didn't — a federation representation
+builds a plain Hash, so an entity has only its name to give. `to_h`'s
+`"struct"` is the name either way, so branch on that.
 
 Business/validation failures returned *as data* (Shopify-style `userErrors { field
 message code }`) aren't errors here — they're just fields you selected, so they
@@ -139,6 +175,14 @@ response.report
 `GraphQLError#field` strips list indices (`people.3.email` → `people.email`) —
 the stable grouping key; the raw `#path` keeps indices for exact location.
 
+`Response#to_h` decomposes the envelope the same way: `{"data" =>, "errors" =>,
+"extensions" =>}`, with each error as its JSON-ready hash. `data` stays the
+typed struct — it is deliberately not re-serialized, because `T::Struct#serialize`
+would give snake_case keys where the wire is camelCase, drop null fields, and
+leave a registered scalar as the Ruby object its codec built. That output would
+look like the server's response without being one, so serialize the typed data
+yourself when you need to re-emit it.
+
 ## Stale schemas
 
 GraphQL has no schema-version signal, so a schema change surfaces as the
@@ -153,6 +197,19 @@ refresh the schema cache.
 When wire data disagrees with the types the schema promised at generation time
 (a nil where non-null was declared, a malformed scalar, an unknown enum value),
 casting raises `GraphWeaver::TypeError` naming the failing generated struct,
-with the original exception as `#cause`. Simulate one in tests with
+with the original exception as `#cause`.
+
+A cast's own complaint is about the value and nothing else — "invalid date"
+locates nothing on a struct holding four of them — so a casting leaf also
+carries **its response key**, and three failures that keep happening say whose
+bug it is rather than leaving you sorbet's words:
+
+| what came back | what the message adds |
+|---|---|
+| an `ID` the server sent unquoted | GraphQL serializes `ID` as a JSON string, so this is the server out of spec — plus how to take it anyway (`register_scalar("ID", "T.untyped")`) |
+| an enum value the generated enum doesn't hold | the values it does hold, and that drift is the likely cause: regenerate, or `register_enum(fallback:)` to absorb them |
+| a field the server nulled **with a reason** | the server's own explanation, rather than only sorbet's nil complaint |
+
+Simulate one in tests with
 `GraphWeaver::Testing::FakeClient.new(schema:, corrupt: "Person.birthday")` — see
 [testing](testing.md).