graph_weaver 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df338e7f577c07e2941daf8e7a06af9a04e04ecfceae6c02a7e6d6619e219a0f
-  data.tar.gz: 939e9c9db69ed23b484ebd60401b96e5b51fea10aa6ee0b4e6c9a62118243302
+  metadata.gz: ef7de8e2cd115b4c757a3dac2e8c41a0e87865914e246131c1037a231f7a60af
+  data.tar.gz: fa89ee78a04a2a07b7c173c82685490ca501a2a29045ef487aae3dd6f3d915d8
 SHA512:
-  metadata.gz: 3eaf7a927dbde9d9eac7353a8d01623a099e5904c458113274bf347524d00567a8d0fdd3794312f2931feb9f0a7fbd212eccfdfc9b09671e646cbfd1a8d35294
-  data.tar.gz: cc4ae772c0c38f3cb547d37ddc88821a1eb9172d8df42c4b0608242c0df19ca4ad669e246c72806fc53701be95fa7a4a4945723725075812ecf4ec602bcd63f0
+  metadata.gz: 4ae73ed74389baa1f08a42e38b7bf2b0bca2f95ccbe247ccb68fda733c9fee849aed3d17dbba424bdb13104344771d9789401710a5add195c71873edc379530b
+  data.tar.gz: 24e15e7a6213c0cd5dee16aa73e675649748b84993be11387f638aeca21c15db77a59b1fa5a85ae406af7182be0f9f6a17164b842add3627a7547ab1670616d1

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--title GraphWeaver
+-
+docs/*.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -1,3 +1,282 @@
+###  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
+  its key per entry; dependency-order DFS uses hash bookkeeping (big
+  bool_exp graphs); require/vocabulary residue swept; the vestigial
+  graph_weaver/testing/rspec shim removed
+- BREAKING: "client" replaces "executor" across the whole surface.
+  Generated modules: the per-call override is an optional POSITIONAL
+  first argument — PersonQuery.execute(github, id: "1") — so variables
+  own the entire kwarg namespace and NOTHING is reserved (a $client or
+  $executor variable is fine; only Ruby keywords refuse); per-module is
+  MyQuery.client=, the baked param is client:. GraphWeaver.executor= is
+  gone — GraphWeaver.client= is the one ambient slot (auto_fake swaps
+  it per example; explicit clients are self-contained and never see it).
+  Client#executor is now Client#transport (transport: to bring your
+  own); SchemaLoader.introspect/stale? speak transport. Renames:
+  FakeExecutor => Testing::FakeClient, SequenceExecutor =>
+  Testing::Sequence, RetryExecutor => GraphWeaver::Retry,
+  Recording/ReplayExecutor => Recorder/Replayer, Cassette.use(client:)
+- Live federation integration: two Ruby subgraphs (apollo-federation
+  gem) composed and routed by a real Apollo gateway (node harness under
+  spec/support/federation), with GraphWeaver introspecting through the
+  router and executing a query stitched across BOTH subgraphs — part of
+  make integration. Complements the existing supergraph-SDL codegen spec
+- graphql-over-http: a non-2xx response carrying a GraphQL errors body
+  (Apollo Server/Router send request errors as 4xx JSON) flows into the
+  Response envelope so QueryError sees the structured errors; only
+  non-GraphQL bodies (proxy pages) raise ServerError
+- Fix: input-struct serialize used bare locals (result/value) that a
+  same-named prop silently shadowed — a field named "result" dropped
+  its value onto the wrong target; generated locals now wear the
+  reserved __gw prefix (GraphQL reserves __-names, so no collision is
+  possible)
+- Input fields and variables whose Ruby name would be a keyword
+  (nil/def/end/...), a generated method (serialize/to_h), or the
+  reserved executor kwarg now refuse at generation with a pointed
+  error instead of emitting broken code
+- Non-JSON 200 bodies (proxy error pages) classify as ServerError, and
+  unserializable variables (NaN/Infinity) raise GraphWeaver::Error —
+  raw JSON::* errors no longer escape the umbrella
+- Transports redact on inspect/to_s (class + url only) — Authorization
+  headers can't leak through logs or exception dumps
+- Narrowed `... on X` selections require at least one unconditional
+  field: with every field behind @skip/@include, a matching response is
+  {} — byte-identical to a non-match — so generation refuses rather
+  than silently dropping real matches to nil
+- Integration spec against Hasura's PokeAPI: snake_case codegen,
+  recursive bool_exp variable filtering, untyped jsonb pass-through
+  (make integration)
+- BREAKING: ValidationError now descends from GraphWeaver::Error (was
+  ArgumentError) — one `rescue GraphWeaver::Error` catches everything
+- Input-struct .coerce raises on unknown hash keys with a spellchecked
+  hint — a typo'd filter key no longer silently drops off the wire
+- Client registrations (register_type/register_enum) validate at the
+  call site when the schema is already loaded; lazy clients still
+  validate at generation
+- Unregistered custom scalars emit bare T.untyped (not
+  T.nilable(T.untyped), an srb tc error under typed: strict)
+- Wire log lines carry [req N OperationName] tags; long queries
+  (introspection) truncate at debug
+- Logging: GraphWeaver.logger (any stdlib-compatible Logger; Rails.logger
+  auto-wired by the railtie) — wire traffic + timings at debug,
+  introspection/cache/codegen at info, every raised error at warn
+- Recursive input types generate — self- and mutually-referential inputs
+  (Hasura's bool_exp filter surface) emit dependency-ordered structs with
+  runtime forward declarations for cycles, so variable-driven Hasura
+  filtering works; previously raised "recursive input type"
+- Fix: snake_case GraphQL type names (Hasura, PostGraphile) camelize
+  into valid Ruby constants — pokemon_v2_pokemon => PokemonV2Pokemon
+  (previously generated a SyntaxError); wire names (__typename dispatch,
+  registry keys) are untouched
+- Everything raised is rescuable: unparseable queries wrap as
+  ValidationError (GraphQL::ParseError no longer leaks), and internal
+  NotImplementedError raises (recursive inputs, unsupported kinds,
+  subscriptions) became GraphWeaver::Error
+- Transport::HTTP takes open_timeout:/read_timeout: (defaults 10s/30s);
+  timeouts surface as retriable TransportError
+- Transport::HTTP reuses its connection (keep-alive, mutex-serialized,
+  keep_alive_timeout: for the idle window); any failure drops the socket
+  so the next call starts fresh
+- GraphQLError#code also reads a top-level "type" (GitHub's dialect:
+  NOT_FOUND, FORBIDDEN) when extensions.code is absent
+- Typo'd client-scoped registrations raise at generation with a
+  spellchecked hint (register_type("Pett") => "did you mean 'Pet'?")
+  instead of silently no-oping
+- Abstract selections narrow: __typename is only required when the
+  selection varies by concrete type. Interface-level-fields-only
+  selections generate one shared struct (no dispatch); a single
+  `... on X` condition generates X's struct, always nilable — a
+  non-matching runtime type casts to nil, so narrowing doubles as
+  filtering
+- Zero-config rspec: require "graph_weaver/rspec" now defaults
+  auto_fake on and auto-locates the schema from the committed dump
+  (config.schema= / config.auto_fake = false to override) — one line is
+  the whole test setup in a conventional app
+- examples/: runnable demos, all directly executable — countries.rb
+  (public API, no auth, all dynamic), rick_and_morty.rb (filtered
+  search, pagination, a block-built type helper), and github/ (auth,
+  checked-in generated modules; stars the repo ⭐ then tours the
+  stargazers, their top repos, and what else they've starred); excluded
+  from the gem package
+- Fix: requires: now load before codec probing, so inference sees
+  methods the required file provides — register_scalar("DateTime", Time,
+  requires: "time") correctly infers Time.parse in a fresh process
+  (previously the cast was silently skipped unless "time" was already
+  loaded)
+- docs/quickstart.md renamed to docs/getting_started.md
+- Rails Railtie: the graph_weaver:* rake tasks self-register (no
+  Rakefile edit) and depend on :environment, and generated modules load
+  at boot (after initializers) when generated_path exists; outside
+  Rails, require "graph_weaver/tasks" and call load_generated! as before
+- BREAKING (vs 0.1.0): reset_scalars! lost its coerce: flavor —
+  GraphWeaver.auto_coerce = true is the one way to default-coerce
+  (broader: convertible built-ins AND full cast/serialize scalars,
+  resolved lazily, per-registration coerce: still wins)
+- GraphWeaver.client= — the blessed global wiring: assign the app's
+  default client and generated modules resolve through it (per call ->
+  per module -> baked -> executor= -> client). executor= stays as the
+  low-level override, so test fakes still win
+- Enum mappings: register_enum("Species", PetKind) (+ bulk
+  register_enums, client-scoped variants) — generated code speaks YOUR
+  T::Enum, with the wire mapping inferred by name, pinned via map:,
+  exhaustiveness-checked at generation (fails naming gaps), and
+  fallback: to absorb unknown wire values on cast (inputs stay strict);
+  translation tables emitted into the source (X_FROM_WIRE / X_TO_WIRE)
+- Type helpers: register_type("Pet", PetHelpers) (global or
+  client-scoped, additive) — app-owned modules included into every
+  struct generated from that GraphQL type, so derived values live as
+  methods beside the honest wire data and srb tc checks them against
+  each query's selection. Or build the mixin inline with a block
+  (module_eval'd into an auto-named GraphWeaver::TypeHelpers constant —
+  quick decoration, invisible to srb tc)
+- BREAKING (vs 0.1.0): register_scalar takes the type positionally —
+  register_scalar("Money", Money, requires: ...) — matching the new
+  registrars: the GraphQL name + your Ruby type up front, options as
+  kwargs
+- GraphWeaver::Client — transport, schema, and scalars for one server in
+  one object: GraphWeaver.new(url_or_schema) takes a url (transport
+  built, schema introspected lazily per cache:/ttl:) or a schema source
+  (live class — also the in-process executor — or a path/SDL/dump);
+  #parse and #execute/#execute! bind the implicit schema + transport;
+  #register_scalar scopes scalar mappings to the client (overlaying the
+  global registry), so two servers can disagree about a scalar type
+- BREAKING: GraphWeaver.connect removed — GraphWeaver.new(url) replaces
+  it (wire generated modules with GraphWeaver.executor = client.executor)
+- BREAKING: the one-shots are now GraphWeaver.execute(url_or_schema,
+  query, **variables) / execute! — Client#execute on a throwaway client;
+  variables are plain kwargs, as on a generated module
+- Client#load_queries! — parse every query file into modules named like
+  generation would name them (reloadable; namespace: to scope): the
+  no-build-step analog of generate! + load_generated!
+- Introspected schema dumps record provenance (source url + timestamp):
+  a parsable SDL header comment, a "graph_weaver" sibling key in JSON —
+  read it back with SchemaLoader.provenance(path), check drift with
+  SchemaLoader.stale?(path) or rake graph_weaver:schema:verify, rewrite
+  with rake graph_weaver:schema:refresh (GRAPHWEAVER_AUTH for tokens)
+- generate!/verify_generated!/rake auto-locate the schema dump at
+  schema_path in any supported format; SchemaLoader.locate is public
+- Calling a result field by its camelCase wire name raises a pointed
+  NoMethodError naming the snake_case prop that does exist
+  (result.addPet => "use 'add_pet'"), and near-miss typos in either
+  casing get a spellchecked suggestion (result.addPt => "did you mean
+  'add_pet'?") — the runtime companion to srb tc's static flag
+- BREAKING: an operation whose only variable is a required input object
+  (the Relay convention) now flattens the input's fields into execute's
+  kwargs — AdoptQuery.execute!(name:, species:) instead of
+  execute!(input: {...}); multi-variable / nullable-input operations
+  keep the input: kwarg (struct or hash)
+- Enum kwargs accept the T::Enum or its wire value (T.any(Enum, String))
+  everywhere — variables now match input-hash fields
+- BREAKING: HttpExecutor / FaradayExecutor are now Transport::HTTP /
+  Transport::Faraday, subclasses of the new abstract GraphWeaver::Transport
+  base, which owns the shared flow (encode, TransportError reclassify,
+  non-2xx ServerError, parse) — a custom transport just implements
+  post(body) => [status, body]. Opt-in require moved:
+  "graph_weaver/faraday_executor" -> "graph_weaver/transport/faraday"
+- SchemaLoader.introspect cache: reuses a fresh dump in ANY supported
+  format before re-introspecting (an existing schema.graphql wins over
+  writing schema.json), and accepts :json / :graphql / :gql to pick the
+  format at GraphWeaver.schema_path's location
+- rubydoc.info rendering: ship .yardopts (markdown markup, docs/ guides
+  as extra files) and re-indent docstring examples so code blocks and
+  backticks render; make docs previews locally
+- GraphWeaver.connect(url, auth:, headers:, retries:): one-shot setup —
+  best transport (Faraday when the app loads it; detection is defined?,
+  never a require), bearer/verbatim auth, opt-in RetryExecutor wrapping
+  (true / options Hash; off by default), wired in as the global executor
+- Generation workflow: GraphWeaver.generate! (queries dir -> generated
+  dir), verify_generated! (the freshness guard — raises naming stale
+  files), load_generated! (factory_bot-style explicit loading), rake
+  tasks (require "graph_weaver/tasks": graph_weaver:generate / :verify),
+  all defaulting to configurable conventional paths (queries_path /
+  generated_path / schema_path)
+- GraphWeaver.auto_coerce = true: default input coercion for scalars
+  without an explicit coerce:, resolved lazily at generation time (no
+  reset_scalars! ordering dance) — convertible built-ins take their
+  conversion, cast/serialize pairs take parse-style coercion
+- SchemaLoader.introspect cache: true — caches at GraphWeaver.schema_path,
+  in the format the extension picks: .json (verbatim wire artifact) or
+  .graphql/.gql (SDL — human-readable, PR-reviewable diffs);
+  the same dump rake graph_weaver:generate reads
+- docs/transports.md: connect, the executor contract, Faraday, retries
+- Cassette workflow: GRAPHWEAVER_RECORD=1 / config.record force
+  re-recording; config.anonymize scrubs responses as they are recorded
+  (caller sees the anonymized data too, so assertions hold on replay);
+  rake graph_weaver:cassettes:anonymize; docs/cassettes.md guide
+- auto_coerce reaches input-object fields: raw scalar values inside
+  input hashes coerce via the registry, mutations included
+- RetryExecutor: composable retries over any transport — tries:,
+  exponential/linear/custom backoff with jitter and max clamp,
+  retry-by-error-class (5xx yes, 4xx no by default; retry_if: override)
+  and retry-by-GraphQL-code (retry_codes: ["THROTTLED"])
+
+###  v0.1.0  (2026-07-11)
+- Structured errors: execute returns a typed Response envelope (#data/#data!,
+  #errors, #errors?, #extensions) instead of raising on GraphQL errors, so
+  partial data and top-level extensions (cost/throttle) survive. Error classes
+  under GraphWeaver::Error — TransportError (network), ServerError (non-2xx
+  HTTP, #status/#body), QueryError (#errors/#data/#extensions/#codes),
+  ValidationError (build-time) — plus a GraphQLError value object with #code.
+  Transport-error classification is an extensible Set (GraphWeaver.transport_errors
+  / register_transport_error): each transport seeds its own network exceptions
+  and apps can add more (e.g. a connection-pool timeout).
+  The envelope is a single generic GraphWeaver::Response[Result] (no per-query
+  wrapper class). execute! is the shortcut for execute(...).data! — the typed
+  result or a raised QueryError — on both generated modules and the one-shot
+  GraphWeaver.execute!/execute.
+  BREAKING: module #execute returns Response; use #execute! (or #data!) for
+  the old raise-or-result behavior. GraphWeaver.execute now returns the
+  envelope too; GraphWeaver.execute! returns the result.
+- GraphWeaver.register_scalar: custom scalar deserialization into rich Ruby
+  objects. cast/serialize inferred from a class type via paired codecs
+  (.parse/#to_s or .load/.dump), or given as a Symbol/Proc (:itself opts out);
+  requires: emits (validated, and require-checked when type: is a class)
+  requires into generated source — the built-in Date scalar carries
+  require "date" so Date-using queries are self-contained; coerce: true lets a
+  variable accept the value or its raw input (coerce: :to_f for a built-in
+  conversion), casting/converting the latter — reset_scalars!(coerce: true)
+  reloads the built-ins coercible; built-in scalars pre-registered in one
+  overridable registry (reset_scalars!/clear_scalars!)
+- FaradayExecutor: url, Faraday connection, or middleware block
+- GraphWeaver.executor default transport; per-module executor= override
+- GraphWeaver.parse and GraphWeaver.execute (dynamic queries)
+- Codegen.generate shorthand; executor: takes a constant; module_name
+  derived from operation or file name
+- Error ergonomics: schema_stale? (validation-shaped rejections hint at
+  regeneration), errors_at(path) + each_error/errors_by_field filtering,
+  #report (field-keyed rollup with entity ids resolved from partial
+  data), #to_h across the hierarchy (JSON-ready machine output), and
+  GraphWeaver::TypeError wrapping cast failures with the failing struct
+- SchemaLoader: introspect(executor, cache:, ttl:) fetches schemas from
+  live endpoints with file caching; load accepts introspection JSON /
+  SDL content / Hashes as well as paths (cache round-trips)
+- GraphWeaver::Testing (require "graph_weaver/testing", or
+  "graph_weaver/rspec" for the rspec integration): FakeExecutor
+  fabricates schema-correct castable responses (mode: :faker semantic
+  values / :literal; overrides by GraphQL name; seeded; list_size /
+  null_chance), failure simulation (Failure.transport/server/graphql/
+  throttled/stale_schema, SequenceExecutor for retries, fail_at: with
+  spec-correct null propagation, corrupt: for derived type mismatches),
+  cassette record/replay above the transport, and Cassette#anonymize!
+  (shape-preserving, consistent id mapping). rspec: seed follows
+  --seed; auto_fake installs a fake executor per example
+- one-off integration specs against live GitHub + Countries APIs
+  (make integration)
+- Input objects: INPUT_OBJECT variables generate module-level T::Structs
+  with serialize (aliased to_h) producing the wire hash; execute kwargs
+  also accept plain hashes, normalized + type-checked via the generated
+  .coerce (underscored Symbol/String keys, enums as instances or wire
+  values, nested inputs as hashes)
+- fields under @skip/@include generate nilable regardless of schema
+  nullability; FakeExecutor honors first/last/limit when sizing lists
+- eval hardening for parse: module names must be constant names, and
+  QUERY heredocs can't be terminated early by block strings
+- GraphWeaver::Selection: one shared query-walk (codegen, FakeExecutor,
+  anonymizer); codegen split into scalar_type / nodes / emit
+- docs/: generated_modules, real_world, scalars, errors, testing;
+  README slimmed to pitch + quickstart
+
 ###  v0.0.1  (2026-07-07)
 - voila: typed codegen (T::Structs, T::Enums, typed variable kwargs)
 - queries + mutations; fragments, unions, interfaces, enums, custom scalars

data/Gemfile.lock

@@ -1,15 +1,20 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.0.1)
+    graph_weaver (0.2.0)
       graphql (>= 2)
       sorbet-runtime
 
 GEM
   remote: https://rubygems.org/
   specs:
+    apollo-federation (3.10.3)
+      google-protobuf (< 5)
+      graphql
     base64 (0.3.0)
     benchmark (0.5.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.7)
     debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
@@ -17,24 +22,50 @@ GEM
     docile (1.4.1)
     erb (6.0.4)
     erubi (1.13.1)
+    faker (3.8.0)
+      i18n (>= 1.8.11, < 2)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
     fiber-storage (1.0.1)
+    google-protobuf (4.35.1-aarch64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
     graphql (2.6.5)
       base64
       fiber-storage
       logger
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
     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)
+    json (2.20.0)
     logger (1.7.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     netrc (0.11.0)
     parallel (2.1.0)
     pp (0.6.4)
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
+    rake (13.4.2)
     rbi (0.3.14)
       prism (~> 1.0)
       rbs (>= 4.0.1)
@@ -47,6 +78,7 @@ GEM
       prism (>= 1.6.0)
       rbs (>= 4.0.0)
       tsort
+    redcarpet (3.6.1)
     reline (0.6.3)
       io-console (~> 0.5)
     require-hooks (0.4.0)
@@ -74,15 +106,15 @@ GEM
       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)
+    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)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -105,7 +137,9 @@ GEM
       tsort
     thor (1.5.0)
     tsort (0.2.0)
+    uri (1.1.1)
     webrick (1.9.2)
+    yard (0.9.44)
 
 PLATFORMS
   aarch64-linux
@@ -115,36 +149,58 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  apollo-federation
+  bigdecimal
   debug
+  faker
+  faraday
   graph_weaver!
+  rake
+  redcarpet
   rspec
   simplecov
   sorbet
   tapioca
   webrick
+  yard
 
 CHECKSUMS
+  apollo-federation (3.10.3) sha256=61e6d8e1fd695ee45bab5d84f86f586d99c296ad77a86c6f1e7b964ac17be3d7
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  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
+  faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
+  faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
-  graph_weaver (0.0.1)
+  google-protobuf (4.35.1-aarch64-linux-gnu) sha256=50ca44d0eeff3f8475e630a1accdd974256f3510694d574e2c9d6119ea8bc9e1
+  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
+  i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  json (2.20.0) sha256=9362bc6e55a952b056abf9167cf053358181c904cb70cd6eee0808ea830fc32b
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   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
+  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
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
   require-hooks (0.4.0) sha256=005f4c6435b4edae73e358cdbaba48370a4121f9ce893d5d2a3c66fce855677d
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
@@ -160,17 +216,19 @@ CHECKSUMS
   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
+  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
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
 
 BUNDLED WITH
   4.0.10

data/Makefile

@@ -1,8 +1,13 @@
-.PHONY: check generate test tc
+.PHONY: check generate test tc integration docs
 
 # full verify loop: regenerate, test, typecheck
 check: generate test tc
 
+# manual/one-off checks against real GraphQL APIs (network; GitHub needs
+# `gh auth login` or GITHUB_TOKEN; federation boots an Apollo gateway — node)
+integration:
+	INTEGRATION=1 bundle exec rspec spec/integration
+
 generate:
 	bundle exec ruby bin/generate
 
@@ -11,3 +16,8 @@ test:
 
 tc:
 	bundle exec srb tc
+
+# preview what rubydoc.info will render
+docs:
+	bundle exec yard doc
+	open doc/index.html

data/NOTES.md

@@ -25,7 +25,7 @@ order, each backed by a spec.
 
 The specs are the documentation — each one asserts an observed behavior:
 
-```
+```sh
 bundle exec rspec
 ```