graph_weaver 0.4.6 → 0.5.1

data/docs/upgrading.md

@@ -0,0 +1,134 @@
+# Upgrading to 0.5.0
+
+0.5.0 is one large breaking release. Almost all of it is caught mechanically,
+in this order:
+
+```sh
+# 1. rename the path settings first — generate won't load without them
+#    (queries_path -> queries_paths, generated_path -> generated_paths,
+#     fragments_path -> fragments_paths; see "One plurality rule" below)
+
+bundle exec tapioca gem graph_weaver   # 2. regenerate the RBI
+rake graph_weaver:generate             # 3. the emitted call shape changed
+srb tc                                 # 4. every call site that moved is an error
+rake graph_weaver:verify               # 5. fails until the tree is regenerated
+```
+
+**Step 2 is not optional.** Against the 0.4.6 RBI, `srb tc` reports errors
+pointing into your `generated/` directory — `QueryModule`, `client_for`,
+`check_envelope!` — which read as though codegen emitted broken Ruby. It
+didn't; sorbet is checking new generated code against the old gem's types.
+Regenerate the RBI and what remains is only your own call sites.
+
+Generated code is `# typed: strict`, so step 4 finds those for you. The rest of
+this page is what a typechecker can't see.
+
+## `execute` means one thing now
+
+Every client answers the same call — `execute(query, variables:, operation_name:)`,
+returning the raw response hash. `Client` used to spell something else under
+that name, which is why `Retry.new(client)` and `Sequence.new(client, fake)`
+raised `ArgumentError`. They work now.
+
+The one-shot sugar moved to `run`:
+
+```ruby
+client.execute!("query { … }", id: "1")   # before
+client.run!("query { … }", id: "1")       # after   (and #run for the envelope)
+
+GraphWeaver.execute(source, query, **vars)   # before
+GraphWeaver.run(source, query, **vars)       # after
+```
+
+**This one is worth grepping for.** `Client#execute` still exists, so a stale
+call fails at runtime rather than at typecheck — as do `GraphWeaver.execute`
+and `GraphWeaver.reset_scalars!`, which are simply gone and will not be flagged
+until the RBI is regenerated (step 2): `rg '\.execute!?\(' --type ruby`
+and check each hit is passing `variables:` rather than loose kwargs.
+
+A generated module takes its per-call client as a **keyword**:
+
+```ruby
+PersonQuery.execute(some_client, id: "1")          # before
+PersonQuery.execute(client: some_client, id: "1")  # after
+```
+
+`GraphWeaver.resolve_transport` is gone; nothing needs unwrapping any more.
+
+## Path settings are lists
+
+`queries_paths`, `generated_paths`, `fragments_paths` — every entry is read.
+Assigning a String still works, so the change is the name:
+
+```ruby
+GraphWeaver.queries_path = "app/graphql/queries"    # before
+GraphWeaver.queries_paths = "app/graphql/queries"   # after
+```
+
+`schema_path` stays singular: one run reads one schema.
+
+## One reset
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests. The four
+narrow ones moved to where they live:
+
+```ruby
+GraphWeaver.reset_scalars!            # before
+GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalars!,
+                                      #          reset_type_helpers!)
+```
+
+## Smaller renames
+
+| before | after |
+|---|---|
+| `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
+| `register_scalar(…, coerce: :to_s)` | `coerce: true`, or a `cast:`/`serialize:` pair |
+| a mutation's `…Query` module | `…Mutation` |
+| `graphql: :none` (rspec tag) | `graphql: false` |
+
+**The shared types module was three, and is now one.** `GraphQLInputs`,
+`GraphQLEnums` and `GraphQLUnions` are all `GraphQLTypes`, and the files move
+with them — `generated/inputs/` becomes `generated/types/`. The three settings
+that named them (`inputs_module=`, `enums_module=`, `unions_module=`) are one
+`types_module=`. Regenerating writes the new tree; delete the old directory,
+which pruning leaves behind empty.
+
+If your specs run one schema class in-process while your client points at a
+different API, name it — per example, since a federated suite runs more than
+one:
+
+```ruby
+graphql_in_process(MySchema)                     # in the example
+GraphWeaver::Testing.config.schema = MySchema    # or once, for the whole suite
+```
+
+## Registering from Rails
+
+A registration naming one of your own constants belongs in a `to_prepare` block
+— the same place the in-process client goes, and for the same reason:
+autoloading is set up after `config/initializers` run.
+
+```ruby
+Rails.application.config.to_prepare do
+  GraphWeaver.register_enum("Species", PetKind, fallback: PetKind::Unknown)
+  GraphWeaver.extend_type("Pet", PetHelpers)
+end
+```
+
+Generation depends on `:environment`, which runs `to_prepare` too, so the
+registration is in place before it emits.
+
+## If you use the federation router
+
+Detection only sees *loaded* schema classes, and Rails does not eager load for
+rake or in the default test environment. Both are one line:
+
+```ruby
+config.eager_load = true        # config/environments/test.rb
+config.rake_eager_load = true   # config/application.rb
+```
+
+Without them the `federation:*` tasks silently see nothing — and
+`federation:diff` now **fails** rather than reporting a green "matches" over
+zero subgraphs.

data/graph_weaver.gemspec

@@ -2,16 +2,32 @@ 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"
+  # the README tagline, verbatim — the two pitches drifted apart once already,
+  # so spec/gemspec_spec.rb pins them together
+  s.description = "Your .graphql files, compiled into Sorbet types — and the fakes to test them."
   # ".yardopts" explicitly: `git ls-files *` skips dotfiles, and
   # rubydoc.info needs it shipped to render docstrings as markdown
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples'`.split("\n") + [".yardopts"]
+  # CLAUDE.md/PLAN.md/REVIEW.md/NOTES.md/DECISIONS.md are written for whoever
+  # works on the gem, not whoever installs it — and REVIEW.md carries examples
+  # from before the API it describes was rewritten
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples' \
+                     ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
+                     ':!:DECISIONS.md' ':!:Makefile' ':!:design'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
-  s.summary     = "GraphWeaver"
+  # rubygems.org shows summary as the headline, description below it
+  s.summary     = "A typed GraphQL client for Ruby"
   s.version     = GraphWeaver::VERSION
 
+  s.metadata = {
+    "bug_tracker_uri" => "#{s.homepage}/issues",
+    "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{s.homepage}/tree/main/docs",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => s.homepage,
+  }
+
   s.required_ruby_version = ">= 3.3"
 
   # 2.6.7 fills defaulted directive arguments when building from SDL

data/lib/generators/graph_weaver/install_generator.rb

@@ -0,0 +1,259 @@
+# typed: ignore — Rails::Generators DSL, only loaded by `rails g`
+# frozen_string_literal: true
+
+require "graph_weaver"
+
+# rails g graph_weaver:install https://api.example.com/graphql
+# rails g graph_weaver:install MyApp::Schema
+# rails g graph_weaver:install db/schema.graphql
+#
+# Scaffolds the conventional layout — initializer, query/generated
+# directories, editor config — and bootstraps the schema dump, so the
+# setup in docs/getting_started.md is one command.
+#
+# The argument is what you'd pass to GraphWeaver.new, and the same three
+# source forms are accepted; the initializer it writes reflects the one
+# you chose. The source arrives on the command line rather than being read
+# from config: at install time the initializer doesn't exist yet.
+module GraphWeaver
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc <<~TEXT
+        Wire up GraphWeaver: initializer, app/graphql layout, editor config, schema dump.
+
+        SOURCE is what you'd pass to GraphWeaver.new:
+
+            rails g graph_weaver:install https://api.example.com/graphql   # an endpoint
+            rails g graph_weaver:install MyApp::Schema                     # a graphql-ruby schema, in-process
+            rails g graph_weaver:install db/schema.graphql                 # a schema dump you already have
+      TEXT
+
+      argument :source, type: :string, banner: "SOURCE",
+        desc: "what you'd pass to GraphWeaver.new: an endpoint url, a graphql-ruby schema class, or a schema dump path"
+
+      # the default is SchemaLoader's, not one restated here — an --auth the
+      # generator omits from the dump is one the schema tasks then can't find
+      class_option :auth, type: :string,
+        desc: "name of the ENV var holding the auth token (url only) — " \
+          "default #{GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV}"
+      class_option :schema, type: :boolean, default: true,
+        desc: "write the schema dump codegen reads"
+
+      # Before anything is written: a mistyped source or a flag that doesn't
+      # apply to it is a mistake in the command just typed, so say so there
+      # rather than at boot, three files later.
+      def check_source
+        if options[:auth] && form != :url
+          raise Thor::Error, "--auth applies to a url — #{source} is a #{form == :schema_class ? "schema class" : "schema dump"}"
+        end
+
+        schema_class if form == :schema_class
+      end
+
+      # Every write goes through create_file, so a re-run prompts with a
+      # diff rather than overwriting an initializer you've edited.
+      def create_initializer
+        create_file "config/initializers/graph_weaver.rb", initializer
+      end
+
+      def create_layout
+        create_file File.join(GraphWeaver.queries_paths.first, ".keep"), ""
+        create_file File.join(GraphWeaver.generated_paths.first, ".keep"), ""
+      end
+
+      # editor autocomplete + validation for .graphql files (docs/editors.md)
+      def create_editor_config
+        create_file "graphql.config.yml", editor_config
+      end
+
+      # A url is introspected and a schema class dumped; a dump the app
+      # already has is left where it is (schema_path points at it instead).
+      def fetch_schema
+        return unless options[:schema] && form != :path
+
+        if form == :url
+          # pass the var name, not just the token — it lands in the dump's
+          # provenance so schema:refresh/:diff read the same one the
+          # initializer does, instead of defaulting to GRAPHWEAVER_AUTH
+          GraphWeaver::SchemaLoader.refresh!(url: source, auth_env: auth_var)
+        else
+          # a schema class is its own introspection source; ttl: 0 so an
+          # existing dump never counts as fresh
+          GraphWeaver::SchemaLoader.introspect(schema_class, cache: schema_path, ttl: 0)
+        end
+        say_status :introspect, "#{schema_path} from #{source}"
+      rescue StandardError => e
+        # the files above are the valuable part — don't lose them to a bad
+        # token or an unreachable host
+        say_status :failed, "#{e.message} — retry with `#{refresh_command}`", :red
+      end
+
+      def next_steps
+        say <<~TEXT
+
+          Write a query in #{GraphWeaver.queries_paths.first}, then:
+
+              rake graph_weaver:generate
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/getting_started.md
+        TEXT
+
+        say federated_steps if subgraphs
+      end
+
+      private
+
+      # This install run is the one moment the user is guaranteed to be
+      # reading, and a composed supergraph changes what the next steps are:
+      # the test client is the interesting one, and there's a CI gate to add.
+      def federated_steps
+        <<~TEXT
+
+          #{source} is a composed supergraph (#{subgraphs.size} subgraphs: #{subgraphs.join(", ")}), so:
+
+              rake graph_weaver:federation:diff       # CI gate: a subgraph changed, nobody recomposed
+              rake graph_weaver:federation:subgraphs  # which schema here serves which subgraph
+
+          and specs run against your real resolvers across all of them, in-process:
+
+              describe "checkout", graphql: :router do ... end   # require "graph_weaver/rspec"
+
+          Docs: https://github.com/dpep/graph_weaver/blob/main/docs/federation.md
+        TEXT
+      end
+
+      # The subgraph names this source composes, or nil when it isn't a
+      # composed supergraph. Read off the routing table rather than guessed —
+      # the same reader Testing::Router and federation:diff use.
+      def subgraphs
+        return @subgraphs if defined?(@subgraphs)
+
+        @subgraphs =
+          begin
+            (GraphWeaver::SchemaLoader.routing_table(source).subgraphs if form == :path)
+          rescue StandardError
+            # not a supergraph, or not readable — nothing to say either way
+            nil
+          end
+      end
+
+      # Which of GraphWeaver.new's source forms this is. Neither test is its
+      # own — a url is whatever the client calls one, a constant path whatever
+      # codegen will spell — so the generator can't disagree with either about
+      # what it just wrote an initializer for. Anything that is neither is
+      # taken as a path to a dump.
+      def form
+        @form ||=
+          if source.match?(GraphWeaver::Client::URL)
+            :url
+          elsif source.match?(GraphWeaver::Codegen::CONSTANT_NAME)
+            :schema_class
+          else
+            :path
+          end
+      end
+
+      # The named schema class, resolved now: `rails g` boots the app, so a
+      # typo is catchable here rather than as a NameError at the next boot.
+      def schema_class
+        @schema_class ||= begin
+          klass = Object.const_get(source)
+          unless klass.respond_to?(:execute)
+            raise Thor::Error, "#{source} isn't a graphql-ruby schema (no .execute) — pass the class that inherits GraphQL::Schema"
+          end
+
+          klass
+        rescue NameError
+          raise Thor::Error, "uninitialized constant #{source} — pass your graphql-ruby schema class " \
+            "(rails g graphql:install writes app/graphql/<app>_schema.rb), an endpoint url, or a path to a schema dump"
+        end
+      end
+
+      # A dump the app already has stays where it is; every other form
+      # writes the conventional one.
+      def schema_path = (form == :path) ? source : GraphWeaver.schema_path
+
+      def auth_var = options[:auth] || GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV
+
+      def refresh_command
+        (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
+      end
+
+      def initializer
+        <<~RUBY
+          # frozen_string_literal: true
+
+          #{client_setup}
+          # Custom scalars, enums and type mixins go here — `rake graph_weaver:generate`
+          # bakes them into the generated source, so they must be registered first:
+          #
+          #   GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+          #   GraphWeaver.extend_type("Person", Greetable)
+        RUBY
+      end
+
+      # The load-bearing lines, per source form: what generated modules
+      # resolve to at execute time, and where codegen reads the schema.
+      def client_setup
+        case form
+        when :url
+          <<~RUBY
+            GraphWeaver.client = GraphWeaver.new(
+              "#{source}",
+              auth: ENV["#{auth_var}"],
+              cache: true, # reuse the committed dump; delete it to re-introspect
+            )
+          RUBY
+        when :schema_class
+          # to_prepare, not a bare assignment: the schema class is autoloaded,
+          # so it isn't resolvable this early, and a dev reload replaces it
+          # with a new class object the client would otherwise still hold.
+          <<~RUBY
+            Rails.application.config.to_prepare do
+              # queries run in-process against the app's own schema — no socket
+              GraphWeaver.client = GraphWeaver.new(#{source})
+            end
+          RUBY
+        when :path
+          if subgraphs
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A composed supergraph: your queries are generated against the whole
+              # graph, and a router serves it. Point the app default at the gateway:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://gateway.example.com/graphql")
+              #
+              # Specs don't need one — `graphql: :router` plans against this
+              # supergraph and runs your own subgraph resolvers in-process
+              # (docs/federation.md).
+            RUBY
+          else
+            <<~RUBY
+              GraphWeaver.schema_path = "#{source}"
+
+              # A dump is type information only — it has no resolvers, so it can't
+              # execute. Point the app default at whatever serves this API:
+              #
+              #   GraphWeaver.client = GraphWeaver.new("https://api.example.com/graphql")
+            RUBY
+          end
+        end
+      end
+
+      # fragments are in documents: too — without them an editor reports
+      # `Unknown fragment` on any query that spreads a shared one. The glob is
+      # codegen's, so the editor validates exactly the files codegen reads.
+      def editor_config
+        <<~YAML
+          # Autocomplete and validation for .graphql files in VS Code / RubyMine.
+          # https://github.com/dpep/graph_weaver/blob/main/docs/editors.md
+          schema: #{schema_path}
+          documents:
+            - #{File.join(GraphWeaver.queries_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
+            - #{File.join(GraphWeaver.fragments_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
+        YAML
+      end
+    end
+  end
+end