rigortype 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96e337b134c8bcb33bf20707e88ffbe16ff98b94513d483043e18432d9bf6328
-  data.tar.gz: e46a5af02a699ef2d0ad41e7b8b94e2d5eac02d1085d30fc03831df208ef930e
+  metadata.gz: c26e2df607ebe3e1ef3b0c34a329aea4b1b0c80ec311cf6d9a83c4a58a358dfa
+  data.tar.gz: 2c4097594c8abe73819197a867cbb9a7b7dc3de86d8a2f22a2a83b1f948fa63a
 SHA512:
-  metadata.gz: cc7a7cadf53373e66de5ff268b2a44452d42972cbd9c1683825e2809480573bf195d9c26252d0522ddac2ae3f39f9dc665768d61cbb7c6e63ee6d60eaa17b87a
-  data.tar.gz: 05b82b8662a6e5b0283a04eca851d0bb6aa1031f55fd1e99525c5b884e433a30b89d519486f6fceebca95e47a306f721766adecc13d4c68134c833e9e525304a
+  metadata.gz: d790e8fdb333983f82d85fb13036661ef87ca82d273b86955e1c7fa3191a65d027a04ea92fb4877edeb24f3df6bdae4dc03780791a79b15510ea5c7b494f23b6
+  data.tar.gz: b1258c842c5e656aea59b32eb91310cdda72a9dade402c87d2523bae3e4fa927f6607b0e2acd4250d24bfcba77e27df778aaf02c50c57300b6c27099c312c098

data/README.md

@@ -91,8 +91,9 @@ It installs Rigor, then runs the bundled **`rigor-project-init`**
 [Agent Skill](https://agentskills.io/): it walks your `Gemfile`,
 proposes plugins matched to your stack (Rails, Sinatra, dry-rb, …),
 lets you pick an adoption mode — **baseline** (acknowledge existing
-diagnostics, work them down incrementally) or **strict**
-(zero-diagnostic gate from day one) — and commits a ready-to-use
+diagnostics, work them down incrementally; the recommended
+default) or **strict** (zero-diagnostic gate from day one, an
+opt-in for users fluent in type theory and RBS) — and commits a ready-to-use
 configuration.
 
 **This works in your language.** The prompt is plain natural
@@ -231,7 +232,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.0`** (2026-09-27) — opening the
+Current release: **`v0.4.1`** (2026-10-08) — 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/docs/handbook/08-understanding-errors.md

@@ -114,8 +114,9 @@ mostly a question of *how much* you want to say:
 
 1. **`severity_profile:`** — the project's overall stance.
    `lenient` for a legacy codebase you are easing Rigor into,
-   `balanced` for everyday work, `strict` for a project with
-   no legacy noise.
+   `balanced` for everyday work, new projects included, and
+   `strict` only if you are ready to resolve inference gaps
+   through signatures and RBS yourself.
 2. **`severity_overrides:`** — one rule (or one family) at a
    different severity from the rest of the profile. The right
    layer when a rule is *useful but not blocking* for you.

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
 

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