lighthouse-graphql 0.5.0 → 0.7.0

data/docs/types.md

@@ -69,17 +69,15 @@ Most schemas need nothing else.
 
 When the default is not enough, say when the values are Hashes from a search
 service rather than records, write the union's class as graphql-ruby does
-(`rails g graphql:union SearchResult`),
-`Types::<Name>Type` including `Lighthouse::GraphQL::Type`, with `resolve_type`.
-It returns a type name, or a type class, which stands for the SDL type of its
-`graphql_name`:
+(`rails g graphql:union SearchResult`): `Types::<Name>Type`, with `resolve_type`.
+Its base, `Types::BaseUnion`, includes `Lighthouse::GraphQL::Type` after
+`lighthouse:install` (see [opting in](#opting-in-and-base-classes)). It returns a
+type name, or a type class, which stands for the SDL type of its `graphql_name`:
 
 ```ruby
 # app/graphql/types/search_result_type.rb
 module Types
   class SearchResultType < BaseUnion
-    include Lighthouse::GraphQL::Type
-
     def self.resolve_type(object, context)
       return unless object.is_a?(Hash)
 
@@ -96,7 +94,6 @@ An interface's goes in graphql-ruby's `definition_methods`:
 module Types
   module AuthoredType
     include BaseInterface
-    include Lighthouse::GraphQL::Type
 
     definition_methods do
       def resolve_type(object, context)
@@ -154,15 +151,14 @@ type Query {
 }
 ```
 
-Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`,
-`Types::<Name>Type` including `Lighthouse::GraphQL::Type`:
+Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`:
+`Types::<Name>Type`, a `Types::BaseScalar`, which includes `Lighthouse::GraphQL::Type`
+after `lighthouse:install`:
 
 ```ruby
 # app/graphql/types/date_time_type.rb
 module Types
   class DateTimeType < BaseScalar
-    include Lighthouse::GraphQL::Type
-
     def self.coerce_input(value, context)
       Time.iso8601(value.to_s)
     rescue ArgumentError
@@ -194,10 +190,12 @@ class with `coerce_input` and `coerce_result` fails when the schema is built.
 ## Opting in, and base classes
 
 Only a class including `Lighthouse::GraphQL::Type` counts: any other
-`Types::SearchResultType` or `Types::DateTimeType`, such as the ones a graphql-ruby
-app already has, is left alone. The concern can be included in a subclass of
-`GraphQL::Schema::Object`, `Union` or `Scalar`, or in a module including
-`GraphQL::Schema::Interface`.
+`Types::SearchResultType` or `Types::DateTimeType` is left alone. `lighthouse:install`
+includes the concern in graphql-ruby's `Types::BaseObject`, `BaseInterface`,
+`BaseUnion` and `BaseScalar`, so every type class inheriting from them counts. In an
+app that did not run it, include the concern by hand, in those bases or in each
+class: a subclass of `GraphQL::Schema::Object`, `Union` or `Scalar`, or a module
+including `GraphQL::Schema::Interface`.
 
 The classes are looked up in [`namespaces[:types]`](configuration.md#namespaces)
 (default `['Types']`). When the schema's `base_types` name a base for a kind,
@@ -205,15 +203,16 @@ graphql-ruby builds the SDL's types of that kind from it, and a type class of th
 kind must inherit from it, or the schema does not build:
 
 ```ruby
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
   options: {
     base_types: {
       object: Types::BaseObject,
       union: Types::BaseUnion,
       interface: Types::BaseInterface,
       scalar: Types::BaseScalar
-      # resolver:, mutation:, subscription: (resolvers.md#handing-the-bases-to-the-schema)
+      # query_type:, node:, resolver:, mutation:, ... (resolvers.md#handing-the-bases-to-the-schema)
     }
   }
 )
+end
 ```

data/docs/uploads.md

@@ -27,7 +27,9 @@ on `User`, the mutation above attaches it.
 
 ## `@upload`
 
-`@upload` stores the file first, and passes along what was stored instead:
+`@upload` stores the file first, and passes along what was stored instead, as PHP
+Lighthouse's `@upload` does on a Laravel disk. The file goes to your app's
+ActiveStorage, the way the rest of the app stores files:
 
 ```graphql
 type Mutation {
@@ -38,23 +40,42 @@ type Mutation {
 }
 ```
 
-By default the file becomes an ActiveStorage blob: on the service `disk:` names (the
-default service without it), with its key under `path:`. The argument then holds the
-blob's **signed id**, which an attachment attribute attaches (`user.avatar = signed_id`)
-and `ActiveStorage::Blob.find_signed` finds. Lists of files are stored one by one.
+| | PHP Lighthouse (Laravel) | lighthouse-graphql (ActiveStorage) |
+| --- | --- | --- |
+| `disk` | a disk of `config/filesystems.php`; `filesystems.default` without it | a service of `config/storage.yml`; `config.active_storage.service` without it |
+| `path` (`"/"`) | the directory the file is stored in | the directory the blob's key starts with (`avatars/<token>`); at `"/"`, ActiveStorage's own key |
+| `public` (`false`) | the file's visibility | must agree with the service's (see below) |
+| the argument holds | the stored path | the blob's **signed id** |
+
+The signed id is what an attachment attribute attaches (`user.avatar = signed_id`) and
+`ActiveStorage::Blob.find_signed` finds; the blob keeps the file's name and content
+type. Lists of files are stored one by one, and `null` stays `null`.
+
+ActiveStorage makes a whole service public (`public: true` in `config/storage.yml`)
+or private, never one file. So `public:` must agree with the service's, and the schema
+never says a file is private that anyone can read: `@upload(public: true)` on a private
+service fails, and so does `@upload` (`public: false`) on a public one. A service
+`config/storage.yml` does not declare fails too.
+
+To store files somewhere else (S3, GCS, Azure or a service of your own), declare an
+ActiveStorage service for it and name it with `disk:`, as a Laravel app declares a disk:
+
+```yaml
+# config/storage.yml
+avatars:
+  service: S3
+  bucket: my-app-avatars
+  region: us-east-1
+  public: true
+```
+
+```graphql
+updateAvatar(avatar: Upload! @upload(disk: "avatars", path: "users", public: true)): User!
+```
 
 `@upload` runs once `@guard`, the `@can*` family and `@validator` have let the call
 through, so a refused call stores nothing.
 
-To store files elsewhere, give [`upload_store`](configuration.md#upload_store) an
-object with `call(file, disk:, path:, public:)`; the argument holds what it returns:
-
-```ruby
-Lighthouse.configure do |config|
-  config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }   # returns the key
-end
-```
-
 ## The request
 
 ```shell
@@ -68,6 +89,12 @@ curl localhost:3000/graphql \
 A batch sends an array as `operations`, and maps files to `"0.variables.avatar"`,
 `"1.variables.files.0"`, and so on.
 
+A multipart request is also what an HTML form on another site can send. If the GraphQL
+controller authenticates with the session cookie, keep Rails' CSRF protection on it
+(`protect_from_forgery`, on by default in `ActionController::Base`) and have clients send
+the `X-CSRF-Token` header, as PHP Lighthouse has them send `X-Requested-With` for its
+`EnsureXHR` middleware. A controller that authenticates with a token header is not exposed.
+
 In a request spec:
 
 ```ruby

data/lib/generators/lighthouse/base_classes.rb

@@ -4,19 +4,18 @@ require 'rails/generators'
 require 'lighthouse-graphql'
 
 # The base class graphql-ruby's convention puts in each namespace, which the
-# classes Lighthouse generates inherit from: Resolvers::BaseResolver,
-# Mutations::BaseMutation and Subscriptions::BaseSubscription.
+# classes Lighthouse generates inherit from.
 #
-# graphql-ruby's `graphql:install` writes the first two (and every Types::Base*),
-# and `lighthouse:install` runs it: Lighthouse does not write copies of them. It
-# writes only the base graphql-ruby has none of, BaseSubscription, which
-# includes Lighthouse's subscription concern. A generator that finds a base
-# missing says how to get it.
+# graphql-ruby's `graphql:install` writes Resolvers::BaseResolver,
+# Mutations::BaseMutation and every Types::Base*, and `lighthouse:install`
+# builds on them: Lighthouse does not write copies of them. It writes only the
+# base graphql-ruby has none of, Subscriptions::BaseSubscription, which
+# includes Lighthouse's subscription concern.
 #
 # A base that already exists is never replaced, not even with --force: it holds
 # the app's own code.
 module Lighthouse::Generators::BaseClasses
-  NAMES = { queries: 'BaseResolver', mutations: 'BaseMutation', subscriptions: 'BaseSubscription' }.freeze
+  NAMES = { subscriptions: 'BaseSubscription' }.freeze
 
   # The bases Lighthouse writes itself, graphql-ruby having none.
   SOURCES = {
@@ -39,19 +38,15 @@ module Lighthouse::Generators::BaseClasses
     NAMES[kind]
   end
 
-  # Write the base class of `kind` into `namespace` when Lighthouse owns it and
-  # it is missing; say how to get one graphql-ruby owns.
+  # Write the base class of `kind` into `namespace` when it is missing.
   def write_base_class(kind, namespace)
     return unless base_class_name(kind)
 
     path = base_class_path(kind, namespace)
     if File.exist?(File.join(destination_root, path))
       say_status :skip, "#{path} already exists", :yellow
-    elsif SOURCES[kind]
-      create_file path, ruby_source(namespace.split('::'), SOURCES[kind])
     else
-      say_status :missing, "#{path}: graphql-ruby writes it — run `bin/rails g lighthouse:install` (which runs graphql:install), " \
-                           "or write #{namespace}::#{base_class_name(kind)} yourself", :red
+      create_file path, ruby_source(namespace.split('::'), SOURCES.fetch(kind))
     end
   end
 

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# What graphql-ruby's `graphql:install` wrote in an app, as lighthouse:install
+# reads it: where its schema class is (under app/, beside its types: --directory,
+# --schema), which of its classes exist (--relay, --skip-mutation-root-type), and
+# the parts of its templates Lighthouse takes out.
+module Lighthouse::Generators::GraphqlRubyInstall
+  # graphql-ruby's code-first root types and Node interface, by base_types key (RootTypes).
+  ROOT_TYPES = { query_type: 'QueryType', mutation_type: 'MutationType', subscription_type: 'SubscriptionType', node: 'NodeType' }.freeze
+
+  # graphql-ruby's base types, by base_types key.
+  TYPE_BASES = {
+    object: 'BaseObject', interface: 'BaseInterface', union: 'BaseUnion', scalar: 'BaseScalar',
+    enum: 'BaseEnum', input_object: 'BaseInputObject'
+  }.freeze
+
+  # Where Lighthouse::GraphQL::Type goes in graphql-ruby's base types: after the
+  # class line, or the interface's own include.
+  TYPE_CONCERN_ANCHORS = {
+    'base_object' => /^([ \t]*)class BaseObject < GraphQL::Schema::Object\n/,
+    'base_union' => /^([ \t]*)class BaseUnion < GraphQL::Schema::Union\n/,
+    'base_scalar' => /^([ \t]*)class BaseScalar < GraphQL::Schema::Scalar\n/,
+    'base_interface' => /^([ \t]*)include GraphQL::Schema::Interface\n/
+  }.freeze
+
+  # 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 `resolve_type` stub graphql-ruby's install puts in the schema class.
+  RESOLVE_TYPE_STUB = /
+    \n+[ \t]*\#\ Union\ and\ Interface\ Resolution\n
+    [ \t]*def\ self\.resolve_type\(.*?\)\n
+    (?:[ \t]*\#.*\n)*
+    [ \t]*raise\(GraphQL::RequiredImplementationMissingError\)\n
+    [ \t]*end\n
+  /x
+
+  private
+
+  # The file of graphql-ruby's schema class under app/ (--schema picks one by name), or nil.
+  def schema_path
+    @schema_path ||= Dir[File.join(destination_root, 'app', '**', '*.rb')].filter_map do |file|
+      name = schema_class_name(File.read(file))
+      file.delete_prefix("#{destination_root}/") if name && (options[:schema].nil? || name.demodulize == options[:schema].camelize)
+    end.first
+  end
+
+  def schema_class_name(source)
+    source[/^[ \t]*class (\S+) < (?:GraphQL::Schema|Lighthouse::GraphQL::RbLightHouse\.get_schema)\b/, 1] ||
+      source[/^[ \t]*(\S+) = Lighthouse::GraphQL::RbLightHouse\.get_schema\b/, 1]
+  end
+
+  def schema_name
+    schema_class_name(read(schema_path)).demodulize
+  end
+
+  def lighthouse?(source)
+    source.include?('Lighthouse::GraphQL::RbLightHouse.get_schema')
+  end
+
+  # graphql-ruby's install: its defaults, an API app's smaller stack, the name --schema gives.
+  def graphql_install_options
+    { schema: options[:schema], api: api_only? || nil }.compact
+  end
+
+  def api_only?
+    exist?('config/application.rb') && read('config/application.rb').match?(/^\s*config\.api_only\s*=\s*true/)
+  end
+
+  # graphql-ruby writes its types beside the schema class (--directory).
+  def directory
+    File.dirname(schema_path)
+  end
+
+  def types_path(file)
+    File.join(directory, 'types', file)
+  end
+
+  # Lighthouse's base_types: every class graphql-ruby's install wrote, found
+  # where it writes it, as [key, constant] pairs.
+  def base_types
+    @base_types ||= type_classes(ROOT_TYPES) + resolver_classes + type_classes(TYPE_BASES)
+  end
+
+  def type_classes(names)
+    names.filter_map { |key, name| [key, "Types::#{name}"] if exist?(types_path("#{name.underscore}.rb")) }
+  end
+
+  def resolver_classes
+    classes = { resolver: %w[resolvers BaseResolver], mutation: %w[mutations BaseMutation] }
+    classes[:subscription] = %w[subscriptions BaseSubscription] if subscription_base?
+    classes.filter_map do |key, (folder, name)|
+      [key, "#{folder.camelize}::#{name}"] if exist?(File.join(directory, folder, "#{name.underscore}.rb"))
+    end
+  end
+
+  def subscription_base?
+    options[:subscriptions] || exist?(File.join(directory, 'subscriptions', 'base_subscription.rb'))
+  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)")
+  end
+
+  def read(path)
+    File.read(File.join(destination_root, path))
+  end
+
+  def exist?(path)
+    File.exist?(File.join(destination_root, path))
+  end
+end

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

@@ -4,50 +4,66 @@ require 'rails/generators'
 require 'generators/graphql/install_generator'
 require 'lighthouse-graphql'
 require_relative '../base_classes'
+require_relative 'graphql_ruby_install'
 
-# `rails generate lighthouse:install` — sets a Rails app up for Lighthouse, on
-# top of graphql-ruby's own install, which it runs first (`graphql:install
-# --no-relay --skip-graphiql --skip-query-logs`, keeping the files the app has):
-# graphql-ruby writes the base classes every graphql-ruby app has (Types::Base*,
-# Resolvers::BaseResolver, Mutations::BaseMutation), its controller and route.
-# Lighthouse then puts its own over what graphql-ruby wrote in this run:
+# `rails generate lighthouse:install` — puts Lighthouse on top of graphql-ruby's
+# own install (`rails g graphql:install`, with whichever of its options the app
+# chose: --relay, --batch, --skip-mutation-root-type, --schema, --directory,
+# ...). When the app has none, it runs graphql:install first, with its
+# defaults. It then adapts what graphql-ruby wrote, instead of writing its own:
 #
-# - the schema class, built from the SDL (graphql-ruby's is code-first);
-# - the controller, with Lighthouse::GraphQL::Controller;
-# - no Types::QueryType / MutationType: the SDL declares the root types;
-# - Mutations::BaseMutation a GraphQL::Schema::Mutation, as the SDL declares a
-#   mutation's arguments (graphql-ruby's is a RelayClassicMutation, one `input:`);
+# - the schema class (`class AppSchema < GraphQL::Schema`) becomes Lighthouse's,
+#   built from the SDL on everything graphql-ruby wrote: its base types, base
+#   resolver and base mutation, and its code-first Types::QueryType /
+#   MutationType, which the SDL's root types extend, so their `field`s (Relay's
+#   `node` / `nodes`, what `graphql:mutation` adds) stay. Its Relay
+#   Types::NodeType is the SDL's Node. Everything else in the class is
+#   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;
+# - 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;
+# - with --batch, the schema uses GraphQL::Dataloader too, which Lighthouse's
+#   directives batch through;
+# - graphql-ruby's controller, as its install wrote it, becomes one with
+#   Lighthouse::GraphQL::Controller.
 #
-# and adds the initializer, a starter SDL file, Subscriptions::BaseSubscription
-# and the graphql-config file IDEs read. Rerunning it skips what is in place. A
-# schema class or controller the app had before is kept (pass --force to replace
-# it), so an app already serving a graphql-ruby schema keeps doing so until it
-# is pointed at ours.
+# It adds the initializer, a starter SDL file and the graphql-config file IDEs
+# read, and with --subscriptions, Subscriptions::BaseSubscription. Rerunning it
+# skips what is in place.
 class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
   include Lighthouse::Generators::BaseClasses
+  include Lighthouse::Generators::GraphqlRubyInstall
 
   CONTROLLER = 'app/controllers/graphql_controller.rb'
-  ROOT_TYPES = %w[app/graphql/types/query_type.rb app/graphql/types/mutation_type.rb].freeze
-  BASE_MUTATION = 'app/graphql/mutations/base_mutation.rb'
 
   source_root File.expand_path('templates', __dir__)
 
-  desc 'Install Lighthouse: initializer, starter schema, schema class, base classes, controller, route and IDE config.'
+  desc "Install Lighthouse on graphql-ruby's install: schema class, base classes, controller, initializer, starter SDL and IDE config."
 
-  class_option :schema, type: :string, default: 'AppSchema',
-                        desc: 'Name of the schema constant to generate'
-  class_option :sdl_folder, type: :string, default: 'graphql',
-                            desc: 'Folder, relative to the app root, holding the *.graphql files'
+  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 :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,
-                                 desc: 'Skip the GraphqlController and its route'
+                                 desc: "Leave graphql-ruby's GraphqlController as it is"
   class_option :skip_ide, type: :boolean, default: false,
                           desc: 'Skip graphql.config.yml and the .gitignore entries for the IDE helper files'
 
-  # graphql-ruby's install, for the base classes. What it writes that Lighthouse
-  # replaces is noted, so a file the app had before is never touched.
+  # graphql-ruby's install: the app's, or one now, with graphql-ruby's defaults.
   def install_graphql_ruby
-    @before = ([schema_path, CONTROLLER, BASE_MUTATION] + ROOT_TYPES).select { |path| exist?(path) }
-    invoke 'graphql:install', [], schema: schema_name, relay: false, skip_graphiql: true, skip_query_logs: true, skip: true
+    return if schema_path
+
+    say_status :invoke, 'graphql:install (no graphql-ruby schema found)', :blue
+    invoke 'graphql:install', [], graphql_install_options
+    @schema_path = nil
+    return if schema_path
+
+    raise Thor::Error, "No graphql-ruby schema class (class #{options[:schema] || 'AppSchema'} < GraphQL::Schema) under app/: " \
+                       'run `bin/rails g graphql:install` first.'
   end
 
   def create_initializer
@@ -55,46 +71,68 @@ 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')
+    template 'schema.graphql.tt', sdl_schema_path
   end
 
-  def create_schema_class
-    return if keep_existing?(schema_path)
-
-    template 'schema.rb.tt', schema_path, force: true
+  # Subscriptions::BaseSubscription, which graphql-ruby has none of (see BaseClasses).
+  def create_base_subscription
+    write_base_class(:subscriptions, Lighthouse::Config.namespaces[:subscriptions].first) if options[:subscriptions]
   end
 
-  # The SDL declares the root types: graphql-ruby's code-first ones go. Not when
-  # the app keeps a code-first schema of its own, which graphql-ruby's install
-  # pointed at them.
-  def remove_root_types
-    return unless exist?(schema_path) && File.read(File.join(destination_root, schema_path)).include?('RbLightHouse.get_schema')
+  # graphql-ruby's schema class, built by Lighthouse from the SDL on its classes.
+  def adopt_schema_class
+    source = read(schema_path)
+    if lighthouse?(source)
+      say_status :skip, "#{schema_path} is Lighthouse's already", :yellow
+      return
+    end
 
-    ROOT_TYPES.each { |path| remove_file path unless before?(path) }
+    declaration = /^([ \t]*)class (\S+) < GraphQL::Schema[ \t]*\n/
+    indent, name = source.match(declaration).captures
+    gsub_file schema_path, declaration, "#{indent}#{schema_comment(indent)}#{indent}class #{name} < #{schema_superclass(indent)}\n"
+    gsub_file schema_path, /^[ \t]*(query|mutation|subscription)\(Types::(Query|Mutation|Subscription)Type\)\n/, ''
+    gsub_file schema_path, /^(#{indent}\)\n)\n+/, '\\1'
+    gsub_file schema_path, RESOLVE_TYPE_STUB, "\n"
+    add_dataloader if source.include?('use GraphQL::Batch') && source.exclude?('use GraphQL::Dataloader')
   end
 
-  # The SDL declares a mutation's arguments, so its class is a plain
-  # GraphQL::Schema::Mutation, not graphql-ruby's RelayClassicMutation.
-  def adapt_base_mutation
-    return if before?(BASE_MUTATION) || !exist?(BASE_MUTATION)
-
-    gsub_file BASE_MUTATION, 'GraphQL::Schema::RelayClassicMutation', 'GraphQL::Schema::Mutation'
-    gsub_file BASE_MUTATION, /^\s*input_object_class .*\n/, ''
+  # The example field goes; the root types' own fields stay.
+  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
   end
 
-  # Subscriptions::BaseSubscription, which graphql-ruby has none of (see BaseClasses).
-  def create_base_subscription
-    write_base_class(:subscriptions, Lighthouse::Config.namespaces[:subscriptions].first)
+  # Every type class is Lighthouse's: graphql-ruby's base object, interface,
+  # union and scalar include Lighthouse::GraphQL::Type, so the classes that
+  # inherit from them (Types::QueryType, Types::NodeType, what `graphql:object`
+  # writes) lend their methods to the SDL's types of their name.
+  def adapt_type_bases
+    TYPE_CONCERN_ANCHORS.each do |name, anchor|
+      path = types_path("#{name}.rb")
+      next if !exist?(path) || read(path).include?('Lighthouse::GraphQL::Type')
+
+      indent = read(path)[anchor, 1]
+      next unless indent
+
+      indent += '  ' unless name == 'base_interface'
+      inject_into_file path, "#{indent}# Lighthouse's: the class of the SDL type of its name lends that type its methods.\n" \
+                             "#{indent}include Lighthouse::GraphQL::Type\n", after: anchor
+    end
   end
 
-  def create_controller
-    return remove_graphql_ruby_controller if options[:skip_controller]
-    return if (@kept_controller = keep_existing?(CONTROLLER))
+  # graphql-ruby's controller, as its install wrote it, serves the schema with
+  # Lighthouse's concern. One the app has changed is left alone.
+  def adapt_controller
+    return if options[:skip_controller] || !exist?(CONTROLLER)
+    return if read(CONTROLLER).include?('Lighthouse::GraphQL::Controller')
+    return @kept_controller = true unless graphql_ruby_controller?(read(CONTROLLER))
 
     template 'graphql_controller.rb.tt', CONTROLLER, force: true
   end
@@ -106,8 +144,7 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     return unless File.exist?(routes)
     return if File.read(routes).include?('graphql#execute')
 
-    # Byte-identical to graphql-ruby's install route, so whichever generator
-    # runs second finds it in place and does not add it again.
+    # Byte-identical to graphql-ruby's install route.
     route 'post "/graphql", to: "graphql#execute"'
   end
 
@@ -128,73 +165,62 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
   def show_next_steps
     serve =
       if @kept_controller
-        "Serve it: #{CONTROLLER} was kept — have it call #{schema_name}.execute(...) to serve Lighthouse's schema."
+        "Serve it: #{CONTROLLER} was changed from graphql-ruby's, so it was kept — " \
+          "include Lighthouse::GraphQL::Controller in it, or keep calling #{schema_name}.execute(...)."
       else
         'Query it:  POST /graphql  {"query": "{ users { data { id name } paginatorInfo { total } } }"}'
       end
 
     say <<~MSG
 
-      Lighthouse is installed. Next steps:
-        1. Describe your API in #{sdl_folder}/*.graphql (the starter schema assumes a User model).
-        2. Resolve a field in Ruby when a directive is not enough:  bin/rails g lighthouse:query LatestPosts
-           (it inherits from Resolvers::BaseResolver, which graphql-ruby's install wrote; lighthouse:mutation and
-           lighthouse:subscription write the others)
+      Lighthouse is installed on graphql-ruby's install (#{schema_path}). Next steps:
+        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),
-           then include Lighthouse::GraphQL::Type in the class
-        4. Generate the IDE helper files:  bin/rails lighthouse:ide_helper
+           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. The IDE helper files are rewritten in development; or:  bin/rails lighthouse:ide_helper
         5. #{serve}
     MSG
   end
 
   private
 
-  # A file the app had before this run is left alone unless --force is given;
-  # one graphql-ruby's install wrote in this run is Lighthouse's to replace.
-  def keep_existing?(path)
-    return false if options[:force] || !before?(path)
-
-    say_status :skip, "#{path} already exists (pass --force to replace it)", :yellow
-    true
-  end
-
-  def before?(path)
-    @before.include?(path)
+  def schema_superclass(indent)
+    lines = base_types.map { |key, name| "#{indent}      #{key}: #{name}" }
+    "Lighthouse::GraphQL::RbLightHouse.get_schema(\n#{indent}  options: {\n#{indent}    base_types: {\n" \
+      "#{lines.join(",\n")}\n#{indent}    }\n#{indent}  }\n#{indent})"
   end
 
-  def exist?(path)
-    File.exist?(File.join(destination_root, path))
-  end
-
-  def schema_path
-    File.join('app/graphql', "#{schema_name.underscore}.rb")
-  end
-
-  # --skip-controller: the app serves the schema itself, so graphql-ruby's
-  # controller and route, if its install just wrote them, go.
-  def remove_graphql_ruby_controller
-    return if before?(CONTROLLER)
-
-    remove_file CONTROLLER
-    gsub_file 'config/routes.rb', %r{^\s*post "/graphql", to: "graphql#execute"\n}, '' if exist?('config/routes.rb')
+  def schema_comment(indent)
+    <<~RUBY.gsub(/^/, indent).delete_prefix(indent)
+      # 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.
+    RUBY
   end
 
-  def schema_name
-    options[:schema].camelize
+  def add_dataloader
+    anchor = /^([ \t]*)use GraphQL::Batch\n/
+    indent = read(schema_path)[anchor, 1]
+    inject_into_file schema_path, "#{indent}# Lighthouse's directives batch through GraphQL::Dataloader, beside GraphQL::Batch.\n" \
+                                  "#{indent}use GraphQL::Dataloader\n", after: anchor
   end
 
-  # `Resolvers::BaseResolver`, for the schema class template.
-  def base_class_constant(kind)
-    "#{Lighthouse::Config.namespaces[kind].first}::#{base_class_name(kind)}"
+  # 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_folder?
-    sdl_folder == 'graphql'
+  def default_sdl_schema_path?
+    sdl_schema_path == 'graphql/schema.graphql'
   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