rigortype 0.2.7 → 0.2.8

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/mailer_discoverer.rb

@@ -8,54 +8,38 @@ require_relative "mailer_index"
 module Rigor
   module Plugin
     class Actionmailer < Rigor::Plugin::Base
-      # Walks the configured mailer-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 mailer-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:
       #
-      # - Reads the instance-side `def` nodes and records each
-      #   one as an action method, capturing the arity envelope.
-      # - For each (class, action) pair, attempts to read every
-      #   candidate view template under
-      #   `app/views/<mailer_underscore>/<action>.{html,text}.erb`.
-      #   Existing templates feed the IoBoundary's cache
-      #   descriptor (so the cache invalidates when the
-      #   template changes); missing templates are recorded so
-      #   the plugin can surface a diagnostic on the mailer
-      #   class definition.
+      # - Reads the instance-side `def` nodes and records each one as an action method, capturing the
+      #   arity envelope.
+      # - For each (class, action) pair, attempts to read every candidate view template under
+      #   `app/views/<mailer_underscore>/<action>.{html,text}.erb`. Existing templates feed the
+      #   IoBoundary's cache descriptor (so the cache invalidates when the template changes); missing
+      #   templates are recorded so the plugin can surface a diagnostic on the mailer class definition.
       #
       # Limitations (intentional for v0.1.0):
       #
-      # - Direct-superclass match only. `class CustomerMailer
-      #   < BaseMailer` where `BaseMailer < ApplicationMailer`
-      #   is NOT discovered. Add `BaseMailer` to
-      #   `mailer_base_classes` if needed.
-      # - Action methods are read from the syntactic instance-
-      #   side `def` list. Methods built via `define_method`,
-      #   `private`, or non-action helpers (e.g. methods
-      #   starting with `_`) are out of scope. The discoverer
-      #   filters obvious non-actions (`initialize`, names
-      #   prefixed with `_`).
-      # - Adding a brand-new view file under
-      #   `app/views/<mailer>/` will NOT invalidate the
-      #   cached index until something the mailer file
-      #   touches changes. This is the standard read-tracking
-      #   trade-off — only files we successfully read get
-      #   digested into the descriptor.
+      # - Direct-superclass match only. `class CustomerMailer < BaseMailer` where `BaseMailer <
+      #   ApplicationMailer` is NOT discovered. Add `BaseMailer` to `mailer_base_classes` if needed.
+      # - Action methods are read from the syntactic instance-side `def` list. Methods built via
+      #   `define_method`, `private`, or non-action helpers (e.g. methods starting with `_`) are out of
+      #   scope. The discoverer filters obvious non-actions (`initialize`, names prefixed with `_`).
+      # - Adding a brand-new view file under `app/views/<mailer>/` will NOT invalidate the cached index
+      #   until something the mailer file touches changes. This is the standard read-tracking trade-off
+      #   — only files we successfully read get digested into the descriptor.
       class MailerDiscoverer
         DEFAULT_VIEWS_ROOT = "app/views"
         VIEW_FORMATS = %w[html text].freeze
         VIEW_EXTENSIONS = %w[erb haml slim].freeze
 
         # @param io_boundary [Rigor::Plugin::IoBoundary]
-        # @param search_paths [Array<String>] absolute or
-        #   project-relative paths to scan for mailers.
-        # @param base_classes [Array<String>] direct
-        #   superclasses that mark a class as a mailer.
-        # @param views_root [String] absolute or project-
-        #   relative path to the views directory (typically
+        # @param search_paths [Array<String>] absolute or project-relative paths to scan for mailers.
+        # @param base_classes [Array<String>] direct superclasses that mark a class as a mailer.
+        # @param views_root [String] absolute or project-relative path to the views directory (typically
         #   `app/views`).
         def initialize(io_boundary:, search_paths:, base_classes:, views_root: DEFAULT_VIEWS_ROOT)
           @io_boundary = io_boundary
@@ -66,11 +50,9 @@ module Rigor
 
         # @return [MailerIndex]
         def discover
-          # Two-pass: first collect every module's defs (for
-          # the include-following step), then build per-class
-          # entries that pull in actions from include'd modules.
-          # GitLab's `Notify` mailer derives every action from
-          # `Emails::*` concerns under `app/mailers/emails/`.
+          # Two-pass: first collect every module's defs (for the include-following step), then build
+          # per-class entries that pull in actions from include'd modules. GitLab's `Notify` mailer
+          # derives every action from `Emails::*` concerns under `app/mailers/emails/`.
           module_actions = {} # module_fqn => Hash<Symbol, ActionEntry>
           class_visits = []   # collected (class_name, path, def_nodes, includes)
 
@@ -135,10 +117,8 @@ module Rigor
           walk_for_mailers(node.body, inner_path, &) if node.body
         end
 
-        # Collects qualified-constant names passed to `include
-        # X` calls inside the class body. Used to look up
-        # concern-module action definitions (GitLab's
-        # `Notify` mailer derives every action from
+        # Collects qualified-constant names passed to `include X` calls inside the class body. Used to
+        # look up concern-module action definitions (GitLab's `Notify` mailer derives every action from
         # `Emails::Issues`, `Emails::MergeRequests`, etc.).
         def collect_includes(body)
           return [] if body.nil?
@@ -155,10 +135,9 @@ module Rigor
           names
         end
 
-        # Walks the AST collecting every module's instance-side
-        # def nodes by fully-qualified module name. The same
-        # `collect_action_defs` filter applies (private /
-        # `_`-prefixed / callback-target methods skipped).
+        # Walks the AST collecting every module's instance-side def nodes by fully-qualified module
+        # name. The same `collect_action_defs` filter applies (private / `_`-prefixed / callback-target
+        # methods skipped).
         def collect_module_actions(node, lexical_path, accumulator)
           return if node.nil?
 
@@ -210,25 +189,18 @@ module Rigor
           end
         end
 
-        # Returns the instance-side `def` nodes that look like
-        # mailer actions. Filters non-actions:
+        # Returns the instance-side `def` nodes that look like mailer actions. Filters non-actions:
         # - `initialize`
-        # - methods starting with `_` (Ruby convention for
-        #   private/internal)
+        # - methods starting with `_` (Ruby convention for private/internal)
         # - `def self.<name>` (singleton-side)
-        # - methods after a bare `private` (or
-        #   `public` → `private` transition) — these are
-        #   internal helpers, not actions
+        # - methods after a bare `private` (or `public` → `private` transition) — these are internal
+        #   helpers, not actions
         # - methods named as a `private :foo` argument
-        # - methods named as a callback target
-        #   (`before_action :name`, `after_action`,
-        #   `around_action`)
+        # - methods named as a callback target (`before_action :name`, `after_action`, `around_action`)
         #
-        # Pre-fix, Mastodon's `AdminMailer#process_params` /
-        # `set_instance` / `set_locale` / `set_important_headers!`
-        # all surfaced as missing-view because the bare `private`
-        # keyword wasn't honoured. ~19 false positives across
-        # Mastodon's mailers.
+        # Pre-fix, Mastodon's `AdminMailer#process_params` / `set_instance` / `set_locale` /
+        # `set_important_headers!` all surfaced as missing-view because the bare `private` keyword
+        # wasn't honoured. ~19 false positives across Mastodon's mailers.
         CALLBACK_DECLARATIONS = %i[before_action after_action around_action].freeze
         private_constant :CALLBACK_DECLARATIONS
 
@@ -252,11 +224,9 @@ module Rigor
           end
         end
 
-        # First pass over the class body: collect (a) names
-        # passed to `private :foo` / `protected :foo` (explicit
-        # visibility-on-existing-method form), and (b) Symbol
-        # arguments to callback declarations
-        # (`before_action :setup`, etc.).
+        # First pass over the class body: collect (a) names passed to `private :foo` / `protected :foo`
+        # (explicit visibility-on-existing-method form), and (b) Symbol arguments to callback
+        # declarations (`before_action :setup`, etc.).
         def collect_visibility_and_callbacks(body)
           private_names = []
           callback_names = []
@@ -278,10 +248,9 @@ module Rigor
           [private_names.to_set, callback_names.to_set]
         end
 
-        # Returns the new visibility scope state after observing
-        # `node`. Bare `private` / `protected` / `public` switch
-        # state; the `private :foo` arg-bearing form does NOT
-        # (already handled by `collect_visibility_and_callbacks`).
+        # Returns the new visibility scope state after observing `node`. Bare `private` / `protected` /
+        # `public` switch state; the `private :foo` arg-bearing form does NOT (already handled by
+        # `collect_visibility_and_callbacks`).
         def next_visibility(node, current)
           return current unless node.is_a?(Prism::CallNode)
           return current unless node.receiver.nil?
@@ -301,11 +270,9 @@ module Rigor
             [entry.method_name, entry]
           end
 
-          # Merge actions from include'd modules (pre-collected
-          # in `module_actions` keyed by fully-qualified name).
-          # Unresolvable includes are tracked; `unresolved_includes?`
-          # (consumed by the analyzer) downgrades `unknown-action`
-          # to silence when any include remains unresolved.
+          # Merge actions from include'd modules (pre-collected in `module_actions` keyed by
+          # fully-qualified name). Unresolvable includes are tracked; `unresolved_includes?` (consumed
+          # by the analyzer) downgrades `unknown-action` to silence when any include remains unresolved.
           unresolved_includes = []
           includes.each do |include_name|
             inc_actions = module_actions[include_name]
@@ -357,17 +324,14 @@ module Rigor
         end
 
         # Checks whether *any* template under
-        # `app/views/<underscore>/<action>.{html,text}.{erb,haml,slim}`
-        # exists, by attempting to read each candidate via the
-        # IoBoundary. Successful reads are recorded by the
-        # boundary; failed reads (missing file or access
-        # denied) are swallowed.
+        # `app/views/<underscore>/<action>.{html,text}.{erb,haml,slim}` exists, by attempting to read
+        # each candidate via the IoBoundary. Successful reads are recorded by the boundary; failed reads
+        # (missing file or access denied) are swallowed.
         def view_exists?(class_name, action_name)
           views_root_absolute = File.expand_path(@views_root)
-          # ADR-39: the real ActiveSupport::Inflector resolves the mailer's
-          # view directory (`Foo::BarMailer` → `foo/bar_mailer`), so a
-          # divergence from Rails' real underscore can't point the
-          # missing-view check at the wrong directory.
+          # ADR-39: the real ActiveSupport::Inflector resolves the mailer's view directory
+          # (`Foo::BarMailer` → `foo/bar_mailer`), so a divergence from Rails' real underscore can't
+          # point the missing-view check at the wrong directory.
           underscore_path = Rigor::Plugin::Inflector.underscore(class_name.delete_prefix("::"))
           mailer_dir = File.join(views_root_absolute, underscore_path)
 

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/mailer_index.rb

@@ -3,17 +3,13 @@
 module Rigor
   module Plugin
     class Actionmailer < Rigor::Plugin::Base
-      # Frozen catalogue of discovered Mailer classes, each
-      # carrying:
+      # Frozen catalogue of discovered Mailer classes, each carrying:
       #
-      # - the action methods it defines (arity envelope per
-      #   action; same shape as `rigor-activejob`'s
+      # - the action methods it defines (arity envelope per action; same shape as `rigor-activejob`'s
       #   `JobIndex::Entry`)
-      # - the source file path the class was declared in
-      #   (used to anchor missing-view diagnostics on the
-      #   mailer file)
-      # - the list of `(action, location)` pairs whose view
-      #   templates are missing from `app/views/`
+      # - the source file path the class was declared in (used to anchor missing-view diagnostics on
+      #   the mailer file)
+      # - the list of `(action, location)` pairs whose view templates are missing from `app/views/`
       class MailerIndex
         ActionEntry = Data.define(:method_name, :min_arity, :max_arity, :def_line, :def_column) do
           def arity_label
@@ -33,12 +29,10 @@ module Rigor
             actions[method_name.to_sym]
           end
 
-          # True when the mailer `include`s a module whose
-          # source we couldn't index (typically a gem-shipped
-          # concern that defines additional mailer actions).
-          # Analyzer downgrades `unknown-action` to silence in
-          # this case — the unresolved module may legitimately
-          # provide the action.
+          # True when the mailer `include`s a module whose source we couldn't index (typically a
+          # gem-shipped concern that defines additional mailer actions). Analyzer downgrades
+          # `unknown-action` to silence in this case — the unresolved module may legitimately provide
+          # the action.
           def unresolved_includes?
             !unresolved_includes.empty?
           end
@@ -61,8 +55,7 @@ module Rigor
           @by_name.key?(class_name.to_s)
         end
 
-        # @param file_path [String] absolute path of a mailer
-        #   file (canonicalised — see plugin entry's
+        # @param file_path [String] absolute path of a mailer file (canonicalised — see plugin entry's
         #   `harvest`)
         # @return [ClassEntry, nil]
         def find_by_file(file_path)

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

@@ -8,12 +8,10 @@ require_relative "actionmailer/analyzer"
 
 module Rigor
   module Plugin
-    # rigor-actionmailer — validates `Mailer.action(args)`
-    # call sites and detects missing view templates.
+    # rigor-actionmailer — validates `Mailer.action(args)` call sites and detects missing view templates.
     #
     # Tier 1C of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
-    # Statically discovers mailer classes by walking
-    # `mailer_search_paths` and parsing each file with
+    # Statically discovers mailer classes by walking `mailer_search_paths` and parsing each file with
     # Prism — no `action_mailer` runtime dependency.
     #
     # ## Configuration
@@ -27,35 +25,27 @@ module Rigor
     #
     # ## What it checks
     #
-    # 1. **Method existence** — `UserMailer.welcome(user)`
-    #    is flagged when `welcome` is not defined on
+    # 1. **Method existence** — `UserMailer.welcome(user)` is flagged when `welcome` is not defined on
     #    `UserMailer`.
-    # 2. **Argument arity** — calls with too few / too many
-    #    positional arguments emit `wrong-arity`.
-    # 3. **View template existence** — for every action
-    #    method, at least one of
-    #    `app/views/<mailer_underscore>/<action>.{html,text}.{erb,haml,slim}`
-    #    must exist. Missing actions get a `missing-view`
-    #    diagnostic anchored on the action's `def`.
+    # 2. **Argument arity** — calls with too few / too many positional arguments emit `wrong-arity`.
+    # 3. **View template existence** — for every action method, at least one of
+    #    `app/views/<mailer_underscore>/<action>.{html,text}.{erb,haml,slim}` must exist. Missing
+    #    actions get a `missing-view` diagnostic anchored on the action's `def`.
     #
     # ## Limitations (v0.1.0)
     #
     # - Direct-superclass match only.
-    # - Action methods are read from the syntactic instance-
-    #   side `def` list. `define_method` actions are out of
-    #   scope.
-    # - Adding a brand-new view file does not invalidate the
-    #   cache until something the mailer file touches
-    #   changes.
+    # - Action methods are read from the syntactic instance-side `def` list. `define_method` actions are
+    #   out of scope.
+    # - Adding a brand-new view file does not invalidate the cache until something the mailer file
+    #   touches changes.
     class Actionmailer < Rigor::Plugin::Base
       manifest(
         id: "actionmailer",
-        # Bumped 2026-05-28 — extended RESERVED_CLASS_METHODS to
-        # include `respond_to?` / `public_send` / `send` /
-        # `__send__` / `method` and friends so dynamic-dispatch
-        # idioms (`Mailer.respond_to?(action)` /
-        # `Mailer.public_send(action)`) stop firing
-        # `unknown-action` against the Ruby reflection method.
+        # Bumped 2026-05-28 — extended RESERVED_CLASS_METHODS to include `respond_to?` / `public_send` /
+        # `send` / `__send__` / `method` and friends so dynamic-dispatch idioms
+        # (`Mailer.respond_to?(action)` / `Mailer.public_send(action)`) stop firing `unknown-action`
+        # against the Ruby reflection method.
         version: "0.4.0",
         description: "Validates ActionMailer call shape and view template existence.",
         config_schema: {
@@ -65,11 +55,10 @@ module Rigor
         }
       )
 
-      # `watch:` covers every mailer class under `mailer_search_paths`
-      # AND every view template under `views_root` (ADR-60 WD3) — a
-      # newly-added view a mailer references must invalidate the index,
-      # and `view_exists?` failures the producer never records would
-      # otherwise be invisible to the dependency descriptor.
+      # `watch:` covers every mailer class under `mailer_search_paths` AND every view template under
+      # `views_root` (ADR-60 WD3) — a newly-added view a mailer references must invalidate the index,
+      # and `view_exists?` failures the producer never records would otherwise be invisible to the
+      # dependency descriptor.
       producer :mailer_index,
                watch: -> { [[@mailer_search_paths, "**/*.rb"], [@views_root, "**/*"]] } do |_params|
         MailerDiscoverer.new(
@@ -86,11 +75,10 @@ module Rigor
         @views_root = config.fetch("views_root").to_s
       end
 
-      # File-level: load-error + the missing-view check (anchored on the
-      # mailer's own source file, so it is genuinely per-file, not
-      # per-call). The per-call mailer validation (action existence /
-      # arity) runs over the engine-owned walk via the node_rule below
-      # (ADR-37). The mailer index is lazily loaded + memoised, shared.
+      # File-level: load-error + the missing-view check (anchored on the mailer's own source file, so it
+      # is genuinely per-file, not per-call). The per-call mailer validation (action existence / arity)
+      # runs over the engine-owned walk via the node_rule below (ADR-37). The mailer index is lazily
+      # loaded + memoised, shared.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:mailer_index)
         return [load_error_diagnostic(path)] if index.nil? && producer_error(:mailer_index)
@@ -108,10 +96,9 @@ module Rigor
 
       private
 
-      # Anchors `missing-view` diagnostics on the mailer file
-      # itself: when the file currently being analysed is the
-      # mailer's source file, emit one diagnostic per missing
-      # action template at the action's `def` location.
+      # Anchors `missing-view` diagnostics on the mailer file itself: when the file currently being
+      # analysed is the mailer's source file, emit one diagnostic per missing action template at the
+      # action's `def` location.
       def missing_view_diagnostics(path, index)
         canonical = canonical_path(path)
         class_entry = index.find_by_file(canonical)