rigortype 0.2.1 → 0.2.2

data/docs/handbook/02-everyday-types.md

@@ -0,0 +1,337 @@
+# Everyday types
+
+This is the most important chapter. Once you have a feel for
+the carriers below, the rest of the handbook is rules
+operating on them. This is also the page to come back to as a
+glossary; the table below is the whole carrier zoo at a
+glance.
+
+## Why "type" is too coarse a word
+
+A vanilla static checker answers "what *class* is this
+object?" Rigor answers a narrower question: "what *subset of
+values* can this expression actually produce?"
+
+```ruby
+n = 1 + 2
+```
+
+A vanilla checker says: `n: Integer`. Rigor says:
+`n: Constant<3>`. Both are correct; Rigor's is much more
+useful.
+
+```ruby
+n = ARGV.size
+```
+
+A vanilla checker says: `n: Integer`. Rigor says:
+`n: int<0, max>` (a non-negative integer — `Array#size` cannot
+return a negative count).
+
+The reason this matters: most diagnostics Rigor wants to fire
+need the narrower fact. "Integer" is not enough to prove
+`n / 0` always raises; `Constant<0>` is. "Array" is not enough
+to prove `arr.first.upcase` is safe; `non-empty-array[String]`
+is.
+
+So: every value at every program point is described by a
+**carrier**. Carriers can be wide (`Integer`, `Dynamic[top]`)
+or narrow (`Constant<3>`, `non-empty-string`). The rest of
+this chapter is the carrier zoo.
+
+One note on notation before the zoo: angle brackets hold a
+concrete value or bound — `Constant<3>`, `int<0, max>` —
+while square brackets hold type parameters, exactly as in RBS
+— `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`.
+
+## Seeing carriers yourself — `rigor annotate`
+
+Every code example below tags each line with its inferred
+type in a trailing `#=> dump_type:` comment:
+
+```ruby
+two = 1 + 1   #=> dump_type: Constant<2>
+```
+
+That is the comment format `rigor annotate FILE` produces:
+it reprints a source file with every line tagged by the
+carrier of the expression that line evaluates to. Run it on
+your own code to watch the carrier zoo appear in the margin.
+(`annotate` prints carriers in their compact display form,
+so it writes `2` where this handbook spells `Constant<2>`
+out in full.)
+
+## Nominal types — the familiar starting point
+
+The simplest carrier is the one you already know:
+`Nominal[ClassName]`. It says "this is an instance of that
+class" with no additional information.
+
+```ruby
+n = ARGV.first  #=> dump_type: Nominal[String] | Constant<nil>
+                # RBS says `String?` — String | nil
+```
+
+`Nominal[Integer]`, `Nominal[String]`, `Nominal[Symbol]`,
+`Nominal[Hash[K, V]]` — exactly what you expect. The display
+form drops the `Nominal[]` wrapper for readability:
+`Integer`, `String`, `Hash[String, Integer]`.
+
+Rigor reads nominal types from RBS. When you write
+`def foo(s) -> ::String`, the call site's result is
+`Nominal[String]`. When the receiver class has a richer
+catalogue (built-in `String`, `Array`, `Integer`, …), Rigor
+often produces something narrower than nominal — see below.
+
+## Constants — single Ruby values
+
+`Type::Constant` is Rigor's "I know exactly which value this
+is" carrier. It wraps one Ruby literal:
+
+```ruby
+n   = 42       #=> dump_type: Constant<42>
+s   = "hello"  #=> dump_type: Constant<"hello">
+sym = :foo     #=> dump_type: Constant<:foo>
+t   = true     #=> dump_type: Constant<true>
+```
+
+Rigor folds arithmetic and string composition aggressively
+when every operand is a Constant:
+
+```ruby
+two = 1 + 1               #=> dump_type: Constant<2>
+ten = 5 * 2               #=> dump_type: Constant<10>
+hi  = "Hello, " + "world" #=> dump_type: Constant<"Hello, world">
+sym = "foo".to_sym        #=> dump_type: Constant<:foo>
+```
+
+Folding extends to a long list of "pure" methods on Numeric,
+String, Symbol, Array, and Hash. The list is not in this
+handbook (it would fill several pages); see
+[`docs/types.md`](../types.md) and the per-class catalogues
+under
+[`data/builtins/ruby_core/`](../../data/builtins/ruby_core/).
+
+When folding is **not** safe (because a method has side
+effects, depends on the environment, or is not in a
+catalogued built-in class), Rigor declines and you get a
+nominal carrier or `Dynamic[top]`.
+
+## Integer ranges — bounded intervals
+
+Some integer-valued expressions produce a known range without
+producing a single literal value. Rigor describes those with
+`Type::IntegerRange`, displayed as `int<min, max>`:
+
+```ruby
+n = ARGV.size               #=> dump_type: int<0, max>
+m = n + 1                   #=> dump_type: int<1, max>
+double = n * 2              #=> dump_type: int<0, max>
+```
+
+`max` here means "positive infinity" — the upper bound is
+unbounded; `min`, which appears in the table below, is its
+mirror, "negative infinity." Multiplication preserves the
+floor, so `n * 2` stays `int<0, max>`.
+
+A handful of common ranges have shorter names:
+
+| Spelling | Meaning |
+| --- | --- |
+| `positive-int` | `int<1, max>` |
+| `non-negative-int` | `int<0, max>` |
+| `negative-int` | `int<min, -1>` |
+| `non-positive-int` | `int<min, 0>` |
+
+`Array#size`, `Array#length`, `Hash#size`, `String#size`, …
+all carry `non-negative-int`. `Array#count` does too. Adding
+`1` to a `non-negative-int` produces a `positive-int`. Adding
+`-1` produces an unconstrained `Integer` (it could go below
+zero).
+
+## Refinements — values restricted by a predicate
+
+Some types are not "this nominal class minus / plus a literal
+value" but "this nominal class restricted by a predicate."
+Rigor uses the carrier `Type::Refined` for these, displayed
+with a kebab-case name. The catalogue:
+
+| Refinement | Means |
+| --- | --- |
+| `non-empty-string` | `String` whose `#empty?` is provably `false` |
+| `lowercase-string` | `String` equal to its `#downcase` |
+| `uppercase-string` | `String` equal to its `#upcase` |
+| `numeric-string` | `String` parseable as a number |
+| `decimal-int-string` | `String` parseable as a decimal integer |
+| `octal-int-string` | leading `0o` / octal digits |
+| `hex-int-string` | leading `0x` / hex digits |
+| `literal-string` | `String` provably composed from literals |
+| `non-empty-lowercase-string` | both at once |
+| `non-empty-uppercase-string` | both at once |
+| `non-empty-literal-string` | both at once |
+
+Most of these carriers come into being one of two ways:
+
+1. **Through narrowing** — `if s.empty?` gives `s` the type
+   `non-empty-string` in the false branch (see
+   [Chapter 3](03-narrowing.md)).
+2. **Through `RBS::Extended` annotations** — a method's RBS
+   sig says `String`, but the author knows the runtime
+   always returns non-empty, so they tag
+   `%a{rigor:v1:return: non-empty-string}` (see
+   [Chapter 7](07-rbs-and-extended.md)).
+
+Refinements **erase** to their base nominal class for RBS
+interop. A method whose signature says `-> String` keeps
+that contract — Rigor only adds a tighter view inside its
+own analysis.
+
+The negation form `~T` denotes the complement: `~lowercase-string`
+is "a String that has at least one non-lowercase character."
+A small number of refinements have a hand-paired complement
+(`lowercase-string` ↔ `non-lowercase-string`) which Rigor
+prefers when it can; the rest fall back to a generic
+`Difference` form.
+
+## Difference — a base minus a single value
+
+`non-empty-string` could equivalently be spelled
+`String - ""`. Rigor uses `Type::Difference` for this kind of
+carrier:
+
+| Carrier | Equivalent |
+| --- | --- |
+| `non-empty-string` | `String - ""` |
+| `non-zero-int` | `Integer - 0` |
+| `non-empty-array[T]` | `Array[T] - []` |
+| `non-empty-hash[K, V]` | `Hash[K, V] - {}` |
+
+You will see them most often in narrowing:
+
+```ruby
+n = some_integer_call
+if n.zero?
+  n   #=> dump_type: Constant<0>
+else
+  n   #=> dump_type: non-zero-int
+end
+```
+
+## `Dynamic[top]` — the gradual carrier
+
+Sometimes Rigor cannot prove anything tighter than "this
+could be any Ruby value" — a bare parameter, for instance,
+carries no calling-side information. That is `Dynamic[top]`,
+often shortened to `untyped` for the RBS-erased view.
+
+```ruby
+def foo(x)
+  x.bar   #=> dump_type: Dynamic[top]
+end
+```
+
+`Dynamic[T]` (with a non-Top inner) is the more specific
+gradual form: "we do not have a static contract for this
+value, but the static facet behaves like `T`." It pops up
+when an RBS-declared `untyped` boundary meets a class Rigor
+already knows something about.
+
+A diagnostic NEVER fires on a `Dynamic[top]` receiver. That is
+the no-false-positives stance — Rigor stays silent rather
+than reporting on values it cannot characterise.
+
+## Tuples and hash shapes — heterogeneous structures
+
+`[1, "two", :three]` is more specific than "an Array of mixed
+elements." Rigor describes it with `Type::Tuple`:
+
+```ruby
+arr = [1, "two", :three]
+#=> dump_type: Tuple[Constant<1>, Constant<"two">, Constant<:three>]
+
+first, second, third = arr
+first   #=> dump_type: Constant<1>
+second  #=> dump_type: Constant<"two">
+third   #=> dump_type: Constant<:three>
+```
+
+Same for hashes with literal keys:
+
+```ruby
+h = { name: "Alice", age: 30 }
+#=> dump_type: HashShape{name: Constant<"Alice">, age: Constant<30>}
+
+h[:name]  #=> dump_type: Constant<"Alice">
+```
+
+Tuples and hash shapes erase to `Array[…]` and `Hash[K, V]`
+when crossing an RBS boundary. Inside Rigor they carry the
+full per-position / per-key type information so destructuring
+and slot access stay precise.
+
+Chapter 4 covers tuples and hash shapes in depth.
+
+## Unions — "one of these"
+
+When a value can be one of finitely many types, Rigor uses
+`Type::Union`:
+
+```ruby
+label = case n
+        when 0      then :zero
+        when 1..9   then :small
+        else             :large
+        end
+#=> dump_type: Constant<:zero> | Constant<:small> | Constant<:large>
+```
+
+A union of constants is the closest Ruby gets to a sum type or
+discriminated union. Rigor takes them seriously: switching on
+a literal-union value with `case` produces a precise narrowing
+(see [Chapter 3](03-narrowing.md)).
+
+There are limits — Rigor does not extend a union past a
+configurable size budget. Beyond that, it widens to the union
+of the members' nominal bases. This keeps the analyzer fast
+and predictable on degenerate input.
+
+## A worked example
+
+Putting it together:
+
+```ruby
+def classify(n)
+  if n.zero?
+    :zero
+  elsif n.positive?
+    :positive
+  else
+    :negative
+  end
+end
+
+result = classify(some_integer_input)
+#=> dump_type: Constant<:zero> | Constant<:positive> | Constant<:negative>
+```
+
+A vanilla type-checker would call `result: Symbol`. Rigor
+narrows to the exact 3-element union. If you later write
+
+```ruby
+case result
+when :positive then "+"
+when :negative then "-"
+when :zero     then "0"
+end
+```
+
+Rigor proves the `case` is exhaustive — every union member
+matches some `when` — and the result is
+`Constant<"+"> | Constant<"-"> | Constant<"0">`.
+
+## What's next
+
+Chapter 3 (narrowing) is the engine that takes these carriers
+and changes them as control flow passes — `if` / `case` /
+`is_a?` / `nil?`. That is where the value-lattice carriers
+above start paying for themselves.

data/docs/handbook/03-narrowing.md

@@ -0,0 +1,359 @@
+# Narrowing
+
+A carrier describes a value at one program point. **Narrowing**
+describes how the carrier changes when control flow passes
+through a predicate. This chapter walks through every form of
+narrowing Rigor recognises today.
+
+The mental model: each predicate produces two scopes — one
+for the truthy edge and one for the falsey edge. Inside each
+edge, the variable's carrier is sharpened to whatever the
+predicate proved. If the predicate is unrecognised, both
+edges share the entry scope unchanged.
+
+## Truthiness narrowing
+
+The simplest form. `if x` separates "x is truthy" from "x is
+`false` or `nil`":
+
+```ruby
+def shout(name)
+  if name
+    # name: String — `false | nil` removed by truthy edge
+    name.upcase
+  else
+    # name: Constant<false> | Constant<nil>
+    "(no name)"
+  end
+end
+```
+
+This is what makes the ubiquitous `if value` idiom useful at
+lint time: inside the `if` body, Rigor knows `value` is
+non-nil.
+
+## `nil?` and the inverse
+
+```ruby
+def length(s)
+  return 0 if s.nil?
+  # s: Nominal[String] (the nil component of String? is gone)
+  s.length
+end
+```
+
+`s.nil?` narrows the truthy edge to `Constant<nil>` and the
+falsey edge to "everything else" — typically the original
+type with `nil` removed.
+
+## `is_a?`, `kind_of?`, `instance_of?`
+
+These three all narrow on the class hierarchy:
+
+```ruby
+def kind(x)
+  if x.is_a?(Integer)
+    # x: Integer
+    x + 1
+  elsif x.is_a?(String)
+    # x: String
+    x.length
+  end
+end
+```
+
+Subclass relationships are honoured: `is_a?(Numeric)` accepts
+`Integer` and `Float` and narrows accordingly. `instance_of?`
+is stricter — only the exact class — and Rigor narrows
+correspondingly.
+
+The falsey edge subtracts the matched class:
+
+```ruby
+x = some_call_that_returns_integer_or_string
+unless x.is_a?(Integer)
+  # x: String — Integer subtracted
+  x.upcase
+end
+```
+
+## Equality with literal values
+
+Rigor narrows `==` and `!=` against trusted literal values:
+
+```ruby
+state = some_call_returning_a_symbol
+if state == :ready
+  # state: Constant<:ready>
+  send_request
+elsif state == :pending
+  # state: Constant<:pending>
+  retry_in(5)
+end
+```
+
+This is most useful when `state` is itself a union of
+constants (`Constant<:ready> | Constant<:pending> |
+Constant<:failed>`). Each branch peels one member off, and
+Rigor can prove the final `else` is one of the remaining
+constants — not "any Symbol."
+
+## `case` / `when`
+
+`case x; when …` is narrowing-syntax sugar over equality and
+class checks. Each `when` branch sees `x` narrowed to the
+matched member:
+
+```ruby
+case n
+when 0      then :zero        # Constant<0>
+when 1..9   then :small       # int<1, 9>
+when 10     then :ten         # Constant<10>
+else             :large       # everything else
+end
+```
+
+The result type unions the per-branch results. When the input
+is a finite literal union, Rigor proves the `else` branch is
+unreachable when every member is matched.
+
+The same narrowing also works in reverse: when a `when <Class>`
+clause is disjoint from the subject's type, or an earlier
+clause already covered it, the clause is dead — Rigor emits
+[`flow.unreachable-clause`](08-understanding-errors.md) so you
+can delete it. (It ships at `:info` under the default profile.)
+
+`case x; in pattern` (one-line pattern matching) narrows the
+same way for the patterns Rigor understands — class checks,
+literal equality, array / hash structural patterns. The
+clause-reachability check extends to bare-class `in` patterns
+(`in String` / `in MyClass => x`) too.
+
+## Boolean composition
+
+```ruby
+def safe_size(s)
+  if s && !s.empty?
+    # s: non-empty-string
+    s.size
+  end
+end
+```
+
+`&&` chains left-to-right narrowing: the right-hand operand
+is evaluated under the truthy edge of the left. `||` chains
+the falsey edge. `!` swaps the two edges.
+
+This composes with everything else:
+
+```ruby
+if x.is_a?(Integer) && x > 0
+  # x: positive-int
+end
+```
+
+The `is_a?` narrowed `x` to `Integer`, then the integer
+comparison narrowed it further to `int<1, max>`.
+
+## Integer comparisons
+
+`<`, `<=`, `>`, `>=`, plus `Integer#zero?` / `#positive?` /
+`#negative?` / `#nonzero?` / `Comparable#between?`, all narrow
+integer ranges:
+
+```ruby
+def safe_index(arr, n)
+  return :empty if arr.empty?
+  return :out_of_range if n < 0 || n >= arr.size
+  # n: int<0, arr.size - 1>  (in practice: int<0, max>
+  # tightened against `n >= arr.size`)
+  arr.fetch(n)
+end
+```
+
+Range comparisons compose with literals:
+
+```ruby
+n = some_input
+if n.between?(1, 9)
+  # n: int<1, 9>
+end
+```
+
+## Predicate methods on refinements
+
+Rigor recognises a small set of "type-carrier predicate
+methods" — methods whose return type is `bool` and whose
+truthy / falsey edges narrow the receiver:
+
+| Method | Narrows the receiver to |
+| --- | --- |
+| `String#empty?` | `Constant<"">` (truthy) / `non-empty-string` (falsey) |
+| `Array#empty?` | `Constant<[]>` (truthy) / `non-empty-array[T]` (falsey) |
+| `Hash#empty?` | `Constant<{}>` (truthy) / `non-empty-hash[K,V]` (falsey) |
+| `Integer#zero?` | `Constant<0>` (truthy) / `non-zero-int` (falsey) |
+| `Integer#positive?` | `positive-int` (truthy) / `non-positive-int` (falsey) |
+| `Integer#negative?` | `negative-int` (truthy) / `non-negative-int` (falsey) |
+
+Compose these as you would expect:
+
+```ruby
+def first_word(s)
+  return "" if s.empty?
+  # s: non-empty-string
+  s.split.first    # at runtime always returns String,
+                   # never nil — and Rigor knows it
+end
+```
+
+## Hash key-presence narrowing
+
+When you guard on `h.key?(:foo)` (or `has_key?`) and `h` is a
+`HashShape` with `:foo` as an *optional* key, the truthy edge
+promotes that key to *required* — so reading it no longer
+includes `nil` for "key absent":
+
+```ruby
+def port_of(config)
+  # config: HashShape{ host: String, ?port: Integer }  (port optional)
+  if config.key?(:port)
+    # config[:port]: Integer  — the optional key is now required
+    config[:port] + 1
+  else
+    80
+  end
+end
+```
+
+This narrows only concrete `HashShape` carriers, never a
+`Dynamic[T]` hash, and only the truthy edge — a false `key?`
+does not prove much about the other keys.
+
+## Array non-empty narrowing
+
+A bare `arr.empty?` / `arr.any?` / `arr.none?` guard (no block,
+no arguments) refines an `Array[T]` to `non-empty-array[T]` on
+the edge that proves there is at least one element:
+
+```ruby
+def first_or_default(arr)
+  # arr: Array[String]
+  if arr.any?
+    # arr: non-empty-array[String]
+    arr.size      # positive-int — proven at least 1
+    arr.first     # String — Rigor already returns T here
+  else
+    "(empty)"
+  end
+end
+```
+
+`empty?` narrows the *false* edge (the array is NOT empty),
+`any?` / `none?` narrow as you would expect. As with the hash
+form, this fires only on a concrete `Array` carrier — never on
+`Dynamic[T]`, and never on the string / range `empty?` /
+`any?` that look the same syntactically.
+
+## Named-capture regex narrowing
+
+When a regex with named captures matches in the predicate
+position of `if` / `unless`, the captured locals are bound to
+`String | nil` after the match, and narrowed to `String` in
+the truthy branch:
+
+```ruby
+def parse_date(s)
+  if /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/ =~ s
+    # year, month, day: String  (narrowed from String | nil)
+    "#{year}/#{month}/#{day}"
+  else
+    "no match"
+  end
+end
+```
+
+(Narrowing the truthy edge further to specific refinement
+carriers — so `\d{4}` would produce `decimal-int-string` — is a
+demand-driven follow-up on the regex-pattern → refinement-name
+recogniser track; see [`docs/ROADMAP.md`](../ROADMAP.md).)
+
+## Negation and `unless`
+
+Both are mechanical mirrors of their non-negated forms.
+`unless x` is `if !x` for narrowing purposes; `x != y` is
+`!(x == y)`. Rigor swaps the two edges.
+
+## Local rebinding flips the narrowing
+
+A narrowing fact is **scope-local**. The moment you reassign
+the variable, the fact resets:
+
+```ruby
+def example(s)
+  return if s.nil?
+  # s: String
+
+  s = some_other_call    # s rebound — narrowing dropped
+  s.upcase               # s: String? again, depending on
+                         # the call's return type
+end
+```
+
+This is why the engine's narrowing facts are bound to a
+specific scope, not a specific variable name. Rebinding is
+detected; mutation through method calls is not (Rigor does
+not chase mutation).
+
+## What's not narrowed (yet)
+
+A few forms you might expect that Rigor does **not** narrow
+today:
+
+- `respond_to?(:method_name)` records only a non-nil
+  narrowing — a truthy check with a statically-known symbol
+  removes `nil` from the receiver (since `nil` does not
+  respond to most methods) — but it does **not** yet expose a
+  structural "this object responds to that method" capability
+  fact you could dispatch against.
+- `frozen?` and other mutation guards — Rigor does not track
+  mutability as a narrowing fact yet.
+- Open-ended class-comparison via `===` against arbitrary
+  user-defined `case_eq` — only Class / Module / Range /
+  Regexp are recognised.
+- Method-chain receivers in `self`-targeted directives
+  (`get_user.admin?`) — there is no scope binding to narrow
+  against. Local, instance-variable, explicit-`self`, and
+  implicit-self receivers are all supported.
+
+When narrowing is not recognised, both edges share the entry
+scope unchanged — Rigor stays conservative rather than
+making a wrong call.
+
+## Reading a narrowing trace
+
+When you want to see what Rigor narrowed at a point:
+
+```ruby
+def foo(x)
+  if x.is_a?(Integer)
+    dump_type(x)     # emits an info diagnostic at this line
+  end
+end
+```
+
+`dump_type(...)` is the introspection helper. It is a no-op
+at runtime (lives in the `Kernel` extension Rigor's test
+harness uses) and emits a `dump.type` diagnostic naming the
+inferred type. Use it during debugging to confirm a narrowing
+fired.
+
+`assert_type("expected-string", value)` is the stricter
+sibling: it emits a diagnostic when the inferred type does
+NOT match the string. It is what the handbook examples use to
+pin behaviour.
+
+## What's next
+
+Chapter 4 covers the structural carriers — `Tuple` and
+`HashShape` — which behave a lot like a per-element
+narrowing of `Array` and `Hash`.