rigortype 0.1.12 → 0.1.13

data/skills/rigor-project-init/references/03-baseline-and-bugs.md

@@ -0,0 +1,168 @@
+# 03 — Triage, baseline, and surfacing real bugs
+
+Covers **Phase 6** (triage), **Phase 7** (baseline — acknowledge mode
+only), and **Phase 8** (real bugs + escalation).
+
+## Phase 6 — Triage the diagnostic stream
+
+Do **not** read the raw `rigor check` output to decide what to do. A
+mature codebase's raw stream is hundreds of lines and reads as
+hundreds of unrelated problems — it is the wrong first artefact. Run
+the triage command instead:
+
+```sh
+rigor triage --format json
+```
+
+`rigor triage` runs the same analysis as `rigor check`, then returns
+a structured summary instead of the per-line dump. It is read-only
+and advisory — it never edits config and never writes a baseline.
+The JSON shape:
+
+```json
+{
+  "summary":      { "total": 489, "error": 480, "warning": 9, "info": 0 },
+  "distribution": [ { "rule": "call.undefined-method", "count": 437 } ],
+  "hotspots":     [ { "file": "app/models/status.rb", "count": 42,
+                      "by_rule": { "call.undefined-method": 40 } } ],
+  "hints": [
+    { "id": "activesupport-core-ext", "confidence": "likely",
+      "diagnostic_count": 365, "summary": "...", "action": "..." }
+  ]
+}
+```
+
+Use the three sections like this:
+
+- **`summary` / `distribution`** — the scale, and which rules
+  dominate. Decides nothing on its own; feeds the mode sanity-check
+  (>100 errors → acknowledge mode is the right default).
+- **`hotspots`** — files carrying the most diagnostics. A single hot
+  file is often one structural cause, not many bugs.
+- **`hints`** — the heuristic catalogue. Each hint names a *likely
+  cause* and a *suggested action*. They are signal, not verdicts —
+  the `confidence` field is `likely` or `possible`; verify before
+  acting.
+
+### Hint catalogue → what to do
+
+| Hint `id` | Cause | Where this skill handles it |
+| --- | --- | --- |
+| `activesupport-core-ext` | ActiveSupport core-class monkey-patches not loaded. | Go back to Phase 3/4: add `rigor-activesupport-core-ext` to `plugins:` (it is an RBS-bundle plugin), re-run triage. This is a config gap, not a bug. |
+| `gem-without-rbs` | A dependency ships no RBS. | Phase 7 escalation — `rbs collection install`, or `dependencies.source_inference:`, or open a Rigor issue. |
+| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see. | Phase 7 escalation — register the defining file via `pre_eval:`, or (if it is a DSL) write a project plugin. |
+| `activerecord-relation-misinference` | An ActiveRecord relation inferred as `Array`. | Ensure `rigor-activerecord` is enabled (Phase 3). If it persists, it is an engine gap — open a Rigor issue. |
+| `systemic-file-cluster` | One file × one rule, large count. | Acknowledge mode: a clean baseline bucket. Strict mode: a single fix may clear many — review that file first. |
+| `genuine-bugs` | Low-count rules scattered across files. | **Phase 7** — these are the localised bugs Rigor caught. Review first, in both modes. Note: the hint groups all low-count rules regardless of severity — filter for `error` severity when prioritising actionable items. |
+
+If triage flags `activesupport-core-ext` (or any config gap),
+**fix the config and re-run `rigor triage` before continuing**. The
+baseline and the real-bug review should both run against the
+post-config diagnostic set, not the inflated one.
+
+## Phase 7 — Generate the baseline (acknowledge mode only)
+
+**Strict mode skips this phase entirely.** A strict project has no
+baseline; every diagnostic stays live.
+
+In acknowledge mode, snapshot today's diagnostics:
+
+```sh
+rigor baseline generate
+```
+
+This writes `.rigor-baseline.yml` at the project root — one
+`(file, rule, count)` bucket per cluster. The command refuses to
+overwrite an existing baseline without `--force`.
+
+Then **wire it into the config**. Per Rigor's no-magic rule, the
+baseline file does nothing until `.rigor.dist.yml` names it. Add (or
+uncomment) the line written in Phase 4:
+
+```yaml
+baseline: .rigor-baseline.yml
+```
+
+`rigor baseline generate` prints a note reminding you of this if the
+config does not yet declare `baseline:`. Do both edits — generate and
+wire — in one step so the user never has a generated baseline that
+silently does nothing.
+
+How the baseline behaves afterwards (acknowledge mode's whole point):
+
+- A `(file, rule)` bucket is silenced while its live count stays at
+  or below the recorded number.
+- If a commit pushes a bucket *over* its recorded count, **every**
+  diagnostic in that bucket surfaces — the bucket is now a regression
+  to review.
+- New `(file, rule)` pairs that were not in the baseline surface
+  immediately.
+
+So ordinary coding cannot quietly grow the diagnostic count: the
+baseline is a ceiling, not a blanket. Reducing it later is the
+`rigor-baseline-reduce` skill's job.
+
+Commit `.rigor-baseline.yml` — it documents project state.
+
+Print the suppression summary for the user: "N diagnostics recorded
+as baseline; M will surface on subsequent runs."
+
+## Phase 8 — Surface real bugs & offer escalation
+
+The triage `genuine-bugs` hint (and any low-count, scattered rule in
+`distribution`) points at the diagnostics most likely to be **actual
+bugs** — a `nil`-receiver crash on a rarely-exercised line, a typo'd
+method. In **both modes**, surface 2–3 of these to the user and offer
+to walk them: a small, scattered rule is rarely systemic.
+
+In acknowledge mode these still went into the baseline — that is
+fine; the baseline is a starting envelope, not a verdict that the
+bug is acceptable. Recommend the user run the `rigor-baseline-reduce`
+skill next to work them down.
+
+### Escalation path A — application-specific metaprogramming
+
+If triage reports `project-monkey-patch`, or a `call.undefined-method`
+cluster lands on the project's own DSL / `define_method` factory /
+in-house macro, Rigor cannot follow it by default. Two answers,
+cheapest first:
+
+1. **A plain monkey-patch in a known file** (e.g.
+   `lib/core_ext/string_extensions.rb`) — register it via `pre_eval:`
+   in `.rigor.dist.yml`. Rigor walks those files before per-file
+   inference, so the added methods become visible.
+2. **A genuine project DSL** — the durable fix is a **project-private
+   Rigor plugin** that teaches Rigor the DSL's shape. Offer to hand
+   off to the `rigor-plugin-author` skill. The plugin can live under
+   the project's own `lib/` (loaded without a gemspec) or as a
+   separate `rigor-<name>` gem.
+
+### Escalation path B — an unsupported external gem
+
+If triage reports `gem-without-rbs`, a dependency ships no type
+information and Rigor has no built-in coverage. In order:
+
+1. `rbs collection install` — pulls community RBS for the gem if it
+   exists. Re-run triage afterwards.
+2. `dependencies.source_inference:` in `.rigor.dist.yml` — opt the
+   gem into Rigor inferring `Dynamic`-typed returns from its source.
+3. If the gem is widely used and genuinely warrants first-class
+   support, **open an issue on the Rigor project** so the maintainers
+   can ship a plugin or RBS bundle:
+   <https://github.com/rigortype/rigor/issues>. Include the gem name,
+   version, and a sample of the diagnostics.
+
+Neither escalation is mandatory — offer them when triage points at
+the cause; the user decides whether to act now or defer.
+
+## Output of this module — onboarding complete
+
+- A committed `.rigor.dist.yml`.
+- Acknowledge mode: a committed `.rigor-baseline.yml` + an active
+  `baseline:` line. Strict mode: neither.
+- The user has seen the likely real bugs and knows the two escalation
+  paths.
+
+Next sessions: `rigor-baseline-reduce` to work the baseline down
+(acknowledge mode), or `rigor-plugin-author` if escalation path A
+applies.

data/skills/rigor-project-init/references/04-sig-uplift.md

@@ -0,0 +1,171 @@
+# 04 — Generate initial RBS sigs and uplift precision
+
+Covers **Phase 5**. Inputs: the configured `.rigor.dist.yml` from
+Phase 4 and the detected source paths.
+
+## Why generate sigs before triaging
+
+Rigor's inference engine uses RBS signatures from `sig/` to sharpen
+its type flow. Without them, whole chains of methods fall back to
+`untyped`. Running `rigor triage` against an uninitialized `sig/`
+inflates the diagnostic count with cascade noise that sigs would
+eliminate. Generating sigs first means Phase 6's `rigor triage`
+report is as signal-rich as possible — the `genuine-bugs` hint
+counts bugs, not sig gaps.
+
+This phase is **optional if the project already has a `sig/`
+directory** with handwritten RBS annotations. In that case skip
+straight to Phase 6.
+
+## Step 5-a — Dry-run sig-gen
+
+Inspect what sig-gen would produce without writing anything:
+
+```sh
+rigor sig-gen lib        # adjust path to match the paths: key
+```
+
+Typical output at this point: most `new_method` candidates have
+literal or concrete return types (`"hello"`, `42`, `:done`, `nil`).
+Methods whose return type cannot be inferred show up with
+`skip_reason: :untyped_return` — these are the sig precision targets.
+
+To get a breakdown in JSON:
+
+```sh
+rigor sig-gen --format json lib | ruby -e '
+  require "json"
+  data = JSON.parse($stdin.read)["candidates"]
+  puts "=== classification breakdown ==="
+  data.group_by { |c| c["classification"] }
+      .sort_by { |k, _| k }
+      .each { |k, v| puts "  #{k}: #{v.size}" }
+  skipped = data.select { |c| c["classification"] == "skipped" }
+  puts "\n=== skip reasons ==="
+  skipped.group_by { |c| c["skip_reason"] }
+         .sort_by { |_, v| -v.size }
+         .each { |r, v| puts "  #{r}: #{v.size}" }
+'
+```
+
+## Step 5-b — Write the baseline sigs
+
+```sh
+rigor sig-gen --write lib
+```
+
+This creates `sig/**/*.rbs` with one method signature per inferred
+method. Check in a few files:
+
+```sh
+head -40 sig/lib/your_class.rbs
+```
+
+At this point, `attr_reader` and `attr_accessor` methods that rely on
+ivar types set from `initialize` parameters will likely still be
+absent (classified as `:untyped_return`). Step 5-c fixes that.
+
+## Step 5-c — Precision uplift with --params=observed
+
+`--params=observed` tells sig-gen to collect observed argument types
+from every call site it processes during the analysis pass. The most
+important use case: **`attr_reader` / `attr_writer` / `attr_accessor`
+methods whose `@ivar` is assigned from an `initialize` parameter**.
+
+### Example
+
+```ruby
+class Person
+  attr_reader :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age  = age
+  end
+end
+
+Person.new("Alice", 30)
+Person.new("Bob",   25)
+```
+
+Without observations: `attr_reader :name` → skipped as `:untyped_return`
+(the ivar's type is unknown because the blank inference scope never
+sees the parameter values).
+
+With `--params=observed`: sig-gen accumulates `name → "Alice" | "Bob"`,
+`age → 25 | 30` from the `Person.new(...)` call sites, then propagates:
+`@name: ("Alice" | "Bob")` → `def name: () -> ("Alice" | "Bob")`.
+
+Run:
+
+```sh
+rigor sig-gen --params=observed --write lib
+```
+
+The cascade effect is significant: a single resolved `attr_reader`
+can unlock dozens of downstream methods whose precision depends on it.
+
+### Measuring the uplift
+
+```sh
+rigor sig-gen --format json lib | ruby -e '
+  require "json"
+  data = JSON.parse($stdin.read)["candidates"]
+  new_m = data.select { |c| c["classification"] == "new_method" }
+  untyped  = new_m.count { |c| (c["inferred_return"] || "").include?("untyped") }
+  concrete = new_m.count { |c| !(c["rbs"] || "").include?("untyped") }
+  puts "new_method: #{new_m.size} | still-untyped return: #{untyped} | concrete: #{concrete}"
+'
+```
+
+Run this before and after `--params=observed` to see how many methods
+resolved.
+
+## Step 5-d — Handle remaining untyped methods
+
+For methods still showing `untyped` return after `--params=observed`,
+there are a few options depending on the cause:
+
+| Pattern | Cause | Fix |
+|---|---|---|
+| `attr_reader :x` with `@x` never set in `initialize` | ivar set from a DB query, config read, or side effect | Add a hand-written sig: create (or edit) `sig/your_class.rbs` with `attr_reader x: String` |
+| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 7 escalation path B |
+| Recursive or mutually recursive methods | Return type not inferrable without a base case | Add a `# @rbs return: YourType` inline annotation, or a hand-written sig |
+| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 7 escalation path A (project plugin) |
+
+Do not spend long on residual `untyped` methods at this stage — a
+handful of `untyped` returns in `sig/` does not block adoption. The
+objective is to reduce the false-positive count before triage, not to
+reach perfect sig coverage.
+
+## Step 5-e — Commit the sig/ directory
+
+Once you are satisfied with the initial sig quality:
+
+```sh
+git add sig/
+git commit -m "Add initial RBS sigs from rigor sig-gen (--params=observed)"
+```
+
+A committed `sig/` is a first-class project artefact: it improves
+inference quality on every subsequent run and is maintained alongside
+the source (add new sig files when adding classes; update sigs with
+`rigor sig-gen --write lib` when method signatures change).
+
+## Quick reference — sig-gen flags used in this phase
+
+| Flag | Effect |
+|---|---|
+| *(no flags)* | Print candidates to stdout; nothing written |
+| `--write` | Write `sig/**/*.rbs` files |
+| `--params=observed` | Collect observed argument types from call sites; used to resolve attr_reader / attr_accessor / attr_writer ivar types from initialize observations |
+| `--format json` | Output structured JSON (for scripted analysis) |
+| `--diff` | Show what would change vs. existing sigs (useful for incremental updates) |
+
+## Output of this module
+
+A committed `sig/` directory with RBS skeletons for all statically
+inferrable methods. Remaining `:untyped_return` methods are noted for
+potential manual annotation; they do not block Phase 6.
+
+Proceed to Phase 6 ([`03-baseline-and-bugs.md`](03-baseline-and-bugs.md)).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.1.13
 platform: ruby
 authors:
 - Rigor contributors
@@ -295,6 +295,7 @@ files:
 - lib/rigor/cli/plugins_renderer.rb
 - lib/rigor/cli/prism_colorizer.rb
 - lib/rigor/cli/sig_gen_command.rb
+- lib/rigor/cli/skill_command.rb
 - lib/rigor/cli/triage_command.rb
 - lib/rigor/cli/triage_renderer.rb
 - lib/rigor/cli/type_of_command.rb
@@ -640,6 +641,18 @@ files:
 - sig/rigor/testing.rbs
 - sig/rigor/trinary.rbs
 - sig/rigor/type.rbs
+- 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-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-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
 homepage: https://github.com/rigortype/rigor
 licenses:
 - MPL-2.0