graph_weaver 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12bea1d4f3d38c00c496ec595788629ea6c12c9f7590fc7938976570d8c86917
-  data.tar.gz: e7f8e60574801cc70032a4e2502a05d6ec8f9ac170ab22b53fa12b4f2633835a
+  metadata.gz: e0ae9c23b2566bfa26c786e07703e4fad357cbd09a29112d3e0c9dd5d3af916c
+  data.tar.gz: fb5f4534174e5ba9cb7b9d323af26c2a13456c022f8682bcc3ccae5e512a1c96
 SHA512:
-  metadata.gz: e913ad4e5104a983b7ba0d87ae838de4a6e9e238aa7fc70c3d8d673ee24faba7eecf2734c7d403443cd2acdf93d4723adbc01bc0fc485e738df608f63adf43c1
-  data.tar.gz: cc1d344c3f99c5d587a3abb5e385626048d4821766c458ae7a7401b639ab9851c6c253d618282b9e314310bae88583240b0770588b06c898052e7a96d8472975
+  metadata.gz: dc780e4f155ea89b9977822a7bb62ed9880d3b7e707fd5046229b1c91c843a9c1ec37c39fb5e2039e71c9095dfb7a0df006347a19ce4544f75f2b3fe13a35a5c
+  data.tar.gz: 3dcc86b06e670408ebc18eaaaad7447d5825d1d580b9640ed8860133ba29908eb42553d52da4a2619eb23f072f4999f5aceb622271fafc8d5431fd57a3106ed3

data/Gemfile

@@ -1,3 +1,11 @@
 source "https://rubygems.org"
 
 gemspec
+
+# Mutation testing — not in the gemspec: it is a local quality tool, not a
+# development dependency contributors need to install the gem's suite.
+# Proprietary EULA, free for opensource projects (see `usage:` in mutant.yml).
+group :development do
+  gem "mutant", "0.16.3"
+  gem "mutant-rspec", "0.16.3"
+end

data/Gemfile.lock

@@ -1,24 +1,63 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.6.1)
+    graph_weaver (0.7.1)
       graphql (>= 2.6.7)
       sorbet-runtime
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (8.1.3.1)
+      actionview (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actionview (8.1.3.1)
+      activesupport (= 8.1.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     apollo-federation (3.10.3)
       google-protobuf (< 5)
       graphql
+    ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (4.1.2)
+    builder (3.3.0)
     concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    crass (1.0.7)
     debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
+    drb (2.2.3)
     erb (6.0.4)
     erubi (1.13.1)
     faker (3.8.0)
@@ -46,6 +85,7 @@ GEM
       base64
       fiber-storage
       logger
+    hashdiff (1.2.1)
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
@@ -56,14 +96,68 @@ GEM
       reline (>= 0.4.2)
     json (2.21.2)
     logger (1.7.0)
+    loofah (2.25.2)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    mutant (0.16.3)
+      diff-lcs (>= 1.6, < 3)
+      irb (~> 1.15)
+      parser (~> 3.3.10)
+      regexp_parser (~> 2.10)
+      securerandom (>= 0.3)
+      sorbet-runtime (~> 0.6.0)
+      unparser (>= 0.8.2, < 0.10)
+    mutant-rspec (0.16.3)
+      mutant (= 0.16.3)
+      rspec-core (>= 3.8.0, < 5.0.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
     netrc (0.11.0)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
     parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
     pp (0.6.4)
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rack (3.2.7)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.1)
+      loofah (~> 2.25, >= 2.25.2)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
     rake (13.4.2)
     rbi (0.3.14)
       prism (~> 1.0)
@@ -78,6 +172,7 @@ GEM
       rbs (>= 4.0.0)
       tsort
     redcarpet (3.6.1)
+    regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
     require-hooks (0.4.0)
@@ -99,6 +194,7 @@ GEM
     rubydex (0.2.7-arm64-darwin)
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
+    securerandom (0.4.1)
     simplecov (1.2.0)
     sorbet (0.6.13485)
       sorbet-static (= 0.6.13485)
@@ -131,9 +227,21 @@ GEM
       tsort
     thor (1.5.0)
     tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unparser (0.9.0)
+      diff-lcs (>= 1.6, < 3)
+      parser (>= 3.3.0)
+      prism (>= 1.5.1)
     uri (1.1.1)
+    useragent (0.16.11)
+    webmock (3.26.4)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     webrick (1.9.2)
-    yard (0.9.44)
+    yard (0.9.45)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   aarch64-linux
@@ -149,23 +257,38 @@ DEPENDENCIES
   faker
   faraday
   graph_weaver!
+  mutant (= 0.16.3)
+  mutant-rspec (= 0.16.3)
+  rack
+  railties
   rake
   redcarpet
   rspec
   simplecov
   sorbet
   tapioca
+  webmock
   webrick
   yard
 
 CHECKSUMS
+  actionpack (8.1.3.1) sha256=974cb7154548e81f470b1b0f247b99cb38e87825899dca58610596e2817723d0
+  actionview (8.1.3.1) sha256=2da68b8414c47b43bfbed1ce69c5afe1c04f78c267aacb5660a4cab5ca12cfb6
+  activesupport (8.1.3.1) sha256=85458765f25ea48b9019c46b6bb3fa5683197bf4280d9f06710a6e8d7a831376
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
   apollo-federation (3.10.3) sha256=61e6d8e1fd695ee45bab5d84f86f586d99c296ad77a86c6f1e7b964ac17be3d7
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   concurrent-ruby (1.3.7) sha256=4412caec3a5ea2e5fdc52076724c071a81f2c0593d83b2ac8cbb8ca63b3151b0
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
+  crass (1.0.7) sha256=94868719948664c89ddcaf0a37c65048413dfcb1c869470a5f7a7ceb5390b295
   debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   faker (3.8.0) sha256=c147b308df73a90f27a4fc84f18d4c22ef0ad9c2a64b2b61c86fd0ca71753efc
@@ -176,24 +299,44 @@ 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.6.1)
+  graph_weaver (0.7.1)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
+  hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
   json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  loofah (2.25.2) sha256=2007f746959ac65552456e04b433e83deb22759ab38c838b4445c70e43425918
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
+  mutant (0.16.3) sha256=7e10fb09b80a78d82f8e38283fc1e4d562cbb1392451e2a21611ea2bc44b5023
+  mutant-rspec (0.16.3) sha256=006ee9640800f205278604bb2160ca4b1d0013464fb216a48b7c09571a1fc547
   net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
+  nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f
+  nokogiri (1.19.4-arm64-darwin) sha256=a46db9853286e6597b36ebc6953817d15acf3a299583eb3f89fdc6f91dd63527
+  nokogiri (1.19.4-x86_64-darwin) sha256=7fd17057d3e1f00e9954a74b3cd76595d3d4a5ef233b7ed9599047c204f70551
+  nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.7) sha256=93e13e1c24f93556671d85d2d79fa228c3485815c50d7e2f265b5330c6528fb7
+  rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
+  rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
+  rails-html-sanitizer (1.7.1) sha256=e797a7c9b01e567307e317c576b49ab4168017e63eea4dba9ce3cb587e2f22c2
+  railties (8.1.3.1) sha256=2388a232579a00cefea4487de66c8553c3408c1300abdc6cf1799d86ffb04487
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   rbi (0.3.14) sha256=932ed904adbb5ca645c285c8b36da1b7ff6321ec1870d187d6325248cb637658
   rbs (4.0.3) sha256=5a7bf70e2628549d9a1f44eae447b2cfe55968a9c60cfff52693a4bdcc020e14
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
   redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
   require-hooks (0.4.0) sha256=005f4c6435b4edae73e358cdbaba48370a4121f9ce893d5d2a3c66fce855677d
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
@@ -206,6 +349,7 @@ CHECKSUMS
   rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
   simplecov (1.2.0) sha256=ea6acd05eece5a41990e2a5171c57d15700d329326c7666c85ee8c6a0dd0977e
   sorbet (0.6.13485) sha256=b885d6a2fcde57bc46c3cdd597b9014b82619dee0f811a6fdf36f57c8f82c380
   sorbet-runtime (0.6.13485) sha256=2982504e662eb424e515b3aa1c8139070451a014b6c1af2302250ed82495b4cc
@@ -217,9 +361,14 @@ CHECKSUMS
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  unparser (0.9.0) sha256=4331f174a73a23b69250b13d47da3794ed1449711ee0f9ed8947dc020ba76067
   uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  useragent (0.16.11) sha256=700e6413ad4bb954bb63547fa098dddf7b0ebe75b40cc6f93b8d54255b173844
+  webmock (3.26.4) sha256=8d8da206d217ebe6968cfb09c77f4533c23074e1432bad865f3994eacbaad50d
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
-  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
+  zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
 
 BUNDLED WITH
   4.0.10

data/README.md

@@ -39,17 +39,15 @@ result.person&.nmae
 ```
 
 `person` is `T.nilable` because the schema says the field is nullable — the `&.`
-isn't defensive, it's the schema talking. A field you misspelled, or never
-selected, is a typecheck error rather than a `NoMethodError` in production.
+isn't defensive, it's the schema talking. Static Sorbet is optional:
+`sorbet-runtime` is the only Sorbet gem this one needs, so in an app that doesn't
+run `srb tc` the same typo surfaces as a `NoMethodError` the first time the line
+runs, rather than in CI — [Sorbet, with or
+without](docs/getting_started.md#sorbet-with-or-without).
 
 ## Start here
 
-```ruby
-# Gemfile
-gem "graph_weaver"
-```
-
-In Rails, setup is one command:
+Add `gem "graph_weaver"` to your Gemfile. In Rails, the rest is one command:
 
 ```sh
 rails g graph_weaver:install https://api.example.com/graphql
@@ -59,42 +57,25 @@ which writes the initializer, the `app/graphql` layout, the editor config and th
 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
+Or skip the build step and poke at an API from a console: `GraphWeaver.new(url)`
+parses a query into a module on the spot, and `run!` executes one without a module
+at all — [against a real API](docs/real_world.md). 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
-fakes. One line in the spec helper:
-
-```ruby
-require "graph_weaver/rspec"
-```
-
-then one tag says what an example runs against:
+fakes. One line in the spec helper (`require "graph_weaver/rspec"`), then one tag
+says what an example runs against:
 
 ```ruby
 it "shows the profile", graphql: :fake do
   person = PersonQuery.execute!(id: "1").person
 
-  person.name       # => "Shakita Stark"      fabricated from your schema
+  person.name       # => "Shakita Stark"      with faker installed; "name-1" without
   person.birthday   # => #<Date: 2024-12-16>  custom scalars included
   person.pets.size  # => 2
 end
@@ -104,68 +85,51 @@ No fixture, no stub, no HTTP — and the values are seeded from rspec's own seed
 `--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
-```
+the fields it's about — `graphql_fake("Person.name" => "Ada")`, or a whole type
+off your factory — and everything else in the selection stays fabricated. Pins are
+schema names, checked and spellchecked, so a typo raises rather than leaving the
+example green against random data.
 
-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).
+The tag also picks a *real* client when you want one: `:in_process` runs your
+resolvers, `:router` runs them across a federated graph, and `:wire` serves either
+at your own endpoint, so the transport you ship runs too. 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. Part of what it prints:
-
-```
-fetches:
-  → accounts  root fields
-  → reviews   _entities × 1 User
-  → products  _entities × 2 Product
-```
-
-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
+boundary — no gateway process, no node, no sockets. It prints the plan as it
+fetches, batching every node at a level into one `_entities` call, and anything it
+can't answer *faithfully* it refuses at plan time rather than guessing, naming the
+coordinate that stopped it. It is 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).
+[`examples/federation.rb`](examples/federation.rb) runs the whole thing with no
+network; 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` 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
+changed when whatever that dump came from has moved past it, `queries:check` names
+the queries that drift broke and where, `unused` names the selections your app
+stopped reading, 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).
 
-**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.
+**Any release can change what codegen emits**, patch releases included. 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
 
-- **Queries and mutations** with typed variable kwargs — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
-- **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), `@skip`/`@include` nullability
-- **Any transport**: in-process execution, a zero-dependency HTTP client, or Faraday with your own middleware — plus a composable `Retry` with backoff and jitter
-- **Structured errors**: a typed envelope that keeps partial data and extensions, an error hierarchy split by failure site, field-level reports with entity ids, and stale-schema detection
+- **Typed variable kwargs** — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
+- **Fragments**, **unions and interfaces** (member structs, `__typename` dispatch), `@skip`/`@include` nullability
+- **Any transport** — in-process, a zero-dependency HTTP client, or Faraday with your own middleware, plus a composable `Retry`
+- **Structured errors** — an envelope that keeps partial data and extensions, a hierarchy split by failure site, field-level reports, stale-schema detection
 
 #### Dig deeper
 
@@ -175,12 +139,14 @@ upgrade, and `verify` is what tells you when you've skipped it.
 - **[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
+- **[Translating input errors](docs/i18n.md)** — stable keys and data for bad input, on either side of the wire
 - **[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
+- **[Upgrading](docs/upgrading.md)** — regenerate on every bump, and what each release moved
+- **[Alternatives](docs/alternatives.md)** — graphql-client, graphlient, artemis, hand-rolled: what each is good at, and where this one loses
 
 ----
 ## Development