rigortype 0.2.1 → 0.2.2

data/skills/rigor-protection-uplift/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rigor-protection-uplift
+description: |
+  Close the type-protection holes `rigor coverage --protection` surfaces: for each unprotected dispatch site, run `rigor sig-gen` first, hand-author only the minimal residual annotation, then verify with a double gate — the site becomes protected AND `rigor check` gains no new diagnostic. Triggers: "raise type protection", "add types where Rigor can't catch bugs", "act on coverage --protection / --mutation output", "make more of this code bug-catchable". NOT for Rigor's own `lib/` or the bundled plugins (use `rigor sig-gen` directly there and treat gaps as engine signal), and NOT for first-time setup (use rigor-project-init).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Protection Uplift
+
+`rigor coverage --protection` (Tier 1) and `rigor coverage --protection
+--mutation` (Tier 2) *surface* "add a type here" — they never author the
+type. This skill *acts* on that surfacing under the discipline that keeps
+Rigor false-positive-safe: protection goes up, and not one line of
+working code starts reporting a new diagnostic.
+
+## When to use
+
+- A user wants to raise how much of their code Rigor can actually catch
+  bugs in.
+- You have `coverage --protection` output (an "add a type here" list) and
+  want to close it.
+
+## When NOT to use
+
+- **Rigor's own `lib/`, or the bundled `plugins/` / `examples/`** — the
+  self-check tree. Hand-authoring types there collides with the
+  sig-gen-first ethos; run `rigor sig-gen` directly and treat residual
+  gaps as engine signal to report, not a private fix.
+- **"Make my code more precise" with no protection goal** — that is
+  `rigor coverage` (precision), not `--protection`.
+- **A project with no Rigor config yet** — onboard first with
+  `rigor-project-init`.
+
+## Load-bearing rules (read before touching a single type)
+
+1. **The signal prioritises and verifies; the contract sources the
+   type.** Never write the type the coverage/mutation signal "wants".
+   Write the type the code *actually has*, derived from the
+   implementation and its callers. A type guessed from the signal is a
+   false-confidence type — worse than no type.
+2. **sig-gen first.** A hand-written annotation is only the *residual*
+   `rigor sig-gen` cannot reach. Every residual is a sig-gen-improvement
+   to report, not just a private fix.
+3. **"Minimal" = annotation footprint, not minimal-to-kill-the-mutant.**
+   Optimising literally for mutant death games the metric. Add the
+   smallest *true* annotation that models the contract; if that also
+   kills the mutant, good.
+4. **Robustness (ADR-5).** Tighten returns, keep parameters lenient. An
+   over-tight param annotation breaks callers and breaches the
+   false-positive discipline.
+
+## Procedure
+
+### Phase 1 — surface the holes
+
+```sh
+rigor coverage --protection --format json PATHS
+```
+
+Read the ranked "add a type here" list (`count`, `method_name`,
+`examples`). Optionally confirm the highest-traffic ones actually buy
+catching power with the Tier 2 deep dive:
+
+```sh
+rigor coverage --protection --mutation --format json   # changed-files by default
+```
+
+### Phase 2 — sig-gen first
+
+```sh
+rigor sig-gen --diff PATHS      # inspect; --write to apply
+```
+
+Adopt every concrete inferred signature. Note where sig-gen emits
+`untyped` for a site on the "add a type here" list — that is the
+**residual** Phase 3 owns.
+
+### Phase 3 — author the residual (cheapest carrier per hole class)
+
+| Hole class                          | Cheapest carrier                              |
+| ----------------------------------- | --------------------------------------------- |
+| `Dynamic` method return             | annotate that method's return in `sig/…rbs`   |
+| `Dynamic[top] \| nil` ivar read     | `# @rbs @field: T` (ADR-58 territory)         |
+| untyped param feeding the receiver  | a *lenient* param annotation                  |
+
+Write the minimal true type. Prefer annotating the *upstream* source of
+the Dynamic (the method return / the ivar) over the call site itself.
+
+**Trap (carrier-additivity):** a sidecar `sig/…rbs` is NOT purely
+additive. Declaring a class there flips it from inference-mode to
+RBS-declared mode and *drops every member the RBS omits* — a lone
+`def formatted: () -> String` can make Rigor forget the inferred
+`initialize` and reject `Money.new(500)`. So either (1) adopt the full
+Phase-2 sig-gen base into the file and add the residual on top, or
+(2) use an in-place additive carrier (rbs-inline `#:` / a
+`%a{rigor:v1:…}` return-override) that annotates the method without
+re-declaring the class. "Minimal footprint" means the smallest *true*
+type, never the smallest *file*.
+
+### Phase 4 — double-gate verify (both must hold)
+
+```sh
+rigor coverage --protection PATHS   # (a) the site is now protected / ratio up
+rigor check PATHS                   # (b) no NEW diagnostic vs the post-sig-gen baseline
+```
+
+If (b) regresses, the annotation modeled the wrong contract — **revert
+it**, do not suppress the diagnostic. If (a) did not move, the carrier
+was wrong (often: you typed the call site, not the upstream Dynamic
+source). Gate (b) is a *diff* against the post-sig-gen state, not an
+absolute "zero diagnostics" — sig-gen itself can surface the
+acknowledge-mode FP envelope a project baseline absorbs; this skill owns
+only the increment it adds.
+
+### Phase 5 — feed the residual back
+
+File each Phase-3 residual as a sig-gen gap (what shape did inference
+miss?). The hand annotation is the stopgap; the durable fix is raising
+inference so the residual disappears.
+
+## Honest bounds
+
+Hand-RBS uplift is a finisher, not a path to 80% protection. The
+dominant remaining holes after this loop are intractable from
+annotation alone — external-gem Dynamic receivers, polymorphic value
+types, generic type parameters, dynamically-built classes. Those need
+parametric types / external RBS / engine folding (and are where the
+`rigor-plugin-author` escalation or a Rigor issue comes in), not another
+hand annotation. Expect a low-20s → low-30s% protection lift on a mature
+library, at zero diagnostic cost.

data/skills/rigor-rbs-setup/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rigor-rbs-setup
+description: |
+  Install community RBS for the project's gems with `rbs collection install`, so Rigor stops typing calls into RBS-less dependencies as `Dynamic` and gains real coverage (and real bug-catching) on them. Rigor auto-detects the resulting `rbs_collection.lock.yaml` — no Rigor config change needed. Triggers: "set up rbs collection", "my gems type as Dynamic", "rigor check says N gems have no RBS available", "reduce false positives from untyped gems". NOT for first-time Rigor setup (use rigor-project-init first) and NOT for a gem that has no entry in the community collection (that needs rigor-plugin-author or a Rigor issue).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor RBS Setup
+
+Most of what Rigor cannot type on a real application is the surface of
+third-party gems that ship **no RBS**: a call into such a gem returns
+`Dynamic`, so every downstream method on the result is unprotected and
+some genuine bugs go uncaught. The Ruby ecosystem's answer is the
+community RBS collection at
+[`ruby/gem_rbs_collection`](https://github.com/ruby/gem_rbs_collection);
+this skill wires it into the project.
+
+## When to use
+
+- `rigor check` ends with `info: N gem(s) in Gemfile.lock have no RBS
+  available: …` — that list is the gap this skill closes.
+- A deep call chain into a gem (an HTTP client, a parser, a service
+  object) types as `Dynamic` and you want Rigor to see through it.
+
+## When NOT to use
+
+- The project has no Rigor config yet — run `rigor-project-init` first.
+- A specific gem you need is **not in** the community collection — RBS
+  setup will not cover it. That residue is for `rigor-plugin-author` (if
+  it is your own DSL) or a Rigor issue (if it is a popular gem worth
+  built-in support).
+
+## How Rigor consumes it (so you know what "done" looks like)
+
+Rigor **auto-detects** `rbs_collection.lock.yaml` at the project root
+(`rbs_collection.auto_detect` defaults to `true`) and feeds each gem's
+downloaded RBS directory into its signature paths, skipping `stdlib`
+entries it already bundles. **No `.rigor.yml` change is required** — the
+lockfile's presence is the whole wiring. (Set `rbs_collection.lockfile:`
+only if the lockfile lives somewhere other than the project root.)
+
+## Procedure
+
+### Phase 1 — see the gap
+
+```sh
+rigor check
+```
+
+Read the closing `info` line listing the gems with no RBS. That is your
+target set.
+
+### Phase 2 — make the `rbs` CLI available
+
+`rbs collection` is part of the `rbs` gem and reads the project's
+`Gemfile.lock`. Check it is runnable:
+
+```sh
+rbs --version            # or: bundle exec rbs --version
+```
+
+If it is missing, add it to the project's development group
+(`bundle add rbs --group development`) or install it standalone
+(`gem install rbs`). Prefer `bundle exec rbs …` when `rbs` is in the
+Gemfile so it matches the project's resolved versions.
+
+### Phase 3 — initialise the collection config (first time only)
+
+```sh
+rbs collection init
+```
+
+This writes `rbs_collection.yaml` (which gems to pull, which to ignore).
+Skip if the file already exists; review it either way — the default
+pulls RBS for every gem in the lockfile that the collection knows.
+
+### Phase 4 — install
+
+```sh
+rbs collection install      # bundle exec rbs collection install when bundled
+```
+
+This resolves against `ruby/gem_rbs_collection`, writes
+`rbs_collection.lock.yaml`, and downloads the `.rbs` files into
+`.gem_rbs_collection/`.
+
+### Phase 5 — verify (re-check; watch for new diagnostics)
+
+```sh
+rigor check
+```
+
+Two things to confirm:
+
+1. **The `info` "no RBS available" list shrank** — the gems now covered
+   dropped off it.
+2. **No surprising new diagnostics.** Community RBS occasionally ships a
+   signature stricter than the gem's real runtime behaviour, which can
+   surface a false positive. Treat the diff like any other:
+   - In **acknowledge mode**, regenerate the baseline
+     (`rigor baseline regenerate`) so the new envelope is recorded.
+   - For a **genuine** new error the sharper types caught, that is a win
+     — fix it.
+   - For a clear RBS-quality false positive, `# rigor:disable <rule>` the
+     site with a reason, or pin the gem out in `rbs_collection.yaml`.
+
+### Phase 6 — commit
+
+Commit the **config + lockfile**, gitignore the **download dir**:
+
+```sh
+# .gitignore
+.gem_rbs_collection/
+```
+
+Commit `rbs_collection.yaml` and `rbs_collection.lock.yaml` so every
+contributor and CI resolves the same RBS. `.gem_rbs_collection/` is
+regenerable from the lockfile (`rbs collection install`), so it is not
+committed.
+
+## Next step
+
+Re-run `rigor skill describe` — with the gem-RBS foundation in place it
+will route you to the next move (CI wiring, baseline work, or protection
+uplift).

data/skills/rigor-upgrade/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: rigor-upgrade
+description: |
+  Adopt a new Rigor version cleanly: after upgrading the `rigortype` gem, re-run the analysis, diff the diagnostics against the committed baseline, and sort the changes into genuine new catches (sharper inference), known sig-quality false positives, and the baseline you should regenerate. Triggers: "I upgraded Rigor, what changed?", "new diagnostics after gem update rigortype", "adopt the new Rigor version", "rigor baseline drifted after upgrade". NOT for first-time setup (use rigor-project-init) or routine baseline work unrelated to an upgrade (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Upgrade
+
+A new Rigor release sharpens inference and may add or tighten rules, so
+`rigor check` can report diagnostics it did not before — most are the new
+version catching more, a few are sig-quality false positives the new
+sharpness exposes. This skill adopts the upgrade without either blindly
+regenerating the baseline (which buries genuine new catches) or treating
+every new line as a regression.
+
+## When to use
+
+- You just ran `mise use gem:rigortype` / `gem update rigortype` and want
+  to understand what the new version changed about your project's
+  diagnostics.
+
+## Procedure
+
+### Phase 1 — confirm the new version
+
+```sh
+rigor --version
+```
+
+### Phase 2 — see the delta against the committed baseline
+
+```sh
+rigor check
+rigor diff            # compare current diagnostics to the saved baseline JSON
+```
+
+`rigor diff` shows what is **new** relative to the baseline — that set is
+what the upgrade changed.
+
+### Phase 3 — sort the new diagnostics
+
+For each newly-surfaced diagnostic:
+
+- **A genuine new catch** — the sharper inference found a real latent
+  issue. Fix it. (Check `evidence_tier` in `rigor check --format json`:
+  `high` is most likely a true positive.)
+- **A sig-quality false positive** — a known class (Struct
+  `call.wrong-arity`, an over-nilable RBS return, a regex-capture `$1`
+  read). `# rigor:disable <rule>` the site with a reason, or address the
+  RBS. Read `rigor explain <rule>` if unsure whether the rule should fire
+  here.
+- **Expected envelope growth** — broadly acceptable in acknowledge mode.
+
+### Phase 4 — regenerate the baseline (acknowledge mode)
+
+Once you have triaged and fixed the genuine catches, record the new
+envelope so the regeneration does not bury what you just fixed:
+
+```sh
+rigor baseline regenerate
+```
+
+Commit the updated `.rigor-baseline.yml` together with any fixes, so the
+team adopts the same post-upgrade baseline.
+
+## Note
+
+`rigor skill describe` cannot detect that you just upgraded — the
+baseline records only its schema version, not the Rigor version that
+generated it — so this skill is invoked on demand rather than
+recommended automatically. Run it whenever you bump the gem.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Rigor contributors
@@ -304,6 +304,83 @@ files:
 - data/vendored_gem_sigs/redis/redis.rbs
 - data/vendored_gem_sigs/redis/redis_extras.rbs
 - data/vendored_gem_sigs/rubygems/rubygems_extras.rbs
+- docs/handbook/01-getting-started.md
+- docs/handbook/02-everyday-types.md
+- docs/handbook/03-narrowing.md
+- docs/handbook/04-tuples-and-shapes.md
+- docs/handbook/05-methods-and-blocks.md
+- docs/handbook/06-classes.md
+- docs/handbook/07-rbs-and-extended.md
+- docs/handbook/08-understanding-errors.md
+- docs/handbook/09-plugins.md
+- docs/handbook/10-sorbet.md
+- docs/handbook/11-sig-gen.md
+- docs/handbook/12-lightweight-hkt.md
+- docs/handbook/README.md
+- docs/handbook/appendix-elixir.md
+- docs/handbook/appendix-go.md
+- docs/handbook/appendix-java-csharp.md
+- docs/handbook/appendix-liskov.md
+- docs/handbook/appendix-mypy.md
+- docs/handbook/appendix-phpstan.md
+- docs/handbook/appendix-protocols-and-structural-typing.md
+- docs/handbook/appendix-rust.md
+- docs/handbook/appendix-steep.md
+- docs/handbook/appendix-type-theory.md
+- docs/handbook/appendix-typeprof.md
+- docs/handbook/appendix-typescript.md
+- docs/install.md
+- docs/llms.txt
+- docs/manual/01-installation.md
+- docs/manual/02-cli-reference.md
+- docs/manual/03-configuration.md
+- docs/manual/04-diagnostics.md
+- docs/manual/05-inspecting-types.md
+- docs/manual/06-baseline.md
+- docs/manual/07-plugins.md
+- docs/manual/08-skills.md
+- docs/manual/09-editor-integration.md
+- docs/manual/10-mcp-server.md
+- docs/manual/11-ci.md
+- docs/manual/12-caching.md
+- docs/manual/13-troubleshooting.md
+- docs/manual/14-rails-quickstart.md
+- docs/manual/15-type-protection-coverage.md
+- docs/manual/16-rbs-extended-annotations.md
+- docs/manual/17-driving-improvement.md
+- docs/manual/README.md
+- docs/manual/ci-templates/README.md
+- docs/manual/plugins/README.md
+- docs/manual/plugins/rigor-actioncable.md
+- docs/manual/plugins/rigor-actionmailer.md
+- docs/manual/plugins/rigor-actionpack.md
+- docs/manual/plugins/rigor-activejob.md
+- docs/manual/plugins/rigor-activerecord.md
+- docs/manual/plugins/rigor-activestorage.md
+- docs/manual/plugins/rigor-activesupport-core-ext.md
+- docs/manual/plugins/rigor-devise.md
+- docs/manual/plugins/rigor-dry-schema.md
+- docs/manual/plugins/rigor-dry-struct.md
+- docs/manual/plugins/rigor-dry-types.md
+- docs/manual/plugins/rigor-dry-validation.md
+- docs/manual/plugins/rigor-factorybot.md
+- docs/manual/plugins/rigor-graphql.md
+- docs/manual/plugins/rigor-hanami.md
+- docs/manual/plugins/rigor-mangrove.md
+- docs/manual/plugins/rigor-minitest.md
+- docs/manual/plugins/rigor-pundit.md
+- docs/manual/plugins/rigor-rails-i18n.md
+- docs/manual/plugins/rigor-rails-routes.md
+- docs/manual/plugins/rigor-rails.md
+- docs/manual/plugins/rigor-rbs-inline.md
+- docs/manual/plugins/rigor-rspec-rails.md
+- docs/manual/plugins/rigor-rspec.md
+- docs/manual/plugins/rigor-shoulda-matchers.md
+- docs/manual/plugins/rigor-sidekiq.md
+- docs/manual/plugins/rigor-sinatra.md
+- docs/manual/plugins/rigor-sorbet.md
+- docs/manual/plugins/rigor-statesman.md
+- docs/manual/plugins/rigor-typescript-utility-types.md
 - exe/rigor
 - lib/rigor.rb
 - lib/rigor/analysis/baseline.rb
@@ -372,6 +449,7 @@ files:
 - lib/rigor/cli/coverage_scan.rb
 - lib/rigor/cli/diagnostic_formats.rb
 - lib/rigor/cli/diff_command.rb
+- lib/rigor/cli/docs_command.rb
 - lib/rigor/cli/explain_command.rb
 - lib/rigor/cli/fused_protection_renderer.rb
 - lib/rigor/cli/fused_protection_report.rb
@@ -390,6 +468,7 @@ files:
 - lib/rigor/cli/show_bleedingedge_command.rb
 - lib/rigor/cli/sig_gen_command.rb
 - lib/rigor/cli/skill_command.rb
+- lib/rigor/cli/skill_describe.rb
 - lib/rigor/cli/trace_command.rb
 - lib/rigor/cli/trace_renderer.rb
 - lib/rigor/cli/triage_command.rb
@@ -777,19 +856,29 @@ files:
 - sig/rigor/testing.rbs
 - sig/rigor/trinary.rbs
 - sig/rigor/type.rbs
+- skills/rigor-ask/SKILL.md
 - skills/rigor-baseline-reduce/SKILL.md
 - skills/rigor-baseline-reduce/references/01-classify.md
 - skills/rigor-baseline-reduce/references/02-fix-or-suppress.md
 - skills/rigor-ci-setup/SKILL.md
+- skills/rigor-doctor/SKILL.md
+- skills/rigor-editor-setup/SKILL.md
+- skills/rigor-mcp-setup/SKILL.md
+- skills/rigor-monkeypatch-resolve/SKILL.md
+- skills/rigor-next-steps/SKILL.md
 - skills/rigor-plugin-author/SKILL.md
 - skills/rigor-plugin-author/references/01-plan-and-scaffold.md
 - skills/rigor-plugin-author/references/02-walker-and-types.md
 - skills/rigor-plugin-author/references/03-test-and-ship.md
+- skills/rigor-plugin-tune/SKILL.md
 - skills/rigor-project-init/SKILL.md
 - skills/rigor-project-init/references/01-detect.md
 - skills/rigor-project-init/references/02-configure.md
 - skills/rigor-project-init/references/03-baseline-and-bugs.md
 - skills/rigor-project-init/references/04-sig-uplift.md
+- skills/rigor-protection-uplift/SKILL.md
+- skills/rigor-rbs-setup/SKILL.md
+- skills/rigor-upgrade/SKILL.md
 homepage: https://github.com/rigortype/rigor
 licenses:
 - MPL-2.0