graph_weaver 0.5.0 → 0.5.1

data/NOTES.md

@@ -1,182 +0,0 @@
-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:
-
-```sh
-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~~ ANSWERED: path-based won. A generated type is named
-  for the response key that selects it, so the name is a function of the
-  field's own position — no walk order, no first-come-first-served, and an
-  unrelated selection can't move it. GraphQL aliases double as the explicit
-  naming escape hatch (`pet: pets` names the struct `Pet`)
-- mutations/subscriptions (only query operations generate)

data/PLAN.md

@@ -1,115 +0,0 @@
-# Project Plan — GraphWeaver, typed GraphQL client for Ruby/Sorbet
-
-_Resume-from-here notes: where the project stands and what's next. The README
-documents the product, CHANGELOG records what changed, DECISIONS.md records the
-roads not taken, NOTES.md is the research notebook this grew out of. Update on
-change._
-
-## Vision
-
-A "graphql-codegen for Ruby": `.graphql` queries + a schema (live class,
-introspection JSON, SDL, or an Apollo supergraph) → checked-in `# typed: strict`
-Ruby — nested `T::Struct`s, generated casting, a typed `execute` — so `srb tc`
-sees the exact shape of every query result. Dynamic mode for consoles, a build
-step for CI. Runtime deps: `graphql` + `sorbet-runtime`, nothing else.
-
-## State
-
-`0.4.6` on RubyGems. `main` carries a large unreleased body of work headed for
-**0.5.0** — see `## Unreleased` in the CHANGELOG, which is long and has a real
-upgrade story to tell.
-
-Green gate is in `CLAUDE.md`; `make check` runs the core of it.
-
-**What's built**, in brief — the CHANGELOG has the detail:
-
-- **Codegen.** Queries and mutations, typed variable kwargs, fragments (inline,
-  named, shared across queries), unions and interfaces (a struct per named
-  condition plus a forward-compatible `Other`), enums as `T::Enum`, custom
-  scalars, `@skip`/`@include` nullability. Generated class names derive from the
-  response key, so they're stable under unrelated edits. Shared types live once
-  per schema in `GraphQLTypes`.
-- **Sources.** Live schema class, introspection JSON, SDL, Apollo supergraph
-  (composition machinery stripped, `@inaccessible` subtracted to the API schema —
-  verified identical to Apollo's own `toAPISchema`), and raw subgraph SDL.
-- **Transports.** `Transport::HTTP` (zero-dep, pooled, keep-alive) by default;
-  Faraday on explicit opt-in. `InProcess` wraps a live schema class with
-  `context:`, logging and branded errors. Composable `Retry` honouring
-  `Retry-After`. One instrumentation seam covering both paths.
-- **Errors.** A typed `Response` envelope, an error hierarchy split by failure
-  site, field-level reporting with entity ids, `schema_stale?`, `#to_h`
-  throughout.
-- **Testing.** Schema-correct fakes, failure simulation, anonymizing cassettes,
-  and an in-process federation router that runs real subgraph resolvers —
-  verified against a real `@apollo/gateway` (42 identical, 1 refused, 0 wrong),
-  refusing at plan time anything it can't answer faithfully. One rspec tag picks
-  the mode: `graphql: :fake | :in_process | :router`.
-- **Lifecycle.** `generate` / `verify` / `schema:refresh` / `schema:diff` /
-  `queries:check` / `federation:diff`, plus `rails g graph_weaver:install`.
-
-## Next
-
-1. **Cut 0.5.0.** Needs an upgrade guide rather than a changelog dump — the
-   breaking list is long, but most of it is caught mechanically, so the guide is
-   largely *"regenerate, then follow `srb tc` and `verify_generated!`"*.
-   `gem push` needs an OTP.
-2. **`extend_type`'s mixin forms can't be statically checked.** A mixin's method
-   bodies are checked in the module's scope, not the struct's, so the docs have
-   to recommend `# typed: false` or `T.unsafe(self)`. In a library whose pitch is
-   static checking, that's a seam worth a design pass. Note `alias:` — which
-   emits into the struct body — *is* checked, which suggests the mixin forms are
-   the ones carrying the cost.
-3. **Nice-to-haves, unclaimed.** `write_timeout` on `Transport::HTTP` (and
-   possibly a `net_http:` passthrough rather than more kwargs); a Tapioca DSL
-   compiler so dynamic `parse` modules get static types without the build step.
-
-## Federation router: what it still refuses
-
-Each refuses at plan time with the type, field, subgraphs and next action. The
-cost of moving each boundary, if a real query mix ever demands it:
-
-- **`@requires` needing a chain** — the prefetch's own key must come from the
-  subgraph in hand; needs a real dependency DAG.
-- **An abstract type the supergraph doesn't break down** — a union or interface
-  at a boundary now plans, one branch per concrete type, bucketed on
-  `__typename` at execution. What is left is the supergraph that doesn't say
-  which concrete types a subgraph answers it with — no
-  `@join__unionMember`/`@join__implements`, and the type in more than one
-  subgraph. Closing it means reading a join version that predates those
-  directives; a modern composition always carries them.
-- **A nested field set no one fetch can build** — a nested field set now
-  crosses as the object it is, to any depth. What is left is the one whose
-  fields are split across subgraphs (`origin` in one and `origin.lat` in
-  another, or a `@key`'s object a `@requires` would half-fill from
-  elsewhere): a representation comes from one fetch, so the object would
-  arrive in pieces. Closing it means merging the pieces, which
-  `DECISIONS.md` argues against — the shapes that produce a split are the
-  ones where a real gateway stops being an oracle.
-- **Mutation root fields spanning subgraphs** — root mutation fields run in
-  series, so grouping them would run them in plan order.
-- **An alias shadowing an injected `@key`** — Apollo resolves the collision in
-  favour of its own key and a spec-conformant server doesn't, so there is no one
-  answer to agree with. Unfixable by design.
-
-`rake graph_weaver:federation:coverage` reports the refusal rate against a real
-supergraph and query set. That number decides whether any of the above is worth
-building — on the demo corpus it is 17/17.
-
-## Stated non-goals
-
-Recorded so they read as decisions rather than omissions, with the reasoning in
-`REVIEW.md` §7: subscriptions, `@defer`/`@stream`, file uploads, normalized
-caching, fragment masking, request batching, and a watch mode.
-
-## Gotchas worth remembering
-
-- graphql-ruby's `to_definition`/`from_introspection` reorder enum values and
-  possible types — codegen sorts both; keep any new emission deterministic.
-- Schemas built from introspection or SDL have no scalar coercion or resolvers,
-  so codegen stays name-keyed and never calls schema runtime hooks.
-- A `SchemaDefinition` node reprints without its body when the root type names
-  are the GraphQL defaults, so directives on `schema` must be stripped before
-  reprinting a supergraph.
-- Code the build doesn't exercise rots silently — integration specs excluded from
-  the default run, examples the generator skips, doc samples nobody executes.
-  Six fabricated doc samples were found in one session by running them.