rigortype 0.2.7 → 0.2.9

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",
@@ -215,14 +182,33 @@ module Rigor
         Rigor::Type::Combinator.nominal_of(class_name)
       end
 
+      # Phase 5b (2026-07-10) — keep the strong-parameters fluent chain typed. `params` types to
+      # `ActionController::Parameters` (above), but the chained `params.require(:user).permit(:name)` /
+      # `params.permit(...)` calls returned `Dynamic` at the first hop (Parameters ships no bundled RBS,
+      # so a call on it resolves lenient-to-Dynamic), leaking every downstream site (`.permit`, `.to_h`,
+      # `.each`) to unprotected. These three methods return another `Parameters`, so gate on a
+      # `Parameters` receiver and re-type the result as the same lenient nominal — the chain stays a
+      # concrete receiver end-to-end and `coverage --protection` counts the sites as protected.
+      #
+      # `require` may return a scalar for a flat key at runtime (`params.require(:id) → String`), but
+      # typing it as the RBS-less `Parameters` is FP-safe by the same argument as the readers: every
+      # method on a Parameters value stays engine-lenient (no `undefined-method`), and this types the
+      # container only, never a caller's argument (ADR-5). The GitLab strong-params survey (108 leaked
+      # `.permit` sites) is the demand.
+      STRONG_PARAMS_CHAIN_METHODS = %i[require permit permit!].freeze
+
+      dynamic_return receivers: [REQUEST_CONTEXT_READER_TYPES[:params]], methods: STRONG_PARAMS_CHAIN_METHODS do |call_node, _scope|
+        next nil unless call_node.is_a?(Prism::CallNode)
+
+        Rigor::Type::Combinator.nominal_of(REQUEST_CONTEXT_READER_TYPES[:params])
+      end
+
       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 +224,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(

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

@@ -3,22 +3,17 @@
 module Rigor
   module Plugin
     class Activejob < Rigor::Plugin::Base
-      # Frozen catalogue of discovered ActiveJob subclasses
-      # keyed by qualified class name. Each entry holds the
-      # `#perform` method's arity envelope so the analyzer can
-      # validate `Job.perform_later(...)` call sites.
+      # Frozen catalogue of discovered ActiveJob subclasses keyed by qualified class name. Each entry
+      # holds the `#perform` method's arity envelope so the analyzer can validate
+      # `Job.perform_later(...)` call sites.
       #
-      # `min_arity` / `max_arity` form a closed range
-      # (`Float::INFINITY` for the upper bound when `*args`
-      # is present). `keyword_required` lists any required
-      # keyword arguments — Active Job supports keyword args
-      # but they're rare in user code, so the analyzer
-      # validates positional arity only (keyword arity
-      # validation is deferred).
+      # `min_arity` / `max_arity` form a closed range (`Float::INFINITY` for the upper bound when
+      # `*args` is present). `keyword_required` lists any required keyword arguments — Active Job
+      # supports keyword args but they're rare in user code, so the analyzer validates positional arity
+      # only (keyword arity validation is deferred).
       class JobIndex
         Entry = Data.define(:class_name, :min_arity, :max_arity, :keyword_required) do
-          # Flexible-friendly textual form of the arity for
-          # error messages: `1`, `1..2`, `2+`.
+          # Flexible-friendly textual form of the arity for error messages: `1`, `1..2`, `2+`.
           def arity_label
             return "#{min_arity}+" if max_arity == Float::INFINITY
             return min_arity.to_s if min_arity == max_arity

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

@@ -8,14 +8,12 @@ require_relative "activejob/analyzer"
 
 module Rigor
   module Plugin
-    # rigor-activejob — validates `Job.perform_later(...)` /
-    # `.perform_now(...)` / `.perform(...)` argument arity
-    # against the discovered `#perform` definitions.
+    # rigor-activejob — validates `Job.perform_later(...)` / `.perform_now(...)` / `.perform(...)`
+    # argument arity against the discovered `#perform` definitions.
     #
     # Tier 1D of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
-    # Statically discovers ActiveJob subclasses by walking
-    # the configured `job_search_paths` and parsing each
-    # file with Prism — no `active_job` runtime dependency.
+    # Statically discovers ActiveJob subclasses by walking the configured `job_search_paths` and
+    # parsing each file with Prism — no `active_job` runtime dependency.
     #
     # ## Configuration
     #
@@ -27,16 +25,12 @@ module Rigor
     #
     # ## Limitations (v0.1.0)
     #
-    # - Direct-superclass match only. `class WelcomeJob <
-    #   BaseJob` where `BaseJob < ApplicationJob` is NOT
-    #   discovered. Add `BaseJob` to `job_base_classes` if
-    #   needed.
-    # - The `#perform` arity is read from the syntactic
-    #   parameter list. Methods built via `define_method`
-    #   are out of scope.
-    # - Required keyword arguments are recognised but not
-    #   validated at the call site (positional arity only
-    #   for v0.1.0).
+    # - Direct-superclass match only. `class WelcomeJob < BaseJob` where `BaseJob < ApplicationJob` is
+    #   NOT discovered. Add `BaseJob` to `job_base_classes` if needed.
+    # - The `#perform` arity is read from the syntactic parameter list. Methods built via
+    #   `define_method` are out of scope.
+    # - Required keyword arguments are recognised but not validated at the call site (positional arity
+    #   only for v0.1.0).
     class Activejob < Rigor::Plugin::Base
       manifest(
         id: "activejob",
@@ -48,11 +42,10 @@ module Rigor
         }
       )
 
-      # Cached: discovered job index. `watch:` (ADR-60 WD3) covers
-      # every `.rb` under `job_search_paths` so the cache invalidates
-      # when a job is added, removed, or edited; the discoverer's
-      # in-block `IoBoundary` reads are captured into the record-and-
-      # validate dependency descriptor after the block runs.
+      # Cached: discovered job index. `watch:` (ADR-60 WD3) covers every `.rb` under `job_search_paths`
+      # so the cache invalidates when a job is added, removed, or edited; the discoverer's in-block
+      # `IoBoundary` reads are captured into the record-and-validate dependency descriptor after the
+      # block runs.
       producer :job_index, watch: -> { [[@job_search_paths, "**/*.rb"]] } do |_params|
         JobDiscoverer.new(
           io_boundary: io_boundary,
@@ -66,9 +59,8 @@ module Rigor
         @job_base_classes = Array(config.fetch("job_base_classes")).map(&:to_s)
       end
 
-      # File-level only: the load-error emission. Per-call arity
-      # validation runs over the engine-owned walk via the node_rule
-      # below (ADR-37). The job index is lazily loaded + memoised by
+      # File-level only: the load-error emission. Per-call arity validation runs over the engine-owned
+      # walk via the node_rule below (ADR-37). The job index is lazily loaded + memoised by
       # `producer_value`, shared by both surfaces.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:job_index)