rigortype 0.1.12 → 0.1.13

data/skills/rigor-baseline-reduce/references/02-fix-or-suppress.md

@@ -0,0 +1,133 @@
+# 02 — Act on the classification, then refresh
+
+Covers **Phase 3** (act per site) and **Phase 4** (refresh the
+baseline). Input: the per-site classifications from
+[`01-classify.md`](01-classify.md).
+
+## Phase 3 — Act
+
+### Real bug → fix the code
+
+Propose the fix and offer to apply it. The fix is ordinary code work
+— the value is that Rigor surfaced a defect that was latent because
+the line is rarely exercised. Common shapes:
+
+- `possible-nil-receiver` → add the missing guard (`return unless x`,
+  `x&.method`, an early raise), or fix the upstream code so the value
+  is never `nil` here.
+- `undefined-method` typo → correct the method name.
+- argument-type mismatch → pass the right type, or fix the signature.
+
+After a real-bug fix the diagnostic is *gone*, not suppressed — the
+bucket count drops on its own.
+
+### Stylistic / safe → `# rigor:disable` with intent
+
+The code is staying as it is; the suppression is a deliberate,
+recorded decision. Place a per-line comment at the end of the
+offending line:
+
+```ruby
+config.fetch(:timeout)  # rigor:disable call.possible-nil-receiver — set in initializer
+```
+
+Placement rules:
+
+- **Per-line `# rigor:disable <rule>`** is the default. It keeps the
+  suppression visible exactly where it applies, and a future reader
+  sees the intent. Always name the specific rule, never `all`.
+- Add a short reason after the rule — *why* the site is safe. A bare
+  `# rigor:disable` rots; `# rigor:disable … — set in initializer`
+  survives review.
+- **Per-file `# rigor:disable-file <rule>`** only when one file has
+  many sites of the same rule and they are all the same safe idiom.
+  Escalate this to the user as a decision (it is coarser — it also
+  silences *future* sites of that rule in the file).
+
+A `# rigor:disable`d diagnostic is suppressed *before* the baseline
+filter, so once the comment is in place the site no longer counts
+toward its bucket.
+
+### False positive → open a Rigor issue
+
+Leave the site baselined (do not `# rigor:disable` it — that would
+imply the code is the thing to live with, when actually Rigor is).
+Open an issue on the Rigor project:
+
+<https://github.com/rigortype/rigor/issues>
+
+A useful issue includes:
+
+- The rule id and the exact diagnostic message.
+- A **minimal** code snippet that reproduces the false positive —
+  reduce it to the smallest shape that still mis-fires.
+- What the correct inference should be, and why.
+- The `rigor version` output.
+
+This is the feedback loop that makes the analyzer better — a false
+positive reported with a minimal repro is far more actionable than
+one buried in a baseline. While the issue is open the baseline keeps
+the site quiet.
+
+## Phase 4 — Refresh the baseline
+
+After working a rule (fixes applied, `# rigor:disable` comments
+added, issues filed), the live diagnostic count for the touched
+buckets has dropped below the recorded count. Make the baseline
+reflect reality.
+
+First, inspect the drift:
+
+```sh
+rigor baseline drift
+```
+
+This reports each bucket as `within` / `over` / `cleared` /
+`reducible`. After a reduction session you expect `cleared` (the
+bucket is now empty) and `reducible` (the bucket shrank but is not
+empty) rows.
+
+Then refresh:
+
+```sh
+rigor baseline regenerate
+```
+
+`regenerate` rewrites `.rigor-baseline.yml` from a fresh `rigor
+check` run — cleared buckets disappear, reducible buckets get their
+new lower counts. This is the command that *banks* the session's
+gains: until you regenerate, the baseline still records the old,
+higher numbers.
+
+`rigor baseline prune` is the narrower tool — it drops only the
+fully-`cleared` buckets and leaves reducible ones at their old count.
+Prefer `regenerate` at the end of a reduction session; it captures
+both kinds of progress in one step.
+
+Commit the updated `.rigor-baseline.yml` together with the code
+fixes and `# rigor:disable` comments, so the smaller baseline and the
+work that earned it land together.
+
+## Verifying the session
+
+Confirm the gains held:
+
+```sh
+rigor baseline drift   # expect "No drift detected" after regenerate
+rigor check            # the project's gate — should still pass
+```
+
+If the project's CI uses `rigor check --baseline-strict`, the run
+after `regenerate` should be clean — a stale baseline (numbers not
+refreshed) is exactly the deficit drift that gate fails on.
+
+## Output of this module — session complete
+
+- Code fixes for the real bugs.
+- Intentional, reasoned `# rigor:disable` comments for the
+  stylistic-safe sites.
+- Rigor issues filed for the false positives.
+- A regenerated, smaller `.rigor-baseline.yml`, committed with the
+  work.
+
+Run the skill again next session to take the next rule.

data/skills/rigor-plugin-author/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: rigor-plugin-author
+description: |
+  Author a Rigor plugin in your own repository — a standalone rigor-prefixed gem or a project-private plugin — to teach Rigor about an application DSL, framework, or metaprogramming pattern. Covers gemspec / Gemfile wiring, the plugin class and AST walker, return-type contributions, fixture-based testing (RSpec or Minitest), and version pinning against the pre-1.0 plugin contract. Triggers: "write a Rigor plugin for our DSL", "extend Rigor for X in this project", "make Rigor understand our macro". NOT for onboarding a project (use rigor-project-init) or reducing a baseline (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Plugin Author (external)
+
+Author a Rigor plugin **in your own repository** — to teach Rigor a
+DSL, framework convention, or metaprogramming pattern its core
+analyzer cannot follow. The result is either a standalone
+`rigor-<id>` gem or a project-private plugin.
+
+This skill targets **external authors**: you depend on the published
+`rigortype` gem (`bundle add rigortype`) and use the public plugin
+API surface — `Rigor::Plugin::Base` and friends. It does not assume
+the rigor monorepo's `Makefile`, `spec/integration/` helpers, or Nix
+environment.
+
+> **Authoring inside the rigor monorepo instead?** If you are adding
+> a plugin to rigor's own `plugins/` or `examples/` tree, use the
+> contributor `rigor-plugin-author` skill bundled in that repo — it
+> covers the in-repo layout, `plugin_helpers.rb`, and `make verify`.
+> This skill is for plugins that live in *your* project.
+
+## Important — the plugin contract is a preview (pre-1.0)
+
+Rigor's plugin contract (ADR-2) is **not yet frozen**. It stabilises
+at `rigortype` v0.2.0. Until then, treat each `rigortype` minor
+release as potentially contract-changing:
+
+- **Pin `rigortype` tightly** — `>= 0.1.0, < 0.2.0` in your gemspec
+  or Gemfile. Do not float across the v0.2.0 boundary blind.
+- Expect to **revisit your plugin** when you bump `rigortype` to the
+  next minor. The walker hook signature, the `Diagnostic` shape, and
+  the type carriers may shift.
+- After v0.2.0 the contract is stable and ordinary semver applies.
+
+Tell the user this up front. A plugin written today is a preview
+artefact, valuable but not yet on a stable foundation.
+
+## Phase 0 — Standalone gem or project-private?
+
+Decide where the plugin lives before scaffolding anything.
+
+| Signal | Build it as |
+| --- | --- |
+| The DSL/library is reusable across projects, or you want to publish it | **Standalone `rigor-<id>` gem** — own repo, own gemspec, RubyGems-publishable |
+| The pattern is specific to *one* application's own code / in-house DSL | **Project-private plugin** — lives inside the app repo, never published |
+
+Both produce the same plugin class and walker; they differ only in
+packaging and activation (Phase 1). When unsure, default to
+**project-private** — it is less ceremony, and a plugin can always
+be extracted into a gem later.
+
+Do NOT use this skill for:
+
+- **Onboarding a project to Rigor** (writing `.rigor.yml`, choosing
+  plugins) → `rigor-project-init`.
+- **Reducing a baseline** → `rigor-baseline-reduce`.
+- **Editing an existing, already-working plugin** — that is ordinary
+  code work; modify the plugin class directly.
+
+## How a plugin works — the one-paragraph model
+
+A Rigor plugin is a Ruby class that subclasses `Rigor::Plugin::Base`,
+declares a `manifest(id:, version:, …)`, and calls
+`Rigor::Plugin.register(self)` at load time. When `.rigor.yml` lists
+the plugin under `plugins:`, Rigor `require`s it and, for every
+analysed file, calls the plugin's `#diagnostics_for_file(path:,
+scope:, root:)` — handing it the file's Prism AST (`root`) and a
+`scope` it can query for inferred types. The plugin walks the AST and
+returns an array of `Rigor::Analysis::Diagnostic`. Optionally it also
+implements `#flow_contribution_for(call_node:, scope:)` to *supply* a
+return type for call sites the core analyzer types as `Dynamic`.
+
+## Phase outline
+
+| Phase | What | Reference |
+| --- | --- | --- |
+| 1 | Package and scaffold — gem vs project-private layout, gemspec / Gemfile, the plugin class skeleton, `.rigor.yml` activation. | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) |
+| 2 | The walker — `diagnostics_for_file`, building `Diagnostic`s, querying `scope.type_of`, optional `flow_contribution_for`, RBS for the DSL. | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) |
+| 3 | Test and ship — fixture-based tests (RSpec / Minitest, no rigor internals), version pinning, README, publish or keep private. | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) |
+
+## Reading order — modules
+
+| Module | Read | Covers |
+| --- | --- | --- |
+| 1 | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) | **Phase 1.** The gem vs project-private packaging split, directory trees for both, gemspec template, project-private path-gem / `RUBYLIB` activation, the `Rigor::Plugin::Base` skeleton, `.rigor.yml` `plugins:` wiring. |
+| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `diagnostics_for_file` AST walk over Prism nodes, the `Diagnostic` constructor shape, asking the analyzer for inferred types via `scope.type_of`, the optional `flow_contribution_for` return-type hook, and shipping `sig/*.rbs` so the DSL's types are visible. |
+| 3 | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) | **Phase 3.** Testing a plugin from outside the monorepo — fixture projects driven through `rigor check --format json`, plus pure unit tests of dispatch tables — with RSpec or Minitest. Version pinning against the pre-1.0 contract. README. Publishing to RubyGems or keeping the plugin private. |

data/skills/rigor-plugin-author/references/01-plan-and-scaffold.md

@@ -0,0 +1,195 @@
+# 01 — Package and scaffold
+
+Covers **Phase 1**. Output: a directory tree, a plugin class
+skeleton that registers itself, and an `.rigor.yml` that activates
+it.
+
+## Naming
+
+- **Plugin id** — kebab-case, starts with a letter, matches
+  `/\A[a-z][a-z0-9._-]*\z/`. Descriptive: `units`, `myapp-dsl`,
+  `legacy-macros`.
+- **Require name** — Rigor activates a plugin by `require`-ing the
+  name in the `.rigor.yml` `plugins:` entry. The convention is
+  `rigor-<id>`, and the file that name resolves to must, when
+  loaded, call `Rigor::Plugin.register`.
+- **Ruby class** — CamelCase under `Rigor::Plugin`, e.g.
+  `Rigor::Plugin::MyappDsl`.
+
+## Standalone gem layout
+
+```text
+rigor-<id>/                      # its own repository
+├── README.md
+├── rigor-<id>.gemspec
+├── Gemfile                      # gem "rigortype" (dev); gemspec
+├── lib/
+│   ├── rigor-<id>.rb            # require name → require_relative the class
+│   └── rigor/plugin/
+│       └── <id>.rb              # the plugin class + Rigor::Plugin.register
+│       └── <id>/                # only if it needs helpers
+│           └── analyzer.rb      # AST walker extracted out of the class
+├── sig/                         # optional — RBS for the DSL (Phase 2)
+└── spec/  or  test/             # fixture tests (Phase 3)
+```
+
+### Gemspec template
+
+```ruby
+# rigor-<id>.gemspec
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name        = "rigor-<id>"
+  spec.version     = "0.1.0"
+  spec.authors     = ["Your Name"]
+  spec.summary     = "Rigor plugin: <one line>."
+  spec.description = "<two sentences naming the DSL / API the plugin types>."
+  spec.license     = "MIT"        # your choice
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files        = Dir.glob(%w[README.md lib/**/*.rb sig/**/*.rbs])
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "prism", ">= 1.0", "< 2.0"
+  # Pin tightly — the plugin contract is pre-1.0 (see SKILL.md).
+  spec.add_dependency "rigortype", ">= 0.1.0", "< 0.2.0"
+end
+```
+
+`prism` is Rigor's parser; a plugin walks `Prism::Node`s, so depend
+on it directly.
+
+## Project-private layout
+
+A project-private plugin lives inside the application repo and is
+never published. Two ways to make `require "rigor-<id>"` succeed:
+
+### Recommended — a path gem
+
+Keep the plugin in a subdirectory with its own gemspec, and reference
+it from the app's `Gemfile` by path:
+
+```text
+your-app/
+├── Gemfile
+├── rigor-plugin/                # the plugin, unpublished
+│   ├── rigor-myapp.gemspec
+│   └── lib/
+│       ├── rigor-myapp.rb
+│       └── rigor/plugin/myapp.rb
+└── .rigor.yml
+```
+
+```ruby
+# your-app/Gemfile
+gem "rigortype", "~> 0.1.0"
+gem "rigor-myapp", path: "rigor-plugin"
+```
+
+`bundle install` then puts `rigor-myapp` on the load path, so Rigor's
+`require "rigor-myapp"` resolves. This keeps the plugin versioned,
+testable, and trivially promotable to a real gem later.
+
+### Simplest — a bare file on the load path
+
+If you do not want a gemspec at all, drop `rigor-myapp.rb` somewhere
+and run `rigor` with that directory on `RUBYLIB`:
+
+```text
+your-app/rigor-ext/rigor-myapp.rb     # requires the plugin class
+```
+
+```sh
+RUBYLIB=rigor-ext rigor check
+```
+
+Workable, but the `RUBYLIB` has to be set on every invocation (CI
+included). Prefer the path gem unless the plugin is a throwaway.
+
+## The plugin class skeleton
+
+`lib/rigor-<id>.rb` — the require entry point:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/<id>"
+```
+
+`lib/rigor/plugin/<id>.rb` — the plugin class:
+
+```ruby
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class MyappDsl < Rigor::Plugin::Base
+      manifest(
+        id: "<id>",
+        version: "0.1.0",
+        description: "<one line>",
+        # Optional: declare config keys the user may set under
+        # `.rigor.yml` plugins: [{ gem:, config: { … } }].
+        config_schema: {
+          # "module_name" => :string,
+          # "rules"       => :array,
+        }
+      )
+
+      # Called once at load time with the service container.
+      # Read config defaults here. `config` is the validated
+      # user config Hash.
+      def init(_services)
+        @module_name = config.fetch("module_name", "Default")
+      end
+
+      # Called per analysed file. `root` is the file's Prism AST,
+      # `scope` answers inferred-type queries. Return an Array of
+      # Rigor::Analysis::Diagnostic. See 02-walker-and-types.md.
+      def diagnostics_for_file(path:, scope:, root:)
+        []
+      end
+    end
+
+    Rigor::Plugin.register(MyappDsl)
+  end
+end
+```
+
+`Rigor::Plugin.register` at the bottom is mandatory — the loader
+`require`s the gem, then looks for a freshly-registered plugin
+class. A gem that registers nothing fails to load with a clear
+error.
+
+## Activate the plugin in `.rigor.yml`
+
+```yaml
+plugins:
+  - rigor-<id>
+
+# Hash form when the plugin takes config:
+# plugins:
+#   - gem: rigor-<id>
+#     config:
+#       module_name: MyApp
+```
+
+Confirm activation with the public CLI:
+
+```sh
+rigor check
+```
+
+A misconfigured plugin surfaces as a `plugin-loader` diagnostic
+rather than crashing the run — read that message if the plugin seems
+inert.
+
+## Output of this module
+
+A scaffolded plugin that loads (even if `diagnostics_for_file` still
+returns `[]`) and is activated in `.rigor.yml`. Proceed to Phase 2
+([`02-walker-and-types.md`](02-walker-and-types.md)) to make it
+actually analyse.

data/skills/rigor-plugin-author/references/02-walker-and-types.md

@@ -0,0 +1,155 @@
+# 02 — The walker and types
+
+Covers **Phase 2** — making `diagnostics_for_file` analyse the AST,
+emit diagnostics, and (optionally) contribute return types.
+
+## `diagnostics_for_file` — the core hook
+
+```ruby
+def diagnostics_for_file(path:, scope:, root:)
+  # root  — Prism::Node, the parsed file (a ProgramNode).
+  # scope — answers inferred-type queries: scope.type_of(node).
+  # path  — the file path, for Diagnostic#path.
+  # → return Array<Rigor::Analysis::Diagnostic>
+end
+```
+
+Walk `root` with a Prism visitor or a recursive descent, recognise
+the DSL's call shapes, and collect diagnostics. Keep the walk in a
+separate `Analyzer` class once it grows past a few methods — pass it
+`path` and let it return the diagnostic array.
+
+### Recognising call sites
+
+Most DSL plugins key off `Prism::CallNode`:
+
+```ruby
+def each_call(node, &block)
+  block.call(node) if node.is_a?(Prism::CallNode)
+  node&.compact_child_nodes&.each { |child| each_call(child, &block) }
+end
+```
+
+Then match on `node.name` (the method name, a Symbol),
+`node.receiver`, and `node.arguments&.arguments`.
+
+## Building a `Diagnostic`
+
+Every diagnostic the plugin emits is a `Rigor::Analysis::Diagnostic`.
+A small constructor helper keeps the call sites clean:
+
+```ruby
+def diagnostic(path, node, severity:, rule:, message:)
+  loc = node.location
+  Rigor::Analysis::Diagnostic.new(
+    path:     path,
+    line:     loc.start_line,
+    column:   loc.start_column + 1,   # 1-based column
+    message:  message,
+    severity: severity,               # :error | :warning | :info
+    rule:     rule                    # short kebab-case id
+  )
+end
+```
+
+`rule` is a short identifier (`dimension-mismatch`,
+`unknown-state`). Rigor namespaces it under your plugin —
+diagnostics surface as `plugin.<manifest.id>.<rule>`, and that
+qualified id is what `.rigor.yml` `disable:` and the baseline key
+on. Pick `severity`:
+
+- `:error` — a real defect (a type mismatch, a call that will
+  raise). Fails `rigor check`.
+- `:warning` — suspicious but not certainly wrong.
+- `:info` — informational; surfaces inferred facts without
+  judgement.
+
+## Asking the analyzer for types — `scope.type_of`
+
+A plugin does not have to infer types itself. `scope.type_of(node)`
+returns the type the core analyzer inferred for any AST node — the
+plugin can build on it:
+
+```ruby
+receiver_type = scope.type_of(call_node.receiver)
+```
+
+The returned object is one of the `Rigor::Type::*` carriers. The
+ones a plugin meets most:
+
+- `Rigor::Type::Nominal` — a class type; `#class_name` is the
+  String.
+- `Rigor::Type::Constant` — a literal value; `#value` is the Ruby
+  object.
+- `Rigor::Type::IntegerRange` — a bounded integer.
+
+Match with `case`/`when` on the carrier class. Treat any carrier you
+do not recognise as "decline to act" — never crash on an unexpected
+type.
+
+## Optional — contribute a return type with `flow_contribution_for`
+
+A plugin can do more than emit diagnostics: it can *supply* the
+inferred return type for a call site the core analyzer would
+otherwise type as `Dynamic`. Implement `flow_contribution_for`:
+
+```ruby
+def flow_contribution_for(call_node:, scope:)
+  return nil unless call_node.is_a?(Prism::CallNode)
+  # ... decide the call site's real return type ...
+  return nil if undecidable   # nil = "I have nothing to add"
+
+  Rigor::FlowContribution.new(
+    return_type: a_rigor_type,
+    provenance: Rigor::FlowContribution::Provenance.new(
+      source_family: "plugin.#{manifest.id}",
+      plugin_id:     manifest.id,
+      node:          call_node,
+      descriptor:    nil
+    )
+  )
+end
+```
+
+Build the `return_type` with `Rigor::Type::Combinator`:
+
+```ruby
+Rigor::Type::Combinator.nominal_of("Money")        # a class type
+Rigor::Type::Combinator.constant_of(true)          # a literal
+Rigor::Type::Combinator.union(a, b)                # a union
+```
+
+Returning `nil` is always safe — it means "no contribution", and the
+core analyzer keeps its own answer. Contribute a type only when the
+plugin is confident; a wrong contribution propagates downstream.
+
+This hook is the most contract-sensitive surface — it is the part
+most likely to shift before v0.2.0. Implement it only if the plugin
+genuinely needs to sharpen call-site types; a diagnostics-only
+plugin can skip it entirely.
+
+## Shipping RBS for the DSL
+
+If the DSL introduces methods or classes that Rigor cannot see (a
+`Money` class defined by metaprogramming, methods mixed into
+`Numeric`), give Rigor RBS for them so *core* inference — not just
+your plugin — understands them. Ship `sig/*.rbs` with the plugin (or
+in the consuming project) and point `.rigor.yml` at it:
+
+```yaml
+signature_paths:
+  - sig
+```
+
+RBS covers what the *shape* of the DSL is; the plugin walker covers
+the *dynamic* parts RBS cannot express (a value computed from a
+literal argument, a dimensional rule). They compose — many plugins
+ship both.
+
+## Output of this module
+
+A plugin whose `diagnostics_for_file` recognises the DSL and emits
+diagnostics with correct severities and rule ids — optionally a
+`flow_contribution_for` and a `sig/` bundle. Verify by eye with
+`rigor check`; lock it down with tests in Phase 3
+([`03-test-and-ship.md`](03-test-and-ship.md)).