fragment-dev 2.0.0 → 2.1.0

data/lib/tapioca/dsl/compilers/fragment_response_types.rb

@@ -0,0 +1,222 @@
+# typed: strict
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compilers)
+
+require 'fragment_client'
+require 'tapioca/dsl/helpers/graphql_sorbet_types'
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Declares the response objects the query methods return, so that
+      # `client.get_ledger(...).data.ledger.name` typechecks.
+      #
+      # graphql-client builds those objects at runtime from anonymous classes whose
+      # fields are served by `method_missing`, so there is nothing to reflect on.
+      # The shape is instead derived statically from each operation's selection set
+      # and the pinned Schema -- the same two inputs graphql-client itself uses,
+      # which is what makes the declared types agree with the runtime.
+      #
+      # In particular graphql-client refuses at runtime to read a field the
+      # operation did not select (`ImplicitlyFetchedFieldError`), so a type derived
+      # from the selection set cannot promise more than the runtime allows.
+      #
+      # Emitted under `FragmentClient::Responses::<Operation>`, one nested class per
+      # selection level.
+      class FragmentResponseTypes < Compiler
+        extend T::Sig
+
+        ConstantType = type_member { { fixed: T.class_of(FragmentClient) } }
+
+        # Scalar names this Schema uses, mapped for `GraphqlSorbetTypes`.
+        SCALARS = T.let(
+          {
+            'String' => '::String', 'ID' => '::String', 'SafeString' => '::String',
+            'ParameterizedString' => '::String', 'Date' => '::String',
+            'DateTime' => '::String', 'FirstMoment' => '::String',
+            'LastMoment' => '::String', 'Period' => '::String',
+            'PeriodFilter' => '::String', 'UTCOffset' => '::String',
+            'Int96' => '::String', 'Int' => '::Integer', 'Float' => '::Float',
+            'Boolean' => 'T::Boolean', 'JSON' => 'T.untyped', 'Parameters' => 'T.untyped'
+          }.freeze,
+          T::Hash[String, String]
+        )
+
+        RESPONSES_NAMESPACE = 'FragmentClient::Responses'
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Enumerable[Module]) }
+          def gather_constants
+            [FragmentClient]
+          end
+        end
+
+        sig { override.void }
+        def decorate
+          operations = FragmentGraphQl.operations
+          return if operations.empty?
+
+          root.create_module(RESPONSES_NAMESPACE) do |namespace|
+            operations.keys.sort.each do |name|
+              declare_operation(namespace, name, T.must(operations[name]))
+            end
+          end
+        end
+
+        private
+
+        sig do
+          params(namespace: RBI::Scope, name: String,
+                 operation: GraphQL::Language::Nodes::OperationDefinition).void
+        end
+        def declare_operation(namespace, name, operation)
+          root_type = operation.operation_type == 'mutation' ? schema.mutation : schema.query
+          return if root_type.nil?
+
+          namespace.create_class(name) do |response|
+            response.create_method('data', return_type: "T.nilable(#{RESPONSES_NAMESPACE}::#{name}::Data)")
+            response.create_method('errors', return_type: 'T.untyped')
+            response.create_method('original_hash', return_type: 'T::Hash[String, T.untyped]')
+            declare_object(response, 'Data', operation.selections, root_type)
+          end
+        end
+
+        # One nested class per selection level. `path` is its fully qualified name,
+        # which children extend so nested references resolve.
+        sig do
+          params(parent: RBI::Scope, class_name: String, selections: T::Array[T.untyped],
+                 graphql_type: T.untyped).void
+        end
+        def declare_object(parent, class_name, selections, graphql_type)
+          fields = collect_fields(selections, graphql_type)
+
+          parent.create_class(class_name) do |scope|
+            fields.each do |field|
+              scope.create_method(field.fetch(:method), return_type: field.fetch(:type),
+                                                        comments: field.fetch(:comments))
+              nested = field[:nested]
+              next unless nested
+
+              declare_object(scope, nested.fetch(:class_name), nested.fetch(:selections),
+                             nested.fetch(:type))
+            end
+          end
+        end
+
+        # Flatten a selection set into field descriptors, following inline fragments.
+        #
+        # A union or interface selection contributes every branch's fields, each
+        # made nilable: graphql-client returns one object whatever the `__typename`,
+        # and only the branch that matched carries values.
+        sig do
+          params(selections: T::Array[T.untyped], graphql_type: T.untyped, force_nilable: T::Boolean,
+                 taken: T::Set[String])
+            .returns(T::Array[T::Hash[Symbol, T.untyped]])
+        end
+        def collect_fields(selections, graphql_type, force_nilable: false, taken: Set.new)
+          selections.flat_map do |selection|
+            case selection
+            when GraphQL::Language::Nodes::Field
+              field = describe_field(selection, graphql_type, force_nilable, taken)
+              field ? [field] : []
+            when GraphQL::Language::Nodes::InlineFragment
+              branch = selection.type ? lookup_type(selection.type.name) : graphql_type
+              next [] if branch.nil?
+
+              collect_fields(selection.selections, branch, force_nilable: true, taken: taken)
+            else
+              []
+            end
+          end
+        end
+
+        sig do
+          params(selection: GraphQL::Language::Nodes::Field, graphql_type: T.untyped,
+                 force_nilable: T::Boolean, taken: T::Set[String])
+            .returns(T.nilable(T::Hash[Symbol, T.untyped]))
+        end
+        def describe_field(selection, graphql_type, force_nilable, taken)
+          name = selection.alias || selection.name
+          method = ActiveSupport::Inflector.underscore(name)
+          return nil if taken.include?(method)
+
+          taken << method
+          return { method: method, type: '::String', comments: [], nested: nil } if name == '__typename'
+
+          field = graphql_type.respond_to?(:fields) ? graphql_type.fields[selection.name] : nil
+          return { method: method, type: 'T.untyped', comments: [], nested: nil } if field.nil?
+
+          build_field(selection, field, method, name, force_nilable, taken)
+        end
+
+        sig do
+          params(selection: GraphQL::Language::Nodes::Field, field: T.untyped, method: String,
+                 name: String, force_nilable: T::Boolean, taken: T::Set[String])
+            .returns(T::Hash[Symbol, T.untyped])
+        end
+        def build_field(selection, field, method, name, force_nilable, taken)
+          unwrapped = field.type.unwrap
+          nilable = force_nilable || !field.type.non_null?
+
+          if selection.selections.empty?
+            return { method: method, type: wrap(scalar_type(unwrapped), field.type, nilable),
+                     comments: [comment("`#{name}`: #{field.type.to_type_signature}")], nested: nil }
+          end
+
+          class_name = ActiveSupport::Inflector.camelize(method)
+          class_name = "#{class_name}Object" if taken.include?("class:#{class_name}")
+          taken << "class:#{class_name}"
+
+          { method: method, type: wrap(class_name, field.type, nilable),
+            comments: [comment("`#{name}`: #{field.type.to_type_signature}")],
+            nested: { class_name: class_name, selections: selection.selections,
+                      type: unwrapped } }
+        end
+
+        # Apply the GraphQL type's list and nullability wrappers to `inner`.
+        #
+        # `[Ledger!]!` becomes `T::Array[X]`, `[Ledger]` becomes
+        # `T::Array[T.nilable(X)]`. `T.untyped` already includes nil, so it is never
+        # wrapped again.
+        sig { params(inner: String, graphql_type: T.untyped, nilable: T::Boolean).returns(String) }
+        def wrap(inner, graphql_type, nilable)
+          bare = graphql_type.non_null? ? graphql_type.of_type : graphql_type
+          type = if bare.list?
+                   "T::Array[#{nilable_unless(inner, bare.of_type.non_null?)}]"
+                 else
+                   inner
+                 end
+          nilable_unless(type, !nilable)
+        end
+
+        sig { params(type: String, non_null: T::Boolean).returns(String) }
+        def nilable_unless(type, non_null)
+          non_null || type == 'T.untyped' ? type : "T.nilable(#{type})"
+        end
+
+        sig { params(unwrapped: T.untyped).returns(String) }
+        def scalar_type(unwrapped)
+          Helpers::GraphqlSorbetTypes.translate(unwrapped.graphql_name, scalars: SCALARS)
+        end
+
+        sig { params(name: String).returns(T.untyped) }
+        def lookup_type(name)
+          schema.types[name]
+        end
+
+        sig { returns(T.untyped) }
+        def schema
+          FragmentGraphQl::FragmentSchema
+        end
+
+        sig { params(text: String).returns(RBI::Comment) }
+        def comment(text)
+          RBI::Comment.new(text)
+        end
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/fragment_typed_entries.rb

@@ -0,0 +1,169 @@
+# typed: strict
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compilers)
+
+require 'fragment_client'
+require 'tapioca/dsl/helpers/graphql_sorbet_types'
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Declares the typed payload classes {FragmentClient::TypedEntries.load}
+      # builds at load time, giving each a real `initialize` signature and typed
+      # readers.
+      #
+      # `bundle exec tapioca dsl` writes them to
+      # `sorbet/rbi/dsl/fragment_client/entries/`. The classes are only visible if
+      # whatever calls `TypedEntries.load` runs when Tapioca loads the application;
+      # it needs no credentials, so an initializer works.
+      class FragmentTypedEntries < Compiler
+        extend T::Sig
+
+        ConstantType = type_member { { fixed: T.class_of(FragmentClient::TypedLedgerEntry) } }
+
+        # Sorbet types for the scalars a Fragment Schema binds parameters to.
+        # Anything absent -- enums, input objects, newer scalars -- falls through to
+        # `T.untyped` rather than a guess that could reject a valid call.
+        GRAPHQL_SCALARS = T.let(
+          {
+            'String' => '::String',
+            'ID' => '::String',
+            'SafeString' => '::String',
+            'ParameterizedString' => '::String',
+            # ISO 8601 strings, not Ruby date objects.
+            'Date' => '::String',
+            'DateTime' => '::String',
+            'FirstMoment' => '::String',
+            'LastMoment' => '::String',
+            'Period' => '::String',
+            'PeriodFilter' => '::String',
+            'UTCOffset' => '::String',
+            # Fragment's big integers are strings on the wire.
+            'Int96' => '::String',
+            'Int' => '::Integer',
+            'Float' => '::Float',
+            'Boolean' => 'T::Boolean',
+            'JSON' => 'T.untyped',
+            'Parameters' => 'T.untyped'
+          }.freeze,
+          T::Hash[String, String]
+        )
+
+        # The optional common fields, in the order the base class declares them.
+        COMMON_OPTIONAL_FIELDS = T.let(
+          {
+            posted: '::String',
+            description: '::String',
+            tags: 'T::Array[T.untyped]',
+            groups: 'T::Array[T.untyped]',
+            conditions: 'T::Array[T.untyped]'
+          }.freeze,
+          T::Hash[Symbol, String]
+        )
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Enumerable[Module]) }
+          def gather_constants
+            # `name_of` is nil for a payload in an anonymous namespace, whose name
+            # (`#<Module:0x...>::AuthCaptureV1`) Sorbet cannot resolve anyway.
+            descendants_of(FragmentClient::TypedLedgerEntry).select { |klass| name_of(klass) }
+          end
+        end
+
+        sig { override.void }
+        def decorate
+          spec = constant.spec
+
+          # `create_path` would omit the superclass, leaving Sorbet unaware that a
+          # payload inherits `to_entry_input`, `set?` and the common-field readers.
+          root.create_class(constant.to_s,
+                            superclass_name: '::FragmentClient::TypedLedgerEntry') do |payload|
+            payload.create_method('initialize', parameters: initialize_parameters(spec),
+                                                return_type: 'void')
+
+            spec.parameters.each do |parameter|
+              payload.create_method(parameter.name.to_s, return_type: reader_type(parameter),
+                                                         comments: parameter_comments(parameter))
+            end
+
+            payload.create_method('entry_type', return_type: '::String', class_method: true,
+                                                comments: [comment(spec.entry_type.inspect)])
+            payload.create_method('type_version', return_type: '::Integer', class_method: true,
+                                                  comments: [comment(spec.type_version.to_s)])
+          end
+        end
+
+        private
+
+        sig do
+          params(spec: FragmentClient::TypedEntries::EntrySpec)
+            .returns(T::Array[RBI::TypedParam])
+        end
+        def initialize_parameters(spec)
+          required, optional = spec.parameters.partition(&:required)
+
+          # Required before optional: Sorbet rejects a `sig` that interleaves them,
+          # though Ruby permits it for keyword arguments. Source order survives
+          # within each group and on the wire, which is where spec 2.4 applies.
+          parameters = [
+            create_kw_param('ik', type: '::String'),
+            create_kw_param('ledger_ik', type: '::String')
+          ]
+          required.each do |parameter|
+            parameters << create_kw_param(parameter.name.to_s, type: sorbet_type(parameter))
+          end
+          optional.each do |parameter|
+            parameters << create_kw_opt_param(parameter.name.to_s, type: optional_type(parameter),
+                                                                   default: 'T.unsafe(nil)')
+          end
+          COMMON_OPTIONAL_FIELDS.each do |name, type|
+            parameters << create_kw_opt_param(name.to_s, type: nilable(type),
+                                                         default: 'T.unsafe(nil)')
+          end
+
+          parameters
+        end
+
+        sig { params(parameter: FragmentClient::TypedEntries::Parameter).returns(String) }
+        def reader_type(parameter)
+          parameter.required ? sorbet_type(parameter) : optional_type(parameter)
+        end
+
+        sig { params(parameter: FragmentClient::TypedEntries::Parameter).returns(String) }
+        def optional_type(parameter)
+          nilable(sorbet_type(parameter))
+        end
+
+        # Optional fields are plainly nilable: the unset sentinel is private to the
+        # constructor and never reaches a caller.
+        sig { params(type: String).returns(String) }
+        def nilable(type)
+          type == 'T.untyped' ? 'T.untyped' : "T.nilable(#{type})"
+        end
+
+        sig { params(parameter: FragmentClient::TypedEntries::Parameter).returns(String) }
+        def sorbet_type(parameter)
+          Helpers::GraphqlSorbetTypes.translate(parameter.graphql_type, scalars: GRAPHQL_SCALARS)
+        end
+
+        sig { params(parameter: FragmentClient::TypedEntries::Parameter).returns(T::Array[RBI::Comment]) }
+        def parameter_comments(parameter)
+          text = "Schema parameter `#{parameter.wire_name}` (`#{parameter.graphql_type}`)."
+          if parameter.escaped?
+            text += " Exposed as `#{parameter.name}` because `#{parameter.wire_name}` is " \
+                    'already taken; the wire name is unchanged.'
+          end
+          [comment(text)]
+        end
+
+        sig { params(text: String).returns(RBI::Comment) }
+        def comment(text)
+          RBI::Comment.new(text)
+        end
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/helpers/graphql_sorbet_types.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Tapioca
+  module Dsl
+    module Helpers
+      # Translates a GraphQL type expression, as written in a document, into a
+      # Sorbet type string.
+      #
+      # Nothing here knows about Fragment: the scalar table is supplied by the
+      # caller, and anything absent from it becomes `T.untyped`. Kept separate so
+      # it can move to a gem of its own if a second consumer appears -- no gem
+      # does this today, and Tapioca ships no GraphQL compiler.
+      #
+      #     translate('[SafeString!]!', scalars: { 'SafeString' => '::String' })
+      #     #=> "T::Array[::String]"
+      #     translate('[String]', scalars: { 'String' => '::String' })
+      #     #=> "T::Array[T.nilable(::String)]"
+      #
+      # Top-level nullability is the caller's to apply, since only the caller knows
+      # whether an optional field is nilable, defaulted, or something else.
+      # Nullability inside a list is applied here, having nowhere else to go.
+      module GraphqlSorbetTypes
+        extend T::Sig
+
+        UNTYPED = 'T.untyped'
+
+        class << self
+          extend T::Sig
+
+          sig { params(graphql_type: String, scalars: T::Hash[String, String]).returns(String) }
+          def translate(graphql_type, scalars:)
+            type = graphql_type.delete_suffix('!')
+            return scalars.fetch(type, UNTYPED) unless type.start_with?('[')
+
+            element = type.delete_prefix('[').delete_suffix(']')
+            "T::Array[#{list_element(element, scalars: scalars)}]"
+          end
+
+          private
+
+          sig { params(element: String, scalars: T::Hash[String, String]).returns(String) }
+          def list_element(element, scalars:)
+            type = translate(element, scalars: scalars)
+            return type if element.end_with?('!') || type == UNTYPED
+
+            "T.nilable(#{type})"
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fragment-dev
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - fragment
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-08 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -67,8 +67,15 @@ files:
 - lib/fragment.schema.json
 - lib/fragment_client.rb
 - lib/fragment_client.rbi
+- lib/fragment_client/graphql_ast.rb
+- lib/fragment_client/typed_entries.rb
+- lib/fragment_client/typed_ledger_entry.rb
 - lib/fragment_client/version.rb
 - lib/queries.graphql
+- lib/tapioca/dsl/compilers/fragment_query_methods.rb
+- lib/tapioca/dsl/compilers/fragment_response_types.rb
+- lib/tapioca/dsl/compilers/fragment_typed_entries.rb
+- lib/tapioca/dsl/helpers/graphql_sorbet_types.rb
 homepage: https://fragment.dev
 licenses:
 - Apache-2.0