graph_weaver 0.6.1 → 0.7.0

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.0)
       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)
+    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.0)
   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
+  zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
 
 BUNDLED WITH
   4.0.10

data/README.md

@@ -41,6 +41,10 @@ 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.
+Static Sorbet is optional: `sorbet-runtime` is the only Sorbet gem this one
+needs, so if your app doesn't run `srb tc`, that same typo surfaces as a
+`NoMethodError` the first time the line runs instead of in CI — [Sorbet, with or
+without](docs/getting_started.md#sorbet-with-or-without).
 
 ## Start here
 
@@ -63,6 +67,11 @@ 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.
 
+A second schema is a second `GraphWeaver.graph` — its own queries, output,
+client, namespace and scalar registrations — and the same one command generates
+and verifies the app: **[more than one
+schema](docs/getting_started.md#more-than-one-schema)**.
+
 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:
 
@@ -94,7 +103,7 @@ then one tag says what an example runs against:
 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
@@ -119,7 +128,8 @@ reads the selected fields off your factory's object and fabricates the rest. The
 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
+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
@@ -150,8 +160,10 @@ See [federation](docs/federation.md).
 
 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.
+changed when whatever that dump came from — an endpoint, your own schema class —
+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).
@@ -162,7 +174,7 @@ 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
+- **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. Results are generated per selection set; an input object has no selection set, so [its whole closure is](docs/generated_modules.md#an-input-object-generates-its-whole-closure)
 - **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
@@ -175,12 +187,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

data/docs/alternatives.md

@@ -0,0 +1,201 @@
+# Alternatives
+
+Why another Ruby GraphQL client, what else exists, and where each one wins.
+Read it before adopting — including the last section, which is where this gem
+loses.
+
+*Figures checked 2026-09-12. Every claim carries its source in an HTML comment
+beside it; a maintainer re-checking this page should follow those, not trust the
+prose.*
+
+## Why another one
+
+Ruby has **one** real GraphQL client — GitHub's `graphql-client` — and the two
+maintained alternatives are wrappers around it.<!-- graphlient.gemspec deps: faraday ~>2.0, graphql-client; artemis.gemspec deps include graphql-client >= 0.13.0 — https://rubygems.org/api/v1/gems/graphlient.json, https://rubygems.org/api/v1/gems/artemis.json -->
+All three share one design: the result object is built at runtime by
+metaprogramming against an introspected schema, so a field you misspelled is a
+`NoMethodError` on a production request rather than a red build.<!-- graphql-client lib/graphql/client/schema/object_type.rb:231-266 — method_missing raises UnimplementedFieldError/UnfetchedFieldError at runtime; a camelCase typo re-raises plain NoMethodError at :248-250 -->
+And none of them ship anything to test with.<!-- graphql-client: no fakes/stubs/fixtures anywhere in lib/, no testing guide among its 14 guides — https://github.com/github-community-projects/graphql-client/tree/master/guides -->
+
+GraphWeaver makes a different structural bet: **the schema is known at
+generation time**, so result types can be real files on disk that `srb tc`
+reads, and the same knowledge that makes them exact is what lets the gem
+fabricate them for your tests. That second half is the part every code generator
+in every language skips — and it is the reason precise types usually feel
+expensive.
+
+The honest counter: if your app doesn't use Sorbet, most of that value
+evaporates, and [graphlient](#graphlient) is the better answer.
+
+This idea was tried once before. `yogurt` generated Sorbet types from GraphQL
+documents, shipped two versions 70 minutes apart in November 2020, and stopped —
+its own README concedes it lacked named fragments and that the author "probably
+got a lot of the decisions wrong".<!-- https://raw.githubusercontent.com/theorygeek/yogurt/master/README.md ; versions 0.1.1 16:52 and 0.2.0 18:02 on 2020-11-26 — https://rubygems.org/api/v1/versions/yogurt.json ; last real commit 29ef902 2020-11-26 -->
+So the thesis is unproven, not proven wrong.
+
+## The table
+
+`graphql-ruby` isn't a column because it isn't a client — see
+[graphql-ruby alone](#graphql-ruby-alone). "Hand-rolled" is `Net::HTTP` or
+Faraday plus a query string and `response["data"]["..."]`, which is what most
+vendor SDKs actually do.
+
+| | **graph_weaver** | **graphql-client** | **graphlient** | **artemis** | **hand-rolled** |
+|---|---|---|---|---|---|
+| **Query lives in** | a `.graphql` file, one operation each<!-- README.md; DECISIONS.md "Directories organize queries" --> | a heredoc assigned to a Ruby constant (enforced)<!-- lib/graphql/client.rb:345-347 raises DynamicQueryError when definition.name is nil --> | a heredoc, a Ruby block DSL, or `parse`<!-- https://github.com/ashkan18/graphlient#usage ; lib/graphlient/query/serializer.rb --> | a `.graphql` file under `app/operations`<!-- https://github.com/yuki24/artemis#the-convention --> | a string in your code |
+| **A result is** | a checked-in nested `T::Struct`<!-- README.md; lib/graph_weaver/result_struct.rb --> | an anonymous class, readers per selected field<!-- lib/graphql/client/schema/object_type.rb:10-22, 56-60 --> | the same (it returns graphql-client's `Response`)<!-- lib/graphlient/client.rb:41 --> | the same<!-- artemis lib/artemis/client.rb #execute delegates to client.query --> | a `Hash` |
+| **A typo is caught** | at `srb tc`, before you run it | at runtime, on the request<!-- object_type.rb:243-266 --> | at runtime | at runtime | never |
+| **Schema needed** | at codegen time: live class, introspection dump, SDL, or supergraph<!-- README.md; lib/graph_weaver/schema_loader.rb --> | at boot: dump recommended; SDL support merged but unreleased<!-- README.md:34-42; https://github.com/github-community-projects/graphql-client/pull/60 merged 2025-12-06, not in 0.26.0 --> | at runtime: introspects over HTTP lazily unless you pass `schema_path`<!-- lib/graphlient/schema.rb:16; lib/graphlient/client.rb:76 --> | a checked-in dump per service<!-- lib/artemis/railtie.rb schema_path vendor/graphql/schema/<service>.json --> | none |
+| **Codegen** | yes — you check the Ruby in | none, all runtime metaprogramming<!-- lib/graphql/client/schema.rb:68-81 --> | none | none | none |
+| **Typing** | Sorbet `# typed: strict`, per query<!-- README.md --> | none shipped; Tapioca PR stalled since 2024-11, and schema-wide not per-operation<!-- https://github.com/github-community-projects/graphql-client/pull/7 — open, mergeable_state blocked, last touched 2024-11-07 --> | none<!-- no .rbs/.rbi/sig in the gem --> | none | none |
+| **Testing** | schema-driven fakes, pinning, failure simulation, cassettes<!-- docs/testing.md; lib/graph_weaver/rspec.rb; lib/graph_weaver/testing/ --> | nothing ships<!-- no stub/fake/fixture in lib/ --> | documented WebMock patterns only<!-- https://github.com/ashkan18/graphlient#testing-with-graphlient-and-rspec --> | `stub_graphql` + YAML fixtures, unvalidated against the schema<!-- lib/artemis/test_helper.rb; lib/artemis/adapters/test_adapter.rb returns fixtures verbatim --> | WebMock |
+| **Federation** | plans and runs a supergraph in-process<!-- docs/federation.md; lib/graph_weaver/federation.rb --> | none; open crash against federated routers<!-- https://github.com/github-community-projects/graphql-client/issues/78 open since 2026-01-15 --> | none | none | none |
+| **Errors** | typed envelope keeping partial data, hierarchy by failure site<!-- docs/errors.md; lib/graph_weaver/errors.rb --> | raw hashes; HTTP errors become a fake `errors` array<!-- lib/graphql/client/http.rb:80-85; https://github.com/github-community-projects/graphql-client/issues/67 --> | raises a real class hierarchy on every failure<!-- lib/graphlient/errors/ --> | thin hierarchy, mostly never raised<!-- lib/artemis/exceptions.rb — GraphQLError/GraphQLServerError defined, never raised --> | yours to write |
+| **Transport** | `Net::HTTP` (pooled) or Faraday, plus `Retry`<!-- docs/transports.md; lib/graph_weaver/transport/ --> | stock adapter self-described as trivial<!-- lib/graphql/client/http.rb:17-19 "Production applications should consider implementing their own network adapter" --> | Faraday 2.x, full middleware access<!-- lib/graphlient/adapters/http/faraday_adapter.rb:36-48 --> | four adapters, no middleware layer<!-- lib/artemis/adapters.rb; https://github.com/yuki24/artemis/issues/57 open since 2019 --> | whatever you picked |
+| **Rails** | generator, railtie, reload-on-edit, rake lifecycle<!-- lib/generators/graph_weaver/install_generator.rb; lib/graph_weaver/railtie.rb; lib/graph_weaver/tasks.rb --> | opt-in railtie, no generators; docs call the boot order "a mess"<!-- lib/graphql/client/railtie.rb:34-37 TODO; https://github.com/github-community-projects/graphql-client/blob/master/guides/rails-configuration.md --> | none | the whole pitch: generators, config, callbacks<!-- lib/artemis/railtie.rb; lib/generators/artemis/ --> | n/a |
+| **Last release** | v0.7.0, 2026-09-12 | v0.26.0, 2025-05-29<!-- https://rubygems.org/api/v1/gems/graphql-client.json --> | v0.9.0, 2026-08-02<!-- https://rubygems.org/api/v1/gems/graphlient.json --> | v1.1.0, 2024-08-16<!-- https://rubygems.org/api/v1/gems/artemis.json --> | n/a |
+| **Downloads** | 7.5k<!-- 7,478 — https://rubygems.org/api/v1/gems/graph_weaver.json --> | 94M<!-- 94,408,657 --> | 32M<!-- 32,287,626 --> | 430k<!-- 425,737 --> | n/a |
+
+## graphql-client
+
+**Where it shines.** It is GitHub's, it has a decade of production use, and 94M
+downloads means someone has hit your problem before you. The duck-typed
+`execute:` slot is genuinely good design — point it at a graphql-ruby schema and
+queries run in-process with no socket.<!-- https://github.com/github-community-projects/graphql-client/blob/master/guides/local-queries.md -->
+It ships two RuboCop cops, including `GraphQL/Overfetch`, which nobody else
+has.<!-- lib/rubocop/cop/graphql/ in the unpacked gem -->
+
+**Where it gaps.** Custom scalars don't deserialize when the schema came from a
+dump — the path its own README recommends — and the suggested workaround is
+monkey-patching `GraphQL::Schema::BUILT_IN_TYPES`; the issue has been open since
+February 2024.<!-- https://github.com/github-community-projects/graphql-client/issues/17 --> Network
+errors are discarded: a 403 surfaces as `KeyError: key not found: "data"`.<!-- https://github.com/github-community-projects/graphql-client/issues/67 open since 2025-04-11 -->
+Fragments enforce Relay-style data masking, so a field another fragment fetched
+raises even though the value is right there in the response — and users file
+issues asking for plain reuse.<!-- object_type.rb:161-168, 261-264; https://github.com/github-community-projects/graphql-client/issues/76 -->
+Its CI matrix stops at Ruby 3.2 and Rails 7.1.<!-- https://github.com/github-community-projects/graphql-client/blob/master/.github/workflows/ci.yml -->
+Nine issues and seven PRs are open, several waiting on a maintainer to approve a
+CI run.<!-- gh api search/issues, repo:github-community-projects/graphql-client, 2026-09-12 -->
+
+**Pick it over graph_weaver when** institutional safety outweighs static types,
+or when you need data masking as a feature rather than a constraint.
+
+## graphlient
+
+**Where it shines.** Quietly the healthiest Ruby client: 0.9.0 shipped
+2026-08-02, more recently than graphql-client itself, adding DSL fragments,
+directives and scalar registration.<!-- https://github.com/ashkan18/graphlient/blob/master/CHANGELOG.md -->
+It fixes the failure everyone hits with its substrate — it raises a real,
+rescuable error hierarchy instead of handing you a half-populated response.<!-- lib/graphlient/errors/ --> Faraday
+means your existing middleware just works.
+
+**Where it gaps.** It is a wrapper, so it inherits graphql-client's result
+model, its fragment isolation, and its untyped everything — its own README
+offers `to_query_string` as "the escape hatch if you want to replace the
+graphql-client dependency entirely".<!-- https://github.com/ashkan18/graphlient#readme, 0.9.0 -->
+Read and write timeouts default to nil, i.e. none.<!-- README config table; lib/graphlient/adapters/http/adapter.rb:33-40 -->
+No Rails integration, no field aliasing, and 18 open issues, the most-reacted
+dating to 2017.<!-- https://github.com/ashkan18/graphlient/issues/10 ; gh api repos/ashkan18/graphlient -->
+
+**Pick it over graph_weaver when** you want to call an API without thinking
+about it. For that job graph_weaver is over-engineered, and this is the right
+answer.
+
+## artemis
+
+**Where it shines.** The best Rails story of the three: `rails g
+artemis:install` writes the client, the config and the schema dump; `.graphql`
+files map to methods by convention; `before_execute`/`after_execute` are real
+hooks; and it has the only shipped test harness among the alternatives —
+`stub_graphql(Artsy, :artist).to_return(:yayoi_kusama)` against YAML
+fixtures.<!-- lib/artemis/test_helper.rb; https://github.com/yuki24/artemis#testing -->
+It also batches, via `Client.multiplex`.<!-- lib/artemis/client.rb .multiplex/MultiplexQueue -->
+
+**Where it gaps.** Fixtures are returned verbatim — nothing checks them against
+the schema or the query's selection set, so a fixture can drift from reality and
+stay green.<!-- lib/artemis/adapters/test_adapter.rb#execute -->
+Its reloader and production preload are both gated on *not* using Zeitwerk,
+which every Rails 7+ app does, so the README's preloading claim no longer
+applies.<!-- lib/artemis/railtie.rb — graphql.client.set_reloader and graphql.client.preload both gated on not_on_zeitwerk -->
+Last release August 2024; Rails 8 support exists only on `main`, and there have
+been no commits since December 2025.<!-- gh api repos/yuki24/artemis/compare/v1.1.0...main ; last commit 8b3d76a 2025-12-04 -->
+
+**Pick it over graph_weaver when** you want convention-over-configuration Rails
+ergonomics and don't need types.
+
+## graphql-ruby alone
+
+`graphql-ruby` is a **server** library and ships no HTTP client at all — its
+only three runtime dependencies are `base64`, `fiber-storage` and `logger`, and
+the only `Net::HTTP` call in the gem fetches a checksum for graphql-pro.<!-- gem spec graphql-2.6.10.gem dependencies; lib/graphql/rake_task/validate.rb:38-44 -->
+The thing called "client" in its docs is
+[JavaScript](https://graphql-ruby.org/javascript_client/overview).
+
+What it does give a client author is the substrate everyone here builds on:
+[`GraphQL.parse`](https://graphql-ruby.org/api-doc/2.6.10/GraphQL.html),
+[`GraphQL::Schema.from_definition`](https://graphql-ruby.org/schema/sdl.html)
+and `from_introspection`, and `GraphQL::StaticValidation::Validator` for
+checking a document against a schema.<!-- lib/graphql.rb:49; lib/graphql/schema.rb:105,115; lib/graphql/static_validation/validator.rb:11-18 -->
+GraphWeaver uses exactly these — it is a code generator on top of graphql-ruby,
+not a reimplementation of it.
+
+**Subscriptions are server-side only** across the whole ecosystem: graphql-ruby
+delivers them over ActionCable and every documented consumer is
+JavaScript,<!-- https://graphql-ruby.org/subscriptions/action_cable_implementation — "See client usage for: Apollo Client, Relay Modern, GraphiQL" -->
+and no Ruby gem consumes GraphQL subscriptions over websockets.<!-- rubygems search graphql+websocket, graphql-ws, subscriptions-transport-ws all return 0 results, 2026-09-12 -->
+Nobody in Ruby has this, GraphWeaver included.
+
+## Hand-rolled HTTP — the real incumbent
+
+Most Ruby code talking to a GraphQL API isn't using a client library. It POSTs a
+string and reads a hash, and that includes the vendors' own SDKs.
+
+Shopify is the sharpest example. `shopify_api` v10 **removed** graphql-client,
+saying so in its breaking-changes doc — "There is no need to dump the schema to
+a local JSON file before using it anymore" — and the migration example replaces
+`result.data.shop.name` with `response.body["data"]["shop"]["name"]`.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/BREAKING_CHANGES_FOR_V10.md:3,115,140-159 -->
+The current gemspec declares `httparty`, `oj` and `sorbet-runtime` and no
+`graphql` at all.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/shopify_api.gemspec:35-46 -->
+The gem is `# typed: strict` throughout — and the GraphQL payload is typed
+`T.any(T::Hash[String, T.untyped], String, OpenStruct)`.<!-- https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_response.rb#L15-L16 -->
+A Sorbet shop, shipping a Sorbet-typed SDK, with untyped GraphQL. Braintree does
+the same thing without the Sorbet.<!-- https://github.com/braintree/braintree_ruby/blob/master/lib/braintree/graphql_client.rb#L13-L26 -->
+
+**Where it shines.** Zero dependencies, zero build step, nothing to learn, and
+it never gets in your way. For three queries against a stable API this is
+genuinely the correct engineering call.
+
+**Where it gaps.** Nothing validates the query, nothing knows the schema
+changed, every response is `T.untyped`, and the error handling is a 40-line
+layer you write once per project. The cost is invisible until the schema moves.
+
+**Pick it over graph_weaver when** you have a handful of queries and no
+appetite for a build step.
+
+## Where graph_weaver loses
+
+Said plainly.
+
+- **Sorbet is a hard dependency.** `sorbet-runtime` is a runtime
+  dependency,<!-- graph_weaver.gemspec: s.add_dependency "sorbet-runtime" --> and
+  the payoff — a typo caught before you run — needs `srb tc` in your build. No
+  RBS output. If Sorbet isn't in your stack, you're carrying the cost of
+  generated code for a fraction of the benefit.
+- **Codegen is a build step.** You check generated Ruby in, and regenerate on
+  every gem upgrade, because any release can change what codegen emits. `rake
+  graph_weaver:verify` exists precisely because that step is easy to skip. The
+  alternatives have no build step at all.
+- **No subscriptions.** A subscription document is refused outright:
+  `GraphWeaver::Error: unsupported operation: subscription`.<!-- lib/graph_weaver/internal/selection.rb:48 --> Nobody
+  in Ruby has this, but that doesn't make it present here.
+- **No `@defer`, no file uploads, no persisted queries, no batching.** artemis
+  has multiplex batching;<!-- lib/artemis/client.rb .multiplex --> this gem has
+  none of the four.
+- **One author, and it's new.** First commit July 2026, 4 stars, pre-1.0, and
+  about 30 breaking-change notes in the changelog so far.<!-- gh api repos/dpep/graph_weaver created_at 2026-07-07, stargazers_count 4; grep -c -i breaking CHANGELOG.md -->
+  Codegen is unforgiving and there is a lot of surface to get wrong.
+  `verify` mitigates drift; nothing mitigates the maintainer. "No static types"
+  is a cost many teams will rationally accept over that.
+
+If you read that list and none of it stops you, the thing you get in exchange is
+in [getting started](getting_started.md).

data/docs/cassettes.md

@@ -31,6 +31,17 @@ to refresh. A *request* with no recording raises
 `GraphWeaver::Testing::MissingRecording`, naming the variables it was called
 with and the ones recorded for that same query — what usually differs.
 
+**One entry per request.** The request key is the query, its variables and the
+operation name together, and a cassette holds one entry per key: re-recording a
+request *replaces* its entry, and a request the file hasn't seen appends one. So
+however often `GRAPHWEAVER_RECORD=1` runs, no cassette ends up with two entries
+for the same request.
+
+Editing a query changes the key, so the re-record writes a new entry and the old
+one stays behind — a recording of a request nothing sends any more.
+`cassettes:check` counts those ("1 not sent by any query module", below); the
+way to clear them is to delete the cassette and record it afresh.
+
 ## Has a recording gone stale?
 
 A cassette is the one artifact here recorded from *someone else's* server, and
@@ -50,7 +61,7 @@ belongs in the normal PR run beside `verify`, and exits non-zero on drift:
 
 ```
 spec/cassettes/dashboard.yml: 1 stale (3 checked, 1 not sent by any query module)
-  DashboardQuery {"id" => "b1"}
+  DashboardQuery {"id":"b1"}
     failed to cast response into DashboardQuery::Result::Me::Reviews::Book: Parameter 'price_cents': Can't set …price_cents to 4200 (instance of Integer) - need a String
 ```
 
@@ -82,6 +93,11 @@ preserving everything that makes the recording faithful:
 | enums, booleans, `__typename` | numbers, dates |
 | id *relationships* (same original id → same fake id) | the id values themselves |
 
+**Every plain string goes**, not the PII-shaped ones — nothing here can tell a
+user's name from a product's, so a recorded `"pikachu"` replays as `"name-1"`
+and an assertion pinned to it fails. Leave it off for a public, non-sensitive
+API, where the real values *are* the point of the cassette.
+
 `data` is walked against the schema — which is why it needs one, to know which
 values are enums, dates, ids. `errors` and `extensions` have none behind them,
 so they're walked by shape instead: keys, nesting and structure survive, every