rigortype 0.3.0 → 0.3.2

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

@@ -2,7 +2,7 @@
 #
 # --- StringScanner#[] ---
 #
-# The pinned `rbs` gem (4.0.2) declares `StringScanner#[]` as only:
+# `rbs` 4.0.x declares `StringScanner#[]` as only:
 #
 #   def []: (Integer) -> String?
 #
@@ -14,14 +14,20 @@
 #   scanner.skip(/(?<key>\w+)=/)
 #   scanner[:key]   # => the captured String, or nil
 #
-# Newer `ruby/rbs` already widens the signature to
-# `(Integer | String | Symbol) -> String?`; the pinned 4.0.2 gem lags.
 # Without the wider overload, a named-capture access such as Mastodon's
 # `scanner[:key]` false-fires `call.argument-type-mismatch` (the lone
 # overload rejects a `Symbol`).
 #
-# The overlay supplies the runtime-accurate overload; drop it once the
-# pinned `rbs` gem carries the wider signature.
+# `rbs` 4.1.0 widened the upstream signature to exactly this
+# (ruby/rbs#2959), so the overlay is redundant on the pinned gem and only
+# 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/handbook/01-getting-started.md

@@ -78,7 +78,9 @@ catalogue of bugs:
 - arithmetic that can be proved to raise (`5 / 0`);
 - arguments whose type does not satisfy a refined parameter
   contract;
-- a few more, all listed in
+- a few more, all catalogued in
+  [manual — Diagnostics](../manual/04-diagnostics.md) and
+  explained in
   [Chapter 8 — Understanding errors](08-understanding-errors.md).
 
 Rigor does **not** ask you to write type annotations in
@@ -170,9 +172,11 @@ on the offending line:
 The same identifier also drives the `disable:` and
 `severity_overrides:` config keys, and family wildcards work
 (`# rigor:disable call` suppresses every `call.*` rule on that
-line). The full list of families and rules, and when to reach
-for each suppression mechanism, is in
-[Chapter 8 — Understanding errors](08-understanding-errors.md).
+line). The full list of families and rules is in
+[manual — Diagnostics](../manual/04-diagnostics.md);
+[Chapter 8 — Understanding errors](08-understanding-errors.md)
+is where to read about choosing between the suppression
+mechanisms.
 
 ## The "no annotations" stance
 
@@ -278,36 +282,20 @@ non-default behaviours: extra `paths`, an alternative
 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:
-
-```yaml
-target_ruby: "3.4"   # your project's Ruby — not Rigor's own 4.0
-
-paths:
-  - lib
-
-# signature_paths: [sig]   # auto-detected when omitted
-
-severity_profile: balanced
-
-# severity_overrides:
-#   call.argument-type-mismatch: warning
-
-# disable: []
-
-# plugins: []
-```
-
-That is all most projects need. The remaining mechanics —
-editor autocomplete from the bundled JSON schema, the
-`.rigor.yml` vs `.rigor.dist.yml` precedence rule, `includes:`
-composition, and how path-bearing keys resolve relative to the
-declaring file — are covered in
-[Configuration](../manual/03-configuration.md). The one rule
-worth knowing up front: when a developer keeps a local
-`.rigor.yml`, it is the *sole* source of config for their runs
-(the two files are never merged automatically), so to extend
-the shared default it must list it under `includes:`.
+— the project default that gets committed, with `target_ruby`,
+`paths`, and a `severity_profile` filled in and the rest
+commented out. That is all most projects need; the key
+reference, the JSON-schema editor integration, and `includes:`
+composition are in
+[Configuration](../manual/03-configuration.md).
+
+Two things are worth knowing up front, because they surprise
+people. `target_ruby` is *your project's* Ruby, not the 4.0
+Rigor itself runs on — those are independent on purpose. And
+when a developer keeps a local `.rigor.yml`, it is the *sole*
+source of config for their runs (the two files are never merged
+automatically), so to extend the shared default it must list it
+under `includes:`.
 
 ## What's next
 

data/docs/handbook/06-classes.md

@@ -97,7 +97,7 @@ both. The setter's argument type is whatever the call site
 provides. The `def.ivar-write-mismatch` rule (v0.1.2) checks
 that two writes to the same ivar in the same class body
 agree on the concrete class — see
-[Chapter 8 — Understanding errors](08-understanding-errors.md)
+[manual — Diagnostics](../manual/04-diagnostics.md)
 for the rule's exact contract; it lets you catch an
 accidental rebind from `String` to `Array` in the same class
 without authoring an explicit ivar type.