rigortype 0.3.4 → 0.3.6

data/docs/manual/03-configuration.md

@@ -176,12 +176,15 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 
 ### Effect labels
 
+The key reference is below; the workflow these keys serve — the vocabulary, the report, the committed
+snapshot, the CI gate — is [Effect labels](19-effect-labels.md).
+
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `effects` | Hash | absent | **Opt-in to effect labels ([ADR-103](../adr/103-effect-labels.md)).** The *presence* of this block is the switch — `effects: {}` enables collection with every sub-key at its default, and leaving it out keeps `rigor check` byte-identical and free. Nothing else turns collection on: an `%a{pure}` or `%a{rigor:v1:effect …}` annotation in your RBS does not, because an annotation must not silently make every run more expensive — such a project gets one `effect.annotations-unchecked` `:info` per run instead, saying the annotations are inert. `rigor effects` runs under an implicit empty block when the key is absent, so you can try the report before configuring anything. Effect summaries are cached under their own identity (Rigor's effect vocabulary, its built-in catalogue and this block), so `rigor effects` after `rigor check` in the same job is a cache hit plus the propagation, and turning this block on or off does not invalidate your diagnostics cache. The sub-keys are below. `views` is declared in the schema and reserved: accepted and **not yet read**. See [`rigor effects`](02-cli-reference.md#rigor-effects). |
 | `effects.check` | Boolean | `true` | Whether the envelopes you declared — `%a{pure}` and `%a{rigor:v1:effect …}` in RBS, and the `effects.envelopes:` stanzas below — are checked against what Rigor proved, surfacing `effect.envelope-exceeded` and, for a label the vocabulary does not recognise, `effect.unknown-label`. Set it to `false` to keep the report and the snapshot while silencing both. Never on without an `effects:` block. |
 | `effects.snapshot.path` | String | `.rigor-effects.yml` | Where `rigor effects update` writes the committed record. |
-| `effects.snapshot.reach` | Array | `[]` | Entry points whose **transitive** footprint the snapshot records under `reach:`. Each entry is a project-relative file glob (the `unused --entry-point` semantics — `**` is the only way across a directory boundary) or the name of an entry-point **preset** a plugin registered. On a Rails app, `reach: [rails]` is the one you want — see below. A name nothing registered is an error when the snapshot is built (not when the configuration loads, because the plugins that name presets load *from* that configuration). |
+| `effects.snapshot.reach` | Array | `[]` | Entry points whose **transitive** footprint the snapshot records under `reach:`. The default is empty **deliberately**: Rigor could infer `[rails]` from your plugin list, but a snapshot is a record you agree to and review the diff of, and one whose contents moved because your plugin list moved would be the worse artefact. `rigor effects update` names the presets your plugins registered and leaves the same hint in the written file. Each entry is a project-relative file glob (the `unused --entry-point` semantics — `**` is the only way across a directory boundary) or the name of an entry-point **preset** a plugin registered. On a Rails app, `reach: [rails]` is the one you want — see below. A name nothing registered is an error when the snapshot is built (not when the configuration loads, because the plugins that name presets load *from* that configuration); the error lists the presets your plugins did register, so it names the fix. |
 | `effects.snapshot.gate` | String | `symmetric` | What `rigor effects check` treats as drift. `symmetric` fails on any difference — a job that *stopped* enqueueing is news too; `additions` is the growth-only ratchet. |
 | `effects.labels` | Array | `[]` | Effect labels **your project** registers, layered over Rigor's shipped vocabulary. A project may open any root (`acme.cache`) — listing the label here is the vouching act. Once registered, a label is usable in every other key below and stops being reported as unknown. Malformed spellings are a load error. |
 | `effects.attribution` | Hash | `{}` | What a call into code Rigor cannot see *does*, keyed by method: `{"Net::HTTP.get": [io.net.http], "Logger#info": [telemetry]}`. Keys are method keys — `Owner#instance_method` or `Owner.singleton_method` — and anything else is a load error. The labels land in the caller's **declared** lane and never in the proven one, so an attribution can never make a diagnostic fire; the call still counts as unresolved, because you told Rigor what that code does and Rigor did not read it. Use it for gems nobody has written a plugin for. |
@@ -215,7 +218,8 @@ effects:
     reach: [rails]
 ```
 
-`rails` — registered by [`rigor-railties`](plugins/rigor-rails.md) — stands for `app/controllers/**`,
+`rails` — registered by `rigor-railties`, which is a distinct plugin from the
+[`rigor-rails`](plugins/rigor-rails.md) convenience grouping — stands for `app/controllers/**`,
 `app/jobs/**`, `app/mailers/**` and `app/channels/**`: every way the outside world enters the
 application. The component plugins also register the narrower `rails-controllers`, `rails-jobs`,
 `rails-mailers` and `rails-channels` if you want one layer's footprint rather than all four. A preset is
@@ -254,6 +258,19 @@ When one method is a deliberate exception, write the narrower envelope on it in
 and no `except:` key is needed. When a whole *kind* of effect is acceptable everywhere, name it in
 `tolerated:` instead of loosening every stanza.
 
+**One stanza can land hundreds of warnings**, one per (method, label) pair — on a mid-size Rails
+application, `match: "app/helpers/**/*.rb"` with `effect: []` produced 343 across 18 files. That is
+the layer telling you what it does rather than a misconfiguration, but it is not a work list either;
+[Effect labels § Envelopes by convention](19-effect-labels.md) walks the recipe for working it down.
+
+A stanza is checked against **proven** labels only, so on a Rails application it cannot fire on
+`io.db.*`, `cache.*`, `telemetry`, `email.send`, `job.enqueue` or any `rails.*`: those come from a
+plugin modelling a framework Rigor did not read, and a claim about unread code must not be able to
+fail your build. The enforcement path for that half is the committed snapshot, whose `rigor effects
+check` marks a declared-lane addition with `≤+` — [Effect labels § What a bound can and cannot
+see](19-effect-labels.md#what-a-bound-can-and-cannot-see), and
+[ADR-103](../adr/103-effect-labels.md) § WD17 for why.
+
 If a layer is not ready for a bound yet, leave `envelopes:` out and start with the committed snapshot
 ([`rigor effects update`](02-cli-reference.md#the-effect-snapshot)) — it needs no declaration at all,
 and stanzas are the second step, written once the record has told you what the layer actually does.

data/docs/manual/04-diagnostics.md

@@ -19,6 +19,18 @@ Every rule has a two-segment `family.rule` identifier:
 | `assert` | `assert_type` checks. |
 | `dump` | `dump_type` notices. |
 
+Every diagnostic carries its identifier in brackets at the end of the
+line, so the ID you need for `# rigor:disable`, for `disable:` and for
+`severity_profile:` is the one you are already looking at:
+
+```text
+app/user.rb:11:3: error: undefined method `lenght' for "hello" [call.undefined-method]
+```
+
+A diagnostic no rule produced — a parse error, a path error, an
+internal analyzer error — has nothing to suppress and carries no
+bracket.
+
 `rigor explain <rule>` prints the full catalogue entry for any
 built-in rule ID; `rigor explain` with no argument lists them all.
 
@@ -27,7 +39,8 @@ built-in rule ID; `rigor explain` with no argument lists them all.
 Each built-in rule has a stable per-rule anchor on this page
 (`#rule-<family>-<name>`, dots written as dashes) — the
 `documentation_url` field in `--format json` and `rigor explain`'s
-`Documentation:` line both point here. The `Evidence` column is
+`Documentation:` line both point here, at this chapter's published
+copy on <https://rigor.typedduck.fail/manual/04-diagnostics/>. The `Evidence` column is
 Rigor's confidence that a firing is a true positive (see
 [Evidence tier](#evidence-tier) below). The one exception is
 `rbs_extended.unsatisfied-conformance`, an `rbs_extended`-family rule
@@ -61,7 +74,7 @@ carries no `documentation_url`.
 | <a id="rule-effect-envelope-exceeded"></a>`effect.envelope-exceeded` | A method performs an effect its declared envelope does not admit — its proven effect labels (its own body plus everything it calls) are not covered by the `%a{pure}` or `%a{rigor:v1:effect …}` bound written on it or on its class. Opt-in twice over: it needs an `effects:` block in `.rigor.yml` and an envelope you wrote. Positioned at the Ruby `def`. Unproven ("and possibly more") effects never fire, and `mutate.local` is tolerated by every envelope. | high |
 | <a id="rule-effect-liskov-widened"></a>`effect.liskov-widened` | An override escapes the envelope written on the method it overrides. A `PgRepo` is usable wherever a `Repo` is, so a `%a{rigor:v1:effect io.db}` on `Repo#find` binds `PgRepo#find` too: an implementation may be purer than the bound it inherits, never less pure. Either what the override *does* exceeds the inherited bound, or the envelope the override *declares for itself* is wider than it. Both sides must be authored — nothing fires unless someone wrote an envelope on the ancestor — and only subclassing counts, not `include`. Positioned at the override's `def`. Needs an `effects:` block. | high |
 | <a id="rule-effect-unknown-label"></a>`effect.unknown-label` | An effect declaration names a label the registry does not know — a typo in an envelope (`%a{rigor:v1:effect io.bd}`), or a member of `effects.tolerated:`. The whole tag then reads as unbounded, so the declaration quietly stops doing anything; this says so. Positioned at the declaration: the `.rbs` line, the `.rb` line for an rbs-inline annotation, or `.rigor.yml` for a config value. `# rigor:disable` comments are not read out of `.rbs` or `.rigor.yml`, so use `disable:` or the baseline there. Only fires where the spelling is evidently meant to be a label (close to a known one, next to a known one, dotted, or retired) — a word nothing resembles stays silent, because you may be opening your own vocabulary. Needs an `effects:` block. | high |
-| <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. | — |
+| <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — except on a run that analyses no file at all (a warm `--incremental` with nothing changed), where only the `.rbs` lane is visible. | — |
 | <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
 | <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
 | <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |

data/docs/manual/08-skills.md

@@ -2,7 +2,7 @@
 
 Rigor bundles a set of **Agent Skills** — structured workflows an AI
 coding agent (Claude Code and compatible tools) can run on your behalf.
-They live in [`skills/`](../../skills/) and are auto-discovered when an
+They live in [`skills/`](../../skills) and are auto-discovered when an
 agent works inside a project that has Rigor available.
 
 Skills are optional. Everything they do, you can do by hand with the

data/docs/manual/11-ci.md

@@ -73,7 +73,7 @@ platform reads to annotate the diff directly, instead of leaving them in
 the job log ([ADR-51](../adr/51-ci-diagnostic-output-formats.md)). These
 layer on the generic `--format json` stream; they add no new diagnostics,
 only a platform-native rendering. Ready-to-copy template files live under
-[`ci-templates/`](ci-templates/).
+[`ci-templates/`](ci-templates).
 
 ### GitHub — inline annotations (the default)
 
@@ -188,6 +188,43 @@ The exit code is unchanged by `--format` — `0` when there are no errors,
 `1` otherwise — so the job still gates the pipeline. `--format json`
 remains available for any other tool that wants the raw diagnostic stream.
 
+## Gating effect drift
+
+If the project uses [effect labels](19-effect-labels.md), add a second
+step beside `rigor check`. It answers a different question — "did this
+branch change what the code *does*?" — and fails for different reasons,
+so keep it as its own step and let the log say which one went red:
+
+```yaml
+      - run: gem install rigortype
+      - run: rigor check
+      - run: rigor effects check
+```
+
+`rigor effects check` exits `0` when the committed
+`.rigor-effects.yml` matches what Rigor just recomputed and `1`
+otherwise — including when the file is missing from the checkout, which
+is what catches the pull request that changed a method and forgot to
+regenerate it. The author's fix is `rigor effects update` plus a commit;
+the regenerated diff is what the reviewer reads.
+
+A bot that wants to report *what this branch changes*, regardless of how
+stale the default branch is, compares against the base instead of the
+committed file:
+
+```sh
+rigor effects diff --baseline <(git show origin/main:.rigor-effects.yml)
+```
+
+`diff` prints the identical comparison and never gates, so it is safe as
+a comment-posting step; `check` takes the same `--baseline`.
+
+With an `effects:` block configured, the snapshot verbs share their
+cached effect summaries with `rigor check`, so running both in one job
+does not re-read the project twice. Exit codes, `--strict-tolerated`, the
+`--no-tolerated-effects` audit switch and the review loop are covered in
+[Effect labels § In CI](19-effect-labels.md).
+
 ## Pinning Rigor's version
 
 The workflow above installs whatever `rigortype` is current at run

data/docs/manual/12-caching.md

@@ -49,6 +49,45 @@ The cache is also schema-versioned: after a Rigor upgrade that
 changes the cache format, the stale cache is purged on the
 first writable run.
 
+## Effect summaries
+
+[Effect labels](19-effect-labels.md) are cached alongside the rest,
+but under their **own** identity: Rigor's effect vocabulary, its
+built-in effect catalogue, and your `effects:` block. Two
+consequences worth knowing:
+
+- **Turning `effects:` on or off does not invalidate the entries
+  your `rigor check` already relies on.** The two identities are
+  separate, so adopting effect labels costs a first collection
+  pass and leaves the diagnostics cache alone. Upgrading to a
+  Rigor whose catalogue changed does the reverse — it re-reads
+  your effects without re-running your check.
+- **The `rigor effects` verbs share those summaries with `rigor
+  check`.** In a job that runs both, the second command pays for
+  the propagation rather than for a second analysis.
+
+The exception is a `rigor effects` run on a project with **no**
+`effects:` block: it collects under an implicit empty block and
+shares no cache with `rigor check`, because a run served from that
+cache would have collected nothing.
+
+**Everything the effect system produces survives a cache hit.** A
+warm `rigor check` reports exactly the `effect.envelope-exceeded`
+warnings a cold one does; there is no configuration in which the
+effect checks fire on the first build of the day and go quiet
+afterwards. The judgment itself is never stored — it is recomputed
+each run from the summaries — so editing an envelope, a
+`tolerated:` list or an `%a{pure}` annotation re-judges your code
+on the next run even though no Ruby file changed, and a warning
+can never outlive the stanza that justified it.
+
+That costs speed in exactly one case. Declaring an envelope
+anywhere opts the project out of the cache-hit fast path, because
+Rigor has to load the analyzer to re-judge: a warm run takes about
+a second on a mid-sized Rails application instead of about a
+quarter of one. A project with `effects:` on and nothing declared
+anywhere pays nothing.
+
 ## How a file is checked for changes
 
 To decide whether a cached entry is still valid, Rigor needs to
@@ -98,7 +137,7 @@ CI detection that `auto` relies on.
 | --- | --- |
 | `rigor check --no-cache` | Run without reading or writing the persistent cache. |
 | `rigor check --clear-cache` | Delete the cache directory, then run. |
-| `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes. |
+| `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). |
 
 There is no config key to disable caching permanently — the

data/docs/manual/15-type-protection-coverage.md

@@ -333,7 +333,7 @@ ones a type actually catches.
 > [Configuration](03-configuration.md)). A project whose gems live in
 > the active Ruby's default gem home — the common `rbenv` / `mise`
 > case with no `--path` set — is invisible to the isolated analyzer by
-> design ([ADR-27](https://github.com/rigortype/rigor/blob/master/docs/adr/27-tool-distribution-model.md)):
+> design ([ADR-27](../adr/27-tool-distribution-model.md)):
 > point Rigor at it with `bundler.bundle_path:`. Until you do, these
 > holes keep the generic `engine_gap` cause instead of `add_rbs` —
 > the label is missing, never wrong.

data/docs/manual/16-rbs-extended-annotations.md

@@ -162,7 +162,7 @@ Every directive above describes what a method returns. Two
 describe what it *does*: `%a{pure}` — rbs' own purity
 annotation, read as "nothing at all" — and
 `%a{rigor:v1:effect <labels>}`, a comma-separated list of bare
-[effect labels](../type-specification/effect-labels.md) the
+[effect labels](19-effect-labels.md) the
 method may not exceed. Both attach to a method or to a `class` /
 `module`, where they distribute to that class's own methods
 (nearest wins), and both tolerate mutating objects the method
@@ -210,7 +210,20 @@ on:
   at the declaration.
 - Without the block, one
   [`effect.annotations-unchecked`](04-diagnostics.md#rule-effect-annotations-unchecked)
-  `:info` per run tells you the annotations are inert.
+  `:info` per run tells you the annotations are inert — from either
+  lane, with one exception: a run that analyses **no file at all**
+  (a warm `rigor check --incremental` with nothing changed) has no
+  synthesised RBS to read, so it reports a `.rbs` annotation and not
+  an inline one. Any run that analyses something reports both.
+
+Two practical notes. Annotating one method in a `.rbs` file forces you to
+declare its whole signature — RBS has no way to annotate a method it does
+not declare — while the rbs-inline form above does not, so prefer the
+inline lane when the bound is all you want. And an envelope is checked
+against the **proven** lane only: a method whose labels all sit in the
+declared (`≤`) lane passes `%a{pure}` in silence.
+[Effect labels](19-effect-labels.md) covers both, with the vocabulary
+these annotations draw from.
 
 ## Higher-kinded type directives
 

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

@@ -140,7 +140,7 @@ Four sections, needing four different decisions:
 
 | Section | What it means | What to do |
 | --- | --- | --- |
-| **Reachable only from test code** | Live test, no production caller | Work these first |
+| **Reachable only from test code** | Live test, no production caller Rigor can see or suspect | Work these first |
 | **Candidates** | Nothing reachable names it | Adjudicate — most are still live |
 | **Cannot decide** | Something can name it at runtime | Read the reason; do not delete from here |
 | **Namespace-only** | A module wrapping live code | Excluded from candidates; count only |
@@ -209,14 +209,23 @@ skip most of a list quickly:
 
 ### Cannot decide: read the reason, do not delete
 
-These were demoted out of `candidates` because something can name the
-class at runtime. Each row says what:
+These were demoted because something can name the class at runtime —
+out of `candidates`, or out of **reachable only from test code**. Each
+row says what:
 
 ```
   1  Handlers::Alpha                     lib/handlers.rb:2
        constantize on an interpolated string (lib/dispatch.rb:14)
 ```
 
+A row demoted out of the test-only section is the second kind, and it
+is the one worth knowing about: a class your specs reference and a
+data file also names — a job in `config/recurring.yml`, a class named
+from a YAML setting — is not a dead production path, because the
+configuration may well be what drives it. The test-only section makes
+a claim about production, so a row Rigor holds evidence against
+belongs here instead, with the file named.
+
 `"Foo".constantize` names `Foo` exactly, so it counts as an ordinary
 reference and never reaches this section. `"Foo::#{key}".constantize`
 can only bound the namespace, so everything under `Foo` is demoted. A
@@ -322,5 +331,5 @@ Running it as a **reporting** job is fine, and is the intended way to
 notice the drift described above: run it on a schedule, publish the
 JSON, and let a person read the trend.
 
-[adr-102]: https://github.com/rigortype/rigor/blob/master/docs/adr/102-unused-code-reachability-report.md
+[adr-102]: ../adr/102-unused-code-reachability-report.md
 [issue-363]: https://github.com/rigortype/rigor/issues/363