rigortype 0.2.1 → 0.2.2

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

@@ -0,0 +1,190 @@
+# RBS::Extended annotations
+
+Plain RBS can say a method returns a `String`. It cannot say it
+returns a *non-empty* string, that a predicate narrows its
+argument on the true branch, or that a class is meant to satisfy
+a structural interface as a checked contract. Rigor reads that
+extra information from **`RBS::Extended` annotations** — ordinary
+RBS `%a{...}` annotations under a reserved `rigor:v1:` key — so
+you can sharpen a signature without leaving RBS and without
+breaking any other RBS tool, which preserves or ignores
+the annotation.
+
+You write these in your `*.rbs` files, on the method or class
+declaration they refine:
+
+```rbs
+%a{rigor:v1:return: non-empty-string}
+def read_name: () -> String
+```
+
+The plain `() -> String` stays the compatibility contract; the
+annotation tells Rigor the return is a non-empty string.
+This page is the *operational* reference — the directives you can
+write and their syntax. For the normative rules (conflict
+handling, merging, provenance) see
+[`docs/type-specification/rbs-extended.md`](../type-specification/rbs-extended.md);
+for the type-model walkthrough see
+[handbook chapter 7](../handbook/07-rbs-and-extended.md).
+
+## Per-method directives
+
+Each directive is one `%a{rigor:v1:<directive> …}` annotation
+written immediately above the `def` it applies to. Multiple
+directives may stack on one method; they compose independently of
+order.
+
+| Directive | Effect |
+| --- | --- |
+| `rigor:v1:return: T` | Override the RBS-declared return type with `T` at every call site. |
+| `rigor:v1:param: name [is] T` | Tighten parameter `name` to `T` — both at overload selection / argument checks *and* inside the method body during inference. The `is` glue word is optional. |
+| `rigor:v1:predicate-if-true target is T` | Refine `target` to `T` on the **true** branch when the call is used as a condition. |
+| `rigor:v1:predicate-if-false target is T` | Refine `target` to `T` on the **false** branch. |
+| `rigor:v1:assert target is T` | Refine `target` after the method returns normally. |
+| `rigor:v1:assert-if-true target is T` | Refine `target` when the method returns a truthy value. |
+| `rigor:v1:assert-if-false target is T` | Refine `target` when the method returns `false` or `nil`. |
+
+`target` is an RBS *parameter name* from the method's own
+signature, or the literal `self`. To refer to an argument, the
+RBS method type must name it (`(untyped value)`, not `(untyped)`).
+
+### Predicates — narrowing through a guard
+
+A predicate teaches Rigor to narrow a variable across the
+branches of a method that tests it — the equivalent of
+TypeScript's type guards or Python's `TypeGuard` / `TypeIs`. A
+true-branch fact alone is enough for `TypeGuard`-style narrowing;
+supplying both branches gives `TypeIs`-style narrowing.
+
+```rbs
+%a{rigor:v1:predicate-if-true value is String}
+%a{rigor:v1:predicate-if-false value is ~String}
+def string?: (untyped value) -> bool
+
+%a{rigor:v1:predicate-if-true self is LoggedInUser}
+def logged_in?: () -> bool
+```
+
+After `if string?(x)`, Rigor types `x` as `String` in the `then`
+branch; in the `else` branch the `~String` negative fact removes
+`String` from its type.
+
+### Assertions — narrowing after a call
+
+An assertion narrows a variable *after* the call returns, the way
+PHPStan models `assert`-style helpers. Use `assert` for a method
+that raises unless the fact holds, and `assert-if-true` /
+`assert-if-false` for a method whose return value carries the
+fact.
+
+```rbs
+%a{rigor:v1:assert value is String}
+def assert_string!: (untyped value) -> void
+
+%a{rigor:v1:assert-if-true value is String}
+def valid_string?: (untyped value) -> bool
+```
+
+After `assert_string!(x)` returns, `x` is `String` for the rest
+of the scope.
+
+## The payload type grammar
+
+The right-hand side of `return:`, `param:`, `assert*`, and
+`predicate-if-*` accepts either:
+
+- an **RBS class name** — `String`, `::Foo::Bar`; or
+- a **refinement payload** — a kebab-case name from the
+  imported-built-in catalogue
+  ([`imported-built-in-types.md`](../type-specification/imported-built-in-types.md)),
+  such as `non-empty-string` or `positive-int`.
+
+Refinement payloads support the parameterised forms
+`non-empty-array[Integer]`, `non-empty-hash[Symbol, Integer]`,
+and the bounded-integer form `int<min, max>`. Type-argument
+positions also accept Symbol / String literal tokens and unions
+of them — `pick_of[T, :name | :email]`,
+`Pick[T, "name" | "email"]` — each lifted to a `Constant<value>`.
+
+Negation with `~T` is allowed on **class-name** payloads (it is
+how the false branch of a predicate is usually written); it is
+**not** yet accepted on refinement-form payloads. For an explicit
+user-authored difference type, prefer `T - U` (see
+[type-operators.md](../type-specification/type-operators.md)).
+
+## `conforms-to` — a checked structural contract
+
+Rigor checks structural compatibility implicitly wherever a value
+flows into a position that needs an interface. The `conforms-to`
+directive makes that contract *explicit and always-checked* on a
+class, regardless of whether any call site currently exercises it
+— useful when a library wants its structural contract to be a
+design assertion:
+
+```rbs
+%a{rigor:v1:conforms-to _RewindableStream}
+class MyBuffer
+end
+```
+
+If the class is missing a method the interface requires, Rigor
+fires
+[`rbs_extended.unsatisfied-conformance`](04-diagnostics.md#rule-rbs_extended-unsatisfied-conformance);
+a satisfied directive is silent. Multiple `conforms-to`
+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.
+
+## Higher-kinded type directives
+
+Two declaration-level directives register and define the
+defunctionalised type constructors behind Rigor's lightweight HKT
+mechanism ([ADR-20](../adr/20-lightweight-hkt.md)). Unlike the
+per-method directives they attach to a `class` / `module` and
+take **space-separated `key=value` pairs** (RBS's annotation
+grammar does not accept nested punctuation):
+
+| Directive | Effect |
+| --- | --- |
+| `rigor:v1:hkt_register: uri=<uri> arity=<int> variance=<v1>,… bound=<class\|untyped>` | Register a type-constructor URI with its arity, per-position variance, and erasure bound. |
+| `rigor:v1:hkt_define: uri=<uri> params=<P1>,… body=<body-text>` | Bind the URI to a type-function body; `body=` consumes the rest of the payload and is parsed into a union tree. |
+
+```rbs
+%a{rigor:v1:hkt_register: uri=json::value arity=1 variance=out bound=untyped}
+%a{rigor:v1:hkt_define: uri=json::value params=K
+   body=nil | true | false | Integer | Float | String |
+        Array[App[json::value, K]] | Hash[K, App[json::value, K]]}
+module JsonOverlay
+end
+```
+
+This is an advanced authoring surface; the worked walkthrough is
+[handbook chapter 12](../handbook/12-lightweight-hkt.md).
+
+## Authoring rules
+
+- The plain RBS signature is always the compatibility contract;
+  annotations only refine or explain it.
+- Always use the explicit, versioned `rigor:v1:` prefix. An
+  unversioned `rigor:` directive is invalid.
+- Multiple annotations on one node are interpreted independently
+  of source order; exact duplicates are idempotent.
+- A directive that **conflicts** with the RBS signature, or two
+  contradictory directives on the same target and flow edge, are
+  reported as diagnostics — Rigor never silently picks a winner.
+- Annotations under unrelated keys belong to other tools; Rigor
+  preserves them untouched. Conversely, exported plain RBS
+  ([RBS erasure](../type-specification/rbs-erasure.md)) drops
+  Rigor-only annotations unless you ask to keep them.
+
+## See also
+
+- [`docs/type-specification/rbs-extended.md`](../type-specification/rbs-extended.md)
+  — the normative grammar and merging rules.
+- [`imported-built-in-types.md`](../type-specification/imported-built-in-types.md)
+  — the reserved refinement-name catalogue.
+- [handbook chapter 7](../handbook/07-rbs-and-extended.md) — the
+  type-model walkthrough.
+- [Inspecting inferred types](05-inspecting-types.md) — the
+  `assert_type` / `dump_type` source helpers, the Ruby-side
+  counterpart to these RBS-side annotations.

data/docs/manual/17-driving-improvement.md

@@ -0,0 +1,160 @@
+# Driving project improvement with `rigor-next-steps`
+
+`rigor-next-steps` is the **single entry point** for "what should we
+do next with Rigor on this project?". You hand it to an AI coding
+agent once; from then on it figures out where the project is on the
+Rigor adoption curve and drives it forward — installing Rigor if
+missing, onboarding the project if it has no config, then routing to
+the right next skill until the project is set up, guarded, and as
+type-protected as you want it.
+
+This chapter is the operator's view of that journey. Each step maps to
+a command you can also run by hand — the skill just drives the whole
+loop for you. The bundled skills it routes to are catalogued in
+[Provided skills](08-skills.md); this chapter is the *workflow* that
+ties them together.
+
+## The loop, in one picture
+
+```
+rigor-next-steps
+   ├─ resolve `rigor` (install via docs/install.md if missing)
+   ├─ no config?  → rigor-project-init   (onboard)
+   └─ otherwise   → rigor skill describe  → the recommended next skill
+                                            ↺ re-run after each step
+```
+
+The engine of the loop is **`rigor skill describe`**. It is cheap and
+side-effect-free — a *presence-only* probe (it stats your config,
+baseline, `sig/`, lockfiles, CI, and editor/MCP configs; it never runs
+`rigor check`) — so an agent can run it freely at any point. Its
+guidance is generated live by your installed Rigor, so it never goes
+stale.
+
+## What `describe` tells you
+
+```sh
+rigor skill describe        # or the alias: rigor describe
+```
+
+```
+# Rigor — next steps for this project
+#
+# Generated live by rigortype 0.2.x; this guidance always
+# reflects your installed version and the project's current state.
+
+## Project state
+- Config file:    .rigor.dist.yml
+- Baseline:       none
+- Project sig/:   present
+- Community RBS:  collection installed
+- CI integration: CI present, Rigor not wired
+- Editor LSP:     .vscode present, Rigor LSP not wired
+- MCP server:     not detected
+
+## Recommended next step
+→ rigor-ci-setup — Rigor is configured but not wired into CI — lock in the regression guard.
+  Load it: rigor skill rigor-ci-setup
+
+## All skills you can run next
+  …the full catalogue, each with its current one-line description…
+
+## For the agent
+  …how to act on the recommendation, and how to refine it from `rigor check` findings…
+```
+
+Run it, follow the **Recommended next step**, complete that skill, then
+run it again. The recommendation advances as the project's state
+changes (e.g. `project-init → rbs-setup → ci-setup → …`).
+
+## The journey, step by step
+
+The recommendation walks a sensible adoption order. For each stage,
+the equivalent hand-commands are in the linked chapter.
+
+| Stage | Recommended skill | What it does | By hand |
+| --- | --- | --- | --- |
+| **Onboard** | `rigor-project-init` | Detect the stack, pick plugins, write `.rigor.dist.yml`, optionally snapshot a baseline. | [Provided skills](08-skills.md), [Configuration](03-configuration.md) |
+| **Community RBS** | `rigor-rbs-setup` | `rbs collection install` so RBS-less gems stop typing as `Dynamic`. | [Configuration](03-configuration.md) (`rbs_collection`) |
+| **Rails plugins** | `rigor-plugin-tune` | If Rails is locked but no Rails plugins are enabled, wire them so ActiveRecord / routes / i18n calls resolve. | [Using plugins](07-plugins.md) |
+| **See findings** | — | `rigor check` for bugs; `rigor coverage --protection` for "add a type here". | [CLI reference](02-cli-reference.md), [Type-protection coverage](15-type-protection-coverage.md) |
+| **Raise protection** | `rigor-protection-uplift` | Close type-protection holes — sig-gen first, minimal hand-RBS, under a double gate. | [Type-protection coverage](15-type-protection-coverage.md) |
+| **Pay down debt** | `rigor-baseline-reduce` | Work an existing baseline down rule by rule. | [Baselines](06-baseline.md) |
+| **Guard it** | `rigor-ci-setup` | Run Rigor in CI with inline PR/MR diagnostics. | [Running Rigor in CI](11-ci.md) |
+| **Editor / agent** | `rigor-editor-setup` / `rigor-mcp-setup` | Wire `rigor lsp` into your editor / `rigor mcp` into your AI agent. | [Editor integration](09-editor-integration.md), [MCP server](10-mcp-server.md) |
+| **Teach a DSL** | `rigor-monkeypatch-resolve` / `rigor-plugin-author` | Resolve your own monkey-patches via `pre_eval:`, or author a plugin. | [Configuration](03-configuration.md), [Provided skills](08-skills.md) |
+| **Upgrade / validate** | `rigor-upgrade` / `rigor-doctor` | Adopt a new Rigor version cleanly; validate the setup is healthy. | [Baselines](06-baseline.md), [Troubleshooting](13-troubleshooting.md) |
+
+## A worked walk-through
+
+A typical Rails app, freshly installed Rigor, no config:
+
+1. **`describe`** → *"no Rigor configuration yet — start here"* → run
+   `rigor-project-init`. It writes `.rigor.dist.yml` (`target_ruby`,
+   `paths:`, the Rails plugins) and snapshots a baseline if the first
+   `rigor check` reports many diagnostics.
+2. **`check` finds real bugs.** On a type-conscious Rails app the
+   plugins resolve hundreds of framework calls *and* surface genuine,
+   RBS-invisible bugs — strong-params keys that are not columns
+   (`permit :start_date_jst` where the column is `start_date`), missing
+   or doubled i18n keys. These are the onboarding payoff.
+3. **`coverage --protection` shows where types help.** A plain library
+   slice might report e.g. `17.5%` protected, with an "add a type here"
+   list pinpointing the untyped receivers.
+4. **`rigor-protection-uplift` closes the cheap holes.** sig-gen first,
+   then a *minimal true* hand-RBS for the residual — e.g. a seven-line
+   RBS for an external gem with no signatures can lift a slice's
+   protection from `13%` to `26%` with **zero new diagnostics** (the
+   skill verifies both: protection up *and* `rigor check` stays clean).
+5. **Acknowledge mode + a baseline** snapshot today's diagnostics so
+   any *new* one is a visible regression. Inject a typo'd i18n key and
+   `rigor check` flags it immediately.
+6. **`describe` advances** to `rigor-ci-setup`, then editor / MCP — and
+   the loop continues whenever you want the next move.
+
+## Refining the recommendation from `check`
+
+`describe`'s headline is presence-only — it never runs `rigor check`,
+which keeps it fast. But the *best* next step often depends on what
+`check` would find, so the **"For the agent"** section tells the agent
+to refine the choice from a `rigor check` it runs (or already ran):
+
+- errors present, no baseline yet → `rigor-baseline-reduce`
+- a `call.unresolved-toplevel` / `call.undefined-method` cluster on
+  your own monkey-patches → `rigor-monkeypatch-resolve`
+- framework calls typing as `Dynamic` with no matching plugins enabled
+  → `rigor-plugin-tune`
+- `RBS classes available: 0` or a `configuration-error` → `rigor-doctor`
+
+If you are following the loop by hand, the same rules apply: run
+`rigor check`, and let its output pick the most useful next skill.
+
+## Practical notes
+
+- **`target_ruby` floor.** Rigor's bundled parser (Prism) supports a
+  recent Ruby floor; if you set `target_ruby` below it, `rigor check`
+  tells you the minimum and where to read the right value (your
+  `Gemfile.lock` `RUBY VERSION` or `.ruby-version`). `rigor-project-init`
+  picks a compatible value for you.
+- **List the individual Rails plugins, not the umbrella.** Put
+  `rigor-activerecord`, `rigor-actionpack`, … in `plugins:` — not
+  `rigor-rails` (a convenience meta-gem, which is not a single plugin).
+  If you try the umbrella, the load error lists the individual plugins
+  to use.
+- **`RBS classes available: 0` is a broken setup, not a clean run.** If
+  `rigor check` prints that warning, the RBS environment failed to build
+  (usually a duplicate declaration in `signature_paths:`) — fix it
+  before trusting the (near-empty) results. `rigor-doctor` helps locate
+  it.
+- **A missing path is skipped, not fatal.** `rigor check app lib` on a
+  project with no `lib/` analyses `app` and warns about `lib` — it does
+  not abort.
+
+## See also
+
+- [Provided skills](08-skills.md) — the per-skill reference for every
+  destination this loop routes to.
+- [Installing Rigor](01-installation.md) — the install step
+  `rigor-next-steps` runs first.
+- [Type-protection coverage](15-type-protection-coverage.md) — the
+  measurement `rigor-protection-uplift` acts on.

data/docs/manual/README.md

@@ -0,0 +1,87 @@
+# The Rigor User Manual
+
+How to install, run, configure, and operate Rigor. Where the
+[handbook](../handbook/README.md) teaches the *type model* —
+what carriers Rigor infers and why — this manual is the
+*operational* reference: the command line, the configuration
+file, the diagnostic catalogue, and the workflows for adopting
+Rigor on a real project.
+
+The two are companions. Reach for the handbook to understand
+what a diagnostic *means*; reach for the manual to look up the
+flag, key, or command that *acts* on it.
+
+## Contents
+
+### Getting started
+
+1. [Installing Rigor](01-installation.md) — `mise`, `asdf`,
+   `gem install`, Nix, and the dev-container guidance. Rigor
+   is a tool, not a project dependency.
+17. [Driving project improvement with `rigor-next-steps`](17-driving-improvement.md) —
+    the single-entry-point loop: onboard, see what Rigor finds,
+    raise type-protection, guard it in CI — driven by
+    `rigor skill describe`.
+14. [Rigor for Rails — step-by-step setup with mise](14-rails-quickstart.md) —
+    install Ruby 4.0 + Rigor via `mise`, activate the Rails
+    plugin set, run `rigor check`, and share the config with
+    your team in about ten minutes.
+
+### Reference
+
+2. [CLI command reference](02-cli-reference.md) — every
+   subcommand (`check`, `annotate`, `type-of`, `sig-gen`,
+   `baseline`, `triage`, `lsp`, …), its flags, and its exit
+   codes.
+3. [Configuration](03-configuration.md) — the `.rigor.yml`
+   key reference, config discovery, and `includes:` layering.
+4. [Diagnostics](04-diagnostics.md) — the rule-ID catalogue,
+   severity profiles, and `# rigor:disable` suppression.
+5. [Inspecting inferred types](05-inspecting-types.md) — the
+   `assert_type` / `dump_type` source helpers and the
+   `rigor annotate` / `rigor type-of` commands.
+16. [RBS::Extended annotations](16-rbs-extended-annotations.md) —
+    the `%a{rigor:v1:…}` annotations you write in `*.rbs` files:
+    `return:` / `param:` overrides, predicate and assertion
+    narrowing, `conforms-to`, and the HKT directives.
+
+### Adopting Rigor on a project
+
+6. [Baselines](06-baseline.md) — `.rigor-baseline.yml`, the
+   `rigor baseline` subcommands, and `rigor triage`.
+7. [Using plugins](07-plugins.md) — activating framework and
+   gem plugins through the `plugins:` config key. Per-plugin
+   user docs live under [Plugin reference](plugins/README.md).
+8. [Provided skills](08-skills.md) — the bundled Agent Skills
+   the `rigor-next-steps` loop routes to: onboarding, RBS /
+   plugin setup, protection uplift, baseline reduction, CI /
+   editor / MCP wiring, and plugin authoring.
+15. [Type-protection coverage](15-type-protection-coverage.md) —
+    measuring whether a bug would be *caught*, fusing your types
+    and your tests into one safety net (`rigor coverage
+    --protection [--mutation --with-tests --include-dynamic]`).
+
+### Integration and operations
+
+9. [Editor integration](09-editor-integration.md) — wiring
+   `rigor lsp` into Neovim, VS Code, Helix, and Emacs.
+10. [MCP server](10-mcp-server.md) — exposing Rigor's
+    analysis tools to AI coding agents (Claude Code, Cursor,
+    Cline, …) via `rigor mcp`.
+11. [Running Rigor in CI](11-ci.md) — a clean CI job, inline
+    PR/MR diagnostics (SARIF / GitHub Actions / GitLab Code
+    Quality), copy-paste [templates](ci-templates/), and
+    version pinning.
+12. [Caching](12-caching.md) — where the cache lives, what
+    invalidates it, and how to clear it.
+13. [Troubleshooting](13-troubleshooting.md) — common
+    problems and their fixes.
+
+## See also
+
+- [The Rigor Handbook](../handbook/README.md) — the type-model
+  walkthrough.
+- [`docs/types.md`](../types.md) — one-page type-system guide.
+- [`docs/type-specification/`](../type-specification/README.md)
+  — the normative spec corpus.
+- [`docs/adr/`](../adr/) — architecture decision records.

data/docs/manual/ci-templates/README.md

@@ -0,0 +1,58 @@
+# CI setup templates
+
+Copy-paste CI configuration for running Rigor in your project's pipeline.
+Each runs Rigor in its **own isolated job** on Ruby 4.0 (see
+[chapter 11, "Running Rigor in CI"](../11-ci.md) for why isolation is
+required) and surfaces diagnostics inline on the pull / merge request via a
+CI-native output format ([ADR-51](../../adr/51-ci-diagnostic-output-formats.md)).
+
+`ruby/setup-ruby` provides **prebuilt** Ruby 4.0.x binaries for
+`ubuntu-latest` — setup is fast (~0.3 s), not a compile-from-source
+wait. Verified 2026-06-13: `setup-ruby` resolves `ruby-version: "4.0"`
+to Ruby 4.0.5 from the runner tool cache.
+
+| File | Copy it to | What it does |
+| --- | --- | --- |
+| [`github-actions-annotations.yml`](github-actions-annotations.yml) | `.github/workflows/rigor.yml` | **The default.** Workflow commands → inline PR annotations. No upload step, no permissions, works on every repo. |
+| [`github-actions-sarif.yml`](github-actions-sarif.yml) | `.github/workflows/rigor.yml` | SARIF 2.1.0 → GitHub code scanning (Security tab + PR alerts). Needs code scanning — public repo, or private with GitHub Advanced Security. |
+| [`github-actions-reviewdog.yml`](github-actions-reviewdog.yml) | `.github/workflows/rigor.yml` | reviewdog → inline PR **review comments**. Needs `pull-requests: write`. |
+| [`gitlab-ci.yml`](gitlab-ci.yml) | `.gitlab-ci.yml` (or `include:` it) | GitLab Code Quality report → the merge-request widget. |
+
+Pick **one** GitHub template. **Default to annotations** — it is the only
+one that works on every repository with zero setup. Use SARIF when code
+scanning is available (public repo, or private with GitHub Advanced
+Security) and you want the Security tab; use reviewdog for threaded review
+comments (it works the same way against GitLab, Gerrit, Bitbucket, and Gitea
+— see the [`rigor-ci-setup`](../../../skills/rigor-ci-setup/SKILL.md) skill).
+All run Rigor the same way — only the output format and publish step differ.
+
+## Other runners (generic recipe)
+
+On any CI system, the four steps are: provision Ruby 4.0, install
+`rigortype`, run `rigor check`, and (optionally) publish the report.
+
+```sh
+# 1. Ruby 4.0 must be the active Ruby (rbenv/asdf/mise/container image).
+# 2. Install Rigor — kept out of your project's Gemfile (see ADR-27).
+gem install rigortype
+# 3. Run it. Pick the format your platform renders, or plain text for logs.
+rigor check                           # human-readable, exit 1 on errors
+rigor check --format sarif      > rigor.sarif      # SARIF 2.1.0
+rigor check --format gitlab     > codequality.json # GitLab Code Quality
+rigor check --format checkstyle > checkstyle.xml   # reviewdog / Jenkins
+rigor check --format junit      > junit.xml        # test-report CIs
+rigor check --format json       > rigor.json       # generic machine stream
+```
+
+The exit code is `0` when there are no errors and `1` otherwise, so the
+step gates the pipeline regardless of format. Redirect the report to a file
+with `>`; if your platform fails the job on a non-zero exit before the
+publish step runs, mark the check step "continue on error" and publish
+unconditionally (the GitHub SARIF template shows the pattern).
+
+## Pinning Rigor's version
+
+These templates install the latest `rigortype` at run time. To pin it — and
+keep CI reproducible — see [chapter 11 § "Pinning Rigor's version"](../11-ci.md#pinning-rigors-version)
+(a CI-only `.github/rigor/Gemfile` that Dependabot can update, or a pinned
+`gem install rigortype -v "X.Y.Z"`).

data/docs/manual/plugins/README.md

@@ -0,0 +1,86 @@
+# Plugin reference
+
+User-facing documentation for each bundled Rigor plugin — what
+it checks, its configuration keys, what it infers, and its
+limitations. For *activating* plugins in general, see
+[Using plugins](../07-plugins.md); to *write* one, see the
+[examples/](../../../examples/README.md) walkthroughs and the
+[`rigor-plugin-author` skill](../08-skills.md).
+
+All plugins ship bundled in `rigortype` — no separate install.
+The full catalogue, with a one-line scope for every plugin, is
+[plugins/README.md](../../../plugins/README.md).
+
+## Available pages
+
+- [rigor-activerecord](rigor-activerecord.md) — ActiveRecord
+  finder / relation typing and schema-checked columns.
+- [rigor-rails-routes](rigor-rails-routes.md) — `*_path` / `*_url`
+  helper validation against a parsed `config/routes.rb`.
+- [rigor-rails-i18n](rigor-rails-i18n.md) — `t(...)` / `I18n.t(...)`
+  key, per-locale coverage, and interpolation validation.
+- [rigor-actionpack](rigor-actionpack.md) — controller route
+  helpers, filter chains, render targets, strong-params keys.
+- [rigor-activestorage](rigor-activestorage.md) — `has_*_attached`
+  attachment-accessor typing on AR models.
+- [rigor-activejob](rigor-activejob.md) — `Job.perform_*` argument
+  arity against the discovered `#perform`.
+- [rigor-actionmailer](rigor-actionmailer.md) — mailer action
+  existence / arity and missing-view-template detection.
+- [rigor-factorybot](rigor-factorybot.md) — factory + attribute
+  (+ AR column) validation for `FactoryBot.create` / `build` / ….
+- [rigor-rails](rigor-rails.md) — convenience grouping of the seven
+  Tier 1+2 Rails plugins (not a checker itself).
+- [rigor-dry-types](rigor-dry-types.md) — `Types::*` alias
+  resolution; the dry-rb foundation (no diagnostics of its own).
+- [rigor-dry-struct](rigor-dry-struct.md) — synthesises
+  `Dry::Struct` `attribute` readers (precise with dry-types).
+- [rigor-dry-schema](rigor-dry-schema.md) — recognises dry-schema
+  declarations; publishes the typed-key table (fact-only).
+- [rigor-dry-validation](rigor-dry-validation.md) — recognises
+  `Dry::Validation::Contract` subclasses; result-API RBS overlay.
+- [rigor-sinatra](rigor-sinatra.md) — narrows the route-block
+  `self` so `params` / `redirect` / `halt` / … resolve.
+- [rigor-rspec](rigor-rspec.md) — RSpec `let` / `subject`
+  duplicate and self-reference checks.
+- [rigor-sorbet](rigor-sorbet.md) — read an existing Sorbet
+  codebase (`sig` blocks, RBI, `T.*` assertions) as a type
+  source (full guide: [handbook ch. 10](../../handbook/10-sorbet.md)).
+- [rigor-devise](rigor-devise.md) — synthesises the methods a
+  `devise :strategy` declaration mixes into a model (no diagnostics).
+- [rigor-statesman](rigor-statesman.md) — validates `transition_to(:state)`
+  against the states declared in a `state_machine` block.
+- [rigor-mangrove](rigor-mangrove.md) — sharpens Mangrove
+  `Result` / `Option` unwrap types and synthesises `Enum` variants.
+- [rigor-pundit](rigor-pundit.md) — policy-class existence and
+  `authorize(record, :action)` predicate validation.
+- [rigor-sidekiq](rigor-sidekiq.md) — Sidekiq `Worker.perform_*`
+  argument arity against the discovered `#perform`.
+- [rigor-actioncable](rigor-actioncable.md) — `broadcast_to` channel
+  existence and `ActionCable.server.broadcast` stream-name validation.
+- [rigor-minitest](rigor-minitest.md) — local-variable narrowing
+  through Minitest / Test::Unit assertions and spec matchers.
+- [rigor-graphql](rigor-graphql.md) — GraphQL-Ruby type / enum / input
+  / mutation table publication (cross-plugin facts, no diagnostics).
+- [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
+  argument validation (out-of-range codes, unknown status symbols).
+- [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher
+  column / association validation against the AR model index.
+- [rigor-hanami](rigor-hanami.md) — Hanami::Action `#handle` protocol
+  enforcement + request/response parameter typing (ADR-28).
+- [rigor-typescript-utility-types](rigor-typescript-utility-types.md) —
+  `Pick` / `Omit` / `Partial` / … mapped onto Rigor shape projections.
+- [rigor-rbs-inline](rigor-rbs-inline.md) — ingests `# @rbs` inline
+  comments as enforced RBS contracts (ADR-32).
+- [rigor-activesupport-core-ext](rigor-activesupport-core-ext.md) —
+  opt-in RBS bundle for ActiveSupport core_ext (the biggest Rails FP source).
+
+The browser **playground** (`rigor playground`) is infrastructure, not
+a checker plugin — it has no page here; see the
+[CLI reference](../02-cli-reference.md) and
+[ADR-29](../../adr/29-browser-playground.md).
+
+_Every bundled checker plugin has a page above; each plugin's in-tree
+[`README.md`](../../../plugins/README.md) now covers its internals
+(layout, architecture, the contract surfaces it exercises) and links
+back up to its page here._

data/docs/manual/plugins/rigor-actioncable.md

@@ -0,0 +1,78 @@
+# rigor-actioncable
+
+Validates ActionCable broadcast call sites against a statically
+discovered channel index: `<X>Channel.broadcast_to(record, data)`
+checks that the channel class exists, and
+`ActionCable.server.broadcast("stream_name", data)` checks that the
+literal stream name was registered with `stream_from` in some channel.
+It reads source only — no `actioncable` runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-actioncable
+```
+
+## What it checks
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "chat_room_5"
+  end
+end
+
+ChatChannel.broadcast_to(room, message: "hi")               # info:  channel exists
+ActionCable.server.broadcast("chat_room_5", body: "hi")     # info:  registered stream
+ChartChannel.broadcast_to(room, message: "hi")              # error: no channel (did you mean ChatChannel?)
+ActionCable.server.broadcast("chat_room_42", body: "hi")    # warning: no such stream registration
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.actioncable.broadcast-target` | info | `<X>Channel.broadcast_to(...)` matched a discovered channel |
+| `plugin.actioncable.broadcast-stream` | info | `ActionCable.server.broadcast("...", ...)` matched a registered `stream_from` literal |
+| `plugin.actioncable.unknown-channel` | error | the receiver ends in `Channel` but is not in the index (with a did-you-mean) |
+| `plugin.actioncable.unknown-stream` | warning | the literal stream name matched no `stream_from` registration (with a did-you-mean) |
+| `plugin.actioncable.load-error` | warning | channel discovery failed (parse/read error) — once per file |
+
+The `unknown-stream` check is **suppressed** when any discovered
+channel registers a dynamic stream (`stream_from interpolated_string`
+or `stream_for record`) — the absence of a literal match doesn't prove
+the stream is invalid. Non-`Channel` receivers and non-literal stream
+arguments pass through silently.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-actioncable
+    config:
+      channel_search_paths: ["app/channels"]                                            # default
+      channel_base_classes: ["ApplicationCable::Channel", "ActionCable::Channel::Base"] # default
+```
+
+## Limitations
+
+- **Direct-superclass match only.** An indirect chain (`AdminChannel <
+  BaseChannel < ApplicationCable::Channel`) needs `BaseChannel` listed
+  in `channel_base_classes`.
+- **Action methods are indexed, not validated.** Channel actions are
+  invoked client-side via `subscription.perform("action", data)`; Rigor
+  does not analyse JavaScript, so the action index is informational.
+- **`broadcast_to` arity is not checked** — it accepts any record + any
+  data hash.
+- **Indirect `stream_from`** (registered inside a helper method rather
+  than directly in the channel body) is out of scope.
+- **Bare `broadcast(...)`** without an explicit `ActionCable.server`
+  receiver is skipped to avoid false positives on unrelated methods.
+
+## Plugin internals
+
+The channel discoverer / index and the contract surfaces this plugin
+exercises are in the
+[plugin's README](../../../plugins/rigor-actioncable/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.