graphql_tag_rbs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91736967e60bb08acadda5c3394bcd2f572358030fc1e44a831c0223cd600203
+  data.tar.gz: 854c435820049688a2b720277ffadda627d653d0481b0c52ed563ce189016f57
+SHA512:
+  metadata.gz: 8dc02cfe6152943af815460d4c55e364ef4d22f35fd2c5529cc4935dc29f5d17013359ebe399cd05a1b81377aa490e7cf8db9a172b67d2f609f915eea8c9f59e
+  data.tar.gz: 388c4aff5e4e83ca00a2d21a56c3d9bb98cd0e168ad9e50817cd911110d3f23a85058214650bd4e126b30cf1203a3e1344b0b2abf877b4d925d6e87e5f6afc2e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+4.0.0

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+
+### Added
+
+- Generate RBS `variables`, `data`, and `response` types for each operation, and
+  a `data` type for each fragment, from a graphql_tag_pluck (0.3.0 or later)
+  operation list and a schema in SDL or introspection JSON.
+- One `.rbs` file per source file, plus a shared file with the GraphQL error
+  type and the enums and input objects the operations use.
+- Validation of operations against the schema, with errors naming the
+  operation's location.
+- Options for the namespace, string or symbol keys, and custom scalar types.
+- The `graphql_tag_rbs:generate` rake task, for Rails and other projects.

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in graphql_tag_rbs.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+
+# Used by the specs to check that generated signatures are valid and usable.
+gem "rbs", ">= 3.4"
+gem "steep", ">= 1.9"
+
+# Used by the end-to-end spec that plucks operations from Ruby files.
+gem "graphql_tag_pluck", ">= 0.3.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 indigolain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# GraphqlTagRbs
+
+Generates [RBS](https://github.com/ruby/rbs) types for the GraphQL operations
+in your Ruby code, so [Steep](https://github.com/soutaro/steep) can check how
+you build variables and read responses.
+
+It reads the operation list exported by
+[graphql_tag_pluck](https://github.com/indigolain/graphql_tag_pluck) (0.3.0 or
+later) and your GraphQL schema, and writes one `.rbs` file per Ruby source file.
+
+## Usage
+
+Given a heredoc in `app/clients/user_client.rb`:
+
+```ruby
+module Clients
+  class UserClient
+    USER_QUERY = <<~GRAPHQL
+      query UserQuery($id: ID!) {
+        user(id: $id) {
+          id
+          name
+          role
+        }
+      }
+    GRAPHQL
+  end
+end
+```
+
+run
+
+```sh
+bundle exec rake graphql_tag_pluck:generate_graphql_operation_list graphql_tag_rbs:generate
+```
+
+to get `sig/graphql/app/clients/user_client.rbs`:
+
+```rbs
+# Generated by graphql_tag_rbs from app/clients/user_client.rb. Do not edit.
+
+module GraphQLTypes
+  # query UserQuery at app/clients/user_client.rb:4 (Clients::UserClient::USER_QUERY)
+  module UserQuery
+    type variables = {
+      "id" => ::String | ::Integer
+    }
+
+    type data = {
+      "user" => {
+        "id" => ::String,
+        "name" => ::String?,
+        "role" => ::GraphQLTypes::Enums::role
+      }?
+    }
+
+    type response = {
+      ?"data" => data?,
+      ?"errors" => ::Array[::GraphQLTypes::error],
+      ?"extensions" => ::Hash[::String, untyped]
+    }
+  end
+end
+```
+
+and `sig/graphql/_shared.rbs` with the error type, enums (`type role = "ADMIN" | "MEMBER"`)
+and input objects the operations use.
+
+The types describe the parsed JSON response, so annotate where you parse it:
+
+```ruby
+# @type var response: GraphQLTypes::UserQuery::response
+response = JSON.parse(http_response.body)
+```
+
+or give your client method a signature that takes `GraphQLTypes::UserQuery::variables`
+and returns `GraphQLTypes::UserQuery::response`.
+
+### Loading the rake task
+
+In a Rails app the task is available automatically. In any other project, add this to your `Rakefile`:
+
+```ruby
+require "graphql_tag_rbs/rake_tasks"
+```
+
+## How GraphQL maps to RBS
+
+| GraphQL | RBS |
+|---|---|
+| `String`, `ID` | `::String` |
+| `Int` | `::Integer` |
+| `Float` | `::Float` |
+| `Boolean` | `bool` |
+| custom scalar | `untyped`, unless mapped with the `scalars` option |
+| enum | a literal union in `Enums`, e.g. `"ADMIN" \| "MEMBER"` |
+| nullable field `T` | `T?` |
+| list `[T!]!` | `::Array[T]` |
+| field under `@include` / `@skip` | optional key, `?"field" => T` |
+| union / interface | a record per distinct shape, with `"__typename"` as a literal type |
+| fragment | inlined into each operation, plus a `data` type of its own |
+
+Variables accept what GraphQL input coercion accepts: `ID` also takes `::Integer`,
+`Float` also takes `::Integer`. Nullable variables and variables with a default value
+are optional keys. Input objects become records in `Inputs`; `@oneOf` input objects
+become a union of single-key records.
+
+When a selection on a union or interface picks different fields for different
+possible types, select `__typename` there. Generation fails otherwise, since
+the result could not be told apart.
+
+Each definition gets a module named after it (`query getUser` becomes `GetUser`).
+Unnamed operations are skipped with a warning.
+
+Operations are validated against the schema first, and errors name the operation
+and where it is defined:
+
+```
+GraphQL validation failed:
+  - UserQuery (app/clients/user_client.rb:4): Field 'nmae' doesn't exist on type 'User'
+```
+
+### Steep caveat
+
+Steep reports calling methods on nullable fields and missing or mistyped variables,
+but it does not report reading a key a record does not have: `user["nmae"]` is typed
+as the union of the record's value types instead of an error.
+
+## Configuration
+
+Create `.graphqltagrbsconfig.yaml` to change any of these options:
+
+- schema_path
+  - The GraphQL schema, as SDL (`.graphql`, `.graphqls`) or an introspection result (`.json`)
+  - default: `"schema.graphql"`
+- input_path
+  - The operation list exported by graphql_tag_pluck
+  - default: `"__generated__/graphql_operation_list.json"`
+- output_dir
+  - Where to write the `.rbs` files. Generated files that are no longer produced are removed; files without the generated header are left alone.
+  - default: `"sig/graphql"`
+- namespace
+  - The module the types are defined in. May be nested, e.g. `"MyApp::GraphQL"`.
+  - default: `"GraphQLTypes"`
+- key_style
+  - `"string"` for `JSON.parse(body)`, `"symbol"` for `JSON.parse(body, symbolize_names: true)`
+  - default: `"string"`
+- scalars
+  - RBS types for custom scalars, as they arrive in JSON
+  - default: `{}`, e.g. `{ DateTime: "::String", JSON: "untyped" }`
+
+Add the output directory to your `Steepfile`:
+
+```ruby
+target :app do
+  signature "sig"
+  check "app"
+end
+```
+
+## Installation
+
+```sh
+bundle add graphql_tag_pluck graphql_tag_rbs --group development
+```
+
+## Releasing
+
+Releases are automated by the [Release workflow](.github/workflows/release.yml):
+
+1. Bump the version in the `VERSION` file at the repository root in a pull request.
+2. Merge it into `main`.
+
+The workflow then tags the merge commit as `vX.Y.Z`, runs the specs and publishes the gem to RubyGems.org. If publishing fails, re-run it from **Actions → Release → Run workflow**; the existing tag is reused.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/graphql_tag_rbs/config.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GraphqlTagRbs
+  # Loads options from .graphqltagrbsconfig.yaml in the current directory.
+  class Config
+    CONFIG_FILE = File.expand_path(".graphqltagrbsconfig.yaml", Dir.pwd)
+
+    def self.load(path = CONFIG_FILE)
+      return {} unless File.exist?(path)
+
+      (YAML.load_file(path) || {}).to_h { |key, value| [key.to_sym, value] }
+    end
+  end
+end

data/lib/graphql_tag_rbs/generator.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+module GraphqlTagRbs
+  # Turns a graphql_tag_pluck operation list into RBS files.
+  #
+  #   Generator.new(schema: schema, operations: operations).generate
+  #   # => { "app/clients/user_client.rbs" => "...", "_shared.rbs" => "..." }
+  #
+  # Every operation gets a module with `variables`, `data`, and `response`
+  # type aliases, and every fragment a module with a `data` alias. Enums,
+  # input objects, and the GraphQL error type go into the shared file.
+  class Generator
+    include Types
+
+    HEADER = "# Generated by graphql_tag_rbs"
+    SHARED_FILE = "_shared.rbs"
+    KEY_STYLES = %i[string symbol].freeze
+
+    Nodes = GraphQL::Language::Nodes
+
+    Definition = Struct.new(:name, :module_name, :kind, :node, :file, :line, :constant, keyword_init: true) do
+      def label = "#{name} (#{file}:#{line})"
+    end
+
+    # All occurrences of one response key within a selection set.
+    FieldEntry = Struct.new(:name, :nodes, :conditional)
+
+    def initialize(schema:, operations:, namespace: "GraphQLTypes", key_style: :string, scalars: {})
+      @schema = schema
+      @namespace = namespace.to_s.split("::")
+      @key_style = key_style.to_sym
+      raise Error, "key_style must be one of #{KEY_STYLES.join(", ")}, got #{key_style.inspect}" unless KEY_STYLES.include?(@key_style)
+
+      @scalars = scalars.to_h { |name, type| [name.to_s, type.to_s] }
+      @definitions = build_definitions(operations)
+      @fragments = @definitions.select { |d| d.kind == "fragment" }.to_h { |d| [d.name, d.node] }
+      @enums = Set.new
+      @inputs = Set.new
+    end
+
+    def generate
+      validate!
+
+      files = @definitions.group_by(&:file).sort.to_h do |file, definitions|
+        [output_path(file), render_file(file, definitions.sort_by(&:line))]
+      end
+      raise Error, "#{SHARED_FILE} clashes with a file generated for a source file; rename that file" if files.key?(SHARED_FILE)
+
+      # Rendered last: rendering the operations collects the enums and inputs it needs.
+      files[SHARED_FILE] = render_shared
+      files
+    end
+
+    private
+
+    # --- Input ------------------------------------------------------------
+
+    def build_definitions(operations)
+      definitions = operations.each_value.filter_map do |entry|
+        entry = entry.to_h { |key, value| [key.to_s, value] }
+        unless entry.key?("file") && entry.key?("line")
+          raise Error, "#{entry["name"] || "An operation"} has no file / line. " \
+            "Regenerate the operation list with graphql_tag_pluck 0.3.0 or later."
+        end
+
+        if entry["name"].nil?
+          warn "graphql_tag_rbs: skipping unnamed operation at #{entry["file"]}:#{entry["line"]}; name it to generate types"
+          next
+        end
+
+        Definition.new(
+          name: entry["name"],
+          module_name: module_name(entry["name"]),
+          kind: entry["type"],
+          node: GraphQL.parse(entry["source"]).definitions.first,
+          file: entry["file"],
+          line: entry["line"],
+          constant: entry["constant"]
+        )
+      end
+
+      definitions.group_by(&:module_name).each do |module_name, same|
+        next if same.size == 1
+
+        raise Error, "#{same.map(&:label).join(" and ")} would both generate module #{module_name}"
+      end
+      definitions
+    end
+
+    def validate!
+      document = Nodes::Document.new(definitions: @definitions.map(&:node))
+      errors = @schema.validate(document).reject do |error|
+        # Fragments get their own types, so a fragment no operation spreads is fine.
+        error.is_a?(GraphQL::StaticValidation::FragmentsAreUsedError) && error.message.end_with?("was defined, but not used")
+      end
+      return if errors.empty?
+
+      by_name = @definitions.to_h { |d| [d.name, d] }
+      messages = errors.map do |error|
+        definition = by_name[error.path&.first.to_s.split(" ").last]
+        definition ? "#{definition.label}: #{error.message}" : error.message
+      end
+      raise Error, "GraphQL validation failed:\n#{messages.map { |m| "  - #{m}" }.join("\n")}"
+    end
+
+    # --- Files ------------------------------------------------------------
+
+    def output_path(file)
+      "#{file.delete_prefix("/").delete_suffix(".rb")}.rbs"
+    end
+
+    def render_file(file, definitions)
+      body = definitions.flat_map.with_index do |definition, index|
+        (index.zero? ? [] : [""]) + render_definition(definition)
+      end
+      "#{HEADER} from #{file}. Do not edit.\n\n#{wrap_in_namespace(body)}"
+    end
+
+    def render_definition(definition)
+      @current = definition
+      comment = "# #{definition.kind} #{definition.name} at #{definition.file}:#{definition.line}"
+      comment += " (#{definition.constant})" if definition.constant
+
+      aliases =
+        if definition.kind == "fragment"
+          { "data" => fragment_type(definition.node) }
+        else
+          { "variables" => variables_type(definition.node), "data" => data_type(definition.node), "response" => response_type }
+        end
+
+      lines = [comment, "module #{definition.module_name}"]
+      aliases.each_with_index do |(name, type), index|
+        lines << "" unless index.zero?
+        lines.concat(indent_lines("type #{name} = #{type.render("")}"))
+      end
+      lines << "end"
+    end
+
+    def render_shared
+      inputs = {}
+      # Input objects can reference further input objects and enums.
+      until (pending = @inputs.to_a.sort - inputs.keys).empty?
+        pending.each { |name| inputs[name] = input_object_type(@schema.get_type(name)) }
+      end
+
+      body = ["type error = #{error_type.render("")}"].flat_map { |line| line.lines(chomp: true) }
+      body += shared_module("Enums", @enums.to_a.sort.to_h { |name| [name, enum_type(@schema.get_type(name))] })
+      body += shared_module("Inputs", inputs.sort.to_h)
+
+      "#{HEADER}. Do not edit.\n\n#{wrap_in_namespace(body)}"
+    end
+
+    def shared_module(module_name, types)
+      return [] if types.empty?
+
+      lines = ["", "module #{module_name}"]
+      types.each_with_index do |(name, type), index|
+        lines << "" unless index.zero?
+        lines.concat(indent_lines("type #{alias_name(name)} = #{type.render("")}"))
+      end
+      lines << "end"
+    end
+
+    def wrap_in_namespace(lines)
+      @namespace.reverse_each do |name|
+        lines = ["module #{name}", *indent_lines(lines), "end"]
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    def indent_lines(text)
+      Array(text)
+        .flat_map { |chunk| chunk.empty? ? [""] : chunk.lines(chomp: true) }
+        .map { |line| line.empty? ? line : INDENT + line }
+    end
+
+    # --- Operation types ----------------------------------------------------
+
+    def data_type(operation)
+      root = @schema.root_type_for_operation(operation.operation_type)
+      raise Error, "#{@current.label}: the schema has no #{operation.operation_type} type" if root.nil?
+
+      selection_set_type(root, operation.selections, [])
+    end
+
+    def fragment_type(fragment)
+      selection_set_type(@schema.get_type(fragment.type.name), fragment.selections, [])
+    end
+
+    def variables_type(operation)
+      fields = operation.variables.map do |variable|
+        required = variable.type.is_a?(Nodes::NonNullType) && variable.default_value.nil?
+        Field.new(variable.name, input_ast_type(variable.type), !required)
+      end
+      Record.new(fields, @key_style)
+    end
+
+    def response_type
+      Record.new([
+        Field.new("data", Optional.new(Named.new("data")), true),
+        Field.new("errors", ArrayOf.new(Named.new("#{namespace_ref}::error")), true),
+        Field.new("extensions", hash_type, true)
+      ], @key_style)
+    end
+
+    def error_type
+      location = Record.new([Field.new("line", Named.new("::Integer"), false), Field.new("column", Named.new("::Integer"), false)], @key_style)
+      Record.new([
+        Field.new("message", Named.new("::String"), false),
+        Field.new("locations", ArrayOf.new(location), true),
+        Field.new("path", ArrayOf.new(Union.of([Named.new("::String"), Named.new("::Integer")])), true),
+        Field.new("extensions", hash_type, true)
+      ], @key_style)
+    end
+
+    def hash_type
+      Named.new(@key_style == :symbol ? "::Hash[::Symbol, untyped]" : "::Hash[::String, untyped]")
+    end
+
+    # --- Selections ---------------------------------------------------------
+
+    # The type of a selection set on `parent_type`. For abstract types, possible
+    # types that select the same fields share one record, distinguished by a
+    # `__typename` literal union; differing shapes become a union of records.
+    def selection_set_type(parent_type, selections, path)
+      possible = @schema.possible_types(parent_type).sort_by(&:graphql_name)
+      return UNTYPED if possible.empty?
+
+      shapes = possible.map do |type|
+        entries = {}
+        collect_fields(type, selections, false, entries)
+        [type, entries.map { |key, entry| field_for(type, key, entry, path) }]
+      end
+
+      groups = shapes.group_by { |_type, fields| fields }.transform_values { |members| members.map(&:first) }
+      if groups.size > 1 && !groups.keys.all? { |fields| fields.any? { |field| field.type == :typename } }
+        location = path.empty? ? "the root selection" : "`#{path.join(".")}`"
+        raise Error, "#{@current.label}: #{location} selects different fields depending on whether the " \
+          "#{parent_type.graphql_name} is a #{possible.map(&:graphql_name).join(", ")}; " \
+          "select `__typename` there so the result can be told apart"
+      end
+
+      Union.of(groups.map do |fields, types|
+        typename = Union.of(types.map { |type| Literal.new(type.graphql_name) })
+        Record.new(fields.map { |field| field.type == :typename ? Field.new(field.key, typename, field.optional) : field }, @key_style)
+      end)
+    end
+
+    # Collects the fields `type` gets from `selections`, following inline
+    # fragments and fragment spreads that apply to it. Fields under
+    # @include / @skip may be missing from the response, so they are marked
+    # conditional unless the same key is also selected unconditionally.
+    def collect_fields(type, selections, conditional, entries)
+      selections.each do |selection|
+        selection_conditional = conditional || selection.directives.any? { |d| %w[include skip].include?(d.name) }
+
+        case selection
+        when Nodes::Field
+          key = selection.alias || selection.name
+          if (entry = entries[key])
+            entry.nodes << selection
+            entry.conditional &&= selection_conditional
+          else
+            entries[key] = FieldEntry.new(selection.name, [selection], selection_conditional)
+          end
+        when Nodes::InlineFragment
+          next if selection.type && !applies_to?(type, selection.type.name)
+
+          collect_fields(type, selection.selections, selection_conditional, entries)
+        when Nodes::FragmentSpread
+          fragment = @fragments.fetch(selection.name)
+          next unless applies_to?(type, fragment.type.name)
+
+          collect_fields(type, fragment.selections, selection_conditional, entries)
+        end
+      end
+    end
+
+    def applies_to?(type, type_condition)
+      condition = @schema.get_type(type_condition)
+      condition == type || (condition.kind.abstract? && @schema.possible_types(condition).include?(type))
+    end
+
+    def field_for(type, key, entry, path)
+      # A placeholder, replaced with the possible type names once types are grouped.
+      return Field.new(key, :typename, entry.conditional) if entry.name == "__typename"
+
+      definition = @schema.get_field(type, entry.name)
+      field_type = output_type(definition.type, entry.nodes.flat_map(&:selections), path + [key])
+      Field.new(key, field_type, entry.conditional)
+    end
+
+    def output_type(type, selections, path)
+      return bare_output_type(type.of_type, selections, path) if type.non_null?
+
+      Optional.new(bare_output_type(type, selections, path))
+    end
+
+    def bare_output_type(type, selections, path)
+      return ArrayOf.new(output_type(type.of_type, selections, path)) if type.list?
+
+      case type.kind.name
+      when "SCALAR" then scalar_type(type.graphql_name, :output)
+      when "ENUM" then enum_ref(type)
+      else selection_set_type(type, selections, path)
+      end
+    end
+
+    # --- Inputs ---------------------------------------------------------------
+
+    def input_ast_type(ast_type)
+      return bare_input_ast_type(ast_type.of_type) if ast_type.is_a?(Nodes::NonNullType)
+
+      Optional.new(bare_input_ast_type(ast_type))
+    end
+
+    def bare_input_ast_type(ast_type)
+      return ArrayOf.new(input_ast_type(ast_type.of_type)) if ast_type.is_a?(Nodes::ListType)
+
+      named_input_type(@schema.get_type(ast_type.name))
+    end
+
+    def input_type(type)
+      return bare_input_type(type.of_type) if type.non_null?
+
+      Optional.new(bare_input_type(type))
+    end
+
+    def bare_input_type(type)
+      return ArrayOf.new(input_type(type.of_type)) if type.list?
+
+      named_input_type(type)
+    end
+
+    def named_input_type(type)
+      case type.kind.name
+      when "SCALAR" then scalar_type(type.graphql_name, :input)
+      when "ENUM" then enum_ref(type)
+      else
+        @inputs << type.graphql_name
+        Named.new("#{namespace_ref}::Inputs::#{alias_name(type.graphql_name)}")
+      end
+    end
+
+    def input_object_type(type)
+      arguments = type.arguments.values
+
+      # @oneOf input objects take exactly one of their fields, and it must not be null.
+      if type.respond_to?(:one_of?) && type.one_of?
+        return Union.of(arguments.map do |argument|
+          value_type = argument.type.non_null? ? argument.type.of_type : argument.type
+          Record.new([Field.new(argument.graphql_name, bare_input_type(value_type), false)], @key_style)
+        end)
+      end
+
+      Record.new(arguments.map do |argument|
+        required = argument.type.non_null? && !argument.default_value?
+        Field.new(argument.graphql_name, input_type(argument.type), !required)
+      end, @key_style)
+    end
+
+    # --- Leaves ---------------------------------------------------------------
+
+    BUILT_IN_SCALARS = {
+      output: { "ID" => "::String", "String" => "::String", "Int" => "::Integer", "Float" => "::Float", "Boolean" => "bool" },
+      # Input coercion also accepts integers for ID and Float.
+      input: { "ID" => "::String | ::Integer", "String" => "::String", "Int" => "::Integer", "Float" => "::Float | ::Integer", "Boolean" => "bool" }
+    }.freeze
+
+    def scalar_type(name, direction)
+      Named.new(@scalars.fetch(name) { BUILT_IN_SCALARS[direction].fetch(name, "untyped") })
+    end
+
+    def enum_ref(type)
+      @enums << type.graphql_name
+      Named.new("#{namespace_ref}::Enums::#{alias_name(type.graphql_name)}")
+    end
+
+    def enum_type(type)
+      Union.of(type.values.keys.map { |value| Literal.new(value) })
+    end
+
+    # --- Naming ---------------------------------------------------------------
+
+    def namespace_ref = "::#{@namespace.join("::")}"
+
+    # GraphQL names may start with a lowercase letter or underscores; RBS module names may not.
+    def module_name(name)
+      stripped = name.sub(/\A_+/, "")
+      module_name = stripped[0].to_s.upcase + stripped[1..].to_s
+      raise Error, "Cannot turn GraphQL name #{name.inspect} into an RBS module name" unless module_name.match?(/\A[A-Z]\w*\z/)
+      raise Error, "#{name} clashes with the generated #{module_name} module; rename it" if %w[Enums Inputs].include?(module_name)
+
+      module_name
+    end
+
+    # RBS type alias names start with a lowercase letter: UserRole => user_role.
+    def alias_name(name)
+      name.sub(/\A_+/, "").gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+  end
+end

data/lib/graphql_tag_rbs/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module GraphqlTagRbs
+  class Railtie < Rails::Railtie
+    railtie_name :graphql_tag_rbs
+
+    rake_tasks do
+      Dir.glob(File.expand_path("tasks/**/*.rake", __dir__)).each { |f| load f }
+    end
+  end
+end

data/lib/graphql_tag_rbs/rake_tasks.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Defines the graphql_tag_rbs rake tasks outside Rails. Add this to your
+# Rakefile:
+#
+#   require "graphql_tag_rbs/rake_tasks"
+#
+# Rails apps get the tasks through GraphqlTagRbs::Railtie and should not
+# require this file, or the tasks will run twice.
+require "graphql_tag_rbs"
+
+Dir.glob(File.expand_path("tasks/**/*.rake", __dir__)).each { |f| load f }

data/lib/graphql_tag_rbs/schema_loader.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GraphqlTagRbs
+  # Loads a schema from SDL (.graphql / .graphqls) or an introspection result (.json).
+  module SchemaLoader
+    def self.load(path)
+      raise Error, "GraphQL schema not found at #{path}" unless File.exist?(path)
+
+      if File.extname(path) == ".json"
+        introspection = JSON.parse(File.read(path))
+        # Accept both a raw `{ "__schema": ... }` and a full `{ "data": { "__schema": ... } }` response.
+        introspection = { "data" => introspection } if introspection.key?("__schema")
+        GraphQL::Schema.from_introspection(introspection)
+      else
+        GraphQL::Schema.from_definition(File.read(path))
+      end
+    end
+  end
+end

data/lib/graphql_tag_rbs/tasks/generate.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :graphql_tag_rbs do
+  desc "Generate RBS types for the GraphQL operations plucked by graphql_tag_pluck"
+  task :generate do
+    result = GraphqlTagRbs.generate
+    puts "graphql_tag_rbs: wrote #{result.written.size} file(s) to #{GraphqlTagRbs.options[:output_dir]}"
+    result.deleted.each { |path| puts "graphql_tag_rbs: removed #{path}" }
+  end
+end

data/lib/graphql_tag_rbs/types.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module GraphqlTagRbs
+  # A small RBS type AST. Every node renders itself given the indentation of
+  # the line it starts on; records span several lines.
+  module Types
+    INDENT = "  "
+
+    # A type written as-is, e.g. `::String`, `bool`, `untyped`, or a type alias reference.
+    Named = Struct.new(:name) do
+      def render(_indent) = name
+
+      def compound? = name.match?(/[|&]/)
+    end
+
+    # A string literal type, e.g. `"User"`.
+    Literal = Struct.new(:value) do
+      def render(_indent) = value.dump
+    end
+
+    Optional = Struct.new(:type) do
+      def render(indent)
+        return type.render(indent) if type == UNTYPED
+
+        inner = type.render(indent)
+        needs_parens = type.is_a?(Union) || (type.is_a?(Named) && type.compound?)
+        needs_parens ? "(#{inner})?" : "#{inner}?"
+      end
+    end
+
+    ArrayOf = Struct.new(:type) do
+      def render(indent) = "::Array[#{type.render(indent)}]"
+    end
+
+    Union = Struct.new(:types) do
+      def self.of(types)
+        unique = types.uniq
+        unique.size == 1 ? unique.first : new(unique)
+      end
+
+      def render(indent) = types.map { |type| type.render(indent) }.join(" | ")
+    end
+
+    Field = Struct.new(:key, :type, :optional)
+
+    Record = Struct.new(:fields, :key_style) do
+      def render(indent)
+        return "{}" if fields.empty?
+
+        inner = indent + INDENT
+        lines = fields.map { |field| "#{inner}#{key(field)}#{field.type.render(inner)}" }
+        "{\n#{lines.join(",\n")}\n#{indent}}"
+      end
+
+      private
+
+      def key(field)
+        prefix = field.optional ? "?" : ""
+        key_style == :symbol ? "#{prefix}#{field.key}: " : "#{prefix}#{field.key.dump} => "
+      end
+    end
+
+    UNTYPED = Named.new("untyped")
+  end
+end

data/lib/graphql_tag_rbs/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GraphqlTagRbs
+  # The version lives in the plain-text VERSION file at the gem root.
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip.freeze
+end

data/lib/graphql_tag_rbs/writer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module GraphqlTagRbs
+  # Writes generated files into the output directory and removes generated
+  # files that are no longer produced, such as those of a deleted source file.
+  # Files without the generated header are never touched.
+  class Writer
+    Result = Struct.new(:written, :deleted, keyword_init: true)
+
+    def initialize(output_dir)
+      @output_dir = output_dir
+    end
+
+    def write(files)
+      written = files.map do |relative_path, content|
+        path = File.join(@output_dir, relative_path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content) unless File.exist?(path) && File.read(path) == content
+        path
+      end
+
+      deleted = (Dir.glob(File.join(@output_dir, "**/*.rbs")) - written).select do |path|
+        next false unless File.foreach(path).first.to_s.start_with?(Generator::HEADER)
+
+        File.delete(path)
+        true
+      end
+
+      Result.new(written: written, deleted: deleted)
+    end
+  end
+end

data/lib/graphql_tag_rbs.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "graphql"
+require "json"
+require "set"
+require "yaml"
+
+require_relative "graphql_tag_rbs/version"
+
+module GraphqlTagRbs
+  class Error < StandardError; end
+end
+
+require_relative "graphql_tag_rbs/config"
+require_relative "graphql_tag_rbs/types"
+require_relative "graphql_tag_rbs/schema_loader"
+require_relative "graphql_tag_rbs/generator"
+require_relative "graphql_tag_rbs/writer"
+require_relative "graphql_tag_rbs/railtie" if defined?(Rails::Railtie)
+
+module GraphqlTagRbs
+  class << self
+    attr_accessor :options
+
+    def default_options
+      {
+        schema_path: "schema.graphql",
+        input_path: "__generated__/graphql_operation_list.json",
+        output_dir: "sig/graphql",
+        namespace: "GraphQLTypes",
+        key_style: "string",
+        scalars: {}
+      }
+    end
+
+    # Reads the schema and the graphql_tag_pluck operation list, and writes
+    # RBS files into output_dir. Returns the Writer::Result.
+    def generate(options = self.options)
+      input_path = options[:input_path]
+      unless File.exist?(input_path)
+        raise Error, "Operation list not found at #{input_path}. " \
+          "Run `rake graphql_tag_pluck:generate_graphql_operation_list` first."
+      end
+
+      files = Generator.new(
+        schema: SchemaLoader.load(options[:schema_path]),
+        operations: JSON.parse(File.read(input_path)),
+        namespace: options[:namespace],
+        key_style: options[:key_style],
+        scalars: options[:scalars] || {}
+      ).generate
+
+      Writer.new(options[:output_dir]).write(files)
+    end
+  end
+
+  self.options = default_options.merge(Config.load)
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: graphql_tag_rbs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- indigolain
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Reads the operation list exported by graphql_tag_pluck and a GraphQL
+  schema, and writes RBS type aliases for each operation's variables, data, and response.
+email:
+- indigo.lain@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/graphql_tag_rbs.rb
+- lib/graphql_tag_rbs/config.rb
+- lib/graphql_tag_rbs/generator.rb
+- lib/graphql_tag_rbs/railtie.rb
+- lib/graphql_tag_rbs/rake_tasks.rb
+- lib/graphql_tag_rbs/schema_loader.rb
+- lib/graphql_tag_rbs/tasks/generate.rake
+- lib/graphql_tag_rbs/types.rb
+- lib/graphql_tag_rbs/version.rb
+- lib/graphql_tag_rbs/writer.rb
+homepage: https://github.com/indigolain/graphql_tag_rbs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/indigolain/graphql_tag_rbs
+  source_code_uri: https://github.com/indigolain/graphql_tag_rbs
+  changelog_uri: https://github.com/indigolain/graphql_tag_rbs/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Generates RBS types for GraphQL operations plucked by graphql_tag_pluck
+test_files: []