rigortype 0.3.9 → 0.4.0

data/docs/manual/02-cli-reference.md

@@ -138,6 +138,28 @@ truncation explicit. `--trace` records fail-soft fallbacks,
 after the rows of a line table in text output. The editor-mode
 `--tmp-file` / `--instead-of` pair is accepted as on `check`.
 
+A template a plugin compiles into Ruby (an ERB view under
+`rigor-actionpack`) is probed the way `rigor check` analyses
+it: the compiled Ruby is typed under the view's declared
+`self`, locals and instance variables, and `LINE:COL` are the
+template's own. A column answers only when it lies in Ruby the
+compiler copied verbatim — the `@user.name` in
+`<%= @user.name %>` — and denotes exactly one compiled
+expression. A column in HTML text, in code the plugin rewrote
+(a layout's `<%= yield %>`), or in bytes copied to more than
+one place prints `no expression found at …` with the reason
+and exits `1`; the command never answers about a nearby
+node instead. Two tags that name the same thing (`<%= v %>`
+beside `<% if "a" <= v %>`, or `<%= v %> <%= v.to_s %>`)
+decline for that reason as well; a name repeated inside ONE
+tag still answers. A bare `FILE:LINE` lists only the expressions
+that map back to a template column. `--trace` fallbacks are
+reported at the template line, and a JSON fallback carries a
+`column` only when its position maps back to one. A template
+the plugin declined to compile prints
+`plugin declined the template; probing its bytes as Ruby`
+and is probed as plain Ruby, parse error included.
+
 The four probe commands — `type-of`, `type-scan`, `trace` and
 `annotate` — build their environment fresh on every invocation
 and never read or write the persistent cache. That is why none
@@ -477,13 +499,52 @@ rigor sig-gen [paths]
 | `--print` | Write RBS to stdout. Default. |
 | `--diff` | Write a unified diff against existing RBS. |
 | `--write` | Write RBS to `sig/<path>.rbs` files. |
-| `--overwrite` | Allow tighter-return updates to replace user-authored RBS. |
+| `--check` | Write nothing; print what `--write` with the same options would change, and exit `1` if anything would. The CI freshness gate. |
+| `--overwrite` | Allow tighter-return updates, and inline declarations that disagree with `sig/`, to replace user-authored RBS. |
 | `--include-private` | Emit private and protected methods too. |
 | `--params=untyped\|observed\|observed-strict` | Parameter-typing policy. Default `untyped`. |
-| `--observe=PATH` | Scan `PATH` for call-site observations. Repeatable. |
+| `--observe=PATH` | Scan `PATH` for call-site observations. Repeatable. Default: the configured `test_paths:` (unset: whichever of `spec/` and `test/` exist). |
 | `--new-files` / `--new-methods` / `--tighter-returns` | Emit only that classification. |
+| `--effect-envelopes` | Also emit `%a{rigor:v1:effect …}` for effectful methods. Needs the `effects:` opt-in. |
+| `--no-cache` | Do not read or write the analysis cache. Only effect collection uses it. |
 | `--format=text\|json` | Output format. |
 
+`--print`, `--diff`, `--write` and `--check` are mutually exclusive.
+`--check` fails exactly when `--write` would create, change or
+refuse a file, so a tighter return `--write` declines without
+`--overwrite` does not fail it; `--check --overwrite` counts one.
+See [handbook chapter 11](../handbook/11-sig-gen.md#keeping-sig-current-in-ci).
+
+A method declared inline with `# @rbs` / `#:` is written as that
+declaration, not as what its body infers; a parameter-only
+annotation keeps its parameters and takes the return from the body,
+and `initialize` is always `-> void`. When `sig/` already declares
+the method (a `def` or an `attr_*`) and the two disagree as types —
+parameter names and union spelling do not count, overload order
+does — sig-gen changes neither: the method is refused
+(`sig.skipped.inline-differs`, listed under `refused` in `--format=json`),
+and `--write` / `--check` exit `1` until you make them agree or pass
+`--overwrite`, which replaces the whole `sig/` member with the inline
+declaration. For a parameter-only annotation only the parameters are
+compared; the return follows the ordinary proposal rules. A class
+made generic inline is not written unless `sig/` declares it with the
+same type parameters. A project whose Steep reads the same
+annotations sets `sig_gen.inline_declared: skip` in `.rigor.yml` to
+keep those methods out of `sig/`. See
+[handbook chapter 11](../handbook/11-sig-gen.md#methods-declared-inline).
+
+When `.rigor.yml` carries an `effects:` block, sig-gen also writes
+`%a{pure}` above a method whose effect summary is **exhaustive**
+(every call it reaches was resolved), **undischarged** (nothing in
+its footprint is only invisible because `effects.tolerated:` says
+so), **claimed** (every callee is described by a catalogue row, a
+plugin, an envelope or a project definition), carries no authored
+bound of its own, and is free of surviving labels in the `≤` lane. Nothing else is annotated, and
+`--effect-envelopes` adds Rigor's own labelled spelling for methods
+that do have a footprint. With no `effects:` block the output is
+byte-for-byte what it was before. See
+[handbook chapter 11](../handbook/11-sig-gen.md#emitting-effect-annotations).
+
 Every signature is parsed before it is emitted. A method whose
 generated RBS does not parse is **skipped** (`sig.skipped.unrenderable-rbs`)
 and reported on stderr rather than written — an unparseable

data/docs/manual/03-configuration.md

@@ -60,6 +60,7 @@ cache:
 | `target_ruby` | String | `"4.0"` | The Ruby version *your* project runs — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. |
 | `paths` | Array | `["lib"]` | Directories or files to analyse. |
 | `exclude` | Array | `[]` | Glob patterns to skip. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
+| `test_paths` | Array | `nil` | The project's test roots: the directories (or files) holding its tests. Relative entries resolve against the config file's directory. Unset auto-detects whichever of `spec/` and `test/` exist; `[]` declares none. `rigor sig-gen --params=observed` reads call sites there to type parameters, and names on stderr a declared root that does not exist. Test roots are not analysed unless `paths:` also lists them, and changing them invalidates no cache. |
 | `includes` | Array | `[]` | Other config files to layer underneath this one. |
 | `fold_platform_specific_paths` | Boolean | `false` | Resolve Ruby-version-conditional load paths when discovering sources. |
 | `parameter_inference` | Boolean | `false` | Opt-in call-site parameter type inference on the `check` walk ([ADR-67](../adr/67-parameter-type-inference.md) WD6). When `true`, an undeclared `def` / `initialize` / setter parameter is typed to the union of its resolved call-site argument types, sharpening downstream ivar reads, folds, and protection coverage. Precision-additive only — the negative rules never fire against an inferred parameter. Cannot be combined with `--incremental`. |
@@ -73,6 +74,12 @@ cache:
 | `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
+### Signature generation
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sig_gen.inline_declared` | String | `"write"` | What `rigor sig-gen` does with a method already declared inline by `# @rbs` / `#:`. `write` copies the inline declaration into `sig/`, so the generated signature is the complete contract a gem ships, and refuses (exit 1) a `sig/` declaration that later disagrees with the inline one until the two agree or `--overwrite` replaces it. `skip` leaves every method the inline reader declares out of `sig/` (`sig.skipped.inline-declared`): set it when Steep reads the same annotations (`inline: true` beside `signature "sig"`), where a copy would declare each method twice (`DuplicatedMethodDefinition`). The cost of `skip`: a consumer reading only your shipped `sig/` never sees those methods, and an annotation on one — a Rigor refinement included — takes effect only where the source itself is analysed. Any other value, or any other key under `sig_gen:`, is a load error. Only `rigor sig-gen` reads this key, and changing it invalidates no cache. See [handbook chapter 11](../handbook/11-sig-gen.md#methods-declared-inline). |
+
 ### Config validation warnings
 
 `rigor check` warns on STDERR when a configured value silently resolves to

data/docs/manual/04-diagnostics.md

@@ -16,6 +16,7 @@ Every rule has a two-segment `family.rule` identifier:
 | `call` | Call sites — undefined methods, arity, argument types, nil receivers. |
 | `flow` | Control-flow proofs — always-raises, dead branches, constant conditions. |
 | `def` | Method definitions — return types, ivar writes, visibility. |
+| `global` | Writes to special globals — a value the setter rejects, a read-only variable. |
 | `assert` | `assert_type` checks. |
 | `dump` | `dump_type` notices. |
 
@@ -70,11 +71,14 @@ carries no `documentation_url`.
 | <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
+| <a id="rule-global-write-type-mismatch"></a>`global.write-type-mismatch` | A special global is assigned a literal its setter rejects, so the write raises `TypeError` every time it runs. `$/`, `$-0`, `$,` and `$\` take only a String or nil (`$/ = 1` and `$/ = /x/` report). `$;` and `$-F` take a String, a Regexp, nil, or an object with `to_str`. `$~` takes a MatchData or nil. `$0` and `$PROGRAM_NAME` take a String or an object with `to_str`, so `$0 = nil` and `$0 = :name` report. `$.` takes an Integer, a Float, or an object with `to_int`, so `$. = "3"` reports and `$. = 3r` does not. `$-i` takes a String, nil, false, or an object with `to_str`. `$stdout`, `$>` and `$stderr` take anything that responds to `write`: `$stdout = 1` reports, `$stdout = StringIO.new` does not. Ruby's setter decides, not the global's RBS type. Only a value written as a literal is judged — a number, a string, a symbol, an array, a hash or a regexp literal (interpolated or not), or `nil`, `true` or `false` — so a variable, a method call or a constant never reports, whatever its type. A literal stays silent when your program defines the method the setter asks for (`write`, `to_str`, `to_int`) or a `method_missing` / `respond_to_missing?` / `respond_to?` anywhere, in any spelling and on any class — Rigor cannot always tell which objects such a definition reaches, so it does not try — or when a top-level `include` / `extend` or an ancestor's `include` names a module Rigor has no RBS for. For `$stdout`, `$>` and `$stderr` it also stays silent where a `using` is in effect for a refinement that may add `write`. `$/`, `$-0`, `$,`, `$\` and `$~` accept only their classes, so none of that silences them. A write to `$stdin` is never checked, and a special any file aliases (`alias $stdout $out`, including a `pre_eval:` file) is exempt. `warning` under `lenient`. | high |
+| <a id="rule-global-readonly-write"></a>`global.readonly-write` | A read-only special global is written — `$!`, `$$`, `$?`, `$<`, `$FILENAME`, `$*`, `$:` / `$LOAD_PATH` / `$-I`, `$"` / `$LOADED_FEATURES`, `$-W`, `$-p`, `$-l` or `$-a` — which raises `NameError` whatever the value. Covers `$g = value`, `$g += value` and a multiple-assignment target. `$LOAD_PATH ||= []` never writes and `$LOAD_PATH << dir` is a method call, so neither fires. A special any file aliases (`alias $! $err`) is exempt. An error in every profile. | high |
 | <a id="rule-static-value-use-void"></a>`static.value-use.void` | A value recovered from an author-declared `-> void` return is used in value context (an assignment right-hand side, a call receiver, or a call argument). Off by default; reaches a run only through the `use-of-void-value` bleeding-edge feature (ADR-100). A bare-statement `void` call and a legitimate `top` value both stay silent. | high |
 | <a id="rule-effect-envelope-exceeded"></a>`effect.envelope-exceeded` | A method performs an effect its declared envelope does not admit — its proven effect labels (its own body plus everything it calls) are not covered by the `%a{pure}` or `%a{rigor:v1:effect …}` bound written on it or on its class. Opt-in twice over: it needs an `effects:` block in `.rigor.yml` and an envelope you wrote. Positioned at the Ruby `def`. Unproven ("and possibly more") effects never fire, and `mutate.local` is tolerated by every envelope. | high |
 | <a id="rule-effect-liskov-widened"></a>`effect.liskov-widened` | An override escapes the envelope written on the method it overrides. A `PgRepo` is usable wherever a `Repo` is, so a `%a{rigor:v1:effect io.db}` on `Repo#find` binds `PgRepo#find` too: an implementation may be purer than the bound it inherits, never less pure. Either what the override *does* exceeds the inherited bound, or the envelope the override *declares for itself* is wider than it. Both sides must be authored — nothing fires unless someone wrote an envelope on the ancestor — and only subclassing counts, not `include`. Positioned at the override's `def`. Needs an `effects:` block. | high |
 | <a id="rule-effect-unknown-label"></a>`effect.unknown-label` | An effect declaration names a label the registry does not know — a typo in an envelope (`%a{rigor:v1:effect io.bd}`), or a member of `effects.tolerated:`. The whole tag then reads as unbounded, so the declaration quietly stops doing anything; this says so. Positioned at the declaration: the `.rbs` line, the `.rb` line for an rbs-inline annotation, or `.rigor.yml` for a config value. `# rigor:disable` comments are not read out of `.rbs` or `.rigor.yml`, so use `disable:` or the baseline there. Only fires where the spelling is evidently meant to be a label (close to a known one, next to a known one, dotted, or retired) — a word nothing resembles stays silent, because you may be opening your own vocabulary. Needs an `effects:` block. | high |
 | <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — on every run, a warm `--incremental` with nothing changed included. | — |
+| <a id="rule-rbs-contradicting-signature"></a>`rbs.contradicting-signature` | A method is declared both in your `sig/` and by an inline `# @rbs` / `#:` annotation, and the two provably contradict — no value or call satisfies both: in the return or a parameter every call must pass, the two types share no value (`::String` against `::Integer`). Only absolutely written Ruby core or stdlib classes count: a module such as `Comparable`, a class your project declares, a gem's class, or a relative name like plain `String` never does, or two keyword-free declarations accept positional counts that cannot meet, or one requires a keyword the other cannot take in any form. Overloads are paired by correspondence, not order. Also fires when a member-level `%a{rigor:v1:return: …}` / `%a{rigor:v1:param: …}` refinement shares no value with the type its own member declares. Positioned at the `.rbs` member; Rigor reads that declaration. A stale generated signature is the usual cause: regenerate it, or fix the annotation. Two declarations where one refines the other merge to the more precise one without a word, and a pair Rigor cannot rank drops the inline side with a `source-rbs-annotation-not-honoured` `:info` instead ([Precedence](plugins/rigor-rbs-inline.md#precedence)). An error in every profile. | high |
 | <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
 | <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
 | <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |

data/docs/manual/07-plugins.md

@@ -95,7 +95,7 @@ with the `plugins_isolation:` configuration key or the
 | --- | --- |
 | `process` (default) | Run the call in a forked, crash-contained worker, so the target library's monkey-patches and any crash never contaminate Rigor. Falls back to `none` where `fork` is unavailable (Windows / JRuby). |
 | `none` | Load the library into Rigor's own process and call it directly. |
-| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
+| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
 
 The environment variable wins over `plugins_isolation:`, so you can
 override a project's committed choice for one invocation. The legacy

data/docs/manual/10-mcp-server.md

@@ -358,8 +358,9 @@ Generate RBS skeleton signatures inferred from Ruby source files.
 | `params` | `"untyped"` \| `"observed"` | no | `"untyped"` |
 | `config` | `string` | no | session default |
 
-`params: "observed"` harvests call-site argument types from `spec/`
-(or a directory named via `--observe=PATH` in the underlying CLI).
+`params: "observed"` harvests call-site argument types from the
+project's test roots: the configured `test_paths:`, or whichever of
+`spec/` and `test/` exist.
 
 **Returns:** JSON — the same as `rigor sig-gen --print --format json`.
 

data/docs/manual/16-rbs-extended-annotations.md

@@ -22,25 +22,56 @@ The plain `() -> String` stays the compatibility contract; the
 annotation tells Rigor the return is a non-empty string.
 
 You may also write any of them **in a `.rb` file**, as an
-rbs-inline `# @rbs %a{…}` comment — `%a{}` is rbs-inline's own
-upstream grammar, and the annotation reaches Rigor on the same
-path the generated signature does:
+inline-RBS comment — `%a{}` is RBS's own annotation grammar, and
+the annotation reaches Rigor on the same path the generated
+signature does. Rigor reads three spellings:
 
 ```rb
 # rbs_inline: enabled
 
 class Reader
+  # Own line: the annotation, then the type on its own tag.
   # @rbs %a{rigor:v1:return: non-empty-string}
   # @rbs return: String
   def read_name = "x"
+
+  # Same line, `@rbs` method type.
+  # @rbs %a{rigor:v1:return: non-empty-string} () -> String
+  def title = "x"
+
+  # Same line, `#:` method type.
+  #: %a{rigor:v1:return: non-empty-string} () -> String
+  def label = "x"
 end
 ```
 
+Several annotations may stand before the method type
+(`#: %a{pure} %a{rigor:v1:return: non-empty-string} () -> String`).
+The other inline-RBS readers do not accept all three:
+
+| spelling | rbs's built-in inline parser, Steep with `inline: true` | the `rbs-inline` gem's own `--output` |
+| --- | --- | --- |
+| own line | syntax error (`expected a token pARROW`), annotation lost | annotation kept |
+| same line | annotation and method type kept | annotation kept, method type **dropped** |
+
+Rigor keeps both halves of every row. If you also run Steep in
+inline mode, use the same-line spelling. The measurement is in
+[ADR-111](../adr/111-inline-refinement-carrier.md). If the method type after a same-line annotation
+does not parse, the method is left untyped and Rigor reports it as
+[`plugin.rbs-inline.source-rbs-annotation-not-honoured`](plugins/rigor-rbs-inline.md#same-line-annotations).
+
 This needs the `rbs-inline` library installed; Rigor ingests
 inline annotations by default when it is
-([ADR-93](../adr/93-default-rbs-inline-ingestion.md)). There is
-no Rigor-only comment dialect: `# rigor:` comments remain
-suppression-only.
+([ADR-93](../adr/93-default-rbs-inline-ingestion.md)). `# rigor:`
+comments remain suppression-only.
+
+A dedicated `# @extrbs` comment for what RBS cannot spell is
+accepted in [ADR-112](../adr/112-extrbs-comment-channel.md) but
+not implemented yet ([#1073](https://github.com/rigortype/rigor/issues/1073)).
+Until it ships, the `%a{}` forms above are the inline route. A type
+plain RBS can spell, such as `:asc | :desc`, belongs in `# @rbs` or
+`#:` either way.
+
 This page is the *operational* reference — the directives you can
 write and their syntax. For the normative rules (conflict
 handling, merging, provenance) see
@@ -183,7 +214,9 @@ class UserRepository
 end
 ```
 
-The same two work as rbs-inline comments in a `.rb` file:
+The same two work as rbs-inline comments in a `.rb` file, in any of
+the three spellings shown above — the own-line
+one here:
 
 ```rb
 # rbs_inline: enabled

data/docs/manual/19-effect-labels.md

@@ -214,6 +214,16 @@ rigor effects --pure
 436 methods on Redmine, and they are your `%a{pure}` candidates — the on-ramp to
 the last section of this chapter.
 
+You do not have to write them all out by hand. With the `effects:` block in
+place, `rigor sig-gen` annotates the methods in this set whose signature it is
+proposing anyway: `%a{pure}` above every method that is exhaustive, undischarged,
+free of surviving `≤` labels, not already carrying a bound you wrote, and calling
+nothing the analyzer had no description for; and, under `--effect-envelopes`, the labelled spelling for the methods that
+do have a footprint. A method that is clean only because `effects.tolerated:`
+says so is deliberately left bare — the annotation would travel to readers who
+do not share your tolerated list. See
+[handbook chapter 11](../handbook/11-sig-gen.md#emitting-effect-annotations).
+
 ### Asking it a question
 
 **By label.** The question this chapter opens with, in one command:

data/docs/manual/plugins/README.md

@@ -54,6 +54,9 @@ The full catalogue, with a one-line scope for every plugin, is
   `Result` / `Option` unwrap types and synthesises `Enum` variants.
 - [rigor-pundit](rigor-pundit.md) — policy-class existence and
   `authorize(record, :action)` predicate validation.
+- [rigor-active-model-serializers](rigor-active-model-serializers.md) —
+  types the `object` reader inside a serializer as the serializer's
+  model (no diagnostics).
 - [rigor-sidekiq](rigor-sidekiq.md) — Sidekiq `Worker.perform_*`
   argument arity against the discovered `#perform`.
 - [rigor-actioncable](rigor-actioncable.md) — `broadcast_to` channel
@@ -62,6 +65,10 @@ The full catalogue, with a one-line scope for every plugin, is
   through Minitest / Test::Unit assertions and spec matchers.
 - [rigor-graphql](rigor-graphql.md) — GraphQL-Ruby type / enum / input
   / mutation table publication (cross-plugin facts, no diagnostics).
+- [rigor-grape](rigor-grape.md) — types the `Grape::API` endpoint DSL
+  (`params`, `namespace`, verb macros, `desc`, `route_setting`) and
+  `Grape::Entity` `expose` declarations, including the `instance_eval`'d
+  block `self` bindings.
 - [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
   argument validation (out-of-range codes, unknown status symbols).
 - [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher

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

@@ -36,7 +36,7 @@ ActionCable.server.broadcast("chat_room_42", body: "hi")    # warning: no such s
 | `plugin.actioncable.broadcast-stream` | info | `ActionCable.server.broadcast("...", ...)` matched a registered `stream_from` literal |
 | `plugin.actioncable.unknown-channel` | error | the receiver ends in `Channel` but is not in the index (with a did-you-mean) |
 | `plugin.actioncable.unknown-stream` | warning | the literal stream name matched no `stream_from` registration (with a did-you-mean) |
-| `plugin.actioncable.load-error` | warning | channel discovery failed (parse/read error) — once per file |
+| `plugin.actioncable.load-error` | warning | channel discovery failed (parse/read error) — once per run, on `.rigor.yml` |
 
 The `unknown-stream` check is **suppressed** when any discovered
 channel registers a dynamic stream (`stream_from interpolated_string`
@@ -100,6 +100,13 @@ default.
 - **The `#receive` contract is path-scoped, not class-scoped** (ADR-28):
   any `def receive(data)` defined anywhere under `channel_search_paths`
   is typed, even on a class that isn't an ActionCable channel.
+- **The "failed to discover channels" 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-actionmailer.md

@@ -69,6 +69,13 @@ plugins:
   which the report already records. Rooting every class under
   `app/mailers` instead would mark a mailer nothing sends reachable
   forever on no evidence.
+- **The "failed to discover mailers" 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-actionpack.md

@@ -54,6 +54,7 @@ plugins:
     config:
       controller_search_paths: ["app/controllers"]  # default
       view_search_paths: ["app/views"]               # default
+      view_type_checks: false                        # default
 ```
 
 ## What it types
@@ -111,8 +112,250 @@ reason `ActionController::Parameters` and the `ActionDispatch` readers
 above stay undeclared; their leniency is what makes the `params`
 typing safe.
 
+## ERB templates as effect units
+
+Every `app/views/**/*.erb` is compiled to Ruby and analysed as one
+**effect unit**, keyed `view:users/show.html` — Rails' own logical
+name with the handler dropped, so an ERB → Haml rewrite is not a
+rename. Nothing has to be enabled: activating the plugin is what
+claims the templates.
+
+What that buys is the answer to *"what does this request actually
+do"* past the `render` line. A partial that calls `@user.update`
+reports `io.db.write` at `app/views/users/_card.html.erb`, a
+`Time.now` in a layout fragment reports `nondet.time`, a leftover
+`puts` reports `io.output.stdout` — all of it in `rigor effects` and
+in the snapshot, so a template that starts writing shows up in a
+diff.
+
+```
+$ rigor effects
+view:users/_card.html: [mutate.local, nondet.time] ≤ [io.db.write] …?
+view:users/show.html:  [mutate.local]              ≤ [io.db.read]  …?
+```
+
+**The compiler** is Erubi when it resolves in your project's bundle
+— Rails' own — and stdlib `ERB` otherwise. Erubi is never added to
+your Gemfile and is not a Rigor dependency
+([ADR-90](../../adr/90-target-library-resolution-from-project-bundle.md)).
+Either way the line map is measured rather than assumed, so a
+finding names the template's own line; the column is always 1,
+because a compiler rewrites the text of each line and a column of
+the compiled Ruby would name nothing you wrote.
+
+**What `self` is.** `ActionView::Base`, declared so the name
+resolves and **open** so its method surface stays lenient. That is
+what keeps `link_to`, `form_with`, `t`, `content_for`, your own
+`ApplicationHelper` methods and every route helper from drawing a
+finding per line.
+
+**What is in scope.** `@ivars` are seeded from the controller
+actions that render the template — the implicit render
+(`UsersController#show` → `users/show`) and explicit
+`render :edit` / `render "admin/form"`. Two restrictions keep a seed
+from claiming a type the template will not find. Only assignments
+whose right-hand side is one record and cannot be `nil` contribute:
+`User.find(id)` and `Model.new` do; `find_by` never does, nor a call
+written to return several records — `User.find(a, b)`,
+`User.find([1, 2])`, `User.find(*ids)`, `User.create([…])` or a
+`find` with a block. A single argument that only holds an Array at
+runtime (`User.find(ids)`) still seeds the model. And only
+assignments the action reaches on **every** path contribute — not
+one inside an `if`, a `case`, a `rescue`, a loop or a block, and
+nothing from a `before_action` carrying `if:` / `unless:`. Anything
+else leaves the ivar unseeded, which reads as `Dynamic` and is
+silent. A partial inherits the assigns of its own directory, because
+an ivar is not a local. Locals come from the Rails 7.1 strict-locals
+comment:
+
+```erb
+<%# locals: (user:, admin: false) %>
+```
+
+**`call.*` findings are off inside templates by default**, while the
+synthesised receivers are still coarse — measured on redmine and
+mastodon, the feature adds **zero** new findings to either
+([the measurement note](../../notes/20260917-erb-template-units.md)).
+Set `view_type_checks: true` to opt in and have `@user.nmae` in
+`show.html.erb` reported like any other call.
+
+`flow.*` **reports in a template like anywhere else.** It was
+suppressed alongside `call.*` for one measured reason — a partial's
+optional-local preamble (`<% path = nil unless defined? path %>`)
+really did assign nil, because nothing told the unit its render site
+had bound `path`. Render-site `locals:` are traced now, and the same
+two projects re-measured with the family reporting are byte-identical
+to the runs with it suppressed ([the #1047 note](../../notes/20260917-render-locals-and-layouts.md)).
+
+### Locals come from the render site
+
+A partial's parameters are bound by whoever renders it, and every
+spelling of that is read — on both sides of the render:
+
+```erb
+<%= render partial: "card", locals: { user: @user } %>
+<%= render "card", user: @user %>          <%# a view's trailing hash IS locals %>
+<%= render partial: "card", collection: @users, as: :row %>
+<%= render partial: "card", object: @user %>
+```
+
+`collection:` binds `row`, `row_counter` and `row_iteration`;
+`object:` and `as:` bind one local named after the partial or after
+`as:`. A controller's `render partial: …, locals: …` is read the same
+way — but a controller's *trailing hash* is options, so
+`render :show, status: :ok` binds nothing.
+
+A partial rendered from several sites gets the **union** of the
+names. A name only some of them pass is still bound, typed
+`Dynamic` — absence is what produced the false positives above.
+A **type** is claimed only where every site agrees on one it could
+settle from the call itself (`User.find(1)`, or an ivar the rendering
+action's own seeds typed); anything else is `Dynamic`. A
+strict-locals comment still wins where a template carries one.
+
+A partial's **own** optional-local test counts too:
+`<% size = nil unless defined?(size) %>`, `local_assigns[:size]` and
+`local_assigns.key?(:size)` bind `size` even when no render site the
+plugin can read passes it — a `locals: opts` hash, a `render` from a
+helper, or a local with a default nobody passes. A name a helper under
+`app/helpers` defines is left alone, so
+`<% if defined?(current_user) %>` stays a helper call. A helper that a
+gem or a concern defines is not seen by that scan, and its name is
+bound as a `Dynamic` local instead.
+
+### The controller → template edge
+
+A controller action's summary **includes what its template does**.
+`render :show`, `render "show"`, `render "admin/form"`,
+`render template:`, `render action:`, `render partial:` (with or
+without `collection:`) and the implicit render of
+`<controller>/<action>` all reach the template's own unit, and a
+template reaches the partials *it* renders — so an `io.db.write` in
+`app/views/users/_card.html.erb` shows up on `UsersController#show`
+three hops away, and `rigor effects explain` prints the path.
+
+A partial is looked up in the rendering template's own format, with
+the one fallback Action View itself hard-codes: a `.js.erb` template
+reaches `_list.js.erb` where it exists and `_list.html.erb`
+otherwise, which is how "a JS response that injects rendered HTML"
+works at all. Only one of the two is joined, never both. A `.json`,
+`.xml` or `.turbo_stream` template gets no fallback — what those fall
+back to depends on the request's `Accept` header, which the source
+does not say — and neither does a render site that names its format
+(`formats: [:js]`, `render "list.js"`) or a controller-side `render`.
+
+The fallback stops at a template that **exists and produced no
+unit**: a `_list.js.haml`, or a `_list.js.erb` whose compiled Ruby
+does not parse. Rails runs that file, so the `.html` one's effects
+are not what the render produces, and the taint stays. That is why
+this plugin claims `app/views/**/*.{haml,slim,jbuilder,builder,rabl,ruby}`
+and compiles none of them: the claim is how the engine learns a
+template is there. A handler outside that list is invisible, and a
+render of one still falls back.
+
+Two approximations ride along, and each costs labels rather than a
+taint. A partial reached *through* the fallback renders its own
+partials in `html`, while Action View's context is still
+`[:js, :html]`; where a nested partial exists in both formats, the
+`.js` template gets the `.html` one's labels. And a template whose
+name carries no format at all (`_row.jbuilder`) blocks nothing, since
+its key has no format to block — which happens to agree with Rails,
+which ranks a formatted template above it. Both are zero occurrences
+on the measured corpus.
+
+The `template-not-analysed` taint on a `render` is discharged
+exactly when the edge lands on a real unit. It **stays** when it
+does not, and both cases are common enough to name:
+
+- the target is computed — `render params[:view]`, or
+  `render formats: some_format`. The render site is read from
+  literals only, so anything computed keeps the honest "and possibly
+  more";
+- the target names no template this plugin compiled — a `render
+  partial: @thing`, or a partial that exists in neither the requested
+  format nor its fallback;
+- the template is outside `app/views/**/*.erb` — a Haml, Slim or
+  Jbuilder view, which this plugin does not claim.
+
+`render json:`, `render plain:` and the rest of the non-template
+family are left alone: they render no template, the rule declines,
+and the row reads exactly as it did before.
+
+An action that answered for itself is **not** edged to the
+conventional template. `redirect_to`, `head`, `send_data` and
+`send_file` each mean the implicit render did not happen, and
+attributing `users/away` to an action that redirects would be a view
+it never runs.
+
+### Holding views to an effect budget
+
+A view unit is an `effects.envelopes:` subject like any class, and a
+finding is positioned in the template:
+
+```yaml
+effects:
+  envelopes:
+    - match: "app/views/**/*"
+      effect: [mutate.local]
+```
+
+A bound judges only what Rigor proved by reading code, so what this
+catches in a view is what Rigor's own catalogue proves: a `puts`
+(`io.output.stdout`) or a `Time.now` (`nondet.time`).
+
+**Plugin-sourced labels are never judged by an envelope.** A plugin's
+statement about a framework method — `User.find` is `io.db.read`,
+`@user.update` is `io.db.write`, `perform_later` is `job.enqueue` —
+rides the declared (`≤`) lane, and the envelope check reads the proven
+one. Listing `io.db.read` in a view's envelope, or leaving it out,
+changes nothing: the lazy `<%= user.posts.count %>` is not a finding
+either way. That is a property of the whole Rails effect layer rather
+than of views ([ADR-103](../../adr/103-effect-labels.md) WD17, ruled
+in [#1059](https://github.com/rigortype/rigor/issues/1059)).
+
+What notices a view that starts reading the database is the effect
+snapshot. With `.rigor-effects.yml` committed, `rigor effects check`
+fails by default on drift in either lane, and a template that gains a
+query shows up in the diff as a declared-lane addition:
+
+```
+view:users/show.html  ≤+ io.db.read
+```
+
+That is a ratchet on the whole project's recorded effects, reviewed as a
+diff — not a policy scoped to `app/views/**/*`. See
+[Effect labels](../19-effect-labels.md#what-a-bound-can-and-cannot-see).
+
 ## Limitations
 
+- **A controller's own layout is not edged.** A layout is a unit
+  now, and a `render layout:` *inside a view* reaches it — but the
+  layout Rails wraps an action's template in (`layouts/application`,
+  or whatever `layout "base"` named) is not attributed to that
+  action. A callee rule may read the call's literals, the unit's
+  owner and the unit's key, and a layout's name is none of those:
+  it is a class-body declaration plus a convention lookup against
+  the view tree. So the layout's own effects reach a view that
+  renders it explicitly and no further.
+- **`yield` in a layout is a `String` and nothing more.** The
+  keyword is rewritten into a declared call on the view context so
+  the body parses; what the inner template produced is never
+  modelled.
+- **Unsaved render sites are not read in the editor.** The
+  render-site index reads templates and controllers from disk, so a
+  `locals:` you have typed but not saved does not reach the partial
+  until the save. A keystroke recompiles only the buffer, and a save
+  rebuilds the project's analysis as it always has. A view changed on
+  disk *without* a save the editor sees (a `git checkout`, a
+  formatter run elsewhere) recompiles every view on the next
+  publish, because a partial's locals can come from any of them. A
+  full `rigor check` does
+  the same compile work it did before — the index hands its compiled
+  sources to the unit transform rather than compiling twice.
+- **ERB only, under `app/views`.** `template_globs:` is a manifest
+  row, read without running plugin code, so it cannot consult
+  `view_search_paths:`. Haml, Slim and Jbuilder are the same seam
+  behind a different compiler and are not claimed.
 - **Implicit-self helpers only.** `*_path` / `*_url` calls with an
   explicit receiver (`Rails.application.routes.url_helpers.x_path`)
   are passed through.