rigortype 0.4.1 → 0.4.3

data/data/core_overlay/string.rbs

@@ -0,0 +1,86 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- String bit operations and String#tr with a Hash (Ruby 4.1) ---
+#
+# Issue #1691. Ruby 4.1 adds bit access and bitwise operations on a
+# string's bytes (`string.c`), and lets `tr` / `tr!` take a single Hash of
+# replacement pairs (Feature #22238). No rbs release through 4.2 declares
+# any of them, so correct 4.1 code reported `call.undefined-method`, or
+# `call.wrong-arity` for `"hello".tr("e" => "er")`. Signatures follow the
+# CRuby call-seqs:
+#
+#   bit_get(offset, lsb_first: true) -> 0, 1, or nil
+#   bit_set?(offset, lsb_first: true) -> true, false, or nil
+#   bit_set / bit_clear / bit_flip(offset, lsb_first: true) -> self
+#                                 (offset, length, lsb_first: true) -> self
+#                                 (range, lsb_first: true) -> self
+#   bit_count -> integer
+#   bit_count(offset, length, lsb_first: true) -> integer
+#   bit_count(range, lsb_first: true) -> integer
+#   bitwise_not -> string             bitwise_not! -> self
+#   bitwise_and / _or / _xor(other) -> string, and their `!` forms -> self
+#   tr(pairs) -> new_string           tr!(pairs) -> self or nil
+#
+# `lsb_first` raises unless it is `true` or `false`, hence `bool`. `other`
+# is converted with `to_str`, hence `string`.
+#
+# TEMPORARY: delete each entry once the rbs release Rigor bundles declares
+# it upstream.
+#
+# Declared unconditionally, not gated on `target_ruby` (ADR-121 § Rejected
+# alternatives; false positives outrank). The new methods sit on a module
+# `String` includes so that a later direct declaration from rbs or a
+# project `sig/` overrides them instead of raising
+# `DuplicatedMethodDefinitionError` for the whole class (see
+# `process.rbs`). The `tr` / `tr!` Hash form is an `| ...` continuation of
+# the upstream declaration, which every supported rbs release carries; a
+# later release that declares the same overload only repeats it.
+module RigorCoreOverlay
+  module Ruby41StringBits
+    def bit_get: (int offset, ?lsb_first: bool) -> (0 | 1)?
+
+    def bit_set?: (int offset, ?lsb_first: bool) -> bool?
+
+    def bit_set: (int offset, ?lsb_first: bool) -> self
+               | (int offset, int length, ?lsb_first: bool) -> self
+               | (Range[Integer?] range, ?lsb_first: bool) -> self
+
+    def bit_clear: (int offset, ?lsb_first: bool) -> self
+                 | (int offset, int length, ?lsb_first: bool) -> self
+                 | (Range[Integer?] range, ?lsb_first: bool) -> self
+
+    def bit_flip: (int offset, ?lsb_first: bool) -> self
+                | (int offset, int length, ?lsb_first: bool) -> self
+                | (Range[Integer?] range, ?lsb_first: bool) -> self
+
+    def bit_count: () -> Integer
+                 | (int offset, int length, ?lsb_first: bool) -> Integer
+                 | (Range[Integer?] range, ?lsb_first: bool) -> Integer
+
+    def bitwise_not: () -> String
+
+    def bitwise_not!: () -> self
+
+    def bitwise_and: (string other) -> String
+
+    def bitwise_and!: (string other) -> self
+
+    def bitwise_or: (string other) -> String
+
+    def bitwise_or!: (string other) -> self
+
+    def bitwise_xor: (string other) -> String
+
+    def bitwise_xor!: (string other) -> self
+  end
+end
+
+class String
+  include RigorCoreOverlay::Ruby41StringBits
+
+  def tr: (Hash[string, string] pairs) -> String
+        | ...
+
+  def tr!: (Hash[string, string] pairs) -> self?
+         | ...
+end

data/data/vendored_gem_sigs/prime/integer-extension.rbs

@@ -0,0 +1,41 @@
+%a{annotate:rdoc:skip}
+class Integer
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - each_prime(ubound) { |prime| ... }
+  # -->
+  # Iterates the given block over all prime numbers.
+  #
+  # See `Prime`#each for more details.
+  #
+  def self.each_prime: (Integer) { (Integer) -> void } -> void
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - from_prime_division(pd)
+  # -->
+  # Re-composes a prime factorization and returns the product.
+  #
+  # See Prime#int_from_prime_division for more details.
+  #
+  def self.from_prime_division: (Array[[ Integer, Integer ]]) -> Integer
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime_division(generator = Prime::Generator23.new)
+  # -->
+  # Returns the factorization of `self`.
+  #
+  # See Prime#prime_division for more details.
+  #
+  def prime_division: (?Prime::PseudoPrimeGenerator) -> Array[[ Integer, Integer ]]
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime?()
+  # -->
+  # Returns true if `self` is a prime number, else returns false. Not recommended
+  # for very big integers (> 10**23).
+  #
+  def prime?: () -> bool
+end

data/data/vendored_gem_sigs/prime/prime.rbs

@@ -0,0 +1,372 @@
+# <!-- rdoc-file=lib/prime.rb -->
+# The set of all prime numbers.
+#
+# ## Example
+#
+#     Prime.each(100) do |prime|
+#       p prime  #=> 2, 3, 5, 7, 11, ...., 97
+#     end
+#
+# Prime is Enumerable:
+#
+#     Prime.first 5 # => [2, 3, 5, 7, 11]
+#
+# ## Retrieving the instance
+#
+# For convenience, each instance method of `Prime`.instance can be accessed as a
+# class method of `Prime`.
+#
+# e.g.
+#     Prime.instance.prime?(2)  #=> true
+#     Prime.prime?(2)           #=> true
+#
+# ## Generators
+#
+# A "generator" provides an implementation of enumerating pseudo-prime numbers
+# and it remembers the position of enumeration and upper bound. Furthermore, it
+# is an external iterator of prime enumeration which is compatible with an
+# Enumerator.
+#
+# `Prime`::`PseudoPrimeGenerator` is the base class for generators. There are
+# few implementations of generator.
+#
+# `Prime`::`EratosthenesGenerator`
+# :   Uses Eratosthenes' sieve.
+# `Prime`::`TrialDivisionGenerator`
+# :   Uses the trial division method.
+# `Prime`::`Generator23`
+# :   Generates all positive integers which are not divisible by either 2 or 3.
+#     This sequence is very bad as a pseudo-prime sequence. But this is faster
+#     and uses much less memory than the other generators. So, it is suitable
+#     for factorizing an integer which is not large but has many prime factors.
+#     e.g. for Prime#prime? .
+#
+class Prime
+  include Singleton
+
+  include Enumerable[Integer]
+
+  extend Enumerable[Integer]
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - each(ubound = nil, generator = EratosthenesGenerator.new, &block)
+  # -->
+  # Iterates the given block over all prime numbers.
+  #
+  # ## Parameters
+  #
+  # `ubound`
+  # :   Optional. An arbitrary positive number. The upper bound of enumeration.
+  #     The method enumerates prime numbers infinitely if `ubound` is nil.
+  # `generator`
+  # :   Optional. An implementation of pseudo-prime generator.
+  #
+  #
+  # ## Return value
+  #
+  # An evaluated value of the given block at the last time. Or an enumerator which
+  # is compatible to an `Enumerator` if no block given.
+  #
+  # ## Description
+  #
+  # Calls `block` once for each prime number, passing the prime as a parameter.
+  #
+  # `ubound`
+  # :   Upper bound of prime numbers. The iterator stops after it yields all prime
+  #     numbers p <= `ubound`.
+  #
+  def self.each: (?Integer? ubound, ?PseudoPrimeGenerator generator) { (Integer) -> void } -> void
+                | (?Integer? ubound, ?PseudoPrimeGenerator generator) -> PseudoPrimeGenerator
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - each(ubound = nil, generator = EratosthenesGenerator.new, &block)
+  # -->
+  # Iterates the given block over all prime numbers.
+  #
+  # ## Parameters
+  #
+  # `ubound`
+  # :   Optional. An arbitrary positive number. The upper bound of enumeration.
+  #     The method enumerates prime numbers infinitely if `ubound` is nil.
+  # `generator`
+  # :   Optional. An implementation of pseudo-prime generator.
+  #
+  #
+  # ## Return value
+  #
+  # An evaluated value of the given block at the last time. Or an enumerator which
+  # is compatible to an `Enumerator` if no block given.
+  #
+  # ## Description
+  #
+  # Calls `block` once for each prime number, passing the prime as a parameter.
+  #
+  # `ubound`
+  # :   Upper bound of prime numbers. The iterator stops after it yields all prime
+  #     numbers p <= `ubound`.
+  #
+  def each: (?Integer? ubound, ?PseudoPrimeGenerator generator) { (Integer) -> void } -> void
+          | (?Integer? ubound, ?PseudoPrimeGenerator generator) -> PseudoPrimeGenerator
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - int_from_prime_division(pd)
+  # -->
+  # Re-composes a prime factorization and returns the product.
+  #
+  # For the decomposition:
+  #
+  #     [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]],
+  #
+  # it returns:
+  #
+  #     p_1**e_1 * p_2**e_2 * ... * p_n**e_n.
+  #
+  # ## Parameters
+  # `pd`
+  # :   Array of pairs of integers. Each pair consists of a prime number -- a
+  #     prime factor -- and a natural number -- its exponent (multiplicity).
+  #
+  #
+  # ## Example
+  #     Prime.int_from_prime_division([[3, 2], [5, 1]])  #=> 45
+  #     3**2 * 5                                         #=> 45
+  #
+  def self.int_from_prime_division: (Array[[ Integer, Integer ]]) -> (Integer | Rational)
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - int_from_prime_division(pd)
+  # -->
+  # Re-composes a prime factorization and returns the product.
+  #
+  # For the decomposition:
+  #
+  #     [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]],
+  #
+  # it returns:
+  #
+  #     p_1**e_1 * p_2**e_2 * ... * p_n**e_n.
+  #
+  # ## Parameters
+  # `pd`
+  # :   Array of pairs of integers. Each pair consists of a prime number -- a
+  #     prime factor -- and a natural number -- its exponent (multiplicity).
+  #
+  #
+  # ## Example
+  #     Prime.int_from_prime_division([[3, 2], [5, 1]])  #=> 45
+  #     3**2 * 5                                         #=> 45
+  #
+  def int_from_prime_division: (Array[[ Integer, Integer ]]) -> (Integer | Rational)
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime?(value, generator = Prime::Generator23.new)
+  # -->
+  # Returns true if `value` is a prime number, else returns false. Integer#prime?
+  # is much more performant.
+  #
+  # ## Parameters
+  #
+  # `value`
+  # :   an arbitrary integer to be checked.
+  # `generator`
+  # :   optional. A pseudo-prime generator.
+  #
+  def self.prime?: (Integer value, ?PseudoPrimeGenerator generator) -> bool
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime?(value, generator = Prime::Generator23.new)
+  # -->
+  # Returns true if `value` is a prime number, else returns false. Integer#prime?
+  # is much more performant.
+  #
+  # ## Parameters
+  #
+  # `value`
+  # :   an arbitrary integer to be checked.
+  # `generator`
+  # :   optional. A pseudo-prime generator.
+  #
+  def prime?: (Integer value, ?PseudoPrimeGenerator generator) -> bool
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime_division(value, generator = Prime::Generator23.new)
+  # -->
+  # Returns the factorization of `value`.
+  #
+  # For an arbitrary integer:
+  #
+  #     p_1**e_1 * p_2**e_2 * ... * p_n**e_n,
+  #
+  # prime_division returns an array of pairs of integers:
+  #
+  #     [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]].
+  #
+  # Each pair consists of a prime number -- a prime factor -- and a natural number
+  # -- its exponent (multiplicity).
+  #
+  # ## Parameters
+  # `value`
+  # :   An arbitrary integer.
+  # `generator`
+  # :   Optional. A pseudo-prime generator. `generator`.succ must return the next
+  #     pseudo-prime number in ascending order. It must generate all prime
+  #     numbers, but may also generate non-prime numbers, too.
+  #
+  #
+  # ### Exceptions
+  # `ZeroDivisionError`
+  # :   when `value` is zero.
+  #
+  #
+  # ## Example
+  #
+  #     Prime.prime_division(45)  #=> [[3, 2], [5, 1]]
+  #     3**2 * 5                  #=> 45
+  #
+  def self.prime_division: (Integer, ?PseudoPrimeGenerator generator) -> Array[[ Integer, Integer ]]
+
+  # <!--
+  #   rdoc-file=lib/prime.rb
+  #   - prime_division(value, generator = Prime::Generator23.new)
+  # -->
+  # Returns the factorization of `value`.
+  #
+  # For an arbitrary integer:
+  #
+  #     p_1**e_1 * p_2**e_2 * ... * p_n**e_n,
+  #
+  # prime_division returns an array of pairs of integers:
+  #
+  #     [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]].
+  #
+  # Each pair consists of a prime number -- a prime factor -- and a natural number
+  # -- its exponent (multiplicity).
+  #
+  # ## Parameters
+  # `value`
+  # :   An arbitrary integer.
+  # `generator`
+  # :   Optional. A pseudo-prime generator. `generator`.succ must return the next
+  #     pseudo-prime number in ascending order. It must generate all prime
+  #     numbers, but may also generate non-prime numbers, too.
+  #
+  #
+  # ### Exceptions
+  # `ZeroDivisionError`
+  # :   when `value` is zero.
+  #
+  #
+  # ## Example
+  #
+  #     Prime.prime_division(45)  #=> [[3, 2], [5, 1]]
+  #     3**2 * 5                  #=> 45
+  #
+  def prime_division: (Integer, ?PseudoPrimeGenerator generator) -> Array[[ Integer, Integer ]]
+
+  # Returns the singleton instance.
+  #
+  def self.instance: () -> Prime
+
+  # <!-- rdoc-file=lib/prime.rb -->
+  # An abstract class for enumerating pseudo-prime numbers.
+  #
+  # Concrete subclasses should override succ, next, rewind.
+  #
+  class PseudoPrimeGenerator
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - new(ubound = nil)
+    # -->
+    #
+    def initialize: (?Integer?) -> void
+
+    include Enumerable[Integer]
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - upper_bound()
+    # -->
+    # ----
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - upper_bound=(ubound)
+    # -->
+    #
+    attr_accessor upper_bound(): Integer?
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - each() { |prime| ... }
+    # -->
+    # Iterates the given block for each prime number.
+    #
+    def each: () { (Integer) -> void } -> void
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - next()
+    # -->
+    # alias of `succ`.
+    #
+    def next: () -> Integer
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - rewind()
+    # -->
+    # Rewinds the internal position for enumeration.
+    #
+    # See `Enumerator`#rewind.
+    #
+    def rewind: () -> void
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - size()
+    # -->
+    #
+    def size: () -> Float
+
+    # <!--
+    #   rdoc-file=lib/prime.rb
+    #   - succ()
+    # -->
+    # returns the next pseudo-prime number, and move the internal position forward.
+    #
+    # `PseudoPrimeGenerator`#succ raises `NotImplementedError`.
+    #
+    def succ: () -> Integer
+  end
+
+  # <!-- rdoc-file=lib/prime.rb -->
+  # An implementation of `PseudoPrimeGenerator`.
+  #
+  # Uses `EratosthenesSieve`.
+  #
+  class EratosthenesGenerator < PseudoPrimeGenerator
+  end
+
+  # <!-- rdoc-file=lib/prime.rb -->
+  # An implementation of `PseudoPrimeGenerator` which uses a prime table generated
+  # by trial division.
+  #
+  class TrialDivisionGenerator < PseudoPrimeGenerator
+  end
+
+  # <!-- rdoc-file=lib/prime.rb -->
+  # Generates all integers which are greater than 2 and are not divisible by
+  # either 2 or 3.
+  #
+  # This is a pseudo-prime generator, suitable on checking primality of an integer
+  # by brute force method.
+  #
+  class Generator23 < PseudoPrimeGenerator
+  end
+end

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

@@ -282,9 +282,9 @@ 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, with `target_ruby`,
-`paths`, and a `severity_profile` filled in and the rest
-commented out. That is all most projects need; the key
+— the project default that gets committed, with `paths` and a
+`severity_profile` filled in, `target_ruby` commented out until
+you set it to your project's Ruby, and the rest commented out. That is all most projects need; the key
 reference, the JSON-schema editor integration, and `includes:`
 composition are in
 [Configuration](../manual/03-configuration.md).

data/docs/handbook/06-classes.md

@@ -96,7 +96,9 @@ u.name    # Constant<"Alice">  — through in-source dispatch +
 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
+agree on the concrete class, unless the class's RBS
+declaration of the ivar (`@name: String | Integer`, or
+`attr_reader name: String | Integer`) admits both — see
 [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

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

@@ -159,6 +159,12 @@ 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.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
+  RBS for it, so `--write` and `--check` are unaffected. Its
+  JSON row has no `class` key. `def self.x`, a `def` inside a
+  block body and one inside `class << obj` are not reported.
 - `sig.skipped.unrenderable-rbs` — the signature Rigor
   rendered for this method does not parse as RBS. This one
   is a **bug in Rigor**, not a property of your code: every
@@ -182,11 +188,11 @@ changes which calls the signature accepts:
 $ rigor sig-gen --diff lib/c.rb
 --- lib/c.rb: C#m
 - def m: (Integer x) -> untyped
-+ def m: (Integer x) -> nil
++ def m: (Integer x) -> Float
 
 --- lib/c.rb: C#n
 - def n: (?) -> untyped
-+ def n: (?) -> nil
++ def n: (?) -> Float
 ```
 
 The `-` line is the declaration the proposal replaces. A method
@@ -517,9 +523,16 @@ Neither does a declaration the body proves as a literal.
 -> String` whose body is the string `"bot"`: the declared
 type is your abstraction over that body, and pinning the
 literal would rewrite a contract every sibling class shares.
-A method no `.rbs` declares is unaffected — the literal is
-still the strictest thing the body proves, and that is what
-gets written.
+A declared `untyped` that you wrote in `sig/` is treated
+the same way for a value literal: an Integer, String or
+Symbol the body proves is widened to its class (`-> 1`
+becomes `-> Integer`, `-> ("S" | nil)` becomes
+`-> (String | nil)`), while `nil`, `true`, `false` and a
+computed `Float` are proposed as they are. An `untyped` that
+only the inline reader synthesizes for a `def` you did not
+annotate keeps the literal, as does a method no `.rbs`
+declares — the literal is still the strictest thing the body
+proves, and that is what gets written.
 
 A comment rather than a `%a{…}` annotation, for three
 reasons: it stays out of the `rigor:v1:` directive namespace

data/docs/handbook/appendix-liskov.md

@@ -482,6 +482,11 @@ stays silent), only a proven (`:no`) violation fires, and severity
 maps through `severity_profile:` (`lenient` → off, `balanced` →
 warning, `strict` → error). The ancestor scope is the superclass
 chain plus included/prepended modules, resolved cross-file.
+Constructors and copy hooks (`initialize`, `initialize_copy`,
+`initialize_dup`, `initialize_clone`) are outside the family:
+`Class#new`, `dup` and `clone` call them on the receiver's own class,
+never through a parent-typed reference, so a subclass constructor
+that takes different arguments is not a violation.
 
 The escape hatch for a *legitimate* specialization that looks like a
 narrowing is **generics first, not suppression**: declare the parent

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

@@ -36,7 +36,7 @@ the `paths:` list from the configuration file.
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
 | `--no-cache` | Skip the persistent cache for this run. With `--incremental` it is a cold full analysis: the incremental snapshot and the run-result cache are neither read nor written, so the next plain `--incremental` run still uses the snapshot it had before. |
 | `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. A run with nothing changed is answered from the cache without starting the analyzer. See [Caching](12-caching.md). |
-| `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics are byte-identical, then exit (0 on match, 1 with the differing diagnostics on mismatch). Used in CI to guarantee `--incremental` never serves a stale result. |
+| `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics agree as a set and in the same order, then exit (0 on match, 1 on mismatch: the differing diagnostics for a set mismatch, or the first index where the order diverges for a same-set, different-order mismatch). Used in CI to guarantee `--incremental` never serves a stale result. |
 | `--clear-cache` | Delete the cache directory before running. |
 | `--cache-stats` | Print the on-disk cache inventory when finished — on stdout under `--format text`, on stderr under every other format, so machine-readable output stays a parseable document. `--clear-cache`'s and `--verify-incremental`'s notes follow the same rule. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
@@ -171,6 +171,24 @@ the two builds against each other — but if you are chasing a
 disagreement between a probe and a `check` run, comparing
 against `rigor check --no-cache` removes that variable.
 
+## `rigor lens`
+
+Map the declarations of one or more files with their types and
+type provenance (experimental). See
+[Inspecting inferred types](05-inspecting-types.md).
+
+```sh
+rigor lens [--format=text|json] [--config=PATH] [--workers=N] FILE...
+```
+
+A lens runs the same incremental analysis as
+`rigor check --incremental` and reads and writes its cache.
+`--workers` applies to a cold run. `--format=json` writes one
+`lens/v0` document ([specification](../internal-spec/lens.md)).
+Exit `0` when at least one file has a result, `1` when none
+does, `64` on a usage error; diagnostics in the code never
+change the exit status.
+
 ## `rigor trace`
 
 Replay HOW the engine typed a file, step by step, as a

data/docs/manual/03-configuration.md

@@ -19,8 +19,10 @@ To *layer* configs rather than replace, a config file can name
 a base with `includes:` (recursive). `--config=PATH` bypasses
 discovery entirely.
 
-All relative paths in a config file resolve against that
-file's own directory.
+Relative paths in a config file resolve against that file's own directory, with three exceptions:
+`bundler.bundle_path:`, `bundler.lockfile:` and `rbs_collection.lockfile:` resolve against the working directory
+`rigor` runs from. They match only when you run `rigor` from the directory that holds the config file, which is
+the usual case; with `--config path/to/.rigor.yml` from elsewhere, give these three as absolute paths.
 A leading `~/` (or a bare `~`) in a path setting expands to your home directory; `~name` is an ordinary
 directory called `~name`, not another user's home. This covers `paths:`, `signature_paths:`, `test_paths:`,
 `pre_eval:`, `plugins_io.allowed_paths:`, `includes:`, `bundler.bundle_path:`, `bundler.lockfile:` and
@@ -62,9 +64,9 @@ cache:
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `target_ruby` | String | `"4.0"` | The Ruby version *your* project runs — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. |
+| `target_ruby` | String | `"4.0"` | The lowest Ruby version *your* project runs on — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. Every value selects the syntax Rigor parses. A version you set explicitly also turns on the Ruby-deprecation rules for that version ([`call.deprecated-ruby2-keywords`](04-diagnostics.md#rule-call-deprecated-ruby2-keywords) from `"4.1"`); the default and `"latest"` never do, which is why `rigor init` writes the key commented out. |
 | `paths` | Array | `["lib"]` | Directories or files to analyse. |
-| `exclude` | Array | `[]` | Glob patterns to skip. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
+| `exclude` | Array | `[]` | Glob patterns to skip. A relative pattern is matched against the file's path relative to the directory of the config file in use (the working directory when no config file is used), so it excludes the same files whether the path came from `paths:` or from a command-line argument, and it never matches on a directory above that base (a file outside it is seen as `../…`, so `../shared/lib/gen/**` reaches a sibling directory that `paths:` names). A leading `./` is ignored, and a pattern starting with `.` (such as `.*`) also matches files outside the base, which appear as `../…`. A symlink to a file is matched only under its own name: the realpath pass resolves directories, not files. `*` and `**` also cross `/`, so `lib/*.rb` matches nested files too. An absolute pattern is matched against the absolute path. Patterns from an `includes:` file resolve against the top-level config's directory, not the included file's. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
 | `test_paths` | Array | `nil` | The project's test roots: the directories (or files) holding its tests. Relative entries resolve against the config file's directory. Unset auto-detects whichever of `spec/` and `test/` exist; `[]` declares none. `rigor sig-gen --params=observed` reads call sites there to type parameters, and names on stderr a declared root that does not exist. Test roots are not analysed unless `paths:` also lists them, and changing them invalidates no cache. |
 | `includes` | Array | `[]` | Other config files to layer underneath this one. |
 | `fold_platform_specific_paths` | Boolean | `false` | Resolve Ruby-version-conditional load paths when discovering sources. |
@@ -76,7 +78,7 @@ cache:
 | --- | --- | --- | --- |
 | `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
 | `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
-| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. The walker does not follow `require` / `require_relative`, so list the files in load order: a method declared in two files takes the last-listed one, and a file that requires a later-listed one is still read in list order. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
 ### Signature generation

data/docs/manual/04-diagnostics.md

@@ -56,6 +56,7 @@ carries no `documentation_url`.
 | <a id="rule-call-argument-type-mismatch"></a>`call.argument-type-mismatch` | An argument's type provably violates the parameter contract. | high |
 | <a id="rule-call-possible-nil-receiver"></a>`call.possible-nil-receiver` | The receiver is `T \| nil` and the method is not defined on `NilClass`. | high |
 | <a id="rule-call-raise-non-exception"></a>`call.raise-non-exception` | A `raise` / `fail` argument's concrete type is provably not an Exception class, an Exception instance, a String, or an object defining `#exception` — a runtime `TypeError`. | high |
+| <a id="rule-call-deprecated-ruby2-keywords"></a>`call.deprecated-ruby2-keywords` | A call to the `ruby2_keywords` family Ruby 4.1 deprecates: `Module#ruby2_keywords`, top-level `ruby2_keywords` and `Proc#ruby2_keywords` (removed in Ruby 4.4), or `Hash.ruby2_keywords_hash?` and `Hash.ruby2_keywords_hash` (removed in Ruby 4.5), directly or through `send` with a literal Symbol. Runs only when `.rigor.yml` sets `target_ruby` explicitly to `"4.1"` or later: the default, an older version and `"latest"` report nothing, because on Ruby 4.0 the call is correct. Not reported when a project or `pre_eval:` file defines a method by the same name, inside a block at the top level, an `instance_eval` / `instance_exec` block or an instance method of a class or module, or where a `RUBY_VERSION` guard rules the call out on the stated Ruby or cannot be decided. `info` under `lenient`, `warning` under `balanced`, `error` under `strict`. | high |
 | <a id="rule-call-unresolved-toplevel"></a>`call.unresolved-toplevel` | A top-level implicit-self call resolves against no same-file `def`, `pre_eval:` patch, or `Kernel` / `Object` method. | low |
 | <a id="rule-flow-always-raises"></a>`flow.always-raises` | The expression provably raises on every reachable path. | high |
 | <a id="rule-flow-unreachable-branch"></a>`flow.unreachable-branch` | An `if` / `unless` / ternary branch is statically dead. | high |
@@ -66,7 +67,7 @@ carries no `documentation_url`.
 | <a id="rule-flow-return-in-ensure"></a>`flow.return-in-ensure` | An explicit `return` inside an `ensure` clause — it overrides the method's in-flight return value and silently swallows any in-flight exception. A `return` in a nested `def`, lambda, or `define_method` block inside the `ensure` does not fire (it exits that inner frame). | high |
 | <a id="rule-flow-shadowed-rescue-clause"></a>`flow.shadowed-rescue-clause` | A `rescue` clause can never run because an earlier clause of the same chain already catches a superclass (or the same class) of every exception class it names. | high |
 | <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
-| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write. | high |
+| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write, unless its RBS declaration (`@x: T` or an `attr_*` member) admits both writes. | high |
 | <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
 | <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |