rigortype 0.2.7 → 0.2.8

data/plugins/rigor-actionpack/lib/rigor/plugin/actionpack/controller_index.rb

@@ -3,13 +3,11 @@
 module Rigor
   module Plugin
     class Actionpack < Rigor::Plugin::Base
-      # Per-run frozen index of discovered controllers AND
-      # concerns (modules) in `controller_search_paths`. Phase 2
-      # (filter-chain validation) consults the index at every
-      # call site to check that `before_action :name` references
-      # a method that actually exists on the controller, its
-      # parent (one level of inheritance), or any module the
-      # controller or its ancestor chain transitively `include`s.
+      # Per-run frozen index of discovered controllers AND concerns (modules) in
+      # `controller_search_paths`. Phase 2 (filter-chain validation) consults the index at every call
+      # site to check that `before_action :name` references a method that actually exists on the
+      # controller, its parent (one level of inheritance), or any module the controller or its ancestor
+      # chain transitively `include`s.
       #
       # Real-world example (Mastodon):
       #   AccountsController < ApplicationController
@@ -19,23 +17,17 @@ module Rigor
       #   SignatureVerification < module
       #     def require_account_signature!        # ← the filter target
       #
-      # The include chain spans three concern modules.
-      # `effective_methods_for("AccountsController")` walks all
-      # of them transitively to collect `require_account_signature!`.
+      # The include chain spans three concern modules. `effective_methods_for("AccountsController")`
+      # walks all of them transitively to collect `require_account_signature!`.
       class ControllerIndex
-        # `defined_methods` carries the discovered method names
-        # (Symbols). `included_module_names` carries the constant
-        # names passed to `include X` calls inside the
-        # class / module body (Strings). `parent_class_name` is
-        # the immediate superclass (nil for plain modules).
-        # `enclosing_namespace` is the qualifier chain of the
-        # declaration's *lexical* enclosing scope (e.g.
-        # `["Admin"]` for an `Admin::Foo` declared via
-        # `module Admin; class Foo; end; end`). Used by the
-        # index's parent / module lookup to try lexically-scoped
-        # constant resolution before falling through to the
-        # top-level form — Ruby's constant lookup walks the
-        # enclosing scope chain before `Object`.
+        # `defined_methods` carries the discovered method names (Symbols). `included_module_names`
+        # carries the constant names passed to `include X` calls inside the class / module body
+        # (Strings). `parent_class_name` is the immediate superclass (nil for plain modules).
+        # `enclosing_namespace` is the qualifier chain of the declaration's *lexical* enclosing scope
+        # (e.g. `["Admin"]` for an `Admin::Foo` declared via `module Admin; class Foo; end; end`). Used
+        # by the index's parent / module lookup to try lexically-scoped constant resolution before
+        # falling through to the top-level form — Ruby's constant lookup walks the enclosing scope chain
+        # before `Object`.
         Entry = Data.define(:class_name, :defined_methods, :parent_class_name, :included_module_names,
                             :enclosing_namespace)
 
@@ -51,20 +43,15 @@ module Rigor
           @entries[class_name]
         end
 
-        # Resolves the **effective** method set for a controller,
-        # including methods contributed by every module the
-        # controller / any ancestor transitively `include`s AND
-        # methods inherited from the ancestor chain (unbounded
-        # depth, cycle-safe via a visited set).
+        # Resolves the **effective** method set for a controller, including methods contributed by
+        # every module the controller / any ancestor transitively `include`s AND methods inherited from
+        # the ancestor chain (unbounded depth, cycle-safe via a visited set).
         #
-        # Parent / module lookups are **lexically scoped** — a
-        # bare `BaseController` reference inside `module Admin`
-        # first tries `Admin::BaseController`, then falls
-        # through to the top-level `BaseController`. Matches
-        # Ruby's constant-resolution semantics. Without this an
-        # `Admin::Foo < BaseController` declaration would
-        # incorrectly walk the top-level `BaseController` even
-        # when an `Admin::BaseController` exists.
+        # Parent / module lookups are **lexically scoped** — a bare `BaseController` reference inside
+        # `module Admin` first tries `Admin::BaseController`, then falls through to the top-level
+        # `BaseController`. Matches Ruby's constant-resolution semantics. Without this an `Admin::Foo <
+        # BaseController` declaration would incorrectly walk the top-level `BaseController` even when an
+        # `Admin::BaseController` exists.
         def effective_methods_for(class_name)
           seen_classes = {}
           seen_modules = {}
@@ -81,11 +68,9 @@ module Rigor
               collect_methods(resolved_include, seen_modules, methods)
             end
             next_parent = entry.parent_class_name
-            # Same self-reference guard as `unresolved_include?`:
-            # `class ActivityPub::ApplicationController <
-            # ::ApplicationController` lexically resolves
-            # `ApplicationController` to itself; fall back to
-            # the unprefixed top-level name in that case.
+            # Same self-reference guard as `unresolved_include?`: `class ActivityPub::ApplicationController
+            # < ::ApplicationController` lexically resolves `ApplicationController` to itself; fall back
+            # to the unprefixed top-level name in that case.
             current = if next_parent
                         resolved = resolve_constant_lexically(next_parent, entry.enclosing_namespace)
                         resolved == current ? next_parent.sub(/\A::/, "") : resolved
@@ -94,30 +79,23 @@ module Rigor
           methods.uniq.freeze
         end
 
-        # @return [Boolean] true when the class has at least one
-        #   include OR parent class we couldn't resolve in the
-        #   index (typically a gem-shipped concern such as Devise's
-        #   `Devise::Controllers::Helpers`, or a gem-shipped
-        #   parent controller such as `Devise::ConfirmationsController`
-        #   or `Doorkeeper::AuthorizedApplicationsController`).
-        #   Phase 2 uses this to downgrade `unknown-filter-method`
-        #   to silence — the unresolved module / parent may
-        #   legitimately contribute the filter (either directly,
-        #   or via its own ancestor chain which the static
-        #   analyzer cannot follow), and there's no way to verify.
+        # @return [Boolean] true when the class has at least one include OR parent class we couldn't
+        #   resolve in the index (typically a gem-shipped concern such as Devise's
+        #   `Devise::Controllers::Helpers`, or a gem-shipped parent controller such as
+        #   `Devise::ConfirmationsController` or `Doorkeeper::AuthorizedApplicationsController`). Phase
+        #   2 uses this to downgrade `unknown-filter-method` to silence — the unresolved module / parent
+        #   may legitimately contribute the filter (either directly, or via its own ancestor chain which
+        #   the static analyzer cannot follow), and there's no way to verify.
         def unresolved_include?(class_name)
           entry = @entries[class_name]
           return false if entry.nil?
 
-          # Walk the full ancestor chain. `Admin::Foo <
-          # BaseController < ApplicationController` should report
-          # an unresolved include if ANY of the three references
-          # a gem-shipped concern OR a gem-shipped parent class
-          # we cannot index. The first iteration's `current_entry`
-          # is always resolved (caller verified `known?`); a nil
-          # `current_entry` on a subsequent iteration means the
-          # AST-side `< Parent` reached a gem-shipped class
-          # whose ancestor methods are invisible to us.
+          # Walk the full ancestor chain. `Admin::Foo < BaseController < ApplicationController` should
+          # report an unresolved include if ANY of the three references a gem-shipped concern OR a
+          # gem-shipped parent class we cannot index. The first iteration's `current_entry` is always
+          # resolved (caller verified `known?`); a nil `current_entry` on a subsequent iteration means
+          # the AST-side `< Parent` reached a gem-shipped class whose ancestor methods are invisible to
+          # us.
           seen_classes = {}
           current = class_name
           first = true
@@ -136,15 +114,11 @@ module Rigor
               return true if resolved.nil? || !@entries.key?(resolved)
             end
             next_parent = current_entry.parent_class_name
-            # Avoid lexically resolving to ourselves. `class
-            # ActivityPub::ApplicationController < ::ApplicationController`
-            # would otherwise resolve `ApplicationController` (in
-            # the lexical scope `["ActivityPub"]`) to
-            # `ActivityPub::ApplicationController` and short-
-            # circuit the walk before reaching the top-level
-            # parent. When the lexical match is the current
-            # class itself, fall back to the unprefixed
-            # top-level name.
+            # Avoid lexically resolving to ourselves. `class ActivityPub::ApplicationController <
+            # ::ApplicationController` would otherwise resolve `ApplicationController` (in the lexical
+            # scope `["ActivityPub"]`) to `ActivityPub::ApplicationController` and short-circuit the walk
+            # before reaching the top-level parent. When the lexical match is the current class itself,
+            # fall back to the unprefixed top-level name.
             current = if next_parent
                         resolved = resolve_constant_lexically(next_parent, current_entry.enclosing_namespace)
                         resolved == current ? next_parent.sub(/\A::/, "") : resolved
@@ -181,37 +155,28 @@ module Rigor
           end
         end
 
-        # Ruby's constant-lookup walk: a bare constant name
-        # inside `module Admin` first tries `Admin::Const`,
-        # then walks outward, and finally falls through to
-        # top-level `Const`. We approximate that by trying
-        # the candidate `enclosing + name` chains from
-        # deepest to shallowest, and returning the first
-        # candidate that has an entry in the index. When
-        # nothing resolves, return the original name
-        # unchanged — the caller treats unresolved entries as
-        # "gem-shipped concerns we cannot see" (the
-        # `unresolved_include?` predicate).
+        # Ruby's constant-lookup walk: a bare constant name inside `module Admin` first tries
+        # `Admin::Const`, then walks outward, and finally falls through to top-level `Const`. We
+        # approximate that by trying the candidate `enclosing + name` chains from deepest to shallowest,
+        # and returning the first candidate that has an entry in the index. When nothing resolves,
+        # return the original name unchanged — the caller treats unresolved entries as "gem-shipped
+        # concerns we cannot see" (the `unresolved_include?` predicate).
         #
-        # `name` may already be qualified (`Foo::Bar`); we
-        # only try lexical prefixing when the unqualified
-        # first segment doesn't match a top-level entry.
+        # `name` may already be qualified (`Foo::Bar`); we only try lexical prefixing when the
+        # unqualified first segment doesn't match a top-level entry.
         def resolve_constant_lexically(name, enclosing)
           return nil if name.nil?
 
-          # A leading `::` denotes the top-level constant
-          # explicitly (`< ::ApplicationController`). Strip it
-          # for index lookup — the discoverer registers entries
-          # under their unprefixed name. Without this strip a
-          # `class ActivityPub::ApplicationController <
-          # ::ApplicationController` parent never resolved.
+          # A leading `::` denotes the top-level constant explicitly (`< ::ApplicationController`).
+          # Strip it for index lookup — the discoverer registers entries under their unprefixed name.
+          # Without this strip a `class ActivityPub::ApplicationController < ::ApplicationController`
+          # parent never resolved.
           name = name.sub(/\A::/, "")
 
           # Constant already absolute or no enclosing scope.
           return name if enclosing.nil? || enclosing.empty?
 
-          # Try the deepest enclosing scope first, walking
-          # outward. `enclosing = ["A", "B"]` produces
+          # Try the deepest enclosing scope first, walking outward. `enclosing = ["A", "B"]` produces
           # candidates `["A::B::name", "A::name", "name"]`.
           enclosing.length.downto(0).each do |depth|
             prefix = enclosing[0, depth]

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

@@ -8,20 +8,15 @@ require_relative "actionpack/controller_index"
 
 module Rigor
   module Plugin
-    # rigor-actionpack — validates Action Pack DSL calls in
-    # controller files.
+    # rigor-actionpack — validates Action Pack DSL calls in controller files.
     #
-    # **Phase 4 of the Action Pack plugin family** (route-helper
-    # consumption). Reads the `:helper_table` fact published by
-    # `rigor-rails-routes` (ADR-9 cross-plugin API) and validates
-    # every implicit-self `*_path` / `*_url` call inside files
-    # under `controller_search_paths` (default `app/controllers`).
+    # **Phase 4 of the Action Pack plugin family** (route-helper consumption). Reads the `:helper_table`
+    # fact published by `rigor-rails-routes` (ADR-9 cross-plugin API) and validates every implicit-self
+    # `*_path` / `*_url` call inside files under `controller_search_paths` (default `app/controllers`).
     #
     # Tier 2 of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
-    # Phase 1 (strong-parameters → AR column validation), Phase 2
-    # (filter chains), and Phase 3 (render targets) ship as
-    # separate slices; each phase composes additively under the
-    # same plugin id.
+    # Phase 1 (strong-parameters → AR column validation), Phase 2 (filter chains), and Phase 3 (render
+    # targets) ship as separate slices; each phase composes additively under the same plugin id.
     #
     # ## Configuration
     #
@@ -36,46 +31,35 @@ module Rigor
     #
     # ## What it checks
     #
-    # - **Helper existence** — every `*_path` / `*_url` call
-    #   inside a controller file is looked up in the helper
-    #   table. Missing entries emit `unknown-helper` with a
-    #   `DidYouMean` suggestion drawn from the table.
-    # - **Helper arity** — the call's positional-argument count
-    #   is matched against the helper's recorded arity (a
-    #   trailing `KeywordHashNode` like `users_path(format: :json)`
-    #   is excluded; same convention `rigor-rails-routes` uses).
-    #   Mismatches emit `wrong-helper-arity`.
-    # - **Trace** — recognised helpers also emit a
-    #   `helper-call` info diagnostic naming the action and
+    # - **Helper existence** — every `*_path` / `*_url` call inside a controller file is looked up in
+    #   the helper table. Missing entries emit `unknown-helper` with a `DidYouMean` suggestion drawn
+    #   from the table.
+    # - **Helper arity** — the call's positional-argument count is matched against the helper's
+    #   recorded arity (a trailing `KeywordHashNode` like `users_path(format: :json)` is excluded; same
+    #   convention `rigor-rails-routes` uses). Mismatches emit `wrong-helper-arity`.
+    # - **Trace** — recognised helpers also emit a `helper-call` info diagnostic naming the action and
     #   path, mirroring the trace shape of the upstream plugin.
     #
     # ## Limitations
     #
-    # - Implicit-self calls only. `Rails.application.routes.url_helpers.users_path`
-    #   and other explicit-receiver shapes are passed through;
-    #   they're rare in controller code and the helper table
-    #   doesn't include any extra context to validate them.
-    # - Files outside `controller_search_paths` are skipped.
-    #   The plugin doesn't try to detect "is this a controller?"
-    #   by class hierarchy — Phase 1's strong-parameters work
-    #   needs that, so it lives there. Phase 4's job is the
-    #   single-purpose helper check.
-    # - When `rigor-rails-routes` is not installed (or its
-    #   helper table is empty), Phase 4 silently degrades to a
-    #   no-op. No load-error diagnostic is emitted; the user
-    #   gets the "no checks happened" failure mode rather than
-    #   a wall of "is this configured right?" warnings.
+    # - Implicit-self calls only. `Rails.application.routes.url_helpers.users_path` and other
+    #   explicit-receiver shapes are passed through; they're rare in controller code and the helper
+    #   table doesn't include any extra context to validate them.
+    # - Files outside `controller_search_paths` are skipped. The plugin doesn't try to detect "is this
+    #   a controller?" by class hierarchy — Phase 1's strong-parameters work needs that, so it lives
+    #   there. Phase 4's job is the single-purpose helper check.
+    # - When `rigor-rails-routes` is not installed (or its helper table is empty), Phase 4 silently
+    #   degrades to a no-op. No load-error diagnostic is emitted; the user gets the "no checks
+    #   happened" failure mode rather than a wall of "is this configured right?" warnings.
     class Actionpack < Rigor::Plugin::Base
       manifest(
         id: "actionpack",
-        # ADR-37: the four phases (helper / filter / render /
-        # strong-params) run per-call over the engine-owned walk;
-        # the enclosing controller is read from the node-rule
-        # `NodeContext` ancestors. Nested-module qualification is
-        # preserved — `module Admin; class DomainBlocksController`
-        # resolves as `Admin::DomainBlocksController` (matching the
-        # `ControllerDiscoverer`), so render paths and filter-chain
-        # validation on nested controllers are correct.
+        # ADR-37: the four phases (helper / filter / render / strong-params) run per-call over the
+        # engine-owned walk; the enclosing controller is read from the node-rule `NodeContext`
+        # ancestors. Nested-module qualification is preserved — `module Admin; class
+        # DomainBlocksController` resolves as `Admin::DomainBlocksController` (matching the
+        # `ControllerDiscoverer`), so render paths and filter-chain validation on nested controllers are
+        # correct.
         version: "0.9.0",
         description: "Validates Action Pack route-helper calls and filter chains inside controllers, and types the request-context readers (`params` / `session` / `request`).",
         config_schema: {
@@ -88,12 +72,10 @@ module Rigor
         ]
       )
 
-      # Phase 2 cached producer — the controller index built from
-      # `controller_search_paths`. `watch:` (ADR-60 WD3) covers every
-      # `.rb` file under those roots so the cache invalidates when a
-      # controller is added, removed, or edited; the discoverer's
-      # in-block `io_boundary` reads are captured into the dependency
-      # descriptor too, so no explicit priming is needed.
+      # Phase 2 cached producer — the controller index built from `controller_search_paths`. `watch:`
+      # (ADR-60 WD3) covers every `.rb` file under those roots so the cache invalidates when a
+      # controller is added, removed, or edited; the discoverer's in-block `io_boundary` reads are
+      # captured into the dependency descriptor too, so no explicit priming is needed.
       producer :controller_index, watch: -> { [[@controller_search_paths, "**/*.rb"]] } do |_params|
         ControllerDiscoverer.new(
           io_boundary: io_boundary,
@@ -106,18 +88,15 @@ module Rigor
         @view_search_paths = Array(config.fetch("view_search_paths")).map(&:to_s)
       end
 
-      # ADR-37 — the four Action Pack phases run per-call over the
-      # engine-owned walk. Each rule gates on `controller_file?(path)` (the
-      # plugin only validates files under `controller_search_paths`,
-      # exactly as the former `diagnostics_for_file` top-level guard did),
-      # then delegates to a per-node `Analyzer.*_violations_for` and
-      # positions each location-free `Violation` with `Base#diagnostic`.
-      # The filter / render phases read the enclosing controller from the
-      # node-rule `NodeContext` ancestors (its fifth block argument).
-
-      # Phase 4 — route-helper consumption. `:helper_table` is
-      # rigor-rails-routes's published fact (ADR-9), read lazily via
-      # `read_fact`.
+      # ADR-37 — the four Action Pack phases run per-call over the engine-owned walk. Each rule gates on
+      # `controller_file?(path)` (the plugin only validates files under `controller_search_paths`,
+      # exactly as the former `diagnostics_for_file` top-level guard did), then delegates to a per-node
+      # `Analyzer.*_violations_for` and positions each location-free `Violation` with `Base#diagnostic`.
+      # The filter / render phases read the enclosing controller from the node-rule `NodeContext`
+      # ancestors (its fifth block argument).
+
+      # Phase 4 — route-helper consumption. `:helper_table` is rigor-rails-routes's published fact
+      # (ADR-9), read lazily via `read_fact`.
       node_rule Prism::CallNode do |node, _scope, path|
         next [] unless controller_file?(path)
 
@@ -127,9 +106,8 @@ module Rigor
         diagnostics_for(Analyzer.helper_violations_for(call_node: node, helper_table: table), path: path, node: node)
       end
 
-      # Phase 2 — filter-chain validation. Skips silently when the
-      # controller index is absent or doesn't recognise the enclosing
-      # class.
+      # Phase 2 — filter-chain validation. Skips silently when the controller index is absent or
+      # doesn't recognise the enclosing class.
       node_rule Prism::CallNode do |node, _scope, path, _fc, context|
         next [] unless controller_file?(path)
 
@@ -142,11 +120,9 @@ module Rigor
         )
       end
 
-      # Phase 3 — render-target validation against the configured
-      # `view_search_paths`. Recognised purely from the call site + the
-      # enclosing controller name, so no per-controller pre-discovery is
-      # needed; the controller index is consulted only to suppress
-      # gem-shipped-view false positives.
+      # Phase 3 — render-target validation against the configured `view_search_paths`. Recognised purely
+      # from the call site + the enclosing controller name, so no per-controller pre-discovery is
+      # needed; the controller index is consulted only to suppress gem-shipped-view false positives.
       node_rule Prism::CallNode do |node, _scope, path, _fc, context|
         next [] unless controller_file?(path)
 
@@ -159,11 +135,9 @@ module Rigor
         )
       end
 
-      # Phase 1 — strong-parameter validation. Reads the `:model_index`
-      # fact from the cross-plugin fact store (published by
-      # rigor-activerecord) and validates every
-      # `params.require(:user).permit(:name, :email)` chain against the
-      # User model's column list.
+      # Phase 1 — strong-parameter validation. Reads the `:model_index` fact from the cross-plugin fact
+      # store (published by rigor-activerecord) and validates every `params.require(:user).permit(:name,
+      # :email)` chain against the User model's column list.
       node_rule Prism::CallNode do |node, _scope, path|
         next [] unless controller_file?(path)
 
@@ -173,28 +147,21 @@ module Rigor
         diagnostics_for(Analyzer.permit_violations_for(call_node: node, model_index: index), path: path, node: node)
       end
 
-      # Phase 5 (2026-07-04) — type the implicit-self request-context
-      # readers (`params`, `session`, `request`, `flash`, `cookies`)
-      # inside controllers. The
-      # typing-obstacle probe
-      # (docs/notes/20260704-rails-coverage-onboarding-carrier-trap.md,
-      # obstacle O3) found `params` typing to `Dynamic[top]` the single
-      # largest protection-coverage hole on real Rails apps: `params[:x]`
-      # is the #1 dispatch cluster (redmine app+lib: `[]` 2378 sites) and
-      # `session[:x] =` a large share of the `[]=` cluster, all
-      # unprotected because the receiver is Dynamic.
+      # Phase 5 (2026-07-04) — type the implicit-self request-context readers (`params`, `session`,
+      # `request`, `flash`, `cookies`) inside controllers. The typing-obstacle probe
+      # (docs/notes/20260704-rails-coverage-onboarding-carrier-trap.md, obstacle O3) found `params`
+      # typing to `Dynamic[top]` the single largest protection-coverage hole on real Rails apps:
+      # `params[:x]` is the #1 dispatch cluster (redmine app+lib: `[]` 2378 sites) and `session[:x] =` a
+      # large share of the `[]=` cluster, all unprotected because the receiver is Dynamic.
       #
-      # Each returns a bare nominal with NO bundled RBS on purpose. That
-      # makes the reader a *concrete* receiver (so `coverage --protection`
-      # counts the site as protected and the dispatch resolves against a
-      # named class) while its method surface stays engine-lenient — Rigor
-      # does not fire `undefined-method` on a class it has no RBS for, so
-      # `params.require(...).permit(...)`, `session.delete(:x)`,
-      # `request.xhr?`, and every other method on these stay FP-safe.
-      # Shipping a partial RBS would re-introduce the carrier-additivity
-      # trap (a declared class drops every member the RBS omits → false
-      # `undefined-method`). ADR-5: this types the container, never the
-      # caller's argument, so the values stay lenient.
+      # Each returns a bare nominal with NO bundled RBS on purpose. That makes the reader a *concrete*
+      # receiver (so `coverage --protection` counts the site as protected and the dispatch resolves
+      # against a named class) while its method surface stays engine-lenient — Rigor does not fire
+      # `undefined-method` on a class it has no RBS for, so `params.require(...).permit(...)`,
+      # `session.delete(:x)`, `request.xhr?`, and every other method on these stay FP-safe. Shipping a
+      # partial RBS would re-introduce the carrier-additivity trap (a declared class drops every member
+      # the RBS omits → false `undefined-method`). ADR-5: this types the container, never the caller's
+      # argument, so the values stay lenient.
       REQUEST_CONTEXT_READER_TYPES = {
         params: "ActionController::Parameters",
         session: "ActionDispatch::Request::Session",
@@ -217,12 +184,10 @@ module Rigor
 
       private
 
-      # True when the current `self` is a controller — the enclosing
-      # class is one the discoverer indexed, or its name follows the
-      # Rails `*Controller` convention (covering controllers outside
-      # `controller_search_paths`, e.g. one shipped by an engine).
-      # Typing `params` is precision-additive, so the name-convention
-      # fallback is FP-safe.
+      # True when the current `self` is a controller — the enclosing class is one the discoverer
+      # indexed, or its name follows the Rails `*Controller` convention (covering controllers outside
+      # `controller_search_paths`, e.g. one shipped by an engine). Typing `params` is precision-additive,
+      # so the name-convention fallback is FP-safe.
       def controller_scope?(scope)
         self_type = scope&.self_type
         return false unless self_type.respond_to?(:class_name)
@@ -238,12 +203,10 @@ module Rigor
 
       def controller_file?(path)
         @controller_search_paths.any? do |root|
-          # The runner may pass `path` as either an absolute
-          # path (when `paths:` was configured absolutely) or a
-          # relative one (when configured relatively). The
-          # `controller_search_paths` knob is always project-
-          # root-relative. Match the configured root as a
-          # /-bracketed substring so both shapes resolve.
+          # The runner may pass `path` as either an absolute path (when `paths:` was configured
+          # absolutely) or a relative one (when configured relatively). The `controller_search_paths`
+          # knob is always project-root-relative. Match the configured root as a /-bracketed substring
+          # so both shapes resolve.
           path.include?("/#{root}/") || path.start_with?("#{root}/") || path == root
         end
       end

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

@@ -5,34 +5,26 @@ require "prism"
 module Rigor
   module Plugin
     class Activejob < Rigor::Plugin::Base
-      # Walks a parsed file's AST looking for
-      # `<JobClass>.perform_later(...)` /
-      # `.perform_now(...)` / `.perform(...)` calls and
-      # validates each against the {JobIndex}.
+      # Walks a parsed file's AST looking for `<JobClass>.perform_later(...)` / `.perform_now(...)` /
+      # `.perform(...)` calls and validates each against the {JobIndex}.
       #
-      # The plugin recognises a call as job-shaped when the
-      # receiver is a `ConstantReadNode` / `ConstantPathNode`
-      # whose resolved name appears in the index, and the
-      # method name is one of the three ActiveJob entry
-      # points.
+      # The plugin recognises a call as job-shaped when the receiver is a `ConstantReadNode` /
+      # `ConstantPathNode` whose resolved name appears in the index, and the method name is one of the
+      # three ActiveJob entry points.
       module Analyzer
-        # Methods that delegate to the job's `#perform`. All
-        # three accept the same argument shape — `perform_later`
-        # is the most common (queues for later execution),
-        # `perform_now` runs synchronously, and `perform` is
-        # the bare execution path.
+        # Methods that delegate to the job's `#perform`. All three accept the same argument shape —
+        # `perform_later` is the most common (queues for later execution), `perform_now` runs
+        # synchronously, and `perform` is the bare execution path.
         ENTRY_METHODS = %i[perform_later perform_now perform].freeze
 
-        # One job-call observation. Carries no path/location — the
-        # caller (the `node_rule` block) positions it via
-        # `Plugin::Base#diagnostic`.
+        # One job-call observation. 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 job-call violations for a single call node (0..2), or `[]`
-        # when the node is not a `<Job>.perform_*` entry call on a known
-        # job. ADR-37: the engine owns the walk.
+        # The job-call violations for a single call node (0..2), or `[]` when the node is not a
+        # `<Job>.perform_*` entry call on a known job. ADR-37: the engine owns the walk.
         #
         # @param call_node [Prism::Node]
         # @param job_index [JobIndex]
@@ -76,8 +68,7 @@ module Rigor
           )
         end
 
-        # Renders a constant-path receiver as a String.
-        # Mirrors the helpers in rigor-activerecord /
+        # Renders a constant-path receiver as a String. Mirrors the helpers in rigor-activerecord /
         # rigor-rails-routes for parity.
         def constant_receiver_name(node)
           case node

data/plugins/rigor-activejob/lib/rigor/plugin/activejob/job_discoverer.rb

@@ -7,25 +7,19 @@ require_relative "job_index"
 module Rigor
   module Plugin
     class Activejob < Rigor::Plugin::Base
-      # Walks the configured job-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 class,
-      # the discoverer also reads the `#perform` method's
-      # parameter list and computes the arity envelope.
+      # Walks the configured job-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 class, the discoverer also reads the `#perform` method's parameter list and
+      # computes the arity envelope.
       #
       # Limitations (intentional for v0.1.0):
       #
-      # - Only direct-superclass matches. `class WelcomeJob <
-      #   BaseJob` where `BaseJob < ApplicationJob` is NOT
-      #   discovered. List `BaseJob` in `job_base_classes`
-      #   if needed.
-      # - The qualified class name is the lexical path
-      #   (`Admin::WelcomeJob` for a class declared inside
+      # - Only direct-superclass matches. `class WelcomeJob < BaseJob` where `BaseJob < ApplicationJob`
+      #   is NOT discovered. List `BaseJob` in `job_base_classes` if needed.
+      # - The qualified class name is the lexical path (`Admin::WelcomeJob` for a class declared inside
       #   `module Admin`).
-      # - The `#perform` arity is read from the syntactic
-      #   parameter list. Methods built via `define_method`
-      #   are out of scope.
+      # - The `#perform` arity is read from the syntactic parameter list. Methods built via
+      #   `define_method` are out of scope.
       class JobDiscoverer
         def initialize(io_boundary:, search_paths:, base_classes:)
           @io_boundary = io_boundary
@@ -119,9 +113,8 @@ module Rigor
           end
         end
 
-        # Returns the `def perform(...)` node from a class
-        # body, or `nil` when the class doesn't override
-        # `#perform`. Only matches instance-side `def perform`.
+        # Returns the `def perform(...)` node from a class body, or `nil` when the class doesn't
+        # override `#perform`. Only matches instance-side `def perform`.
         def lookup_perform_def(body)
           return nil if body.nil?
 
@@ -134,13 +127,10 @@ module Rigor
           nil
         end
 
-        # Builds a JobIndex::Entry from the discovered class's
-        # `#perform` def. When the class doesn't override
-        # `#perform`, we record an "any-arity" entry — Active
-        # Job's default `#perform` is abstract; calling
-        # `perform_later` on a job that didn't override it is
-        # itself a bug, but it's the user's bug, not the
-        # plugin's call to flag without runtime context.
+        # Builds a JobIndex::Entry from the discovered class's `#perform` def. When the class doesn't
+        # override `#perform`, we record an "any-arity" entry — Active Job's default `#perform` is
+        # abstract; calling `perform_later` on a job that didn't override it is itself a bug, but it's
+        # the user's bug, not the plugin's call to flag without runtime context.
         def build_entry(class_name, perform_def)
           if perform_def.nil?
             return JobIndex::Entry.new(