rigortype 0.2.9 → 0.3.1

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/03-narrowing.md

@@ -275,7 +275,8 @@ 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).)
+recogniser track, tracked as
+[#164](https://github.com/rigortype/rigor/issues/164).)
 
 ## Negation and `unless`
 

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

@@ -221,9 +221,13 @@ 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`.
+The same goes for hashes whose keys are not provably scalar
+literals (symbols, plain strings, integers, floats, `true` /
+`false` / `nil`) — Rigor produces `Hash[K, V]` rather than
+`HashShape`. Within a shape, key identity follows `Hash#eql?`:
+`1` and `1.0` are distinct keys, and a repeated literal key
+keeps the last entry, exactly like the runtime. Non-symbol,
+non-string keys display in hashrocket form (`{ 1 => 2 }`).
 
 ## Deriving new shapes — `pick_of` / `omit_of` / `partial_of` / `required_of` / `readonly_of`
 

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.
@@ -170,8 +170,8 @@ discovery composes uniformly across both shapes.
 
 `Struct.new(*Symbol)` produces a positional-arg constructor
 plus the same accessors as `Data.define`. Rigor folds struct
-member reads too, but — because a `Struct` is mutable — only
-where the value cannot have changed:
+member reads too, and — because a `Struct` is mutable — tracks a
+straight-line setter so the read stays precise:
 
 ```ruby
 Coord = Struct.new(:x, :y)
@@ -181,18 +181,27 @@ c = Coord.new(10, 20)
 assert_type("10", c.x)
 assert_type("20", c.y)
 
-# A local that is mutated, aliased, or escapes is not fold-safe —
-# its reads degrade to Dynamic, never a stale value.
+# A straight-line setter re-types the member; the sibling stays precise.
 m = Coord.new(1, 2)
 m.x = 9
-assert_type("Dynamic[top]", m.x)
+assert_type("9", m.x)
+assert_type("2", m.y)
+
+# A local that is aliased, escapes, or is mutated inside a loop or
+# block is not fold-safe — its reads degrade to Dynamic, never a
+# stale value, because a write Rigor cannot see could have changed it.
+a = Coord.new(1, 2)
+alias_ref = a
+a.x = 9
+assert_type("Dynamic[top]", a.x)
 ```
 
 Because `Struct` accessors are also writers, the fold is gated:
-a member read off a freshly constructed instance (`Coord.new(1,
-2).x`) or a local the analysis proves is never written, aliased,
-or passed away folds to the member's type; anything else widens
-to `Dynamic[top]`. `Data` is read-only, so its reads always fold.
+a member read folds off a freshly constructed instance (`Coord.new(1,
+2).x`), off a local the analysis proves is never written, aliased, or
+passed away, or off one whose only writes are straight-line member
+setters (their assigned type flows into the later read); anything else
+widens to `Dynamic[top]`. `Data` is read-only, so its reads always fold.
 
 ## Inheritance and method resolution
 

data/docs/handbook/07-rbs-and-extended.md

@@ -100,27 +100,24 @@ Rigor sees a tightening.
 
 ## The directive grammar
 
-`RBS::Extended` lives at
+There are seven per-method directives, and they divide by
+*when* the fact they carry becomes true: `return:` and `param:`
+retype the signature itself, `predicate-if-true` /
+`predicate-if-false` narrow a variable across the branches of a
+condition, and `assert` / `assert-if-true` / `assert-if-false`
+narrow one after the call returns. Each is one
+`%a{rigor:v1:…}` annotation above the `def` it refines; they
+stack, and order does not matter.
+
+The exhaustive table — every directive, its payload syntax, and
+what the `<type>` slot accepts (RBS class names, refinement
+payloads, the parameterised and bounded forms, and where `~T`
+negation is and is not allowed) — is
+[manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md#per-method-directives);
+the normative rules for conflicts, merging and provenance are
 [`docs/type-specification/rbs-extended.md`](../type-specification/rbs-extended.md).
-The per-method directives:
-
-| Directive | Says |
-| --- | --- |
-| `%a{rigor:v1:return: <type>}` | Tighten the method's return type. |
-| `%a{rigor:v1:param: <name> is <type>}` | Tighten a parameter's accepted type at the call site, AND narrow the local in the body. |
-| `%a{rigor:v1:assert <name> is <type>}` | After this method returns, the named local in the caller's scope is `<type>`. |
-| `%a{rigor:v1:predicate-if-true <name> is <type>}` | When this method returns truthy, the named local in the caller's scope is `<type>`. (Symmetric `predicate-if-false`.) |
-| `%a{rigor:v1:assert-if-true <name> is <type>}` | When this method returns a truthy value, the named local in the caller's scope is `<type>`. (Symmetric `assert-if-false` for `false` / `nil` returns.) |
-
-The `<type>` slot accepts:
-
-- **RBS class names** — `String`, `Integer`, `::Foo::Bar`.
-- **Imported refinement names** —
-  `non-empty-string`, `lowercase-string`, `numeric-string`,
-  `int<5, 10>`, `non-empty-array[Integer]`, `literal-string`,
-  …
-- **Negation `~T`** — `~lowercase-string` means
-  "non-lowercase-string."
+The rest of this chapter works through the directives one
+example at a time.
 
 ## Refinement names
 
@@ -140,9 +137,8 @@ A short reference:
 ## Declaring conformance — `conforms-to`
 
 The directives above attach to a `def`. One more attaches to a
-`class` / `module` declaration and asserts the whole class
-satisfies a named structural interface, as a checked design
-assertion — whether or not any call site exercises it:
+`class` / `module` declaration and asserts that the whole class
+satisfies a named structural interface:
 
 ```rbs
 %a{rigor:v1:conforms-to _RewindableStream}
@@ -153,13 +149,21 @@ end
 ```
 
 If `MyBuffer` is missing a method the `_RewindableStream`
-interface requires (or the signature is incompatible), Rigor
-reports `rbs_extended.unsatisfied-conformance`; a class that
-satisfies the interface is silent. Multiple `conforms-to`
-directives on one class combine like an intersection of
-interfaces. The directive is purely additive — implicit
-structural compatibility at call sites keeps working with or
-without it.
+interface requires, Rigor reports
+`rbs_extended.unsatisfied-conformance`; a class that satisfies
+the interface is silent.
+
+The reason to reach for this is that Rigor already checks
+structural compatibility *implicitly*, wherever a value flows
+into a position that needs a structural interface — so a class
+nobody currently passes anywhere is never checked at all.
+`conforms-to` turns the contract into a design assertion that
+holds whether or not a call site exercises it, which is what a
+library wants when the structural shape is the point. It is
+purely additive: nothing that type-checked before stops doing
+so because you added it. The stacking and diagnostic semantics
+are in
+[manual — `conforms-to`](../manual/16-rbs-extended-annotations.md#conforms-to--a-checked-structural-contract).
 
 ## Worked example: an assertion gate
 
@@ -181,6 +185,45 @@ end
 The runtime side is whatever `assert_non_empty` does (raise
 on empty, log, ...) — Rigor only reads the directive.
 
+## Worked example: asserting a negative
+
+An assertion payload can be negated with `~T`, which is how you
+model the "this is definitely not nil any more" helper every
+codebase grows:
+
+```rbs
+# sig/asserts.rbs
+class Asserts
+  %a{rigor:v1:assert x is ~nil}
+  def self.not_nil: (untyped x) -> void
+end
+```
+
+```ruby
+# lib/configure.rb
+def configure(maybe)
+  Asserts.not_nil(maybe)
+  # maybe: (~nil), so .upcase resolves on the narrowed type
+  maybe.upcase
+end
+```
+
+The target can also be the receiver itself — name it with
+`self`, and the fact lands on the object the method was called
+on:
+
+```rbs
+class Connection
+  %a{rigor:v1:assert self is Connected}
+  def assert_connected!: () -> void
+end
+```
+
+If PHPDoc's `@phpstan-assert` family is your mental model for
+all of this, the reading is nearly one-for-one; the mapping
+table is in
+[appendix: Coming from PHPStan](appendix-phpstan.md#the-phpstan-assert-family).
+
 ## Worked example: a type predicate
 
 ```rbs
@@ -343,74 +386,6 @@ dynamic boundaries (deserialisation, `eval`, plugin entry
 points). The static analysis you lose is made up by the
 honesty of admitting "this could be anything."
 
-## Coming from PHPStan? The `@phpstan-assert` family
-
-If you are familiar with PHPStan's PHPDoc annotations,
-Rigor's `RBS::Extended` directives map directly onto the
-post-return / conditional narrowing primitives PHPStan calls
-"asserts" and "type-specifying functions." The behaviour is
-identical:
-
-> "After this method returns, the named argument is `T`."
-
-That is `@phpstan-assert` in PHPStan and
-`%a{rigor:v1:assert}` in Rigor.
-
-| PHPStan PHPDoc | Rigor RBS::Extended | Effect |
-| --- | --- | --- |
-| `@phpstan-assert T $x` | `%a{rigor:v1:assert x is T}` | After this method returns normally, the caller's `x` is `T`. |
-| `@phpstan-assert-if-true T $x` | `%a{rigor:v1:predicate-if-true x is T}` | If this method returns truthy, the caller's `x` is `T`. |
-| `@phpstan-assert-if-false T $x` | `%a{rigor:v1:predicate-if-false x is T}` | If this method returns falsey, the caller's `x` is `T`. |
-| `@phpstan-assert !T $x` | `%a{rigor:v1:assert x is ~T}` | After this method returns, the caller's `x` is **not** `T` (negation form). |
-| `@phpstan-assert-if-true !T $x` | `%a{rigor:v1:predicate-if-true x is ~T}` | Conditional negation. Symmetric with `predicate-if-false`. |
-
-Worked example — the canonical "assertNotNull" pattern from
-PHPStan's docs:
-
-```rbs
-# sig/asserts.rbs
-class Asserts
-  %a{rigor:v1:assert x is ~nil}
-  def self.not_nil: (untyped x) -> void
-end
-```
-
-```ruby
-# lib/configure.rb
-def configure(maybe)
-  Asserts.not_nil(maybe)
-  # maybe: (~nil), so .upcase resolves on the narrowed type
-  maybe.upcase
-end
-```
-
-Self-targeted forms are supported too — the PHPStan
-analogue would be a method on `$this` that narrows
-`$this`. Name the receiver with `self`:
-
-```rbs
-class Connection
-  %a{rigor:v1:assert self is Connected}
-  def assert_connected!: () -> void
-end
-```
-
-Rigor's directive grammar covers what PHPStan ships in the
-`@phpstan-assert*` family. The directives **only fire from
-RBS** (per ADR-5: strict on returns, lenient on parameters);
-in PHPStan-land you can also write `@phpstan-assert` in
-PHPDoc directly above the function — Rigor's equivalent is
-the same RBS file's `def` line.
-
-If you need plugin-side equivalents (when the assertion is
-recognised by **call shape** rather than by sig — PHPStan's
-"Type-Specifying Extensions"), see
-[Chapter 9](09-plugins.md). The plugin contract surfaces
-the same `Fact(target_kind: :self)` and
-`Fact(target_kind: :parameter)` carriers that the directives
-use, so a plugin author writes the equivalent of a PHPStan
-`StaticMethodTypeSpecifyingExtension` from Ruby.
-
 ## When RBS cannot help — the plugin escape hatch
 
 When a method's behaviour depends on the **shape of its
@@ -422,6 +397,6 @@ see [Chapter 9](09-plugins.md) and the
 
 ## What's next
 
-Chapter 8 covers the rule catalogue — what each diagnostic
-means, when it fires, and how to suppress it when it is wrong
-or noisy.
+Chapter 8 is about reading a diagnostic — what each rule
+family claims, why one fires when you did not expect it, and
+which layer to reach for when you want it quieter.