rigortype 0.1.12 → 0.1.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +12 -2
- data/lib/rigor/analysis/check_rules.rb +96 -3
- data/lib/rigor/cli/skill_command.rb +170 -0
- data/lib/rigor/cli.rb +9 -1
- data/lib/rigor/configuration/severity_profile.rb +3 -0
- data/lib/rigor/environment/rbs_collection_discovery.rb +29 -7
- data/lib/rigor/environment/rbs_loader.rb +17 -0
- data/lib/rigor/environment.rb +13 -3
- data/lib/rigor/scope.rb +14 -0
- data/lib/rigor/version.rb +1 -1
- data/sig/rigor/environment.rbs +1 -0
- data/sig/rigor/scope.rbs +1 -0
- data/skills/rigor-baseline-reduce/SKILL.md +100 -0
- data/skills/rigor-baseline-reduce/references/01-classify.md +107 -0
- data/skills/rigor-baseline-reduce/references/02-fix-or-suppress.md +133 -0
- data/skills/rigor-plugin-author/SKILL.md +95 -0
- data/skills/rigor-plugin-author/references/01-plan-and-scaffold.md +195 -0
- data/skills/rigor-plugin-author/references/02-walker-and-types.md +155 -0
- data/skills/rigor-plugin-author/references/03-test-and-ship.md +163 -0
- data/skills/rigor-project-init/SKILL.md +129 -0
- data/skills/rigor-project-init/references/01-detect.md +139 -0
- data/skills/rigor-project-init/references/02-configure.md +202 -0
- data/skills/rigor-project-init/references/03-baseline-and-bugs.md +169 -0
- data/skills/rigor-project-init/references/04-sig-uplift.md +171 -0
- metadata +14 -1
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# 02 — Write the configuration
|
|
2
|
+
|
|
3
|
+
Covers **Phase 4**. Inputs: the plugin set + path scope from
|
|
4
|
+
[`01-detect.md`](01-detect.md), and the adoption mode chosen in
|
|
5
|
+
Phase 2.
|
|
6
|
+
|
|
7
|
+
## `.rigor.dist.yml` vs `.rigor.yml`
|
|
8
|
+
|
|
9
|
+
Rigor reads both. The convention:
|
|
10
|
+
|
|
11
|
+
- **`.rigor.dist.yml`** — the committed, shared project config. This
|
|
12
|
+
skill writes this file.
|
|
13
|
+
- **`.rigor.yml`** — an optional, gitignored per-developer override.
|
|
14
|
+
Leave it for individuals to create; do not write one here.
|
|
15
|
+
|
|
16
|
+
When both exist, `.rigor.yml` takes precedence. Writing the shared
|
|
17
|
+
config as `.rigor.dist.yml` lets a contributor opt out locally (for
|
|
18
|
+
example, run without the baseline) without touching the committed
|
|
19
|
+
file.
|
|
20
|
+
|
|
21
|
+
## Selecting `target_ruby`
|
|
22
|
+
|
|
23
|
+
Read the project's declared Ruby version from `.ruby-version`, the
|
|
24
|
+
`Gemfile` `ruby "…"` line, or `.tool-versions`. Use the **minimum**
|
|
25
|
+
version of the declared range (e.g. `>= 3.2.0, < 3.5.0` → `3.2`).
|
|
26
|
+
|
|
27
|
+
Then apply this decision table — **do not ask the user**; act
|
|
28
|
+
automatically and emit the message described:
|
|
29
|
+
|
|
30
|
+
| Declared minimum | `target_ruby` to write | Action |
|
|
31
|
+
| --- | --- | --- |
|
|
32
|
+
| 4.x | `"4.0"` (or exact patch) | Write as-is. |
|
|
33
|
+
| 3.3 – 3.x | `"3.3"` (or exact minor) | Write as-is. |
|
|
34
|
+
| 3.0 – 3.2 | `"3.3"` | Write `"3.3"` automatically. Emit: *"Project targets Ruby X.Y, but Prism (the parser bundled with rigortype) supports Ruby 3.3 as its minimum. Setting `target_ruby: \"3.3\"` — syntax parsing is compatible across 3.0–3.3, but RBS type definitions in `.gem_rbs_collection/` or community libraries may be authored for 3.3+ and could produce type-level false positives on APIs that changed between 3.0 and 3.3."* |
|
|
35
|
+
| 2.x | — | **Stop.** Emit: *"Project targets Ruby 2.x. Rigor's bundled Prism parser does not support Ruby 2.x syntax (removed keyword argument syntax, pattern matching differences). Rigor cannot reliably analyse this project. Consider upgrading the project to Ruby 3.3+ before onboarding Rigor."* Do not write a config; do not continue the skill. |
|
|
36
|
+
| Unknown / not declared | `"4.0"` (Rigor's default) | Write as-is; note that the default was used. |
|
|
37
|
+
|
|
38
|
+
## Severity profile — follows the mode
|
|
39
|
+
|
|
40
|
+
The `severity_profile:` key re-stamps every rule's severity. Set it
|
|
41
|
+
from the Phase 2 mode:
|
|
42
|
+
|
|
43
|
+
| Mode | `severity_profile` | Why |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| Acknowledge, >100 errors on first run | `lenient` | Most rules become warnings; the baseline carries the residue. The point is the regression guard, not a wall of errors. |
|
|
46
|
+
| Acknowledge, small project | `balanced` | The default. Errors stay errors; the baseline is small enough to live with. |
|
|
47
|
+
| Strict | `strict` | Promotes borderline rules to errors. Paired with no baseline, every diagnostic is a live gate. |
|
|
48
|
+
|
|
49
|
+
`balanced` is the built-in default — omit the key to get it.
|
|
50
|
+
|
|
51
|
+
## No separate installation needed
|
|
52
|
+
|
|
53
|
+
All plugins ship **bundled inside the `rigortype` gem**. The
|
|
54
|
+
`plugins:` list in the config is all that is needed to activate
|
|
55
|
+
them — the plugin loader runs `require "rigor-<id>"` from within
|
|
56
|
+
the gem's own load path. No Gemfile entry, no `bundle install`,
|
|
57
|
+
no separate gem channel.
|
|
58
|
+
|
|
59
|
+
**The `rigortype` gem itself stays out of the project's
|
|
60
|
+
`Gemfile`** — install it standalone per the manual's
|
|
61
|
+
[Installing Rigor](../../docs/manual/01-installation.md) chapter
|
|
62
|
+
(`mise use gem:rigortype` is the recommended channel). The
|
|
63
|
+
project's Gemfile is untouched by this workflow.
|
|
64
|
+
|
|
65
|
+
## The template
|
|
66
|
+
|
|
67
|
+
Write `.rigor.dist.yml` at the project root. A Rails app in
|
|
68
|
+
acknowledge mode looks like:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
# .rigor.dist.yml — Rigor configuration (committed; shared).
|
|
72
|
+
# Generated by the rigor-project-init workflow.
|
|
73
|
+
|
|
74
|
+
# Match the Ruby version in .ruby-version or the Gemfile `ruby "x.y"` line.
|
|
75
|
+
# Rigor defaults to 4.0; set this explicitly if the project targets Ruby < 4.0.
|
|
76
|
+
target_ruby: "3.4"
|
|
77
|
+
|
|
78
|
+
paths:
|
|
79
|
+
- app
|
|
80
|
+
- lib
|
|
81
|
+
|
|
82
|
+
exclude:
|
|
83
|
+
- vendor
|
|
84
|
+
- tmp
|
|
85
|
+
|
|
86
|
+
plugins:
|
|
87
|
+
- rigor-actionpack
|
|
88
|
+
- rigor-activerecord
|
|
89
|
+
- rigor-actionmailer
|
|
90
|
+
- rigor-rails-routes
|
|
91
|
+
- rigor-rails-i18n
|
|
92
|
+
# An RBS-bundle plugin — ships ActiveSupport core_ext signatures,
|
|
93
|
+
# no signature_paths: wiring needed (see 01-detect.md).
|
|
94
|
+
- rigor-activesupport-core-ext
|
|
95
|
+
|
|
96
|
+
severity_profile: lenient
|
|
97
|
+
|
|
98
|
+
# Phase 6 (acknowledge mode) appends this line after generating the
|
|
99
|
+
# baseline. Strict mode leaves it out entirely.
|
|
100
|
+
# baseline: .rigor-baseline.yml
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Existing `sig/` directory
|
|
104
|
+
|
|
105
|
+
If the project already has a `sig/` directory (from Steep, `rbs_rails`,
|
|
106
|
+
or handwritten annotations), wire it into `signature_paths:` so Rigor
|
|
107
|
+
consumes it. Phase 5 (sig uplift) can be skipped, but the paths must
|
|
108
|
+
still be declared — Rigor does not auto-detect `sig/`:
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
signature_paths:
|
|
112
|
+
- sig/handwritten # adjust to the layout in your project
|
|
113
|
+
- sig/generated
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
List only directories that contain `.rbs` files or subdirectories of
|
|
117
|
+
them. Rigor walks each path recursively. If the sig layout is a single
|
|
118
|
+
flat `sig/` directory, use `- sig` instead.
|
|
119
|
+
|
|
120
|
+
A strict-mode plain-Ruby gem is shorter:
|
|
121
|
+
|
|
122
|
+
```yaml
|
|
123
|
+
paths:
|
|
124
|
+
- lib
|
|
125
|
+
severity_profile: strict
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Key reference
|
|
129
|
+
|
|
130
|
+
Only the keys this skill needs. `rigor --help` and the project
|
|
131
|
+
handbook document the full surface.
|
|
132
|
+
|
|
133
|
+
| Key | Meaning |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| `paths:` | Directories Rigor analyses. Source roots only — not `spec/` / `test/`. |
|
|
136
|
+
| `exclude:` | Paths removed from the `paths:` walk. |
|
|
137
|
+
| `plugins:` | Plugin ids to activate (the Phase 3 set). |
|
|
138
|
+
| `signature_paths:` | Extra RBS source **directories** (paths, not gem names; resolved relative to the config file). Use it for the project's own local `sig/` if it has one. RBS-bundle *plugins* like `rigor-activesupport-core-ext` ship their own `sig/` and need no entry here — list them under `plugins:`. |
|
|
139
|
+
| `severity_profile:` | `lenient` / `balanced` / `strict`. See the table above. |
|
|
140
|
+
| `severity_overrides:` | Per-rule severity tweaks. Leave empty at init; the baseline-reduce workflow tunes it later. |
|
|
141
|
+
| `baseline:` | Path to the baseline file. **Only acknowledge mode sets it**, and only in Phase 6 *after* the file exists. Per Rigor's no-magic rule, a `.rigor-baseline.yml` on disk does nothing until this key names it. |
|
|
142
|
+
| `pre_eval:` | Project files Rigor walks before per-file inference — used to register in-project monkey-patches. Leave empty at init; Phase 7 may suggest it. |
|
|
143
|
+
| `dependencies.source_inference:` | Opt-in inference for gems shipping no RBS. Leave empty at init; Phase 7 may suggest it. |
|
|
144
|
+
|
|
145
|
+
## Do not write the baseline yet
|
|
146
|
+
|
|
147
|
+
Phase 4 writes the config with the `baseline:` line **commented out
|
|
148
|
+
or absent**. The baseline file does not exist until Phase 6, and a
|
|
149
|
+
`baseline:` pointing at a missing file is an error. Phase 6 writes
|
|
150
|
+
the file and uncomments / appends the line in one step.
|
|
151
|
+
|
|
152
|
+
Strict mode never adds `baseline:` at all.
|
|
153
|
+
|
|
154
|
+
## Verify plugin activation (`rigor plugins`)
|
|
155
|
+
|
|
156
|
+
Before proceeding to sig uplift, **run `rigor plugins`** from the
|
|
157
|
+
project root to confirm every entry under `plugins:` actually
|
|
158
|
+
loaded. The activation surface is the part of the configuration
|
|
159
|
+
most prone to silent failure — a typoed gem name, a missing
|
|
160
|
+
third-party plugin gem, or running rigor from a different cwd
|
|
161
|
+
(so a different `.rigor.yml` is discovered) all leave plugins
|
|
162
|
+
inert, which the per-file diagnostic stream then attributes to
|
|
163
|
+
"missing types" rather than to a config gap.
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
rigor plugins
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Expected: every entry shows `[OK ]`, the `loaded: N` count
|
|
170
|
+
matches the entries in `plugins:`, and `load-error: 0`. The
|
|
171
|
+
report also lists each plugin's `signature_paths:` (with a
|
|
172
|
+
per-directory `.rbs` file count) and any `open_receivers:` /
|
|
173
|
+
`owns_receivers:` / `produces:` / `consumes:` / macro substrate
|
|
174
|
+
contributions — useful for confirming the plugin is contributing
|
|
175
|
+
what you expect.
|
|
176
|
+
|
|
177
|
+
If any entry shows `[ERR]`, read the `load error:` line:
|
|
178
|
+
|
|
179
|
+
| Error fragment | Cause | Fix |
|
|
180
|
+
| --- | --- | --- |
|
|
181
|
+
| `could not load plugin gem "rigor-foo"` | The gem is not on the load path. Either misspelled in `plugins:`, or a third-party plugin (per ADR-31 WD4) that is not installed in the rigor runtime environment. | Check spelling against the catalogue in `01-detect.md`; for third-party plugins, install via the same channel that installed `rigortype` (mise / gem install). |
|
|
182
|
+
| `did not register any plugin via Rigor::Plugin.register` | The require succeeded but the gem did not call `Rigor::Plugin.register`. Usually a version mismatch (older / forked rigor-foo) or a partial install. | Reinstall the plugin gem; verify the version matches `rigortype`'s. |
|
|
183
|
+
| `signature path "..." is not a directory` | The bundled `sig/` directory is missing — a packaging bug in the plugin gem. | File an issue against the plugin gem's repo. |
|
|
184
|
+
| `plugin "foo" config invalid: ...` | The `config:` block under the plugin entry has a typo or wrong value type. | Compare against the plugin's documented `config_schema:`. |
|
|
185
|
+
|
|
186
|
+
Re-run `rigor plugins` until `load-error: 0`. Add `--strict` to
|
|
187
|
+
the invocation when you want it to exit 1 (the canonical CI gate
|
|
188
|
+
shape):
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
rigor plugins --strict
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Output of this module
|
|
195
|
+
|
|
196
|
+
A committed `.rigor.dist.yml` with `paths:`, `exclude:`,
|
|
197
|
+
`plugins:`, and `severity_profile:` set — and no active
|
|
198
|
+
`baseline:` line. `rigor plugins` reports every entry loaded,
|
|
199
|
+
zero load errors. No Gemfile changes; plugins are bundled inside
|
|
200
|
+
`rigortype`.
|
|
201
|
+
|
|
202
|
+
Proceed to Phase 5 ([`04-sig-uplift.md`](04-sig-uplift.md)).
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# 03 — Triage, baseline, and surfacing real bugs
|
|
2
|
+
|
|
3
|
+
Covers **Phase 6** (triage), **Phase 7** (baseline — acknowledge mode
|
|
4
|
+
only), and **Phase 8** (real bugs + escalation).
|
|
5
|
+
|
|
6
|
+
## Phase 6 — Triage the diagnostic stream
|
|
7
|
+
|
|
8
|
+
Do **not** read the raw `rigor check` output to decide what to do. A
|
|
9
|
+
mature codebase's raw stream is hundreds of lines and reads as
|
|
10
|
+
hundreds of unrelated problems — it is the wrong first artefact. Run
|
|
11
|
+
the triage command instead:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
rigor triage --format json
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`rigor triage` runs the same analysis as `rigor check`, then returns
|
|
18
|
+
a structured summary instead of the per-line dump. It is read-only
|
|
19
|
+
and advisory — it never edits config and never writes a baseline.
|
|
20
|
+
The JSON shape:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"summary": { "total": 489, "error": 480, "warning": 9, "info": 0 },
|
|
25
|
+
"distribution": [ { "rule": "call.undefined-method", "count": 437 } ],
|
|
26
|
+
"hotspots": [ { "file": "app/models/status.rb", "count": 42,
|
|
27
|
+
"by_rule": { "call.undefined-method": 40 } } ],
|
|
28
|
+
"hints": [
|
|
29
|
+
{ "id": "activesupport-core-ext", "confidence": "likely",
|
|
30
|
+
"diagnostic_count": 365, "summary": "...", "action": "..." }
|
|
31
|
+
]
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Use the three sections like this:
|
|
36
|
+
|
|
37
|
+
- **`summary` / `distribution`** — the scale, and which rules
|
|
38
|
+
dominate. Decides nothing on its own; feeds the mode sanity-check
|
|
39
|
+
(>100 errors → acknowledge mode is the right default).
|
|
40
|
+
- **`hotspots`** — files carrying the most diagnostics. A single hot
|
|
41
|
+
file is often one structural cause, not many bugs.
|
|
42
|
+
- **`hints`** — the heuristic catalogue. Each hint names a *likely
|
|
43
|
+
cause* and a *suggested action*. They are signal, not verdicts —
|
|
44
|
+
the `confidence` field is `likely` or `possible`; verify before
|
|
45
|
+
acting.
|
|
46
|
+
|
|
47
|
+
### Hint catalogue → what to do
|
|
48
|
+
|
|
49
|
+
| Hint `id` | Cause | Where this skill handles it |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| `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. |
|
|
52
|
+
| `gem-without-rbs` | A dependency ships no RBS. | If `rbs_collection.lock.yaml` was present and Phase 1 installed the collection, re-run `rigor triage` — the hint may shrink or disappear. Otherwise: Phase 8 escalation — `bundle exec rbs collection install`, or `dependencies.source_inference:`, or open a Rigor issue. |
|
|
53
|
+
| `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. |
|
|
54
|
+
| `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. |
|
|
55
|
+
| `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. |
|
|
56
|
+
| `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. |
|
|
57
|
+
|
|
58
|
+
If triage flags `activesupport-core-ext` (or any config gap),
|
|
59
|
+
**fix the config and re-run `rigor triage` before continuing**. The
|
|
60
|
+
baseline and the real-bug review should both run against the
|
|
61
|
+
post-config diagnostic set, not the inflated one.
|
|
62
|
+
|
|
63
|
+
## Phase 7 — Generate the baseline (acknowledge mode only)
|
|
64
|
+
|
|
65
|
+
**Strict mode skips this phase entirely.** A strict project has no
|
|
66
|
+
baseline; every diagnostic stays live.
|
|
67
|
+
|
|
68
|
+
In acknowledge mode, snapshot today's diagnostics:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
rigor baseline generate
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
This writes `.rigor-baseline.yml` at the project root — one
|
|
75
|
+
`(file, rule, count)` bucket per cluster. The command refuses to
|
|
76
|
+
overwrite an existing baseline without `--force`.
|
|
77
|
+
|
|
78
|
+
Then **wire it into the config**. Per Rigor's no-magic rule, the
|
|
79
|
+
baseline file does nothing until `.rigor.dist.yml` names it. Add (or
|
|
80
|
+
uncomment) the line written in Phase 4:
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
baseline: .rigor-baseline.yml
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`rigor baseline generate` prints a note reminding you of this if the
|
|
87
|
+
config does not yet declare `baseline:`. Do both edits — generate and
|
|
88
|
+
wire — in one step so the user never has a generated baseline that
|
|
89
|
+
silently does nothing.
|
|
90
|
+
|
|
91
|
+
How the baseline behaves afterwards (acknowledge mode's whole point):
|
|
92
|
+
|
|
93
|
+
- A `(file, rule)` bucket is silenced while its live count stays at
|
|
94
|
+
or below the recorded number.
|
|
95
|
+
- If a commit pushes a bucket *over* its recorded count, **every**
|
|
96
|
+
diagnostic in that bucket surfaces — the bucket is now a regression
|
|
97
|
+
to review.
|
|
98
|
+
- New `(file, rule)` pairs that were not in the baseline surface
|
|
99
|
+
immediately.
|
|
100
|
+
|
|
101
|
+
So ordinary coding cannot quietly grow the diagnostic count: the
|
|
102
|
+
baseline is a ceiling, not a blanket. Reducing it later is the
|
|
103
|
+
`rigor-baseline-reduce` skill's job.
|
|
104
|
+
|
|
105
|
+
Commit `.rigor-baseline.yml` — it documents project state.
|
|
106
|
+
|
|
107
|
+
Print the suppression summary for the user: "N diagnostics recorded
|
|
108
|
+
as baseline; M will surface on subsequent runs."
|
|
109
|
+
|
|
110
|
+
## Phase 8 — Surface real bugs & offer escalation
|
|
111
|
+
|
|
112
|
+
The triage `genuine-bugs` hint (and any low-count, scattered rule in
|
|
113
|
+
`distribution`) points at the diagnostics most likely to be **actual
|
|
114
|
+
bugs** — a `nil`-receiver crash on a rarely-exercised line, a typo'd
|
|
115
|
+
method. In **both modes**, surface 2–3 of these to the user and offer
|
|
116
|
+
to walk them: a small, scattered rule is rarely systemic.
|
|
117
|
+
|
|
118
|
+
In acknowledge mode these still went into the baseline — that is
|
|
119
|
+
fine; the baseline is a starting envelope, not a verdict that the
|
|
120
|
+
bug is acceptable. Recommend the user run the `rigor-baseline-reduce`
|
|
121
|
+
skill next to work them down.
|
|
122
|
+
|
|
123
|
+
### Escalation path A — application-specific metaprogramming
|
|
124
|
+
|
|
125
|
+
If triage reports `project-monkey-patch`, or a `call.undefined-method`
|
|
126
|
+
cluster lands on the project's own DSL / `define_method` factory /
|
|
127
|
+
in-house macro, Rigor cannot follow it by default. Two answers,
|
|
128
|
+
cheapest first:
|
|
129
|
+
|
|
130
|
+
1. **A plain monkey-patch in a known file** (e.g.
|
|
131
|
+
`lib/core_ext/string_extensions.rb`) — register it via `pre_eval:`
|
|
132
|
+
in `.rigor.dist.yml`. Rigor walks those files before per-file
|
|
133
|
+
inference, so the added methods become visible.
|
|
134
|
+
2. **A genuine project DSL** — the durable fix is a **project-private
|
|
135
|
+
Rigor plugin** that teaches Rigor the DSL's shape. Offer to hand
|
|
136
|
+
off to the `rigor-plugin-author` skill. The plugin can live under
|
|
137
|
+
the project's own `lib/` (loaded without a gemspec) or as a
|
|
138
|
+
separate `rigor-<name>` gem.
|
|
139
|
+
|
|
140
|
+
### Escalation path B — an unsupported external gem
|
|
141
|
+
|
|
142
|
+
If triage reports `gem-without-rbs`, a dependency ships no type
|
|
143
|
+
information and Rigor has no built-in coverage. In order:
|
|
144
|
+
|
|
145
|
+
1. `bundle exec rbs collection install` (bare `rbs collection install`
|
|
146
|
+
if `rbs` is not in the project's Gemfile) — pulls community RBS for
|
|
147
|
+
the gem if it exists. Re-run triage afterwards.
|
|
148
|
+
2. `dependencies.source_inference:` in `.rigor.dist.yml` — opt the
|
|
149
|
+
gem into Rigor inferring `Dynamic`-typed returns from its source.
|
|
150
|
+
3. If the gem is widely used and genuinely warrants first-class
|
|
151
|
+
support, **open an issue on the Rigor project** so the maintainers
|
|
152
|
+
can ship a plugin or RBS bundle:
|
|
153
|
+
<https://github.com/rigortype/rigor/issues>. Include the gem name,
|
|
154
|
+
version, and a sample of the diagnostics.
|
|
155
|
+
|
|
156
|
+
Neither escalation is mandatory — offer them when triage points at
|
|
157
|
+
the cause; the user decides whether to act now or defer.
|
|
158
|
+
|
|
159
|
+
## Output of this module — onboarding complete
|
|
160
|
+
|
|
161
|
+
- A committed `.rigor.dist.yml`.
|
|
162
|
+
- Acknowledge mode: a committed `.rigor-baseline.yml` + an active
|
|
163
|
+
`baseline:` line. Strict mode: neither.
|
|
164
|
+
- The user has seen the likely real bugs and knows the two escalation
|
|
165
|
+
paths.
|
|
166
|
+
|
|
167
|
+
Next sessions: `rigor-baseline-reduce` to work the baseline down
|
|
168
|
+
(acknowledge mode), or `rigor-plugin-author` if escalation path A
|
|
169
|
+
applies.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# 04 — Generate initial RBS sigs and uplift precision
|
|
2
|
+
|
|
3
|
+
Covers **Phase 5**. Inputs: the configured `.rigor.dist.yml` from
|
|
4
|
+
Phase 4 and the detected source paths.
|
|
5
|
+
|
|
6
|
+
## Why generate sigs before triaging
|
|
7
|
+
|
|
8
|
+
Rigor's inference engine uses RBS signatures from `sig/` to sharpen
|
|
9
|
+
its type flow. Without them, whole chains of methods fall back to
|
|
10
|
+
`untyped`. Running `rigor triage` against an uninitialized `sig/`
|
|
11
|
+
inflates the diagnostic count with cascade noise that sigs would
|
|
12
|
+
eliminate. Generating sigs first means Phase 6's `rigor triage`
|
|
13
|
+
report is as signal-rich as possible — the `genuine-bugs` hint
|
|
14
|
+
counts bugs, not sig gaps.
|
|
15
|
+
|
|
16
|
+
This phase is **optional if the project already has a `sig/`
|
|
17
|
+
directory** with handwritten RBS annotations. In that case skip
|
|
18
|
+
straight to Phase 6.
|
|
19
|
+
|
|
20
|
+
## Step 5-a — Dry-run sig-gen
|
|
21
|
+
|
|
22
|
+
Inspect what sig-gen would produce without writing anything:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
rigor sig-gen lib # adjust path to match the paths: key
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Typical output at this point: most `new_method` candidates have
|
|
29
|
+
literal or concrete return types (`"hello"`, `42`, `:done`, `nil`).
|
|
30
|
+
Methods whose return type cannot be inferred show up with
|
|
31
|
+
`skip_reason: :untyped_return` — these are the sig precision targets.
|
|
32
|
+
|
|
33
|
+
To get a breakdown in JSON:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
rigor sig-gen --format json lib | ruby -e '
|
|
37
|
+
require "json"
|
|
38
|
+
data = JSON.parse($stdin.read)["candidates"]
|
|
39
|
+
puts "=== classification breakdown ==="
|
|
40
|
+
data.group_by { |c| c["classification"] }
|
|
41
|
+
.sort_by { |k, _| k }
|
|
42
|
+
.each { |k, v| puts " #{k}: #{v.size}" }
|
|
43
|
+
skipped = data.select { |c| c["classification"] == "skipped" }
|
|
44
|
+
puts "\n=== skip reasons ==="
|
|
45
|
+
skipped.group_by { |c| c["skip_reason"] }
|
|
46
|
+
.sort_by { |_, v| -v.size }
|
|
47
|
+
.each { |r, v| puts " #{r}: #{v.size}" }
|
|
48
|
+
'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Step 5-b — Write the baseline sigs
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
rigor sig-gen --write lib
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
This creates `sig/**/*.rbs` with one method signature per inferred
|
|
58
|
+
method. Check in a few files:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
head -40 sig/lib/your_class.rbs
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
At this point, `attr_reader` and `attr_accessor` methods that rely on
|
|
65
|
+
ivar types set from `initialize` parameters will likely still be
|
|
66
|
+
absent (classified as `:untyped_return`). Step 5-c fixes that.
|
|
67
|
+
|
|
68
|
+
## Step 5-c — Precision uplift with --params=observed
|
|
69
|
+
|
|
70
|
+
`--params=observed` tells sig-gen to collect observed argument types
|
|
71
|
+
from every call site it processes during the analysis pass. The most
|
|
72
|
+
important use case: **`attr_reader` / `attr_writer` / `attr_accessor`
|
|
73
|
+
methods whose `@ivar` is assigned from an `initialize` parameter**.
|
|
74
|
+
|
|
75
|
+
### Example
|
|
76
|
+
|
|
77
|
+
```ruby
|
|
78
|
+
class Person
|
|
79
|
+
attr_reader :name, :age
|
|
80
|
+
|
|
81
|
+
def initialize(name, age)
|
|
82
|
+
@name = name
|
|
83
|
+
@age = age
|
|
84
|
+
end
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
Person.new("Alice", 30)
|
|
88
|
+
Person.new("Bob", 25)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Without observations: `attr_reader :name` → skipped as `:untyped_return`
|
|
92
|
+
(the ivar's type is unknown because the blank inference scope never
|
|
93
|
+
sees the parameter values).
|
|
94
|
+
|
|
95
|
+
With `--params=observed`: sig-gen accumulates `name → "Alice" | "Bob"`,
|
|
96
|
+
`age → 25 | 30` from the `Person.new(...)` call sites, then propagates:
|
|
97
|
+
`@name: ("Alice" | "Bob")` → `def name: () -> ("Alice" | "Bob")`.
|
|
98
|
+
|
|
99
|
+
Run:
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
rigor sig-gen --params=observed --write lib
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The cascade effect is significant: a single resolved `attr_reader`
|
|
106
|
+
can unlock dozens of downstream methods whose precision depends on it.
|
|
107
|
+
|
|
108
|
+
### Measuring the uplift
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
rigor sig-gen --format json lib | ruby -e '
|
|
112
|
+
require "json"
|
|
113
|
+
data = JSON.parse($stdin.read)["candidates"]
|
|
114
|
+
new_m = data.select { |c| c["classification"] == "new_method" }
|
|
115
|
+
untyped = new_m.count { |c| (c["inferred_return"] || "").include?("untyped") }
|
|
116
|
+
concrete = new_m.count { |c| !(c["rbs"] || "").include?("untyped") }
|
|
117
|
+
puts "new_method: #{new_m.size} | still-untyped return: #{untyped} | concrete: #{concrete}"
|
|
118
|
+
'
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Run this before and after `--params=observed` to see how many methods
|
|
122
|
+
resolved.
|
|
123
|
+
|
|
124
|
+
## Step 5-d — Handle remaining untyped methods
|
|
125
|
+
|
|
126
|
+
For methods still showing `untyped` return after `--params=observed`,
|
|
127
|
+
there are a few options depending on the cause:
|
|
128
|
+
|
|
129
|
+
| Pattern | Cause | Fix |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| `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` |
|
|
132
|
+
| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 7 escalation path B |
|
|
133
|
+
| 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 |
|
|
134
|
+
| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 7 escalation path A (project plugin) |
|
|
135
|
+
|
|
136
|
+
Do not spend long on residual `untyped` methods at this stage — a
|
|
137
|
+
handful of `untyped` returns in `sig/` does not block adoption. The
|
|
138
|
+
objective is to reduce the false-positive count before triage, not to
|
|
139
|
+
reach perfect sig coverage.
|
|
140
|
+
|
|
141
|
+
## Step 5-e — Commit the sig/ directory
|
|
142
|
+
|
|
143
|
+
Once you are satisfied with the initial sig quality:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
git add sig/
|
|
147
|
+
git commit -m "Add initial RBS sigs from rigor sig-gen (--params=observed)"
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
A committed `sig/` is a first-class project artefact: it improves
|
|
151
|
+
inference quality on every subsequent run and is maintained alongside
|
|
152
|
+
the source (add new sig files when adding classes; update sigs with
|
|
153
|
+
`rigor sig-gen --write lib` when method signatures change).
|
|
154
|
+
|
|
155
|
+
## Quick reference — sig-gen flags used in this phase
|
|
156
|
+
|
|
157
|
+
| Flag | Effect |
|
|
158
|
+
|---|---|
|
|
159
|
+
| *(no flags)* | Print candidates to stdout; nothing written |
|
|
160
|
+
| `--write` | Write `sig/**/*.rbs` files |
|
|
161
|
+
| `--params=observed` | Collect observed argument types from call sites; used to resolve attr_reader / attr_accessor / attr_writer ivar types from initialize observations |
|
|
162
|
+
| `--format json` | Output structured JSON (for scripted analysis) |
|
|
163
|
+
| `--diff` | Show what would change vs. existing sigs (useful for incremental updates) |
|
|
164
|
+
|
|
165
|
+
## Output of this module
|
|
166
|
+
|
|
167
|
+
A committed `sig/` directory with RBS skeletons for all statically
|
|
168
|
+
inferrable methods. Remaining `:untyped_return` methods are noted for
|
|
169
|
+
potential manual annotation; they do not block Phase 6.
|
|
170
|
+
|
|
171
|
+
Proceed to Phase 6 ([`03-baseline-and-bugs.md`](03-baseline-and-bugs.md)).
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: rigortype
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.14
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Rigor contributors
|
|
@@ -295,6 +295,7 @@ files:
|
|
|
295
295
|
- lib/rigor/cli/plugins_renderer.rb
|
|
296
296
|
- lib/rigor/cli/prism_colorizer.rb
|
|
297
297
|
- lib/rigor/cli/sig_gen_command.rb
|
|
298
|
+
- lib/rigor/cli/skill_command.rb
|
|
298
299
|
- lib/rigor/cli/triage_command.rb
|
|
299
300
|
- lib/rigor/cli/triage_renderer.rb
|
|
300
301
|
- lib/rigor/cli/type_of_command.rb
|
|
@@ -640,6 +641,18 @@ files:
|
|
|
640
641
|
- sig/rigor/testing.rbs
|
|
641
642
|
- sig/rigor/trinary.rbs
|
|
642
643
|
- sig/rigor/type.rbs
|
|
644
|
+
- skills/rigor-baseline-reduce/SKILL.md
|
|
645
|
+
- skills/rigor-baseline-reduce/references/01-classify.md
|
|
646
|
+
- skills/rigor-baseline-reduce/references/02-fix-or-suppress.md
|
|
647
|
+
- skills/rigor-plugin-author/SKILL.md
|
|
648
|
+
- skills/rigor-plugin-author/references/01-plan-and-scaffold.md
|
|
649
|
+
- skills/rigor-plugin-author/references/02-walker-and-types.md
|
|
650
|
+
- skills/rigor-plugin-author/references/03-test-and-ship.md
|
|
651
|
+
- skills/rigor-project-init/SKILL.md
|
|
652
|
+
- skills/rigor-project-init/references/01-detect.md
|
|
653
|
+
- skills/rigor-project-init/references/02-configure.md
|
|
654
|
+
- skills/rigor-project-init/references/03-baseline-and-bugs.md
|
|
655
|
+
- skills/rigor-project-init/references/04-sig-uplift.md
|
|
643
656
|
homepage: https://github.com/rigortype/rigor
|
|
644
657
|
licenses:
|
|
645
658
|
- MPL-2.0
|