rigortype 0.3.3 → 0.3.5

data/docs/manual/03-configuration.md

@@ -70,7 +70,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. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
 ### Config validation warnings
@@ -174,6 +174,106 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 | `plugins_io.allowed_paths` | Array | `[]` | Filesystem paths plugins may read. |
 | `plugins_io.allowed_url_hosts` | Array | `[]` | URL hosts plugins may fetch from when `network: allowlist`. |
 
+### 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:`. 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. |
+| `effects.envelopes` | Array | `[]` | Effect envelopes by **convention**, so a whole architectural layer is bounded by one stanza instead of a per-method annotation. Each entry names exactly one of `match:` (a project-relative path glob over the files a class is defined in) or `namespace:` (a constant glob: `*` is one segment, `**` is one or more), plus `effect:` — the labels the selected classes may perform, or `[]` for pure. Nearest wins: a per-method annotation beats a class-level one, which beats a stanza; among stanzas the **first** match wins. See the example below. |
+| `effects.tolerated` | Array | `[]` | Labels your project has decided not to act on. Applied when a bound or a difference is **judged**, never when a record is written, and **per origin**: `Logger#info` carries `io` and `telemetry` together, so `tolerated: [telemetry]` frees the `io` that came with the logging and leaves an `io.fs.read` from a `File.read` in the same method exactly where it was. `rigor check --no-tolerated-effects` (and the same flag on `rigor effects check`) re-judges as if the list were empty — the audit switch for the policy. |
+
+Want the block on without writing it? The
+[`effects-on-by-default`](02-cli-reference.md#rigor-show-bleedingedge)
+bleeding-edge feature (`bleeding_edge: [effects-on-by-default]`) makes a
+config with no `effects:` key at all behave as `effects: {}` — collection,
+`effects.check`, and everything else on this page all turn on at their
+defaults. It only fills an *absence*: write `effects: false` and you stay
+opted out regardless, and any `effects:` block you do write is left exactly
+as written. It previews what becomes the default at **v0.4.0**
+([ADR-103](../adr/103-effect-labels.md) § WD15).
+
+#### Entry-point presets
+
+`reach:` asks "whose footprint should the record cover", and on a framework the honest answer is a fact
+about the framework rather than about your code. So the plugin that models it names the set, and you
+adopt it:
+
+```yaml
+plugins:
+  - rigor-railties
+  - rigor-activerecord
+  - rigor-actionpack
+
+effects:
+  snapshot:
+    reach: [rails]
+```
+
+`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
+just a name for globs; mixing the two in one list is fine.
+
+Listing the plugin is what registers its preset, so `reach: [rails]` without `rigor-railties` in
+`plugins:` is an error saying so.
+
+#### Envelopes by convention
+
+The `envelopes:` list is the surface that pays on day one, before you have written any RBS:
+
+```yaml
+effects:
+  envelopes:
+    - match: "app/presenters/**/*.rb"   # presenters render; they do not query
+      effect: []
+    - namespace: "Policies::*"          # Policies::Edit, not Policies::Admin::Edit
+      effect: [mutate.local]
+    - match: "app/jobs/**/*.rb"
+      effect: [io]
+  tolerated: [telemetry]
+```
+
+A stanza attaches its bound to every method of every class it selects, exactly as an annotation on the
+class would. A method that exceeds it gets one `effect.envelope-exceeded` at its `def`, naming the
+stanza it broke:
+
+```
+app/presenters/user_presenter.rb:14:1: warning: Method Presenters::User#render performs io.fs.read
+  (File.read), but is declared effect: [] at .rigor.yml effects.envelopes[0], so io.fs.read exceeds
+  the envelope.
+```
+
+When one method is a deliberate exception, write the narrower envelope on it in RBS — nearest wins,
+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.
 ### Reserved for other implementations
 
 | Key | Type | Default | Meaning |

data/docs/manual/04-diagnostics.md

@@ -27,7 +27,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
@@ -58,6 +59,10 @@ carries no `documentation_url`.
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
 | <a id="rule-static-value-use-void"></a>`static.value-use.void` | A value recovered from an author-declared `-> void` return is used in value context (an assignment right-hand side, a call receiver, or a call argument). Off by default; reaches a run only through the `use-of-void-value` bleeding-edge feature (ADR-100). A bare-statement `void` call and a legitimate `top` value both stay silent. | high |
+| <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. 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 |
@@ -104,8 +109,8 @@ are:
 
 | Severity | Rules |
 | --- | --- |
-| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker` |
-| `info` | `flow.unreachable-clause`, `dump.type` |
+| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker`, `effect.envelope-exceeded`, `effect.liskov-widened` |
+| `info` | `flow.unreachable-clause`, `dump.type`, `effect.unknown-label`, `effect.annotations-unchecked` |
 | `off` | `call.self-undefined-method`, `static.value-use.void` |
 
 Everything else emits as `error`. For one rule under all three

data/docs/manual/11-ci.md

@@ -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

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

@@ -20,6 +20,27 @@ def read_name: () -> String
 
 The plain `() -> String` stays the compatibility contract; the
 annotation tells Rigor the return is a non-empty string.
+
+You may also write any of them **in a `.rb` file**, as an
+rbs-inline `# @rbs %a{…}` comment — `%a{}` is rbs-inline's own
+upstream grammar, and the annotation reaches Rigor on the same
+path the generated signature does:
+
+```rb
+# rbs_inline: enabled
+
+class Reader
+  # @rbs %a{rigor:v1:return: non-empty-string}
+  # @rbs return: String
+  def read_name = "x"
+end
+```
+
+This needs the `rbs-inline` library installed; Rigor ingests
+inline annotations by default when it is
+([ADR-93](../adr/93-default-rbs-inline-ingestion.md)). There is
+no Rigor-only comment dialect: `# rigor:` comments remain
+suppression-only.
 This page is the *operational* reference — the directives you can
 write and their syntax. For the normative rules (conflict
 handling, merging, provenance) see
@@ -135,6 +156,75 @@ directives on one class combine like an intersection of
 interfaces. The directive is purely additive — a class that
 already satisfies the interface type-checks with or without it.
 
+## Effect envelopes — bounding what a method *does*
+
+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](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
+itself allocated and never let out:
+
+```rbs
+class UserRepository
+  %a{rigor:v1:effect io.db, nondet.time}
+  def find: (Integer) -> User
+
+  %a{pure}
+  def slug: (String) -> String
+end
+```
+
+The same two work as rbs-inline comments in a `.rb` file:
+
+```rb
+# rbs_inline: enabled
+
+class UserRepository
+  # @rbs %a{rigor:v1:effect io.db}
+  # @rbs id: Integer
+  # @rbs return: User
+  def find(id) = User.find(id)
+
+  # @rbs %a{pure}
+  # @rbs return: String
+  def slug(s) = s.strip.downcase
+end
+```
+
+Three things follow, and all three need an `effects:` block in
+`.rigor.yml` — an annotation alone never turns effect collection
+on:
+
+- A method whose proven effects escape its bound fires
+  [`effect.envelope-exceeded`](04-diagnostics.md#rule-effect-envelope-exceeded),
+  positioned at the Ruby `def`.
+- A label the registry does not recognise makes the **whole
+  annotation** read as unbounded — a typo can never manufacture
+  a finding — and, where the spelling is evidently meant to be a
+  label, says so as
+  [`effect.unknown-label`](04-diagnostics.md#rule-effect-unknown-label)
+  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 — 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
 
 Two declaration-level directives register and define the