graph_weaver 0.7.3 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 653ecbcc2215bf5358e34bc83d701ded874a6ee1910ceeca18f0ed205a44798f
-  data.tar.gz: 2d1e49f247e84347c7bd86123b54b1b9d31d8978bc2a6a8f8d9538342c3ab67d
+  metadata.gz: 53034719b6dcd597d098091606e08b6f4a33a15a89826374cf6b14df841aa0fc
+  data.tar.gz: cb64c3e12070f522a44353066aaac80ea7faf9df7d8a564a1abfcd053584049b
 SHA512:
-  metadata.gz: 220c5d9ab87c671a602b226b2789fee65307e3b8a85407fa5c979eb272cde0e27d551e0a6d5ef32ad2714a6eec211fcf0657d1a2b7eb7a53c33d063756d8e82c
-  data.tar.gz: 650c62d1ca107aaaccfa03ddd4686475c15ad68c0cf421be67379a7b88212af8366681da61208dee39ee2a68a468ca792f8cc9fee54c8982087924f927c2a2d1
+  metadata.gz: 6b320bc47a5839ef8561f44ac12b78eba36cc8b33078397f2818db59ce1268fef5f3b6b4aa347ef1e21443c9e213dd1ea6c5a297d14d8fa5c651ff8bcacd3052
+  data.tar.gz: 35abfec468ca9f50327c7f6a33a7f881884c004daf294019dd0a27c12498c010ec4383404a86d7015ed74616d114978e62e081703acffbcba58b9b3abad69add

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.3)
+    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.3)
+  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/federation.md

@@ -690,8 +690,9 @@ the rest.
 
 The table is also what a good error message wants. When the schema dump is a
 composed supergraph, `rake graph_weaver:queries:check` brands each validation error
-with the subgraphs behind the type it names, and `check_queries` carries the same
-list as a `"subgraphs"` key:
+with the subgraphs behind the type it names, and `check_queries` — or
+`client.check_query(source)`, for a client built from that dump — carries the
+same list as a `"subgraphs"` key:
 
 ```
 app/graphql/queries/product.graphql

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
@@ -308,6 +321,25 @@ camelizes to nothing — `_` and `__` are both legal GraphQL — is refused at
 generation: there is no constant to name it. Map the enum onto one of yours
 instead.
 
+Two values that camelize to the *same* constant are refused for the same reason.
+A schema mid-rename declares exactly that — `LEGACY_MODE` alongside
+`legacy_mode`, so old clients keep working — and if they are one value, say
+which spelling goes on the wire:
+
+```ruby
+GraphWeaver.register_enum("Status", alias: { "legacy_mode" => "LEGACY_MODE" })
+```
+
+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,
@@ -356,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**,
@@ -389,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`
 
@@ -425,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
 
@@ -470,19 +542,42 @@ The name is where the block is written and what it extends:
 `GraphWeaver::TypeHelpers::Billing::Pet` inside `GraphWeaver.graph :billing`.
 Generated code spells it, so it depends on your source and nothing else — two
 graphs can extend the same type name, and the name a `generate` bakes in is the
-one a boot creates.
-
-**Neither form is statically checked as written**, for the same reason: `srb tc`
-checks a mixin's method bodies in the module's own scope, not the including
-struct's, so a helper reading a wire field (`name`, `birthday`) fails with
-"method does not exist on the module" — and the block form has no source on disk
-for `srb tc` to read at all. A *named* module can carry real sigs, though, by
+one a boot creates. The module is minted at registration, so no file declares
+it; generation writes a `type_helpers.rbi` beside the modules that does, which
+is what lets your `srb tc` resolve the `include`. Ruby never loads an `.rbi`, so
+dropping the registration still fails loudly at require rather than quietly
+handing the struct an empty module.
+
+**Neither form has its method bodies statically checked**, for the same reason:
+`srb tc` checks a mixin's method bodies in the module's own scope, not the
+including struct's, so a helper reading a wire field (`name`, `birthday`) fails
+with "method does not exist on the module" — and the block form has no source on
+disk for `srb tc` to read at all. A *named* module can carry real sigs, though, by
 declaring the fields it leans on: `abstract!` plus a
 `sig { abstract.returns(String) }; def name; end` is how a mixin says "whatever
-includes me has these", and the struct's `const`s satisfy them.
+includes me has these", and the struct's `const`s satisfy them — generation
+declares the override Sorbet demands there (`const :name, String, override:
+true`, and `sig { override.returns(...) }` on an `alias:` accessor), which is
+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
@@ -508,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
@@ -534,6 +630,26 @@ excuses a field the query didn't select, not a segment the schema doesn't have:
 typo or a wire-cased name (`findPets` for `find_pets`) still raises, since no
 selection could ever satisfy it.
 
+**One call does both halves.** `alias:` and a block are independent parts of the
+same registration — the accessor is emitted into the struct body, the block
+becomes a mixin the struct includes — so a block method can call an accessor the
+same call declared. Inside the block the alias is spelled `alias_field`, which
+is the same keyword said next to the methods that use it: same paths, same
+errors, same accessor. Two positions, one thing.
+
+```ruby
+GraphWeaver.extend_type("Widget") do
+  alias_field :tag, "meta.tag"     # or alias_field "meta.tag" — accessor named `tag`
+  def shout = tag&.upcase
+end
+```
+
+The verb is `alias_field` because the block can't spell `alias` itself: it is a
+Ruby keyword, and the block is `module_eval`'d Ruby, so writing it there would
+define a method alias rather than a projection. A block says one alias per line
+and nothing else — the compact `{ }`/`[ ]` forms and `optional: true` stay on
+the keyword, since leniency describes the registration rather than one accessor.
+
 For anything beyond a passthrough projection — real logic, still typed — reopen
 the generated struct in your own file and add sig'd methods; Sorbet merges the
 bodies. Every form above, and every error it raises, is a named example in
@@ -602,6 +718,7 @@ app/graphql/
   generated/
     types.rb         # manifest: requires + forward declarations, in load order
     types/           # one file per shared type
+    type_helpers.rbi # only with a block-form extend_type — declares its module
     *_query.rb       # one module per query — generated, checked in, never edited
     *_mutation.rb    # ...and per mutation
 ```
@@ -638,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
@@ -675,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,12 +303,33 @@ 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
 a path) and nothing touches the network, which is how you check your queries
 against a proposed subgraph before it's live.
 
+A query you have as a **string** rather than on disk asks the same client the
+same question, and gets the same entries back:
+
+```ruby
+client.check_query('query($id: ID!) { person(id: $id) { nmae } }')
+# => [{ "message" => "Field 'nmae' doesn't exist on type 'Person' (Did you mean `name`?)",
+#       "line" => 1, "column" => 37 }]
+```
+
+Empty means it validates. It checks against that client's own schema — the one
+`execute` would run against — so nothing re-introspects, and an unparseable
+source comes back as an entry rather than an exception. Shared fragments are
+inlined from `fragments:`, defaulting to `GraphWeaver.fragments_paths` the way
+`parse` does.
+
 ### The selections nothing reads
 
 `rake graph_weaver:unused` asks the one question the others can't: not "is the
@@ -316,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
@@ -401,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
@@ -469,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
@@ -512,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
@@ -526,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/i18n.md

@@ -121,10 +121,10 @@ I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.
 Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
 know the language — `members: e.details[:members].to_sentence`.
 
-`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
-sentence built from it still says "Int" in the middle of the French. Translate
-the name yourself under a key of your own and pass it *after* the splat, which
-wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
+`details[:type]` is the **GraphQL** spelling of the type — a name (`Int`,
+`Money`) or a whole signature (`[JSON!]`, `[Float!]!`) — so a sentence built
+from it still says "Int" in the middle of the French. Translate the spelling
+yourself under a key of your own and pass it *after* the splat, which wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
 
 `@oneOf` violations are `:refused`, except exactly one field explicitly null,
 which is `:missing` on that field — a form gets the one slot to highlight. The