quail-graphql 0.1.0

data/lib/quail/resource/mutation_builder/resolvers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    module MutationBuilder
+      # Runtime resolve logic for auto-generated mutations.
+      module Resolvers
+        def self.create(model, name, subs, gql_context, attrs)
+          record = model.new(attrs)
+          return { name.to_sym => nil, errors: record.errors.full_messages } unless record.save
+
+          MutationBuilder.trigger_subscription(gql_context, subs, :create, name, record)
+          { name.to_sym => record, errors: [] }
+        end
+
+        def self.update(model, name, subs, gql_context, params)
+          record = model.find_by(id: params[:id])
+          return { name.to_sym => nil, errors: ["#{model.name} not found"] } unless record
+
+          unless record.update(params[:attrs].compact)
+            return { name.to_sym => nil,
+                     errors: record.errors.full_messages }
+          end
+
+          MutationBuilder.trigger_subscription(gql_context, subs, :update, name, record)
+          { name.to_sym => record, errors: [] }
+        end
+
+        def self.delete(model, name, subs, gql_context, id)
+          record = model.find_by(id: id)
+          return { success: false, errors: ["#{model.name} not found"] } unless record
+
+          snapshot = MutationBuilder.capture_delete_snapshot(subs, record)
+          return { success: false, errors: record.errors.full_messages } unless record.destroy
+
+          MutationBuilder.trigger_delete_event(gql_context, name, snapshot)
+          { success: true, errors: [] }
+        end
+      end
+    end
+  end
+end

data/lib/quail/resource/mutation_builder.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "mutation_builder/context"
+require_relative "mutation_builder/resolvers"
+
+module Quail
+  module Resource
+    # Builds create, update, and delete GraphQL mutations for a resource.
+    module MutationBuilder # rubocop:disable Metrics/ModuleLength
+      def self.call(resource_class)
+        skipped = resource_class.skipped_mutations
+        overrides = resource_class.resolved_mutation_overrides
+        ctx = MutationContext.new(resource_class)
+        mutations = {}
+
+        %i[create update delete].each do |action|
+          next if skipped.include?(action)
+
+          mutations[action] = overrides[action] || build_mutation(action, ctx)
+        end
+        mutations
+      end
+
+      def self.build_mutation(action, ctx)
+        case action
+        when :create then build_create(ctx)
+        when :update then build_update(ctx)
+        when :delete then build_delete(ctx)
+        end
+      end
+
+      def self.default_writable(model, resource_class = nil)
+        excluded = %i[id created_at updated_at]
+        excluded += polymorphic_columns(resource_class) if resource_class
+        model.column_names.map(&:to_sym).reject { |c| excluded.include?(c) }
+      end
+
+      def self.polymorphic_columns(resource_class)
+        return [] unless resource_class
+
+        resource_class.association_definitions
+                      .select { |_, config| config[:polymorphic] }
+                      .flat_map do |name, _|
+          [
+            :"#{name}_type", :"#{name}_id"
+          ]
+        end
+      end
+
+      def self.resolve_scope(scope_config, record)
+        return {} unless scope_config
+
+        case scope_config
+        when Symbol then { scope_config => record.public_send(scope_config) }
+        when Hash
+          key, value_proc = scope_config.first
+          { key.to_sym => value_proc.call(record) }
+        else {}
+        end
+      end
+
+      def self.add_writable_arguments(klass, model, writable, required:)
+        writable.each do |attr|
+          col = model.columns_hash[attr.to_s]
+          next unless col
+
+          klass.argument attr, TypeMap.graphql_types(col), required: required ? !TypeMap.nullable?(col) : false
+        end
+      end
+
+      def self.add_result_fields(klass, underscore_name, type_class)
+        klass.field underscore_name.to_sym, type_class, null: true
+        klass.field :errors, [GraphQL::Types::String], null: false
+      end
+
+      def self.trigger_subscription(gql_context, subs, event, underscore_name, record)
+        sub_config = subs[event]
+        return unless sub_config
+
+        scope_args = resolve_scope(sub_config[:scope], record)
+        gql_context.schema.subscriptions&.trigger(:"#{underscore_name}_#{event}d", scope_args, record)
+      end
+
+      def self.capture_delete_snapshot(subs, record)
+        return nil unless subs[:delete]
+
+        { attributes: record.attributes, scope_args: resolve_scope(subs[:delete][:scope], record) }
+      end
+
+      def self.trigger_delete_event(gql_context, name, snapshot)
+        return unless snapshot
+
+        gql_context.schema.subscriptions&.trigger(:"#{name}_deleted", snapshot[:scope_args], snapshot[:attributes])
+      end
+
+      def self.build_create(ctx)
+        model = ctx.model
+        name = ctx.underscore_name
+        subs = ctx.subscriptions
+        klass = new_mutation_class(ctx, "Create", model)
+        add_writable_arguments(klass, model, ctx.writable, required: true)
+        add_result_fields(klass, name, ctx.type_class)
+        klass.define_method(:resolve) { |**attrs| Resolvers.create(model, name, subs, context, attrs) }
+        klass
+      end
+
+      def self.build_update(ctx)
+        model, name, subs = ctx.model, ctx.underscore_name, ctx.subscriptions
+        klass = new_mutation_class(ctx, "Update", model)
+        klass.argument :id, GraphQL::Types::ID, required: true
+        add_writable_arguments(klass, model, ctx.writable, required: false)
+        add_result_fields(klass, name, ctx.type_class)
+        klass.define_method(:resolve) do |id:, **attrs|
+          Resolvers.update(model, name, subs, context, { id: id, attrs: attrs })
+        end
+        klass
+      end
+
+      def self.build_delete(ctx)
+        model = ctx.model
+        name = ctx.underscore_name
+        subs = ctx.subscriptions
+        klass = new_mutation_class(ctx, "Delete", model)
+        klass.argument :id, GraphQL::Types::ID, required: true
+        klass.field :success, GraphQL::Types::Boolean, null: false
+        klass.field :errors, [GraphQL::Types::String], null: false
+        klass.define_method(:resolve) { |id:| Resolvers.delete(model, name, subs, context, id) }
+        klass
+      end
+
+      def self.new_mutation_class(ctx, prefix, model)
+        Class.new(ctx.base) do
+          graphql_name "#{prefix}#{model.name}"
+          description "#{prefix}s a #{model.name}"
+        end
+      end
+    end
+  end
+end

data/lib/quail/resource/query_builder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    # Builds find and list GraphQL query fields for a resource.
+    module QueryBuilder
+      def self.call(resource_class)
+        return {} if resource_class.skipped_queries.include?(:all)
+
+        model = resource_class.model_class
+        type_class = resource_class.graphql_type
+        skipped = resource_class.skipped_queries
+        fields = {}
+
+        fields.merge!(build_find_field(model, type_class)) unless skipped.include?(:find)
+        fields.merge!(build_list_field(model, type_class)) unless skipped.include?(:list)
+        fields
+      end
+
+      def self.build_find_field(model, type_class)
+        {
+          model.name.underscore.to_sym => {
+            type: type_class,
+            null: true,
+            arguments: { id: { type: GraphQL::Types::ID, required: true } },
+            resolve: ->(_obj, args, _ctx) { model.find_by(id: args[:id]) }
+          }
+        }
+      end
+
+      def self.build_list_field(model, type_class)
+        {
+          model.name.underscore.pluralize.to_sym => {
+            type: type_class.connection_type,
+            null: false,
+            resolve: ->(_obj, _args, _ctx) { model.all }
+          }
+        }
+      end
+    end
+  end
+end

data/lib/quail/resource/subscription_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    # Builds GraphQL subscription fields for a resource based on its subscription definitions.
+    module SubscriptionBuilder
+      def self.call(resource_class)
+        subs = resource_class.subscription_definitions
+        return {} if subs.empty?
+
+        model_name = resource_class.model_class.name
+        type_class = resource_class.graphql_type
+        fields = {}
+
+        subs.each do |event, config|
+          field_name = :"#{model_name.underscore}_#{event}d"
+          fields[field_name] = build_subscription_class(type_class, model_name, event, config)
+        end
+
+        fields
+      end
+
+      def self.build_subscription_class(type_class, model_name, event, config)
+        sub_class = Class.new(GraphQL::Schema::Subscription) do
+          graphql_name "#{model_name}#{event.to_s.capitalize}d"
+          description "Triggered when a #{model_name} is #{event}d"
+          payload_type type_class
+        end
+
+        define_hash_rehydration(sub_class, model_name.constantize)
+        apply_scope(sub_class, config[:scope])
+        sub_class
+      end
+
+      # Rehydrate Hash payloads (e.g. from delete snapshots) into model
+      # instances so computed attributes that call associations still work.
+      def self.define_hash_rehydration(sub_class, model_class)
+        sub_class.define_method(:update) do |**_args|
+          return object unless object.is_a?(Hash)
+
+          model_class.new(object).tap(&:readonly!)
+        end
+      end
+
+      def self.apply_scope(sub_class, scope)
+        return unless scope
+
+        scope_key = scope.is_a?(Hash) ? scope.keys.first.to_sym : scope.to_sym
+        sub_class.argument scope_key, GraphQL::Types::ID, required: true
+      end
+    end
+  end
+end

data/lib/quail/resource/type_builder/association_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    module TypeBuilder
+      # Wires up association fields (belongs_to, has_one, has_many, polymorphic)
+      # on a GraphQL type.
+      module AssociationBuilder
+        def self.add_fields(resource_class)
+          model = resource_class.model_class
+          type_class = resource_class.graphql_type
+
+          resource_class.association_definitions.each do |name, config|
+            next if type_class.own_fields.key?(name.to_s)
+
+            add_single(type_class, model, name, config)
+          end
+        end
+
+        def self.add_single(type_class, model, name, config)
+          if config[:polymorphic]
+            add_polymorphic_field(type_class, name, config)
+          elsif config[:resource]
+            add_explicit_resource_field(type_class, model, name, config)
+          else
+            add_reflected_field(type_class, model, name, config)
+          end
+        end
+
+        def self.add_polymorphic_field(type_class, name, config)
+          union_type = build_union_type(name, config)
+          type_class.field name, union_type, null: true
+        end
+
+        def self.add_explicit_resource_field(type_class, model, name, config)
+          resource_class = TypeBuilder.resolve_resource_ref(config[:resource])
+          assoc_type = resource_class&.graphql_type
+          return unless assoc_type
+
+          ar_assoc = model.reflect_on_association(name)
+          add_association_field(type_class, name, config[:kind], assoc_type, ar_assoc)
+        end
+
+        def self.add_reflected_field(type_class, model, name, config)
+          ar_assoc = model.reflect_on_association(name)
+          return unless ar_assoc
+
+          assoc_type = Quail.resource_for(ar_assoc.klass)&.graphql_type
+          return unless assoc_type
+
+          add_association_field(type_class, name, config[:kind], assoc_type, ar_assoc)
+        end
+
+        def self.build_union_type(name, config)
+          gql_name = config[:union_name] || "#{name.to_s.camelize}Union"
+          resolved_types = resolve_polymorphic_types(config[:polymorphic_types])
+          assoc_name = name
+
+          Class.new(GraphQL::Schema::Union) do
+            graphql_name gql_name
+            description "Union type for polymorphic association #{assoc_name}"
+            possible_types(*resolved_types)
+            define_method(:resolve_type) { |obj, _ctx| TypeBuilder.resolve_polymorphic_type(obj, assoc_name) }
+          end
+        end
+
+        def self.resolve_polymorphic_types(types)
+          types.map do |t|
+            resource = TypeBuilder.resolve_resource_ref(t)
+            gql_type = resource.graphql_type
+            unless gql_type
+              raise ArgumentError,
+                    "Polymorphic type #{t.inspect} resolved to #{resource.name} but its graphql_type is nil. " \
+                    "Ensure the resource is registered before building associations."
+            end
+            gql_type
+          end
+        end
+
+        def self.add_association_field(type_class, name, kind, assoc_type, ar_assoc)
+          case kind
+          when :has_many
+            type_class.field name, [assoc_type], null: false
+          when :has_one, :belongs_to
+            nullable = kind != :belongs_to || !ar_assoc || ar_assoc.options[:optional] != false
+            type_class.field name, assoc_type, null: nullable
+          end
+        end
+      end
+    end
+  end
+end

data/lib/quail/resource/type_builder/field_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    module TypeBuilder
+      # Defines scalar (column-backed) and computed fields on a GraphQL type.
+      module FieldBuilder
+        # Full block signature: |object, args, context|
+        CONTEXT_AWARE_ARITY = 3
+
+        def self.define_column_fields(type_class, model, attrs)
+          attrs.each do |name, config|
+            next unless config[:type] == :column
+
+            col = model.columns_hash[name.to_s]
+            if col
+              type_class.field name, TypeMap.graphql_types(col), null: TypeMap.nullable?(col)
+            else
+              type_class.field name, GraphQL::Types::String, null: true
+            end
+          end
+        end
+
+        def self.define_computed_fields(type_class, attrs)
+          attrs.each do |name, config|
+            next unless config[:type] == :computed
+
+            define_single_computed_field(type_class, name, config)
+          end
+        end
+
+        def self.define_single_computed_field(type_class, name, config)
+          gql_type = config[:graphql_type] || GraphQL::Types::String
+          nullable = config[:null].nil? || config[:null]
+          type_class.field name, gql_type, null: nullable
+          define_computed_resolver(type_class, name, config[:block])
+        end
+
+        def self.define_computed_resolver(type_class, name, blk)
+          type_class.define_method(name) do
+            if blk.arity.abs >= CONTEXT_AWARE_ARITY
+              FieldBuilder.safe_call(blk, object, nil, context)
+            else
+              FieldBuilder.safe_call(blk, object)
+            end
+          end
+        end
+
+        def self.safe_call(blk, *)
+          blk.call(*)
+        rescue LocalJumpError => e
+          e.exit_value
+        end
+      end
+    end
+  end
+end

data/lib/quail/resource/type_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "type_builder/field_builder"
+require_relative "type_builder/association_builder"
+
+module Quail
+  module Resource
+    # Generates GraphQL object types from resource attribute and association definitions.
+    module TypeBuilder
+      def self.build_all
+        # Two-pass build: first create all GraphQL types so that @graphql_type
+        # is available on every resource, then wire up associations (which may
+        # reference other resources' types, e.g. polymorphic unions).
+        Quail.registry.each_value { |rc| build_scalar_fields(rc) unless rc.graphql_type }
+        Quail.registry.each_value { |rc| AssociationBuilder.add_fields(rc) } # rubocop:disable Style/CombinableLoops
+      end
+
+      def self.build_scalar_fields(resource_class)
+        model = resource_class.model_class
+        attrs = resource_class.attribute_definitions
+        type_class = create_type_class(model)
+
+        FieldBuilder.define_column_fields(type_class, model, attrs)
+        FieldBuilder.define_computed_fields(type_class, attrs)
+        resource_class.instance_variable_set(:@graphql_type, type_class)
+        register_type_constant(model, type_class)
+      end
+
+      def self.create_type_class(model)
+        base = Quail.base_object_class || GraphQL::Schema::Object
+        Class.new(base) do
+          graphql_name "#{model.name}Type"
+          description "Auto-generated type for #{model.name}"
+        end
+      end
+
+      def self.register_type_constant(model, type_class)
+        const_name = "#{model.name}Type"
+        Object.const_set(const_name, type_class) unless Object.const_defined?(const_name)
+      end
+
+      # Resolve a resource reference that can be a Class or a String class name.
+      def self.resolve_resource_ref(ref)
+        case ref
+        when Class  then ref
+        when String then ref.constantize
+        else raise ArgumentError, "Expected a resource class or string class name, got #{ref.inspect}"
+        end
+      end
+
+      def self.resolve_polymorphic_type(obj, assoc_name)
+        resource = Quail.resource_for(obj.class)
+        unless resource
+          raise GraphQL::ExecutionError,
+                "Cannot resolve polymorphic type '#{obj.class.name}' " \
+                "for association :#{assoc_name} — no resource registered"
+        end
+        resource.graphql_type
+      end
+
+      # Delegate public API so existing callers (and tests) still work.
+      def self.add_association_fields(resource_class) = AssociationBuilder.add_fields(resource_class)
+      def self.add_single_association(...) = AssociationBuilder.add_single(...)
+      def self.add_polymorphic_field(...) = AssociationBuilder.add_polymorphic_field(...)
+      def self.build_union_type(...) = AssociationBuilder.build_union_type(...)
+    end
+  end
+end

data/lib/quail/resource.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Quail
+  # Mixin that turns a class into a Quail resource with auto-generated GraphQL types,
+  # queries, mutations, and subscriptions.
+  module Resource
+    def self.included(base)
+      base.include DSL
+      base.extend Lookup
+
+      Quail.register(base)
+    end
+
+    # Class-level accessors for the generated GraphQL type, mutations, queries, and subscriptions.
+    module Lookup
+      def graphql_type
+        @graphql_type
+      end
+
+      def mutations
+        @mutations ||= MutationBuilder.call(self)
+      end
+
+      def query_fields
+        @query_fields ||= QueryBuilder.call(self)
+      end
+
+      def subscription_fields
+        @subscription_fields ||= SubscriptionBuilder.call(self)
+      end
+    end
+  end
+end

data/lib/quail/schema_builder/discovery.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Quail
+  module SchemaBuilder
+    # Discovers custom mutation and query classes from the app/graphql directory.
+    module Discovery
+      def self.custom_mutations
+        discover_classes("mutations", Quail::Mutation)
+      end
+
+      def self.custom_queries
+        discover_classes("queries", Quail::Query)
+      end
+
+      def self.discover_classes(dir, base_class)
+        return {} unless defined?(Rails)
+
+        result = {}
+        Dir[Rails.root.join("app/graphql/#{dir}/**/*.rb")].each do |f|
+          name, klass = resolve_class(f, dir, base_class)
+          result[name] = klass if klass
+        end
+        result
+      end
+
+      def self.resolve_class(file, dir, base_class)
+        relative = Pathname.new(file).relative_path_from(Rails.root.join("app/graphql/#{dir}"))
+        base_name = relative.to_s.delete_suffix(".rb").camelize
+
+        # Try top-level constant first (autoload root convention), fall back to namespaced
+        klass = begin
+          base_name.constantize
+        rescue NameError
+          "#{dir.camelize}::#{base_name}".constantize
+        end
+        return nil unless klass < base_class
+
+        [klass.name.demodulize.camelize(:lower).to_sym, klass]
+      end
+    end
+  end
+end

data/lib/quail/schema_builder/type_definitions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Quail
+  module SchemaBuilder
+    # Helpers for defining fields and arguments on dynamically-built GraphQL types.
+    module TypeDefinitions
+      def self.define_query_fields(type_class, fields)
+        fields.each do |name, config|
+          f = type_class.field name, config[:type], null: config[:null]
+          add_arguments(f, config[:arguments])
+          next unless config[:resolve]
+
+          type_class.define_method(name) do |**args|
+            config[:resolve].call(object, args, context)
+          end
+        end
+      end
+
+      def self.define_extra_query_fields(type_class, extra_fields)
+        extra_fields.each do |name, config|
+          f = type_class.field name, config[:type], null: config[:null]
+          add_arguments(f, config[:arguments])
+
+          resolver = config[:resolver]
+          type_class.define_method(name) do |**args|
+            resolver.new(object, args, context).call
+          end
+        end
+      end
+
+      def self.define_subscription_fields(type_class, fields)
+        fields.each do |name, sub_class|
+          type_class.field name, subscription: sub_class
+        end
+      end
+
+      def self.add_arguments(field, arguments)
+        arguments&.each do |arg_name, arg_config|
+          field.argument arg_name, arg_config[:type], required: arg_config[:required]
+        end
+      end
+    end
+  end
+end