rigortype 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 608dc6b03dfc9267330c24c6493f3f4ee2d025ac5ce01a044202828fc282e258
-  data.tar.gz: 395692680ea16ec6dc42d4187fc57c10ce00731eea4cd1d03176fcc2daa07c14
+  metadata.gz: d2aa3cbe98e027e6ed461d3252980ae558778e4df0b2c78f658b848e73b13d8b
+  data.tar.gz: 611f238af77124e90cab5844f65be0720898b93469eb7a908d1e82eb4d9a1177
 SHA512:
-  metadata.gz: c7145aafeaf9fd22fe3759970c9b4eaafd8720796048641a387ec7a02d4e579689fde37540db686da9904b7d8419a6338b9db7caa38997d7184960c346253f5a
-  data.tar.gz: bff814da943de361c7c1e5bee99fd0e4847d16bb8a9bd3e36609e69246e8eb0e141c6c6e87b425720d709e2277195d9a14100a3018fef75670361fe2acd2160b
+  metadata.gz: 8b82ef7bdde5d2f8ca978379190effc8730bd6dcb7224207282b9b820d06a2853cc61f87314ad6b8b7a0d81351f3aedd869d1f8449bb6f75e74f83baa56590b8
+  data.tar.gz: fe1685b7aad2412ea38090bdc53e350972c25522036330375eba7424457e086057018bad9827c35c1e4e0c65ca48d496bb54e5a8f58f0213668f4609053c7fdd

data/README.md

@@ -20,6 +20,8 @@ rigor check app lib                  # find bugs in the code you already have
 global `-g` install keeps it off your project's pins. See
 [Get started](#get-started-in-one-prompt).)
 
+If your project's bundle also lists `rbs` (directly, or through Steep or `rbs_rails`), the `rbs` that `gem:rigortype` puts on `PATH` can shadow it; see the [install guide's note on `rbs` shadowing](docs/install.md#case-a--mise-is-available-recommended).
+
 No annotations required, no runtime dependency, no changes to your
 code — and any RBS you do add, Rigor reads and uses. Rigor parses Ruby
 with
@@ -131,7 +133,7 @@ and [CI guide](https://rigor.typedduck.fail/manual/11-ci/).
 
 ```sh
 rigor check lib                 # find bugs (caches under .rigor/ — gitignore it)
-rigor init                      # drop a starter .rigor.yml
+rigor init                      # drop a starter .rigor.yml (suggests plugins from Gemfile.lock)
 rigor annotate lib/foo.rb       # reprint a file with inferred types in the margin
 rigor triage lib                # summarise diagnostics: distribution, hotspots
 rigor sig-gen --diff lib/foo.rb # emit RBS from inference (--write to save)
@@ -232,7 +234,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.6`** (2026-10-23) — on the
+Current release: **`v0.4.8`** (2026-11-15) — on the
 `0.4.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a

data/data/core_overlay/bigdecimal.rbs

@@ -0,0 +1,33 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- BigDecimal precision readers (issue #2969) ---
+#
+# rbs 4.2 ships `stdlib/bigdecimal/0/big_decimal.rbs` without `precision`, `scale`,
+# `precision_scale` or `n_significant_digits`, and the bigdecimal gem's own `sig/` (4.1.3)
+# omits them too, so `BigDecimal("1.5").precision` reported `call.undefined-method` on correct code.
+#
+# Upstream: bigdecimal 4.1.3 `ext/bigdecimal/bigdecimal.c` registers the four readers as instance
+# methods (`rb_define_method(rb_cBigDecimal, "precision", ...)`, and likewise for the other three).
+# Their documented results: `precision -> integer` (decimal digits), `scale -> integer`,
+# `precision_scale -> [integer, integer]`, and `n_significant_digits -> integer`.
+#
+# bigdecimal is a bundled gem, not a default library, so this file is gated on it
+# (`Rigor::Environment::RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS`). Without the library the file would
+# open a phantom `BigDecimal` that nothing else declares.
+#
+# The methods sit on a module the class includes, not as direct `def`s, so a later rbs or a project
+# `sig/` that declares one of them directly overrides it instead of raising
+# `DuplicatedMethodDefinitionError` (the same shape as `process.rbs` and `ruby41_core_overlay`).
+
+module RigorCoreOverlay
+  module BigDecimalPrecision
+    def precision: () -> Integer
+    def scale: () -> Integer
+    def precision_scale: () -> [Integer, Integer]
+    def n_significant_digits: () -> Integer
+  end
+end
+
+class BigDecimal
+  include RigorCoreOverlay::BigDecimalPrecision
+end

data/data/core_overlay/resolv.rbs

@@ -29,3 +29,33 @@ class Resolv
   def initialize: (?(Array[Resolv::Hosts | Resolv::DNS] | Hash[Symbol, untyped])? resolvers, ?use_ipv6: bool?) -> untyped
                 | ...
 end
+
+# --- Resolv::DNS#getresources / #getresource / #each_resource ---
+#
+# `rbs` declares the three typeclass lookups as answering the base class
+# whatever the typeclass argument names:
+#
+#   def getresources: (dns_name name, singleton(Resolv::DNS::Query) typeclass) -> Array[Resolv::DNS::Resource]
+#
+# so `dns.getresources(d, Resolv::DNS::Resource::IN::MX).map(&:exchange)`
+# false-fires `call.undefined-method` (`exchange` is declared on
+# `Resolv::DNS::Resource::MX`, not on `Resource`). At runtime every returned
+# record is an instance of the typeclass (rigortype/rigor#2828).
+#
+# The overlay prepends a generic overload binding `T` from `singleton(T)`, so
+# the answer is `Array[Resolv::DNS::Resource::IN::MX]`. An argument the
+# binder cannot read as a class object under the `Resource` bound leaves `T`
+# unbound, and the base overload (`| ...`) still accepts every `Query`
+# typeclass the upstream signature does.
+class Resolv
+  class DNS
+    def each_resource: [T < Resolv::DNS::Resource] (Resolv::DNS::dns_name name, singleton(T) typeclass) { (T) -> void } -> void
+                     | ...
+
+    def getresource: [T < Resolv::DNS::Resource] (Resolv::DNS::dns_name name, singleton(T) typeclass) -> T
+                   | ...
+
+    def getresources: [T < Resolv::DNS::Resource] (Resolv::DNS::dns_name name, singleton(T) typeclass) -> Array[T]
+                    | ...
+  end
+end

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -347,6 +347,35 @@ class Float
   def gigabytes: () -> Float
 end
 
+# ---------------------------------------------------------------
+# NumericWithFormat — ActiveSupport's `core_ext/numeric/conversions`, included into Integer, Float and
+# BigDecimal. Declared on the module and included, not as a `def` on each class, so a project `sig/` that
+# declares `Integer#to_fs` itself overrides it instead of raising `DuplicatedMethodDefinitionError` (the
+# `process.rbs` shape). Not pure: the Symbol formats read `I18n` for their locale. An Integer or String
+# format is `to_s(format)`, and no format is `to_s`, so every form answers a String. `options` is any
+# Hash-like value: ActiveSupport calls `symbolize_keys` on it, so String keys and a HashWithIndifferentAccess
+# are both valid.
+# ---------------------------------------------------------------
+
+module ActiveSupport
+  module NumericWithFormat
+    def to_fs: (?(Symbol | Integer | String | nil) format, ?Hash[untyped, untyped]? options) -> String
+    def to_formatted_s: (?(Symbol | Integer | String | nil) format, ?Hash[untyped, untyped]? options) -> String
+  end
+end
+
+class Integer
+  include ActiveSupport::NumericWithFormat
+end
+
+class Float
+  include ActiveSupport::NumericWithFormat
+end
+
+class BigDecimal
+  include ActiveSupport::NumericWithFormat
+end
+
 # ---------------------------------------------------------------
 # ActiveSupport::Duration — issue #632
 # ---------------------------------------------------------------
@@ -898,31 +927,34 @@ end
 
 class Hash[unchecked out K, unchecked out V]
   # `core_ext/hash/keys`
-  def symbolize_keys: () -> Hash[Symbol, V]
+  # `key.to_sym rescue key` keeps a key without `to_sym`, so no one key type is right: `Hash[untyped, V]` here,
+  # and with the plugin `dynamic_return` hook (#2433) maps each key member where it can.
+  def symbolize_keys: () -> Hash[untyped, V]
   def symbolize_keys!: () -> self
   def deep_symbolize_keys: () -> Hash[untyped, untyped]
-  def deep_symbolize_keys!: () -> self
+  def deep_symbolize_keys!: () -> Hash[untyped, untyped]
   def stringify_keys: () -> Hash[String, V]
-  def stringify_keys!: () -> self
+  def stringify_keys!: () -> Hash[String, V]
   def deep_stringify_keys: () -> Hash[untyped, untyped]
-  def deep_stringify_keys!: () -> self
+  def deep_stringify_keys!: () -> Hash[untyped, untyped]
   def assert_valid_keys: (*K | Array[K]) -> self
-  def deep_transform_keys: () { (K) -> K } -> Hash[K, untyped]
-  def deep_transform_keys!: () { (K) -> K } -> self
+  def deep_transform_keys: [X] () { (K) -> X } -> Hash[X, untyped]
+  def deep_transform_keys!: [X] () { (K) -> X } -> Hash[X, untyped]
   def deep_transform_values: () { (V) -> untyped } -> Hash[K, untyped]
-  def deep_transform_values!: () { (V) -> untyped } -> self
+  def deep_transform_values!: () { (V) -> untyped } -> Hash[K, untyped]
   # `alias_method`s of `symbolize_keys` / `symbolize_keys!`.
-  def to_options: () -> Hash[Symbol, V]
+  def to_options: () -> Hash[untyped, V]
   def to_options!: () -> self
 
   # `core_ext/hash/deep_dup`
   def deep_dup: () -> Hash[K, V]
 
-  # `core_ext/hash/deep_merge`
-  def deep_merge: (Hash[K, V]) -> Hash[K, V]
-                | (Hash[K, V]) { (K, V, V) -> V } -> Hash[K, V]
-  def deep_merge!: (Hash[K, V]) -> self
-                 | (Hash[K, V]) { (K, V, V) -> V } -> self
+  # `core_ext/hash/deep_merge` — the twin of the plugin's rows (#2424 review): the argument's keys join the
+  # receiver's, and a nested merge makes a value neither side declares, so values read `untyped`.
+  def deep_merge: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
+  def deep_merge!: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                 | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
   # `other.is_a?(Hash)` — the hook `ActiveSupport::DeepMergeable` asks before
   # recursing into a value. `:nodoc:`, but public.
   def deep_merge?: (untyped other) -> bool

data/data/gem_overlay/addressable/addressable.rbs

@@ -0,0 +1,40 @@
+# Addressable — `rbs collection` correction overlay (issue #2857).
+#
+# gem_rbs_collection's `gems/addressable/*/addressable.rbs` declares
+# `Addressable::URI.parse` as `(String | URI uri) -> instance`, but
+# `Addressable::URI.parse(nil)` returns nil, so `Addressable::URI.parse(x)`
+# on a `String?` — the mastodon `fetch_link_card_service.rb` shape — drew a
+# false `call.argument-type-mismatch` on correct code.
+#
+# Unlike the activesupport overlay this directory does NOT ride the ADR-72
+# `:missing` gate: it loads only when `rbs collection` supplies the gem's
+# RBS (`:rbs_collection` coverage — `Environment::GEM_OVERLAY_COVERAGE_SOURCES`).
+# The deferred-signature plan (#2422) then composes this declaration over the
+# collection's copy as an overload continuation, so `parse(nil)` binds nil
+# while `parse(String | URI)` keeps the URI answer and a `String?` argument
+# mismatches nothing. Under `:missing` coverage — no sigs at all — the
+# overlay stays unloaded on purpose: this partial `Addressable::URI`
+# declaration would make every member it omits (`host`, `path`, …) a false
+# `call.undefined-method`, which is worse than the `Dynamic` silence a
+# sig-less gem already has.
+module Addressable
+  class URI
+    # Two arms, URI-carrying first — the order is load-bearing, not cosmetic.
+    # `Addressable::URI` is RBS-known but not loadable in the analyzer's host
+    # process, so `NilClass`-vs-`Addressable::URI` acceptance answers `maybe`,
+    # and the overload selector's strict pass takes the FIRST maybe-match: a
+    # leading `(::NilClass)` arm would shadow this one and type
+    # `parse(existing_uri)` as `nil`. With the URI arm first it answers `yes`
+    # and wins; `nil` still reaches the second arm.
+    #
+    # `::NilClass`, not the `nil` keyword: they accept the same arguments, but
+    # RBS types `nil` as `Types::Bases::Nil`, which the
+    # `call.argument-type-mismatch` non-nil channel reads as "undecidable →
+    # admits", silently dropping `Addressable::URI.parse(123)`. `NilClass` is
+    # a `ClassInstance`, so the channel still refutes what no overload admits.
+    #
+    # The collection's own `(String | URI uri) -> instance` stays reachable as
+    # the `| ...` fallback the deferred plan appends.
+    def self.parse: (String | URI uri) -> URI | (::NilClass) -> nil
+  end
+end

data/data/vendored_gem_sigs/bundler/bundler.rbs

@@ -150,7 +150,7 @@ module Bundler
     # `#initialize`, `#specs` — declared by `sig/shims/bundler.rbs` with the same types.
     def platforms: () -> Array[untyped]
     def sources: () -> Array[untyped]
-    def dependencies: () -> Array[Dependency]
+    def dependencies: () -> Hash[String, Dependency]
     def ruby_version: () -> untyped
     def bundler_version: () -> untyped
   end

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -112,8 +112,9 @@ class Gem::Specification
 
   # Instance-side surface widely used by bundler / rubygems
   # internals. `attr_accessor` mirrors the writer + reader pair
-  # so the survey's `.name=` / `.version=` / `.full_gem_path=` /
-  # `.loaded_from=` / `.post_install_message=` writes resolve too.
+  # so the survey's `.name=` / `.version=` / `.loaded_from=` /
+  # `.post_install_message=` writes resolve too. `.full_gem_path` is declared on `Gem::BasicSpecification`,
+  # which this class inherits from.
   def activate: () -> untyped
   def specification_version: () -> Integer
   def files: () -> Array[String]
@@ -127,13 +128,13 @@ class Gem::Specification
   # `#version`'s READER is declared by `sig/shims/rubygems.rbs` (`attr_reader version (): Version`);
   # only the writer is ours.
   def version=: (Gem::Version) -> Gem::Version
-  attr_accessor full_gem_path: String
   attr_accessor loaded_from: String?
   attr_accessor post_install_message: String?
 end
 
 class Gem::BasicSpecification
   def version: () -> Gem::Version
+  attr_accessor full_gem_path: String
   def executables: () -> Array[String]
   def name: () -> String
   def full_name: () -> String

data/docs/handbook/01-getting-started.md

@@ -59,7 +59,7 @@ mise use gem:rigortype
 With mise activated in your shell, `rigor` is on your `PATH`. The
 gem is named `rigortype` (the name `rigor` was taken on RubyGems);
 the executable it installs is `rigor`. If you already have Ruby
-4.0, `gem install rigortype` works too.
+4.0, `gem install rigortype` works too. If the project's bundle lists `rbs`, 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).
 
 For shell activation and shims, `asdf`, and developing inside a
 container, see [Installing Rigor](../manual/01-installation.md);
@@ -283,8 +283,11 @@ If you used the [AI-assisted setup](#the-fast-path-let-an-ai-agent-set-it-up),
 the `rigor-project-init` skill already wrote one for you. To
 write a starter by hand, `rigor init` emits `.rigor.dist.yml`
 — the project default that gets committed, with `paths` and a
-`severity_profile` filled in, `target_ruby` commented out until
-you set it to your project's Ruby, and the rest commented out. That is all most projects need; the key
+`severity_profile` filled in. When your `Gemfile.lock` declares a
+gem a bundled plugin models, the template suggests that plugin
+under `plugins:`, commented out, for you to enable. `target_ruby`
+is commented out until you set it to your project's Ruby, and the
+rest is commented out too. That is all most projects need; the key
 reference, the JSON-schema editor integration, and `includes:`
 composition are in
 [Configuration](../manual/03-configuration.md).

data/docs/handbook/11-sig-gen.md

@@ -155,10 +155,41 @@ The `sig.skipped.*` reasons are:
   generic by an inline declaration and `sig/` does not declare
   it yet, or names its type parameters otherwise. See
   [Classes made generic inline](#classes-made-generic-inline).
+- `sig.skipped.generic-reopening` — the method's class, or one
+  it is nested in, is declared generic by loaded RBS with a
+  type parameter that has a bound or a default, and `sig/`
+  does not declare it. See
+  [Reopening a generic class](#reopening-a-generic-class).
 - `sig.skipped.inline-differs` — the method is declared
   inline and in `sig/`, and the two disagree. A refusal:
   `--write` and `--check` exit `1`. See
   [Methods declared inline](#methods-declared-inline).
+- `sig.skipped.overridden-bot` — the method's body never
+  returns (its inferred return is `bot`), and the analysed
+  code defines the method again, with `def` or
+  `define_method`: in a subclass, signed or not, in a class
+  that includes the method's module, in a module included
+  later or prepended, or as an extending class's own
+  singleton method. `bot` would describe only the base body
+  the overrides replace. A class left with nothing to write
+  because of this is still written as an empty class, so its
+  subclasses keep their signatures, unless your `sig/` or a
+  gem's signatures already declare it.
+- `sig.skipped.abstract-method` — the method's inferred return
+  is `bot` from an abstract-style raise: `NotImplementedError`,
+  an error class named `Abstract…` or `NotImplemented…`, or a
+  message that asks for the method to be implemented or
+  overridden, or to define it by name ("please define
+  about"; not "you must define a block"). The
+  implementations may live outside the analysed code, as in a
+  plugin gem, so no `bot` is proposed.
+- `sig.skipped.template-method` — the method's inferred return
+  is `bot`, its body does not end in a direct `raise`, `fail`,
+  `throw`, `exit` or `abort`, and it calls a method the
+  analysed code overrides or declares abstract, directly or
+  through self-dispatched calls. The call is matched by name,
+  whatever the receiver. A `bot` that ends in a direct
+  `throw` or a raise nothing overrides is still proposed.
 - `sig.skipped.top-level-def` — a plain top-level `def`, which
   defines a private `Object` method. sig-gen lists it (file,
   method name and this reason in `--format=json`) but writes no
@@ -180,6 +211,15 @@ The `sig.skipped.*` reasons are:
   down with it. The rest of the signatures are unaffected;
   the skipped method is reported on stderr, and it is worth
   reporting to us.
+- `sig.skipped.platform-guarded` — the method is defined in
+  a file Ruby loads only under a `RUBY_ENGINE`,
+  `RUBY_PLATFORM` or `defined?(…)` require guard (the
+  `if RUBY_ENGINE == 'truffleruby'` → `require
+  "stackprof/truffleruby"` shape), so it is not an ordinary
+  definition for every platform. sig-gen withholds the
+  proposal when another scanned file also defines the
+  method, or when the inferred return is `bot` — the shape
+  a raising stub takes (#3035).
 
 ### Tighter returns keep the declared parameters
 
@@ -330,10 +370,34 @@ so a return inferred for the new line would describe
 parameters that are about to change. Delete the `sig/` member
 and re-run; sig-gen then writes the method afresh.
 
+### Reopening a generic class
+
+When your code reopens a class that loaded RBS declares
+generic — `class Array`, `class Hash`, a gem's class, or one
+your `sig/` declares — sig-gen writes the header with that
+declaration's type parameters: `class Array[unchecked out E]`.
+rbs rejects a reopening whose parameters differ, so a bare
+`class Array` would fail the class, and every class whose
+signature mentions it, with `GenericParameterMismatchError`.
+The members still say `untyped` for the element type, and a
+class whose name matches a copied parameter is written
+anchored (`::E`), since a bare `E` would name the parameter.
+
+The parameters are copied only when every one is plain: a
+name, a variance and `unchecked`. A bound or a default
+(`class Box[T < Comparable]`) is a type written for the
+declaring file's namespace and could mean another class
+where sig-gen writes, so that class's methods, and those of
+classes nested in it, are skipped as
+`sig.skipped.generic-reopening`. Declare the class in `sig/`
+with its parameters and sig-gen writes the members into that
+declaration. A file that already declares the class keeps its
+own header.
+
 ### Classes made generic inline
 
-sig-gen does not write a class's type parameters yet. A class
-declared generic inline (`# @rbs generic T`) is therefore not
+sig-gen does not copy type parameters from an inline
+declaration. A class declared generic inline (`# @rbs generic T`) is therefore not
 opened in `sig/`: a header without its parameters would make
 rbs reject the class, and every class whose signature mentions
 it, with `GenericParameterMismatchError`. Its methods, and
@@ -626,6 +690,24 @@ list is the current state):
   are recognised as user-authored and never produce a
   duplicate `def` insertion.
 
+Two rules shape the class declarations and type names around
+those methods:
+
+- **A subclass of a core or stdlib class** is declared even
+  when it has no method of its own to emit, so a method
+  returning one resolves: `class MyHash < Hash; end` is
+  written `class MyHash < ::Hash[untyped, untyped]`. The
+  declaration goes into the file written for its source file,
+  so it appears only when that source file has at least one
+  method to emit. A class some signature already declares is
+  left to that declaration.
+- **A type name a namespace shadows** is written with a
+  leading `::`. Inside a `module Foo` that declares a
+  `Foo::Set`, a method returning a core `Set` is written
+  `-> ::Set[untyped]`, because RBS would read a bare `Set`
+  there as `Foo::Set`. Where nothing shadows the name, it is
+  written bare as before.
+
 Method shapes the generator does **not** cover yet:
 
 - `define_method(:name) { ... }`.
@@ -643,7 +725,7 @@ two are wired today, one is reserved.
 | Policy | Behaviour |
 | --- | --- |
 | `untyped` (default) | Every parameter is spelled `untyped`. No inference-derived parameter contract is imposed on future callers. The user retains complete authorship over parameter typing. |
-| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
+| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. A literal argument is widened to its class first, so `"hello"` proposes `String` (#2254). With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
 | `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
 
 Under `--params=observed`, the `--print` / `--diff` JSON payload gains

data/docs/handbook/appendix-phpstan.md

@@ -20,7 +20,7 @@ unchanged. This appendix maps the vocabulary.
 | Default behaviour | Inference, fall back silent | Inference, fall back silent |
 | "Levels" | 0 – 10 (numeric) | `lenient` / `balanced` / `strict` (named) |
 | Per-rule control | `ignoreErrors:` regex, level demotion | `disable:`, `severity_overrides:` |
-| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor.baseline.json` (ad-hoc) |
+| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor-check.json` (ad-hoc) |
 | Stub format | PHP stub files | RBS files |
 | Custom narrowing | Type-Specifying Extensions | Plugins (Chapter 9) |
 | Custom return shape | Dynamic Return Type Extensions | Plugin `dynamic_return` |
@@ -140,10 +140,10 @@ severity controls, and includes.
 | `ignoreErrors:` (regex / pattern) | `disable:` (rule identifier or wildcard) |
 | `parameters: ignoreErrors:` per-path | `# rigor:disable-file <rule>` at the file head |
 | `includes:` | `includes:` |
-| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor.baseline.json` (ad-hoc) |
-| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor.baseline.json` (ad-hoc) |
+| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor-check.json` (ad-hoc) |
+| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor-check.json` (ad-hoc) |
 | `phpstan analyse` | `rigor check` |
-| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor.baseline.json` (ad-hoc) |
+| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor-check.json` (ad-hoc) |
 | Path resolution: relative to declaring file | Path resolution: relative to declaring file (same rule). |
 
 Rigor has two baseline mechanisms: a **managed** baseline

data/docs/install.md

@@ -109,6 +109,26 @@ A user-wide `~/.config/mise/config.toml` entry for `gem:rigortype`
 keeps applying outside this project. Mention it if it names an older
 version, but do not edit global config without the user's consent.
 
+`gem:rigortype` also puts an `rbs` on `PATH`: mise wraps every
+executable the gem's dependencies install, and that wrapper runs with
+rigortype's private `GEM_HOME`. When `rbs` is in the project's bundle
+(`Gemfile.lock` lists it, directly or through Steep or `rbs_rails`)
+and the bundle uses the default path, `bundle exec rbs` runs the
+wrapper instead of the project's `rbs`. A git-sourced gem then fails
+with `is not yet checked out` under rigortype's `GEM_HOME`. A bundle
+installed under a configured path such as `vendor/bundle` is not
+affected, because `bundle exec` puts that path's `bin` first. Only
+when `Gemfile.lock` lists `rbs`, run `mise exec -- bundle exec which
+rbs` (the shell you are in has not picked up the new tool yet, so a
+bare `bundle exec which rbs` can miss it). If it prints a path under
+`installs/gem-rigortype/`, tell the user, and tell them the fix is
+local to this checkout: `bundle config set --local path vendor/bundle`
+followed by `bundle install` writes an untracked `.bundle/config`
+(teammates and CI keep the default path), puts the bundle in
+`vendor/`, and makes Rigor read each bundled gem's shipped `sig/`
+(ADR-27). Offer it; do not change the bundle path without their
+consent.
+
 Then verify:
 
 ```sh

data/docs/manual/01-installation.md

@@ -28,6 +28,14 @@ so nothing is lost by installing it separately.
 > [Rails quickstart](14-rails-quickstart.md)). The channels below
 > are the manual route.
 
+> **Only trying Rigor in VS Code?** When the
+> [Rigor extension](../../editors/vscode/README.md) finds no `rigor`,
+> it offers to install one into its own storage, using a Ruby 4.0
+> already on the machine (or one `mise install ruby@4.0` provides).
+> That install serves the editor only and is never used for a project
+> that pins `rigortype`; for the command line and CI, use a channel
+> below.
+
 ### Set up in your language
 
 The prompt above is plain natural language — your agent follows the
@@ -269,6 +277,8 @@ A few things worth knowing if you have not used mise before:
 The gem is `rigortype`; the executable it installs (and the only
 command you run) is `rigor`.
 
+If the project's bundle lists `rbs`, the `rbs` that `gem:rigortype` puts on `PATH` can shadow the project's own; see the [install guide's note on `rbs` shadowing](../install.md#case-a--mise-is-available-recommended).
+
 ### Putting `rigor` on your PATH
 
 Installing the tool is not enough on its own — `rigor` reaches your
@@ -356,8 +366,63 @@ gem install rigortype
 `asdf` has no general-purpose gem backend, so the gem itself is
 installed with `gem install` rather than an `asdf` command. `mise`
 (above) is the more integrated option because its `gem:` backend
-records the gem in the same config that records Ruby, and — as the
-next section explains — keeps the two from interfering.
+records the gem in the same config that records Ruby, and — as
+[Simple alternative](#simple-alternative--gem-install) explains —
+keeps the two from interfering.
+
+## Secondary — a pinned bundle
+
+The rule at the top of this chapter is about your *application's*
+`Gemfile` — the one Bundler resolves against your app's gems, and whose
+entries `Bundler.require` loads at boot. It is not a rule against
+Bundler. A `Gemfile` holding nothing but Rigor, resolved separately and
+selected with `BUNDLE_GEMFILE`, keeps every property the prohibition
+exists to protect: your application's dependency graph never meets
+Rigor's, and your application's Ruby is never constrained by Rigor's.
+
+Commit it, with its `Gemfile.lock`, at `.github/rigor/`, the path Rigor's
+CI template uses. The VS Code extension runs it (discovery kind
+`pinned-bundle`, under a Ruby it finds the way it does for its managed
+Rigor, preferring one that matches the lockfile's `RUBY VERSION` or
+the Gemfile's `ruby` line; `rigor.server.bundleGemfile` names another
+location), and never a different Rigor while it pins one.
+`rigor doctor` does not recognise it yet
+([#2751](https://github.com/rigortype/rigor/issues/2751)):
+
+```ruby
+# .github/rigor/Gemfile
+source "https://rubygems.org"
+ruby ">= 4.0.0", "< 4.1"
+gem "rigortype", "~> 0.4"
+```
+
+Each command has to run under a Ruby 4.0, which is usually not your
+project's Ruby, so select it on the command line:
+
+```sh
+# with mise
+BUNDLE_GEMFILE=.github/rigor/Gemfile mise exec ruby@4.0 -- bundle install
+BUNDLE_GEMFILE=.github/rigor/Gemfile mise exec ruby@4.0 -- bundle exec rigor check
+# with rbenv
+BUNDLE_GEMFILE=.github/rigor/Gemfile RBENV_VERSION=4.0.5 bundle exec rigor check
+```
+
+A `.ruby-version` inside `.github/rigor/` does not select it, because
+Rigor runs from the project root, and neither does a Bundler binstub,
+whose `#!/usr/bin/env ruby` runs the project's Ruby.
+
+The same pin then serves local runs and CI, Dependabot can keep it
+current (see [Pinning Rigor's version](11-ci.md#pinning-rigors-version)
+in the CI chapter), and it is where a third-party Rigor plugin gem
+goes. What it does **not** do is provide Ruby: every `bundle exec`
+must already run under a Ruby 4.0, which the `ruby` line checks. Only
+`rigortype` is pinned exactly; the lockfile records the dependency
+versions Bundler resolved when you installed.
+
+It is more moving parts than `mise use --pin gem:rigortype`, which
+records the version and the Ruby in one place and needs no `bundle
+exec`. Reach for it when your team already runs everything through
+Bundler, or needs a plugin gem — not as a first choice.
 
 ## Simple alternative — gem install
 
@@ -386,30 +451,6 @@ reach it. A `gem install` under a Ruby 4.0 you never switch away from
 is perfectly fine; one that shares a Ruby with projects you switch
 between is a footgun.
 
-## If you want Bundler to manage the version
-
-The rule at the top of this chapter is about your *application's*
-`Gemfile` — the one Bundler resolves against your app's gems, and whose
-entries `Bundler.require` loads at boot. It is not a rule against
-Bundler. A `Gemfile` holding nothing but Rigor, resolved separately and
-selected with `BUNDLE_GEMFILE`, keeps every property the prohibition
-exists to protect: your application's dependency graph never meets
-Rigor's, and your application's Ruby is never constrained by Rigor's.
-
-That arrangement — a `Gemfile` under `.github/rigor/`, plus the
-Dependabot config that keeps it current — is written up under
-[Pinning Rigor's version](11-ci.md#pinning-rigors-version) in the CI
-chapter. Nothing about it is CI-specific:
-
-```sh
-BUNDLE_GEMFILE=.github/rigor/Gemfile bundle exec rigor check
-```
-
-It is more moving parts than `mise use --pin gem:rigortype`, which
-records the same version in one line and needs no `bundle exec`. Reach
-for it when your team already runs everything through Bundler and wants
-Rigor on the same footing — not as a first choice.
-
 ## Nix
 
 If you use Nix, Rigor's flake exposes the executable as a package,