lighthouse-graphql 0.6.0 → 0.7.1

data/docs/schema-organisation.md

@@ -0,0 +1,177 @@
+# Schema Organisation
+
+Lighthouse reads your schema from a single entrypoint, `graphql/schema.graphql`
+by default (`config.schema_path`), as PHP Lighthouse does. As the schema grows,
+you split it across files, and the entrypoint imports them.
+
+## Schema imports
+
+```
+graphql/
+|-- schema.graphql
+|-- user.graphql
+```
+
+An import starts with `#import`, followed by the path of the imported file,
+relative to the file the import is in:
+
+```graphql
+type Query {
+  user: User
+}
+
+#import user.graphql
+```
+
+The contents of `user.graphql` are pasted in where the import is:
+
+```graphql
+type Query {
+  user: User
+}
+
+type User {
+  name: String!
+}
+```
+
+An imported file can import others. A file is read once, so importing it twice,
+or importing a file that imports it back, adds nothing more.
+
+Only the entrypoint and the files it imports make up the schema. A `.graphql`
+file in the folder that nothing imports is not part of it. A missing import
+fails the build: "Did not find GraphQL schema import at …".
+
+### Wildcard imports
+
+```
+graphql/
+|-- schema.graphql
+|-- blog/
+    |-- post.graphql
+    |-- category.graphql
+```
+
+To import every file in `blog/` at once, use a glob (Ruby's `Dir.glob`), which
+imports the files in name order:
+
+```graphql
+#import blog/*.graphql
+```
+
+`#import **/*.graphql` imports every file below the entrypoint's folder.
+
+## Type extensions
+
+A type is defined once. Defining it twice is an error that points at
+`extend`. This applies even across files:
+
+```
+Duplicate definition Query found when parsing the schema. Define a type once and add to it from other files with `extend type Query`.
+```
+
+PHP Lighthouse keeps the last definition and drops the earlier one without a
+word. Lighthouse here makes that an error, so a type's fields are never lost.
+
+Say `Post` is defined in `post.graphql`:
+
+```graphql
+type Post {
+  title: String
+  author: User @belongsTo
+}
+```
+
+and `schema.graphql` imports it:
+
+```graphql
+#import post.graphql
+```
+
+To add the queries that fetch posts, you could add them to the `Query` type in
+`schema.graphql`. It is usually better to keep queries next to the type they
+return. Make sure `schema.graphql` defines `Query`, even with no fields:
+
+```graphql
+type Query
+```
+
+Then extend `Query` in `post.graphql`:
+
+```graphql
+type Post {
+  title: String
+  author: User @belongsTo
+}
+
+extend type Query {
+  posts: [Post!]! @paginate
+}
+```
+
+The fields of the `extend type` are merged into the type's definition, and the
+directives on them work as on any field. Besides object types, you can extend
+`input`, `interface`, `enum`, `union` and `scalar` types:
+
+```graphql
+extend input PostFilter { authorId: ID @eq(key: "author_id") }
+extend enum Role { EDITOR }
+extend union SearchResult = Comment
+```
+
+The final schema always has one type per name. An extension of a type that is
+not defined is an error, and so is an extension that redefines a field:
+
+```
+Could not find a base definition User of kind ObjectTypeExtension to extend.
+Duplicate definition title found when merging.
+```
+
+The root types `Query`, `Mutation` and `Subscription` are the exception: an
+`extend type Mutation` with no `type Mutation` anywhere defines it.
+
+## How the schema is built
+
+The build runs these phases in order, as PHP Lighthouse's `ASTBuilder` does:
+
+1. The entrypoint and its imports are read (`Lighthouse::GraphQL::SchemaStitcher`),
+   along with what `BuildSchemaString` listeners add
+   ([events.md](events.md)).
+2. Every type is defined once (`Lighthouse::GraphQL::DocumentAST`).
+3. Type extensions are merged into their types.
+4. Type and field manipulators run: `@hide`/`@show`, `@model`, `@paginate`
+   and the relation directives' `type:`, `@softDeletes`, `@node`.
+5. Argument manipulators run: `@whereConditions`, `@whereHasConditions` and
+   `@orderBy` replace the `_` placeholder with the types they generate
+   ([filtering-and-ordering.md](filtering-and-ordering.md)). An argument still
+   typed `_` after this phase is an error.
+6. `ManipulateAST` listeners see the document.
+
+## IDE support
+
+An IDE reads the `.graphql` files as they are written, so it does not know
+Lighthouse's directives, the types the build generates, or the `_` placeholder.
+Lighthouse writes two files that declare them:
+
+- `schema-directives.graphql`: every directive the schema uses and does not declare.
+- `programmatic-types.graphql`: the generated types (paginators, the `@orderBy`
+  and `@whereConditions` inputs, ...) and `scalar _`.
+
+`graphql.config.yml` (written by `lighthouse:install`) points the GraphQL
+plugins of VS Code and JetBrains IDEs at them, next to every `.graphql` file:
+
+```yaml
+schema:
+  - graphql/**/*.graphql
+  - schema-directives.graphql
+  - programmatic-types.graphql
+```
+
+In development, Lighthouse rewrites both files on boot and on every reload when
+the app has a `graphql.config.yml` (`config.ide_helper`). Elsewhere, run
+`bin/rails lighthouse:ide_helper`. No type is in two of the three sources, because
+graphql-js, which the IDE plugins build the schema with, rejects a type defined
+twice.
+
+The IDE sees the files as one schema, imports or not. Without the generated
+files it reports `Unknown type "_"` and unknown directives.

data/lib/generators/lighthouse/install/graphql_ruby_install.rb

@@ -26,6 +26,10 @@ module Lighthouse::Generators::GraphqlRubyInstall
   # The example field graphql-ruby's install puts in each root type.
   TEST_FIELD = /\n+[ \t]*# TODO: remove me\n[ \t]*field :test_field,.*?\n[ \t]*def test_field\n.*?\n[ \t]*end\n/m
 
+  # The `node` and `nodes` fields graphql-ruby's install (--relay, its default)
+  # puts in Types::QueryType, without the methods that resolve them.
+  RELAY_FIELDS = /^[ \t]*field :nodes?, \[?Types::NodeType\b.*? do\n(?:[ \t]*argument .*\n)*[ \t]*end\n\n?/
+
   # The `resolve_type` stub graphql-ruby's install puts in the schema class.
   RESOLVE_TYPE_STUB = /
     \n+[ \t]*\#\ Union\ and\ Interface\ Resolution\n
@@ -98,6 +102,16 @@ module Lighthouse::Generators::GraphqlRubyInstall
     options[:subscriptions] || exist?(File.join(directory, 'subscriptions', 'base_subscription.rb'))
   end
 
+  # Did graphql-ruby's install write Relay's side (--relay, its default):
+  # Types::NodeType, and Types::QueryType's node and nodes, as it writes them?
+  def relay?
+    query_type = types_path('query_type.rb')
+    return false unless exist?(types_path('node_type.rb')) && exist?(query_type)
+
+    source = read(query_type)
+    source.scan(RELAY_FIELDS).size == 2 && source.include?('def node(id:)') && source.include?('def nodes(ids:)')
+  end
+
   def graphql_ruby_controller?(source)
     source.include?('def prepare_variables(variables_param)') && source.include?('def handle_error_in_development(e)') &&
       source.include?("#{schema_name}.execute(query, variables: variables, context: context, operation_name: operation_name)")

data/lib/generators/lighthouse/install/install_generator.rb

@@ -21,6 +21,9 @@ require_relative 'graphql_ruby_install'
 #   graphql-ruby's and stays, but the `resolve_type` stub (Lighthouse resolves
 #   types) and the root types it is built on;
 # - the example `test_field` goes from the root types;
+# - with Relay, the starter SDL declares Query.node and nodes (and a User
+#   @node with global ids), so their `field`s go from Types::QueryType, whose
+#   #node / #nodes methods resolve the SDL's fields;
 # - graphql-ruby's base object, interface, union and scalar include
 #   Lighthouse::GraphQL::Type, so every type class (Types::QueryType,
 #   Types::NodeType, what `graphql:object` writes) is Lighthouse's;
@@ -44,8 +47,8 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
 
   class_option :schema, type: :string,
                         desc: "The schema class to adopt; for graphql:install, when it runs, its name (default: graphql-ruby's)"
-  class_option :sdl_folder, type: :string, default: 'graphql',
-                            desc: 'Folder, relative to the app root, holding the *.graphql files'
+  class_option :schema_path, type: :string, default: 'graphql/schema.graphql',
+                             desc: "The schema's entrypoint, relative to the app root; it #imports the other .graphql files"
   class_option :subscriptions, type: :boolean, default: false,
                                desc: 'Add Subscriptions::BaseSubscription, the base of the classes Subscription fields resolve to'
   class_option :skip_controller, type: :boolean, default: false,
@@ -71,12 +74,13 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
   end
 
   def create_starter_schema
-    if Dir[File.join(destination_root, sdl_folder, '**', '*.graphql')].any?
-      say_status :skip, "#{sdl_folder}/ already has .graphql files", :yellow
+    if File.exist?(File.join(destination_root, sdl_schema_path))
+      say_status :skip, "#{sdl_schema_path} exists", :yellow
       return
     end
 
-    template 'schema.graphql.tt', File.join(sdl_folder, 'schema.graphql')
+    @relay_starter = relay?
+    template 'schema.graphql.tt', sdl_schema_path
   end
 
   # Subscriptions::BaseSubscription, which graphql-ruby has none of (see BaseClasses).
@@ -101,12 +105,15 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     add_dataloader if source.include?('use GraphQL::Batch') && source.exclude?('use GraphQL::Dataloader')
   end
 
-  # The example field goes; the root types' own fields stay.
+  # The example field goes; the root types' own fields stay. With Relay, the
+  # starter SDL declares Query.node and nodes, so their `field`s go too, and
+  # the methods graphql-ruby wrote resolve the SDL's fields.
   def adapt_root_types
     %w[query_type mutation_type subscription_type].each do |name|
       path = types_path("#{name}.rb")
       gsub_file path, TEST_FIELD, "\n" if exist?(path) && read(path).match?(TEST_FIELD)
     end
+    move_relay_fields_to_sdl if @relay_starter
   end
 
   # Every type class is Lighthouse's: graphql-ruby's base object, interface,
@@ -174,14 +181,14 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     say <<~MSG
 
       Lighthouse is installed on graphql-ruby's install (#{schema_path}). Next steps:
-        1. Describe your API in #{sdl_folder}/*.graphql (the starter schema assumes a User model).
+        1. Describe your API in #{sdl_schema_path} (the starter assumes a User model); #import more files, which `extend type Query`.
         2. Resolve a field in Ruby when a directive is not enough, as in graphql-ruby: a method of
            Types::QueryType (Query.latestPosts -> #latest_posts), a `field` of its own there,
            `bin/rails g graphql:mutation`, or a Resolvers::BaseResolver subclass named after the field.
         3. Give a type Ruby methods, a union or interface its resolve_type, a scalar its coercion:
            bin/rails g graphql:object Post (or graphql:union, graphql:interface, graphql:scalar);
            the class is Lighthouse's through its base (Lighthouse::GraphQL::Type)
-        4. Generate the IDE helper files:  bin/rails lighthouse:ide_helper
+        4. The IDE helper files are rewritten in development; or:  bin/rails lighthouse:ide_helper
         5. #{serve}
     MSG
   end
@@ -196,7 +203,7 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
 
   def schema_comment(indent)
     <<~RUBY.gsub(/^/, indent).delete_prefix(indent)
-      # Lighthouse builds the schema from the SDL in #{sdl_folder}/, on the classes graphql-ruby's
+      # Lighthouse builds the schema from the SDL in #{sdl_schema_path}, on the classes graphql-ruby's
       # install wrote (base_types): the SDL's root types extend the code-first ones, whose
       # `field`s stay the schema's, and every type, resolver and mutation class inherits from
       # its kind's base. The rest of the class is graphql-ruby's.
@@ -210,12 +217,24 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
                                   "#{indent}use GraphQL::Dataloader\n", after: anchor
   end
 
+  # The SDL's entrypoint (Config.schema_path); `schema_path` is graphql-ruby's schema class.
+  def sdl_schema_path
+    options[:schema_path].delete_prefix('/')
+  end
+
   def sdl_folder
-    options[:sdl_folder].delete_suffix('/')
+    File.dirname(sdl_schema_path)
+  end
+
+  def default_sdl_schema_path?
+    sdl_schema_path == 'graphql/schema.graphql'
   end
 
-  def default_sdl_folder?
-    sdl_folder == 'graphql'
+  def move_relay_fields_to_sdl
+    path = types_path('query_type.rb')
+    gsub_file path, RELAY_FIELDS, ''
+    gsub_file path, /^([ \t]*)def node\(id:\)\n/,
+              "\\1# Query.node and nodes are declared in #{sdl_schema_path}; these methods resolve them.\n\\1def node(id:)\n"
   end
 
   def ide_helper_files

data/lib/generators/lighthouse/install/templates/graphql.config.yml.tt

@@ -1,6 +1,7 @@
 # graphql-config, read by the GraphQL plugins for JetBrains IDEs and VS Code.
 # The two generated files describe Lighthouse's directives and the types it
-# generates; refresh them after changing the schema:
+# generates. In development they are rewritten on boot and on every reload
+# (config.ide_helper); elsewhere, refresh them with:
 #   bin/rails lighthouse:ide_helper
 schema:
   - <%= sdl_folder %>/**/*.graphql

data/lib/generators/lighthouse/install/templates/initializer.rb.tt

@@ -3,11 +3,13 @@
 # Lighthouse configuration. Every option is optional; the defaults are shown.
 # Reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/configuration.md
 Lighthouse.configure do |config|
-  # Folder the *.graphql schema files are loaded from.
-<% if default_sdl_folder? -%>
-  # config.sdl_folder = Rails.root.join('graphql').to_s
+  # The schema's entrypoint. It imports the other .graphql files
+  # (#import user.graphql, #import blog/*.graphql), which add to a type
+  # defined elsewhere with `extend type`.
+<% if default_sdl_schema_path? -%>
+  # config.schema_path = Rails.root.join('graphql/schema.graphql').to_s
 <% else -%>
-  config.sdl_folder = Rails.root.join('<%= sdl_folder %>').to_s
+  config.schema_path = Rails.root.join('<%= sdl_schema_path %>').to_s
 <% end -%>
 
   # Where classes named by the schema are looked up, by kind. A Query or Mutation
@@ -58,6 +60,11 @@ Lighthouse.configure do |config|
   # Reload the app (and so the schema) when a .graphql file changes.
   # config.watch_sdl = Rails.env.development?
 
+  # Rewrite schema-directives.graphql and programmatic-types.graphql, which your
+  # IDE reads through graphql.config.yml, on boot and on every reload. nil: in
+  # development, when the app has a graphql.config.yml.
+  # config.ide_helper = nil
+
   # Automatic Persisted Queries (Apollo's protocol). Add a GET route too, so
   # hashed queries can be cached by CDNs: get "/graphql", to: "graphql#execute"
   # config.persisted_queries = true

data/lib/generators/lighthouse/install/templates/schema.graphql.tt

@@ -1,15 +1,44 @@
 # Starter schema generated by `rails generate lighthouse:install`. It assumes a
 # User model with `name` and `email` columns — replace it with your own types.
+# This file is the schema's entrypoint: split the schema into files it imports
+# (#import user.graphql), which add their fields with `extend type Query`.
 # Directives reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/directives.md
 
 "Indicates what fields are available at the top level of a query operation."
 type Query {
+<% if relay? -%>
+  "Fetches an object given its ID. Resolved by Types::QueryType#node, with <%= schema_name %>.object_from_id."
+  node("ID of the object." id: ID!): Node
+
+  "Fetches a list of objects given a list of IDs. Resolved by Types::QueryType#nodes."
+  nodes("IDs of the objects." ids: [ID!]!): [Node]
+
+  "Find a single user by its global id."
+  user(id: ID! @globalId(decode: ID) @eq): User @find
+<% else -%>
   "Find a single user by id."
   user(id: ID! @eq): User @find
+<% end -%>
 
   "List users, a page at a time (10 by default; pass first: and page:)."
   users: [User!]! @paginate(defaultCount: 10)
 }
+<% if relay? -%>
+
+"An object with an ID: graphql-ruby's Types::NodeType."
+interface Node {
+  "ID of the object."
+  id: ID!
+}
+
+"Account of a person who uses this application. @node makes it a Node, which Query.node finds."
+type User @node {
+  "Its global id, from <%= schema_name %>.id_from_object (Rails' GlobalID)."
+  id: ID! @globalId
+  name: String
+  email: String
+}
+<% else -%>
 
 "Account of a person who uses this application."
 type User {
@@ -17,3 +46,4 @@ type User {
   name: String
   email: String
 }
+<% end -%>

data/lib/lighthouse/ast_builder.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# The manipulation phase, as PHP Lighthouse's ASTBuilder runs it on the
+# stitched schema:
+#
+# 1. DocumentAST.from_source: every type defined once.
+# 2. Type extensions merged into the types they extend. An extension of a
+#    root type that has no definition (`extend type Query` alone) defines it.
+# 3. The type and field manipulators: @hide/@show, @model, @paginate (and the
+#    relation directives' `type:`), @softDeletes, @node.
+# 4. The argument manipulators: each argument directive whose class includes
+#    Contracts::ArgManipulator rewrites its argument (@whereConditions,
+#    @whereHasConditions, @orderBy turn `_` into the input types they generate).
+# 5. The definitions of directives the generated types use (`@enum`).
+#
+# Returns the manipulated SDL; ManipulateAST listeners then see its document.
+module Lighthouse::GraphQL::ASTBuilder
+  Nodes = ::GraphQL::Language::Nodes
+
+  EXTENSION_TO_DEFINITION = {
+    Nodes::ObjectTypeExtension => Nodes::ObjectTypeDefinition,
+    Nodes::InterfaceTypeExtension => Nodes::InterfaceTypeDefinition,
+    Nodes::InputObjectTypeExtension => Nodes::InputObjectTypeDefinition,
+    Nodes::EnumTypeExtension => Nodes::EnumTypeDefinition,
+    Nodes::UnionTypeExtension => Nodes::UnionTypeDefinition,
+    Nodes::ScalarTypeExtension => Nodes::ScalarTypeDefinition
+  }.freeze
+
+  # What each extension adds to its definition, besides directives.
+  MERGED_LISTS = {
+    Nodes::ObjectTypeExtension => %i[fields interfaces],
+    Nodes::InterfaceTypeExtension => %i[fields interfaces],
+    Nodes::InputObjectTypeExtension => %i[fields],
+    Nodes::EnumTypeExtension => %i[values],
+    Nodes::UnionTypeExtension => %i[types],
+    Nodes::ScalarTypeExtension => []
+  }.freeze
+
+  ROOT_TYPES = %w[Query Mutation Subscription].freeze
+
+  OBJECT_LIKE = [Nodes::ObjectTypeDefinition, Nodes::InterfaceTypeDefinition].freeze
+
+  module_function
+
+  def build(sdl, registry: Lighthouse::DirectiveRegistry.default)
+    document_ast = Lighthouse::GraphQL::DocumentAST.from_source(sdl)
+    extend_types(document_ast)
+
+    document_ast = Lighthouse::GraphQL::DocumentAST.from_source(registry.manipulate_sdl(document_ast.to_sdl))
+    apply_arg_manipulators(document_ast, registry)
+
+    Lighthouse::GraphQL::SchemaGenerator.inject_directive_definitions(document_ast.to_sdl)
+  end
+
+  def extend_types(document_ast)
+    document_ast.type_extensions.each do |name, extensions|
+      extensions.each { |extension| extend_type(document_ast, name, extension) }
+    end
+    document_ast.type_extensions.clear
+  end
+
+  def extend_type(document_ast, name, extension)
+    definition = document_ast.types[name] || root_type(document_ast, name, extension)
+    unless definition.is_a?(EXTENSION_TO_DEFINITION.fetch(extension.class))
+      raise Lighthouse::DefinitionError,
+            "The type extension #{name} of kind #{kind(extension)} can not extend a definition of kind #{kind(definition)}."
+    end
+
+    merged = MERGED_LISTS.fetch(extension.class).index_with { |list| merge_unique(definition.public_send(list), extension.public_send(list)) }
+    document_ast.put_type(definition.merge(directives: definition.directives + extension.directives, **merged))
+  end
+
+  # `extend type Query` with no `type Query` anywhere defines it, as in PHP Lighthouse.
+  def root_type(document_ast, name, extension)
+    unless ROOT_TYPES.include?(name) && extension.is_a?(Nodes::ObjectTypeExtension)
+      raise Lighthouse::DefinitionError, "Could not find a base definition #{name} of kind #{kind(extension)} to extend."
+    end
+
+    Nodes::ObjectTypeDefinition.new(name: name, fields: [], interfaces: [], directives: []).tap { |root| document_ast.put_type(root) }
+  end
+
+  # The definition's nodes followed by the extension's; a name in both is an error.
+  def merge_unique(original, addition)
+    names = addition.to_set(&:name)
+    duplicate = original.find { |node| names.include?(node.name) }
+    raise Lighthouse::DefinitionError, "Duplicate definition #{duplicate.name} found when merging." if duplicate
+
+    original + addition
+  end
+
+  def kind(node)
+    node.class.name.demodulize
+  end
+
+  # Every argument of every object and interface field, through the
+  # manipulators of the directives it carries, in their SDL order.
+  def apply_arg_manipulators(document_ast, registry)
+    document_ast.type_names.each do |name|
+      type = document_ast.types[name]
+      next unless OBJECT_LIKE.any? { |kind| type.is_a?(kind) }
+
+      fields = type.fields.map do |field|
+        field.merge(arguments: field.arguments.map { |arg| manipulate_argument(document_ast, registry, arg, field, type) })
+      end
+      document_ast.put_type(type.merge(fields: fields))
+    end
+  end
+
+  def manipulate_argument(document_ast, registry, arg, field, type)
+    manipulated = arg.directives.reduce(arg) do |current, directive|
+      manipulator = registry.arg_manipulator_class(directive.name)
+      manipulator ? manipulator.new(current, directive).manipulate_arg_definition(document_ast, field, type) : current
+    end
+    return manipulated unless placeholder?(manipulated.type)
+
+    raise Lighthouse::DefinitionError,
+          "#{type.name}.#{field.name}(#{arg.name}:) has the placeholder type `_`, which only a directive that generates " \
+          'its type replaces: @whereConditions, @whereHasConditions or @orderBy.'
+  end
+
+  def placeholder?(type)
+    Lighthouse::GraphQL::Directives::GeneratedTypes.placeholder?(type)
+  end
+end

data/lib/lighthouse/config.rb

@@ -24,7 +24,7 @@ module Lighthouse
 
     # Every setting reset! forgets, so the next read falls back to its default.
     SETTINGS = %i[
-      sdl_folder resolver_namespaces namespaces transactional_mutations pagination_default_count pagination_max_count
+      schema_path ide_helper resolver_namespaces namespaces transactional_mutations pagination_default_count pagination_max_count
       schema_cache schema_cache_path watch_sdl persisted_queries persisted_queries_store persisted_queries_ttl
       persisted_queries_manifest persisted_queries_only on_error directive_map authenticated_user policy_user authorizer
       feature_checker feature_actor
@@ -35,13 +35,32 @@ module Lighthouse
     ].freeze
 
     class << self
-      attr_writer :sdl_folder, :resolver_namespaces, :on_error, :authenticated_user, :policy_user, :authorizer,
+      attr_writer :schema_path, :ide_helper, :resolver_namespaces, :on_error, :authenticated_user, :policy_user, :authorizer,
                   :transactional_mutations, :schema_cache, :watch_sdl, :persisted_queries, :persisted_queries_store, :persisted_queries_only,
                   :queue_broadcasts,
                   :convert_empty_strings_to_null, :feature_checker, :feature_actor, :global_id
 
-      def sdl_folder
-        @sdl_folder ||= (defined?(Rails) && Rails.respond_to?(:root) ? Rails.root.join('graphql').to_s : nil)
+      # The schema's entrypoint, as PHP Lighthouse's `schema_path`: the one file
+      # the schema is read from, importing the others (`#import user.graphql`,
+      # `#import blog/*.graphql`; see SchemaStitcher). RAILS_ROOT/graphql/schema.graphql
+      # by default.
+      def schema_path
+        @schema_path ||= (::Rails.root.join('graphql/schema.graphql').to_s if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root)
+      end
+
+      # The folder of the schema's entrypoint, which watch_sdl watches.
+      def schema_directory
+        schema_path && File.dirname(schema_path.to_s)
+      end
+
+      # Rewrite the IDE helper files (schema-directives.graphql,
+      # programmatic-types.graphql) on boot and on every reload. nil (the
+      # default): in development, when the app has a graphql.config.yml.
+      def ide_helper
+        return @ide_helper unless @ide_helper.nil?
+
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.development? && ::Rails.root &&
+          File.exist?(::Rails.root.join('graphql.config.yml'))
       end
 
       def directive_map = @directive_map ||= {}

data/lib/lighthouse/contracts/arg_manipulator.rb

@@ -2,12 +2,16 @@
 
 require_relative 'directive'
 
-# A directive on a field ARGUMENT that mutates the schema AST before build,
-# e.g. @whereConditions / @whereHasConditions generating input/enum types and
-# swapping the `_` placeholder argument type.
+# A directive on a field ARGUMENT that rewrites the schema before it is built,
+# as PHP Lighthouse's ArgManipulator: @whereConditions, @whereHasConditions and
+# @orderBy generate the input types of an argument written with the `_`
+# placeholder, and type it with them.
 #
-# Implementors provide (at the class level)
-# `manipulate_argument_definition(manipulation_context, parent, field, arg, directive)`.
+# Implementors, built with (arg_node, directive_node), provide
+# `#manipulate_arg_definition(document_ast, field_node, type_node)` returning
+# the argument node (graphql-ruby's nodes are immutable: `arg.merge(type: ...)`).
+# New types go in the Lighthouse::GraphQL::DocumentAST (`define_type`).
+# ASTBuilder calls it for every argument of an object or interface field.
 module Lighthouse::Contracts::ArgManipulator
   include Lighthouse::Contracts::Directive
 end

data/lib/lighthouse/contracts/field_builder.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+# A directive on a FIELD that constrains the query of the field's resolver
+# whatever the client sends, e.g. @orderBy(column:, direction:) on a field.
+# Applied after the argument builders, as PHP Lighthouse's FieldBuilderDirective.
+#
+# Implementors, built with (field_node, directive_node), provide
+# `#handle_field_builder(relation)` returning a relation.
+module Lighthouse::Contracts::FieldBuilder
+  include Lighthouse::Contracts::Directive
+end

data/lib/lighthouse/directive_resolvers/aggregate_resolver.rb

@@ -25,13 +25,12 @@ class Lighthouse::GraphQL::DirectiveResolvers::AggregateDirectiveResolver < Ligh
     column_name = extract_directive_arg('column')
     function_name = extract_directive_arg('function')
     resolver_instance = self
-    field_ast_node = @field_def.ast_node
 
     install(target_type_class, lambda do |obj, args, ctx|
       relation = resolver_instance.send(:aggregate_source, obj, model_name, relation_name)
       return nil unless relation
 
-      relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args, ctx, resolver_instance)
+      relation = resolver_instance.apply_where_filters(relation, args, ctx)
       resolver_instance.send(:compute_aggregation, relation, column_name, function_name)
     end)
   end

data/lib/lighthouse/directive_resolvers/all_resolver.rb

@@ -25,8 +25,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::AllDirectiveResolver < Lighthouse
     args = arguments.respond_to?(:to_h) ? arguments.to_h : {}
     relation = apply_scopes(model_class.all)
 
-    relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, @field_def.ast_node, args, ctx, self)
-
     relation = apply_where_filters(relation, args, ctx)
     relation = relation.limit(args[:first]) if args[:first]
     relation = relation.offset(args[:offset]) if args[:offset]