graph_weaver 0.7.4 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f631eac2f0c9bbd78b50cfe1b7a0178911a8939cc697d57328bc63b3b60cd0d7
-  data.tar.gz: 771837c86ab744d47de6b1f58e990575ee7618d9cb362e871614f6aeebcded18
+  metadata.gz: 53034719b6dcd597d098091606e08b6f4a33a15a89826374cf6b14df841aa0fc
+  data.tar.gz: cb64c3e12070f522a44353066aaac80ea7faf9df7d8a564a1abfcd053584049b
 SHA512:
-  metadata.gz: 8f24e3485d8ff839de3a9fd626b2c0038c0617c322b6249742aa90eae3552073d3cbf3335de430364072bfa990304689a7e9ad3db652ae527d46ac711573a276
-  data.tar.gz: a484029fbbdd141af8be0586d8a830e2439f13fdbbc1b9f4826840f289af3e000a81457749657e5573cd67c4ae2017aa2929bfb34a300e9777669b9265c22eb5
+  metadata.gz: 6b320bc47a5839ef8561f44ac12b78eba36cc8b33078397f2818db59ce1268fef5f3b6b4aa347ef1e21443c9e213dd1ea6c5a297d14d8fa5c651ff8bcacd3052
+  data.tar.gz: 35abfec468ca9f50327c7f6a33a7f881884c004daf294019dd0a27c12498c010ec4383404a86d7015ed74616d114978e62e081703acffbcba58b9b3abad69add

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.4)
+    graph_weaver (0.7.5)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -299,7 +299,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.7.4)
+  graph_weaver (0.7.5)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5

data/README.md

@@ -146,6 +146,7 @@ when you've skipped it.
 - **[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 each release moved
+- **[Migrating](docs/migrating.md)** — coming off graphql-client or a hand-rolled client, commit by commit
 - **[Alternatives](docs/alternatives.md)** — graphql-client, graphlient, artemis, hand-rolled: what each is good at, and where this one loses
 
 ----

data/docs/errors.md

@@ -172,7 +172,10 @@ A nested filter reports the innermost input type, so the error points at the inp
 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`
-([why](generated_modules.md#variables-become-typed-kwargs)).
+([why](generated_modules.md#variables-become-typed-kwargs)). And once a boundary
+of your own between that call site and `execute` carries a sig, sorbet-runtime
+checks the value there first: the caller sees a plain `TypeError`, and none of
+the structured, translatable detail below ever reaches it.
 
 The one-shot `GraphWeaver.run` / `run!` mirror `execute` / `execute!`.
 
@@ -464,7 +467,7 @@ 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 |
+| 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("Species", fallback: true)` to absorb them into `Other` |
 | 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

data/docs/generated_modules.md

@@ -61,6 +61,18 @@ name your operations**: an anonymous document is named after the module in the
 emitted `QUERY` *and* in `OPERATION_NAME` — both, since a server rejects an
 `operationName` its document doesn't declare.
 
+Code that takes *any* generated module — a persisted-query manifest, a
+transport of your own — types it as `GraphWeaver::QueryModule` and reads the
+same two through `query_string` and `operation_name`, which carry sigs. That is
+the spelling rubocop-sorbet allows: `mod.const_get(:QUERY)` on a `Module` is
+`Sorbet/ConstantsFromStrings`, and the `T.unsafe` that gets around it is
+`Sorbet/ForbidTUnsafe`.
+
+```ruby
+sig { params(mod: GraphWeaver::QueryModule).returns(String) }
+def manifest_line(mod) = "#{mod.operation_name}: #{mod.query_string.bytesize} bytes"
+```
+
 A `Result` is an **ordinary Ruby object**: value `==` (with `eql?` and `hash`,
 so a result works as a hash key), `deconstruct_keys` for pattern matching,
 `#to_h`, and `#to_json`/`#as_json`. All of them go the whole way down a nested
@@ -167,10 +179,11 @@ query: `pet: pets { name }` generates `Pet` (and a `.pet` accessor).
 
 **Union and interface members** are the one name that doesn't come from a key:
 they take the type condition that produces them (`... on Book` → `Book`) inside
-the container named for the field, plus the catch-all `Other`; a union hoisted
-out of a shared fragment is named for the fragment; and several fields sharing
-one collapsed union type take the first of their keys alphabetically. Still
-position-determined, all of it.
+the container named for the field, plus the catch-all `Other`; a type
+[hoisted](#a-shared-fragment-is-one-type) out of a shared fragment is named for
+the fragment; and several fields sharing one collapsed union type take the first
+of their keys alphabetically. Still position-determined, all of it — a fragment
+name is a source fact like a result key.
 
 Two collisions are handled rather than left to surprise you. A name that would
 shadow the struct it nests in (`pet { pet { ... } }`) takes a numeric suffix
@@ -321,6 +334,12 @@ Both spellings then cast to `Status::LegacyMode`, only the target gets a
 constant, and a variable sends the target — see
 [scalars.md](scalars.md#two-spellings-one-value).
 
+A value the *server* adds after you generate is drift, and casting it raises by
+default. `register_enum("Species", fallback: true)` gives the generated enum one
+extra member, `Other`, that every undeclared wire value casts to — the same
+catch-all an abstract type's dispatch always carries. A variable can't send it;
+see [scalars.md](scalars.md#values-the-server-hasnt-told-you-about-yet).
+
 `register_enum` replaces the generated `T::Enum` with your own app enum — see
 [scalars.md](scalars.md#enums-map-onto-your-own-tenum). Dynamic `parse` emits the
 enums into the query module itself; there's no cross-query set to share against,
@@ -369,6 +388,46 @@ schema's spelling in both directions, so the query, the request, the response,
 and `#as_json`/`#to_json` are untouched and `render json: result` never leaks a
 trailing underscore.
 
+### A shared fragment is one type
+
+**A whole field selected as exactly one named shared fragment is one type in
+`GraphQLTypes`, named for the fragment, which each query aliases.** Object or
+abstract, same sentence:
+
+```graphql
+# app/graphql/fragments/pet_fields.graphql
+fragment PetFields on Pet { name species birthday }
+
+# two queries, one Ruby type
+query Roster  { pets           { ...PetFields } }
+query Shelter { shelter { pets { ...PetFields } } }
+```
+
+```ruby
+GraphQLTypes::PetFields                       # the struct, generated once
+RosterQuery::PetFields                        # the alias each query opens with
+sig { params(pet: GraphQLTypes::PetFields).returns(String) }  # nameable by your app
+```
+
+That is what makes the fragment the unit of reuse on *both* sides of the wire: a
+presenter, a serializer or a policy can name its argument's type, and a union
+spread this way gives one exhaustive `case … T.absurd` everywhere instead of a
+fresh dispatch module per query.
+
+It is opt-in by how you write the query, and only the exact shape hoists —
+`{ ...PetFields id }`, `{ ...PetFields ...Vaccinations }`, a spread carrying
+`@skip`/`@include`, a fragment the query file defines itself, and a fragment
+written on some other type than the field's all stay a position-named struct
+where they are. A spread *inside* a hoisted fragment is inlined into it rather
+than hoisted again. Like shared inputs, it's a `generate!`-directory concern;
+dynamic `parse` inlines everything.
+
+Registrations follow the type, not the position, so `extend_type("Pet", …)`
+mixins and `alias:` accessors land on the hoisted struct exactly as they would
+on a local one. An `alias:` path on the *parent* may end on the hoisted struct
+(`alias: { first_pet: "pets.first" }`) but not read through it — the struct
+belongs to another module — and says so at generation.
+
 ### Abstract types
 
 An abstract field emits **one struct per type condition the selection names**,
@@ -402,11 +461,10 @@ off `__typename` when the selection carries one unaliased and unguarded, and off
 narrowed fragment, or one whose `__typename` is itself guarded, is refused: a
 match would be indistinguishable from a miss.
 
-When a whole union field is selected as one named *shared* fragment
-(`{ ...FeedItemFields }`), that type is hoisted once into `GraphQLTypes` — named
-for the fragment — and each query aliases it, so the same union is one Ruby type
-family across queries, not a fresh dispatch module per query. Like shared inputs,
-it's a `generate!`-directory concern; dynamic `parse` inlines.
+A whole union field selected as one named *shared* fragment
+(`{ ...FeedItemFields }`) is [hoisted](#a-shared-fragment-is-one-type) into
+`GraphQLTypes` like any other, so the same union is one Ruby type family across
+queries rather than a fresh dispatch module per query.
 
 ### Consuming a union — dispatch on the class, not `__typename`
 
@@ -438,8 +496,9 @@ you handle it.** It is exhaustive over the members *this query asked about*, plu
 cover: two *differently-selected* occurrences of the same union are distinct type
 families (`Result::Item::Book` is not `Result::FeaturedItem::Book`), so a `case`
 written for one won't span the other. Select the union through a shared fragment
-to hold it as one type across queries ([above](#abstract-types)); if all you have
-is the bare tag, `__typename` is the common denominator, unchecked.
+to hold it as one type across queries
+([above](#a-shared-fragment-is-one-type)); if all you have is the bare tag,
+`__typename` is the common denominator, unchecked.
 
 ## Type helpers
 
@@ -503,6 +562,22 @@ the one thing you couldn't add by hand: a `const` has no sig to put it in.
 `T.unsafe(self).name` also silences it, at the cost of checking nothing. Either
 beats `# typed: false` for a helper you want checked.
 
+**An `abstract!` mixin has a precondition: every query must select what it
+declares.** The mixin goes into *every* struct generated from the type, so a
+query selecting a subset has nothing to satisfy the rest, and generation refuses
+— naming the struct, the mixin, the members, and the two ways out: select them
+in that query, or select the type through one
+[shared fragment](#a-shared-fragment-is-one-type), which hoists a single struct
+for every query to share. The second is usually the answer: a shape several
+queries lean on is a fragment.
+
+One sig a mixin cannot write is one over a *generated* type — `sig {
+abstract.returns(GraphQLTypes::Species) }` raises `NameError` at generation,
+because registrations load before the enum that generation is about to write.
+The field's sig has to be `T.untyped` there. The struct's own `const` still
+carries the real type, so a call site reading `pet.species` is checked; only the
+mixin's view of it isn't.
+
 ### Flat accessors with `alias:`
 
 The one derivation the generator can type for you is a plain projection — a
@@ -528,7 +603,8 @@ alias: { label: "name", tag: "meta.tag" }
 ```
 
 The path is the **Ruby** accessor chain, so its segments are snake_case props
-(`name_with_owner.tag`), not wire names. It's typed from the selection: any
+(`name_with_owner.tag`), not wire names. It may end on a
+[hoisted](#a-shared-fragment-is-one-type) struct but not read through one. It's typed from the selection: any
 nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
 scalar, enum, or nested struct. It's validated against each query at generation —
 an unselected or misspelled segment (`did you mean 'tag'?`), a selector on a
@@ -679,8 +755,8 @@ it goes. The schema dump is step 0: codegen reads it, never a live endpoint, and
 generating without one fails pointing at exactly that.
 
 **A type shared across query modules lives in `GraphQLTypes` and is aliased in.**
-Input types, schema enums, and unions hoisted from shared fragments are all one
-kind of thing — a type that would otherwise be copied into every query that
+Input types, schema enums, and the types hoisted from shared fragments are all
+one kind of thing — a type that would otherwise be copied into every query that
 touches it — so they live in one module, one file each, and a query module that
 uses any of them opens with `require_relative "types"`. Rename the constant
 (`GraphWeaver.types_module=`, or `generate!(types_module:)`) when one app
@@ -716,6 +792,43 @@ spot a *schema* change for you — `schema:diff`, `schema:refresh`, `queries:che
 — are in [getting started](getting_started.md#5-verify-in-ci); a
 [`schema_stale?`](errors.md) error in production is the late signal.
 
+### Make your tooling treat generated/ as generated
+
+Three readers, three tellings — and `rails g graph_weaver:install` writes the
+two that live in files:
+
+- **You.** Every generated file opens with `# Generated by GraphWeaver
+  <version> — do not edit.`
+- **Rubocop.** The output directory goes into `AllCops: Exclude:` — machine-written
+  code isn't yours to style, and plain `rubocop` otherwise fires
+  `Style/Documentation` on every struct and `Metrics/*` on every `from_h`.
+- **GitHub.** `linguist-generated` collapses these files in a pull-request diff
+  (shown as "Load diff") and drops them from the repository's language
+  breakdown. It is display-only: they stay versioned, expandable, and `git diff`
+  here is unchanged.
+
+An app that didn't run the installer adds the two by hand:
+
+```yaml
+# .rubocop.yml — inherit_mode keeps rubocop's own Exclude defaults
+AllCops:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "app/graphql/generated/**/*"
+```
+
+```text
+# .gitattributes — gitignore-style, so `dir/**` is everything beneath it
+app/graphql/generated/** linguist-generated
+```
+
+`git check-attr linguist-generated app/graphql/generated/types.rb` answers `set`
+when the pattern is right. One line per graph in a multi-schema app, and
+[linguist's overrides](https://github.com/github-linguist/linguist/blob/main/docs/overrides.md)
+has the other attributes it reads.
+
 ### Loading what it wrote
 
 In Rails, loading is automatic — the Railtie requires every generated file at

data/docs/getting_started.md

@@ -6,6 +6,8 @@ Follow it once when you add the gem to an app. Rails is assumed;
 [not Rails?](#not-rails) covers the differences. Exploring an API from a console
 instead? Start with [dynamic mode](real_world.md) — no build step. No Sorbet in
 your app? None needed — [Sorbet, with or without](#sorbet-with-or-without).
+Already have a GraphQL client? [Migrating](migrating.md) is the order to move
+off it in.
 
 ## 1. Install
 
@@ -96,6 +98,11 @@ What it wrote:
   marked "do not edit," so the output directory is added to `AllCops: Exclude:`.
   An `AllCops:` you already have is left alone (a second one would replace it,
   not merge); the generator prints the line to add.
+- **`.gitattributes`** — `app/graphql/generated/** linguist-generated`, which is
+  how GitHub is told the same thing: it collapses those files in a pull-request
+  diff and leaves them out of the repository's language breakdown. Display only,
+  so they stay versioned and expandable
+  ([the three tellings](generated_modules.md#make-your-tooling-treat-generated-as-generated)).
 
 Rake needs no wiring: in Rails the `graph_weaver:*` tasks register themselves and
 depend on `:environment`, so your initializer runs first. The generated modules
@@ -165,10 +172,11 @@ Fragment files hold only fragments (no operations), and names are unique across
 them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
 default `app/graphql/fragments`).
 
-One payoff: when a shared fragment *is* the whole selection on a union field,
-its type is hoisted once into `GraphQLTypes` and every query that spreads it
-gets the same Ruby type — so one exhaustive `case … T.absurd` works everywhere.
-See [abstract types](generated_modules.md#abstract-types).
+One payoff: when a shared fragment *is* the whole selection on a field, its type
+is hoisted once into `GraphQLTypes` under the fragment's name and every query
+that spreads it gets the same Ruby type — so a presenter can take a
+`GraphQLTypes::PersonFields`, and a union's `case … T.absurd` works everywhere.
+See [hoisting](generated_modules.md#a-shared-fragment-is-one-type).
 
 ## 4. Test against fakes
 
@@ -216,9 +224,10 @@ Five questions, five tasks — the last only on a federated graph:
 Every one of them exits non-zero on a finding, so the gate is a chain.
 `verify` compares the committed generated files against what the current schema
 + queries + registrations would produce, so it belongs in every CI build.
-`schema:diff` asks whatever the dump came from — a recorded source url (with
-`GRAPHWEAVER_AUTH` for private APIs), or your own schema class when the app
-[serves the schema itself](#your-apps-own-schema-in-process) — and
+`schema:diff` asks whatever the dump came from — the source url the dump
+recorded (with `GRAPHWEAVER_AUTH` for private APIs), your own schema class when
+the app [serves the schema itself](#your-apps-own-schema-in-process), else the
+client this graph's modules already post to — and
 `rake graph_weaver:schema:refresh` is the repair either way. On an app with more
 than one schema, `rake graph_weaver:graphs` lists which graphs are configured,
 where each generates, and what each registers.
@@ -283,8 +292,8 @@ omits it. Any drift exits non-zero — whether a change matters is yours to judg
 (`#breaking`, `#compatible`, `#to_h`, `#empty?`).
 
 `queries:check` answers the question that matters when the schema *has* moved:
-**which of your queries no longer validate, and why.** It re-introspects the
-recorded url (without rewriting the dump) and validates every `.graphql` file
+**which of your queries no longer validate, and why.** It re-introspects the url
+the dump records (without rewriting the dump) and validates every `.graphql` file
 against the schema as it is right now, naming each error's line and column:
 
 ```
@@ -294,6 +303,12 @@ app/graphql/queries/person.graphql
 1 invalid query
 ```
 
+A dump that records no url has nothing to re-read, and so does a graph that
+names its own schema: both are checked as they stand on disk. That is `verify`'s
+question rather than this one's, so the passing verdict names the file instead of
+claiming a check against the server ([a dump you already
+have](#a-schema-dump-you-already-have)).
+
 `GraphWeaver.check_queries` returns the same findings as data — a hash of file
 to `message`/`line`/`column`, empty when everything validates — so you can wire
 it into a spec, a Slack ping, an issue. Pass it `schema:` a *loaded* schema (not
@@ -331,9 +346,11 @@ app/graphql/queries/products.graphql: Products.sku — selected, never read (Cat
 Each line names the query file, the selection to go and delete, and the
 generated prop behind it. It reads the generated structs for the props a query
 produced, then sweeps your `.rb`, `.rake`, `.builder`, `.erb`, `.slim`, `.haml`
-and `.jbuilder` for every name they could be read by — `.sku`, `sku:`, `:sku`,
-`"sku"`. `PATHS=app,lib` narrows the sweep (a `PATHS=` naming a directory that
-isn't there is refused rather than swept as nothing); anything under a directory
+and `.jbuilder` — plus Ruby carrying no extension, which is any name under
+`bin/` or `exe/` and a ruby shebang anywhere else — for every name they could be
+read by: `.sku`, `sku:`, `:sku`, `"sku"`. `PATHS=app,lib` narrows the sweep (a
+`PATHS=` naming a directory that isn't there is refused rather than swept as
+nothing); anything under a directory
 named `generated`, plus `vendor`, `node_modules`, `tmp` and `log`, is skipped,
 as is any file defining a graphql-ruby **type** — a `field :sku` there is your
 *server* offering a field, not this app reading one back. A module handed whole
@@ -416,6 +433,27 @@ Sets `GraphWeaver.schema_path` to that file rather than writing a second copy,
 and introspects nothing. A dump has no resolvers, so it can't execute — set
 `GraphWeaver.client` to whatever serves the API.
 
+**A dump you brought from elsewhere has no provenance**: it doesn't record the
+server it was introspected from, which is exactly what migrating off
+graphql-client leaves you ([migrating](migrating.md)). `rake
+graph_weaver:schema:refresh` adopts it — with no url on the file it introspects
+the client the graph names, rewrites the dump, and records the source, so every
+later refresh and `schema:diff` re-read the right server. `URL=` names the
+endpoint instead, if you'd rather say it once than configure the client first.
+
+Do it early. Until the dump records a source, `queries:check` has nothing to
+re-introspect, so it validates against the committed file — a real check, but
+`verify`'s question rather than this one's — and the verdict says which:
+
+```
+every query validates against db/schema.graphql as committed — not the server (rake graph_weaver:schema:diff asks whether the server moved)
+```
+
+A dump with no recorded url and no client behind it *is* the schema — a
+hand-maintained SDL nothing serves. `schema:refresh` leaves that one alone
+(`records no source url and the graph names no client — left as checked in`) and
+refreshes the rest, rather than taking the whole task down with it.
+
 ## More than one schema
 
 The five steps above describe one graph — a schema, its queries, its output. An
@@ -484,8 +522,9 @@ An app that is a pure client of someone else's GraphQL owns no schema class, so
 every graph's `schema` is a dump. Give each the file you want and a `client`
 that can fetch it: `rake graph_weaver:schema:refresh` introspects each graph's
 client into its own dump, recording the url so every later `schema:refresh` and
-`schema:diff` re-reads the right server. (`URL=` is for the app that has one
-dump and no graphs.)
+`schema:diff` re-reads the right server. A graph with neither a recorded url nor
+a client is left as checked in and the rest still refresh. (`URL=` is for the
+app that has one dump and no graphs.)
 
 In specs, `graph:` is how an example says which graph a helper stands in for —
 `graphql_fake(graph: :poke, "pokemon_v2_pokemon.name" => "pikachu")`. See
@@ -527,6 +566,106 @@ per-struct `extend T::Sig` in generated files is redundant — rubocop's
 time and skips the `extend`; override with `GraphWeaver.extend_t_sig =
 true`/`false`.
 
+### The types stop where your sigs do
+
+That typo is caught where the struct comes back. Hand the struct to one method
+without a sig and it is `T.untyped` from there on — the same typo, one layer in,
+is silent — and a sig on the method that produced it is no help either:
+
+```ruby
+# typed: true
+class PersonDirectory
+  extend T::Sig
+
+  sig { returns(T.nilable(PersonQuery::Result::Person)) }
+  def person = PersonQuery.execute!(id: "1").person
+end
+
+class Profile
+  def initialize(person)   # no sig, so @person is untyped
+    @person = person
+  end
+
+  def title = @person.nmae   # "No errors! Great job."
+end
+
+class Page
+  def initialize(directory)   # nor is the sig above any help here
+    @directory = directory
+  end
+
+  def title = @directory.person&.nmae   # also clean
+end
+```
+
+Every hop has to be sig'd: the method that produces the struct, any wrapper it
+passes through, and the constructor that stored the collaborator. Two shapes
+cover most of an app.
+
+A wrapper that only passes a block through keeps the block's type with
+`type_parameters`:
+
+```ruby
+# a rescue wrapper that keeps the block's type
+sig do
+  type_parameters(:T).params(blk: T.proc.returns(T.type_parameter(:T)))
+   .returns(T.type_parameter(:T))
+end
+def people(&blk) = yield
+```
+
+A service boundary spells the struct it hands out, and whoever holds that
+service types the ivar:
+
+```ruby
+class Page
+  extend T::Sig
+
+  sig { params(directory: PersonDirectory).void }
+  def initialize(directory)
+    @directory = directory   # the sig is what types this ivar
+  end
+
+  sig { returns(T.nilable(String)) }
+  def title = @directory.person&.nmae   # now srb tc has it
+end
+```
+
+That is sigs on half a dozen service methods and a couple of constructors before
+the first typo in a layered app is caught. Budget it as its own piece of work
+rather than as part of generating the types — and if it isn't work you're going
+to do, the runtime half still holds: a bad field is a `NoMethodError` the first
+time the line runs.
+
+### Give a struct a short name where you name one
+
+A generated struct's constant path spells out the query that produced it, which
+is what makes it stable — and long. Where your own code names one in a sig, alias
+it once, in the class that hands it out:
+
+```ruby
+# before
+sig { params(code: String).returns(T.nilable(Countries::CountryProfileQuery::Result::Country)) }
+
+# after
+class Directory
+  Country = Countries::CountryProfileQuery::Result::Country
+
+  sig { params(code: String).returns(T.nilable(Country)) }
+end
+```
+
+Use a plain constant, not `T.type_alias`: the constant works in a sig *and* as a
+value (`Country.from_h`), and in a `# typed: strict` file it needs no `T.let`
+around it. Reach for `T.type_alias` only where a constant can't express the type
+— a union of two queries' structs.
+
+That takes the worst sig in one migrated app from 116 characters to 72, and the
+callers get the short name too: a presenter takes a `Directory::Country` and
+stops knowing which `.graphql` file produced it. It is also what makes the sig
+chain above affordable, since a sig usually goes unwritten because the line is
+too long to want to write.
+
 ## Not Rails?
 
 There's no generator, but what it writes is short — a few lines wherever your
@@ -541,6 +680,12 @@ GraphWeaver.client = GraphWeaver.new(
 GraphWeaver.load_generated!   # no Railtie to require the generated files
 ```
 
+**`load_generated!` goes before your own requires** when anything your app loads
+names a generated constant as it loads — a `STATUS_LABELS` table keyed on
+`GraphQLTypes::ShipmentStatus` raises `uninitialized constant` otherwise, and
+building it lazily to dodge that earns `Dynamic constant references are
+unsupported` from `srb tc`. One line of ordering settles both.
+
 ```sh
 mkdir -p app/graphql/queries app/graphql/generated
 rake graph_weaver:schema:refresh URL=https://api.example.com/graphql

data/docs/migrating.md

@@ -0,0 +1,119 @@
+# Migrating from graphql-client (or a hand-rolled client)
+
+**The wire doesn't change.** The same query text goes out and the same JSON comes
+back, so this is a sequence of small commits rather than a cutover: queries move
+across one at a time while the old client keeps serving, and most of the spec
+suite you already have keeps passing untouched.
+
+Budget 3–4 weeks of one engineer for an app with ~40 queries and 25k lines of
+code reading them — [what it costs](#what-it-costs) breaks that down. If the app
+doesn't run Sorbet and has fewer than ten queries, don't migrate: the wins that
+survive without `srb tc` are real, but they don't pay for a checked-in code
+generator ([alternatives](alternatives.md#graphlient)).
+
+## From graphql-client, in Rails
+
+**Both gems stay in the Gemfile until the last commit.** `rails g
+graph_weaver:install` boots the app to read your configuration, so an initializer
+that still requires graphql-client has to keep resolving — remove the gem first
+and the generator dies on `cannot load such file -- graphql/client`. Running the
+two side by side is the right shape anyway.
+
+1. **Install beside graphql-client**, pointed at the dump you already have:
+   `rails g graph_weaver:install db/petstore_schema.json` ([a schema dump you
+   already have](getting_started.md#a-schema-dump-you-already-have)). Commit that
+   and nothing else.
+2. **Adopt the dump.** It records no source url, so `schema:diff` and
+   `queries:check` have no server to ask. `rake graph_weaver:schema:refresh`
+   rewrites it from the client the app points at (or `URL=<your endpoint>` once)
+   and records the provenance. Do it now: until you do, `queries:check` is
+   re-reading the file it is meant to be checking against, and says so.
+3. **Register scalars and enums, and regenerate**, before porting any code.
+   Registrations are baked into generated source, so one added later reaches
+   nothing until the next `rake graph_weaver:generate` ([scalars](scalars.md)).
+4. **Port one query end to end** — write the `.graphql` file, generate, rewrite
+   its call site — and leave the specs alone. They pass untouched. That single
+   commit is the proof for every one after it.
+5. **Port the rest, one commit per query.** Each `Client.parse` constant stays
+   where it is until its last caller is gone.
+6. **Only now port the specs** to `graphql: :fake` ([testing](testing.md)). Keep
+   webmock until the last wire-level stub is gone, and keep one spec that really
+   serves HTTP.
+7. **Delete graphql-client.** Last commit.
+8. **Sigs through your own app are a separate project**, after all of the above —
+   [the types stop where your sigs do](getting_started.md#the-types-stop-where-your-sigs-do)
+   says what that work is.
+
+Keep your own error classes. Translating `GraphWeaver::QueryError`,
+`TransportError` and `ServerError` at one seam leaves a controller, its rescues
+and their specs untouched ([errors](errors.md)). Keep your presenters too, and
+your fixtures until step 6.
+
+### Why app code and specs are separate commits
+
+Because the wire is the same, a webmock suite doesn't notice which client sent
+the request. Swap the client under an untouched suite and most of it stays green
+— 18 of 22 stubbed examples in one migrated Rails app, same stubs, same JSON
+fixtures; the four that failed were unit specs feeding a hand-rolled `Struct` to
+a presenter. That is the difference between a reviewable migration and a big-bang
+one.
+
+## From a hand-rolled client
+
+Same skeleton, three differences.
+
+- **One branch, no seam.** There's no generator to keep bootable and a
+  hand-rolled client is sixty lines, so running two of them side by side costs
+  more than it saves.
+- **Set the load order first**: `GraphWeaver.load_generated!` goes before your own
+  requires ([not Rails?](getting_started.md#not-rails)). Add `rake` to the Gemfile
+  while you're there.
+- **Keep the old client's transport specs**, rewritten against a real
+  `GraphWeaver.new(url, retries: 2)` with webmock. Retries, timeouts and backoff
+  are the one thing fakes can't cover.
+
+## What you delete
+
+- **The retry loop.** A hand-rolled one usually retries everything, mutations
+  included. `retries: 2` excludes mutations by default, honours `Retry-After`,
+  and knows 408 and 429 ([retries](transports.md#retries)) — twenty lines gone and
+  a correctness bug gone with them.
+- **Scalar parsers.** `register_scalar("Money", Money)` is one line, and it
+  deletes the `"USD 12.50".split` sitting in every place that parsed one. `Date`
+  and `DateTime` need no registration at all ([scalars](scalars.md)).
+- **Fragment unwrapping.** graphql-client masks a spread fragment's fields on the
+  parent, so every call site reads `Petstore::PetFields.new(data.pet).name` and
+  carries the parent alongside for the fields the fragment didn't cover. Generated
+  structs inline the fragment, so it's `pet.name`; a fragment that is a whole
+  selection becomes one shared Ruby type
+  ([hoisting](generated_modules.md#a-shared-fragment-is-one-type)).
+- **JSON fixtures and stub helpers.** `graphql: :fake` fabricates a
+  schema-correct response and you pin the fields the example is about. Pins are
+  schema vocabulary (`"Pet.species" => "DOG"`), so they survive query refactors,
+  and they're spellchecked — a typo raises instead of leaving the example green
+  against random data ([testing](testing.md)).
+
+## The one behaviour change to plan for
+
+**Enum drift is fatal.** A hand-rolled client hands you the raw string, so a value
+the server added after you shipped falls through to whatever your code does with
+an unknown one — commonly a `humanize`. A generated enum refuses instead: casting
+raises and the whole response is lost, naming the value, the enum and the values
+it knows about.
+
+That is the right default for an API you own and a real risk for one you don't,
+because it breaks on a day nobody deployed. Before you port a query over an enum
+someone else can extend, register a fallback for it and unknown values land there
+instead — [enums](scalars.md#enums-map-onto-your-own-tenum).
+
+## What it costs
+
+| | how it scales | ~40 queries, 25k lines |
+|---|---|---|
+| `.graphql` files and generating | sublinear — the second query costs a tenth of the first | 2–3 days |
+| call sites | linear, and the bulk of it: every `data["x"]["y"]` becomes `x.y`, and every defensive `nil` guard either disappears or turns out to have been wrong | ~1 day per 3–4k lines of consuming code |
+| specs | linear, and pleasant — the fixture-to-pin conversion is the same edit every time | ~2 days |
+| sigs through your own app | the one that decides whether the migration paid off | weeks; a separate project |
+
+Coming off graphql-client, run the new one behind the old for the first two
+weeks. The wire compatibility makes that free.