lighthouse-graphql 0.6.0 → 0.7.1

data/lib/lighthouse/directives/generated_types.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# What the argument manipulators that generate types share, as PHP
+# Lighthouse's ASTHelper and GeneratesColumnsEnum: the qualified name of an
+# argument's types, the enum of its allowed columns, and the `_` placeholder
+# the argument is written with.
+#
+#   type Query { posts(orderBy: _ @orderBy(columns: ["posted_at"])): [Post!]! @all }
+#
+# names Query.posts(orderBy:)'s types QueryPostsOrderBy..., its columns enum
+# QueryPostsOrderByColumn { POSTED_AT @enum(value: "posted_at") }.
+module Lighthouse::GraphQL::Directives::GeneratedTypes
+  PLACEHOLDER = '_'
+
+  module_function
+
+  # Studly(Type) + Studly(field) + Studly(argument): QueryPostsOrderBy.
+  def qualified_arg_type(arg, field, type)
+    [type.name, field.name, arg.name].map { |name| studly(name) }.join
+  end
+
+  def studly(name)
+    name.to_s.split(/[_\s-]+/).map { |part| part[0].to_s.upcase + part[1..].to_s }.join
+  end
+
+  # `argument` of the directive as a Ruby value (`columns: ["a"]` -> ["a"]), or nil.
+  def directive_value(directive, name)
+    Lighthouse::Support::DirectiveArgs.literal(directive, name)
+  end
+
+  def directive_argument?(directive, name)
+    directive.arguments.any? { |argument| argument.name == name }
+  end
+
+  # Raises unless at most one of `names` is given to the directive.
+  def mutually_exclusive!(directive, names)
+    given = names.select { |name| directive_argument?(directive, name) }
+    return if given.size <= 1
+
+    raise Lighthouse::DefinitionError,
+          "The @#{directive.name} directive can only have one of the following arguments: #{names.map { |n| "`#{n}`" }.join(', ')}."
+  end
+
+  # Does the directive restrict the columns (`columns:` or `columnsEnum:`)?
+  def allowed_columns?(directive)
+    mutually_exclusive!(directive, %w[columns columnsEnum])
+    directive_argument?(directive, 'columns') || directive_argument?(directive, 'columnsEnum')
+  end
+
+  # The enum of the allowed columns: `columnsEnum:`, or one generated from
+  # `columns:` as <QualifiedArgType>Column.
+  def columns_enum(document_ast, directive, arg, field, type)
+    enum = directive_value(directive, 'columnsEnum')
+    return enum if enum
+
+    name = "#{qualified_arg_type(arg, field, type)}Column"
+    define_columns_enum(document_ast, name, directive_value(directive, 'columns'), "#{type.name}.#{field.name}.#{arg.name}")
+    name
+  end
+
+  def define_columns_enum(document_ast, name, columns, path)
+    values = Array(columns).map { |column| %(  #{enum_value_name(column)} @enum(value: "#{column}")) }.uniq
+    document_ast.put_type(parse(<<~GRAPHQL))
+      "Allowed column names for #{path}."
+      enum #{name} {
+      #{values.join("\n")}
+      }
+    GRAPHQL
+  end
+
+  # `posted_at` -> POSTED_AT, `roles.id` -> ROLES_ID.
+  def enum_value_name(column)
+    name = column.to_s.gsub(/[^0-9A-Za-z_]/, '_').upcase
+    name.match?(/\A[0-9]/) ? "_#{name}" : name
+  end
+
+  # The argument with its type replaced by `type_string` ("[QueryPostsOrderByClause!]"),
+  # when it is written with the `_` placeholder. An argument given a type of
+  # its own keeps it.
+  def replace_placeholder(arg, type_string)
+    return arg unless placeholder?(arg.type)
+
+    arg.merge(type: parse_type(type_string))
+  end
+
+  def placeholder?(type)
+    type = type.of_type while type.respond_to?(:of_type)
+    type.name == PLACEHOLDER
+  end
+
+  # The argument with `description`, unless it has one.
+  def describe(arg, description)
+    arg.description.to_s.empty? ? arg.merge(description: description) : arg
+  end
+
+  def parse(sdl)
+    ::GraphQL::Language::Parser.parse(sdl).definitions.first
+  end
+
+  def parse_type(type_string)
+    parse("input LighthouseTypeReference { field: #{type_string} }").fields.first.type
+  end
+end

data/lib/lighthouse/directives/registry.rb

@@ -13,7 +13,9 @@
 #
 # A registered class is classified as a field resolver when it includes
 # Contracts::FieldResolver OR responds to the legacy `#define_resolver`
-# instance method.
+# instance method. A class including Contracts::ArgManipulator also rewrites
+# its arguments while the schema is built (ASTBuilder), and one including
+# Contracts::FieldBuilder constrains its fields' queries.
 class Lighthouse::DirectiveRegistry
   class << self
     def default
@@ -29,6 +31,8 @@ class Lighthouse::DirectiveRegistry
   def initialize
     @resolution = {}
     @arg_builders = {}
+    @arg_manipulators = {}
+    @field_builders = {}
     @sdl_manipulators = []
     @definitions = {}
     @type_definitions = {}
@@ -42,11 +46,7 @@ class Lighthouse::DirectiveRegistry
       name = name_or_klass
     end
 
-    if arg_builder?(klass)
-      @arg_builders[name.to_s] = klass
-    elsif resolver?(klass)
-      @resolution[name.to_s] = klass
-    end
+    classify(name.to_s, klass)
     self
   end
 
@@ -97,6 +97,21 @@ class Lighthouse::DirectiveRegistry
     @arg_builders.keys
   end
 
+  # Argument directives that rewrite their argument while the schema is built
+  # (@whereConditions, @whereHasConditions, @orderBy), as ASTBuilder applies them.
+  def arg_manipulator_class(name)
+    @arg_manipulators[name.to_s]
+  end
+
+  def arg_manipulator_classes
+    @arg_manipulators.values
+  end
+
+  # Field directives that constrain the field's query (@orderBy on a field).
+  def field_builder_class(name)
+    @field_builders[name.to_s]
+  end
+
   # SDL `directive @name(...) on ...` definitions contributed by registered,
   # self-describing directive classes. The generator injects these so the app
   # does not have to hand-declare every directive it uses.
@@ -193,7 +208,7 @@ class Lighthouse::DirectiveRegistry
 
   # Argument-builder filter/sort directives.
   ARG_BUILDERS = %i[
-    Eq Neq In NotIn Like Where WhereKey OrderBy Trashed WithoutGlobalScopes
+    Eq Neq In NotIn Like Where WhereKey OrderBy WhereConditions WhereHasConditions Trashed WithoutGlobalScopes
     WhereNull WhereNotNull WhereBetween WhereNotBetween WhereJsonContains Scope Limit
   ].freeze
 
@@ -205,11 +220,11 @@ class Lighthouse::DirectiveRegistry
 
     # SDL manipulators run in registration order during the manipulation phase.
     # @hide / @show first, so a removed field generates nothing; then @model,
-    # which names the model of fields @paginate then rewrites.
+    # which names the model of fields @paginate then rewrites. The argument
+    # manipulators (@whereConditions, @orderBy, ...) run after all of them.
     register_manipulator(Lighthouse::GraphQL::Directives::VisibilityDirective)
     register_manipulator(Lighthouse::GraphQL::Directives::ModelDirective)
     register_manipulator(Lighthouse::GraphQL::Directives::PaginationManipulator)
-    register_manipulator(Lighthouse::GraphQL::Directives::WhereConditionsDirective)
     register_manipulator(Lighthouse::GraphQL::Directives::SoftDeletesDirective)
     register_manipulator(Lighthouse::GraphQL::Directives::NodeDirective)
 
@@ -232,8 +247,22 @@ class Lighthouse::DirectiveRegistry
     nil
   end
 
+  def classify(name, klass)
+    if arg_builder?(klass)
+      @arg_builders[name] = klass
+    elsif resolver?(klass)
+      @resolution[name] = klass
+    end
+    @arg_manipulators[name] = klass if includes?(klass, Lighthouse::Contracts::ArgManipulator)
+    @field_builders[name] = klass if includes?(klass, Lighthouse::Contracts::FieldBuilder)
+  end
+
   def arg_builder?(klass)
-    klass.respond_to?(:include?) && klass.include?(Lighthouse::Contracts::ArgBuilder)
+    includes?(klass, Lighthouse::Contracts::ArgBuilder)
+  end
+
+  def includes?(klass, contract)
+    klass.respond_to?(:include?) && klass.include?(contract)
   end
 
   def resolver?(klass)

data/lib/lighthouse/document_ast.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# The schema document as the manipulation phase works on it, as PHP
+# Lighthouse's DocumentAST: the type definitions by name, the type extensions
+# by the name they extend, the directive definitions and the schema
+# definition/extensions.
+#
+# A type is defined once. A second definition of the same name is an error,
+# not a merge: add to a type from another file with `extend type` (or
+# `extend input`, `extend enum`, ...), which ASTBuilder merges into it.
+#
+# graphql-ruby's nodes are immutable, so a manipulation replaces a type with
+# `put_type(type.merge(...))` rather than editing it.
+class Lighthouse::GraphQL::DocumentAST
+  Nodes = ::GraphQL::Language::Nodes
+
+  # The SDL keyword each kind of definition is extended with.
+  KEYWORDS = {
+    Nodes::ObjectTypeDefinition => 'type',
+    Nodes::InterfaceTypeDefinition => 'interface',
+    Nodes::InputObjectTypeDefinition => 'input',
+    Nodes::EnumTypeDefinition => 'enum',
+    Nodes::UnionTypeDefinition => 'union',
+    Nodes::ScalarTypeDefinition => 'scalar'
+  }.freeze
+
+  EXTENSIONS = [
+    Nodes::ObjectTypeExtension, Nodes::InterfaceTypeExtension, Nodes::InputObjectTypeExtension,
+    Nodes::EnumTypeExtension, Nodes::UnionTypeExtension, Nodes::ScalarTypeExtension
+  ].freeze
+
+  attr_reader :types, :type_extensions, :directives, :schema_definitions
+
+  def self.from_source(sdl)
+    document = begin
+      ::GraphQL::Language::Parser.parse(sdl.to_s)
+    rescue ::GraphQL::ParseError => e
+      raise Lighthouse::DefinitionError, "The schema is not valid GraphQL: #{e.message}"
+    end
+    from_document(document)
+  end
+
+  def self.from_document(document)
+    new.tap { |ast| document.definitions.each { |definition| ast.add(definition) } }
+  end
+
+  def initialize
+    @types = {}
+    @type_extensions = Hash.new { |hash, name| hash[name] = [] }
+    @directives = {}
+    @schema_definitions = []
+  end
+
+  def add(definition)
+    case definition
+    when *KEYWORDS.keys then add_type(definition)
+    when *EXTENSIONS then @type_extensions[definition.name] << definition
+    when Nodes::DirectiveDefinition then add_directive(definition)
+    when Nodes::SchemaDefinition, Nodes::SchemaExtension then @schema_definitions << definition
+    else raise Lighthouse::DefinitionError, "Unknown definition type: #{definition.class}"
+    end
+  end
+
+  # Adds a type, or replaces the definition of the same name.
+  def put_type(definition)
+    @types[definition.name] = definition
+    self
+  end
+
+  # Adds the type parsed from `sdl`, unless the document has a type of that name.
+  def define_type(name, sdl = nil)
+    return @types[name] if @types.key?(name)
+
+    definition = ::GraphQL::Language::Parser.parse(sdl || yield).definitions.first
+    put_type(definition)
+    definition
+  end
+
+  def type?(name) = @types.key?(name)
+
+  # The names of the types, as they are now: manipulators add types while
+  # ASTBuilder goes over these.
+  def type_names = @types.keys
+
+  def to_document
+    Nodes::Document.new(definitions: @schema_definitions + @directives.values + @types.values + @type_extensions.values.flatten)
+  end
+
+  def to_sdl
+    ::GraphQL::Language::Printer.new.print(to_document)
+  end
+
+  private
+
+  def add_type(definition)
+    if @types.key?(definition.name)
+      keyword = KEYWORDS.fetch(definition.class)
+      raise Lighthouse::DefinitionError,
+            "Duplicate definition #{definition.name} found when parsing the schema. Define a type once and add to it " \
+            "from other files with `extend #{keyword} #{definition.name}`."
+    end
+
+    @types[definition.name] = definition
+  end
+
+  def add_directive(definition)
+    raise Lighthouse::DefinitionError, "Duplicate definition @#{definition.name} found when parsing the schema." if @directives.key?(definition.name)
+
+    @directives[definition.name] = definition
+  end
+end

data/lib/lighthouse/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module GraphQL
-    VERSION = '0.6.0'
+    VERSION = '0.7.1'
   end
 end

data/lib/lighthouse/ide_helper.rb

@@ -13,7 +13,13 @@ require 'fileutils'
 #   ...), which exist in the executable schema but in no .graphql file.
 #
 # Point your IDE's graphql-config at both files next to your own SDL. Run it
-# with `bin/rails lighthouse:ide_helper`.
+# with `bin/rails lighthouse:ide_helper`; in development, an app with a
+# graphql.config.yml also gets them rewritten on boot and on every reload
+# (Config.ide_helper).
+#
+# The IDE reads the three together as one schema, so no type may be in two of
+# them: graphql-js (the VS Code and JetBrains plugins) rejects a type defined
+# twice, even where graphql-ruby keeps the last definition.
 module Lighthouse::IdeHelper
   DIRECTIVES_FILE = 'schema-directives.graphql'
   PROGRAMMATIC_TYPES_FILE = 'programmatic-types.graphql'
@@ -27,23 +33,66 @@ module Lighthouse::IdeHelper
     ::GraphQL::Language::Nodes::ScalarTypeDefinition
   ].freeze
 
-  PLACEHOLDER_SCALAR = %("Placeholder for an argument type Lighthouse generates, e.g. with @whereConditions."\nscalar _)
+  PLACEHOLDER_SCALAR = %("Placeholder for an argument type Lighthouse generates, e.g. with @whereConditions or @orderBy."\nscalar _)
 
   module_function
 
-  # Writes both files into `output_dir` and returns their paths.
-  def write(output_dir:, sdl_folder: Lighthouse::Config.sdl_folder, registry: Lighthouse::DirectiveRegistry.default)
-    sdl = sdl_folder && Dir.exist?(sdl_folder.to_s) ? Lighthouse::GraphQL::SDLLoader.load_from_folder(sdl_folder.to_s) : ''
+  # Writes both files into `output_dir` and returns their paths. A file whose
+  # content has not changed is left alone, so the IDE does not reload for nothing.
+  #
+  # A schema that does not build (a type defined twice, half-written, ...)
+  # still gets its directives, and keeps the programmatic types it had, or
+  # gets the `_` placeholder alone: the IDE never loses a type it was given.
+  def write(output_dir:, schema_path: Lighthouse::Config.schema_path, registry: Lighthouse::DirectiveRegistry.default)
+    sdl = ide_sdl(schema_path)
+    directives = directives_sdl(sdl, registry: registry)
 
     FileUtils.mkdir_p(output_dir.to_s)
-    {
-      DIRECTIVES_FILE => directives_sdl(sdl, registry: registry),
-      PROGRAMMATIC_TYPES_FILE => programmatic_types_sdl(sdl, registry: registry)
-    }.map do |name, content|
-      path = File.join(output_dir.to_s, name)
-      File.write(path, content)
-      path
+    directives_path = write_file(output_dir, DIRECTIVES_FILE, directives)
+    types_path = File.join(output_dir.to_s, PROGRAMMATIC_TYPES_FILE)
+    begin
+      write_file(output_dir, PROGRAMMATIC_TYPES_FILE, programmatic_types_sdl(sdl, registry: registry, directives: directives))
+    rescue StandardError => e
+      warn("Lighthouse: #{PROGRAMMATIC_TYPES_FILE} kept as it was, the schema does not build: #{e.message}")
+      write_file(output_dir, PROGRAMMATIC_TYPES_FILE, placeholder_only(sdl)) unless File.exist?(types_path)
     end
+    [directives_path, types_path]
+  end
+
+  # The schema as the IDE reads it: the entrypoint and its imports, or, when
+  # they do not load, every .graphql file under the entrypoint's folder.
+  def ide_sdl(schema_path)
+    return '' unless schema_path
+
+    return Lighthouse::GraphQL::SchemaFactory.load_sdl(schema_path) if File.file?(schema_path.to_s)
+
+    raise Lighthouse::DefinitionError, "no schema at #{schema_path}"
+  rescue Lighthouse::DefinitionError
+    Dir[File.join(File.dirname(schema_path.to_s), '**', '*.graphql')].map { |file| File.read(file) }.join("\n")
+  end
+
+  def write_file(output_dir, name, content)
+    path = File.join(output_dir.to_s, name)
+    File.write(path, content) unless File.exist?(path) && File.read(path) == content
+    path
+  end
+
+  def placeholder_only(sdl)
+    declared = sdl.to_s.match?(/^\s*scalar\s+_\b/) ? Set['_'] : Set.new
+    render('The schema does not build: only the `_` placeholder is declared until it does.',
+           undeclared_placeholder?(sdl, declared) ? [PLACEHOLDER_SCALAR] : [])
+  end
+
+  # Config.ide_helper's refresh: the files in the Rails app's root, when the
+  # schema loads. A schema that does not is the next request's error to raise;
+  # here it only warns.
+  def refresh(output_dir: ::Rails.root)
+    return [] unless Lighthouse::Config.ide_helper
+
+    write(output_dir: output_dir)
+  rescue StandardError => e
+    warn("Lighthouse: the IDE helper files were not refreshed: #{e.message}")
+    []
   end
 
   def directives_sdl(sdl = '', registry: Lighthouse::DirectiveRegistry.default)
@@ -56,13 +105,12 @@ module Lighthouse::IdeHelper
     )
   end
 
-  def programmatic_types_sdl(sdl, registry: Lighthouse::DirectiveRegistry.default)
-    original = type_names(sdl)
-    generated = parse(registry.manipulate_sdl(sdl)).definitions.select do |definition|
-      type_definition?(definition) && original.exclude?(definition.name)
-    end
-    generated_sdl = generated.sort_by(&:name).map(&:to_query_string)
-    generated_sdl.unshift(PLACEHOLDER_SCALAR) if undeclared_placeholder?(sdl, original, generated)
+  # `directives`: the schema-directives.graphql written next to it, whose types
+  # (`CanAction`, `Mixed`, ...) some manipulators inject too and are left out here.
+  def programmatic_types_sdl(sdl, registry: Lighthouse::DirectiveRegistry.default, directives: directives_sdl(sdl, registry: registry))
+    declared = type_names(sdl) | type_names(directives)
+    generated_sdl = generated_types(sdl, declared, registry).sort_by(&:name).map(&:to_query_string)
+    generated_sdl.unshift(PLACEHOLDER_SCALAR) if undeclared_placeholder?(sdl, declared)
 
     render(
       'Types the manipulation phase generates (Connection/Paginator types, whereConditions inputs, ...).',
@@ -70,10 +118,19 @@ module Lighthouse::IdeHelper
     )
   end
 
-  # The manipulation phase replaces the `_` placeholder (`where: _ @whereConditions`),
-  # but the IDE reads the SDL as written, so it needs the placeholder declared.
-  def undeclared_placeholder?(sdl, original, generated)
-    sdl.to_s.match?(/:\s*\[?\s*_\b/) && original.exclude?('_') && generated.none? { |d| d.name == '_' }
+  # The types of the manipulated schema that neither the SDL nor the directives file defines.
+  def generated_types(sdl, declared, registry)
+    manipulated = Lighthouse::GraphQL::ASTBuilder.build(Lighthouse::GraphQL::SchemaGenerator.inject_directive_definitions(sdl), registry: registry)
+    parse(manipulated).definitions.select do |definition|
+      type_definition?(definition) && declared.exclude?(definition.name) && definition.name != '_'
+    end
+  end
+
+  # The manipulation phase replaces the `_` placeholder (`where: _ @whereConditions`,
+  # `orderBy: _ @orderBy`), but the IDE reads the SDL as written, so it needs
+  # the placeholder declared.
+  def undeclared_placeholder?(sdl, declared)
+    sdl.to_s.match?(/:\s*\[?\s*_\b/) && declared.exclude?('_')
   end
 
   def type_names(sdl)

data/lib/lighthouse/namespaces.rb

@@ -8,6 +8,7 @@ module Lighthouse
   module Contracts; end
   module Events; end
   module Generators; end
+  module OrderBy; end
   module Support; end
   module WhereConditions; end
 

data/lib/lighthouse/order_by/types.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# The types @orderBy generates for an argument written with the `_`
+# placeholder, as PHP Lighthouse's OrderByDirective and OrderByServiceProvider
+# define them. For Query.posts(orderBy:), the prefix is QueryPostsOrderBy:
+#
+#   no columns:/columnsEnum:/relations:  [OrderByClause!]           column: String!, order: SortOrder!
+#   columns: / columnsEnum:              [<Prefix>OrderByClause!]   column: <Prefix>Column! (or the columnsEnum)
+#   relations:                           [<Prefix>RelationOrderByClause!]
+#     column: <Prefix>Column (or String), order: SortOrder!, and per relation
+#     <relation>: <Prefix><Relation> { aggregate: COUNT } or, with the relation's
+#     own columns:, { aggregate: AVG|MIN|MAX|SUM|COUNT, column: <Prefix><Relation>Column }
+class Lighthouse::OrderBy::Types
+  GeneratedTypes = Lighthouse::GraphQL::Directives::GeneratedTypes
+
+  DEFAULT_CLAUSE = 'OrderByClause'
+  SORT_ORDER = 'SortOrder'
+  AGGREGATE = 'OrderByRelationAggregateFunction'
+  AGGREGATE_WITH_COLUMN = 'OrderByRelationWithColumnAggregateFunction'
+
+  SDL = {
+    SORT_ORDER => <<~GRAPHQL,
+      "Directions for ordering a list of records."
+      enum SortOrder {
+        "Sort records in ascending order."
+        ASC
+
+        "Sort records in descending order."
+        DESC
+      }
+    GRAPHQL
+    AGGREGATE => <<~GRAPHQL,
+      "Aggregate functions when ordering by a relation without specifying a column."
+      enum OrderByRelationAggregateFunction {
+        "Amount of items."
+        COUNT @enum(value: "count")
+      }
+    GRAPHQL
+    AGGREGATE_WITH_COLUMN => <<~GRAPHQL
+      "Aggregate functions when ordering by a relation that may specify a column."
+      enum OrderByRelationWithColumnAggregateFunction {
+        "Average."
+        AVG @enum(value: "avg")
+
+        "Minimum."
+        MIN @enum(value: "min")
+
+        "Maximum."
+        MAX @enum(value: "max")
+
+        "Sum."
+        SUM @enum(value: "sum")
+
+        "Amount of items."
+        COUNT @enum(value: "count")
+      }
+    GRAPHQL
+  }.freeze
+
+  def initialize(document_ast, directive, arg, field, type)
+    @document_ast = document_ast
+    @directive = directive
+    @relations = Array(GeneratedTypes.directive_value(directive, 'relations')).map { |relation| relation.transform_keys(&:to_s) }
+    @arg = arg
+    @path = "#{type.name}.#{field.name}.#{arg.name}"
+    @prefix = GeneratedTypes.qualified_arg_type(arg, field, type)
+    @columns_enum = -> { GeneratedTypes.columns_enum(document_ast, directive, arg, field, type) }
+  end
+
+  # The argument, typed with the clauses generated for it.
+  def argument
+    @document_ast.define_type(SORT_ORDER, SDL[SORT_ORDER])
+    arg = GeneratedTypes.describe(@arg, "Order by clause for #{@path}.")
+    allowed = GeneratedTypes.allowed_columns?(@directive)
+    column_type = allowed ? @columns_enum.call : 'String'
+
+    clause =
+      if @relations.any? then relation_clause(column_type)
+      elsif allowed then column_clause("#{@prefix}OrderByClause", column_type, "Order by clause for #{@path}.")
+      else column_clause(DEFAULT_CLAUSE, 'String', 'Allows ordering a list of records.')
+      end
+    GeneratedTypes.replace_placeholder(arg, "[#{clause}!]")
+  end
+
+  private
+
+  def column_clause(name, column_type, description)
+    define(name, description, ["column: #{column_type}!", 'The column that is used for ordering.'], order_field)
+  end
+
+  # A column, or one relation's aggregate.
+  def relation_clause(column_type)
+    aggregates = @relations.map { |relation| ["#{relation['relation']}: #{aggregate_input(relation)}", 'Aggregate specification.'] }
+    define("#{@prefix}RelationOrderByClause", "Order by clause for #{@path}.",
+           ["column: #{column_type}", 'The column that is used for ordering.'], order_field, *aggregates)
+  end
+
+  # COUNT, or, with the relation's `columns:` / `columnsEnum:`, an aggregate of one of its columns.
+  def aggregate_input(relation)
+    name = "#{@prefix}#{GeneratedTypes.studly(relation['relation'])}"
+    columns_enum = relation_columns_enum(relation, name)
+    aggregate = columns_enum ? AGGREGATE_WITH_COLUMN : AGGREGATE
+    @document_ast.define_type(aggregate, SDL[aggregate])
+
+    fields = if columns_enum
+               [["aggregate: #{aggregate}!", 'The aggregate function to apply to the column.'],
+                ["column: #{columns_enum}", 'Name of the column to use.']]
+             else
+               [["aggregate: #{aggregate}!", 'Always COUNT.']]
+             end
+    define(name, "Aggregate specification for #{@path}.#{relation['relation']}.", *fields)
+  end
+
+  def relation_columns_enum(relation, name)
+    if relation['columns'] && relation['columnsEnum']
+      raise Lighthouse::DefinitionError,
+            "The relation #{relation['relation']} of @orderBy on #{@path} can only have one of the following arguments: `columns`, `columnsEnum`."
+    end
+    return relation['columnsEnum'] if relation['columnsEnum']
+    return nil unless relation['columns']
+
+    GeneratedTypes.define_columns_enum(@document_ast, "#{name}Column", relation['columns'], "#{@path}.#{relation['relation']}")
+    "#{name}Column"
+  end
+
+  def order_field
+    ["order: #{SORT_ORDER}!", 'The direction that is used for ordering.']
+  end
+
+  # Defines the input `name` with `fields`, each [SDL, description]; returns its name.
+  def define(name, description, *fields)
+    @document_ast.define_type(name) do
+      %("#{description}"\ninput #{name} {\n#{fields.map { |sdl, doc| %(  "#{doc}"\n  #{sdl}) }.join("\n\n")}\n}\n)
+    end
+    name
+  end
+end

data/lib/lighthouse/railtie.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # Hooks Lighthouse into a Rails host: exposes the `lighthouse:*` rake tasks,
-# and — with `config.watch_sdl` — reloads the app when a .graphql file changes.
+# with `config.watch_sdl` reloads the app when a .graphql file changes, and
+# with `config.ide_helper` (on in development when the app has a
+# graphql.config.yml) rewrites the IDE helper files on boot and every reload.
 # Generators (`rails g lighthouse:install`) are found through lib/generators.
 class Lighthouse::Railtie < Rails::Railtie
   rake_tasks do
@@ -14,10 +16,15 @@ class Lighthouse::Railtie < Rails::Railtie
     Lighthouse::Railtie.watch_sdl(app.config)
   end
 
+  initializer 'lighthouse.ide_helper', after: :load_config_initializers do |app|
+    app.reloader.to_prepare { Lighthouse::IdeHelper.refresh(output_dir: app.root) }
+  end
+
   # Rails' reloader then treats a .graphql edit like a Ruby one: the app's
   # constants — the schema among them — are reloaded on the next request.
+  # Every .graphql under the entrypoint's folder is watched, imported or not.
   def self.watch_sdl(config)
-    folder = Lighthouse::Config.sdl_folder
+    folder = Lighthouse::Config.schema_directory
     return false unless Lighthouse::Config.watch_sdl && folder
 
     config.watchable_dirs[folder.to_s] = %w[graphql graphqls]