rigortype 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a812e377e347e70448e42c33e6f4fe79152d40851b999609e9e5fdd98dc5a5a0
-  data.tar.gz: 285b195c8058fa30063c5ad40ac6718cd59a3f1d79bb79ccac32184093dba5b0
+  metadata.gz: a09068aa2810a8d01758e3ce78f52dc6020f0d197bb83a561684b96969e5eddf
+  data.tar.gz: 0105753f063477bea3a85ba3dea3fe660fbe58d846d9388867eafd3b6fed1055
 SHA512:
-  metadata.gz: 148890acd58affcbc6eb81afe948d882cf254930ff7ad83635592a065bf038de149865891767318721bdc103e7def6e4c71686b8d40a8ff9b55034c446cf8d32
-  data.tar.gz: e6d458ec387e004c83b8751e5381eda53ec5979433580263ea1586cbb574245875f50a94fce86540badae485d08d20ff73c7e3aea4d80d33c4226af3a4b7f584
+  metadata.gz: fb111fc503dbb60810cbcdf4bfb0a717f694f771fe16bf41007ef1b9eb2728014aa19d112183e79652e4a1ae03c09d6e227ad13ebc063a9804b7a6ba916ae71b
+  data.tar.gz: 4c3d925ef588248fbd84529262632bcfa5e081eedd340c164f0de89b3a0f83abd5cdaad37be922a90571068966ec204f77e075993994db8b106abbaa8d135cd8

data/README.md

@@ -232,7 +232,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.2`** (2026-10-11) — on the
+Current release: **`v0.4.4`** (2026-10-16) — on the
 `0.4.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a

data/data/core_overlay/ostruct.rbs

@@ -0,0 +1,40 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- OpenStruct#method_missing (issue #1456) ---
+#
+# rbs 4.2 ships no `ostruct` signatures (since Ruby 4.0 `ostruct` is a bundled
+# gem, not a default one), and the gem ships no `sig/`. The only `OpenStruct`
+# declaration in the environment is json's add-on reopening in
+# `stdlib/json/0/json.rbs` (`json_create` / `as_json` / `to_json`), so the
+# class read as fully declared and `OpenStruct.new(name: "x").name` reported
+# `call.undefined-method`.
+#
+# Upstream: ostruct 0.6.3 `lib/ostruct.rb` defines each field as a
+# per-instance singleton method (`new_ostruct_member!` through
+# `define_singleton_method!`) and answers the rest through
+# `private def method_missing(mid, *args)`, which this file declares. It
+# defines no `respond_to_missing?` of its own (Kernel's answers, and the
+# fields are real singleton methods), so none is declared here.
+#
+# The per-field accessors cannot be declared on the class at all, so
+# `Rigor::Analysis::CheckRules::CORE_OVERLAY_OPEN_RECEIVERS` names
+# `OpenStruct` as an open receiver: an RBS `method_missing` alone does not
+# stop the undefined-method rule. That list is what quiets `rigor check`;
+# this file supplies the declaration the maintainer decision asked for.
+#
+# The declaration sits on a module the class includes, as `process.rbs`
+# does, so a project `sig/` that declares `OpenStruct#method_missing` itself
+# overrides it instead of raising `DuplicatedMethodDefinitionError`.
+#
+# Maintainer decision on #1456 (2026-10-16, option c): this narrow overlay.
+# The general rule for a class declared only by another library's partial
+# reopening is #1978.
+module RigorCoreOverlay
+  module OpenStructMissing
+    private def method_missing: (Symbol mid, *untyped args) -> untyped
+  end
+end
+
+class OpenStruct
+  include RigorCoreOverlay::OpenStructMissing
+end

data/docs/handbook/11-sig-gen.md

@@ -188,11 +188,11 @@ changes which calls the signature accepts:
 $ rigor sig-gen --diff lib/c.rb
 --- lib/c.rb: C#m
 - def m: (Integer x) -> untyped
-+ def m: (Integer x) -> nil
++ def m: (Integer x) -> Float
 
 --- lib/c.rb: C#n
 - def n: (?) -> untyped
-+ def n: (?) -> nil
++ def n: (?) -> Float
 ```
 
 The `-` line is the declaration the proposal replaces. A method
@@ -523,9 +523,16 @@ Neither does a declaration the body proves as a literal.
 -> String` whose body is the string `"bot"`: the declared
 type is your abstraction over that body, and pinning the
 literal would rewrite a contract every sibling class shares.
-A method no `.rbs` declares is unaffected — the literal is
-still the strictest thing the body proves, and that is what
-gets written.
+A declared `untyped` that you wrote in `sig/` is treated
+the same way for a value literal: an Integer, String or
+Symbol the body proves is widened to its class (`-> 1`
+becomes `-> Integer`, `-> ("S" | nil)` becomes
+`-> (String | nil)`), while `nil`, `true`, `false` and a
+computed `Float` are proposed as they are. An `untyped` that
+only the inline reader synthesizes for a `def` you did not
+annotate keeps the literal, as does a method no `.rbs`
+declares — the literal is still the strictest thing the body
+proves, and that is what gets written.
 
 A comment rather than a `%a{…}` annotation, for three
 reasons: it stays out of the `rigor:v1:` directive namespace
@@ -744,6 +751,22 @@ by side without coordination.
   every other byte of the file verbatim.
 - **Will** append a new `class Foo … end` block when the
   target file does not declare the class yet.
+- **Will** treat a method as already declared when a file
+  under the signature tree declares it on the same class
+  with a `def` or an `attr_*` of the same kind (instance or
+  singleton), in any opening of the class in that file. A
+  `def self?.` declares both kinds, and a `def self?.`
+  proposal counts as declared when either kind is. The
+  method is updated (`--overwrite`) or skipped in the file
+  that declares it instead of being added to the class's
+  first file. A replacement lands only on a `def` of the
+  proposal's own kind in the first opening of the class:
+  a `def self?.` proposal over a lone `def self.f` or
+  `def f`, a plain proposal over a `def self?.f`, or a
+  method declared in a later opening is skipped. A
+  `def f: ... | ...` overload is never replaced and never
+  counts as the file that declares `f`. An `alias` in
+  `sig/` is not yet recognised as declaring its name.
 - **Will not** touch files outside the configured signature
   tree.
 - **Will not** replace an existing method declaration

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

@@ -36,7 +36,7 @@ the `paths:` list from the configuration file.
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
 | `--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. |
+| `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics agree as a set and in the same order, then exit (0 on match, 1 on mismatch: the differing diagnostics for a set mismatch, or the first index where the order diverges for a same-set, different-order 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. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
@@ -171,6 +171,24 @@ the two builds against each other — but if you are chasing a
 disagreement between a probe and a `check` run, comparing
 against `rigor check --no-cache` removes that variable.
 
+## `rigor lens`
+
+Map the declarations of one or more files with their types and
+type provenance (experimental). See
+[Inspecting inferred types](05-inspecting-types.md).
+
+```sh
+rigor lens [--format=text|json] [--config=PATH] [--workers=N] FILE...
+```
+
+A lens runs the same incremental analysis as
+`rigor check --incremental` and reads and writes its cache.
+`--workers` applies to a cold run. `--format=json` writes one
+`lens/v0` document ([specification](../internal-spec/lens.md)).
+Exit `0` when at least one file has a result, `1` when none
+does, `64` on a usage error; diagnostics in the code never
+change the exit status.
+
 ## `rigor trace`
 
 Replay HOW the engine typed a file, step by step, as a
@@ -895,10 +913,11 @@ rigor mcp [--transport=stdio] [--config=PATH]
 ```
 
 `stdio` is the only transport. The server is a pure-Ruby
-JSON-RPC 2.0 implementation exposing seven read-only tools:
-`rigor_check`, `rigor_type_of`, `rigor_triage`,
+JSON-RPC 2.0 implementation exposing eight read-only tools:
+`rigor_check`, `rigor_type_of`, `rigor_triage`, `rigor_lens`,
 `rigor_annotate`, `rigor_sig_gen`, `rigor_explain`,
-`rigor_coverage`.
+`rigor_coverage`. `rigor_lens` writes only the incremental
+cache `rigor check --incremental` writes.
 
 ## `rigor lsp` vs `rigor mcp`
 

data/docs/manual/03-configuration.md

@@ -19,8 +19,10 @@ To *layer* configs rather than replace, a config file can name
 a base with `includes:` (recursive). `--config=PATH` bypasses
 discovery entirely.
 
-All relative paths in a config file resolve against that
-file's own directory.
+Relative paths in a config file resolve against that file's own directory, with three exceptions:
+`bundler.bundle_path:`, `bundler.lockfile:` and `rbs_collection.lockfile:` resolve against the working directory
+`rigor` runs from. They match only when you run `rigor` from the directory that holds the config file, which is
+the usual case; with `--config path/to/.rigor.yml` from elsewhere, give these three as absolute paths.
 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
@@ -64,7 +66,7 @@ cache:
 | --- | --- | --- | --- |
 | `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. |
+| `exclude` | Array | `[]` | Glob patterns to skip. A relative pattern is matched against the file's path relative to the directory of the config file in use (the working directory when no config file is used), so it excludes the same files whether the path came from `paths:` or from a command-line argument, and it never matches on a directory above that base (a file outside it is seen as `../…`, so `../shared/lib/gen/**` reaches a sibling directory that `paths:` names). A leading `./` is ignored, and a pattern starting with `.` (such as `.*`) also matches files outside the base, which appear as `../…`. A symlink to a file is matched only under its own name: the realpath pass resolves directories, not files. `*` and `**` also cross `/`, so `lib/*.rb` matches nested files too. An absolute pattern is matched against the absolute path. Patterns from an `includes:` file resolve against the top-level config's directory, not the included file's. `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. |
 | `includes` | Array | `[]` | Other config files to layer underneath this one. |
 | `fold_platform_specific_paths` | Boolean | `false` | Resolve Ruby-version-conditional load paths when discovering sources. |
@@ -76,7 +78,7 @@ cache:
 | --- | --- | --- | --- |
 | `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
 | `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
-| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. The walker does not follow `require` / `require_relative`, so list the files in load order: a method declared in two files takes the last-listed one, and a file that requires a later-listed one is still read in list order. `type-of`, `type-scan`, `trace`, `annotate` and `sig-gen` read the patches too, so they type a patched method as `rigor check` does. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
 ### Signature generation
@@ -101,6 +103,8 @@ rigor: signature_paths: "/path/to/sig" does not exist (no signatures loaded from
 rigor: signature_paths: "/path/to/sig" matched 0 signature files
 rigor: libraries: "csb" is not an available RBS library (no signatures loaded from it)
 rigor: disable: "call.undefined-methdo" is not a recognized rule id; the suppression has no effect
+rigor: disable: "plugin_loader.load-error" names a run-level row, which `disable:` does not reach; use `severity_overrides:` or a baseline
+rigor: disable: "plugin.shoulda-matchers.unknown-column" names no plugin `plugins:` configures; the suppression has no effect
 rigor: severity_overrides: "flow.bogus" is not a recognized rule id; the override has no effect
 rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
 ```
@@ -123,10 +127,19 @@ the JSON schema as you type rather than at check time.
 These are warnings, not errors — partial or optional bundles and
 forward-looking config are valid setups. The audit only fires on explicit,
 working-setup-safe signals: an unset default (auto-detected `<root>/sig`,
-auto-detected bundle) is never warned about, and a `disable:` /
-`severity_overrides:` token under a *plugin* family (`rspec.…`,
+auto-detected bundle) is never warned about, and a
+`severity_overrides:` key under a non-built-in family (`rspec.…`,
 `rbs_extended.…`) is left alone, since its rule id cannot be enumerated
-statically and may resolve at run time. The same findings appear in the
+statically and may resolve at run time. `disable:` is checked more
+closely, because what it can reach is known: a plugin's rule counts
+only in its qualified `plugin.<id>.<rule>` form, so a bare plugin rule
+(`rspec.let-binding`) is warned about. A qualified token is checked
+against `plugins:` only when every entry's plugin ID is known without
+loading it — an explicit `id:`, or a bundled plugin's gem name minus
+`rigor-`; one third-party gem listed without `id:` turns that check
+off. A token under `rbs_extended.…`, `rbs.…` or `dynamic.…` is left
+alone, other than the reserved run-level rows (`rbs.coverage.…`,
+`dynamic.dependency-source.…`), which are flagged. The same findings appear in the
 `--format=json` payload under `config_warnings` (each tagged with a
 `kind`), so CI can assert on them.
 
@@ -134,7 +147,7 @@ statically and may resolve at run time. The same findings appear in the
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `disable` | Array | `[]` | Rule IDs or families to suppress project-wide. |
+| `disable` | Array | `[]` | Rule IDs or families to suppress project-wide; `all` suppresses every built-in check rule. A plugin's diagnostics are named by qualified ID (`plugin.<id>.<rule>`, or `plugin.<id>` for the whole plugin); a bare ID or `all` does not reach them. The run-level `.rigor.yml` rows (`plugin_loader.*`, `dynamic.dependency-source.*`, `rbs.coverage.*`, `plugin_trust.*`, `pool-degraded`) are not reached by any spelling; use `severity_overrides:` for those. See [Diagnostics](04-diagnostics.md#suppressing-a-diagnostic). |
 | `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
 | `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
 | `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |

data/docs/manual/04-diagnostics.md

@@ -253,7 +253,12 @@ config.merge(extra)  # rigor:disable call.undefined-method
 ```
 
 It accepts qualified IDs, family wildcards (`call`), a
-comma- or space-separated list, or `all`. The comment must sit
+comma- or space-separated list, or `all`. A plugin's diagnostic
+is reached only by its qualified ID as printed in brackets
+(`plugin.shoulda-matchers.unknown-column`) or by the plugin's
+whole family (`plugin.shoulda-matchers`); its bare rule
+(`unknown-column`) and `all` leave it alone, because several
+plugins share bare rules. The comment must sit
 on the line the diagnostic points at; there is no
 `disable-block` form, so an expression spread over several
 lines needs the comment on each line that fires.
@@ -283,7 +288,8 @@ suppressible like any other rule.
 
 **In-source, whole file.** `# rigor:disable-file <rules>`
 anywhere in a file suppresses those rules for every line;
-`# rigor:disable-file all` silences the file. Convention is to
+`# rigor:disable-file all` silences every built-in rule in the file
+(a plugin's diagnostics need their qualified ID, as above). Convention is to
 put it near the top — typically on a generated file, a fixture,
 or a vendored snippet — but every comment in the file is
 scanned, so any placement works.
@@ -300,6 +306,42 @@ disable:
   - flow.dead-assignment
 ```
 
+`disable: [all]` turns off every built-in check rule, including
+`effect.annotations-unchecked`, which is reported at a signature
+file.
+
+A plugin's own diagnostics are turned off by their qualified ID —
+`plugin.<id>.<rule>` for one rule, `plugin.<id>` for every rule
+of that plugin:
+
+```yaml
+disable:
+  - plugin.shoulda-matchers.unknown-column
+  - plugin.rails-i18n
+```
+
+A bare rule (`unknown-column`, `load-error`) and `all` do not
+reach them, so one plugin's suppression never hides another
+plugin's finding of the same name.
+
+The list does not reach the run-level rows reported at
+`.rigor.yml` — a plugin that failed to load or raised in
+`prepare` (`plugin_loader.*`), a `dependencies.source_inference:`
+gem that did not resolve (`dynamic.dependency-source.*`), the
+`rbs.coverage.*` notices, `plugin_trust.*`, `pool-degraded` —
+under any spelling, `plugin_loader.load-error` included. Turn
+those off with [`severity_overrides:`](#severity-profiles) set
+to `off`, or record them in a [baseline](06-baseline.md).
+`severity_overrides:` matches the row's rule ID without the
+source prefix, so the plugin loader's rows are `load-error` and
+`runtime-error` there — and that key also re-stamps any plugin
+diagnostic whose bare rule is the same. `rigor check` warns when a
+`disable:` entry names one of these rows, names no rule at all,
+or names a plugin `plugins:` does not configure (see
+[Config validation warnings](03-configuration.md#config-validation-warnings)).
+A path or parse error, which has no rule ID, is always
+reported.
+
 For a *known backlog* you want to keep visible but not fail
 on, prefer a [baseline](06-baseline.md) over a blanket
 `disable:` — `disable:` also hides any new occurrences.

data/docs/manual/05-inspecting-types.md

@@ -89,6 +89,14 @@ array. Line queries add `line_enumerations` metadata with the
 shown and total expression counts. An exact position is the same
 query the editor integration answers on hover.
 
+Inside a `rescue` or `ensure` clause, `type-of` and hover can
+disagree with `rigor check`. `check` reads a variable that the
+`begin` body assigns as untyped there, because the clause may run
+after the body raised partway through. `type-of` shows the value
+the variable had before the `begin`. In
+`conn = nil; begin; conn = open_conn; work; rescue; conn.close; end`,
+`type-of` reports `conn` as `nil` and `check` reports nothing.
+
 ## `rigor trace` — watch the inference happen
 
 Where `annotate` and `type-of` show the *answer*, `rigor trace
@@ -110,11 +118,53 @@ typer visits; the default keeps only the three teachable event
 kinds. The JSON stream is stable enough to build course
 material or figures from.
 
+## `rigor lens` — a file's declarations and where their types come from
+
+`rigor lens` lists every class, module, method and attribute a
+file declares, with the type each one has and where that type
+came from: `sig/`, an inline `#:` / `@rbs` comment, a plugin, a
+library, or Rigor's inference from the body. It is experimental:
+the command and its `lens/v0` JSON may still change.
+
+```sh
+rigor lens lib/shop.rb                    # text, for reading
+rigor lens --format=json lib/*.rb         # one JSON document
+```
+
+```text
+lib/shop.rb  xxh3-64:845f7426b6acfe12  (2 omitted)
+  4:7c90  class Shop
+  8:e37e  Shop#label: (::Integer n) -> ::String  [contract inline]
+  14:ce93  Shop#total: () -> Integer  [single_site inferred]
+  16:182b  Shop#fetch  [contested; also lib/legacy_shop.rb:2]
+  omitted constant Shop::LIMIT (line 5)
+```
+
+The answer is the one `rigor check` reaches. A lens runs the
+same incremental analysis as `rigor check --incremental` and
+shares its cache, so the first run costs a full check and later
+runs reuse it. The diagnostics it reports for a file are the
+ones `check` reports.
+
+- A method Ruby could take from more than one definition (the
+  same method defined in two files) is `contested`. Rigor does
+  not guess which one runs, so it prints no signature for it.
+- A declaration this version does not model yet (a constant, an
+  `alias`, a `define_method`) is listed as omitted, never
+  dropped.
+- `LINE:HASH` is an anchor: it changes when the declaration or
+  the type comments above it change, and not when prose
+  comments do.
+
+The JSON document is specified in
+[the lens output contract](../internal-spec/lens.md).
+
 ## Which to reach for
 
 | You want… | Use |
 | --- | --- |
 | One expression's type, from the shell | `rigor type-of` |
+| A file's declarations, their types and where each came from | `rigor lens` |
 | Every line of a file surveyed | `rigor annotate` |
 | The derivation replayed step by step | `rigor trace` |
 | A type printed mid-analysis, in context | `dump_type` |

data/docs/manual/07-plugins.md

@@ -95,7 +95,7 @@ with the `plugins_isolation:` configuration key or the
 | --- | --- |
 | `process` (default) | Run the call in a forked, crash-contained worker, so the target library's monkey-patches and any crash never contaminate Rigor. Falls back to `none` where `fork` is unavailable (Windows / JRuby). |
 | `none` | Load the library into Rigor's own process and call it directly. |
-| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
+| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. The same check runs when `RUBY_BOX=1` is already in your environment: without the fix, the launcher prints a notice and restarts itself without `RUBY_BOX`, so the run completes but plugins are not boxed. The check result is cached per Ruby build under `$XDG_CACHE_HOME/rigor` (or `~/.cache/rigor`) and never expires, so if you rebuild a Ruby in place with the fix, delete `$XDG_CACHE_HOME/rigor/ruby-box-probe` (or `~/.cache/rigor/ruby-box-probe`). A check that times out is not cached, so it costs up to ten seconds on every run. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
 
 The environment variable wins over `plugins_isolation:`, so you can
 override a project's committed choice for one invocation. The legacy

data/docs/manual/10-mcp-server.md

@@ -33,6 +33,7 @@ There is no conflict in running both simultaneously.
 | `rigor_check` | `rigor check --format json` | JSON diagnostic report |
 | `rigor_type_of` | `rigor type-of --format json` | JSON type at `FILE:LINE:COL` |
 | `rigor_triage` | `rigor triage --format json` | JSON distribution + class/method selectors + hotspots + hints |
+| `rigor_lens` | `rigor lens --format json` | JSON `lens/v0` declaration map (experimental) |
 | `rigor_annotate` | `rigor annotate --no-color` | Annotated Ruby source |
 | `rigor_sig_gen` | `rigor sig-gen --print --format json` | JSON RBS skeleton candidates |
 | `rigor_explain` | `rigor explain --format json` | JSON rule catalog entries |
@@ -320,6 +321,34 @@ by `count` for the highest-leverage class/method, or filter by
 
 ---
 
+### rigor_lens
+
+Map the classes, modules, methods and attributes the given files declare,
+with the type `rigor check` gives each one and where it came from. The
+document is the experimental `lens/v0` format
+([specification](../internal-spec/lens.md)); see
+[Inspecting inferred types](05-inspecting-types.md) for the command.
+
+**Input:**
+
+| Argument | Type | Required |
+|---|---|---|
+| `files` | `string[]` | yes |
+| `config` | `string` | no |
+
+**Returns:** JSON. Each file carries its `status`, `sites`, `omissions`
+and `diagnostics`; `members` holds the signatures.
+
+**Typical agent use:** learn what a file or class offers, and the
+contracts its methods already have, before editing it or writing a type.
+Pass every file in one call: each call runs one analysis, and the first
+call on a project costs a full `rigor check`. Paths, site keys and the cache are
+relative to the directory the server was started in, so start it from the
+project root; `--config` fixes which files belong to the project, not how
+paths are written.
+
+---
+
 ### rigor_annotate
 
 Return the given Ruby source file with each line's last-expression
@@ -482,7 +511,7 @@ You should get a JSON response. If you get nothing or a shell error,
 `rigor` is not on your `PATH` — fix the install path first (see
 [Installing Rigor](01-installation.md)).
 
-**`rigor_check` / `rigor_triage` return an empty diagnostics array on a project that has errors.**
+**`rigor_check` / `rigor_triage` return an empty diagnostics array on a project that has errors, or `rigor_lens` reports every file `outside_project`.**
 
 The tool uses `Configuration.discover` from the working directory the
 MCP server was started in. If the client launches `rigor mcp` from a
@@ -517,8 +546,8 @@ warmed by a prior `rigor check` run reduces it significantly.
 
 ## Status and roadmap
 
-`rigor mcp` shipped in v0.1.10 with all seven tools and stdio
-transport. Queued follow-ups are demand-driven:
+`rigor mcp` shipped in v0.1.10 with seven tools and stdio
+transport; `rigor_lens` joined them in v0.4.4. Queued follow-ups are demand-driven:
 
 - **HTTP transport** (slice 2) — `--transport=http` for CI / remote
   agent use; a minimal Rack endpoint.

data/docs/manual/12-caching.md

@@ -184,7 +184,8 @@ file, which other files its analysis read from, so it knows
 exactly which files an edit can affect. A continuous-integration
 gate, `rigor check --verify-incremental`, asserts this on every
 build: it runs the incremental analyzer and a full analysis and
-fails if they disagree on a single diagnostic.
+fails if they disagree on a single diagnostic, or list the same
+diagnostics in a different order.
 
 Rigor is also precise about *what* an edit changed. Re-checking a
 file that many others depend on — a base class, a widely-used
@@ -259,6 +260,22 @@ 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.
 
+
+A warm `--incremental` run says on stderr how far the edit spread,
+for example `rigor: --incremental warm — re-analysed 3 of 1295 files
+(1 changed), reused the rest`. The first count is the files the
+recheck re-analysed, out of M, the analysed set: every project file
+the run covers, or only the subset under a path argument such as
+`rigor check --incremental lib`. The re-analysed files are M minus
+those served from the snapshot. They include files that a change
+reached without editing them, such as a file whose inferred
+parameter types moved (ADR-67), not only the edited files and their
+dependents. The parenthesis lists `changed`, and `added` or
+`removed` when there are some. View templates from a plugin are not
+in M. The recheck re-runs every template on every warm run, so they
+are counted after the file clause, as `plus 2 view templates`. An
+unchanged run reads `re-analysed 0 of 1295 files, reused all`.
+
 `--incremental` is most useful for fast local re-checks and CI
 on a changed branch.
 

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

@@ -185,8 +185,8 @@ paths:
   - lib
 
 exclude:
-  - vendor
-  - tmp
+  - "vendor/**"
+  - "tmp/**"
 
 plugins:
   # Rails core

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

@@ -116,8 +116,9 @@ gap in coverage rather than a finding about your code.
 rigor unused --entry-point='lib/cli.rb' --entry-point='lib/workers/**/*.rb'
 ```
 
-Repeatable. Each glob is matched against every declaration's path, and
-roots every declaration in a matching file.
+Repeatable. Each glob is matched against every declaration's path as
+written, relative to the project root, and relative to the directory
+you run in, and roots every declaration in a matching file.
 
 **File-level references**, free. Code that runs on load — an
 initializer naming a class, a `.rake` task — roots what it names. This
@@ -162,9 +163,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
+"Test code" is decided by path, relative to the project root: the directory of the `.rigor.yml` in
+use, or the directory you run `rigor unused` in when there is none or when the config sits below it
+(`--config=ci/rigor.yml` from the project root). Running it from a subdirectory with `--config` reads
+the same project, and references are read from the directory you run it in as well. A file counts
+as test code when its path as written below either directory says so. The test paths are `spec/` and `test/` anywhere below the root,
+`*_spec.rb` and `*_test.rb`, and the end-to-end trees `qa/`, `e2e/` and `features/` at the 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.
 
@@ -257,10 +261,23 @@ 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
+`Migration::V1` — and the `V*` names under `Migration`'s superclasses
+and mixins and at the top level as well, unless the call passes `false`
+as its second argument. A literal `const_get("Handler")` is a reference
+looked up in the same order, so it names `Migration::Handler` when
+that exists rather than a top-level `Handler`. When the receiver is
+implicit, `self` or `self.class` inside a method (or a block in a class
+body, such as a lambda or `define_method`), the call may run on a
+subclass or on an includer, so a `Handler` declared in a descendant is
+kept reachable too. Descendants are the classes written `class D < Base`
+and the declarations whose body has a plain `include`, `prepend` or
+`extend` of the module; `K.include(Mix)`, `K.send(:include, Mix)`,
+`K.extend(Ext)` and `K = Class.new(Base)` are not followed yet. A call
+written directly in a class body is not widened. Inside
+`Other.instance_eval { }` (or `class_eval`, `module_eval` and their
+`_exec` forms) the receiver is `Other`. 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/rigor-rails-routes.md

@@ -127,8 +127,8 @@ routed. Helper-name recognition for all three is unaffected.
   metaprogramming the parser can't unfold (routes built in a loop
   over runtime data, helpers injected by an engine the parser
   doesn't model) may not register, which can surface a false
-  `unknown-helper`. Record those in a baseline, or
-  `# rigor:disable` the line.
+  `unknown-helper`. Record those in a baseline, or add
+  `# rigor:disable plugin.rails-routes.unknown-helper` to the line.
 - **The "routes file did not load" warning is run-scoped.** It is a
   fact about your configuration, not about any one source file, so
   it is reported once per run on `.rigor.yml` rather than on the

data/docs/manual/plugins/rigor-shoulda-matchers.md

@@ -48,7 +48,10 @@ expected kind: `belong_to` / `have_one` (singular), `have_many` /
 
 Suppress with the qualified rule, e.g.
 `# rigor:disable plugin.shoulda-matchers.unknown-column`, or silence
-the whole family with `# rigor:disable plugin.shoulda-matchers`.
+the whole family with `# rigor:disable plugin.shoulda-matchers`. The
+same spellings work project-wide in `.rigor.yml`'s `disable:`. The
+bare rule (`# rigor:disable unknown-column`) does not reach these
+diagnostics.
 
 ## No configuration
 

data/exe/rigor

@@ -6,8 +6,7 @@
 # (`RUBY_BOX=1`, not toggleable at runtime). When a project selects that
 # strategy (`RIGOR_PLUGIN_ISOLATION=ruby_box`, or the legacy `RIGOR_BOX`
 # alias) we re-exec the same command with the flag set before anything
-# else loads. The `RUBY_BOX` guard prevents an infinite re-exec, and the
-# inherited environment (RUBYOPT / BUNDLE_*) preserves the Bundler
+# else loads. The inherited environment (RUBYOPT / BUNDLE_*) preserves the Bundler
 # context across the exec. The `none` and `process` (default) strategies
 # need no flag, so this is a no-op for them — behaviour is unchanged
 # unless a project opts into `ruby_box`.
@@ -17,22 +16,18 @@
 # Rubies through 4.0.7 segfault on Ruby Bug #22260). When it cannot,
 # the request is dropped with a warning and the run proceeds under the
 # configured strategy (`process` by default) instead of crashing.
-rigor_isolation = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
-rigor_wants_box = rigor_isolation == "ruby_box" || !ENV["RIGOR_BOX"].to_s.empty?
-if rigor_wants_box && ENV["RUBY_BOX"].to_s.empty?
+#
+# When `RUBY_BOX` is already set (by hand or by a wrapper), this process
+# booted inside the box before any Rigor code ran, so the same probe
+# runs here too, and a refused Ruby is re-exec'ed with `RUBY_BOX`
+# removed. The probe's verdict is cached per Ruby build, and the
+# re-exec is marked so the child neither probes nor re-execs again.
+# Nothing above `require "rigor/cli"` may define a Ractor-shareable
+# lambda: that is what crashes inside the box.
+if !ENV["RUBY_BOX"].to_s.empty? || ENV["RIGOR_PLUGIN_ISOLATION"].to_s == "ruby_box" ||
+   !ENV["RIGOR_BOX"].to_s.empty? || ENV.key?("RIGOR_BOX_PROBED")
   require_relative "../lib/rigor/plugin/box_probe"
-  if (rigor_box_unsupported = Rigor::Plugin::BoxProbe.unsupported_reason)
-    rigor_box_warning = "rigor: ruby_box plugin isolation is unavailable: #{rigor_box_unsupported}. " \
-                        "Falling back to the configured plugins_isolation strategy (default: process)."
-    # `$stderr.puts`, not `warn`: `-W0` silences `warn`, and this fallback must never be silent.
-    $stderr.puts rigor_box_warning # rubocop:disable Style/StderrPuts
-    ENV.delete("RIGOR_PLUGIN_ISOLATION") if rigor_isolation == "ruby_box"
-    ENV.delete("RIGOR_BOX")
-  else
-    ENV["RUBY_BOX"] = "1"
-    ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
-    exec(RbConfig.ruby, __FILE__, *ARGV)
-  end
+  exec(RbConfig.ruby, __FILE__, *ARGV) if Rigor::Plugin::BoxProbe.needs_reexec?(ENV)
 end
 
 lib = File.expand_path("../lib", __dir__)