rigortype 0.3.9 → 0.4.0

data/docs/manual/plugins/rigor-active-model-serializers.md

@@ -0,0 +1,153 @@
+# rigor-active-model-serializers
+
+Teaches Rigor what `object` is inside an ActiveModel::Serializer
+subclass, so the reads below it — `object.username`,
+`object.account.display_name` — resolve against your model instead of
+dispatching on an unknown receiver. It reads source only; no
+ActiveModelSerializers runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`, alongside
+`rigor-activerecord`, which is what tells this plugin which models exist
+and what they answer:
+
+```yaml
+plugins:
+  - rigor-activerecord
+  - rigor-active-model-serializers
+```
+
+## What it does — no diagnostics
+
+The plugin emits nothing of its own. It contributes one return type and
+the gem's framework constants, so that
+
+```ruby
+class REST::AccountSerializer < ActiveModel::Serializer
+  attributes :id, :username, :display_name
+
+  def display_name
+    object.display_name
+  end
+end
+```
+
+types `object` as `Account`, and `object.display_name` as the
+`accounts.display_name` column's type. What you notice is the diagnostics
+that now CAN fire — a typo below a serializer's `object` used to be
+invisible:
+
+```text
+app/serializers/errors_serializer.rb:11:23: error: undefined method `nickname' for String [call.undefined-method]
+```
+
+and `rigor coverage` reporting a larger share of `app/serializers` as
+precise. On Mastodon that share went from 51.1 % to 53.2 % with no change
+at all to the diagnostic set
+([the measurement](../../notes/20260917-ams-object-recognizer.md)).
+
+## When `object` is typed, and when it is not
+
+Nothing in a serializer's source states which class it serializes — AMS
+binds the resource when the serializer is constructed. So the type is
+always DERIVED, and two independent things have to agree before the
+plugin contributes one:
+
+1. **The name resolves.** `<Model>Serializer` names exactly one model
+   your project has — `REST::AccountSerializer` → `Account`.
+2. **The model answers the serializer.** Every name the serializer will
+   read off its resource — the `attributes` / `attribute` / `has_many` /
+   `has_one` / `belongs_to` declarations it does not define itself, plus
+   every `object.<name>` in its body — is a column, per-column predicate,
+   association, enum, alias, scope or macro-defined method of that model,
+   or a method your project defines on it or an ancestor.
+
+One unanswered name declines the whole serializer, because the resource
+is then something else — commonly a presenter or a decorator around the
+model, which shares most of its surface and is given away by the one or
+two names that differ. On Mastodon that check is what stops
+`REST::ConversationSerializer` typing as `Conversation` when its resource
+is an `AccountConversation`.
+
+| your code | `object` types as |
+| --- | --- |
+| `REST::AccountSerializer`, `Account` exists and answers it | `Account` |
+| `Admin::AccountSerializer`, where `Admin::Account` and `Account` both exist | unchanged — the reading is ambiguous and nothing here ranks one above the other |
+| `ConversationSerializer` whose declarations `Conversation` cannot answer | unchanged (`Dynamic`) |
+| a serializer that reads nothing off its resource | unchanged — there is nothing to check the name against |
+| `ContextSerializer`, and no `Context` **model** exists | unchanged (`Dynamic`) |
+| a serializer you listed in `model_overrides` | the model you named |
+| `object` written outside a serializer, or over your own `def object` | unchanged (`Dynamic`) |
+
+A serializer is a class under `serializer_search_paths` whose superclass
+chain reaches `ActiveModel::Serializer` — including through your own base
+serializer (`class ApplicationSerializer < ActiveModel::Serializer`, then
+`class AccountSerializer < ApplicationSerializer`). A class the chain does
+not reach is not a serializer here whatever it is called: `object` is an
+ordinary method name, and a `Json::ConversationSerializer` of your own is
+entitled to define it.
+
+`class << self` and `def self.` bodies are left alone. An `object` read
+there is a `NoMethodError` at run time — AMS's reader is an instance
+method — so there is nothing to type and nothing the plugin should say
+about it.
+
+**The plugin never guesses.** Where the resource cannot be established it
+contributes nothing and `object` keeps the answer it had, because a wrong
+class here would turn every read on it into a false
+`call.undefined-method` on working code.
+
+It also does nothing at all without `rigor-activerecord`, or on a project
+with no `db/schema.rb` / `db/structure.sql`: the model set it resolves and
+checks against comes from that plugin, and is withheld when the schema is
+missing.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-active-model-serializers
+    config:
+      serializer_search_paths: ["app/serializers", "app/lib"]
+      serializer_base_classes: ["ActiveModel::Serializer"]
+      model_overrides:
+        REST::InstanceSerializer: InstancePresenter
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `serializer_search_paths` | `["app/serializers", "app/lib"]` | Where to look for serializer classes. `app/lib` is in the default set because a base serializer routinely lives outside `app/serializers` — Mastodon's `ActivityPub::Serializer`, the parent of 60 of its serializers, is one. A directory you do not have costs one probe. |
+| `serializer_base_classes` | `["ActiveModel::Serializer"]` | The roots the ancestry walk starts from. |
+| `model_overrides` | `{}` | Serializer class name → resource class name, for a serializer the derivation cannot reach — a presenter, a decorator, or a class named for a JSON shape. Your assertion; it is not re-checked. |
+
+## Limitations
+
+- **SimpleForm inputs.** `SimpleForm::Inputs::Base#object` shares the name
+  and nothing else — its resource comes from the `simple_form_for` call
+  site, not from the input class.
+- **`serializer:` / `each_serializer:` options.** They name the
+  serializer for an association, never the model for a serializer.
+- **Model surface your schema and source do not state.** A method the
+  model gets from `method_missing`, from a gem's macro `rigor-activerecord`
+  does not recognise, or from a module included at runtime is invisible to
+  the model index, so a serializer reading one is declined.
+  `rigor-activerecord` reads `delegate`, the associations a concern
+  declares in its `included do`, the Paperclip / Active Storage attachment
+  macros and `enum` value predicates
+  ([#1049](https://github.com/rigortype/rigor/issues/1049)); anything else
+  a macro defines is not folded yet.
+- **Some ways of reading the resource.** `object[:key]`, `object.title =`,
+  `object.try(:name)`, `object.present?` and an `attribute(:x) { ... }`
+  block are not read as evidence, so a serializer using one may decline
+  even where the model is right. Always the safe direction — a decline,
+  never a wrong type.
+- **Serializers for plain objects** — `ActiveModelSerializers::Model`
+  subclasses, Structs, presenters. Use `model_overrides` where the class
+  you want is a real constant you are happy to have checked.
+
+## Plugin internals
+
+The serializer discoverer / index, the ancestry closure and the contract
+surfaces this plugin exercises are in the
+[plugin's README](../../../plugins/rigor-active-model-serializers/README.md).
+To write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-activejob.md

@@ -95,6 +95,13 @@ nothing loads Solid Queue.
   evidence. A schedule loaded from Ruby rather than from a file under
   `recurring_paths` supplies nothing, by the same "read only what is
   written" rule.
+- **The "failed to discover jobs" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-activerecord.md

@@ -29,13 +29,21 @@ errors_demo.rb:24:1: error: `User.find` expects at least 1 argument, got 0 [plug
 | --- | --- | --- |
 | Recognised `Model.find` / `Model.find_by` / `Model.where` call | `:info` | `plugin.activerecord.model-call` |
 | `Model.find_by(unknown: ...)` / `Model.where(unknown: ...)` | `:error` | `plugin.activerecord.unknown-column` |
-| `Model.find` with 0 args | `:error` | `plugin.activerecord.wrong-arity` |
+| `Model.find` with 0 args and no block (unless the model defines `self.find`) | `:error` | `plugin.activerecord.wrong-arity` |
 | No schema source (`db/schema.rb` or `db/structure.sql`) present — reduced mode | `:info` | `plugin.activerecord.load-error` |
 | A schema source that exists but cannot be read or parsed | `:warning` | `plugin.activerecord.load-error` |
 
 Did-you-mean suggestions use `DidYouMean` fuzzy matching against
 the resolved table's column names.
 
+A model that defines its own `self.find` owns that method's arity.
+The plugin reports no `wrong-arity` for it, and no note for the
+several-id or block form, where the call types as the model's
+method rather than Rails' `find`. A single id is still noted as the
+model, which is how it types. In an editor, a `self.find` in the
+same file is not yet seen here, so the note and the error still
+appear there ([#1329](https://github.com/rigortype/rigor/issues/1329)).
+
 ## Configuration
 
 ```yaml
@@ -61,8 +69,17 @@ All keys are optional. Tweak them when:
 ## What it infers
 
 The plugin contributes call-site types as well as diagnostics.
-Class-side: `User.find(1)` → `User`, `User.find_by(...)` →
-`User | nil`, `User.find_by!(...)` → non-nullable `User`.
+Class-side: `User.find(1)` → `User`, `User.find(1, 2)` →
+`Array[User]`, `User.find_by(...)` → `User | nil`,
+`User.find_by!(...)` → non-nullable `User`. A single argument
+stays `User` even when it is an Array (`User.find([1, 2])`), so
+that an untyped one, such as `params[:id]`, keeps the model type.
+A relation or association (`user.posts.find(1, 2)`) answers the
+same way. With a block, `find` is `Enumerable#find` over the
+records, on the class and on a relation alike:
+`User.find { |u| u.admin? }` → `User | nil`, and it takes no id.
+The block's parameter is the model on a relation; on the class
+side it stays untyped.
 Instance-side: a column read (`user.name`) narrows to the
 column's value type, `user.admin?` to `bool`, and a singular
 association (`post.user`) to the target model.
@@ -76,6 +93,71 @@ Chained query methods keep the element type, and iteration
 scope invoked on a typed relation (`User.where(...).published`)
 never surfaces a false `call.undefined-method`.
 
+A `scope` declared inside a concern's `included do ... end` block
+counts as the including model's own. `Account.without_suspended`
+types as `ActiveRecord::Relation[Account]` when `Account` includes
+the concern that declares the scope — directly, or through another
+concern that concern includes. A concern included once in your
+base class (`ApplicationRecord`) reaches every model under it.
+Attribution follows the `include` you wrote, not the name: a
+model that includes nothing gets nothing, whatever some other
+concern in the project declares.
+
+The gate is the `included do ... end` block itself. A scope
+declared some other way — in a `class_methods do` block, a
+hand-written `def self.included(base)` with `base.class_eval`, or
+directly in the body of your base class rather than in a concern —
+is not folded, and the call stays as untyped as it was.
+
+`belongs_to` / `has_one` / `has_many` /
+`has_and_belongs_to_many` declared in that same `included do ...
+end` block count as the including model's own too, with the same
+`include`-edge attribution: `account.user` narrows to
+`User | nil` when `Account` includes the concern that declares
+`has_one :user`, and `where(user: ...)` stops reporting a false
+`unknown-column`. A model that declares the association itself
+keeps its own version.
+
+### The names a macro defines
+
+Three macro families define ordinary instance methods that are
+neither columns nor associations, and the model's recorded
+surface now carries their names:
+
+- `delegate :followers_count, to: :account_stat` — every
+  delegated name, including the `prefix:` spellings
+  (`delegate :can?, to: :user, prefix: true` defines
+  `user_can?`). `delegate` is read from the model body, from a
+  concern's `included do ... end`, and from a concern's own
+  top level, where it defines an instance method the including
+  model inherits.
+- Attachment macros — Paperclip's `has_attached_file :avatar`
+  (`avatar`, `avatar=`, `avatar?`) and Active Storage's
+  `has_one_attached` / `has_many_attached` (`banner`,
+  `banner_attachment`, `banner_blob`; `docs`,
+  `docs_attachments`, `docs_blobs`). Paperclip's
+  `avatar_file_name` / `avatar_content_type` / `avatar_file_size`
+  / `avatar_updated_at` are real columns, so they come from your
+  schema rather than from the macro.
+- `enum` value predicates — `enum :visibility, { limited: 4 },
+  suffix: :visibility` defines `limited_visibility?`, and
+  `prefix:` / `_prefix:` / `_suffix:` are read the same way. An
+  `enum` declared `instance_methods: false` defines none of
+  them, and none are recorded.
+
+These are recorded as NAMES. Nothing here says what a delegated
+method returns, and the plugin contributes no type for one — the
+value is that a consumer asking "does this model answer
+`followers_count`?" gets the right answer. The consumer this was
+built for is
+[`rigor-active-model-serializers`](rigor-active-model-serializers.md),
+which types a serializer's `object` only when the candidate model
+answers every name the serializer reads.
+
+A declaration this plugin cannot read off the source contributes
+nothing rather than a guess: a `prefix: true` whose `to:` is a
+method call, a non-literal `prefix:`, a computed enum value list.
+
 If the project also installs `activerecord` through
 `rbs collection install`, the collection declares
 `ActiveRecord::Relation` without a type parameter while the
@@ -182,12 +264,25 @@ close every model in the project.
   the column-dependent half stands down — column readers stay
   untyped and `where(col:)` keys are not validated, exactly as they
   are for a table the schema does not describe. The plugin says so
-  once per run at `:info`. Committing a schema dump (or pointing
+  once per run at `:info`, positioned on `.rigor.yml` — it is a
+  fact about your configuration, not about any one source file,
+  and you get the same single row with `--workers` as without. If
+  you baselined this row at its old position (a controller or a
+  model), that baseline entry no longer matches it — run `rigor
+  baseline regenerate`. Committing a schema dump (or pointing
   `schema_file` / `structure_sql_file` at one) turns the column half
   back on from the next cold run — a warm cache keeps serving the
   reduced index until it is invalidated, so use `rigor check
   --no-cache` (or `make cache-clean`) if you want to see the change
   immediately.
+- **Every kind of relation shares one signature.**
+  `user.posts`, `user.posts.where(...)` and `Post.where(...)` all
+  type as `ActiveRecord::Relation[Post]`, although only the first
+  is an association's `CollectionProxy`, so the signature they share
+  accepts the widest argument list any of them takes.
+  `user.posts.delete_all(:nullify)` is valid and not reported. The
+  same call on the other two raises `ArgumentError` at run time, and
+  is not reported either.
 - **Column reads, not setters.** The plugin types instance-side
   column *reads* (`user.name`, `user.admin?`) and singular
   associations, but not the `name=` setter or the dirty-tracking
@@ -201,6 +296,17 @@ close every model in the project.
 
 ## Plugin internals
 
+The plugin also answers `Plugin::Base#declared_members` (ADR-113
+WD4): it enumerates each model's synthesized members — column
+readers and `column?` predicates, association accessors, declared
+scopes, enum attributes, and macro-defined names — off the prepared
+model index, so `rigor lens` can list `User`'s members without a
+grep-able declaration. A row carries the member-level type the
+plugin commits to: `Dynamic[top]` for column readers on purpose
+(the bare, receiver-less read's answer — a written `user.name`
+still narrows to the column's type), and a type only where the
+plugin already answers one at `check`.
+
 Architecture (the cached schema-parser → model-index → analyzer
 chain), the source layout, how to run the demo, and the plugin
 contract surfaces this plugin exercises are documented in the

data/docs/manual/plugins/rigor-activestorage.md

@@ -40,12 +40,19 @@ arguments decline — those are covered by ActiveStorage's own RBS.
 | Rule | Severity | When |
 | --- | --- | --- |
 | `plugin.activestorage.attachment-call` | info | a recognised `model.attachment_name` call surfaces; confirms the model → attachment mapping |
-| `plugin.activestorage.load-error` | warning | discovery failed (e.g. the model directory is inaccessible under the IoBoundary trust policy) |
+| `plugin.activestorage.load-error` | warning | discovery failed (e.g. the model directory is inaccessible under the IoBoundary trust policy) — once per run, on `.rigor.yml` |
 
 No `:error` diagnostics in this slice — the value is the
 return-type contribution; an "unknown attachment name" rule is a
 future slice.
 
+The `load-error` warning is run-scoped: it is a fact about your
+configuration, not about any one source file, so it is reported once
+per run on `.rigor.yml` rather than repeated on every analysed file.
+It is `:warning`, so if you baselined it at its old position that
+entry no longer matches and the row fails a `--fail-on=warning` run —
+regenerate with `rigor baseline regenerate`.
+
 ## Configuration
 
 ```yaml

data/docs/manual/plugins/rigor-activesupport-core-ext.md

@@ -36,21 +36,27 @@ path, no vendoring, no `signature_paths:` wiring.
 
 Roughly the top ~40 selectors plus their close neighbours, across:
 
-- **Object (universal)** — `#blank?`, `#present?`, `#presence`, `#try`,
-  `#try!`, `#acts_like?` (+ `NilClass` / `TrueClass` / `FalseClass`).
+- **Object (universal)** — `#blank?`, `#present?`, `#presence`,
+  `#presence_in`, `#try`, `#try!`, `#acts_like?`, `#deep_dup`, `#with`,
+  `#with_options`, `#html_safe?`, `Kernel#class_eval` (+ `NilClass` /
+  `TrueClass` / `FalseClass`).
 - **Integer / Float** — Duration multipliers (`#days`, `#hours`,
   `#minutes`, …) and Bytes multipliers (`#megabytes`, `#gigabytes`, …).
 - **String** — inflections (`#underscore`, `#camelize`, `#classify`,
   `#constantize`, `#pluralize`, …), filters (`#squish`, `#truncate`),
-  `#html_safe`, `#starts_with?` / `#ends_with?`, conversions.
+  `#html_safe`, `#starts_with?` / `#ends_with?` (also on **Symbol**),
+  conversions and `#in_time_zone`.
 - **Time / Date / DateTime** — `.current`, `.zone`, `#yesterday`,
   `#tomorrow`, `#beginning_of_*` / `#end_of_*`, `#ago`, `#since`. `Time`
   additionally carries its **whole** Rails instance surface (see below);
   `Date` and `DateTime` carry the same subset they always did.
 - **Array** — `.wrap`, `#to_sentence`, `#in_groups_of`, `#second` …
   `#fifth`, `#compact_blank`, `#exclude?`.
-- **Hash** — `#symbolize_keys` / `#stringify_keys` (+ deep / bang),
-  `#deep_merge`, `#with_indifferent_access`, `#except!`.
+- **Hash** — `#symbolize_keys` / `#stringify_keys` (+ deep / bang) and
+  their `#to_options` alias, `#deep_merge`, `#reverse_merge` /
+  `#with_defaults` (+ bang), `#with_indifferent_access`, `#except!`,
+  `#extract!`.
+- **Range** — `#overlaps?`, `#to_fs` / `#to_formatted_s`.
 - **Enumerable** — `#index_by`, `#index_with`, `#pluck`, `#exclude?`.
 
 ```ruby

data/docs/manual/plugins/rigor-grape.md

@@ -0,0 +1,106 @@
+# rigor-grape
+
+Types the [Grape](https://github.com/ruby-grape/grape)
+endpoint-declaration DSL so calls inside `class API < Grape::API`
+bodies — and inside `Grape::Entity` subclasses from
+[grape-entity](https://github.com/ruby-grape/grape-entity) — resolve to
+real carriers instead of `Dynamic[top]`. It reads source only, with no
+`grape` runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:` (or let
+bundler auto-detection pick it up when `grape` or `grape-entity` is in
+`Gemfile.lock`):
+
+```yaml
+plugins:
+  - rigor-grape
+```
+
+## What it types
+
+```ruby
+class ThingsAPI < Grape::API
+  version "v1", using: :path
+  format :json
+
+  desc "List things"                       # Object?
+  route_setting :swagger, tags: %w[things] # Object?
+
+  params do                                # → Grape::Validations::ParamsScope
+    requires :id, type: Integer            # Object?
+    optional :q, type: String              # Object?
+    requires :filter, type: Hash do        # nested scope re-enters ParamsScope
+      requires :state, type: String
+    end
+    mutually_exclusive :q, :filter
+  end
+
+  namespace :things do                     # self: the API::Instance class object
+    get "/:id" do                          # self: Grape::Endpoint
+      params                               # Hash[untyped, untyped]
+      error!("nope", 404)                  # bot
+      present Thing.first, with: Entities::Thing
+    end
+  end
+end
+
+class Entities::Thing < Grape::Entity
+  expose :id                               # Array[untyped]
+  expose :name do                          # `self` stays the class object
+    expose :first
+  end
+  format_with(:iso) { |d| d.to_s }         # Object
+end
+```
+
+Recognised surfaces:
+
+- **Class-body declarations** on `Grape::API` subclasses (including
+  through intermediate source base classes): `params`, `namespace` /
+  `group` / `resource` / `resources` / `segment` / `route_param` /
+  `version` / `given` / `mounted`, `get`/`put`/`post`/`delete`/`head`/
+  `patch`/`options`/`route`, `desc`, `route_setting`, `helpers`, `use`,
+  `mount`, `rescue_from`, the format/error-format setters, callbacks
+  (`before`/`after`/`before_validation`/`after_validation`), `prefix`,
+  `scope`, `contract`, and friends.
+- **`params` block bodies** bind `self` to
+  `Grape::Validations::ParamsScope`, so `requires`, `optional`, `given`,
+  `with`, `use`, and the grouping macros (`mutually_exclusive`,
+  `exactly_one_of`, `at_least_one_of`, `all_or_none_of`) resolve —
+  including nested `requires :x, type: Hash do ... end` bodies.
+- **Namespace-family bodies** (`namespace`, `route_param`, `version`,
+  `given`, `mounted`) bind `self` to the `Grape::API::Instance` class
+  object, matching Grape's `instance_eval`-on-class semantics, so nested
+  declarations resolve the same surface.
+- **`desc 'x' do ... end` bodies** bind `self` to
+  `Grape::DSL::Desc::ConfigContext` — the closed `ROUTE_ATTRIBUTES`
+  setter surface — so `detail`, `success`, `failure`, `tags`,
+  `entity`, `hidden`, `is_array`, `consumes`, `headers`, `summary`,
+  `deprecated`, `named`, `nickname`, `produces`, `security`,
+  `http_codes`, `body_name`, `default`, `description`, and `params`
+  (the documentation setter, not `ParamsScope`) resolve.
+- **Verb bodies** bind `self` to `Grape::Endpoint`, so `params`,
+  `headers`, `cookies`, `env`, `declared`, `present`, `error!`,
+  `status`, `redirect`, `body`, `content_type`, `route`,
+  `route_setting`, `stream`, `sendfile` resolve.
+- **`Grape::Entity` class bodies**: `expose`, `unexpose`,
+  `with_options`, `documentation`, `format_with`, `root`,
+  `root_element`, `represent`, `present_collection`, `root_exposures`.
+  Nested `expose` bodies keep `self` on the class object, so they
+  resolve the same way.
+
+## Deferred
+
+- `helpers do ... end` bodies (an anonymous module is `self` —
+  unnameable).
+- Named `params :name` scopes inside `helpers` and `contract` schema
+  blocks.
+- Value-level typing: `present`/`declared` results against the declared
+  entity or params, entity `represent` result typing.
+- `Grape::Middleware` and custom-middleware DSL.
+
+Calls on classes outside `Grape::API` / `Grape::Entity` ancestry keep
+the `Dynamic` fallback, and DSL names the bundled signature does not
+declare stay opaque rather than diagnosed — the declared classes are
+registered as open receivers because Grape's runtime surface is
+generated (`override_all_methods!`) and user base classes extend it.

data/docs/manual/plugins/rigor-graphql.md

@@ -58,11 +58,25 @@ name. `null:` extracts to `nullable:` (defaulting to `true`, mirroring
 graphql-ruby); `required:` defaults to `false`. The single-element
 `[String]` list form is recognised.
 
+## Typed DSL surface
+
+Beyond the fact tables, the plugin bundles the graphql-ruby class-level
+DSL signature, so calls inside a recognised subclass type as their real
+carriers instead of staying opaque: `field` returns
+`GraphQL::Schema::Field`, `argument` returns `GraphQL::Schema::Argument`,
+`Enum.value` returns `GraphQL::Schema::EnumValue`, `description` /
+`graphql_name` return their configured strings, and the `Schema`
+registration macros (`query`, `mutation`, `use`, `orphan_types`, …)
+return what they registered. A block parameter on `field`/`argument`
+(`field(:comments) { |f| … }`) types as `GraphQL::Schema::Field` /
+`GraphQL::Schema::Argument`.
+
 ## No diagnostics, no config
 
 The plugin emits no diagnostics and has no configuration knobs — it
-contributes the type tables above for other plugins to consume. It
-walks every `paths:` entry's `.rb` files for the schema-class shapes.
+contributes the type tables and signature above for the engine and
+other plugins to consume. It walks every `paths:` entry's `.rb` files
+for the schema-class shapes.
 
 ## Limitations
 
@@ -72,6 +86,13 @@ walks every `paths:` entry's `.rb` files for the schema-class shapes.
 - **No `Schema.execute(...)` result typing.** Typing
   `Schema.execute(query).to_h` against the queried fields is a future
   plugin.
+- **Interface DSL stays opaque.** `include GraphQL::Schema::Interface`
+  wires the DSL onto the includer through an include-time `extend`
+  hook RBS cannot express, so `field` inside an interface module is
+  not yet typed.
+- **Zero-arity definition blocks keep an opaque `self`.**
+  `field :x do ... end` `instance_eval`s on the new `Field` at
+  runtime; only the explicit-parameter form (`{ |f| … }`) is typed.
 - **Constant-form types only.** The string form (`field :foo, "User"`)
   and the `<Type>.array` / `<Type>!` sugar chains are not recognised
   (the `[String]` bracket form is). Multi-element and empty list

data/docs/manual/plugins/rigor-pundit.md

@@ -33,7 +33,7 @@ authorize(Comment, :edit)   # error: no policy class CommentPolicy (did you mean
 | `plugin.pundit.policy-call` | info | an `authorize` / `policy` / `policy_scope` call resolved to a discovered policy |
 | `plugin.pundit.unknown-policy-class` | error | the record maps to a `<Type>Policy` with no entry in the index (with a did-you-mean) |
 | `plugin.pundit.unknown-policy-method` | error | the policy exists but the `:action` has no `<action>?` predicate (lists known predicates + a did-you-mean) |
-| `plugin.pundit.load-error` | warning | policy discovery failed (parse/read error) — once per file |
+| `plugin.pundit.load-error` | warning | policy discovery failed (parse/read error) — once per run, on `.rigor.yml` |
 
 The record maps to a policy by constant name or inferred
 `Nominal[T]` (`Post` → `PostPolicy`); `:update` normalises to
@@ -88,6 +88,13 @@ candidate rather than being guessed at.
   not validated when `local` has no inferred `Nominal[T]`.
 - **`Scope` policies** are validated for class existence, not for
   `Scope#resolve`.
+- **The "failed to discover policies" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-rails-i18n.md

@@ -88,11 +88,16 @@ view templates containing lazy `t('.key')` calls.
   may come from controller instance variables not visible in the
   template source. Configure `view_search_paths:` to override the
   default `["app/views"]`.
-- **View diagnostics duplicate under `--workers`** — the view
-  scan is a project-wide pass surfaced through the per-file
-  diagnostic hook, so each fork-pool worker re-emits the full set
-  (the same once-per-run limitation the `load-error` diagnostics
-  carry). Default `rigor check` (sequential) is unaffected.
+- **`load-error` rows are reported on `.rigor.yml`** — a locale
+  file that does not parse, or a locale or view scan that fails,
+  is reported once per run at `.rigor.yml:1:1`. They are
+  `:warning`, so if you baselined one at its old position on a
+  Ruby file, that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`. View diagnostics keep their view file position and
+  are reported once per run whatever `--workers` is set to
+  ([#1060](https://github.com/rigortype/rigor/issues/1060)); a
+  baseline entry recorded against a view still matches.
 - **Pluralization is recognised but not validated** — `count:` is
   treated as a reserved option; whether the locale defines
   `:zero` / `:one` / `:other` is not checked.

data/docs/manual/plugins/rigor-rails-routes.md

@@ -129,6 +129,13 @@ routed. Helper-name recognition for all three is unaffected.
   doesn't model) may not register, which can surface a false
   `unknown-helper`. Record those in a baseline, or
   `# rigor:disable` the line.
+- **The "routes file did not load" warning is run-scoped.** It is a
+  fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than on the
+  first analysed file. It is `:warning`, so if you baselined it at
+  its old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 - **Project-custom inflections** declared in
   `config/initializers/inflections.rb` are not yet fully ingested
   (ADR-39 slice 3); the standard ActiveSupport inflections are