rigortype 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b23cb8236c12aeeee7e95afef03a5db32b6644769af9d70bb9514c969aac7a4
-  data.tar.gz: acc54aa19e19a77279730981492509fc0bfec4436d7d24e7ffb7fc454c761c26
+  metadata.gz: 53ce9543e32229f3a80491f33886ac27cc0e1d3c0bb834536c703ab669188dd2
+  data.tar.gz: f9bb40e6e3a44a8bd362cee2b5f46a406d36391c5cf3053982950f4acae574df
 SHA512:
-  metadata.gz: 107bf59c35a02a22eca658fda615288c6f607ff94338c7c5b7671c799080b77a74386317a7d6f2f6c0ba73d7890114460e910a465c8f5a7eb7ac56ceaff67b11
-  data.tar.gz: eebc42e786b36caacc03112d93be9d5f91261ff2d3766b902e9bf61e8d26f1bb069776b94791d2d8ca43b662140c66b73bee0f7ac915c71da9a2f35a1d999eac
+  metadata.gz: f233af3b211b096772e29ee29eda2ef7a7bca353e02f300c0f6ed36cbfb66deb73df709486896207f9459a0fbb5203c155ed257790c7d8122562780b1a532391
+  data.tar.gz: 21ed0e73b967f692d6df3a65a9cd6444b5b801b545cb82cb59e4cec8d0effdcec4e8f9b97ebd7a811a0ebe8a08366bdaabbb07df1338a59a939e5d855281b2be

data/README.md

@@ -108,7 +108,7 @@ Ready-made prompts — 日本語, 简体中文, 繁體中文, 한국어, Españo
 Português, Français, Deutsch, Italiano, Tiếng Việt, ภาษาไทย,
 Bahasa Indonesia, Polski, Українська, Русский, Română, Türkçe,
 العربية, فارسی — are in
-the [installation guide](https://rigor.typedduck.fail/reference/manual/01-installation/#set-up-in-your-language).
+the [installation guide](https://rigor.typedduck.fail/manual/01-installation/#set-up-in-your-language).
 
 **Manual install** — Rigor is a tool, not a library: install it
 independently, **not** in your project's `Gemfile`. Install it
@@ -123,8 +123,8 @@ mise use -g ruby@4.0 gem:rigortype     # or: gem install rigortype
 
 The gem is named `rigortype` (the name `rigor` was taken on RubyGems);
 the executable is `rigor`. `asdf`, dev containers, and CI templates are
-in the [installation guide](https://rigor.typedduck.fail/reference/manual/01-installation/)
-and [CI guide](https://rigor.typedduck.fail/reference/manual/11-ci/).
+in the [installation guide](https://rigor.typedduck.fail/manual/01-installation/)
+and [CI guide](https://rigor.typedduck.fail/manual/11-ci/).
 
 ### Daily commands
 
@@ -145,7 +145,7 @@ TeamCity).
 1. **Types are facts, not wishes.** Hand-written annotations drift the
    moment they are written. Rigor infers from the code itself — every
    type is derived from what your source actually produces. When you do
-   want RBS in `sig/`, [`rigor sig-gen`](https://rigor.typedduck.fail/reference/adr/14-rbs-sig-generation/)
+   want RBS in `sig/`, [`rigor sig-gen`](https://rigor.typedduck.fail/adr/14-rbs-sig-generation/)
    emits it from inference results so the written form starts in sync
    with reality.
 2. **A false positive is the worst bug.** Your program works; a
@@ -161,7 +161,7 @@ TeamCity).
    literal values, integer ranges, refinements like
    `non-empty-string`, and per-position tuple / hash shapes — and
    exposes a plugin API plus a
-   [macro / DSL expansion substrate](https://rigor.typedduck.fail/reference/adr/16-macro-expansion/)
+   [macro / DSL expansion substrate](https://rigor.typedduck.fail/adr/16-macro-expansion/)
    so Rails-shape DSLs become first-class type sources.
 
 ## Works with your stack
@@ -202,10 +202,10 @@ interop, so adopting Rigor is strictly additive. When you want to
 in `sig/` files tighten types while staying a no-op for ordinary RBS
 tools.
 
-The twelve-chapter [handbook](https://rigor.typedduck.fail/reference/handbook/)
+The twelve-chapter [handbook](https://rigor.typedduck.fail/handbook/)
 walks the whole type model; the
-[type specification](https://rigor.typedduck.fail/reference/type-specification/)
-and [user manual](https://rigor.typedduck.fail/reference/manual/) are
+[type specification](https://rigor.typedduck.fail/type-specification/)
+and [user manual](https://rigor.typedduck.fail/manual/) are
 the reference companions.
 
 **Stuck on Rigor — or just curious how it works? Ask your agent in
@@ -231,7 +231,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.3.1`** (2026-07-29) — on the
+Current release: **`v0.3.2`** (2026-08-08) — on the
 `0.3.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
@@ -241,7 +241,7 @@ Mastodon, Redmine, and GitLab FOSS, and the deliberately conservative
 rule catalogue grows only as fast as the zero-false-positive bar
 allows. Release history: [`CHANGELOG.md`](CHANGELOG.md) ·
 forward-looking commitments:
-[Roadmap](https://rigor.typedduck.fail/reference/roadmap/).
+[Roadmap](https://github.com/rigortype/rigor/milestones).
 
 ## Contributing
 

data/data/core_overlay/pathname.rbs

@@ -19,6 +19,11 @@
 #
 # The overlay widens `dir` to `String | Pathname`, matching the runtime
 # delegation and the `File.expand_path` `path` alias used elsewhere in RBS.
+#
+# The `| ...` continuation is safe with no library loaded — unlike the
+# `RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS` files, its base declaration
+# lives in rbs's `core/pathname.rbs` on every supported rbs release
+# (3.10 / 4.0 / 4.1), not in the `pathname` stdlib library.
 class Pathname
   def expand_path: (?String | Pathname dir) -> Pathname
                  | ...

data/data/core_overlay/resolv.rbs

@@ -0,0 +1,31 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Resolv#initialize ---
+#
+# `rbs` before 4.1 declares `Resolv#initialize` as only:
+#
+#   def initialize: (?Resolv::Hosts | Resolv::DNS resolvers) -> untyped
+#
+# But `Resolv.new` takes an *array* of resolvers — the runtime default is
+# `[Hosts.new, DNS.new]`, and `each_address` iterates the argument — so the
+# documented, idiomatic call passes an Array:
+#
+#   Resolv.new([Resolv::Hosts.new, Resolv::DNS.new(nameserver: ...)])
+#
+# Against the pre-4.1 signature every overload rejects that Array and
+# `call.argument-type-mismatch` false-fires (measured on Mastodon's
+# `app/lib/request.rb`).
+#
+# `rbs` 4.1.0 fixed the signature upstream (ruby/rbs#2960); the overlay
+# backports that overload for the older releases the gemspec still supports
+# (`>= 3.0, < 5.0`). On 4.1 the appended overload duplicates the upstream
+# one, which costs nothing. Drop this file when the rbs floor reaches 4.1.
+#
+# Loaded ONLY when the `resolv` library resolves
+# (`RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS`): the `| ...` overload
+# continuation is invalid without the base declaration, and the resulting
+# `InvalidOverloadMethodError` would take the whole class down.
+class Resolv
+  def initialize: (?(Array[Resolv::Hosts | Resolv::DNS] | Hash[Symbol, untyped])? resolvers, ?use_ipv6: bool?) -> untyped
+                | ...
+end

data/data/core_overlay/string_scanner.rbs

@@ -23,6 +23,11 @@
 # earns its keep for a consumer resolving an older `rbs` inside the
 # gemspec's `>= 3.0, < 5.0` range. It stays until that floor moves;
 # reopening with an identical overload costs nothing on 4.1.
+#
+# Loaded ONLY when the `strscan` library resolves
+# (`RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS`): the `| ...` overload
+# continuation is invalid without the base declaration, and the resulting
+# `InvalidOverloadMethodError` would take the whole class down.
 class StringScanner
   def []: (Integer | String | Symbol) -> String?
         | ...

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -245,10 +245,10 @@ class Time
   def self.zone: () -> untyped # ActiveSupport::TimeZone | nil
   def self.zone=: (String | Symbol | untyped) -> untyped
 
-  # `core_ext/time/conversions` — also `Time.parse` from stdlib
-  # `time`, which is already in core RBS.
-  def self.httpdate: (String) -> Time
-  def self.iso8601: (String) -> Time
+  # `core_ext/time/conversions` — nothing to declare. `Time.parse`, `Time.httpdate` and `Time.iso8601`
+  # all come from stdlib `time`, which rbs types; ActiveSupport only re-opens them. Declaring them
+  # here raised `RBS::DuplicatedMethodDefinitionError` and collapsed the whole `Time` definition to
+  # `Dynamic[top]`.
 
   # `core_ext/time/calculations`
   def yesterday: () -> Time
@@ -278,7 +278,10 @@ class Time
   def midday: () -> Time
   def midnight: () -> Time
   def noon: () -> Time
-  def utc?: () -> bool
+  # NOTE: `Time#utc?` is NOT declared here — it is Ruby core, already typed by rbs's `core/time.rbs`.
+  # Re-declaring it raised `RBS::DuplicatedMethodDefinitionError` and took the WHOLE `Time` definition
+  # down with it (every `Time` call degraded to `Dynamic[top]`). This overlay only ADDS what
+  # ActiveSupport adds.
   def acts_like_time?: () -> true
 end
 
@@ -457,7 +460,8 @@ end
 
 class DateTime
   def utc: () -> Time
-  def to_time: () -> Time
+  # NOTE: `DateTime#to_time` is NOT declared here — stdlib `date` already types it, and re-declaring it
+  # collapsed the whole `DateTime` definition (see the `Time#utc?` note above).
   def in_time_zone: (?String | Symbol zone) -> untyped
   def yesterday: () -> DateTime
   def tomorrow: () -> DateTime

data/data/vendored_gem_sigs/bundler/bundler.rbs

@@ -2,14 +2,12 @@
 # Rigor-side vendored RBS stub for the `bundler` gem.
 #
 # The `bundler` gem does not ship its own `sig/` and is not
-# covered by `ruby/gem_rbs_collection`. The shim in
-# `references/rbs/sig/shims/bundler.rbs` (rbs gem upstream)
-# carries a tiny subset (`LockfileParser`, `LazySpecification`,
-# `Dependency`, `Definition`, `default_lockfile`, `definition`,
-# `Source::Gemspec`) but is only loaded when the user opts in via
-# `library "bundler"` — that's rare in Rigor `.rigor.yml` setups,
-# so most projects analyse bundler-using code with NO `Bundler`
-# RBS in scope.
+# covered by `ruby/gem_rbs_collection`. The rbs gem's own
+# `sig/shims/bundler.rbs` carries a tiny subset (`LockfileParser`,
+# `LazySpecification`, `Dependency`, `Definition`,
+# `default_lockfile`, `definition`, `Source::Gemspec`) — enough to
+# type rbs's own use of bundler, not enough to analyse a project
+# that uses it.
 #
 # This stub covers the Bundler module's top-25 singleton methods
 # surfaced by the `references/ruby/lib` survey
@@ -21,13 +19,23 @@
 # silence `call.undefined-method` rather than infer precise
 # returns.
 #
-# Declarations are intentionally a SUPERSET of the
-# `references/rbs/sig/shims/bundler.rbs` shim. When the user
-# opts into `library "bundler"`, the shim's typed declarations
-# (`LockfileParser#specs -> Array[LazySpecification]`, etc.)
-# would conflict; users who want both should drop the
-# `library "bundler"` entry from their config so this vendored
-# stub wins.
+# The `rbs` gem's own `sig/shims/bundler.rbs` IS always in scope:
+# `rbs` sits in `Environment::DEFAULT_LIBRARIES`, so its `sig/`
+# tree — shims included — loads on every run. This file therefore
+# declares only what the shim does NOT, and never re-declares a
+# shim method: a duplicate raises
+# `RBS::DuplicatedMethodDefinitionError` inside
+# `RBS::DefinitionBuilder` and collapses the ENTIRE class to
+# `Dynamic[top]` (issue #299). Where the shim's type is weaker
+# than Rigor's would have been, the shim still wins: an RBS
+# overload continuation (`| ...`) would append rather than
+# collide, but it raises `InvalidOverloadMethodError` when the
+# base declaration is absent, which breaks every environment
+# built without the `rbs` library. Those spots are marked below.
+#
+# Keep this file and `sig/shims/bundler.rbs` in sync on an `rbs`
+# bump — `spec/rigor/environment/bundled_rbs_definition_build_spec.rb`
+# fails the suite if a new collision reappears.
 #
 module Bundler
   # `Bundler.<name>` — accessors / module-level entry points.
@@ -46,7 +54,13 @@ module Bundler
   def self.require: (*untyped groups) -> untyped
   def self.load: () -> untyped
   def self.environment: () -> untyped
-  def self.definition: (?untyped unlock, ?untyped lockfile) -> Definition
+  # `self.definition` — declared by `sig/shims/bundler.rbs`. Note that the shim types it `() ->
+  # Definition` while the real `Bundler.definition(unlock = nil, lockfile = default_lockfile)` takes
+  # two optional arguments; an `| ...` overload continuation here would restore that arity, but a
+  # continuation with no base declaration raises `RBS::InvalidOverloadMethodError` — so any
+  # environment built WITHOUT the `rbs` library would lose the whole `Bundler` module to
+  # `Dynamic[top]`. The narrower arity is the cheaper of the two failure modes; the fix belongs
+  # upstream in the shim.
   def self.frozen_bundle?: () -> bool
   def self.locked_gems: () -> untyped
   def self.ruby_scope: () -> String
@@ -78,7 +92,7 @@ module Bundler
   def self.local_platform: () -> untyped
   def self.generic_local_platform: () -> untyped
   def self.default_gemfile: () -> Pathname
-  def self.default_lockfile: () -> Pathname
+  # `self.default_lockfile` — declared by `sig/shims/bundler.rbs` with the same type.
   def self.default_bundle_dir: () -> Pathname?
   def self.system_bindir: () -> String?
   def self.preferred_gemfile_name: () -> String
@@ -104,10 +118,9 @@ module Bundler
 
     def initialize: (*untyped) -> void
     def gemfiles: () -> Array[Pathname]
-    def lockfile: () -> Pathname
+    # `#lockfile`, `#locked_gems`, `#dependencies` — declared by `sig/shims/bundler.rbs` with the
+    # same types.
     def lockfile=: (untyped) -> untyped
-    def locked_gems: () -> LockfileParser
-    def dependencies: () -> Array[Dependency]
     def current_dependencies: () -> Array[Dependency]
     def requested_dependencies: () -> Array[Dependency]
     def dependencies_for: (untyped groups) -> Array[Dependency]
@@ -134,8 +147,7 @@ module Bundler
   end
 
   class LockfileParser
-    def initialize: (String body) -> void
-    def specs: () -> Array[LazySpecification]
+    # `#initialize`, `#specs` — declared by `sig/shims/bundler.rbs` with the same types.
     def platforms: () -> Array[untyped]
     def sources: () -> Array[untyped]
     def dependencies: () -> Array[Dependency]
@@ -144,16 +156,16 @@ module Bundler
   end
 
   class LazySpecification
-    def name: () -> String
-    def version: () -> Gem::Version
+    # `#name`, `#version`, `#dependencies` — declared by `sig/shims/bundler.rbs`. The shim types
+    # `#version` as `() -> String` where bundler returns a `Gem::Version`; see the note on
+    # `Bundler.definition` above for why that is left alone rather than corrected with an `| ...`
+    # overload continuation.
     def platform: () -> untyped
-    def dependencies: () -> Array[Gem::Dependency]
     def source: () -> untyped
   end
 
   class Dependency < Gem::Dependency
-    attr_reader autorequire: Array[String]?
-    attr_reader source: untyped
+    # `#autorequire`, `#source` — declared by `sig/shims/bundler.rbs` with the same types.
     attr_reader groups: Array[Symbol]
     attr_reader platforms: Array[Symbol]
   end

data/data/vendored_gem_sigs/cgi/cgi_extras.rbs

@@ -29,6 +29,12 @@
 # `include CGI::Util` + `extend CGI::Util`; adding a sibling
 # `include CGI::QueryExtension` is purely additive.
 #
+# Loaded ONLY when the `cgi` stdlib library resolves
+# (`RbsLoader::LIBRARY_SUPPLEMENT_VENDORED_DIRS`): without it the
+# mixin target does not exist, `RBS::DefinitionBuilder` raises
+# `NoMixinFoundError`, and the whole `CGI` class silently degrades
+# to `Dynamic[top]`.
+#
 class CGI
   include CGI::QueryExtension
 end

data/data/vendored_gem_sigs/prism/prism_supplement.rbs

@@ -21,6 +21,13 @@
 #      — bound as singleton methods by the C extension; the
 #      gem's RBS only declares the matching instance methods.
 #
+# Loaded ONLY when the `prism` library resolves
+# (`RbsLoader::LIBRARY_SUPPLEMENT_VENDORED_DIRS`): the
+# `ParseResult < Result` re-opening names a superclass only the
+# gem's own RBS declares, so without it `RBS::DefinitionBuilder`
+# raises `NoSuperclassFoundError` and the whole class silently
+# degrades to `Dynamic[top]`.
+#
 module Prism
   class ParseResult < Result
     # Walk the parse result's tree, attaching every comment to

data/data/vendored_gem_sigs/racc/racc.rbs

@@ -0,0 +1,67 @@
+#
+# Rigor-side vendored RBS stub for the `racc` gem's runtime.
+#
+# Vendored for ONE structural reason: `data/vendored_gem_sigs/nokogiri/nokogiri.rbs` declares
+# `class Nokogiri::CSS::Parser < Racc::Parser`, and `RBS::DefinitionBuilder` raises
+# `RBS::NoSuperclassFoundError` when a declared superclass has no declaration anywhere in the
+# environment — which took the whole `Nokogiri::CSS::Parser` definition down to `Dynamic[top]`
+# (issue #299). Dropping the superclass from the nokogiri sig would have hidden the inheritance
+# instead of typing it, and `Racc::Parser` is a real, small, stable class, so it is declared here.
+#
+# Scope is the documented runtime surface a racc-generated parser inherits, plus `Racc::ParseError`
+# (which `Nokogiri::CSS::SyntaxError` and every generated parser raise). The `_racc_*` methods are
+# private implementation detail of the generated parse loop and are deliberately NOT declared —
+# nothing outside racc itself calls them.
+#
+# Returns are `untyped` wherever the value is a grammar-defined semantic value: racc has no way to
+# know what a generated parser's actions produce, and guessing would cost false positives.
+#
+module Racc
+  # Raised by a generated parser on an unrecoverable syntax error.
+  class ParseError < StandardError
+  end
+
+  # The runtime base class every racc-generated parser inherits from.
+  class Parser
+    # Runs the parse loop, pulling tokens from the subclass's `#next_token`. Returns the grammar's
+    # start-rule value.
+    def do_parse: () -> untyped
+
+    # Token source: a generated parser's user code overrides this to return `[token_symbol, value]`,
+    # or `nil` / `[false, ...]` at end of input.
+    def next_token: () -> untyped
+
+    # Runs the parse loop pulling tokens by calling `recv.__send__(mid)` instead of `#next_token`.
+    def yyparse: (untyped recv, Symbol | String mid) -> untyped
+
+    # Error hook: called with the offending token id, its value, and the value stack. The default
+    # implementation raises `Racc::ParseError`; user code overrides it to report and recover.
+    def on_error: (untyped error_token_id, untyped error_value, untyped value_stack) -> void
+
+    # Explicitly signals a syntax error from inside a parser action.
+    def yyerror: () -> void
+
+    # Accepts the input from inside a parser action, ending the parse.
+    def yyaccept: () -> void
+
+    # Clears the error state after `#on_error`, resuming normal parsing.
+    def yyerrok: () -> void
+
+    # Human-readable name for a token id, or `nil` when the id is unknown.
+    def token_to_str: (untyped t) -> String?
+
+    # Debug-trace hooks. Enabled by a generated parser built with racc's `--debug`; harmless no-ops
+    # otherwise.
+    def racc_read_token: (untyped t, untyped tok, untyped val) -> void
+    def racc_shift: (untyped tok, untyped tstack, untyped vstack) -> void
+    def racc_reduce: (untyped toks, untyped sim, untyped tstack, untyped vstack) -> void
+    def racc_accept: () -> void
+    def racc_e_pop: (untyped state, untyped tstack, untyped vstack) -> void
+    def racc_next_state: (untyped curstate, untyped state) -> void
+    def racc_print_stacks: (untyped t, untyped v) -> void
+    def racc_print_states: (untyped s) -> void
+    def racc_token2str: (untyped tok) -> String
+
+    def self.racc_runtime_type: () -> String
+  end
+end

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -8,6 +8,17 @@
 # the upstream RBS already covers, so the loader does not raise
 # `RBS::DuplicatedDeclarationError`.
 #
+# "Upstream RBS" here means BOTH `core/rubygems/*.rbs` and the
+# `rbs` gem's `sig/shims/rubygems.rbs`: `rbs` is in
+# `Environment::DEFAULT_LIBRARIES`, so its whole `sig/` tree —
+# shims included — is in scope on every run. A duplicate against
+# either raises `RBS::DuplicatedMethodDefinitionError` inside
+# `RBS::DefinitionBuilder` and collapses the ENTIRE class to
+# `Dynamic[top]` (issue #299), so a shim-declared reader is left
+# to the shim and only the writer half is declared here.
+# `spec/rigor/environment/bundled_rbs_definition_build_spec.rb`
+# fails the suite if a new collision reappears on an `rbs` bump.
+#
 # Driven by the `references/ruby/lib` survey
 # (`docs/CURRENT_WORK.md` § "Queued engine items") which
 # clusters `undefined-method` on Gem-side selectors most-touched
@@ -62,7 +73,7 @@ class Gem::Platform
   def match_spec?: (untyped) -> bool
   def match_gem?: (untyped, untyped) -> bool
 
-  def self.local: () -> Platform
+  def self.local: () -> Gem::Platform
   def self.match_spec?: (untyped) -> bool
   def self.match_gem?: (untyped, untyped) -> bool
   def self.installable?: (untyped) -> bool
@@ -75,7 +86,9 @@ class Gem::Dependency
   # permissive splat keeps the canonical and the
   # `(name, requirements, type)` invocation forms both silent.
   def initialize: (*untyped) -> void
-  attr_accessor name: String
+  # `#name`'s READER is declared by `sig/shims/rubygems.rbs` (`() -> String`); only the writer is
+  # ours, so this is a `def name=` rather than the `attr_accessor` the other members use.
+  def name=: (String) -> String
   attr_accessor requirement: Gem::Requirement
   attr_accessor type: Symbol
   attr_accessor prerelease: bool
@@ -111,7 +124,9 @@ class Gem::Specification
   def required_ruby_version: () -> Gem::Requirement
   def require_paths: () -> Array[String]
   attr_accessor name: String
-  attr_accessor version: Gem::Version
+  # `#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?
@@ -131,7 +146,7 @@ end
 
 class Gem::Requirement
   def requirements: () -> Array[untyped]
-  def self.create: (*untyped) -> Gem::Requirement
+  # `.create` — declared by `core/rubygems/requirement.rbs`, and more precisely than this file did.
 end
 
 class Gem::ConfigFile
@@ -172,7 +187,7 @@ class Gem::SourceList
   def include?: (untyped) -> bool
   def each: () { (untyped) -> untyped } -> void
   def to_a: () -> Array[untyped]
-  def from: (untyped) -> SourceList
+  def from: (untyped) -> Gem::SourceList
 end
 
 class Gem::RequestSet
@@ -217,10 +232,6 @@ class Gem::Installer
   def initialize: (*untyped) -> void
 end
 
-class Gem::DependencyInstaller
-  def initialize: (*untyped) -> void
-end
-
 class Gem::MissingSpecError < StandardError
   def initialize: (*untyped) -> void
 end

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

@@ -48,11 +48,38 @@ the `paths:` list from the configuration file.
 | `--treat-all-as-inline-rbs` | Force-load `rigor-rbs-inline` with `require_magic_comment: false`, so every analysed file is treated as inline-RBS without the `# rbs_inline: enabled` comment (ADR-32). |
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
-| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. |
+| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
 any are reported, `64` on a usage error.
 
+### Editor mode scope
+
+`--tmp-file` / `--instead-of` on their own analyse **only** the
+buffer's file: fast, and blind to what the unsaved edit does to the
+rest of the project.
+
+Adding `--incremental` analyses the **whole project with the buffer
+substituted** — the edited file and the files that depend on it are
+re-analysed, everything else is served from the incremental snapshot.
+An unsaved change to a method's return type therefore surfaces in its
+callers, not just in the file being edited.
+
+Two things to know:
+
+- It needs a snapshot to reuse. Run `rigor check --incremental` once
+  (it is also what a normal terminal check should use) and every later
+  editor invocation gets whole-project scope. Without one, Rigor says
+  so on stderr and analyses the buffer alone.
+- An editor-mode run never writes the snapshot — the buffer's bytes
+  exist only in your editor, and recording them would make the next
+  ordinary run believe it had already analysed a file in a state it
+  was never in.
+
+`--verify-incremental` refuses a buffer: it compares against a full
+analysis of the files on disk, which a buffer contradicts by
+construction.
+
 ## `rigor init`
 
 Write a starter configuration file.
@@ -333,7 +360,10 @@ the effectiveness ratio and `--format=json` carries `mode`,
 `killed`, `survived`, `effectiveness_ratio`, per-file rows, and
 `add_a_type_here`. It is the truth tier behind the static
 `--protection` proxy, at the cost of many analyses — an opt-in CI
-deep-dive, not an interactive check.
+deep-dive, not an interactive check. `--workers=N` fork-parallelizes
+this tier too (the whole-project pre-pass is paid once on the parent
+and the per-file measurement is spread across workers), with the
+same precedence chain and the same byte-identical output.
 
 ```sh
 rigor coverage --protection --mutation [paths]
@@ -352,7 +382,10 @@ cost is proportional to the protection hole. `--format=json`
 carries `mode` (`protection-fused`), `type_killed`,
 `test_killed`, `unprotected`, `protected_ratio`, per-file rows,
 and `add_protection_here`; `--threshold` gates on the fused
-ratio.
+ratio. This tier is always sequential — the suite hook shells out
+to your test runner, and concurrent runs would race over one
+working tree — so `--workers` does not apply and an explicit one
+is reported as ignored on stderr.
 
 `--test-command=CMD` is the runner hook (default
 `bundle exec rake`). The suite must pass on clean code first, or
@@ -378,6 +411,18 @@ to a deterministic sample of `N` mutations per file, bounding the
 cost on large files. Per-file ratios then become estimates, noted
 on stderr so `--format=json` stdout stays clean.
 
+A re-run is served from a per-file measurement cache while
+nothing that could change a file's number has moved: the file
+itself, any file it was recorded as reading from, the resolved
+configuration, `sig/`, the gem set, the engine version, `--limit`
+/ `--seed`, and the adopted bleeding-edge features. It reads the
+cross-file edges a `rigor check --incremental` run records, so
+warm one once per project; without a usable snapshot every file
+is measured, never silently served. `--no-cache` measures
+everything from scratch. A one-line stderr report says which of
+those happened — see
+[Type-protection coverage](15-type-protection-coverage.md).
+
 ```sh
 rigor coverage --protection --mutation --with-tests \
   --test-command "bundle exec rspec" --include-dynamic [paths]
@@ -578,7 +623,7 @@ pages from the installed gem with no HTTP request.
 ## `rigor show-bleedingedge`
 
 Print the **bleeding-edge overlay** — the Rigor-maintained set of
-the next major's queued diagnostic disciplines ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
+the next major's queued changes ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
 § WD2) — and report which of them the project's
 [`bleeding_edge:`](03-configuration.md) configuration adopts. Read-only:
 it loads `.rigor.yml` to resolve the active selection but runs no
@@ -593,16 +638,31 @@ rigor show-bleedingedge [--config PATH] [--format text|json]
 | `--config PATH` | Use this `.rigor.yml` instead of auto-discovery. |
 | `--format text\|json` | Output format. Default `text`. |
 
-Each queued feature appears with its stable id, the severity it imposes,
-and whether your configuration adopts it. See
-[`docs/compatibility.md`](../compatibility.md) for how bleeding-edge fits
-the stability model.
+Each queued feature appears with its stable id, its **kind** — `severity`
+or `behaviour` — and whether your configuration adopts it. A `severity`
+feature also prints the rule → severity diff it imposes; a `behaviour`
+feature changes a measurement, an algorithm, or a default without moving
+any rule's severity, so it has no such diff and its summary is the whole
+description. See [`docs/compatibility.md`](../compatibility.md) for how
+bleeding-edge fits the stability model.
 
 Queued today:
 
-| Feature id | What it changes |
-| --- | --- |
-| `reject-unparseable-signatures` | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
+| Feature id | Kind | What it changes |
+| --- | --- | --- |
+| `reject-unparseable-signatures` | severity | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
+| `use-of-void-value` | severity | Using a value recovered from an author-declared `-> void` return in value context is reported as `static.value-use.void` (`warning`). |
+| `discovery-seeded-mutation-sites` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) measures against the same cross-file project discovery Tier 1 already uses — both when picking the sites and when deciding whether a breakage was caught — so a call on a project class declared in a *sibling* file is measured instead of dropped, and a breakage there can actually be caught. **Adds sites to the denominator, so the reported effectiveness ratio moves** — check it against any `--threshold` you pin in CI before adopting. |
+| `dependent-closure-kill-oracle` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) counts a breakage as caught when the diagnostic appears anywhere in the mutated file **or the files that depend on it**, instead of in the mutated file alone — so changing what a method returns counts as caught when the error lands in its callers. Can only **add** kills, so the ratio moves up or not at all; it costs about a third more wall time per mutant, and a ratio measured under it is not comparable with one measured without it. |
+
+Once a feature **graduates** — it becomes the default at a major
+([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7)
+— it leaves the queued list and appears under `Graduated`, an
+acknowledgement that naming it in `bleeding_edge:` no longer does
+anything: the behaviour is on for everyone. The section is absent while
+nothing has graduated. In `--format json` the same information is the
+`graduated` array, alongside `overlay` (every queued feature, each with
+its `kind`), `active`, and `unknown_selected`.
 
 ## `rigor doctor`
 

data/docs/manual/03-configuration.md

@@ -116,7 +116,22 @@ statically and may resolve at run time. The same findings appear in the
 | `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
 | `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
 | `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |
-| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued diagnostic disciplines early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
+| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued changes early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
+
+A queued feature is one of two kinds, and `bleeding_edge:` selects both the
+same way:
+
+- A **severity** feature promotes one or more rules — a discipline Rigor
+  already reports quietly becomes an error or a warning. Its diff is a list
+  of rule ids, printed by `rigor show-bleedingedge`.
+- A **behaviour** feature changes a measurement, an algorithm, or a
+  default, and moves no rule's severity. There is no rule-id diff to read,
+  so its summary in `rigor show-bleedingedge` is the whole description of
+  what adopting it does.
+
+An id you name that this version of Rigor does not know is ignored rather
+than rejected, so a shared `.rigor.yml` can name a feature that only some
+of the versions in use have queued.
 
 ### Dependency RBS discovery