rigortype 0.3.8 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30b66e3d183999cbd85557c5af6b770ac78bf82507a2e587e5878c1a411b4326
-  data.tar.gz: 2c3cee80d75ea9769d7b965dd84ac60eb4af89c27fc63d3ec35a1cdce3b45338
+  metadata.gz: 96e337b134c8bcb33bf20707e88ffbe16ff98b94513d483043e18432d9bf6328
+  data.tar.gz: e46a5af02a699ef2d0ad41e7b8b94e2d5eac02d1085d30fc03831df208ef930e
 SHA512:
-  metadata.gz: 9986a78b908e05fd017f772b0c26d6bc3d654e665cbf59d85cdf0176b76735403d644238ca7072268f9e47ba3937073002de47a308deda6cab77311459f6f008
-  data.tar.gz: 66df68005471dc8df33c9a1881659644fca80c4e406830b7ab9c1fe5b641e3872d13a70ab39cccdf66fba3d256e46026ab13963a70a76be1362ac86b8e823f1d
+  metadata.gz: cc7a7cadf53373e66de5ff268b2a44452d42972cbd9c1683825e2809480573bf195d9c26252d0522ddac2ae3f39f9dc665768d61cbb7c6e63ee6d60eaa17b87a
+  data.tar.gz: 05b82b8662a6e5b0283a04eca851d0bb6aa1031f55fd1e99525c5b884e433a30b89d519486f6fceebca95e47a306f721766adecc13d4c68134c833e9e525304a

data/README.md

@@ -231,8 +231,8 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.3.8`** (2026-09-08) — on the
-`0.3.x` line, continuing the evaluation era opened by `v0.2.0`, the first
+Current release: **`v0.4.0`** (2026-09-27) — opening 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
 minor-non-break trial, rehearsing the contract that hard-freezes at

data/data/capability_roles/capability_roles.rbs

@@ -0,0 +1,36 @@
+# Rigor's capability-role catalog (ADR-1 § "Capability roles",
+# docs/type-specification/structural-interfaces-and-object-shapes.md).
+#
+# These are the roles Rigor itself ships, as opposed to the stdlib interfaces (`_Reader`, `_ToStr`, …)
+# it reuses from upstream RBS. They exist so a `%a{rigor:v1:conforms-to _ClosableStream}` directive
+# written by following the specification resolves in a default run instead of failing soft.
+#
+# Parameter and return types are deliberately the loosest honest reading: a role says which members a
+# value answers, and narrowing them here would reject conforming classes rather than describe them.
+
+# The specification's running example: the one-member lifetime contract.
+interface _Closable
+  def close: () -> untyped
+end
+
+interface _RewindableStream
+  def read: (*untyped) -> String?
+
+  def rewind: () -> untyped
+end
+
+interface _ClosableStream
+  def close: () -> untyped
+
+  def closed?: () -> bool
+end
+
+interface _FileDescriptorBacked
+  def fileno: () -> Integer
+end
+
+# Not generic: `_Callable[**A, R]` as ADR-1 first drafted it is not RBS grammar (`**A` has no meaning
+# in a type-parameter list). A generic form is a future extension, gated on RBS gaining the syntax.
+interface _Callable
+  def call: (*untyped) -> untyped
+end

data/data/core_overlay/enumerable.rbs

@@ -0,0 +1,51 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Enumerable#detect with an ifnone argument ---
+#
+# CRuby binds `detect` and `find` to one C function (`enum.c`:
+# `rb_define_method(rb_mEnumerable, "detect", enum_find, -1)`), so
+# `detect(ifnone)` answers `ifnone.call` when no element matches, exactly as
+# `find(ifnone)` does. Upstream `ruby/rbs` declares the two apart, and only
+# `find` carries the fallback arm:
+#
+#   def find: () { (Elem) -> boolish } -> Elem?
+#           | () -> ::Enumerator[Elem, Elem?]
+#           | [T] (_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+#           | [T] (_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+#   def detect: (?Proc ifnone) { (Elem) -> boolish } -> Elem?
+#             | (?Proc ifnone) -> ::Enumerator[Elem, Elem?]
+#
+# so `r = { a: 1 }.detect(-> { 0 }) { |k, v| v > 5 }` typed `[:a, 1]?`
+# although it is `0` at runtime, and `r + 1` reported
+# `call.possible-nil-receiver` on correct code. No core or stdlib class
+# declares a `detect` of its own except `Array`, which rbs 4.1 and later
+# alias to `Array#find`; `Hash`, `Range`, `Set`, `Struct`, `Enumerator`,
+# `Enumerator::Lazy` (whose lazy method table leaves `detect` eager), `IO`,
+# `Dir`, `ENV` and every other includer inherit this one, as does `Array`
+# before rbs 4.1.
+#
+# Upstream's `?Proc` parameter also rejected a valid fallback that is not a
+# `Proc` — `nil` (no fallback) or any object answering `call` — with
+# `call.argument-type-mismatch`. Such an argument reaches the `_NotFound[T]`
+# arms below, so `detect` checks its argument as `find` does.
+#
+# The overloads below are prepended to upstream's through `| ...` (rbs
+# unshifts a continuation's overloads, so they are tried first). The last two
+# are `find`'s ifnone arms. The first two restate them for a `Proc` argument:
+# `OverloadSelector`'s strict pass skips an interface-typed parameter such as
+# `_NotFound[T]`, so without them upstream's strictly typed `(?Proc ifnone)`
+# arm would win a lambda and answer `Elem?` again. A block-only
+# `detect { ... }` passes no argument, skips all four on arity, and keeps
+# upstream's `Elem?`.
+#
+# The continuation's base is in rbs core on every supported release, so the
+# file loads unconditionally. Once an upstream release aligns `detect` with
+# `find`, gate this file off that release through
+# `RbsLoader::RBS_LINE_CORE_OVERLAYS`, as `hash_rbs3.rbs` is.
+module Enumerable[unchecked out Elem]
+  def detect: [T] (^() -> T ifnone) { (Elem) -> boolish } -> (Elem | T)
+            | [T] (^() -> T ifnone) -> ::Enumerator[Elem, Elem | T]
+            | [T] (_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+            | [T] (_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+            | ...
+end

data/data/core_overlay/enumerator.rbs

@@ -0,0 +1,84 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Enumerator::Lazy's redefined enumerable methods ---
+#
+# Issue #1121. `Enumerator::Lazy` is not merely an `Enumerator`: CRuby
+# redefines most of `Enumerable` on it so that the call CHAINS another lazy
+# enumerator instead of forcing the source (`enumerator.c`'s lazy method
+# table: `collect` / `map`, `find_all` / `select` / `filter`, `reject`,
+# `grep`, `grep_v`, `flat_map` / `collect_concat`, `take`, `take_while`,
+# `drop`, `drop_while`, `uniq`, `zip`, `filter_map`). Upstream `ruby/rbs`
+# declares none of them on `Enumerator::Lazy` — its whole body is `force`
+# plus `compact` and `eager` — so dispatch walks up to `Enumerable` and
+# adopts THAT class's eager return type:
+#
+#   [1, 2, 3].lazy.map { |x| x * 2 }   # Enumerable#map -> Array[U], not Lazy
+#
+# The receiver class is lost, and with it every terminal method only a lazy
+# enumerator answers: `…map { … }.force` / `.eager` report
+# `call.undefined-method` on correct code, on 124 `.lazy` sites in one
+# survey corpus (gitlab services and graphql, rails actiontext, sidekiq,
+# rubocop).
+#
+# The entries below mirror each upstream `Enumerable` declaration the lazy
+# method replaces, with the return rewritten to `Enumerator::Lazy`. Two
+# deliberate exclusions:
+#
+# * The single type argument spelling (`Enumerator::Lazy[U]`, not
+#   `[U, Return]`) mirrors upstream's own `Enumerable#lazy:
+#   () -> Enumerator::Lazy[Elem]` — the trailing `Return` parameter is
+#   defaulted (`void`), and Rigor binds the supplied prefix (see
+#   `docs/internal-spec/inference-engine.md` § generic dispatch).
+# * The no-block arms of the block-taking methods are NOT carried over.
+#   CRuby RAISES for a blockless `lazy.map` / `select` / `reject` /
+#   `find_all` / `take_while` ("tried to call lazy map without a block"), so
+#   the inherited `Enumerable` arm is a wrong answer for a lazy receiver
+#   rather than a harmless fallback.
+#
+# `zip` is left to `Enumerable` for now: its lazy form yields
+# `[elem, other_elem]` pairs through `_Each`, and the pair shape upstream
+# declares for the eager form is not what the lazy chain hands downstream.
+# `compact`, `eager` and `force` are upstream already and MUST NOT be
+# duplicated here — a second declaration of a method `rbs` core already
+# declares in this class is a `DuplicatedMethodDefinitionError`, which
+# degrades the whole class to `Dynamic[top]`. (`eager` in particular is
+# declared by rbs 4.x only; a `| ...` overload continuation that would
+# declare it on the 3.10 line as well raises `InvalidOverloadMethodError`
+# there, for the same whole-class cost, so `.eager` stays the 3.10 line's
+# own gap.)
+class Enumerator::Lazy[out E, out R = void]
+  def collect: [U] () { (E) -> U } -> Enumerator::Lazy[U]
+
+  def map: [U] () { (E) -> U } -> Enumerator::Lazy[U]
+
+  def find_all: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def select: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def filter: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def reject: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def filter_map: [U] () { (E) -> (nil | false | U) } -> Enumerator::Lazy[U]
+
+  def flat_map: [U] () { (E) -> (Array[U] | U) } -> Enumerator::Lazy[U]
+
+  def collect_concat: [U] () { (E) -> (Array[U] | U) } -> Enumerator::Lazy[U]
+
+  def take: (Integer n) -> Enumerator::Lazy[E]
+
+  def take_while: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def drop: (Integer n) -> Enumerator::Lazy[E]
+
+  def drop_while: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def uniq: () -> Enumerator::Lazy[E]
+          | () { (E item) -> untyped } -> Enumerator::Lazy[E]
+
+  def grep: (untyped pattern) -> Enumerator::Lazy[E]
+          | [U] (untyped pattern) { (E) -> U } -> Enumerator::Lazy[U]
+
+  def grep_v: (untyped pattern) -> Enumerator::Lazy[E]
+            | [U] (untyped pattern) { (E) -> U } -> Enumerator::Lazy[U]
+end

data/data/core_overlay/hash_rbs3.rbs

@@ -0,0 +1,41 @@
+# Rigor core overlay — supplemental core signatures, rbs 3.x line only.
+#
+# --- Hash#transform_keys / #transform_keys! with a replacements hash ---
+#
+# Ruby 3.0 added the replacements-hash argument
+# (`h.transform_keys({ a: :z }) { |k| k.to_s }`), and rbs 4.0 declares it.
+# Every rbs 3.x release declares only the blockless `Enumerator` form and
+# the block form, both with no positional parameter:
+#
+#   def transform_keys: () -> Enumerator[K, Hash[untyped, V]]
+#                     | [A] () { (K) -> A } -> Hash[A, V]
+#   def transform_keys!: () -> Enumerator[K, self]
+#                      | () { (K) -> K } -> self
+#
+# so under rbs 3.x a correct replacements call reports `call.wrong-arity`
+# ("given 1, expected 0"), and `transform_keys!` answers `Enumerator`
+# instead of the receiver.
+#
+# The overloads below are rbs 4.2's, prepended to 3.x's own through
+# `| ...`. `RbsLoader::RBS_LINE_CORE_OVERLAYS` loads this file only on
+# the rbs 3.x line: on 4.x the continuation would add a second copy of
+# the overloads upstream already declares.
+#
+# Two spellings differ from rbs 4.2 so that every name resolves on every
+# rbs 3.x release the gemspec admits:
+#
+# * `hash[K, V]` is written out as `Hash[K, V] | _ToHash[K, V]`: the
+#   `hash` alias arrived in rbs 3.3, `_ToHash` is in 3.0.
+# * `hash[_Key, K2]`'s key is `untyped`: `Hash::_Key` arrived in rbs 3.4.
+#   It constrains only `hash` / `eql?`, which every object answers.
+#
+# The non-bang return type is answered ahead of either declaration by
+# `MethodDispatcher::HashTransformKeysFolding`.
+class Hash[unchecked out K, unchecked out V]
+  def transform_keys: [K2] (Hash[untyped, K2] | _ToHash[untyped, K2] replacements) -> Hash[K | K2, V]
+                    | [K2] (Hash[untyped, K2] | _ToHash[untyped, K2] replacements) { (K old_key) -> K2 } -> Hash[K2, V]
+                    | ...
+
+  def transform_keys!: (Hash[K, K] | _ToHash[K, K] replacements) ?{ (K key) -> K } -> self
+                     | ...
+end

data/data/core_overlay/process.rbs

@@ -0,0 +1,40 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Process.last_status ---
+#
+# CRuby's `process.c` defines `Process.last_status` as a singleton method
+# answering the calling thread's last child status — the object `$?` reads:
+#
+#   rb_define_singleton_method(rb_mProcess, "last_status", proc_s_last_status, 0);
+#
+# It is `nil` until the thread has waited on a child process. Upstream
+# `ruby/rbs` names `::last_status` in `Process`'s doc comment but has never
+# declared it (no commit to `core/process.rbs` through 4.2 adds a `def`), so
+#
+#   system("true")
+#   status = Process.last_status
+#
+# reported `call.undefined-method` on correct code. The return mirrors rbs
+# core's own `$?: Process::Status?`.
+#
+# Declared on a module `Process` extends, not with `def self.last_status`.
+# A second direct `def` of the method is a `DuplicatedMethodDefinitionError`
+# that takes `Process`'s whole singleton surface down to `Dynamic[top]`, and
+# this method is one a project is likely to have declared already: a
+# `sig/` written for Steep, which reads the same rbs gap, or a later rbs
+# release that fills it. A direct `def` from either source overrides a
+# method `Process` gets through `extend`, on rbs 3.x and 4.x alike, so the
+# overlay stands down instead of colliding.
+#
+# Unconditional: `Process` and `Process::Status` are rbs core on every
+# supported release. `MethodDispatcher::ProcessFolding` refines the answer
+# past a subprocess call, where `$?` is known to be set.
+module RigorCoreOverlay
+  module ProcessLastStatus
+    def last_status: () -> Process::Status?
+  end
+end
+
+module Process
+  extend RigorCoreOverlay::ProcessLastStatus
+end

data/data/core_overlay/string_io.rbs

@@ -0,0 +1,33 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- StringIO includes Enumerable[String] ---
+#
+# CRuby's `ext/stringio/stringio.c` makes `StringIO` Enumerable:
+#
+#   rb_include_module(StringIO, rb_mEnumerable);
+#
+# and `StringIO#each` yields the stream's lines, so a `StringIO` is an
+# `Enumerable[String]` exactly as rbs core declares `IO` to be. Upstream
+# `ruby/rbs` declares `class StringIO` with no `include` on every release the
+# gemspec supports, so `StringIO.new(s).detect { ... }`, `.map`,
+# `.each_with_index` and the rest of Enumerable reported
+# `call.undefined-method` on correct code, and a block-taking `.select` fell
+# through to `Kernel#select` (the IO multiplexer) and reported
+# `call.wrong-arity`.
+#
+# The mixin sits behind the class in the ancestry, so every method StringIO
+# declares itself (`each`, `each_line`, `each_char`, `readlines`, ...) keeps
+# upstream's signature. A duplicate include, should upstream add one, builds
+# on both rbs lines.
+#
+# Unconditional — NOT in `RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS`,
+# because every environment Rigor builds already declares `StringIO`: in rbs
+# `core/string_io.rbs` before 3.7, and from 3.7 on because
+# `RBS::EnvironmentLoader#load` adds the `stringio` library itself whenever
+# it loads core ("For migrating stringio to stdlib"). Gating on `stringio`
+# would drop the mixin on rbs < 3.7, which has no such library, and from any
+# environment that does not name it. The premise is pinned in
+# `spec/rigor/environment/bundled_rbs_definition_build_spec.rb`.
+class StringIO
+  include Enumerable[String]
+end

data/data/effects/core.yml

@@ -173,7 +173,7 @@ classes:
       instance_variable_set:
         effects: []
         mutates: receiver
-        why: "writes another object's state; the label follows the receiver's ownership (mutate.self on self, mutate.instance on a parameter, taint otherwise)"
+        why: "writes another object's state; the label follows the receiver's ownership (effect-summaries.md § Ownership)"
       instance_variable_get: { effects: [], why: "reads an ivar — object state, not global state" }
       hash: { effects: [], why: "per-process SipHash salt makes it irreproducible (`NON_REPRODUCIBLE_SELECTORS`), but irreproducibility is a fold hazard, not an observable effect" }
       object_id: { effects: [], why: "per-process identity — a fold hazard (`NON_REPRODUCIBLE_SELECTORS`), not an effect" }
@@ -235,12 +235,12 @@ classes:
   Hash:
     posture: value
     mutators: hash
-    why: "a value class; mutation is ownership-classified from `MutationWidening::HASH_MUTATORS`"
+    why: "a value class; mutation is ownership-classified from `MutationClassifier::HASH_MUTATORS`, the union of the widening's `HASH_MUTATORS` and `HashLookupMutation::MUTATORS` plus `rehash`"
 
   String:
     posture: value
     mutators: string
-    why: "a value class; mutation is ownership-classified from `MutationClassifier::STRING_MUTATORS`"
+    why: "a value class; mutation is ownership-classified from `StringMutation::MUTATORS`"
 
   Symbol: { posture: value, why: "immutable value class" }
   Integer: { posture: value, why: "immutable value class" }