graph_weaver 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df338e7f577c07e2941daf8e7a06af9a04e04ecfceae6c02a7e6d6619e219a0f
+  data.tar.gz: 939e9c9db69ed23b484ebd60401b96e5b51fea10aa6ee0b4e6c9a62118243302
+SHA512:
+  metadata.gz: 3eaf7a927dbde9d9eac7353a8d01623a099e5904c458113274bf347524d00567a8d0fdd3794312f2931feb9f0a7fbd212eccfdfc9b09671e646cbfd1a8d35294
+  data.tar.gz: cc4ae772c0c38f3cb547d37ddc88821a1eb9172d8df42c4b0608242c0df19ca4ad669e246c72806fc53701be95fa7a4a4945723725075812ecf4ec602bcd63f0

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+###  v0.0.1  (2026-07-07)
+- voila: typed codegen (T::Structs, T::Enums, typed variable kwargs)
+- queries + mutations; fragments, unions, interfaces, enums, custom scalars
+- schema sources: live class, introspection JSON, SDL (incl. supergraph)
+- pluggable executor: in-process schema or HTTP
+- dynamic (no-build) mode for development

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,176 @@
+PATH
+  remote: .
+  specs:
+    graph_weaver (0.0.1)
+      graphql (>= 2)
+      sorbet-runtime
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.4)
+    erubi (1.13.1)
+    fiber-storage (1.0.1)
+    graphql (2.6.5)
+      base64
+      fiber-storage
+      logger
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    netrc (0.11.0)
+    parallel (2.1.0)
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    rbi (0.3.14)
+      prism (~> 1.0)
+      rbs (>= 4.0.1)
+    rbs (4.0.3)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    require-hooks (0.4.0)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubydex (0.2.7-aarch64-linux)
+    rubydex (0.2.7-arm64-darwin)
+    rubydex (0.2.7-x86_64-darwin)
+    rubydex (0.2.7-x86_64-linux)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    sorbet (0.6.13323)
+      sorbet-static (= 0.6.13323)
+    sorbet-runtime (0.6.13323)
+    sorbet-static (0.6.13323-aarch64-linux)
+    sorbet-static (0.6.13323-universal-darwin)
+    sorbet-static (0.6.13323-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13323)
+      sorbet (= 0.6.13323)
+      sorbet-runtime (= 0.6.13323)
+    spoom (1.8.3)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.3.14)
+      rbs (>= 4.0.0.dev.5)
+      rexml (>= 3.2.6)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.19.2)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (>= 0.3.7)
+      require-hooks (>= 0.2.2)
+      rubydex (>= 0.1.0.beta10)
+      sorbet-static-and-runtime (>= 0.6.12698)
+      spoom (>= 1.7.16)
+      thor (>= 1.2.0)
+      tsort
+    thor (1.5.0)
+    tsort (0.2.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  aarch64-linux
+  arm64-darwin
+  universal-darwin
+  x86_64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  debug
+  graph_weaver!
+  rspec
+  simplecov
+  sorbet
+  tapioca
+  webrick
+
+CHECKSUMS
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
+  debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
+  erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
+  fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
+  graph_weaver (0.0.1)
+  graphql (2.6.5) sha256=1051825bfb4aedb4293cdbcd9726c3150e69e3512556609a32c2ca19d4be3d00
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  rbi (0.3.14) sha256=932ed904adbb5ca645c285c8b36da1b7ff6321ec1870d187d6325248cb637658
+  rbs (4.0.3) sha256=5a7bf70e2628549d9a1f44eae447b2cfe55968a9c60cfff52693a4bdcc020e14
+  rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  require-hooks (0.4.0) sha256=005f4c6435b4edae73e358cdbaba48370a4121f9ce893d5d2a3c66fce855677d
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubydex (0.2.7-aarch64-linux) sha256=9a016039f7e94e55cd812e073d310de7effcce4cac560edd1185e1ce6b5b4eb0
+  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
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  sorbet (0.6.13323) sha256=78b2d4b17fe171b2facd636033ce6e0be8544aa776b7713216209ba015d911d3
+  sorbet-runtime (0.6.13323) sha256=cf9c4e6793e1a9ef69bd96e3a006e0fd1fead429f4e4370163460bf569a23518
+  sorbet-static (0.6.13323-aarch64-linux) sha256=33d428073b491970b1b2528d6a89c4f104fdaf7f8752c6489f120040faafc5c4
+  sorbet-static (0.6.13323-universal-darwin) sha256=35ea7cca7011adea28fd7aa18002aff7f242365d829ca31219ad5e723fe28270
+  sorbet-static (0.6.13323-x86_64-linux) sha256=8ce81180e0e91394a87bf39722ff797f90315d71e29559f015716b3512347373
+  sorbet-static-and-runtime (0.6.13323) sha256=04b636933a28c8adedc81ad469f25d3a59b8a3eceaeef9accd6a92e2066d461d
+  spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
+  tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+
+BUNDLED WITH
+  4.0.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Daniel Pepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,13 @@
+.PHONY: check generate test tc
+
+# full verify loop: regenerate, test, typecheck
+check: generate test tc
+
+generate:
+	bundle exec ruby bin/generate
+
+test:
+	bundle exec rspec
+
+tc:
+	bundle exec srb tc

data/NOTES.md

@@ -0,0 +1,182 @@
+Research notes — graphql-client exploration → GraphWeaver
+======
+
+**What this is now:** a working prototype of a standalone, Sorbet-typed
+GraphQL client for Ruby — "graphql-codegen for Ruby". `.graphql` queries +
+a schema (live class, introspection JSON, or SDL) generate `# typed: strict`
+Ruby: nested `T::Struct`s, casting code, and a typed `execute`, so `srb tc`
+sees the exact shape of every query result. It is **not** a graphql-client
+extension: generated code depends only on `graphql` (generation time) and
+`sorbet-runtime` (runtime); transport is a pluggable `executor:` (in-process
+schema or the bundled `HttpExecutor`).
+
+Start with `PLAN.md` for current state and next steps. Key files:
+`lib/struct_codegen.rb` (the generator), `queries/` → `bin/generate` →
+`lib/generated/` (the build loop), `StructCodegen.load` (build-free dynamic
+mode for development).
+
+**How it got here:** the repo began as an exploration of
+[graphql-client](https://github.com/github-community-projects/graphql-client)
+internals — could its class-generation layer be swapped to emit custom
+classes? (Yes: the `StructTypes` spike below.) The per-query codegen
+approach then outgrew graphql-client entirely, and everything below the
+next heading is preserved as the lab notebook: findings in chronological
+order, each backed by a spec.
+
+The specs are the documentation — each one asserts an observed behavior:
+
+```
+bundle exec rspec
+```
+
+## Findings, in exploration order
+
+- The client runs fine against an in-process schema: `GraphQL::Client.new(schema: Schema, execute: Schema)` — no HTTP involved.
+- Each query selection gets its own dynamically generated wrapper class (subclass of `GraphQL::Client::Schema::ObjectClass`); fields are snake_case readers, and unselected fields raise instead of returning nil.
+- **Custom scalars are deserialized automatically** when the client is built from a live schema class: the reader casts wire values through the scalar's `coerce_input` (e.g. `"1990-06-15"` → `Date`). This is the built-in hook for producing rich Ruby values.
+  - Caveat: this only works with `schema:` as a live schema class. A schema loaded from an introspection JSON dump has no coercion logic, so scalars would stay raw.
+- `to_h` returns the raw wire values (strings), not the casted ones — hydration code should read via the typed readers, not `to_h`.
+- Hydrating into `T::Struct`s is straightforward manually; the interesting next step is generating the structs (or a generic hydrator) from the parsed query definition, since the client already knows each selection's shape and types.
+
+## Swapping the class-generation layer (answered: yes)
+
+`lib/struct_types.rb` + `spec/struct_types_spec.rb` prove the generation layer
+can be replaced wholesale — the client deserializes straight into generated
+`T::Struct`s, no `ObjectClass` involved.
+
+How the pipeline hangs together (graphql-client 0.26.0):
+
+- `Client#initialize` builds the types module: `@types = Schema.generate(schema)`
+  (`attr_reader :types`, no setter — swap via `instance_variable_set` or a subclass).
+- `Client#parse` → `Definition#initialize` calls
+  `client.types.define_class(definition, ast_nodes, type)` and stores the result
+  as `definition.schema_class`. This is the ONLY thing the client asks of the
+  types module.
+- `Client#query` → `definition.new(data, errors)` → `schema_class.new(data, errors)`.
+- Everything below that is the `cast(value, errors)` protocol, composed
+  recursively per the query selection (NonNull/List wrappers, scalars, objects).
+
+So the replacement contract is just:
+- `define_class(definition, ast_nodes, type)` returning casters
+- casters respond to `cast(value, errors)`
+- the top-level caster must satisfy `Definition#new`'s case dispatch, which
+  tests `===` against the `GraphQL::Client::Schema::ObjectType` module —
+  including that module in your caster class is enough, plus a
+  `new(data, errors)` method
+
+Gotchas found:
+- the client injects `__typename` into every selection (`QueryTypename`), so a
+  custom generator must skip/handle `__`-prefixed fields
+- scalar casting reuses the schema type's `coerce_isolated_input` — same hook
+  the stock `ScalarType` uses
+- prop nullability comes for free from the type walk: everything is
+  `T.nilable` unless wrapped in NON_NULL
+
+## Sorbet
+
+- `sorbet` + `tapioca` are set up (`bundle exec srb tc` is green); rbis in `sorbet/rbi/gems`
+- `struct_types.rb` typechecks at `# typed: true`
+- generated structs are real `T::Struct`s: schema-derived prop types
+  (`T.nilable(Date)`, `T::Array[StructTypes::Pet]`) and runtime type
+  enforcement on bad wire data
+
+## Codegen: srb tc sees query result types (answered: yes)
+
+`lib/struct_codegen.rb` goes one step further than the runtime swap: it
+emits plain `# typed: strict` Ruby source from a query + schema — nested
+`T::Struct` classes, fully generated `from_h` casting code (no runtime
+reflection), and a sig'd `execute`.
+
+- source of truth: `queries/*.graphql`; regenerate with `bin/generate`
+  into `lib/generated/`; a spec asserts the checked-in output is current
+- queries are validated against the schema at generation time
+- `srb tc` statically checks result access end to end:
+  `result.person&.nmae` → `Method nmae does not exist on
+  PersonQuery::Result::Person`
+- custom scalar deserialization is inlined by the generator
+  (`Date.iso8601(...)`) via a scalar registry; nullability and list
+  casting come from the NON_NULL/LIST walk
+- note: generated `execute` runs against the schema directly, replacing
+  graphql-client at runtime entirely — the client's remaining value here
+  would be its HTTP adapter, which the generated code could target instead
+
+## Fragments & unions (answered for codegen)
+
+`queries/search.graphql` + `lib/generated/search_query.rb` exercise the
+design:
+
+- inline fragments and named fragment spreads are flattened into their
+  matching member's selection (exact type-name condition match; interface
+  conditions still open)
+- unions emit a module per selection site: one `T::Struct` per possible
+  type, a `Type = T.type_alias { T.any(...) }`, and a `from_h` that
+  dispatches on `__typename` — codegen refuses union selections that
+  don't select `__typename`
+- every possible type gets a member struct even without a fragment (it
+  still carries `__typename`), so dispatch is total
+
+## Introspection / __type metadata
+
+- `__type` / `__schema` queries work against the demo schema as expected
+  (see `spec/introspection_spec.rb` for the shapes)
+- the key result: `GraphQL::Schema.from_introspection(Demo::Schema.as_json)`
+  produces a schema that codegen runs against **byte-identically** — so
+  generation works for remote APIs known only via an introspection dump.
+  Custom scalar handling survives because the codegen scalar registry is
+  keyed by type *name*, unlike runtime `coerce_input` which needs the live
+  schema class (the caveat that broke graphql-client's scalar casting)
+
+## Federation / supergraph
+
+- join__/link-annotated supergraph SDL parses via
+  `GraphQL::Schema.from_definition`, and codegen runs against it
+  unchanged — the directives are transparent to result typing
+  (`spec/federation_spec.rb` generates from a mini supergraph and casts a
+  response with no live subgraphs)
+- gotcha: graphql-ruby's SDL builder does not apply directive-argument
+  defaults, so real Apollo `join v0.3` SDL (non-null defaulted args like
+  `extension: Boolean! = false`) fails to load unless those args are
+  provided or the directive defs are trimmed — a compatibility issue a
+  real tool would need to patch around
+- client-side, federation needs nothing more: you query the router like
+  any schema. The *server-side* angle (emitting `@key`/`@external` via
+  apollo-federation) is a separate exploration — potentially relevant to
+  autographql
+
+## Round 2: enums, interface conditions, loaders, dynamic mode, HTTP
+
+- **enums** generate `T::Enum` classes (`Species::Dog`), deserialized via
+  `Species.deserialize(...)` in `from_h`; values sorted so output is
+  deterministic across schema sources
+- **interface fragment conditions** (`... on Named { name }`) apply via
+  `schema.possible_types`, not just exact type-name match. Interface-typed
+  *fields* (a field returning `Named`) are still open — they'd emit like
+  unions with `__typename` dispatch
+- **SchemaLoader** accepts both formats a remote service can hand you:
+  introspection dump (`.json`) or SDL (`.graphql`/`.gql`); both generate
+  byte-identically to the live schema class
+- **dynamic mode**: `StructCodegen.load(...)` generates + evals in one
+  step — no build artifact, same runtime semantics, right for development
+  or one-off scripts. Tradeoff: the module is invisible to `srb tc`, so
+  static checking of result access needs the build step
+- **HTTP transport**: generated `execute` takes `executor:` — anything
+  with `execute(query, variables:)` returning `{"data" => ...}`.
+  `HttpExecutor` (Net::HTTP POST) runs the same generated structs against
+  a live server (`spec/http_spec.rb` proves it against a local WEBrick
+  serving Demo::Schema)
+- **directive defaults gap**: root cause found —
+  `BuildFromDefinition#prepare_directives` passes only usage-site args
+  while `Directive#initialize` validates all defined args without
+  applying `default_value`. `lib/directive_defaults_patch.rb` prepends
+  the fix; the federation spec now loads the *real* join v0.3 SDL.
+  Present in graphql 2.6.3 (latest) — worth an upstream issue/PR
+
+## Open questions
+
+- interface-typed fields (vs fragment conditions, which work)
+- name collisions: the generator disambiguates one level (field-name
+  prefix) and raises otherwise. A real gem needs a *stable* naming scheme:
+  names shouldn't shift when unrelated selections are added (generated
+  code is checked in and referenced by app code), which argues for
+  path-based or explicitly-aliased names over first-come-first-served
+- mutations/subscriptions (only query operations generate)

data/PLAN.md

@@ -0,0 +1,74 @@
+# Project Plan — typed GraphQL codegen for Ruby/Sorbet
+
+_Resume-from-here notes. The README is the lab notebook (findings); this is
+the plan. Update both when state changes._
+
+## Vision
+
+A "graphql-codegen for Ruby": `.graphql` queries + a schema (live class,
+introspection JSON, or SDL) → checked-in `# typed: strict` Ruby — nested
+T::Structs, generated casting, typed execute — so `srb tc` sees the exact
+shape of every query result. Dynamic (eval) mode for development, build
+step for CI/static checking. Runtime deps: graphql + sorbet-runtime only
+(graphql-client is NOT a dependency; the exploration outgrew it).
+
+## State: working prototype, all green
+
+`bundle exec rspec` (35 examples) + `bundle exec srb tc` + `bin/generate`
+(regenerates lib/generated/ from queries/; parity specs enforce freshness).
+
+Language coverage: queries, mutations, typed variables (kwargs on execute,
+optional-when-defaulted, enum/scalar serialization), fragments (inline,
+named, interface conditions), union- AND interface-typed fields
+(__typename dispatch, required at generation time), enums (T::Enum),
+custom scalars (name-keyed SCALAR_CASTS / SCALAR_SERIALIZERS registries).
+Sources: live schema / introspection JSON / SDL — byte-identical output
+(enum values + abstract-type members sorted for determinism).
+Transport: executor: kwarg — in-process schema or HttpExecutor (e2e spec
+against WEBrick). Federation supergraph SDL loads transparently (needs
+directive_defaults_patch until upstream fix ships).
+
+## Next steps (in rough order)
+
+~~Extraction~~ DONE 2026-07-07: this repo IS the gem now — GraphWeaver,
+github.com/dpep/graph_weaver, rspec-uuid conventions throughout. The
+graphql-client spikes live in git history (tag: `exploration`) and
+NOTES.md. Prior-art check partially answered: graphql-client PR #7
+(tapioca compiler over schema-wide dynamic classes) stalled since
+Jan 2024 with users asking; schema-wide typing can't catch
+unfetched-field bugs or type unions/interfaces — the niche looks open.
+
+1. Stable class naming design — names come from GraphQL type names per
+   selection site; must not shift when unrelated selections are added
+   (generated code is app-code API). Current: one-level field-name
+   disambiguation, then raise.
+2. Input objects as variables (raise NotImplementedError today) — likely
+   generated T::Structs with serialize.
+3. CLI entrypoint (graph_weaver generate --schema X --queries dir) —
+   bin/generate is spec-fixture tooling, not shipped.
+4. Subscriptions (unsupported; raise).
+5. First release: 0.1.0 to rubygems once naming design settles.
+6. Nice-to-haves: __typename auto-injection (currently required manually
+   on abstract selections), fragment reuse across queries, directives on
+   selections (@skip/@include make non-null fields nullable).
+7. Tapioca DSL compiler over dynamic mode (idea from graphql-client
+   PR #7): RBI the GraphWeaver::Codegen.load-eval'd modules so development mode
+   gets static types without the bin/generate build step — tapioca is
+   already in every Sorbet shop's workflow. Upstream's
+   Tapioca::Dsl::Helpers::GraphqlTypeHelper is prior art for type mapping.
+
+## External dependencies
+
+- rmosolgo/graphql-ruby#5659 (directive-argument defaults fix; our branch
+  `directive-argument-defaults` in ~/code/lib/ruby/graphql, pushed to the
+  dpep fork, PR in draft). When it ships in a release: bump graphql,
+  delete lib/graph_weaver/directive_defaults_patch.rb + its requires (TODO in file).
+
+## Gotchas worth remembering
+
+- graphql-ruby to_definition/from_introspection reorder enum values and
+  possible_types — codegen sorts both; keep any new emission deterministic
+- schemas built from introspection/SDL have no scalar coercion or
+  resolvers — codegen must stay name-keyed, never call schema runtime hooks
+- graphql-client (the gem) casts scalars via coerce_isolated_input and
+  only with a live schema class — documented in the early specs

data/README.md

@@ -0,0 +1,87 @@
+GraphWeaver
+======
+![Gem](https://img.shields.io/gem/dt/graph_weaver?style=plastic)
+[![codecov](https://codecov.io/gh/dpep/graph_weaver/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/graph_weaver)
+
+A typed GraphQL client for Ruby, built for federation, extensibility, Sorbet, and testing.
+
+GraphWeaver generates `# typed: strict` Ruby from your queries: nested `T::Struct`s, casting code, and a typed `execute` — so `srb tc` sees the exact shape of every query result, and a typo'd field is a static error, not a runtime surprise.
+
+```graphql
+# queries/person.graphql
+query($id: ID!) {
+  person(id: $id) {
+    name
+    birthday
+    pets { name }
+  }
+}
+```
+
+```ruby
+result = PersonQuery.execute(id: "1")
+
+result.person&.name       # => "Daniel" (typed String)
+result.person&.birthday   # => Date (custom scalars deserialize)
+result.person&.nmae       # => srb tc: Method `nmae` does not exist
+```
+
+####  Features
+
+- **Queries and mutations** with typed variable kwargs — required vs optional falls out of nullability and defaults
+- **Fragments** (inline, named, interface conditions), **unions and interfaces** (member structs, `__typename` dispatch), **enums** (`T::Enum`), **custom scalars** (pluggable registry)
+- **Any schema source**: live schema class, introspection JSON, or SDL — including Apollo Federation supergraph SDL
+- **Any transport**: in-process schema execution (perfect for tests) or HTTP via the bundled executor — swap per call with `executor:`
+- **Dynamic mode** for development: `GraphWeaver::Codegen.load(...)` generates and evals on the fly, no build step
+
+####  Usage
+
+```ruby
+require "graph_weaver"
+
+# generate from any schema source
+schema = GraphWeaver::SchemaLoader.load("schema.json")   # or .graphql SDL, or a live class
+
+source = GraphWeaver::Codegen.new(
+  schema:,
+  executor_const: "MyApi::Executor",
+  query: File.read("queries/person.graphql"),
+  module_name: "PersonQuery",
+).generate
+
+File.write("app/queries/person_query.rb", source)
+
+# at runtime
+executor = GraphWeaver::HttpExecutor.new("https://api.example.com/graphql")
+PersonQuery.execute(id: "1", executor:)
+```
+
+In development, skip the build step:
+
+```ruby
+PersonQuery = GraphWeaver::Codegen.load(schema:, executor_const: "...", query:, module_name: "PersonQuery")
+```
+
+----
+## Installation
+
+```ruby
+# Gemfile
+gem "graph_weaver"
+```
+
+or
+
+```
+gem install graph_weaver
+```
+
+----
+## Development
+
+`make check` — regenerate spec fixtures, run specs, typecheck.
+
+See `PLAN.md` for roadmap and `NOTES.md` for the research notebook this
+gem grew out of (an exploration of graphql-client internals — GraphWeaver
+is a standalone client, not an extension; it depends only on `graphql`
+and `sorbet-runtime`).

data/graph_weaver.gemspec

@@ -0,0 +1,24 @@
+require_relative "lib/graph_weaver/version"
+
+Gem::Specification.new do |s|
+  s.authors     = ["Daniel Pepper"]
+  s.description = "A typed GraphQL client for Ruby — generate Sorbet T::Structs from queries, with federation, extensibility, and testing in mind"
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin'`.split("\n")
+  s.homepage    = "https://github.com/dpep/graph_weaver"
+  s.license     = "MIT"
+  s.name        = "graph_weaver"
+  s.summary     = "GraphWeaver"
+  s.version     = GraphWeaver::VERSION
+
+  s.required_ruby_version = ">= 3.3"
+
+  s.add_dependency "graphql", ">= 2"
+  s.add_dependency "sorbet-runtime"
+
+  s.add_development_dependency "debug"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "sorbet"
+  s.add_development_dependency "tapioca"
+  s.add_development_dependency "webrick"
+end