rigortype 0.2.0 → 0.2.2

data/docs/manual/plugins/rigor-rails-i18n.md

@@ -0,0 +1,92 @@
+# rigor-rails-i18n
+
+Validates `t('key.path')` / `I18n.t(...)` / `I18n.translate(...)`
+calls against `config/locales/*.yml`: missing keys (with
+did-you-mean suggestions), per-locale coverage gaps, and
+interpolation-variable mismatches. No Rails runtime dependency —
+locale files are read through Prism and `YAML.safe_load` only.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-rails-i18n
+```
+
+## What it checks
+
+Against a locale catalogue, every statically-resolvable call site
+is validated:
+
+```text
+demo.rb:14:1: info:    `t('users.welcome')` resolves in en, ja
+errors_demo.rb:12:1: error:   missing translation key `users.welcom` in any locale (did you mean `users.welcome`?)
+errors_demo.rb:16:1: error:   `t('users.welcome')` expects interpolation `name`, got (none)
+errors_demo.rb:20:1: warning: `t('users.welcome')` does not use interpolation `extra` (known placeholders: `name`)
+errors_demo.rb:25:1: warning: `t('errors.messages.blank')` is missing from locale(s) ja
+```
+
+1. **Key existence** — a key absent from every locale is flagged,
+   with `DidYouMean` near-matches.
+2. **Per-locale coverage** — a key present in some
+   `configured_locales` but not others emits a `missing-locale`
+   warning (suppressed when the call passes `default:`).
+3. **Interpolation variables** — the leaf string's `%{var}`
+   placeholders must match the call's keyword arguments. Missing
+   required placeholders are errors; extras are warnings. Reserved
+   I18n option keys (`default:` / `scope:` / `locale:` / `count:`
+   / `raise:` / …) are excluded.
+
+### Recognised call shapes
+
+`t(...)` (implicit self), `I18n.t(...)`, and `I18n.translate(...)`
+with a literal first argument. **Lazy keys** — `t('.title')` in a
+controller — are expanded to `<controller_scope>.<action>.<key>`
+from the file path and the innermost enclosing `def`, matching
+Rails' convention; lazy keys in non-controller files are skipped
+(the scope can't be determined statically). Calls with a
+non-literal key (`t(some_variable)`) pass through unchecked.
+
+Keys under the prefixes Rails and the `rails-i18n` gem ship
+themselves (`date.` / `time.` / `datetime.` / `number.` /
+`errors.messages.` / `errors.format` / `support.array.` /
+`helpers.{select,submit,label}.` / `i18n.transliterate.` /
+`activerecord.errors.{messages,models}.`) are not flagged as
+unknown, since the framework provides them.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-rails-i18n
+    config:
+      locale_search_paths: ["config/locales"]   # default
+      configured_locales: ["en"]                # default
+```
+
+`configured_locales` is the set of locales the project ships;
+setting it to `["en", "ja"]` turns on `missing-locale` warnings
+whenever a key resolves in one but not the other.
+
+## Limitations
+
+- **Literal-string keys only** — a variable key passes through.
+- **Lazy keys outside controllers are skipped** — the
+  controller/action scope `t('.x')` depends on isn't derivable in
+  a model / helper / mailer.
+- **Pluralization is recognised but not validated** — `count:` is
+  treated as a reserved option; whether the locale defines
+  `:zero` / `:one` / `:other` is not checked.
+- **Per-locale interpolation differences are merged** into one
+  placeholder set (if `en` uses `%{name}` and `ja` uses
+  `%{user_name}`, both are treated as required).
+- **`safe_load` only** — YAML aliases / merges are accepted;
+  custom Ruby classes in the YAML are not.
+
+## Plugin internals
+
+The locale loader / index, the cached `:locale_index` producer,
+the demo, and the contract surfaces this plugin exercises are in
+the [plugin's README](../../../plugins/rigor-rails-i18n/README.md).
+To write a plugin, see [`examples/`](../../../examples/README.md)
+and the [`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-rails-routes.md

@@ -0,0 +1,94 @@
+# rigor-rails-routes
+
+Statically interprets `config/routes.rb` with Prism (no Rails
+runtime dependency), builds the route-helper table Rails would
+generate, and validates every `*_path` / `*_url` call site against
+it: an unknown helper is flagged (with a did-you-mean suggestion),
+as is a wrong argument count. Model↔route inflection uses the real
+`ActiveSupport::Inflector`, so irregular names resolve the way Rails
+resolves them.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-rails-routes
+```
+
+## What it checks
+
+Given a `config/routes.rb`, the plugin recognises every helper
+Rails would generate and flags typos / arity mismatches at the call
+site:
+
+```text
+file:line:col: info:  `users_path` → GET /users
+file:line:col: info:  `admin_widgets_path` → GET /admin/widgets
+
+file:line:col: error: no route helper `widgts_path` (did you mean `users_path`?)
+file:line:col: error: `user_path` expects 1 argument(s), got 3
+```
+
+Both `_path` and `_url` forms are recognised.
+
+### Recognised routing DSL
+
+The parser covers the routing DSL real apps use (expanded across
+the v0.1.11 / v0.1.12 OSS surveys against Mastodon / Redmine /
+GitLab FOSS):
+
+- `Rails.application.routes.draw do … end`, plus `draw :name` /
+  `draw_all :name` partial route files.
+- `resources` / `resource` (with `only:` / `except:`), nested
+  resources, and `member do … end` / `collection do … end`.
+- `namespace :admin do … end` and `scope` — both the positional
+  form and keyword `scope(path:, as:, module:)`, with the `as:`
+  prefix and dynamic path segments counted into helper arity.
+- `root`, and explicit `get`/`post`/`patch`/`put`/`delete`
+  routes (named via `as:`, including anonymous static routes).
+- `devise_for`, `mount`, `use_doorkeeper`, `with_options`,
+  `direct`, and `concern :name do … end` (definition recorded;
+  the body is skipped to avoid wrong-arity false positives).
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-rails-routes
+    config:
+      routes_file: "config/routes.rb"   # default
+      helper_paths: ["app"]             # default; dirs scanned for
+                                        # project-defined *_path / *_url methods
+```
+
+`helper_paths` lets the plugin also register URL builders you
+define yourself (e.g. a private `def callback_url` under
+`app/controllers` or `app/lib`), so calls to them are not flagged
+as unknown helpers.
+
+## What it provides
+
+The parsed helper table is published as the `:helper_table`
+cross-plugin fact (ADR-9), which `rigor-actionpack` consumes to
+validate helper calls inside controllers.
+
+## Limitations
+
+- **Statically unfoldable route definitions.** Helpers produced by
+  metaprogramming the parser can't unfold (routes built in a loop
+  over runtime data, helpers injected by an engine the parser
+  doesn't model) may not register, which can surface a false
+  `unknown-helper`. Record those in a baseline, or
+  `# rigor:disable` the line.
+- **Project-custom inflections** declared in
+  `config/initializers/inflections.rb` are not yet ingested
+  (ADR-39 slice 3); the standard ActiveSupport inflections are
+  covered.
+
+## Plugin internals
+
+The Prism routes-parser, the cached `:helper_table` producer, the
+demo, and the contract surfaces this plugin exercises are in the
+[plugin's README](../../../plugins/rigor-rails-routes/README.md).
+To write a plugin, see [`examples/`](../../../examples/README.md)
+and the [`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-rails.md

@@ -0,0 +1,44 @@
+# rigor-rails
+
+A convenience grouping of the seven Tier 1+2 Rails ecosystem
+plugins. It is **not itself a checker** — it runs no analysis of
+its own — and there is nothing to install: every plugin ships
+bundled in `rigortype`.
+
+You enable the Rails plugins by listing the ones you want under
+`plugins:`. `rigor-rails` does **not** one-line-activate the set
+(that keeps each plugin's opt-in under your control — a
+route-helper-light app skips `rigor-rails-routes`, a
+fixture-light app skips `rigor-factorybot`, and so on):
+
+```yaml
+plugins:
+  - rigor-rails-routes
+  - rigor-rails-i18n
+  - rigor-actionmailer
+  - rigor-activejob
+  - rigor-activerecord
+  - rigor-actionpack
+  - rigor-factorybot
+```
+
+| Plugin | Scope |
+| --- | --- |
+| [rigor-rails-routes](rigor-rails-routes.md) | `*_path` / `*_url` helper validation |
+| [rigor-rails-i18n](rigor-rails-i18n.md) | `t('key')` translation-key validation |
+| [rigor-actionmailer](rigor-actionmailer.md) | mailer action existence / arity / view templates |
+| [rigor-activejob](rigor-activejob.md) | `Job.perform_*` argument arity |
+| [rigor-activerecord](rigor-activerecord.md) | finder / relation typing, schema-checked columns |
+| [rigor-actionpack](rigor-actionpack.md) | controller helpers / filters / renders / strong-params |
+| [rigor-factorybot](rigor-factorybot.md) | factory + attribute (+ AR column) validation |
+
+Historically `rigor-rails` was a Gemfile meta-gem whose
+`require "rigor-rails"` pulled in all seven entry points at once.
+Under Rigor's single-bundled-gem distribution model that `require`
+is redundant — the plugins are already loadable by id from
+`rigortype` — so the `plugins:` list above is the canonical setup.
+
+**Tier 3 plugins** (`rigor-pundit`, `rigor-sidekiq`, `rigor-rspec`,
+`rigor-actioncable`, `rigor-activestorage`, `rigor-graphql`) are not
+part of this grouping; enable them individually as your project
+needs them.

data/docs/manual/plugins/rigor-rbs-inline.md

@@ -0,0 +1,83 @@
+# rigor-rbs-inline
+
+Ingests [rbs-inline](https://github.com/soutaro/rbs-inline)-shaped
+comments (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`, attribute
+`#:` casts, `# @rbs!` raw RBS, …) in your Ruby source and feeds the
+synthesised RBS into the analysis environment — so a `# @rbs`
+annotation Rigor would otherwise ignore becomes an enforced contract
+that fires the same `argument-type-mismatch` diagnostics as a
+hand-written `.rbs` file. The design is recorded in
+[ADR-32](../../adr/32-rbs-inline-comment-ingestion.md).
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-rbs-inline
+```
+
+> **Full guide.** The worked walkthrough — every supported annotation
+> form, the magic-comment opt-in, the top-level-`def` caveat, and parse-
+> failure handling — is
+> [handbook chapter 7 — RBS and Extended](../../handbook/07-rbs-and-extended.md),
+> § "Inline RBS in Ruby source". This page is the operational quick
+> reference.
+
+## What it does
+
+Per file, opt in with the upstream magic comment:
+
+```ruby
+# rbs_inline: enabled
+
+class AscDesc
+  # @rbs asc_or_desc: :asc | :desc
+  def ascdesc(asc_or_desc) = asc_or_desc
+end
+
+AscDesc.new.ascdesc(:bad)   # error: argument type mismatch — expected :asc | :desc, got :bad
+```
+
+Files without `# rbs_inline: enabled` are untouched (a top-of-file scan
+only). The synthesised RBS is cached per file (keyed on content SHA +
+plugin id/version + config), so an unchanged second run skips the parse.
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.rbs-inline.source-rbs-synthesis-failed` | info | rbs-inline could not parse a file; analysis falls back to no inline-RBS contribution and the diagnostic carries the upstream error |
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-rbs-inline
+    config:
+      require_magic_comment: true   # default
+```
+
+- **`require_magic_comment`** (default `true`) — when `true`, only files
+  carrying `# rbs_inline: enabled` are processed. Set `false` to treat
+  every file as if it carried the magic comment — useful only when you
+  own the whole analysis scope (a single-file CI run or the hosted
+  [browser playground](../../adr/29-browser-playground.md), which sets
+  it so pasted snippets analyse without the magic line).
+
+## Limitations
+
+- **Top-level `def` produces no RBS.** Upstream rbs-inline emits nothing
+  for a bare top-level `def` (verified against rbs-inline 0.14.0) —
+  wrap the method in a `class` / `module`. This is an inherited upstream
+  behaviour, not a Rigor limitation.
+- **Parse failures fail soft.** A file rbs-inline can't parse is
+  analysed as if it had no inline RBS (the `:info` diagnostic above
+  records it); re-stamp the severity via `severity_profile:` to escalate.
+- **Runtime dependency.** The plugin pulls in the `rbs-inline` gem; core
+  `rigortype` stays zero-runtime-dep, so only projects that opt in pay it.
+
+## Plugin internals
+
+The synthesizer, the `source_rbs_synthesizer:` manifest hook, and the
+caching wiring are in the
+[plugin's README](../../../plugins/rigor-rbs-inline/README.md). To write
+a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-rspec-rails.md

@@ -0,0 +1,72 @@
+# rigor-rspec-rails
+
+Validates [rspec-rails](https://github.com/rspec/rspec-rails)
+**behavioral** matchers whose arguments are statically checkable —
+currently `have_http_status(int_or_symbol)`, flagging out-of-range
+status codes and typo'd status symbols. It is the behavioral sibling
+of [rigor-rspec](rigor-rspec.md): where rigor-rspec *narrows a local's
+type* through matchers like `be_a` / `be_nil` / `eq(literal)`,
+rigor-rspec-rails emits *domain diagnostics* on matcher arguments
+without narrowing anything. The two activate independently and compose.
+
+It ships bundled in `rigortype`. Activate it under `plugins:` (usually
+alongside rigor-rspec):
+
+```yaml
+plugins:
+  - rigor-rspec
+  - rigor-rspec-rails
+```
+
+## What it checks
+
+```ruby
+RSpec.describe HomeController do
+  it "returns 200" do
+    expect(response).to have_http_status(200)       # OK
+    expect(response).to have_http_status(:ok)       # OK
+    expect(response).to have_http_status(:success)  # OK (Rails 2xx group alias)
+    expect(response).to have_http_status(99)        # warning: out-of-range
+    expect(response).to have_http_status(:succes)   # warning: unknown symbol (typo)
+  end
+end
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.rspec-rails.have_http_status.out-of-range` | warning | an integer argument is outside `100..599` |
+| `plugin.rspec-rails.have_http_status.unknown-symbol` | warning | a symbol argument is not a known Rack status code nor a Rails status-group alias (with a did-you-mean) |
+
+The accepted status symbols come from the **real**
+`Rack::Utils::SYMBOL_TO_STATUS_CODE` read at analysis time (the same
+authority `have_http_status` itself uses), not a vendored snapshot — so
+a newly-added Rack symbol is never mistaken for a typo
+([ADR-39](../../adr/39-plugin-target-library-invocation.md)). When Rack
+can't be loaded the plugin **declines** to flag any symbol (reduced
+coverage, never a false positive). The eight Rails status-group aliases
+(`:success`, `:successful`, `:missing`, `:redirect`, `:error`,
+`:client_error`, `:server_error`, `:informational`) are a small stable
+constant set. Only literal integer / symbol arguments are checked;
+strings, variables, and computed expressions pass through.
+
+## No configuration
+
+The plugin has no configuration knobs.
+
+## Limitations
+
+- **Only `have_http_status`.** Other rspec-rails matchers are queued
+  behind cross-plugin coordination: `render_template` (overlaps
+  rigor-actionpack render-target validation), `route_to` / `redirect_to`
+  / `be_routable` (need the rigor-rails-routes table), `have_enqueued_job`
+  / `have_received` (overlap engine constant / undefined-method rules).
+- **Literal arguments only** — a status passed via a variable or method
+  call is not statically checkable, so it's accepted silently.
+
+## Plugin internals
+
+The matcher recogniser, the Rack-table lookup, and the contract
+surfaces this plugin exercises are in the
+[plugin's README](../../../plugins/rigor-rspec-rails/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-rspec.md

@@ -0,0 +1,86 @@
+# rigor-rspec
+
+Validates RSpec `let` / `subject` declarations within each
+`describe` / `context` scope. It is deliberately small: the two
+checks it ships have the lowest false-positive risk of the
+proposed RSpec surface, run in pure syntactic-walk mode, and
+catch real bugs that `rspec` / `rubocop-rspec` don't always
+surface clearly. No RSpec runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-rspec
+```
+
+## What it checks
+
+```ruby
+RSpec.describe "User" do
+  let(:user) { :alice }
+  let(:user) { :bob }            # ← warning: duplicate `let(:user)`
+
+  let(:tags) { tags.map(&:up) }  # ← error: self-referencing let
+
+  context "when admin" do
+    let(:user) { :admin }        # ← OK: different scope
+  end
+end
+```
+
+```text
+spec/user_spec.rb:5:3: warning: duplicate `let(:user)` in this scope (first declared at line 4); the last declaration wins at runtime
+spec/user_spec.rb:7:3: error:   `let(:tags)` references its own name `tags` — this will infinite-loop at runtime
+```
+
+1. **Duplicate `let` / `subject` declarations** within the same
+   scope — `warning`. RSpec's runtime lets the last declaration
+   win, so the first is silently shadowed; the message names the
+   line of the first declaration.
+2. **Self-referencing `let` / `subject`** — calling the declared
+   name from inside its own block body — `error`. At runtime this
+   infinite-loops.
+
+The walker recognises `RSpec.describe … do` (root), nested
+`describe` / `context … do`, `let(:name)` / `let!(:name)`, and
+`subject(:name)` / bare `subject` (the implicit `:subject`).
+
+## Configuration
+
+No configuration knobs. The plugin walks every file on the
+project's `paths:` for `RSpec.describe … do` blocks; files with
+no recognised describe block are silently skipped, so it is safe
+to enable project-wide alongside non-spec files.
+
+## Limitations
+
+- **No let-typo detection in `it` bodies.** Flagging a misspelled
+  `let` name inside an `it` block needs a much heavier walker
+  (matcher DSL, helper methods, the let scope chain) — queued.
+- **No mock-target validation.** `expect(x).to receive(:nme)`
+  against `x`'s methods is a separate slice.
+- **No shared-context resolution.** `include_context`,
+  `shared_context`, and `it_behaves_like` are ignored.
+- **Self-reference detection is intra-block only.** An indirect
+  loop (`let(:user) { foo }` where `foo` calls back to `user`) is
+  not flagged.
+- Constant validation (`RSpec.describe SomeClass`) is the
+  engine's job, not this plugin's.
+
+## Related plugins
+
+`rspec-rails` and `shoulda-matchers` matchers are mostly
+*behavioral* (they assert runtime state, not a static type), so
+they are out of scope here; the queued `rigor-rspec-rails` and
+`rigor-shoulda-matchers` plugins would emit domain-specific
+diagnostics for them. The README covers that boundary in detail.
+
+## Plugin internals
+
+The scope-walker / analyzer layout, how to run the demo, the
+contract surfaces this plugin exercises, and the future-direction
+slices are in the
+[plugin's README](../../../plugins/rigor-rspec/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md)
+and the [`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-shoulda-matchers.md

@@ -0,0 +1,78 @@
+# rigor-shoulda-matchers
+
+Validates [shoulda-matchers](https://github.com/thoughtbot/shoulda-matchers)
+calls inside `RSpec.describe <Model> do … end` blocks against the
+model's real schema: column matchers (`validate_presence_of(:col)`,
+`have_db_column(:col)`, …) must name a real column, and association
+matchers (`belong_to(:assoc)`, `have_many(:assoc)`, …) must name a real
+association of the matching kind. It cross-checks against the
+`:model_index` fact published by [rigor-activerecord](rigor-activerecord.md)
+(ADR-9) — so it complements, rather than overlaps, rigor-rspec (which
+handles RSpec's own `let` / `subject` DSL).
+
+It ships bundled in `rigortype`. Activate it under `plugins:` together
+with rigor-activerecord (which publishes the model index it consumes):
+
+```yaml
+plugins:
+  - rigor-activerecord     # publishes :model_index
+  - rigor-shoulda-matchers # consumes it
+```
+
+## What it checks
+
+```ruby
+RSpec.describe User do
+  it { should validate_presence_of(:email) }   # OK if `email` is a column
+  it { should validate_presence_of(:nme) }     # warning: unknown column
+  it { should belong_to(:author) }             # OK if `author` is singular
+  it { should belong_to(:posts) }              # warning: kind mismatch (posts is a collection)
+  it { should have_many(:comments) }           # OK if `comments` is a collection
+  it { should have_many(:nonexistent) }        # warning: unknown association
+end
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.shoulda-matchers.unknown-column` | warning | a column matcher names a column absent from the model |
+| `plugin.shoulda-matchers.unknown-association` | warning | an association matcher names an association absent from the model |
+| `plugin.shoulda-matchers.association-kind-mismatch` | warning | the matcher's expected kind (singular / collection) disagrees with the association's actual kind |
+
+Column matchers: `validate_presence_of` / `_uniqueness_of` /
+`_length_of` / `_numericality_of` / `_acceptance_of` / `_inclusion_of`
+/ `_exclusion_of` / `_absence_of` / `_format_of` / `_confirmation_of`,
+plus `have_db_column` / `have_db_index`. Association matchers and their
+expected kind: `belong_to` / `have_one` (singular), `have_many` /
+`have_and_belong_to_many` (collection). The enclosing
+`describe <Constant>` (innermost wins) anchors which model is checked.
+
+Suppress with the qualified rule, e.g.
+`# rigor:disable plugin.shoulda-matchers.unknown-column`, or silence
+the whole family with `# rigor:disable plugin.shoulda-matchers`.
+
+## No configuration
+
+The plugin has no configuration knobs. When rigor-activerecord is not
+loaded — or hasn't published an index for the analysed model — the
+plugin falls silent; the cross-check is opt-in.
+
+## Limitations
+
+- **No chained-matcher argument validation** — the chain terminals on
+  `validate_length_of(:col).is_at_most(50)`,
+  `validate_inclusion_of(:col).in_array([...])`, etc. are runtime-only.
+- **No polymorphic / `through:` validation** — only the named
+  association is checked; the chain modifiers are ignored.
+- **No nested-attribute or callback matchers**
+  (`accept_nested_attributes_for`, `callback(...)`).
+- **No route / routing matchers** — those are the rigor-rspec-rails
+  domain.
+
+## Plugin internals
+
+The describe-walker / matcher recogniser and the contract surfaces this
+plugin exercises (the optional `:model_index` consume, `NodeContext`
+ancestor resolution) are in the
+[plugin's README](../../../plugins/rigor-shoulda-matchers/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-sidekiq.md

@@ -0,0 +1,78 @@
+# rigor-sidekiq
+
+Validates Sidekiq enqueue calls — `Worker.perform_async(...)`,
+`.perform_inline(...)`, `.perform_in(t, ...)`, `.perform_at(t, ...)` —
+against the arity of the worker's discovered `#perform`. It discovers
+workers by walking the configured search paths and matching classes
+that `include Sidekiq::Job` (or the legacy `Sidekiq::Worker`); it reads
+source only, with no `sidekiq` runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-sidekiq
+```
+
+## What it checks
+
+```ruby
+# app/workers/welcome_email_worker.rb
+class WelcomeEmailWorker
+  include Sidekiq::Job
+  def perform(user_id, locale = "en")   # arity 1..2
+  end
+end
+
+WelcomeEmailWorker.perform_async(123)          # info:  matches #perform (arity 1..2)
+WelcomeEmailWorker.perform_in(60, 123, "ja")   # info:  schedule carved out, 123/"ja" forwarded
+WelcomeEmailWorker.perform_async              # error: expects 1..2 argument(s), got 0
+WelcomeEmailWorker.perform_in                 # error: requires a schedule as its first argument
+```
+
+`perform_in` / `perform_at` consume their first argument as the
+schedule (interval / Time); the remaining arguments are validated
+against `#perform`. `perform_async` / `perform_inline` forward all
+arguments.
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.sidekiq.worker-call` | info | a `Worker.perform_*` call matched a discovered worker's `#perform` arity |
+| `plugin.sidekiq.wrong-arity` | error | the forwarded argument count falls outside `#perform`'s arity envelope (message names the schedule carve-out for `perform_in` / `perform_at`) |
+| `plugin.sidekiq.missing-schedule` | error | `perform_in()` / `perform_at()` called with zero arguments (the schedule is required even when `#perform` takes none) |
+| `plugin.sidekiq.load-error` | warning | worker discovery failed (parse/read error) — once per file |
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-sidekiq
+    config:
+      worker_search_paths: ["app/workers", "app/sidekiq"]          # default
+      worker_marker_modules: ["Sidekiq::Job", "Sidekiq::Worker"]   # default
+```
+
+The default `worker_marker_modules` covers both modern Sidekiq
+(`Sidekiq::Job`, since 6.3) and the legacy `Sidekiq::Worker`.
+
+## Limitations
+
+- **Direct `include` only.** A worker that mixes in a custom concern
+  which re-includes `Sidekiq::Job` is not discovered — add the
+  intermediate module to `worker_marker_modules`.
+- **Syntactic arity only.** `#perform` arity is read from the parameter
+  list; methods built with `define_method` are out of scope.
+- **No keyword-argument validation.** Sidekiq serialises arguments to
+  JSON, so positional args are the standard shape.
+- **Schedule type is not validated.** The first slot of `perform_in` /
+  `perform_at` is consumed as the schedule regardless of its type.
+- **Chained `set(...)`** (`Worker.set(queue: "low").perform_async(...)`)
+  is validated as a normal call; `set`'s own options are not checked.
+
+## Plugin internals
+
+The worker discoverer / index and the contract surfaces this plugin
+exercises are in the
+[plugin's README](../../../plugins/rigor-sidekiq/README.md). To write a
+plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.