graph_weaver 0.7.5 → 0.7.6

data/docs/upgrading.md

@@ -1,8 +1,8 @@
 # Upgrading
 
 [Regenerate](#regenerate-on-every-upgrade) whichever version you're on, then read
-the one section that is yours: from [0.7.4](#upgrading-from-074), from
-[0.7.3](#upgrading-from-073), from
+the one section that is yours: from [0.7.5](#upgrading-from-075), from
+[0.7.4](#upgrading-from-074), from [0.7.3](#upgrading-from-073), from
 [0.7.1](#upgrading-from-071), from [0.7.0](#upgrading-from-070) or from
 [0.6.1](#upgrading-from-061). Coming from 0.6.0 or older, the path is that
 version's own upgrade notes — read them at the tag they shipped under
@@ -24,6 +24,28 @@ That's the reminder working, not a false alarm. Generation is deterministic, so
 the diff is exactly what the new version emits differently and nothing else —
 worth reading rather than rubber-stamping.
 
+## Upgrading from 0.7.5
+
+A patch release. The regenerate is what changes behaviour — every module gains
+the per-call event — and the rest reaches an app only where it already relied
+on the old wording. Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| subscribe to `execute.graph_weaver`, or read `GraphWeaver::LogSubscriber`'s line | a second event, [`operation.graph_weaver`](logging.md#instrumentation), covers one `execute` start to typed result — retries, backoff and the cast — and the request events nest inside it. **The info log line is the operation's now**: `failed GraphWeaver::CastError` where it read `ok`, present under a `graphql:` tag, one line per retried call; the per-attempt line writes at debug. A module generated by 0.7.5 emits neither until regenerated |
+| spread a shared fragment on an interface or union that selects no `... on`, or exactly one — `grep -rn 'fragment .* on' app/graphql/fragments` | it [hoists](generated_modules.md#abstract-types) into `GraphQLTypes::<Fragment>` like every other shared fragment; app code naming `YourQuery::Result::Field` moves, and `srb tc` finds each site |
+| run `rake graph_weaver:queries:check` in CI for a graph that names its own `schema` — `rake graph_weaver:graphs` lists them | it re-introspects that graph's server (the dump's url, or the client's url or schema class) where it used to check the committed file, so CI needs the same reach a single-schema app already had. The verdict names what it checked against either way |
+| keep a composed supergraph on a graph that also names a `client` | `schema:refresh` steps over it with the recompose line where 0.7.5 could have overwritten it with the API schema |
+| parse `rake graph_weaver:unused` output, or run it `STRICT=1` | a `before_action`-loaded `@result` is credited again, and the coordinate printed comes from the query, not from any word in the file |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
 ## Upgrading from 0.7.4
 
 Read the left column and skip what isn't yours; the
@@ -227,7 +249,7 @@ only one here that shows up in production rather than in your code.
   Nothing raises: a subscriber comparing it to an Integer just stops matching. **A
   subscriber that branched on a 4xx/5xx reads `:http_status` now**, which is nil
   in-process. The whole payload is a documented contract —
-  [logging](logging.md#the-payload).
+  [logging](logging.md#the-request-payload).
 - **`respond_to?` on a result struct no longer answers true for a name that doesn't
   exist.** It used to say true for any near miss, which broke the standard
   duck-typing guard. **A branch that read the old answer now takes the other path**,

data/examples/README.md

@@ -34,5 +34,7 @@ looks like an app:
   fellow stargazers.
 
 Regeneration introspects GitHub's schema (a few seconds, cached to a gitignored
-`github/schema.json`); `run.rb` alone never introspects, because the generated
-modules already carry their types.
+`github/schema.json`); once that dump is there the repo's own `bin/generate`
+refreshes these modules along with every other generated file, offline. `run.rb`
+alone never introspects, because the generated modules already carry their
+types.

data/examples/github/generate.rb

@@ -6,15 +6,29 @@
 # the same workflow `rake graph_weaver:generate` runs in an app:
 #
 #      examples/github/generate.rb
+#
+# bin/generate calls generate! too, off the cached dump, so these files are
+# regenerated by the build like every other checked-in generated file.
 require_relative "setup"
 
-GraphWeaver.graph :github do
-  schema GraphWeaver.client.schema
-  queries File.join(__dir__, "queries")
-  output File.join(__dir__, "generated")
+module GithubExample
+  # The graph, declared once for both doors: this script, which introspects
+  # GitHub, and bin/generate, which passes the dump that introspection cached.
+  def self.generate!(schema_source)
+    GraphWeaver.graph :github do
+      schema schema_source
+      queries File.join(__dir__, "queries")
+      output File.join(__dir__, "generated")
+    end
+
+    GraphWeaver.generate!
+    GraphWeaver.changed_files
+  end
 end
 
-GraphWeaver.generate!
-changed = GraphWeaver.changed_files
-changed.each { |path| puts "wrote #{path}" }
-puts "already up to date" if changed.empty?
+if $PROGRAM_NAME == __FILE__
+  GithubExample.connect!
+  changed = GithubExample.generate!(GraphWeaver.client.schema)
+  changed.each { |path| puts "wrote #{path}" }
+  puts "already up to date" if changed.empty?
+end

data/examples/github/generated/star_mutation.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.6 — do not edit.
 
 module StarMutation
   extend T::Sig
@@ -117,7 +117,7 @@ module StarMutation
       "id" => GraphWeaver::Coerce.variable("id", OPERATION_NAME, id) { |v| GraphWeaver::Coerce.id(v, "ID") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(id: String, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/generated/stargazers_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.6 — do not edit.
 
 require "time"
 
@@ -257,7 +257,7 @@ module StargazersQuery
       "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(owner: String, name: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/generated/starred_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.6 — do not edit.
 
 module StarredQuery
   extend T::Sig
@@ -150,7 +150,7 @@ module StarredQuery
       "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(login: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/run.rb

@@ -7,6 +7,7 @@
 #
 #      examples/github/run.rb
 require_relative "setup"
+GithubExample.connect!
 
 # the checked-in typed modules (regenerate: examples/github/generate.rb)
 Dir[File.join(__dir__, "generated", "*.rb")].sort.each { |file| require file }

data/examples/github/setup.rb

@@ -4,15 +4,23 @@
 # Shared wiring for the GitHub example: auth and the client.
 require_relative "../../lib/graph_weaver"
 
-token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
-abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
-
-GraphWeaver.client = GraphWeaver.new(
-  "https://api.github.com/graphql",
-  auth: token,
+module GithubExample
   # used by generate.rb (and any dynamic parse): the first introspection
   # of GitHub's large schema dumps here — gitignored, a few seconds once,
   # instant after. run.rb's checked-in generated modules never introspect,
   # so running it alone won't create this file.
-  cache: File.join(__dir__, "schema.json"),
-)
+  SCHEMA_CACHE = File.join(__dir__, "schema.json")
+
+  # Requiring this file reaches nothing, so bin/generate can regenerate from
+  # SCHEMA_CACHE with no token; needing GitHub is this call.
+  def self.connect!
+    token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
+    abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
+
+    GraphWeaver.client = GraphWeaver.new(
+      "https://api.github.com/graphql",
+      auth: token,
+      cache: SCHEMA_CACHE,
+    )
+  end
+end

data/graph_weaver.gemspec

@@ -5,8 +5,6 @@ Gem::Specification.new do |s|
   # 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
   # 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
@@ -14,10 +12,21 @@ Gem::Specification.new do |s|
   # someone who only has the installed gem, not a checkout
   # CHANGELOG.md doesn't (259 KB, ~16% of the package) — changelog_uri below
   # points at the GitHub copy instead
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' \
-                     ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
-                     ':!:DECISIONS.md' ':!:CHANGELOG.md' ':!:Makefile' ':!:design' \
-                     ':!:research'`.split("\n") + [".yardopts"]
+  unpackaged = %w[spec sorbet bin design research CLAUDE.md PLAN.md REVIEW.md
+    NOTES.md DECISIONS.md CHANGELOG.md Makefile]
+  # git knows what is tracked; a checkout that isn't a repo — an unpacked gem,
+  # a vendored copy, a shallow CI export — has no such answer, and git's
+  # "fatal:" on stderr lands in the output of every subprocess a spec captures.
+  # So ask quietly, and walk the tree rather than ship nothing.
+  files = `git ls-files * #{unpackaged.map { |path| "':!:#{path}'" }.join(" ")} 2>/dev/null`.split("\n")
+  if files.empty?
+    files = Dir.glob("**/*", base: __dir__).reject do |path|
+      unpackaged.include?(path.split("/").first) || File.directory?(File.join(__dir__, path))
+    end
+  end
+  # ".yardopts" explicitly: neither list carries a dotfile, and rubydoc.info
+  # needs it shipped to render docstrings as markdown
+  s.files       = files + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"

data/lib/generators/graph_weaver/install_generator.rb

@@ -128,8 +128,7 @@ module GraphWeaver
       # .gitattributes turns no tooling on, so there is no app this surprises.
       def mark_generated_for_github
         body = File.read(gitattributes) if File.exist?(gitattributes)
-        # already marked — a re-run, or done by hand
-        globs = linguist_globs.reject { |glob| body&.include?(glob) }
+        globs = linguist_globs.reject { |glob| marked?(body, glob) }
         return if globs.empty?
 
         lines = globs.map { |glob| "#{glob} linguist-generated" }.join("\n")
@@ -246,6 +245,25 @@ module GraphWeaver
       # everything beneath dir — spelled as git reads it, not as rubocop does.
       def linguist_globs = generated_outputs.map { |dir| File.join(dir, "**") }
 
+      # git's own spellings of the one attribute: set, unset (`-`), unspecified
+      # (`!`), or valued.
+      LINGUIST = /\A[-!]?linguist-generated(?:=|\z)/
+
+      # Already marked — a re-run, or done by hand. A .gitattributes line is
+      # `<pattern> <attribute>…`, with `#` opening a comment, and the same
+      # directory is `dir/**`, `dir/*`, `dir/` or `dir`. Searching the body as
+      # one string instead let a comment that mentions the path suppress the
+      # mark, and saw only the spelling this generator writes.
+      def marked?(body, glob)
+        dir = glob.delete_suffix("/**")
+        body.to_s.lines.any? do |line|
+          pattern, *attributes = line.split
+          next false if pattern.nil? || pattern.start_with?("#")
+
+          pattern.chomp("**").chomp("*").chomp("/") == dir && attributes.any? { |a| LINGUIST.match?(a) }
+        end
+      end
+
       # 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.

data/lib/graph_weaver/client.rb

@@ -190,29 +190,6 @@ class GraphWeaver::Client
     run(query, **variables).data!
   end
 
-  # Does this query validate? The string form of GraphWeaver.check_queries,
-  # answering with the same JSON-ready hashes — `message`, `line`, `column`,
-  # plus `subgraphs` where a supergraph brands them — so an empty array means
-  # it validates:
-  #
-  #      client.check_query("query { viewer { login } }")   # => []
-  #      client.check_query("query { viewer { lgoin } }")
-  #      # => [{ "message" => "Field 'lgoin' doesn't exist on type 'User'",
-  #      #      "line" => 1, "column" => 17 }]
-  #
-  # Checked against this client's own schema — what `execute` would run
-  # against — so a url client introspects on first use as it always does, and
-  # nothing re-introspects the way check_queries defaults to. An unparseable
-  # source is an entry like any other; nothing here raises for a bad query.
-  # Shared fragments are inlined from fragments: the same way every other door
-  # inlines them.
-  def check_query(source, fragments: GraphWeaver.fragments_paths)
-    GraphWeaver::Internal::QueryCheck.errors(
-      schema, source, GraphWeaver::Codegen.load_fragments(fragments),
-      GraphWeaver::Internal::QueryCheck.routing_table_for(schema_source),
-    )
-  end
-
   private
 
   # Anything already speaking the client contract — another Client,

data/lib/graph_weaver/codegen/aliases.rb

@@ -34,6 +34,13 @@ class GraphWeaver::Codegen
         rescue UnknownSegment => e
           # names nothing in the schema, so no selection would fit — offering
           # optional: as the way out would just hide the typo
+          raise e.class, qualify(node, e.message)
+        rescue HoistedSegment => e
+          # optional: still skips it, but the message doesn't offer it: the two
+          # fixes it names are the only ones that end with an accessor, and no
+          # change to the fragment would make the path fit
+          next nil if spec[:optional]
+
           raise e.class, qualify(node, e.message)
         rescue GraphWeaver::Error => e
           # a path that doesn't fit THIS query's selection: optional simply
@@ -86,7 +93,10 @@ class GraphWeaver::Codegen
     # ever satisfy it, so it's a typo (or a wire-cased name), not a path that
     # doesn't fit this query. optional: skips the latter, never this.
     UnknownSegment = Class.new(GraphWeaver::Error)
-    private_constant :ALIAS_RESERVED, :LIST_SELECTORS, :UnknownSegment
+
+    # A segment inside a struct another module owns — see refuse_hoisted!.
+    HoistedSegment = Class.new(GraphWeaver::Error)
+    private_constant :ALIAS_RESERVED, :LIST_SELECTORS, :UnknownSegment, :HoistedSegment
 
     # Walk a dotted path through this struct's selected shape, building the
     # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
@@ -158,11 +168,13 @@ class GraphWeaver::Codegen
 
     # A hop landing on a hoisted shared fragment: the struct is another
     # module's, so the path stops here. Which query hoists is a property of how
-    # that query spreads the fragment, so optional: still skips it.
+    # that query spreads the fragment, so optional: still skips it — but
+    # selecting differently inside the fragment never makes the path fit, so
+    # the message names only the two fixes that do.
     def refuse_hoisted!(node, name, ref, seg)
       return unless ref
 
-      raise GraphWeaver::Error,
+      raise HoistedSegment,
         "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is inside the shared fragment " \
         "#{ref.class_name}, which hoists to #{@types_namespace}::#{ref.class_name} — a path can't " \
         "read into it. Register the alias on #{ref.graphql_type}, or select a field beside the " \

data/lib/graph_weaver/codegen/emit.rb

@@ -521,10 +521,11 @@ class GraphWeaver::Codegen
           flag ? "#{var.kwarg}: (#{flag} = true; nil)" : "#{var.kwarg}: nil"
         } + ["client: nil"]
 
-      # QueryModule#dispatch reads QUERY/OPERATION_NAME/GRAPH off the module,
-      # so the gem gets to bracket every request without a line of it landing
-      # in every generated file
-      call = "dispatch(variables, client:)"
+      # QueryModule#dispatch reads QUERY/OPERATION_NAME/GRAPH off the module
+      # and closes the operation event over the cast the block does, so the
+      # gem brackets the whole call — request and cast — without a line of it
+      # landing in every generated file
+      call = "dispatch(variables, client:) { |raw| from_response(raw) }"
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # the typed result, or a raised QueryError.
@@ -534,7 +535,7 @@ class GraphWeaver::Codegen
       out << "  def self.execute(#{kwargs.join(", ")})"
       emit_variables(out, required, optional, omitted)
       out << ""
-      out << "    from_response(#{call})"
+      out << "    #{call}"
       out << "  end"
       out << ""
       out << "  sig { params(#{sig_params.join(", ")}).returns(Result).checked(:never) }"
@@ -547,7 +548,7 @@ class GraphWeaver::Codegen
         # left out is exactly what a Ruby call can't forward
         emit_variables(out, required, optional, omitted)
         out << ""
-        out << "    from_response(#{call}).data!"
+        out << "    #{call}.data!"
       end
       out << "  end"
       out << ""

data/lib/graph_weaver/codegen/enum_type.rb

@@ -83,7 +83,31 @@ class GraphWeaver::Codegen
           "add them, pin with map:, or absorb with fallback:"
       end
 
-      [from_wire, to_wire(from_wire, aliases)]
+      wire = to_wire(from_wire, aliases)
+      warn_unsendable(wire)
+      [from_wire, wire]
+    end
+
+    # The other direction, which nothing said: a member no wire value maps back
+    # from. A warning, not a refusal — one app-wide T::Enum serving two APIs
+    # that each expose a subset is a real shape, and the call that carries such
+    # a member is refused by name at runtime (InputStruct.enum_wire), so no
+    # wrong answer gets through either way. Warned on the channel
+    # validate_registrations! already narrates a mismatched registration on.
+    # fallback: is exempt: standing for what the schema doesn't declare is
+    # exactly what it is for.
+    def warn_unsendable(wire)
+      unsendable = type.values - wire.keys - [fallback].compact
+      return if unsendable.empty?
+
+      # a T::Enum member inspects as #<Type::Name>
+      names = unsendable.map { |member| member.inspect[2..-2] }.join(", ")
+      them = unsendable.one? ? "it" : "them"
+      GraphWeaver::Internal::Log.log(:warn) do
+        "#{graphql_name} has no value for #{type} member(s) #{names} — a kwarg carrying " \
+          "#{them} is refused at the call; map onto a matching T::Enum, or name the drift " \
+          "member with fallback:"
+      end
     end
 
     # alias spelling => the value it is read as, checked against what the
@@ -185,7 +209,7 @@ class GraphWeaver::Codegen
         groups = ambiguous.values.map { |pairs| pairs.map(&:first) }
         more = ambiguous.size - 1
         raise GraphWeaver::Error,
-          "enum #{graphql_name}: #{groups.first.join(" and ")} both map onto the #{type} member " \
+          "enum #{graphql_name}: #{groups.first.join(" and ")} all map onto the #{type} member " \
           "#{member.serialize.to_s.inspect}#{" (and #{more} more)" unless more.zero?} — say which spelling " \
           "goes on the wire:\n  #{EnumType.alias_suggestion(graphql_name, groups, type)}"
       end

data/lib/graph_weaver/codegen/nodes.rb

@@ -293,7 +293,9 @@ class GraphWeaver::Codegen
     # #as_json. Without a fallback the table is total and a miss is a real
     # mistake, so it still raises.
     def serialize(expr, _depth)
-      return "#{const_prefix}_TO_WIRE.fetch(#{expr})" unless @fallback
+      unless @fallback
+        return "GraphWeaver::InputStruct.enum_wire(#{@graphql_name.inspect}, #{const_prefix}_TO_WIRE, #{expr})"
+      end
 
       "#{const_prefix}_TO_WIRE.fetch(#{expr}) { |member| member.serialize }"
     end
@@ -406,6 +408,23 @@ class GraphWeaver::Codegen
     def bare_type = "#{class_name}::Type"
   end
 
+  # An abstract fragment narrowing to one member hoists to that member's
+  # struct, and narrowing filters — so the match is tested at the reference,
+  # the way NarrowedNode does it, rather than inside a T::Struct.from_h that
+  # has no way to answer nil. See NarrowedNode for what `typename` being
+  # absent means.
+  class NarrowedRefNode < HoistedRefNode
+    def initialize(class_name, graphql_type = nil, typename: nil)
+      super(class_name, graphql_type)
+      @typename = typename
+    end
+
+    def cast(expr, depth)
+      match = @typename ? "#{expr}[\"__typename\"] == #{@typename.inspect}" : "!#{expr}.empty?"
+      "(#{match} ? #{super} : nil)"
+    end
+  end
+
   # An input-object variable: emitted as a module-level T::Struct whose
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,
@@ -479,5 +498,5 @@ class GraphWeaver::Codegen
   # from inside the walk.
   private_constant :Node, :Scalar, :NonNull, :List, :ObjectNode, :EnumNode,
     :MappedEnum, :NarrowedNode, :UnionNode, :HoistedRefNode, :UnionRefNode,
-    :InputNode, :RepresentationNode
+    :NarrowedRefNode, :InputNode, :RepresentationNode
 end