rigortype 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 608dc6b03dfc9267330c24c6493f3f4ee2d025ac5ce01a044202828fc282e258
-  data.tar.gz: 395692680ea16ec6dc42d4187fc57c10ce00731eea4cd1d03176fcc2daa07c14
+  metadata.gz: 983cf341f34d4407d6d06ab2b0bf50260f5b52a4f6e29c61ce0042123ab833cc
+  data.tar.gz: 17ea6b8b13033e507d0e7570913ab2609c830c9a5cfa706cfe055b6857d315f5
 SHA512:
-  metadata.gz: c7145aafeaf9fd22fe3759970c9b4eaafd8720796048641a387ec7a02d4e579689fde37540db686da9904b7d8419a6338b9db7caa38997d7184960c346253f5a
-  data.tar.gz: bff814da943de361c7c1e5bee99fd0e4847d16bb8a9bd3e36609e69246e8eb0e141c6c6e87b425720d709e2277195d9a14100a3018fef75670361fe2acd2160b
+  metadata.gz: 0cd85174733cb61860d33f5636e81ac5d19972f9e6bd66fc6282d1aa7330735f8a57a067e1cfa81071632a45a0ca123f607be5b5bda7b3b32153fb8069328dfc
+  data.tar.gz: 64ecfde3bfe3eaef83ff44fa6ee1ca72bf6f353648c55a354726e60a87203012f907ce5406dc162289ff2a99056cf8b2962a79f636d5e7dd93cf16ec2b00e8d2

data/README.md

@@ -131,7 +131,7 @@ and [CI guide](https://rigor.typedduck.fail/manual/11-ci/).
 
 ```sh
 rigor check lib                 # find bugs (caches under .rigor/ — gitignore it)
-rigor init                      # drop a starter .rigor.yml
+rigor init                      # drop a starter .rigor.yml (suggests plugins from Gemfile.lock)
 rigor annotate lib/foo.rb       # reprint a file with inferred types in the margin
 rigor triage lib                # summarise diagnostics: distribution, hotspots
 rigor sig-gen --diff lib/foo.rb # emit RBS from inference (--write to save)
@@ -232,7 +232,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.6`** (2026-10-23) — on the
+Current release: **`v0.4.7`** (2026-11-03) — 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/gem_overlay/activesupport/core_ext.rbs

@@ -898,31 +898,34 @@ end
 
 class Hash[unchecked out K, unchecked out V]
   # `core_ext/hash/keys`
-  def symbolize_keys: () -> Hash[Symbol, V]
+  # `key.to_sym rescue key` keeps a key without `to_sym`, so no one key type is right: `Hash[untyped, V]` here,
+  # and with the plugin `dynamic_return` hook (#2433) maps each key member where it can.
+  def symbolize_keys: () -> Hash[untyped, V]
   def symbolize_keys!: () -> self
   def deep_symbolize_keys: () -> Hash[untyped, untyped]
-  def deep_symbolize_keys!: () -> self
+  def deep_symbolize_keys!: () -> Hash[untyped, untyped]
   def stringify_keys: () -> Hash[String, V]
-  def stringify_keys!: () -> self
+  def stringify_keys!: () -> Hash[String, V]
   def deep_stringify_keys: () -> Hash[untyped, untyped]
-  def deep_stringify_keys!: () -> self
+  def deep_stringify_keys!: () -> Hash[untyped, untyped]
   def assert_valid_keys: (*K | Array[K]) -> self
-  def deep_transform_keys: () { (K) -> K } -> Hash[K, untyped]
-  def deep_transform_keys!: () { (K) -> K } -> self
+  def deep_transform_keys: [X] () { (K) -> X } -> Hash[X, untyped]
+  def deep_transform_keys!: [X] () { (K) -> X } -> Hash[X, untyped]
   def deep_transform_values: () { (V) -> untyped } -> Hash[K, untyped]
-  def deep_transform_values!: () { (V) -> untyped } -> self
+  def deep_transform_values!: () { (V) -> untyped } -> Hash[K, untyped]
   # `alias_method`s of `symbolize_keys` / `symbolize_keys!`.
-  def to_options: () -> Hash[Symbol, V]
+  def to_options: () -> Hash[untyped, V]
   def to_options!: () -> self
 
   # `core_ext/hash/deep_dup`
   def deep_dup: () -> Hash[K, V]
 
-  # `core_ext/hash/deep_merge`
-  def deep_merge: (Hash[K, V]) -> Hash[K, V]
-                | (Hash[K, V]) { (K, V, V) -> V } -> Hash[K, V]
-  def deep_merge!: (Hash[K, V]) -> self
-                 | (Hash[K, V]) { (K, V, V) -> V } -> self
+  # `core_ext/hash/deep_merge` — the twin of the plugin's rows (#2424 review): the argument's keys join the
+  # receiver's, and a nested merge makes a value neither side declares, so values read `untyped`.
+  def deep_merge: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
+  def deep_merge!: [A, B] (Hash[A, B] other_hash) -> Hash[K | A, untyped]
+                 | [A, B] (Hash[A, B] other_hash) { (K | A, untyped, untyped) -> untyped } -> Hash[K | A, untyped]
   # `other.is_a?(Hash)` — the hook `ActiveSupport::DeepMergeable` asks before
   # recursing into a value. `:nodoc:`, but public.
   def deep_merge?: (untyped other) -> bool

data/data/vendored_gem_sigs/bundler/bundler.rbs

@@ -150,7 +150,7 @@ module Bundler
     # `#initialize`, `#specs` — declared by `sig/shims/bundler.rbs` with the same types.
     def platforms: () -> Array[untyped]
     def sources: () -> Array[untyped]
-    def dependencies: () -> Array[Dependency]
+    def dependencies: () -> Hash[String, Dependency]
     def ruby_version: () -> untyped
     def bundler_version: () -> untyped
   end

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -112,8 +112,9 @@ class Gem::Specification
 
   # Instance-side surface widely used by bundler / rubygems
   # internals. `attr_accessor` mirrors the writer + reader pair
-  # so the survey's `.name=` / `.version=` / `.full_gem_path=` /
-  # `.loaded_from=` / `.post_install_message=` writes resolve too.
+  # so the survey's `.name=` / `.version=` / `.loaded_from=` /
+  # `.post_install_message=` writes resolve too. `.full_gem_path` is declared on `Gem::BasicSpecification`,
+  # which this class inherits from.
   def activate: () -> untyped
   def specification_version: () -> Integer
   def files: () -> Array[String]
@@ -127,13 +128,13 @@ class Gem::Specification
   # `#version`'s READER is declared by `sig/shims/rubygems.rbs` (`attr_reader version (): Version`);
   # only the writer is ours.
   def version=: (Gem::Version) -> Gem::Version
-  attr_accessor full_gem_path: String
   attr_accessor loaded_from: String?
   attr_accessor post_install_message: String?
 end
 
 class Gem::BasicSpecification
   def version: () -> Gem::Version
+  attr_accessor full_gem_path: String
   def executables: () -> Array[String]
   def name: () -> String
   def full_name: () -> String

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

@@ -283,8 +283,11 @@ 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, with `paths` and a
-`severity_profile` filled in, `target_ruby` commented out until
-you set it to your project's Ruby, and the rest commented out. That is all most projects need; the key
+`severity_profile` filled in. When your `Gemfile.lock` declares a
+gem a bundled plugin models, the template suggests that plugin
+under `plugins:`, commented out, for you to enable. `target_ruby`
+is commented out until you set it to your project's Ruby, and the
+rest is commented out too. That is all most projects need; the key
 reference, the JSON-schema editor integration, and `includes:`
 composition are in
 [Configuration](../manual/03-configuration.md).

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

@@ -155,6 +155,11 @@ The `sig.skipped.*` reasons are:
   generic by an inline declaration and `sig/` does not declare
   it yet, or names its type parameters otherwise. See
   [Classes made generic inline](#classes-made-generic-inline).
+- `sig.skipped.generic-reopening` — the method's class, or one
+  it is nested in, is declared generic by loaded RBS with a
+  type parameter that has a bound or a default, and `sig/`
+  does not declare it. See
+  [Reopening a generic class](#reopening-a-generic-class).
 - `sig.skipped.inline-differs` — the method is declared
   inline and in `sig/`, and the two disagree. A refusal:
   `--write` and `--check` exit `1`. See
@@ -330,10 +335,34 @@ so a return inferred for the new line would describe
 parameters that are about to change. Delete the `sig/` member
 and re-run; sig-gen then writes the method afresh.
 
+### Reopening a generic class
+
+When your code reopens a class that loaded RBS declares
+generic — `class Array`, `class Hash`, a gem's class, or one
+your `sig/` declares — sig-gen writes the header with that
+declaration's type parameters: `class Array[unchecked out E]`.
+rbs rejects a reopening whose parameters differ, so a bare
+`class Array` would fail the class, and every class whose
+signature mentions it, with `GenericParameterMismatchError`.
+The members still say `untyped` for the element type, and a
+class whose name matches a copied parameter is written
+anchored (`::E`), since a bare `E` would name the parameter.
+
+The parameters are copied only when every one is plain: a
+name, a variance and `unchecked`. A bound or a default
+(`class Box[T < Comparable]`) is a type written for the
+declaring file's namespace and could mean another class
+where sig-gen writes, so that class's methods, and those of
+classes nested in it, are skipped as
+`sig.skipped.generic-reopening`. Declare the class in `sig/`
+with its parameters and sig-gen writes the members into that
+declaration. A file that already declares the class keeps its
+own header.
+
 ### Classes made generic inline
 
-sig-gen does not write a class's type parameters yet. A class
-declared generic inline (`# @rbs generic T`) is therefore not
+sig-gen does not copy type parameters from an inline
+declaration. A class declared generic inline (`# @rbs generic T`) is therefore not
 opened in `sig/`: a header without its parameters would make
 rbs reject the class, and every class whose signature mentions
 it, with `GenericParameterMismatchError`. Its methods, and
@@ -626,6 +655,24 @@ list is the current state):
   are recognised as user-authored and never produce a
   duplicate `def` insertion.
 
+Two rules shape the class declarations and type names around
+those methods:
+
+- **A subclass of a core or stdlib class** is declared even
+  when it has no method of its own to emit, so a method
+  returning one resolves: `class MyHash < Hash; end` is
+  written `class MyHash < ::Hash[untyped, untyped]`. The
+  declaration goes into the file written for its source file,
+  so it appears only when that source file has at least one
+  method to emit. A class some signature already declares is
+  left to that declaration.
+- **A type name a namespace shadows** is written with a
+  leading `::`. Inside a `module Foo` that declares a
+  `Foo::Set`, a method returning a core `Set` is written
+  `-> ::Set[untyped]`, because RBS would read a bare `Set`
+  there as `Foo::Set`. Where nothing shadows the name, it is
+  written bare as before.
+
 Method shapes the generator does **not** cover yet:
 
 - `define_method(:name) { ... }`.
@@ -643,7 +690,7 @@ two are wired today, one is reserved.
 | Policy | Behaviour |
 | --- | --- |
 | `untyped` (default) | Every parameter is spelled `untyped`. No inference-derived parameter contract is imposed on future callers. The user retains complete authorship over parameter typing. |
-| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
+| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. A literal argument is widened to its class first, so `"hello"` proposes `String` (#2254). With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
 | `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
 
 Under `--params=observed`, the `--print` / `--diff` JSON payload gains

data/docs/handbook/appendix-phpstan.md

@@ -20,7 +20,7 @@ unchanged. This appendix maps the vocabulary.
 | Default behaviour | Inference, fall back silent | Inference, fall back silent |
 | "Levels" | 0 – 10 (numeric) | `lenient` / `balanced` / `strict` (named) |
 | Per-rule control | `ignoreErrors:` regex, level demotion | `disable:`, `severity_overrides:` |
-| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor.baseline.json` (ad-hoc) |
+| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor-check.json` (ad-hoc) |
 | Stub format | PHP stub files | RBS files |
 | Custom narrowing | Type-Specifying Extensions | Plugins (Chapter 9) |
 | Custom return shape | Dynamic Return Type Extensions | Plugin `dynamic_return` |
@@ -140,10 +140,10 @@ severity controls, and includes.
 | `ignoreErrors:` (regex / pattern) | `disable:` (rule identifier or wildcard) |
 | `parameters: ignoreErrors:` per-path | `# rigor:disable-file <rule>` at the file head |
 | `includes:` | `includes:` |
-| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor.baseline.json` (ad-hoc) |
-| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor.baseline.json` (ad-hoc) |
+| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor-check.json` (ad-hoc) |
+| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor-check.json` (ad-hoc) |
 | `phpstan analyse` | `rigor check` |
-| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor.baseline.json` (ad-hoc) |
+| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor-check.json` (ad-hoc) |
 | Path resolution: relative to declaring file | Path resolution: relative to declaring file (same rule). |
 
 Rigor has two baseline mechanisms: a **managed** baseline

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

@@ -10,6 +10,8 @@ rigor <command> [options] [arguments]
 `rigor help` prints the command list; `rigor version` prints
 the installed version. An unknown command, or a malformed
 option, exits `64` — the conventional "usage error" code.
+See [`rigor help`](#rigor-help) for a single command's help and
+the machine-readable list of commands and flags.
 
 Every command that loads your project configuration also
 accepts `--config=PATH` to point at a specific config file
@@ -46,7 +48,7 @@ check their arity, since another file may redefine them.
 | `--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 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). It re-analyses half of an unchanged tree and serves the other half from cache, so it checks the cache-merge path but not that an edit re-checks every file it affects; `--verify-incremental-edits` adds that. |
-| `--verify-incremental-edits=N` | With `--verify-incremental` (and implying it): after the check above, replay two edits on each of `N` files spread over the analysed list, through an editor buffer, never on disk: the file emptied, then the file reduced to its `class` / `module` declarations with every body dropped (skipped when that is the file itself, or holds no declaration). After each edit, the warm recheck of the baseline must equal a full analysis of the edited tree, or the run fails naming the edit and the file. Each replay costs a recheck and a full analysis. A replay the recheck declines (it would have been a full analysis) is counted in the OK line, and the run fails if every replay declined. Only these two removals are replayed, never an addition. Default 0. |
+| `--verify-incremental-edits=N` | With `--verify-incremental` (and implying it): after the check above, replay edits on each of `N` files spread over the analysed list, through an editor buffer, never on disk: the file emptied; the file reduced to its `class` / `module` declarations with every body dropped (skipped when that is the file itself, or holds no declaration); and up to two copies of the file each missing one statement of a `class` / `module` body, with everything else kept, so a finer dependency edge is the only thing that re-checks a reader (visibility calls such as `private` and `module_function` are dropped first, then other statements spread over the file). After each edit, the warm recheck of the baseline must equal a full analysis of the edited tree, or the run fails naming the edit and the file. Each replay costs a recheck and a full analysis. A replay the recheck declines (it would have been a full analysis) is counted in the OK line, and the run fails if every replay declined. Only removals are replayed, never an addition. Default 0. |
 | `--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. |
@@ -60,7 +62,7 @@ check their arity, since another file may redefine them.
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
 | `--no-tolerated-effects` | Check effect envelopes as if [`effects.tolerated:`](03-configuration.md) were empty — the audit switch for your discharge policy (ADR-103). Judgment only: the run, what it collects and its cache entry are identical either way, so this never costs a re-analysis. |
-| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
+| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together, once per run (a repeat is a usage error). Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
 any are reported, `64` on a usage error. `--fail-on` raises that
@@ -70,14 +72,16 @@ that want the stricter reading.
 ### Editor mode scope
 
 `--tmp-file` / `--instead-of` on their own analyse **only** the
-buffer's file. It still reads the rest of the project's declarations
-(the classes and methods other files define), as `rigor check FILE`
+buffer's file. The `--instead-of` logical path is analysed even when it
+lies outside `paths:`, as it always has been. It still reads the rest of the
+project's declarations (the classes and methods other files define), as `rigor check FILE`
 does, but it reports nothing about what the unsaved edit does to the
 rest of the project.
 
 Adding `--incremental` analyses the **whole project with the buffer
 substituted** — the edited file and the files that depend on it are
 re-analysed, everything else is served from the incremental snapshot.
+A buffer for a claimed template is analysed as its template unit, once.
 An unsaved change to a method's return type therefore surfaces in its
 callers, not just in the file being edited.
 
@@ -91,6 +95,11 @@ Two things to know:
   exist only in your editor, and recording them would make the next
   ordinary run believe it had already analysed a file in a state it
   was never in.
+- The buffer's file need not exist on disk yet: a new file is analysed
+  as an added file, with or without path arguments.
+- Editor mode binds one buffer per run. Repeating `--tmp-file` or
+  `--instead-of` is a usage error (exit `64`), not a silent replacement
+  of the earlier pair.
 
 `--verify-incremental` refuses a buffer: it compares against a full
 analysis of the files on disk, which a buffer contradicts by
@@ -101,12 +110,41 @@ construction.
 Write a starter configuration file.
 
 ```sh
-rigor init [--path=PATH] [--force]
+rigor init [--path=PATH] [--force] [--no-plugins]
 ```
 
 Writes `.rigor.dist.yml` by default. `--path` chooses a
 different target; `--force` overwrites an existing file.
-Exit `1` if the file exists and `--force` was not given.
+Exit `1` if the file exists and `--force` was not given. A `--path` whose
+directory does not exist, or that cannot be written, is a usage error: one
+`rigor init: cannot write PATH: REASON` line on stderr and exit `64`. The
+directory is not created.
+
+When the project has a `Gemfile.lock` in the working directory,
+`rigor init` suggests the bundled plugins whose gems the lockfile
+declares (the same read as [`rigor doctor`](#rigor-doctor)'s
+plugin-gap check). The suggestions are commented out under
+`plugins: []`, so nothing loads until you enable one: delete the
+`[]` on the `plugins:` line, uncomment the entries you want, then
+run `rigor plugins --strict`. A Rails project's `rails` also brings
+in the Rails family, so the list can be long. Without a lockfile,
+or when no locked gem has a bundled plugin, the template has no
+suggestions.
+
+Suggesting rather than enabling follows ADR-96 Criterion 2: a
+lockfile's presence does not by itself opt a project into a
+plugin's code.
+
+In a Rails application (a `config/application.rb` in the working
+directory), `rigor init` also suggests the source directories that
+exist, `app` and `lib`. The active `paths:` stays `lib`; the
+suggestion is a commented `paths:` line under it, which names what
+was detected. A bare `rigor check` analyses only `lib` until you
+delete the `paths:` list above and uncomment the line below. Other
+layouts get no directory suggestion.
+
+`--no-plugins` writes the template with no plugin suggestions, even
+when a lockfile is present.
 
 ## `rigor annotate`
 
@@ -123,10 +161,16 @@ honours `NO_COLOR`; `--color` / `--no-color` override. When
 colour is on and [`bat`](https://github.com/sharkdp/bat) is on
 `PATH`, highlighting goes through bat (`--no-bat` opts out;
 `--bat` warns if bat is missing and falls back to the built-in
-colorizer). `--format=json` emits a `{ line => type }` map
-instead of the annotated source. Exit `1` on a parse error or a
+colorizer). `--format=json` emits an `{ "schema_version": 1, "annotations": { line => type } }`
+document instead of the annotated source. Exit `1` on a parse error or a
 missing file.
 
+## JSON documents
+
+Every `--format=json` document Rigor defines whose top level is an object, except the three named below, starts with an integer `schema_version` (currently `1`). Where a flag selects which document is printed, `mode` follows it: `rigor coverage` prints `precision`, `protection`, `mutation` or `protection-fused`, and `rigor plugins` prints `status` or `capabilities`. The key set is contract from v1.0.0: a minor release may add a key, and removing or renaming one needs a major.
+
+`rigor lens` (its own `schema` / `revision`), `rigor baseline dump` (`version`) and `rigor check`'s CI formats (`sarif`, `gitlab`, ...) keep their own markers. `rigor type-of`, `rigor explain` and `rigor trace` are the exceptions and still print their current top-level shape (an array; for `type-of` a flat object or `{ results }`; for `explain <skip-reason>` a flat object); the next minor release switches them to `{ "schema_version": 1, "results" | "rules" | "skip_reasons" | "events": [...] }`. Until then each prints a note on stderr, and the matching MCP tools append the same note as an extra text block.
+
 ## `rigor type-of`
 
 Print inferred types at one or more source positions.
@@ -148,7 +192,8 @@ wraps several results in a `results` array. Line queries add a
 `line_enumerations` array whose `shown` and `total` counts make
 truncation explicit. `--trace` records fail-soft fallbacks,
 after the rows of a line table in text output. The editor-mode
-`--tmp-file` / `--instead-of` pair is accepted as on `check`.
+`--tmp-file` / `--instead-of` pair is accepted as on `check`, and a repeated flag is a usage error
+(exit `64`) there too.
 
 A class or constant that another project file declares reads as
 `rigor check` types it (`singleton(User)`) when a bare
@@ -159,9 +204,13 @@ and never writes it. With no reusable snapshot (none yet, or one a
 change made unusable, for example a changed configuration, lockfile, `sig/`, `pre_eval:`
 file or required feature, an engine upgrade, or a snapshot written
 for other roots) the probe types the one file on its own, so such a name reads
-`Dynamic[top]`, and it prints nothing about it. Only those
-declarations are shared: the types `check` infers for an unannotated
-parameter are not.
+`Dynamic[top]`, and it prints nothing about it. With
+`parameter_inference: true`, the types `check` infers for an
+unannotated parameter come from the same snapshot (its recorded
+call-site table), so `@v = v` reads as `check` types it, but only
+while no project file has changed since the snapshot (an editor
+buffer whose bytes differ from the snapshot counts as a change); once any file differs, or with the setting off
+or no snapshot, those types are not shared.
 
 A template a plugin compiles into Ruby (an ERB view under
 `rigor-actionpack`) is probed the way `rigor check` analyses
@@ -521,11 +570,11 @@ a severity or a suppression line.
 
 ## `rigor diff`
 
-Compare the current diagnostics against a saved baseline JSON
-and report only what is new.
+Compare the current diagnostics against a saved
+`rigor check --format=json` result and report only what is new.
 
 ```sh
-rigor diff [options] <baseline.json> [paths...]
+rigor diff [options] <rigor-check.json> [paths...]
 ```
 
 `--current=PATH` compares against a saved diagnostics JSON
@@ -571,6 +620,18 @@ refuse a file, so a tighter return `--write` declines without
 `--overwrite` does not fail it; `--check --overwrite` counts one.
 See [handbook chapter 11](../handbook/11-sig-gen.md#keeping-sig-current-in-ci).
 
+`--write` also repairs a header in any file under the signature directory it writes to (the directory
+under the project root named like the last path component of the first `signature_paths:` entry, `sig/` by
+default, vendored or generated `.rbs` under it included) that opens a generic class such as
+`class Array` or `class Hash` without its type parameters (an earlier release wrote them), reporting
+`repaired N generic header(s)`, and `--check` fails until it is written. In `--format=json` the row of a file
+no method of the run maps to has `"source": null`. A class is repaired in all of its bare headers or in none:
+when the body of any of them names a type spelt like one of the parameters (`def old: () -> E`), which the
+parameter would capture, or one of them is in another `signature_paths:` entry, which `--write` never
+rewrites, none is repaired. A `generic header left bare` line (`left_bare` in `--format=json`) names the files
+and the reason, and `--check` does not fail on it. Write the name as `::E`, or fix the other file, to let the
+repair through.
+
 `--write` names each proposal it skipped (a member `sig/` already declares, an `alias` included, or one that
 routes to a signature path it does not write to, because it is declared there or its class lives there) on its own `skipped Class#method (reason)` line; the exit status is
 unchanged. See [handbook chapter 11](../handbook/11-sig-gen.md#safety-what---write-will-and-will-not-do).
@@ -614,7 +675,13 @@ would take every other type in the file down with it. Under
 **refused** (the existing file is left untouched) and the command
 exits `1`: you asked for a write and did not get one. Such a skip
 is a bug in Rigor's RBS rendering, not in your code — please
-report it.
+report it. An existing target that does not parse as RBS in the
+first place, and that sig-gen would write into, is refused the same
+way, named on stdout as `REFUSED` with the parse location (the JSON
+action is `skipped_unparseable`); `--check` fails on it too, so such a
+target is never reported as up to date. An unparseable `sig/` file that
+no emittable candidate maps to is not refused and still passes
+`--check`. Fix its syntax error and re-run.
 
 A method the generator declined for any other reason (a body
 that proves only `untyped`, a user-authored declaration it will
@@ -634,10 +701,20 @@ Run the Language Server over stdio. See
 rigor lsp [--transport=stdio] [--log=PATH] [--config=PATH]
 ```
 
-`stdio` is the only transport in v1. `--log=PATH` is accepted
-but not yet wired in this release — it is reserved for routing
-the server's wire log to a file; until then logging stays on
-stderr.
+`stdio` is the only transport in v1. `--log=PATH` appends the LSP
+wire log to PATH: each JSON-RPC message the client sends (`<-`) and
+each one the server writes (`->`), one line per message with a
+timestamp, plus the server's debug output from the start of the
+server loop to its end. The file is opened for appending before the
+server starts, so an unwritable PATH exits with a usage error. An
+exception that escapes the loop is written to the file with its
+backtrace. Output written before the loop starts (configuration
+loading and server setup) and any crash outside the loop still go to
+stderr, as does the server's output when the file becomes unwritable
+mid-session. A message the JSON encoder rejects (raw invalid UTF-8) is
+logged in a scrubbed form. Without `--log`, no wire log is written and
+the server's debug output goes to stderr; stdout carries only the
+protocol.
 
 ## `rigor baseline`
 
@@ -661,6 +738,12 @@ rigor baseline <generate|regenerate|dump|drift|prune> [options]
 `--baseline=PATH` to read a non-default baseline file. `dump`
 also accepts `--format=text|json` for machine-readable output.
 
+No subcommand takes a positional path: `generate` and `regenerate`
+analyse the configured `paths:`, `drift` and `prune` audit them, and
+`dump` reads the baseline file and filters with `--rule`/`--file`. A path argument is a usage error
+(exit `64`). Narrow the scope with `paths:` in the configuration, not on
+the command line.
+
 ## `rigor triage`
 
 Summarise a diagnostic stream — rule distribution, **class/method
@@ -1011,15 +1094,22 @@ toolchain, so you can read a real, working plugin as a worked
 example when authoring your own.
 
 ```sh
-rigor plugin <list|path|print|root> [name]
+rigor plugin [<name>] [--path <name>] [--list] [--root]
 ```
 
-| Subcommand | Purpose |
+The positional slot is a plugin *name*; alternative outputs are
+flags, the same grammar as `rigor skill` and `rigor docs`.
+
+| Form | Purpose |
 | --- | --- |
-| `list` | Table of every bundled plugin and example, name + absolute directory path (default when no subcommand given). |
-| `path <name>` | One-line absolute path to the plugin's directory. |
-| `print <name>` | A header (dir / lib / sig / README paths) followed by the plugin's main source body inlined. |
-| `root` | The `rigortype` gem root and its key subdirectories. |
+| `rigor plugin`, `--list` | Table of every bundled plugin and example, name + absolute directory path (the default). |
+| `<name>` | A header (dir / lib / sig / README paths) followed by the plugin's main source body inlined. |
+| `--path <name>` | One-line absolute path to the plugin's directory. |
+| `--root` | The `rigortype` gem root and its key subdirectories. |
+
+The earlier verbs `list`, `path <name>`, `print <name>` and `root`
+still work for one minor release and print a deprecation notice on
+stderr naming the replacement; the output on stdout is the same.
 
 Paths resolve at runtime from the gem location (a documented
 caveat for container / cross-filesystem setups).
@@ -1275,6 +1365,42 @@ rigor upgrade
 Until then it prints the current version and notes that upgrade is
 queued. Exits `0`.
 
+## `rigor help`
+
+```sh
+rigor help                  # the command list
+rigor help <command>        # the same as `rigor <command> --help`
+rigor help --format=json    # every command, its flags and formats
+```
+
+`rigor help --format=json` prints the whole CLI surface as one JSON
+document, for tools and agents that would otherwise parse the help
+text:
+
+```json
+{ "schema_version": 1, "version": "…", "commands": [ … ] }
+```
+
+Each entry of `commands` has:
+
+| Key | Value |
+| --- | --- |
+| `name` | The command name. |
+| `summary` | The one-line description `rigor help` prints. |
+| `usage` | The usage line (`Usage: rigor …`). |
+| `flags` | The command's own switches, each `{ "name", "arg", "optional", "desc" }`. `arg` is the argument's name, `null` for a switch that takes none, and `optional` is `true` when the argument may be left out (`--bleeding-edge[=LIST]`). `--[no-]x` is listed as the two flags `--x` and `--no-x`. |
+| `formats` | The values the command's own `--format` accepts, empty when it has none. A command that only has subcommands with the flag (`baseline`) lists none here. |
+| `subcommands` | One `{ "name", "usage", "flags", "formats" }` object per subcommand (`baseline dump`, `effects check`, `skill describe`), with the same meaning as above and empty arrays where the subcommand has nothing to list. |
+| `mcp_tool` | The [MCP](10-mcp-server.md) tool that mirrors the command, or `null`. |
+
+The list covers every command above plus `help` and `version`. The
+text help is rendered from the same list.
+
+`rigor help <command>` takes one command: a second word
+(`rigor help baseline drift`) is refused with exit `64`, and an
+unknown command exits `64` too. Flags after the command name are
+ignored rather than parsed.
+
 ## Environment variables
 
 Most behaviour is driven by flags and `.rigor.yml`; a few

data/docs/manual/03-configuration.md

@@ -24,7 +24,7 @@ Relative paths in a config file resolve against that file's own directory, with
 `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:`,
+directory called `~name`, not another user's home. This covers `paths:`, `signature_paths:`, `core_root:`, `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.
@@ -78,9 +78,39 @@ 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. |
+| `core_root` | String | `nil` | A directory of core `.rbs` files loaded **instead of** the `rbs` gem's own core, such as one [rbs-shifter](https://github.com/rigortype/rbs-shifter) generates for an older CRuby. A relative path resolves against the config file's directory. `nil` loads the gem's core. See [Analysing for an older Ruby](#analysing-for-an-older-ruby). |
 | `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). |
 
+#### Analysing for an older Ruby
+
+Rigor runs on Ruby 4.0, and its bundled core signatures describe Ruby 4.0. A project that runs on an older
+Ruby can call a method that version does not have, and Rigor accepts the call. To check against the older
+API, point `core_root:` at a core signature directory written for it:
+
+```yaml
+target_ruby: "3.3"
+core_root: vendor/rbs-shifter/3.3/core
+```
+
+`core_root:` replaces the core, while `signature_paths:` only adds to it. A method that a signature directory
+omits stays declared by the default core, so `signature_paths:` cannot remove one. With the core above,
+`[1, 2].rfind { ... }` reports `call.undefined-method` and `" text ".strip(" ")` reports `call.wrong-arity`.
+Project signatures, plugins and `libraries:` still load on top of it. `target_ruby:` sets the syntax Rigor
+parses; it does not choose a core.
+
+A `core_root:` that does not exist, is not a directory, holds no `.rbs` file, lies inside (or contains) one of
+your `signature_paths:`, or does not build an RBS environment stops the run with exit code 64. A core class
+whose definition fails to build because of the core's own files is reported as an
+`rbs.coverage.definition-build-failed` error:
+
+```
+rigor: core_root: "/path/to/vendor/rbs-shifter/3.3/core" does not exist
+```
+
+The cache keys on the directory and on the contents of its files, so switching cores or regenerating one
+invalidates cached results, including in a running language server.
+
 ### Signature generation
 
 | Key | Type | Default | Meaning |
@@ -144,7 +174,10 @@ is left alone, other than the reserved run-level rows (`rbs.coverage.…`,
 those rows are the intended keys and are never flagged, while a bare plugin
 rule, `all`, or a `plugin.`-qualified key for an unconfigured plugin is. The same findings appear in the
 `--format=json` payload under `config_warnings` (each tagged with a
-`kind`), so CI can assert on them.
+`kind`), so CI can assert on them. The [language server](09-editor-integration.md)
+shows each one as a `window/showMessage` warning, and every
+[MCP tool](10-mcp-server.md#tool-reference) that takes a `config`
+argument includes them in its result.
 
 ### Diagnostics
 
@@ -194,7 +227,7 @@ project Ruby's gem home without running your toolchain. If `rigor check`'s
 `--stats` shows gems whose RBS it could not find, point it at the bundle
 explicitly with `bundler.bundle_path:`, or supply signatures another way:
 `rbs collection install` (auto-discovered) or `dependencies.source_inference:`.
-| `rbs_collection.auto_detect` | Boolean | `true` | Auto-discover `rbs_collection.lock.yaml`. |
+| `rbs_collection.auto_detect` | Boolean | `true` | Auto-discover `rbs_collection.lock.yaml`. An entry is not loaded for a gem your `Gemfile.lock` sources from a `path:` directory that is at or under one of your `paths:` entries, or contains one, and is not left out by `exclude:` (the gem is code Rigor analyses, which your `sig/` declares). |
 | `rbs_collection.lockfile` | String | `nil` | Explicit `rbs_collection.lock.yaml` path. |
 | `dependencies.source_inference` | Array | `[]` | Per-gem source-inference modes (ADR-10). |
 | `dependencies.budget_per_gem` | Integer | `5000` | Per-gem source-walk cap, counted in **method definitions** (not time): the walker stops harvesting a gem's catalog once it reaches this many `def`s, then emits `dynamic.dependency-source.budget-exceeded` and degrades the rest to `Dynamic[top]`. Range 1250–20000. |