rigortype 0.3.9 → 0.4.1

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

data/docs/manual/plugins/rigor-rbs-inline.md

@@ -45,40 +45,97 @@ plugin id/version + config), so an unchanged second run skips the parse.
 | Rule | Severity | Fires when |
 | --- | --- | --- |
 | `plugin.rbs-inline.source-rbs-synthesis-failed` | info | rbs-inline could not parse a file; analysis falls back to no inline-RBS contribution and the diagnostic carries the upstream error |
-| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Two causes: a member your `sig/` also declares (see [Precedence](#precedence)), and the `# @rbs module-self: Foo` spelling (see below) |
+| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Six causes: a member your `sig/` also declares where Rigor cannot tell which of the two is more precise (see [Precedence](#precedence)), the `# @rbs module-self: Foo` spelling (see below), a `#:` line whose type does not parse (see [Unparseable `#:` types](#unparseable--types)), a same-line `# @rbs %a{…}` whose method type does not parse (see [Same-line annotations](#same-line-annotations)), a `# @rbs name: T` parameter type that does not parse (see [Unparseable `# @rbs name:` types](#unparseable--rbs-name-types)), and an `@rbs`-prefixed tag the gem does not recognise (see [An unrecognised tag after `@rbs`](#an-unrecognised-tag-after-rbs)) |
+| `rbs.contradicting-signature` | error | an inline declaration contradicts the `sig/` declaration of the same method, or an inline `%a{rigor:v1:…}` refinement is outside its own declared type (see [Precedence](#precedence)). A core rule rather than the plugin's own, so it carries no `plugin.rbs-inline.` prefix |
 
 ## Precedence
 
 When a method is declared **both** in `sig/` and by an inline
-annotation, **the `.rbs` wins, per member.** The inline signature for
-that one method is dropped; every other annotation in the file still
-binds, and the class keeps its method surface.
+annotation, Rigor **compares the two**, position by position — each
+parameter, the return type, a block's parameters and return — and
+exactly one of them binds. Every other annotation in the file still
+binds either way, and the class keeps its method surface.
 
 ```ruby
-# lib/demo.rb                  # sig/demo.rbs
-class Demo                     # class Demo
-  # @rbs (Integer) -> String   #   def shared: (String) -> Integer  ← this one wins
-  def shared(v) = v.to_s       #   def only_sig: () -> String
-                               # end
-  # @rbs (Integer) -> Integer
-  def only_inline(v) = v + 1   # ← inline-only: still binds
+# lib/demo.rb                          # sig/demo.rbs
+class Demo                             # class Demo
+  # @rbs dir: :asc | :desc             #   def order: (Symbol dir) -> void
+  def order(dir) = nil                 #   def shared: (String) -> Integer
+                                       # end
+  # @rbs (Integer) -> String
+  def shared(v) = v.to_s
 end
 ```
 
-Each dropped member is reported once as
-`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the
-member and the `.rbs` that won. Delete one of the two declarations to
-make the inline annotation take effect.
-
-`sig/` wins because it is the reviewed artefact — the one you diff in
-review and the one `rigor sig-gen --diff` reasons about. There is no
-upstream rule to defer to: rbs merges an inline `.rb` declaration and a
-`.rbs` one into a single class entry and ranks neither, so Steep reports
-the same overlap as a signature error and the class still fails to
-build. Rigor keeps the reporting and drops the degradation
-([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD13) — left to
-collide, one duplicated method costs the class every other method, and
-each call on it, real methods and typos alike, reads `Dynamic[top]`.
+- **One refines the other: the more precise one binds, silently.**
+  `:asc | :desc` is a subtype of `Symbol`, so `Demo#order` takes the
+  inline contract and `order(:up)` is an argument-type error, where
+  the `.rbs` alone let it pass. The merge takes the narrower type in
+  every position, parameters included, on purpose: both declarations
+  are yours, and the narrower one is what you stated. `String` in
+  `sig/` beside `non-empty-string` inline reads as `non-empty-string`.
+  `untyped`, `void` and `top` are consistent with anything and say the
+  least, so `sig/`'s `-> untyped` beside an inline `-> void` is quiet.
+  Identical declarations — what `rigor sig-gen` writes for an annotated
+  method — are quiet too. The inline side binds only if the `.rbs`
+  member loses nothing by it: the same visibility, and every
+  annotation it carries (a predicate, an assertion, an effect
+  envelope) also on the inline one.
+- **They contradict: an error, and the `.rbs` binds.** If `Demo#shared`
+  took a `::String` in `sig/` and an `::Integer` inline, no value would
+  be both, so the run would report
+  [`rbs.contradicting-signature`](../04-diagnostics.md#rule-rbs-contradicting-signature)
+  at the `sig/` line, naming the annotated file. Spelled `String` and
+  `Integer`, as in the example, the pair is undecided instead (below). Positional counts that
+  cannot meet, or a keyword one side requires and the other cannot take
+  in any form, contradict the same way. The error needs a proof, and
+  only Ruby core or stdlib classes written absolutely (`::String`,
+  `::Integer`) give one, read from their RBS hierarchy. A module such
+  as `Comparable` never counts, since any class may include it; nor
+  does a class of your own (your `sig/` may omit the superclass Ruby
+  gives it), a gem's class, a relative name such as plain `String`
+  (it may be your own `App::String`), an optional or rest parameter
+  (a call may leave it out), or a block's parameters (the body may
+  never yield). A stale generated signature is the usual cause:
+  regenerate it, or fix the annotation.
+- **Rigor cannot tell: the `.rbs` binds, with an `:info`.** When a
+  position names a type alias, an interface, `self`, a type variable,
+  or a relative class name your project also declares, when Rigor
+  cannot prove two types disjoint (a subclass relation such as
+  `Integer` against `Numeric` included), when the parameter lists are shaped
+  differently but overlap, when the overloads do not pair one to one
+  (they are paired by what they declare, not by their order), or when
+  each side is more precise somewhere, the inline signature is dropped
+  and reported as
+  `plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the
+  member and the `.rbs` that bound. Make one a refinement of the
+  other, or delete one, to settle it.
+
+`rigor sig-gen --write` produces this overlap on purpose: by default it
+copies each inline declaration into `sig/`, so the generated signature
+is the complete contract a gem ships. An identical copy is quiet, as
+above. When an inline annotation later disagrees with its copy,
+`rigor sig-gen --write` and `--check` refuse the method and exit `1`
+until you make the two agree or pass `--overwrite`, which replaces the
+`sig/` member with the inline declaration. A project whose Steep reads the same
+annotations sets `sig_gen.inline_declared: skip` instead
+([handbook chapter 11](../../handbook/11-sig-gen.md#methods-declared-inline)).
+
+A `%a{rigor:v1:return: …}` or `%a{rigor:v1:param: …}` refinement on an
+inline annotation must also share values with its own declared type:
+`# @rbs %a{rigor:v1:return: positive-int} () -> ::String` is reported as
+`rbs.contradicting-signature` at the annotated file (the same proof rule
+applies, so `-> String` without `::` is left alone).
+
+There is no upstream rule to defer to: rbs merges an inline `.rb`
+declaration and a `.rbs` one into a single class entry and ranks
+neither, so Steep reports the same overlap as a signature error and
+the class fails to build. Rigor keeps the reporting and drops the
+degradation ([ADR-112](../../adr/112-extrbs-comment-channel.md) WD5,
+which replaced [ADR-32](../../adr/32-rbs-inline-comment-ingestion.md)
+WD13's "the `.rbs` always wins") — left to collide, one duplicated
+method costs the class every other method, and each call on it, real
+methods and typos alike, reads `Dynamic[top]`.
 
 Two overlaps this does **not** cover: a `.rbs` that collides with
 *bundled* RBS (Ruby core, stdlib, a gem's signatures) is quarantined
@@ -109,6 +166,136 @@ in silence. Constructs the gem supports and the built-in parser does not —
 `@rbs generic T`, `@rbs!` embedded RBS blocks, `@rbs inherits`, method
 visibility — all work here.
 
+## Same-line annotations
+
+An `%a{…}` annotation can sit on the same line as a method type:
+
+```ruby
+class Reader
+  # @rbs %a{rigor:v1:return: non-empty-string} () -> String
+  def title = "x"
+
+  #: %a{pure} () -> String
+  def label = "x"
+end
+```
+
+This is the spelling the built-in parser and Steep's inline mode accept. The
+gem itself does not: it keeps the annotation and drops the method type in the
+`@rbs` form, and drops the whole `#:` line. Rigor splits the line back into the
+annotation and the method type before the gem's writer runs, so both apply, as
+they do when the annotation has a line of its own
+([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD11). The gem's own
+`rbs-inline --output` is unchanged and still drops them.
+
+When the method type after the annotations does not parse, nothing is split:
+the method types as if no signature had been written, and Rigor reports it — a
+`#:` line under [Unparseable `#:` types](#unparseable--types), and an `@rbs`
+line as `plugin.rbs-inline.source-rbs-annotation-not-honoured` naming the line
+and the text it could not read.
+
+## Unparseable `#:` types
+
+A `#:` line whose type does not parse as RBS is dropped — the signature never
+applies, and the method types as if the line had never been written, not
+merely as if its type were wrong:
+
+```ruby
+class BadRefProbe
+  #: (finite-float) -> String
+  def show(f)
+    f.to_s
+  end
+end
+```
+
+`finite-float` is a [Rigor refinement](../16-rbs-extended-annotations.md)
+name, not an RBS type, and does not belong in an ordinary type position.
+Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the text that failed to parse, rather than leaving `show` silently `untyped`
+with no diagnostic anywhere. The `# @rbs name: TYPE` tag form of the same
+mistake is a different failure shape — see the next section.
+
+## An unresolvable type name in `# @rbs`
+
+Naming a Rigor refinement (or any other unresolvable name) where an RBS type
+belongs in the `# @rbs name: TYPE` tag form does not drop silently the way
+`#:` does — it takes the whole class down:
+
+```ruby
+class ProbeZZ
+  # @rbs g: finite-float
+  def probe(g)
+    g.to_s
+  end
+end
+```
+
+Upstream's own type parser truncates `finite-float` to `finite` (a hyphen
+cannot continue an RBS type name) before this ever reaches Rigor, so `finite`
+is the only token that reaches `RBS::DefinitionBuilder` — and it names no
+loaded type, so the build for the WHOLE class fails
+(`RBS::NoTypeFoundError`). `probe`, and every other real method on `ProbeZZ`,
+reads `Dynamic[top]`. This surfaces as
+`rbs.coverage.definition-build-failed`, naming the token and, when it is the
+truncated head of a registered refinement name, the `%a{rigor:v1:…}` spelling
+that IS valid today (see
+[RBS::Extended annotations](../16-rbs-extended-annotations.md)).
+
+## Unparseable `# @rbs name:` types
+
+A bounded or parameterised refinement — `Integer[1..10]`, `non-empty-array
+[Integer]` — does not truncate at a hyphen the way `finite-float` does, so it
+does not take the whole class down. In a `# @rbs name: TYPE` position it
+leaves the parameter untyped instead, silently:
+
+```ruby
+class BoundedProbe
+  # @rbs n: Integer[1..10]
+  def probe(n)
+    n
+  end
+end
+```
+
+The gem's grammar makes the colon-and-type optional on this annotation, so a
+`TYPE` it cannot parse leaves the parameter's name recorded and its type
+unset rather than raising — indistinguishable downstream from a parameter
+nobody annotated at all. Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the text that failed to parse, and points at the `%a{rigor:v1:param:}`
+spelling that carries a refinement like `Integer[1..10]` correctly (see
+[RBS::Extended annotations](../16-rbs-extended-annotations.md)) — the same
+advice the `%a{rigor:v1:…}` pointer above gives for the tag form.
+
+## An unrecognised tag after `@rbs`
+
+The gem recognises a comment as an `@rbs` annotation attempt as soon as it
+sees the word boundary right after `@rbs` — which matches a hyphen, not only
+whitespace or end-of-line:
+
+```ruby
+class TagProbe
+  # @rbs-ext return: non-empty-string
+  # @rbs return: String
+  def name
+    "x"
+  end
+end
+```
+
+`# @rbs-ext …` is inside that net, but nothing in the gem's grammar
+recognises `-ext`, so the gem gives up on the whole paragraph and folds it
+back into an ordinary comment — the neighbouring `# @rbs return: String`
+line still binds, but the `@rbs-ext` line contributes nothing and, before
+this, said nothing either. Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the comment text — without implying `@rbs-ext` is a recognised tag of any
+kind. A comment that merely mentions `@rbs` in prose, or one that opens with
+a tag not starting with `@rbs` (`# @extrbs …`), is outside the gem's
+detector and stays silent.
+
 ## Configuration
 
 ```yaml

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

@@ -40,7 +40,7 @@ arguments.
 | `plugin.sidekiq.worker-call` | info | a `Worker.perform_*` call matched a discovered worker's `#perform` arity |
 | `plugin.sidekiq.wrong-arity` | error | the forwarded argument count falls outside `#perform`'s arity envelope (message names the schedule carve-out for `perform_in` / `perform_at`) |
 | `plugin.sidekiq.missing-schedule` | error | `perform_in()` / `perform_at()` called with zero arguments (the schedule is required even when `#perform` takes none) |
-| `plugin.sidekiq.load-error` | warning | worker discovery failed (parse/read error) — once per file |
+| `plugin.sidekiq.load-error` | warning | worker discovery failed (parse/read error) — once per run, on `.rigor.yml` |
 
 ## What it types
 
@@ -144,6 +144,13 @@ added it is 100.
   alternative `klass:` spelling, and a schedule built in Ruby with
   `Sidekiq::Cron::Job.load_from_hash!`, supply no roots — the worker
   stays a `rigor unused` candidate rather than being guessed at.
+- **The "failed to discover workers" 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-sorbet.md

@@ -47,11 +47,27 @@ plugins:
 The plugin is **input-side only**: it translates Sorbet's syntax
 into Rigor's type model. It does **not** run Sorbet's checker,
 ship `sorbet-runtime`, or enforce Sorbet's runtime guarantees.
-When an RBS sig and a Sorbet sig disagree, RBS wins (the Sorbet
-sig may refine but not contradict it). Forms outside the
-translation table (`T.proc`, `T.self_type`, `T::Struct` /
-`T::Enum` subclasses, …) degrade to `Dynamic[top]`. Chapter 10
-documents the full vocabulary and these edges.
+When an RBS sig and a Sorbet sig disagree, call sites get the
+Sorbet sig's return type, and the method's body is checked
+against the RBS return. Forms outside the
+translation table (`T.proc`, `T.self_type`, …) degrade to
+`Dynamic[top]`. Chapter 10 documents the full vocabulary and
+these edges.
+
+The plugin also types the annotation DSL's own expressions
+(`sig`, `params`, `returns`, `void`, `abstract`, `override`,
+`type_member`, `T::Array[...]`, `T::Helpers`/`T::Generic` macros,
+`T::Struct`/`T::Enum` class bodies — `sig` on a plain
+`T::Struct` subclass still needs the subclass's own `extend T::Sig`,
+matching the runtime) through a bundled
+`sorbet-runtime` RBS surface — so the sig DSL no longer reads as
+`Dynamic[top]` on a Sorbet codebase. What it does not model:
+`T::Struct` does not synthesise `prop`-declared readers (a
+`Doc#name` accessor still reads opaque), `include T::Props` does
+not confer the `ClassMethods` surface (only the `< T::Struct`
+subclass path does), and the deeper type-member machinery
+(`T.attached_class` variance, `type_member` bounds) is not
+propagated into call sites.
 
 ## Plugin internals
 

data/exe/rigor

@@ -11,13 +11,28 @@
 # context across the exec. The `none` and `process` (default) strategies
 # need no flag, so this is a no-op for them — behaviour is unchanged
 # unless a project opts into `ruby_box`.
+#
+# Before re-exec'ing, a child Ruby probes whether this Ruby can run
+# Rigor under `RUBY_BOX=1` at all (Rigor::Plugin::BoxProbe — released
+# Rubies through 4.0.7 segfault on Ruby Bug #22260). When it cannot,
+# the request is dropped with a warning and the run proceeds under the
+# configured strategy (`process` by default) instead of crashing.
 rigor_isolation = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
 rigor_wants_box = rigor_isolation == "ruby_box" || !ENV["RIGOR_BOX"].to_s.empty?
 if rigor_wants_box && ENV["RUBY_BOX"].to_s.empty?
-  require "rbconfig"
-  ENV["RUBY_BOX"] = "1"
-  ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
-  exec(RbConfig.ruby, __FILE__, *ARGV)
+  require_relative "../lib/rigor/plugin/box_probe"
+  if (rigor_box_unsupported = Rigor::Plugin::BoxProbe.unsupported_reason)
+    rigor_box_warning = "rigor: ruby_box plugin isolation is unavailable: #{rigor_box_unsupported}. " \
+                        "Falling back to the configured plugins_isolation strategy (default: process)."
+    # `$stderr.puts`, not `warn`: `-W0` silences `warn`, and this fallback must never be silent.
+    $stderr.puts rigor_box_warning # rubocop:disable Style/StderrPuts
+    ENV.delete("RIGOR_PLUGIN_ISOLATION") if rigor_isolation == "ruby_box"
+    ENV.delete("RIGOR_BOX")
+  else
+    ENV["RUBY_BOX"] = "1"
+    ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
+    exec(RbConfig.ruby, __FILE__, *ARGV)
+  end
 end
 
 lib = File.expand_path("../lib", __dir__)

data/lib/rigor/analysis/baseline.rb

@@ -275,7 +275,7 @@ module Rigor
         YAML.dump(document)
       end
 
-      # The number of buckets recorded. Useful for the CLI summary on `generate`.
+      # The bucket count the `generate` summary reports.
       def size
         buckets.size
       end