graph_weaver 0.7.3 → 0.7.5

data/lib/graph_weaver.rb

@@ -29,7 +29,11 @@ module GraphWeaver
   # How far into a file to look for it: the header sits under the `typed:` and
   # `frozen_string_literal:` magic comments, never deeper.
   HEADER_SCAN_LINES = 10
-  private_constant :GENERATED_HEADER, :HEADER_SCAN_LINES
+
+  # Where a graph declares the modules its extend_type blocks mint — an .rbi,
+  # so the declaration reaches `srb tc` and nothing else (see helpers_rbi).
+  HELPERS_RBI = "type_helpers.rbi"
+  private_constant :GENERATED_HEADER, :HEADER_SCAN_LINES, :HELPERS_RBI
 
   class << self
     # A client for one GraphQL server — transport, schema, and scoped
@@ -210,7 +214,7 @@ module GraphWeaver
     attr_accessor :skip_generated_load
 
     # The name of the shared module — the types that live once per schema
-    # (input types, enums, unions hoisted from shared fragments) and are
+    # (input types, enums, the types hoisted from shared fragments) and are
     # aliased into every query module that touches them. Constant, not derived
     # from where you put the files: set it globally, or pass types_module: per
     # generate!. A multi-schema layout names it in the same initializer that
@@ -484,12 +488,13 @@ module GraphWeaver
     end
     private :orphaned
 
-    # Every .rb under output that GraphWeaver wrote, identified by the header
+    # Every file under output that GraphWeaver wrote, identified by the header
     # it emits. The header — not a *_query.rb glob — is what makes pruning
     # safe: this is a real directory, and a hand-written file in it must
-    # survive regeneration.
+    # survive regeneration. .rbi too: a stale type-helper declaration would
+    # keep an app's srb tc green over an include that is gone.
     def generated_files(output)
-      Dir[File.join(Internal::Util.resolve(output), "**/*.rb")].sort.select do |path|
+      Dir[File.join(Internal::Util.resolve(output), "**/*.{rb,rbi}")].sort.select do |path|
         File.foreach(path).first(HEADER_SCAN_LINES).any? { |line| line.start_with?(GENERATED_HEADER) }
       end
     end
@@ -618,6 +623,9 @@ module GraphWeaver
     # (products, reviews)", plus a "subgraphs" key — since knowing whose
     # code to look at is half the answer. A plain schema is unaffected.
     #
+    # One query you have as a *string* is Client#check_query — the same
+    # entries, against that client's own schema.
+    #
     # A different question from verify_generated!, which asks whether the
     # committed Ruby matches the committed schema. `rake
     # graph_weaver:queries:check` prints this and exits non-zero.
@@ -628,7 +636,7 @@ module GraphWeaver
         checked = checked_schema(graph)
         table = checked_routing_table(graph)
         Internal::Util.query_files(graph.queries).each do |path|
-          errors = validation_errors(checked, File.read(path), shared, table)
+          errors = Internal::QueryCheck.errors(checked, File.read(path), shared, table)
           next if errors.empty?
 
           # keyed by file, as it has always been — and two graphs may share a
@@ -647,20 +655,11 @@ module GraphWeaver
     def checked_schema(graph) = graph.named_schema? ? graph.schema : refreshed_schema
     private :checked_schema
 
-    # The routing table behind the schema check_queries is about to use,
-    # when there is one: a composed supergraph dump says who resolves what,
-    # so a validation error can name the subgraph whose code to look at. nil
-    # for every other source — a plain schema is entirely unaffected — and
-    # nil when a live schema class is what gets checked, since the dump then
-    # isn't what the errors came from.
+    # The routing table behind the schema check_queries is about to use, when
+    # there is one — nil when a live schema class is what gets checked, since
+    # the dump then isn't what the errors came from.
     def checked_routing_table(graph)
-      return if graph.live_schema
-
-      path = graph.dump_path
-      return unless path&.end_with?(".graphql", ".gql")
-
-      sdl = File.read(path)
-      SchemaLoader.routing_table(sdl) if SchemaLoader.federation_sdl?(sdl)
+      Internal::QueryCheck.routing_table_for(graph.dump_path) unless graph.live_schema
     end
     private :checked_routing_table
 
@@ -686,53 +685,6 @@ module GraphWeaver
     end
     private :refreshed_schema
 
-    # One query's schema-validation errors as JSON-ready hashes, with the
-    # source position graphql-ruby reports. Unparseable counts as an error
-    # too — it doesn't validate either, and inline_fragments (which parses
-    # first) has already branded it with its position.
-    def validation_errors(schema, source, shared, table = nil)
-      # path omitted: the caller keys the report by file, so branding the
-      # message with it too would just print the path twice
-      schema.validate(Codegen.inline_fragments(source, shared)).map do |error|
-        detail = error.to_h
-        location = detail["locations"]&.first || {}
-        subgraphs = table ? attribute(table, detail["extensions"]) : []
-        entry = {
-          "message" => subgraphs.empty? ? error.message : "#{error.message} (#{subgraphs.join(", ")})",
-          "line" => location["line"],
-          "column" => location["column"],
-        }
-        subgraphs.empty? ? entry : entry.merge("subgraphs" => subgraphs)
-      end
-    rescue GraphWeaver::QueryValidationError => e
-      # an unparseable query: codegen folds the position (and the file) into
-      # the message, and this report keeps them separate — same splitter the
-      # rendered error uses, so the two can't drift apart
-      e.errors.map do |detail|
-        _path, _position, message = QueryValidationError.split(detail)
-        detail.transform_keys(&:to_s).merge("message" => message)
-      end
-    end
-    private :validation_errors
-
-    # Which subgraphs a validation error is about, on a federated schema:
-    # "Field 'weight' doesn't exist on type 'Product'" is much less useful
-    # than the same line plus "(products)" — whose code to look at, whose
-    # team to talk to. graphql-ruby reports the coordinate structurally, so
-    # this is a lookup rather than message parsing. Both halves of the
-    # coordinate are required: an argument error reports typeName "Field"
-    # (the AST node kind, not a type), and looking that up would attribute
-    # confidently and wrongly.
-    def attribute(table, extensions)
-      return [] unless extensions
-
-      type_name, field_name = extensions.values_at("typeName", "fieldName")
-      return [] unless type_name && field_name
-
-      table.responsible(type_name, field_name)
-    end
-    private :attribute
-
     # Load the generated modules — one line in an initializer or spec
     # helper (loading happens only when you call this; skip it and
     # require files yourself if you'd rather):
@@ -843,7 +795,7 @@ module GraphWeaver
 
     # (filename, source) per artifact. Types a schema shares across queries —
     # input types, schema enums, and each named shared fragment spread as a
-    # whole-union field — are emitted once into the shared module, with query
+    # whole field — are emitted once into the shared module, with query
     # modules aliasing what they use. That's the difference between hundreds of
     # duplicated bool_exp structs (or one Ruby class per query for the same
     # schema enum) and one copy per schema. (Single-query parse inlines
@@ -862,7 +814,8 @@ module GraphWeaver
       @unmatched_registrations |= registry.unmatched_registrations(schema)
 
       used = { inputs: [], enums: [], mapped: [] }
-      used_unions = []
+      hoisted = []
+      helpers = []
       shared = Codegen.load_fragments(fragments)
 
       refusals = []
@@ -878,14 +831,15 @@ module GraphWeaver
           name:,
           graph_name: graph.name,
           types_namespace: graph.types_module,
-          hoistable_unions: Codegen.shared_fragment_spreads(source, shared, path),
+          hoistable_fragments: Codegen.shared_fragment_spreads(source, shared, path),
           path:,
           registry:,
         )
         out = codegen.generate
         codegen.variable_type_names.each { |kind, names| used[kind] |= names }
         found.concat(codegen.untyped_scalars).uniq!
-        used_unions |= codegen.used_union_names
+        hoisted |= codegen.used_fragment_names
+        helpers |= codegen.block_helpers
         [filename, out]
       rescue GraphWeaver::Error => e
         # collected, not raised: nothing is written either way, and an adopter
@@ -895,24 +849,60 @@ module GraphWeaver
       end
       refuse_all!(refusals, paths.size)
 
-      if used_unions.any? || used.values.any?(&:any?)
+      if hoisted.any? || used.values.any?(&:any?)
         refuse_duplicate_types!(seen, graph)
         codegen = Codegen.new(schema:, query: "", name: graph.types_module, registry:)
         types = codegen.generate_types(
           inputs: used[:inputs], enums: used[:enums] + used[:mapped],
-          unions: used_unions, fragments: shared,
+          hoisted:, fragments: shared,
         )
         found.concat(codegen.untyped_scalars).uniq!
+        helpers |= codegen.block_helpers
         # these land in the graph's output like any other file, so they collide
         # with another graph's the same way
         types.each_key { |filename| refuse_duplicate_file!(seen, filename, graph, graph.types_module) }
         plan = types.to_a + plan
       end
 
+      if helpers.any?
+        refuse_duplicate_file!(seen, HELPERS_RBI, graph, "the extend_type blocks")
+        plan = [[HELPERS_RBI, helpers_rbi(helpers)]] + plan
+      end
+
       plan
     end
     private :generation_plan
 
+    # One rule: generation declares every constant it includes. A block-form
+    # extend_type mints its mixin at registration, so no source file declares
+    # GraphWeaver::TypeHelpers::Pet — and an app's `srb tc` failed on every
+    # generated include of one ("Unable to resolve constant ...").
+    #
+    # An .rbi rather than Ruby, because Ruby never loads one: the include stays
+    # the only thing that resolves the constant at runtime, which keeps a
+    # dropped registration loud (see load_generated!) instead of silently
+    # handing the struct an empty module.
+    def helpers_rbi(names)
+      # `module A::B` does not define A, so each outer segment is opened first
+      declared = names.flat_map { |name|
+        segments = name.split("::")
+        (1...segments.size).map { |i| segments.first(i + 1).join("::") }
+      }.uniq.sort
+      # assembled line by line, not from a heredoc (as Emit does): a `# typed:`
+      # sigil at the start of a line is the sigil srb reads for THIS file
+      lines = [
+        "# typed: strict",
+        "",
+        "#{GENERATED_HEADER} #{VERSION} — do not edit. The modules this graph's",
+        "# extend_type blocks mint, declared so `srb tc` can resolve the includes",
+        "# in the generated code. Ruby never loads an .rbi; the registrations do",
+        "# the real work.",
+        "",
+      ]
+      (lines + declared.map { |mod| "module #{mod}; end" }).join("\n") + "\n"
+    end
+    private :helpers_rbi
+
     # Every query that refused, in one error. One refusal is re-raised as
     # itself, so a single bad file reads exactly as it always has — class,
     # message and all; several become one list, because clearing them a file
@@ -1054,8 +1044,24 @@ module GraphWeaver
     # strict), requires: names files the generated code should require.
     # Generation fails naming any schema value that doesn't resolve —
     # exhaustiveness checked ahead of runtime.
-    def register_enum(graphql_name, type, positional_map = nil, map: nil, fallback: nil, requires: nil)
-      Codegen.register_enum(graphql_name, type, positional_map, map:, fallback:, requires:)
+    #
+    # alias: says two of the schema's wire values are one value — both cast,
+    # the target is what goes back on the wire. It is the whole registration
+    # when there is no enum of your own to map onto, which is what a schema
+    # mid-rename needs:
+    #
+    #      GraphWeaver.register_enum("Status", alias: { "legacy_mode" => "LEGACY_MODE" })
+    #
+    # fallback: true is the type-less form of forward-compat: the generated
+    # enum gains an Other member and casts every value the schema doesn't
+    # declare to it, so a server adding one doesn't take the client down.
+    #
+    #      GraphWeaver.register_enum("Species", fallback: true)
+    def register_enum(graphql_name, type = nil, positional_map = nil, map: nil, fallback: nil, requires: nil,
+      alias: nil)
+      # `alias` is a Ruby keyword, so the parameter is only readable through binding
+      Codegen.register_enum(graphql_name, type, positional_map, map:, fallback:, requires:,
+        alias: binding.local_variable_get(:alias))
     end
 
     # Include app-owned helper modules into every struct generated from a

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.5
 platform: ruby
 authors:
 - Daniel Pepper
@@ -281,6 +281,7 @@ files:
 - docs/getting_started.md
 - docs/i18n.md
 - docs/logging.md
+- docs/migrating.md
 - docs/real_world.md
 - docs/scalars.md
 - docs/testing.md
@@ -363,7 +364,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dpep/graph_weaver/issues
-  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.3/CHANGELOG.md
+  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.5/CHANGELOG.md
   documentation_uri: https://github.com/dpep/graph_weaver/tree/main/docs
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/dpep/graph_weaver