lighthouse-graphql 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44c0b7f96cdd9ba27384cff96408e10839eab552d11371d3d6fa977e646adcc7
-  data.tar.gz: c68872ac75f3233cec0bbefda727e50074fb1b81e7c39d7e11de782bf473f089
+  metadata.gz: 844e3fc4942a637b4353427932e031c210ad52d4d425161a58f45e2e36f1d931
+  data.tar.gz: 9b0b05109d1fcac2f330b7266fe91eb502d521dabce399adfd98828137119468
 SHA512:
-  metadata.gz: 613a4c6a0692f228bee57d8ab160c5c523a6b1660d99b1ad37ccbd38dcb51d7cdc30585642d9f40687183940e660349e14125a773a0b793579ba623e082299ac
-  data.tar.gz: 5fad77a3975ee0ed94da5db38258585f99227eecb8834e1264275801052e03073098c2b441ce53a38c3324f8044be46b0f79af095b0d65cffbac6cc3ddd6e122
+  metadata.gz: ef2d22dd33355e36e3b40725cea55ebf5923a06ea2c94660228d8cc6b3a6e222bd7da6f42f796d52275a2130c1ebd9e54844f85febf31d66a7a4c759d310723e
+  data.tar.gz: 7334b3e2b4ecb745fea9a4f9c08860d8e5c6245654323b0161a0b97c367d8ea022a3b23f7bd7e5bbd8c4e8614939b16e82fa737e9e133e4c5cba555199088c1d

data/CHANGELOG.md

@@ -6,6 +6,178 @@ 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
+
+- `rails generate lighthouse:install` sets a Rails app up: the initializer (every option,
+  commented out at its default), a starter schema, the schema class with
+  `GraphQL::Dataloader`, a `GraphqlController` and its route, and a `graphql.config.yml`
+  for IDEs. `--schema`, `--sdl-folder`, `--skip-controller` and `--skip-ide` adjust it;
+  rerunning it adds the route and `.gitignore` entries only once. It coexists with
+  graphql-ruby's `graphql:install`: an existing controller or schema class is kept unless
+  `--force` is given, and the route is written exactly as graphql-ruby writes it, so it is
+  never added twice in either order.
+- `bin/rails lighthouse:ide_helper` writes `schema-directives.graphql` (every registered
+  directive the SDL does not declare) and `programmatic-types.graphql` (the types the
+  manipulation phase generates) so IDEs can validate and autocomplete a Lighthouse
+  schema, as PHP Lighthouse's `lighthouse:ide-helper` does.
+- `DirectiveRegistry#register_definition` contributes the SDL definition of a directive
+  that has no class of its own; `register_type_definition` / a class's `type_definitions`
+  contribute the types such definitions refer to, injected alongside them.
+- **Queries, mutations and builders as separate kinds**, each with its own namespace
+  (`Config.namespaces`) and contract. 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`, `RelayClassicMutation`
+  included) — graphql-ruby's contract: `resolve(**args)`, `object`, `context`, `ready?`,
+  `authorized?`. `@field(resolver:)` on those roots looks in the same namespaces. `@builder`
+  classes live in `Builders::`. Generators: `lighthouse:query`, `lighthouse:mutation`,
+  `lighthouse:builder`, `lighthouse:validator`.
+- `@create`, `@createMany`, `@update`, `@updateMany`: save the returned model through
+  ActiveRecord, in a transaction (`Config.transactional_mutations`), reporting model
+  validation errors by argument path (`extensions.validation`, as in PHP Lighthouse).
+  `@spread` flattens an input into the arguments, `@inject(context:, name:)` sets
+  server-side values, `@rename` now also applies to arguments.
+- `@validator` (field or input type) runs a contract before the field resolves:
+  a `Dry::Validation::Contract` (optional dependency) or any `call(values)` returning
+  errors. Input-type validators apply wherever the type is used, nested and in lists.
+- The `@can*` family, Pundit by default: `@canFind`, `@canModel`, `@canQuery`,
+  `@canResolved`, `@canRoot`, with `injectArgs`, `args`, `action`
+  (`EXCEPTION_PASS` / `EXCEPTION_NOT_AUTHORIZED` / `RETURN_VALUE`) and `returnValue`. The
+  authorizer receives those arguments as a fourth parameter, only when there are any.
+- `@cache(maxAge:, private:)`, `@cacheKey` and `@clearCache(type:, idSource:, field:)` over
+  `Config.cache_store` (`Rails.cache`), invalidating through versioned keys so it works on
+  any store, including ones without `delete_matched`.
+- **Nested mutations**, PHP Lighthouse's API over ActiveRecord: an input field named after
+  an association carries `connect` / `create` / `update` / `upsert` / `disconnect` /
+  `delete` (belongs_to, polymorphic belongs_to, has_one, has_many) and `sync` /
+  `syncWithoutDetaching` (has_many :through, has_and_belongs_to_many — with pivot columns on a
+  `:through` join model), to any depth. Each record is saved once; errors are keyed by the full
+  input path. `@create` / `@update` / `@upsert` / `@delete(relation:)` on an argument run one
+  operation on an association.
+- `@upsert` / `@upsertMany` (by primary key or `identifyingColumns`) and `@delete` (by the
+  field's filter arguments; refuses to delete without one), and the `@whereKey` filter.
+- `@paginate(type: PAGINATOR | SIMPLE | CONNECTION, scopes:, defaultCount:, maxCount:)` and
+  `type:` on `@hasMany` / `@belongsToMany` / `@morphMany` / `@morphToMany`, generating PHP
+  Lighthouse's types and arguments (`first`, `page`, `after`; `PaginatorInfo`,
+  `SimplePaginatorInfo`, `PageInfo` with `total` / `count` / `currentPage` / `lastPage`). The total
+  is only counted when selected. `Config.pagination_default_count` / `pagination_max_count`.
+- `@morphTo`, `@morphOne`, `@morphMany`, `@morphToMany` (ActiveRecord polymorphic
+  associations), and `scopes:` on every relationship directive.
+- The integration suites of PHP Lighthouse for nested mutations (belongsTo, hasOne, hasMany,
+  belongsToMany, morphTo, morphOne, morphMany, morphToMany), the model mutation directives,
+  `@all` and `@paginate`, ported to RSpec against the same models (spec/integration).
+- **Opt-in options for large schemas and high traffic**, all off by default (docs/performance.md):
+  - `config.schema_cache` caches the built schema document in `tmp/cache/lighthouse`, Bootsnap
+    style: content-addressed (SDL, versions, registered directives, manipulator source, config),
+    so it invalidates itself; atomic writes; `bin/rails lighthouse:cache` / `lighthouse:clear_cache`.
+    About 1.8x faster schema builds on large schemas.
+  - `config.watch_sdl` adds the SDL folder to Rails' watched dirs, so editing a `.graphql` file
+    reloads the schema in development (it previously needed a server restart).
+  - `config.persisted_queries`: Apollo-compatible Automatic Persisted Queries
+    (`PersistedQueries.execute`, used by the generated controller), with a TTL, a store, a
+    manifest of trusted operations (Apollo's format or `{ sha256 => query }`) served from memory,
+    `persisted_queries_only` as an allowlist, and `bin/rails lighthouse:persisted_queries:verify`
+    to check the manifest against the schema in CI.
+- `@cacheControl(maxAge:, scope:, inheritMaxAge:)` computes the response's `Cache-Control`
+  header from the selected fields (PHP Lighthouse's / Apollo's rules);
+  `Lighthouse::GraphQL::CacheControl.apply(response, result)` sets it, and the generated
+  controller calls it.
+- `example/`: a Rails 8.1 blog API built with Lighthouse, which is both an example to
+  read and the end-to-end suite. Its specs go through the real `/graphql` endpoint:
+  queries, pagination, relationships without N+1, `@guard` and the `@can*` family with
+  Pundit, mutations (nested ones included), validation, `@cache`/`@cacheControl`,
+  persisted queries over `GET`, and the rake tasks. CI runs it.
+- RuboCop (with rubocop-rails, -rspec, -performance and -factory_bot) lints the gem and
+  the example app; CI runs it, and `rake` runs it after the suite.
+- **Paginated relations no longer query once per parent.** `@hasMany`,
+  `@belongsToMany`, `@morphMany` and `@morphToMany` with `type:`, and `@paginate` on a
+  nested field, load every parent's page in one query (a `ROW_NUMBER()` window
+  partitioned by parent) and every total in one `GROUP BY`, only when a total is
+  selected. Databases without window functions keep loading one parent at a time. See
+  docs/relationships.md.
+
+### Fixed
+
+- `@whereConditions`' `AND`, `OR` and `HAS` were ignored when they came from a query.
+  graphql-ruby hands input objects over with Ruby-style keys (`:and`, `:or`, `:has`), and
+  only the upper-case keys were read, so a nested condition matched every record.
+- `scopes:` was declared but ignored by `@count` and `@first`; `@all` now accepts it too.
+- The default resolver discarded the result of a generated three-argument resolver
+  (`resolve_field_<name>(obj, args, ctx)`) and fell through to reading the attribute.
+- Used standalone (without Rails), the gem missed ActiveSupport's `Enumerable` and
+  `String#exclude?` extensions it relies on (`index_by`, `pluck`, `exclude?`).
+
+- Every built-in directive now contributes its SDL definition. `@all`, `@find`,
+  `@paginate`, `@hasMany`, `@belongsTo`, `@belongsToMany`, `@aggregate`, `@field`,
+  `@auth`, `@builder`, `@whereConditions` and `@whereHasConditions` had none, so a schema
+  that used one without declaring it failed to build — contrary to the docs.
+- `@find` without `model:` found nothing: it inferred the model from the return type's
+  Ruby class name, which is `nil` for SDL-built types, instead of its GraphQL name.
+- `@find` returned `null` for existing records when batched through the Dataloader: `ID`
+  arguments arrive as strings and were looked up against integer primary keys.
+- Wrapping directives (`@guard`, ...) on a field without a resolving directive called
+  graphql-ruby's internal resolver with the wrong arity instead of the default reader.
+- The gem now requires `graphql` itself instead of relying on the app to load it first.
+- `@all` on a list field returned `nodes: null`: the field was rewritten to a connection the
+  resolver never built. `@all` now returns the list, as in PHP Lighthouse; it also resolved
+  `model:` ignoring `resolver_namespaces` and stripping the namespace (`Admin::User` → `User`).
+- `@paginate` ignored the field's argument filters (`@eq`, `@like`, ...), took no `first` /
+  `page` arguments as a paginator, and returned `nodes: null` as a connection.
+- `@find` ignored every argument but `id`; it now applies the argument filters and errors on
+  more than one match.
+- The relationship directives' Dataloader source loaded each parent's association separately
+  (N+1); it now batches with ActiveRecord's preloader.
+- The relationship directives and `@find` raised "Dataloader is not running" on schemas without
+  `GraphQL::Dataloader`; they now load directly there.
+- Generated pagination wrappers made every paginated field `no-cache` under `@cacheControl`;
+  they now inherit the parent's maxAge, as in PHP Lighthouse.
+- An explicit `null` directive argument (`@paginate(maxCount: null)`) failed to build the
+  schema: graphql-ruby passes it on as a NullValue node. Lighthouse maps it to nil.
+
+### Removed
+
+- **`@can`** — replaced by the `@can*` family. `@can(ability:)` becomes `@canResolved`,
+  `root: true` becomes `@canRoot`, `find:` / `model:` become `@canFind`; see the migration
+  table in docs/authorization.md. Schemas still using `@can` fail to build.
+
+### Changed
+
+- **`@hasMany` and `@belongsToMany` return plain lists**, as in PHP Lighthouse, instead of
+  connections. Pass `type: CONNECTION` (or `PAGINATOR` / `SIMPLE`) to paginate; clients that
+  selected `edges` / `nodes` on them need the `type:`.
+- Paginated fields follow PHP Lighthouse: a paginator takes `first: Int!` (defaulted by
+  `defaultCount`) and `page`, a connection `first: Int!` and `after`, and returns non-null.
+- `@paginate`'s `type:` is the `PaginateType` enum (`PAGINATOR`, `SIMPLE`, `CONNECTION`); the
+  string form still works at runtime.
+- `@builder` classes are looked up in `Config.namespaces[:builders]` (`Builders::`) instead of
+  `resolver_namespaces`. Fully-qualified names work as before.
+- `@field(resolver:)` on `Query` / `Mutation` looks in the queries / mutations namespaces;
+  elsewhere still in `resolver_namespaces`.
+- `@aggregate`'s `function:` is declared as `String`. Enum
+  literals (`function: SUM`) still work at runtime, but IDEs expect strings
+  (`function: "SUM"`).
+
 ## [0.1.1] - 2026-09-23
 
 Release tooling only: the library is unchanged from `0.1.0`. The packaged gem differs because
@@ -56,6 +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.1.1...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
 
@@ -63,8 +63,36 @@ gem 'lighthouse-graphql'
 It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 `apollo-federation` in your app (it is an optional, app-provided dependency).
 
+Then let the generator set the app up:
+
+```shell
+bin/rails generate lighthouse:install
+```
+
+It creates the initializer, a starter schema in `graphql/schema.graphql`, the
+`AppSchema` class, a `GraphqlController` with its `POST /graphql` route, and a
+`graphql.config.yml` for your IDE. Run `bin/rails generate lighthouse:install --help`
+for its options (`--schema`, `--sdl-folder`, `--skip-controller`, `--skip-ide`).
+
+### IDE support
+
+Lighthouse's directives and the types it generates (Paginator/Connection types,
+`whereConditions` inputs, …) are defined in Ruby, so your IDE can't see them in
+your `.graphql` files. Write them out for it:
+
+```shell
+bin/rails lighthouse:ide_helper
+```
+
+This writes `schema-directives.graphql` and `programmatic-types.graphql` to the app
+root; the generated `graphql.config.yml` already points the GraphQL plugins for
+JetBrains IDEs and VS Code at them. Rerun it after changing your schema or
+registering a directive. See [docs/getting-started.md](docs/getting-started.md#ide-support).
+
 ## Quick start
 
+Prefer to wire it by hand? These are the steps the generator performs.
+
 1. **Put your SDL** in `app/graphql` or any folder (default: `RAILS_ROOT/graphql`),
    split across as many `.graphql` files as you like:
 
@@ -103,17 +131,33 @@ It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 See **[docs/getting-started.md](docs/getting-started.md)** for the full setup,
 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,
+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).
+
 ---
 
 ## 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` and batching |
+| [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` |
-| [Authentication & authorization](docs/authorization.md) | `@guard`, `@can` (policy-based, Pundit by default) |
+| [Queries, mutations & builders](docs/resolvers.md) | `Queries::` / `Mutations::` 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) |
+| [Performance at scale](docs/performance.md) | Opt-in schema cache, SDL reloading in development, persisted queries (APQ) and trusted-document allowlists |
+| [Caching](docs/caching.md) | `@cache`, `@cacheKey`, `@clearCache` (Rails.cache), `@cacheControl` (HTTP) |
 | [Apollo Federation](docs/federation.md) | `@key`, `resolve_reference`, the `ReferenceResolver` registry |
 | [Custom directives](docs/custom-directives.md) | The contracts, the registry, writing your own directive |
 | [Configuration](docs/configuration.md) | `Lighthouse.configure`, namespaces, error handling |

data/docs/authorization.md

@@ -1,109 +1,168 @@
 # Authentication & Authorization
 
-Lighthouse lets you enforce **authentication** and **authorization** declaratively
-in your schema with the `@guard` and `@can` directives — instead of hand-writing
-a resolver whose only job is a policy check. This mirrors PHP Lighthouse's
-`@guard` / `@can*` family, adapted to Ruby and your authorization library (Pundit
-by default).
+Enforce **authentication** and **authorization** declaratively in your schema,
+instead of in resolvers whose only job is a policy check. `@guard` requires a
+user. The `@can*` family checks a policy ability, Pundit by default. This is PHP
+Lighthouse's v6 design, which replaced its single `@can` with one directive per
+*thing being authorized*.
 
 ## Configuration
 
-The library is framework-agnostic: how it reads the current user and how it
-checks an ability are both configurable. The defaults work with a Rails app that
-puts `current_user` / `pundit_user` in the GraphQL context and uses Pundit, so
-**typically no configuration is needed**:
+The defaults work with a Rails app that puts `current_user` (or `pundit_user`)
+in the GraphQL context and uses Pundit, so **typically no configuration is
+needed**:
 
 ```ruby
 Lighthouse.configure do |config|
   # The authenticated user (nil if none). Default:
   config.authenticated_user = ->(ctx) { ctx[:current_user] }
 
-  # The "user" passed to the authorizer. Default: ctx[:pundit_user], falling back
-  # to the authenticated user.
+  # The "user" handed to policies. Default: ctx[:pundit_user], else the authenticated user.
   config.policy_user = ->(ctx) { ctx[:pundit_user] }
 
-  # How an ability is checked. Default uses Pundit:
-  config.authorizer = ->(user, record, ability) { Pundit.policy!(user, record).public_send("#{ability}?") }
+  # How an ability is checked. Default (Pundit):
+  config.authorizer = ->(user, record, ability, args = []) do
+    Pundit.policy!(user, record).public_send("#{ability}?", *args)
+  end
 end
 ```
 
-Point `authorizer` at any system (CanCanCan, ActionPolicy, a plain lambda) to use
-something other than Pundit.
+Point `authorizer` at any system (CanCanCan, ActionPolicy, a lambda) to use
+something else. It receives `args` only when a directive passes some, so a
+three-argument authorizer keeps working for checks without them.
 
 ## `@guard` — require authentication
 
-Require an authenticated user before a field resolves. Raises `Unauthenticated.`
-otherwise.
+Raises `Unauthenticated.` when there is no user. It runs before everything else
+on the field.
 
 ```graphql
 type Query {
-  me: User @field(resolver: "Resolvers::CurrentUser") @guard
+  me: User @guard
 }
 ```
 
-`@guard` runs **outermost** — before any other directive on the field.
+## The `@can*` family
 
-## `@can` — authorize with a policy
+Each directive checks `ability` with the policy, e.g. `PostPolicy#update?` for
+`ability: "update"`. They differ in what they authorize:
 
-Check a policy ability. By default it authorizes the **resolved record**: the
-field resolves first, then `@can` checks the ability against the result (and
-raises if denied). `nil` results pass through; collections are left to scoping.
+| Directive | Authorizes | Typical use |
+| --- | --- | --- |
+| `@canModel` | the model **class** | `create?` before `@create` |
+| `@canFind` | the models whose keys an argument holds | `update?` before `@update` |
+| `@canQuery` | the models the field's argument filters select | bulk reads or writes |
+| `@canResolved` | what the field resolved to (each item of a list) | read-only fields |
+| `@canRoot` | the parent object | a sensitive field on a type |
 
 ```graphql
 type Query {
-  # Resolve the (account-scoped) contact, then authorize ContactPolicy#show?
-  contact(id: ID!): Contact
-    @field(resolver: "Resolvers::ContactResolver")
-    @can(ability: "show")
+  post(id: ID! @eq): Post @find @canResolved(ability: "show")
+  draftCount(authorId: ID @eq): Int @count(model: "Post") @canQuery(ability: "show")
+}
+
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post @create @canModel(ability: "create")
+  updatePost(input: UpdatePostInput! @spread): Post @update @canFind(ability: "update", find: "input.id")
+}
+
+type User {
+  email: String @canRoot(ability: "view_email")
 }
 ```
 
+With Pundit, `@canFind(ability: "update", find: "input.id")` loads the post and
+calls `PostPolicy.new(pundit_user, post).update?`. `@canModel(ability: "create")`
+calls `PostPolicy.new(pundit_user, Post).create?`.
+
+All of them run **before** the field resolves, except `@canResolved`. That one
+needs the result, so use it only on fields that do not change data.
+
+### Arguments
+
+Every `@can*` directive takes:
+
+| Argument | Meaning |
+| --- | --- |
+| `ability: String!` | The policy method, without `?` |
+| `injectArgs: Boolean = false` | Pass the field's arguments (a Hash) to the policy method |
+| `args: CanArgs` | Static values passed after them, e.g. `args: 2` or `args: ["a", "b"]` |
+| `action: CanAction = EXCEPTION_PASS` | What a denial does (below) |
+| `returnValue: CanArgs` | The value returned for `action: RETURN_VALUE` |
+
 ```ruby
-# The resolver is now just a scoped finder — no authorization boilerplate.
-module Resolvers
-  class ContactResolver
-    def self.call(_obj, args, ctx)
-      account = ctx[:current_account]
-      account.contacts.find_by(id: args[:id]) || raise(GraphQL::ExecutionError, 'Contact not found.')
-    end
+class PostPolicy < ApplicationPolicy
+  def publish?(args)      # @canFind(ability: "publish", find: "id", injectArgs: true)
+    user.admin? && args[:title] != record.title
+  end
+
+  def edit?(level)        # @canFind(ability: "edit", find: "id", args: 2)
+    user.level >= level
   end
 end
 ```
 
-With Pundit, `@can(ability: "show")` calls `ContactPolicy.new(pundit_user, contact).show?`.
+Plus, per directive:
 
-### Other modes
+- `@canFind(find: String!, model: String, findOrFail: Boolean = true, scopes: [String!])`.
+  `find` is the argument holding the primary key or keys, and may be a dot path
+  (`"input.id"`). A key that matches no record fails with
+  `Couldn't find Post with 'id'=…`, unless `findOrFail: false`. `scopes` are model
+  scopes applied to the lookup.
+- `@canModel(model: String)`.
+- `@canQuery(model: String, scopes: [String!])`. `scopes` narrow the records
+  being authorized, not the field's result.
 
-```graphql
-# Authorize against the parent object (e.g. restrict a field on a type):
-type User {
-  email: String! @can(ability: "view_email", root: true)
-}
+The model defaults to the `model:` of another directive on the field (as in
+`@count(model: "Post") @canQuery`), then to the field's return type.
 
-# Find a model by an argument and authorize it before resolving:
-type Mutation {
-  archivePost(id: ID!): Post @can(ability: "update", find: "id", model: "Post") @field(resolver: "...")
-}
+### `action`: what a denial does
+
+| `action` | Result |
+| --- | --- |
+| `EXCEPTION_PASS` (default) | The error reaches the client: `This action is unauthorized.`, or `@canFind`'s not-found message |
+| `EXCEPTION_NOT_AUTHORIZED` | Always `This action is unauthorized.`, which hides whether a record exists |
+| `RETURN_VALUE` | The field returns `returnValue` instead of resolving |
+
+```graphql
+post(id: ID!): Post @canFind(ability: "show", find: "id", action: EXCEPTION_NOT_AUTHORIZED)
 ```
 
-`@can` is `repeatable`, so you can require multiple abilities.
+`action` applies to the directive's own checks only. Errors from the resolver
+itself are untouched.
+
+## Ordering
+
+The order you write directives in does not matter. They run as:
+
+1. `@guard` / `@auth` (authentication)
+2. `@canFind`, `@canModel`, `@canQuery`, `@canRoot` (and the check of `@canResolved`, after the resolver)
+3. `@validator` (see [validation.md](validation.md))
+4. `@cache`, then the resolver
+
+So a cached value is still authorized on every request.
 
 ## Multi-tenancy vs. authorization
 
 Keep the two layers distinct:
 
-- **Tenancy / scoping** (which account's records are visible) belongs in your
-  resolver or an `@builder` — e.g. `account.contacts`. This is application-specific.
-- **Authorization** (may this user perform this action on this record) belongs in
-  `@can` + your policies.
+- **Tenancy / scoping** decides which account's records are visible. It belongs in
+  a [builder](resolvers.md#builders) or query class, e.g. `account.posts`.
+- **Authorization** decides whether this user may do this to this record. It
+  belongs in `@can*` and your policies.
 
-For list fields, filter with a policy **scope** in a builder (e.g. Pundit's
-`policy_scope`) rather than authorizing item-by-item.
+For lists, scope with a builder (e.g. Pundit's `policy_scope`) rather than
+authorizing item by item.
 
-## Ordering
+## Migrating from `@can`
+
+`@can` is gone. Its modes map one to one:
 
-When several wrapping directives are on one field, they run in this order:
+| Before | After |
+| --- | --- |
+| `@can(ability: "show")` | `@canResolved(ability: "show")` |
+| `@can(ability: "view_email", root: true)` | `@canRoot(ability: "view_email")` |
+| `@can(ability: "update", find: "id", model: "Post")` | `@canFind(ability: "update", find: "id", model: "Post")` |
 
-1. `@guard` / `@auth` (authentication) — outermost
-2. `@can` (authorization of the resolved value)
-3. the field's data resolver (`@field`, `@all`, `@hasMany`, …) — innermost
+One difference: `@canResolved` authorizes **each item** of a list. `@can` skipped
+lists.

data/docs/best-practices.md

@@ -40,8 +40,21 @@ Without it, nested relationships re-introduce N+1 queries.
 
 ## Authorize at the field, early
 
-Use `@auth` (and your own authorization directives) on fields that require it.
-Because `@auth` wraps the resolver, the check runs before any data is loaded.
+Use `@guard` and the `@can*` directives on fields that require them. They wrap the
+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).
+
+## Validate in the model first
+
+Model validations already cover `@create` / `@update`. Reach for `@validator` only
+for rules that aren't the model's. See [validation.md](validation.md).
 
 ## Mutations: prefer throwable errors
 
@@ -62,7 +75,7 @@ end
 
 ## One configuration seam
 
-Keep all Lighthouse wiring — `resolver_namespaces`, custom directive
+Keep all Lighthouse wiring — `namespaces`, `resolver_namespaces`, custom directive
 registration, federation reference resolvers, `on_error` — in initializers, not
 scattered through the app. This keeps the library a clean dependency and makes the
 app's GraphQL setup easy to find.