graph_weaver 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef7de8e2cd115b4c757a3dac2e8c41a0e87865914e246131c1037a231f7a60af
-  data.tar.gz: fa89ee78a04a2a07b7c173c82685490ca501a2a29045ef487aae3dd6f3d915d8
+  metadata.gz: 7673fd6efc0459bdb3097e73e1c3f8fe265910bfdaf349bf7a358adc1ece1830
+  data.tar.gz: f5ce9f4c484e1fb8f5eb074eaaac502ca62fb3ecf6ab90d9157a2a055e88c3b3
 SHA512:
-  metadata.gz: 4ae73ed74389baa1f08a42e38b7bf2b0bca2f95ccbe247ccb68fda733c9fee849aed3d17dbba424bdb13104344771d9789401710a5add195c71873edc379530b
-  data.tar.gz: 24e15e7a6213c0cd5dee16aa73e675649748b84993be11387f638aeca21c15db77a59b1fa5a85ae406af7182be0f9f6a17164b842add3627a7547ab1670616d1
+  metadata.gz: a75dd5a723dd52108e2f449bd1c5f0e1dc9a71065106614c57854f318024f700e16596cd4764cf9768f02d536cc040bd0554bdd75762eeba23c09b71a7051cf5
+  data.tar.gz: 377c07a20d2cf47873425c72ad84709c36555396fea1a2102c7bdc3f79e07e8e823ed9639238aecac8066f352e65599a10ae15a71013a7de3a0a4d3675bf169c

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+###  v0.2.2  (2026-07-22)
+- Generated modules expose from_response / from_response! alongside
+  execute / execute!: deserialize a raw GraphQL response (fetched by any
+  client) into the typed envelope without going through the transport.
+  execute now delegates to from_response
+
+###  v0.2.1  (2026-07-13)
+- Conventional paths are appendable lists: queries_paths /
+  generated_paths (singular accessors read the first entry, so existing
+  config keeps working); load_generated!, Client#load_queries!, and the
+  Railtie walk every entry — append spec/support/graphql/* from a spec
+  helper to load test-only queries. Entries may be globs, and the
+  generated default includes app/graphql/*/generated so per-schema
+  layouts auto-load
+- inputs_module derives from the output path: multi-schema layouts name
+  each schema's module after its directory
+  (app/graphql/github/generated -> GithubInputs), the conventional
+  layout keeps GraphQLInputs; GraphWeaver.inputs_module= and
+  generate!(inputs_module:) still override
+- Shared types split one-file-per-type: generated/inputs/ holds each
+  input struct/enum in its own small file (PokeAPI: 573 files, median
+  24 lines vs one 11.5k-line blob) with inputs.rb as the manifest
+  (forward declarations make load order irrelevant); regeneration
+  prunes files for types the schema dropped, verify flags strays;
+  generate!/verify take inputs_module: per invocation (multi-schema
+  apps generate into different modules)
+- Shared input types: generate! emits every variable type (input
+  structs + their enums + mapped-enum tables) ONCE per schema into
+  generated/inputs.rb (module GraphQLInputs; GraphWeaver.inputs_module=
+  renames, shared_inputs: false opts out), with query modules aliasing
+  only what their own surface references — AdoptQuery::AdoptionInput
+  keeps working and shared types gain one identity across modules.
+  Three filtered Hasura queries: 34,684 lines inline -> 11,754 shared
+  (~90 lines per query module)
+- BREAKING (vs 0.2.0): auto_fake is opt-in again — require
+  "graph_weaver/rspec" no longer swaps every example onto a fake;
+  set config.auto_fake = true explicitly (the schema still auto-locates
+  once you do). Less magic, no unexpected behavior
+- Generated input structs are table-driven: typed consts + a per-field
+  FIELDS table (conversions as lambdas) interpreted by the
+  GraphWeaver::InputStruct runtime, replacing unrolled
+  serialize/coerce/value_at per struct — a bool_exp-heavy PokeAPI module
+  shrinks 29k -> 11.5k lines (-60%) with identical behavior (nil
+  omission, wire-value enums, nested/recursive coercion, spellchecked
+  unknown keys all covered by the existing suite)
+- Internal: Node base class for the codegen IR protocol; module
+  assembly moved from Codegen#generate into Emit#emit_module
+  (byte-identical output)
+
 ###  v0.2.0  (2026-07-12)
 - Cleanup pass (staff-engineer review): scalar registrations get the
   same typo validation as enums/types; cassette replay stops recomputing

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.2.0)
+    graph_weaver (0.2.2)
       graphql (>= 2)
       sorbet-runtime
 
@@ -19,7 +19,6 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    docile (1.4.1)
     erb (6.0.4)
     erubi (1.13.1)
     faker (3.8.0)
@@ -43,7 +42,7 @@ GEM
     google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    graphql (2.6.5)
+    graphql (2.6.6)
       base64
       fiber-storage
       logger
@@ -100,21 +99,16 @@ GEM
     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.13327)
-      sorbet-static (= 0.6.13327)
-    sorbet-runtime (0.6.13327)
-    sorbet-static (0.6.13327-aarch64-linux)
-    sorbet-static (0.6.13327-universal-darwin)
-    sorbet-static (0.6.13327-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13327)
-      sorbet (= 0.6.13327)
-      sorbet-runtime (= 0.6.13327)
+    simplecov (1.0.2)
+    sorbet (0.6.13347)
+      sorbet-static (= 0.6.13347)
+    sorbet-runtime (0.6.13347)
+    sorbet-static (0.6.13347-aarch64-linux)
+    sorbet-static (0.6.13347-universal-darwin)
+    sorbet-static (0.6.13347-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13347)
+      sorbet (= 0.6.13347)
+      sorbet-runtime (= 0.6.13347)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -172,7 +166,6 @@ CHECKSUMS
   concurrent-ruby (1.3.7) sha256=4412caec3a5ea2e5fdc52076724c071a81f2c0593d83b2ac8cbb8ca63b3151b0
   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
   faker (3.8.0) sha256=c147b308df73a90f27a4fc84f18d4c22ef0ad9c2a64b2b61c86fd0ca71753efc
@@ -183,8 +176,8 @@ 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.2.0)
-  graphql (2.6.5) sha256=1051825bfb4aedb4293cdbcd9726c3150e69e3512556609a32c2ca19d4be3d00
+  graph_weaver (0.2.2)
+  graphql (2.6.6) sha256=7438e2036b571c884377eb1529225470ba959365f26dc47152953c213bc38c31
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
@@ -213,15 +206,13 @@ 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
-  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
-  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
-  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
-  sorbet (0.6.13327) sha256=4b56cb04542661c6bf5075f1ca38ca00506045325fd689f460aee8466dd3d7a3
-  sorbet-runtime (0.6.13327) sha256=86f32b2df6d266bf5c0e0eb8ea81d0376ba36eece4c8610938174e403222948d
-  sorbet-static (0.6.13327-aarch64-linux) sha256=da8a575785d34641095631c50fe1d1f645ee8782c8e2aa5a0ecfd12d1fa22a8a
-  sorbet-static (0.6.13327-universal-darwin) sha256=a2a8c6b624aada3f6ef68852398de756248f71b3ea691119873515847010dcda
-  sorbet-static (0.6.13327-x86_64-linux) sha256=f3a915bab4af1979145c793a08d3b1db207526d5e2f332513da10a95e70f9028
-  sorbet-static-and-runtime (0.6.13327) sha256=7b039be023b6a7d2d17b1f751191f32307d9ace4170b6a192bb0e005d222e00e
+  simplecov (1.0.2) sha256=c6459434efe4b948b46477cc2df2faa73ab365f83a33c7c17f81262f4f7f1244
+  sorbet (0.6.13347) sha256=2830946e6efda8dc732c5d703350bed17f437fbea1ccfbef543a65e33ae445c1
+  sorbet-runtime (0.6.13347) sha256=54e7221d9f4b63f58aec79f3043752a9ba7810347c6ae0d903531591cc2d5f01
+  sorbet-static (0.6.13347-aarch64-linux) sha256=9bb60509bf9a8715d93e77cd55f96659575d81a5f47b52bd4f66b3dfe6f2182e
+  sorbet-static (0.6.13347-universal-darwin) sha256=d12678a45369dba9db724103d8badda995e66a83ae35798f68d804c46a6d3e45
+  sorbet-static (0.6.13347-x86_64-linux) sha256=5a4803d2ba4fc1964e23f3aa4073b224c345c2a72a5f5317623a4bae7ce2c8da
+  sorbet-static-and-runtime (0.6.13347) sha256=2130e3c20326948a3edd20385b444345cb7327eea9b141f373486e7c087a498d
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/PLAN.md

@@ -105,6 +105,13 @@ Response envelope; execute! for raise-or-result).
 
 ## From the field-test experiments (2026-07-12)
 
+Generated-module size (2026-07-12, post-0.2.0): input structs are now
+table-driven (InputStruct runtime + FIELDS) — the PokeAPI filtered-query
+module dropped 29,233 -> 11,562 lines. The floor is ~2 lines/field
+(typed const + FIELDS entry). Remaining lever if it matters again:
+shared input structs emitted once per schema instead of per module.
+
+
 A junior + senior agent pair exercised the repo cold (clone, examples,
 extensions, a Pokedex app against Hasura's 4,441-type PokeAPI schema).
 Fixed same-day: snake_case type names generated invalid constants

data/docs/generated_modules.md

@@ -21,7 +21,10 @@ fails when the two drift. The conventional layout (configurable via
 app/graphql/
   schema.json        # introspection dump (or schema.graphql SDL)
   queries/           # *.graphql — hand-written, reviewed
-  generated/         # *_query.rb — generated, checked in, never edited
+  generated/
+    inputs.rb        # manifest: requires + forward declarations
+    inputs/          # one file per shared type (input structs, enums)
+    *_query.rb       # one module per query — generated, checked in, never edited
 ```
 
 The schema dump is step 0 — codegen reads it, never a live endpoint.
@@ -58,6 +61,20 @@ first). Elsewhere it's explicit, factory_bot-style:
 GraphWeaver.load_generated!   # require every file under generated_path
 ```
 
+The conventional paths are lists (entries may be globs — the default
+includes `app/graphql/*/generated`, so per-schema layouts load too).
+Append extra locations (a test-only schema, an engine's queries) and
+every loader walks them all:
+
+```ruby
+# e.g. in spec/support/graph_weaver.rb
+GraphWeaver.generated_paths << "spec/support/graphql/generated"
+GraphWeaver.queries_paths << "spec/support/graphql/queries"
+```
+
+The singular accessors (`generated_path` etc.) read and replace the
+first entry — the default target for `generate!` and the rake tasks.
+
 (Plain requires, not Zeitwerk: Zeitwerk would expect
 `Generated::PersonQuery` from `generated/person_query.rb`, and generated
 code only changes on regeneration — restart, like a schema migration.)
@@ -102,6 +119,9 @@ module PersonQuery
   def self.client ...            # default client (see below)
   def self.execute(client = nil, id:)   # -> GraphWeaver::Response[Result]
   def self.execute!(client = nil, id:)  # -> Result, or raises QueryError
+
+  def self.from_response(response)      # deserialize a raw hash -> Response[Result]
+  def self.from_response!(response)     # -> Result, or raises QueryError
 end
 ```
 
@@ -110,6 +130,38 @@ end
   cost/throttle metadata survive.
 - `execute!` is the shortcut: the typed result or a raised
   `GraphWeaver::QueryError`.
+- `from_response` / `from_response!` are the **network-free half** of the
+  pair — same envelope, but from a response hash you already have (see below).
+
+## Deserializing a response from another client
+
+`execute` is two steps: make the request, then cast the JSON into the typed
+structs. Only the second step is GraphWeaver-specific, and it's exposed on its
+own — so you can fetch with any GraphQL client (Apollo, a raw `Net::HTTP` post,
+a batching layer, a recorded fixture) and hand the result to GraphWeaver:
+
+```ruby
+raw = my_graphql_client.post(PersonQuery::QUERY, id: "1")
+# => {"data" => {"person" => {...}}, "errors" => [...], "extensions" => {...}}
+
+response = PersonQuery.from_response(raw)   # GraphWeaver::Response[Result]
+person   = response.data!.person            # typed, no network
+
+# or skip the envelope:
+person   = PersonQuery.from_response!(raw).person
+```
+
+`from_response` builds the exact same `GraphWeaver::Response[Result]` envelope
+`execute` does — in fact `execute` *is* `from_response(transport.execute(...))`.
+Errors and extensions are preserved; `#data!` / `from_response!` raise
+`QueryError` on top-level errors.
+
+The one requirement: pass the response **verbatim** — a hash (or anything with
+`#to_h`) with the standard GraphQL shape and **wire-cased string keys**
+(`"person"`, `"nameWithOwner"`), the top-level `"data"` / `"errors"` /
+`"extensions"` keys included. Don't symbolize or snake_case it first;
+`from_response` reads `raw["data"]` and the casting reads camelCase field keys.
+The module must, of course, be generated for the query you ran.
 
 ## Variables become typed kwargs
 
@@ -152,9 +204,31 @@ hint rather than silently dropping):
 AdoptQuery.execute!(input: { name: "Rex", species: "DOG" }, detail: true)
 ```
 
-The structs themselves are module-level (`AdoptQuery::AdoptionInput`) with
-`serialize` (aliased as `to_h`) producing the wire hash — optional fields
-default nil and stay off the wire. Nested inputs work (dependencies emit
+In the generate! workflow, input types (and the enums they use) are
+emitted **once per schema** — one file per type under
+`generated/inputs/`, with `inputs.rb` as the manifest. The module is
+named from the output path: the conventional layout gets
+`GraphQLInputs`, while a multi-schema layout names each schema's module
+after its directory (`app/graphql/github/generated` → `GithubInputs`).
+Override globally with `GraphWeaver.inputs_module=` or per run with
+`generate!(inputs_module:)`; opt out with
+`generate!(shared_inputs: false)`. Per-type files keep schema drift
+reviewable: a migration diffs exactly the types it touched, and types
+the schema drops are pruned on regeneration (`verify` flags strays).
+Query modules alias what they touch,
+so `AdoptQuery::AdoptionInput` still works and shared types keep one
+identity across modules — three filtered Hasura queries cost one ~11k-line
+inputs file plus ~90 lines each, instead of ~35k lines of duplicates.
+Deeply nested types live unaliased in the shared module
+(`GraphQLInputs::PetFilter`). Dynamic `parse` stays self-contained.
+
+The structs themselves are module-level (`AdoptQuery::AdoptionInput`):
+typed consts plus a compact per-field `FIELDS` table that the
+`GraphWeaver::InputStruct` runtime drives — `serialize` (aliased `to_h`)
+produces the wire hash with nil optionals omitted, `coerce` builds from
+plain hashes. The conversions ship in the generated file as data
+(lambdas in the table), so a Hasura `bool_exp` pulling hundreds of input
+types stays ~2 lines per field instead of unrolled methods. Nested inputs work (dependencies emit
 first), including recursive ones — Hasura's self-referential `bool_exp`
 filters generate cleanly (`_and:`/`_not:` fields typed as the struct
 itself), so variable-driven filtering works:

data/docs/getting_started.md

@@ -91,14 +91,16 @@ PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```ruby
 # spec/support/graph_weaver.rb
 require "graph_weaver/rspec"
+
+GraphWeaver::Testing.configure { |config| config.auto_fake = true }
 ```
 
-That's the whole setup: the schema auto-locates from the committed dump
-and `auto_fake` defaults on, so every query in every example executes
-against a seeded, schema-correct `FakeClient` — no server, no stubs,
-and `rspec --seed 1234` reproduces the fake data along with test order.
-Pin values with `overrides:`, simulate failures with `Failure.*`, opt
-out with `config.auto_fake = false` — see [testing](testing.md).
+The opt-in is deliberate (no surprise fakes); once on, the schema
+auto-locates from the committed dump and every query in every example
+executes against a seeded, schema-correct `FakeClient` — no server, no
+stubs, and `rspec --seed 1234` reproduces the fake data along with test
+order. Pin values with `overrides:`, simulate failures with `Failure.*`
+— see [testing](testing.md).
 
 ## 7. Verify in CI
 

data/docs/testing.md

@@ -31,24 +31,22 @@ GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
 })
 ```
 
-With rspec, one line in `spec/support/graph_weaver.rb` is the whole
-default setup — the schema auto-locates from the committed dump at
-`GraphWeaver.schema_path`, and `auto_fake` defaults on:
+With rspec, the setup is two lines in `spec/support/graph_weaver.rb` —
+the require, plus an explicit opt-in to per-example fakes (deliberately
+not a default: silently swapping every example onto a fake would be
+surprising). The schema auto-locates from the committed dump at
+`GraphWeaver.schema_path`:
 
 ```ruby
-require "graph_weaver/rspec"   # seed follows --seed; every example auto-fakes
-```
-
-Configure to override any of it:
+require "graph_weaver/rspec"   # seed follows --seed
 
-```ruby
 GraphWeaver::Testing.configure do |config|
-  config.schema = MySchema             # an in-process class instead of the located dump
-  config.auto_fake = false             # opt out of per-example fakes
-  config.mode = :faker                 # or :literal (plain typed values); nil = auto
-  config.overrides = { "Person.name" => "Daniel" }
-  config.list_size = 1..3
-  config.null_chance = 0.1             # nullable fields go nil sometimes
+  config.auto_fake = true              # every example runs against a fresh fake
+  # config.schema = MySchema           # optional: an in-process class instead of the dump
+  # config.mode = :faker               # or :literal (plain typed values); nil = auto
+  # config.overrides = { "Person.name" => "Daniel" }
+  # config.list_size = 1..3
+  # config.null_chance = 0.1           # nullable fields go nil sometimes
 end
 ```
 
@@ -59,6 +57,15 @@ they consult `GraphWeaver.client`). `mode:` picks value fabrication: `:faker`
 (semantic, field-name matched — raises if the gem is missing),
 `:literal` (plain type-derived), or nil to auto-detect faker.
 
+Test-only queries don't have to live in `app/` — the conventional paths
+are appendable lists, so the same support file can register a
+spec-local set that `load_generated!` (and the Railtie) pick up:
+
+```ruby
+GraphWeaver.generated_paths << "spec/support/graphql/generated"
+GraphWeaver.queries_paths << "spec/support/graphql/queries"
+```
+
 **Simulating failures** — every failure mode is just a client, so
 error-handling paths are testable without a server that misbehaves on cue:
 

data/lib/graph_weaver/client.rb

@@ -127,8 +127,9 @@ class GraphWeaver::Client
   #
   # Reloadable (constants are replaced), so it suits consoles and dev.
   # Returns the modules.
-  def load_queries!(dir = GraphWeaver.queries_path, namespace: Object)
-    Dir[File.join(dir, "*.graphql")].sort.map do |path|
+  def load_queries!(dir = nil, namespace: Object)
+    dirs = dir ? [dir] : GraphWeaver.queries_paths
+    dirs.flat_map { |d| Dir[File.join(d, "*.graphql")].sort }.map do |path|
       name = "#{GraphWeaver::Inflect.camelize(File.basename(path, ".graphql"))}Query"
       namespace.send(:remove_const, name) if namespace.const_defined?(name, false)
       GraphWeaver.log(:info) { "loaded #{name} from #{path}" }