rigortype 0.2.7 → 0.2.8

data/plugins/rigor-mangrove/lib/rigor/plugin/mangrove.rb

@@ -5,75 +5,54 @@ require "rigor/plugin"
 
 module Rigor
   module Plugin
-    # rigor-mangrove — precision plugin for the
-    # [Mangrove](https://github.com/kazzix14/mangrove) functional
+    # rigor-mangrove — precision plugin for the [Mangrove](https://github.com/kazzix14/mangrove) functional
     # toolkit (Result / Option carriers).
     #
     # ## Why this plugin exists (and what it deliberately is NOT)
     #
-    # Mangrove is a Sorbet-first library: every carrier method is
-    # annotated with an inline `sig { ... }`, and the Enum DSL's
-    # dynamic variants are materialised by a bundled Tapioca DSL
-    # compiler. So the *type source* for Mangrove is already
-    # covered by `rigor-sorbet` (sig ingestion + RBI walking) —
-    # this plugin is NOT a parallel type source. See
-    # `docs/notes/20260530-mangrove-library-survey.md`.
+    # Mangrove is a Sorbet-first library: every carrier method is annotated with an inline `sig { ... }`, and
+    # the Enum DSL's dynamic variants are materialised by a bundled Tapioca DSL compiler. So the *type source*
+    # for Mangrove is already covered by `rigor-sorbet` (sig ingestion + RBI walking) — this plugin is NOT a
+    # parallel type source. See `docs/notes/20260530-mangrove-library-survey.md`.
     #
-    # What sig-ingestion (Sorbet-level precision) structurally
-    # cannot do is **instantiate the carrier's generic
-    # type-member at the unwrap call site**. Mangrove's `Result`
-    # interface declares:
+    # What sig-ingestion (Sorbet-level precision) structurally cannot do is **instantiate the carrier's generic
+    # type-member at the unwrap call site**. Mangrove's `Result` interface declares:
     #
     #     sig { abstract.returns(OkType) }
     #     def unwrap!; end
     #
-    # `OkType` is a `type_member(:out)`. When the receiver's
-    # static type is `Mangrove::Result[String, StandardError]`,
-    # `unwrap!` *should* yield `String` — but resolving the
-    # abstract `OkType` to the receiver's first type argument is
-    # generic instantiation, which neither `rigor-sorbet` (it
-    # contributes the cataloged sig's return type verbatim) nor a
-    # bare-`def unwrap!: () -> untyped` RBS stub performs. The
-    # call degrades to `Dynamic[top]`.
+    # `OkType` is a `type_member(:out)`. When the receiver's static type is
+    # `Mangrove::Result[String, StandardError]`, `unwrap!` *should* yield `String` — but resolving the abstract
+    # `OkType` to the receiver's first type argument is generic instantiation, which neither `rigor-sorbet` (it
+    # contributes the cataloged sig's return type verbatim) nor a bare-`def unwrap!: () -> untyped` RBS stub
+    # performs. The call degrades to `Dynamic[top]`.
     #
-    # This plugin closes exactly that gap. At every recognised
-    # unwrap-family call on a known Mangrove carrier, it reads the
-    # receiver's `Rigor::Type::Nominal#type_args` and contributes
-    # the first argument (the `OkType` / `InnerType`) as the
-    # call's return type. The receiver type is already known, so
-    # this only ever *sharpens* an existing `Dynamic[top]` into a
-    # concrete type — it never invents a receiver type and never
-    # emits a diagnostic of its own, so it cannot frighten working
-    # code (Rigor's false-positive discipline).
+    # This plugin closes exactly that gap. At every recognised unwrap-family call on a known Mangrove carrier,
+    # it reads the receiver's `Rigor::Type::Nominal#type_args` and contributes the first argument (the
+    # `OkType` / `InnerType`) as the call's return type. The receiver type is already known, so this only ever
+    # *sharpens* an existing `Dynamic[top]` into a concrete type — it never invents a receiver type and never
+    # emits a diagnostic of its own, so it cannot frighten working code (Rigor's false-positive discipline).
     #
     # ## Scope (slice 1)
     #
-    # - Result unwrap family → `OkType` (`type_args[0]`):
-    #   `unwrap!`, `unwrap_in`, `expect!`, `expect_with!`,
-    #   `unwrap_or_raise!`, `unwrap_or_raise_with!`,
-    #   `unwrap_or_raise_inner!`.
-    # - Option unwrap family → `InnerType` (`type_args[0]`):
-    #   `unwrap`, `unwrap!`, `unwrap_or`, `expect!`,
+    # - Result unwrap family → `OkType` (`type_args[0]`): `unwrap!`, `unwrap_in`, `expect!`, `expect_with!`,
+    #   `unwrap_or_raise!`, `unwrap_or_raise_with!`, `unwrap_or_raise_inner!`.
+    # - Option unwrap family → `InnerType` (`type_args[0]`): `unwrap`, `unwrap!`, `unwrap_or`, `expect!`,
     #   `expect_with!`.
     #
-    # The contribution fires only when the receiver resolves to a
-    # carrier Nominal carrying a non-empty `type_args` — i.e. when
-    # the Result/Option came from a method whose declared return
-    # type is an applied generic (`-> Result[String, E]`), the
-    # realistic Mangrove shape. The bare-constructor shape
-    # (`Result::Ok.new("x")`) currently yields a raw Nominal with
-    # no `type_args` (the engine does not infer generics from
-    # constructor arguments), so the plugin no-ops there rather
-    # than guessing — a conservative floor, not a regression.
+    # The contribution fires only when the receiver resolves to a carrier Nominal carrying a non-empty
+    # `type_args` — i.e. when the Result/Option came from a method whose declared return type is an applied
+    # generic (`-> Result[String, E]`), the realistic Mangrove shape. The bare-constructor shape
+    # (`Result::Ok.new("x")`) currently yields a raw Nominal with no `type_args` (the engine does not infer
+    # generics from constructor arguments), so the plugin no-ops there rather than guessing — a conservative
+    # floor, not a regression.
     #
     # ## Out of scope (tracked elsewhere)
     #
-    # - `is_a?(Result::Ok)` / `Some` / `None` exhaustive
-    #   narrowing — core control-flow analysis over a sealed
+    # - `is_a?(Result::Ok)` / `Some` / `None` exhaustive narrowing — core control-flow analysis over a sealed
     #   hierarchy, not a plugin surface.
-    # - The `variants do variant Const, Type end` Enum DSL is handled
-    #   via ADR-36 `nested_class_templates:` in this plugin's manifest
-    #   (Slice A — see `nested_class_templates:` block below).
+    # - The `variants do variant Const, Type end` Enum DSL is handled via ADR-36 `nested_class_templates:` in
+    #   this plugin's manifest (Slice A — see `nested_class_templates:` block below).
     class Mangrove < Rigor::Plugin::Base
       manifest(
         id: "mangrove",
@@ -90,10 +69,9 @@ module Rigor
         #     end
         #   end
         #
-        # mints `Shape::Circle < Shape` with `#inner : Float`. The
-        # substrate resolves the variant constant + its `#inner`
-        # reader statically so `Shape::Circle.new(1.0).inner`
-        # types as `Float` without running Mangrove's `const_missing`.
+        # mints `Shape::Circle < Shape` with `#inner : Float`. The substrate resolves the variant constant +
+        # its `#inner` reader statically so `Shape::Circle.new(1.0).inner` types as `Float` without running
+        # Mangrove's `const_missing`.
         nested_class_templates: [
           Rigor::Plugin::Macro::NestedClassTemplate.new(
             receiver_constraint: "Mangrove::Enum",
@@ -106,11 +84,9 @@ module Rigor
         ]
       )
 
-      # Carrier class names whose FIRST type argument is the
-      # value the unwrap family yields (`OkType` for Result,
-      # `InnerType` for Option). Matched with and without a
-      # leading `::` because `scope.type_of` reports the lexical
-      # form while user code may root the constant.
+      # Carrier class names whose FIRST type argument is the value the unwrap family yields (`OkType` for
+      # Result, `InnerType` for Option). Matched with and without a leading `::` because `scope.type_of`
+      # reports the lexical form while user code may root the constant.
       RESULT_CARRIERS = [
         "Mangrove::Result",
         "Mangrove::Result::Ok",
@@ -123,23 +99,19 @@ module Rigor
         "Mangrove::Option::None"
       ].freeze
 
-      # Methods on the Result carriers that return `OkType`
-      # (`type_args[0]`). All of these are documented as yielding
-      # the success value, raising / short-circuiting on `Err`.
+      # Methods on the Result carriers that return `OkType` (`type_args[0]`). All of these are documented as
+      # yielding the success value, raising / short-circuiting on `Err`.
       RESULT_UNWRAP_METHODS = %i[
         unwrap! unwrap_in expect! expect_with!
         unwrap_or_raise! unwrap_or_raise_with! unwrap_or_raise_inner!
       ].freeze
 
-      # Methods on the Option carriers that return `InnerType`
-      # (`type_args[0]`).
+      # Methods on the Option carriers that return `InnerType` (`type_args[0]`).
       OPTION_UNWRAP_METHODS = %i[unwrap unwrap! unwrap_or expect! expect_with!].freeze
 
-      # ADR-37 slice 2 — a pure return-type contributor. The engine
-      # gates on the receiver being a known carrier class (so the block
-      # only runs on Result/Option receivers); the block then confirms
-      # the call is an unwrap method on an instantiated carrier and
-      # yields the carried `type_args[0]`.
+      # ADR-37 slice 2 — a pure return-type contributor. The engine gates on the receiver being a known
+      # carrier class (so the block only runs on Result/Option receivers); the block then confirms the call
+      # is an unwrap method on an instantiated carrier and yields the carried `type_args[0]`.
       dynamic_return receivers: (RESULT_CARRIERS + OPTION_CARRIERS) do |call_node, scope|
         receiver = call_node.receiver
         next nil if receiver.nil?
@@ -152,18 +124,16 @@ module Rigor
 
       private
 
-      # @return [Rigor::Type, nil] the receiver's inferred type, or
-      #   nil when the engine raises on a synthetic / unrecognised
-      #   node (mirrors rigor-sorbet's defensive degrade).
+      # @return [Rigor::Type, nil] the receiver's inferred type, or nil when the engine raises on a synthetic
+      #   / unrecognised node (mirrors rigor-sorbet's defensive degrade).
       def receiver_type_of(receiver, scope)
         scope.type_of(receiver)
       rescue StandardError
         nil
       end
 
-      # The value the unwrap family yields for this receiver, or
-      # nil when the call is not an unwrap on a known carrier, or
-      # the carrier is raw (no `type_args` to instantiate).
+      # The value the unwrap family yields for this receiver, or nil when the call is not an unwrap on a
+      # known carrier, or the carrier is raw (no `type_args` to instantiate).
       def carried_type(receiver_type, method_name)
         class_name = normalize(receiver_type.class_name)
         type_args = receiver_type.type_args

data/plugins/rigor-minitest/lib/rigor/plugin/minitest/assertion_analyzer.rb

@@ -8,9 +8,8 @@ require "rigor/flow_contribution/fact"
 module Rigor
   module Plugin
     class Minitest < Rigor::Plugin::Base
-      # Recognises the four shapes of Minitest / Test::Unit
-      # assertions and emits a `post_return_fact` that narrows
-      # the named local on the post-call edge.
+      # Recognises the four shapes of Minitest / Test::Unit assertions and emits a `post_return_fact` that
+      # narrows the named local on the post-call edge.
       #
       # ## Recognised call shapes
       #
@@ -29,9 +28,8 @@ module Rigor
       #   refute_nil(x)               →  narrow x AWAY from nil
       #   refute_equal(literal, x)    →  narrow x AWAY from Constant<literal>
       #
-      # Test::Unit's `assert_not_nil(x)` / `assert_not_equal(...)` /
-      # `assert_not_kind_of(...)` / `assert_not_instance_of(...)`
-      # share the recognizer with `refute_*` (they're aliases).
+      # Test::Unit's `assert_not_nil(x)` / `assert_not_equal(...)` / `assert_not_kind_of(...)` /
+      # `assert_not_instance_of(...)` share the recognizer with `refute_*` (they're aliases).
       #
       # ### (3) Minitest/spec `_(x).must_*` (positive) ###
       #
@@ -41,12 +39,10 @@ module Rigor
       #   _(x).must_equal(literal)    →  narrow x to Constant<literal>
       #   _(x).must_match(regex)      →  narrow x to String
       #
-      # The legacy bare `x.must_be_kind_of(T)` form (Minitest <
-      # 6.0 monkey-patched onto Object) is intentionally NOT
-      # recognised — the receiver is the value itself rather
-      # than a wrapping `_(value)`, so the analyzer has nothing
-      # to narrow against. Users who still rely on the legacy
-      # form should migrate to `_(x).must_*`.
+      # The legacy bare `x.must_be_kind_of(T)` form (Minitest < 6.0 monkey-patched onto Object) is
+      # intentionally NOT recognised — the receiver is the value itself rather than a wrapping `_(value)`,
+      # so the analyzer has nothing to narrow against. Users who still rely on the legacy form should
+      # migrate to `_(x).must_*`.
       #
       # ### (4) Minitest/spec `_(x).wont_*` (negative) ###
       #
@@ -56,14 +52,10 @@ module Rigor
       #
       # ## Not yet recognised
       #
-      # `assert_predicate(x, :foo?)` (custom predicate) /
-      # `assert_respond_to(x, :method)` / `assert_includes` /
-      # `assert_operator` / `assert_throws` /
-      # `assert_raises(T) { ... }` etc. — each either needs a
-      # carrier Rigor doesn't model today (predicate-state,
-      # respond-to-set) or a multi-edge fact that the
-      # `post_return_facts` slot can't express. Queued for
-      # follow-up slices.
+      # `assert_predicate(x, :foo?)` (custom predicate) / `assert_respond_to(x, :method)` / `assert_includes`
+      # / `assert_operator` / `assert_throws` / `assert_raises(T) { ... }` etc. — each either needs a
+      # carrier Rigor doesn't model today (predicate-state, respond-to-set) or a multi-edge fact that the
+      # `post_return_facts` slot can't express. Queued for follow-up slices.
       module AssertionAnalyzer
         module_function
 
@@ -83,16 +75,12 @@ module Rigor
 
         # --- assert_* / refute_* / assert_not_* form ---
 
-        # Maps each recognised assertion name to a tuple
-        # `[shape, negative]`. `shape` is one of:
+        # Maps each recognised assertion name to a tuple `[shape, negative]`. `shape` is one of:
         #
-        # - :class_then_local   — `assert_kind_of(T, x)`, T at
-        #   args[0], local at args[1].
+        # - :class_then_local   — `assert_kind_of(T, x)`, T at args[0], local at args[1].
         # - :nil_local          — `assert_nil(x)`, local at args[0].
-        # - :literal_then_local — `assert_equal(literal, x)`,
-        #   literal at args[0], local at args[1].
-        # - :regex_then_local   — `assert_match(regex, x)`,
-        #   regex at args[0], local at args[1].
+        # - :literal_then_local — `assert_equal(literal, x)`, literal at args[0], local at args[1].
+        # - :regex_then_local   — `assert_match(regex, x)`, regex at args[0], local at args[1].
         ASSERT_FORM = {
           assert_kind_of: [:class_then_local, false],
           assert_instance_of: [:class_then_local, false],
@@ -123,8 +111,7 @@ module Rigor
 
         # --- _(x).must_* / .wont_* form ---
 
-        # Maps the spec-style matcher names to `[shape,
-        # negative]`. `shape`:
+        # Maps the spec-style matcher names to `[shape, negative]`. `shape`:
         # - :class_arg   — `_(x).must_be_kind_of(T)`, T at args[0].
         # - :no_arg_nil  — `_(x).must_be_nil`, no args.
         # - :literal_arg — `_(x).must_equal(literal)`, literal at args[0].
@@ -144,8 +131,8 @@ module Rigor
         }.freeze
         private_constant :SPEC_MATCHER_FORM
 
-        # ADR-37 slice 2 — the method names this analyzer narrows on,
-        # for the plugin's `narrowing_facts methods:` gate.
+        # ADR-37 slice 2 — the method names this analyzer narrows on, for the plugin's
+        # `narrowing_facts methods:` gate.
         SUPPORTED_METHODS = (ASSERT_FORM.keys + SPEC_MATCHER_FORM.keys).freeze
 
         def spec_form_fact(call_node, environment:)
@@ -160,10 +147,9 @@ module Rigor
           fact_for_spec_shape(shape, target_local, args, negative: negative, environment: environment)
         end
 
-        # `_(x)` returns a `Minitest::Expectation` wrapping x.
-        # Some specs use `value(x)` or `expect(x)` interchangeably
-        # (Minitest provides all three as aliases). Recognises the
-        # local-variable arg in any of those receiver-call shapes.
+        # `_(x)` returns a `Minitest::Expectation` wrapping x. Some specs use `value(x)` or `expect(x)`
+        # interchangeably (Minitest provides all three as aliases). Recognises the local-variable arg in
+        # any of those receiver-call shapes.
         SPEC_WRAPPER_NAMES = %i[_ value expect].freeze
         private_constant :SPEC_WRAPPER_NAMES
 

data/plugins/rigor-minitest/lib/rigor/plugin/minitest.rb

@@ -6,61 +6,44 @@ require_relative "minitest/assertion_analyzer"
 
 module Rigor
   module Plugin
-    # rigor-minitest — narrows locals through Minitest /
-    # Test::Unit assertions.
+    # rigor-minitest — narrows locals through Minitest / Test::Unit assertions.
     #
-    # Recognises every supported `assert_*` / `refute_*` /
-    # `assert_not_*` shape (Minitest core + Test::Unit aliases),
-    # plus the Minitest/spec `_(x).must_*` / `.wont_*` matchers
-    # (`expect(x)` / `value(x)` wrappers covered too). For each
-    # recognised assertion the plugin emits a Rigor
-    # `post_return_fact` whose `:local`-kind target narrows the
-    # named local on the post-call edge so downstream calls in
-    # the same `it` / `test_` / `def test_*` body resolve
-    # against the narrowed type.
+    # Recognises every supported `assert_*` / `refute_*` / `assert_not_*` shape (Minitest core + Test::Unit
+    # aliases), plus the Minitest/spec `_(x).must_*` / `.wont_*` matchers (`expect(x)` / `value(x)` wrappers
+    # covered too). For each recognised assertion the plugin emits a Rigor `post_return_fact` whose
+    # `:local`-kind target narrows the named local on the post-call edge so downstream calls in the same
+    # `it` / `test_` / `def test_*` body resolve against the narrowed type.
     #
     # ## Why a single plugin covers two frameworks
     #
-    # Minitest and Test::Unit share the `assert_*` / `refute_*`
-    # surface (Test::Unit's `assert_not_*` aliases are
-    # recognised by the same rule table). The matchers_vaccine
-    # gem layers RSpec-style matcher composition on top of
-    # Minitest's `must` API and is covered by the spec-style
-    # recogniser without additional wiring.
+    # Minitest and Test::Unit share the `assert_*` / `refute_*` surface (Test::Unit's `assert_not_*` aliases
+    # are recognised by the same rule table). The matchers_vaccine gem layers RSpec-style matcher composition
+    # on top of Minitest's `must` API and is covered by the spec-style recogniser without additional wiring.
     #
     # ## Configuration
     #
-    # No configuration knobs. Activate via
-    # `plugins: ["rigor-minitest"]` in `.rigor.yml`.
+    # No configuration knobs. Activate via `plugins: ["rigor-minitest"]` in `.rigor.yml`.
     #
     # ## Limitations
     #
-    # - **No `assert_raises(T) { ... }`** — that's a block-shape
-    #   matcher and Rigor's narrowing model is for
+    # - **No `assert_raises(T) { ... }`** — that's a block-shape matcher and Rigor's narrowing model is for
     #   straight-line locals.
-    # - **No `assert_predicate(x, :foo?)`** — needs a
-    #   predicate-state carrier Rigor doesn't model today.
-    # - **No `assert_respond_to(x, :m)`** — same shape gap
-    #   (respond-to-set carrier).
-    # - **No legacy bare `x.must_be_kind_of(T)`** — the
-    #   receiver IS the value, so the analyzer has nothing to
+    # - **No `assert_predicate(x, :foo?)`** — needs a predicate-state carrier Rigor doesn't model today.
+    # - **No `assert_respond_to(x, :m)`** — same shape gap (respond-to-set carrier).
+    # - **No legacy bare `x.must_be_kind_of(T)`** — the receiver IS the value, so the analyzer has nothing to
     #   narrow against. Users should migrate to `_(x).must_*`.
-    # - **No `assert_in_delta` / `assert_operator`** — float-
-    #   range / generic operator narrowing is future work.
-    # - **No `assert_throws(:tag) { ... }` / `assert_raises`** —
-    #   block-form expectations need a separate slice.
+    # - **No `assert_in_delta` / `assert_operator`** — float-range / generic operator narrowing is future work.
+    # - **No `assert_throws(:tag) { ... }` / `assert_raises`** — block-form expectations need a separate slice.
     class Minitest < Rigor::Plugin::Base
       manifest(
         id: "minitest",
         version: "0.1.0",
         description: "Narrows locals through Minitest / Test::Unit `assert_*` / `refute_*` " \
                      "and Minitest/spec `_(x).must_*` / `.wont_*` matchers.",
-        # ADR-38 — `def setup` runs before every `def test_*`, so
-        # ivars it assigns are initialised by the time a test body
-        # reads them. Declaring it an additional initializer stops
-        # the read-before-write nil widening that would otherwise
-        # type `@conn` (set in `setup`, read in a test) as
-        # `T | nil` and surface a false nil-receiver diagnostic.
+        # ADR-38 — `def setup` runs before every `def test_*`, so ivars it assigns are initialised by the
+        # time a test body reads them. Declaring it an additional initializer stops the read-before-write
+        # nil widening that would otherwise type `@conn` (set in `setup`, read in a test) as `T | nil` and
+        # surface a false nil-receiver diagnostic.
         additional_initializers: [
           Rigor::Plugin::AdditionalInitializer.new(
             receiver_constraint: "Minitest::Test", methods: [:setup]
@@ -74,10 +57,8 @@ module Rigor
         ]
       )
 
-      # ADR-37 slice 2 — emits `post_return_facts` for every recognised
-      # assertion, method-gated by the engine. The engine routes
-      # `:local`-kind facts through
-      # `StatementEvaluator#apply_local_post_return_fact`.
+      # ADR-37 slice 2 — emits `post_return_facts` for every recognised assertion, method-gated by the
+      # engine. The engine routes `:local`-kind facts through `StatementEvaluator#apply_local_post_return_fact`.
       narrowing_facts methods: AssertionAnalyzer::SUPPORTED_METHODS do |call_node, scope|
         AssertionAnalyzer.contribution_for(call_node, environment: scope&.environment)&.post_return_facts
       end

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/analyzer.rb

@@ -6,41 +6,32 @@ require "prism"
 module Rigor
   module Plugin
     class Pundit < Rigor::Plugin::Base
-      # Walks a parsed file's AST looking for Pundit
-      # entry-point calls and validates each against the
+      # Walks a parsed file's AST looking for Pundit entry-point calls and validates each against the
       # {PolicyIndex}.
       #
       # Recognised shapes:
       #
-      # - `authorize(record, :action)` — record's inferred
-      #   type → `<Type>Policy#<action>?` lookup. Both the
+      # - `authorize(record, :action)` — record's inferred type → `<Type>Policy#<action>?` lookup. Both the
       #   policy class and the predicate must exist.
-      # - `authorize(record)` — without an action argument,
-      #   we only validate that `<Type>Policy` exists. The
-      #   action name is determined at runtime from the
-      #   controller's current action; static validation
+      # - `authorize(record)` — without an action argument, we only validate that `<Type>Policy` exists. The
+      #   action name is determined at runtime from the controller's current action; static validation
       #   isn't possible without controller context.
-      # - `policy(record)` / `policy_scope(scope)` — same
-      #   `<Type>Policy` existence check.
+      # - `policy(record)` / `policy_scope(scope)` — same `<Type>Policy` existence check.
       #
-      # When the first argument's inferred type is NOT a
-      # `Nominal[T]` (e.g. an untyped local variable), the
-      # call is silently passed through. The plugin only
-      # validates what it can prove from the static type
+      # When the first argument's inferred type is NOT a `Nominal[T]` (e.g. an untyped local variable), the
+      # call is silently passed through. The plugin only validates what it can prove from the static type
       # carrier.
       module Analyzer
         ENTRY_METHODS = %i[authorize policy policy_scope].freeze
 
-        # One policy violation: the kebab-case `rule`, `severity`, and
-        # human-readable `message`. Carries no path/location — the caller
-        # (the `node_rule` block) positions it via `Plugin::Base#diagnostic`.
+        # One policy violation: the kebab-case `rule`, `severity`, and human-readable `message`. Carries no
+        # path/location — the caller (the `node_rule` block) positions it via `Plugin::Base#diagnostic`.
         Violation = Struct.new(:rule, :severity, :message, keyword_init: true)
 
         module_function
 
-        # The policy violations for a single call node (0..2 of them), or
-        # `[]` when the node is not a Pundit entry call or its record type
-        # is not statically determinable. ADR-37: the engine owns the
+        # The policy violations for a single call node (0..2 of them), or `[]` when the node is not a
+        # Pundit entry call or its record type is not statically determinable. ADR-37: the engine owns the
         # walk, so this is per-node logic.
         #
         # @param call_node [Prism::Node]
@@ -71,15 +62,11 @@ module Rigor
           ENTRY_METHODS.include?(node.name) && node.receiver.nil?
         end
 
-        # Resolves the first-argument expression to a policy
-        # class name. The candidates are:
+        # Resolves the first-argument expression to a policy class name. The candidates are:
         # - `Foo` (a constant) → `FooPolicy`
-        # - `Foo.method(...)` whose inferred type is
-        #   `Nominal[Bar]` → `BarPolicy`
-        # - any other expression whose inferred type is
-        #   `Nominal[Bar]` → `BarPolicy`
-        # Returns `nil` when the type isn't statically
-        # determinable.
+        # - `Foo.method(...)` whose inferred type is `Nominal[Bar]` → `BarPolicy`
+        # - any other expression whose inferred type is `Nominal[Bar]` → `BarPolicy`
+        # Returns `nil` when the type isn't statically determinable.
         def derive_policy_class_name(record_node, scope)
           if record_node.is_a?(Prism::ConstantReadNode) || record_node.is_a?(Prism::ConstantPathNode)
             constant_name = constant_receiver_name(record_node)
@@ -118,10 +105,8 @@ module Rigor
           )
         end
 
-        # Validates the `authorize(record, :action)` form.
-        # Returns nil when the call has no second argument
-        # (the runtime infers it from the controller — out
-        # of scope here) or when the second argument isn't
+        # Validates the `authorize(record, :action)` form. Returns nil when the call has no second argument
+        # (the runtime infers it from the controller — out of scope here) or when the second argument isn't
         # a literal symbol / string.
         def action_violation(call_node, policy_entry)
           args = call_node.arguments&.arguments || []

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/policy_discoverer.rb

@@ -7,22 +7,17 @@ require_relative "policy_index"
 module Rigor
   module Plugin
     class Pundit < Rigor::Plugin::Base
-      # Walks the configured policy-search paths via the
-      # plugin's `IoBoundary`, parses each `.rb` file with
-      # Prism, and collects classes whose immediate
-      # superclass is one of the configured base classes.
+      # Walks the configured policy-search paths via the plugin's `IoBoundary`, parses each `.rb` file with
+      # Prism, and collects classes whose immediate superclass is one of the configured base classes.
       #
-      # For each discovered policy class, the discoverer
-      # collects every instance-side `def name?` predicate
-      # method. Non-predicate methods (`initialize`,
-      # `resolve`, helper methods) are ignored — Pundit's
+      # For each discovered policy class, the discoverer collects every instance-side `def name?` predicate
+      # method. Non-predicate methods (`initialize`, `resolve`, helper methods) are ignored — Pundit's
       # `authorize` only ever calls predicate methods.
       #
       # Limitations (intentional for v0.1.0):
       #
       # - Direct-superclass match only.
-      # - Predicate methods are read from the syntactic
-      #   `def` list. Methods built via `define_method` /
+      # - Predicate methods are read from the syntactic `def` list. Methods built via `define_method` /
       #   inherited from a sibling concern are out of scope.
       class PolicyDiscoverer
         def initialize(io_boundary:, search_paths:, base_classes:)
@@ -120,8 +115,7 @@ module Rigor
           end
         end
 
-        # Returns symbolic predicate names (`:update?`,
-        # `:show?`, …) defined on the policy. Only
+        # Returns symbolic predicate names (`:update?`, `:show?`, …) defined on the policy. Only
         # instance-side names that end in `?` are recorded.
         def collect_predicate_methods(body)
           return [] if body.nil?

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/policy_index.rb

@@ -3,14 +3,11 @@
 module Rigor
   module Plugin
     class Pundit < Rigor::Plugin::Base
-      # Frozen catalogue of discovered Pundit policy classes
-      # keyed by policy class name (e.g. `"PostPolicy"`).
-      # Each entry tracks the set of predicate methods
-      # defined on the policy (instance-side `def name?`)
+      # Frozen catalogue of discovered Pundit policy classes keyed by policy class name (e.g. `"PostPolicy"`).
+      # Each entry tracks the set of predicate methods defined on the policy (instance-side `def name?`)
       # plus the source file path.
       #
-      # The analyzer maps a record's inferred type
-      # (`Nominal[Post]`) to the policy class name
+      # The analyzer maps a record's inferred type (`Nominal[Post]`) to the policy class name
       # (`"PostPolicy"`) and looks up the predicate.
       class PolicyIndex
         Entry = Data.define(:policy_class_name, :file_path, :predicate_methods) do
@@ -22,8 +19,7 @@ module Rigor
             predicate_methods.to_a.sort
           end
 
-          # Normalises an action symbol / string by ensuring
-          # a trailing `?`. `:update` and `:update?` both
+          # Normalises an action symbol / string by ensuring a trailing `?`. `:update` and `:update?` both
           # resolve to `update?`.
           def normalize(name)
             string = name.to_s

data/plugins/rigor-pundit/lib/rigor/plugin/pundit.rb

@@ -8,13 +8,11 @@ require_relative "pundit/analyzer"
 
 module Rigor
   module Plugin
-    # rigor-pundit — validates Pundit `authorize` /
-    # `policy` / `policy_scope` calls against the project's
+    # rigor-pundit — validates Pundit `authorize` / `policy` / `policy_scope` calls against the project's
     # `app/policies/` tree.
     #
     # Tier 3B of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
-    # Statically discovers policy classes by walking
-    # `policy_search_paths` and parsing each file with
+    # Statically discovers policy classes by walking `policy_search_paths` and parsing each file with
     # Prism — no `pundit` runtime dependency.
     #
     # ## Configuration
@@ -27,34 +25,22 @@ module Rigor
     #
     # ## What it checks
     #
-    # 1. **Policy class existence** — `authorize(record, ...)`
-    #    looks up `<inferred-type>Policy` in the index.
-    #    Missing policies emit `unknown-policy-class` with
-    #    a did-you-mean suggestion.
-    # 2. **Predicate method existence** — for the
-    #    `authorize(record, :action)` form, validates that
-    #    `<Policy>#<action>?` is defined. Missing methods
-    #    emit `unknown-policy-method` listing the known
+    # 1. **Policy class existence** — `authorize(record, ...)` looks up `<inferred-type>Policy` in the index.
+    #    Missing policies emit `unknown-policy-class` with a did-you-mean suggestion.
+    # 2. **Predicate method existence** — for the `authorize(record, :action)` form, validates that
+    #    `<Policy>#<action>?` is defined. Missing methods emit `unknown-policy-method` listing the known
     #    predicates.
     #
     # ## Limitations (v0.1.0)
     #
-    # - Records whose inferred type is NOT a `Nominal[T]`
-    #   (untyped local variables, untyped instance
-    #   variables) are silently passed through. The plugin
-    #   only validates what it can prove from the static
-    #   carrier.
-    # - The two-argument form
-    #   `authorize(record, :action_symbol)` is the only
-    #   one validated. The implicit form
-    #   `authorize(record)` (which Pundit resolves at
-    #   runtime against the controller's current action) is
-    #   passed through with the policy-class check only.
-    # - Direct-superclass match for `policy_base_classes`.
-    #   Indirect inheritance (`AdminPolicy <
-    #   ApplicationPolicy`) needs `AdminPolicy` listed in
-    #   `policy_base_classes` if subclasses inherit from
-    #   it.
+    # - Records whose inferred type is NOT a `Nominal[T]` (untyped local variables, untyped instance
+    #   variables) are silently passed through. The plugin only validates what it can prove from the
+    #   static carrier.
+    # - The two-argument form `authorize(record, :action_symbol)` is the only one validated. The implicit
+    #   form `authorize(record)` (which Pundit resolves at runtime against the controller's current action)
+    #   is passed through with the policy-class check only.
+    # - Direct-superclass match for `policy_base_classes`. Indirect inheritance (`AdminPolicy <
+    #   ApplicationPolicy`) needs `AdminPolicy` listed in `policy_base_classes` if subclasses inherit from it.
     class Pundit < Rigor::Plugin::Base
       manifest(
         id: "pundit",
@@ -79,10 +65,9 @@ module Rigor
         @policy_base_classes = Array(config.fetch("policy_base_classes")).map(&:to_s)
       end
 
-      # File-level only: the load-error emission. The per-call policy
-      # validation runs over the engine-owned walk via the node_rule
-      # below (ADR-37). The index is lazily loaded + memoised by
-      # `producer_value`, so both surfaces share one load.
+      # File-level only: the load-error emission. The per-call policy validation runs over the engine-owned
+      # walk via the node_rule below (ADR-37). The index is lazily loaded + memoised by `producer_value`,
+      # so both surfaces share one load.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:policy_index)
         return [load_error_diagnostic(path)] if index.nil? && producer_error(:policy_index)