lighthouse-graphql 0.6.0 → 0.7.0

data/lib/lighthouse/schema_factory.rb

@@ -7,13 +7,13 @@
 module Lighthouse::GraphQL::SchemaFactory
   module_function
 
-  def build_base_schema(sdl_folder: nil, sdl: nil, base_types: {}, schema_options: {}, **extra_options)
+  def build_base_schema(schema_path: nil, sdl: nil, base_types: {}, schema_options: {}, **extra_options)
     # Absorb any extra keyword options (e.g. `federation: true`) into the
     # schema options bag so callers can pass schema-level flags directly
     # without the factory needing to enumerate every one.
     schema_options = extra_options.merge(schema_options)
 
-    sdl_string = sdl || load_sdl(sdl_folder)
+    sdl_string = sdl || load_sdl(schema_path)
     schema_class = schema_options.delete(:schema_class)
 
     Lighthouse::GraphQL::SchemaGenerator.build(
@@ -24,12 +24,9 @@ module Lighthouse::GraphQL::SchemaFactory
     )
   end
 
-  # The SDL in `sdl_folder` (default: Config.sdl_folder), or the bundled
-  # schema.graphql when there is no such folder.
-  def load_sdl(sdl_folder)
-    folder = sdl_folder || (Lighthouse::GraphQL::Config.sdl_folder if defined?(Lighthouse::GraphQL::Config))
-    return Lighthouse::GraphQL::SDLLoader.load_from_folder(folder) if folder && Dir.exist?(folder)
-
-    File.read(File.expand_path('../../schema.graphql', __dir__))
+  # The schema read from `schema_path` (default: Config.schema_path) and the
+  # files it imports.
+  def load_sdl(schema_path = nil)
+    Lighthouse::GraphQL::SchemaStitcher.new(schema_path || Lighthouse::Config.schema_path).schema_string
   end
 end

data/lib/lighthouse/schema_generator.rb

@@ -122,10 +122,11 @@ module Lighthouse::GraphQL::SchemaGenerator
   end
 
   # The SDL as the schema is built from it: directive definitions injected
-  # (so apps don't hand-declare Lighthouse's directives), then every
-  # registered manipulator run (pagination types, whereConditions inputs, ...).
+  # (so apps don't hand-declare Lighthouse's directives), then the
+  # manipulation phase (ASTBuilder: type extensions merged, pagination types,
+  # whereConditions / orderBy inputs, ...).
   def manipulate(sdl)
-    augment_sdl_with_connections(inject_directive_definitions(sdl))
+    Lighthouse::GraphQL::ASTBuilder.build(inject_directive_definitions(sdl))
   end
 
   # `bases`: { root kind => the base class its fields' classes inherit from } (ResolverBases).
@@ -194,18 +195,6 @@ module Lighthouse::GraphQL::SchemaGenerator
     # ignore failures during post-processing
   end
 
-  # Scan SDL string for list-typed fields that carry relationship directives
-  # and produce Connection/Edge types where missing. This is a lightweight
-  # transformation that mirrors Lighthouse behavior: clients can declare
-  # `roles: [Role!]! @belongsToMany` and the builder will expose a
-  # `RoleConnection` type and swap the field to return that connection.
-  def augment_sdl_with_connections(sdl)
-    # Drive SDL manipulation through the registry so each directive owns its
-    # manipulation behavior and new manipulators can be added by registering
-    # a class (no edits here).
-    Lighthouse::DirectiveRegistry.default.manipulate_sdl(sdl)
-  end
-
   # Prepend `directive @name(...) on ...` definitions for registered,
   # self-describing directives that the SDL uses but has not declared.
   # Already-declared directives are left untouched (no duplicates).

data/lib/lighthouse/schema_stitcher.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Reads the schema from one entrypoint (Config.schema_path,
+# graphql/schema.graphql by default) and pastes in the files it imports, as PHP
+# Lighthouse's SchemaStitcher does:
+#
+#   type Query
+#
+#   #import user.graphql
+#   #import blog/*.graphql
+#
+# An import names a path relative to the file it is in, and may be a glob.
+# Imported files are read the same way, so they can import others. A file is
+# read once: importing it again, or importing a file that imports it back,
+# adds nothing. Only the files reached from the entrypoint are in the schema.
+class Lighthouse::GraphQL::SchemaStitcher
+  IMPORT = '#import '
+
+  attr_reader :root_schema_path
+
+  def initialize(root_schema_path)
+    path = File.expand_path(root_schema_path.to_s)
+    unless File.file?(path)
+      raise Lighthouse::DefinitionError,
+            "Failed to find a GraphQL schema file at #{path}. Set config.schema_path, or run bin/rails generate lighthouse:install."
+    end
+
+    @root_schema_path = File.realpath(path)
+  end
+
+  # The stitched schema: the entrypoint with every import replaced by the file's content.
+  def schema_string
+    gather(@root_schema_path, Set.new)
+  end
+
+  # Every file the schema is read from, the entrypoint first.
+  def files
+    visited = Set.new
+    gather(@root_schema_path, visited)
+    visited.to_a
+  end
+
+  private
+
+  def gather(path, visited)
+    return '' unless visited.add?(path)
+
+    File.readlines(path, chomp: true).map { |line| import_line?(line) ? import(path, line, visited) : "#{line}\n" }.join
+  end
+
+  def import_line?(line)
+    line.strip.start_with?(IMPORT)
+  end
+
+  def import(path, line, visited)
+    name = line.strip.delete_prefix(IMPORT).strip
+    import_path = File.join(File.dirname(path), name)
+    return Dir.glob(import_path).map { |file| gather(File.realpath(file), visited) }.join if name.include?('*')
+
+    raise Lighthouse::DefinitionError, "Did not find GraphQL schema import at #{import_path}." unless File.file?(import_path)
+
+    gather(File.realpath(import_path), visited)
+  end
+end

data/lib/lighthouse/support/naming.rb

@@ -52,16 +52,4 @@ module Lighthouse::Support::Naming
     snake = raw.underscore
     [raw.to_sym, raw, snake.to_sym, snake].uniq
   end
-
-  # Derive an Eloquent-style relation name from a `has<Relation>` argument
-  # name, e.g. "hasContact" -> "contacts". Returns nil when the argument does
-  # not follow the `has` convention.
-  def derive_relation_name(arg_name)
-    return nil unless arg_name.to_s.match?(/^has/i)
-
-    trailing = arg_name.to_s.sub(/^has/i, '')
-    return nil if trailing.empty?
-
-    trailing.underscore.pluralize
-  end
 end

data/lib/lighthouse/where_conditions/columns.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The column a client names in @whereConditions or @orderBy, as an Arel node.
+# Enum values (`CREATED_AT`, or the column an @enum(value:) gives) map onto
+# columns as everywhere (Support::Naming). A column of an unrestricted input
+# (`column: String`) comes from the client as is, so it must be an identifier,
+# `table.column`, or either with a path into a JSON document (`meta->tags`,
+# JsonColumn), as PHP Lighthouse checks it.
+module Lighthouse::WhereConditions::Columns
+  IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?\z/
+
+  module_function
+
+  # The column on `klass`'s table, or `table.column`. A JSON path's value is
+  # compiled `as` JsonColumn.node says: :sort to order by, :text, :numeric or
+  # :boolean to compare with.
+  def attribute(klass, column, as: :sort)
+    json = Lighthouse::WhereConditions::JsonColumn
+    if json.json?(column)
+      raise ::GraphQL::ExecutionError, invalid_column_name(column) unless json.valid?(column)
+
+      return json.node(klass, column, as: as)
+    end
+
+    name = Lighthouse::Support::Naming.column(column)
+    raise ::GraphQL::ExecutionError, invalid_column_name(column) unless IDENTIFIER.match?(name)
+
+    table, name = name.split('.', 2) if name.include?('.')
+    table ? ::Arel::Table.new(table)[name] : klass.arel_table[name]
+  end
+
+  def invalid_column_name(column)
+    'Column names may contain only alphanumerics or underscores, optionally a table and a JSON path ' \
+      "(posts.meta->tags), and may not begin with a digit, got: #{column}"
+  end
+end

data/lib/lighthouse/where_conditions/handler.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Applies a @whereConditions value to a relation, as PHP Lighthouse's
+# WhereConditionsHandler: the conditions of one level all hold, an AND list is
+# a nested group whose conditions all hold, an OR list one where at least one
+# does, and HAS checks how many related records match a condition.
+#
+#   { column: AGE, operator: GT, value: 37, OR: [{ column: TYPE, value: "Actor" }, ...] }
+#   -> age > 37 AND (type = 'Actor' OR ...)
+#
+#   { HAS: { relation: "posts", amount: 3, condition: { column: "published", value: true } } }
+#   -> users with at least 3 published posts
+#
+# A column the client names (an unrestricted WhereConditions takes any) must
+# be an identifier, `table.column` at most (Columns). The columns of a HAS
+# condition are those of the related model's table.
+#
+# A custom handler (`@whereConditions(handler: "...")`) is any object or
+# class answering `call(relation, conditions)` with the relation.
+module Lighthouse::WhereConditions::Handler
+  Types = Lighthouse::WhereConditions::Types
+
+  # How a HAS operator compares the number of related records with `amount`.
+  COUNT_COMPARISONS = { 'EQ' => :eq, 'NEQ' => :not_eq, 'GT' => :gt, 'GTE' => :gteq, 'LT' => :lt, 'LTE' => :lteq }.freeze
+  RUBY_COMPARISONS = { 'EQ' => :==, 'NEQ' => :!=, 'GT' => :>, 'GTE' => :>=, 'LT' => :<, 'LTE' => :<= }.freeze
+
+  # The Arel predicate of each operator that takes a value: [method, how the value is passed].
+  PREDICATES = {
+    'LIKE' => [:matches, :pattern], 'NOT_LIKE' => [:does_not_match, :pattern],
+    'IN' => [:in, :list], 'NOT_IN' => [:not_in, :list],
+    'BETWEEN' => [:between, :range], 'NOT_BETWEEN' => [:not_between, :range]
+  }.merge(COUNT_COMPARISONS.transform_values { |method| [method, :value] }).freeze
+
+  module_function
+
+  def call(relation, conditions)
+    predicate = predicate(relation.klass, normalize(conditions))
+    predicate ? relation.where(predicate) : relation
+  end
+
+  # The conditions as a Hash of :column, :operator, :value, :and, :or, :has
+  # (and :relation, :amount, :condition in a HAS), leaving the value as given.
+  def normalize(conditions)
+    return nil if conditions.nil?
+
+    hash = conditions.respond_to?(:to_h) ? conditions.to_h : conditions
+    hash.each_with_object({}) do |(key, value), normalized|
+      key = key.to_s.underscore.to_sym
+      normalized[key] =
+        case key
+        when :and, :or then Array(value).map { |condition| normalize(condition) }
+        when :has, :condition then normalize(value)
+        else value
+        end
+    end
+  end
+
+  # The Arel predicate of one level of conditions, or nil when it has none.
+  def predicate(klass, conditions)
+    return nil if conditions.blank?
+
+    nodes = [
+      group(klass, conditions[:and], :and),
+      group(klass, conditions[:or], :or),
+      conditions[:has] && has(klass, conditions[:has]),
+      conditions[:column] && column_condition(klass, conditions)
+    ].compact
+    nodes.empty? ? nil : nodes.reduce { |left, right| left.and(right) }
+  end
+
+  def group(klass, conditions, boolean)
+    nodes = Array(conditions).filter_map { |condition| predicate(klass, condition) }
+    return nil if nodes.empty?
+
+    boolean == :and ? ::Arel::Nodes::Grouping.new(::Arel::Nodes::And.new(nodes)) : nodes.reduce { |left, right| left.or(right) }
+  end
+
+  def column_condition(klass, conditions)
+    operator = (conditions[:operator] || Types::DEFAULT_OPERATOR).to_s.upcase
+    compared_as = Lighthouse::WhereConditions::JsonColumn.compared_as(operator, conditions[:value])
+    attribute = Lighthouse::WhereConditions::Columns.attribute(klass, conditions[:column], as: compared_as)
+    return attribute.eq(nil) if operator == 'IS_NULL'
+    return attribute.not_eq(nil) if operator == 'IS_NOT_NULL'
+
+    unless conditions.key?(:value)
+      raise ::GraphQL::ExecutionError, "Did not receive a value to match the WhereConditions for column #{conditions[:column]}."
+    end
+
+    compare(attribute, operator, conditions[:value])
+  end
+
+  def compare(attribute, operator, value)
+    method, kind = PREDICATES[operator]
+    raise ::GraphQL::ExecutionError, "Unknown SQLOperator #{operator}." unless method
+
+    case kind
+    when :pattern then attribute.public_send(method, value, nil, true) # LIKE, case-sensitive as SQL's
+    when :list then attribute.public_send(method, Array(value))
+    when :range then attribute.public_send(method, range(value))
+    else attribute.public_send(method, value)
+    end
+  end
+
+  def range(value)
+    values = Array(value)
+    raise ::GraphQL::ExecutionError, 'BETWEEN needs a value of two elements: [from, to].' unless values.size == 2
+
+    values.first..values.last
+  end
+
+  # Records of `klass` with `amount` (compared by `operator`) related records
+  # matching the condition: an IN over the records that have them, and, when
+  # having none satisfies the comparison, the records that have none too.
+  def has(klass, has)
+    reflection = reflection(klass, has[:relation])
+    operator = (has[:operator] || Types::DEFAULT_HAS_OPERATOR).to_s.upcase
+    amount = (has[:amount] || Types::DEFAULT_HAS_AMOUNT).to_i
+    raise ::GraphQL::ExecutionError, "HAS can not compare the amount with #{operator}." unless COUNT_COMPARISONS.key?(operator)
+
+    key = klass.arel_table[klass.primary_key]
+    related = related_scope(klass, reflection, has[:condition])
+    predicate = key.in(owners(related, key, reflection.klass, operator, amount).arel)
+    0.public_send(RUBY_COMPARISONS.fetch(operator), amount) ? predicate.or(key.not_in(related.select(key).arel)) : predicate
+  end
+
+  # `klass` joined to its related records that match the condition.
+  def related_scope(klass, reflection, condition)
+    scope = klass.unscoped.joins(reflection.name)
+    predicate = predicate(reflection.klass, condition)
+    predicate ? scope.where(predicate) : scope
+  end
+
+  # The keys of the records with `amount` related records, by `operator`. At
+  # least one is any join; another amount needs them counted.
+  def owners(related_scope, key, related, operator, amount)
+    return related_scope.select(key) if (operator == 'GTE' && amount == 1) || (operator == 'GT' && amount.zero?)
+
+    counted = related.primary_key ? related.arel_table[related.primary_key] : ::Arel.star
+    count = ::Arel::Nodes::Count.new([counted], true)
+    related_scope.group(key).having(count.public_send(COUNT_COMPARISONS.fetch(operator), amount)).select(key)
+  end
+
+  # The association `name` names on `klass`: as written, snake_cased, singular or plural.
+  def reflection(klass, name)
+    candidates = [name.to_s, name.to_s.underscore, name.to_s.underscore.singularize, name.to_s.underscore.pluralize].uniq
+    reflection = candidates.lazy.filter_map { |candidate| klass.reflect_on_association(candidate.to_sym) }.first
+    raise ::GraphQL::ExecutionError, "#{klass.name} has no relation #{name}." unless reflection
+    raise ::GraphQL::ExecutionError, "HAS can not check the polymorphic relation #{name}." if reflection.polymorphic?
+
+    reflection
+  end
+end

data/lib/lighthouse/where_conditions/json_column.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# A column with a path into its JSON document, as Laravel names one and PHP
+# Lighthouse's @whereConditions and @orderBy take it: `meta->tags`,
+# `posts.meta->author->name`, `meta->tags->0` (an array index). The value at
+# the path is compiled for the database, as Laravel's query grammars do:
+#
+#   PostgreSQL  "posts"."meta"->'author'->>'name'
+#   MySQL       JSON_UNQUOTE(JSON_EXTRACT(`posts`.`meta`, '$."author"."name"'))
+#   SQLite      json_extract("posts"."meta", '$."author"."name"')
+#
+# Unlike Laravel, it compares numbers and booleans as such, and orders by the
+# JSON value (numbers numerically), on every database. The result is an Arel
+# node: a condition calls its predicates (`eq`, `in`, `matches`, ...) and an
+# order its `asc` / `desc`.
+module Lighthouse::WhereConditions::JsonColumn
+  PATH = /\A(?:(?<table>[A-Za-z_]\w*)\.)?(?<column>[A-Za-z_]\w*)(?<path>(?:->[A-Za-z0-9_-]+)+)\z/
+
+  module_function
+
+  def json?(name)
+    name.to_s.include?('->')
+  end
+
+  def valid?(name)
+    PATH.match?(name.to_s)
+  end
+
+  # The value at the path, as `as` says: :text, :numeric, :boolean, :null (NULL
+  # when the path is missing or holds JSON null), or :sort (the JSON value,
+  # ordered by type, numbers numerically).
+  def node(klass, name, as: :text)
+    match = PATH.match(name.to_s) or raise ArgumentError, "not a JSON column: #{name}"
+    connection = klass.connection
+    target = [match[:table] || klass.table_name, match[:column]].then do |table, column|
+      "#{connection.quote_table_name(table)}.#{connection.quote_column_name(column)}"
+    end
+    segments = match[:path].split('->').drop(1)
+
+    ::Arel.sql(public_send(dialect(connection), target, segments, as))
+  end
+
+  # How a condition with `operator` compares the value at the path: patterns as
+  # text, nulls as JSON null too, the rest as the value is.
+  def compared_as(operator, value)
+    case operator
+    when 'LIKE', 'NOT_LIKE' then :text
+    when 'IS_NULL', 'IS_NOT_NULL' then :null
+    else kind_of_value(value)
+    end
+  end
+
+  # What a value compares as: numbers as numbers, booleans as booleans, the rest as text.
+  def kind_of_value(value)
+    sample = value.is_a?(Array) ? value.first : value
+    case sample
+    when Numeric then :numeric
+    when true, false then :boolean
+    else :text
+    end
+  end
+
+  def dialect(connection)
+    case connection.adapter_name
+    when /postg/i then :postgresql
+    when /mysql|trilogy/i then :mysql
+    else :sqlite
+    end
+  end
+
+  def postgresql(target, segments, as)
+    keys = segments.map { |segment| segment.match?(/\A\d+\z/) ? segment : "'#{segment}'" }
+    return "(#{target}->#{keys.join('->')})::jsonb" if as == :sort
+
+    text = keys.size == 1 ? "#{target}->>#{keys.first}" : "#{target}->#{keys[0...-1].join('->')}->>#{keys.last}"
+    { numeric: "(#{text})::numeric", boolean: "(#{text})::boolean" }.fetch(as, text) # :text, :null
+  end
+
+  def mysql(target, segments, as)
+    extract = "JSON_EXTRACT(#{target}, '#{json_path(segments)}')"
+    case as
+    when :text then "JSON_UNQUOTE(#{extract})"
+    when :numeric then "CAST(JSON_UNQUOTE(#{extract}) AS DECIMAL(65, 10))"
+    when :boolean then "(#{extract} = CAST('true' AS JSON))"
+    when :null then "NULLIF(JSON_TYPE(#{extract}), 'NULL')"
+    else extract
+    end
+  end
+
+  # json_extract answers SQLite's own types: numbers compare and order as numbers,
+  # booleans are 1 and 0.
+  def sqlite(target, segments, _as)
+    "json_extract(#{target}, '#{json_path(segments)}')"
+  end
+
+  def json_path(segments)
+    "$#{segments.map { |segment| segment.match?(/\A\d+\z/) ? "[#{segment}]" : %(."#{segment}") }.join}"
+  end
+end

data/lib/lighthouse/where_conditions/operator_map.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-# Maps the GraphQL SQLOperator enum values to Arel predicate methods.
-# Extracted from WhereConditionsApplier so that simple argument-filter
-# directives (@eq, @neq, @in, @notIn, @like, @where) can share the same
-# operator semantics.
+# Maps the operators @where(operator:) takes to Arel predicate methods.
 module Lighthouse::WhereConditions::OperatorMap
   OPERATORS = {
     'EQ' => :eq,

data/lib/lighthouse/where_conditions/types.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# The types @whereConditions and @whereHasConditions generate, as PHP
+# Lighthouse's WhereConditionsServiceProvider defines them. For an argument
+# whose input is named N:
+#
+#   N               column, operator, value, AND, OR, HAS: the conditions
+#   NRelation       HAS: a relation, how many of its records (operator, amount), and a condition on them
+#   NHasCondition   the condition on the related records: as N, but on any column
+#
+# Without `columns:` / `columnsEnum:` the argument shares the unrestricted
+# WhereConditions (and its WhereConditionsRelation / WhereConditionsHasCondition).
+module Lighthouse::WhereConditions::Types
+  DEFAULT = 'WhereConditions'
+  SQL_OPERATOR = 'SQLOperator'
+  MIXED = 'Mixed'
+
+  # The SQLOperator enum: what a condition compares the column with.
+  OPERATORS = {
+    'EQ' => 'Equal operator (`=`)',
+    'NEQ' => 'Not equal operator (`!=`)',
+    'GT' => 'Greater than operator (`>`)',
+    'GTE' => 'Greater than or equal operator (`>=`)',
+    'LT' => 'Less than operator (`<`)',
+    'LTE' => 'Less than or equal operator (`<=`)',
+    'LIKE' => 'Simple pattern matching (`LIKE`)',
+    'NOT_LIKE' => 'Negation of simple pattern matching (`NOT LIKE`)',
+    'IN' => 'Whether a value is within a set of values (`IN`)',
+    'NOT_IN' => 'Whether a value is not within a set of values (`NOT IN`)',
+    'BETWEEN' => 'Whether a value is within a range of values (`BETWEEN`)',
+    'NOT_BETWEEN' => 'Whether a value is not within a range of values (`NOT BETWEEN`)',
+    'IS_NULL' => 'Whether a value is null (`IS NULL`)',
+    'IS_NOT_NULL' => 'Whether a value is not null (`IS NOT NULL`)'
+  }.freeze
+
+  DEFAULT_OPERATOR = 'EQ'
+  DEFAULT_HAS_OPERATOR = 'GTE'
+  DEFAULT_HAS_AMOUNT = 1
+
+  module_function
+
+  # Defines N, NHasCondition and NRelation, and the SQLOperator and Mixed they use.
+  def define(document_ast, name, column_type, path)
+    document_ast.define_type(SQL_OPERATOR) { sql_operator }
+    document_ast.define_type(MIXED, 'scalar Mixed')
+    document_ast.define_type(name) { conditions(name, "Dynamic WHERE conditions for #{path}.", column_type) }
+    document_ast.define_type("#{name}HasCondition") do
+      conditions("#{name}HasCondition", "Dynamic WHERE HAS conditions for #{path}.", 'String')
+    end
+    document_ast.define_type("#{name}Relation") { relation(name, "Dynamic HAS conditions for WHERE conditions for #{path}.") }
+  end
+
+  def define_default(document_ast)
+    define(document_ast, DEFAULT, 'String', 'any column')
+  end
+
+  def conditions(name, description, column_type)
+    <<~GRAPHQL
+      "#{description}"
+      input #{name} {
+        "The column that is used for the condition."
+        column: #{column_type}
+
+        "The operator that is used for the condition."
+        operator: #{SQL_OPERATOR} = #{DEFAULT_OPERATOR}
+
+        "The value that is used for the condition."
+        value: #{MIXED}
+
+        "A set of conditions that requires all conditions to match."
+        AND: [#{name}!]
+
+        "A set of conditions that requires at least one condition to match."
+        OR: [#{name}!]
+
+        "Check whether a relation exists. Extra conditions or a minimum amount can be applied."
+        HAS: #{name.delete_suffix('HasCondition')}Relation
+      }
+    GRAPHQL
+  end
+
+  def relation(name, description)
+    <<~GRAPHQL
+      "#{description}"
+      input #{name}Relation {
+        "The relation that is checked."
+        relation: String!
+
+        "The comparison operator to test against the amount."
+        operator: #{SQL_OPERATOR} = #{DEFAULT_HAS_OPERATOR}
+
+        "The amount to test."
+        amount: Int = #{DEFAULT_HAS_AMOUNT}
+
+        "Additional condition logic."
+        condition: #{name}HasCondition
+      }
+    GRAPHQL
+  end
+
+  def sql_operator
+    values = OPERATORS.map { |value, description| %(  "#{description}"\n  #{value}) }
+    <<~GRAPHQL
+      "The available SQL operators that are used to filter query results."
+      enum #{SQL_OPERATOR} {
+      #{values.join("\n\n")}
+      }
+    GRAPHQL
+  end
+end

data/sig/lighthouse/directives.rbs

@@ -36,9 +36,17 @@ module Lighthouse
       include Directive
     end
 
+    # Its instances, built with (arg_node, directive_node), answer
+    # `manipulate_arg_definition(document_ast, field_node, type_node)` with the argument node.
     module ArgManipulator
       include Directive
     end
+
+    # Its instances, built with (field_node, directive_node), answer
+    # `handle_field_builder(relation)` with the constrained relation.
+    module FieldBuilder
+      include Directive
+    end
   end
 
   class DirectiveRegistry
@@ -67,6 +75,9 @@ module Lighthouse
     def resolution_names: () -> Array[String]
     def arg_builder_class: (String | Symbol name) -> Class?
     def arg_builder_names: () -> Array[String]
+    def arg_manipulator_class: (String | Symbol name) -> Class?
+    def arg_manipulator_classes: () -> Array[Class]
+    def field_builder_class: (String | Symbol name) -> Class?
 
     # { "name" => "directive @name(...) on ..." }
     def directive_definitions: () -> Hash[String, String]
@@ -83,9 +94,11 @@ module Lighthouse
     PROGRAMMATIC_TYPES_FILE: String
 
     # Writes both files into `output_dir` and returns their paths.
-    def self?.write: (output_dir: path, ?sdl_folder: path?, ?registry: DirectiveRegistry) -> Array[String]
+    def self?.write: (output_dir: path, ?schema_path: path?, ?registry: DirectiveRegistry) -> Array[String]
+    # Config.ide_helper's rewrite, on boot and every reload.
+    def self?.refresh: (?output_dir: path) -> Array[String]
     def self?.directives_sdl: (?String sdl, ?registry: DirectiveRegistry) -> String
-    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry) -> String
+    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry, ?directives: String) -> String
   end
 
   module GraphQL
@@ -107,7 +120,7 @@ module Lighthouse
         # `ctx`: the query's context, which @builder on an argument receives.
         def apply_where_filters: (relation relation, untyped args, ?context? ctx) -> relation
         def apply_arg_builders: (relation relation, arguments args_h, ?context? ctx) -> relation
-        def extract_relation_name_from_directive: (untyped arg_node) -> String?
+        def apply_field_builders: (relation relation, ?arguments args_h, ?context? ctx) -> relation
         def constantize_model: (String? name) -> Class?
         def apply_scopes: (relation relation) -> relation
 

data/sig/lighthouse/graphql.rbs

@@ -9,16 +9,60 @@ module Lighthouse
     type schema = untyped
 
     module RbLightHouse
-      # The schema built from the SDL in `sdl_folder` (default: Config.sdl_folder).
+      # The schema built from the SDL `schema_path` (default: Config.schema_path) and its imports.
       # `options` takes :base_types, :base_schema and the schema's own options.
-      def self.get_schema: (?sdl_folder: path?, ?options: Hash[Symbol, untyped]) -> schema
+      def self.get_schema: (?schema_path: path?, ?options: Hash[Symbol, untyped]) -> schema
       def self.configure: () ?{ (singleton(Lighthouse::Config) config) -> void } -> void
     end
 
     module SchemaFactory
-      def self?.build_base_schema: (?sdl_folder: path?, ?sdl: String?, ?base_types: Hash[untyped, untyped],
+      def self?.build_base_schema: (?schema_path: path?, ?sdl: String?, ?base_types: Hash[untyped, untyped],
                                     ?schema_options: Hash[Symbol, untyped], **untyped extra_options) -> schema
-      def self?.load_sdl: (path? sdl_folder) -> String
+      def self?.load_sdl: (?path? schema_path) -> String
+    end
+
+    # Reads the schema from its entrypoint, pasting in what it #imports.
+    class SchemaStitcher
+      IMPORT: String
+
+      attr_reader root_schema_path: String
+
+      def initialize: (path root_schema_path) -> void
+      def schema_string: () -> String
+      # Every file the schema is read from, the entrypoint first.
+      def files: () -> Array[String]
+    end
+
+    # The schema document the manipulation phase works on: each type defined once.
+    class DocumentAST
+      KEYWORDS: Hash[Class, String]
+      EXTENSIONS: Array[Class]
+
+      attr_reader types: Hash[String, untyped]
+      attr_reader type_extensions: Hash[String, Array[untyped]]
+      attr_reader directives: Hash[String, untyped]
+      attr_reader schema_definitions: Array[untyped]
+
+      def self.from_source: (String sdl) -> DocumentAST
+      def self.from_document: (untyped document) -> DocumentAST
+
+      def initialize: () -> void
+      def add: (untyped definition) -> untyped
+      # Adds a type, or replaces the one of the same name.
+      def put_type: (untyped definition) -> self
+      # Adds the type parsed from the SDL (or the block's), unless one of the name exists.
+      def define_type: (String name, ?String? sdl) ?{ () -> String } -> untyped
+      def type?: (String name) -> bool
+      def type_names: () -> Array[String]
+      def to_document: () -> untyped
+      def to_sdl: () -> String
+    end
+
+    # The manipulation phase: extensions merged, then the type, field and argument manipulators.
+    module ASTBuilder
+      ROOT_TYPES: Array[String]
+
+      def self?.build: (String sdl, ?registry: DirectiveRegistry) -> String
     end
 
     # Apollo's Automatic Persisted Queries, and a manifest of trusted operations.