lighthouse-graphql 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b6e89e140483d01ad4cb9c945cfc29d6f025e05798ed4e5e11868060b86885
-  data.tar.gz: cac88d1820f171e4cbe6dfaa51b737c405cacf6ec3c08ed4ce8694eb2039aa18
+  metadata.gz: a15bb4d92716a08d5d248c5155b9cf336407a7988fed6e00c825b07bea4a206b
+  data.tar.gz: 421fca84187c5030f38c2cdd07ed26f9909747944f788cfd9662e67b6e322e2d
 SHA512:
-  metadata.gz: b70da4e82689cc2808b00c514f4de0eafb60fedcff45d6f0fa28b560bc3dbe502e6d3b4c0a7615d33065f95fa82fc756332added5dd9f2ba9396ef6b38ff79ce
-  data.tar.gz: 8a30bc33a00599f3302196e3e24c881be56a68f94026ae1c0ab64246afa7b2114f6e723fba4f203fe51be03661bc6351f65fc12e3d4827624a6e04a2798b53fd
+  metadata.gz: 388112925823baa63d0a7a4436bb1df4511f4a4c13b01001dd72b351156b78982ca4eab136a131c9c25b997915bff26099fa2a485bc4df74bfef390138e37c3a
+  data.tar.gz: e2f90e9654cfcdc2d26e084f68476ac59f56eb708683b3b4817cfc41006843363feb0f9a08b838bdcdd888395bc8f13ae29394d28b0bc37566c26dad63657cac

data/CHANGELOG.md

@@ -6,6 +6,48 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-17
+
+### Added
+
+- `@complexity` sets what a field costs in graphql-ruby's query complexity analysis, so
+  `AppSchema.max_complexity(n)` refuses expensive queries before they run. A bare `@complexity`
+  costs `1 + child complexity × first`. `@complexity(resolver: "Name")` names a
+  `GraphQL::Analysis::Analyzer` subclass in the new `analyzers` namespace (`Analyzers::Name`),
+  which Lighthouse installs on the schema. Including `Lighthouse::GraphQL::ComplexityAnalyzer`
+  gives the analyzer a `complexity` (a number, or a proc of `context, args, child_complexity`,
+  as graphql-ruby's) that is the cost of the fields naming it.
+- A root field resolved by a `GraphQL::Schema::Resolver` class, by convention or through `@field`,
+  takes the `complexity` that class declares, as graphql-ruby's `field ..., resolver:` does.
+- `BuildExtensionsResponse#query_complexity` holds the query's complexity score while something
+  listens to the event. It used to be `nil`.
+- `docs/security.md`: query complexity, depth and introspection limits.
+- graphql-ruby's base classes: `rails g lighthouse:install` writes `Resolvers::BaseResolver`,
+  `Mutations::BaseMutation` and `Subscriptions::BaseSubscription` (which includes
+  `Lighthouse::GraphQL::Subscription`), and `lighthouse:query`, `:mutation` and `:subscription`
+  write the one they need when it is missing. Generated classes inherit from them. An existing
+  base, such as the ones graphql-ruby's `graphql:install` writes, is never replaced.
+- `get_schema`'s `base_types` takes `resolver:`, `mutation:` and `subscription:` beside
+  graphql-ruby's own keys. Every class a `Query`, `Mutation` or `Subscription` field resolves to
+  must then inherit from its kind's base (`Lighthouse::DefinitionError` otherwise), and a
+  `Subscription` field with no class of its own resolves with the subscription base. The
+  generated schema class names the three.
+
+### Changed
+
+- The classes of `Query` fields are looked up in `Resolvers` (`app/graphql/resolvers`), graphql-ruby's
+  convention, instead of `Queries`: `Query.latestPosts` resolves to `Resolvers::LatestPosts`, and
+  `lighthouse:query` writes there. To keep `app/graphql/queries`, set
+  `config.namespaces = { queries: ['Queries'] }`.
+- `lighthouse:subscription` no longer takes `--lighthouse`. The class inherits from
+  `Subscriptions::BaseSubscription`, which includes the concern, and gets its hooks; under a base
+  without the concern, it gets graphql-ruby's `authorized?` and `update`.
+
+- Paginated fields (`@paginate`, and relationship directives given `type:`) cost
+  `1 + child complexity × first` in the complexity score. A page of 1,000 items now scores
+  1,000 times one item's cost; before, a paginator scored the same whatever `first` was.
+  A schema that already sets `max_complexity` may need a higher limit.
+
 ## [0.3.0] - 2026-10-17
 
 ### Added
@@ -282,7 +324,8 @@ had been running inside a private monorepo as a path gem before being extracted.
 - Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
   `on_error`, and `DirectiveRegistry.register` for app-defined directives.
 
-[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.1...v0.2.0

data/README.md

@@ -127,7 +127,14 @@ Prefer to wire it by hand? These are the steps the generator performs.
 
    AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
      sdl_folder: Rails.root.join('graphql').to_s,
-     options: { base_types: { object: BaseObject } } # your graphql-ruby base classes
+     options: {
+       base_types: {
+         resolver: Resolvers::BaseResolver,              # graphql-ruby's base classes, which
+         mutation: Mutations::BaseMutation,              # rails g lighthouse:install writes
+         subscription: Subscriptions::BaseSubscription
+         # object: Types::BaseObject, ...
+       }
+     }
    )
    ```
 
@@ -143,7 +150,8 @@ including base types and configuration.
 ### Example app
 
 [`example/`](example) is a small blog API built with Lighthouse on Rails 8.1. It shows
-the schema, the generated `Queries::`/`Mutations::`/`Builders::`/`Validators::` classes,
+the schema, the generated `Resolvers::`/`Mutations::`/`Subscriptions::`/`Builders::`/`Validators::` classes
+under graphql-ruby's base classes,
 Pundit policies and the opt-in performance features working together, and its specs
 are the library's end-to-end suite. See [example/README.md](example/README.md).
 
@@ -161,7 +169,7 @@ or as Markdown in [`docs/`](docs):
 | [Directives reference](docs/directives.md) | Every built-in directive, grouped by purpose |
 | [Relationships](docs/relationships.md) | `@hasMany`, `@belongsTo`, `@belongsToMany`, `@hasOne`, the `@morph*` variants, batching and `type:` pagination |
 | [Filtering & ordering](docs/filtering-and-ordering.md) | `@eq`/`@where`/`@in`/`@like`, `@whereConditions`, `@orderBy` |
-| [Queries, mutations & builders](docs/resolvers.md) | `Queries::` / `Mutations::` classes (graphql-ruby's contract), builders, generators |
+| [Resolvers, mutations & builders](docs/resolvers.md) | `Resolvers::` / `Mutations::` classes and their base classes (graphql-ruby's contract), builders, generators |
 | [Mutations](docs/mutations.md) | `@create`, `@update`, `@upsert`, `@delete` (and `*Many`), nested mutations on every kind of association, `@spread`, `@inject` |
 | [Validation](docs/validation.md) | Model validations, `@validator` with Dry::Validation contracts |
 | [Authentication & authorization](docs/authorization.md) | `@guard`, `@canFind` / `@canModel` / `@canQuery` / `@canResolved` / `@canRoot` (Pundit by default) |

data/docs/best-practices.md

@@ -44,12 +44,22 @@ Use `@guard` and the `@can*` directives on fields that require them. They wrap t
 resolver, so the check runs before any data is loaded (only `@canResolved`, which
 needs the result, runs after — keep it to fields that don't write).
 
-## Keep queries, mutations and builders apart
-
-A custom `Query` field is a `GraphQL::Schema::Resolver` in `app/graphql/queries`,
-a `Mutation` field a `GraphQL::Schema::Mutation` in `app/graphql/mutations`, and a
-query refinement a builder in `app/graphql/builders`. They have different jobs and
-contracts; don't fold them into one "resolvers" folder. See [resolvers.md](resolvers.md).
+## Keep resolvers, mutations and builders apart
+
+A custom `Query` field is a `Resolvers::BaseResolver` in `app/graphql/resolvers`, a
+`Mutation` field a `Mutations::BaseMutation` in `app/graphql/mutations`, and a query
+refinement a builder in `app/graphql/builders`. They have different jobs and
+contracts; keep each kind in its own folder. See [resolvers.md](resolvers.md).
+
+## Share through the base classes
+
+What every resolver, mutation or subscription needs (a concern, a helper,
+graphql-ruby's `argument_class`) goes in `Resolvers::BaseResolver`,
+`Mutations::BaseMutation` or `Subscriptions::BaseSubscription`, once, as in any
+graphql-ruby app. Name them in the schema's `base_types` (`resolver:`, `mutation:`,
+`subscription:`), and a class that forgets to inherit from its base is refused
+instead of quietly missing what it shares. See
+[resolvers.md](resolvers.md#base-classes).
 
 ## Validate in the model first
 

data/docs/configuration.md

@@ -10,8 +10,8 @@ require 'lighthouse-graphql'
 
 Lighthouse.configure do |config|
   config.sdl_folder = Rails.root.join('graphql').to_s
-  config.namespaces = { queries: ['Queries'], mutations: ['Mutations'] }
-  config.resolver_namespaces = ['App::Graphql', 'Resolvers']
+  config.namespaces = { queries: ['Resolvers'], mutations: ['Mutations'] }
+  config.resolver_namespaces = ['App::Graphql']
   config.on_error = ->(error, _context) { Rails.error.report(error) }
 end
 ```
@@ -31,15 +31,16 @@ different contracts, so they live apart ([resolvers.md](resolvers.md)):
 
 | Kind | Default | Holds |
 | --- | --- | --- |
-| `queries` | `['Queries']` | `GraphQL::Schema::Resolver` classes for `Query` fields |
-| `mutations` | `['Mutations']` | `GraphQL::Schema::Mutation` classes for `Mutation` fields |
+| `queries` | `['Resolvers']` | `Resolvers::BaseResolver` classes (a `GraphQL::Schema::Resolver`) for `Query` fields. `['Queries']` before 0.4.0 |
+| `mutations` | `['Mutations']` | `Mutations::BaseMutation` classes (a `GraphQL::Schema::Mutation`) for `Mutation` fields |
 | `builders` | `['Builders']` | `@builder` classes |
 | `validators` | `['Validators']` | `@validator` contracts |
 | `events` | `['Events']` | Classes `@event(dispatch:)` names ([events.md](events.md)) |
-| `subscriptions` | `['Subscriptions']` | `GraphQL::Schema::Subscription` classes (optionally including `Lighthouse::GraphQL::Subscription`) for `Subscription` fields, and `@subscription(class:)` ([subscriptions.md](subscriptions.md)) |
+| `subscriptions` | `['Subscriptions']` | `Subscriptions::BaseSubscription` classes (a `GraphQL::Schema::Subscription`; the base includes `Lighthouse::GraphQL::Subscription`) for `Subscription` fields, and `@subscription(class:)` ([subscriptions.md](subscriptions.md)) |
+| `analyzers` | `['Analyzers']` | `GraphQL::Analysis::Analyzer` classes (optionally including `Lighthouse::GraphQL::ComplexityAnalyzer`) that `@complexity(resolver:)` names ([security.md](security.md)) |
 
 ```ruby
-config.namespaces = { queries: ['Api::Queries'] }   # the other kinds keep their defaults
+config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep their defaults
 ```
 
 ### `resolver_namespaces`

data/docs/directives.md

@@ -150,8 +150,9 @@ The relation name defaults to the field name (snake_cased). Override with
 
 Delegate a field to a class — your escape hatch for anything the built-in
 directives don't cover. On `Query` and `Mutation` you usually don't need it:
-a field without a resolving directive resolves to `Queries::<FieldName>` /
-`Mutations::<FieldName>`, graphql-ruby resolver and mutation classes. See
+a field without a resolving directive resolves to `Resolvers::<FieldName>` /
+`Mutations::<FieldName>`, graphql-ruby resolver and mutation classes under
+`Resolvers::BaseResolver` / `Mutations::BaseMutation`. See
 [resolvers.md](resolvers.md).
 
 ```graphql
@@ -321,7 +322,7 @@ type Query {
 ### `@convertEmptyStringsToNull`
 
 Replaces incoming empty strings `""` with `null`, before any resolver sees them —
-directive resolvers (`@create`, `@all` filters, …), `@field`, `Queries::` /
+directive resolvers (`@create`, `@all` filters, …), `@field`, `Resolvers::` /
 `Mutations::` classes and `@validator` alike. On an argument or an input field it
 converts that one input; on a field it converts every input of the field, nested
 input objects and lists included. Non-null inputs (`String!`) pass unchanged when
@@ -520,9 +521,9 @@ directive @subscription(class: String!) on FIELD_DEFINITION
 
 Names the class a `Subscription` field resolves to, when it does not follow the
 convention (`postUpdated` → `Subscriptions::PostUpdated`). The class inherits from
-`GraphQL::Schema::Subscription` (which may `include Lighthouse::GraphQL::Subscription`,
-the optional concern with PHP Lighthouse's `filter?` hooks) and is looked up in
-`Config.namespaces[:subscriptions]`; a name with `::` is used as it is.
+`Subscriptions::BaseSubscription`, a `GraphQL::Schema::Subscription` that includes
+`Lighthouse::GraphQL::Subscription` (PHP Lighthouse's `filter?` hooks), and is looked
+up in `Config.namespaces[:subscriptions]`; a name with `::` is used as it is.
 
 ```graphql
 type Subscription {
@@ -634,6 +635,30 @@ Flipper.enable_actor(:new_checkout, User.find(1))
 
 ---
 
+## Query complexity
+
+### `@complexity`
+
+Customize what a field costs in the query's complexity score, which graphql-ruby
+checks against the schema's `max_complexity` before it runs the query.
+
+```graphql
+type Query {
+  search(first: Int, term: String!): [Post!]! @complexity
+  posts(includeFullText: Boolean): [Post!]! @all @complexity(resolver: "PostsComplexity")
+}
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `resolver: String` | A `GraphQL::Analysis::Analyzer` subclass in `namespaces[:analyzers]` (`Analyzers::PostsComplexity`), installed on the schema. With `Lighthouse::GraphQL::ComplexityAnalyzer` included, its `complexity` (a number, or a proc of `context, args, child_complexity`) is the field's cost. Without it, or without `resolver:`: `1 + child complexity × first`. |
+
+Paginated fields cost `1 + child complexity × first` without the directive, and a
+field resolved by a `GraphQL::Schema::Resolver` class costs what that class
+declares. See [security.md](security.md).
+
+---
+
 ## Events
 
 `@event` dispatches an event once the field has resolved. The class is built with

data/docs/events.md

@@ -107,7 +107,9 @@ end
 # => { "data" => {...}, "extensions" => { "queries" => 3 } }
 ```
 
-`query_complexity` is `nil`: Lighthouse does not compute it for you.
+`query_complexity` is the query's complexity score, the number graphql-ruby
+checks against `max_complexity` (see [security.md](security.md#reading-the-score)).
+It is `nil` for a query that failed validation.
 
 **`ManipulateResult`**: change `event.result` (the Hash with `data`, `errors` and
 `extensions`) in place, or assign a new Hash to `event.result=`:

data/docs/federation.md

@@ -13,7 +13,8 @@ Include the federation mixins in the base types you pass to Lighthouse, and make
 your schema a federation schema:
 
 ```ruby
-class BaseObject < GraphQL::Schema::Object
+# app/graphql/types/base_object.rb
+class Types::BaseObject < GraphQL::Schema::Object
   include ApolloFederation::Object
 
   # Default entity resolution: look the record up by id on the model that shares
@@ -29,7 +30,7 @@ end
 
 BaseAppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   sdl_folder: Rails.root.join('graphql').to_s,
-  options: { federation: true, base_types: { object: BaseObject } }
+  options: { federation: true, base_types: { object: Types::BaseObject, resolver: Resolvers::BaseResolver } }
 )
 
 class AppSchema < BaseAppSchema

data/docs/getting-started.md

@@ -75,16 +75,44 @@ argument (the `@eq` makes `id` a filter). Lighthouse infers the model from the
 field's return type name (`User`), or you can be explicit with
 `@all(model: "User")`.
 
-## 2. Provide your base types
+## 2. Provide your base classes
 
-Lighthouse builds on graphql-ruby, so you supply the base classes it should use
-for objects, interfaces, etc. — exactly the place to mix in Apollo Federation or
-any custom field/argument behavior.
+Lighthouse builds on graphql-ruby, and follows its convention: each kind of class
+inherits from a base class in its own namespace, where what they all share goes
+once. `rails g lighthouse:install` writes the bases of the classes that resolve
+root fields:
 
 ```ruby
-# app/graphql/base_object.rb
-class BaseObject < GraphQL::Schema::Object
-  # include ApolloFederation::Object   # if you use federation
+# app/graphql/resolvers/base_resolver.rb       — Query fields (Resolvers::LatestPosts)
+module Resolvers
+  class BaseResolver < GraphQL::Schema::Resolver
+  end
+end
+
+# app/graphql/mutations/base_mutation.rb       — Mutation fields (Mutations::PublishPost)
+module Mutations
+  class BaseMutation < GraphQL::Schema::Mutation
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb — Subscription fields
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+The SDL's types can have graphql-ruby base classes too, as `graphql:install`
+writes them: the place to mix in Apollo Federation or custom field and argument
+behavior.
+
+```ruby
+# app/graphql/types/base_object.rb
+module Types
+  class BaseObject < GraphQL::Schema::Object
+    # include ApolloFederation::Object   # if you use federation
+  end
 end
 ```
 
@@ -98,13 +126,22 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   sdl_folder: Rails.root.join('graphql').to_s,
   options: {
     base_types: {
-      object: BaseObject,
+      resolver: Resolvers::BaseResolver,
+      mutation: Mutations::BaseMutation,
+      subscription: Subscriptions::BaseSubscription,
+      object: Types::BaseObject,
       # interface:, union:, enum:, input_object:, scalar: ...
     }
   }
 )
 ```
 
+`object:` and the other SDL kinds go to graphql-ruby, which builds the SDL's types
+from them. `resolver:`, `mutation:` and `subscription:` are Lighthouse's: every
+class a `Query`, `Mutation` or `Subscription` field resolves to must inherit from
+its kind's base, and a `Subscription` field with no class of its own resolves with
+the subscription base. See [resolvers.md](resolvers.md#base-classes).
+
 `get_schema` returns a `GraphQL::Schema` subclass you can use directly, or
 subclass further (e.g. to add federation, tracing, a Dataloader):
 
@@ -247,18 +284,19 @@ type User {
 }
 ```
 
-## Custom queries and mutations
+## Custom resolvers and mutations
 
 When a field needs Ruby, write a graphql-ruby resolver or mutation class named
-after it — `Query.latestPosts` resolves to `Queries::LatestPosts`
-(`app/graphql/queries/latest_posts.rb`), `Mutation.publishPost` to
-`Mutations::PublishPost`. `bin/rails generate lighthouse:query LatestPosts`
-scaffolds one. See [resolvers.md](resolvers.md).
+after it — `Query.latestPosts` resolves to `Resolvers::LatestPosts`
+(`app/graphql/resolvers/latest_posts.rb`, a `Resolvers::BaseResolver`),
+`Mutation.publishPost` to `Mutations::PublishPost` (a `Mutations::BaseMutation`).
+`bin/rails generate lighthouse:query LatestPosts` scaffolds one. See
+[resolvers.md](resolvers.md).
 
 ## Next steps
 
 - [Directives reference](directives.md) — the full vocabulary.
-- [Queries, mutations & builders](resolvers.md), [Mutations](mutations.md),
+- [Resolvers, mutations & builders](resolvers.md), [Mutations](mutations.md),
   [Validation](validation.md), [Caching](caching.md).
 - [Relationships](relationships.md) — wiring associations.
 - [Filtering & ordering](filtering-and-ordering.md) — query constraints.

data/docs/motivation.md

@@ -151,8 +151,9 @@ Schema-first doesn't mean schema-only. When a field does something no directive
 describes, write Ruby, using graphql-ruby's own classes:
 
 - A `Query` or `Mutation` field without a resolving directive resolves by convention to
-  `Queries::FieldName` (a `GraphQL::Schema::Resolver`) or `Mutations::FieldName` (a
-  `GraphQL::Schema::Mutation`). See [Queries, Mutations and Builders](resolvers.md).
+  `Resolvers::FieldName` (a `Resolvers::BaseResolver`) or `Mutations::FieldName` (a
+  `Mutations::BaseMutation`), under the base classes graphql-ruby's convention gives
+  each kind. See [Resolvers, Mutations and Builders](resolvers.md).
 - `@builder` classes adjust a query; `@validator` contracts check arguments.
 - Your own directives plug in through the registry, with the same contracts as the
   built-in ones. See [Custom Directives](custom-directives.md).

data/docs/resolvers.md

@@ -1,4 +1,4 @@
-# Queries, Mutations and Builders
+# Resolvers, Mutations and Builders
 
 Most fields need no Ruby: a directive (`@all`, `@find`, `@paginate`, `@create`,
 …) or the default attribute reader resolves them. For the rest, Lighthouse looks
@@ -7,17 +7,86 @@ interchangeable. Each kind has its own contract and its own folder:
 
 | Kind | Folder / namespace | Contract | Used by |
 | --- | --- | --- | --- |
-| Query | `app/graphql/queries` · `Queries::` | `GraphQL::Schema::Resolver` | `Query` fields |
-| Mutation | `app/graphql/mutations` · `Mutations::` | `GraphQL::Schema::Mutation` | `Mutation` fields |
-| Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `GraphQL::Schema::Subscription` | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
+| Resolver | `app/graphql/resolvers` · `Resolvers::` | `Resolvers::BaseResolver` (a `GraphQL::Schema::Resolver`) | `Query` fields |
+| Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (a `GraphQL::Schema::Mutation`) | `Mutation` fields |
+| Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `Subscriptions::BaseSubscription` (a `GraphQL::Schema::Subscription`) | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
 Validators (`app/graphql/validators`) are the fourth kind. They are covered in
 [validation.md](validation.md).
 
-## Queries and mutations: graphql-ruby's contract
+## Base classes
 
-A query or mutation class is a plain graphql-ruby
+As in any graphql-ruby app, each of the first three kinds has a base class in its
+namespace, and every class of the kind inherits from it:
+
+```ruby
+# app/graphql/resolvers/base_resolver.rb
+module Resolvers
+  class BaseResolver < GraphQL::Schema::Resolver
+  end
+end
+
+# app/graphql/mutations/base_mutation.rb
+module Mutations
+  class BaseMutation < GraphQL::Schema::Mutation
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+What every class of a kind shares goes in its base, once: a concern (as
+`BaseSubscription` includes Lighthouse's, see [subscriptions.md](subscriptions.md)),
+a helper, graphql-ruby settings such as `argument_class Types::BaseArgument`.
+`rails g lighthouse:install` writes the three, and the class generators write the
+one they need when it is missing. graphql-ruby's own `graphql:install` writes
+`Resolvers::BaseResolver` and `Mutations::BaseMutation` too, and Lighthouse keeps
+whatever is already there: an existing base is never replaced.
+
+### Handing the bases to the schema
+
+Name the bases in `base_types`, beside graphql-ruby's own base types, and the
+schema holds every class to them:
+
+```ruby
+# app/graphql/app_schema.rb
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    base_types: {
+      resolver: Resolvers::BaseResolver,
+      mutation: Mutations::BaseMutation,
+      subscription: Subscriptions::BaseSubscription
+      # object: Types::BaseObject, ... (graphql-ruby's, for the SDL's types)
+    }
+  }
+)
+```
+
+- A class a `Query`, `Mutation` or `Subscription` field resolves to, by convention
+  or through `@subscription(class:)`, that does not inherit from its kind's base
+  raises `Lighthouse::DefinitionError` when the field is first used (`…so it must
+  inherit from Resolvers::BaseResolver…`). No class misses what the base shares.
+- A `Subscription` field with no class of its own resolves with the subscription
+  base, so its concern and settings apply there too.
+- A base must be a subclass of the graphql-ruby class of its kind
+  (`GraphQL::Schema::Resolver`, `GraphQL::Schema::Mutation`, which
+  `RelayClassicMutation` is, `GraphQL::Schema::Subscription`), or the schema does not
+  build. graphql-ruby never sees these three keys.
+
+`rails g lighthouse:install` writes the schema class with them. Without them,
+Lighthouse requires only the graphql-ruby class (`GraphQL::Schema::Resolver`, …),
+and a `Subscription` field with no class resolves with a built-in subscription that
+includes the concern.
+
+## Resolvers and mutations: graphql-ruby's contract
+
+A resolver or mutation class is a plain graphql-ruby
 [resolver](https://graphql-ruby.org/fields/resolvers.html) or
 [mutation](https://graphql-ruby.org/mutations/mutation_classes.html), so everything
 you know from graphql-ruby applies:
@@ -40,9 +109,9 @@ type Mutation {
 ```
 
 ```ruby
-# app/graphql/queries/latest_posts.rb
-module Queries
-  class LatestPosts < GraphQL::Schema::Resolver
+# app/graphql/resolvers/latest_posts.rb
+module Resolvers
+  class LatestPosts < BaseResolver
     def resolve(limit: 10)
       Post.order(created_at: :desc).limit(limit)
     end
@@ -51,7 +120,7 @@ end
 
 # app/graphql/mutations/publish_post.rb
 module Mutations
-  class PublishPost < GraphQL::Schema::Mutation
+  class PublishPost < BaseMutation
     def authorized?(id:)
       context[:current_user]&.admin? || raise(GraphQL::ExecutionError, 'Admins only.')
     end
@@ -68,7 +137,7 @@ end
 A field on `Query` or `Mutation` with **no resolving directive** resolves to the
 class named after it, as in PHP Lighthouse:
 
-- `Query.latestPosts` resolves to `Queries::LatestPosts`;
+- `Query.latestPosts` resolves to `Resolvers::LatestPosts`;
 - `Mutation.publishPost` resolves to `Mutations::PublishPost`.
 
 The class is looked up on each call, so code reloading works. Classes found by
@@ -78,8 +147,8 @@ field with no class is reported through [`on_error`](configuration.md#on_error):
 it raises in test and logs elsewhere. Lighthouse never falls back to a top-level
 constant, so a `post` field is never mistaken for the `Post` model.
 
-graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` generates
-`Mutations::BaseMutation` from) works too, as long as the SDL field takes the
+graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` makes
+`Mutations::BaseMutation` inherit from) works too, as long as the SDL field takes the
 `input:` argument it expects.
 
 Wrapping directives (`@guard`, the `@can*` family, `@validator`, `@cache`,
@@ -95,12 +164,12 @@ type Mutation {
 ### Naming a class explicitly
 
 `@field(resolver:)` points a field at a class by name. On `Query` and `Mutation`
-the name is looked up in the queries and mutations namespaces; on any other type,
+the name is looked up in the resolvers and mutations namespaces; on any other type,
 in [`resolver_namespaces`](configuration.md#resolver_namespaces).
 
 ```graphql
 type Query {
-  feed: [Post!]! @field(resolver: "Feeds::Home")   # Queries::Feeds::Home
+  feed: [Post!]! @field(resolver: "Feeds::Home")   # Resolvers::Feeds::Home
 }
 ```
 
@@ -166,7 +235,7 @@ end
 ## Generators
 
 ```shell
-bin/rails generate lighthouse:query LatestPosts        # app/graphql/queries/latest_posts.rb
+bin/rails generate lighthouse:query LatestPosts        # app/graphql/resolvers/latest_posts.rb
 bin/rails generate lighthouse:mutation PublishPost     # app/graphql/mutations/publish_post.rb
 bin/rails generate lighthouse:subscription PostUpdated # app/graphql/subscriptions/post_updated.rb
 bin/rails generate lighthouse:builder Published        # app/graphql/builders/published.rb
@@ -174,8 +243,10 @@ bin/rails generate lighthouse:validator CreatePostInput # app/graphql/validators
 ```
 
 Each one writes the class with its contract, into the first namespace configured
-for its kind (or `--namespace=…`). Namespaced names nest modules:
-`lighthouse:mutation Blog::Publish` writes `Mutations::Blog::Publish`. These
+for its kind (or `--namespace=…`). A resolver, mutation or subscription inherits
+from the namespace's base class, which is written first when it is missing.
+Namespaced names nest modules: `lighthouse:mutation Blog::Publish` writes
+`Mutations::Blog::Publish < BaseMutation`. These
 generators do not collide with graphql-ruby's `graphql:*` generators. A
 `lighthouse:mutation` and a `graphql:mutation` of the same name target the same
 file, and Rails asks before overwriting it.
@@ -184,8 +255,11 @@ file, and Rails asks before overwriting it.
 
 ```ruby
 Lighthouse.configure do |config|
-  config.namespaces = { queries: ['Api::Queries'], mutations: ['Api::Mutations'] }
+  config.namespaces = { queries: ['Api::Resolvers'], mutations: ['Api::Mutations'] }
 end
 ```
 
 Kinds you leave out keep their defaults. Each kind takes a list, tried in order.
+The `queries` kind is the classes of `Query` fields. Before 0.4.0 it defaulted to
+`Queries`; an app keeping its classes in `app/graphql/queries` sets
+`config.namespaces = { queries: ['Queries'] }`.