rigortype 0.4.6 → 0.4.8

data/docs/manual/03-configuration.md

@@ -24,7 +24,7 @@ Relative paths in a config file resolve against that file's own directory, with
 `rigor` runs from. They match only when you run `rigor` from the directory that holds the config file, which is
 the usual case; with `--config path/to/.rigor.yml` from elsewhere, give these three as absolute paths.
 A leading `~/` (or a bare `~`) in a path setting expands to your home directory; `~name` is an ordinary
-directory called `~name`, not another user's home. This covers `paths:`, `signature_paths:`, `test_paths:`,
+directory called `~name`, not another user's home. This covers `paths:`, `signature_paths:`, `core_root:`, `test_paths:`,
 `pre_eval:`, `plugins_io.allowed_paths:`, `includes:`, `bundler.bundle_path:`, `bundler.lockfile:` and
 `rbs_collection.lockfile:`. It does not apply to `cache.path:`, `baseline:` or `effects.snapshot.path:`, which stay
 literal and relative to the working directory.
@@ -78,9 +78,39 @@ cache:
 | --- | --- | --- | --- |
 | `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
 | `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
+| `core_root` | String | `nil` | A directory of core `.rbs` files loaded **instead of** the `rbs` gem's own core, such as one [rbs-shifter](https://github.com/rigortype/rbs-shifter) generates for an older CRuby. A relative path resolves against the config file's directory. `nil` loads the gem's core. See [Analysing for an older Ruby](#analysing-for-an-older-ruby). |
 | `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. The walker does not follow `require` / `require_relative`, so list the files in load order: a method declared in two files takes the last-listed one, and a file that requires a later-listed one is still read in list order. `type-of`, `type-scan`, `trace`, `annotate` and `sig-gen` read the patches too, so they type a patched method as `rigor check` does. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
+#### Analysing for an older Ruby
+
+Rigor runs on Ruby 4.0, and its bundled core signatures describe Ruby 4.0. A project that runs on an older
+Ruby can call a method that version does not have, and Rigor accepts the call. To check against the older
+API, point `core_root:` at a core signature directory written for it:
+
+```yaml
+target_ruby: "3.3"
+core_root: vendor/rbs-shifter/3.3/core
+```
+
+`core_root:` replaces the core, while `signature_paths:` only adds to it. A method that a signature directory
+omits stays declared by the default core, so `signature_paths:` cannot remove one. With the core above,
+`[1, 2].rfind { ... }` reports `call.undefined-method` and `" text ".strip(" ")` reports `call.wrong-arity`.
+Project signatures, plugins and `libraries:` still load on top of it. `target_ruby:` sets the syntax Rigor
+parses; it does not choose a core.
+
+A `core_root:` that does not exist, is not a directory, holds no `.rbs` file, lies inside (or contains) one of
+your `signature_paths:`, or does not build an RBS environment stops the run with exit code 64. A core class
+whose definition fails to build because of the core's own files is reported as an
+`rbs.coverage.definition-build-failed` error:
+
+```
+rigor: core_root: "/path/to/vendor/rbs-shifter/3.3/core" does not exist
+```
+
+The cache keys on the directory and on the contents of its files, so switching cores or regenerating one
+invalidates cached results, including in a running language server.
+
 ### Signature generation
 
 | Key | Type | Default | Meaning |
@@ -144,7 +174,10 @@ is left alone, other than the reserved run-level rows (`rbs.coverage.…`,
 those rows are the intended keys and are never flagged, while a bare plugin
 rule, `all`, or a `plugin.`-qualified key for an unconfigured plugin is. The same findings appear in the
 `--format=json` payload under `config_warnings` (each tagged with a
-`kind`), so CI can assert on them.
+`kind`), so CI can assert on them. The [language server](09-editor-integration.md)
+shows each one as a `window/showMessage` warning, and every
+[MCP tool](10-mcp-server.md#tool-reference) that takes a `config`
+argument includes them in its result.
 
 ### Diagnostics
 
@@ -194,12 +227,50 @@ project Ruby's gem home without running your toolchain. If `rigor check`'s
 `--stats` shows gems whose RBS it could not find, point it at the bundle
 explicitly with `bundler.bundle_path:`, or supply signatures another way:
 `rbs collection install` (auto-discovered) or `dependencies.source_inference:`.
-| `rbs_collection.auto_detect` | Boolean | `true` | Auto-discover `rbs_collection.lock.yaml`. |
+| `rbs_collection.auto_detect` | Boolean | `true` | Auto-discover `rbs_collection.lock.yaml`. A `source: { type: stdlib }` entry loads that stdlib library, as `libraries:` would. An entry is not loaded for a gem your `Gemfile.lock` sources from a `path:` directory that is at or under one of your `paths:` entries, or contains one, and is not left out by `exclude:` (the gem is code Rigor analyses, which your `sig/` declares). |
 | `rbs_collection.lockfile` | String | `nil` | Explicit `rbs_collection.lock.yaml` path. |
 | `dependencies.source_inference` | Array | `[]` | Per-gem source-inference modes (ADR-10). |
 | `dependencies.budget_per_gem` | Integer | `5000` | Per-gem source-walk cap, counted in **method definitions** (not time): the walker stops harvesting a gem's catalog once it reaches this many `def`s, then emits `dynamic.dependency-source.budget-exceeded` and degrades the rest to `Dynamic[top]`. Range 1250–20000. |
 | `dependencies.budget_overrun_strategy` | String | `"walker_cap"` | What happens to calls on a gem that hit `budget_per_gem` (ADR-10 § 5b). `walker_cap` (default) lets methods past the cap fall through to the engine's normal user-class resolution. `dependency_silence` instead resolves any call on a class from a budget-exceeded gem to `Dynamic[top]`, silencing `call.undefined-method` on that gem's unrecorded surface at the cost of weaker static checking there. |
 
+#### Running Rigor in a gem_rbs_collection `_test/` directory
+
+To check a signature you are writing for
+[`ruby/gem_rbs_collection`](https://github.com/ruby/gem_rbs_collection), run
+Rigor in the gem's `gems/<name>/<version>/_test/` directory after the
+collection's own test setup:
+
+1. Run `bin/test gems/<name>/<version>` once from the collection root. It
+   writes `rbs_collection.yaml` and `rbs_collection.lock.yaml` into `_test/`
+   and installs the gem and its dependencies into `_test/.gem_rbs_collection/`,
+   with your working tree linked in as a `local` source.
+2. Put a `.rigor.yml` in `_test/`:
+
+   ```yaml
+   paths: ["."]
+   signature_paths: ["."]
+   ```
+
+   This is the shape of the `Steepfile` that `bin/test` writes (`check "."`,
+   `signature "."`). Rigor finds the lockfile and loads the gem and its
+   dependencies from it, and `signature_paths: ["."]` loads the `.rbs` files in
+   `_test/` itself. Without that line, the types those test signatures declare
+   are absent and calls into them are not checked.
+
+   `signature_paths: [".."]` is also safe. It loads the gem from your working
+   tree, and Rigor skips the lockfile's copy of the same gem and version, so the
+   gem is not loaded twice. Use it when the lockfile's copy is not your working
+   tree, for example when `rbs_collection.yaml` names a `git` source instead of
+   the collection's `gems/` directory.
+3. Run `rigor check` in `_test/`.
+
+Rigor skips every `_`-prefixed directory inside a collected gem, such as another
+gem's `_test/` fixtures, as `rbs` does. Rigor does not read `manifest.yaml`
+or a gemspec to find dependencies. Without a lockfile it loads none of them and
+reports `rbs.coverage.collection-not-installed` (`:info`), which tells you to run
+the `bin/test` setup, or `rbs collection install` where an `rbs_collection.yaml`
+is present.
+
 ### Execution
 
 | Key | Type | Default | Meaning |
@@ -237,8 +308,8 @@ config with no `effects:` key at all behave as `effects: {}` — collection,
 `effects.check`, and everything else on this page all turn on at their
 defaults. It only fills an *absence*: write `effects: false` and you stay
 opted out regardless, and any `effects:` block you do write is left exactly
-as written. It previews what becomes the default at **v0.4.0**
-([ADR-103](../adr/103-effect-labels.md) § WD15).
+as written. It previews what becomes the default at **v0.5.0**
+([ADR-103](../adr/103-effect-labels.md) § WD15, moved by § WD18).
 
 #### Entry-point presets
 

data/docs/manual/04-diagnostics.md

@@ -67,7 +67,7 @@ carries no `documentation_url`.
 | <a id="rule-flow-return-in-ensure"></a>`flow.return-in-ensure` | An explicit `return` inside an `ensure` clause — it overrides the method's in-flight return value and silently swallows any in-flight exception. A `return` in a nested `def`, lambda, or `define_method` block inside the `ensure` does not fire (it exits that inner frame). | high |
 | <a id="rule-flow-shadowed-rescue-clause"></a>`flow.shadowed-rescue-clause` | A `rescue` clause can never run because an earlier clause of the same chain already catches a superclass (or the same class) of every exception class it names. | high |
 | <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
-| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write, unless its RBS declaration (`@x: T` or an `attr_*` member) admits both writes. With `rigor-actionpack` or `rigor-actionmailer` loaded, writes in two different actions of a controller or mailer are not compared, since Rails runs one action per instance. A write in a private or protected helper, `initialize` or the same action still is, and so is one in a callback target or `helper_method` that a macro in the same file names. A public method named only by a macro in another file or a concern, or reached through a lambda callback, counts as an action, and so does an action another action calls. | high |
+| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write, unless its RBS declaration (`@x: T` or an `attr_*` member) admits both writes. A write in a block whose `self` is provably another object (`Other.new.instance_eval { @x = 1 }`, `Class.new { … }`, `X.class_eval { … }`, a `class << obj` body) sets that object's variable and is not compared. With `rigor-actionpack` or `rigor-actionmailer` loaded, writes in two different actions of a controller or mailer are not compared, since Rails runs one action per instance. A write in a private or protected helper, `initialize` or the same action still is, and so is one in a callback target or `helper_method` that a macro in the same file names. A public method named only by a macro in another file or a concern, or reached through a lambda callback, counts as an action, and so does an action another action calls. | high |
 | <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
 | <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 |
@@ -75,9 +75,10 @@ carries no `documentation_url`.
 | <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-plugin-api-surface"></a>`plugin.api-surface` | Plugin code (inside a class that inherits `Rigor::Plugin::Base`) calls a member that a `Rigor::Plugin` interface (`_Scope`, `_Environment`, `_Services`, `_FactStore`, `_Configuration`) does not declare, on a value that interface types: a hook's `scope`, `scope.environment`, and so on. The engine object answers the call today, but it is outside the plugin API Rigor promises to keep, so call a member the interface declares (`sig/rigor/plugin/interfaces.rbs`) or a public namespace instead. Off by default; reaches a run through the `plugin-api-surface` bleeding-edge feature (ADR-128), or a `severity_overrides:` key naming `plugin.api-surface` itself (a bare `plugin` key does not reach it). Calls of members every object has (`nil?`, `respond_to?`) and values that lost the interface type (a helper parameter with no signature, a join with an untyped value) stay silent; a call a `respond_to?` guard protects still reports. | 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-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 the loaded configuration file (`.rigor.yml` when none was loaded) 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 |
@@ -130,7 +131,7 @@ re-stamps it for the run. Three profiles, set with the
 | --- | --- |
 | `lenient` | Only proven diagnostics are errors; uncertain ones drop to `warning` / `info`. For incremental adoption on legacy code. |
 | `balanced` *(default)* | Most rules `error`; `dump.type` `info`; uncertain rules `warning`. |
-| `strict` | Nearly every rule is an `error`. The exceptions: `call.self-undefined-method` and `static.value-use.void` stay `off` (both opt-in only), `flow.unreachable-clause` stays `warning` pending its false-positive gate, and the three `suppression.*` rules stay `warning` — a stale suppression comment is worth telling you about, but it is not a reason to fail a build. CI-friendly. |
+| `strict` | Nearly every rule is an `error`. The exceptions: `call.self-undefined-method`, `static.value-use.void` and `plugin.api-surface` stay `off` (all three opt-in only), `flow.unreachable-clause` stays `warning` pending its false-positive gate, and the three `suppression.*` rules stay `warning` — a stale suppression comment is worth telling you about, but it is not a reason to fail a build. CI-friendly. |
 
 Under `balanced`, the rules that do **not** emit as `error`
 are:
@@ -139,7 +140,7 @@ are:
 | --- | --- |
 | `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker`, `effect.envelope-exceeded`, `effect.liskov-widened` |
 | `info` | `flow.unreachable-clause`, `dump.type`, `effect.unknown-label`, `effect.annotations-unchecked` |
-| `off` | `call.self-undefined-method`, `static.value-use.void` |
+| `off` | `call.self-undefined-method`, `static.value-use.void`, `plugin.api-surface` |
 
 Everything else emits as `error`. For one rule under all three
 profiles, `rigor explain <rule>` prints `Authored severity:` and

data/docs/manual/06-baseline.md

@@ -77,7 +77,9 @@ a diagnostic another layer has already suppressed.
 | `rigor baseline drift` | Show how buckets have moved — `--only=over` for buckets that grew, `reducible` for ones you have already improved past, `cleared` for empty ones. |
 | `rigor baseline prune` | Drop buckets that match nothing any more. `--dry-run` previews. |
 
-`generate` and `regenerate` analyse with your loaded configuration unchanged except that `baseline:` is off, so options such as `bleeding_edge`, `target_ruby` or `severity_overrides` shape the recorded set exactly as they shape `rigor check`.
+`generate` and `regenerate` analyse with your loaded configuration unchanged except that `baseline:` is off, so options such as `bleeding_edge`, `target_ruby` or `severity_overrides` shape the recorded set exactly as they shape `rigor check`. They analyse the configured `paths:` only: a positional path argument is rejected with a usage error (exit `64`), since a baseline over a subset of files would silently drop the entries of every other file. The other three subcommands reject a positional path the same way.
+
+The summary counts only the diagnostics the written buckets cover. A diagnostic with no rule — a **parse error** in a file Rigor could not parse, a missing `paths:` entry, or an internal error — or no path cannot be keyed, so it never enters the baseline. The command prints a second line saying how many, why, and which files. The exit status stays 0, but the next `rigor check` with `baseline:` wired still reports them and exits non-zero until you fix those files, exclude them, or remove a bad `paths:` entry.
 
 `generate` and `regenerate` take `--match-mode=rule` (the
 default — one bucket per file × rule) or `--match-mode=message`
@@ -103,11 +105,11 @@ snapshot in the repository and compares against it explicitly:
 
 ```sh
 # Once: capture the current diagnostic surface.
-rigor check --format=json > rigor.baseline.json
-git add rigor.baseline.json
+rigor check --format=json > rigor-check.json
+git add rigor-check.json
 
 # Per PR: compare against the committed snapshot.
-rigor diff rigor.baseline.json
+rigor diff rigor-check.json
 ```
 
 [`rigor diff`](02-cli-reference.md#rigor-diff) prints a `+ NEW`

data/docs/manual/08-skills.md

@@ -80,6 +80,17 @@ is not repeated here.)
   minimal hand-RBS residual, under a double gate (the site becomes
   protected *and* `rigor check` gains no new diagnostic). See
   [Type-protection coverage](15-type-protection-coverage.md).
+- **`rigor-rbs-contract`** — audits, repairs, and extends RBS
+  declarations as *contracts*: a gem's own `sig/`, an application's
+  `sig/`, or an entry contributed to `ruby/gem_rbs_collection`. It finds
+  where a declaration and the code disagree (`rigor check`'s
+  `def.return-type-mismatch`, `rigor sig-gen --diff`, use-site checks,
+  the library's documentation), changes a declaration only on cited
+  evidence, keeps a declared `void` unless the library documents a
+  value, and proves each change with a use-site test. On your own code
+  it asks you the contract questions the evidence leaves open; on a gem
+  you do not own, the gem's documentation decides. See
+  [ADR-131](../adr/131-declarations-are-contracts.md).
 - **`rigor-baseline-reduce`** — works an existing `.rigor-baseline.yml`
   down rule by rule. It prioritises with `rigor triage`, classifies each
   site as a real bug / safe stylistic finding / false positive, and

data/docs/manual/09-editor-integration.md

@@ -25,6 +25,7 @@ design + capability matrix lives in
 | `textDocument/documentSymbol` | Outline tree from Prism AST: `class` / `module` / `def` with nesting. |
 | `workspace/didChangeWatchedFiles` | Invalidates the per-session `Environment` + `Cache::Store` cache so saved files repropagate. |
 | `workspace/didChangeConfiguration` | Same — re-reads `.rigor.yml` / `Gemfile.lock` etc. |
+| `window/showMessage` | One warning per [configuration warning](03-configuration.md) — the lines `rigor check` prints on STDERR, such as a key that has no effect or a `disable:` token that names no rule. Sent on `initialized`, and again after a save only when re-reading `.rigor.yml` changed the set of warnings. |
 
 ## Prerequisites
 
@@ -34,6 +35,14 @@ install channels in [Installing Rigor](01-installation.md) provide it;
 `mise` is the recommended one because its shims make `rigor` available
 to GUI-launched editors that do not inherit your shell environment.
 
+The [VS Code extension](../../editors/vscode/README.md) also finds a
+mise or asdf shim when `rigor` is not on `PATH`. When it finds no
+`rigor` at all, it offers to install a **managed Rigor** into its own
+storage with a Ruby 4.0 already on the machine, and uses it as its
+last resort; a project that pins `rigortype` in `Gemfile.lock`,
+`mise.toml` or `.tool-versions` is never served by it. See the
+extension README's *Server discovery*.
+
 Do **not** add `rigortype` to your project's `Gemfile`. Rigor is a
 tool, not a library — installing it standalone keeps its Ruby version
 and its dependencies out of your application's resolution. See
@@ -51,8 +60,10 @@ rigor lsp [--transport=stdio] [--log=PATH] [--config=PATH]
 
 - `--transport=stdio` — default; only value accepted in v1. TCP /
   Unix-socket transports are queued.
-- `--log=PATH` — wire log + server debug to a file. Without it,
-  server-side logs go to stderr.
+- `--log=PATH` — append the wire log (each message in and out, one
+  line each) and the server's debug output from the start of the loop to
+  a file. Output before the loop starts still goes to stderr. Without
+  it, no wire log is written and server-side logs go to stderr.
 - `--config=PATH` — mirrors `rigor check --config=PATH`. Without
   it, `Configuration.discover` walks `.rigor.yml` / `.rigor.dist.yml`
   from the project root.
@@ -194,6 +205,14 @@ For a legacy bundler-based install, swap the connection list to
   there, the LSP should too. If `rigor check` fails, fix that
   first.
 
+**A rule still fires although `.rigor.yml` turns it off.**
+
+- Look for a `rigor:` warning the server showed when it started (or
+  after the save that changed `.rigor.yml`): a misspelt key such as
+  `undefined-method: "off"` at the top level, or a `disable:` token
+  that names no rule, has no effect, and the server says so once.
+  The same warnings appear on STDERR from `rigor check`.
+
 **Completion popup is empty.**
 
 - Completion only fires on a node with a known type. Receivers

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

@@ -193,6 +193,28 @@ All messages except `notifications/*` require a response.
 
 ## Tool reference
 
+Every tool that takes a `config` argument reports the configuration's
+warnings — the ones `rigor check` prints on STDERR, such as a key that
+has no effect or a `disable:` token that names no rule. `rigor_check`
+carries them in its own document; every other such tool appends a
+second `text` content block holding one JSON object, after the tool's
+own output, which is left unchanged:
+
+```json
+{"config_warnings": [{"kind": "unknown_key", "message": "`undefined-method` is not a recognized configuration key; it has no effect.", "key": "undefined-method", "suggestion": null}]}
+```
+
+Each entry has the shape of `rigor check --format json`'s
+`config_warnings` entries. There is no such block when the
+configuration has no warnings, or when it fails to load (the tool
+reports that error itself).
+
+`rigor_type_of` and `rigor_explain` print JSON whose top-level shape changes
+in the next minor release (`{ "schema_version": 1, "results" | "rules" |
+"skip_reasons": [...] }`). Until then, a successful call carries a final
+`text` content block, after any `config_warnings` block, with the one-line
+notice the CLI prints on STDERR. The tool's own document is left unchanged.
+
 ### rigor_check
 
 Analyze one or more Ruby files or directories for type errors,
@@ -222,9 +244,16 @@ undefined methods, arity mismatches, and nil-receiver risks.
 }
 ```
 
+When `.rigor.yml` has [configuration warnings](03-configuration.md)
+(a key or a `disable:` token that has no effect), the document carries
+them under `config_warnings`, as `rigor check --format json` does.
+
 `isError` is `false` when the run completes normally, even if
-diagnostics were found. `isError: true` signals a configuration or
-runtime failure (bad path, unreadable config, etc.).
+diagnostics were found. `isError: true` signals a usage or runtime
+failure: an unreadable `config`, or a `rigor_coverage` call whose
+`paths` leave nothing to measure. A missing path given to `rigor_check`
+is not one of these: it is reported in the diagnostics, and the call
+returns `isError: false`.
 
 **Typical agent use:** call `rigor_check` on the files an agent is
 about to edit, record the baseline, apply the edit, call again, diff
@@ -484,6 +513,13 @@ as `Constant` / `Nominal` / shaped / refined (precise) versus
 
 **Returns:** JSON — the same as `rigor coverage --format json`.
 
+A `paths` entry that is missing, or is not a Ruby file, is reported as
+`rigor coverage` reports it. Beside files that are measured it is skipped. The result
+then carries a second text block with the CLI's stderr, unfiltered: path
+warnings such as `missing.rb:1:1: warning: no such file or directory (skipped)`,
+and any other warnings. When no entry holds a Ruby file, the call is
+`isError: true` and the block says so.
+
 ```json
 {
   "summary": {

data/docs/manual/12-caching.md

@@ -190,9 +190,10 @@ unchanged tree, so it cannot see an edit that fails to re-check a
 file it affects. `--verify-incremental-edits=N` also edits `N`
 files one at a time, in memory and not on disk, and compares each
 warm recheck with a full analysis of the edited tree. Each file is
-edited twice: once emptied, and once reduced to its `class` /
-`module` declarations with every body dropped. It replays only
-those two removals, never an addition or any other edit.
+edited up to four times: once emptied, once reduced to its
+`class` / `module` declarations with every body dropped, and up
+to twice with one statement of a `class` / `module` body removed
+and the rest kept. It replays only removals, never an addition.
 
 Rigor is also precise about *what* an edit changed. Re-checking a
 file that many others depend on — a base class, a widely-used

data/docs/manual/14-rails-quickstart.md

@@ -61,7 +61,7 @@ mise use gem:rigortype
 ```
 
 `mise use` records the chosen versions in a `mise.toml` in the
-current directory and installs them in one step. Verify:
+current directory and installs them in one step. Rails projects with Steep or `rbs_rails` list `rbs` in the bundle, and the `rbs` that `gem:rigortype` puts on `PATH` can shadow it; see the [install guide's note on `rbs` shadowing](../install.md#case-a--mise-is-available-recommended) before running `bundle exec rbs`. Verify:
 
 ```sh
 rigor --version

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

@@ -108,10 +108,9 @@ annotations and no block gets told so, once per run:
 sig/slug.rbs:2:1: info: Effect annotations (`%a{pure}` / `%a{rigor:v1:effect …}`) are present in your project's signatures, but `.rigor.yml` carries no `effects:` block, so effect collection never runs and nothing checks them — they are documentation, not a contract. Add `effects: {}` to have Rigor prove what your methods do and check these bounds against it (ADR-103); an annotation alone never turns collection on, because that would make one line in one signature file more expensive for every run of the project.
 ```
 
-From **v0.4.0** collection is the default: a config with no `effects:` key at
-all behaves as `effects: {}`, and `effects: false` is how you opt out. On the
-`0.3.x` line you can preview that with
-`bleeding_edge: [effects-on-by-default]`.
+From **v0.5.0** collection is the default: a config with no `effects:` key at
+all behaves as `effects: {}`, and `effects: false` is how you opt out. Until
+then you can preview that with `bleeding_edge: [effects-on-by-default]`.
 
 One exception to all of this: `rigor effects` — the bare report — runs under an
 implicit empty block whether or not you configured one, so you can look before

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

@@ -397,21 +397,38 @@ diff — not a policy scoped to `app/views/**/*`. See
   knows what `rigor-rails-routes` published, and `permit`
   validation only what `rigor-activerecord` published — enabling
   those producers widens what this plugin can check.
-- **`params[:key]` stays untyped.** Inside a controller, `params`
-  types as `ActionController::Parameters`, and so does the result
-  of every builder method that always returns one — `require`,
-  `permit`, `permit!`, `expect`, `slice`, `slice!`, `except`,
-  `without`, `extract!`, `merge`, `merge!`, `reverse_merge`,
-  `reverse_merge!`, `with_defaults`, `with_defaults!`, `compact`,
-  `compact_blank`, `deep_dup` — so a chain built from them keeps a
-  concrete receiver throughout. A subscript read is deliberately
-  left untyped: `params[:missing]` is `nil` at runtime, and a type
-  that says otherwise would let the flow rules fold live
-  conditions (`if params[:q]`, `url.nil?`) to a constant and report
-  working code. Methods whose result depends on the call — `dig`,
-  `fetch`, `compact!`, and the block-less `select` / `reject` /
-  `transform_keys` / `transform_values` — are untyped for the same
-  reason.
+- **`params[:key]` is a gradual carrier.** Inside a controller,
+  `params` types as `ActionController::Parameters`, and so does the
+  result of every builder method that always returns one — `permit`,
+  `permit!`, `slice`, `slice!`, `except`, `without`, `extract!`,
+  `merge`, `merge!`, `reverse_merge`, `reverse_merge!`,
+  `with_defaults`, `with_defaults!`, `compact`, `compact_blank`,
+  `deep_dup` — when the receiver is `params` itself. A carrier
+  (`params[:tags]`) may hold an Array or a String at runtime, so a
+  builder call on one answers the carrier too, except `permit` and
+  `permit!`, which no core class defines and which answer `Parameters`.
+  `require`
+  and `expect` are different: Rails returns the value itself, which
+  can be a scalar (`params.require(:id).to_sym`), so they answer the
+  same `Dynamic[ActionController::Parameters]` carrier (#2947). A
+  `permit` or `permit!` after one (`params.require(:user).permit(:name)`)
+  still types as `Parameters`; other chain methods off a carrier stay
+  the carrier. A subscript read answers
+  `Dynamic[ActionController::Parameters | nil]` (#2430): the static
+  facet is the nilable `Parameters`, so `params[:user][:name]` and
+  `params[:user].permit(:name)` keep dispatching on that facet, and
+  the `Dynamic` wrapper lets the value cross a declared boundary such
+  as a `String` parameter, as a scalar param does at runtime. The
+  facet is nilable rather than the non-nil nominal on purpose:
+  `params[:missing]` is `nil` at runtime, and a non-nil type would
+  let the flow rules fold live conditions (`if params[:q]`,
+  `url.nil?`) to a constant and report working code. Methods on the
+  carrier outside the chain (`params[:q].to_s`) answer `Dynamic[top]`,
+  because the engine dispatches a `Dynamic` receiver without projecting
+  its facet: a loss of precision, not a false positive. Methods whose
+  result depends on the call — `dig`, `fetch`, `compact!`, and the
+  block-less `select` / `reject` / `transform_keys` /
+  `transform_values` — are untyped for the same reason.
 - **`flash[:key]` and `session[:key]` stay untyped too**, for that
   same reason and measured the same way. Both are leaf reads that
   return whatever was stored — or `nil` for a key that is not set.

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

@@ -32,6 +32,17 @@ path, no vendoring, no `signature_paths:` wiring.
 > surface. When it is loaded, the auto overlay stands down so the two
 > never double-declare.
 
+If the project also runs `rbs collection install` for `activesupport`,
+some methods are declared twice — `Object#acts_like?`,
+`Object#html_safe?`, `Time#to_fs` among them. Rigor merges the two:
+the plugin's signatures are tried first and the collection's still
+apply, so a call either one accepts type-checks. When your own `sig/`
+or inline RBS declares one of the plugin's methods, yours is used
+instead and the plugin's stands down; the run reports one
+`rbs.coverage.plugin-signature-stood-down` info row for the plugin's
+file, naming those methods and the file whose declaration is used for
+each.
+
 ## What it covers
 
 Roughly the top ~40 selectors plus their close neighbours, across:
@@ -42,6 +53,9 @@ Roughly the top ~40 selectors plus their close neighbours, across:
   `TrueClass` / `FalseClass`).
 - **Integer / Float** — Duration multipliers (`#days`, `#hours`,
   `#minutes`, …) and Bytes multipliers (`#megabytes`, `#gigabytes`, …).
+- **Integer / Float / BigDecimal** — `#to_fs` / `#to_formatted_s`
+  (`NumericWithFormat`: a Symbol format, an Integer radix or a String
+  format, and the no-argument `to_s` form).
 - **String** — inflections (`#underscore`, `#camelize`, `#classify`,
   `#constantize`, `#pluralize`, …), filters (`#squish`, `#truncate`),
   `#html_safe`, `#starts_with?` / `#ends_with?` (also on **Symbol**),
@@ -55,7 +69,15 @@ Roughly the top ~40 selectors plus their close neighbours, across:
 - **Hash** — `#symbolize_keys` / `#stringify_keys` (+ deep / bang) and
   their `#to_options` alias, `#deep_merge`, `#reverse_merge` /
   `#with_defaults` (+ bang), `#with_indifferent_access`, `#except!`,
-  `#extract!`.
+  `#extract!`. `#symbolize_keys` / `#to_options` map the key type per
+  member, as ActiveSupport does (`key.to_sym rescue key`): a `String` or
+  `Symbol` key reads as `Symbol`, and every other key (an `Integer`, a
+  `Float`, a project class) reads as `untyped`, because a mixin or a
+  project file can give any class a `to_sym`. So
+  `Hash[String, Integer]` gives `Hash[Symbol, Integer]` and
+  `Hash[Integer, Integer]` gives `Hash[untyped, Integer]`. Without the
+  plugin, on the activesupport overlay alone, the key reads `untyped`.
+  The bang forms answer the receiver's own type.
 - **Range** — `#overlaps?`, `#to_fs` / `#to_formatted_s`.
 - **Enumerable** — `#index_by`, `#index_with`, `#pluck`, `#exclude?`.
 

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

@@ -61,9 +61,23 @@ The plugin also types the annotation DSL's own expressions
 `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
+`Dynamic[top]` on a Sorbet codebase.
+
+On a `T::Struct`, `T::InexactStruct` or `T::ImmutableStruct`
+subclass, `prop :name, Type` and `const :name, Type` at the top
+level of the class body give `obj.name` the translated `Type`
+(`T.nilable(String)` reads `String?`; a form outside the table
+reads `Dynamic[top]`), and `prop` also answers `obj.name = v`.
+A relative constant in `Type` resolves from the class body's
+namespaces outward, and one that names no known class reads
+`Dynamic[top]`.
+A `const` has no writer, so `obj.name = v` still reports.
+Subclasses inherit the accessors, a `def` of the same name in
+the class body wins over the macro, and a `prop` nested under an
+`if` or a block reads `Dynamic[top]`. A `prop` call in a class
+outside the struct family defines nothing.
+
+What it does not model: `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

data/lib/rigor/analysis/baseline.rb

@@ -97,6 +97,13 @@ module Rigor
           new(buckets, project_root: project_root)
         end
 
+        # The diagnostics a baseline cannot address: no rule (a Prism parse error, a path or internal error) or no path.
+        # `#filter` passes these through and `from_diagnostics` leaves them out of every bucket; this is the one
+        # definition of both.
+        def unkeyable(diagnostics)
+          diagnostics.reject { |d| d.qualified_rule && d.path }
+        end
+
         private
 
         def parse_loaded(raw, path:, project_root:)
@@ -138,17 +145,12 @@ module Rigor
           raise LoadError, "#{path}: ignored[#{index}] `message:` is not a valid Regexp: #{e.message}"
         end
 
-        # Returns Hash{[file, rule, regex_or_nil] => Array<Diagnostic>}.
-        # In message mode, each unique message gets its own bucket;
-        # in rule mode, every diagnostic for a (file, rule) pair
-        # contributes to a single bucket regardless of message.
-        # File paths are normalised to relative before keying.
+        # Groups diagnostics by [file, rule, regex_or_nil]. In message mode, each unique message gets its own
+        # bucket; in rule mode, every diagnostic for a (file, rule) pair contributes to a single bucket regardless
+        # of message. File paths are normalised to relative before keying.
         def group_for_baseline(diagnostics, match_mode, project_root)
           root = Pathname.new(project_root)
-          diagnostics.each_with_object({}) do |diag, into|
-            next if diag.qualified_rule.nil?
-            next if diag.path.nil?
-
+          (diagnostics - unkeyable(diagnostics)).each_with_object({}) do |diag, into|
             rel = relative_path(diag.path, root)
             key = case match_mode
                   when :rule
@@ -160,18 +162,18 @@ module Rigor
           end
         end
 
+        def relative_path(path, root_pathname)
+          Pathname.new(path).relative_path_from(root_pathname).to_s
+        rescue ArgumentError
+          path # different drive letter on Windows or non-child path
+        end
+
         # Generates a Regexp source string for the baseline row. The string is `Regexp.escape`d so the YAML
         # round-trip produces a regex that matches the literal message. Users hand-editing the row can replace
         # the escaped form with a pattern.
         def message_pattern_for(message)
           Regexp.new(Regexp.escape(message.to_s))
         end
-
-        def relative_path(path, root_pathname)
-          Pathname.new(path).relative_path_from(root_pathname).to_s
-        rescue ArgumentError
-          path # different drive letter on Windows or non-child path
-        end
       end
 
       class LoadError < StandardError; end
@@ -181,11 +183,8 @@ module Rigor
       def initialize(buckets, project_root: Dir.pwd)
         @project_root = Pathname.new(project_root)
         @buckets = buckets.freeze
-        # For each (file, qualified_rule) pair, two arrays:
-        # - rule-ID rows (message_regex == nil)
-        # - message-pattern rows (message_regex != nil)
-        # The matcher walks message-pattern rows first (tighter match takes precedence); diagnostics that
-        # don't match any message row fall through to the rule-ID row if one exists.
+        # Buckets grouped by (file, rule). `claim_bucket_for` splits each group into message-pattern rows, tried
+        # first as the tighter match, and the rule-ID row (message_regex == nil) as the fallback.
         @by_pair = buckets.group_by { |b| [b.file, b.rule] }.freeze
         freeze
       end
@@ -216,7 +215,7 @@ module Rigor
 
         # Diagnostics that lacked a rule or a path bypass the baseline entirely (the baseline can't address
         # them).
-        unkeyable = diagnostics.reject { |d| d.qualified_rule && d.path }
+        unkeyable = self.class.unkeyable(diagnostics)
         [surfaced + unkeyable, silenced_count]
       end
 
@@ -225,7 +224,7 @@ module Rigor
       # - `:within`    — `actual <= count` (silenced by the filter).
       # - `:over`      — `actual > count` (over threshold; surfaced in the regular `rigor check` output).
       # - `:cleared`   — `actual == 0` (the bucket can be pruned).
-      # - `:reducible` — `0 < actual < count` (the bucket's count can be tightened; future `regenerate` slice 5
+      # - `:reducible` — `0 < actual < count` (the bucket's count can be tightened; `rigor baseline regenerate`
       #                  handles this).
       DriftRow = Struct.new(:bucket, :actual_count, :status, keyword_init: true) do
         def delta
@@ -254,8 +253,8 @@ module Rigor
         end
       end
 
-      # Returns a new Baseline with the given buckets dropped. Used by `rigor baseline prune` (slice 2) to
-      # remove cleared buckets (`actual == 0`) from the on-disk file.
+      # Returns a new Baseline with the given buckets dropped. Used by `rigor baseline prune` to remove cleared
+      # buckets (`actual == 0`) from the on-disk file.
       def without(buckets_to_drop)
         dropset = buckets_to_drop.to_set
         self.class.new(buckets.reject { |b| dropset.include?(b) }, project_root: @project_root)
@@ -311,9 +310,7 @@ module Rigor
         # over rule-ID rows because they're more specific. A diagnostic that matches no row goes into a
         # synthetic "no-bucket" bin keyed by (file, rule).
         bins = {}
-        diagnostics.each do |diag|
-          next if diag.qualified_rule.nil? || diag.path.nil?
-
+        (diagnostics - self.class.unkeyable(diagnostics)).each do |diag|
           bucket = claim_bucket_for(diag)
           key = if bucket
                   [bucket.file, bucket.rule,