rigortype 0.4.7 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 983cf341f34d4407d6d06ab2b0bf50260f5b52a4f6e29c61ce0042123ab833cc
-  data.tar.gz: 17ea6b8b13033e507d0e7570913ab2609c830c9a5cfa706cfe055b6857d315f5
+  metadata.gz: d2aa3cbe98e027e6ed461d3252980ae558778e4df0b2c78f658b848e73b13d8b
+  data.tar.gz: 611f238af77124e90cab5844f65be0720898b93469eb7a908d1e82eb4d9a1177
 SHA512:
-  metadata.gz: 0cd85174733cb61860d33f5636e81ac5d19972f9e6bd66fc6282d1aa7330735f8a57a067e1cfa81071632a45a0ca123f607be5b5bda7b3b32153fb8069328dfc
-  data.tar.gz: 64ecfde3bfe3eaef83ff44fa6ee1ca72bf6f353648c55a354726e60a87203012f907ce5406dc162289ff2a99056cf8b2962a79f636d5e7dd93cf16ec2b00e8d2
+  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
@@ -232,7 +234,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.7`** (2026-11-03) — 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
 # ---------------------------------------------------------------

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/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);

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

@@ -164,6 +164,32 @@ The `sig.skipped.*` reasons are:
   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
@@ -185,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
 

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,