rigor-plugin-author

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.

First: load the version-current copy

The plugin contract is pre-1.0 and moving (see the next section), so this skill's step detail — in its references/ files — is exactly the kind that drifts between releases. Follow the copy that ships with the installed Rigor rather than any vendored or frozen copy of this file. Get the complete current procedure (body + all references, inline) in one call:

rigor skill --full rigor-plugin-author

If you already loaded this skill via rigor skill you have the current copy — just proceed. If the rigor command is not available, run rigor-next-steps to install Rigor first, then come back.

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.

Read a real plugin — rigor plugin

You do not have to learn the Rigor::Plugin::Base surface from this prose alone. Because Rigor is installed on disk (mise / gem install), every plugin bundled in the toolchain is readable source. Use it as a worked-example library throughout this skill:

rigor plugin list                              # all bundled + example plugins, with paths
rigor plugin print rigor-activesupport-core-ext  # a plugin's main source, inline
rigor plugin path  rigor-units                 # the dir, to browse with your file tool
rigor plugin root                              # gem root + public API (lib/rigor/plugin.rb)

rigor plugin (singular) browses the toolchain's plugins; rigor plugins (plural) reports your own .rigor.yml activation — different commands. When a step below is thinner than you need, read a shipped plugin that does the same thing. (Paths are local to where rigor runs — see the command's own note about containers.)

Phase 0 — Standalone gem or project-private?

Decide where the plugin lives before scaffolding anything.

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 requires it and runs its node rules: the plugin declares node_rule(Prism::CallNode) { |node, scope, path, _fc, context| … }, and the engine — which owns the single AST walk per file — hands every matching node to the block along with a scope it can query for inferred types. The block returns an array of Rigor::Analysis::Diagnostic (built via the diagnostic helper). Optionally the plugin also declares dynamic_return(receivers:) / narrowing_facts(methods:) to supply a return type or narrowing facts for call sites the core analyzer types as Dynamic. (narrowing_facts was renamed from type_specifier in ADR-80; the old verb was removed in 0.3.0, so narrowing_facts is the only spelling.) #diagnostics_for_file is the file-rule surface for whole-file diagnostics a per-node walk can't express. (flow_contribution_for was removed pre-1.0 in ADR-52 WD3 — defining it now raises ArgumentError; use dynamic_return / narrowing_facts. See Phase 2.)

Phase outline

Reading order — modules