rigortype 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11db7e9c0140dbb303b0644587e80cc683e5a9ee32791c007234dd12e37ecb21
-  data.tar.gz: 375cbd7387b2f8cac6d668db993b34e627d19ebacf74e5092c17c8717191b401
+  metadata.gz: a23952ba800fa7d807c8b8acc4d1cfbb3489024d91c3c30d687ebfdb75c7d1f5
+  data.tar.gz: 1a301a820c1c0bd3c2946695ae59f8e00906d1ecebedc0fbfb1fa93da3f6a72a
 SHA512:
-  metadata.gz: 42a9121e67acbf27afc287c586c7b3cd9fbd271a0de9e0a7f28a1e57703ffb578572213402e37f57b7327572c944f799a186ccc0a13dbe1fba49eca02c39df6b
-  data.tar.gz: d5b333586309d0b25b17880608797e005a2083bad60d91e2a20163265cb31b948a08363ef4f37920862dc7ee5da3fb0cd1d7c67a7af6f64b1bc37d8721469f6c
+  metadata.gz: 6574512ee06d1eb87e42f697d7261eac8ecf9bba9ae4a8a4be6263fba188de5b9786babdcef7e9b2cf41ac4877010726d60f66b741af7b5295d6d3e98e5937cb
+  data.tar.gz: d1bcccf23cac521597657aadd2f1c35d7a860998dd3fc8e02a7802c2dc0e9bf23ca3c0e6c368cdb9574cc1ac1e5ff2395f9dd5f164beae13541874d617886b19

data/README.md

@@ -4,20 +4,25 @@
 [![GitHub License](https://img.shields.io/github/license/rigortype/rigor)](https://github.com/rigortype/rigor/blob/master/LICENSE)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/rigortype/rigor)
 
-**Type-aware bug finding for Ruby — zero annotations, and a
-zero-false-positive bar enforced against real codebases.** Run one
-command over the code you already have, and trust every line of
-output.
+**Type-aware bug finding for Ruby — no annotations required, and a
+zero-false-positive bar enforced against real codebases.** Built on
+RBS: Rigor infers types from the values your code produces, reads any
+RBS you write as an authoritative source, and generates more — but
+needs none to start. Run one command over the code you already have,
+and trust every line of output.
 
 ```sh
-gem install rigortype && rigor check app lib
+mise use -g ruby@4.0 gem:rigortype   # install the tool, globally, on Ruby 4.0
+rigor check app lib                  # find bugs in the code you already have
 ```
 
-(The tool itself runs on Ruby 4.0; your project can stay on whatever
-Ruby it targets — see [Get started](#get-started-in-one-prompt).)
+(The tool runs on Ruby 4.0 while your project keeps its own Ruby; the
+global `-g` install keeps it off your project's pins. See
+[Get started](#get-started-in-one-prompt).)
 
-No type annotations to write or maintain, no runtime dependency, no
-changes to your code. Rigor parses Ruby with
+No annotations required, no runtime dependency, no changes to your
+code — and any RBS you do add, Rigor reads and uses. Rigor parses Ruby
+with
 [Prism](https://github.com/ruby/prism) and runs a flow-sensitive
 inference engine that reasons about the *values* your expressions
 produce — not just their classes. It catches undefined methods (and
@@ -106,13 +111,14 @@ Bahasa Indonesia, Polski, Українська, Русский, Română, Türk
 the [installation guide](https://rigor.typedduck.fail/reference/manual/01-installation/#set-up-in-your-language).
 
 **Manual install** — Rigor is a tool, not a library: install it
-independently, **not** in your project's `Gemfile`. It runs on Ruby
-4.0 regardless of which Ruby your project targets
-([`mise`](https://mise.jdx.dev/) provisions both, pinned per project):
+independently, **not** in your project's `Gemfile`. Install it
+**globally** so `rigor` is on your `PATH` everywhere, running on Ruby
+4.0 while each project keeps its own Ruby — the `-g` install lives in
+your global [`mise`](https://mise.jdx.dev/) config and never touches a
+project's pins:
 
 ```sh
-mise use ruby@4.0
-mise use gem:rigortype     # or: gem install rigortype
+mise use -g ruby@4.0 gem:rigortype     # or: gem install rigortype
 ```
 
 The gem is named `rigortype` (the name `rigor` was taken on RubyGems);
@@ -202,6 +208,27 @@ walks the whole type model; the
 and [user manual](https://rigor.typedduck.fail/reference/manual/) are
 the reference companions.
 
+**Stuck on Rigor — or just curious how it works? Ask your agent in
+plain language.** The whole skill surface collapses to two an agent (and
+you) need to remember: **`rigor-next-steps`** ("what should we do
+next?") and **`rigor-ask`** ("answer this about Rigor"). Rigor is niche
+and fast-moving, so a model's *remembered* answer is often stale —
+`rigor-ask` **investigates instead**: it reads Rigor's own handbook and
+manual (bundled in the gem, served **offline** by `rigor docs`, always
+matching your installed version) *and* runs Rigor over your actual code
+(`rigor check` / `annotate` / `type-of`), then answers from what it
+found — citing the page, or the inferred type. Ask *"why is this
+flagged?"*, *"how does narrowing work?"*, *"how is it different from
+Sorbet?"*, *"does it handle Sidekiq?"*, or *"how do I type this
+method?"* — you only have to remember the question, never the command.
+To browse the docs yourself:
+
+```sh
+rigor docs                        # the offline doc index
+rigor docs handbook/03-narrowing  # any handbook or manual page by name
+rigor docs --list                 # list every bundled page
+```
+
 ## Status
 
 Current release: **`v0.2.0`** (2026-06-17) — the first

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

@@ -0,0 +1,311 @@
+# Getting started
+
+By the end of this chapter you will be able to:
+
+- get `rigor` onto your `PATH` (the fast AI-assisted way, or
+  by hand);
+- run `rigor check` and read the diagnostics it prints;
+- understand the "no annotations needed" stance that sets
+  Rigor apart from most checkers, and the escape hatches for
+  when inference falls short.
+
+It is the only chapter you must read top to bottom. The rest
+of the handbook is reference you can dip into later.
+
+## Installing Rigor
+
+Rigor is a tool, not a library — like a linter or a compiler, it
+analyses your project but is not part of its runtime. **Do not add
+it to your application's `Gemfile`.** Install it on its own and
+point it at your project.
+
+Rigor itself runs on Ruby 4.0, independently of the Ruby your own
+code targets. The [`target_ruby:` config key](#the-config-file)
+tells Rigor which Ruby *your* project runs.
+
+### The fast path: let an AI agent set it up
+
+If you work with an AI coding agent (Claude Code or any assistant
+that supports [Agent Skills](https://agentskills.io/)), hand it
+this prompt:
+
+```
+Install Rigor in this project by following the instructions at
+https://raw.githubusercontent.com/rigortype/rigor/refs/heads/master/docs/install.md
+```
+
+The agent detects your environment, installs Rigor, then runs the
+**`rigor-project-init` skill** — which walks your `Gemfile`,
+proposes a plugin set matched to your framework, picks an adoption
+mode, and writes `.rigor.dist.yml` for you. No manual YAML editing.
+This is the recommended path; the [config file](#the-config-file)
+section below shows what the skill produces so you can read and
+tweak it afterwards.
+
+The same prompt is available in sixteen languages in the
+[Rails quickstart](../manual/14-rails-quickstart.md#step-1--install-ruby-40-and-rigor-common-to-both-paths).
+
+### The manual path: mise
+
+If you prefer to drive the setup yourself, the recommended runtime
+version manager is [`mise`](https://mise.jdx.dev/), which
+provisions both Ruby 4.0 and Rigor:
+
+```sh
+mise use ruby@4.0
+mise use gem:rigortype
+```
+
+With mise activated in your shell, `rigor` is on your `PATH`. The
+gem is named `rigortype` (the name `rigor` was taken on RubyGems);
+the executable it installs is `rigor`. If you already have Ruby
+4.0, `gem install rigortype` works too.
+
+For shell activation and shims, `asdf`, and developing inside a
+container, see [Installing Rigor](../manual/01-installation.md);
+for continuous integration, see
+[Running Rigor in CI](../manual/11-ci.md).
+
+## What does `rigor check` look at?
+
+Rigor reads your `.rb` files, runs a flow-sensitive type
+inference engine over each one, consults any `sig/*.rbs`
+declarations available to your project, and reports a small
+catalogue of bugs:
+
+- methods called on the wrong receiver class;
+- methods called with the wrong number of arguments;
+- 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
+  [Chapter 8 — Understanding errors](08-understanding-errors.md).
+
+Rigor does **not** ask you to write type annotations in
+your Ruby source. It infers as much as it can, and stays
+silent everywhere it cannot prove a narrower type.
+A diagnostic only fires when Rigor has enough static
+information to be confident.
+
+## The smallest working session
+
+Drop into your project root and run:
+
+```sh
+rigor check lib
+```
+
+That walks every `.rb` under `lib/`. When the analyzer finds
+nothing to complain about, it prints `No diagnostics` and
+exits `0`:
+
+```text
+No diagnostics
+```
+
+When it does find something, each diagnostic is one line. Given
+this file:
+
+```ruby
+# lib/demo.rb
+"hello".no_such_method        # typo'd method name
+[1, 2, 3].rotate(1, 2)        # too many arguments
+```
+
+`rigor check lib/demo.rb` prints:
+
+```text
+lib/demo.rb:1:9: error: undefined method `no_such_method' for "hello" [call.undefined-method]
+lib/demo.rb:2:11: error: wrong number of arguments to `rotate' on Array (given 2, expected 0..1) [call.wrong-arity]
+```
+
+To run on a single file, pass the file instead of a directory:
+
+```sh
+rigor check path/to/file.rb
+```
+
+And to ask what Rigor inferred at one precise position:
+
+```sh
+rigor type-of lib/foo.rb:10:5
+```
+
+That prints both the rich Rigor type and the conservative
+RBS erasure (the type a non-Rigor RBS tool would see). It is
+the fastest way to ask "what does Rigor think this expression
+produces?"
+
+## Reading a diagnostic
+
+Take the first line from the run above:
+
+```text
+lib/demo.rb:1:9: error: undefined method `no_such_method' for "hello" [call.undefined-method]
+```
+
+| Slice | Meaning |
+| --- | --- |
+| `lib/demo.rb:1:9` | File, 1-indexed line, 1-indexed column |
+| `error` | Severity (`error` / `warning` / `info`) |
+| `undefined method ...` | Human-readable message |
+| `[call.undefined-method]` | The qualified rule identifier |
+
+The qualified rule identifier is the handle you use to silence,
+demote, or look up a rule. The quickest is an in-source comment
+on the offending line:
+
+```ruby
+"hello".no_such_method  # rigor:disable call.undefined-method
+```
+
+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).
+
+## The "no annotations" stance
+
+Most static checkers ask the user to annotate types. Rigor
+does the opposite: it looks at what your Ruby code does and
+**proves** types from the values themselves. Three quick
+examples:
+
+```ruby
+n = 100
+m = n + 1
+assert_type("101", m)     # arithmetic folds
+```
+
+```ruby
+def kind(x)
+  case x
+  when Integer then :int
+  when String  then :str
+  end
+end
+assert_type(":int | :str | nil", kind(7))  # union of all case branches
+```
+
+```ruby
+greeting = "Hello, "                 # Constant<"Hello, ">
+name     = ARGV.first                # String?  (RBS-declared)
+hello    = "#{greeting}#{name}!"     # literal-string carrier:
+                                     # every interpolated part
+                                     # is itself literal-string-
+                                     # compatible, so the result
+                                     # is "provably source-derived"
+```
+
+You did not write a single annotation. Rigor reasons about the
+values directly.
+
+> The `assert_type(...)` line is Rigor's introspection helper,
+> not a runtime check — it pins the inferred type at that point
+> so you can compare the prose to the analyzer's actual output.
+> See [How to read this handbook](README.md#how-to-read-this-handbook)
+> for the full snippet convention.
+
+When inference cannot prove a narrower type, the engine
+returns `Dynamic[top]` (the gradual carrier — "could be any
+Ruby value") and stays silent. Rigor never invents
+diagnostics it cannot prove.
+
+## When inference is not enough
+
+*First read? Skip this section.* Out of the box, inference plus
+any RBS your gems already ship covers most code, and the next
+chapters teach you to read what it produces. Come back here when
+Rigor resolves something to `Dynamic[top]` that you wish it knew
+more about. For most projects only escape hatches (1) and (2)
+ever come up.
+
+There are five escape hatches, in rough order of how often you
+will need them:
+
+1. **Add an `.rbs` file.** Drop a signature into `sig/` and
+   Rigor picks it up automatically. This is the most common
+   reason inference does not see further than the local
+   `def` — by default the analyzer treats every external gem
+   as `Dynamic[top]` unless the gem ships RBS or you
+   opt in to gem-source inference per (4) below.
+2. **Tighten an existing RBS sig with `RBS::Extended`.** Add
+   a `%a{rigor:v1:return: non-empty-string}` annotation
+   above the method's `def ... -> ::String` line. Rigor
+   sees the refinement; ordinary RBS tools see a comment.
+3. **Write a plugin.** When your project has a domain DSL
+   (`Lisp.eval`, `100.kilometers`, `transition_to(:foo)`)
+   that no general-purpose analyzer can know about, a
+   plugin teaches Rigor about it.
+4. **Opt in to gem-source inference.** When a no-RBS gem's
+   methods would otherwise resolve to `Dynamic[top]`, list
+   the gem under `dependencies.source_inference:` in
+   `.rigor.dist.yml` and Rigor will walk its `lib/` the same way
+   it walks project source. Returns are wrapped in
+   `Dynamic[T]` so the call site retains the provenance.
+   See [ADR-10](../adr/10-dependency-source-inference.md)
+   for the trade-offs (per-gem opt-in by design — broad
+   defaults would inflate budgets and make `bundle update`
+   noisy).
+5. **Use the `rigor-sorbet` adapter.** If your project
+   already uses [Sorbet](https://sorbet.org/), Rigor can
+   read your existing `sig { ... }` blocks, RBI files, and
+   `T.let` / `T.cast` / `T.must` / `T.unsafe` assertions
+   as type sources without rewriting anything. See
+   [Chapter 10](10-sorbet.md) for the migration patterns
+   and the translation table.
+
+Chapters 7 and 9 cover (1)–(3) in detail; chapter 10 covers
+(5).
+
+## The config file
+
+The minimum useful run needs no config file at all —
+`rigor check lib` works out of the box. A config file is for
+non-default behaviours: extra `paths`, an alternative
+`severity_profile`, project-wide rule disables, plugins.
+
+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:`.
+
+## What's next
+
+Chapter 2 introduces the carriers Rigor uses to represent
+types — the part of the model that distinguishes Rigor from
+ordinary RBS. After that, Chapter 3 (narrowing) makes the
+carriers come alive: the carriers describe values, and
+narrowing describes how those carriers change as control
+flow passes through `if` / `case` / predicate methods.