rigortype 0.4.0 → 0.4.2

data/docs/install.md

@@ -10,19 +10,42 @@ skill (`rigor-project-init` for a project that has never run Rigor).
 **Do not add Rigor to the project's `Gemfile`** — Rigor is a
 standalone tool, not a library.
 
+**Install the latest release, not whatever is already on the
+machine.** A `rigor` already on PATH, or a version manager that
+resolves to an older release, is not a reason to stop early: Rigor
+changes quickly, and the skills this guide hands off to are written
+for the current release. Step 1 looks up the latest version; Step 2
+installs it and Step 3 checks it.
+
 ---
 
 ## Step 1 — Detect the environment
 
-Run these four checks and note which tools are available:
+Run these checks and note which tools are available:
 
 ```sh
 which mise    # preferred — see Step 2A
 which asdf    # fallback — see Step 2B
 ruby --version 2>/dev/null | head -1   # is Ruby 4.0 already on PATH?
-which docker  # last resort — see Step 2D
+which docker  # last resort — see "Last resort — Docker"
+rigor --version 2>/dev/null            # an existing install, if any
+```
+
+Then look up the latest Rigor release on RubyGems:
+
+```sh
+curl -fsS https://rubygems.org/api/v1/versions/rigortype/latest.json
 ```
 
+It prints `{"version":"X.Y.Z"}`. Below, `<LATEST>` stands for that
+`X.Y.Z`: replace it with the version you got, never type `<LATEST>`
+literally. Without `curl`, `gem search --remote --exact rigortype`
+gives the same answer once Ruby is available. If neither works, tell
+the user you could not determine the latest version instead of
+guessing one.
+
+An existing `rigor` older than `<LATEST>` still goes through Step 2;
+tell the user which version they have and which you are installing.
 Then proceed to the **first** matching case below.
 
 ---
@@ -40,23 +63,51 @@ that can be committed alongside the code. Other contributors — and CI
 — run `mise install` to restore those versions with no `Gemfile`
 involvement.
 
-Run in the project root:
+First ask mise which Rigor version it would pick:
+
+```sh
+mise latest gem:rigortype
+```
+
+If that is older than `<LATEST>`, mise is holding the newer release
+back — usually its `minimum_release_age` quarantine, which hides
+releases for a while after they are published (`mise ls-remote
+gem:rigortype` then warns `1 newer gem:rigortype release hidden by
+minimum_release_age` on stderr). A bare `mise use gem:rigortype`
+would install the older version with no error, so this is the step where agents
+silently end up on a stale Rigor. The quarantine is a supply-chain
+safeguard, so do not bypass it on your own: tell the user both
+versions and ask which to install. `mise settings get
+minimum_release_age` tells you whose choice it is: an error ("not
+set") means mise's built-in default is in effect and you can recommend
+`<LATEST>`; a value means the user configured it, so recommend
+respecting it.
+
+Then run in the project root, with the version the user agreed to:
 
 ```sh
 mise use ruby@4.0
-mise use --pin gem:rigortype
+mise use --pin gem:rigortype@<LATEST>
 ```
 
 `mise use` installs the tools and writes their versions to `mise.toml`
-in one step. Commit `mise.toml` so the version is shared.
+in one step. Commit `mise.toml` so the version is shared. Name the
+version explicitly, as above: an explicit version is installed even
+while the quarantine hides it from `mise latest`.
 
-`--pin` records the exact Rigor version (`"gem:rigortype" = "0.2.9"`).
+`--pin` records the exact Rigor version (`"gem:rigortype" = "X.Y.Z"`).
 Without it mise writes `"gem:rigortype" = "latest"`, which every
 machine re-resolves to whatever is newest when it first installs — so
 a committed `latest` does not give the team one shared version. The
 trade-off: a pin will not move on its own, and `mise outdated` cannot
-report a pinned tool as behind. Upgrade with `mise upgrade --bump
-gem:rigortype`.
+report a pinned tool as behind. Upgrade by running `mise use --pin
+gem:rigortype@<version>` again with the newer version; `mise upgrade
+--bump gem:rigortype` goes through the same quarantine as a bare
+`mise use`.
+
+A user-wide `~/.config/mise/config.toml` entry for `gem:rigortype`
+keeps applying outside this project. Mention it if it names an older
+version, but do not edit global config without the user's consent.
 
 Then verify:
 
@@ -88,7 +139,8 @@ gem is installed with `gem install` after setting the Ruby version.
 ```sh
 asdf install ruby latest:4.0
 asdf local ruby latest:4.0
-gem install rigortype
+gem install rigortype -v <LATEST>
+asdf reshim ruby
 ```
 
 Verify:
@@ -108,7 +160,7 @@ pinning; see <https://mise.jdx.dev/getting-started.html>.
 If `ruby --version` reports `ruby 4.0.*`, install the gem directly:
 
 ```sh
-gem install rigortype
+gem install rigortype -v <LATEST>
 ```
 
 Verify:
@@ -152,6 +204,11 @@ and does not integrate well with editor LSP. Use it only when a
 host-side Ruby 4.0 is genuinely unavailable (for example, Windows
 without WSL). For all other environments, prefer Case A–D above.
 
+With Docker there is no `rigor` on the host PATH, so Step 3 checks the
+image instead: `docker run --rm ghcr.io/rigortype/rigor:latest rigor
+--version`. The image can trail RubyGems by a release; report its
+version to the user rather than treating a mismatch as a failure.
+
 ---
 
 ## Step 3 — Verify the installation
@@ -160,8 +217,23 @@ without WSL). For all other environments, prefer Case A–D above.
 rigor --version
 ```
 
-A version string like `rigor 0.2.x` confirms a successful install.
-If the command is not found, revisit Step 2 for your case.
+The reported version should be the one you installed in Step 2
+(normally `<LATEST>`). If it is older, you are running a different
+`rigor` than the one just installed. With mise, first check what the
+project resolves to:
+
+```sh
+mise exec -- rigor --version
+mise which rigor
+```
+
+If `mise exec` reports the new version, the shell's PATH is stale (a
+non-interactive shell does not re-run mise's activation after `mise
+use`); run `eval "$(mise hook-env)"`, or use `mise exec -- rigor` for
+the remaining steps. Otherwise run `which -a rigor` to find the older
+install. Do not uninstall anything to fix this without asking, and do
+not continue on the older version without telling the user. If the
+command is not found, revisit Step 2 for your case.
 
 ---
 
@@ -192,6 +264,6 @@ project is set up, re-run `rigor skill describe` for the step after
 that.
 
 If `rigor skill describe` is not recognised, your Rigor version predates
-it. Run `rigor --version` and upgrade with `mise upgrade --bump
-gem:rigortype` (or `gem update rigortype` for Case B/C); on an older
-version, run `rigor skill rigor-project-init` directly.
+it: you are not on the version Step 1 found. Go back to Step 3. If
+you are staying on an older version with the user's agreement, run
+`rigor skill rigor-project-init` directly.

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

@@ -34,8 +34,8 @@ the `paths:` list from the configuration file.
 | `--format=FORMAT` | Output format. Default `text`. Also `json` (structured stream), plus the CI-native renderings `sarif`, `github`, `gitlab`, `checkstyle`, `junit`, and `teamcity` — see [Running Rigor in CI](11-ci.md). |
 | `--no-ci-detect` | Disable CI auto-detection — by default `text` output also emits the running CI's native annotations / hint (`RIGOR_CI_DETECT=0` does the same). See [Running Rigor in CI § auto-detection](11-ci.md). |
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
-| `--no-cache` | Skip the persistent cache for this run. |
-| `--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. See [Caching](12-caching.md). |
+| `--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. |
 | `--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. |

data/docs/manual/03-configuration.md

@@ -21,6 +21,11 @@ discovery entirely.
 
 All relative paths in a config file resolve against that
 file's own directory.
+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
+`rbs_collection.lockfile:`. It does not apply to `cache.path:`, `baseline:` or `effects.snapshot.path:`, which stay
+literal and relative to the working directory.
 
 ## Editor validation
 
@@ -57,7 +62,7 @@ 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. |
 | `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. |

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 |

data/docs/manual/06-baseline.md

@@ -77,6 +77,8 @@ a diagnostic another layer has already suppressed.
 | `rigor baseline drift` | Show how buckets have moved — `--only=over` for buckets that grew, `reducible` for ones you have already improved past, `cleared` for empty ones. |
 | `rigor baseline prune` | Drop buckets that match nothing any more. `--dry-run` previews. |
 
+`generate` and `regenerate` analyse with your loaded configuration unchanged except that `baseline:` is off, so options such as `bleeding_edge`, `target_ruby` or `severity_overrides` shape the recorded set exactly as they shape `rigor check`.
+
 `generate` and `regenerate` take `--match-mode=rule` (the
 default — one bucket per file × rule) or `--match-mode=message`
 (a bucket per distinct message: more precise, more churn).

data/docs/manual/07-plugins.md

@@ -54,7 +54,7 @@ each plugin's options — but the families today are:
   `rigor-ffi` provides the `ffi_binding_recognizer` class DSL on
   `Rigor::Plugin::Base` to recognize custom binding definitions.
 - **Other ecosystems** — `rigor-sinatra`, `rigor-hanami`,
-  `rigor-devise`, `rigor-pundit`, `rigor-sidekiq`,
+  `rigor-devise`, `rigor-pundit`, `rigor-alba`, `rigor-typelizer`, `rigor-sidekiq`,
   `rigor-graphql`, `rigor-statesman`, `rigor-sorbet`,
   `rigor-typescript-utility-types`,
   `rigor-activesupport-core-ext`.

data/docs/manual/08-skills.md

@@ -60,9 +60,10 @@ is not repeated here.)
 - **`rigor-project-init`** — onboards a project from a cold start. It
   detects the stack (Rails, RSpec, dry-rb, …), proposes the matching
   [plugins](07-plugins.md), picks an adoption mode — a
-  [baseline](06-baseline.md) snapshot for an existing codebase or a
-  zero-diagnostic gate for a clean one — writes a `.rigor.dist.yml`, and
-  generates the first baseline. Reach for it when setting Rigor up for
+  [baseline](06-baseline.md) snapshot by default, new projects
+  included, or an opt-in zero-diagnostic gate for users fluent in type
+  theory and RBS — writes a `.rigor.dist.yml`, and generates the first
+  baseline. Reach for it when setting Rigor up for
   the first time.
 - **`rigor-rbs-setup`** — installs community RBS for your gems
   (`rbs collection install`) so RBS-less dependencies stop typing as

data/docs/manual/12-caching.md

@@ -135,7 +135,7 @@ CI detection that `auto` relies on.
 
 | Flag | Effect |
 | --- | --- |
-| `rigor check --no-cache` | Run without reading or writing the persistent cache. |
+| `rigor check --no-cache` | Run without reading or writing the persistent cache. With `--incremental` this includes the snapshot: every file is analysed and the snapshot on disk is left untouched. |
 | `rigor check --clear-cache` | Delete the cache directory, then run. |
 | `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes (on stderr under every `--format` but `text`, so the document on stdout stays parseable). |
 | `rigor check --incremental` | Re-analyse only what changed; serve the rest from the incremental snapshot (see below). |
@@ -144,9 +144,12 @@ There is no config key to disable caching permanently — the
 flags are per-run toggles. To run without a persistent cache
 habitually, point `cache.path` at a disposable directory.
 
+With `--incremental --no-cache` and an editor buffer (`--tmp-file` with `--instead-of`), the buffer is analysed on its own, as it is when no snapshot exists, and the note says that `--no-cache` skipped the snapshot rather than suggesting `rigor check --incremental`.
+
 ## Size and eviction
 
-A project's active cache set is small (around 2 MB). Entries
+A project's active cache set is a few megabytes (about 10 MB
+for a Rails application the size of Mastodon). Entries
 are content-keyed, so events like a gem upgrade or an `.rbs`
 edit write fresh entries and leave the old ones *orphaned* —
 nothing references them, and no run would otherwise delete
@@ -219,9 +222,45 @@ dependents of removed ones.) As with the rest of the cache, a
 missing or corrupt snapshot is simply a full run; it can never
 wedge analysis.
 
+When nothing has changed since the last `--incremental` run, the
+answer comes straight from the cache, without starting the
+analyzer at all. Rigor first checks the inputs that answer was
+computed from — your source files and view templates, your RBS,
+your configuration and the files your plugins read — and runs the
+ordinary incremental re-check the moment any of them differs. On
+a Rails application the size of Mastodon, an unchanged
+`--incremental` run takes about a quarter of a second. An
+unchanged plain `rigor check` skips the analyzer the same way,
+except when a plugin compiles your view templates, as
+rigor-actionpack does.
+
+The shortcut stands aside under `--workers=N` (or
+`parallel.workers:`), `--explain`, `--cache-stats`, `--coverage`,
+an editor buffer, and an `effects:` block, and when the cache
+directory is on a different filesystem from the project; those
+runs re-check as before. It also switches itself off, silently:
+
+- when an input changes that the ordinary re-check does not look
+  at itself: an auto-detected `sig/` directory (one you did not
+  list under `signature_paths:`), a file a narrower
+  `rigor check --incremental DIR` only discovers from the rest of
+  your configured `paths:`, or a `pre_eval:` file outside the
+  analysed paths. The re-check may keep printing the answer from
+  before that change; the shortcut does not repeat it;
+- when an `--incremental` run cannot record its answer safely:
+  after a run with `--workers=N` that re-analysed files, when a file or directory changes while a run is reading
+  it, after a CI cache is restored onto a fresh checkout, or when
+  two runs race.
+
+Either way it stays off, and every run is an ordinary re-check,
+until the next full analysis. The ordinary re-check never starts
+one by itself: only a configuration, `Gemfile.lock` or Rigor
+version change does, or `--clear-cache`. So the shortcut can stay
+off indefinitely; run `rigor check --incremental --clear-cache`
+once to turn it back on.
+
 `--incremental` is most useful for fast local re-checks and CI
-on a changed branch. For a one-shot run on an unchanged project,
-the ordinary cache already serves the whole result in one step.
+on a changed branch.
 
 ## Concurrency
 

data/docs/manual/14-rails-quickstart.md

@@ -90,8 +90,9 @@ It runs eight phases in order:
 2. **Choose an adoption mode** — proposes either *acknowledge*
    (snapshot today's diagnostics into a baseline; catch
    regressions going forward) or *strict* (drive the project to
-   zero and keep it there). It recommends acknowledge for
-   codebases with more than ~100 initial diagnostics.
+   zero and keep it there). It recommends acknowledge for every
+   project, new ones included; strict is an opt-in for users
+   fluent in type theory and RBS.
 3. **Select plugins** — proposes the plugin set matching your
    detected stack; you confirm or trim the list.
 4. **Write `.rigor.dist.yml`** — the committed shared config,
@@ -151,14 +152,19 @@ source-of-truth copy is
 
 | Mode | When | What happens |
 | --- | --- | --- |
-| **Acknowledge** | Existing codebase with many diagnostics | Record today's diagnostics in a baseline; surface only new ones on each PR. |
-| **Strict** | New or small project | Zero outstanding diagnostics; no baseline. |
+| **Acknowledge** | Recommended for every project, new ones included | Record today's diagnostics in a baseline; surface only new ones on each PR. |
+| **Strict** | Opt-in, for users fluent in type theory and RBS | Zero outstanding diagnostics; no baseline. |
 
-If your first `rigor check` reports more than ~100 diagnostics,
-acknowledge mode is the natural starting point. You can tighten
-it later. In `.rigor.dist.yml` (Step 3) the mode maps to a
-`severity_profile:` — acknowledge → `lenient`, strict → `strict`
-(omit the key for the default `balanced`).
+Start with acknowledge mode even on a brand-new project. Rigor's
+inference still has gaps, so a zero-diagnostic gate meets
+diagnostics on correct code, and clearing those means fixing
+signatures or RBS rather than your code. Choose strict only if
+you are comfortable doing that yourself. You can tighten later.
+
+In `.rigor.dist.yml` (Step 3) the mode maps to a
+`severity_profile:`. Acknowledge mode uses the default `balanced`
+(omit the key), or `lenient` when the first `rigor check` reports
+more than ~100 diagnostics; strict mode uses `strict`.
 
 ### Step 3 — Write .rigor.dist.yml
 
@@ -198,7 +204,7 @@ plugins:
   - rigor-rspec
   - rigor-factorybot
 
-severity_profile: lenient   # "strict" for strict mode; omit for "balanced"
+# severity_profile: lenient   # only for >100 initial diagnostics; "strict" for strict mode
 
 # baseline: .rigor-baseline.yml   # uncomment after Step 6 (acknowledge mode only)
 ```
@@ -288,7 +294,9 @@ first, then large clusters to record in a baseline.
 
 ### Step 6 — Generate a baseline (acknowledge mode)
 
-*Skip this step if you chose strict mode.*
+*Skip this step if you chose strict mode.* Settle `severity_profile:`
+first: changing it afterwards changes which rules fire and leaves the
+baseline out of step.
 
 ```sh
 rigor baseline generate

data/docs/manual/18-removing-dead-code.md

@@ -145,7 +145,7 @@ Four sections, needing four different decisions:
 | **Reachable only from test code** | Live test, no production caller Rigor can see or suspect | Work these first |
 | **Candidates** | Nothing reachable names it | Adjudicate — most are still live |
 | **Cannot decide** | Something can name it at runtime | Read the reason; do not delete from here |
-| **Namespace-only** | A module wrapping live code | Excluded from candidates; count only |
+| **Namespace-only** | A module wrapping code production reaches | Excluded from candidates; count only |
 
 Work them in that order — which is not the order you *read* the
 summary in, where `roots` comes first because it tells you whether to
@@ -162,6 +162,12 @@ section held 22 policy classes whose only remaining caller was
 `spec/policies/`. Those 22 were not adjudicated, so treat the section
 as high-signal rather than high-yield; the yield is unmeasured.
 
+"Test code" is decided by path, relative to the directory you run `rigor unused` in (run it from the
+project root): `spec/` and `test/` anywhere below it, `*_spec.rb` and `*_test.rb`, and the end-to-end
+trees `qa/`, `e2e/` and `features/` at that root. Tooling directories such as
+`rubocop/`, `keeps/`, `tooling/` and `scripts/` count as production, so a class used only by them is
+rooted rather than listed: deleting it would break the tooling.
+
 ### Candidates: sort by how conventional the class is
 
 A candidate row is its name and declaration site:
@@ -171,6 +177,23 @@ Candidates — nothing reachable references these (45)
     1  Api::V1::Timelines::TopicController   app/controllers/api/v1/timelines/topic_controller.rb:3
 ```
 
+A base class is reachable whenever one of its subclasses is:
+`class Sub < Base` names `Base` on `Sub`'s behalf. So a base class
+that nothing else names appears together with its subclasses when none
+of them is reachable, and the decision belongs to the whole family
+rather than to one row. When a subclass sits under **Cannot decide**,
+its base moves there too.
+
+A class declared outside `paths:` — `config/application.rb`'s
+`Application`, a class in an initializer, a spec helper — is not
+itself in the report, so what it names counts as named from its file:
+`config.middleware.use MyMw` keeps `MyMw` live, and a fake subclass in
+`spec/support` keeps its base reachable from tests. The same holds for
+a gem class you reopen inside `paths:`. A name the file declares
+itself still means that declaration: a migration's local
+`class LegacyThing < ActiveRecord::Base` stub does not keep the app's
+`LegacyThing` model live.
+
 The 53 false positives in the adjudicated run fell into a few recurring
 shapes, and 28 of them were the first one. Recognising these lets you
 skip most of a list quickly:
@@ -230,7 +253,14 @@ belongs here instead, with the file named.
 
 `"Foo".constantize` names `Foo` exactly, so it counts as an ordinary
 reference and never reaches this section. `"Foo::#{key}".constantize`
-can only bound the namespace, so everything under `Foo` is demoted. A
+can only bound the namespace, so everything under `Foo` is demoted;
+`"V#{version}"` is the start of a name, so `V1`, `V2_0` and everything
+under them are. `const_get` looks the name up from its receiver, so
+`const_get("V#{version}")` inside `class Migration` demotes
+`Migration::V1` — and the top-level `V*` names as well, unless the call
+passes `false` as its second argument. A name built into a local
+variable first (`name = "V#{version}"; const_get(name)`) is read the
+same way. A
 class name appearing as a string in a `.yml`, `.json` or template file
 demotes the same way — weaker evidence than a constant reference, and
 neither proof of use nor grounds to call it dead.

data/docs/manual/plugins/README.md

@@ -14,7 +14,8 @@ The full catalogue, with a one-line scope for every plugin, is
 ## Available pages
 
 - [rigor-activerecord](rigor-activerecord.md) — ActiveRecord
-  finder / relation typing and schema-checked columns.
+  finder / relation typing and schema-checked columns; roots models reached only through an
+  association for `rigor unused`.
 - [rigor-rails-routes](rigor-rails-routes.md) — `*_path` / `*_url`
   helper validation against a parsed `config/routes.rb`.
 - [rigor-rails-i18n](rigor-rails-i18n.md) — `t(...)` / `I18n.t(...)`
@@ -69,6 +70,10 @@ The full catalogue, with a one-line scope for every plugin, is
   (`params`, `namespace`, verb macros, `desc`, `route_setting`) and
   `Grape::Entity` `expose` declarations, including the `instance_eval`'d
   block `self` bindings.
+- [rigor-alba](rigor-alba.md) — types the inline `Alba.serialize { }` block `self`, and
+  roots the resources alba infers from `many :articles` for `rigor unused`.
+- [rigor-typelizer](rigor-typelizer.md) — roots the serializer classes typelizer generates TypeScript
+  interfaces from, for `rigor unused`.
 - [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
   argument validation (out-of-range codes, unknown status symbols).
 - [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher

data/docs/manual/plugins/rigor-activerecord.md

@@ -228,6 +228,27 @@ member left out stays lenient rather than reported.
 `ActiveRecord::Base` is deliberately **not** declared: closing it would
 close every model in the project.
 
+## Roots for `rigor unused`
+
+```ruby
+class Recipe < ApplicationRecord
+  belongs_to :user                              # ActiveRecord loads User
+  has_many :comments, as: :commentable          # ... and Comment
+  has_many :tags, through: :taggings            # no root of its own, see below
+  belongs_to :owner, polymorphic: true          # no single target: no root
+end
+```
+
+`User` and `Comment` are named nowhere in the source, so [`rigor unused`](../02-cli-reference.md#rigor-unused) would list a model reached only this way. The plugin publishes the class each association resolves to as a `:reachability_roots` fact, mirroring ActiveRecord's own lookup:
+
+- a literal `class_name:` (String or Symbol, or a rooted `"::Foo"`) wins;
+- otherwise `has_many` / `has_and_belongs_to_many` use the singularized, camelized name and `belongs_to` / `has_one` the camelized name;
+- the name is tried as nested in the owner itself (`Post` looks for `Post::Comment`), then in the owner's enclosing namespaces innermost first (`Admin::Recipe` looks for `Admin::User`), then at top level. If a candidate is not a model but is a namespace of one, nothing is rooted, since ActiveRecord would pick that module.
+
+A root is published only when the project declares a model of that name. Nothing is published for a `polymorphic: true` association, a non-literal `class_name:` or `**options`, or a `through:` association without a literal `class_name:` / `source_type:` (a literal `source_type:` names the class; otherwise its target is the source association's, and that association roots it). Associations written inside `class << self`, a `def` or a block other than `with_options` are not seen, and neither is the block-parameter form `with_options(...) do |o| o.belongs_to :x end`. Literal options of a `with_options` group are merged into the associations inside it, the innermost group winning as in Rails; a group with non-literal options (`with_options opts do`) is skipped, as is `anonymous_class:`, an association whose own options hide the class (a `**splat`, an options variable, a non-literal `class_name:`), and a computed name equal to the owner's own name (Rails 7.2+ tries the top-level class first). The merged options also decide the association reader's type: `with_options optional: true` makes `belongs_to` readers nilable, and `class_name:` and `polymorphic:` set the target or make it `Dynamic`. The name is inflected with the real `ActiveSupport::Inflector`; if it cannot be loaded the plugin publishes nothing.
+
+The roots are flat: an association on a model `rigor unused` itself reports as dead still roots its target, so a chain of dead models can leave the last one unlisted. Project-custom inflections are not read, so a model whose name relies on one is under-rooted rather than wrongly rooted. The roots are published in reduced mode too, since they do not depend on the schema.
+
 ## Limitations
 
 - **Direct-superclass match only.** `class Admin < User` where

data/docs/manual/plugins/rigor-alba.md

@@ -0,0 +1,60 @@
+# rigor-alba
+
+Teaches Rigor about the [alba](https://github.com/okuramasafumi/alba) JSON serializer. alba does not ship its
+RBS in the gem, so without this plugin every alba call in your project reads `Dynamic[top]`. The plugin only
+removes false diagnostics and publishes `rigor unused` roots; it adds no diagnostic and no return type.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-alba
+```
+
+## What it does
+
+```ruby
+# Inline resources: the block runs on an anonymous Alba::Resource class, so `attributes` and friends resolve
+# instead of firing call.unresolved-toplevel.
+json = Alba.serialize(user) { attributes :id, :name }
+hash = Alba.hashify(user) { attributes :id }
+```
+
+The plugin contributes no return types: `Alba.serialize(obj)` runs your own `<Class>Resource#serialize`, which
+you may override to return anything.
+
+The block may sit anywhere a value can: `render json: Alba.serialize(x) { ... }` resolves the same as an
+assignment.
+
+## Roots for `rigor unused`
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  many :articles                               # alba loads ArticleResource, then ArticleSerializer
+  one :editor, resource: EditorResource        # explicit: nothing inferred
+end
+```
+
+`ArticleResource` appears nowhere in the source, so `rigor unused` would list it. The plugin publishes it as a
+root. It does so only for an association that gives no `resource:` / `serializer:`, no second argument and no
+block, and only when a class of the inferred name exists in the project (nesting-aware: inside `module Admin`
+alba tries `Admin::ArticleResource` first). The name is classified with the real `ActiveSupport::Inflector`;
+if it cannot be loaded the plugin publishes nothing.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-alba
+    config:
+      resource_search_paths: ["app"]   # default
+```
+
+`resource_search_paths` is where the plugin looks for resource classes. Widen it if your resources live
+outside `app/`.
+
+## More
+
+Internals and the known limits: [plugins/rigor-alba/README.md](../../../plugins/rigor-alba/README.md).

data/docs/manual/plugins/rigor-minitest.md

@@ -44,18 +44,36 @@ their `refute_*` equivalents.
 | --- | --- |
 | `assert_kind_of(T, x)` / `assert_instance_of(T, x)` | narrow to `T` |
 | `assert_nil(x)` | narrow to `Constant<nil>` |
-| `assert_equal(literal, x)` | narrow to `Constant<literal>` |
+| `assert_equal(literal, x)` | meet with `Constant<literal>` (see below) |
 | `assert_match(regex, x)` | narrow to `String` |
 | `refute_kind_of` / `refute_instance_of` (+ `assert_not_*`) | narrow away from `T` |
 | `refute_nil(x)` / `assert_not_nil(x)` | narrow away from nil |
-| `refute_equal(literal, x)` / `assert_not_equal(...)` | narrow away from `Constant<literal>` |
+| `refute_equal(literal, x)` / `assert_not_equal(...)` | unchanged |
 | `_(x).must_be_kind_of(T)` / `must_be_a(T)` / `must_be_instance_of(T)` / `must_be_an_instance_of(T)` | narrow to `T` |
 | `_(x).must_be_nil` | narrow to `Constant<nil>` |
-| `_(x).must_equal(literal)` | narrow to `Constant<literal>` |
+| `_(x).must_equal(literal)` | meet with `Constant<literal>` (see below) |
 | `_(x).must_match(regex)` | narrow to `String` |
 | `_(x).wont_be_kind_of(T)` / `wont_be_instance_of(T)` | narrow away from `T` |
 | `_(x).wont_be_nil` | narrow away from nil |
-| `_(x).wont_equal(literal)` | narrow away from `Constant<literal>` |
+| `_(x).wont_equal(literal)` | unchanged |
+
+### Equality is not identity
+
+`assert_equal(literal, x)` and `_(x).must_equal(literal)` pass when
+`literal == x`, and `==` can hold across classes: `1 == 1.0`,
+`1 == 1r`, and a class with its own `==` (a `ModInt` that compares
+`to_i`) passes `assert_equal 9, m`. The assertion therefore never
+replaces `x`'s type:
+
+- a `nil`, `true`, `false`, or Symbol literal has identity `==`, so `x`
+  narrows to that literal whatever its type was;
+- an Integer, Float, or String literal narrows `x` only when every
+  member of `x`'s type is already of the literal's class (or a `nil`,
+  boolean, or Symbol the literal cannot equal). After
+  `x = rand(10); assert_equal 9, x`, `x` is `9`;
+- otherwise — `x` is `Dynamic`, of a user class, or of another numeric
+  class (`assert_equal 9.0, x` with an Integer `x`), or the literal is
+  `0.0`, which `-0.0` also equals — `x` keeps its type.
 
 ## No diagnostics, no config