graph_weaver 0.7.3 → 0.7.5

data/examples/github/generated/stargazers_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.3 — do not edit.
+# Generated by GraphWeaver 0.7.4 — do not edit.
 
 require "time"
 
@@ -85,6 +85,14 @@ module StargazersQuery
                 rescue StandardError => e
                   raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
                 end
+
+                sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+                def as_json(*_options)
+                  {
+                    "nameWithOwner" => name_with_owner,
+                    "stargazerCount" => stargazer_count,
+                  }
+                end
               end
 
               const :nodes, T.nilable(T::Array[T.nilable(Nodes)])
@@ -99,6 +107,13 @@ module StargazersQuery
               rescue StandardError => e
                 raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
               end
+
+              sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+              def as_json(*_options)
+                {
+                  "nodes" => nodes&.then { |v1| v1.map { |v2| v2&.then { |v3| v3.as_json } } },
+                }
+              end
             end
 
             const :login, String
@@ -117,6 +132,15 @@ module StargazersQuery
             rescue StandardError => e
               raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
             end
+
+            sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+            def as_json(*_options)
+              {
+                "login" => login,
+                "name" => name,
+                "repositories" => repositories.as_json,
+              }
+            end
           end
 
           const :starred_at, Time
@@ -125,7 +149,7 @@ module StargazersQuery
           sig { params(data: T::Hash[String, T.untyped]).returns(Edges) }
           def self.from_h(data)
             new(
-              starred_at: GraphWeaver::Hints.field(self, "starredAt") { Time.parse(data.fetch("starredAt")) },
+              starred_at: GraphWeaver::Hints.field(self, "starredAt") { Time.iso8601(data.fetch("starredAt")) },
               node: Node.from_h(data.fetch("node")),
             )
           rescue GraphWeaver::Error
@@ -133,6 +157,14 @@ module StargazersQuery
           rescue StandardError => e
             raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
           end
+
+          sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+          def as_json(*_options)
+            {
+              "starredAt" => GraphWeaver::Coerce.timestamp(starred_at),
+              "node" => node.as_json,
+            }
+          end
         end
 
         const :edges, T.nilable(T::Array[T.nilable(Edges)])
@@ -147,6 +179,13 @@ module StargazersQuery
         rescue StandardError => e
           raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
         end
+
+        sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+        def as_json(*_options)
+          {
+            "edges" => edges&.then { |v1| v1.map { |v2| v2&.then { |v3| v3.as_json } } },
+          }
+        end
       end
 
       const :id, String
@@ -167,6 +206,16 @@ module StargazersQuery
       rescue StandardError => e
         raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
       end
+
+      sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def as_json(*_options)
+        {
+          "id" => id,
+          "nameWithOwner" => name_with_owner,
+          "stargazerCount" => stargazer_count,
+          "stargazers" => stargazers.as_json,
+        }
+      end
     end
 
     const :repository, T.nilable(Repository)
@@ -181,6 +230,13 @@ module StargazersQuery
     rescue StandardError => e
       raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
     end
+
+    sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def as_json(*_options)
+      {
+        "repository" => repository&.then { |v1| v1.as_json },
+      }
+    end
   end
 
   # client — see GraphWeaver::QueryModule
@@ -196,9 +252,9 @@ module StargazersQuery
   sig { params(owner: String, name: String, first: Integer, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
   def self.execute(owner:, name:, first:, client: nil)
     variables = {
-      "owner" => GraphWeaver::Coerce.variable("owner", OPERATION_NAME, owner) { |v| GraphWeaver::Coerce.string(v) },
-      "name" => GraphWeaver::Coerce.variable("name", OPERATION_NAME, name) { |v| GraphWeaver::Coerce.string(v) },
-      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v) },
+      "owner" => GraphWeaver::Coerce.variable("owner", OPERATION_NAME, owner) { |v| GraphWeaver::Coerce.string(v, "String") },
+      "name" => GraphWeaver::Coerce.variable("name", OPERATION_NAME, name) { |v| GraphWeaver::Coerce.string(v, "String") },
+      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
     from_response(dispatch(variables, client:))

data/examples/github/generated/starred_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.3 — do not edit.
+# Generated by GraphWeaver 0.7.4 — do not edit.
 
 module StarredQuery
   extend T::Sig
@@ -57,6 +57,14 @@ module StarredQuery
           rescue StandardError => e
             raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
           end
+
+          sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+          def as_json(*_options)
+            {
+              "nameWithOwner" => name_with_owner,
+              "stargazerCount" => stargazer_count,
+            }
+          end
         end
 
         const :total_count, Integer
@@ -73,6 +81,14 @@ module StarredQuery
         rescue StandardError => e
           raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
         end
+
+        sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+        def as_json(*_options)
+          {
+            "totalCount" => total_count,
+            "nodes" => nodes&.then { |v1| v1.map { |v2| v2&.then { |v3| v3.as_json } } },
+          }
+        end
       end
 
       const :starred_repositories, StarredRepositories
@@ -87,6 +103,13 @@ module StarredQuery
       rescue StandardError => e
         raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
       end
+
+      sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def as_json(*_options)
+        {
+          "starredRepositories" => starred_repositories.as_json,
+        }
+      end
     end
 
     const :user, T.nilable(User)
@@ -101,6 +124,13 @@ module StarredQuery
     rescue StandardError => e
       raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
     end
+
+    sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def as_json(*_options)
+      {
+        "user" => user&.then { |v1| v1.as_json },
+      }
+    end
   end
 
   # client — see GraphWeaver::QueryModule
@@ -116,8 +146,8 @@ module StarredQuery
   sig { params(login: String, first: Integer, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
   def self.execute(login:, first:, client: nil)
     variables = {
-      "login" => GraphWeaver::Coerce.variable("login", OPERATION_NAME, login) { |v| GraphWeaver::Coerce.string(v) },
-      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v) },
+      "login" => GraphWeaver::Coerce.variable("login", OPERATION_NAME, login) { |v| GraphWeaver::Coerce.string(v, "String") },
+      "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
     from_response(dispatch(variables, client:))

data/lib/generators/graph_weaver/install_generator.rb

@@ -119,6 +119,28 @@ module GraphWeaver
         end
       end
 
+      # The same thing the header and the Exclude above say, told to GitHub:
+      # linguist-generated collapses these files in a diff ("Load diff") and
+      # drops them from the language breakdown. Display only — they stay
+      # versioned, expandable, and `git diff` here is untouched.
+      #
+      # Written even when there is no .gitattributes, unlike .rubocop.yml: a
+      # .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) }
+        return if globs.empty?
+
+        lines = globs.map { |glob| "#{glob} linguist-generated" }.join("\n")
+        marks = <<~TEXT + lines + "\n"
+          # Machine-written by `rake graph_weaver:generate` — GitHub collapses it in
+          # diffs and leaves it out of the language breakdown.
+        TEXT
+
+        body ? append_to_file(GITATTRIBUTES, "\n#{marks}") : create_file(GITATTRIBUTES, marks)
+      end
+
       # The `graphql:` tags need this require, and it has to be somewhere
       # rspec actually loads. A spec/support file is not: rspec-rails ships
       # the spec/support glob commented out, so the require sat there doing
@@ -191,6 +213,7 @@ module GraphWeaver
       private
 
       RUBOCOP_CONFIG = ".rubocop.yml"
+      GITATTRIBUTES = ".gitattributes"
 
       # rails_helper first: rspec-rails writes both, and only rails_helper
       # has Rails booted by the time the require runs.
@@ -203,6 +226,8 @@ module GraphWeaver
 
       def rubocop_config = File.join(GraphWeaver.root, RUBOCOP_CONFIG)
 
+      def gitattributes = File.join(GraphWeaver.root, GITATTRIBUTES)
+
       # Parsed, not counted: a `---` can also be a line inside a block scalar.
       # A file rubocop itself can't read is left to rubocop to complain about.
       def yaml_documents(body)
@@ -213,9 +238,13 @@ module GraphWeaver
 
       # Every graph's output directory, so a multi-schema app is covered by
       # the same run — read off the graphs rather than restated here.
-      def generated_globs
-        GraphWeaver.graphs.map { |graph| File.join(graph.output, "**/*") }.uniq
-      end
+      def generated_outputs = GraphWeaver.graphs.map(&:output).uniq
+
+      def generated_globs = generated_outputs.map { |dir| File.join(dir, "**/*") }
+
+      # gitattributes patterns are gitignore-style, where `dir/**` is
+      # everything beneath dir — spelled as git reads it, not as rubocop does.
+      def linguist_globs = generated_outputs.map { |dir| File.join(dir, "**") }
 
       # This install run is the one moment the user is guaranteed to be
       # reading, and a composed supergraph changes what the next steps are:

data/lib/graph_weaver/client.rb

@@ -190,6 +190,29 @@ 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

@@ -119,6 +119,7 @@ class GraphWeaver::Codegen
           nilable = true
         else
           obj = object_of(cur)
+          refuse_hoisted!(node, name, hoisted_of(cur), seg)
           unless obj
             hint = if list_of(cur)
               " — use .first or .last to pick an element"
@@ -155,6 +156,19 @@ class GraphWeaver::Codegen
       ObjectNode::Alias.new(name, expr, type)
     end
 
+    # 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.
+    def refuse_hoisted!(node, name, ref, seg)
+      return unless ref
+
+      raise GraphWeaver::Error,
+        "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 " \
+        "spread to keep the struct local"
+    end
+
     # Separate "this query didn't select it" from "no query could": a segment
     # the schema doesn't declare on the type is a mistake in the registration,
     # so it raises even for an optional alias — which otherwise turns a typo
@@ -185,7 +199,7 @@ class GraphWeaver::Codegen
     # The leaf's Sorbet type as referenced from the aliased struct. Generated
     # nested constants (structs, enums, unions) must carry the container path,
     # since the delegator's `sig` is emitted in an outer struct where a bare
-    # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted union refs are
+    # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted refs are
     # already top-level. `containers` is the class-name chain to the leaf.
     def qualified_alias_type(node, containers)
       node = node.of if node.is_a?(NonNull)
@@ -203,10 +217,17 @@ class GraphWeaver::Codegen
       # there from the shared enums module — either way, no container prefix
       when EnumNode then node.class_name
       when UnionNode then "#{prefix}#{node.bare_type}"
-      else node.bare_type # Scalar, MappedEnum, UnionRefNode — already top-level
+      else node.bare_type # Scalar, MappedEnum, a hoisted ref — already top-level
       end
     end
 
+    # the hoisted-fragment reference a node resolves to (through NON_NULL), or nil
+    def hoisted_of(node)
+      node = T.let(node, T.untyped)
+      node = node.of while node.is_a?(NonNull)
+      node if node.is_a?(HoistedRefNode)
+    end
+
     # the List a node wraps (through NON_NULL), or nil
     def list_of(node)
       node = T.let(node, T.untyped)

data/lib/graph_weaver/codegen/emit.rb

@@ -97,7 +97,7 @@ class GraphWeaver::Codegen
     # both reference it by that name.
     def shared_enum_names
       @mapped_enums.each_value.flat_map { |m| ["#{m.const_prefix}_FROM_WIRE", "#{m.const_prefix}_TO_WIRE"] } +
-        @enums.each_value.map(&:class_name)
+        @enums.each_value.flat_map { |e| e.aliased? ? [e.class_name, e.alias_const] : [e.class_name] }
     end
 
     # Inputs: only the variable root types — the names this module's own
@@ -130,8 +130,8 @@ class GraphWeaver::Codegen
     # The shared types artifact as files: one file per type under types/, plus
     # types.rb — the manifest that requires them in the order the runtime needs
     # (see below). One rule for all three kinds, so a schema migration diffs
-    # exactly the types it touched whether they're inputs, enums or unions.
-    def emit_types_files(unions)
+    # exactly the types it touched whether they're inputs, enums or fragments.
+    def emit_types_files(fragments)
       files = {}
       # a mapped enum's constants are its wire tables, but the file is still
       # named for the GraphQL enum — one type, one file, whichever it is
@@ -142,15 +142,15 @@ class GraphWeaver::Codegen
       }
       inputs, = ordered_inputs
       structs = inputs.map { |input| type_file(files, input.class_name) { |out| emit_input(input, out, 1) } }
-      hoisted = unions.map { |union| type_file(files, union.class_name) { |out| emit_union(union, out, 1) } }
+      hoisted = fragments.map { |node| type_file(files, node.class_name) { |out| emit_nested(node, out, 1) } }
 
       out = []
       out << "# typed: strict"
       out << "# frozen_string_literal: true"
       out << ""
       out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit. Shared types for this schema —"
-      out << "# input types, enums, and unions hoisted from shared fragments — one file"
-      out << "# per type; query modules alias what they use."
+      out << "# input types, enums, and the types hoisted out of shared fragments — one"
+      out << "# file per type; query modules alias what they use."
       out << ""
       requires = @requires.uniq.sort
       if requires.any?
@@ -175,7 +175,7 @@ class GraphWeaver::Codegen
       # both spell them bare, and a T::Enum can't be forward-declared the way
       # an input struct can
       if enums.any? && (structs.any? || hoisted.any?)
-        out << "# enums first — input structs and union members spell them bare"
+        out << "# enums first — input structs and hoisted fragments spell them bare"
       end
       (enums.sort + structs.sort + hoisted.sort).each do |file|
         out << "require_relative #{file.delete_suffix(".rb").inspect}"
@@ -210,11 +210,11 @@ class GraphWeaver::Codegen
     # assembled from the generator's walked state.
     def emit_module(root, variables, representations = [], operation_name = nil)
       # Every shared type this module names: its variable root inputs, the
-      # enums it reached, and the unions it hoisted (aliased so <Name>::Type
-      # and <Name>.from_h resolve to the shared module).
+      # enums it reached, and the fragments it hoisted (aliased so <Name> and
+      # <Name>.from_h resolve to the shared module).
       aliases = if @types_namespace
         (shared_input_names(variables) + shared_enum_names +
-          @used_unions.map { |name| camelize(name) }).uniq.sort
+          @used_fragments.map { |name| camelize(name) }).uniq.sort
       else
         []
       end
@@ -338,11 +338,23 @@ class GraphWeaver::Codegen
       node.values.each do |value|
         out << "#{pad}    #{camelize(value.downcase)} = new(#{value.inspect})"
       end
+      if node.fallback?
+        out << "#{pad}    # every other wire value casts here (register_enum fallback: true)"
+        out << "#{pad}    #{node.fallback} = new(#{GraphWeaver::Internal::ENUM_FALLBACK_WIRE.inspect})"
+      end
       out << "#{pad}  end"
       out << "#{pad}end"
+      return unless node.aliased?
+
+      out << "#{pad}# wire spellings read as another value of #{node.class_name} (register_enum alias:)"
+      out << "#{pad}#{node.alias_const} = T.let({"
+      node.aliases.each { |from, to| out << "#{pad}  #{from.inspect} => #{to.inspect}," }
+      out << "#{pad}}.freeze, T::Hash[String, String])"
     end
 
-    # module-level wire translation tables for an app-mapped enum
+    # module-level wire translation tables for an app-mapped enum. TO_WIRE is
+    # written out rather than inverted from FROM_WIRE: an alias puts two
+    # spellings on one member, and only one of them goes back out.
     def emit_mapped_enum(node, out, indent)
       pad = "  " * indent
       type = node.bare_type
@@ -354,7 +366,11 @@ class GraphWeaver::Codegen
         out << "#{pad}  #{wire.inspect} => #{type}.deserialize(#{member.serialize.to_s.inspect}),"
       end
       out << "#{pad}}.freeze, T::Hash[String, #{type}])"
-      out << "#{pad}#{prefix}_TO_WIRE = T.let(#{prefix}_FROM_WIRE.invert.freeze, T::Hash[#{type}, String])"
+      out << "#{pad}#{prefix}_TO_WIRE = T.let({"
+      node.to_wire.each do |member, wire|
+        out << "#{pad}  #{type}.deserialize(#{member.serialize.to_s.inspect}) => #{wire.inspect},"
+      end
+      out << "#{pad}}.freeze, T::Hash[#{type}, String])"
     end
 
     def emit_object(node, out, indent)
@@ -383,7 +399,10 @@ class GraphWeaver::Codegen
       node.fields.each do |field|
         note = renamed_note(field.prop, field.key)
         out << "#{pad}  #{note}" if note
-        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}"
+        # a prop satisfying a mixin's abstract sig has to declare the override,
+        # and a `const` says it as a rule — there is no sig to put it in
+        override = node.overrides.include?(field.prop) ? ", override: true" : ""
+        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{override}"
       end
 
       out << ""
@@ -418,7 +437,7 @@ class GraphWeaver::Codegen
       # selected field onto the struct, next to the honest wire data
       node.aliases.each do |a|
         out << ""
-        out << "#{pad}  sig { returns(#{a.type}) }"
+        out << "#{pad}  sig { #{"override." if node.overrides.include?(a.name)}returns(#{a.type}) }"
         out << "#{pad}  def #{a.name} = #{a.expr}"
       end
       out << "#{pad}end"
@@ -677,13 +696,13 @@ class GraphWeaver::Codegen
         out << "#{pad}  const :#{field.prop}, #{type}#{default}"
       end
       out << ""
-      out << "#{pad}  # (prop, wire, required, serializer, coercer, coordinate) per field"
+      out << "#{pad}  # (prop, wire, required, serializer, coercer, coordinate, type) per field"
       out << "#{pad}  FIELDS = T.let(["
       node.fields.each do |field|
         serializer = field.node.serialize_identity? ? "nil" : "->(v) { #{field.node.serialize("v", 1)} }"
         coercer = field.node.hash_coerce_identity? ? "nil" : "->(v) { #{field.node.hash_coerce("v", 1)} }"
         coordinate = "#{node.graphql_name}.#{field.wire}"
-        out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}, #{coordinate.inspect}),"
+        out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}, #{coordinate.inspect}, #{field.type.inspect}),"
       end
       out << "#{pad}  ].freeze, T::Array[GraphWeaver::InputStruct::Field])"
       # InputStruct reads it with const_get, which privacy doesn't block