rigortype 0.2.1 → 0.2.3

data/docs/handbook/04-tuples-and-shapes.md

@@ -0,0 +1,321 @@
+# Tuples and hash shapes
+
+`Tuple` and `HashShape` are how Rigor gives precise types to
+heterogeneous arrays and known-key hashes. They look a lot like
+Ruby's `Array` and `Hash` from the outside (and erase to those
+nominal types when crossing an RBS boundary), but inside Rigor
+they carry the per-position / per-key types that ordinary
+`Array[T]` / `Hash[K, V]` would lose.
+
+## Tuples — heterogeneous arrays
+
+When the analyzer can prove the layout of an array literal, it
+produces `Tuple[…]` rather than `Array[T]`:
+
+```ruby
+arr = [1, "two", :three]
+# Tuple[Constant<1>, Constant<"two">, Constant<:three>]
+```
+
+The most common ways tuples appear in real code:
+
+```ruby
+# Multiple-assignment destructuring is per-position.
+first, second, third = [10, 20, 30]
+assert_type("10", first)
+assert_type("20", second)
+assert_type("30", third)
+
+# divmod returns a 2-tuple.
+quotient, remainder = 17.divmod(5)
+assert_type("3", quotient)
+assert_type("2", remainder)
+
+# Each-with-index yields a 2-tuple.
+%w[a b c].each_with_index do |elt, idx|
+  assert_type("\"a\" | \"b\" | \"c\"", elt)
+  assert_type("non-negative-int", idx)
+end
+```
+
+Indexed access into a tuple stays per-position:
+
+```ruby
+arr = [1, "two", :three]
+arr[0]   # Constant<1>
+arr[1]   # Constant<"two">
+arr[-1]  # Constant<:three>
+arr[5]   # Constant<nil> — out of bounds
+```
+
+Slicing with `[start, length]` or `[range]` produces a tuple
+of the matching elements:
+
+```ruby
+arr = [10, 20, 30, 40, 50]
+arr[1..3]    # Tuple[Constant<20>, Constant<30>, Constant<40>]
+arr[2, 2]    # Tuple[Constant<30>, Constant<40>]
+```
+
+## Tuples through `map`, `select`, and friends
+
+When you call an Enumerable method on a tuple, Rigor evaluates
+the block once per element with the per-position type
+substituted, then unions the results:
+
+```ruby
+arr = [1, 2, 3]
+doubled = arr.map { |n| n * 2 }
+# Tuple[Constant<2>, Constant<4>, Constant<6>]
+
+mixed = [1, "two", :three]
+strings = mixed.map { |x| x.to_s }
+# Tuple[Constant<"1">, Constant<"two">, Constant<"three">]
+```
+
+`select` and `filter_map` widen to `Array[Element]` because
+the resulting size depends on the predicate, not the
+positions. `find` returns the union of the elements (or `nil`
+when no element matches statically).
+
+## Tuples widen — when and why
+
+A `Tuple` widens to `Array[T]` when its size grows past the
+configurable union budget, when an unknown-shape array is
+concatenated to it, or when it crosses an RBS-declared
+parameter typed as `Array[T]`. The widening is deterministic
+and documented in
+[`docs/type-specification/inference-budgets.md`](../type-specification/inference-budgets.md).
+
+Widening is safe (`Array[T]` is a strictly less precise view
+of the same value), but you lose the per-position information.
+If you find yourself writing code where `[a, b, c]` should
+type-check precisely but does not, look for a method
+in the chain that takes `Array[T]` rather than a tuple, or a
+`+` / `concat` against a wider array.
+
+## Hash shapes — known-key hashes
+
+The hash analogue is `HashShape`:
+
+```ruby
+user = { name: "Alice", age: 30, admin: false }
+# { name: "Alice", age: 30, admin: false }
+
+assert_type("\"Alice\"", user[:name])
+assert_type("30", user[:age])
+assert_type("false", user[:admin])
+```
+
+Hash shapes have a few extra dimensions over tuples:
+
+- **Required vs optional keys.** Was the key written
+  unconditionally in the literal, or merged in conditionally?
+- **Open vs closed.** Can the value carry extra keys beyond
+  the listed ones?
+- **Read-only entries.** Has Rigor seen a write to the key, or
+  only reads?
+
+Rigor tracks all three but exposes them mostly through the
+narrowing rules — most users do not need to think about them
+directly.
+
+## Hash shapes through method calls
+
+```ruby
+config = { host: "example.com", port: 8080 }
+# HashShape{host: Constant<"example.com">, port: Constant<8080>}
+
+config.fetch(:host)        # Constant<"example.com">
+config.fetch(:host, "x")   # Constant<"example.com"> (default unused)
+config[:port]              # Constant<8080>
+config.key?(:host)         # Constant<true>  — proven
+config.empty?              # Constant<false> — proven
+config.size                # Constant<2>
+```
+
+## Keyword-argument hashes
+
+When you call a method with keyword arguments, the implicit
+hash shape is what Rigor type-checks against:
+
+```ruby
+def connect(host:, port: 80)
+  # ...
+end
+
+connect(host: "example.com")            # OK (port defaults)
+connect(host: "example.com", port: 80)  # OK
+connect(host: "example.com", port: "8080")  # warning when
+                                            #  port: Integer
+                                            #  is required
+```
+
+Hash shapes flow through `**` splat and double-splat
+operations, so `connect(**opts)` where `opts` is a known
+shape narrows correctly.
+
+## Splat composition
+
+Splatting one tuple into another preserves the per-position
+information when the splat is at a fixed position:
+
+```ruby
+head = [1, 2]
+tail = [3, 4]
+arr = [*head, *tail]
+# Tuple[Constant<1>, Constant<2>, Constant<3>, Constant<4>]
+
+with_middle = [*head, "X", *tail]
+# Tuple[Constant<1>, Constant<2>, Constant<"X">,
+#       Constant<3>, Constant<4>]
+```
+
+Same for double-splat into hash shapes:
+
+```ruby
+defaults = { port: 80, ssl: false }
+overrides = { port: 443, ssl: true }
+final = { **defaults, **overrides }
+# HashShape{port: Constant<443>, ssl: Constant<true>}
+# (the override wins per Ruby semantics)
+```
+
+## Pattern matching destructuring
+
+`case x in [a, b, c]` narrows `a` / `b` / `c` per-position
+exactly like multiple-assignment:
+
+```ruby
+case [10, 20, 30]
+in [first, _, third]
+  assert_type("Dynamic[top]", first)   # pattern bindings are not constant-folded
+  assert_type("Dynamic[top]", third)
+end
+```
+
+Hash patterns work the same way:
+
+```ruby
+case { name: "Alice", age: 30 }
+in { name:, age: }
+  assert_type("Dynamic[top]", name)   # pattern bindings are not constant-folded
+  assert_type("Dynamic[top]", age)
+end
+```
+
+An alternation pattern (`Integer | String => x`) produces a
+union for the captured local — see
+[Chapter 3](03-narrowing.md) for the underlying narrowing
+rule.
+
+## When the layout is not provable
+
+If even one element of an array literal has a non-Constant,
+non-tuple-shaped type, Rigor falls back to `Array[T]` where
+`T` is the union of element types — still useful, just not
+per-position:
+
+```ruby
+arr = [1, ARGV.first]
+# Array[Constant<1> | String?]
+```
+
+The same goes for hashes whose keys are not provably symbol /
+string literals — Rigor produces `Hash[K, V]` rather than
+`HashShape`.
+
+## Deriving new shapes — `pick_of` / `omit_of` / `partial_of` / `required_of` / `readonly_of`
+
+When you have a `HashShape` (or a `Tuple`) and want a derived
+shape that keeps some fields, drops others, or flips the
+required-ness, Rigor exposes five **shape-projection type
+functions** on `Type::Combinator`. They mirror TypeScript's
+`Pick` / `Omit` / `Partial` / `Required` / `Readonly` utility
+types but are first-class Rigor operations, not a TS bolt-on.
+Each preserves the source's existing classification (required /
+optional / read-only / extra-keys policy) on the entries it
+keeps.
+
+| Projection | What it does | TypeScript analogue |
+| --- | --- | --- |
+| `pick_of[T, K]` | Keep only the entries whose key is in the literal-key union `K`. On `Tuple`, `K` is an integer-index union. | `Pick<T, K>` |
+| `omit_of[T, K]` | Drop the entries whose key is in `K`; keep the rest. | `Omit<T, K>` |
+| `partial_of[T]` | Flip every required entry to optional. **Does not** widen value types to `nil` — Rigor distinguishes "key absent" from "key present with `nil` value". | `Partial<T>` |
+| `required_of[T]` | Inverse of `partial_of`. Every optional entry becomes required. | `Required<T>` |
+| `readonly_of[T]` | Mark every entry as read-only in the current view. Does NOT prove the underlying object is frozen — it is a view-level marker. | `Readonly<T>` |
+
+These show up in two surfaces:
+
+### As `RBS::Extended` directive payloads
+
+The projection name is part of the directive grammar — the
+parser accepts Symbol / String literals and `|`-unions inside
+the type-arg position, so you can author the key set inline:
+
+```rbs
+class UserView
+  # The runtime returns the full user hash; the view exposes
+  # only :name and :email to its caller. The directive narrows
+  # the return-side HashShape to those two entries.
+  %a{rigor:v1:return: pick_of[UserHash, :name | :email]}
+  def public_attrs: () -> ::Hash[::Symbol, ::String]
+end
+```
+
+Inside an analysed file, the call site's result type is the
+projected HashShape rather than the raw `Hash[Symbol, String]`
+the underlying RBS sig advertises.
+
+### Through the opt-in TypeScript-utility-types plugin
+
+If you prefer the TS spellings (`Pick<T, K>` etc.) in
+directives, opt into the
+[`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/)
+plugin. The plugin registers a `Plugin::TypeNodeResolver` that
+translates each TS name onto the canonical projection:
+
+```yaml
+# .rigor.yml
+plugins:
+  - gem: rigor-typescript-utility-types
+```
+
+```rbs
+%a{rigor:v1:return: Pick[UserHash, "name" | "email"]}
+```
+
+The plugin chain resolves `Pick[…]` to `pick_of[…]` before the
+analyzer sees it — the inferred result is identical to the
+direct `pick_of` spelling. The plugin is purely a naming
+convenience.
+
+### Lossy projection
+
+The projections fire only on carriers that preserve shape
+information (`HashShape` and, for `pick_of` / `omit_of`,
+`Tuple`). Applying them to a plain `Hash[K, V]` or any other
+non-shape input is **lossy** — the projection silently
+degrades to the input type and Rigor records a
+[`dynamic.shape.lossy-projection`](../type-specification/diagnostic-policy.md)
+`:info` diagnostic so you can audit the call site.
+
+```rbs
+class C
+  # `User` here is `Nominal[User]`, not a HashShape, so the
+  # projection cannot narrow anything. The directive is
+  # accepted but `:info` records the lossy degrade.
+  %a{rigor:v1:return: pick_of[User, :name]}
+  def render: () -> ::User
+end
+```
+
+The fix is usually to author a `HashShape` carrier (or use
+`Data.define` / a `Struct`) instead of a bare `Nominal`.
+
+## What's next
+
+Chapter 5 covers the function side: how Rigor types method
+parameters and return values, how block parameters are bound
+through Enumerable iteration, and how arity / parameter-type
+mismatches surface as `call.*` diagnostics.

data/docs/handbook/05-methods-and-blocks.md

@@ -0,0 +1,339 @@
+# Methods and blocks
+
+This chapter covers what Rigor knows about method calls — the
+receiver's type, the argument types, the inferred return
+type, and the block parameters when a block is attached.
+Several sections double as the reference for a call-site
+diagnostic, so the rule IDs appear in the headings.
+
+## Method dispatch — what Rigor sees at a call site
+
+When Rigor encounters `receiver.method(args, &block)`, it
+runs through a fixed sequence of dispatch tiers, taking the
+first one that produces a result:
+
+1. **Constant folding.** Every argument is a `Constant<...>`
+   or a tuple of constants, the receiver is a known
+   nominal class, and the method is in the per-class
+   "pure" catalog. Rigor invokes the method at lint time
+   and returns the result. `1 + 2` → `Constant<3>`,
+   `[1, 2, 3].first` → `Constant<1>`.
+2. **Shape dispatch.** The receiver carries a `Tuple` /
+   `HashShape` / `IntegerRange` / refinement and the method
+   has a per-shape rule. `Tuple[A, B, C].size` →
+   `Constant<3>`; `int<0, max>.zero?` → `Constant<true> |
+   Constant<false>`.
+3. **RBS dispatch.** The class has an RBS sig for the method.
+   Argument types are checked against the parameter contract
+   (more on this below); the return type is read from the sig
+   and may be tightened by `RBS::Extended` directives.
+4. **In-source dispatch.** The class has no RBS but Rigor
+   discovered a `def` (or `define_method`, `attr_*`) in the
+   project. Parameter types are not checked (no contract);
+   the return type is inferred from the method body.
+5. **Fallback.** None of the above — the call returns
+   `Dynamic[top]` and stays silent.
+
+The cascading "first match wins" structure is why a method
+with a tight RBS sig + an `RBS::Extended` directive overrides
+the in-source body's inferred return type. Tightening at the
+sig level is the supported way to teach Rigor about a
+domain-specific method whose return type is narrower than
+RBS expresses.
+
+## Argument typing — `call.argument-type-mismatch`
+
+When the method has an RBS sig (or an `RBS::Extended`
+parameter override), Rigor checks each positional / keyword
+argument against the declared parameter type:
+
+```rbs
+class Slug
+  %a{rigor:v1:param: id is non-empty-string}
+  def normalise: (::String id) -> ::String
+end
+```
+
+```ruby
+Slug.new.normalise("hello")  # OK — Constant<"hello"> accepted
+                             # by non-empty-string
+
+Slug.new.normalise("")       # error: argument-type-mismatch
+                             # ("" is the one value
+                             # non-empty-string excludes)
+
+Slug.new.normalise(some_str) # OK if Rigor cannot prove some_str
+                             # is empty; Rigor stays silent on
+                             # "could be either" cases.
+```
+
+`call.argument-type-mismatch` only fires when Rigor can
+**prove** the argument cannot satisfy the parameter contract.
+"Possibly empty" stays silent — the no-false-positives rule.
+
+## Arity — `call.wrong-arity`
+
+When the receiver class is statically known and the method is
+discoverable (RBS sig or in-source `def`), Rigor checks the
+number of arguments against the method's arity:
+
+```ruby
+[1, 2, 3].rotate(1, 2)
+# error: wrong number of arguments to `rotate' on Array
+#        (given 2, expected 0..1)
+```
+
+Arity checking respects optional positional, splat, keyword
+arguments, and overload signatures. When the method is
+overloaded, every overload that accepts the given arity is a
+candidate — Rigor only flags arity when **no** overload
+accepts.
+
+## `call.undefined-method`
+
+When the receiver class is statically known and the method is
+not in any of (RBS sig, in-source `def`, in-source attr,
+`Data.define` accessor), Rigor flags the call:
+
+```ruby
+"hello".no_such_method
+# error: undefined method `no_such_method' for "hello"
+```
+
+The rule is **deliberately conservative**: a call only fires
+when the receiver type is statically known and the method
+catalogue is enumerable. `Dynamic[top]` receivers, implicit-
+self calls inside method bodies, and constant-decl alias
+classes (`YAML` → `Psych`) are silenced.
+
+## `call.possible-nil-receiver`
+
+When the receiver's type is `T | nil` and the method called
+on it is not defined on `NilClass`, Rigor flags it:
+
+```ruby
+def shout(name)
+  name.upcase  # warning if name: String?
+end
+```
+
+The fix is usually a guard:
+
+```ruby
+def shout(name)
+  return "" if name.nil?
+  name.upcase  # name: String now
+end
+```
+
+This rule is one of the highest-value diagnostics Rigor ships.
+It catches the entire family of `NoMethodError on nil`
+crashes that pepper any non-trivial Ruby code base.
+
+## Return-type inference for in-source methods
+
+When you write a `def` without an RBS sig, Rigor infers the
+return type from the method body. The inferred type is
+whatever the last expression evaluates to:
+
+```ruby
+def double(n)
+  n * 2
+end
+
+double(5)   # Constant<10>  — Rigor folds the call
+```
+
+When the body has multiple branches, the return type is the
+union of every reachable terminal expression:
+
+```ruby
+def kind(x)
+  if x.is_a?(Integer)
+    :int
+  elsif x.is_a?(String)
+    :str
+  end
+end
+
+kind(7)        # Constant<:int>
+kind("hi")     # Constant<:str>
+kind(:nope)    # Constant<nil>  — the implicit nil from
+               # the if's missing else branch
+```
+
+`return` mid-body works as expected; explicit `raise` excludes
+that branch from the union (a `bot` carrier internally).
+
+### Recursive methods
+
+A recursive method infers a precise return type rather than
+collapsing to `Dynamic[top]`. When the recursive call has
+fully-constant arguments, Rigor unrolls it (under a hard frame
+budget) and folds the result:
+
+```ruby
+def factorial(n)
+  n <= 1 ? 1 : n * factorial(n - 1)
+end
+
+factorial(5)   # Constant<120>
+```
+
+When the arguments are not constant, Rigor reaches a fixpoint
+*return summary* instead — so a pass-through recursion returns
+the right type rather than a contaminated one:
+
+```ruby
+def last_step(n)
+  n <= 0 ? :done : last_step(n - 1)
+end
+
+last_step(some_int)   # Constant<:done>
+```
+
+Both paths are hard-capped and degrade to the previous
+base-type behaviour when they cannot converge. Mutual
+recursion across two methods terminates, degrading to a safe
+`Dynamic[top]` floor where a precise summary is unavailable.
+
+## `def.return-type-mismatch`
+
+When a method has both an RBS-declared return type and an
+inferred one, Rigor checks that the inferred fits the
+declared:
+
+```rbs
+class Slug
+  def normalise: (::String) -> ::String
+end
+```
+
+```ruby
+class Slug
+  def normalise(s)
+    s.empty? ? nil : s.upcase   # warning:
+                                # def.return-type-mismatch
+                                # (declared String, inferred
+                                # String | nil)
+  end
+end
+```
+
+The rule is the symmetric counterpart of
+`call.argument-type-mismatch`: argument-side is "the caller
+gave me a wrong type"; return-side is "I gave my caller a
+wrong type."
+
+## Block parameters
+
+When a method takes a block, Rigor binds the block parameters
+based on the receiver method's signature. Every block-using
+method in the bundled catalog has a per-method rule:
+
+```ruby
+[1, 2, 3].each do |n|
+  assert_type("1 | 2 | 3", n)
+end
+
+%w[a b c].each_with_index do |word, idx|
+  assert_type("\"a\" | \"b\" | \"c\"", word)
+  assert_type("non-negative-int", idx)
+end
+
+{name: "Alice", age: 30}.each_pair do |key, value|
+  assert_type(":age | :name", key)
+  assert_type("\"Alice\" | 30", value)
+end
+```
+
+Per-position binding works for tuples, hash shapes, and
+ranges. When the receiver is widened (`Array[T]` instead of
+`Tuple[…]`), the block parameter is the element type `T`.
+
+When the receiving method does not have a per-method rule,
+the block parameter falls back to `Dynamic[top]`. Custom
+block-using methods you write in your project's source are
+seen by the in-source dispatch tier — Rigor walks the body to
+infer the parameter type from `yield` calls — but that
+analysis is more limited than the catalogued built-ins.
+
+## Numbered parameters and `it`
+
+`_1`, `_2`, ..., and Ruby 3.4's `it` are bound exactly like
+explicit parameters:
+
+```ruby
+[1, 2, 3].each { _1.succ }
+# _1: Constant<1> | Constant<2> | Constant<3>
+
+[10, 20, 30].each { it.to_s }
+# it: same as the explicit form
+```
+
+## Block-local declarations (`do |i; x|`)
+
+The `;`-prefixed names introduce a fresh block-local
+variable that shadows any outer local of the same name. Rigor
+binds these locals to `Constant<nil>` at block entry — Ruby's
+runtime semantics — and treats writes inside the block as
+local to the block:
+
+```ruby
+x = 100
+[1, 2, 3].each do |i; x|
+  # x: Constant<nil>  at this point — the block-local shadow
+  x = i * 2
+  # x: Constant<2> | Constant<4> | Constant<6>
+end
+
+assert_type("100", x)  # outer x untouched
+```
+
+## Closure escape and captured locals
+
+When a block captures an outer local, the block's writes to
+that local flow back into the post-call view of the local. For
+known non-escaping methods (`Array#each`, `tap`, …) the
+write-back is applied; for escaping methods (`Thread.new`,
+`define_method`, …) the analyzer drops captured-local facts
+because the block could fire arbitrarily later.
+
+The write-back covers both *rebinding* a local and *mutating a
+collection* the block was building up. A rebound accumulator
+widens to its base type rather than keeping a stale seed, and a
+collection grown inside the block carries the appended element
+types:
+
+```ruby
+total = 0
+[1, 2, 3].each { |n| total += n }
+# total: Integer  — the rebind is written back (not a stale 0)
+
+out = [0]
+[1, 2, 3].each { |x| out << x }
+# out: Array[Integer]  — the appended element type joins in,
+#                        not just the seed's Constant<0>
+
+squares = [1, 2, 3].each_with_object([]) { |n, acc| acc << n * n }
+# squares: Array[Integer]
+```
+
+The same write-back applies to `while` / `until` loop
+bodies — an accumulator a loop rebinds no longer keeps a stale
+single-pass constant. The analysis runs the body to a small
+fixpoint and widens (it never folds a loop accumulator to a
+value the runtime would exceed). A `for` loop joins a single
+body pass rather than running this fixpoint. For an *escaping* or unknown
+block that mutates a captured collection, the local widens to
+its bare-collection floor instead of an unsoundly-precise seed.
+
+This is the conservative call: better to widen too much than
+to claim narrowed-after-escape facts that the runtime might
+violate.
+
+## What's next
+
+Chapter 6 covers the class side: how Rigor types `self`,
+constant lookup, `attr_*` declarations, and the
+class-vs-instance method distinction.