lighthouse-graphql 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3be850a4eb57c4d4fc6bd41103d5bb783482530f3fc0f3584aa00314de4e936
-  data.tar.gz: 75ae5604d85d1549f159dc17a98932d7c4274074ea26b9a9ade38b4f8d8d6af6
+  metadata.gz: 844e3fc4942a637b4353427932e031c210ad52d4d425161a58f45e2e36f1d931
+  data.tar.gz: 9b0b05109d1fcac2f330b7266fe91eb502d521dabce399adfd98828137119468
 SHA512:
-  metadata.gz: 62cafecf9c4deae7b974747a9de82c422ea1d58d50fa752d6c583fba20f6ff16b99db56496a9963d0740826803b89e730c3ede19fed937baf22fac7f954bd826
-  data.tar.gz: fcd638c332e4f055afb9b28e7ac211162582878e578e5cb45c02a7d24dcf2ae70f7dd5342cdd477bc1f8a16b3cc1e6dd78e487791ee396044fefbe7aa95bea49
+  metadata.gz: ef2d22dd33355e36e3b40725cea55ebf5923a06ea2c94660228d8cc6b3a6e222bd7da6f42f796d52275a2130c1ebd9e54844f85febf31d66a7a4c759d310723e
+  data.tar.gz: 7334b3e2b4ecb745fea9a4f9c08860d8e5c6245654323b0161a0b97c367d8ea022a3b23f7bd7e5bbd8c4e8614939b16e82fa737e9e133e4c5cba555199088c1d

data/CHANGELOG.md

@@ -6,6 +6,26 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-17
+
+### Added
+
+- RBS signatures in `sig/`, shipped with the gem, for the parts an app implements or calls:
+  `Lighthouse::_Builder` (what a `@builder` class answers) and `_Validator`, every
+  `Lighthouse::Config` setting with the callables it takes (`_ErrorHandler`, `_UserReader`,
+  `_Authorizer`), the directive extension points (`DirectiveRegistry`, the contracts,
+  `BaseDirectiveResolver`, `Directives::Arguments::Base`), the entrypoints (`get_schema`,
+  `SchemaFactory`, `PersistedQueries`, `CacheControl`, `SchemaCache`, `IdeHelper`) and the
+  errors. `rbs collection` (and so Steep) loads them from the installed gem, as it does for any
+  gem that ships `sig/`; nothing changes at runtime.
+  CI validates them and runs the suite with every Lighthouse method checked against its
+  signature, so they cannot drift from the code.
+- A documentation site, built from `docs/` with VuePress as PHP Lighthouse builds its own,
+  and published to GitHub Pages on every push to `main`:
+  <https://vaz-innovation.github.io/lighthouse-graphql/>.
+- `docs/motivation.md`: where Lighthouse comes from, why the schema comes first, and why
+  directives work so well on Active Record — and when something else fits better.
+
 ## [0.2.0] - 2026-10-17
 
 ### Added
@@ -208,7 +228,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.2.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.1...HEAD
+[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
 [0.1.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/releases/tag/v0.1.0

data/README.md

@@ -39,7 +39,7 @@ paginate, walk a relationship, or read an attribute. Lighthouse — like its PHP
 inspiration — captures those patterns as **directives** you attach in the schema,
 and falls back to a sensible default reader for plain fields. You write Ruby only
 for the genuinely custom parts (`@field(resolver: "...")`), and your schema stays
-the single source of truth.
+the single source of truth. [Motivation](docs/motivation.md) explains the idea in depth.
 
 ### Inspirations
 
@@ -142,8 +142,12 @@ are the library's end-to-end suite. See [example/README.md](example/README.md).
 
 ## Documentation
 
+**Read it at [vaz-innovation.github.io/lighthouse-graphql](https://vaz-innovation.github.io/lighthouse-graphql/)**,
+or as Markdown in [`docs/`](docs):
+
 | Guide | What it covers |
 | --- | --- |
+| [Motivation](docs/motivation.md) | Where Lighthouse comes from, why the schema comes first, and why directives fit Active Record |
 | [Getting started](docs/getting-started.md) | Install, base types, building & serving the schema |
 | [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 |

data/docs/motivation.md

@@ -0,0 +1,184 @@
+# Motivation
+
+Lighthouse GraphQL Rails brings the ideas of [Lighthouse](https://lighthouse-php.com),
+the GraphQL framework for Laravel, to Ruby on Rails. This page explains those ideas:
+why the schema comes first, why behaviour lives in directives, and why that works so
+well on top of an opinionated model layer like Active Record.
+
+## Where it comes from
+
+Lighthouse ([nuwave/lighthouse](https://github.com/nuwave/lighthouse)) changed how many
+Laravel teams build GraphQL APIs. Instead of a resolver class for every field, you write
+the schema in GraphQL's own language and attach **directives** that say what a field
+does: `@paginate` it, follow a `@hasMany` relationship, `@create` a model, check a policy
+with `@canFind`. Lighthouse reads those directives and generates efficient queries against
+Eloquent, Laravel's ORM.
+
+The idea does not depend on PHP. It depends on two things: a schema written first, and a
+model layer with strong conventions. Rails has the second in Active Record, and
+[graphql-ruby](https://graphql-ruby.org) gives Ruby a mature GraphQL engine to build the
+first on. Lighthouse GraphQL Rails puts them together. It keeps Lighthouse's directive
+names, arguments and error formats wherever they make sense, so its documentation, its
+examples and the experience of Laravel teams carry over.
+
+## The problem with writing every resolver
+
+Most GraphQL fields in a Rails app do one of a handful of things: list records, find one,
+paginate, follow an association, filter and sort, read an attribute, or create, update
+and delete a record. Written by hand, each of these is a resolver. Each resolver is a
+place where:
+
+- **the API's shape hides in Ruby.** To know what `posts` accepts and returns, you read
+  a type class, its fields, their resolver methods and the scopes they call.
+- **N+1 queries creep in.** Every association needs its own batch loader, and every
+  paginated association needs a separate count, page and cursor logic.
+- **the same decisions are made again**, slightly differently each time: how pages are
+  numbered, what a cursor contains, how validation errors are reported, which filter
+  arguments are allowed.
+
+With [graphql-ruby](https://graphql-ruby.org) alone, a list of published posts with their
+author and comments, filterable by author, looks roughly like this:
+
+```ruby
+class Types::PostType < Types::BaseObject
+  field :id, ID, null: false
+  field :title, String, null: false
+  field :author, Types::UserType, null: false
+  field :comments, Types::CommentType.connection_type, null: false
+
+  def author
+    dataloader.with(Sources::RecordById, User).load(object.author_id)
+  end
+
+  def comments
+    object.comments.order(:created_at) # one query per post
+  end
+end
+
+class Types::QueryType < Types::BaseObject
+  field :posts, Types::PostType.connection_type, null: false do
+    argument :author_id, ID, required: false
+  end
+
+  def posts(author_id: nil)
+    scope = Post.published.order(created_at: :desc)
+    author_id ? scope.where(author_id: author_id) : scope
+  end
+end
+```
+
+…plus the `Sources::RecordById` batch loader, and more code to batch the comments. With
+Lighthouse, it is the schema:
+
+```graphql
+type Query {
+  posts(authorId: ID @eq): [Post!]! @paginate(type: CONNECTION) @builder(class: "Published")
+}
+
+type Post {
+  id: ID!
+  title: String!
+  author: User! @belongsTo
+  comments: [Comment!]! @hasMany(type: CONNECTION, scopes: ["chronological"])
+}
+```
+
+The `author` of every post loads in one query, and so does every post's page of
+comments, with one more for their totals if the client asks for `pageInfo { total }`. This isn't a
+special case: it is how every relationship directive works.
+
+## Why the schema comes first
+
+In a schema-first API, the `.graphql` files *are* the API's definition, not something
+generated from Ruby classes:
+
+- **It is a contract you can read.** Frontend developers, mobile developers and reviewers
+  read the same SDL that clients query. A pull request that changes the API shows the
+  change in the schema diff.
+- **It is designed before it is implemented.** You can agree on the types and fields
+  first, as a team, and the server follows the design rather than leaking its internals.
+- **Tools understand it directly.** IDE plugins, code generators and schema registries
+  read SDL. Lighthouse's `lighthouse:ide_helper` task adds its directives and generated
+  types so editors validate and autocomplete the schema.
+- **It says what each field does.** `posts: [Post!]! @paginate @guard @cacheControl(maxAge: 60)`
+  tells a reader, without opening any Ruby, that the field is paginated, requires a
+  signed-in user and can be cached for a minute.
+
+## Why directives
+
+Directives are a small vocabulary that composes. Each one does one job, and a field
+combines them:
+
+```graphql
+type Mutation {
+  updatePost(input: UpdatePostInput! @spread): Post!
+    @guard                                        # require a user
+    @canFind(ability: "update", find: "input.id") # PostPolicy#update?
+    @update                                       # save through Active Record, in a transaction
+    @clearCache(type: "Post", idSource: { argument: "input.id" })
+}
+```
+
+Because the behaviour is declared, Lighthouse controls the order it runs in
+(authentication, then authorization, then validation, then the save, then cache
+invalidation) and handles the details the same way everywhere: pagination types and
+cursors, validation errors keyed by argument path, `Cache-Control` headers. That
+consistency is what a hand-written resolver per field rarely achieves.
+
+## Why it fits Active Record
+
+A directive can only be this short if something else knows the details. In Lighthouse,
+that is the model layer. Active Record is opinionated, and every convention it imposes is
+information Lighthouse can use:
+
+| Active Record already knows | So Lighthouse can |
+| --- | --- |
+| Associations, their foreign keys, `:through` and polymorphic links | Resolve `@hasMany`, `@belongsTo`, `@belongsToMany` and `@morph*` from the name alone, batch them, and paginate many parents in one query |
+| Scopes | Narrow any query with `scopes: ["published"]` |
+| Validations | Report a failed `@create` or `@update` by argument path, with the model's own messages and locale |
+| Transactions and callbacks | Run nested mutations (create a post, attach tags, add comments) atomically, with your callbacks |
+| Naming conventions (`Post`, `posts`, `author_id`) | Map `Post` to its model, `authorId` to `author_id`, and a field to its association, with no configuration |
+
+The schema says **what** the API offers; the models already say **how** the data
+behaves. Nothing is described twice, and your domain logic stays where Rails puts it,
+in models, scopes, validations and policies, instead of moving into GraphQL resolvers.
+That is the same reason Lighthouse works so well on Eloquent: both are opinionated
+Active Record ORMs, and conventions are what make a declarative layer on top possible.
+
+## Ruby where there is real logic
+
+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).
+- `@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).
+
+Lighthouse is built on graphql-ruby, not instead of it: its Dataloader, its execution
+engine and its classes are all there when you need them.
+
+## From small apps to large ones
+
+The same schema serves a side project and a busy API. When it grows, opt-in features keep
+it fast without changing the schema: a cached schema build for quick boots, Apollo's
+persisted queries for CDN caching, and an allowlist of trusted operations. They are all
+off by default. See [Performance at scale](performance.md).
+
+## When something else fits better
+
+Lighthouse is at its best when the API is close to your models. Consider plain
+graphql-ruby, or using Lighthouse only for part of the schema, when:
+
+- the API is mostly computed, aggregated or fetched from other services, rather than read
+  from and written to your database;
+- your team prefers to define the schema in Ruby and generate the SDL from it
+  (code-first);
+- types differ so much from your tables that most fields would need their own resolver.
+
+Both approaches run on graphql-ruby, and a Lighthouse schema can call graphql-ruby
+classes anywhere, so you can start with directives and write Ruby where it pays off.
+
+Ready to try it? Continue with [Getting Started](getting-started.md).

data/docs/resolvers.md

@@ -152,6 +152,16 @@ are looked up in the builders namespace only. Raising a `GraphQL::ExecutionError
 from a builder (e.g. a tenancy check) always reaches the client; it never falls
 back to the unscoped relation.
 
+The gem ships RBS signatures in `sig/`, so with Steep (or anything that reads
+`rbs collection`) a builder can be checked against `Lighthouse::_Builder`:
+
+```rbs
+# sig/builders/published.rbs
+class Builders::Published
+  extend Lighthouse::_Builder
+end
+```
+
 ## Generators
 
 ```shell

data/lib/generators/lighthouse/builder_generator.rb

@@ -15,7 +15,7 @@ class Lighthouse::Generators::BuilderGenerator < Lighthouse::Generators::ClassGe
     <<~RUBY
       # Applied by @builder(class: "#{class_name}") before the field resolves:
       # receives the relation, the field's arguments and the GraphQL context, and
-      # returns the relation to use.
+      # returns the relation to use. Its type is Lighthouse::_Builder.
       class #{class_basename}
         def self.call(relation, args, context)
           relation

data/lib/lighthouse/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module GraphQL
-    VERSION = '0.2.0'
+    VERSION = '0.2.1'
   end
 end

data/sig/lighthouse/directives.rbs

@@ -0,0 +1,158 @@
+# The extension points for custom directives: the contracts a directive class
+# includes, the registry it is registered in, and the base classes it can
+# subclass. See docs/custom-directives.md.
+module Lighthouse
+  # What the registry asks a self-describing directive class: its SDL name
+  # (without the @) and its `directive @name(...) on ...` definition.
+  interface _DirectiveClass
+    def directive_name: () -> String
+    def definition: () -> String?
+  end
+
+  # Marker modules: the registry detects a class's capabilities by which of
+  # them it includes. Only FieldResolver and ArgBuilder change how a class is
+  # registered; the others document intent.
+  module Contracts
+    module Directive
+    end
+
+    # Its instances, built with (field_def, type_def, directive_node, opts),
+    # install the field's resolver in `define_resolver(target_type)`.
+    module FieldResolver
+      include Directive
+    end
+
+    # Its instances, built with (arg_node, directive_node), answer
+    # `handle_builder(relation, value)` with the constrained relation.
+    module ArgBuilder
+      include Directive
+    end
+
+    module FieldMiddleware
+      include Directive
+    end
+
+    module FieldManipulator
+      include Directive
+    end
+
+    module ArgManipulator
+      include Directive
+    end
+  end
+
+  class DirectiveRegistry
+    RESOLUTION_ORDER: Hash[String, Integer]
+    NAMED_RESOLVERS: Hash[String, Symbol]
+    SELF_DESCRIBING_RESOLVERS: Array[Symbol]
+    ARG_BUILDERS: Array[Symbol]
+    PASSIVE_DEFINITIONS: Hash[String, String]
+
+    def self.default: () -> DirectiveRegistry
+
+    # register(MyDirective) when the class answers `directive_name`, else
+    # register('name', MyDirective).
+    def self.register: (Class | String | Symbol name_or_klass, ?Class? klass) -> DirectiveRegistry
+
+    def initialize: () -> void
+    def register: (Class | String | Symbol name_or_klass, ?Class? klass) -> self
+    def register_defaults: () -> self
+    def register_definition: (String | Symbol name, String definition) -> self
+    def register_type_definition: (String | Symbol name, String definition) -> self
+    def register_manipulator: (_SdlManipulator manipulator) -> self
+
+    def resolution_class: (String | Symbol name) -> Class?
+    def resolution_order: (String | Symbol name) -> Integer
+    def wrapper?: (String | Symbol name) -> bool
+    def resolution_names: () -> Array[String]
+    def arg_builder_class: (String | Symbol name) -> Class?
+    def arg_builder_names: () -> Array[String]
+
+    # { "name" => "directive @name(...) on ..." }
+    def directive_definitions: () -> Hash[String, String]
+    # { "Name" => "enum Name { ... }" }
+    def type_definitions: () -> Hash[String, String]
+
+    attr_reader sdl_manipulators: Array[_SdlManipulator]
+    def manipulate_sdl: (String sdl) -> String
+  end
+
+  # Writes the SDL an IDE needs next to the app's own: `bin/rails lighthouse:ide_helper`.
+  module IdeHelper
+    DIRECTIVES_FILE: String
+    PROGRAMMATIC_TYPES_FILE: String
+
+    # Writes both files into `output_dir` and returns their paths.
+    def self?.write: (output_dir: path, ?sdl_folder: path?, ?registry: DirectiveRegistry) -> Array[String]
+    def self?.directives_sdl: (?String sdl, ?registry: DirectiveRegistry) -> String
+    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry) -> String
+  end
+
+  module GraphQL
+    module DirectiveResolvers
+      # The base of the built-in field directives, and of a custom one:
+      # subclass it and implement `define_resolver`.
+      class BaseDirectiveResolver
+        # graphql-ruby's field and type definitions, and the directive's AST node.
+        @field_def: untyped
+        @type_def: untyped
+        @directive_node: untyped
+        @opts: Hash[Symbol, untyped]
+
+        def initialize: (untyped field_def, untyped type_def, untyped directive_node, ?Hash[Symbol, untyped] opts) -> void
+
+        # Install the field's resolver on `target_type_class` (a graphql-ruby type class).
+        def define_resolver: (untyped target_type_class) -> untyped
+
+        def apply_where_filters: (relation relation, untyped args) -> relation
+        def apply_arg_builders: (relation relation, arguments args_h) -> relation
+        def extract_relation_name_from_directive: (untyped arg_node) -> String?
+        def constantize_model: (String? name) -> Class?
+        def apply_scopes: (relation relation) -> relation
+
+        # The literal value of an argument of this directive.
+        def directive_arg: (String name) -> untyped
+        def resolver_method_name: () -> String
+        # The field's resolver so far, for a directive that wraps it.
+        def capture_inner: (untyped target_type_class) -> untyped
+        def install: (untyped target_type_class, untyped callable) -> untyped
+        # The model the directive acts on; raises DefinitionError when there is none.
+        def model_class: () -> Class
+      end
+
+      # Applies the field's @builder directives, in SDL order, to its relation.
+      class BuilderApplier
+        DEFINITION: String
+
+        def self.apply: (relation relation, untyped field_def_ast_node, arguments args, context ctx, untyped resolver_instance) -> relation
+        def self.apply_directive: (relation relation, untyped directive_node, arguments args, context ctx, untyped resolver_instance) -> relation
+        def self.extract_directive_arg: (untyped directive_node, String name) -> untyped
+      end
+    end
+
+    module Directives
+      module Arguments
+        # The base of the argument filters (@eq, @in, @orderBy, ...), and of a
+        # custom one: subclass it and implement `handle_builder`.
+        class Base
+          include Contracts::ArgBuilder
+
+          # graphql-ruby's AST nodes for the argument and the directive on it.
+          @arg_node: untyped
+          @directive_node: untyped
+
+          def initialize: (untyped arg_node, untyped directive_node) -> void
+
+          # Constrain the relation by the value the client gave the argument.
+          def handle_builder: (relation relation, untyped value) -> relation
+
+          private
+
+          # The directive's `key:`, else the argument's name in snake_case.
+          def column: () -> String
+          def arel_column: (relation relation) -> untyped
+        end
+      end
+    end
+  end
+end

data/sig/lighthouse/graphql.rbs

@@ -0,0 +1,78 @@
+# The entrypoints: building the schema from SDL and running operations.
+module Lighthouse
+  module GraphQL
+    VERSION: String
+
+    Config: singleton(Lighthouse::Config)
+
+    # A GraphQL::Schema subclass.
+    type schema = untyped
+
+    module RbLightHouse
+      # The schema built from the SDL in `sdl_folder` (default: Config.sdl_folder).
+      # `options` takes :base_types, :base_schema and the schema's own options.
+      def self.get_schema: (?sdl_folder: path?, ?options: Hash[Symbol, untyped]) -> schema
+      def self.configure: () ?{ (singleton(Lighthouse::Config) config) -> void } -> void
+    end
+
+    module SchemaFactory
+      def self?.build_base_schema: (?sdl_folder: path?, ?sdl: String?, ?base_types: Hash[untyped, untyped],
+                                    ?schema_options: Hash[Symbol, untyped], **untyped extra_options) -> schema
+      def self?.load_sdl: (path? sdl_folder) -> String
+    end
+
+    # Apollo's Automatic Persisted Queries, and a manifest of trusted operations.
+    module PersistedQueries
+      HASH: Regexp
+      NOT_FOUND: Array[String]
+      NOT_SUPPORTED: Array[String]
+      HASH_MISMATCH: Array[String]
+      NOT_IN_LIST: Array[String]
+
+      # A request the protocol rejects, rendered with Apollo's error codes.
+      class Error < StandardError
+        attr_reader code: String
+
+        def initialize: (String message, String code) -> void
+        def to_h: () -> Hash[String, untyped]
+      end
+
+      # `extensions` as the request carries it: a Hash, a JSON String (GET) or
+      # ActionController::Parameters.
+      #
+      # `schema.execute` with the query the request names: its result, or a
+      # protocol error as a ready-to-render { "errors" => [...] } Hash.
+      def self?.execute: (schema schema, query: String?, ?extensions: untyped, **untyped options) -> untyped
+      # The query text to run for a request's `query` and `extensions`.
+      def self?.resolve: (String? query, untyped extensions) -> String?
+      def self?.enabled?: () -> bool
+      def self?.digest: (String query) -> String
+      # Store a query ahead of time (e.g. from a deploy task); returns its hash.
+      def self?.register: (String query) -> String
+    end
+
+    # The Cache-Control header the selected fields' @cacheControl hints allow.
+    module CacheControl
+      DEFINITION: String
+      TYPE_DEFINITIONS: Hash[String, String]
+      CONTEXT_KEY: Symbol
+
+      # For an executed query (a GraphQL::Query::Result or GraphQL::Query);
+      # nil when the schema does not use @cacheControl.
+      def self?.header: (untyped result) -> String?
+      # Set the header on a Rails (or Rack) response, and return it.
+      def self?.apply: (untyped response, untyped result) -> String?
+    end
+
+    # The opt-in cache of the manipulated schema document, in tmp/cache.
+    module SchemaCache
+      PREFIX: String
+
+      def self?.enabled?: () -> bool
+      def self?.directory: () -> path
+      # Build the schema document now and return the cache file's path.
+      def self?.warm!: (?String? sdl) -> String
+      def self?.clear!: () -> void
+    end
+  end
+end

data/sig/lighthouse.rbs

@@ -0,0 +1,142 @@
+# Signatures for the parts of Lighthouse an application implements or calls:
+# the classes a schema names (builders, validators), the configuration, the
+# directive extension points and the entrypoints. Internals are left out.
+#
+# graphql-ruby and Active Record ship no RBS every app has, so the values that
+# come from them are aliases of untyped, named for what they hold.
+module Lighthouse
+  # An ActiveRecord::Relation, or anything with its query interface.
+  type relation = untyped
+
+  # A field's arguments, with snake_case Symbol keys as graphql-ruby passes them.
+  type arguments = Hash[Symbol, untyped]
+
+  # The request's GraphQL::Query::Context.
+  type context = untyped
+
+  # A path on disk: a String or a Pathname.
+  type path = String | _ToPath
+
+  # A class `@builder(class: "Name")` names, looked up in Config.namespaces[:builders].
+  # It refines the relation of a field resolved by @all, @paginate, @first,
+  # @count or @aggregate and returns the relation to use; nil keeps the one it
+  # was given. `@builder(method:)` names a method other than `call`, with the
+  # same signature. The class answers it, or else an instance built with no
+  # arguments does. A GraphQL::ExecutionError it raises reaches the client.
+  interface _Builder
+    def call: (relation relation, arguments args, context context) -> relation?
+  end
+
+  # A @validator contract other than a Dry::Validation::Contract: it gets the
+  # arguments (snake_case Symbol keys) and answers the errors by key,
+  # { title: ["is missing"] }, nested for input objects; empty when valid.
+  interface _Validator
+    def call: (Hash[Symbol, untyped] values) -> Hash[Symbol | String, untyped]
+  end
+
+  # Config.on_error: called with an error a directive or resolver swallowed.
+  interface _ErrorHandler
+    def call: (StandardError error, context? context) -> void
+  end
+
+  # Config.authenticated_user and Config.policy_user: the user of a request.
+  interface _UserReader
+    def call: (context? context) -> untyped
+  end
+
+  # Config.authorizer: may `user` perform `ability` on `record` (a model
+  # instance, or a model class for @canModel)? `args` are the @can* `args:`,
+  # after the field's arguments with `injectArgs: true`.
+  interface _Authorizer
+    def call: (untyped user, untyped record, String | Symbol ability, ?Array[untyped] args) -> boolish
+  end
+
+  # What DirectiveRegistry#register_manipulator takes: it transforms the SDL
+  # before the schema is built.
+  interface _SdlManipulator
+    def manipulate: (String sdl) -> String
+  end
+
+  def self.configure: () ?{ (singleton(Config) config) -> void } -> void
+
+  module Config
+    DEFAULT_NAMESPACES: Hash[Symbol, Array[String]]
+    SETTINGS: Array[Symbol]
+
+    def self.configure: () ?{ (singleton(Config) config) -> void } -> void
+    def self.[]: (Symbol | String key) -> untyped
+    def self.reset!: () -> void
+
+    def self.sdl_folder: () -> path?
+    def self.sdl_folder=: (path? folder) -> path?
+
+    # { queries:, mutations:, builders:, validators: } => [namespace, ...].
+    # Assigning a partial hash overrides only the kinds it names.
+    def self.namespaces: () -> Hash[Symbol, Array[String]]
+    def self.namespaces=: (Hash[Symbol | String, String | Array[String]] overrides) -> Hash[Symbol | String, String | Array[String]]
+
+    def self.resolver_namespaces: () -> Array[String]
+    def self.resolver_namespaces=: (Array[String] namespaces) -> Array[String]
+
+    def self.directive_map: () -> Hash[untyped, untyped]
+
+    # An ActiveSupport::Cache::Store; Rails.cache by default.
+    def self.cache_store: () -> untyped
+    def self.cache_store=: (untyped store) -> untyped
+
+    def self.transactional_mutations: () -> bool
+    def self.transactional_mutations=: (bool? enabled) -> bool?
+
+    def self.pagination_default_count: () -> Integer?
+    def self.pagination_default_count=: (Integer? count) -> Integer?
+    def self.pagination_max_count: () -> Integer?
+    def self.pagination_max_count=: (Integer? count) -> Integer?
+
+    def self.schema_cache: () -> bool
+    def self.schema_cache=: (bool? enabled) -> bool?
+    def self.schema_cache_path: () -> path?
+    def self.schema_cache_path=: (path? path) -> path?
+    def self.watch_sdl: () -> bool
+    def self.watch_sdl=: (bool? enabled) -> bool?
+
+    def self.persisted_queries: () -> bool
+    def self.persisted_queries=: (bool? enabled) -> bool?
+    def self.persisted_queries_store: () -> untyped
+    def self.persisted_queries_store=: (untyped store) -> untyped
+    def self.persisted_queries_ttl: () -> Numeric?
+    def self.persisted_queries_ttl=: (Numeric? seconds) -> Numeric?
+    def self.persisted_queries_manifest: () -> path?
+    def self.persisted_queries_manifest=: (path? path) -> path?
+    def self.persisted_queries_only: () -> bool
+    def self.persisted_queries_only=: (bool? enabled) -> bool?
+
+    def self.on_error: () -> _ErrorHandler
+    def self.on_error=: (_ErrorHandler? handler) -> _ErrorHandler?
+    def self.handle_error: (StandardError error, ?context? context) -> void
+
+    def self.authenticated_user: () -> _UserReader
+    def self.authenticated_user=: (_UserReader? reader) -> _UserReader?
+    def self.policy_user: () -> _UserReader
+    def self.policy_user=: (_UserReader? reader) -> _UserReader?
+    def self.authorizer: () -> _Authorizer
+    def self.authorizer=: (_Authorizer? authorizer) -> _Authorizer?
+  end
+
+  # The schema refers to something that does not exist or breaks a contract.
+  class DefinitionError < StandardError
+  end
+
+  # A GraphQL::ExecutionError (declared from StandardError, which it descends
+  # from, as graphql-ruby ships no RBS): the @can* family denied the ability.
+  class AuthorizationError < StandardError
+    def initialize: (?String message, **untyped options) -> void
+  end
+
+  # A GraphQL::ExecutionError: invalid arguments, keyed by argument path
+  # ({ "input.title" => ["Title can't be blank"] }) under extensions.validation.
+  class ValidationError < StandardError
+    attr_reader messages: Hash[String, Array[String]]
+
+    def initialize: (String | Symbol field_name, Hash[String, Array[String]] messages) -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Vaz Innovation
@@ -62,6 +62,7 @@ files:
 - docs/federation.md
 - docs/filtering-and-ordering.md
 - docs/getting-started.md
+- docs/motivation.md
 - docs/mutations.md
 - docs/performance.md
 - docs/relationships.md
@@ -155,13 +156,16 @@ files:
 - lib/lighthouse/support/naming.rb
 - lib/lighthouse/tasks/lighthouse.rake
 - lib/lighthouse/where_conditions/operator_map.rb
+- sig/lighthouse.rbs
+- sig/lighthouse/directives.rbs
+- sig/lighthouse/graphql.rbs
 homepage: https://github.com/Vaz-Innovation/lighthouse-graphql
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/Vaz-Innovation/lighthouse-graphql
   changelog_uri: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/Vaz-Innovation/lighthouse-graphql/tree/main/docs
+  documentation_uri: https://vaz-innovation.github.io/lighthouse-graphql/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: